Durable agent auth — roadmap

Spec freeze: DURABLE-AGENT-AUTH-SPEC.md (2026-07-12)
Branch (thinking): feat/durable-agent-mcp-auth-thinking
Branch (Phase A build): feat/durable-mcp-oauth-refresh
Owner approval required before any Build phase marked Auto starts.

Phase routing

Never Outline/Plan on Auto. Never mark DONE without green required tests.

Phase 0 — Thinking freeze

DoD: Spec answers all design questions; recommendation + interim labeled; Build-ready Phase A prompt in OVERSEER handover.
Status: DONE.

Phase A — Durable MCP OAuth refresh + Hermes spike

Mode: Spike (Thinking, short) then Auto Build against frozen interfaces below.
Status: DONE (2026-07-12).

Spike (HARD GATE — completed)

• Upstream Hermes: auth: oauth, token cache, headless paste-back — supported (docs + PR #5420).
• Hostinger Managed Hermes version: unverified this session → spike verdict partial.
• Rank 1 ↔ Rank 2 swap applied: Phase B device authorization is primary for headless Hostinger; Phase A durable MCP OAuth remains shipped for Cursor + OAuth-capable Hermes.
• Evidence: docs/evidence/durable-agent-auth/hermes-oauth-spike-2026-07-12.md.

Frozen interfaces (Build) — implemented

1. Reuse existing store — KnowtationOAuthProvider takes createGatewayRefreshStore({ consistency: 'strong' }) (same instance as native OAuth on persistent host).
2. Strong consistency — file backend; blob prohibited for MCP (and for non-Netlify gateway refresh store).
3. Lifetimes: access 3600s; refresh DEFAULT_TOKEN_TTL_MS (30d); family DEFAULT_FAMILY_TTL_MS (90d).
4. MCP OAuth 2.1 discovery/token unchanged for Cursor Sign-in.
5. Public URL https://mcp.knowtation.store/mcp.
6. Refresh meta.agent (+ client_id / scopes) for multi-Hermes revoke.
7. Offline-lock: shouldMountDurableAgentAuth — endpoints unmounted; documented.

DoD checklist

• [x] Gateway restart does not invalidate unexpired MCP refresh families (integration test).
• [x] Unit + integration + e2e + security + data-integrity + security-stress tests.
• [x] Scope-aware REST: mcp_access vault:read cannot write (access-token-authz + getUserId).
• [x] Offline-lock documented + asserted.
• [x] Hermes spike notes (no secrets).
• [x] docs/AGENT-INTEGRATION.md always-on section in same PR as code.

Test tiers

Phase B — Hub “Connect cloud agent”

Mode: Thinking (wireframes + device-code vs guided OAuth) → Auto.
Priority: Primary for headless Hostinger after Phase A spike Rank swap.

Frozen product goal

A non-SSH user completes “connect my cloud agent to my vault” in one Hub flow (device code preferred when loopback impossible).

DoD

• Settings → Integrations → Connect cloud agent
• Issues user_code / verification URL or deep-links Hermes MCP OAuth steps
• Agent ends with refreshable credential (MCP and/or agent refresh)
• Revoke from same panel
• Docs + Hub copy updated in same PR

Test tiers

unit (device code store), integration (poll → token), e2e (Hub UI happy path), security (code brute-force limits, single-use).

Phase C — Scoped agent credentials (REST)

Mode: Thinking (JWT/kt_agent_ prefix shape, OpenAPI) → Auto.

Frozen invariants

• Scoped, rotatable, vault-bound, Hub-revocable
• Default: no admin; prefer propose-only option
• Amends HUB-API.md “no API-key-only path”

DoD

• Mint once + list + revoke APIs + Hub UI
• REST accepts credential; MCP optional bridge
• Seven-tier tests for credential module (Aaron standard)

Phase D — Propose-only + path prefix

Mode: Thinking → Auto.

• Agent may create proposals under projects/<slug>/** without direct POST /notes
• Enforce in gateway + MCP ACL
• Hard dependency: §8 confused-deputy scope-elevation closed in Phase A for mcp_access on REST mutating methods. Do not advertise propose-only / path-prefix scopes until remaining role-elevation edges (if any) are closed in Thinking freeze for D.

Phase E — Marketing honesty

Ship with whichever of A/B/C lands first that changes the user-visible connect story. No docs-only PR to main. Phase A docs ship with this code PR.

Build status table