@north-light/sdk 0.3.414 → 0.3.415

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.
 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 { OAuth2Client, ConnectedCrouter, DEFAULT_DIRECTORY_TIMEOUT_MS, 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';
@@ -32,8 +32,8 @@ export type { RunNotice, VerifyRunNoticeOptions } from './resources/run-notice.j
 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 { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, DeadlineExceededError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export type { DeadlineDetails, RuntimeVersionDetails } from './errors.js';
 export { SDK_VERSION } from './version.js';
 export { sdkErrorCodes } from './error-codes.js';
 export type { SdkErrorCode } from './error-codes.js';

package/dist/index.js

@@ -3,7 +3,7 @@ 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 { OAuth2Client, ConnectedCrouter, DEFAULT_DIRECTORY_TIMEOUT_MS, 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';
@@ -12,6 +12,6 @@ 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 { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, DeadlineExceededError, 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.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
+// The `crouter-sdk` bin: `keygen` and `env`. The file keeps its first command's name because the
+// published bin path (`dist/keygen-cli.js`) is part of the package.
+import { runEnv } from './env-command.js';
 import { runKeygen } from './keygen-command.js';
-runKeygen(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (error) => {
+const args = process.argv.slice(2);
+const run = args[0] === 'env' ? runEnv(args) : runKeygen(args);
+run.then((code) => { process.exitCode = code; }, (error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
 });

package/dist/keygen-command.js

@@ -1,10 +1,9 @@
-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 { CRTR_TIMEOUT_MS, notJoinedLines, parseJson, runCrtr, say } from './crtr.js';
 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);
@@ -41,11 +40,6 @@ const addedSteps = (path, app) => [
     '  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 });
@@ -62,41 +56,17 @@ function confirm(question) {
         });
     });
 }
-const parseJson = (text) => {
-    try {
-        return JSON.parse(text.trim());
-    }
-    catch {
-        return undefined;
+/** Runs `crtr cloud apps keys add` once. */
+async function addKey(app, publicJwk, timeoutMs) {
+    const outcome = await runCrtr(['cloud', 'apps', 'keys', 'add', '--app-id', app, '--jwk', publicJwk, '--json'], timeoutMs);
+    if (outcome.kind !== 'ok')
+        return outcome;
+    const answer = parseJson(outcome.stdout);
+    if (typeof answer?.kid !== 'string') {
+        const last = outcome.stdout.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+        return { kind: 'failed', message: `crtr answered without the added key: ${last ?? '(no output)'}` };
     }
-};
-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 });
-        });
-    });
+    return { 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 = {}) {
@@ -143,6 +113,10 @@ export async function runKeygen(argv, options = {}) {
         say(["Couldn't find crtr, so the key was not added.", ...manualSteps(path)]);
         return 0;
     }
+    if (outcome.kind === 'not_joined') {
+        say([...notJoinedLines('the key was not added', outcome.joinStep), ...manualSteps(path)]);
+        return 2;
+    }
     if (outcome.kind === 'failed') {
         say([`Couldn't add the key: ${outcome.message}`, ...manualSteps(path)]);
         return 2;

package/dist/oauth/index.d.ts

@@ -94,6 +94,15 @@ export interface OAuth2Options {
     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. */
@@ -104,10 +113,13 @@ export declare class ConnectedCrouter extends Crouter {
     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?;
@@ -117,8 +129,13 @@ export declare class OAuth2Client {
     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. */
+     *  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.
@@ -211,6 +228,7 @@ export declare class OAuth2Client {
         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;

package/dist/oauth/index.js

@@ -1,7 +1,9 @@
 import { calculateJwkThumbprint, decodeJwt, decodeProtectedHeader, exportJWK, importJWK, importPKCS8, SignJWT } from 'jose';
-import { JwksCache, parseScope, verifyIdToken } from '@north-light/identity';
+import { boundedFetch, FetchDeadlineError, JwksCache, parseScope, verifyIdToken } from '@north-light/identity';
+import { deadlineExceeded, sleepWithin } from '@north-light/api';
 import { APIError, CrouterError, mapError } from '../errors.js';
 import { Crouter } from '../client.js';
+import { withinDeadline } from '../resources/request.js';
 import { RunWatcher } from '../resources/run-watcher.js';
 import { GrantWatcher } from '../resources/grant-watcher.js';
 import { attachRefusal, isRefusalCode, refusalKindOf } from './refusal.js';
@@ -73,8 +75,8 @@ export class ConnectedCrouter extends Crouter {
         this.runtimeUrl = connection.runtimeUrl;
     }
 }
-/** How long one discovery read may take before it rejects (and is forgotten). */
-const DISCOVERY_TIMEOUT_MS = 10_000;
+/** The default deadline of one directory operation (`OAuth2Options.timeoutMs`): a discovery read is forgotten when it passes. */
+export const DEFAULT_DIRECTORY_TIMEOUT_MS = 10_000;
 const assertionType = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
 let refusalScope;
 function handlerScope() {
@@ -88,6 +90,7 @@ export class OAuth2Client {
     options;
     issuer;
     fetcher;
+    timeoutMs;
     store;
     jwks;
     discoveryPromise;
@@ -104,20 +107,22 @@ export class OAuth2Client {
         this.issuer = options.issuer;
         this.store = options.store;
         this.fetcher = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_DIRECTORY_TIMEOUT_MS;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0 || this.timeoutMs > 2_147_483_647)
+            throw new CrouterError('OAuth2Options.timeoutMs must be a positive finite number of at most 2147483647');
     }
     /** 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. */
+     *  passes the deadline (`timeoutMs`) 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;
+            const value = await this.bounded(`${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`, {}, Date.now() + this.timeoutMs, async (response) => {
+                if (!response.ok)
+                    throw new CrouterError(`Directory discovery failed: ${response.status}`);
+                return await response.json();
+            });
+            return parseDiscovery(value, this.issuer);
         })();
         this.discoveryPromise = read;
         // Only this read's own failure clears the memo, never a newer read started after it.
@@ -125,6 +130,27 @@ export class OAuth2Client {
             this.discoveryPromise = undefined; });
         return read;
     }
+    /** One directory request and the reading of its answer under `deadlineAt`; a deadline rejects `DeadlineExceededError`. */
+    async bounded(url, init, deadlineAt, read) {
+        try {
+            return await boundedFetch(this.fetcher, url, init, { deadlineAt }, read);
+        }
+        catch (error) {
+            if (error instanceof FetchDeadlineError)
+                throw mapError(deadlineExceeded(error.deadlineAt));
+            throw error;
+        }
+    }
+    /** 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. */
+    async discoveryWithin(deadlineAt) {
+        try {
+            return await withinDeadline(this.discovery(), deadlineAt);
+        }
+        catch (error) {
+            throw error instanceof APIError ? mapError(error) : error;
+        }
+    }
     /**
      * 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.
@@ -284,8 +310,10 @@ export class OAuth2Client {
             if (stored.refreshToken !== connection.refreshToken)
                 return { kind: 'current', connection: stored };
             let response;
+            // The refresh's one deadline starts here, with the lock held, so the lock is held no longer than `timeoutMs`
+            // for the discovery read, the signing and the token request together (plus the store's own time).
             try {
-                response = await this.tokenResponse({ grant_type: 'refresh_token', refresh_token: stored.refreshToken });
+                response = await this.tokenResponse({ grant_type: 'refresh_token', refresh_token: stored.refreshToken }, Date.now() + this.timeoutMs);
             }
             catch (error) {
                 if (error instanceof APIError && error.origin === 'directory' && isRefusalCode(error.code))
@@ -376,8 +404,10 @@ export class OAuth2Client {
     }
     /** 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);
+        // One deadline for the operation: the discovery read and the key-set read share it.
+        const deadlineAt = Date.now() + this.timeoutMs;
+        const discovery = await this.discoveryWithin(deadlineAt);
+        this.jwks ??= new JwksCache(this.issuer, this.fetcher, discovery.jwks_uri, { timeoutMs: this.timeoutMs });
         const invalid = (reason) => new CrouterError(`ID token failed verification: ${reason}`, 'id_token_invalid');
         try {
             decodeProtectedHeader(idToken);
@@ -387,7 +417,7 @@ export class OAuth2Client {
         }
         let claims;
         try {
-            claims = await verifyIdToken({ token: idToken, jwks: this.jwks, issuer: this.issuer, audience: this.options.clientId });
+            claims = await withinDeadline(verifyIdToken({ token: idToken, jwks: this.jwks, issuer: this.issuer, audience: this.options.clientId }), deadlineAt);
         }
         catch (error) {
             // A token that fails verification is id_token_invalid; a JWKS that cannot be fetched or is malformed is the
@@ -396,6 +426,10 @@ export class OAuth2Client {
             // 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);
+            if (error instanceof FetchDeadlineError)
+                throw mapError(deadlineExceeded(error.deadlineAt));
+            if (error instanceof APIError)
+                throw mapError(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);
@@ -406,17 +440,19 @@ export class OAuth2Client {
         return claims;
     }
     async revoke(connection) {
-        const metadata = await this.discovery();
+        const deadlineAt = Date.now() + this.timeoutMs;
+        const metadata = await this.discoveryWithin(deadlineAt);
         if (!metadata.revocation_endpoint)
             return false;
-        await this.post(metadata.revocation_endpoint, { token: connection.refreshToken, token_type_hint: 'refresh_token' }, true);
+        await this.post(metadata.revocation_endpoint, { token: connection.refreshToken, token_type_hint: 'refresh_token' }, true, deadlineAt);
         return true;
     }
-    async tokenResponse(params) {
-        const metadata = await this.discovery();
+    /** A token request. `deadlineAt` is the whole operation's deadline (discovery included); without one it starts now. */
+    async tokenResponse(params, deadlineAt = Date.now() + this.timeoutMs) {
+        const metadata = await this.discoveryWithin(deadlineAt);
         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);
+        return await this.post(metadata.token_endpoint, params, false, deadlineAt);
     }
     connectionFrom(response, previous) {
         if (typeof response.access_token !== 'string' || typeof response.refresh_token !== 'string')
@@ -434,7 +470,7 @@ export class OAuth2Client {
             ...(idToken ? { idToken } : {}),
         };
     }
-    async post(endpoint, values, revocation = false) {
+    async post(endpoint, values, revocation = false, deadlineAt = Date.now() + this.timeoutMs) {
         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');
@@ -455,19 +491,24 @@ export class OAuth2Client {
             imported = await importJWK(key, alg);
         }
         const kid = this.options.keyId ?? (typeof key === 'string' ? undefined : key.kid);
+        // `deadlineAt` is the whole operation's: discovery, signing, every attempt, the reading of each answer and each retry wait.
         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, {
+            const answer = await this.bounded(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 }),
+            }, deadlineAt, async (response) => {
+                if (revocation && response.ok)
+                    return { response, payload: undefined };
+                return { response, payload: await response.json() };
             });
+            const { response, payload } = answer;
             if (revocation && response.ok)
                 return undefined;
-            const payload = await response.json();
             if (response.ok)
                 return payload;
             const refusal = payload;
@@ -479,8 +520,13 @@ export class OAuth2Client {
             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));
+                // A Retry-After longer than the time left fails now (DeadlineExceededError) instead of sleeping past the deadline.
+                try {
+                    await sleepWithin(500 * 2 ** attempt * (0.5 + Math.random()), { deadlineAt }, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : undefined);
+                }
+                catch (stop) {
+                    throw stop instanceof APIError ? mapError(stop) : stop;
+                }
                 continue;
             }
             const message = refusal.error_description ?? refusal.error ?? 'Directory token request failed';
@@ -513,6 +559,46 @@ async function describeSigningKey(key, kid) {
     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}` };
 }
+/** The discovery JSON as a `Discovery`, or `CrouterError` naming the field that is wrong. `authorization_endpoint`,
+ *  `token_endpoint` and `jwks_uri` must be absolute `https:` URLs (`http:` when the issuer itself is `http:`, for a
+ *  local directory); `revocation_endpoint`, when present, likewise; `token_endpoint_auth_methods_supported`, when
+ *  present, an array of strings. Which origin an endpoint may sit on is not restricted: the directory chooses it. */
+function parseDiscovery(value, issuer) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new CrouterError('Directory discovery is not a JSON object');
+    const record = value;
+    const allowHttp = new URL(issuer).protocol === 'http:';
+    const endpoint = (name) => {
+        const field = record[name];
+        if (field === undefined || field === null || field === '')
+            throw new CrouterError('Directory discovery has missing endpoints');
+        if (typeof field !== 'string')
+            throw new CrouterError(`Directory discovery's ${name} must be a URL string`);
+        let url;
+        try {
+            url = new URL(field);
+        }
+        catch {
+            throw new CrouterError(`Directory discovery's ${name} is not an absolute URL`);
+        }
+        if (url.protocol !== 'https:' && !(allowHttp && url.protocol === 'http:'))
+            throw new CrouterError(`Directory discovery's ${name} must be an https URL`);
+        return field;
+    };
+    const methods = record['token_endpoint_auth_methods_supported'];
+    if (methods !== undefined && (!Array.isArray(methods) || methods.some((method) => typeof method !== 'string'))) {
+        throw new CrouterError("Directory discovery's token_endpoint_auth_methods_supported must be an array of strings");
+    }
+    const template = record['account_app_uri_template'];
+    return {
+        authorization_endpoint: endpoint('authorization_endpoint'),
+        token_endpoint: endpoint('token_endpoint'),
+        jwks_uri: endpoint('jwks_uri'),
+        ...(record['revocation_endpoint'] === undefined || record['revocation_endpoint'] === null ? {} : { revocation_endpoint: endpoint('revocation_endpoint') }),
+        ...(methods === undefined ? {} : { token_endpoint_auth_methods_supported: methods }),
+        ...(typeof template === 'string' ? { account_app_uri_template: template } : {}),
+    };
+}
 function notConnected(userId) {
     return new CrouterError(`No stored connection for ${userId}: they must sign in with crouter cloud again`, 'not_connected');
 }

package/dist/resources/request.d.ts

@@ -5,3 +5,8 @@ export declare function withQuery(path: string, query: object | undefined): stri
  *  request timeout by the hold, so the timeout bounds the answer rather than the wait. Shared by `runs.get` and
  *  `grant.get`. */
 export declare function heldReadOptions(wait: number | undefined, options: RequestOptions): RequestOptions;
+/** The call's one deadline, fixed at call start: `budgetMs` from now and/or `deadlineAt`, whichever is earlier, as
+ *  `deadlineAt` (so a retry after a 401 and every transport attempt share it). Options without either pass through. */
+export declare function deadline(options: RequestOptions | undefined): RequestOptions | undefined;
+/** `promise`, or `deadline_exceeded` once `deadlineAt` passes first. */
+export declare function withinDeadline<T>(promise: Promise<T>, deadlineAt: number | undefined): Promise<T>;

package/dist/resources/request.js

@@ -1,3 +1,4 @@
+import { deadlineExceeded, MAX_TIMER_MS } from '@north-light/api';
 export function withQuery(path, query) {
     if (query === undefined)
         return path;
@@ -17,3 +18,33 @@ export function heldReadOptions(wait, options) {
         throw new RangeError('wait must be 1–25 seconds');
     return wait ? { ...options, timeout: (options.timeout ?? 30_000) + wait * 1_000 } : options;
 }
+/** The call's one deadline, fixed at call start: `budgetMs` from now and/or `deadlineAt`, whichever is earlier, as
+ *  `deadlineAt` (so a retry after a 401 and every transport attempt share it). Options without either pass through. */
+export function deadline(options) {
+    if (options === undefined || (options.budgetMs === undefined && options.deadlineAt === undefined))
+        return options;
+    const { budgetMs, deadlineAt, ...rest } = options;
+    if (budgetMs !== undefined && (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > MAX_TIMER_MS))
+        throw new RangeError(`budgetMs must be a positive finite number of at most ${MAX_TIMER_MS}`);
+    if (deadlineAt !== undefined && (!Number.isFinite(deadlineAt) || deadlineAt - Date.now() > MAX_TIMER_MS))
+        throw new RangeError(`deadlineAt must be a finite epoch-millisecond instant at most ${MAX_TIMER_MS} ms from now`);
+    return { ...rest, deadlineAt: Math.min(deadlineAt ?? Infinity, budgetMs === undefined ? Infinity : Date.now() + budgetMs) };
+}
+/** `promise`, or `deadline_exceeded` once `deadlineAt` passes first. */
+export async function withinDeadline(promise, deadlineAt) {
+    if (deadlineAt === undefined)
+        return promise;
+    const remaining = deadlineAt - Date.now();
+    if (remaining <= 0) {
+        promise.catch(() => { });
+        throw deadlineExceeded(deadlineAt);
+    }
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_resolve, reject) => { timer = setTimeout(() => reject(deadlineExceeded(deadlineAt)), remaining); })]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/resources/runs.d.ts

@@ -150,6 +150,13 @@ export declare class Runs {
         start_turn?: boolean;
         idempotencyKey?: string;
     }): Promise<SentRunMessage>;
+    /** A keyed POST under one overall deadline. `budgetMs` / `deadlineAt` (fixed here, once) bound every attempt, every
+     *  backoff and every `retry_after_s` wait together, so the call never outlasts its deadline: an application lease
+     *  taken for the call needs only to exceed that deadline. A server `retry_after_s` is honored only when it fits the
+     *  time left; otherwise the call rejects at once with `DeadlineExceededError` (`reason: 'retry_after'`), carrying
+     *  the refusal as `cause`, rather than sleeping past the deadline. A send without a deadline keeps the capped
+     *  backoff and honors any `retry_after_s`. */
+    private keyedSend;
     interrupt(runId: string, options?: RequestOptions & {
         children?: 'stop' | 'continue';
     }): Promise<RunObject>;

package/dist/resources/runs.js

@@ -1,8 +1,9 @@
-import { APIError } from '../errors.js';
+import { sleepWithin } from '@north-light/api';
+import { APIError, mapError } from '../errors.js';
 import { RunStream } from './run-stream.js';
 import { RunReply } from './run-reply.js';
 import { resolveJsonSchema } from '../schema.js';
-import { heldReadOptions } from './request.js';
+import { deadline, heldReadOptions } from './request.js';
 export class Runs {
     request;
     openEvents;
@@ -15,16 +16,7 @@ export class Runs {
     async start(params, options = {}) {
         const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, ...rest } = options;
         const body = params.output_schema === undefined ? params : { ...params, output_schema: resolveJsonSchema(params.output_schema) };
-        for (let attempt = 0;; attempt++) {
-            try {
-                return await this.request('POST', '/v1/runs', body, { ...rest, maxRetries: 0, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } });
-            }
-            catch (error) {
-                if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
-                    throw error;
-                await pause(error.retryAfterS ? error.retryAfterS * 1_000 : 500 * 2 ** attempt, rest.signal);
-            }
-        }
+        return this.keyedSend('/v1/runs', body, idempotencyKey, maxRetries, rest);
     }
     get(runId, options = {}) {
         const { wait, ...rest } = options;
@@ -63,14 +55,38 @@ export class Runs {
         const body = { message, ...(start_turn === undefined ? {} : { start_turn }) };
         // One key per logical send, reused on every retry: the daemon answers a repeat with the first send's
         // result, so a retry after a lost response cannot deliver the message twice.
+        return this.keyedSend(`${runPath(runId)}/messages`, body, idempotencyKey, maxRetries, rest);
+    }
+    /** A keyed POST under one overall deadline. `budgetMs` / `deadlineAt` (fixed here, once) bound every attempt, every
+     *  backoff and every `retry_after_s` wait together, so the call never outlasts its deadline: an application lease
+     *  taken for the call needs only to exceed that deadline. A server `retry_after_s` is honored only when it fits the
+     *  time left; otherwise the call rejects at once with `DeadlineExceededError` (`reason: 'retry_after'`), carrying
+     *  the refusal as `cause`, rather than sleeping past the deadline. A send without a deadline keeps the capped
+     *  backoff and honors any `retry_after_s`. */
+    async keyedSend(path, body, idempotencyKey, maxRetries, rest) {
+        const options = deadline(rest) ?? rest;
         for (let attempt = 0;; attempt++) {
             try {
-                return await this.request('POST', `${runPath(runId)}/messages`, body, { ...rest, maxRetries: 0, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } });
+                return await this.request('POST', path, body, { ...options, maxRetries: 0, headers: { ...options.headers, 'Idempotency-Key': idempotencyKey } });
             }
             catch (error) {
                 if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
                     throw error;
-                await pause(error.retryAfterS ? error.retryAfterS * 1_000 : 500 * 2 ** attempt, rest.signal);
+                // The server's wait is honored only against a deadline (sleepWithin refuses a wait longer than the time
+                // left); with none, the plain backoff applies and a Retry-After is waited as before.
+                const waitS = error.retryAfterS;
+                try {
+                    if (options.deadlineAt === undefined)
+                        await pause(waitS ? waitS * 1_000 : 500 * 2 ** attempt, options.signal);
+                    else
+                        await sleepWithin(500 * 2 ** attempt, { deadlineAt: options.deadlineAt, signal: options.signal }, waitS, error);
+                }
+                catch (stop) {
+                    // An abort during the wait rejects with the signal's own reason, as `pause` does.
+                    if (options.signal?.aborted)
+                        throw options.signal.reason;
+                    throw stop instanceof APIError ? mapError(stop) : stop;
+                }
             }
         }
     }
@@ -120,9 +136,11 @@ export class Runs {
     /** Long-polls `runs.get` until the run is `settled`, `waiting_on_user`, or `idle`, and returns that response
      *  unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
     async wait(runId, options = {}) {
-        return abortable(options.signal, async () => {
+        // One deadline for the whole wait: every poll shares it instead of restarting `budgetMs`.
+        const bounded = deadline(options) ?? options;
+        return abortable(bounded.signal, async () => {
             for (;;) {
-                const result = await this.get(runId, { ...options, wait: 25 });
+                const result = await this.get(runId, { ...bounded, wait: 25 });
                 if (result.status === 'settled' || result.status === 'waiting_on_user' || result.status === 'idle')
                     return result;
             }
@@ -133,7 +151,9 @@ export class Runs {
      *  `APIError` code `waiting_on_user`. A run that stops without settling rejects `run_idle` (untouched:
      *  send `runs.message` or `runs.cancel`). Aborting `signal` rejects with its reason; the run is never canceled. */
     async parse(params, options = {}) {
-        const { onQuestion, idempotencyKey, ...rest } = options;
+        const { onQuestion, idempotencyKey, ...unbounded } = options;
+        // One deadline for the start, every poll and every answer.
+        const rest = deadline(unbounded) ?? unbounded;
         return abortable(rest.signal, () => this.parseRun(params, onQuestion, idempotencyKey, rest));
     }
     async parseRun(params, onQuestion, idempotencyKey, rest) {

package/dist/testing/clock.d.ts

@@ -0,0 +1,7 @@
+/** A clock a test steps by hand: `now()` returns the same instant until `advance(ms)` moves it. */
+export interface ManualClock {
+    now(): number;
+    advance(ms: number): void;
+}
+/** A `ManualClock` starting at `startMs` (default 2026-01-01T00:00:00Z). Pass it to `FakeCloud` as `clock`. */
+export declare function manualClock(startMs?: number): ManualClock;

package/dist/testing/clock.js

@@ -0,0 +1,12 @@
+/** A `ManualClock` starting at `startMs` (default 2026-01-01T00:00:00Z). Pass it to `FakeCloud` as `clock`. */
+export function manualClock(startMs = Date.UTC(2026, 0, 1)) {
+    let current = startMs;
+    return {
+        now: () => current,
+        advance(ms) {
+            if (!Number.isFinite(ms) || ms < 0)
+                throw new RangeError(`advance needs a non-negative number of ms, got ${ms}`);
+            current += ms;
+        },
+    };
+}