Identity and admission
Trust explains what the Trust Firewall does once a call is admitted; this page is the gate itself — how a connection is admitted to exactly one worktree, and what identity machinery exists versus is designed.
sequenceDiagram
participant U as You
participant L as Launcher (zephr connect)
participant S as Store
participant C as Client (MCP)
U->>L: approve project / bind path
L->>S: record installation, project, repo, worktree
L->>C: hand a signed, single-use launch capability
C->>S: present capability once, at launch
S-->>S: verify MAC, epoch, nonce, live roots; consume nonce; write admission
S-->>C: admitted — or refusal with a precise code
C->>S: every tool call: validateAdmission (fresh scope from the admission)
S-->>C: run — or refuse on epoch/roots driftThe local admission chain (shipped)
The trusted launcher establishes exactly one admitted worktree before any tool call is allowed:
- Approval and binding —
zephr connectrecords the installation → project → repository → worktree hierarchy. The commands are in Connect your client. - A launch capability is minted — a length-prefixed canonical encoding
with the
zephr.launch.v1domain separator, MAC'd with server-held key material, single-use (the nonce is consumed exactly once), short-lived (TTL between 1 and 60 seconds, enforced), and bound to the connection, the scope ids, thebindingEpoch, and a digest of the approved root paths. - Launch admission, once per connection (shipped). At startup the client
presents the capability once and
validateAndAdmitCapabilityinpackages/core/src/admission.tsruns the full predicate chain — structure and TTL, connection and server nonce, installation key material, MAC (constant-time), client kind, binding state/epoch/roots digest, the scope hierarchy, and live root identity — then atomically consumes the nonce and writes the admission record. The client keeps the admission's connection, binding, epoch, and roots digest; it does not re-present the capability. - Per-request validation (shipped). Every tool call runs
validateAdmission, which resolves a fresh scope snapshot from the store for that request — role and context never leak from a previous request on the connection — re-checking the binding state, epoch, and roots digest. An epoch that has advanced (a re-approval or rebind happened) refuses the call; the client must reconnect. - Refusal, never fallback — there is no default scope. The visible codes
are
scope_violationandhierarchy_mismatch; recovery steps are in Troubleshooting.
The scope model
Scope is a hierarchy: installation → project → repository → worktree, with a recall-time scope lattice on top (organization, repository, ref, commons grants). The Workspaces page covers the hierarchy and why a connection binds to exactly one worktree.
Two rules worth knowing here:
- Most specific wins, with mandatory policy above it. Organization-scoped mandatory policy applies regardless of narrower scope.
- Confirmation is scoped, not transitive upward. Confirming a belief at one extent never confirms it at a broader one.
Identity today, honestly
The baseline capability tags each identity requirement with its build state
(openspec/specs/platform/spec.md). The current state:
| Mechanism | State | Where |
|---|---|---|
| Launch capability MAC, single-use, domain-separated | shipped | packages/core/src/admission.ts |
Scope binding + binding_epoch compare-and-operate | shipped | same, plus packages/core/src/db/admission-lease.test.ts |
| Live approved-root revalidation, revalidate-then-finalize | shipped | packages/core/src/admission.ts |
| JWT verification (one maintained library, full claim set) | shipped | packages/cloud-jwt |
| OAuth 2.1 for MCP client connections | shipped | apps/web/src/app/api/cloud/oauth/* |
API keys: zephr_ prefix, hash-only storage, expiry at mint | shipped | packages/store-postgres/sql/0013_api_keys.sql |
| CLI device-flow login (RFC 8628) | shipped | zephr login / zephr init |
Credential middleware on every /api/cloud request | designed | platform spec, "Credential-consuming middleware" |
| Device records + global revocation cascade | designed | platform spec, "The device record roots the local admission chain" |
The honest summary: the local admission chain is real and load-bearing; the
cloud credential planes are part-way there. One local disclosure: the CLI
persists its cloud credentials at ~/.zephr/credentials.json with owner-only
permissions — the device-key design intends device-bound keys instead, and that
remains the designed gap above.
One authorization rule crosses into the review machinery and is stated once there: agents never self-confirm — see Trust.
Sources
openspec/specs/platform/spec.md— admission, credential, and scope requirements, each tagged with its build state.packages/core/src/admission.ts— capability encoding, MAC, launch admission (validateAndAdmitCapability, once per connection) and per-request lease validation (validateAdmission).packages/mcp-server/src/cli.ts— the launch admission invocation; the client retains the admission's connection/binding/epoch/roots, not the capability.packages/mcp-server/src/transport.ts— fresh-scope-per-request validation ordering (ZEP-1724 note).packages/cli/src/cli.ts—connect,init,login.