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.
Status: DONE (2026-07-13) on branch feat/connect-cloud-agent-device-code.

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).

Implemented

• POST /api/v1/auth/device/authorize → device_code + user_code + verification URIs
• Hub Settings → Integrations → Connect cloud agent — approve/deny user_code; pending list; non-secret setup pack
• POST /api/v1/auth/device/token — RFC 8628 poll → mcp_access + durable refresh (createGatewayRefreshStore strong)
• Refresh + revoke endpoints; discovery metadata; GET /setup-pack
• Session-token honesty on Copy button; landing Hermes tile = import; AGENT-INTEGRATION Hostinger mcp-remote interim
• Evidence: docs/evidence/durable-agent-auth/hermes-hostinger-mcp-remote-2026-07-13.md

DoD checklist

• [x] Settings → Integrations → Connect cloud agent
• [x] Issues user_code / verification URL
• [x] Agent ends with refreshable credential (MCP mcp_access + refresh)
• [x] Revoke endpoint (refresh token); Hub can deny pending codes
• [x] Docs + Hub copy updated in same PR
• [x] Tests: unit, integration, e2e, security, data-integrity, performance, stress

Test tiers

Operator follow-up (not blocking DoD)

• Deploy persistent MCP gateway with this branch so Hub device UI (deviceAuthBase → mcp.knowtation.store) hits live routes.
• Re-verify hermes mcp login on Hostinger only after upstream fixes; until then keep mcp-remote interim documented.
• Hermes-native device-code client wiring (agent polls Knowtation device endpoints) — document once a Hermes version consumes RFC 8628 against custom issuers.

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