@zackbart/connecta 0.21.1 → 0.21.2

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this package are documented here.
 
+## 0.21.2 — 2026-08-31
+
+This patch closes two runtime isolation gaps: concurrent request scopes now
+share one downstream OAuth refresh inside a connector runtime, and QuickJS
+children no longer inherit the deployment process environment. Existing
+deployments need no configuration or storage migration. OAuth deployments get
+the refresh fix automatically; Node deployments using QuickJS get the tighter
+child boundary automatically. Deployments using neither path can ignore this
+release.
+
+### Changed
+
+- **Empty QuickJS child environments.** The Node process hosting the QuickJS
+  guest runtime starts with an explicit empty environment, so deployment
+  credentials and Node startup configuration such as `NODE_OPTIONS` never
+  cross the child-process boundary (#515).
+
+### Fixed
+
+- **One rotating-token redemption per runtime.** Concurrent request scopes for
+  one OAuth connector generation share the owner's refresh result or bounded
+  failure instead of independently redeeming the same refresh token. The gate
+  remains request-safe across follower and owner cancellation, storage
+  failures, force reauthorization, and issuer-generation changes (#514).
+- **Late and byte-identical refresh races.** Generation-scoped mutation and
+  success identities close token-save TOCTOU and complete-flight ABA windows,
+  including authorization servers that preserve the refresh token or return
+  byte-identical credentials. The guarantee is deliberately runtime-local;
+  `KVStorage` still has no cross-isolate compare-and-set primitive (#514).
+
 ## 0.21.1 — 2026-08-30
 
 This patch aligns the handwritten Cloudflare and Notion contracts and the four

package/dist/auth/downstream-oauth.d.ts

@@ -1,5 +1,55 @@
-import type { OAuthClientInformationContext, OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthTokens } from "@modelcontextprotocol/client";
+import type { FetchLike, OAuthClientInformationContext, OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthTokens } from "@modelcontextprotocol/client";
 import type { KVStorage } from "../types.js";
+type OAuthRefreshFlightOutcome = {
+    status: "refreshed";
+} | {
+    status: "retired";
+} | {
+    status: "failed";
+    error: unknown;
+};
+interface OAuthRefreshFlight {
+    done: Promise<OAuthRefreshFlightOutcome>;
+    release: (outcome: OAuthRefreshFlightOutcome) => void;
+    stopObservingOwnerAbort: () => void;
+    mutationId: object;
+}
+/**
+ * Share one rotating-token redemption within one connector runtime and OAuth
+ * generation. The first request still owns the real fetch and response. Its
+ * abort signal has one bounded listener until the exact flight settles, so a
+ * cancellation after the response cannot strand waiters during token storage.
+ * Followers wait for that provider to save tokens, then re-read storage. The
+ * map never retains a token response or transport.
+ *
+ * This is intentionally runtime-local. KVStorage has no atomic coordination
+ * operation, so a second isolate can still race the same refresh token.
+ */
+export declare class OAuthRefreshCoordinator {
+    private readonly flights;
+    /** Opaque identities only: no request promise, signal, callback, or response. */
+    private readonly pendingMutations;
+    /** One bounded latest-success slot, containing only generation + identity. */
+    private successfulRefresh;
+    /** Replaced on every map mutation, closing flight/pending ABA across awaits. */
+    private stateRevision;
+    private advanceStateRevision;
+    private observeAuthoritativeGeneration;
+    private settle;
+    private markMutationPending;
+    private finishMutation;
+    /** @internal Opaque basis for issuer-aware provider token reads. */
+    successfulRefreshIdentity(generation: string): object | undefined;
+    coordinatedFetch(provider: KvOAuthProvider, baseFetch: FetchLike, requestSignal?: AbortSignal): FetchLike;
+    /** Publish one exact owner's successful save without disturbing a newer try. */
+    succeedMutation(generation: string, flight: OAuthRefreshFlight): void;
+    /** Give joined callers a fetch/flow failure, without rejecting the gate. */
+    fail(generation: string, flight: OAuthRefreshFlight, error: unknown): void;
+    /** Finish an exact failed credential write, then publish its failure. */
+    failMutation(generation: string, flight: OAuthRefreshFlight, error: unknown): void;
+    /** Force reauthorization fences and wakes every waiter on the retired epoch. */
+    retire(generation: string): void;
+}
 /**
  * Physical key for an OAuth value in one authorization epoch. Legacy values
  * keep their historical names so upgrades can read an existing grant. Modern
@@ -20,19 +70,31 @@ export declare class KvOAuthProvider implements OAuthClientProvider {
     private readonly connectorId;
     private readonly storage;
     private readonly redirectUri;
+    private readonly refreshCoordinator?;
     /**
      * The reset generation this provider's flow started under. Every OAuth value
      * it writes carries this epoch, so a late write can land after a reset without
      * becoming readable under the new generation.
      */
     private capturedGeneration;
-    constructor(connectorId: string, storage: KVStorage, redirectUri: string);
+    private refreshFlight;
+    /** Tokens this request's issuer-aware auth flow decided to refresh. */
+    private refreshBasis;
+    constructor(connectorId: string, storage: KVStorage, redirectUri: string, refreshCoordinator?: OAuthRefreshCoordinator | undefined);
     /**
      * Stamp the force-reauth generation the current connect flow started under.
      * Called by the connector once per connect, before c.connect(). The callback
      * path captures the generation stored beside its verified state instead.
      */
     captureGeneration(gen: string): void;
+    /** The generation captured for this flow, before a concurrent reset. */
+    flowGeneration(): Promise<string>;
+    /** @internal Record the refresh attempt this provider owns. */
+    captureRefreshFlight(generation: string, flight: OAuthRefreshFlight): void;
+    private succeedRefreshFlight;
+    private failRefreshFlight;
+    /** True when another request saved a refresh result after this flow's read. */
+    refreshBasisChanged(current: OAuthTokens, generation: string): boolean;
     /**
      * The epoch this provider writes under. Direct unit/custom use lazily captures
      * the current generation; connector-driven connect and callback paths stamp it
@@ -121,3 +183,4 @@ export declare class KvOAuthProvider implements OAuthClientProvider {
     resetAuthorization(operatorDisconnected?: boolean): Promise<void>;
     invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
 }
+export {};

package/dist/auth/downstream-oauth.js

@@ -26,6 +26,312 @@ const OAUTH_VALUE_KEYS = [
     "oauth:state",
 ];
 const MAX_CLEANUP_BACKLOG = 1_000;
+function isRefreshTokenRequest(init) {
+    if ((init?.method ?? "GET").toUpperCase() !== "POST")
+        return false;
+    const body = init?.body;
+    if (body instanceof URLSearchParams) {
+        return body.get("grant_type") === "refresh_token";
+    }
+    if (typeof body !== "string")
+        return false;
+    return new URLSearchParams(body).get("grant_type") === "refresh_token";
+}
+function sdkAcceptsOAuthTokens(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (typeof candidate.access_token !== "string" ||
+        typeof candidate.token_type !== "string") {
+        return false;
+    }
+    for (const key of ["id_token", "scope", "refresh_token"]) {
+        if (candidate[key] !== undefined && typeof candidate[key] !== "string") {
+            return false;
+        }
+    }
+    if (candidate.expires_in !== undefined) {
+        try {
+            if (!Number.isFinite(Number(candidate.expires_in)))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+async function refreshResponseFailure(response) {
+    if (!response.ok) {
+        return new Error(`OAuth refresh failed with HTTP ${response.status}.`);
+    }
+    try {
+        return sdkAcceptsOAuthTokens(await response.clone().json())
+            ? undefined
+            : new Error("OAuth refresh response did not match the token schema.");
+    }
+    catch {
+        return new Error("OAuth refresh response did not contain JSON tokens.");
+    }
+}
+function refreshMutationPendingResponse() {
+    return Response.json({
+        error: "temporarily_unavailable",
+        error_description: "OAuth refresh is temporarily unavailable while previous credentials commit.",
+    }, { status: 503 });
+}
+function aborted(signal) {
+    return (signal.reason ?? new DOMException("This operation was aborted", "AbortError"));
+}
+async function waitForRefreshFlight(flight, signal) {
+    let outcome;
+    if (!signal) {
+        outcome = await flight.done;
+    }
+    else {
+        outcome = await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (settle) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", onAbort);
+                settle();
+            };
+            const onAbort = () => finish(() => reject(aborted(signal)));
+            signal.addEventListener("abort", onAbort, { once: true });
+            void flight.done.then((result) => finish(() => resolve(result)));
+            // Abort may land between the caller's check and listener registration.
+            if (signal.aborted)
+                onAbort();
+        });
+    }
+    if (outcome.status === "failed")
+        throw outcome.error;
+    return outcome;
+}
+/**
+ * Share one rotating-token redemption within one connector runtime and OAuth
+ * generation. The first request still owns the real fetch and response. Its
+ * abort signal has one bounded listener until the exact flight settles, so a
+ * cancellation after the response cannot strand waiters during token storage.
+ * Followers wait for that provider to save tokens, then re-read storage. The
+ * map never retains a token response or transport.
+ *
+ * This is intentionally runtime-local. KVStorage has no atomic coordination
+ * operation, so a second isolate can still race the same refresh token.
+ */
+export class OAuthRefreshCoordinator {
+    flights = new Map();
+    /** Opaque identities only: no request promise, signal, callback, or response. */
+    pendingMutations = new Map();
+    /** One bounded latest-success slot, containing only generation + identity. */
+    successfulRefresh;
+    /** Replaced on every map mutation, closing flight/pending ABA across awaits. */
+    stateRevision = {};
+    advanceStateRevision() {
+        this.stateRevision = {};
+    }
+    observeAuthoritativeGeneration(generation) {
+        const staleGenerations = new Set([
+            ...this.flights.keys(),
+            ...this.pendingMutations.keys(),
+        ]);
+        for (const stale of staleGenerations) {
+            if (stale !== generation)
+                this.retire(stale);
+        }
+        if (this.successfulRefresh &&
+            this.successfulRefresh.generation !== generation) {
+            this.successfulRefresh = undefined;
+            this.advanceStateRevision();
+        }
+    }
+    settle(generation, flight, outcome) {
+        if (this.flights.get(generation) !== flight)
+            return;
+        this.flights.delete(generation);
+        this.advanceStateRevision();
+        flight.stopObservingOwnerAbort();
+        flight.release(outcome);
+    }
+    markMutationPending(generation, flight) {
+        if (this.flights.get(generation) !== flight)
+            return false;
+        this.pendingMutations.set(generation, flight.mutationId);
+        this.advanceStateRevision();
+        return true;
+    }
+    finishMutation(generation, flight) {
+        if (this.pendingMutations.get(generation) === flight.mutationId) {
+            this.pendingMutations.delete(generation);
+            this.advanceStateRevision();
+            return true;
+        }
+        return false;
+    }
+    /** @internal Opaque basis for issuer-aware provider token reads. */
+    successfulRefreshIdentity(generation) {
+        return this.successfulRefresh?.generation === generation
+            ? this.successfulRefresh.identity
+            : undefined;
+    }
+    coordinatedFetch(provider, baseFetch, requestSignal) {
+        return async (input, init) => {
+            // Await passthrough failures here so workerd associates the rejection
+            // with the fetch the SDK is already awaiting, rather than reporting the
+            // adopted inner promise as an unhandled rejection.
+            if (!isRefreshTokenRequest(init))
+                return await baseFetch(input, init);
+            const generation = await provider.flowGeneration();
+            const requestedRefreshToken = init?.body instanceof URLSearchParams
+                ? init.body.get("refresh_token")
+                : new URLSearchParams(String(init?.body ?? "")).get("refresh_token");
+            while (true) {
+                const revisionBeforeReads = this.stateRevision;
+                const activeGeneration = await provider.generation();
+                this.observeAuthoritativeGeneration(activeGeneration);
+                if (activeGeneration !== generation)
+                    this.retire(generation);
+                const activeFlight = this.flights.get(generation);
+                const pendingMutation = this.pendingMutations.get(generation);
+                if (activeGeneration === generation &&
+                    pendingMutation &&
+                    activeFlight?.mutationId !== pendingMutation) {
+                    return refreshMutationPendingResponse();
+                }
+                let currentTokens = activeGeneration === generation ? await provider.tokens() : undefined;
+                const latestGeneration = await provider.generation();
+                this.observeAuthoritativeGeneration(latestGeneration);
+                if (latestGeneration !== generation) {
+                    this.retire(generation);
+                    currentTokens = undefined;
+                }
+                if (this.stateRevision !== revisionBeforeReads)
+                    continue;
+                // Re-check both identities after every storage await. An owner can
+                // abort while this caller reads tokens, leaving only the mutation
+                // marker; a reset can likewise retire this caller's captured epoch.
+                const existing = this.flights.get(generation);
+                const latestPendingMutation = this.pendingMutations.get(generation);
+                if (latestGeneration === generation &&
+                    latestPendingMutation &&
+                    existing?.mutationId !== latestPendingMutation) {
+                    return refreshMutationPendingResponse();
+                }
+                // This flow may have read a token just before another flow saved its
+                // rotation. Replaying the retired token would recreate the race after
+                // the first network response. Give the SDK the already-saved rotating
+                // credential instead. A tokenless current value cannot do that: the
+                // SDK would merge the requested old refresh token back into it.
+                if (currentTokens?.refresh_token &&
+                    (currentTokens.refresh_token !== requestedRefreshToken ||
+                        provider.refreshBasisChanged(currentTokens, generation))) {
+                    return Response.json(currentTokens);
+                }
+                if (currentTokens?.refresh_token !== requestedRefreshToken) {
+                    return Response.json({
+                        error: "invalid_grant",
+                        error_description: "Refresh token is no longer active.",
+                    }, { status: 400 });
+                }
+                if (existing) {
+                    const outcome = await waitForRefreshFlight(existing, requestSignal);
+                    if (outcome.status === "refreshed") {
+                        const activeGeneration = await provider.generation();
+                        const refreshedTokens = activeGeneration === generation
+                            ? await provider.tokens()
+                            : undefined;
+                        if (refreshedTokens?.refresh_token) {
+                            return Response.json(refreshedTokens);
+                        }
+                    }
+                    continue;
+                }
+                let release;
+                const flight = {
+                    done: new Promise((resolve) => {
+                        release = resolve;
+                    }),
+                    release: (outcome) => release(outcome),
+                    stopObservingOwnerAbort: () => { },
+                    mutationId: {},
+                };
+                this.flights.set(generation, flight);
+                this.advanceStateRevision();
+                provider.captureRefreshFlight(generation, flight);
+                if (requestSignal) {
+                    let observing = true;
+                    const onOwnerAbort = () => {
+                        this.fail(generation, flight, aborted(requestSignal));
+                    };
+                    flight.stopObservingOwnerAbort = () => {
+                        if (!observing)
+                            return;
+                        observing = false;
+                        requestSignal.removeEventListener("abort", onOwnerAbort);
+                    };
+                    requestSignal.addEventListener("abort", onOwnerAbort, { once: true });
+                    // Abort may land between flight publication and listener registration.
+                    if (requestSignal.aborted)
+                        onOwnerAbort();
+                }
+                try {
+                    const response = await baseFetch(input, requestSignal ? { ...init, signal: requestSignal } : init);
+                    // These responses never reach a successful saveTokens callback. Give
+                    // current waiters a bounded failure now while leaving the owner's
+                    // response untouched for the SDK to parse and classify itself.
+                    const failure = await refreshResponseFailure(response);
+                    if (failure) {
+                        this.fail(generation, flight, failure);
+                    }
+                    else if (requestSignal?.aborted ||
+                        !this.markMutationPending(generation, flight)) {
+                        throw requestSignal?.aborted
+                            ? aborted(requestSignal)
+                            : new Error("OAuth refresh ended before tokens could be saved.");
+                    }
+                    return response;
+                }
+                catch (error) {
+                    this.fail(generation, flight, error);
+                    throw error;
+                }
+            }
+        };
+    }
+    /** Publish one exact owner's successful save without disturbing a newer try. */
+    succeedMutation(generation, flight) {
+        if (this.finishMutation(generation, flight)) {
+            this.successfulRefresh = { generation, identity: {} };
+            this.advanceStateRevision();
+        }
+        this.settle(generation, flight, { status: "refreshed" });
+    }
+    /** Give joined callers a fetch/flow failure, without rejecting the gate. */
+    fail(generation, flight, error) {
+        this.settle(generation, flight, { status: "failed", error });
+    }
+    /** Finish an exact failed credential write, then publish its failure. */
+    failMutation(generation, flight, error) {
+        this.finishMutation(generation, flight);
+        this.settle(generation, flight, { status: "failed", error });
+    }
+    /** Force reauthorization fences and wakes every waiter on the retired epoch. */
+    retire(generation) {
+        if (this.pendingMutations.delete(generation)) {
+            this.advanceStateRevision();
+        }
+        if (this.successfulRefresh?.generation === generation) {
+            this.successfulRefresh = undefined;
+            this.advanceStateRevision();
+        }
+        const flight = this.flights.get(generation);
+        if (!flight)
+            return;
+        this.settle(generation, flight, { status: "retired" });
+    }
+}
 function storedOAuthValue(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -75,16 +381,21 @@ export class KvOAuthProvider {
     connectorId;
     storage;
     redirectUri;
+    refreshCoordinator;
     /**
      * The reset generation this provider's flow started under. Every OAuth value
      * it writes carries this epoch, so a late write can land after a reset without
      * becoming readable under the new generation.
      */
     capturedGeneration = null;
-    constructor(connectorId, storage, redirectUri) {
+    refreshFlight;
+    /** Tokens this request's issuer-aware auth flow decided to refresh. */
+    refreshBasis;
+    constructor(connectorId, storage, redirectUri, refreshCoordinator) {
         this.connectorId = connectorId;
         this.storage = storage;
         this.redirectUri = redirectUri;
+        this.refreshCoordinator = refreshCoordinator;
     }
     /**
      * Stamp the force-reauth generation the current connect flow started under.
@@ -94,6 +405,43 @@ export class KvOAuthProvider {
     captureGeneration(gen) {
         this.capturedGeneration = gen;
     }
+    /** The generation captured for this flow, before a concurrent reset. */
+    async flowGeneration() {
+        return this.capturedGeneration ?? this.generation();
+    }
+    /** @internal Record the refresh attempt this provider owns. */
+    captureRefreshFlight(generation, flight) {
+        this.refreshFlight = { generation, flight };
+    }
+    succeedRefreshFlight() {
+        const owned = this.refreshFlight;
+        this.refreshFlight = undefined;
+        if (owned) {
+            this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
+        }
+    }
+    failRefreshFlight(error, mutationFinished = false) {
+        const owned = this.refreshFlight;
+        this.refreshFlight = undefined;
+        if (owned) {
+            if (mutationFinished) {
+                this.refreshCoordinator?.failMutation(owned.generation, owned.flight, error);
+            }
+            else {
+                this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
+            }
+        }
+    }
+    /** True when another request saved a refresh result after this flow's read. */
+    refreshBasisChanged(current, generation) {
+        const basis = this.refreshBasis;
+        return Boolean(basis &&
+            basis.generation === generation &&
+            (basis.accessToken !== current.access_token ||
+                basis.refreshToken !== current.refresh_token ||
+                basis.successIdentity !==
+                    this.refreshCoordinator?.successfulRefreshIdentity(generation)));
+    }
     /**
      * The epoch this provider writes under. Direct unit/custom use lazily captures
      * the current generation; connector-driven connect and callback paths stamp it
@@ -274,10 +622,32 @@ export class KvOAuthProvider {
         await this.writeValue("oauth:client", info, (value) => JSON.stringify(value), ctx?.issuer);
     }
     async tokens(ctx) {
-        return this.readIssuerBoundValue("oauth:tokens", (raw) => JSON.parse(raw), (value) => JSON.stringify(value), ctx);
+        const refreshGeneration = ctx ? await this.flowGeneration() : undefined;
+        const successIdentity = refreshGeneration !== undefined
+            ? this.refreshCoordinator?.successfulRefreshIdentity(refreshGeneration)
+            : undefined;
+        const tokens = await this.readIssuerBoundValue("oauth:tokens", (raw) => JSON.parse(raw), (value) => JSON.stringify(value), ctx);
+        if (ctx && tokens && refreshGeneration !== undefined) {
+            this.refreshBasis = {
+                accessToken: tokens.access_token,
+                generation: refreshGeneration,
+                ...(tokens.refresh_token !== undefined
+                    ? { refreshToken: tokens.refresh_token }
+                    : {}),
+                ...(successIdentity !== undefined ? { successIdentity } : {}),
+            };
+        }
+        return tokens;
     }
     async saveTokens(tokens, ctx) {
-        await this.writeValue("oauth:tokens", tokens, (value) => JSON.stringify(value), ctx?.issuer);
+        try {
+            await this.writeValue("oauth:tokens", tokens, (value) => JSON.stringify(value), ctx?.issuer);
+            this.succeedRefreshFlight();
+        }
+        catch (error) {
+            this.failRefreshFlight(error, true);
+            throw error;
+        }
     }
     /**
      * OAuth `state`. The SDK calls this (when present) and appends the value to
@@ -317,7 +687,14 @@ export class KvOAuthProvider {
         return stored.value;
     }
     async redirectToAuthorization(authorizationUrl) {
-        await this.writeValue("oauth:pending", authorizationUrl.toString(), (raw) => raw);
+        try {
+            await this.writeValue("oauth:pending", authorizationUrl.toString(), (raw) => raw);
+            this.failRefreshFlight(new Error("OAuth refresh required reauthorization before tokens were saved."));
+        }
+        catch (error) {
+            this.failRefreshFlight(error);
+            throw error;
+        }
     }
     /** The stored authorization URL, if a flow is pending. */
     async pendingAuthorizationUrl() {
@@ -385,6 +762,7 @@ export class KvOAuthProvider {
         // reset's epoch after their cleanup finishes out of order.
         try {
             await this.storage.set("oauth:generation", active);
+            this.refreshCoordinator?.retire(previous);
         }
         catch (error) {
             try {
@@ -414,23 +792,33 @@ export class KvOAuthProvider {
             throw firstError;
     }
     async invalidateCredentials(scope) {
-        const generation = await this.writeGeneration();
-        if (scope === "all") {
-            await this.deleteAll([
-                oauthValueStorageKey("oauth:client", generation),
-                oauthValueStorageKey("oauth:tokens", generation),
-                oauthValueStorageKey("oauth:verifier", generation),
-            ]);
-            return;
-        }
-        if (scope === "client") {
-            await this.storage.delete(oauthValueStorageKey("oauth:client", generation));
-        }
-        if (scope === "tokens") {
-            await this.storage.delete(oauthValueStorageKey("oauth:tokens", generation));
+        const endsRefresh = scope === "all" || scope === "tokens";
+        try {
+            const generation = await this.writeGeneration();
+            if (scope === "all") {
+                await this.deleteAll([
+                    oauthValueStorageKey("oauth:client", generation),
+                    oauthValueStorageKey("oauth:tokens", generation),
+                    oauthValueStorageKey("oauth:verifier", generation),
+                ]);
+            }
+            else if (scope === "client") {
+                await this.storage.delete(oauthValueStorageKey("oauth:client", generation));
+            }
+            else if (scope === "tokens") {
+                await this.storage.delete(oauthValueStorageKey("oauth:tokens", generation));
+            }
+            else if (scope === "verifier") {
+                await this.storage.delete(oauthValueStorageKey("oauth:verifier", generation));
+            }
+            if (endsRefresh) {
+                this.failRefreshFlight(new Error("OAuth refresh invalidated credentials before tokens were saved."));
+            }
         }
-        if (scope === "verifier") {
-            await this.storage.delete(oauthValueStorageKey("oauth:verifier", generation));
+        catch (error) {
+            if (endsRefresh)
+                this.failRefreshFlight(error);
+            throw error;
         }
     }
 }

package/dist/connectors/remote-mcp.js

@@ -1,5 +1,5 @@
 import { Client, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
-import { KvOAuthProvider } from "../auth/downstream-oauth.js";
+import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { ConnectorCallError, msg } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
@@ -328,6 +328,9 @@ export function remoteMcp(id, opts) {
     // must not recreate an ownerless connection under the ended scope.
     const closedScopes = new WeakSet();
     const isOauth = opts.auth?.type === "oauth";
+    // Long-lived enough for distinct request scopes in this connector runtime to
+    // join one token redemption. It owns no client, transport, or request state.
+    const refreshCoordinator = new OAuthRefreshCoordinator();
     const logger = opts.logger ?? console;
     const credentialAuth = opts.auth?.type === "credential" ? opts.auth : undefined;
     if (credentialAuth?.credential?.fields?.length) {
@@ -497,7 +500,7 @@ export function remoteMcp(id, opts) {
     const newProvider = (ctx, state) => {
         if (state?.provider)
             return state.provider;
-        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`);
+        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator);
         if (state)
             state.provider = provider;
         return provider;
@@ -514,9 +517,10 @@ export function remoteMcp(id, opts) {
         const url = new URL(opts.url);
         const guardedFetch = redirectSafeFetch(id, opts.redirects);
         if (opts.auth?.type === "oauth") {
+            const oauthProvider = provider ?? newProvider(ctx);
             return new StreamableHTTPClientTransport(url, {
-                authProvider: provider ?? newProvider(ctx),
-                fetch: guardedFetch,
+                authProvider: oauthProvider,
+                fetch: refreshCoordinator.coordinatedFetch(oauthProvider, guardedFetch, ctx.signal),
             });
         }
         const headers = opts.auth?.type === "headers"

package/dist/executors/quickjs.js

@@ -278,6 +278,10 @@ class QuickJsChildPool {
                 "@zackbart/connecta/quickjs) when bundling the server.");
         }
         const child = fork(childPath, [], {
+            // The child needs only its entry path, exec arguments, and IPC channel.
+            // Do not copy deployment credentials or Node startup configuration into
+            // the process that contains the guest runtime.
+            env: {},
             execArgv: sourceMode ? ["--import", "tsx"] : [],
             stdio: ["ignore", "ignore", "pipe", "ipc"],
         });

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.21.1";
+export declare const CONNECTA_VERSION = "0.21.2";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.21.1";
+export const CONNECTA_VERSION = "0.21.2";

package/documentation/architecture.md

@@ -20,6 +20,23 @@ isolate or process —
 on Workers that means a lazy module-scope singleton, which is why both
 deployment shapes build it outside the request handler.
 
+An OAuth `remoteMcp()` connector also owns a runtime-local refresh completion
+gate. It coordinates credential mutation across concurrent request scopes but
+never shares their clients, transports, or responses, and never lets a follower
+cancel the owner. Every participant still awaits the refresh inside its own
+request lifetime; a cancelled follower leaves the shared owner untouched and
+removes only its own wait. The owner's request signal belongs to its token
+fetch. Cancelling that owner fails current joiners too because promoting one
+could replay a refresh token the authorization server already consumed.
+
+The coordinator retains the owner's abort signal only through one temporary
+listener on the exact active refresh. Save, failure, cancellation, or
+generation retirement removes it along with the map entry. It never retains a
+token response, client, or transport. If cancellation lands after a valid
+response while its credential write is still running, a generation-keyed
+identity marker rejects new owners until that exact write finishes. The marker
+contains no promise and generation retirement removes it.
+
 **Per request, and no longer.** The MCP server, its transport, downstream MCP
 clients, abort signals, and the connector scope a probe opens all belong to the
 request that created them. `Nothing request-bound survives a request` is an

package/documentation/auth.md

@@ -65,7 +65,7 @@ Worker-level Access runs before every connecta route. Consequently:
   OAuth discovery paths when Managed OAuth is enabled.
 
 The [Worker example](../examples/worker/) carries the complete deployment shape
-and the [upgrade guide](./upgrading.md#0200--0211) gives the reversible Clerk
+and the [upgrade guide](./upgrading.md#0200--0212) gives the reversible Clerk
 migration.
 
 ## Clerk configuration is checked at construction

package/documentation/code-mode.md

@@ -746,7 +746,7 @@ Worker renders arguments with `String()` (so an object logs as
 latter two. Only the three captured everywhere are contract (`R5`); rendering is
 not.
 
-**X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
+**X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. Its Node child starts with an explicitly empty process environment rather than inheriting deployment variables or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
 The supported Worker construction is exactly `new DynamicWorkerExecutor({ loader })`. Do not pass `bindings`, `modules`, or `globalOutbound`: each can grant ambient configuration, code, or egress. Under it, `process.env`, lexical `this.env`, and `cloudflare:workers.env` are empty; `node:fs`, `node:http`, and `node:https` are unavailable through either access route; external `fetch`, `WebSocket`, `node:net`, and `node:tls` fail with workerd's outbound-denial error; DNS lookup ends unresolved; and `fetch("data:...")` resolves locally.
 `P2` is the portable contract. Programs use none of this runtime-only authority, including timers and `crypto`, because the same code fails on QuickJS. The `execute_code` description and served `usage` skill say so before an agent writes code.
 
@@ -832,7 +832,7 @@ the upstream `Executor` shape assignable.
 | Clauses | Test |
 | --- | --- |
 | `P1`, `P5` | `test/guest-api-contract.test.ts` (TypeScript syntax), `test/quickjs-executor.test.ts` (`normalizeCode`) |
-| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
+| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (empty child-process environment), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
 | `P3`, `X9` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` |
 | `P4` | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution) |
 | `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (sanitizing), `test/server.test.ts` (bounded live connector inventory) |

package/documentation/operations.md

@@ -239,7 +239,7 @@ in.
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
-| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and races, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
+| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, runtime-local rotating-token refresh coordination across request scopes, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
 | `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
 | `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
@@ -291,7 +291,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, dependency-free Cloudflare Access behind its Worker subpath, every provider independently importable, and the Cloudflare API provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
-| `quickjs-child-stderr.test.ts` | abnormal child exits retaining only an 8 KiB stderr tail, included in the parent-side diagnostic | mocks Node child-process streams |
+| `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, plus abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic | mocks Node child-process streams |
 | `quickjs-executor.test.ts` | the child-process sandbox — code normalization, lazy namespace proxies, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |

package/documentation/storage-and-credentials.md

@@ -107,3 +107,38 @@ the retired grant.
 The OAuth callback verifies the one-shot `state` first, then hands the complete
 query string—including RFC 9207 `iss`—to the SDK transport. One-shot state,
 verifier, and pending URL are cleared only after a successful exchange.
+
+Within one `remoteMcp()` runtime, one request scope owns refresh-token
+redemption for an OAuth generation. Concurrent scopes wait for the owner's
+token save or bounded failure, then either read storage again or receive that
+failure. A scope that had already read the retired refresh token reuses the
+newly stored rotating token locally instead of sending the retired value
+upstream. Force reauthorization retires the old generation's gate, and a
+failed flow releases ownership for a later attempt. The coordinator retains
+only a completion signal and one temporary owner-abort listener until that
+exact flight settles, never the token response or downstream transport. A
+follower may stop waiting when its own request is cancelled without cancelling
+the owner or poisoning the generation for later callers. If the owner's
+credential mutation fails, joined callers receive that same bounded failure
+instead of waking to redeem the unchanged token; a later independent call may
+retry. Non-success and malformed token responses settle current waiters at the
+fetch boundary, before any later authorization callback can itself fail.
+Cancelling the owner aborts its fetch and fails current joiners rather than
+promoting one: once a request reaches the authorization server, repeating its
+old refresh token is not known to be safe. If that cancellation lands while
+the valid response's credential write is already running, a same-generation
+attempt receives `temporarily_unavailable` until the exact write succeeds or
+fails. This mutation marker contains no retained promise; force
+reauthorization removes it when the old generation becomes unreadable.
+An additional opaque success identity lets a request recognize a refresh that
+completed after its issuer-aware token read even when the authorization server
+returned byte-identical credentials. The identity is generation-scoped and is
+discarded with the retired generation. Every authoritative storage-generation
+read also retires coordinator state from other epochs, so an externally
+advanced generation cannot be overwritten in runtime state by late old work.
+
+This guarantee is runtime-local. `KVStorage` has no atomic lock or
+compare-and-set operation, so separate processes or Worker isolates can still
+redeem the same refresh token concurrently. Generation envelopes continue to
+fence their writes, but Connecta does not claim cross-isolate exactly-once
+refresh.

package/documentation/upgrading.md

@@ -57,7 +57,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.21.1 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.21.2 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.21.1
+npm pkg set dependencies.@zackbart/connecta=0.21.2
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.21.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.21.2 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.21.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.21.2 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,9 +207,9 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
-### 0.20.0 → 0.21.1
+### 0.20.0 → 0.21.2
 
-0.21.1 adds no deployment migration beyond 0.21.0. The boundary is additive
+0.21.2 adds no deployment migration beyond 0.21.0. The boundary is additive
 for Node and existing Clerk deployments. The new Worker path
 uses Cloudflare Access identity directly and removes Clerk only after the edge
 cutover has been verified. An agent can perform every repository edit; a human
@@ -218,7 +218,7 @@ Managed OAuth in the Cloudflare dashboard.
 
 For a Worker currently using Clerk, keep rollback live through the cutover:
 
-1. Bump and install 0.21.1. Add the new provider **before** the existing Clerk
+1. Bump and install 0.21.2. Add the new provider **before** the existing Clerk
    provider, but remove nothing:
 
    ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.21.1",
+    "@zackbart/connecta": "0.21.2",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {