Summary
We don't currently have anything in the docs that explains the isolation hierarchy in CipherStash — how keysets, auth strategies, and lock context relate to one another. These are three different mechanisms that solve three different isolation problems, and it's easy for developers to conflate them (or reach for the wrong one). We should document the hierarchy somewhere discoverable.
This came out of a conversation while renaming the encryption client's strategy field to authStrategy and adding a keysets section to the Encryption() TypeDoc in cipherstash/stack. The reference docs (TypeDoc) now cover each piece, but there's no conceptual page that ties them together.
The three levels (as they exist today in @cipherstash/stack)
| Mechanism |
Granularity |
Where it's set |
What it isolates |
Keyset (config.keyset) |
Per-tenant keyspace, fixed for the client's lifetime |
Client init |
An entire tenant's data — data encrypted under keyset A cannot be decrypted under keyset B. One client per keyset/tenant. |
Auth strategy (config.authStrategy) |
Per-request authentication |
Client init |
Who is making ZeroKMS requests — AccessKeyStrategy (service/CI), OidcFederationStrategy (per end-user, via your own IdP). Default is auto. |
Lock context (.withLockContext({ identityClaim })) |
Per-value, per-user |
Per encrypt/decrypt operation |
An individual value bound to a user's identity claim (typically sub), so only the user who encrypted it can decrypt it. Requires OidcFederationStrategy; not valid with AccessKeyStrategy. |
Key points worth making explicit:
- They are orthogonal and composable — a request can use a specific keyset and an OIDC auth strategy and lock context at once.
- Keyset = coarse (whole tenant, set once). Lock context = fine (single value, per operation). Auth strategy = who you are, independent of both.
- Lock context depends on
OidcFederationStrategy because it needs a real end-user sub claim to bind to — which is also why AccessKeyStrategy can't be used with it.
Open question
Not sure where this belongs in the docs IA — possibly a new "Isolation model" / "Concepts" page, or folded into an existing encryption concepts section. Flagging that as part of this issue.
Related
cipherstash/stack Encryption() TypeDoc now covers keysets, auth strategies, and lock context individually (see packages/stack/src/encryption/index.ts). This issue is about the conceptual overview that links them.
Summary
We don't currently have anything in the docs that explains the isolation hierarchy in CipherStash — how keysets, auth strategies, and lock context relate to one another. These are three different mechanisms that solve three different isolation problems, and it's easy for developers to conflate them (or reach for the wrong one). We should document the hierarchy somewhere discoverable.
This came out of a conversation while renaming the encryption client's
strategyfield toauthStrategyand adding a keysets section to theEncryption()TypeDoc incipherstash/stack. The reference docs (TypeDoc) now cover each piece, but there's no conceptual page that ties them together.The three levels (as they exist today in
@cipherstash/stack)config.keyset)config.authStrategy)AccessKeyStrategy(service/CI),OidcFederationStrategy(per end-user, via your own IdP). Default isauto..withLockContext({ identityClaim }))sub), so only the user who encrypted it can decrypt it. RequiresOidcFederationStrategy; not valid withAccessKeyStrategy.Key points worth making explicit:
OidcFederationStrategybecause it needs a real end-usersubclaim to bind to — which is also whyAccessKeyStrategycan't be used with it.Open question
Not sure where this belongs in the docs IA — possibly a new "Isolation model" / "Concepts" page, or folded into an existing encryption concepts section. Flagging that as part of this issue.
Related
cipherstash/stackEncryption()TypeDoc now covers keysets, auth strategies, and lock context individually (seepackages/stack/src/encryption/index.ts). This issue is about the conceptual overview that links them.