@zackbart/connecta 0.38.0 → 0.40.0

package/dist/auth/downstream-oauth/grant-store.js

@@ -0,0 +1,439 @@
+import { Effect } from "effect";
+import { runEdge } from "../../runtime/run.js";
+import { oauthGrantKeys, retiredOAuthKeys } from "../../storage/keys.js";
+import { revokeDownstreamGrant } from "../downstream-revocation.js";
+import { authAwait, authCall, authCatch, authFlow, authInvoke, authMethod, authStorage, authValue } from "../native.js";
+import { discoveryIssuer, tokenExpiry } from "../oauth-grant.js";
+import { aborted } from "./refresh-coordinator.js";
+import { discoveryBinding } from "./consent.js";
+export const GRANT = oauthGrantKeys.grant;
+/** The epoch of an owner with no grant record yet. */
+const INITIAL_EPOCH = "initial";
+/** The epoch of a record that does not parse: readers see no grant in it. */
+const UNREADABLE_EPOCH = "unreadable";
+export const ACTIVE_EPOCH_PREFIX = "v3:";
+const DISCONNECTED_EPOCH_PREFIX = "disconnected:";
+const GRANT_VERSION = 3;
+/** Attempts at one grant write while other writers keep winning. */
+export const MAX_GRANT_WRITES = 32;
+export function plainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function parsed(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function storedGrant(raw) {
+    const value = parsed(raw);
+    return plainObject(value) &&
+        value.connectaOAuth === GRANT_VERSION &&
+        typeof value.epoch === "string" &&
+        (value.flow === undefined || typeof value.flow === "string") &&
+        (value.sealed === undefined || typeof value.sealed === "string")
+        ? value
+        : undefined;
+}
+/** The epoch a raw grant record names, without opening its body. */
+export function epochOf(raw) {
+    if (raw === null)
+        return INITIAL_EPOCH;
+    return storedGrant(raw)?.epoch ?? UNREADABLE_EPOCH;
+}
+/** Nothing here trusts stored bytes: keep only what has the expected shape. */
+function grantBody(value) {
+    if (!plainObject(value))
+        return {};
+    const { issuer, client, tokens, expiresAt, discovery, refreshConsent } = value;
+    const hasTokens = plainObject(tokens) && typeof tokens.access_token === "string";
+    return {
+        ...(typeof issuer === "string" ? { issuer } : {}),
+        ...(plainObject(client) && plainObject(client.value) && typeof client.value.client_id === "string"
+            ? {
+                client: {
+                    value: client.value,
+                    ...(typeof client.binding === "string" ? { binding: client.binding } : {}),
+                    ...(client.carried === true ? { carried: true } : {}),
+                    ...(client.registrationPath === "cimd" ||
+                        client.registrationPath === "dcr" ||
+                        client.registrationPath === "static"
+                        ? { registrationPath: client.registrationPath }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(hasTokens ? { tokens: tokens } : {}),
+        // Meaningful only beside the tokens it describes.
+        ...(hasTokens && typeof expiresAt === "number" && Number.isFinite(expiresAt) ? { expiresAt } : {}),
+        ...(discoveryIssuer(discovery) !== undefined ? { discovery: discovery } : {}),
+        ...(plainObject(refreshConsent) &&
+            typeof refreshConsent.digest === "string" &&
+            typeof refreshConsent.resolution === "string"
+            ? { refreshConsent: { digest: refreshConsent.digest, resolution: refreshConsent.resolution } }
+            : {}),
+    };
+}
+/** What an invalidation compares: the value exactly as this flow saw it. */
+export function fingerprint(value) {
+    return value === undefined ? undefined : JSON.stringify(value);
+}
+export function isDisconnectedEpoch(epoch) {
+    return epoch.startsWith(DISCONNECTED_EPOCH_PREFIX);
+}
+/** KvOAuthProvider's grant and epoch methods; `authMethods` installs them. */
+export const grantStoreMethods = {
+    wait: function (work, signal) {
+        signal = signal === undefined ? this.signal : signal;
+        return authFlow(function* () {
+            if (signal?.aborted)
+                throw aborted(signal);
+            const value = signal
+                ? (yield authAwait(authCall(work, []), { signal }.signal))
+                : (yield authCall(work, []));
+            if (signal?.aborted)
+                throw aborted(signal);
+            return value;
+        });
+    },
+    encodeGrant: function (grant, signal) {
+        signal = signal === undefined ? this.signal : signal;
+        return authFlow(function* () {
+            this.assertCredentialFree({ issuer: grant.body.issuer, discovery: grant.body.discovery }, grant.body);
+            const stored = {
+                connectaOAuth: GRANT_VERSION,
+                epoch: grant.epoch,
+                ...(grant.flow !== undefined ? { flow: grant.flow } : {}),
+            };
+            if (Object.keys(grant.body).length > 0) {
+                if (this.sealer) {
+                    stored.sealed = (yield authInvoke(this, "wait", [
+                        authMethod(() => {
+                            return authInvoke(this.sealer, "seal", [
+                                this.grantLabel(grant.epoch),
+                                JSON.stringify(grant.body),
+                            ]);
+                        }),
+                        signal,
+                    ]));
+                }
+                else {
+                    stored.body = grant.body;
+                }
+            }
+            return JSON.stringify(stored);
+        }.bind(this));
+    },
+    openGrant: function (raw, signal) {
+        signal = signal === undefined ? this.signal : signal;
+        return authFlow(function* () {
+            const stored = raw === null ? undefined : storedGrant(raw);
+            if (!stored) {
+                this.observed = undefined;
+                return { epoch: raw === null ? INITIAL_EPOCH : UNREADABLE_EPOCH, body: {} };
+            }
+            let body = stored.body;
+            if (stored.sealed !== undefined) {
+                body = undefined;
+                try {
+                    if (this.sealer)
+                        body = parsed((yield authInvoke(this, "wait", [
+                            authMethod(() => {
+                                return authInvoke(this.sealer, "open", [
+                                    this.grantLabel(stored.epoch),
+                                    stored.sealed,
+                                ]);
+                            }),
+                            signal,
+                        ])));
+                }
+                catch {
+                    if (signal?.aborted)
+                        throw aborted(signal);
+                    this.sealer?.warn(`[connecta] connector "${this.connectorId}" has a sealed OAuth grant ` +
+                        "the configured vault cannot open; treating it as absent, so the " +
+                        "connector needs authorization again. A changed vault key or " +
+                        "tampered storage causes this.");
+                }
+            }
+            const grant = {
+                epoch: stored.epoch,
+                ...(stored.flow !== undefined ? { flow: stored.flow } : {}),
+                body: grantBody(body),
+            };
+            this.observe(grant);
+            return grant;
+        }.bind(this));
+    },
+    storedAuthorization: function (issuer) {
+        return authFlow(function* () {
+            const raw = (yield authStorage(this.storage, "get", [GRANT]));
+            const grant = (yield authInvoke(this, "openGrant", [raw]));
+            if (isDisconnectedEpoch(grant.epoch))
+                return false;
+            const body = grant.body;
+            const configured = issuer ?? this.clientOptions?.client?.issuer;
+            const discovered = body.discovery;
+            if (!configured &&
+                (!discovered || discovered.authorizationServerMetadata?.issuer !== discovered.authorizationServerUrl))
+                return false;
+            const expected = configured ?? discoveryIssuer(discovered);
+            return Boolean(expected && body.issuer === expected && body.tokens?.access_token);
+        }.bind(this)).pipe(Effect.catch(() => Effect.succeed(false)));
+    },
+    peekGrant: function () {
+        return authFlow(function* () {
+            const raw = (yield authInvoke(this, "wait", [
+                authMethod(() => authStorage(this.storage, "get", [GRANT])),
+            ]));
+            const grant = (yield authInvoke(this, "openGrant", [raw]));
+            return { epoch: grant.epoch, ...(grant.body.tokens ? { tokens: grant.body.tokens } : {}) };
+        }.bind(this));
+    },
+    readGrant: function (signal) {
+        signal = signal === undefined ? this.signal : signal;
+        return authFlow(function* () {
+            let raw = (yield authInvoke(this, "wait", [
+                authMethod(() => {
+                    return authStorage(this.storage, "get", [GRANT]);
+                }),
+                signal,
+            ]));
+            if (raw === null) {
+                // Inspect names only: retired credentials are never opened or copied.
+                const keys = (yield authInvoke(this, "wait", [
+                    authMethod(() => authStorage(this.storage, "list", [retiredOAuthKeys.scan])),
+                    signal,
+                ]));
+                if (keys.some((key) => retiredOAuthKeys.prefixes.some((prefix) => key.startsWith(prefix))))
+                    (this.sealer ?? console).warn(`[connecta] connector "${this.connectorId}" has an unsupported pre-layout-3 OAuth grant; ` +
+                        "treating it as absent. Connect again to authorize, or restore a backup and run the " +
+                        "OAuth migration on Connecta 0.37.1 before upgrading.");
+            }
+            const grant = (yield authInvoke(this, "openGrant", [raw, signal]));
+            if (raw !== null && this.sealer && storedGrant(raw)?.body !== undefined) {
+                const sealed = (yield authInvoke(this, "encodeGrant", [grant, signal]));
+                if ((yield authInvoke(this, "wait", [
+                    authMethod(() => {
+                        return authCatch(authStorage(this.storage, "compareAndSet", [GRANT, raw, sealed]), () => false);
+                    }),
+                    signal,
+                ])))
+                    raw = sealed;
+            }
+            return { raw, grant };
+        }.bind(this));
+    },
+    boundGrant: function (signal) {
+        signal = signal === undefined ? this.signal : signal;
+        return authFlow(function* () {
+            const { grant } = (yield authInvoke(this, "readGrant", [signal]));
+            if (this.bound && grant.epoch !== this.epoch)
+                throw this.flowSuperseded();
+            return grant;
+        }.bind(this));
+    },
+    activeGrant: function () {
+        return authInvoke(this, "boundGrant", []);
+    },
+    updateGrant: function (change, options = {}) {
+        return authFlow(function* () {
+            const signal = options.signal ?? (options.commit ? null : this.signal);
+            for (let attempt = 0; attempt < MAX_GRANT_WRITES; attempt++) {
+                if (!options.commit && this.signal?.aborted)
+                    return false;
+                const { raw, grant } = (yield authInvoke(this, "readGrant", [signal]));
+                const epoch = options.epoch ?? (this.epoch ??= grant.epoch);
+                if (grant.epoch !== epoch) {
+                    if (options.quiet || !this.bound)
+                        return false;
+                    throw this.flowSuperseded();
+                }
+                // A disconnect's epoch holds nothing until an explicit start replaces it.
+                if (isDisconnectedEpoch(epoch))
+                    return false;
+                const next = change(grant);
+                if (next === undefined)
+                    return true;
+                const encoded = (yield authInvoke(this, "encodeGrant", [next, signal]));
+                if (!options.commit && this.signal?.aborted)
+                    return false;
+                let written;
+                try {
+                    written = (yield authInvoke(this, "wait", [
+                        authMethod(() => {
+                            return authStorage(this.storage, "compareAndSet", [GRANT, raw, encoded], options.beforeWrite && (() => options.beforeWrite?.()));
+                        }),
+                        signal,
+                    ]));
+                }
+                catch {
+                    if (signal?.aborted)
+                        throw aborted(signal);
+                    // A store's own error can quote the value it refused.
+                    throw this.credentialWriteError();
+                }
+                if (written) {
+                    if (next.epoch !== grant.epoch)
+                        this.epoch = next.epoch;
+                    this.observe(next);
+                    return true;
+                }
+            }
+            throw this.credentialWriteError();
+        }.bind(this));
+    },
+    writeCredential: function (field, value, issuer, refreshConsent) {
+        return authFlow(function* () {
+            // The SDK saves a code exchange's tokens once its answer is read;
+            // their lifetime started when its request was sent.
+            const issuedAt = (field === "tokens" ? this.tokenRequestSent : undefined) ?? Date.now();
+            (yield authInvoke(this, "updateGrant", [
+                (grant) => {
+                    const body = issuer !== undefined && grant.body.issuer !== issuer ? { issuer } : { ...grant.body };
+                    if (field === "client")
+                        body.client = value;
+                    else {
+                        const tokens = value;
+                        // The same access token saved again keeps the expiry it was issued with.
+                        const expiresAt = body.tokens?.access_token === tokens.access_token && body.expiresAt !== undefined
+                            ? body.expiresAt
+                            : tokenExpiry(tokens, issuedAt);
+                        body.tokens = tokens;
+                        delete body.expiresAt;
+                        if (expiresAt !== undefined)
+                            body.expiresAt = expiresAt;
+                        delete body.refreshConsent;
+                        if (refreshConsent)
+                            body.refreshConsent = refreshConsent;
+                    }
+                    return this.withIssuer(grant, body);
+                },
+            ]));
+            if (field === "tokens")
+                this.tokenRequestSent = undefined;
+            // A flow may invalidate what it wrote itself.
+            this.seen[field] = fingerprint(field === "client" ? value.value : value);
+        }.bind(this));
+    },
+    bindingForGrant: function (grant) {
+        return authFlow(function* () {
+            const configured = this.configuredAuthorizationBinding();
+            return configured
+                ? { ...configured, issuer: grant.body.issuer }
+                : {
+                    ...(yield authInvoke(this, "wait", [
+                        authMethod(() => {
+                            return authCall(discoveryBinding, [grant.body.discovery]);
+                        }),
+                    ])),
+                    issuer: grant.body.issuer,
+                    clientId: grant.body.client?.value.client_id,
+                };
+        }.bind(this));
+    },
+    checkFlowBinding: function (grant) {
+        return authFlow(function* () {
+            const binding = this.callback?.flow.binding;
+            if (!binding ||
+                fingerprint(binding) !== fingerprint((yield authInvoke(this, "bindingForGrant", [grant])))) {
+                throw this.flowSuperseded();
+            }
+        }.bind(this));
+    },
+    liveEpoch: function () {
+        return authFlow(function* () {
+            return (yield authInvoke(this, "readGrant", [])).grant.epoch;
+        }.bind(this));
+    },
+    operatorDisconnected: function () {
+        return authFlow(function* () {
+            return isDisconnectedEpoch((yield authInvoke(this, "liveEpoch", [])));
+        }.bind(this));
+    },
+    beginFlow: function (expectedEpoch) {
+        return authFlow(function* () {
+            const epoch = (yield authInvoke(this, "liveEpoch", []));
+            if (expectedEpoch !== undefined && epoch !== expectedEpoch)
+                throw this.flowSuperseded();
+            this.epoch = epoch;
+            this.bound = true;
+            return epoch;
+        }.bind(this));
+    },
+    flowEpoch: function () {
+        return authFlow(function* () {
+            return this.epoch ?? (yield authInvoke(this, "liveEpoch", []));
+        }.bind(this));
+    },
+    bindFlow: function () {
+        return authFlow(function* () {
+            const { grant } = (yield authInvoke(this, "readGrant", []));
+            const epoch = this.callback?.flow.epoch ?? this.epoch ?? grant.epoch;
+            if (grant.epoch !== epoch)
+                throw this.flowSuperseded();
+            this.epoch = epoch;
+            this.bound = true;
+            this.codeExchange = true;
+            (yield authInvoke(this, "checkFlowBinding", [grant]));
+            this.seen = {
+                client: fingerprint(grant.body.client?.value),
+                tokens: fingerprint(grant.body.tokens),
+            };
+        }.bind(this));
+    },
+    resetAuthorization: function (operatorDisconnected = false, preserveClient = false) {
+        return authFlow(function* () {
+            const operation = authInvoke(this, "performReset", [operatorDisconnected, preserveClient]);
+            if (!this.onReset)
+                return (yield operation);
+            const reset = runEdge(operation);
+            this.onReset?.(reset);
+            return (yield authValue(() => reset));
+        }.bind(this));
+    },
+    disconnectAuthorization: function (send) {
+        return authFlow(function* () {
+            const operation = authInvoke(this, "performReset", [true, false, send]);
+            if (!this.onReset)
+                return (yield operation);
+            const reset = runEdge(operation);
+            this.onReset?.(reset);
+            return (yield authValue(() => reset));
+        }.bind(this));
+    },
+    performReset: function (operatorDisconnected, preserveClient, revoke) {
+        return authFlow(function* () {
+            const epoch = `${operatorDisconnected ? DISCONNECTED_EPOCH_PREFIX : ACTIVE_EPOCH_PREFIX}${crypto.randomUUID()}`;
+            for (let attempt = 0; attempt < MAX_GRANT_WRITES; attempt++) {
+                const { raw, grant } = (yield authInvoke(this, "readGrant", [null]));
+                const carried = preserveClient && !operatorDisconnected ? this.carriableClient(grant) : undefined;
+                const encoded = (yield authInvoke(this, "encodeGrant", [{ epoch, body: carried ?? {} }, null]));
+                let written;
+                try {
+                    written = (yield authStorage(this.storage, "compareAndSet", [GRANT, raw, encoded]));
+                }
+                catch {
+                    throw this.credentialWriteError();
+                }
+                if (written) {
+                    this.refreshCoordinator?.retire(grant.epoch);
+                    try {
+                        (yield authInvoke(this, "sweepConsents", []));
+                        (yield authInvoke(this, "sweepRefreshLeases", []));
+                    }
+                    finally {
+                        if (revoke) {
+                            const snapshot = this.revocationSnapshot(grant.body);
+                            (yield authCall(revokeDownstreamGrant, [snapshot.body, revoke, snapshot.client]));
+                        }
+                    }
+                    return;
+                }
+            }
+            throw this.credentialWriteError();
+        }.bind(this));
+    },
+};