[ethan-huo]

Summary

A server's need for OAuth is now decided by its Authorization Challenge, on any request, not by an @add GET probe. OAuth itself is the official SDK's auth() (@modelcontextprotocol/client 2.4) driven by an mcpx OAuthClientProvider; src/oauth.ts no longer hand-rolls discovery/DCR/PKCE/exchange/refresh.

 runAuthorized(call)
   resolveCredential            # token now flows via transport authProvider.token()
   callTool
-    catch /401|unauthorized/i  → reauth-required (auth "none" never recovers)
+    catch AuthorizationChallenge {status, resource_metadata, scope}
+      authorize(server, challenge)   # joins the shared Authentication Flow (ADR 0004/0008)
+        authorizeOAuth
+          refresh mode:     SDK auth() — never opens the browser
+          interactive mode: loopback callback → SDK auth() → browser → auth(code, iss)
+        grant written through to Credential Store; none → oauth in the same commit
+      retry once

 src/
-├── auth-discovery.ts     # GET probe at @add, frozen as auth kind
 ├── mcp-client.ts         # + challengeAuthProvider, authorizationChallenge()
 ├── oauth.ts              # SDK auth() + McpxOAuthProvider + loopback callback
 ├── runtime-stores.ts     # Credential Store v3: oauth[server] = {client, tokens}; journaled v2→v3 migration
 └── runtime-authentication.ts

• Manual clients (servers without DCR) still prompt via Caller Input and use http://127.0.0.1:65245/callback. Slack-specific authed_user handling is removed (Slack is used through its own CLI).
• Invalidation deletes only what the server refused (another flow's rotation survives); a failed sign-in never replaces a working grant.
• @add reports auth-required when the tool listing is challenged; it still never opens a browser.
• ADR 0009 added; README, GLOSSARY (Authorization Challenge, Credential Identity), ADR 0008 updated. Bump to 0.14.0.

Evidence

• Before: mcpx wb.status (whiteboardanimation.ai, registered as auth: none because GET /mcp → 405) → Credentials for wb must be refreshed.
  After (local build, isolated MCPX_HOME copy of real state):

  mcpx wb.status
    mcpx: wb: authorize in your browser (waiting up to 5 minutes): https://whiteboardanimation.ai/oauth/authorize?…scope=mcp:tools+offline_access…
    [approved in Aside]
    workspace: org:… plan: pro credits: 589 …           # registry: wb → { kind: oauth }
  mcpx wb.status                                        # no prompt
  [expiresAt forced to 2000-01-01] mcpx wb.status
    mcpx: wb: refreshing OAuth token                    # token rotated, no browser
  mcpx sentry.find_organizations                        # migrated v2 grant works
  

• bun run check: 127 pass. New tests/oauth-challenge.test.ts runs the real SDK transport against a mixed-auth fixture: anonymous quote ok → status 401 → browser → retry ok → next call reuses grant. tests/oauth.test.ts covers DCR, refresh, revoked-refresh fallback, compare-and-delete invalidation, manual client, iss mismatch.
• Live acceptance found a real bug the old fixtures missed (Bun reports port 0 after stop(), so the code exchange sent a different redirect_uri); fixed, and the fixture now enforces redirect_uri equality.
• prototype:cancellation:evidence re-run on v2: same verdicts; only the error type changed (SdkError REQUEST_TIMEOUT) and v2 no longer sends a stray cancel after completion.

Merge Danger

Door: one-way

The first 0.14.0 Runtime start migrates state-v2/credentials.json to version 3 (journaled). A 0.13.x binary cannot read v3 credentials, so downgrading after running 0.14.0 means re-authenticating OAuth servers.

Blast Radius: authentication

Every OAuth server and every HTTP call path (token now via transport authProvider). Bearer servers use the same path (round-robin unchanged). Servers previously recorded unknown become none and are re-decided by their next challenge. SDK v2 also touches stdio/notifications (covered by existing dogfood tests).

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}