Zephr Docs

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 drift

The local admission chain (shipped)

The trusted launcher establishes exactly one admitted worktree before any tool call is allowed:

  1. Approval and binding — zephr connect records the installation → project → repository → worktree hierarchy. The commands are in Connect your client.
  2. A launch capability is minted — a length-prefixed canonical encoding with the zephr.launch.v1 domain 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, the bindingEpoch, and a digest of the approved root paths.
  3. Launch admission, once per connection (shipped). At startup the client presents the capability once and validateAndAdmitCapability in packages/core/src/admission.ts runs 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.
  4. 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.
  5. Refusal, never fallback — there is no default scope. The visible codes are scope_violation and hierarchy_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:

MechanismStateWhere
Launch capability MAC, single-use, domain-separatedshippedpackages/core/src/admission.ts
Scope binding + binding_epoch compare-and-operateshippedsame, plus packages/core/src/db/admission-lease.test.ts
Live approved-root revalidation, revalidate-then-finalizeshippedpackages/core/src/admission.ts
JWT verification (one maintained library, full claim set)shippedpackages/cloud-jwt
OAuth 2.1 for MCP client connectionsshippedapps/web/src/app/api/cloud/oauth/*
API keys: zephr_ prefix, hash-only storage, expiry at mintshippedpackages/store-postgres/sql/0013_api_keys.sql
CLI device-flow login (RFC 8628)shippedzephr login / zephr init
Credential middleware on every /api/cloud requestdesignedplatform spec, "Credential-consuming middleware"
Device records + global revocation cascadedesignedplatform 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.