@north-light/sdk 0.0.0 → 0.3.415

package/dist/oauth/index.d.ts

@@ -0,0 +1,235 @@
+import { type JWK } from 'jose';
+import { type IdTokenClaims } from '@north-light/identity';
+import { Crouter, type CrouterOptions } from '../client.js';
+import { RunWatcher, type RunWatchOptions } from '../resources/run-watcher.js';
+import { GrantWatcher, type GrantWatchOptions } from '../resources/grant-watcher.js';
+import { type Refusal } from './refusal.js';
+export { refusalOf } from './refusal.js';
+export type { Refusal, RefusalKind } from './refusal.js';
+/** One connection `refreshIdleConnections` could not refresh and that is still stored: an error other than a
+ *  refusal, or a refusal whose `onRefusal` threw (then `refusalOf(error)` is set and `error.cause` is what it threw). */
+export interface RefreshFailure {
+    userId: string;
+    error: unknown;
+}
+export interface Connection {
+    userId: string;
+    runtimeUrl: string;
+    refreshToken: string;
+    grantId: string;
+    accessToken: string;
+    accessTokenExpiresAt: number;
+    idToken?: string;
+}
+export interface ConnectionStore {
+    load(userId: string): Promise<Connection | null>;
+    save(connection: Connection): Promise<void>;
+    /** Run `fn` holding `userId`'s lock across every process that shares the store, and commit what it wrote when
+     *  it resolves. `OAuth2Client` reloads, refreshes and saves inside it, so two processes never spend one refresh token. */
+    lock<T>(userId: string, fn: () => Promise<T>): Promise<T>;
+    /** Delete `userId`'s connection only while its refresh token is still `refreshToken`, and answer whether a row
+     *  was deleted. The SDK calls it, under `lock`, after a refused refresh's `onRefusal` resolves; a connection a
+     *  fresh sign-in saved meanwhile carries another token and is kept. */
+    remove(userId: string, refreshToken: string): Promise<boolean>;
+    /** Connections last saved before this instant. A save must update the store's activity timestamp. */
+    listStale?(before: Date): Promise<Connection[]>;
+}
+/** A connection store for one process (local development and tests): its lock does not reach other processes. */
+export declare class MemoryConnectionStore implements ConnectionStore {
+    private readonly connections;
+    private readonly locks;
+    private readonly savedAt;
+    load(userId: string): Promise<Connection | null>;
+    save(connection: Connection): Promise<void>;
+    remove(userId: string, refreshToken: string): Promise<boolean>;
+    listStale(before: Date): Promise<Connection[]>;
+    /** Not reentrant: calling `lock` for the same user from inside `fn` waits forever. */
+    lock<T>(userId: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A person's crouter cloud identity from a sign-in-only (`openid`, `openid email`, `openid profile`, or `openid email profile`) request, read from an
+ * ID token the SDK verified: ES256 signature against the directory's JWKS, `iss`, `aud` = the client id,
+ * `exp`, and the `nonce` from `authorizeUrl`. It is not a connection: it holds no runtime URL, refresh
+ * token, or grant, and nothing can be called on the person's runtime with it.
+ */
+export interface Identity {
+    /** The person's crouter cloud user id (`user:<id>`), the same `sub` a `Connection.userId` carries. */
+    sub: string;
+    /** Present only when `email` was requested and approved. */
+    email?: string;
+    emailVerified?: boolean;
+    /** Present only when `profile` was requested and approved and the person has a name (a phone-only account has none). The full name, e.g. `Sam Rivera`. */
+    name?: string;
+    givenName?: string;
+    familyName?: string;
+    /** Present only when `profile` was requested and approved and the ID token carries an https `picture` (the person's Google photo URL). An account with no photo has none; show initials then. */
+    picture?: string;
+    /** Every verified ID token claim. */
+    claims: IdTokenClaims;
+}
+/** `authorizeUrl`'s nonce: `string` when the scopes are known to include `openid`, `undefined` when known not to, else either. */
+export type AuthorizeNonce<S extends readonly string[]> = string extends S[number] ? string | undefined : 'openid' extends S[number] ? string : undefined;
+/** 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 declare function profileFromClaims(claims: IdTokenClaims): Pick<Identity, 'name' | 'givenName' | 'familyName' | 'picture'>;
+export interface OAuth2Options {
+    clientId: string;
+    privateKey: string | JWK;
+    keyId?: string;
+    redirectUri: string;
+    issuer: string;
+    /** Where the app keeps each person's `Connection`. Save `exchangeCode`'s result here; every refresh reloads,
+     *  rotates and saves under its `lock`, and a refused connection is removed from it. */
+    store: ConnectionStore;
+    /**
+     * Called when the directory refuses to refresh a stored connection (`grant_removed`, `grant_suspended`,
+     * `refresh_token_expired`, `refresh_token_reused`, `grant_revoked`): act on the person's data here, once, for
+     * every caller (a request, `refreshIdleConnections`, a `RunWatcher`). `refusal.kind` says what it means.
+     *
+     * At least once per dead connection, so make it idempotent: it runs after the store lock is released, and the
+     * SDK removes the stored connection (only while it still holds the refused token) after it resolves. If it
+     * throws, the connection stays stored and the next use of it refreshes, is refused, and calls it again.
+     * It must not call the runtime for `refusal.userId` (that connection is dead): `oauth.client(userId)` for that
+     * user inside it throws `CrouterError` `refusal_handler_reentry`.
+     */
+    onRefusal?: (refusal: Refusal) => void | Promise<void>;
+    /** Transport override for the directory requests and for the runtime calls of every `client(userId)`. */
+    fetch?: typeof fetch;
+    /**
+     * One deadline, in milliseconds, for each directory operation: a discovery read, a token request (the code
+     * exchange or a refresh) or a revocation. It covers every attempt of that operation, the reading of the answer
+     * and every `runtime_provisioning` retry wait, including a `Retry-After`; a wait that would pass it fails at
+     * once. A refresh runs this bound while it holds the user's store lock, so the lock is held at most this long
+     * (plus the store's own time) and a hung directory cannot stall the user's other refreshes. Defaults to
+     * `DEFAULT_DIRECTORY_TIMEOUT_MS` (10 s). The error is `DeadlineExceededError` (`code: 'deadline_exceeded'`).
+     */
+    timeoutMs?: number;
+}
+/** 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 declare class ConnectedCrouter extends Crouter {
+    /** The person whose connection this client uses (`user:<id>`). */
+    readonly userId: string;
+    /** The person's runtime URL this client calls, as the stored connection named it. */
+    readonly runtimeUrl: string;
+    constructor(connection: Pick<Connection, 'userId' | 'runtimeUrl'>, options: Pick<CrouterOptions, 'tokenSource' | 'onUnauthorized' | 'fetch'>);
+}
+/** The default deadline of one directory operation (`OAuth2Options.timeoutMs`): a discovery read is forgotten when it passes. */
+export declare const DEFAULT_DIRECTORY_TIMEOUT_MS = 10000;
+export declare class OAuth2Client {
+    private readonly options;
+    private readonly issuer;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    private readonly store;
+    private jwks?;
+    private discoveryPromise?;
+    /** One refresh per (user, refresh token) in this process; a client holding a newer token never joins an older refusal. */
+    private readonly inFlight;
+    /** Refusals whose connection the SDK removed (or found already replaced) after `onRefusal` resolved. */
+    private readonly settled;
+    constructor(options: OAuth2Options);
+    /** The issuer's discovery document. The first successful read is kept for the client's life; a read that fails or
+     *  passes the deadline (`timeoutMs`) rejects and is forgotten, so the next call reads again. */
+    private discovery;
+    /** One directory request and the reading of its answer under `deadlineAt`; a deadline rejects `DeadlineExceededError`. */
+    private bounded;
+    /** The discovery document within the operation's `deadlineAt`: the memoised read keeps its own deadline, and this
+     *  caller stops waiting for it at its own. */
+    private discoveryWithin;
+    /**
+     * 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.
+     */
+    accountAppUrl(): Promise<string>;
+    /** 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. */
+    authorizeUrl<const S extends readonly string[]>({ scopes, state, codeVerifier, prompt }: {
+        scopes: S;
+        state: string;
+        codeVerifier?: string;
+        prompt?: 'consent';
+    }): Promise<{
+        url: string;
+        codeVerifier: string;
+        state: string;
+        nonce: AuthorizeNonce<S>;
+    }>;
+    /**
+     * 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.
+     */
+    exchangeCode({ code, codeVerifier, state, expectedState, nonce }: {
+        code: string;
+        codeVerifier: string;
+        state: string;
+        expectedState: string;
+        nonce?: string;
+    }): Promise<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`.
+     */
+    exchangeIdentity({ code, codeVerifier, state, expectedState, nonce }: {
+        code: string;
+        codeVerifier: string;
+        state: string;
+        expectedState: string;
+        nonce: string;
+    }): Promise<Identity>;
+    /**
+     * 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.
+     */
+    refreshIdleConnections({ olderThanMs }: {
+        olderThanMs: number;
+    }): Promise<{
+        refreshed: number;
+        refused: number;
+        failures: RefreshFailure[];
+    }>;
+    /**
+     * 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: Connection): Promise<Connection>;
+    private rotate;
+    /**
+     * 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`.
+     */
+    client(userId: string): Promise<ConnectedCrouter>;
+    /**
+     * 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: RunWatchOptions): RunWatcher;
+    /**
+     * 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: GrantWatchOptions): GrantWatcher;
+    /** 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. */
+    verifyIdToken(idToken: string, { nonce }?: {
+        nonce?: string;
+    }): Promise<IdTokenClaims>;
+    revoke(connection: Connection): Promise<boolean>;
+    /** A token request. `deadlineAt` is the whole operation's deadline (discovery included); without one it starts now. */
+    private tokenResponse;
+    private connectionFrom;
+    private post;
+}