@zackbart/connecta 0.27.0 → 0.28.1

package/dist/auth/downstream-oauth.js

@@ -2,7 +2,30 @@ import { UnauthorizedError } from "@modelcontextprotocol/client";
 import { Deferred, Effect } from "effect";
 import { retryAfterMs } from "../connectors/guarded-fetch.js";
 import { ConnectorCallError } from "../errors.js";
+import { attachOAuthPartition, oauthPartitionFor, retainOAuthPartition, } from "../oauth-partition.js";
+import { inheritOAuthSealer } from "../oauth-sealing.js";
 import { detach, fromSignal, runEdge } from "../runtime/run.js";
+/** RFC 6749 section 3.3: one or more scope tokens, separated by single spaces. */
+const OAUTH_SCOPE = /^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/;
+/** Refuse, at construction, a configured scope no authorization server could parse. */
+export function assertOAuthScope(connectorId, scope) {
+    if (scope !== undefined && !OAUTH_SCOPE.test(scope)) {
+        throw new Error(`[connecta] connector "${connectorId}" OAuth scope must contain space-separated scope tokens.`);
+    }
+}
+/**
+ * The context an explicit authorization start runs under: allowed to begin
+ * consent, with a request scope of its own, carrying the registry's sealer and
+ * owner partition across the copy. Only `startAuth` builds one; status reads
+ * and calls never do, which is what keeps them from starting authorization.
+ */
+export function authorizingContext(ctx) {
+    return attachOAuthPartition(inheritOAuthSealer(ctx, {
+        ...ctx,
+        requestScope: ctx.requestScope ?? ctx,
+        allowAuthorization: true,
+    }), oauthPartitionFor(ctx));
+}
 /** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
 function randomState() {
     const bytes = new Uint8Array(32);
@@ -18,7 +41,7 @@ function timingSafeEqual(a, b) {
         diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
     return diff === 0;
 }
-const LEGACY_GENERATION = "legacy";
+export const LEGACY_GENERATION = "legacy";
 const ACTIVE_GENERATION_PREFIX = "v2:";
 const RESETTING_GENERATION_PREFIX = "reset:";
 const DISCONNECTED_GENERATION_PREFIX = "disconnected:";
@@ -592,6 +615,9 @@ export class OAuthRefreshCoordinator {
                 // reaches the token endpoint.
                 if (requestSignal?.aborted)
                     throw aborted(requestSignal);
+                // The authorization server this redemption answers to, fixed now: a
+                // recovery save outlives the SDK flow that would have stamped it.
+                const issuer = provider.refreshIssuer(generation);
                 const flight = {
                     outcome: Deferred.makeUnsafe(),
                     stopObservingOwnerAbort: () => { },
@@ -601,7 +627,7 @@ export class OAuthRefreshCoordinator {
                     recoveryPending: false,
                     settled: false,
                     releasePartition: this.retainWork(),
-                    persist: (tokens) => provider.saveAcceptedRefreshTokens(tokens, generation, flight),
+                    persist: (tokens) => provider.saveAcceptedRefreshTokens(tokens, generation, flight, issuer),
                 };
                 this.flights.set(generation, flight);
                 this.advanceStateRevision();
@@ -790,6 +816,25 @@ export class OAuthRefreshCoordinator {
         this.settle(generation, flight, { status: "retired" });
     }
 }
+/**
+ * One refresh coordinator per owner partition, for one connector runtime.
+ * Long-lived enough for distinct request scopes to join one token redemption;
+ * it owns no client, transport, or request state. Production contexts carry a
+ * stable registry partition; hand-written contexts coordinate by their shared
+ * storage object instead.
+ */
+export function refreshCoordinatorsByPartition() {
+    const coordinators = new WeakMap();
+    return (ctx) => {
+        const partition = oauthPartitionFor(ctx) ?? ctx.storage;
+        let coordinator = coordinators.get(partition);
+        if (!coordinator) {
+            coordinator = new OAuthRefreshCoordinator(() => retainOAuthPartition(partition));
+            coordinators.set(partition, coordinator);
+        }
+        return coordinator;
+    };
+}
 function storedOAuthValue(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -798,6 +843,7 @@ function storedOAuthValue(value) {
         typeof candidate.generation === "string" &&
         (candidate.issuer === undefined || typeof candidate.issuer === "string") &&
         (candidate.binding === undefined || typeof candidate.binding === "string") &&
+        (candidate.carried === undefined || candidate.carried === true) &&
         "value" in candidate);
 }
 function legacyStoredOAuthValue(value) {
@@ -1012,6 +1058,11 @@ export class KvOAuthProvider {
             this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
         }
     }
+    /** @internal The issuer this flow's issuer-aware read bound its refresh to. */
+    refreshIssuer(generation) {
+        const basis = this.refreshBasis;
+        return basis?.generation === generation ? basis.issuer : undefined;
+    }
     /** True when another request saved a refresh result after this flow's read. */
     refreshBasisChanged(current, generation) {
         const basis = this.refreshBasis;
@@ -1226,6 +1277,7 @@ export class KvOAuthProvider {
                     generation,
                     ...(parsed.issuer !== undefined ? { issuer: parsed.issuer } : {}),
                     ...(parsed.binding !== undefined ? { binding: parsed.binding } : {}),
+                    ...(parsed.carried === true ? { carried: true } : {}),
                     // Only a finite number is a time; anything else reads as untimed.
                     ...(typeof parsed.writtenAt === "number" &&
                         Number.isFinite(parsed.writtenAt)
@@ -1421,6 +1473,7 @@ export class KvOAuthProvider {
             this.refreshBasis = {
                 accessToken: tokens.access_token,
                 generation: refreshGeneration,
+                issuer: ctx.issuer,
                 ...(tokens.refresh_token !== undefined
                     ? { refreshToken: tokens.refresh_token }
                     : {}),
@@ -1438,9 +1491,16 @@ export class KvOAuthProvider {
             await this.persistTokens(tokens, ctx, false, owned);
         }
     }
-    /** @internal Commit an already redeemed rotation even after its request leaves. */
-    async saveAcceptedRefreshTokens(tokens, generation, flight) {
-        await this.persistAcceptedTokens(tokens, undefined, { generation, flight });
+    /**
+     * @internal Commit an already redeemed rotation even after its request
+     * leaves. A token response names no issuer, so the one the refreshed grant
+     * was bound to is stamped here as the SDK's own save would: an unbound
+     * rotation would read as legacy state and bind to whichever authorization
+     * server the connector names next.
+     */
+    async saveAcceptedRefreshTokens(tokens, generation, flight, issuer) {
+        const stamped = issuer !== undefined ? { ...tokens, issuer } : tokens;
+        await this.persistAcceptedTokens(stamped, issuer !== undefined ? { issuer } : undefined, { generation, flight });
     }
     persistAcceptedTokens(tokens, ctx, owned) {
         // The SDK can save the same response while cancellation recovery is
@@ -1542,13 +1602,27 @@ export class KvOAuthProvider {
      * direction to tolerate clock skew between isolates. A URL with no write
      * time — stored by an earlier release, or under a pre-envelope generation —
      * is treated as stale, so the caller starts a fresh flow instead.
+     *
+     * The URL must also still name the epoch's client. A callback whose code
+     * exchange the server refused with `invalid_client` leaves the URL behind
+     * but drops the client; handing that URL back would send the operator to a
+     * consent the server has already refused, where a fresh flow registers.
      */
     async reusablePendingAuthorizationUrl() {
         const pending = await this.readValue("oauth:pending", (raw) => raw);
-        if (pending?.writtenAt === undefined)
+        if (pending?.writtenAt === undefined ||
+            Math.abs(Date.now() - pending.writtenAt) >= PENDING_AUTHORIZATION_MAX_AGE_MS) {
+            return undefined;
+        }
+        let clientId;
+        try {
+            clientId = new URL(pending.value).searchParams.get("client_id");
+        }
+        catch {
             return undefined;
-        return Math.abs(Date.now() - pending.writtenAt) <
-            PENDING_AUTHORIZATION_MAX_AGE_MS
+        }
+        const client = await this.clientInformation();
+        return clientId !== null && client?.client_id === clientId
             ? pending.value
             : undefined;
     }
@@ -1616,24 +1690,13 @@ export class KvOAuthProvider {
     async performResetAuthorization(operatorDisconnected, preserveClient) {
         const nonce = crypto.randomUUID();
         const previous = await this.generation();
-        // Only an explicitly forced restart may carry a registration forward.
-        // Discovery is never copied: the SDK must select the authorization server
-        // again, then its issuer-aware clientInformation hook checks the issuer.
-        const priorClient = preserveClient && !operatorDisconnected && this.clientBinding
-            ? await this.readValue("oauth:client", (raw) => {
-                try {
-                    return JSON.parse(raw);
-                }
-                catch {
-                    return {};
-                }
-            })
-            : undefined;
-        const reusableClient = priorClient?.generation === previous &&
-            priorClient.issuer !== undefined &&
-            priorClient.binding === this.clientBinding &&
-            typeof priorClient.value?.client_id === "string"
-            ? priorClient
+        // Only an explicitly forced restart may carry a registration forward, and
+        // only one this connector registered: an operator disconnect, an issuer
+        // mismatch, and every unforced reset discard it. Discovery is never
+        // copied: the SDK must select the authorization server again, then its
+        // issuer-aware clientInformation hook checks the issuer.
+        const reusableClient = preserveClient && !operatorDisconnected && this.clientBinding
+            ? await this.carriableClient(previous)
             : undefined;
         const now = Date.now();
         const inherited = await this.cleanupBacklog(previous, now);
@@ -1678,10 +1741,17 @@ export class KvOAuthProvider {
         await this.storage.set("oauth:generation", active);
         this.refreshCoordinator?.retire(previous);
         if (reusableClient && !this.signal?.aborted) {
-            // readValue opened the old physical key; writeValue seals the plaintext
+            // readValue opened the old physical key; the write seals the plaintext
             // under the new one. Copying ciphertext would fail its AAD check.
             this.captureGeneration(active);
-            await this.writeValue("oauth:client", reusableClient.value, (value) => JSON.stringify(value), reusableClient.issuer, undefined, this.clientBinding);
+            await this.storeInGeneration("oauth:client", active, () => JSON.stringify({
+                connectaOAuthVersion: STORED_VALUE_VERSION,
+                generation: active,
+                issuer: reusableClient.issuer,
+                binding: reusableClient.binding,
+                carried: true,
+                value: reusableClient.value,
+            }));
         }
         // Delete the generation just retired: its values, then the lineage it
         // published, which the new epoch has copied. Then retry the newest few
@@ -1713,6 +1783,55 @@ export class KvOAuthProvider {
         if (failure)
             throw failure.reason;
     }
+    /**
+     * The registration a forced restart may copy out of `previous`, or nothing.
+     *
+     * It must have been registered in that epoch for this authorization server
+     * (an issuer stamp) under this connector's exact configuration, redirect
+     * URI, and client metadata (the binding), and it is read through this
+     * owner's own storage, so another principal's partition is never a source.
+     * Three registrations are never carried:
+     *
+     * - A URL-based client (`clientMetadataUrl`). Nothing was registered, so
+     *   nothing is saved by copying it, and leaving it behind makes the SDK ask
+     *   the freshly discovered metadata whether the server still accepts one.
+     * - One whose `client_secret_expires_at` has passed (RFC 7591: zero means
+     *   never). The token endpoint would refuse it.
+     * - One a previous restart carried that has not since earned a grant. The
+     *   SDK builds a consent URL locally and sends nothing that could answer
+     *   `invalid_client`, and RFC 6749 section 4.1.2.1 forbids an authorization
+     *   server from redirecting a client it does not recognize, so a forgotten
+     *   registration never reaches the callback. Tokens in the epoch are the
+     *   only proof the server still knows the client. Without them the second
+     *   restart registers again, which bounds a forgotten registration to one
+     *   refused consent rather than a restart loop only a disconnect escapes.
+     */
+    async carriableClient(previous) {
+        const prior = await this.readValue("oauth:client", (raw) => {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        });
+        const clientId = prior?.value?.client_id;
+        const expiresAt = prior?.value?.client_secret_expires_at;
+        if (prior?.generation !== previous ||
+            prior.issuer === undefined ||
+            prior.binding === undefined ||
+            prior.binding !== this.clientBinding ||
+            typeof clientId !== "string" ||
+            clientId === this.clientMetadataUrl ||
+            (typeof expiresAt === "number" && expiresAt > 0 && expiresAt * 1000 <= Date.now())) {
+            return undefined;
+        }
+        const carriable = { ...prior, issuer: prior.issuer, binding: prior.binding };
+        if (!prior.carried)
+            return carriable;
+        const earnedGrant = (await this.storage.get(oauthValueStorageKey("oauth:tokens", previous))) !== null;
+        return earnedGrant ? carriable : undefined;
+    }
     async invalidateCredentials(scope) {
         const endsRefresh = scope === "all" || scope === "tokens";
         try {