Companion App — Phase 3 Session Prompt (OAuth Native/Public Client — PKCE + Loopback Redirect, JWT in OS Keychain)

Use this to seed a fresh chat session. Start that session on a thinking model (Opus) — Phase 3 is a full 🧠 phase (auth-protocol/crypto correctness; subtle deviations create real account-compromise paths), not Hybrid. Stay on a thinking model for the whole phase.

0. Copy-paste prompt (paste this into the new session)

You are continuing the Knowtation Companion App build on the Muse branch feat/companion-app.
This is PHASE 3 — OAuth native/public client: PKCE + loopback redirect (RFC 7636 / RFC 8252),
no device-side client secret, JWT in the OS keychain. It is a 🧠 Thinking phase: auth-protocol and
crypto correctness, where a subtle mistake is an account-compromise path, not a style nit. Argue
each control against an attacker model; do not pattern-match. Stay on a thinking model the whole phase.

FIRST, read these in full (do not skip):
  - docs/COMPANION-APP-DESIGN-AND-AUTHORIZATION-GATE.md  (§3 OAuth model; §4.1 the per-session
    bearer token; §12 phase table row 3; the "DOES NOT approve (no code)" list — ESPECIALLY
    "Any change to OAuth client registration or scopes" and "no new local HTTP listener")
  - docs/COMPANION-APP-MODEL-ROUTING-AND-ENRICHMENT-ARCHITECTURE.md  (§5 OAuth for the companion,
    §3 client-side constraint)
  - docs/COMPANION-APP-PHASE-1-ADAPTER-SEAM.md and lib/model-runtime-lane.mjs  (the seam; lane logic)
  - docs/COMPANION-APP-PHASE-2-LOOPBACK-SECURITY.md and lib/companion-loopback-guard.mjs  (Phase 2
    output: the per-session loopback bearer token whose CUSTODY this phase defines; both the loopback
    inference socket AND this phase's loopback redirect listener are bound together in Phase 5)
  - hub/gateway/mcp-oauth-provider.mjs  (EXISTING server-side "PKCE + dynamic client registration"
    OAuth provider — read it to learn what a native/public + loopback-redirect client needs, and to
    determine whether that is already supported or would require a server-side OAuth change)
  - hub/auth-session.mjs and hub/lib/refresh-token-core.mjs  (EXISTING JWT session + refresh-token
    custody patterns; the browser uses an HttpOnly cookie — the companion uses the OS keychain instead)
  - hub/bridge/server.mjs  (EXISTING patterns to stay consistent with: signState/verifyState HMAC
    state, userIdFromJwt = jwt.verify(token, SESSION_SECRET), and the GitHub OAuth connect flow)
  - lib/github-connection.mjs  (existing OAuth connection helper)

RESOLVE THESE SCOPE QUESTIONS BEFORE WRITING ANY LISTENER / NETWORK / KEYCHAIN CODE (ask me):
  1. PURE-THEN-BIND scope (mirrors Phase 1 and Phase 2). Proposed: Phase 3 builds the OAuth/PKCE
     PROTOCOL CORE as pure, fully-tested functions (PKCE pair + S256 challenge, state/nonce generate
     + constant-time validate, RFC 8252 loopback-redirect validation, authorization-response
     validation, token-REQUEST builder, token-RESPONSE validator, JWT expiry/refresh DECISION) with
     NO socket bind, NO network fetch, and NO real OS-keychain I/O. The loopback redirect LISTENER
     bind, the actual TLS POST to the token endpoint, opening the system browser, and the real
     Keychain/DPAPI/libsecret calls are deferred to Phase 5 (the shared bind gate that also opens the
     Phase 2 inference socket), or a separate explicit gate. Confirm this scope, or approve real I/O
     in Phase 3.
  2. CLIENT REGISTRATION boundary. The gate's "DOES NOT approve" list forbids "Any change to OAuth
     client registration or scopes." Confirm whether the existing provider
     (hub/gateway/mcp-oauth-provider.mjs) ALREADY supports a native/public client with a loopback
     redirect at the SAME scopes as the web session — in which case Phase 3 is purely client-side
     protocol code — or whether enabling that is a SERVER-SIDE OAuth change that needs its own gate
     before Phase 3 can target it. Do NOT register a new client or alter scopes in this phase.

THEN produce, in order:
  1. A short adversarial THREAT MODEL section. Attacker capabilities and the EXACT control that stops
     each: (a) authorization-code interception by a malicious local app on the loopback redirect
     (→ PKCE S256, code bound to code_verifier); (b) CSRF / session-fixation on the callback
     (→ state, constant-time compare); (c) authorization-server / redirect mix-up (→ exact loopback
     redirect validation per RFC 8252; consider RFC 9207 `iss`); (d) PKCE downgrade to "plain"
     (→ enforce method=S256, reject plain); (e) open-redirect / redirect_uri manipulation (→ strict
     loopback-literal allowlist, no wildcard); (f) JWT/refresh-token theft at rest (→ OS keychain,
     never a plaintext file, never logged); (g) client-secret extraction from the distributed binary
     (→ public client, NO secret on device); (h) authorization-response replay (→ one-time state,
     single-use code); (i) embedded-webview phishing (→ system browser only, RFC 8252).
  2. lib/companion-oauth-pkce.mjs — pure functions, no I/O, no env reads, no network, no socket:
       createPkcePair()                         → { codeVerifier, codeChallenge, method:'S256' }  (CSPRNG)
       computeCodeChallenge(codeVerifier)       → base64url(SHA-256(verifier))  (pure, S256 only)
       createOAuthState() / createNonce()       → high-entropy values  (CSPRNG)
       buildAuthorizationUrl({...})             → pure; response_type=code, S256, scope = web-session
                                                  scopes, exact loopback redirect_uri
       validateRedirectUri(uri, { allowedHosts })→ RFC 8252 loopback rules  (pure, fail-closed)
       validateAuthorizationResponse({ params, expectedState }) → constant-time state compare; reject
                                                  on error param; extract code  (fail-closed; NO
                                                  secret/code/state in any reason or thrown error)
       buildTokenRequest({...})                 → pure request descriptor (grant_type=authorization_code,
                                                  code, code_verifier, redirect_uri, client_id);
                                                  NO fetch — returns the body for Phase 5 to send
       validateTokenResponse(json)              → shape-validate; extract { accessToken, refreshToken?,
                                                  expiresIn, tokenType }; fail-closed on anything off
       decideTokenRefresh({ expiresAt, now, skewMs }) → 'valid' | 'refresh' | 'reauth'  (pure)
     Enforce: S256 only (reject 'plain'); constant-time comparisons; fail-closed on anything
     ambiguous/missing; NEVER put a token/JWT/refresh-token/code/code_verifier/state into a returned
     reason, a return value meant for logging, or any thrown error.
     (If a token-CUSTODY decision layer is warranted, add lib/companion-token-custody.mjs as a pure
     module that takes an INJECTED keychain adapter interface — no real keychain calls — defining
     what is stored, JWT/refresh lifecycle, and the per-session loopback token from Phase 2.)
  3. The 7-tier test suite test/companion-oauth-pkce-*.test.mjs (and custody tests if that module
     exists). The SECURITY tier is the centerpiece and must cover, at minimum: code_challenge is
     correct S256 of the verifier and verifier has sufficient entropy/length (RFC 7636 §4.1);
     'plain' method is rejected (no downgrade); state mismatch → reject (constant-time, no oracle);
     an authorization-server error response is surfaced without leaking; a non-loopback or
     wildcard/foreign redirect_uri is rejected (RFC 8252); the authorization URL never contains a
     client secret and uses response_type=code + S256; the token request carries the code_verifier
     (proves PKCE binding) and no client secret; a malformed/oversized token response fails closed;
     replay (reused state) is rejected; and NO secret (code, code_verifier, state, access/refresh
     token, JWT) appears in any output, reason, log, or thrown error.
  4. docs/COMPANION-APP-PHASE-3-OAUTH-PKCE.md — the accepted design + the module contract + the
     threat-model→control mapping + the RFC citations (7636/8252, and 9207 if adopted) + EXACTLY what
     Phase 5 must do to bind safely: open the system browser (never an embedded webview), bind the
     loopback redirect listener on 127.0.0.1 with an ephemeral port, perform the token-endpoint POST
     over TLS, store the JWT + refresh token in the OS keychain (Keychain/DPAPI/libsecret), and the
     custody/rotation rules for both the JWT and the Phase 2 per-session loopback token.

CONSTRAINTS:
  - Muse-canonical (knowtation). Commit on feat/companion-app via `muse code add` + `muse commit`.
    Do NOT open a docs-only PR to main (owner policy). Do NOT use git/gh for knowtation work.
  - Honor the gate "DOES NOT approve" list: no new local HTTP listener bound this phase; NO change to
    OAuth client registration or scopes; the companion acts at the SAME scopes as the web session.
  - RFC-correct: cite RFC 7636 (PKCE, S256 only), RFC 8252 (native apps: system browser + loopback
    redirect + exact match with variable loopback port), and consider RFC 9207 (iss) for mix-up
    defense. Use Node's crypto (randomBytes / createHash / timingSafeEqual) — NEVER hand-roll crypto.
  - Aaron's standards: 7 test tiers + strong docstrings; no temporary fixes; no assumptions stated as
    fact (verify against the files above); fail-closed on anything ambiguous; security first.
  - Verify the full suite is green before committing. Give a plain-language + technical summary and a
    clear recommendation when done (Rule #7).

When Phase 3 is complete and committed, recommend the sequencing of Phase 4 (bundled runtime manager,
⚡ Sonnet/auto) vs Phase 5 (companion shell — the SHARED BIND GATE that opens BOTH the Phase 2
inference socket AND this phase's loopback redirect listener, and performs the real network/keychain
I/O). Note that Phase 5's bind step is itself security-critical and may warrant its own 🧠 gate.

1. Where we are (state at start of Phase 3)

Branch: feat/companion-app (Muse-canonical, knowtation). Commits on it so far:

• Phase 0 Decision Record (gate §13, D1–D3).
• Phase 1 seam + 7-tier tests (lib/model-runtime-lane.mjs).
• Phase 2 loopback security core (lib/companion-loopback-guard.mjs + 7-tier suite, 102 cases green; docs/COMPANION-APP-PHASE-2-LOOPBACK-SECURITY.md). Pure request-guard; no socket bound; the real listener bind was deferred to Phase 5.

Why Phase 3 now (gate §12, row 3 — 🧠 Thinking):

OAuth native/public client — PKCE + loopback redirect (RFC 7636/8252), no device-side secret, JWT in OS keychain (Keychain/DPAPI/libsecret) (§3). Depends on Phase 1.

Phase 3 is auth/crypto protocol correctness. It also closes the custody loop for Phase 2: the per-session loopback bearer token (expectedToken in the guard) is generated and stored alongside the OAuth JWT in the OS keychain.

2. The pure-then-bind discipline (carried from Phases 1–2)

Build the protocol/crypto decisions as pure, deterministic, fully-tested functions; defer every real-world bind/I/O action to Phase 5 behind an explicit gate. This is the pattern that has kept the most dangerous surfaces closed while proving the logic:

3. Mandatory controls / standards to argue against the attacker

1. PKCE S256 only (RFC 7636). code_challenge = base64url(SHA-256(code_verifier)); verifier is a high-entropy 43–128-char string. Reject plain — no downgrade.
2. No client secret on the device — public/native client. The distributed binary contains no secret; security comes from PKCE + loopback redirect, not a shared secret.
3. System browser, not an embedded webview (RFC 8252 §8.12) — embedded webviews enable credential phishing and defeat SSO.
4. Loopback redirect, exact validation (RFC 8252 §7.3) — http://127.0.0.1:<ephemeral-port>/... (prefer the IP literal over localhost); allow the variable loopback port; reject any non-loopback or wildcard redirect.
5. state (CSRF) + one-time use — high-entropy, compared constant-time, single-use; reject replay. Optionally nonce if an ID token is involved, and iss (RFC 9207) for AS mix-up.
6. JWT + refresh token in the OS keychain — never a plaintext file; never logged; never in a URL or an error. Consistent with hub/lib/refresh-token-core.mjs semantics (reuse/expiry handling).
7. Same scopes as the web session; no client/scope change (gate "DOES NOT approve").
8. No secret in any output/log/error — code, code_verifier, state, access/refresh token, JWT.
9. Fail-closed on anything ambiguous, missing, malformed, or unrecognised.

4. Threat model to reason against (argue each — do not pattern-match)

• Authorization-code interception by another local app racing the loopback redirect → PKCE S256 binds the code to the code_verifier the attacker never saw; a stolen code is useless.
• CSRF / session fixation on the callback → state constant-time match + single-use.
• AS / redirect mix-up → exact loopback redirect validation; consider RFC 9207 iss.
• PKCE downgrade (server or MITM forces plain) → client enforces S256 and refuses plain.
• Open redirect / redirect_uri manipulation → strict loopback-literal allowlist, no wildcard.
• Token theft at rest → OS keychain custody; never plaintext; never logged.
• Client-secret extraction from the binary → there is none (public client).
• Authorization-response replay → one-time state; single-use code.
• Embedded-webview phishing → system browser only.

5. Proposed deliverables (confirm scope first — see §0 scope questions)

• lib/companion-oauth-pkce.mjs — pure PKCE/redirect/state/token-shape functions; constant-time compares; fail-closed; no I/O. No listener bound, no fetch, no keychain call in Phase 3.
• (optional) lib/companion-token-custody.mjs — pure custody/refresh decisions over an injected keychain adapter interface (no real keychain); covers the JWT, the refresh token, and the Phase 2 per-session loopback token.
• test/companion-oauth-pkce-*.test.mjs (+ custody tests) — 7 tiers; security tier is the centerpiece.
• docs/COMPANION-APP-PHASE-3-OAUTH-PKCE.md — accepted design + module contract + threat→control map
  • RFC citations + the safe-bind checklist Phase 5 must satisfy.

6. Definition of done

• Both scope questions resolved with the owner before any listener/network/keychain code.
• Protocol core enforces: S256-only PKCE, exact loopback redirect validation, constant-time state compare, token-request carries code_verifier + no secret, token-response validated fail-closed, JWT/refresh expiry decision.
• 7-tier suite green; security tier covers every threat in §4.
• No secret (code/verifier/state/JWT/refresh) in any return value, log, or error.
• No new listener bound; no OAuth client/scope change.
• Committed on feat/companion-app via Muse; no docs-only PR to main.
• Plain + technical summary with a recommendation (Rule #7), and a Phase 4-vs-Phase 5 sequencing call.

7. Open questions to settle at session start

1. Pure-then-bind scope: protocol core now, listener/fetch/keychain deferred to Phase 5 (recommended) — or approve real I/O in Phase 3?
2. Client registration: does hub/gateway/mcp-oauth-provider.mjs already support a native/public client + loopback redirect at the web-session scopes, or is that a server-side OAuth change that needs its own gate first? (Phase 3 must not change client registration or scopes.)
3. Redirect literal: 127.0.0.1 (RFC-preferred) vs localhost; how the ephemeral port is chosen and reflected into redirect_uri and validateRedirectUri.
4. State custody: in-process random + constant-time compare (recommended for a native client that holds state between authorize and callback) vs the bridge's signState/verifyState HMAC pattern.
5. Token custody + rotation: keychain layout for JWT + refresh token + the Phase 2 per-session loopback token; refresh strategy consistent with hub/lib/refresh-token-core.mjs; what triggers re-auth vs silent refresh (decideTokenRefresh).
6. ID token / nonce / iss: is an OIDC ID token in play (→ add nonce), and do we adopt RFC 9207 iss for mix-up defense?