Skip to content

docs(data): accept-and-document mongo/turso passthrough secrets with no binder slot#9253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-project-manager merged 1 commit into from
Aug 17, 2026
+40 −0
Merged

docs(data): accept-and-document mongo/turso passthrough secrets with no binder slot #9253

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions content/docs/data-modeling/drivers.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -164,6 +164,46 @@ which the Studio connection form renders — so the form offers exactly the fiel
the validator accepts.
</Callout>

### Secret-shaped keys with no binder slot: accepted at-rest risk

The datasource secret binder injects exactly **one** secret per datasource —
the login password, resolved through `external.credentialsRef` (or the
connection form's password field) into `sys_secret` at connect time. A small
number of other config keys are secret-shaped too, but the binder has no
second slot to put them in, and the client library that owns them — not
ObjectStack — is what makes them secrets:

| Driver | Key | What it carries |
| :--- | :--- | :--- |
| `mongo` \| `mongodb` | `options.proxyPassword` | SOCKS5 proxy password |
| `mongo` \| `mongodb` | `options.tlsCertificateKeyFilePassword` | TLS key-file passphrase |
| `mongo` \| `mongodb` | `options.key` | TLS private key material (PEM) |
| `mongo` \| `mongodb` | `options.passphrase` | TLS key passphrase |
| `turso` \| `libsql` | `encryptionKey` | AES-256 key for the local database file |

Unlike `password` / `authToken` (typed `never` in their schemas — the parse
refuses them outright), these five keys are **writable**: the parse accepts
them, and they are stored **at rest in `sys_metadata` as plain text**, right
alongside the rest of the datasource row. The protection that exists today is
on the READ side only — every one of them is stripped before a datasource
record is ever served back over the admin API or shown in the Setup UI
(`PASSTHROUGH_SECRET_PATHS` / `STILL_WRITABLE_CREDENTIAL_KEYS` in
`datasource-credential-redaction.ts`, shipped in
[#9040](https://github.com/objectstack-ai/objectstack/issues/9040)). That stops the value
round-tripping through a read; it is not encryption at rest, and an operator
with direct access to the metadata store can still read the plain-text value.

<Callout type="warn">
**This is a deliberate, documented trade-off ([#9124](https://github.com/objectstack-ai/objectstack/issues/9124)), not an oversight.**
The binder has exactly one named slot. Refusing these five keys at write time
would remove the only way to configure an authenticated SOCKS5 proxy or a
passphrase-protected TLS key — a capability the client genuinely honours, with
no working refusal remedy. **Restart condition:** the first real deployment
that needs an authenticated proxy or a passphrase-protected key converts this
into named binder-slot support — one mechanism covering all five keys — rather
than the current per-key accept-and-document posture.
</Callout>

## Startup: a driver that cannot connect aborts the boot

`ObjectQLEngine.init()` connects every registered driver during kernel
Expand Down
Loading