@north-light/sdk 0.3.418 → 0.3.419

package/dist/index.d.ts

@@ -16,8 +16,8 @@ export type { MemoryDocument, MemoryGetParams, MemoryListItem, MemoryListPage, M
 export type { Question, QuestionAnswered, QuestionFields, QuestionResponses, QuestionSlot, QuestionStatus } from './resources/questions.js';
 export type { ProviderToolEntry } from './resources/providers.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 { authorizationRefusalOf, refusalOf } from './oauth/index.js';
+export type { AuthorizationRefusal, RefreshFailure, Refusal, RefusalKind } from './oauth/index.js';
 export { RunWatcher } from './resources/run-watcher.js';
 export type { PendingRun, RunActivityEvent, RunEnded, RunEnding, RunWatchOptions } from './resources/run-watcher.js';
 export { GrantWatcher } from './resources/grant-watcher.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { RunStream } from './resources/run-stream.js';
 export { CustomObjects } from './resources/custom-objects.js';
 export { RunReply } from './resources/run-reply.js';
 export { OAuth2Client, ConnectedCrouter, DEFAULT_DIRECTORY_TIMEOUT_MS, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
-export { refusalOf } from './oauth/index.js';
+export { authorizationRefusalOf, refusalOf } from './oauth/index.js';
 export { RunWatcher } from './resources/run-watcher.js';
 export { GrantWatcher } from './resources/grant-watcher.js';
 export { generateKeyPair } from './oauth/keygen.js';

package/dist/oauth/index.d.ts

@@ -4,8 +4,8 @@ import { Crouter, type CrouterOptions } from '../client.js';
 import { RunWatcher, type RunWatchOptions } from '../resources/run-watcher.js';
 import { GrantWatcher, type GrantWatchOptions } from '../resources/grant-watcher.js';
 import { type Refusal } from './refusal.js';
-export { refusalOf } from './refusal.js';
-export type { Refusal, RefusalKind } from './refusal.js';
+export { authorizationRefusalOf, refusalOf } from './refusal.js';
+export type { AuthorizationRefusal, 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 {
@@ -81,7 +81,7 @@ export interface OAuth2Options {
      *  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`,
+     * Called when the directory refuses to refresh a stored connection (`grant_removed`, `grant_suspended`, `app_in_testing`,
      * `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.
      *

package/dist/oauth/index.js

@@ -7,7 +7,7 @@ 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';
-export { refusalOf } from './refusal.js';
+export { authorizationRefusalOf, 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();

package/dist/oauth/refusal.d.ts

@@ -5,6 +5,9 @@ import { APIError } from '../errors.js';
  *   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.
+ * - `paused` also covers `app_in_testing`: the app is still in testing and the person is not its admin or a named tester
+ *   (they were removed as a tester, or their email or phone stopped matching). The grant is revoked, not removed, and
+ *   the person's data is kept; they get access back when the developer adds them again and 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.
  */
@@ -14,7 +17,7 @@ export declare const isRefusalCode: (code: string) => boolean;
  *  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`. */
+    /** The directory's code: `grant_removed`, `grant_suspended`, `app_in_testing`, `refresh_token_expired`, `refresh_token_reused`, or `grant_revoked`. */
     code: string;
     /** The connection's crouter cloud user id (`user:<id>`). */
     userId: string;
@@ -30,3 +33,19 @@ export declare function attachRefusal(error: APIError, refusal: Refusal): void;
  *  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;
+/** A sign-in the directory refused before issuing a code, read from the redirect back to the app (`authorizationRefusalOf`). */
+export interface AuthorizationRefusal {
+    /** The directory's reason, the redirect's `error_description`: `app_in_testing`. */
+    code: 'app_in_testing';
+    /** The redirect's `error`: always `access_denied`. */
+    error: 'access_denied';
+    /** The redirect's `state`, or null when it carried none. Check it against the saved value before showing anything. */
+    state: string | null;
+}
+type CallbackQuery = string | URL | URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+/** The `AuthorizationRefusal` a sign-in redirect carries when the directory refused the person (`error=access_denied`
+ *  with a reason the SDK knows), else `null`. Pass the callback's query: a `URL`, a URL or query string, a
+ *  `URLSearchParams`, or a parsed query object. A person who pressed Cancel (`access_denied` without a known reason)
+ *  and any other error answer `null`; handle those yourself. There is no grant to refresh, so no `onRefusal` runs. */
+export declare function authorizationRefusalOf(callback: CallbackQuery): AuthorizationRefusal | null;
+export {};

package/dist/oauth/refusal.js

@@ -1,7 +1,7 @@
 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',
+    grant_removed: 'removed', grant_suspended: 'paused', app_in_testing: 'paused',
     refresh_token_expired: 'reconnect', refresh_token_reused: 'reconnect', grant_revoked: 'reconnect',
 };
 export const isRefusalCode = (code) => Object.hasOwn(refusalKinds, code);
@@ -15,3 +15,24 @@ export function attachRefusal(error, refusal) { Object.defineProperty(error, ref
 export function refusalOf(error) {
     return error instanceof APIError ? error[refusalKey] ?? null : null;
 }
+/** The `AuthorizationRefusal` a sign-in redirect carries when the directory refused the person (`error=access_denied`
+ *  with a reason the SDK knows), else `null`. Pass the callback's query: a `URL`, a URL or query string, a
+ *  `URLSearchParams`, or a parsed query object. A person who pressed Cancel (`access_denied` without a known reason)
+ *  and any other error answer `null`; handle those yourself. There is no grant to refresh, so no `onRefusal` runs. */
+export function authorizationRefusalOf(callback) {
+    const read = (name) => {
+        if (callback instanceof URLSearchParams)
+            return callback.get(name);
+        if (callback instanceof URL)
+            return callback.searchParams.get(name);
+        if (typeof callback === 'string') {
+            const query = callback.includes('?') ? callback.slice(callback.indexOf('?') + 1).split('#')[0] : callback;
+            return new URLSearchParams(query).get(name);
+        }
+        const value = callback[name];
+        return Array.isArray(value) ? value[0] ?? null : value ?? null;
+    };
+    if (read('error') !== 'access_denied' || read('error_description') !== 'app_in_testing')
+        return null;
+    return { code: 'app_in_testing', error: 'access_denied', state: read('state') };
+}

package/dist/testing/cloud.d.ts

@@ -98,6 +98,45 @@ export interface FakeCloudOptions {
         now(): number;
     };
 }
+/** A tester entry: an email (matched case-insensitively against a verified email) or a phone (E.164, matched against the confirmed phone). */
+export type FakeTesterRef = {
+    email: string;
+    phone?: never;
+} | {
+    phone: string;
+    email?: never;
+};
+/** A stored tester entry, normalized (email lowercased and trimmed). */
+export interface FakeTester {
+    kind: 'email' | 'phone';
+    value: string;
+}
+/** Testing mode for the app this cloud serves: an unverified third-party app admits only its admin and up to 100 named testers. */
+export interface FakeTesting {
+    /** Whether the app is in testing. Default false (verified). */
+    readonly active: boolean;
+    /** Put the app in testing. `admin` is the user id who manages it and is always allowed. Every active grant whose
+     *  person is not allowed is revoked with `app_in_testing`; the user ids are returned. */
+    enable(options?: {
+        admin?: string;
+    }): string[];
+    /** Take the app out of testing: everyone is allowed again. Revoked grants stay revoked until the person signs in (`authorize`). */
+    disable(): void;
+    /** The tester entries, oldest first. Kept while the app is not in testing. */
+    readonly testers: readonly FakeTester[];
+    /** Add a tester by `{email}` or `{phone}` (E.164). Returns false when the entry was already present. The 101st entry throws. */
+    addTester(tester: FakeTesterRef): boolean;
+    /** Remove a tester. When the app is in testing, every active grant whose person is no longer allowed is revoked with
+     *  `app_in_testing`; those user ids are returned. Their next refresh answers `invalid_grant` `app_in_testing`. */
+    removeTester(tester: FakeTesterRef): {
+        removed: boolean;
+        revoked: string[];
+    };
+    /** Whether `userId` may use the app now: not in testing, the admin, or matched by a tester entry. */
+    allowed(userId: string): boolean;
+}
+/** The directory's cap on tester entries per app. */
+export declare const FAKE_TESTER_LIMIT = 100;
 /** `cloud.runs` and `user.runs`: the runs in start order, and the responder for them. */
 export interface FakeRuns {
     /** The runs in start order (deleted ones included, with `deleted` set). */
@@ -120,6 +159,8 @@ export declare class FakeCloud {
     /** What responders threw. */
     readonly responderErrors: unknown[];
     readonly runs: FakeRuns;
+    /** Testing mode for this cloud's app. */
+    readonly testing: FakeTesting;
     readonly providers: {
         define(provider: string, definition: FakeProvider): void;
     };
@@ -137,10 +178,33 @@ export declare class FakeCloud {
     private readonly host;
     /** Superseded refresh tokens → owner, for `refresh_token_reused`. */
     private readonly superseded;
+    private inTesting;
+    private testingAdmin;
+    private readonly testerEntries;
+    /** Authorization codes `authorize` issued → person. */
+    private readonly codes;
+    private codeSerial;
     private tokenSerial;
     private refreshSerial;
     private runSerial;
     constructor(options: FakeCloudOptions);
+    private testerEntry;
+    /** The directory's `allowedInTesting(app, user)`: the app is not in testing, the person is its admin, or a tester entry matches their account. */
+    private allowedInTesting;
+    /** The testing sweep: revoke each active grant whose person is no longer allowed. */
+    private sweepTesting;
+    /**
+     * The redirect the directory sends the browser back to after `userId` signs in to the app: the person's
+     * `redirectUri` with `code` and `state`, or with `error=access_denied`, `error_description=app_in_testing` and `state`
+     * when the app is in testing and they are not allowed (the testing page's "Back", or `prompt=none`). An allowed
+     * person's grant is active (default scopes `crtr:llm`, `crtr:act`; an existing grant keeps its scopes) and `code` exchanges at the fake `/token`
+     * through `oauth.exchangeCode`. Nothing is written for a refused person.
+     */
+    authorize(userId: string, options: {
+        redirectUri: string;
+        state: string;
+        scopes?: FakeScope[];
+    }): URL;
     /** A `FakeError` envelope for intercepts, `failNext` and provider handlers. `retryable` defaults to `status === 503`. */
     static error(input: {
         status: number;
@@ -206,6 +270,8 @@ export declare class FakeCloud {
     /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
     private mint;
     private refresh;
+    /** `grant_type=authorization_code`: the code `authorize` issued, once. The client assertion and PKCE verifier are not verified. */
+    private exchange;
     private newRefreshToken;
     private accessToken;
     private runtime;

package/dist/testing/cloud.js

@@ -12,6 +12,8 @@ import { RunNotices, SigningKey } from './notices.js';
 import { FakeRun } from './run.js';
 import { UserState, normalizeScopes } from './users.js';
 import { FakeRefused, decodeUnsigned, envelopeBody, fakeError, integerParam, invalid, isFakeError, jsonAnswer, notFound, objectBody, refuse, requestedScopes, sha256Hex, unsignedJwt, waitSeconds, } from './wire.js';
+/** The directory's cap on tester entries per app. */
+export const FAKE_TESTER_LIMIT = 100;
 const ROUTES = [
     ['GET', /^\/v1\/grant$/, 'grant.get'],
     ['POST', /^\/v1\/runs$/, 'run.start'],
@@ -69,6 +71,8 @@ export class FakeCloud {
     /** What responders threw. */
     responderErrors = [];
     runs;
+    /** Testing mode for this cloud's app. */
+    testing;
     providers;
     options;
     clock;
@@ -84,6 +88,12 @@ export class FakeCloud {
     host;
     /** Superseded refresh tokens → owner, for `refresh_token_reused`. */
     superseded = new Map();
+    inTesting = false;
+    testingAdmin = null;
+    testerEntries = [];
+    /** Authorization codes `authorize` issued → person. */
+    codes = new Map();
+    codeSerial = 0;
     tokenSerial = 0;
     refreshSerial = 0;
     runSerial = 0;
@@ -122,8 +132,96 @@ export class FakeCloud {
                     throw new TypeError(`invalid provider id ${provider}`);
                 this.providerDefs.set(provider, definition);
             } };
+        const cloud = this;
+        this.testing = {
+            get active() { return cloud.inTesting; },
+            enable: (enableOptions = {}) => {
+                this.inTesting = true;
+                this.testingAdmin = enableOptions.admin ?? null;
+                return this.sweepTesting();
+            },
+            disable: () => { this.inTesting = false; },
+            get testers() { return cloud.testerEntries.map((entry) => ({ ...entry })); },
+            addTester: (ref) => {
+                const entry = this.testerEntry(ref);
+                if (this.testerEntries.some((other) => other.kind === entry.kind && other.value === entry.value))
+                    return false;
+                if (this.testerEntries.length >= FAKE_TESTER_LIMIT)
+                    throw new TypeError(`This app has ${FAKE_TESTER_LIMIT} testers. Remove one before adding another.`);
+                this.testerEntries.push(entry);
+                return true;
+            },
+            removeTester: (ref) => {
+                const entry = this.testerEntry(ref);
+                const index = this.testerEntries.findIndex((other) => other.kind === entry.kind && other.value === entry.value);
+                if (index < 0)
+                    return { removed: false, revoked: [] };
+                this.testerEntries.splice(index, 1);
+                return { removed: true, revoked: this.sweepTesting() };
+            },
+            allowed: (userId) => this.allowedInTesting(this.state(userId)),
+        };
         this.fetch = (input, init) => this.route(input, init);
     }
+    testerEntry(ref) {
+        const { email, phone } = ref;
+        if ((email === undefined) === (phone === undefined))
+            throw new TypeError('Pass email or phone, not both.');
+        if (email !== undefined) {
+            const value = email.trim().toLowerCase();
+            if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
+                throw new TypeError(`${email} is not an email address`);
+            return { kind: 'email', value };
+        }
+        if (!/^\+[1-9]\d{6,14}$/.test(phone))
+            throw new TypeError(`${phone} is not an E.164 phone number (+15551234567)`);
+        return { kind: 'phone', value: phone };
+    }
+    /** The directory's `allowedInTesting(app, user)`: the app is not in testing, the person is its admin, or a tester entry matches their account. */
+    allowedInTesting(user) {
+        if (!this.inTesting || user.id === this.testingAdmin)
+            return true;
+        const { email, emailVerified = true, phone } = user.account;
+        return this.testerEntries.some((entry) => entry.kind === 'email'
+            ? email !== undefined && emailVerified && email.trim().toLowerCase() === entry.value
+            : phone !== undefined && phone === entry.value);
+    }
+    /** The testing sweep: revoke each active grant whose person is no longer allowed. */
+    sweepTesting() {
+        const revoked = [];
+        if (!this.inTesting)
+            return revoked;
+        for (const user of this.users.values()) {
+            if (!user.active || this.allowedInTesting(user))
+                continue;
+            user.revoke('app_in_testing');
+            revoked.push(user.id);
+        }
+        return revoked;
+    }
+    /**
+     * The redirect the directory sends the browser back to after `userId` signs in to the app: the person's
+     * `redirectUri` with `code` and `state`, or with `error=access_denied`, `error_description=app_in_testing` and `state`
+     * when the app is in testing and they are not allowed (the testing page's "Back", or `prompt=none`). An allowed
+     * person's grant is active (default scopes `crtr:llm`, `crtr:act`; an existing grant keeps its scopes) and `code` exchanges at the fake `/token`
+     * through `oauth.exchangeCode`. Nothing is written for a refused person.
+     */
+    authorize(userId, options) {
+        const target = new URL(options.redirectUri);
+        const state = this.state(userId);
+        if (!this.allowedInTesting(state)) {
+            target.searchParams.set('error', 'access_denied');
+            target.searchParams.set('error_description', 'app_in_testing');
+            target.searchParams.set('state', options.state);
+            return target;
+        }
+        this.activateState(state, options.scopes === undefined ? {} : { scopes: options.scopes });
+        const code = `code-${++this.codeSerial}-${userId}`;
+        this.codes.set(code, userId);
+        target.searchParams.set('code', code);
+        target.searchParams.set('state', options.state);
+        return target;
+    }
     /** A `FakeError` envelope for intercepts, `failNext` and provider handlers. `retryable` defaults to `status === 503`. */
     static error(input) {
         return fakeError(input);
@@ -166,6 +264,7 @@ export class FakeCloud {
                 if (code !== 'ok')
                     state.minSerial = cloud.tokenSerial + 1;
             },
+            setAccount(account) { state.account = { ...account }; },
             expireTokens() { state.minSerial = cloud.tokenSerial + 1; },
             get reads() { return cloud.calls.filter((call) => call.userId === userId && call.op === 'grant.get'); },
             get holding() { return state.holds.size; },
@@ -362,7 +461,8 @@ export class FakeCloud {
         const presented = params?.get('refresh_token') ?? '';
         const credentials = params?.get('grant_type') === 'client_credentials';
         const owner = op === 'directory.token' && credentials ? params.get('sub') || null
-            : op === 'directory.token' ? [...this.users.values()].find((user) => user.refreshToken === presented)?.id ?? this.superseded.get(presented) ?? null : null;
+            : op === 'directory.token' && params.get('grant_type') === 'authorization_code' ? this.codes.get(params.get('code') ?? '') ?? null
+                : op === 'directory.token' ? [...this.users.values()].find((user) => user.refreshToken === presented)?.id ?? this.superseded.get(presented) ?? null : null;
         const call = { op, userId: owner, answer: 'ok', at: this.clock.now() };
         this.directoryCalls.push(call);
         const scripted = await this.runIntercepts(op, call, signal);
@@ -384,6 +484,8 @@ export class FakeCloud {
         }
         if (op === 'directory.jwks')
             return Response.json(await this.key.jwks());
+        if (params?.get('grant_type') === 'authorization_code')
+            return this.exchange(params, call);
         return credentials ? this.mint(params, call) : this.refresh(params, presented, call);
     }
     /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
@@ -410,6 +512,9 @@ export class FakeCloud {
         if (call.userId === null)
             return refused('grant_revoked');
         const user = this.state(call.userId);
+        // "Why a refresh is refused": after `grant_suspended`, before `refresh_token_reused`. Nothing is written.
+        if (user.active && !this.allowedInTesting(user))
+            return refused('app_in_testing');
         if (user.refreshToken !== presented)
             return refused('refresh_token_reused');
         if (user.refusal)
@@ -421,6 +526,24 @@ export class FakeCloud {
             refresh_token: user.refreshToken, runtimeUrl: this.runtimeUrlFor(user.id),
         });
     }
+    /** `grant_type=authorization_code`: the code `authorize` issued, once. The client assertion and PKCE verifier are not verified. */
+    exchange(params, call) {
+        const code = params.get('code') ?? '';
+        const userId = this.codes.get(code);
+        this.codes.delete(code);
+        if (userId === undefined) {
+            call.answer = 'grant_revoked';
+            return Response.json({ error: 'invalid_grant' }, { status: 400 });
+        }
+        const user = this.state(userId);
+        if (user.refreshToken)
+            this.superseded.set(user.refreshToken, user.id);
+        user.refreshToken = this.newRefreshToken(user.id);
+        return Response.json({
+            access_token: this.accessToken(user), token_type: 'Bearer', expires_in: 3600,
+            refresh_token: user.refreshToken, runtimeUrl: this.runtimeUrlFor(user.id),
+        });
+    }
     newRefreshToken(userId) { return `rt-${++this.refreshSerial}-${userId}`; }
     accessToken(user, ttlSeconds = 3600) {
         const now = Math.floor(this.clock.now() / 1000);

package/dist/testing/index.d.ts

@@ -1,7 +1,7 @@
-export { FakeCloud } from './cloud.js';
+export { FakeCloud, FAKE_TESTER_LIMIT } from './cloud.js';
 export { manualClock } from './clock.js';
 export type { ManualClock } from './clock.js';
-export type { FakeAnswer, FakeCall, FakeCloudOptions, FakeDirectoryCall, FakeDirectoryOp, FakeInterceptOp, FakeOp, FakeProvider, FakeRuns, FakeToolHandler, Intercept, } from './cloud.js';
+export type { FakeAnswer, FakeCall, FakeCloudOptions, FakeDirectoryCall, FakeDirectoryOp, FakeInterceptOp, FakeOp, FakeProvider, FakeRuns, FakeTester, FakeTesterRef, FakeTesting, FakeToolHandler, Intercept, } from './cloud.js';
 export type { FakeRun, FakeRunEnding, FakeRunMessage, FakeRunParams, FakeQuestion } from './run.js';
 export type { FakeNotice, RunNoticeOptions } from './notices.js';
-export type { FakeMemoryDoc, FakeRefusalCode, FakeScope, FakeUser, GrantPatch, Responder, ResponderInput } from './users.js';
+export type { FakeAccount, FakeMemoryDoc, FakeRefusalCode, FakeScope, FakeUser, GrantPatch, Responder, ResponderInput } from './users.js';

package/dist/testing/index.js

@@ -1,4 +1,4 @@
 // `@north-light/sdk/testing`: a fake crouter cloud (directory + runtime) your real `OAuth2Client` and `Crouter` talk to
 // through `fetch`. Node-only; no test framework. See docs/sdk/testing.md.
-export { FakeCloud } from './cloud.js';
+export { FakeCloud, FAKE_TESTER_LIMIT } from './cloud.js';
 export { manualClock } from './clock.js';

package/dist/testing/users.d.ts

@@ -1,7 +1,15 @@
 import type { GrantGetDTO, ProviderDependency, SetupState } from '@north-light/api';
 import type { FakeRun } from './run.js';
 /** The directory's reasons for refusing a refresh token (the SDK's refusal table). */
-export type FakeRefusalCode = 'grant_removed' | 'grant_suspended' | 'refresh_token_expired' | 'refresh_token_reused' | 'grant_revoked' | 'runtime_provisioning';
+export type FakeRefusalCode = 'grant_removed' | 'grant_suspended' | 'app_in_testing' | 'refresh_token_expired' | 'refresh_token_reused' | 'grant_revoked' | 'runtime_provisioning';
+/** The identifiers a person's account holds. Only `email` (when `emailVerified`) and `phone` match a tester entry. */
+export interface FakeAccount {
+    email?: string;
+    /** Default true when `email` is set. An unverified email matches no tester entry. */
+    emailVerified?: boolean;
+    /** The confirmed phone, E.164 (`+15551234567`). */
+    phone?: string;
+}
 /** What a run's responder receives. */
 export interface ResponderInput {
     run: FakeRun;
@@ -61,6 +69,8 @@ export declare class UserState {
     refreshToken: string | null;
     /** Access tokens with a serial below this answer 401 `unauthorized`. */
     minSerial: number;
+    /** The identifiers the account holds, which tester entries match (`FakeUser.setAccount`). */
+    account: FakeAccount;
     readonly grantId: string;
     readonly runs: FakeRun[];
     responder: Responder | null;
@@ -108,6 +118,9 @@ export interface FakeUser {
         /** Active again at `rev` +1; the directory answers `ok`. */
         restore(patch?: GrantPatch): void;
     };
+    /** The email and phone this person's account holds, replacing any set before. A tester entry matches them
+     *  (`cloud.testing`); nothing is revoked when they stop matching, and the next refresh or `authorize` is refused. */
+    setAccount(account: FakeAccount): void;
     /** The directory refuses each refresh with `code` (`'ok'` clears it); tokens issued before now answer 401 `unauthorized`. */
     refuse(code: FakeRefusalCode | 'ok'): void;
     /** Tokens issued before now answer 401 `unauthorized`, forcing a refresh; the directory's answer is unchanged. */

package/dist/testing/users.js

@@ -18,6 +18,8 @@ export class UserState {
     refreshToken = null;
     /** Access tokens with a serial below this answer 401 `unauthorized`. */
     minSerial = 0;
+    /** The identifiers the account holds, which tester entries match (`FakeUser.setAccount`). */
+    account = {};
     grantId;
     runs = [];
     responder = null;

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.418";
+export declare const SDK_VERSION = "0.3.419";

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.418';
+export const SDK_VERSION = '0.3.419';

package/package.json

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