@north-light/sdk 0.0.0 → 0.3.414

package/dist/oauth/index.js

@@ -0,0 +1,535 @@
+import { calculateJwkThumbprint, decodeJwt, decodeProtectedHeader, exportJWK, importJWK, importPKCS8, SignJWT } from 'jose';
+import { JwksCache, parseScope, verifyIdToken } from '@north-light/identity';
+import { APIError, CrouterError, mapError } from '../errors.js';
+import { Crouter } from '../client.js';
+import { RunWatcher } from '../resources/run-watcher.js';
+import { GrantWatcher } from '../resources/grant-watcher.js';
+import { attachRefusal, isRefusalCode, refusalKindOf } from './refusal.js';
+export { refusalOf } from './refusal.js';
+/** A connection store for one process (local development and tests): its lock does not reach other processes. */
+export class MemoryConnectionStore {
+    connections = new Map();
+    locks = new Map();
+    savedAt = new Map();
+    async load(userId) { return this.connections.get(userId) ?? null; }
+    async save(connection) {
+        this.connections.set(connection.userId, connection);
+        this.savedAt.set(connection.userId, Date.now());
+    }
+    async remove(userId, refreshToken) {
+        if (this.connections.get(userId)?.refreshToken !== refreshToken)
+            return false;
+        this.connections.delete(userId);
+        this.savedAt.delete(userId);
+        return true;
+    }
+    async listStale(before) {
+        return [...this.connections.values()].filter((connection) => (this.savedAt.get(connection.userId) ?? Infinity) < before.getTime());
+    }
+    /** Not reentrant: calling `lock` for the same user from inside `fn` waits forever. */
+    async lock(userId, fn) {
+        const prior = this.locks.get(userId);
+        let release;
+        const done = new Promise((resolve) => { release = resolve; });
+        this.locks.set(userId, done);
+        await prior;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.locks.get(userId) === done)
+                this.locks.delete(userId);
+        }
+    }
+}
+/** The `profile` claims a verified ID token carries, each only when present: use it on `Connection.idToken` after `verifyIdToken` for a sign-in that requested runtime scopes (`exchangeCode`), as `exchangeIdentity` does for a sign-in-only one. */
+export function profileFromClaims(claims) {
+    const text = (value) => typeof value === 'string' && value !== '' ? value : undefined;
+    const [name, givenName, familyName, picture] = [text(claims.name), text(claims.given_name), text(claims.family_name), httpsUrl(claims.picture)];
+    return { ...(name ? { name } : {}), ...(givenName ? { givenName } : {}), ...(familyName ? { familyName } : {}), ...(picture ? { picture } : {}) };
+}
+/** `value` when it is a string parsing as an `https:` URL, else undefined: a `picture` claim is rendered as an image source, so no other scheme gets through. */
+function httpsUrl(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    try {
+        return new URL(value).protocol === 'https:' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A runtime client on one person's stored connection (`oauth.client(userId)`): a `Crouter` that refreshes its
+ *  token through the `OAuth2Client`'s store, plus whose connection it is and the runtime it calls. */
+export class ConnectedCrouter extends Crouter {
+    /** The person whose connection this client uses (`user:<id>`). */
+    userId;
+    /** The person's runtime URL this client calls, as the stored connection named it. */
+    runtimeUrl;
+    constructor(connection, options) {
+        super({ ...options, baseURL: connection.runtimeUrl });
+        this.userId = connection.userId;
+        this.runtimeUrl = connection.runtimeUrl;
+    }
+}
+/** How long one discovery read may take before it rejects (and is forgotten). */
+const DISCOVERY_TIMEOUT_MS = 10_000;
+const assertionType = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+let refusalScope;
+function handlerScope() {
+    if (refusalScope !== undefined)
+        return refusalScope;
+    const hooks = globalThis.process?.getBuiltinModule?.('node:async_hooks');
+    refusalScope = hooks ? new hooks.AsyncLocalStorage() : null;
+    return refusalScope;
+}
+export class OAuth2Client {
+    options;
+    issuer;
+    fetcher;
+    store;
+    jwks;
+    discoveryPromise;
+    /** One refresh per (user, refresh token) in this process; a client holding a newer token never joins an older refusal. */
+    inFlight = new Map();
+    /** Refusals whose connection the SDK removed (or found already replaced) after `onRefusal` resolved. */
+    settled = new WeakSet();
+    constructor(options) {
+        this.options = options;
+        if (!options.issuer || !options.issuer.trim())
+            throw new CrouterError('OAuth2Client requires an issuer');
+        if (!options.store)
+            throw new CrouterError('OAuth2Client requires a store (a ConnectionStore such as PostgresConnectionStore)');
+        this.issuer = options.issuer;
+        this.store = options.store;
+        this.fetcher = options.fetch ?? fetch;
+    }
+    /** The issuer's discovery document. The first successful read is kept for the client's life; a read that fails or
+     *  takes longer than 10 s rejects and is forgotten, so the next call reads again. */
+    discovery() {
+        if (this.discoveryPromise)
+            return this.discoveryPromise;
+        const read = (async () => {
+            const response = await this.fetcher(`${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS) });
+            if (!response.ok)
+                throw new CrouterError(`Directory discovery failed: ${response.status}`);
+            const value = await response.json();
+            if (!value.authorization_endpoint || !value.token_endpoint || !value.jwks_uri)
+                throw new CrouterError('Directory discovery has missing endpoints');
+            return value;
+        })();
+        this.discoveryPromise = read;
+        // Only this read's own failure clears the memo, never a newer read started after it.
+        read.catch(() => { if (this.discoveryPromise === read)
+            this.discoveryPromise = undefined; });
+        return read;
+    }
+    /**
+     * The app's page on the signed-in person's crouter cloud account, where they change or remove what the app may do:
+     * the discovery document's `account_app_uri_template` with its one `{client_id}` replaced by the encoded client id.
+     * Needs no user or connection; its only request is the shared discovery read. Throws `CrouterError` when the field
+     * is absent, does not contain `{client_id}` exactly once, or does not expand to a URL on the issuer's origin.
+     */
+    async accountAppUrl() {
+        const template = (await this.discovery()).account_app_uri_template;
+        if (typeof template !== 'string' || !template)
+            throw new CrouterError('Directory discovery has no account_app_uri_template');
+        const parts = template.split('{client_id}');
+        if (parts.length !== 2)
+            throw new CrouterError("Directory discovery's account_app_uri_template must contain {client_id} exactly once");
+        const expanded = parts.join(encodeURIComponent(this.options.clientId));
+        const origin = new URL(this.issuer).origin;
+        let parsed;
+        try {
+            parsed = new URL(expanded);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (parsed?.origin !== origin)
+            throw new CrouterError(`Directory discovery's account_app_uri_template is not a URL on ${origin}`);
+        return expanded;
+    }
+    /** Start a sign-in. When `scopes` includes `openid` the result carries the `nonce` to pass to the exchange; with literal scopes its type is `string`.
+     * `prompt: 'consent'` makes the directory show its consent screen even when the person already approved these scopes. */
+    async authorizeUrl({ scopes, state, codeVerifier, prompt }) {
+        for (const scope of scopes) {
+            if (scope === 'openid' || scope === 'email' || scope === 'profile')
+                continue;
+            try {
+                parseScope(scope);
+            }
+            catch {
+                throw new APIError(400, 'invalid_scope', `Unsupported scope: ${scope}`);
+            }
+        }
+        const verifier = codeVerifier ?? randomBase64url(32);
+        const nonce = scopes.includes('openid') ? randomBase64url(32) : undefined;
+        const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+        const challenge = base64url(new Uint8Array(hash));
+        const url = new URL((await this.discovery()).authorization_endpoint);
+        url.search = new URLSearchParams({
+            client_id: this.options.clientId, response_type: 'code', redirect_uri: this.options.redirectUri,
+            scope: scopes.join(' '), state, code_challenge: challenge, code_challenge_method: 'S256',
+            ...(nonce ? { nonce } : {}), ...(prompt === undefined ? {} : { prompt }),
+        }).toString();
+        return { url: url.href, codeVerifier: verifier, state, ...(nonce ? { nonce } : {}) };
+    }
+    /**
+     * Finish a sign-in that asked for runtime scopes and return the person's `Connection`. A sign-in-only
+     * request (`openid`, `openid email`, `openid profile`, or `openid email profile`) gets no connection from the directory; finish it with
+     * `exchangeIdentity`, which this method names when it receives such a response.
+     */
+    async exchangeCode({ code, codeVerifier, state, expectedState, nonce }) {
+        assertState(state, expectedState);
+        const response = await this.tokenResponse({ grant_type: 'authorization_code', code, redirect_uri: this.options.redirectUri, code_verifier: codeVerifier });
+        if (response.refresh_token === undefined && response.runtimeUrl === undefined && typeof response.id_token === 'string') {
+            throw new CrouterError('The directory answered a sign-in-only request (openid, optionally with email and profile) with an identity and no connection; finish a sign-in-only request with exchangeIdentity(), not exchangeCode()', 'oauth_exchange_mismatch');
+        }
+        const connection = this.connectionFrom(response);
+        if (connection.idToken) {
+            const claims = await this.verifyIdToken(connection.idToken, { nonce });
+            if (typeof claims.nonce !== 'string' || claims.nonce !== nonce)
+                throw new CrouterError('ID token nonce is missing or does not match', 'id_token_invalid');
+        }
+        return connection;
+    }
+    /**
+     * Finish a sign-in-only request (`authorizeUrl` with scopes `openid` or `openid email`) and return the
+     * person's verified identity. There is no connection, refresh token, or runtime access on this path.
+     * `nonce` is the value `authorizeUrl` returned and is required. A response without an ID token, or with
+     * one that fails verification, throws `id_token_invalid`; a response carrying a runtime connection (the
+     * request asked for runtime scopes) throws `oauth_exchange_mismatch` and must be finished with `exchangeCode`.
+     */
+    async exchangeIdentity({ code, codeVerifier, state, expectedState, nonce }) {
+        assertState(state, expectedState);
+        if (typeof nonce !== 'string' || !nonce)
+            throw new CrouterError('exchangeIdentity requires the nonce authorizeUrl returned', 'oauth_nonce_missing');
+        const response = await this.tokenResponse({ grant_type: 'authorization_code', code, redirect_uri: this.options.redirectUri, code_verifier: codeVerifier });
+        if (response.refresh_token !== undefined || response.runtimeUrl !== undefined) {
+            throw new CrouterError('The directory answered with a runtime connection, so the request asked for runtime scopes; finish it with exchangeCode(), or request only openid or openid email for a sign-in-only visitor', 'oauth_exchange_mismatch');
+        }
+        if (typeof response.id_token !== 'string' || !response.id_token)
+            throw new CrouterError('Directory returned no ID token for a sign-in-only request', 'id_token_invalid');
+        const claims = await this.verifyIdToken(response.id_token, { nonce });
+        return {
+            sub: claims.sub,
+            ...(typeof claims['email'] === 'string' ? { email: claims['email'] } : {}),
+            ...(typeof claims['email_verified'] === 'boolean' ? { emailVerified: claims['email_verified'] } : {}),
+            ...profileFromClaims(claims),
+            claims,
+        };
+    }
+    /**
+     * Refresh the store's idle connections once (the app schedules it, for example daily, with `olderThanMs` of 30
+     * days). Each refusal goes through `onRefusal` and the connection's removal, and is counted in `refused`.
+     * `failures` holds every connection still stored that could not be refreshed: an error other than a refusal,
+     * or a refusal whose `onRefusal` threw (`refusalOf(failure.error)` is set and `failure.error.cause` is what the
+     * handler threw); the next run retries those. A connection removed before its turn is skipped.
+     */
+    async refreshIdleConnections({ olderThanMs }) {
+        if (!this.store.listStale)
+            throw new CrouterError('ConnectionStore.listStale(before) is required to refresh idle connections');
+        if (!Number.isFinite(olderThanMs) || olderThanMs <= 0)
+            throw new CrouterError('olderThanMs must be a positive number');
+        const stale = await this.store.listStale(new Date(Date.now() - olderThanMs));
+        let refreshed = 0;
+        let refused = 0;
+        const failures = [];
+        for (const connection of stale) {
+            try {
+                // refresh() holds the cross-process store lock and reloads before rotating.
+                const current = await this.refresh(connection);
+                if (current.refreshToken !== connection.refreshToken)
+                    refreshed++;
+            }
+            catch (error) {
+                if (error instanceof CrouterError && error.code === 'not_connected')
+                    continue;
+                if (error instanceof APIError && this.settled.has(error))
+                    refused++;
+                else
+                    failures.push({ userId: connection.userId, error });
+            }
+        }
+        return { refreshed, refused, failures };
+    }
+    /**
+     * Rotate `connection`'s refresh token through the store: under the user's lock it reloads, and when another
+     * process already rotated (or the person signed in again) it returns the stored connection without calling the
+     * directory. Nothing stored throws `CrouterError` `not_connected`. A refusal runs `onRefusal`, removes the
+     * connection, and rejects with the directory's `AuthenticationError` (`refusalOf(error)` set).
+     */
+    refresh(connection) {
+        assertNotInHandler(connection.userId);
+        const key = `${connection.userId}\u0000${connection.refreshToken}`;
+        const existing = this.inFlight.get(key);
+        if (existing)
+            return existing;
+        const pending = this.rotate(connection);
+        this.inFlight.set(key, pending);
+        const forget = () => { if (this.inFlight.get(key) === pending)
+            this.inFlight.delete(key); };
+        pending.then(forget, forget);
+        return pending;
+    }
+    async rotate(connection) {
+        const { userId } = connection;
+        // C1/M1: the locked closure never throws a refusal (a throw rolls a Postgres store back) and never runs app code.
+        const rotation = await this.store.lock(userId, async () => {
+            const stored = await this.store.load(userId);
+            if (!stored)
+                return { kind: 'missing' };
+            if (stored.refreshToken !== connection.refreshToken)
+                return { kind: 'current', connection: stored };
+            let response;
+            try {
+                response = await this.tokenResponse({ grant_type: 'refresh_token', refresh_token: stored.refreshToken });
+            }
+            catch (error) {
+                if (error instanceof APIError && error.origin === 'directory' && isRefusalCode(error.code))
+                    return { kind: 'refused', error, stored };
+                throw error;
+            }
+            const updated = this.connectionFrom(response, stored);
+            await this.store.save(updated);
+            return { kind: 'current', connection: updated };
+        });
+        if (rotation.kind === 'current')
+            return rotation.connection;
+        if (rotation.kind === 'missing')
+            throw notConnected(userId);
+        const { error, stored } = rotation;
+        const refusal = { kind: refusalKindOf(error.code), code: error.code, userId, grantId: stored.grantId, error };
+        attachRefusal(error, refusal);
+        const handler = this.options.onRefusal;
+        if (handler) {
+            const scope = handlerScope();
+            try {
+                await (scope ? scope.run(userId, () => handler(refusal)) : handler(refusal));
+            }
+            catch (handlerError) {
+                // The connection stays stored, so the next use is refused again and calls the handler again.
+                Object.defineProperty(error, 'cause', { value: handlerError, configurable: true, writable: true });
+                throw error;
+            }
+        }
+        try {
+            await this.store.lock(userId, () => this.store.remove(userId, stored.refreshToken));
+        }
+        catch (removeError) {
+            Object.defineProperty(error, 'cause', { value: removeError, configurable: true, writable: true });
+            throw error;
+        }
+        this.settled.add(error);
+        throw error;
+    }
+    /**
+     * A runtime client on `userId`'s stored connection; `runtimeUrl` on it names the runtime it calls. Nothing
+     * stored throws `CrouterError` `not_connected` (show "sign in again"). The client refreshes through the store;
+     * once its connection is refused (and `onRefusal` resolved) it throws that same refusal on every later call
+     * without asking the directory again. Called for the user whose `onRefusal` is running, it throws
+     * `refusal_handler_reentry`.
+     */
+    async client(userId) {
+        assertNotInHandler(userId);
+        const connection = await this.store.load(userId);
+        if (!connection)
+            throw notConnected(userId);
+        let current = connection;
+        let refused;
+        const refresh = async (force) => {
+            if (refused)
+                throw refused;
+            if (!force && current.accessToken && current.accessTokenExpiresAt - Date.now() > 30_000)
+                return;
+            try {
+                current = await this.refresh(current);
+            }
+            catch (error) {
+                if (error instanceof APIError && this.settled.has(error))
+                    refused = error;
+                throw error;
+            }
+        };
+        return new ConnectedCrouter(connection, {
+            tokenSource: async () => { await refresh(false); return current.accessToken; },
+            onUnauthorized: async () => { await refresh(true); },
+            ...(this.options.fetch ? { fetch: this.options.fetch } : {}),
+        });
+    }
+    /**
+     * Follow the app's background runs until each comes to rest, and hand each ending to `onEnded` (see
+     * `RunWatchOptions`). Runs are opened with `client(userId)`, so refusals reach `onRefusal`. Call `start()`.
+     */
+    watchRuns(options) {
+        return new RunWatcher((userId) => this.client(userId), options);
+    }
+    /**
+     * Follow the grants of the people `users()` names, and hand each change (and each user's first reading in this
+     * process) to `onChanged` (see `GrantWatchOptions`). Grants are read with `client(userId)`, so refusals reach
+     * `onRefusal`. Call `start()`.
+     */
+    watchGrants(options) {
+        return new GrantWatcher((userId) => this.client(userId), options);
+    }
+    /** Verify an ID token: ES256 signature against the discovered JWKS, `iss`, `aud` = client id, `exp`, and `nonce` when given. A token that fails any check throws `id_token_invalid`; a JWKS that can't be fetched or is malformed rethrows that error. */
+    async verifyIdToken(idToken, { nonce } = {}) {
+        const discovery = await this.discovery();
+        this.jwks ??= new JwksCache(this.issuer, this.fetcher, discovery.jwks_uri);
+        const invalid = (reason) => new CrouterError(`ID token failed verification: ${reason}`, 'id_token_invalid');
+        try {
+            decodeProtectedHeader(idToken);
+        }
+        catch {
+            throw invalid('it is not a signed JWT');
+        }
+        let claims;
+        try {
+            claims = await verifyIdToken({ token: idToken, jwks: this.jwks, issuer: this.issuer, audience: this.options.clientId });
+        }
+        catch (error) {
+            // A token that fails verification is id_token_invalid; a JWKS that cannot be fetched or is malformed is the
+            // directory's fault, not the token's, and is rethrown as is. jose's token errors (bad signature, wrong iss/aud,
+            // expired, no matching key) carry an ERR_J* code; ERR_JWKS_INVALID and ERR_JWKS_TIMEOUT describe the key set.
+            // The identity package's own checks throw "Invalid ID token …". Duck-typed, since jose may be a separate copy.
+            const joseCode = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            const keySetFault = joseCode === 'ERR_JWKS_INVALID' || joseCode === 'ERR_JWKS_TIMEOUT';
+            if ((typeof joseCode === 'string' && joseCode.startsWith('ERR_J') && !keySetFault) || /^Invalid ID token/.test(message))
+                throw invalid(message);
+            throw error;
+        }
+        if (nonce !== undefined && claims.nonce !== nonce)
+            throw new CrouterError('ID token nonce is missing or does not match', 'id_token_invalid');
+        return claims;
+    }
+    async revoke(connection) {
+        const metadata = await this.discovery();
+        if (!metadata.revocation_endpoint)
+            return false;
+        await this.post(metadata.revocation_endpoint, { token: connection.refreshToken, token_type_hint: 'refresh_token' }, true);
+        return true;
+    }
+    async tokenResponse(params) {
+        const metadata = await this.discovery();
+        if (!metadata.token_endpoint_auth_methods_supported?.includes('private_key_jwt'))
+            throw new CrouterError('Directory does not support private_key_jwt');
+        return await this.post(metadata.token_endpoint, params);
+    }
+    connectionFrom(response, previous) {
+        if (typeof response.access_token !== 'string' || typeof response.refresh_token !== 'string')
+            throw new CrouterError('Directory returned an invalid token response');
+        const claims = decodeJwt(response.access_token);
+        const runtimeUrl = typeof response.runtimeUrl === 'string' && response.runtimeUrl ? response.runtimeUrl : previous?.runtimeUrl;
+        if (typeof claims.sub !== 'string' || typeof claims.grant !== 'string' || typeof claims.exp !== 'number' || !runtimeUrl) {
+            throw new CrouterError('Directory returned an incomplete connection');
+        }
+        const idToken = typeof response.id_token === 'string' ? response.id_token : previous?.idToken;
+        return {
+            userId: claims.sub, runtimeUrl, refreshToken: response.refresh_token,
+            grantId: claims.grant,
+            accessToken: response.access_token, accessTokenExpiresAt: claims.exp * 1_000,
+            ...(idToken ? { idToken } : {}),
+        };
+    }
+    async post(endpoint, values, revocation = false) {
+        const key = this.options.privateKey;
+        if (typeof key !== 'string' && key.alg !== undefined && key.alg !== 'ES256' && key.alg !== 'RS256')
+            throw new CrouterError('privateKey must use ES256 or RS256');
+        let alg;
+        let imported;
+        if (typeof key === 'string') {
+            try {
+                imported = await importPKCS8(key, 'ES256');
+                alg = 'ES256';
+            }
+            catch {
+                imported = await importPKCS8(key, 'RS256');
+                alg = 'RS256';
+            }
+        }
+        else {
+            alg = key.alg === 'RS256' || key.kty === 'RSA' ? 'RS256' : 'ES256';
+            imported = await importJWK(key, alg);
+        }
+        const kid = this.options.keyId ?? (typeof key === 'string' ? undefined : key.kid);
+        for (let attempt = 0;; attempt++) {
+            const now = Math.floor(Date.now() / 1000);
+            const assertion = await new SignJWT({})
+                .setProtectedHeader({ alg, typ: 'JWT', ...(kid ? { kid } : {}) })
+                .setIssuer(this.options.clientId).setSubject(this.options.clientId).setAudience(endpoint)
+                .setIssuedAt(now).setExpirationTime(now + 60).setJti(crypto.randomUUID()).sign(imported);
+            const response = await this.fetcher(endpoint, {
+                method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ ...values, client_id: this.options.clientId, client_assertion_type: assertionType, client_assertion: assertion }),
+            });
+            if (revocation && response.ok)
+                return undefined;
+            const payload = await response.json();
+            if (response.ok)
+                return payload;
+            const refusal = payload;
+            // invalid_grant carries the directory's reason as its error_description; a reason it does not name is grant_revoked.
+            const description = refusal.error_description ?? '';
+            const code = refusal.error === 'invalid_grant'
+                ? description === 'runtime_provisioning' || isRefusalCode(description) ? description : 'grant_revoked'
+                : refusal.error === 'invalid_client' ? 'unauthorized' : 'invalid_request';
+            const reconnect = isRefusalCode(code);
+            if (code === 'runtime_provisioning' && attempt < 2) {
+                const retryAfter = refusal.retry_after_s ?? Number(response.headers.get('retry-after'));
+                const delay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1_000 : 500 * 2 ** attempt * (0.5 + Math.random());
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            const message = refusal.error_description ?? refusal.error ?? 'Directory token request failed';
+            const keyHint = code === 'unauthorized' ? await describeSigningKey(key, kid) : undefined;
+            // mapError gives the refusal its status class (401 → AuthenticationError) as errors.md documents.
+            throw mapError(new APIError(code === 'runtime_provisioning' ? 503 : reconnect || code === 'unauthorized' ? 401 : response.status, code, keyHint ? `${message}: ${keyHint.hint}` : message, code === 'invalid_request' ? { oauth_error: refusal.error }
+                : keyHint ? { oauth_error: 'invalid_client', kid: keyHint.kid, ...(keyHint.thumbprint ? { key_thumbprint: keyHint.thumbprint } : {}) } : undefined, response.headers, { origin: 'directory', type: code === 'runtime_provisioning' ? 'server_error' : code === 'invalid_request' ? 'invalid_request_error' : 'authentication_error',
+                retryable: code === 'runtime_provisioning', user_action: reconnect ? 'reconnect' : undefined }));
+        }
+    }
+}
+/**
+ * Name the key an `invalid_client` refusal rejected, so a developer who switched key files before
+ * uploading the public JWK sees which key the SDK signed with and where it must be registered.
+ */
+async function describeSigningKey(key, kid) {
+    const question = "is this key's public JWK registered on the app's Sign-in tab in the console?";
+    if (kid)
+        return { kid, hint: `the directory rejected the client assertion signed with key id (kid) "${kid}"; ${question}` };
+    // An assertion without a kid: the console lists such a key by its RFC 7638 thumbprint.
+    let thumbprint;
+    try {
+        thumbprint = typeof key === 'string'
+            ? await calculateJwkThumbprint(await exportJWK(await importPKCS8(key, 'ES256', { extractable: true }).catch(() => importPKCS8(key, 'RS256', { extractable: true }))), 'sha256')
+            : await calculateJwkThumbprint(key, 'sha256');
+    }
+    catch {
+        thumbprint = undefined;
+    }
+    const named = thumbprint ? `signed without a kid by the key whose thumbprint is "${thumbprint}"` : 'signed without a kid';
+    return { kid: null, ...(thumbprint ? { thumbprint } : {}), hint: `the directory rejected the client assertion ${named}; ${question}` };
+}
+function notConnected(userId) {
+    return new CrouterError(`No stored connection for ${userId}: they must sign in with crouter cloud again`, 'not_connected');
+}
+function assertNotInHandler(userId) {
+    if (handlerScope()?.getStore() === userId) {
+        throw new CrouterError(`onRefusal for ${userId} called that user's runtime; their connection is dead, so act only on the app's own data there`, 'refusal_handler_reentry');
+    }
+}
+// expectedState is the state saved by the app at authorizeUrl(), not a value from the callback.
+function assertState(state, expectedState) {
+    if (!state || !expectedState || state !== expectedState)
+        throw new CrouterError('OAuth state is missing or does not match', 'oauth_state_mismatch');
+}
+function randomBase64url(length) { return base64url(crypto.getRandomValues(new Uint8Array(length))); }
+function base64url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}

package/dist/oauth/keygen.d.ts

@@ -0,0 +1,18 @@
+import { type JWK } from 'jose';
+/** Make an app signing key and the public JWK to register in the directory. */
+export declare function generateKeyPair(): Promise<{
+    privateJwk: JWK;
+    publicJwk: JWK;
+    kid: string;
+}>;
+/** Check that `value` (a JWK object or its JSON text) is a private signing key with a `kid`, and return it as
+ *  `OAuth2Options.privateKey` takes it. `source` names where it came from in the error, e.g. a file path. */
+export declare function parsePrivateJwk(value: string | JWK, source?: string): JWK & {
+    d: string;
+    kid: string;
+};
+/** Read a private JWK file, such as the one `crouter-sdk keygen` writes, and check it as `parsePrivateJwk` does. Node only. */
+export declare function privateKeyFromFile(path: string): Promise<JWK & {
+    d: string;
+    kid: string;
+}>;

package/dist/oauth/keygen.js

@@ -0,0 +1,46 @@
+import { calculateJwkThumbprint, exportJWK, generateKeyPair as generateSigningKeyPair } from 'jose';
+import { CrouterError } from '../errors.js';
+/** Make an app signing key and the public JWK to register in the directory. */
+export async function generateKeyPair() {
+    const keys = await generateSigningKeyPair('ES256', { extractable: true });
+    const publicKey = await exportJWK(keys.publicKey);
+    const kid = await calculateJwkThumbprint(publicKey, 'sha256');
+    const properties = { kid, alg: 'ES256', use: 'sig' };
+    return {
+        privateJwk: { ...await exportJWK(keys.privateKey), ...properties },
+        publicJwk: { ...publicKey, ...properties },
+        kid,
+    };
+}
+const keygenHint = 'make one with: pnpm exec crouter-sdk keygen';
+/** Check that `value` (a JWK object or its JSON text) is a private signing key with a `kid`, and return it as
+ *  `OAuth2Options.privateKey` takes it. `source` names where it came from in the error, e.g. a file path. */
+export function parsePrivateJwk(value, source = 'The key') {
+    let key = value;
+    if (typeof value === 'string') {
+        try {
+            key = JSON.parse(value);
+        }
+        catch {
+            throw new CrouterError(`${source} is not JSON; it must hold a private JWK with a kid (${keygenHint}).`);
+        }
+    }
+    if (!key || typeof key !== 'object' || Array.isArray(key) || typeof key.d !== 'string' || !key.d
+        || typeof key.kid !== 'string' || !key.kid) {
+        throw new CrouterError(`${source} must hold a private JWK with a kid (${keygenHint}).`);
+    }
+    return key;
+}
+/** Read a private JWK file, such as the one `crouter-sdk keygen` writes, and check it as `parsePrivateJwk` does. Node only. */
+export async function privateKeyFromFile(path) {
+    const load = new Function('specifier', 'return import(specifier)');
+    const { readFile } = await load('node:fs/promises');
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new CrouterError(`${path} could not be read (${error instanceof Error ? error.message : String(error)}); it must hold a private JWK with a kid (${keygenHint}).`);
+    }
+    return parsePrivateJwk(text, path);
+}

package/dist/oauth/refusal.d.ts

@@ -0,0 +1,32 @@
+import { APIError } from '../errors.js';
+/**
+ * What a refused refresh means for the app's data:
+ * - `removed` (`grant_removed`): the person removed the app or deleted their account. The runtime has
+ *   deleted the app's runs; delete what the app stores for them.
+ * - `paused` (`grant_suspended`): the grant is suspended or expired. Nothing was deleted; keep the
+ *   person's data and show the app paused until they sign in again.
+ * - `reconnect` (`refresh_token_expired`, `refresh_token_reused`, or `grant_revoked` with no reason given):
+ *   the grant still exists. Nothing was deleted; ask them to sign in again.
+ */
+export type RefusalKind = 'removed' | 'paused' | 'reconnect';
+export declare const isRefusalCode: (code: string) => boolean;
+/** A connection the directory refused to refresh: passed to `OAuth2Options.onRefusal`, and read from the
+ *  refused call's error with `refusalOf(error)`. The SDK removes the stored connection once the handler resolves. */
+export interface Refusal {
+    kind: RefusalKind;
+    /** The directory's code: `grant_removed`, `grant_suspended`, `refresh_token_expired`, `refresh_token_reused`, or `grant_revoked`. */
+    code: string;
+    /** The connection's crouter cloud user id (`user:<id>`). */
+    userId: string;
+    /** The grant the refused connection held. */
+    grantId: string;
+    /** The `AuthenticationError` (401, `origin: 'directory'`, `userAction: 'reconnect'`) the refusal raised. */
+    error: APIError;
+}
+export declare function refusalKindOf(code: string): RefusalKind | null;
+export declare function attachRefusal(error: APIError, refusal: Refusal): void;
+/** The `Refusal` a call failed with when the directory refused its connection's refresh, else `null`. Read it to
+ *  answer one request (show "sign in again"); act on the connection itself in `OAuth2Options.onRefusal`, which the
+ *  SDK has already run. Only an error raised by `OAuth2Client` refreshing a stored connection carries one; a 429,
+ *  `cap_exhausted`, `scope_missing`, or a runtime-origin `grant_revoked` does not. */
+export declare function refusalOf(error: unknown): Refusal | null;

package/dist/oauth/refusal.js

@@ -0,0 +1,17 @@
+import { APIError } from '../errors.js';
+/** The one map from a directory refresh refusal code to what it means. Every other use of these codes reads its keys. */
+const refusalKinds = {
+    grant_removed: 'removed', grant_suspended: 'paused',
+    refresh_token_expired: 'reconnect', refresh_token_reused: 'reconnect', grant_revoked: 'reconnect',
+};
+export const isRefusalCode = (code) => Object.hasOwn(refusalKinds, code);
+const refusalKey = Symbol('crouter.refusal');
+export function refusalKindOf(code) { return isRefusalCode(code) ? refusalKinds[code] : null; }
+export function attachRefusal(error, refusal) { Object.defineProperty(error, refusalKey, { value: refusal }); }
+/** The `Refusal` a call failed with when the directory refused its connection's refresh, else `null`. Read it to
+ *  answer one request (show "sign in again"); act on the connection itself in `OAuth2Options.onRefusal`, which the
+ *  SDK has already run. Only an error raised by `OAuth2Client` refreshing a stored connection carries one; a 429,
+ *  `cap_exhausted`, `scope_missing`, or a runtime-origin `grant_revoked` does not. */
+export function refusalOf(error) {
+    return error instanceof APIError ? error[refusalKey] ?? null : null;
+}