Companion App — Server-Side OAuth Gate (client registration + scopes)

Status: ✅ RATIFIED 2026-06-06 + IMPLEMENTED 2026-06-06. All four decisions (D-SS.1–D-SS.4) accepted. All six changes (C1–C6) implemented and tested (86/86 tests green across 7 tiers). Branch: feat/companion-app (Muse-canonical; paired with the Phase 3/4 code already on this branch — not a docs-only PR to main). Resolves: COMPANION-APP-PHASE-3-OAUTH-PKCE.md §7 (the four server-side items Phase 3 explicitly deferred) and §1 D-P3.2. Unblocks: Phase 5 (companion shell) — it cannot obtain a web-session-equivalent identity until this gate is accepted. Touches the protected list: this gate decides OAuth client registration and scopes — the exact items COMPANION-APP-DESIGN-AND-AUTHORIZATION-GATE.md §"DOES NOT approve" guards. A wrong default here is an over-privilege or account-compromise path, so every decision below is argued against an attacker and defaults fail-closed.

Simple summary

The companion app (a helper that runs AI on your own computer) needs to sign in the same way the website does, and end up with the same kind of pass the website gives you — no weaker, no stronger. Phase 3 already built the safe sign-in handshake as pure math (PKCE), but it left four questions about the server side unanswered, because answering them changes who gets what permissions — and getting that wrong could over-grant access or open an account-takeover path. This document answers those four questions, argues each one against an attacker, and lists exactly what the server team must build and test next. It writes no server code.

The four questions: (1) what permissions should the companion's pass carry, and how is it issued? (2) the sign-in server is currently turned off on our hosted (Netlify) deployment — where does it run instead? (3) should the sign-in reply include a tamper-proof "who sent this" stamp (RFC 9207)? (4) does the server correctly accept a desktop app's "reply to me on my own computer" address even though its exact door number changes every time?

Technical summary

Phase 3 shipped a provider-agnostic, pure PKCE client core (lib/companion-oauth-pkce.mjs) plus pure custody (lib/companion-token-custody.mjs) and deferred all server-side OAuth to this gate (Phase 3 §1 D-P3.2, §7). Verified against source, the existing hosted OAuth surface does not yet deliver the gate's "same JWT / same scopes as the web session" promise (design gate §3):

The decisions below resolve the four §7 items on top of these facts. The headline finding that reframes Decision 1: the JWT scopes claim is not the gateway's enforcement point today — data authority is governed by the signature + sub + server-side role resolution — so the meaningful parity question is the token shape and refresh lifecycle, not the scope string.

1. Decision D-SS.1 — Scope / identity parity for the native client

Phase 3 §7(1): either (a) the MCP provider issues role-derived web scopes instead of the read-only mcp_access default, or (b) a dedicated native-client path issues the web-session JWT.

Verified state

The companion must write ai_summary enrichment back to the partition it can already read (design gate §6, D3; Phase 0 D1.3). That requires vault:write, which is exactly what a web member already holds (scopesForRole, server.mjs:225). So web-session-equivalent IS least-privilege for this client — read-only (mcp_access default) breaks the function; anything above [vault:read, vault:write] (e.g. admin) over-grants.

Critically, on the REST data plane authority is not read from the JWT scopes claim (verifyToken ignores it, server.mjs:194); it is re-derived from the bridge hosted-context (getHostedAccessContext, server.mjs:1178) keyed on sub. Therefore the choice between (a) and (b) is decided by token shape, identity fidelity, and refresh lifecycle, not by the scope string.

Adversarial argument

Recommendation — Option (b) (product + eng call → owner ratification requested, §9)

Issue the web-session JWT (issueToken shape) to the native/loopback client through a dedicated native-client authorization path, with the issued scope bound to scopesForRole(role) — never a superset, never admin unless the user is already admin (identical to the web ceiling). Drive its refresh through refresh-token-core (rotation + reuse-detection family-revoke), delivered in the token-response body (the companion is not a browser — no HttpOnly cookie), stored by Phase 5 in the OS keychain per Phase 3 custody.

Implementation note (allowed, not required): the path MAY reuse the MCP SDK auth-router's PKCE / dynamic-registration / authorization / token protocol plumbing as machinery, but the token it mints must be the web-session JWT (via the shared issueToken) and its refresh must be backed by refresh-token-core — i.e. option (b)'s semantics, regardless of which plumbing is reused. The companion is not an MCP-tool client; it is a native app acting as the user against the REST data plane, so it does not need the type:'mcp_access' token and the existing mcp_access path must remain unchanged for actual MCP clients.

Fail-closed defaults: missing/unknown role → treat as member ceiling ([vault:read, vault:write]), never elevate; never issue a non-rotating or long-lived token.

2. Decision D-SS.2 — Hosted availability of the authorization/token endpoints

Phase 3 §7(2): the PKCE provider is skipped on Netlify (SESSION_SECRET && !NETLIFY, server.mjs:540). The companion targets the hosted gateway — where are the endpoints served?

Verified state

The OAuth router is gated off on Netlify because the SDK MCP session transport needs stateful SSE + shared memory incompatible with serverless (server.mjs:534-539), and the provider keeps _pendingCodes + _refreshTokens in in-memory Maps (mcp-oauth-provider.mjs:80-83). The web refresh path, by contrast, already runs on Netlify against a durable blob store through refresh-token-core + auth-session.mjs — so durable AS state on serverless is not without precedent.

Verified live server inventory (owner-confirmed 2026-06-06)

The former AWS paperclip-prod (t3.xlarge) has been decommissioned; Paperclip migrated to the iMac. Two servers remain in AWS us-east-2:

The hosted REST API runs on Netlify (serverless); the OAuth/MCP router is skipped there (server.mjs:540,568). hub/gateway/README.md:62 documents the intended split — API on Netlify, persistent MCP on a separate host — and knowtation-mcp-gateway is that host.

Adversarial argument

• Discord Bot (t3.micro) — REJECTED. Automation/bot workload; same privilege-separation failure as the old Paperclip box. A compromise yields the ability to mint identity for every Knowtation user if the gateway's SESSION_SECRET is co-located there.
• knowtation-mcp-gateway (t3.small) — ACCEPTED for reuse. Purpose-built for this exact role (the name and dedicated knowtation-mcp-sg security group confirm it), has a public IP, is already the intended co-location for /mcp and the OAuth AS per hub/gateway/README.md. It runs no automation/bot workloads — it is the gateway itself. The privilege-separation requirement is satisfied: identity is isolated on a host whose only job is serving the Knowtation persistent gateway. A t3.small (2 vCPU, 2 GB) is correctly sized — the gateway is I/O-bound, runs no inference, no Postgres, no agent subprocesses.
• New host — not needed. knowtation-mcp-gateway already exists, is already dedicated, and already has the right posture. Provisioning a third server would duplicate it for no security gain.
• (ii) Durable-state-on-Netlify — viable fallback, not needed. Acceptable if the owner ever wants to decommission the persistent host, but adds bespoke AS-state porting work (expired/replayed codes must be atomic across isolated invocations) and this host already exists.

Recommendation — DECIDED: reuse knowtation-mcp-gateway (no new server)

The companion's OAuth authorization/token/registration endpoints co-locate on knowtation-mcp-gateway (i-025679d93cf47aeab, t3.small, 18.221.120.124), alongside the existing /mcp endpoint, exactly as hub/gateway/README.md planned. No third server is needed.

Implementation obligations for the follow-up phase:

• TLS must terminate on the host (Caddy/Let's Encrypt or an ACM-backed ALB) — the OAuth endpoints MUST be HTTPS-only; the companion's buildAuthorizationUrl enforces HTTPS on the AS endpoint.
• SESSION_SECRET stored in AWS SSM Parameter Store / Secrets Manager under a least-privilege IAM role scoped to this instance only — never in the process environment of the Discord bot or any other host.
• The knowtation-mcp-sg security group must allow inbound 443 (HTTPS) from 0.0.0.0/0 for OAuth redirects (the companion's system browser hits the authorization endpoint) and inbound from the Netlify gateway IP range for the MCP proxy path. No other ports.
• Durable AS state (pending codes + native refresh records) must survive process restart — use the same blob/file store the web refresh path uses, or a small SQLite/Redis local to the host. No in-memory Maps for production AS state.

Either way: the endpoints must serve over HTTPS, advertise discovery metadata whose issuer exactly matches the emitted iss (D-SS.3), and never rely on in-memory Maps for code/refresh state (that would silently drop valid sessions and break reuse detection).

3. Decision D-SS.3 — RFC 9207 iss emission on the redirect

Phase 3 §7(3) and D-P3.3: emit iss so clients passing expectedIssuer get full mix-up defense.

Verified state

completeMcpAuthorization (mcp-oauth-provider.mjs:146-149) builds the loopback redirect with code and state only — no iss. Phase 3's client validates iss constant-time when present and tolerates absence for back-compat (D-P3.3). So today, even a client that passes expectedIssuer gets no mix-up protection (threat c), because absent-iss is tolerated.

Recommendation — CONFIRM (emit iss)

Add iss to the authorization-response redirect (the loopback redirect built in completeMcpAuthorization), set to the issuer identifier string — identical to the issuerUrl the SDK auth-router advertises in discovery metadata (server.mjs:557, new URL(BASE_URL)), with no trailing-slash drift. Specification:

• Value = the AS issuer identifier, URL-encoded, exactly equal to the issuer in the authorization-server metadata (RFC 9207 §2 / RFC 8414).
• Emitted on the authorization response (the redirect), not the token response.
• Purely additive: a Phase 3 client passing expectedIssuer now gets constant-time mix-up defense with zero client change (Phase 3 threat c, ISSUER_MISMATCH); a client that does not pass expectedIssuer is unaffected.
• Carries no secret. Absent-iss remains tolerated only for any pre-existing client; new native clients SHOULD pass expectedIssuer and SHOULD treat a mismatch as fatal.

4. Decision D-SS.4 — Loopback redirect registration with a variable ephemeral port

Phase 3 §7(4): confirm the provider/SDK auth-router accepts a native client registering a loopback redirect_uri with a variable ephemeral port (RFC 8252 §7.3), and that redirect_uri is validated against the registration at the token exchange.

Verified state

• The provider stores params.redirectUri at authorize and redirects to it at completeMcpAuthorization (mcp-oauth-provider.mjs:97-118,146-149), but does not re-validate it at the token exchange — exchangeAuthorizationCode's _redirectUri argument is ignored (:158).
• Whether a loopback redirect_uri with a variable port is accepted at registration and authorization is governed by the @modelcontextprotocol/sdk auth-router (mcpAuthRouter, mounted server.mjs:555), whose source/version this gate has not inspected. This is therefore a CONFIRM-WITH-VERIFICATION, not an assertion.

Adversarial argument

If neither the SDK nor the provider validates redirect_uri at token exchange, a code intercepted on the loopback could in principle be exchanged from a different redirect. PKCE still blocks the exchange (the attacker lacks the code_verifier, Phase 3 threat a), so this is not a stand-alone compromise — but redirect_uri validation is defense-in-depth required by RFC 6749 §4.1.3 and must not be skipped.

RFC 8252 §7.3 nuance the implementation must respect: the AS MUST allow variable ports for loopback redirects, i.e. registration/authorization matching must be port-agnostic on the loopback literal. But within a single attempt the companion binds one ephemeral port, derives the redirect_uri from it, and uses that same value for both authorization and token exchange — so the §4.1.3 equality check (same redirect_uri for a given code) holds per attempt. "Variable port" is a property across attempts/registration, not within one exchange. Both are satisfiable simultaneously.

Recommendation — CONFIRM, with a hard implementation obligation

1. Verify against the pinned @modelcontextprotocol/sdk version that (a) a native client can dynamically register a loopback redirect_uri, and (b) the authorization request's loopback redirect_uri is accepted with a variable/ephemeral port (port-agnostic loopback match, RFC 8252 §7.3) — 127.0.0.1/[::1] literals only, never localhost-wildcard, never a non-loopback host.
2. Enforce redirect_uri validation at the token exchange: the redirect_uri presented with a code MUST equal the one bound to that code at authorize (RFC 6749 §4.1.3). If the SDK does not already enforce this upstream, change the provider to compare against pending.redirectUri (replacing the ignored _redirectUri). The comparison is per-code equality (the same attempt's value), not a port-agnostic match — port-agnosticism applies only to registration/authorization acceptance.
3. Reject any registered/presented redirect that is not an RFC 8252 loopback literal (mirrors the client-side validateRedirectUri, Phase 3 threat e), fail-closed.

5. Threat model → control (server side)

Extends Phase 3 §2 (client side) to the server changes this gate authorizes.

6. Precise server-side change list (for the FOLLOW-UP implementation phase)

✅ Implementation complete 2026-06-06. 86/86 tests green across all 7 tiers.

New files: hub/gateway/native-as-store.mjs, hub/gateway/native-oauth-provider.mjs, test/native-oauth-c1-c6-{unit,integration,e2e,stress,data-integrity,performance,security}.test.mjs

Modified files: hub/gateway/mcp-oauth-provider.mjs (C3, C5), hub/gateway/server.mjs (native router mount at /api/v1/auth/native, IDP callback native: state prefix)

Explicitly out of scope (unchanged): the existing verifyToken behavior of not enforcing the JWT scopes claim (server.mjs:194) is a separately tracked concern. Authority is re-derived server-side by role. Changing data-plane scope enforcement requires its own gate.

7. 7-tier test obligations (per change C1–C6)

Aaron's Rule #0. Each change above ships all seven tiers before merge to main.

8. Constraints honored

• Decisions only — no server code. This document changes no hub/ runtime; it records what a follow-up phase must build and test.
• Muse-canonical, on feat/companion-app, paired with the Phase 3/4 code already there — not a docs-only PR to main (per the owner's no-docs-only-PR-to-main policy).
• Security first; fail-closed defaults. Every default above denies/least-privileges on ambiguity.
• No assumptions stated as fact. Every claim is anchored to a verified file:line; the one item this gate could not verify (SDK loopback variable-port behavior) is marked CONFIRM-WITH-VERIFICATION (D-SS.4), not asserted.

9. Approval table

D-SS.1–D-SS.4 are ratified. The four Phase 3 §7 items are resolved. The server-side implementation phase (changes C1–C6, §6) is unblocked — itself gated on the §7 7-tier test obligation before any merge to main. That phase in turn unblocks Phase 5 (companion shell).