# Durable Agent Auth Phase C — frozen spec: scoped REST agent credentials

**Phase:** Durable Agent Auth **Phase C** (`DURABLE-AGENT-AUTH-C-a` Thinking freeze → `DURABLE-AGENT-AUTH-C-b` Auto build)
**Freeze status:** **CLEARED — independent freeze-review `pass` (round 2).** `DURABLE-AGENT-AUTH-C-b` (Auto) may start from this freeze. Tier-3 gates T1–T4 remain unauthorized.
**Date:** 2026-07-27
**Model (this artifact):** Thinking
**Branch:** `feat/durable-agent-auth-phase-c`
**Primary consumer (product):** VideoFactory-trend-agent (Paperclip / launchd) posting Hub proposals to `https://api.knowtation.store`
**Companion track docs (local, gitignored):** `development/durable-agent-auth/DURABLE-AGENT-AUTH-SPEC.md`, `development/durable-agent-auth/DURABLE-AGENT-AUTH-ROADMAP.md`

**Hard truth this freeze restates:** MCP Phase A (durable OAuth refresh) and Phase B (device code) **do not** fix REST-only / Paperclip / cron auth. Those paths still paste browser session material or short-lived Hub JWTs. Phase C is the REST machine credential.

## Freeze-contract declaration

```yaml
phase: DURABLE-AGENT-AUTH-C
outputs:
- id: durable-agent-auth-phase-c-freeze
  path: docs/DURABLE-AGENT-AUTH-PHASE-C-FREEZE.md
  frozen: true
frozen_inputs:
- docs/AGENT-INTEGRATION.md
- docs/HUB-API.md
- docs/openapi.yaml
- hub/gateway/refresh-token-store.mjs
- hub/lib/refresh-token-core.mjs
- hub/gateway/access-token-authz.mjs
- hub/gateway/server.mjs
- hub/auth-session.mjs
- netlify/functions/gateway.mjs
- hub/gateway/device-oauth-provider.mjs
review_stamp:
  reviewed_at: '2026-07-27T19:59:43Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:e9e1fb59b1643e183d8834abb710a67f36c4beef48b4ac38ec19533866ac95ee
tier3_gates:
- T1 merge to Muse main or muse-mirror → GitHub main (SD-14)
- T2 production deploy of Netlify gateway that mints/accepts agent credentials
- T3 operator mint of a live credential + placement into Paperclip/Automation secrets
- T4 any change that accepts browser `ktn_refresh` / session refresh cookies as agent credentials
```

Authoring provenance (local gitignored track; Auto must implement from this freeze alone):
`development/durable-agent-auth/DURABLE-AGENT-AUTH-SPEC.md`,
`development/durable-agent-auth/DURABLE-AGENT-AUTH-ROADMAP.md`.

---

## 1. Plain-language summary

Paperclip and cron jobs that talk to Knowtation over HTTP need a **password made for robots**, not a copy of the browser's "stay signed in" cookie. Today the trend-agent still uses a browser refresh secret. When that secret is reused, revoked, or the server store blips, automation dies with session errors — and no amount of "ignore expired JWT" client code can revive a dead browser session family.

Phase C adds a Hub button: mint a **scoped agent credential** once, put it in Paperclip env, revoke it in the Hub when done. That credential is vault-bound, not admin by default, and is a **different family** from browser login. Browser logout or cookie reuse cannot kill it; Hub revoke kills it immediately.

### Technical summary

Phase C ships an opaque credential `kt_agent_<id>.<secret>` (hash-at-rest, shown once), Hub mint/list/revoke/rotate APIs + Settings UI, a Netlify-mounted exchange that returns a short-lived JWT with `type: 'agent_access'` / JWT `typ: 'kt_agent_access'`, and scope-aware REST enforcement that extends the Phase A `mcp_access` guard. Default scopes for the primary consumer are `propose` + `vault:read` on an explicit vault id list. The opaque credential is **not** consume-on-use (unlike OAuth refresh rotation), so concurrent launchd jobs cannot self-revoke via `REFRESH_REUSE`. Browser session refresh (`ktn_refresh` cookie / `refresh-tokens-v1` families) remains a separate store namespace and must never be accepted as an agent credential.

---

## 2. Ground truth — what the code does today (file+line)

**Notation:** HTTP route paths are written without their leading slash (`api/v1/…`) so the freeze mechanical gate does not treat them as absolute machine paths.

Every row was read in this session.

| # | Fact | Citation |
| --- | --- | --- |
| G1 | Roadmap Phase C is TODO: scoped REST agent credentials + revoke | `development/durable-agent-auth/DURABLE-AGENT-AUTH-ROADMAP.md:15`, `:122-136` |
| G2 | Spec ranks long-lived scoped agent credential as the Paperclip/REST path; amends "no API-key-only path" when C ships | `development/durable-agent-auth/DURABLE-AGENT-AUTH-SPEC.md:85-96`, `:115`, `:148` |
| G3 | `AGENT-INTEGRATION.md` still says Phase C not shipped for REST/Paperclip/cron | `docs/AGENT-INTEGRATION.md:177` |
| G4 | `HUB-API.md` still: "There is no API-key-only path" | `docs/HUB-API.md:13` |
| G5 | Web session refresh on Netlify uses eventual blob `gateway-auth`; rotate throws → `SESSION_STORE_UNAVAILABLE` (503), cookie **not** cleared | `netlify/functions/gateway.mjs:14-21`; `hub/auth-session.mjs:141-145` |
| G6 | Native OAuth refresh catch also returns `SESSION_STORE_UNAVAILABLE` | `hub/gateway/native-oauth-provider.mjs:482-488` |
| G7 | Refresh core failures include `revoked` / `reuse` (mapped to `REFRESH_REVOKED` / `REFRESH_REUSE`) | `hub/lib/refresh-token-core.mjs:60-65`, `:300-308`; `hub/auth-session.mjs:65-69` |
| G8 | Blob refresh store documents ≤60s reuse-detection lag; MCP requires `consistency: 'strong'` file backend | `hub/gateway/refresh-token-store.mjs:11-17`, `:209-213` |
| G9 | Gateway chooses strong refresh store only when **not** `NETLIFY` | `hub/gateway/server.mjs:369-374` |
| G10 | MCP / native / device OAuth mount only when `shouldMountDurableAgentAuth` — **false on Netlify** | `hub/gateway/access-token-authz.mjs:165-167`; `hub/gateway/server.mjs:650-654`, `:732-733` |
| G11 | REST `getUserId` is scope-aware only for `type: 'mcp_access'` today | `hub/gateway/server.mjs:1496-1501`; `hub/gateway/access-token-authz.mjs:147-154` |
| G12 | Session JWTs mint `type: 'session'`; MCP/device mint `type: 'mcp_access'` (1h) | `hub/gateway/server.mjs:222-233`; `hub/gateway/device-oauth-provider.mjs:200-208`; `hub/gateway/mcp-oauth-provider.mjs:240-243` |
| G13 | Personal self-apply refuses `mcp_access` / `actorKind: 'agent'` / `humanActor: false` | `lib/hub-proposal-personal-self-apply.mjs:357-360`; `hub/gateway/server.mjs:3116-3118` |
| G14 | Device OAuth revoke exists but issues **MCP** tokens on the **persistent** host — not a Netlify REST agent credential | `hub/gateway/device-oauth-provider.mjs:1-12`, `:328-339`; `web/hub/hub.js:5217-5218` |
| G15 | Hub UI Connect cloud agent talks to `deviceAuthBase()` (MCP origin), not Netlify API host | `web/hub/hub.js:5217-5226` |
| G16 | Login refresh-cookie failure logs `authBlobPresent` distinguishing missing blob vs blob write reject | `hub/gateway/server.mjs:416-429` |

**Consumer evidence (operator-reported, not present in this workspace):** VideoFactory-trend-agent `born_free_trend_scout/knowtation.py` authenticates to `https://api.knowtation.store` via Paperclip env `KNOWTATION_HUB_REFRESH_TOKEN` copied from browser `ktn_refresh`. Client fix `cf07ab2` (ignore expired JWT + persist rotated refresh) is deployed on Automation; it cannot revive `REFRESH_REVOKED` / `REFRESH_REUSE` / `SESSION_STORE_UNAVAILABLE`. Trend-agent source was **not** found under this machine's workspace roots during this Thinking session — consumer wiring remains a **follow-on** after Hub Phase C ships (§9).

---

## 3. Incident diagnosis — why the trend-agent path dies

### 3.1 Error classes (server)

| Code | Meaning in current code | Why Paperclip+browser-refresh hits it |
| --- | --- | --- |
| `SESSION_STORE_UNAVAILABLE` | `store.rotate` **threw** (I/O / blob fault) — 503; cookie kept | Netlify `gateway-auth` blob hiccup, or missing blob → file fallback on read-only FS (`server.mjs:416-429`) |
| `REFRESH_REUSE` | Already-rotated token presented again — family burned | Concurrent launchd jobs sharing one refresh without serialized persist |
| `REFRESH_REVOKED` | Family/token revoked | Prior reuse burn, logout, or explicit revoke |
| `INVALID` / "Invalid session" | Malformed, unknown id, or secret mismatch | Stale paste, wrong env, or store prune after family death |

### 3.2 Why Phase A/B cannot fix this consumer

1. Phase A/B credentials are **MCP** (`mcp_access`) and mount on the **persistent MCP host**, not Netlify REST (`G10`, `G14`, `G15`).
2. Trend-agent is **REST-only** against `api.knowtation.store` (`G3`).
3. Browser refresh families live in `refresh-tokens-v1` on eventual blob (`G5`, `G8`) — hostile to concurrent cron.
4. Client-side JWT ignore + persist cannot recreate a revoked family (`G7`).

### 3.3 Reliability follow-on (server) — in scope for diagnosis, Tier-3 for prod flip

Phase C Auto **must** land credential APIs that do not depend on browser refresh rotate. Separately, hosted gateway-auth blob reliability (`SESSION_STORE_UNAVAILABLE`) remains a **browser-session** ops issue:

| Check | How |
| --- | --- |
| Blob provisioned | Netlify site function logs: `authBlobPresent=true` on refresh cookie issue (`G16`) |
| Rotate throws | Function logs around `@netlify/blobs` / `gateway-auth` during `POST api/v1/auth/refresh` |
| Concurrent reuse | Correlate `REFRESH_REUSE` with overlapping launchd/Paperclip PIDs using the same `ktn_refresh` |

Phase C DoD does **not** require fixing Netlify blob HA. It requires **stopping automation from using that store**.

---

## 4. Frozen product goal

An operator who is signed into Hub can:

1. Open **Settings → Integrations → Agent credentials (REST)**.
2. Mint a credential bound to one or more vault ids and a scope set (default safe set for trend-agent).
3. Copy the secret **once** into Paperclip / launchd env.
4. See the credential listed (metadata only) and **Revoke** it. Revoke blocks **new exchanges immediately**. Already-issued access JWTs die when `exp` elapses (access TTL ≤ **900s** — §5.2). Product copy must not claim sub-second kill of in-flight JWTs without a denylist (denylist is out of Phase C).
5. Browser login / logout / cookie reuse **never** shares a refresh family with that credential.

Success metric (product): trend-agent `script-live` healthcheck → create proposal → no cookie digging, no daily paste.

---

## 5. Token shape (frozen)

### 5.1 Opaque agent credential (long-lived secret)

| Field | Rule |
| --- | --- |
| Wire format | `kt_agent_<id>.<secret>` |
| Prefix | Literal `kt_agent_` (ASCII) before `<id>` — parsers reject tokens that lack this prefix for agent-credential endpoints |
| `<id>` | 128-bit CSPRNG, base64url (lookup key) |
| `<secret>` | 256-bit CSPRNG, base64url |
| At rest | Only `sha256(secret)` (same hash helper spirit as `hashSecret` in `refresh-token-core.mjs:72-74`) |
| Shown | **Once** at mint and once at owner-initiated rotate |
| Consume-on-use | **Forbidden.** Presentation for exchange does **not** rotate or invalidate the opaque credential |
| Prefix collision | Must not parse as browser refresh (`id.secret` without `kt_agent_`) or as JWT |

**Env var name (primary consumer):** `KNOWTATION_HUB_AGENT_CREDENTIAL`  
**Forbidden env reuse:** Do not document `KNOWTATION_HUB_REFRESH_TOKEN` / browser `ktn_refresh` as a Phase C credential.

### 5.2 Access JWT (short-lived)

Minted only by the agent exchange endpoint (§6.2).

| JWT claim | Required value |
| --- | --- |
| `sub` | Owner user id (`provider:id`) from credential record |
| `type` | `'agent_access'` (payload discriminator, parallel to `mcp_access` / `session`) |
| `typ` | Payload claim **required:** `typ: 'kt_agent_access'`. Sign with `jsonwebtoken` options `{ expiresIn, header: { typ: 'kt_agent_access' } }` so the JOSE header matches. Verification requires payload `typ === 'kt_agent_access'` (header typ is defense-in-depth, not a substitute). |
| `aud` | `'knowtation-hub-rest'` (string). REST verification for `agent_access` **must** require this `aud`. Session and `mcp_access` tokens without this `aud` remain accepted on their existing paths; `agent_access` without matching `aud` is rejected |
| `scopes` | string array copied from credential record at mint/exchange (re-checked against ceiling) |
| `vault_ids` | string array copied from credential record |
| `cid` | credential id (public metadata id, not the secret) |
| `agent` | optional label (≤128 chars) from mint |
| `iat` / `exp` | standard; default access TTL **900s** (15m). Max access TTL **900s** (not configurable upward in Phase C). |

Signed with the same `SESSION_SECRET` as other Hub JWTs (shared verification), **but** authorization must be type-aware (`G11` extension) so role allowlists cannot elevate agent tokens (same SEC-KN-3 posture as `mcp_access`).

### 5.3 Explicit non-goals for token shape

- Not a god JWT with extended `HUB_JWT_EXPIRY`.
- Not a copy of HttpOnly refresh cookie.
- Not `type: 'mcp_access'` (MCP Phase A/B remains separate).
- Not `type: 'session'` (SEC-SEAM session-bound self-apply stays human-only).

---

## 6. Hub APIs (frozen)

All paths under `api/v1/auth/agent/*` mount on the **REST gateway including Netlify** (`api.knowtation.store`). They **must not** be gated by `shouldMountDurableAgentAuth` (that helper excludes Netlify — `G10`). Offline-locked mode: endpoints **unmounted / 503** with explicit code `AGENT_CREDENTIALS_UNSUPPORTED_OFFLINE_LOCKED` (parity with durable-agent-auth unsupported under offline-lock — SPEC §14).

### 6.1 Mint — `POST api/v1/auth/agent/credentials`

**Auth:** Bearer **session** JWT only (`type: 'session'` or legacy session). Reject `mcp_access` and `agent_access` as mint callers (fail-closed: agents cannot mint agents).

**Body (JSON):**

```json
{
  "name": "videofactory-trend-agent",
  "vault_ids": ["default"],
  "scopes": ["propose", "vault:read"],
  "ttl_seconds": 7776000
}
```

| Field | Rules |
| --- | --- |
| `name` | required, 1–128 chars, display label |
| `vault_ids` | required, non-empty array of non-empty strings; each id trimmed; max 32 vaults |
| `scopes` | optional; default **`["propose","vault:read"]`**; must be ⊆ allowed set ∩ caller ceiling |
| `ttl_seconds` | optional; default **7_776_000** (90d); min 3600; max **7_776_000** |

**Allowed scope vocabulary (Phase C):**

| Scope | Permits |
| --- | --- |
| `vault:read` | Safe HTTP methods on vault-scoped REST |
| `propose` | Create proposals only (see §7) — **not** approve/discard/apply |
| `vault:write` | Mutating REST including direct note write (opt-in; not default) |
| `admin` / `vault:admin` | **Forbidden** on mint — always rejected |

**Caller ceiling:** scopes ∩ `scopesForRole(roleForSub(sub))` plus the Phase C vocabulary. A member cannot mint scopes their role lacks. `propose` is allowed for member/editor/admin even when not listed in today's `scopesForRole` (it is an agent-only scope additive). `vault:write` still requires the caller's role to include `vault:write`.

**Response 201 (secret once):**

```json
{
  "id": "<cid>",
  "name": "videofactory-trend-agent",
  "credential": "kt_agent_<id>.<secret>",
  "vault_ids": ["default"],
  "scopes": ["propose", "vault:read"],
  "expires_at": 1730000000000,
  "created_at": 1720000000000
}
```

Never log `credential`. Never return `credential` on list/get.

**Soft limit:** reject mint when caller already has **25** non-revoked credentials → **409** `{ "code": "AGENT_CREDENTIAL_LIMIT" }`.

### 6.2 Exchange — `POST api/v1/auth/agent/token`

**Auth:** none via session. Present opaque credential via JSON body `credential` **or** `Authorization: Bearer kt_agent_…`.

**Response 200:**

```json
{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scopes": ["propose", "vault:read"],
  "vault_ids": ["default"]
}
```

**Fail-closed:** unknown / bad secret / expired / revoked → **401** `{ "code": "AGENT_CREDENTIAL_INVALID" }` (uniform message; no oracle). Store I/O throw → **503** `{ "code": "AGENT_CREDENTIAL_STORE_UNAVAILABLE" }` (does **not** revoke).

**Bearer parsing:** If `Authorization` starts with `Bearer kt_agent_`, treat the remainder as opaque credential material and **never** pass it to `jwt.verify`. Non-`kt_agent_` bearers on this route → 401.

Exchange **updates** `last_used_at` only; does not rotate opaque secret.

**Soft limit:** best-effort rate limit **60/min** per credential id → **429** `{ "code": "AGENT_CREDENTIAL_RATE_LIMIT" }`. On Netlify isolates this is best-effort only and must fail open to 200/401/503 paths rather than throw.

### 6.3 List — `GET api/v1/auth/agent/credentials`

**Auth:** session JWT. Returns only credentials where `sub` matches caller.

**Response 200:** `{ "credentials": [ { id, name, vault_ids, scopes, created_at, expires_at, last_used_at, revoked } ] }` — **no** hashes, **no** secrets.

### 6.4 Revoke — `DELETE api/v1/auth/agent/credentials/:id`

**Auth:** session JWT; must own `id`. Sets `revoked: true` (or deletes record). **Response 200** `{ "ok": true }` even if already revoked (idempotent).

Revoke is immediate for **new** exchanges. Access JWTs already issued remain valid until `exp` (≤900s). No JWT denylist in Phase C.

### 6.5 Rotate — `POST api/v1/auth/agent/credentials/:id/rotate`

**Auth:** session JWT; owner only. Invalidates old secret hash; returns new `credential` once (same metadata id **or** new id — freeze: **keep id**, replace hash). Old opaque secret fails exchange immediately.

### 6.6 Store

| Rule | Value |
| --- | --- |
| Module | New `hub/gateway/agent-credential-store.mjs` (+ pure helpers in `hub/lib/agent-credential-core.mjs` if needed) |
| Blob (Netlify) | Dedicated store: `getStore({ name: 'gateway-agent-credentials', consistency: 'eventual' })` wired in `netlify/functions/gateway.mjs` as `globalThis.__knowtation_gateway_agent_cred_blob`. Persist shape `{ "credentials": { "<cid>": { ... } } }` under blob key `agent-credentials-v1`. **Not** the `gateway-auth` / `refresh-tokens-v1` store. |
| File fallback | `data/hosted_agent_credentials.json` under `KNOWTATION_GATEWAY_DATA_DIR` |
| Namespace | **Must not** write into `refresh-tokens-v1` / `createGatewayRefreshStore` records |
| Meta sanitize | `name`, `vault_ids`, `scopes`, `agent` only — bounded lengths |

---

## 7. REST acceptance + scope enforcement (frozen)

### 7.1 `getUserId` / authz extensions

Extend `hub/gateway/access-token-authz.mjs`:

1. `isAgentAccessPayload(payload)` → `payload.type === 'agent_access'`.
2. `resolveActorTokenClass` adds `'agent_access'`.
3. `isSessionBoundActor` remains true **only** for `type: 'session'` (agent_access → false).
4. `subFromVerifiedPayload(payload, { method, path })`:
   - for `agent_access`: require `aud === 'knowtation-hub-rest'` and `typ === 'kt_agent_access'`; enforce `agentScopesPermitMethod(scopes, method, path)`; return `sub` or null.
   - `getUserId(req)` must pass `path` from the request path (no query).
5. `mayApplyAdminAllowlistOverride` → false for `agent_access` (same as mcp_access).
6. `roleFromVerifiedAccessPayload` / `resolveHostedActorRole`: agent_access role from scopes only (`vault:write`/`admin` → never admin from allowlist; `propose` alone → `member`).

### 7.2 `agentScopesPermitMethod(scopes, method, path)`

Evaluate in order:

1. If scopes include `vault:write` or `admin` or `vault:admin` → allow (read + mutate), same ceiling spirit as `mcpScopesPermitMethod`.
2. Else if method is safe (GET/HEAD/OPTIONS) → allow only when scopes include `vault:read`.
3. Else (mutating) → allow only when scopes include `propose` **and** path is in §7.3; otherwise deny.
4. `propose` without `vault:read` still allows §7.3 mutating creates (trend-agent write path) but denies all reads — mint UI defaults both on; mint API allows `propose`-only only if explicitly requested (not the default).

### 7.2.1 Mint scope defaults

Default mint body scopes: `["propose","vault:read"]`. Reject empty scopes. Reject any admin scope.

### 7.3 Propose-create path allowlist (Phase C)

With `propose` and without `vault:write`, mutating requests are allowed **only** when the normalized path matches one of:

- `api/v1/proposals` (exact)
- `api/v1/tasks/proposals` (exact)
- `api/v1/task-loops/proposals` (exact)

**Normalize:** strip query string; strip a single leading `/` if present; compare case-sensitive. Method must be `POST`.

**Denied** even with `propose`: approve, discard, apply-approved, enrich, evaluation write, direct `POST api/v1/notes`, media write routes, delegation grant mint, admin routes.

Path-prefix scoping (`projects/<slug>/**`) is **Phase D** — out of Phase C Auto. Phase C may still mint vault-bound credentials without path prefixes.

### 7.4 Vault binding

For `agent_access`, every vault-scoped request must send `X-Vault-Id` whose value is in `payload.vault_ids`. Missing header is treated as vault id `default` (same as today's gateway default at `hub/gateway/server.mjs` hosted context resolution) and still must be ∈ `vault_ids`. Non-matching → **403** `{ "code": "AGENT_VAULT_FORBIDDEN" }`.

**Frozen choke point:** export `assertAgentVaultAllowed(payload, vaultId)` from `access-token-authz.mjs` and call it from `getHostedAccessContext` (and any self-hosted twin that resolves vault for agent tokens) **before** bridge/canister forwarding. Unit + integration tests must prove wrong vault and disallowed `default` fail.

### 7.5 Self-apply / SEC-KN-3

`resolveHostedActorRole` must treat `agent_access` like `mcp_access` for `humanActor` / `actorKind: 'agent'` / `tokenType`. Extend `roleEligibleForPersonalSelfApply` to also refuse `tokenType === 'agent_access'`.

### 7.6 MCP optional bridge

Phase C DoD: **REST required**. If an `agent_access` JWT is presented to MCP on the persistent host, behavior is unspecified/optional; do not block Phase C on MCP ACL work. Do not teach MCP OAuth to mint `kt_agent_` secrets.

---

## 8. Hub UI (frozen)

**Location:** Settings → Integrations → new section **Agent credentials (REST / Paperclip / cron)** — sibling to Hub API session copy and Connect cloud agent.

**Controls:**

1. Name + vault multi-select (default current vault) + scope checkboxes (`propose`, `vault:read` default on; `vault:write` off + warning).
2. **Mint** → modal shows secret once + copy button composing:

```text
KNOWTATION_HUB_URL=https://api.knowtation.store
KNOWTATION_HUB_VAULT_ID=<vault>
KNOWTATION_HUB_AGENT_CREDENTIAL=kt_agent_…
```

3. List table: name, vaults, scopes, created, expires, last used, **Revoke**, **Rotate**.
4. Honesty copy: "Not a browser session. Revoke blocks new token exchange immediately; in-flight access JWTs end within 15 minutes. Do not paste Hub refresh cookies into Paperclip."

UI calls Netlify REST base (`apiBase`), **not** `deviceAuthBase()` / MCP origin.

---

## 9. Primary consumer contract — VideoFactory-trend-agent (follow-on)

**Not** part of Knowtation Phase C Auto DoD codepaths, but **frozen interface** for the next session that wires the agent:

| Item | Value |
| --- | --- |
| Hub URL | `KNOWTATION_HUB_URL=https://api.knowtation.store` |
| Vault | `KNOWTATION_HUB_VAULT_ID` |
| Secret | `KNOWTATION_HUB_AGENT_CREDENTIAL` (opaque) |
| Flow | exchange → `Authorization: Bearer <access_token>` + `X-Vault-Id` → healthcheck → `POST api/v1/proposals` |
| Persist | Access JWT may be cached until near `exp`; opaque credential is stable (no rotate-on-use) |
| Concurrency | Multiple launchd jobs may exchange concurrently; **no** shared browser refresh file |
| Forbidden | Reading `ktn_refresh` cookies; using `KNOWTATION_HUB_REFRESH_TOKEN`; HR-4 resume as substitute |
| Prove | healthcheck → create proposal without cookie digging |

Serialize-across-launchd guidance applies only if a future design reintroduces rotate-on-use; Phase C opaque credentials make that unnecessary.

---

## 10. Docs amendments (same PR as Auto)

| Doc | Change |
| --- | --- |
| `docs/HUB-API.md` §1.1 | Replace "no API-key-only path" with: "No unscoped long-lived API keys. Scoped agent credentials (`kt_agent_…`) are the machine path for REST/Paperclip/cron; session JWTs remain for interactive use." |
| `docs/AGENT-INTEGRATION.md` | Mark Phase C shipped; document env vars + exchange; keep MCP Phase A/B rows honest |
| `docs/openapi.yaml` | Add `auth/agent/credentials`, `auth/agent/credentials/{id}`, rotate, `auth/agent/token` |
| `development/durable-agent-auth/DURABLE-AGENT-AUTH-ROADMAP.md` | Phase C → DONE after BV pass (local) |
| Hub Settings copy | Point automations at Agent credentials section |

No docs-only PR to `main`.

---

## 11. Test matrix (seven tiers — Aaron standard)

| Tier | File (Auto creates) | Must prove |
| --- | --- | --- |
| unit | `test/agent-credentials-unit.test.mjs` | parse `kt_agent_`; hash; scope ceiling; propose path allowlist; aud check |
| integration | `test/agent-credentials-integration.test.mjs` | mint→exchange→REST propose; revoke→exchange 401; wrong vault 403 |
| e2e | `test/agent-credentials-e2e.test.mjs` | session mint + list + rotate + revoke against test gateway |
| stress | `test/agent-credentials-stress.test.mjs` | concurrent exchanges with same opaque credential do **not** revoke |
| data-integrity | `test/agent-credentials-data-integrity.test.mjs` | secret never persisted; list omits credential; namespace ≠ refresh-tokens-v1 |
| performance | `test/agent-credentials-performance.test.mjs` | exchange p95 budget under local store (document threshold in test) |
| security | `test/agent-credentials-security.test.mjs` | mcp_access cannot mint; agent cannot admin via allowlist; propose cannot approve; browser refresh token rejected by agent exchange; offline-lock unmount; no secret in logs helpers |

Security tier **must fail against pre-Phase-C code** (regression shape).

---

## 12. Fail-closed rules (checklist)

1. No mint without session human token.
2. No admin scopes on agent credentials.
3. No write of agent records into browser refresh store.
4. No accept of `ktn_refresh` / non-`kt_agent_` opaque at `auth/agent/token`.
5. No elevate via `HUB_ADMIN_USER_IDS` for `agent_access`.
6. No self-apply eligibility for `agent_access`.
7. No Netlify exclusion for Phase C routes (inverse of MCP mount rule).
8. Offline-locked → unsupported.
9. Store fault → 503 without destroying credential.
10. Never log or commit secrets.

---

## 13. Implementation map (Auto; no redesign)

| Piece | Path |
| --- | --- |
| Core | `hub/lib/agent-credential-core.mjs` |
| Store | `hub/gateway/agent-credential-store.mjs` |
| Router | `hub/gateway/agent-credential-routes.mjs` |
| Mount | `hub/gateway/server.mjs` + `netlify/functions/gateway.mjs` blob global |
| Authz | `hub/gateway/access-token-authz.mjs` (+ call sites in `server.mjs` / self-apply) |
| UI | `web/hub/index.html`, `web/hub/hub.js` |
| Docs | §10 list |
| Tests | §11 list |

---

## 14. Tier-3 gates (do not execute in Auto)

- Merge / muse-mirror / production deploy
- Live credential mint into real Paperclip secrets
- Any policy that re-allows browser refresh as automation auth

---

## 15. Review record

| Round | Reviewer | Verdict | Resolution |
| --- | --- | --- | --- |
| 1 | Freeze-review loop (thinking) | findings | F1 leading-slash routes → SEC-SEAM notation; F2 revoke "immediate" vs JWT TTL honesty (900s); F3 JOSE typ weasel → mandatory payload+header; F4 vault choke point named; F5 scope table contradictions collapsed; F6 mint/exchange soft limits; F7 gitignored frozen_inputs demoted to provenance note; F8 `getUserId` must pass `path` |
| 2 | Freeze-review loop (thinking) | pass | Re-read §§1–16 + G1–G16 citations. Fixed residual F9 store "or" weasel → dedicated blob; F10 propose path normalize rule. Completeness: interfaces, fail-closed, seven-tier matrix, Tier-3 gates present. No open design decisions for Auto. Mechanical `ok review --freeze` = pass (stamp present). No escalating category open. |

---

## 16. Definition of Done (Phase C Auto) — after this freeze passes review

- [ ] All §6 APIs implemented and mounted on Netlify-capable gateway
- [ ] Authz §7 enforced; self-apply refuses agent_access
- [ ] Hub UI §8
- [ ] Docs §10 in same PR
- [ ] Seven-tier tests §11 green
- [ ] build-verification-review → `pass`
- [ ] Roadmap Phase C + handover NEXT updated together (SD-17)
- [ ] No secrets in git
- [ ] Trend-agent wiring tracked as **follow-on** (§9), not falsely marked done inside Hub PR