@zackbart/connecta 0.21.1 → 0.22.0

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/api.d.ts

@@ -34,6 +34,8 @@ export interface ApiOptions {
     /** Human-readable display name; the connector id remains the address prefix. */
     title?: string;
     description?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    authScope?: "shared" | "personal";
     /**
      * Max inline result size (bytes) for this connector's tools before
      * call_tool truncates and stashes the full text for get_result

package/dist/connectors/api.js

@@ -40,6 +40,7 @@ export function api(id, opts) {
         kind: "api",
         ...defined({
             description: opts.description,
+            authScope: opts.authScope,
             maxResultBytes: opts.maxResultBytes,
             callAdmission: opts.callAdmission,
             usageGuide: opts.usageGuide,

package/dist/connectors/remote-mcp.d.ts

@@ -59,6 +59,8 @@ export interface RemoteMcpOptions {
     /** Human-readable display name; the connector id remains the address prefix. */
     title?: string;
     description?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    authScope?: "shared" | "personal";
     /**
      * Max inline result size (bytes) for this connector's tools before
      * call_tool truncates and stashes the full text for get_result

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";
@@ -320,6 +320,11 @@ export function redirectSafeFetch(connectorId, policy = "none", baseFetch = fetc
  * server or hide other connectors).
  */
 export function remoteMcp(id, opts) {
+    if (opts.authScope === "personal" && opts.auth?.type === "headers") {
+        throw new Error(`[connecta] connector "${id}" cannot combine authScope "personal" ` +
+            "with static headers. Use credential or OAuth auth so each principal " +
+            "can own a different grant.");
+    }
     // Weak keys ensure a completed request does not leave its SDK client,
     // transport, response bodies, AbortSignals, or connection promise reachable
     // from the isolate singleton. Those are request-bound in Cloudflare Workers.
@@ -328,6 +333,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 +505,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 +522,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"
@@ -749,6 +758,7 @@ export function remoteMcp(id, opts) {
         ...(opts.description !== undefined
             ? { description: opts.description }
             : {}),
+        ...(opts.authScope !== undefined ? { authScope: opts.authScope } : {}),
         ...(opts.maxResultBytes !== undefined
             ? { maxResultBytes: opts.maxResultBytes }
             : {}),

package/dist/credentials.d.ts

@@ -107,11 +107,11 @@ export declare class CredentialVault {
     constructor(storage: KVStorage, encryptionKey: string);
     private additionalData;
     private read;
-    get(connectorId: string, field?: string): Promise<string | null>;
-    getAll(connectorId: string): Promise<ConnectorCredentialValues | null>;
-    metadata(connectorId: string): Promise<CredentialMetadata | null>;
-    set(connectorId: string, value: string, updatedBy: string): Promise<CredentialMetadata>;
-    setAll(connectorId: string, values: ConnectorCredentialValues, updatedBy: string): Promise<CredentialMetadata>;
-    delete(connectorId: string): Promise<void>;
+    get(connectorId: string, field?: string, owner?: string): Promise<string | null>;
+    getAll(connectorId: string, owner?: string): Promise<ConnectorCredentialValues | null>;
+    metadata(connectorId: string, owner?: string): Promise<CredentialMetadata | null>;
+    set(connectorId: string, value: string, updatedBy: string, owner?: string): Promise<CredentialMetadata>;
+    setAll(connectorId: string, values: ConnectorCredentialValues, updatedBy: string, owner?: string): Promise<CredentialMetadata>;
+    delete(connectorId: string, owner?: string): Promise<void>;
 }
 export {};