@zackbart/connecta 0.37.1 → 0.39.0

package/dist/auth/downstream-oauth/consent.js

@@ -0,0 +1,519 @@
+// Consent flow records for KvOAuthProvider: the consent's state and verifier,
+// its flow record and binding, the authorization URL it hands out, and the
+// callback's single code exchange.
+import { bytesToHex, sha256Hex } from "../../bytes.js";
+import { byteReadResponse } from "../../byte-read-response.js";
+import { ConnectorCallError } from "../../errors.js";
+import { keepErrorName } from "../../redaction-identity.js";
+import { runEdge } from "../../runtime/run.js";
+import { OAUTH_FLOW_TTL_SECONDS, oauthFlowKeys, oauthRefreshSpentKeys } from "../../storage/keys.js";
+import { authCall, authCatch, authFlow, authInvoke, authMethod, authProgram, authStorage, authThen, authValue, registerAuth, } from "../native.js";
+import { discoveryIssuer } from "../oauth-grant.js";
+import { GRANT, epochOf, parsed, plainObject } from "./grant-store.js";
+import { aborted } from "./refresh-coordinator.js";
+import { storedRefreshSpent } from "./refresh-records.js";
+/** @internal Keep the SDK's cloned body reads inside the code exchange's request. */
+export function codeExchangeResponse(response, signal) {
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    void reader.closed.catch(() => { });
+    let closed = false;
+    let abort;
+    const release = () => {
+        closed = true;
+        signal.removeEventListener("abort", abort);
+        reader.releaseLock();
+    };
+    const body = new ReadableStream({
+        start(controller) {
+            abort = () => {
+                if (closed)
+                    return;
+                void reader.cancel().catch(() => { });
+                release();
+                controller.error(signal.reason);
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            if (signal.aborted)
+                abort();
+        },
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (closed)
+                    return;
+                if (next.done) {
+                    release();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(next.value);
+            }
+            catch (error) {
+                if (!closed) {
+                    release();
+                    controller.error(error);
+                }
+            }
+        },
+        cancel() {
+            if (!closed) {
+                void reader.cancel().catch(() => { });
+                release();
+            }
+        },
+    });
+    return byteReadResponse(new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers }));
+}
+/**
+ * A callback whose consent another callback already claimed: fixed text, and
+ * nothing was sent. Its own class so the callback route can answer it as the
+ * already-used link it is, not as an exchange the provider refused.
+ */
+export class OAuthCallbackClaimedError extends ConnectorCallError {
+    constructor(connectorId) {
+        super("connector_call_failed", `Connector "${connectorId}" authorization callback was already used by another request; nothing was exchanged.`);
+        this.name = "OAuthCallbackClaimedError";
+    }
+}
+keepErrorName(OAuthCallbackClaimedError, "OAuthCallbackClaimedError");
+/** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
+export function randomState() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+}
+/** Lowercase hex SHA-256 of a consent's `state`: the name of its flow record. */
+export async function oauthStateDigest(state) {
+    return sha256Hex(state);
+}
+const FLOW_VERSION = 1;
+/**
+ * How long a pending authorization URL may be handed out again instead of
+ * starting a fresh flow. The authorization server's half of it expires: a
+ * pushed request URI lives seconds to minutes (RFC 9126), and login
+ * transactions are commonly held for minutes. Past this age a reissued URL
+ * more likely lands on an expired session than on consent, and a fresh start
+ * costs one authorization request, not a registration. It sits inside the
+ * flow record's fifteen minutes.
+ */
+const PENDING_AUTHORIZATION_MAX_AGE_MS = 10 * 60 * 1000;
+export function discoveryBinding(state) {
+    return runEdge(authProgram(discoveryBindingNative, [state]));
+}
+const discoveryBindingNative = /* @__PURE__ */ registerAuth(discoveryBinding, function (state) {
+    return authFlow(function* () {
+        return state
+            ? {
+                issuer: discoveryIssuer(state),
+                tokenEndpoint: state.authorizationServerMetadata?.token_endpoint,
+                ...(state.authorizationServerMetadata?.authorization_response_iss_parameter_supported === true
+                    ? { issRequired: true }
+                    : {}),
+                discovery: (yield authCall(oauthStateDigest, [JSON.stringify(state)])),
+            }
+            : {};
+    });
+});
+/** KvOAuthProvider's consent and code exchange methods; `authMethods` installs them. */
+export const consentMethods = {
+    encodeFlow: function (key, flow) {
+        return authFlow(function* () {
+            const { verifier, ...rest } = flow;
+            const stored = { connectaOAuthFlow: FLOW_VERSION, ...rest };
+            if (verifier !== undefined) {
+                if (this.sealer) {
+                    stored.verifier = (yield authInvoke(this, "wait", [
+                        authMethod(() => {
+                            return authInvoke(this.sealer, "seal", [this.flowLabel(key, flow.epoch), verifier]);
+                        }),
+                    ]));
+                    stored.sealed = true;
+                }
+                else {
+                    stored.verifier = verifier;
+                }
+            }
+            return JSON.stringify(stored);
+        }.bind(this));
+    },
+    openFlow: function (key, raw, withVerifier) {
+        return authFlow(function* () {
+            const value = parsed(raw);
+            if (!plainObject(value) ||
+                value.connectaOAuthFlow !== FLOW_VERSION ||
+                typeof value.epoch !== "string" ||
+                typeof value.at !== "number" ||
+                (value.url !== undefined && typeof value.url !== "string") ||
+                (value.verifier !== undefined && typeof value.verifier !== "string")) {
+                return undefined;
+            }
+            const flow = {
+                epoch: value.epoch,
+                at: value.at,
+                ...(plainObject(value.binding) ? { binding: value.binding } : {}),
+                ...(typeof value.url === "string" ? { url: value.url } : {}),
+                ...(value.consumed === true ? { consumed: true } : {}),
+            };
+            if (!withVerifier || typeof value.verifier !== "string")
+                return flow;
+            if (value.sealed !== true)
+                return { ...flow, verifier: value.verifier };
+            try {
+                if (!this.sealer)
+                    return undefined;
+                return {
+                    ...flow,
+                    verifier: (yield authInvoke(this, "wait", [
+                        authMethod(() => {
+                            return authInvoke(this.sealer, "open", [
+                                this.flowLabel(key, flow.epoch),
+                                value.verifier,
+                            ]);
+                        }),
+                    ])),
+                };
+            }
+            catch {
+                if (this.signal?.aborted)
+                    throw aborted(this.signal);
+                this.sealer?.warn(`[connecta] connector "${this.connectorId}" has a sealed OAuth consent ` +
+                    "the configured vault cannot open; its callback is refused.");
+                return undefined;
+            }
+        }.bind(this));
+    },
+    latestConsent: function () {
+        return authFlow(function* () {
+            const grant = (yield authInvoke(this, "boundGrant", []));
+            if (grant.flow === undefined)
+                return undefined;
+            const key = oauthFlowKeys.flow(grant.flow);
+            const raw = (yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "get", [key]);
+                }),
+            ]));
+            const flow = raw === null ? undefined : (yield authInvoke(this, "openFlow", [key, raw, false]));
+            return flow && !flow.consumed && flow.epoch === grant.epoch && flow.url !== undefined
+                ? { ...flow, url: flow.url }
+                : undefined;
+        }.bind(this));
+    },
+    verifyCallbackState: function (state) {
+        return authFlow(function* () {
+            if (this.callback?.key ===
+                oauthFlowKeys.flow((yield authInvoke(this, "wait", [
+                    authMethod(() => {
+                        return authCall(oauthStateDigest, [state]);
+                    }),
+                ]))))
+                return true;
+            return (yield authInvoke(this, "verifyState", [state]));
+        }.bind(this));
+    },
+    redirectToAuthorization: function (authorizationUrl) {
+        return authFlow(function* () {
+            if (this.signal?.aborted)
+                return;
+            if (!this.allowAuthorization)
+                throw this.authorizationRefused();
+            for (const [name, value] of this.clientOptions?.authorizationParams ?? []) {
+                authorizationUrl.searchParams.set(name, value);
+            }
+            this.assertCredentialFree(authorizationUrl.toString(), (yield authInvoke(this, "boundGrant", [])).body, true);
+            const state = this.consent.state ?? authorizationUrl.searchParams.get("state");
+            if (!state)
+                throw new Error(`OAuth consent for "${this.connectorId}" carries no state`);
+            const client = this.clientOptions?.client;
+            if (client && !(yield authInvoke(this, "boundGrant", [])).body.client) {
+                (yield authInvoke(this, "saveClientInformation", [
+                    { client_id: client.clientId },
+                    { issuer: client.issuer },
+                ]));
+            }
+            const configured = this.configuredAuthorizationBinding();
+            if (configured?.issuer !== undefined) {
+                const issuer = configured.issuer;
+                // Static adapters do not save discovery or client configuration. Publish
+                // their server identity before consent so a changed endpoint fences the
+                // old grant before any code exchange can leave.
+                (yield authInvoke(this, "updateGrant", [
+                    (grant) => (grant.body.issuer === issuer ? undefined : this.withIssuer(grant, { issuer })),
+                ]));
+            }
+            const epoch = (yield authInvoke(this, "flowEpoch", []));
+            this.epoch = epoch;
+            const digest = (yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authCall(oauthStateDigest, [state]);
+                }),
+            ]));
+            const key = oauthFlowKeys.flow(digest);
+            const url = authorizationUrl.toString();
+            const { verifier } = this.consent;
+            const grant = (yield authInvoke(this, "boundGrant", []));
+            this.assertCredentialFree(url, grant.body, true);
+            const binding = this.configuredAuthorizationBinding() ?? {
+                ...(yield authInvoke(this, "wait", [
+                    authMethod(() => {
+                        return authCall(discoveryBinding, [this.consentDiscovery ?? grant.body.discovery]);
+                    }),
+                ])),
+                issuer: discoveryIssuer(this.consentDiscovery) ?? grant.body.issuer,
+                clientId: authorizationUrl.searchParams.get("client_id") ?? grant.body.client?.value.client_id,
+            };
+            const record = (yield authInvoke(this, "encodeFlow", [
+                key,
+                {
+                    epoch,
+                    at: Date.now(),
+                    binding,
+                    url,
+                    ...(verifier !== undefined ? { verifier } : {}),
+                },
+            ]));
+            if (this.signal?.aborted)
+                return;
+            if (!(yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "compareAndSet", [
+                        key,
+                        null,
+                        record,
+                        { ttlSeconds: OAUTH_FLOW_TTL_SECONDS },
+                    ]);
+                }),
+            ]))) {
+                throw new Error(`OAuth consent for "${this.connectorId}" reused a state`);
+            }
+            let published = false;
+            try {
+                published = (yield authInvoke(this, "updateGrant", [
+                    (grant) => ({ ...grant, flow: digest }),
+                    { epoch },
+                ]));
+            }
+            finally {
+                if (!published)
+                    (yield authCatch(authInvoke(this, "wait", [
+                        authMethod(() => {
+                            return authStorage(this.storage, "compareAndSet", [key, record, null]);
+                        }),
+                    ]), () => { }));
+            }
+            if (published)
+                this.published = { epoch, url };
+        }.bind(this));
+    },
+    consentUrl: function (signal) {
+        signal = signal === undefined ? this.signal : signal;
+        return authFlow(function* () {
+            const published = this.published;
+            if (!published)
+                return undefined;
+            if (epochOf((yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "get", [GRANT]);
+                }),
+                signal,
+            ]))) !== published.epoch)
+                throw this.flowSuperseded();
+            this.assertCredentialFree(published.url, (yield authInvoke(this, "boundGrant", [signal])).body, true);
+            return published.url;
+        }.bind(this));
+    },
+    pendingAuthorizationUrl: function () {
+        return authFlow(function* () {
+            const url = (yield authInvoke(this, "latestConsent", []))?.url;
+            this.assertCredentialFree(url, (yield authInvoke(this, "boundGrant", [])).body, true);
+            return url;
+        }.bind(this));
+    },
+    reusablePendingAuthorizationUrl: function () {
+        return authFlow(function* () {
+            const consent = (yield authInvoke(this, "latestConsent", []));
+            if (!consent || Math.abs(Date.now() - consent.at) >= PENDING_AUTHORIZATION_MAX_AGE_MS) {
+                return undefined;
+            }
+            this.assertCredentialFree(consent.url, (yield authInvoke(this, "boundGrant", [])).body, true);
+            let clientId;
+            try {
+                clientId = new URL(consent.url).searchParams.get("client_id");
+            }
+            catch {
+                return undefined;
+            }
+            const client = (yield authInvoke(this, "clientInformation", []));
+            return clientId !== null && client?.client_id === clientId ? consent.url : undefined;
+        }.bind(this));
+    },
+    verifyState: function (candidate) {
+        return authFlow(function* () {
+            this.callback = undefined;
+            if (candidate === null)
+                return false;
+            const key = oauthFlowKeys.flow((yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authCall(oauthStateDigest, [candidate]);
+                }),
+            ])));
+            const raw = (yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "get", [key]);
+                }),
+            ]));
+            const flow = raw === null ? undefined : (yield authInvoke(this, "openFlow", [key, raw, true]));
+            if (raw === null || !flow || flow.consumed)
+                return false;
+            this.callback = { key, raw, flow, claimed: false };
+            this.epoch = flow.epoch;
+            return true;
+        }.bind(this));
+    },
+    claimCodeExchange: function () {
+        return authFlow(function* () {
+            if (this.exchangeRefusal)
+                return this.exchangeRefusal.clone();
+            (yield authInvoke(this, "claimConsent", []));
+            return undefined;
+        }.bind(this));
+    },
+    consumeAuthError: function () {
+        return authFlow(function* () {
+            const { grant } = (yield authInvoke(this, "readGrant", []));
+            if (!this.callback || grant.epoch !== this.callback.flow.epoch)
+                throw this.flowSuperseded();
+            (yield authInvoke(this, "checkFlowBinding", [grant]));
+            (yield authInvoke(this, "claimConsent", []));
+            this.callback = undefined;
+        }.bind(this));
+    },
+    claimConsent: function () {
+        return authFlow(function* () {
+            const callback = this.callback;
+            if (!callback)
+                throw this.flowSuperseded();
+            if (callback.claimed)
+                throw new OAuthCallbackClaimedError(this.connectorId);
+            callback.claimed = true;
+            const { epoch, at } = callback.flow;
+            const claimed = JSON.stringify({
+                connectaOAuthFlow: FLOW_VERSION,
+                epoch,
+                at,
+                consumed: true,
+            });
+            const remaining = Math.ceil((at + OAUTH_FLOW_TTL_SECONDS * 1000 - Date.now()) / 1000);
+            const ttlSeconds = Math.min(OAUTH_FLOW_TTL_SECONDS, Math.max(1, remaining));
+            if ((yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "compareAndSet", [
+                        callback.key,
+                        callback.raw,
+                        claimed,
+                        { ttlSeconds },
+                    ]);
+                }),
+            ]))) {
+                return;
+            }
+            if (epochOf((yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "get", [GRANT]);
+                }),
+            ]))) !== epoch)
+                throw this.flowSuperseded();
+            throw new OAuthCallbackClaimedError(this.connectorId);
+        }.bind(this));
+    },
+    dispatchCodeExchange: function (send, endpoint) {
+        return authFlow(function* () {
+            const epoch = this.epoch;
+            if (!this.codeExchange || epoch === undefined)
+                throw this.flowSuperseded();
+            const raw = (yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "get", [GRANT]);
+                }),
+            ]));
+            const grant = (yield authInvoke(this, "openGrant", [raw]));
+            if (grant.epoch !== epoch)
+                throw this.flowSuperseded();
+            (yield authInvoke(this, "checkFlowBinding", [grant]));
+            if (endpoint !== undefined && this.callback?.flow.binding?.tokenEndpoint !== String(endpoint)) {
+                throw this.flowSuperseded();
+            }
+            // Opening ciphertext may yield. Re-read the exact record after opening,
+            // then check and send in the same reaction, without another await.
+            return (yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authThen(authStorage(this.storage, "get", [GRANT]), authMethod((current) => {
+                        return authFlow(function* () {
+                            if (this.signal?.aborted)
+                                throw aborted(this.signal);
+                            if (current !== raw)
+                                throw this.flowSuperseded();
+                            const sent = send();
+                            sent.catch(() => { });
+                            return (yield authValue(() => sent));
+                        }.bind(this));
+                    }));
+                }),
+            ]));
+        }.bind(this));
+    },
+    recordCodeExchangeTokens: function (tokens) {
+        return authFlow(function* () {
+            this.exchangeConsent = undefined;
+            if (tokens.refresh_token === undefined)
+                return;
+            try {
+                const digest = (yield authInvoke(this, "wait", [
+                    authMethod(() => {
+                        return authCall(oauthStateDigest, [tokens.refresh_token]);
+                    }),
+                ]));
+                const resolution = (yield authInvoke(this, "wait", [
+                    authMethod(() => {
+                        return authStorage(this.storage, "get", [oauthRefreshSpentKeys.spent(digest)]);
+                    }),
+                ]));
+                const spent = storedRefreshSpent(resolution);
+                // Observing the exact resolved storage write before consent completion
+                // proves their order without comparing isolate clocks. A consent that
+                // saw outstanding/ambiguous cannot become eligible on a delayed save.
+                if (spent?.state === "resolved")
+                    this.exchangeConsent = { digest, resolution: resolution };
+            }
+            catch {
+                if (this.signal?.aborted)
+                    throw aborted(this.signal);
+                throw this.credentialWriteError();
+            }
+        }.bind(this));
+    },
+    sweepConsents: function () {
+        return authFlow(function* () {
+            try {
+                const consents = [];
+                for (const key of (yield authStorage(this.storage, "list", [oauthFlowKeys.prefix]))) {
+                    const raw = (yield authStorage(this.storage, "get", [key]));
+                    if (raw !== null)
+                        consents.push([key, raw]);
+                }
+                const live = epochOf((yield authStorage(this.storage, "get", [GRANT])));
+                for (const [key, raw] of consents) {
+                    const flow = parsed(raw);
+                    if (plainObject(flow) && flow.epoch === live)
+                        continue;
+                    (yield authStorage(this.storage, "compareAndSet", [key, raw, null]));
+                }
+            }
+            catch {
+                // Hygiene only: the epoch, not this, fences a stale consent.
+            }
+        }.bind(this));
+    },
+};