Skip to content

Add a lock context skill #795

Description

@coderdan

Lock context is the mechanism most likely to be misunderstood in the whole stack, and it currently has no dedicated explanation anywhere. #793 records a case where shipped material — both a source comment and a customer-facing skill — described an auth strategy as being identity-bound encryption. There was nowhere to check.

Why it needs its own skill

The failure mode is silent and destructive. A value encrypted under a lock context and decrypted without one (or under a different claim) does not come back. That surfaces as a failed decrypt, not as a key error, so it reads like data corruption.

Scope

  • What a lock context actually is{ identityClaim: string[] }, passed per operation, changing key derivation at ZeroKMS. Contrast explicitly with authentication: config.authStrategy decides who the client is, a lock context decides which key the value is encrypted under. Both are needed for identity-bound encryption; neither substitutes for the other.
  • The symmetry rule — the same claim on encrypt and decrypt, every time, including in backfills, migrations, and admin tooling. What happens when it is missing, and why the error does not name the cause.
  • Chaining and composition.withLockContext() on operations, and how it composes with .audit() in either order (mapped-decrypt.ts:46-50 goes to some trouble to make this work).
  • Which operations support it, and what it means for bulk and model helpers.
  • The deprecated pathLockContext.identify() and getLockContext() (identity/index.ts:119, :185). Per-operation CTS tokens were removed in protect-ffi 0.25, so the token identify() fetches is no longer consumed. Kept for compatibility, slated for removal. Anyone reading older code or blog posts will land on this first.
  • Operational consequences — what identity-bound data means for support access, re-keying, and users who change identity provider subject.
  • Entry parity — currently native-only; see wasm-inline has no lock context — and explains its absence incorrectly #793 and the implementation issue.

Relationship to #794

#794 proposes a broader auth skill covering credentials, strategies, and the CS_* variables, with lock context as one section. These two should be scoped together — either this is the deep-dive that #794 links to, or the two merge. Deciding that split is part of this issue.

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions