comisai 1.0.41 → 1.0.44

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/oauth/browser-callback.js

@@ -0,0 +1,316 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Loopback OAuth browser-callback server (guarded by the no-module-globals AST gate).
+ *
+ * One ephemeral `node:http` server per interactive login. It binds
+ * `listen(0, "127.0.0.1")` (kernel-assigned port, loopback IP only), serves a
+ * SINGLE `GET /callback?code=&state=`, validates the CSRF `state` in constant
+ * time, captures the authorization code, replies with a "close this tab" page,
+ * and resolves. Then it closes — on success, on a 300s timeout, and on
+ * rejection — so no port or file descriptor lingers.
+ *
+ * ── ZERO module-scope mutables ──────────────────────────────────────────────
+ * Hermes kept the callback port in a MODULE-GLOBAL (`_oauth_port`); two
+ * concurrent logins then clobbered each other's port (a TOCTOU that could
+ * mis-route an authorization code). THIS file therefore has NO module-scope
+ * `let`/`var`. Every piece of mutable state — the server handle, the port, the
+ * `state`, the `code_verifier`, the resolve/reject, the timeout timer, the
+ * "already settled" guard — lives inside the closure of a single
+ * {@link runBrowserCallback} call. The only module-level bindings are `const`
+ * (the timeout default, the close-tab HTML, and the const-bound helper arrows),
+ * which are immutable and pose no TOCTOU risk. `test/architecture/
+ * mcp-no-module-globals.test.ts` AST-asserts this on exactly this file.
+ *
+ * ── CSRF state ───────────────────────────────────────────────────────────────
+ * The caller generates `state = randomBytes(32).toString("hex")` (upstream, in
+ * the adapter's `state()`); it is passed in, held in the closure, NEVER written
+ * to disk. The callback compares the returned `state` against it via
+ * `crypto.timingSafeEqual`. `timingSafeEqual` THROWS on a length mismatch, so a
+ * length-guard runs first and treats any length difference as a (non-throwing)
+ * mismatch. A mismatch → HTTP 400 + an `errorKind:"auth"` WARN (CSRF is an
+ * code is NOT resolved (the attacker's code is dropped; the server stays up for
+ * the legitimate redirect or the timeout).
+ *
+ * ── Redirect-URI allowlist ───────────────────────────────────────────────────
+ * The redirect URI is `http://127.0.0.1:<port>/callback` — the IP literal, NOT
+ * `localhost` (DNS-rebindable per RFC 8252). {@link validateRedirectHost}
+ * rejects `localhost` and `[::1]`/`::1` (the latter unless an explicit opt-in)
+ * BEFORE any browser launch.
+ *
+ * ── Headless detection ───────────────────────────────────────────────────────
+ * The shared `isRemoteEnvironment` helper checks only `SSH_CLIENT`/`SSH_TTY`/
+ * `!DISPLAY` — too narrow for this flow. {@link isHeadless} DELEGATES to it and
+ * ORs the four missing signals (`SSH_CONNECTION || !isTTY || CONTAINER ||
+ * existsSync('/proc/sys/fs/binfmt_misc/WSLInterop')`). On headless, the server
+ * does NOT call `openUrl` — it surfaces a `ssh -L <port>:localhost:<port>`
+ * port-forward hint for the RPC layer (the operator forwards the port and opens
+ * the URL themselves). The shared helper is intentionally NOT widened
+ * (rule-of-three: one consumer).
+ *
+ * ── `open` dependency ────────────────────────────────────────────────────────
+ * `open` is NOT a skills dependency. The browser launch is an INJECTED
+ * `openUrl: (url) => void` (a no-op spy in tests; the real `open` is wired
+ * CLI-side). This module only hosts the callback server + headless decision;
+ * it never imports `open`.
+ *
+ * ── code_verifier ────────────────────────────────────────────────────────────
+ * The PKCE `code_verifier` is held in memory only — never written to any file,
+ * never logged. After the caller exchanges the code, it zeroes the verifier
+ * buffer via {@link zeroVerifier} (`Buffer.fill(0)`). An architecture-grep
+ * (in the sibling test) asserts `code_verifier` never reaches a write call site.
+ *
+ * SECURITY: the `state`, the `code_verifier`, and the authorization `code` are
+ * NEVER logged at any level — only the server name, the port, and the headless
+ * decision. Pino redaction is a safety net, not a license.
+ *
+ * @module
+ */
+import { createServer } from "node:http";
+import { existsSync as nodeExistsSync } from "node:fs";
+import { timingSafeEqual } from "node:crypto";
+import { isRemoteEnvironment, systemSetTimeout, systemClearTimeout, systemEnvSnapshot, } from "@comis/core";
+/**
+ * Default callback timeout (RFC-style native-app loopback flow). After this an
+ * abandoned login rejects and the server closes (no lingering port/fd).
+ * Module-level `const` is permitted by the no-module-globals gate (it forbids
+ * only `let`/`var`).
+ */
+const CALLBACK_TIMEOUT_MS = 300_000;
+/** Loopback IP literal — the ONLY accepted redirect host (RFC 8252). */
+const LOOPBACK_IPV4 = "127.0.0.1";
+/** Path to the WSL interop marker — its presence means "no local browser". */
+const WSL_INTEROP_MARKER = "/proc/sys/fs/binfmt_misc/WSLInterop";
+/** The single-use "you may close this tab" page returned on a successful callback. */
+const CLOSE_TAB_HTML = "<!doctype html><html><head><meta charset=utf-8>" +
+    "<title>Authorized</title></head><body>" +
+    "<p>Authorized. You may close this tab and return to your terminal.</p>" +
+    "</body></html>";
+/**
+ * Reject `localhost` and (by default) the IPv6 loopback; accept only the IPv4
+ * loopback literal `127.0.0.1`. `localhost` is DNS-rebindable (RFC 8252) and is
+ * NEVER accepted, even with {@link ValidateRedirectHostOptions.allowIpv6Loopback}.
+ *
+ * Const-bound arrow → an immutable module binding (only `let`/`var` are prohibited).
+ */
+export const validateRedirectHost = (host, options = {}) => {
+    if (host === LOOPBACK_IPV4)
+        return true;
+    if (options.allowIpv6Loopback === true && (host === "::1" || host === "[::1]")) {
+        return true;
+    }
+    return false;
+};
+/**
+ * True when the current host has no usable local browser. DELEGATES to the
+ * shared `isRemoteEnvironment` (SSH_CLIENT/SSH_TTY/!DISPLAY) then ORs the four
+ * signals that helper misses: an SSH_CONNECTION env var, a non-TTY
+ * stdout, a CONTAINER marker, or the WSL interop marker on disk.
+ *
+ * The shared helper is delegated-to, not widened (rule-of-three).
+ */
+export const isHeadless = (input) => {
+    if (isRemoteEnvironment({ env: input.env }))
+        return true;
+    if (input.env.SSH_CONNECTION)
+        return true;
+    if (!input.isTTY)
+        return true;
+    if (input.env.CONTAINER)
+        return true;
+    if (input.existsSync(WSL_INTEROP_MARKER))
+        return true;
+    return false;
+};
+/**
+ * Zero a PKCE `code_verifier` buffer in place after the code exchange.
+ * `Buffer.fill(0)` overwrites the secret so a later heap inspection cannot
+ * recover it. Idempotent and safe on an already-zeroed or empty buffer.
+ */
+export const zeroVerifier = (verifier) => {
+    verifier.fill(0);
+};
+/**
+ * Build the `ssh -L <port>:localhost:<port> <vps>` port-forward hint. The host
+ * placeholder is `<vps>` (the operator substitutes their host) since this
+ * module does not know the daemon's external address. Const-bound arrow.
+ */
+const buildPortForwardHint = (port) => `ssh -L ${port}:localhost:${port} <vps>`;
+/**
+ * Start an ephemeral loopback callback server for ONE interactive OAuth login.
+ *
+ * Resolves once the server is listening, with a {@link BrowserCallbackHandle}
+ * exposing the redirect URI, the headless decision, and `waitForCode()`. On a
+ * non-headless host it has already called `openUrl(authorizationUrl)`; on a
+ * headless host it left `openUrl` untouched and populated `portForwardHint`.
+ *
+ * ALL mutable state below is closure-local — there is no module-scope `let`/
+ * `var` anywhere in this file (no module-scope mutables). The `code_verifier` is referenced only
+ * to document memory-only ownership; it is never written or logged.
+ */
+export function runBrowserCallback(options) {
+    const { serverName, authorizationUrl, state, openUrl, logger, timeoutMs = CALLBACK_TIMEOUT_MS, } = options;
+    // Reference codeVerifier so the memory-only contract is explicit at the call
+    // boundary without ever writing or logging it.
+    void options.codeVerifier;
+    // Pattern B: env via the sanctioned `systemEnvSnapshot()` from
+    // @comis/core/runtime instead of a direct `process.env` global, satisfying
+    // the architecture globals gate (no new direct-global call sites outside
+    // BOOTSTRAP_PATH_PATTERNS). Tests inject `options.env`; production reads
+    // the snapshot once per invocation, which is the right semantic anyway —
+    // the headless decision is per-login and should not observe later env
+    // mutations within the same process lifetime.
+    const env = options.env ?? systemEnvSnapshot();
+    // Defensive `process.stdout?.isTTY` access. Some platforms (worker
+    // threads, stubbed-process shims, certain test environments) expose
+    // `process` without a `stdout` property; a non-optional read would throw a
+    // TypeError before the headless decision could even reach the four extended
+    // signals. With optional chaining a missing `process.stdout` falls back to
+    // `undefined` → coerced to `false` → "no TTY" → `isHeadless` returns true,
+    // which is the safe default (suppresses the browser open, surfaces the
+    // port-forward hint). Tests still inject `options.isTTY` for determinism.
+    const isTTY = options.isTTY ?? Boolean(process.stdout?.isTTY);
+    const existsSync = options.existsSync ?? nodeExistsSync;
+    return new Promise((resolveHandle, rejectHandle) => {
+        // ── Closure-local mutable state (the ENTIRE reason for no module-scope mutables). ─
+        // `let`/`const` HERE is fine — these bindings live in the Promise executor
+        // scope, not module scope. The no-module-globals walker only inspects top-level
+        // statements, so these are intentionally invisible to it.
+        let settled = false;
+        let codeResolve;
+        let codeReject;
+        // The code promise is created eagerly so a synchronous callback (tests fire
+        // the GET immediately) cannot race a not-yet-assigned resolver.
+        const codePromise = new Promise((res, rej) => {
+            codeResolve = res;
+            codeReject = rej;
+        });
+        const server = createServer((req, res) => {
+            // Parse against the loopback origin; only the path + query matter.
+            const url = new URL(req.url ?? "/", `http://${LOOPBACK_IPV4}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("not found");
+                return;
+            }
+            const gotState = url.searchParams.get("state") ?? "";
+            const code = url.searchParams.get("code") ?? "";
+            if (!timingSafeStateEqual(gotState, state)) {
+                // CSRF mismatch: 400 + security WARN, do NOT resolve. The
+                // attacker's code is dropped; the server stays up for the legitimate
+                // redirect or the timeout. NEVER log the state values themselves.
+                res.writeHead(400, { "content-type": "text/plain" });
+                res.end("state mismatch");
+                logger.warn(
+                // CSRF state mismatch is an authentication-domain violation (the
+                // attacker's redirect is the OAuth handshake failing the integrity
+                // check). Maps to the closed errorKind union's "auth" member; the
+                // "security" semantic is preserved in the log message ("possible
+                // CSRF") + the submodule ("oauth-browser-callback").
+                //
+                // The canonical `submodule` field is required so structured-log
+                // dashboards can filter this high-priority security event by
+                // subsystem.
+                {
+                    submodule: "oauth-browser-callback",
+                    errorKind: "auth",
+                    serverName,
+                }, "OAuth callback state mismatch — rejected (possible CSRF)");
+                return;
+            }
+            // Valid callback → reply, THEN close + resolve (single-use). The close
+            // is deferred to the `res.end` flush callback so `closeAllConnections()`
+            // cannot destroy the socket before the "close this tab" body reaches the
+            // browser; the timeout/reject paths (no in-flight response) close at once.
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(CLOSE_TAB_HTML, () => {
+                finish(() => codeResolve?.(code));
+            });
+        });
+        // ── Cleanup: idempotent close + timer cancel (success/timeout/reject). ──
+        // `closeAllConnections()` (Node 18.2+) forcibly destroys keep-alive sockets
+        // so the loopback port is RELEASED promptly — `server.close()` alone only
+        // stops accepting NEW connections and waits for existing ones to drain,
+        // which would leave the port held (no lingering port/fd).
+        const cleanup = () => {
+            systemClearTimeout(timer);
+            server.closeAllConnections?.();
+            server.close();
+        };
+        // Settle exactly once: cancel the timer, close the server, run the action.
+        function finish(action) {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            action();
+        }
+        const timer = systemSetTimeout(() => {
+            finish(() => codeReject?.(new Error(`OAuth browser callback timeout after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        // Do not keep the event loop alive solely for the callback timer.
+        timer.unref?.();
+        server.on("error", (err) => {
+            finish(() => {
+                rejectHandle(err);
+                codeReject?.(err);
+            });
+        });
+        server.listen(0, LOOPBACK_IPV4, () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                finish(() => {
+                    const err = new Error("callback server failed to bind a loopback port");
+                    rejectHandle(err);
+                    codeReject?.(err);
+                });
+                return;
+            }
+            const port = addr.port;
+            const redirectUri = `http://${LOOPBACK_IPV4}:${port}/callback`;
+            const headless = isHeadless({ env, isTTY, existsSync });
+            if (headless) {
+                const portForwardHint = buildPortForwardHint(port);
+                // Surface the hint via the handle; do NOT open a browser that isn't
+                // there. NEVER log the auth URL (it carries the state param).
+                logger.info({ serverName, port, headless: true }, "headless host — suppressing browser open; port-forward hint surfaced");
+                resolveHandle({
+                    port,
+                    redirectUri,
+                    headless: true,
+                    portForwardHint,
+                    waitForCode: () => codePromise,
+                    close: () => finish(() => undefined),
+                });
+                return;
+            }
+            logger.info({ serverName, port, headless: false }, "opening browser for OAuth authorization");
+            openUrl(authorizationUrl);
+            resolveHandle({
+                port,
+                redirectUri,
+                headless: false,
+                waitForCode: () => codePromise,
+                close: () => finish(() => undefined),
+            });
+        });
+    });
+}
+/**
+ * Constant-time `state` comparison. `crypto.timingSafeEqual` THROWS
+ * when the two buffers differ in length, which would (a) leak length via the
+ * exception path and (b) turn a forged callback into an HTTP 500. So we
+ * length-guard first and treat any length difference as a non-throwing
+ * mismatch. Equal-length inputs go through `timingSafeEqual` so a same-length
+ * forgery cannot be distinguished by timing.
+ *
+ * Const-bound function declaration is a `const`-equivalent immutable binding;
+ * declared as a `function` here only for hoisting clarity within the module
+ * (still not a `let`/`var`, so the no-module-globals invariant is satisfied).
+ */
+function timingSafeStateEqual(a, b) {
+    const bufA = Buffer.from(a, "utf8");
+    const bufB = Buffer.from(b, "utf8");
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/oauth/deduped-fetch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Deduped-refresh fetch wrapper — the production 401 path for an
+ * `auth:"oauth"` MCP server. Deduplicates concurrent refresh requests and
+ * persists rotated tokens. Composes ON TOP of the redirect-policy fetch;
+ * the redirect policy stays unchanged and runs INSIDE this wrapper for the
+ * initial request + the retry, so cross-host header scrub still applies.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ * `createOAuthClientProvider` accepts a `RefreshDeduper` in its deps but never
+ * calls `dedupedRefresh`. The MCP SDK's own `OAuthClientProvider`-aware
+ * transport routes a 401 through its internal `auth()` → `refreshAuthorization`
+ * call, which BYPASSES the deduper. With N concurrent in-flight tool calls
+ * against an expired access token, that is the thundering herd:
+ *   - N concurrent 401s fire N concurrent refresh POSTs.
+ *   - A provider that rotates refresh_token (e.g. Notion) invalidates the
+ *     N-1 losers, collapsing the token chain into a lockout.
+ *   - Even on a non-rotating provider, the token endpoint sees N requests
+ *     where 1 suffices (rate-limit risk).
+ *
+ * This wrapper intercepts the 401 BEFORE the SDK sees it:
+ *   1. Read the bearer from the outgoing request's Authorization header — that
+ *      IS the EXPIRED access token (the deduper's dedup key).
+ *   2. Load the refresh_token + client information + discovery state from the
+ *      token store. If any are missing → return the 401 verbatim (the SDK
+ *      surfaces `needs_oauth_login` via UnauthorizedError; we cannot refresh
+ *      without these inputs).
+ *   3. Call `deduper.dedupedRefresh({...})`. The deduper's critical section is
+ *      `state.callQueues[serverName]` (the same concurrency-1 PQueue that
+ *      serializes tool calls), so N concurrent 401s for the same access token
+ *      coalesce into ONE refresh POST and ALL waiters resolve to the same
+ *      shared future.
+ *   4. The deduper's `doRefresh` persists the rotated tokens via
+ *     `tokenStore.saveTokens` so the next refresh reads the new
+ *      refresh_token off disk and Notion is not locked out.
+ *   5. Re-issue the original request with `Authorization: Bearer <new>` and
+ *      return that response to the SDK.
+ *
+ * ── No retry loop (defense-in-depth) ────────────────────────────────────────
+ * One refresh + one retry. If the retry STILL returns 401, the wrapper
+ * returns it verbatim; the SDK surfaces UnauthorizedError and connectServer
+ * tags `needs_oauth_login`. A persistent 401 after a fresh access token is a
+ * provider-side issue (revoked tokens, scope mismatch) — re-driving the
+ * deduper would just thrash the token endpoint.
+ *
+ * ── Security ────────────────────────────────────────────────────────────────
+ * Tokens and Authorization header values are NEVER logged — only the server
+ * name, the dedup decision, and the resulting status. Header capture for the
+ * retry uses a defensive copy.
+ *
+ * @module
+ */
+import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { RefreshDeduper } from "./refresh-deduper.js";
+import type { TokenStore } from "./token-store.js";
+/** Structural logger — matches the token store / deduper contract. */
+interface DedupedFetchLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+    debug?(obj: Record<string, unknown>, msg: string): void;
+}
+/** Per-server inputs for {@link createDedupedRefreshFetch}. */
+export interface DedupedRefreshFetchDeps {
+    /** Validated server name (token-store key; logged). */
+    readonly serverName: string;
+    /** Disk-backed token store — read refresh_token/client_info/discovery; persist rotated tokens. */
+    readonly tokenStore: TokenStore;
+    /** The 401 refresh-deduper (66c) — the shared-future critical section. */
+    readonly deduper: RefreshDeduper;
+    /** Inner fetch (e.g. {@link createRedirectPolicyFetch}). Required. */
+    readonly innerFetch: FetchLike;
+    /**
+     * Optional `addClientAuthentication` hook (e.g. Stripe-Account header on refresh).
+     * Forwarded to `deduper.dedupedRefresh` verbatim — the deduper threads it
+     * onto the refresh POST so connected-account providers (Stripe) still work
+     * when the rotation happens via the 401 path.
+     */
+    readonly addClientAuthentication?: (headers: Headers, params: URLSearchParams, url: string | URL, metadata?: import("@modelcontextprotocol/sdk/shared/auth.js").AuthorizationServerMetadata) => void | Promise<void>;
+    readonly logger: DedupedFetchLogger;
+}
+/**
+ * Wrap an inner `FetchLike` (typically the redirect-policy fetch) so any 401
+ * response triggers a deduped refresh via {@link RefreshDeduper.dedupedRefresh},
+ * followed by ONE retry with the rotated bearer. Returns the inner fetch's
+ * response verbatim on non-401 status, when no Authorization header is present,
+ * when the token store lacks the inputs to refresh, or when the retry still
+ * returns 401 (which surfaces `needs_oauth_login` upstream).
+ */
+export declare function createDedupedRefreshFetch(deps: DedupedRefreshFetchDeps): FetchLike;
+export {};

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/oauth/deduped-fetch.js

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Deduped-refresh fetch wrapper — the production 401 path for an
+ * `auth:"oauth"` MCP server. Deduplicates concurrent refresh requests and
+ * persists rotated tokens. Composes ON TOP of the redirect-policy fetch;
+ * the redirect policy stays unchanged and runs INSIDE this wrapper for the
+ * initial request + the retry, so cross-host header scrub still applies.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ * `createOAuthClientProvider` accepts a `RefreshDeduper` in its deps but never
+ * calls `dedupedRefresh`. The MCP SDK's own `OAuthClientProvider`-aware
+ * transport routes a 401 through its internal `auth()` → `refreshAuthorization`
+ * call, which BYPASSES the deduper. With N concurrent in-flight tool calls
+ * against an expired access token, that is the thundering herd:
+ *   - N concurrent 401s fire N concurrent refresh POSTs.
+ *   - A provider that rotates refresh_token (e.g. Notion) invalidates the
+ *     N-1 losers, collapsing the token chain into a lockout.
+ *   - Even on a non-rotating provider, the token endpoint sees N requests
+ *     where 1 suffices (rate-limit risk).
+ *
+ * This wrapper intercepts the 401 BEFORE the SDK sees it:
+ *   1. Read the bearer from the outgoing request's Authorization header — that
+ *      IS the EXPIRED access token (the deduper's dedup key).
+ *   2. Load the refresh_token + client information + discovery state from the
+ *      token store. If any are missing → return the 401 verbatim (the SDK
+ *      surfaces `needs_oauth_login` via UnauthorizedError; we cannot refresh
+ *      without these inputs).
+ *   3. Call `deduper.dedupedRefresh({...})`. The deduper's critical section is
+ *      `state.callQueues[serverName]` (the same concurrency-1 PQueue that
+ *      serializes tool calls), so N concurrent 401s for the same access token
+ *      coalesce into ONE refresh POST and ALL waiters resolve to the same
+ *      shared future.
+ *   4. The deduper's `doRefresh` persists the rotated tokens via
+ *     `tokenStore.saveTokens` so the next refresh reads the new
+ *      refresh_token off disk and Notion is not locked out.
+ *   5. Re-issue the original request with `Authorization: Bearer <new>` and
+ *      return that response to the SDK.
+ *
+ * ── No retry loop (defense-in-depth) ────────────────────────────────────────
+ * One refresh + one retry. If the retry STILL returns 401, the wrapper
+ * returns it verbatim; the SDK surfaces UnauthorizedError and connectServer
+ * tags `needs_oauth_login`. A persistent 401 after a fresh access token is a
+ * provider-side issue (revoked tokens, scope mismatch) — re-driving the
+ * deduper would just thrash the token endpoint.
+ *
+ * ── Security ────────────────────────────────────────────────────────────────
+ * Tokens and Authorization header values are NEVER logged — only the server
+ * name, the dedup decision, and the resulting status. Header capture for the
+ * retry uses a defensive copy.
+ *
+ * @module
+ */
+const SUBMODULE = "oauth-deduped-fetch";
+const BEARER_PREFIX = "Bearer ";
+/**
+ * Read the bearer from a `RequestInit.headers` value. Returns the access-token
+ * portion (without the `Bearer ` prefix), or `undefined` if no Authorization
+ * header is present, the scheme is not Bearer, or the value is empty.
+ *
+ * Accepts Headers | Record<string, string> | array-of-tuples. NEVER logs.
+ */
+function extractBearer(headersInit) {
+    if (headersInit === undefined)
+        return undefined;
+    const headers = new Headers(headersInit);
+    const auth = headers.get("authorization") ?? headers.get("Authorization");
+    if (auth === null)
+        return undefined;
+    if (!auth.startsWith(BEARER_PREFIX))
+        return undefined;
+    const token = auth.slice(BEARER_PREFIX.length).trim();
+    return token === "" ? undefined : token;
+}
+/**
+ * Build a fresh `RequestInit` with `Authorization: Bearer <newToken>` replacing
+ * any existing Authorization header. All other headers + the body / method /
+ * signal pass through unchanged. Defensive header copy so the caller's init is
+ * not mutated.
+ */
+function withRefreshedBearer(init, newAccessToken) {
+    const headers = new Headers(init?.headers ?? {});
+    headers.set("Authorization", `${BEARER_PREFIX}${newAccessToken}`);
+    return { ...(init ?? {}), headers };
+}
+/**
+ * Wrap an inner `FetchLike` (typically the redirect-policy fetch) so any 401
+ * response triggers a deduped refresh via {@link RefreshDeduper.dedupedRefresh},
+ * followed by ONE retry with the rotated bearer. Returns the inner fetch's
+ * response verbatim on non-401 status, when no Authorization header is present,
+ * when the token store lacks the inputs to refresh, or when the retry still
+ * returns 401 (which surfaces `needs_oauth_login` upstream).
+ */
+export function createDedupedRefreshFetch(deps) {
+    const { serverName, tokenStore, deduper, innerFetch, addClientAuthentication, logger } = deps;
+    return async (input, init) => {
+        const response = await innerFetch(input, init);
+        if (response.status !== 401) {
+            return response;
+        }
+        // 401 path — try to dedup-refresh. Read the expired access token from the
+        // OUTGOING Authorization header (NOT the response): that header is the
+        // dedup key. The SDK transport always sets it (the SDK reads tokens()
+        // before each request); if the SDK omitted it, we have no key to dedup
+        // against and surface the 401 verbatim.
+        const expiredAccessToken = extractBearer(init?.headers);
+        if (expiredAccessToken === undefined) {
+            logger.debug?.({ submodule: SUBMODULE, serverName, status: 401 }, "401 without an outgoing Bearer — cannot dedup-refresh; surfacing");
+            return response;
+        }
+        const [storedTokens, clientInfo, discovery] = await Promise.all([
+            tokenStore.tokens(serverName),
+            tokenStore.clientInformation(serverName),
+            tokenStore.discoveryState(serverName),
+        ]);
+        const refreshToken = storedTokens?.refresh_token;
+        if (refreshToken === undefined ||
+            clientInfo === undefined ||
+            discovery === undefined) {
+            // Missing inputs — surface the 401 verbatim. The SDK's auth() would also
+            // fail to refresh here (no refresh_token / no discovery); we let
+            // connectServer surface needs_oauth_login from the resulting
+            // UnauthorizedError.
+            logger.debug?.({
+                submodule: SUBMODULE,
+                serverName,
+                status: 401,
+                hasRefreshToken: refreshToken !== undefined,
+                hasClientInfo: clientInfo !== undefined,
+                hasDiscovery: discovery !== undefined,
+            }, "401 path: missing refresh inputs — surfacing 401 for needs_oauth_login");
+            return response;
+        }
+        // CRITICAL: the body has been consumed by `innerFetch`. Cancel it now so
+        // the socket can be released before the retry; the SDK does not read 401
+        // bodies anyway (it inspects status + WWW-Authenticate).
+        await response.body?.cancel().catch(() => undefined);
+        // Drive the deduped refresh (thundering herd → 1 refresh POST). The
+        // deduper persists rotated tokens via tokenStore.saveTokens so a
+        // subsequent connect/refresh reads the new refresh_token off disk.
+        let refreshed;
+        try {
+            refreshed = await deduper.dedupedRefresh({
+                serverName,
+                authServerUrl: discovery.authorizationServerUrl,
+                accessToken: expiredAccessToken,
+                refreshToken,
+                clientInformation: clientInfo,
+                ...(discovery.authorizationServerMetadata !== undefined
+                    ? { metadata: discovery.authorizationServerMetadata }
+                    : {}),
+                ...(addClientAuthentication !== undefined ? { addClientAuthentication } : {}),
+            });
+        }
+        catch (err) {
+            // Refresh itself failed (provider rejected the refresh_token, or 5xx).
+            // Surface the original 401 — the SDK reads status + WWW-Authenticate;
+            // connectServer surfaces needs_oauth_login from the resulting
+            // UnauthorizedError. Log via WARN (the deduper already logged its own
+            // failure WARN with the err detail).
+            logger.warn({
+                submodule: SUBMODULE,
+                serverName,
+                hint: "OAuth refresh on 401 failed — operator must re-login via `comis mcp login <server>`",
+                errorKind: "auth",
+                err: err instanceof Error ? err : new Error(String(err)),
+            }, "OAuth deduped refresh failed; surfacing 401");
+            return response;
+        }
+        const newAccessToken = refreshed.tokens.access_token;
+        if (!newAccessToken) {
+            // Provider returned a refresh response without an access_token (spec
+            // violation). Surface the 401 — re-trying with an empty bearer would
+            // 401 again and could loop.
+            logger.warn({
+                submodule: SUBMODULE,
+                serverName,
+                hint: "OAuth refresh returned no access_token — provider spec violation; re-login required",
+                errorKind: "auth",
+            }, "OAuth deduped refresh returned no access_token; surfacing 401");
+            return response;
+        }
+        // One retry with the rotated bearer. We intentionally do NOT recurse on a
+        // second 401 — a fresh access token that still 401s indicates a provider-
+        // side issue (revoked, scope mismatch) the deduper cannot fix. Return that
+        // 401 verbatim so the SDK surfaces UnauthorizedError and connectServer
+        // tags needs_oauth_login.
+        logger.debug?.({ submodule: SUBMODULE, serverName }, "401 path: retrying original request with refreshed bearer");
+        return innerFetch(input, withRefreshedBearer(init, newAccessToken));
+    };
+}