@crouter/sdk 0.3.393 → 0.3.395

package/README.md

@@ -145,7 +145,7 @@ console.log(source.content, command.exit_code);
 
 ## PostgreSQL connection store (Node)
 
-For a multi-process OAuth app, install `pg` in the app (`npm install pg`) and import the optional `@crouter/sdk/stores/postgres` subpath; the SDK's main entry never loads `pg`. `new PostgresConnectionStore(pool, { table: 'connection' })` implements `load`, `save`, `lock`, and `listStale(before: Date)`. Use one shared database and the same table for all workers. The lock keeps one PostgreSQL transaction and client open across the entire refresh callback (including the token request), so provision the pool for concurrent refreshes and avoid a transaction timeout shorter than the request. The table name accepts one or two lowercase SQL identifiers (schema.table), never SQL fragments.
+For a multi-process OAuth app, install `pg` in the app (`npm install pg`) and import the optional `@crouter/sdk/stores/postgres` subpath; the SDK's main entry never loads `pg`. `new PostgresConnectionStore(pool, { table: 'connection' })` implements `load`, `save`, `lock`, `remove(userId, refreshToken)`, and `listStale(before: Date)`. Pass it as `new OAuth2Client({..., store})`. Use one shared database and the same table for all workers. The lock keeps one PostgreSQL transaction and client open across the entire refresh callback (including the token request), so provision the pool for concurrent refreshes and avoid a transaction timeout shorter than the request. The table name accepts one or two lowercase SQL identifiers (schema.table), never SQL fragments.
 
 Create the table before using the store (or adapt this schema in your migration):
 
@@ -163,7 +163,7 @@ CREATE TABLE connection (
 CREATE INDEX connection_updated_at_idx ON connection (updated_at, user_id);
 ```
 
-`save` upserts all fields and sets `updated_at` to the database clock. `listStale(before)` selects connections with `updated_at < before`, oldest first; it is a **last save** timestamp, not necessarily last successful refresh if an app also calls `save` for another reason. For idle-token maintenance, schedule `oauth.refreshIdleConnections(store, {olderThanMs: 30 * 24 * 60 * 60 * 1000})` (for example, daily). It selects stale connections, refreshes under the store lock, reloads there to avoid rotating an already-used token, saves a rotated connection, and reports `{refreshed, failures}` for the worker to inspect; each failure's `reason` is `refreshRefusal(error)`. `refreshRefusal(error)` classifies any refused refresh as `'removed'` (`grant_removed`: the runtime deleted the app's runs; delete what you store for the person), `'paused'` (`grant_suspended`: nothing was deleted; keep the data until they sign in again), `'reconnect'` (`refresh_token_expired`, `refresh_token_reused`, `grant_revoked`: nothing was deleted; ask them to sign in again), or `null` when the error is not the directory refusing a refresh. Load the signing key `crouter-sdk keygen` wrote with `privateKey: await privateKeyFromFile('local/app-key.json')` (Node), or check one from an environment variable with `parsePrivateJwk(text)`; both refuse anything but a private JWK with a `kid`. The SDK does not start a timer. `listStale` returns connections, not timestamps, so a worker needing a strict cutoff recheck must maintain that policy separately. The table contains credentials: restrict database access, encrypt backups, and delete a row when its user disconnects. PostgreSQL `timestamptz` must be returned as a JavaScript `Date` (the `pg` default parser).
+`save` upserts all fields and sets `updated_at` to the database clock. `listStale(before)` selects connections with `updated_at < before`, oldest first; it is a **last save** timestamp, not necessarily last successful refresh if an app also calls `save` for another reason. For idle-token maintenance, schedule `oauth.refreshIdleConnections({olderThanMs: 30 * 24 * 60 * 60 * 1000})` (for example, daily). It selects stale connections, refreshes under the store lock, reloads there to avoid rotating an already-used token, saves a rotated connection, and reports `{refreshed, refused, failures}`. A connection the directory refuses goes to the client's `onRefusal(refusal)` and is then removed (`remove` deletes the row only while it still holds the refused token); `refusal.kind` is `'removed'` (`grant_removed`: the runtime deleted the app's runs; delete what you store for the person), `'paused'` (`grant_suspended`: nothing was deleted; keep the data until they sign in again), or `'reconnect'` (`refresh_token_expired`, `refresh_token_reused`, `grant_revoked`: nothing was deleted; ask them to sign in again). `refusalOf(error)` returns the same `Refusal` from a refused call's error. Load the signing key `crouter-sdk keygen` wrote with `privateKey: await privateKeyFromFile('local/app-key.json')` (Node), or check one from an environment variable with `parsePrivateJwk(text)`; both refuse anything but a private JWK with a `kid`. The SDK does not start a timer. `listStale` returns connections, not timestamps, so a worker needing a strict cutoff recheck must maintain that policy separately. The table contains credentials: restrict database access, encrypt backups, and delete a row when its user disconnects. PostgreSQL `timestamptz` must be returned as a JavaScript `Date` (the `pg` default parser).
 
 ## Example application
 

package/dist/error-codes.d.ts

@@ -2,6 +2,6 @@ export { errorCodes } from '@crouter/api';
 export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from '@crouter/api';
 export { mapError } from './errors.js';
 /** Codes the SDK raises itself rather than reading from a daemon or directory response. */
-export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "runtime_version_unsupported", "invalid_response", "stream_error", "stream_ended"];
+export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "not_connected", "refusal_handler_reentry", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "runtime_version_unsupported", "invalid_response", "stream_error", "stream_ended"];
 /** A code the SDK raises itself. An `APIError`'s `code` is one of these or an `ErrorCode` from the contract. */
 export type SdkErrorCode = typeof sdkErrorCodes[number];

package/dist/error-codes.js

@@ -13,6 +13,10 @@ export const sdkErrorCodes = [
     'oauth_state_mismatch',
     /** `exchangeCode` got a sign-in-only answer, or `exchangeIdentity` got one carrying a connection. */
     'oauth_exchange_mismatch',
+    /** `oauth.client(userId)` or `refresh` found no stored connection for the person: they must sign in again. */
+    'not_connected',
+    /** `onRefusal` called `oauth.client` (or `refresh`) for the user whose dead connection it is handling. */
+    'refusal_handler_reentry',
     /** `runs.parse`: the run stopped without settling. */
     'run_idle',
     /** `runs.parse`: the run waits on a question and no `onQuestion` was given. */

package/dist/index.d.ts

@@ -15,9 +15,11 @@ 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, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
-export { refreshRefusal } from './oauth/index.js';
-export type { RefreshFailure, RefreshRefusal } from './oauth/index.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, RunEnded, RunEnding, RunWatchOptions } from './resources/run-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';

package/dist/index.js

@@ -3,8 +3,9 @@ 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, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
-export { refreshRefusal } from './oauth/index.js';
+export { OAuth2Client, ConnectedCrouter, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refusalOf } from './oauth/index.js';
+export { RunWatcher } from './resources/run-watcher.js';
 export { generateKeyPair } from './oauth/keygen.js';
 export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
 export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';

package/dist/oauth/index.d.ts

@@ -1,24 +1,15 @@
 import { type JWK } from 'jose';
 import { type IdTokenClaims } from '@crouter/identity';
-import { Crouter } from '../client.js';
-/**
- * Why the directory refused a connection's refresh token, and what it 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; drop the dead connection and ask them to sign in again.
- */
-export type RefreshRefusal = 'removed' | 'paused' | 'reconnect';
-/** What a refused refresh means (`RefreshRefusal`), or `null` when `error` is not the directory refusing one.
- *  Takes any error a connected client or `refresh` threw; only `APIError` with `origin: 'directory'` counts. */
-export declare function refreshRefusal(error: unknown): RefreshRefusal | null;
-/** One connection `refreshIdleConnections` could not refresh. `reason` is `refreshRefusal(error)`. */
+import { Crouter, type CrouterOptions } from '../client.js';
+import { RunWatcher, type RunWatchOptions } from '../resources/run-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;
-    reason: RefreshRefusal | null;
 }
 export interface Connection {
     userId: string;
@@ -32,17 +23,26 @@ export interface Connection {
 export interface ConnectionStore {
     load(userId: string): Promise<Connection | null>;
     save(connection: Connection): Promise<void>;
-    lock?<T>(userId: string, fn: () => Promise<T>): Promise<T>;
+    /** 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>;
 }
 /**
@@ -76,15 +76,44 @@ export interface OAuth2Options {
     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);
     private discovery;
     /** 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`.
@@ -126,16 +155,41 @@ export declare class OAuth2Client {
         expectedState: string;
         nonce: string;
     }): Promise<Identity>;
-    /** Refresh a store's idle connections once. The app owns scheduling; failures remain visible to its worker,
-     *  each with `reason` set when the directory refused that connection's refresh (see `RefreshRefusal`). */
-    refreshIdleConnections(store: ConnectionStore, { olderThanMs }: {
+    /**
+     * 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[];
     }>;
-    refresh(connection: Connection, store?: ConnectionStore): Promise<Connection>;
-    client(connection: Connection, store: ConnectionStore): Crouter;
+    /**
+     * 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;
     /** 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;

package/dist/oauth/index.js

@@ -2,19 +2,10 @@ import { calculateJwkThumbprint, decodeJwt, decodeProtectedHeader, exportJWK, im
 import { JwksCache, parseScope, verifyIdToken } from '@crouter/identity';
 import { APIError, CrouterError, mapError } from '../errors.js';
 import { Crouter } from '../client.js';
-/** Refresh refusals the app must answer by reconnecting; each latches the connected client (SDK-AUTH-17). */
-const reconnectCodes = new Set(['grant_revoked', 'grant_removed', 'grant_suspended', 'refresh_token_expired', 'refresh_token_reused']);
-const refusals = {
-    grant_removed: 'removed', grant_suspended: 'paused',
-    refresh_token_expired: 'reconnect', refresh_token_reused: 'reconnect', grant_revoked: 'reconnect',
-};
-/** What a refused refresh means (`RefreshRefusal`), or `null` when `error` is not the directory refusing one.
- *  Takes any error a connected client or `refresh` threw; only `APIError` with `origin: 'directory'` counts. */
-export function refreshRefusal(error) {
-    if (!(error instanceof APIError) || error.origin !== 'directory')
-        return null;
-    return Object.hasOwn(refusals, error.code) ? refusals[error.code] : null;
-}
+import { RunWatcher } from '../resources/run-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();
@@ -24,9 +15,17 @@ export class MemoryConnectionStore {
         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;
@@ -60,19 +59,47 @@ function httpsUrl(value) {
         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;
+    }
+}
 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;
     }
     discovery() {
@@ -157,73 +184,151 @@ export class OAuth2Client {
             claims,
         };
     }
-    /** Refresh a store's idle connections once. The app owns scheduling; failures remain visible to its worker,
-     *  each with `reason` set when the directory refused that connection's refresh (see `RefreshRefusal`). */
-    async refreshIdleConnections(store, { olderThanMs }) {
-        if (!store.listStale)
+    /**
+     * 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 store.listStale(new Date(Date.now() - olderThanMs));
+        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, store);
+                const current = await this.refresh(connection);
                 if (current.refreshToken !== connection.refreshToken)
                     refreshed++;
             }
             catch (error) {
-                failures.push({ userId: connection.userId, error, reason: refreshRefusal(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, failures };
+        return { refreshed, refused, failures };
     }
-    async refresh(connection, store) {
-        const existing = this.inFlight.get(connection.userId);
+    /**
+     * 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 rotate = async () => {
-            const stored = await store?.load(connection.userId);
-            if (stored && stored.refreshToken !== connection.refreshToken)
-                return stored;
-            const updated = this.connectionFrom(await this.tokenResponse({ grant_type: 'refresh_token', refresh_token: connection.refreshToken }), connection);
-            await store?.save(updated);
-            return updated;
-        };
-        const pending = store?.lock ? store.lock(connection.userId, rotate) : rotate();
-        this.inFlight.set(connection.userId, pending);
+        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 {
-            return await pending;
+            await this.store.lock(userId, () => this.store.remove(userId, stored.refreshToken));
         }
-        finally {
-            this.inFlight.delete(connection.userId);
+        catch (removeError) {
+            Object.defineProperty(error, 'cause', { value: removeError, configurable: true, writable: true });
+            throw error;
         }
+        this.settled.add(error);
+        throw error;
     }
-    client(connection, store) {
+    /**
+     * 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 revoked;
+        let refused;
         const refresh = async (force) => {
-            if (revoked)
-                throw revoked;
+            if (refused)
+                throw refused;
             if (!force && current.accessToken && current.accessTokenExpiresAt - Date.now() > 30_000)
                 return;
             try {
-                current = await this.refresh(current, store);
+                current = await this.refresh(current);
             }
             catch (error) {
-                if (error instanceof APIError && reconnectCodes.has(error.code))
-                    revoked = error;
+                if (error instanceof APIError && this.settled.has(error))
+                    refused = error;
                 throw error;
             }
         };
-        return new Crouter({
-            baseURL: connection.runtimeUrl,
+        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);
+    }
     /** 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();
@@ -324,9 +429,9 @@ export class OAuth2Client {
             // 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' || reconnectCodes.has(description) ? description : 'grant_revoked'
+                ? description === 'runtime_provisioning' || isRefusalCode(description) ? description : 'grant_revoked'
                 : refusal.error === 'invalid_client' ? 'unauthorized' : 'invalid_request';
-            const reconnect = reconnectCodes.has(code);
+            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());
@@ -363,6 +468,14 @@ 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}` };
 }
+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)

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;
+}

package/dist/resources/run-watcher.d.ts

@@ -0,0 +1,86 @@
+import type { Crouter } from '../client.js';
+import type { RunObject } from './runs.js';
+/** A run the app is still waiting on: whose runtime holds it, and its id. `pending()` returns these from the app's own rows. */
+export interface PendingRun {
+    userId: string;
+    runId: string;
+}
+/** How a watched run came to rest. `gone`: the runtime answered 404 `not_found` for it (the run was deleted). */
+export type RunEnding = 'settled' | 'idle' | 'waiting_on_user' | 'gone';
+/** One ending `RunWatcher` hands to `onEnded`. `run` is the `runs.get` answer that came to rest, or `null` when `gone`. */
+export type RunEnded = {
+    userId: string;
+    runId: string;
+    ended: Exclude<RunEnding, 'gone'>;
+    run: RunObject;
+} | {
+    userId: string;
+    runId: string;
+    ended: 'gone';
+    run: null;
+};
+export interface RunWatchOptions {
+    /** Every run the app still waits on, read from its own rows (the durable record). Called at `start()`, every
+     *  `sweepMs`, after each delivery, and on `nudge()`. Stop returning a run once `onEnded` has landed it. */
+    pending: () => Promise<PendingRun[]> | PendingRun[];
+    /** Land one ending. At least once per `(runId, status, latest_sequence)`: make it idempotent (guard the write on
+     *  the row still waiting on that run). If it throws, the same ending is retried after 5 s, doubling to 5 min. */
+    onEnded: (event: RunEnded) => Promise<void> | void;
+    /** Told about every failure the watcher recovers from itself: a throwing `pending()` or `onEnded`, a transient
+     *  runtime error, a missing (`not_connected`) or refused connection. Defaults to ignoring them. */
+    onError?: (error: unknown, run: PendingRun | null) => void;
+    /** Milliseconds between sweeps of `pending()`. Default 30 000. */
+    sweepMs?: number;
+    /** Most runs followed with an open long-poll at once. Default 50; the rest wait their turn. */
+    concurrency?: number;
+}
+/**
+ * Follows an app's background runs until each comes to rest (`settled`, `idle`, `waiting_on_user`, or deleted),
+ * and hands each ending to `onEnded` at least once. Build it with `oauth.watchRuns(...)`, then `start()`.
+ *
+ * Delivery is keyed in memory on `(runId, status, latest_sequence)`: a run still in `pending()` after delivery is
+ * re-read once per sweep without `wait` and delivered again only when that key changes (it worked again, or an
+ * `idle` run was later canceled to `settled`); a sweep that reads `running` goes back to the long-poll. The app's
+ * rows are the durable record, so a restarted watcher re-derives everything from `pending()`.
+ */
+export declare class RunWatcher {
+    private readonly open;
+    private readonly options;
+    private readonly sweepMs;
+    private readonly concurrency;
+    /** Followed runs by runId (one open loop each). */
+    private readonly following;
+    /** The last key delivered per runId: `${status}:${latest_sequence}`, or `gone`. */
+    private readonly delivered;
+    /** Runs that rested and were delivered: re-read only on sweeps. */
+    private readonly resting;
+    /** Runs backing off after a failure, until this instant. */
+    private readonly retryAt;
+    private readonly backoff;
+    private readonly queue;
+    private active;
+    private running;
+    private timer;
+    private sweeping;
+    private sweepAgain;
+    private readonly lifetime;
+    constructor(open: (userId: string) => Promise<Crouter>, options: RunWatchOptions);
+    /** Read `pending()` and begin following; sweeps repeat every `sweepMs` until `stop()`. Resolves after the first sweep. */
+    start(): Promise<void>;
+    /** Sweep now instead of waiting for `sweepMs`, for example right after the app starts a run it will watch. */
+    nudge(): void;
+    /** Stop sweeping, abort every open long-poll, and resolve once every loop has ended. No handler starts afterwards. */
+    stop(): Promise<void>;
+    private sweep;
+    private sweepOnce;
+    private forget;
+    private drain;
+    /** One loop: read the run until it rests, deliver once per key, then leave it to the sweeps. */
+    private follow;
+    private deliver;
+    /** Back off this run: 5 s doubling to 5 min, then a sweep picks it up again. */
+    private fail;
+    /** No stored connection, or a refusal `OAuth2Client` already handled: drop the loop; the next sweep decides. */
+    private connectionTrouble;
+    private report;
+}

package/dist/resources/run-watcher.js

@@ -0,0 +1,242 @@
+import { APIError, CrouterError } from '../errors.js';
+import { refusalOf } from '../oauth/refusal.js';
+const restingStatuses = new Set(['settled', 'idle', 'waiting_on_user']);
+const firstBackoffMs = 5_000;
+const maxBackoffMs = 300_000;
+/**
+ * Follows an app's background runs until each comes to rest (`settled`, `idle`, `waiting_on_user`, or deleted),
+ * and hands each ending to `onEnded` at least once. Build it with `oauth.watchRuns(...)`, then `start()`.
+ *
+ * Delivery is keyed in memory on `(runId, status, latest_sequence)`: a run still in `pending()` after delivery is
+ * re-read once per sweep without `wait` and delivered again only when that key changes (it worked again, or an
+ * `idle` run was later canceled to `settled`); a sweep that reads `running` goes back to the long-poll. The app's
+ * rows are the durable record, so a restarted watcher re-derives everything from `pending()`.
+ */
+export class RunWatcher {
+    open;
+    options;
+    sweepMs;
+    concurrency;
+    /** Followed runs by runId (one open loop each). */
+    following = new Map();
+    /** The last key delivered per runId: `${status}:${latest_sequence}`, or `gone`. */
+    delivered = new Map();
+    /** Runs that rested and were delivered: re-read only on sweeps. */
+    resting = new Set();
+    /** Runs backing off after a failure, until this instant. */
+    retryAt = new Map();
+    backoff = new Map();
+    queue = [];
+    active = 0;
+    running = false;
+    timer;
+    sweeping;
+    sweepAgain = false;
+    lifetime = new AbortController();
+    constructor(open, options) {
+        this.open = open;
+        this.options = options;
+        this.sweepMs = options.sweepMs ?? 30_000;
+        this.concurrency = options.concurrency ?? 50;
+        if (!Number.isFinite(this.sweepMs) || this.sweepMs <= 0)
+            throw new CrouterError('sweepMs must be a positive number');
+        if (!Number.isInteger(this.concurrency) || this.concurrency < 1)
+            throw new CrouterError('concurrency must be a positive integer');
+    }
+    /** Read `pending()` and begin following; sweeps repeat every `sweepMs` until `stop()`. Resolves after the first sweep. */
+    async start() {
+        if (this.running)
+            return;
+        if (this.lifetime.signal.aborted)
+            throw new CrouterError('A stopped RunWatcher cannot be started again; build a new one');
+        this.running = true;
+        await this.sweep();
+    }
+    /** Sweep now instead of waiting for `sweepMs`, for example right after the app starts a run it will watch. */
+    nudge() { if (this.running)
+        void this.sweep(); }
+    /** Stop sweeping, abort every open long-poll, and resolve once every loop has ended. No handler starts afterwards. */
+    async stop() {
+        this.running = false;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.lifetime.abort();
+        this.queue.length = 0;
+        await Promise.allSettled([...this.following.values()].map((follow) => follow.done));
+    }
+    sweep() {
+        if (this.sweeping) {
+            this.sweepAgain = true;
+            return this.sweeping;
+        }
+        this.sweeping = (async () => {
+            do {
+                this.sweepAgain = false;
+                await this.sweepOnce();
+            } while (this.sweepAgain && this.running);
+        })().finally(() => {
+            this.sweeping = undefined;
+            if (this.running) {
+                if (this.timer)
+                    clearTimeout(this.timer);
+                this.timer = setTimeout(() => void this.sweep(), this.sweepMs);
+                this.timer.unref?.();
+            }
+        });
+        return this.sweeping;
+    }
+    async sweepOnce() {
+        if (!this.running)
+            return;
+        let runs;
+        try {
+            runs = await this.options.pending();
+        }
+        catch (error) {
+            this.report(error, null);
+            return;
+        }
+        if (!this.running)
+            return;
+        const wanted = new Map(runs.map((run) => [run.runId, run]));
+        // Forget runs the app no longer waits on, so a later reuse of the id starts clean.
+        for (const runId of [...this.delivered.keys()])
+            if (!wanted.has(runId))
+                this.forget(runId);
+        for (let i = this.queue.length - 1; i >= 0; i--)
+            if (!wanted.has(this.queue[i].runId))
+                this.queue.splice(i, 1);
+        const now = Date.now();
+        for (const run of wanted.values()) {
+            if (this.following.has(run.runId) || this.queue.some((queued) => queued.runId === run.runId))
+                continue;
+            if ((this.retryAt.get(run.runId) ?? 0) > now)
+                continue;
+            // A deleted run cannot come back: once `gone` is delivered it is not read again while pending() returns it.
+            if (this.delivered.get(run.runId) === 'gone')
+                continue;
+            this.queue.push(run);
+        }
+        this.drain();
+    }
+    forget(runId) {
+        this.delivered.delete(runId);
+        this.resting.delete(runId);
+        this.retryAt.delete(runId);
+        this.backoff.delete(runId);
+    }
+    drain() {
+        while (this.running && this.active < this.concurrency && this.queue.length > 0) {
+            const run = this.queue.shift();
+            const controller = new AbortController();
+            const abort = () => controller.abort(this.lifetime.signal.reason);
+            this.lifetime.signal.addEventListener('abort', abort, { once: true });
+            this.active++;
+            const follow = { run, controller, done: Promise.resolve() };
+            this.following.set(run.runId, follow);
+            follow.done = this.follow(run, controller.signal).finally(() => {
+                this.lifetime.signal.removeEventListener('abort', abort);
+                this.active--;
+                if (this.following.get(run.runId) === follow)
+                    this.following.delete(run.runId);
+                this.drain();
+            });
+        }
+    }
+    /** One loop: read the run until it rests, deliver once per key, then leave it to the sweeps. */
+    async follow(run, signal) {
+        let client;
+        try {
+            client = await this.open(run.userId);
+        }
+        catch (error) {
+            this.connectionTrouble(error, run);
+            return;
+        }
+        // A run delivered before is re-read once without waiting: waitRun answers a resting run at once, so a
+        // long-poll would spin. Only a run seen running (or never delivered) long-polls.
+        let plain = this.resting.has(run.runId);
+        for (;;) {
+            if (signal.aborted || !this.running)
+                return;
+            let current;
+            try {
+                current = await client.runs.get(run.runId, plain ? { signal } : { signal, wait: 25 });
+            }
+            catch (error) {
+                if (signal.aborted || !this.running)
+                    return;
+                if (error instanceof APIError && error.status === 404 && error.code === 'not_found' && error.origin === 'runtime') {
+                    await this.deliver(run, 'gone', { userId: run.userId, runId: run.runId, ended: 'gone', run: null });
+                    return;
+                }
+                if (isConnectionTrouble(error)) {
+                    this.connectionTrouble(error, run);
+                    return;
+                }
+                this.fail(run, error);
+                return;
+            }
+            if (!restingStatuses.has(current.status)) {
+                plain = false;
+                this.resting.delete(run.runId);
+                continue;
+            }
+            const key = `${current.status}:${current.latest_sequence}`;
+            if (this.delivered.get(run.runId) === key) {
+                this.resting.add(run.runId);
+                return;
+            }
+            await this.deliver(run, key, { userId: run.userId, runId: run.runId, ended: current.status, run: current });
+            return;
+        }
+    }
+    async deliver(run, key, event) {
+        if (!this.running)
+            return;
+        try {
+            await this.options.onEnded(event);
+        }
+        catch (error) {
+            this.fail(run, error);
+            return;
+        }
+        this.delivered.set(run.runId, key);
+        this.resting.add(run.runId);
+        this.retryAt.delete(run.runId);
+        this.backoff.delete(run.runId);
+        // The app has likely landed it; re-read pending() so the set shrinks (and the next run gets a slot) promptly.
+        if (this.running)
+            void this.sweep();
+    }
+    /** Back off this run: 5 s doubling to 5 min, then a sweep picks it up again. */
+    fail(run, error) {
+        this.report(error, run);
+        const delay = Math.min(maxBackoffMs, this.backoff.get(run.runId) ?? firstBackoffMs);
+        this.backoff.set(run.runId, Math.min(maxBackoffMs, delay * 2));
+        this.retryAt.set(run.runId, Date.now() + delay);
+        if (!this.running)
+            return;
+        const timer = setTimeout(() => { if (this.running)
+            void this.sweep(); }, delay);
+        timer.unref?.();
+        this.lifetime.signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+    }
+    /** No stored connection, or a refusal `OAuth2Client` already handled: drop the loop; the next sweep decides. */
+    connectionTrouble(error, run) {
+        if (isConnectionTrouble(error)) {
+            this.report(error, run);
+            return;
+        }
+        this.fail(run, error);
+    }
+    report(error, run) {
+        try {
+            this.options.onError?.(error, run);
+        }
+        catch { /* A throwing onError must not stop the watcher. */ }
+    }
+}
+function isConnectionTrouble(error) {
+    return refusalOf(error) !== null || (error instanceof CrouterError && (error.code === 'not_connected' || error.code === 'refusal_handler_reentry'));
+}

package/dist/stores/postgres.d.ts

@@ -23,6 +23,9 @@ export declare class PostgresConnectionStore implements ConnectionStore {
     lock<T>(userId: string, fn: () => Promise<T>): Promise<T>;
     load(userId: string): Promise<Connection | null>;
     save(connection: Connection): Promise<void>;
+    /** Delete `userId`'s row only while it still holds `refreshToken`; answers whether one was deleted. Inside
+     *  `lock` it runs in that transaction, so it commits when the locked callback resolves. */
+    remove(userId: string, refreshToken: string): Promise<boolean>;
     /** Connections not saved since `before`, oldest first. Save activity is not necessarily refresh activity. */
     listStale(before: Date): Promise<Connection[]>;
 }

package/dist/stores/postgres.js

@@ -75,6 +75,12 @@ export class PostgresConnectionStore {
          access_token_expires_at = EXCLUDED.access_token_expires_at, id_token = EXCLUDED.id_token, updated_at = clock_timestamp()`, [connection.userId, connection.runtimeUrl, connection.refreshToken, connection.grantId,
             connection.accessToken, expiry, connection.idToken ?? null]);
     }
+    /** Delete `userId`'s row only while it still holds `refreshToken`; answers whether one was deleted. Inside
+     *  `lock` it runs in that transaction, so it commits when the locked callback resolves. */
+    async remove(userId, refreshToken) {
+        const result = await (this.transaction.getStore() ?? this.pool).query(`DELETE FROM ${this.table} WHERE user_id = $1 AND refresh_token = $2 RETURNING user_id`, [userId, refreshToken]);
+        return result.rows.length > 0;
+    }
     /** Connections not saved since `before`, oldest first. Save activity is not necessarily refresh activity. */
     async listStale(before) {
         if (!Number.isFinite(before.getTime()))

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
-export declare const SDK_VERSION = "0.3.393";
+export declare const SDK_VERSION = "0.3.395";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
-export const SDK_VERSION = '0.3.393';
+export const SDK_VERSION = '0.3.395';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouter/sdk",
-  "version": "0.3.393",
+  "version": "0.3.395",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,8 +31,8 @@
     "build": "tsc -p tsconfig.json && chmod 755 dist/keygen-cli.js"
   },
   "dependencies": {
-    "@crouter/api": "0.3.393",
-    "@crouter/identity": "0.3.393",
+    "@crouter/api": "0.3.395",
+    "@crouter/identity": "0.3.395",
     "jose": "^6.2.1"
   },
   "peerDependencies": {