feat(auth): login mints a durable user-scoped credential, one per machine

[indykish]

Intent

An operator who logs in once keeps using the terminal — as themselves, against the deployment they logged into — until they log out.

agentsfleet login ran a correct Elliptic Curve Diffie-Hellman (ECDH) device flow and then persisted the wrong thing: the session JSON Web Token (JWT) recovered from the handshake, valid for about a minute. A terminal went stale while its operator was still reading the success message, and no renewal path exists — the Command-Line Interface (CLI) carries no Clerk Software Development Kit (SDK) and structurally cannot refresh a browser-coupled token.

Two workstreams land from this branch by Indy's call (Aug 11, 2026): M160_002 (durable credential) and M136_001 (live connector proof).

Landed

M160_002 — every section, every Dimension DONE. Specification in docs/v2/done/.

§1 — a credential that names the human. New core.cli_credentials (schema 250) with a partial unique index making two live credentials per (user, machine) unrepresentable. Only a hash is stored. Mint, list, and revoke endpoints; the credential joins the accepted principal set resolving to a user rather than a tenant.

§2 — login spends its sixty seconds on something that lasts. The recovered session token buys one POST /v1/cli-credentials call, and the durable afc_ credential that comes back is what reaches disk. The exchange completes before anything is saved, so a failed mint leaves the operator logged out and told why rather than logged in with a credential already dead.

§3 — one machine, one live credential; logout ends it. A second login from the same machine revokes what it left behind. Logout revokes this terminal's credential and deliberately leaves browser sessions alone. login --token and its piped-stdin seeding are gone; an unattended caller reaches the Application Programming Interface (API) with AGENTSFLEET_API_KEY alone, writing nothing to disk.

§4 — a credential remembers which deployment minted it. Un-parked and landed on Indy's Aug 14 call ("yes b is fine"). Shipped as one guard rather than the two originally designed: Dimension 4.2's refusal proved unreachable, because an inferred target resolves to the stored deployment and the two cannot disagree. What remains is the leg that reached production in silence — no stored deployment and no named target — refused as DEPLOYMENT_UNKNOWN before anything is dialed. guardCommand in cli/src/program/auth-guard.ts owns the whole policy; logout and doctor stay reachable.

§5 — one writer, one spelling. Folded in on Indy's Aug 13 call. scopes is the only capability claim read; the scope-before-scopes fallback was live and mis-ordered on the authorisation path. OIDC_PROVIDER=custom is refused at boot.

§6 — a tenant key carries its creator's capabilities. Folded in on Indy's Aug 13 call. An agt_t key resolves through clerk_scope_resolver keyed on the created_by subject the row already held, and the compiled-in TENANT_API_KEY_GRANT is removed rather than left unread.

M136_001 — closed with the live proof deferred. Specification in docs/v2/done/. §4 (replay closes the architecture marker) and §5 (the real reviewer proves the Live Wall, Playwright specs) are PARKED on Indy's Aug 14 call, quoted in the specification header: "I cant keep in active M136_001 - move it to Done"; §4: "i want to take it later".

Session notes

Two security defects found while building the exchange, both fixed here

Unbounded, self-renewing credentials. Minting accepted an existing credential as its authorisation (.jwt_oidc, .cli_credential), and machine_name is client-supplied and is the uniqueness key. The mint path carries no per-user ceiling and no rate limit — both verified by reading the handler and store, not assumed. Chained, that turns one stolen credential into an unbounded supply: each mints the next under a machine name of the caller's choosing, revoking any single row leaves its siblings live, and the account holder cannot tell how many exist. Since the credential is durable, a compromise that previously expired in sixty seconds became permanent.

Minting now takes a browser sign-in alone — the one step a stolen credential cannot replay. Listing and revoking still accept a credential, so a terminal can end its own access without opening a browser.

Prefix-only validation. The stored value was checked by prefix on both the load path and the mint-response decode. A value carrying trailing bytes passed. Both now match the full declared shape (afc_ plus exactly 64 lower-case hexadecimal characters), mirroring looksWellFormed in src/agentsfleetd/auth/cli_credential.zig — the mechanism the spec cites Supabase's access_token.go for.

Decisions

• The load allowlist admits agt_t as well as afc_. Per the spec's Failure Modes, a tenant key resolves as a tenant principal and is refused at the route, not at the file; only a session token is refused on load. A literal reading of Dimension 1.4 would have broken login --token.
• UZ-AUTH-025 is registered with a reachable: no annotation naming the client as producer. The spec already intends client-produced registered codes (§4's deployment-mismatch refusal never leaves the process), so this follows its decided design. UZ-AUTH-021 was deliberately retired by f64e20c and was not reused.
• A refused mint preserves the daemon's own error code rather than flattening every cause into the client's. The client code covers only causes that carry none.
• machineName derives from the hostname, not the platform. defaultTokenName() returns "macos-cli"; using it would have made every Mac claim the same row and break Dimension 3.2.
• The empty-credentials literal moved to emptyCredentials() — a factory, not a shared constant, because loadCredentials hands its fallback back by reference and a caller mutating what it read would corrupt the next reader's.

Verification

• make test-unit-cli — 1443 pass, 13 skip, 0 fail
• make test-unit-agentsfleetd — 2205 pass, 287 skip, 0 fail
• make test-integration — exit 0; filtered run of the new security test reports 76 pass / 0 skip, so it executes rather than skipping on an unavailable datastore
• make check-version — all versions match 0.26.2
• gitleaks — clean; every credential-shaped fixture is built by repetition so no high-entropy literal enters the tree
• Depth gate: integration 598 → 599

Caveats, stated rather than buried

• The mutation probe on the mint restriction never ran. Both the production-side and test-side mutations were blocked by the harness classifier as security-weakening edits. The test provably executes and passes, but "proved to bite" is not a claim this one has earned. Worth a reviewer's eye.
• The spec's rubric commands use --test-filter, which this Zig version rejects. The working form is make test-integration TEST_FILTER=<substring>. The rubric rows need correcting before they are graded.
• docs/AUTH.md still says the afc_ branch and mint endpoints are "not yet wired". Stale as of §1; it is in the Files Changed table and will be corrected at DOCUMENT.
• A latent test weakness was fixed in passing: several fixtures seeded a three-segment session token into the credential field. Four specs failed outright once the built binary was refreshed; two others were passing only because they assert the api_url rung and never noticed they had become logged out.
• make memleak and the cross-compile rows have not been run on this diff yet; they are due before this leaves draft.

🤖 Generated with Claude Code

Session notes — Aug 14, 2026 (memleak fix + adversarial sweep)

CI red on the memleak lane — root-caused and fixed. The boot-drain lifecycle
test failed SseUnexpectedStatus after the resolved-capability change: the
seeded agt_t key's creator (user_lifecycle_test) has no identity-provider
record, and the real serve boot hardcoded the vendor API base, so the offline
lane could never answer the scope resolve. The leak dump in the job log was
fallout (test erred before its drain; every daemon thread was still alive at
exit). Fix: CLERK_API_BASE boot override resolved once beside the secret and
threaded to BOTH the scope resolver and the signup metadata writer, plus a
loopback FakeClerk in the lifecycle test answering the creator claim. The
boot-drain now proves the resolved model end to end: agt_t auth → creator claim
over real HTTP → scope closure → SSE held through SIGTERM → clean drain.
make _memleak-boot-drain green locally (valgrind-free on macOS; CI runs the
gate).

Adversarial sweep (Indy's ask, no spec): 17 findings fixed.
TypeScript: dead JWT-claims path deleted from auth status (every credential
is opaque post-resolve; JSON envelope drops token/credential_kind);
credentials.json read once per command via a snapshot accessor (was 3
reads; logout's token+credential-id could span two snapshots); hydrate's
duplicated save block unified (+ dead guard removed); reasonOf single-sourced
in errors/index.ts (was 4 copies); emptyWorkspaces() kills a live drift bug
(cli.ts fallback had lost tenant_id); dead getApiUrl/authRole/
extractRoleFromToken deleted; isString de-cloned for PR files
(lib/guards.ts); CLI_CREDENTIAL_TOTAL_LEN now pinned by a test.
Zig: CLI-credential auth JOIN now returns u.tenant_id (authoritative) onto
the principal — resolvePrincipalTenant stops re-querying core.users on
every workspace-scoped CLI request (~15 handler paths); scope-resolver cache
Mutex → RwLock (shared reads on the hot path of both resolved credential
classes); five route-matcher clones collapsed into two shared shapes;
redundant (user_id, revoked_at) index removed from the new credentials
schema (both readers served by the partial unique index); stale "API keys
never touch Clerk" paragraph in docs/AUTH.md corrected.

Deferred (agent call, listed for Indy's veto or a follow-up slice):

• Login pingMe → fold into hydration's first fetch (drops one round trip;
  changes specced fail-loud semantics + acceptance pins).
• Logout dual DELETE → one endpoint (needs new/extended public API + docs).
• resolveHashedCredential generic to dedupe the two credential middlewares,
  and a shared clerk_http.zig for the backend fetch pair — coherent slice
  with ScopeFn returning a parsed scopes.Set (kills the per-request
  claim re-parse) and per-subject single-flight (resolver doc updated with
  the caveat meanwhile).
• Mint path: 5 statements → data-modifying CTE; principal user_row_id to
  skip resolveUser on list/revoke.
• c.deployment stays on the auth SELECT despite no current reader — the
  deployment-binding dimension (§4) reads it at exactly that site.

Coverage: merged Zig line coverage 88.30% (was 87.80% at handoff; 83% gate
passes; Indy's 90% target not yet reached). Next targets by missed lines:
serve.zig 111, tenant_provider 53, serve_webhook_lookup 48,
tenant_model_entries 47, session_store_redis 45, platform_keys 42.

Test Delta: unit 3512 → 3741 (+229), integration 589 → 629 (+40) vs the
CHORE(open) baseline. CLI: 1434 pass / 0 fail. Preflight integration tests
mutation-probed red→green against live datastores.

Still owed on this branch: M160_002 §4 (deployment binding), M136_001 §5
(Playwright), ~/Projects/docs changelog branch (breaking scope-inheritance
change, --token warning rewording, auth status envelope change, logout
reason strings).

Decisions — Aug 14, 2026 (Indy, verbatim)

• M136_001 §5 parked: "just make it parked i will ask another agent after
  this PR is merged to implement/execute/ run the scenario via playwright, so
  record in your dimension towards that effect" — recorded in the spec section
  header; dimensions 5.1–5.4 are the follow-up agent's work order.
• Docs-repo changelog waived for this PR: "i dont need a change log
  update, but any update needed in the CLI is needed" — CLI-side prose updated
  instead (auth status description, README login row, orphaned role constants
  removed) in b6edd41.
• M160_002 §4 parked: "Yes think park this, the error will say it to check
  the api_url as well when it fails is the simple fix here." — simple fix
  landed in 6b6dab5 (401/403 suggestions + auth status rejection line now
  name the target API URL); the guard's full design is recorded in the spec
  section as the follow-up work order.

Session notes — Aug 14, 2026 (session 3: review-fix batch landed)

Landed as e4db078ba. Every finding from the Aug 14 adversarial chain is now committed and verified on this tree.

Review outcome — 16 findings fixed (Claude adversarial: 9; Codex adversarial: 7), plus greptile's one P1 (concurrent mint race, replied on the thread). Three were closed as decisions rather than code:

• Codex C3 — tenant snapshot during provider latency. Accepted semantics: a snapshot taken at mint reads the same as api_key mode does today. Noted, not changed.
• Codex C5 / Claude chore: simplify README comic and apply pending updates #6 — auth status JSON envelope break. Indy waived the docs/changelog obligation for this PR: "i dont need a change log update, but any update needed in the CLI is needed."
• Claude feat: iamborn alpha v1 merge to main #2 — in-place index edit. Moot: schema slot 250 never merged anywhere, so there is no deployed index to migrate.

Three defects found while verifying, not inherited from the review:

1. RULE FLL was red. auth/clerk_backend.zig reached 355 lines against the 350 cap. Split per write_zig.md §Module Split Pattern into auth/clerk_backend_config.zig; clerk_backend re-exports the surface and remains the public API, so none of the six call sites changed.
2. sql.zig doc-comment mis-attachment. LOCK_CLI_CREDENTIAL_MINT had been inserted between INSERT_CLI_CREDENTIAL and its doc comment, so the partial-unique-index rationale documented the lock and the insert carried none. Reordered; the lock's parameters are now pinned $1::text || ':' || $2::text rather than relying on Postgres unknown-type inference.
3. docs/AUTH.md rotation runbook was wrong. It stated agentsfleetd does not present CLERK_SECRET_KEY directly. It does — auth/clerk_scope_fetch.zig on every authenticated command-line request that misses the scope cache, and handlers/auth/identity_events_clerk.zig on signup. A rotation that skipped the Fly redeploy would fail scope resolution closed once warm cache entries aged out. Fixed, and CLERK_API_BASE is now documented beside the compromise model it governs.

Verification on e4db078ba:

Lane	Result
cd cli && bun test	1438 pass / 13 skip / 0 fail
zig build test	exit 0
make test-integration TEST_FILTER='divergent mint snapshot'	full integration suite passed
make _memleak-boot-drain	boot→SIGTERM→drain ran leak-clean under the gate
make lint-all	✓ all lint checks passed
Test Delta vs CHORE(open) baseline	unit 3512 → 3746 (+234) · integration 589 → 630 (+41)

Docs audit (Indy's punch-list ask, landed 0ff091470). Every contributor doc reviewed against the brief — brief, agent-locatable, human-skimmable, no duplication of docs.agentsfleet.net, link out where user coverage exists. Changed: docs/AUTH.md (question→anchor lookup index; scope catalogue names scopes.zig as canon and links the published subset; runner token corrected to the fifth surface; plus the CLERK_API_BASE section and rotation-runbook fix from e4db078ba) and docs/architecture/README.md (fleet key retired at M154 §8 removed from the AUTH row; Facts-table claim narrowed to what's true on disk). Audited clean, untouched: README.md, docs/development.md, docs/AUTH_DEVICE_LOGIN.md, the architecture topic files. One cross-repo finding for Indy: published api-reference/scopes.mdx lists fleetkey:read/fleetkey:write, which do not exist in auth/scopes.zig — needs its own ~/Projects/docs branch, not this worktree.

Tracked for Indy, not implemented — CLERK_API_BASE threat model as a class. The end-to-end analysis is settled for this variable: the override is read once at boot, so an attacker who can set it already owns the daemon's environment and could read CLERK_SECRET_KEY outright. What the loopback-termination rule actually closes is the review bypass — http://127.0.0.1.attacker.example and http://localhost@evil.example read as localhost to a human eyeballing a manifest or a boot log, and a prefix-only check would have shipped the admin secret in cleartext on every scope-cache miss. The open question Indy owns: whether the same reasoning applies as a class to the other *_API_BASE / *_URL overrides that ride hx.ctx in the daemon (the github and slack connector bases), and whether the test-lane override should be a build-time flag rather than an environment variable. Decision wanted class-wide, not per variable.

Session notes — Aug 14, 2026 (session 4: close-out, merged)

Review is closed. Greptile raised exactly one finding across the branch's life: the P1 concurrent credential replacement race at src/agentsfleetd/state/cli_credentials.zig:110, fixed in e4db078ba with a transaction-scoped advisory lock keyed on (user_id, machine_name) and answered in thread. Greptile's re-review of 360559493 scored 5/5 with "no blocking failure remains". One review thread total, zero unresolved. Continuous Integration (CI) finished green on every check — no failures, nothing skipped that carried code. Merged by Indy as 92589429b.

Specification state at close. M160_002 Status: DONE, every Dimension across §1–§6 marked DONE. M136_001 Status: DONE with §4 and §5 PARKED under the quoted Indy call. Both in docs/v2/done/; docs/v2/active/ is empty.

Published documentation landed separately: agentsfleet/docs#173 on chore/m160-durable-credential-changelog. It carries the Aug 14 changelog <Update> and corrects four pages that this milestone made false — cli/configuration.mdx still told operators the login command accepts --token and piped input, cli/agentsfleet.mdx said logout "revokes every active session", api-reference/introduction.mdx said login saves a short-lived JWT, and docs.json had none of the three /v1/cli-credentials operations registered. The cross-repo fleetkey:* finding tracked above is fixed there too, along with the retired agentsfleet fleet-key commands the reference still advertised.

One defect this PR shipped, fix pending. UZ-AUTH-024's registry detail tells operators to run agentsfleet cli-credentials list — not a command in the client; only the Hypertext Transfer Protocol (HTTP) path exists. The same string also fails the docs repository's own checker on sentence length (DOC-02) and sentence count (DOC-03), so the generated error-codes.mdx could not lint until it was reworded. The generated page carries the corrected wording; src/agentsfleetd/errors/error_entries.zig does not yet, so the next make gen-error-codes would reintroduce it. Needs a small follow-up PR against main.

Cross-repository version drift, for Indy. make gen-error-codes stamps the agentsfleet repository version into the generated page's front matter (0.26.2), while ~/Projects/docs scripts/check-documentation.py hardcodes EXPECTED_VERSION = "0.25.0" and rejects anything else. Every regeneration now fails the docs checker until the pin moves across all 25 pages. Left as a decision rather than folded in.

Greptile Summary

The PR replaces short-lived session-token persistence with durable, user-scoped CLI credentials and adds their complete mint, authentication, listing, revocation, and logout lifecycle.

• Adds the core.cli_credentials schema and database-backed credential operations.
• Exchanges device-flow session tokens for durable credentials before persisting login state.
• Resolves credential principals and scopes through the daemon authentication pipeline.
• Serializes concurrent replacement mints per user and machine.
• Updates CLI state, deployment handling, logout behavior, API definitions, tests, and authentication documentation.

Confidence Score: 5/5

The PR appears safe to merge because the previously reported concurrent credential replacement failure is fixed and no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/agentsfleetd/state/cli_credentials.zig	Implements transactional mint, list, and owner-scoped revocation; the advisory lock fixes the previously reported concurrent replacement race.
src/agentsfleetd/state/sql.zig	Adds credential persistence, lookup, revocation, listing, and transaction-scoped mint-lock statements.
schema/250_cli_credentials.sql	Introduces hashed durable credentials with a partial unique index enforcing one live credential per user and machine.
src/agentsfleetd/http/handlers/auth/cli_credentials.zig	Exposes authenticated mint, list, and revoke operations for user-scoped CLI credentials.
cli/src/commands/login-exchange.ts	Exchanges the recovered browser session token for a validated durable credential before login state is persisted.
cli/src/commands/auth-logout.ts	Revokes pending sessions and the current machine credential before clearing local authentication state.
cli/src/program/auth-guard.ts	Adds deployment-aware command guarding while retaining explicit exemptions for login, logout, and diagnostics.

Sequence Diagram

sequenceDiagram
  participant CLI
  participant API
  participant DB as Postgres
  CLI->>API: POST /v1/cli-credentials with session token
  API->>DB: BEGIN
  API->>DB: Advisory lock(user, machine)
  API->>DB: Revoke existing live credential
  API->>DB: Insert replacement credential hash
  API->>DB: COMMIT
  API-->>CLI: One-time afc_ credential
  CLI->>CLI: Persist credential and deployment

Loading

_{Reviews (6): Last reviewed commit: "feat(m160_002): login names the deployme..." | Re-trigger Greptile}

Context used (4)

• Knowledge Base — Auth and secrets
• Knowledge Base — The agentsfleet CLI and agentsfleetd's internal command wiring
• Knowledge Base — HTTP Server (agentsfleetd)
• Knowledge Base — State store: Postgres layer for tenants, billing, models, and secrets