teapot-coding-agent 0.37.59 → 0.37.61

package/dist/agent/mcp-oauth-manager.js

@@ -1,44 +1,8 @@
-/**
- * OAuth for MCP servers (#67), on the official client's `OAuthClientProvider`.
- *
- * The hand-written discovery/PKCE/token-exchange layer is GONE. What remains is the part
- * the SDK cannot own: **where the grant is stored**, and **how the operator completes the
- * browser step**. The SDK calls this interface at each stage:
- *
- *   clientMetadata()          → who we are, for dynamic registration
- *   clientInformation()       → the client id/secret obtained earlier, or undefined
- *   saveClientInformation()   → persist what registration returned
- *   tokens()                  → the current grant, or undefined
- *   saveTokens()              → persist a token PAIR
- *   redirectToAuthorization() → the URL to open in a browser
- *   saveCodeVerifier()        → keep the PKCE verifier for the exchange
- *   codeVerifier()            → hand it back afterwards
- *
- * Storage choices, unchanged from the previous implementation because they are the
- * security-relevant part and were already right:
- *   - **access token: memory only.** It is short-lived and bound to a fingerprint of the
- *     client credentials, so a changed client id can never reuse a stale token.
- *   - **refresh token + client info: on disk at 0600**, beside the data dir, never in
- *     `config.json` (which operators copy around).
- *
- * The redirect is a real LOOPBACK listener: this is a local harness with a browser UI, so
- * the tab can close itself. The reference implementations (easywebui, deepseek-pp) run
- * serverless and need a host-provided browser identity instead.
- */
 import { createServer } from "node:http";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-/** how long a started flow waits for the browser */
 export const FLOW_TIMEOUT_MS = 5 * 60_000;
-/**
- * One server's OAuth state.
- *
- * The pieces the SDK needs and the pieces the UI needs live together because they are
- * two views of the same grant: a token saved here is what `status()` reports as
- * authorized.
- */
 export class ServerAuth {
-    /** the URL the browser must be sent to, set by `redirectToAuthorization` */
     authUrl;
     verifier;
     flow = { phase: "idle" };
@@ -47,60 +11,29 @@ export class ServerAuth {
     server;
     redirectUrl;
     persist;
-    // Explicit fields, NOT parameter properties (`constructor(readonly x)`): Node's
-    // type-stripping loader refuses that syntax and `pnpm test` runs the sources directly
-    // (ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX).
     constructor(server, redirectUrl, persist) {
         this.server = server;
         this.redirectUrl = redirectUrl;
         this.persist = persist;
     }
-    /** load persisted state (called once, before the server is connected) */
     async hydrate(data) {
         if (!data)
             return;
         this.store = { ...data };
-        /**
-         * Restore the PKCE verifier alongside the rest.
-         *
-         * `codeVerifier()` reads the in-memory field and throws when it is empty, so a rebuilt instance
-         * would refuse the exchange even though the verifier is on disk. MEASURED cause of Notion's
-         * `invalid_grant`: `saveCodeVerifier` never persisted, and even once it does, nothing read the
-         * value back into the field that the exchange actually uses.
-         */
         if (data.codeVerifier)
             this.verifier = data.codeVerifier;
     }
-    /** the persisted payload, for the store */
     snapshot() {
         return { ...this.store };
     }
-    // ---- OAuthClientProvider ----
     get clientMetadata() {
         return {
             client_name: "teapot",
-            // a local harness is a PUBLIC client: it cannot keep a secret meaningful, and the
-            // SDK sends `token_endpoint_auth_method: none` for exactly this shape
             redirect_uris: [this.redirectUrl],
             grant_types: ["authorization_code", "refresh_token"],
             response_types: ["code"],
         };
     }
-    /**
-     * Does a recorded redirect URI describe THIS loopback listener?
-     *
-     * The callback binds an EPHEMERAL port (`server.listen(0)`), so `redirectUrl` carries a different
-     * port on every attempt while the registration is bound to the one it was created with. Comparing
-     * them literally means "never matches", which re-registers on every flow — and re-registering
-     * issues a NEW client_id, which `saveClientInformation` correctly treats as invalidating the
-     * grant. MEASURED: Canva's store had `clientId`/`clientInformation` and NO `accessToken`/
-     * `refreshToken`, i.e. the authorization kept working and the token was thrown away by this loop.
-     *
-     * A loopback port is an implementation detail of the listener, not an identity of the client: the
-     * authorization server redirects to whatever port the request named, and RFC 8252 §7.3 explicitly
-     * allows a loopback redirect to use any port. So the comparison ignores it, and only the
-     * scheme/host/path have to agree.
-     */
     redirectMatches(recorded) {
         if (recorded === this.redirectUrl)
             return true;
@@ -110,52 +43,24 @@ export class ServerAuth {
             const loopback = (h) => h === "127.0.0.1" || h === "::1" || h === "localhost";
             if (!loopback(a.hostname) || !loopback(b.hostname))
                 return false;
-            // any loopback host is interchangeable with any other, and the port is the listener's
             return a.protocol === b.protocol && a.pathname === b.pathname;
         }
         catch {
-            return false; // unparseable record: cannot claim a match
+            return false;
         }
     }
     clientInformation() {
         if (!this.store.clientId)
             return undefined;
-        /**
-         * A registration made with a DIFFERENT redirect URI cannot be reused.
-         *
-         * The callback listens on an ephemeral port (`server.listen(0)`), so `redirectUrl` carries a
-         * new port on every attempt. A registration is bound to the `redirect_uris` it was created
-         * with, and the authorize request must match — so a stored registration from another port would
-         * have to be re-made.
-         *
-         * MEASURED from this machine's real store: `clientInformation.redirect_uris` was
-         * `["http://127.0.0.1/callback"]` — NO PORT, because it was registered from the placeholder
-         * provider in `authFor()` — while every flow runs on `http://127.0.0.1:<port>/callback`. The
-         * browser completed the authorization, `codeVerifier` was persisted, and no `access_token` was
-         * ever written: the exchange never got past the URI check.
-         *
-         * Returning `undefined` makes the SDK register afresh against the CURRENT redirect URI, which
-         * is the only value that can match. The client id/secret are kept, so anything the server bound
-         * to them survives; only the redirect list is re-established.
-         */
         const stored = this.store.clientInformation;
         if (stored) {
             const uris = Array.isArray(stored.redirect_uris)
                 ? stored.redirect_uris
                 : [];
-            /**
-             * Only a RECORDED mismatch forces a re-registration.
-             *
-             * An empty list means the server never told us which URI it bound — some registration
-             * responses omit `redirect_uris` entirely, and a record written by an older teapot has none.
-             * Treating "unknown" as "wrong" would re-register on every single flow and lose whatever the
-             * server bound to the client id, so absence keeps the registration.
-             */
             if (uris.length === 0)
                 return stored;
             if (uris.some((u) => this.redirectMatches(String(u))))
                 return stored;
-            // a recorded URI that cannot match this run: re-register rather than send one it never saw
             return undefined;
         }
         return {
@@ -163,30 +68,11 @@ export class ServerAuth {
             ...(this.store.clientSecret ? { client_secret: this.store.clientSecret } : {}),
         };
     }
-    /**
-     * Is the STORED registration unusable for this run?
-     *
-     * True when a redirect URI was recorded and it is not the one this flow listens on — the same
-     * condition `clientInformation()` acts on, factored out so `tokens()` cannot disagree with it.
-     */
-    /**
-     * Is the STORED registration unusable for this run?
-     *
-     * The SAME comparison `clientInformation()` uses (`redirectMatches`), factored out so `tokens()`
-     * cannot disagree with it about one record. Everything below used to be re-derived here, and the
-     * two definitions drifted twice — once reporting stale where the other reused, once the reverse.
-     *
-     * - no recorded list  → not stale. "Unknown" is not "wrong": some registration responses omit
-     *   `redirect_uris`, and treating absence as a mismatch re-registers on every flow.
-     * - a loopback record → matches whatever port this run listens on (see `redirectMatches`), which
-     *   is what stops the re-register → new client_id → grant-dropped loop.
-     * - anything else      → stale: a record naming a different host cannot be reused.
-     */
     registrationIsStale() {
         const stored = this.store.clientInformation;
         const uris = Array.isArray(stored?.redirect_uris) ? stored.redirect_uris : [];
         if (uris.length === 0)
-            return false; // unknown is not wrong
+            return false;
         return !uris.some((u) => this.redirectMatches(String(u)));
     }
     async saveClientInformation(info, _ctx) {
@@ -196,55 +82,15 @@ export class ServerAuth {
             this.store.clientId = i.client_id;
         if (typeof i?.client_secret === "string")
             this.store.clientSecret = i.client_secret;
-        /**
-         * A NEW client id INVALIDATES the grant issued to the old one.
-         *
-         * `clientInformation()` returns undefined when the stored registration cannot match this run's
-         * redirect URI, which makes the SDK register afresh. Keeping the old tokens across that is fatal:
-         * the refresh request authenticates as the NEW client while presenting a refresh token the
-         * authorization server bound to the OLD one, and the server answers
-         * `invalid_grant: Client ID mismatch` — MEASURED against both Notion and Canva, where every
-         * reconnect failed for exactly this reason while the store still held a valid-looking token.
-         *
-         * Dropping them turns that into an honest "needs a grant": the panel shows 🔑 authorize, and
-         * completing it issues a token pair for the client that actually exists.
-         */
         if (previous && typeof i?.client_id === "string" && i.client_id !== previous) {
             this.store.accessToken = undefined;
             this.store.refreshToken = undefined;
             this.store.expiresAt = undefined;
         }
-        // keep the whole payload: a future field (a client id issued with metadata) survives
         this.store.clientInformation = info;
         await this.persist(this.server, this.store);
     }
     tokens(_ctx) {
-        /**
-         * A grant whose client can no longer be reused must not be presented.
-         *
-         * `clientInformation()` returns undefined when the stored registration cannot match this run's
-         * redirect URI, which makes the SDK register afresh — but `tokens()` would still hand back the
-         * token pair the OLD client obtained. The refresh then authenticates as the new client while
-         * presenting the old client's refresh token, and the server answers
-         * `invalid_grant: Client ID mismatch` (MEASURED against Notion and Canva: every reconnect failed
-         * this way while the store held a token that looked valid).
-         *
-         * Returning nothing makes the flow an honest "needs a grant" instead: the panel offers 🔑, and
-         * completing it issues a pair for the client that actually exists.
-         */
-        /**
-         * A registration we cannot vouch for means DO NOT PRESENT the grant — never DELETE it.
-         *
-         * This used to clear the stored tokens here, and clearing is not the same as declining: the
-         * store persists on the next write, so an "I cannot verify this" answer from a placeholder
-         * provider ERASED a working grant minutes after it was obtained (MEASURED on this machine:
-         * both Notion's and Canva's `accessToken`/`refreshToken` were gone from mcp-oauth.json while the
-         * authorizations themselves had succeeded).
-         *
-         * Declining is reversible — the next connect that CAN verify the registration reads the tokens
-         * again. Erasing is not: it costs the operator a full re-authorization for a transient
-         * uncertainty.
-         */
         if (this.store.accessToken && this.registrationIsStale())
             return undefined;
         if (!this.store.accessToken)
@@ -259,8 +105,6 @@ export class ServerAuth {
     }
     async saveTokens(tokens, _ctx) {
         this.store.accessToken = tokens.access_token;
-        // PERSIST A ROTATED REFRESH TOKEN IMMEDIATELY: a server that rotates invalidates the
-        // previous one, so keeping the old token breaks the NEXT refresh with invalid_grant.
         if (tokens.refresh_token)
             this.store.refreshToken = tokens.refresh_token;
         if (typeof tokens.expires_in === "number" && tokens.expires_in > 0)
@@ -277,75 +121,17 @@ export class ServerAuth {
     async saveCodeVerifier(verifier) {
         this.verifier = verifier;
         this.store.codeVerifier = verifier;
-        /**
-         * PERSIST it, or the exchange cannot complete after the instance is rebuilt.
-         *
-         * The verifier is the secret half of PKCE: the authorization request carries its SHA-256
-         * challenge and the token request must present the verifier itself. Keeping it only in memory
-         * means any path that constructs a fresh `ServerAuth` — a restart while the browser tab is open,
-         * a reconnect, a second `authFor()` — exchanges with no verifier and the authorization server
-         * answers `invalid_grant`.
-         *
-         * MEASURED against the real store: `clientId`/`clientSecret`/`clientInformation` were written
-         * but `codeVerifier` was ABSENT, because this method was the one mutation that never persisted.
-         * Notion's `/token` returns `invalid_grant` for exactly this shape.
-         */
         await this.persist(this.server, this.store);
     }
     codeVerifier() {
-        /**
-         * Fall back to the STORE, not just the in-memory field.
-         *
-         * The field is populated by `saveCodeVerifier` (same instance) or by `hydrate` (a rebuilt one).
-         * Reading the store as a last resort means an instance that was hydrated before this field was
-         * restored still completes the exchange instead of throwing — the failure mode is a silent
-         * `invalid_grant` from the server, so being generous here costs nothing.
-         */
         const v = this.verifier ?? this.store.codeVerifier;
         if (!v)
             throw new Error("no PKCE verifier — the authorization flow did not start here");
         return v;
     }
-    /**
-     * The SDK's discovery cache — the reason Notion's exchange never completed.
-     *
-     * The OAuth flow is split across TWO transport instances: the one that hits the 401 and
-     * redirects the browser, and the one built after the callback arrives. The SDK's own contract
-     * says this state "MUST persist with the same durability as `codeVerifier` (survives the
-     * redirect round-trip)", because the issuer recorded at redirect time is what the authorization
-     * response's `iss` is validated against (RFC 9207) when the code is redeemed.
-     *
-     * MEASURED on this machine's real store after a BROWSER-COMPLETED Notion authorization:
-     * `codeVerifier` present, `clientInformation.redirect_uris` a real ephemeral port
-     * (`http://127.0.0.1:37209/callback`), and no `accessToken` — the redeeming instance had
-     * re-discovered a different issuer binding, so the exchange never produced tokens. Both earlier
-     * fixes (persist the verifier, re-register on a redirect mismatch) were necessary and neither was
-     * sufficient.
-     */
     discoveryState() {
         return this.store.discoveryState;
     }
-    /**
-     * The issuer this client believes it is talking to, from our OWN discovery record.
-     *
-     * Needed because the SDK treats a missing `iss` on the callback as an ATTACK when the server's
-     * metadata declares `authorization_response_iss_parameter_supported` (RFC 9207), and throws
-     * `IssuerMismatchError` before the code is ever redeemed.
-     *
-     * Notion declares that support and then does not send `iss`. MEASURED against
-     * `mcp.notion.com/.well-known/oauth-authorization-server`:
-     * `authorization_response_iss_parameter_supported: true`, while its real redirect carries only
-     * `code` and `state`. Reproduced directly against the SDK with this machine's stored grant:
-     * `IssuerMismatchError: expected "https://mcp.notion.com", received undefined` — i.e. every
-     * browser-completed authorization was discarded at the last step, which is the "コールバック踏んだ
-     * のに Unauthorized" report.
-     *
-     * Supplying the issuer ourselves is sound here: the code arrived on OUR loopback listener, and
-     * this value comes from the discovery document we fetched before sending the browser out. RFC 9207
-     * exists to stop a MIX-UP attack, and there is no mix-up to detect when the client already knows
-     * which authorization server it directed the user to. The SDK's own check
-     * (`iss !== expectedIssuer`) still runs, so a genuinely wrong issuer is still rejected.
-     */
     expectedIssuer() {
         const meta = this.store.discoveryState?.authorizationServerMetadata;
         if (typeof meta?.issuer === "string" && meta.issuer)
@@ -357,11 +143,8 @@ export class ServerAuth {
         if (!state || typeof state !== "object")
             return;
         this.store.discoveryState = state;
-        // same durability as the verifier: the instance that redeems the code is not this one
         await this.persist(this.server, this.store);
     }
-    // ---- teapot-facing ----
-    /** the url the browser must open, once `redirectToAuthorization` has been called */
     pendingUrl() {
         return this.flow.phase === "authorizing" ? this.flow.url : undefined;
     }
@@ -369,7 +152,6 @@ export class ServerAuth {
         this.lastError = message;
         this.flow = { phase: "error", message };
     }
-    /** drop the grant (disconnect) */
     async clear() {
         this.store = {};
         this.verifier = undefined;
@@ -380,7 +162,6 @@ export class ServerAuth {
     }
     status() {
         const expiresAt = this.store.expiresAt ?? null;
-        // a token with no advertised expiry counts as usable; the SDK refreshes on 401 anyway
         const fresh = Boolean(this.store.accessToken) && (expiresAt === null || Date.now() < expiresAt - 60_000);
         return {
             pending: this.flow.phase === "authorizing",
@@ -393,13 +174,6 @@ export class ServerAuth {
         };
     }
 }
-/**
- * The loopback listener an OAuth flow needs.
- *
- * Bound to 127.0.0.1, never 0.0.0.0: this endpoint accepts an authorization code and must
- * not be reachable from the network. The `state` check lives in the caller (the SDK
- * generates and verifies it), so this only has to deliver `code` and `iss`.
- */
 export async function listenForCallback() {
     return await new Promise((resolve, reject) => {
         const server = createServer();
@@ -421,7 +195,6 @@ export async function listenForCallback() {
                 return;
             }
             if (!code) {
-                // a favicon or a stray probe: keep listening rather than failing the flow
                 res.writeHead(404, { "content-type": "text/plain" }).end("not the oauth callback");
                 return;
             }
@@ -458,24 +231,6 @@ export async function listenForCallback() {
         });
     });
 }
-/** the page the operator sees in the callback tab */
-/**
- * The page the browser lands on after authorizing.
- *
- * ## Why it does not close itself any more
- *
- * It used to end with `setTimeout(() => window.close(), 1200)`. Reported as "Notionから認証終わって
- * http://127.0.0.1:41621/callback?code=xxx に飛ぶはずなのに、dev toolsを見るとリダイレクトされてる
- * んだけど、ブラウザ画面ではリダイレクトされてない(謎)" — the redirect DOES happen, the page renders,
- * and then it vanishes on its own. Nothing in DevTools distinguishes "loaded and closed itself" from
- * "never navigated", so the symptom reads as a broken callback.
- *
- * It also only works for a tab a script opened: `window.close()` silently fails on a
- * user-navigated tab, so the behaviour differed by browser and by how the flow started.
- *
- * Saying what happened and leaving the tab alone is both honest and unambiguous. The operator
- * closes it when they are done reading.
- */
 function page(title, body) {
     return `<!doctype html><meta charset="utf-8"><title>${title}</title>
 <style>body{font:15px system-ui;margin:12vh auto;max-width:34rem;text-align:center;color:#222}
@@ -483,12 +238,6 @@ h1{font-size:1.1rem}p{color:#555}</style>
 <h1>${title}</h1><p>${body}</p>
 <p>You can close this tab and return to teapot.</p>`;
 }
-/**
- * Grants for every server, persisted together.
- *
- * One file rather than one per server: the set is small, and a single atomic write keeps
- * a rotation from racing a second write.
- */
 export class McpAuthStore {
     file;
     cache = null;
@@ -500,7 +249,6 @@ export class McpAuthStore {
             return this.cache;
         try {
             const raw = JSON.parse(await readFile(this.file, "utf8"));
-            // tolerate hand edits: keep only entries that look like ours
             const out = {};
             for (const [k, v] of Object.entries(raw ?? {}))
                 if (v && typeof v === "object")
@@ -523,7 +271,6 @@ export class McpAuthStore {
             await writeFile(this.file, JSON.stringify(all, null, 2), { mode: 0o600 });
         }
         catch {
-            /* a failed write must not break a live session */
         }
     }
 }