@zackbart/connecta 0.28.0 → 0.29.0

package/dist/auth/downstream-revocation.js

@@ -0,0 +1,106 @@
+import { Effect } from "effect";
+import { ConnectorCallError } from "../errors.js";
+import { fromSignal, runEdge } from "../runtime/run.js";
+import { classifyHost } from "../url-safety.js";
+import { authenticateRemoteClient, remoteClientAuthMethod, } from "./downstream-client-metadata.js";
+import { discoveryIssuer } from "./oauth-v2-migration.js";
+/** Local removal succeeded; provider-side removal needs the operator's attention. */
+export class OAuthRevocationError extends ConnectorCallError {
+    constructor() {
+        super("oauth_revocation_failed", "Local OAuth authorization was removed, but provider revocation could not be confirmed. Revoke the grant in the provider's console.");
+    }
+}
+const REVOCATION_DEADLINE_MS = 20_000;
+/** Revoke only the issuer-bound snapshot removed by a successful reset CAS, once. */
+export async function revokeDownstreamGrant(body, send, configuredClient) {
+    const metadata = body.discovery?.authorizationServerMetadata;
+    const revocation = metadata;
+    const endpoint = revocation?.revocation_endpoint;
+    if (endpoint === undefined || !body.tokens)
+        return;
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), REVOCATION_DEADLINE_MS);
+    try {
+        if (typeof endpoint !== "string" ||
+            !body.issuer ||
+            discoveryIssuer(body.discovery) !== body.issuer ||
+            !body.client ||
+            (body.client.value.issuer !== undefined && body.client.value.issuer !== body.issuer))
+            throw new OAuthRevocationError();
+        const target = new URL(endpoint);
+        // An operator-trusted HTTP MCP origin does not authorize plaintext
+        // credential endpoints. Only the existing loopback development exception
+        // is eligible; the connector's destination guard still checks that scope.
+        if ((target.protocol !== "https:" &&
+            !(target.protocol === "http:" && classifyHost(target.hostname) === "loopback")) ||
+            target.username ||
+            target.password ||
+            target.hash)
+            throw new OAuthRevocationError();
+        const information = body.client.value;
+        const secret = configuredClient ? configuredClient.clientSecret : information.client_secret;
+        if (configuredClient &&
+            (body.issuer !== configuredClient.issuer || information.client_id !== configuredClient.clientId))
+            throw new OAuthRevocationError();
+        const advertisedMethods = revocation?.revocation_endpoint_auth_methods_supported;
+        if (advertisedMethods !== undefined &&
+            (!Array.isArray(advertisedMethods) || !advertisedMethods.every((method) => typeof method === "string")))
+            throw new OAuthRevocationError();
+        const methods = advertisedMethods;
+        const declared = configuredClient
+            ? remoteClientAuthMethod(configuredClient)
+            : "token_endpoint_auth_method" in information
+                ? information.token_endpoint_auth_method
+                : undefined;
+        const method = declared ??
+            (secret === undefined
+                ? "none"
+                : methods?.includes("client_secret_basic") || !methods
+                    ? "client_secret_basic"
+                    : "client_secret_post");
+        if ((method !== "none" && method !== "client_secret_basic" && method !== "client_secret_post") ||
+            (method === "none") !== (secret === undefined) ||
+            (methods && !methods.includes(method)))
+            throw new OAuthRevocationError();
+        const token = body.tokens.refresh_token ?? body.tokens.access_token;
+        if (typeof token !== "string" || !token)
+            throw new OAuthRevocationError();
+        const params = new URLSearchParams({
+            token,
+            token_type_hint: body.tokens.refresh_token ? "refresh_token" : "access_token",
+        });
+        const headers = new Headers({ "Content-Type": "application/x-www-form-urlencoded" });
+        authenticateRemoteClient({
+            issuer: body.issuer,
+            clientId: information.client_id,
+            ...(secret !== undefined ? { clientSecret: secret } : {}),
+            tokenEndpointAuthMethod: method,
+        }, headers, params);
+        await runEdge(Effect.raceAllFirst([
+            fromSignal(deadline.signal),
+            Effect.tryPromise({
+                try: async () => {
+                    const response = await send(target, {
+                        method: "POST",
+                        headers,
+                        body: params,
+                        redirect: "manual",
+                        signal: deadline.signal,
+                    });
+                    // RFC 7009's success is HTTP 200. Bodies and headers never explain a failure.
+                    void response.body?.cancel().catch(() => { });
+                    if (response.status !== 200)
+                        throw new OAuthRevocationError();
+                },
+                catch: () => new OAuthRevocationError(),
+            }),
+        ]));
+    }
+    catch {
+        // No provider text, credential-bearing URL, original exception, or cause survives.
+        throw new OAuthRevocationError();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/auth/oauth-token-response.js

@@ -0,0 +1,231 @@
+// The token endpoint's answers as downstream OAuth classifies them and the SDK
+// gets to parse them: a refresh's re-consent verdict, and every failure
+// rebuilt from its OAuth `error` code alone, so nothing else a token endpoint
+// wrote reaches the SDK's console output (#695).
+/** The `grant_type` of a token request, or undefined for any other request. */
+export function tokenGrantType(init) {
+    if ((init?.method ?? "GET").toUpperCase() !== "POST")
+        return undefined;
+    const body = init?.body;
+    if (body instanceof URLSearchParams)
+        return body.get("grant_type") ?? undefined;
+    if (typeof body !== "string")
+        return undefined;
+    return new URLSearchParams(body).get("grant_type") ?? undefined;
+}
+export function isRefreshTokenRequest(init) {
+    return tokenGrantType(init) === "refresh_token";
+}
+/** Grant exchanges and revocation forms carry credentials that must not be replayed. */
+export function isOAuthCredentialRequest(init) {
+    if (tokenGrantType(init) !== undefined)
+        return true;
+    if ((init?.method ?? "GET").toUpperCase() !== "POST")
+        return false;
+    const body = init?.body;
+    const form = body instanceof URLSearchParams ? body : typeof body === "string" ? new URLSearchParams(body) : undefined;
+    return form?.has("token") === true;
+}
+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;
+}
+const MAX_REFRESH_RESPONSE_BYTES = 65_536;
+class OversizedRefreshResponse extends Error {
+    constructor() {
+        super(`OAuth refresh response exceeded ${MAX_REFRESH_RESPONSE_BYTES} bytes.`);
+    }
+}
+async function readRefreshResponse(response, signal, clone = true) {
+    if (Number(response.headers.get("content-length")) > MAX_REFRESH_RESPONSE_BYTES) {
+        void response.body?.cancel().catch(() => { });
+        throw new OversizedRefreshResponse();
+    }
+    const reader = (clone ? response.clone() : response).body?.getReader();
+    if (!reader)
+        return undefined;
+    void reader.closed.catch(() => { });
+    const cancel = () => {
+        void reader.cancel().catch(() => { });
+        void response.body?.cancel().catch(() => { });
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    if (signal?.aborted)
+        cancel();
+    const decoder = new TextDecoder();
+    let size = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_REFRESH_RESPONSE_BYTES) {
+                // A cloned body's cancellation can await its sibling. Cancel both,
+                // without making the refusal wait for the provider to finish sending.
+                void reader.cancel().catch(() => { });
+                void response.body?.cancel().catch(() => { });
+                throw new OversizedRefreshResponse();
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        return JSON.parse(text + decoder.decode());
+    }
+    finally {
+        signal?.removeEventListener("abort", cancel);
+        reader.releaseLock();
+    }
+}
+function oauthErrorCode(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const code = body.error;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * The OAuth `error` codes a token-endpoint failure may carry to the SDK, each
+ * with the only description it will ever see beside it. RFC 6749's error
+ * codes, RFC 8707's, and RFC 9449's: the SDK decides its control flow on the
+ * code, so the code is all that has to survive.
+ */
+const SDK_TOKEN_ERROR_DESCRIPTIONS = {
+    invalid_request: "The authorization server refused the token request.",
+    invalid_client: "The authorization server refused the client.",
+    invalid_grant: "The authorization server refused the grant.",
+    unauthorized_client: "The authorization server refused the client for this grant.",
+    unsupported_grant_type: "The authorization server refused the grant type.",
+    invalid_scope: "The authorization server refused the requested scope.",
+    invalid_target: "The authorization server refused the requested resource.",
+    server_error: "The authorization server is temporarily unavailable.",
+    temporarily_unavailable: "The authorization server is temporarily unavailable.",
+    invalid_dpop_proof: "The authorization server refused the DPoP proof.",
+    use_dpop_nonce: "The authorization server requires a DPoP nonce.",
+};
+/**
+ * A token-endpoint failure as the SDK gets to parse it: the OAuth `error`
+ * code, a fixed description, the status, and `Retry-After`, and nothing else
+ * the server wrote. Since client 2.1.0 the SDK writes a failure's description
+ * to `console.warn` when it restarts or falls through to consent, and a body
+ * that is no OAuth error at all goes there raw. A token endpoint that echoes
+ * the form it refused would put the refresh token and client secret in the
+ * host's console, below any logger the deployment configured.
+ */
+function sdkTokenFailure(original, code, status = original.status) {
+    void original.body?.cancel().catch(() => { });
+    const retryAfter = original.headers.get("retry-after");
+    const known = code in SDK_TOKEN_ERROR_DESCRIPTIONS ? code : "invalid_request";
+    return Response.json({ error: known, error_description: SDK_TOKEN_ERROR_DESCRIPTIONS[known] }, {
+        status,
+        ...(retryAfter !== null ? { headers: { "retry-after": retryAfter } } : {}),
+    });
+}
+/**
+ * Rebuild a code exchange's answer (or any token request's but a refresh,
+ * which `refreshResponseOutcome` classifies) before the SDK parses it, unless
+ * it is a token response the SDK accepts. Whatever fails that check is a
+ * failure, and the SDK puts a failure's body in its error message whole — a
+ * 200 whose `error` is `null`, a number, or an object included. A code outside
+ * the registered set becomes `invalid_request`, and a body without a string
+ * code becomes `server_error`, the classes the SDK already gave them.
+ */
+export async function sdkSafeTokenResponse(response, accept) {
+    if (response.status >= 300 && response.status < 400) {
+        return sdkTokenFailure(response, "invalid_request", 400);
+    }
+    let parsed;
+    try {
+        parsed = await readRefreshResponse(response);
+    }
+    catch {
+        // Not JSON, or too large to be a token response: only the status is left.
+        return sdkTokenFailure(response, "server_error");
+    }
+    if (response.ok && sdkAcceptsOAuthTokens(parsed)) {
+        await accept?.(parsed);
+        return response;
+    }
+    return sdkTokenFailure(response, oauthErrorCode(parsed) ?? "server_error");
+}
+/**
+ * Classify the token endpoint's answer once with a bounded read, and keep the parsed
+ * tokens: a valid response has already consumed the rotating refresh token, so
+ * the coordinator stores it before releasing anyone, rather than trusting the
+ * SDK's later `saveTokens` to arrive on a request that may already be cancelled.
+ *
+ * A failure also decides what the SDK gets to parse. Pinned against
+ * `@modelcontextprotocol/client` 2.3.1, `src/client/auth.ts`: `authInternal()`
+ * swallows a refresh failure that is not an `OAuthError`, or is `server_error`,
+ * and falls through to `startAuthorization`. All dispatched failures reach the
+ * SDK as `invalid_grant`, except client refusals that also clear registration.
+ * Provider hooks preserve the re-consent verdict for passive calls. Rebuilding
+ * the response keeps provider text out of SDK output.
+ */
+export async function refreshResponseOutcome(response, signal) {
+    if (response.status >= 300 && response.status < 400) {
+        return {
+            failure: new Error("OAuth token endpoint redirected; authorization required."),
+            verdict: { kind: "dead" },
+            forSdk: sdkTokenFailure(response, "invalid_grant", 400),
+        };
+    }
+    if (!response.ok) {
+        let code;
+        try {
+            const body = await readRefreshResponse(response, signal, false);
+            if (body && typeof body === "object" && ("access_token" in body || "refresh_token" in body)) {
+                // A provider issuing tokens while reporting failure may have rotated.
+                throw new Error("OAuth refresh failure response may contain a rotation.");
+            }
+            code = oauthErrorCode(body);
+        }
+        catch (error) {
+            // Complete non-JSON failures still require re-consent. A lost body or
+            // evidence of issued tokens cannot prove a committed outcome.
+            if (!(error instanceof SyntaxError))
+                throw error;
+        }
+        const failure = new Error(`OAuth refresh failed with HTTP ${response.status}.`);
+        return {
+            failure,
+            verdict: { kind: "dead" },
+            forSdk: sdkTokenFailure(response, code === "invalid_client" || code === "unauthorized_client" ? code : "invalid_grant", 400),
+        };
+    }
+    // A successful HTTP status may have consumed the token even when its
+    // body cannot be read or parsed. The coordinator refuses the fingerprint.
+    const parsed = await readRefreshResponse(response, signal, false);
+    if (sdkAcceptsOAuthTokens(parsed)) {
+        // An `issuer` names the server a grant is bound to, and only the client
+        // stamps it — never the server answering, as the SDK's own parse agrees.
+        const { issuer: _ignored, ...tokens } = parsed;
+        return { tokens };
+    }
+    if (oauthErrorCode(parsed) !== undefined) {
+        return {
+            failure: new Error("OAuth refresh was refused by the authorization server."),
+            verdict: { kind: "dead" },
+            forSdk: sdkTokenFailure(response, "invalid_grant", 400),
+        };
+    }
+    throw new Error("OAuth refresh response did not match the token schema.");
+}

package/dist/auth/oauth-v2-migration.js

@@ -0,0 +1,116 @@
+import { oauthV2Keys } from "../storage/keys.js";
+function plainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The issuer a discovery record names, as the SDK derives it. */
+export function discoveryIssuer(state) {
+    if (!plainObject(state) || typeof state.authorizationServerUrl !== "string")
+        return undefined;
+    const metadata = state.authorizationServerMetadata;
+    const issuer = plainObject(metadata) && typeof metadata.issuer === "string" ? metadata.issuer : state.authorizationServerUrl;
+    return issuer === "" ? undefined : issuer;
+}
+/**
+ * Layout 2's grant in this namespace, or nothing when it holds none.
+ *
+ * Only issuer-stamped envelopes (`connectaOAuthVersion: 2`, written since
+ * v0.9.0) of the active generation are read; anything older, and any value
+ * the vault cannot open, is left behind, as layout 2's own flow entry would
+ * have retired it. A grant is kept only when every credential carries a
+ * stamp, the stamps agree, and they name the server the generation's
+ * discovery names, if any; otherwise it migrates empty and needs consent.
+ * One-shot consent state (pending URL, verifier, state) is not carried.
+ */
+export async function readV2Grant(storage, sealer) {
+    const keys = await listV2Keys(storage);
+    if (keys.length === 0)
+        return undefined;
+    const generation = (await storage.get(oauthV2Keys.generation)) ?? "legacy";
+    if (generation.startsWith("disconnected:"))
+        return { disconnected: true, body: {} };
+    if (!generation.startsWith("v2:") && generation !== "legacy") {
+        // An unfinished reset, or a numeric generation from before epochs.
+        return { disconnected: false, body: {} };
+    }
+    const epoch = generation === "legacy" ? null : generation;
+    const read = async (field) => {
+        const physicalKey = oauthV2Keys.value(field, epoch);
+        const raw = await storage.get(physicalKey);
+        if (raw === null)
+            return undefined;
+        let parsed = parse(raw);
+        if (plainObject(parsed) && parsed.connectaOAuthSealed === 1 && typeof parsed.sealed === "string") {
+            if (!sealer)
+                return undefined;
+            try {
+                parsed = parse(await sealer.open(physicalKey, parsed.sealed));
+            }
+            catch {
+                return undefined;
+            }
+        }
+        if (plainObject(parsed) &&
+            parsed.connectaOAuthVersion === 2 &&
+            parsed.generation === generation &&
+            (parsed.issuer === undefined || typeof parsed.issuer === "string") &&
+            (parsed.binding === undefined || typeof parsed.binding === "string")) {
+            return {
+                value: parsed.value,
+                ...(parsed.issuer !== undefined ? { issuer: parsed.issuer } : {}),
+                ...(parsed.binding !== undefined ? { binding: parsed.binding } : {}),
+                ...(parsed.carried === true ? { carried: true } : {}),
+            };
+        }
+        // Layout 2 wrote discovery bare under the legacy generation.
+        return field === oauthV2Keys.field.discovery && epoch === null && discoveryIssuer(parsed)
+            ? { value: parsed }
+            : undefined;
+    };
+    const [client, tokens, discovery] = await Promise.all([
+        read(oauthV2Keys.field.client),
+        read(oauthV2Keys.field.tokens),
+        read(oauthV2Keys.field.discovery),
+    ]);
+    const named = discovery ? discoveryIssuer(discovery.value) : undefined;
+    const credentials = [client, tokens].filter((value) => value !== undefined);
+    const issuer = credentials[0]?.issuer ?? named;
+    const consistent = credentials.every((value) => value.issuer !== undefined && value.issuer === issuer && plainObject(value.value)) &&
+        (named === undefined || named === issuer);
+    if (!consistent || issuer === undefined)
+        return { disconnected: false, body: {} };
+    return {
+        disconnected: false,
+        body: {
+            issuer,
+            ...(client
+                ? {
+                    client: {
+                        value: client.value,
+                        ...(client.binding !== undefined ? { binding: client.binding } : {}),
+                        ...(client.carried ? { carried: true } : {}),
+                    },
+                }
+                : {}),
+            ...(tokens ? { tokens: tokens.value } : {}),
+            ...(discovery && named !== undefined ? { discovery: discovery.value } : {}),
+        },
+    };
+}
+/** Only historical families are removed, never grants, flows, or leases. */
+async function listV2Keys(storage) {
+    return (await storage.list(oauthV2Keys.scan)).filter((key) => oauthV2Keys.family.prefixes.some((prefix) => key.startsWith(prefix)));
+}
+/** Return true only when every historical key was deleted. */
+export async function deleteV2Keys(storage) {
+    const keys = await listV2Keys(storage);
+    const results = await Promise.allSettled(keys.map((key) => storage.delete(key)));
+    return results.every((result) => result.status === "fulfilled");
+}