@north-light/sdk 0.0.0 → 0.3.414

package/dist/errors.js

@@ -0,0 +1,87 @@
+import { APIError } from '@north-light/api';
+export { APIError };
+/** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
+export class CrouterError extends APIError {
+    constructor(message, code = 'crouter_error') {
+        super(0, code, message);
+        this.name = 'CrouterError';
+    }
+}
+/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
+ *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+ *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
+export class RuntimeVersionError extends APIError {
+    /** The oldest runtime this SDK accepts: its own release version. */
+    get sdkVersion() { return this.details.sdk_version; }
+    /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
+    get runtimeVersion() { return this.details.runtime_version; }
+}
+/** The daemon rejected the request: HTTP 400. */
+export class BadRequestError extends APIError {
+}
+/** The token was missing or wrong: HTTP 401. */
+export class AuthenticationError extends APIError {
+}
+/** The caller is not allowed to do this: HTTP 403. */
+export class PermissionDeniedError extends APIError {
+}
+/** No such node, profile, cron, or other resource: HTTP 404. */
+export class NotFoundError extends APIError {
+}
+/** The resource is in a state that forbids the request: HTTP 409. */
+export class ConflictError extends APIError {
+}
+/** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
+export class UnprocessableEntityError extends APIError {
+}
+/** Too many requests: HTTP 429. */
+export class RateLimitError extends APIError {
+}
+/** The daemon failed while handling the request: HTTP 500 and above. */
+export class InternalServerError extends APIError {
+}
+/** The daemon could not be reached, or the connection failed mid-request. */
+export class APIConnectionError extends APIError {
+}
+/** The request exceeded its timeout before the daemon answered. */
+export class APIConnectionTimeoutError extends APIConnectionError {
+}
+/** The caller's `AbortSignal` fired. */
+export class APIUserAbortError extends APIError {
+}
+/** Maps a transport failure or a plain `APIError` onto the specific class for its status and code. */
+export function mapError(error) {
+    if (!(error instanceof APIError) || error.constructor !== APIError) {
+        return error instanceof APIError ? error : new APIConnectionError(0, 'connection_error', error instanceof Error ? error.message : String(error));
+    }
+    const Constructor = error.code === 'runtime_version_unsupported'
+        ? RuntimeVersionError
+        : error.code === 'request_aborted'
+            ? APIUserAbortError
+            : error.status === 504 || error.code === 'request_timeout'
+                ? APIConnectionTimeoutError
+                : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
+                    ? APIConnectionError
+                    : error.status === 400
+                        ? BadRequestError
+                        : error.status === 401
+                            ? AuthenticationError
+                            : error.status === 403
+                                ? PermissionDeniedError
+                                : error.status === 404
+                                    ? NotFoundError
+                                    : error.status === 409
+                                        ? ConflictError
+                                        : error.status === 413 || error.status === 422
+                                            ? UnprocessableEntityError
+                                            : error.status === 402 || error.status === 429
+                                                ? RateLimitError
+                                                : error.status >= 500
+                                                    ? InternalServerError
+                                                    : APIError;
+    return new Constructor(error.status, error.code, error.message, error.details, error.headers, {
+        type: error.type, param: error.param, origin: error.origin, retryable: error.retryable,
+        retry_after_s: error.retryAfterS, reset_at: error.resetAt, request_id: error.requestId, run_id: error.runId,
+        question_id: error.questionId, scope: error.scope, user_action: error.userAction,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+export { Crouter as default, Crouter } from './client.js';
+export type { CrouterOptions } from './client.js';
+export { NodeStream } from './resources/node-stream.js';
+export { RunStream } from './resources/run-stream.js';
+export { CustomObjects } from './resources/custom-objects.js';
+export type { CustomDeliveryStream, ReceiveOptions } from './resources/custom-objects.js';
+export type { RunEvent, RunEventListener, RunEventOf, RunEventType, RunStreamEnd, UnknownRunEvent } from './resources/run-stream.js';
+export { RunReply } from './resources/run-reply.js';
+export type { RunReplyCollectOptions, RunReplyEnding, RunReplyEvent, RunReplyResult, SentRunMessage } from './resources/run-reply.js';
+export type { AppProfile, RunActivity, RunDeleteResult, RunObject, RunParsedOutcome, RunParseOptions, RunParseParams, RunStartParams, RunStartResult, RunStatus, RunTrace } from './resources/runs.js';
+export type { FileDownloadOptions } from './resources/files.js';
+export type { Upload, UploadCreateParams } from './resources/uploads.js';
+export type { AttachmentLink } from './resources/attachments.js';
+export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.js';
+export type { MemoryDocument, MemoryGetParams, MemoryListItem, MemoryListPage, MemoryListParams } from './resources/memory.js';
+export type { Question, QuestionAnswered, QuestionFields, QuestionResponses, QuestionSlot, QuestionStatus } from './resources/questions.js';
+export type { ProviderToolEntry } from './resources/providers.js';
+export { OAuth2Client, ConnectedCrouter, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refusalOf } from './oauth/index.js';
+export type { RefreshFailure, Refusal, RefusalKind } from './oauth/index.js';
+export { RunWatcher } from './resources/run-watcher.js';
+export type { PendingRun, RunActivityEvent, RunEnded, RunEnding, RunWatchOptions } from './resources/run-watcher.js';
+export { GrantWatcher } from './resources/grant-watcher.js';
+export type { GrantChanged, GrantWatchOptions } from './resources/grant-watcher.js';
+export { generateKeyPair } from './oauth/keygen.js';
+export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
+export type { AuthorizeNonce, Connection, ConnectionStore, Identity, OAuth2Options } from './oauth/index.js';
+export type { IdTokenClaims } from '@north-light/identity';
+export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { RUN_NOTICE_SCOPE, RunNoticeError, verifyRunNotice } from './resources/run-notice.js';
+export type { RunNotice, VerifyRunNoticeOptions } from './resources/run-notice.js';
+export type { NodeStreamEvent, NodeStreamEventListener, NodeStreamEventType } from './resources/node-stream.js';
+export { describeToolDefault, followActivity } from './resources/activity.js';
+export type { ActivityStep, DescribeTool } from './resources/activity.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export type { RuntimeVersionDetails } from './errors.js';
+export { SDK_VERSION } from './version.js';
+export { sdkErrorCodes } from './error-codes.js';
+export type { SdkErrorCode } from './error-codes.js';
+export type { AuthStatus, AuthStatusParams, CancelParams, EnsureProfileParams, JsonSchema, MessageParams, NodeCreateParams, NodeEventsOptions, NodeOutcomeOptions, OutputSchema, ParsedOutcome, RequestOptions, SchemaOutput, } from './types.js';
+export type * from '@north-light/api';

package/dist/index.js

@@ -0,0 +1,17 @@
+export { Crouter as default, Crouter } from './client.js';
+export { NodeStream } from './resources/node-stream.js';
+export { RunStream } from './resources/run-stream.js';
+export { CustomObjects } from './resources/custom-objects.js';
+export { RunReply } from './resources/run-reply.js';
+export { OAuth2Client, ConnectedCrouter, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refusalOf } from './oauth/index.js';
+export { RunWatcher } from './resources/run-watcher.js';
+export { GrantWatcher } from './resources/grant-watcher.js';
+export { generateKeyPair } from './oauth/keygen.js';
+export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
+export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { RUN_NOTICE_SCOPE, RunNoticeError, verifyRunNotice } from './resources/run-notice.js';
+export { describeToolDefault, followActivity } from './resources/activity.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export { SDK_VERSION } from './version.js';
+export { sdkErrorCodes } from './error-codes.js';

package/dist/keygen-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/keygen-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runKeygen } from './keygen-command.js';
+runKeygen(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/keygen-command.d.ts

@@ -0,0 +1,6 @@
+export interface KeygenOptions {
+    /** How long `crtr cloud apps keys add` may run before keygen gives up. */
+    crtrTimeoutMs?: number;
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export declare function runKeygen(argv: string[], options?: KeygenOptions): Promise<number>;

package/dist/keygen-command.js

@@ -0,0 +1,157 @@
+import { execFile } from 'node:child_process';
+import { mkdir, open, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { generateKeyPair } from './oauth/keygen.js';
+const USAGE = 'Usage: crouter-sdk keygen [--out <path>] [--app <client id>] [--yes]';
+const CRTR_TIMEOUT_MS = 60_000;
+function parseArgs(args) {
+    if (args[0] !== 'keygen')
+        throw new Error(USAGE);
+    const parsed = { path: 'local/app-key.json', yes: false };
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        if (seen.has(flag))
+            throw new Error(USAGE);
+        seen.add(flag);
+        if (flag === '--yes') {
+            parsed.yes = true;
+            continue;
+        }
+        const value = args[++i];
+        if ((flag !== '--out' && flag !== '--app') || !value || value.startsWith('--'))
+            throw new Error(USAGE);
+        if (flag === '--out')
+            parsed.path = value;
+        else
+            parsed.app = value;
+    }
+    return parsed;
+}
+const manualSteps = (path) => [
+    'Next, in this order:',
+    "  1. Add the public JWK printed on stdout as a key: click Add key on your app's Sign-in tab in the console, or paste it under Register an app for a new app. Adding a key never replaces your current one.",
+    `  2. Then point your app's privateKey at ${path} and deploy.`,
+    '  3. Once a real sign-in works, retire the old key on the Sign-in tab.',
+];
+const addedSteps = (path, app) => [
+    'Next, in this order:',
+    `  1. Point your app's privateKey at ${path} and deploy.`,
+    '  2. Check that a real sign-in works.',
+    `  3. Retire the old key: on the app's Sign-in tab, or \`crtr cloud apps keys retire --app-id ${app} --kid <old kid>\` (\`crtr cloud apps keys list --app-id ${app}\` shows the kids).`,
+];
+const seconds = (ms) => {
+    const n = Math.max(1, Math.round(ms / 1000));
+    return `${n} second${n === 1 ? '' : 's'}`;
+};
+const say = (lines) => console.error(lines.join('\n'));
+/** Asks on stderr; resolves true only for Enter or y/yes. End of input declines. */
+function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        let answered = false;
+        rl.on('close', () => { if (!answered) {
+            process.stderr.write('\n');
+            resolve(false);
+        } });
+        rl.question(`${question} `, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(/^(y|yes)?$/i.test(answer.trim()));
+        });
+    });
+}
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+};
+const lastLine = (text) => text.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+/** The `message` of a JSON error that ends `text`, even when other lines (a warning, a notice) precede it. */
+const errorMessage = (text) => {
+    const body = parseJson(text.slice(text.lastIndexOf('\n{') + 1));
+    return typeof body?.message === 'string' && body.message ? body.message : undefined;
+};
+/** Runs `crtr cloud apps keys add` once: execFile, no shell, the caller's environment. */
+function addKey(app, publicJwk, timeoutMs) {
+    const argv = ['cloud', 'apps', 'keys', 'add', '--app-id', app, '--jwk', publicJwk, '--json'];
+    return new Promise((resolve) => {
+        execFile('crtr', argv, { timeout: timeoutMs, env: process.env, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+            const err = error;
+            if (err?.code === 'ENOENT')
+                return resolve({ kind: 'missing' });
+            if (err) {
+                const message = err.killed
+                    ? `crtr did not answer within ${seconds(timeoutMs)}.`
+                    : errorMessage(stdout) ?? errorMessage(stderr) ?? lastLine(stderr) ?? lastLine(stdout) ?? err.message;
+                return resolve({ kind: 'failed', message });
+            }
+            const answer = parseJson(stdout);
+            if (typeof answer?.kid !== 'string') {
+                return resolve({ kind: 'failed', message: `crtr answered without the added key: ${lastLine(stdout) ?? '(no output)'}` });
+            }
+            resolve({ kind: 'added', kid: answer.kid, created: answer.created !== false });
+        });
+    });
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export async function runKeygen(argv, options = {}) {
+    const { path, app, yes } = parseArgs(argv);
+    await mkdir(dirname(path), { recursive: true });
+    // Reserve the destination before generating or printing the public key; never truncate an existing key.
+    const file = await open(path, 'wx', 0o600).catch((error) => {
+        if (error.code === 'EEXIST')
+            throw new Error(`${path} already exists. Delete it or pass --out to write somewhere else.`);
+        throw error;
+    });
+    let publicJwk;
+    let kid;
+    try {
+        const pair = await generateKeyPair();
+        await file.writeFile(`${JSON.stringify(pair.privateJwk)}\n`);
+        ({ publicJwk, kid } = pair);
+    }
+    catch (error) {
+        await file.close();
+        await unlink(path);
+        throw error;
+    }
+    await file.close();
+    const publicLine = JSON.stringify(publicJwk);
+    console.error(`Saved the private key to ${path} (key id ${kid}). Keep it out of git.`);
+    console.log(publicLine);
+    if (!app) {
+        say([...manualSteps(path), 'Tip: pass --app <client id> to add the key with crtr.']);
+        return 0;
+    }
+    if (!yes) {
+        if (!process.stdin.isTTY || !process.stderr.isTTY) {
+            say(['Not adding the key: no terminal to confirm. Pass --yes to add it with crtr.', ...manualSteps(path)]);
+            return 0;
+        }
+        if (!(await confirm(`Add this key to ${app} as an additional key? Your current key keeps working. [Y/n]`))) {
+            say(manualSteps(path));
+            return 0;
+        }
+    }
+    const outcome = await addKey(app, publicLine, options.crtrTimeoutMs ?? CRTR_TIMEOUT_MS);
+    if (outcome.kind === 'missing') {
+        say(["Couldn't find crtr, so the key was not added.", ...manualSteps(path)]);
+        return 0;
+    }
+    if (outcome.kind === 'failed') {
+        say([`Couldn't add the key: ${outcome.message}`, ...manualSteps(path)]);
+        return 2;
+    }
+    say([
+        outcome.created
+            ? `Added key ${outcome.kid} to ${app} as an additional key. Your current key still works.`
+            : `Key ${outcome.kid} is already on ${app}.`,
+        ...addedSteps(path, app),
+    ]);
+    return 0;
+}

package/dist/oauth/index.d.ts

@@ -0,0 +1,217 @@
+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;
+}
+/** 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'>);
+}
+export declare class OAuth2Client {
+    private readonly options;
+    private readonly issuer;
+    private readonly fetcher;
+    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
+     *  takes longer than 10 s rejects and is forgotten, so the next call reads again. */
+    private discovery;
+    /**
+     * 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>;
+    private tokenResponse;
+    private connectionFrom;
+    private post;
+}