@wtfalch/auth 0.30.0 → 0.31.0

package/README.md

@@ -41,6 +41,14 @@ middleware for the paths that need a session, and read the person with
 `createAuth` from `@wtfalch/auth` is the same thing without the framework, for
 a CLI or a worker that has no router to import.
 
+**Sign-in entry form.** `/auth/start` answers a GET (query) and a same-origin
+form POST (`application/x-www-form-urlencoded`, at most 4096 bytes, length
+declared). Post the form to keep an email `login_hint` out of URLs, access logs
+and `Referer`: `<form method="post" action="/auth/start">` with `next`,
+`intent`, `prompt`, `max_age` and `login_hint` as fields. A POST reads only its
+body, refuses another origin (403), a non-form type (415) and a large or
+undeclared body (413), and a `login_hint` still blocks a silent pass.
+
 ## One-time passwords
 
 An account created with `changeRequired: true` holds a one-time password.
@@ -103,6 +111,14 @@ already has a query string keeps it. `expired` and `request` carry no `next`:
 there is no transaction to read it from. Use it for the retry link
 (`/auth/start?next=<path>`); a page that ignores it behaves as before.
 
+**`next` on the error page is attacker-controllable.** The SDK only puts a safe
+path there, but anyone can open `<onError>?next=//evil.test` themselves. The
+error page must run `next` through `safeNextPath` (exported from
+`@wtfalch/auth`) before building a retry link, and never use it raw in a link,
+redirect or `Location`. `next` can also
+carry an invite token: send no `Referer` from the error page
+(`Referrer-Policy: no-referrer`) and keep its query string out of your logs.
+
 ## In a browser app
 
 `@wtfalch/auth/browser` is the other half: a public PKCE client for an app that
@@ -142,6 +158,21 @@ again. `forget()` sets the same mark, so a sign-out does not undo itself.
 `completeSignIn()` at the callback returns `signed-in`, `silent-refused` — the
 answer to a silent attempt, not a failure — or `error`.
 
+**Signing out at the issuer.** `forget()` only clears this tab. To end the
+person's session at the issuer too, read the URL first, then forget, then go:
+
+```ts
+const url = auth.endSessionUrl('https://app.example.com/signed-out');
+await auth.forget();
+if (url) window.location.assign(url);
+```
+
+The SDK keeps the ID token it received at sign-in inside its stored session and
+builds `id_token_hint` itself; it is never on `currentSession()` or any
+outcome. The URL is the issuer's `/oidc/v1/end_session`, and the return address
+must be registered for the client. It is `null` when no ID token is held, and
+always on a namespace client.
+
 ### Multi-session seams: a non-default opener, storage, refresh and scopes
 
 Four options on `BrowserAuthOptions` exist for a client that is not a
@@ -250,6 +281,42 @@ wiring one in — `createBrowserAuth` throws rather than silently ignoring it.
 always reports `no-refresh-token`: the namespace exchange never retains a
 refresh token to begin with.
 
+## Native sign-in for a desktop or mobile shell
+
+`@wtfalch/auth/desktop` mounts the handoff under `/auth/desktop/*`:
+`createDesktopHandoff({ auth, appUrl, secret, appId, scheme, store, admit })`.
+The shell opens `/auth/desktop/start` in the system browser, the person signs
+in and confirms, and the shell trades its verifier for the session cookie once
+at `/auth/desktop/redeem`.
+
+- **Set `admit`.** The default, `alwaysAdmit`, hands the shell a session for
+  whoever the issuer signed in, with no further check. It fails open: an app
+  that needs an organisation, second-factor or linked-principal check and leaves
+  `admit` out gets no warning. Pass the check explicitly.
+- **The store must lock.** `lock(tx, id)` is `SELECT ... FOR UPDATE` in a real
+  store. The memory store locks per row; a store that only reads lets two
+  concurrent redeems both get the cookie.
+- **Rate-limit `/auth/desktop/start` at the edge too.** The handler caps open
+  sign-ins per caller (`maxStartsPerCaller`, default 8, keyed on the address in
+  `clientAddressHeader`, default `cf-connecting-ip`) under the store's total
+  capacity. Callers with no such header share one bucket.
+- **Log unexpected failures.** The browser sees only `unavailable`; pass
+  `onError` to receive `{ step, reason, errorName }` (fixed text, never a
+  message, cookie or verifier) and alert on it.
+
+## An MCP resource with a path
+
+`@wtfalch/auth/mcp` serves several apps on one host, each at its own resource
+URL (`https://host/a/mcp`, `https://host/b/mcp`). Serve each app's metadata at
+`protectedResourceMetadataPath({ issuer, audience, resource })`, which is the
+RFC 9728 path-suffixed form (`/.well-known/oauth-protected-resource/a/mcp`; a
+resource at the root keeps `/.well-known/oauth-protected-resource`), with
+`protectedResourceMetadata(...)` as the body. The path is exact: `/a/mcp` and
+`/a/mcp2` never share one, and a trailing slash is part of it. `mcpChallenge`
+names the same URL. Each app has its own `audience`, and a token issued for one
+is refused (`invalid`) at the other. A stage copy passes its own host's
+`resource`, never the live one.
+
 ## Configuration
 
 | | |
@@ -309,6 +376,51 @@ Not available in namespace mode. `extraScopes` on `createAuth`'s options
 adds to the scope every sign-in and QR device grant asks for, for a
 resource server's own audience scope. See `docs/adopting.md` for both.
 
+## Verifying a person's access token
+
+`createPersonTokenVerifier` (`@wtfalch/auth/person-token`) is for a server that
+accepts a signed-in person's bearer token. `verify(token)` returns
+`{ sub, organizationId? }` or `null`; `null` covers a bad token and an issuer
+that could not be asked alike. A JWT is checked against the issuer's keys only;
+an opaque token is introspected (RFC 7662).
+
+`verifyOutcome(token)` is for a caller that must tell those apart. It also
+introspects a JWT after the signature checks, so a revoked JWT is refused
+before its `exp`. It returns `{ ok: true, identity }` or `{ ok: false, reason }`
+with `reason` one of `invalid`, `expired`, `revoked` or `unavailable`.
+`unavailable` means the issuer could not be asked (network error, non-2xx,
+unreadable answer): answer with a retryable error and do not remember it as a
+refusal. It needs `introspectionClientId` and `introspectionClientSecret`;
+without them every token is `invalid`. A positive introspection answer is
+cached for up to 60 seconds; a refusal or an `unavailable` never is.
+
+`organizationId` is present only when the token's organisation claim is a
+non-empty string. An empty or non-string claim is treated as missing and the
+token still verifies.
+
+## Back-channel logout
+
+In namespace mode, `auth.backchannelLogout` (mounted by `handle` at
+`{basePath}/backchannel-logout`) receives the issuer's own POST of a
+`logout_token` and ends every session of the subject it names. Register that
+URL as the client's back-channel logout URI at the issuer. It takes no
+same-origin check, because the issuer calls it, not a browser.
+
+A token is refused with 400 unless it is signed by the issuer's published keys
+for this client, carries the back-channel-logout event, no `nonce`, an `iat`
+no older than two minutes (plus 60 seconds of clock tolerance) and an `exp`.
+There is no `jti` store, so that window is all that limits a replay, and a
+replay only ends sessions again. A body over 16 KiB is refused with 413. Outside
+namespace mode the route answers 404.
+
+A token that names only a `sid` (the issuer's own session id) is answered 200
+and ends nothing: the session store is keyed by subject. Configure the issuer
+to send `sub`, or sessions stay alive after logout.
+
+Sessions are also re-checked against the issuer at least every 60 seconds
+whatever `freshness` is set to, so a revoked or deactivated person is signed
+out within a minute even if the logout call never arrives.
+
 ## Passkeys and QR sign-in
 
 Passkeys live on each app's own domain: the relying-party ID is the app's

package/dist/auth.d.ts

@@ -208,6 +208,14 @@ export interface Auth {
     complete(callbackUrl: string, cookieHeader: string | null, requestHeaders?: Headers): Promise<Completed>;
     /** POST {basePath}/logout */
     logout(request: Request): Promise<Response>;
+    /**
+     * POST {basePath}/backchannel-logout: the issuer's own call, not the
+     * browser's. Needs namespace mode -- a plain cookie session holds no
+     * server-side record this can end. Throws if namespace mode is not
+     * configured; use the OIDC back-channel logout registration to point only
+     * namespace-mode deployments at it.
+     */
+    backchannelLogout(request: Request): Promise<Response>;
     /** GET {basePath}/verify?userId=&code= */
     verify(request: Request): Promise<Response>;
     /** GET {basePath}/link?sessionId=&code= : the sign-in link from an email, on any device. */
@@ -308,6 +316,25 @@ export interface Auth {
     }): Promise<{
         userId: string;
     }>;
+    /**
+     * Replaces the developer's own session with one for a test user, `userId`
+     * -- act-as, refused everywhere but a stage or laptop entry (see
+     * `App.actAs` in the broker). Runs its own OIDC transaction, exactly as
+     * `resetPassword` does, so there is no `authRequestId` to receive.
+     *
+     * `actorId` is the developer's own id -- not resolved from a request here,
+     * because the caller already knows who is signed in -- and travels into
+     * the `act_as.started` event `onActAs` writes once the broker has made the
+     * session and finished the auth request. That write is required and
+     * awaited: unlike `onAuthEvent`, a throw or a rejection from `onActAs`
+     * fails this call, because an admin override nobody's audit trail caught
+     * is worse than one refused outright.
+     */
+    actAs(input: {
+        actorId: string;
+        userId: string;
+        next?: string;
+    }, requestHeaders?: Headers): Promise<Completed>;
     handle(request: Request): Promise<Response>;
     /**
      * `refresh: false` for callers that cannot set cookies; they get a user only while the token is valid.
@@ -336,7 +363,8 @@ export interface Auth {
     /**
      * Where to send somebody when a sign-in step failed for a reason they
      * cannot fix by retrying it automatically: `onError` with `?auth_error=`,
-     * which is the same shape the callback's own failures use. Exposed because
+     * which is the shape the callback's own failures use. Unlike a callback
+     * failure that had a transaction, it carries no `next`. Exposed because
      * the Next adapter has to reach it from a server component, where a
      * `Response` is no use.
      */

package/dist/auth.js

@@ -6,7 +6,7 @@ import { namespaceSessions } from './namespace-session.js';
 import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, rejected, scopeFor, } from './oidc.js';
 import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
 import { safeLoginHint, safeNextPath } from './redirect.js';
-import { expiryOf, issuedAtOf, timeoutSignal } from './util.js';
+import { expiryOf, issuedAtOf, recheckSeconds, timeoutSignal } from './util.js';
 export function createAuth(input) {
     // Resolved on first use so `next build`, which imports every route module, needs none of the values set.
     let resolved = null;
@@ -128,12 +128,36 @@ export function createAuth(input) {
             return false;
         return Date.now() / 1000 - user.authTime <= maxAge + CLOCK_TOLERANCE;
     };
+    /**
+     * `/start` takes its parameters from the query on a GET and from a form-encoded
+     * body on a POST (the entry form posts, so an email hint stays out of URLs, logs
+     * and `Referer`). A POST ignores the query; it must come from this app's own
+     * origin, declare a small length and be a form body.
+     */
+    const startParams = async (request) => {
+        if (request.method !== 'POST')
+            return new URL(request.url).searchParams;
+        if (!isSameOrigin(request, options().appUrl.origin))
+            return new Response('Forbidden', { status: 403 });
+        const type = request.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+        if (type !== 'application/x-www-form-urlencoded')
+            return new Response('Unsupported Media Type', { status: 415 });
+        const length = request.headers.get('content-length');
+        if (length === null || !/^\d{1,9}$/.test(length) || Number(length) > START_BODY_MAX)
+            return new Response('Payload Too Large', { status: 413 });
+        const text = await request.text();
+        if (text.length > START_BODY_MAX)
+            return new Response('Payload Too Large', { status: 413 });
+        return new URLSearchParams(text);
+    };
     const start = async (request) => {
         if (!isNavigation(request))
             return new Response('Unauthorized', { status: 401 });
         if (options().namespace && !(await sessions.bindingActive()))
             return unavailable();
-        const params = new URL(request.url).searchParams;
+        const params = await startParams(request);
+        if (params instanceof Response)
+            return params;
         const next = safeNextPath(params.get('next'), options().afterLogin);
         // Only the gate can ask for a silent pass: its sealed marker is the sole way
         // in, and the query's own `prompt` never reaches `none`. An explicit choice
@@ -326,7 +350,7 @@ export function createAuth(input) {
         const route = pathname.startsWith(`${options().basePath}/`)
             ? pathname.slice(options().basePath.length + 1)
             : null;
-        if (route === 'start' && request.method === 'GET')
+        if (route === 'start' && (request.method === 'GET' || request.method === 'POST'))
             return start(request);
         if (route === 'callback' && request.method === 'GET')
             return callback(request);
@@ -336,6 +360,8 @@ export function createAuth(input) {
             return link(request);
         if (route === 'logout' && request.method === 'POST')
             return logout(request);
+        if (route === 'backchannel-logout' && request.method === 'POST')
+            return backchannelLogout(request);
         return new Response('Not found', { status: 404 });
     };
     const readCookie = async (value, { refresh = true } = {}) => {
@@ -354,7 +380,7 @@ export function createAuth(input) {
         const exp = expiryOf(session.idt);
         const iat = issuedAtOf(session.idt);
         const valid = exp !== null && exp > now - 60;
-        const stale = iat !== null && now - iat >= options().freshness;
+        const stale = iat !== null && now - iat >= recheckSeconds(options().freshness);
         const due = exp === null || exp - options().refreshWindow <= now || stale;
         if (due && refresh && session.rt) {
             try {
@@ -461,6 +487,47 @@ export function createAuth(input) {
             throw new Error('@wtfalch/auth: revokeSessions needs namespace sessions');
         return sessions.revokeSubject(userId);
     };
+    /**
+     * POST {basePath}/backchannel-logout: the issuer's own back-channel call,
+     * never the browser's -- so, unlike `logout`, this takes no same-origin
+     * check. A logout token names a session by `sub` and/or `sid`; this store
+     * keys a record by subject, not by the issuer's session id, so a `sid`-only
+     * token is accepted (200, per the spec: a token this app cannot act on is
+     * not a token it may reject) but ends nothing. Every failure path answers
+     * with no cookie and nothing about which case it was, since the caller is
+     * the issuer, not the person the token names.
+     */
+    const backchannelLogout = async (request) => {
+        if (!options().namespace)
+            return new Response('Not found', { status: 404, headers: NO_STORE });
+        if (request.method !== 'POST')
+            return new Response('Method not allowed', { status: 405, headers: NO_STORE });
+        let token;
+        try {
+            const body = await readBounded(request, BACKCHANNEL_LOGOUT_MAX_BODY_BYTES);
+            if (body === null) {
+                return backchannelLogoutError('invalid_request', 'the request body is too large', 413);
+            }
+            token = new URLSearchParams(body).get('logout_token');
+        }
+        catch {
+            return backchannelLogoutError('invalid_request', 'the request body could not be read');
+        }
+        if (!token)
+            return backchannelLogoutError('invalid_request', 'missing logout_token');
+        let claims;
+        try {
+            claims = await oidc().verifyLogoutToken(token);
+        }
+        catch (error) {
+            if (rejected(error))
+                return backchannelLogoutError('invalid_token', 'the logout token was refused');
+            throw error;
+        }
+        if (claims.sub)
+            await sessions.revokeSubject(claims.sub);
+        return new Response(null, { status: 200, headers: NO_STORE });
+    };
     const listSessions = async (request) => {
         if (!options().namespace)
             throw new Error('@wtfalch/auth: sessions needs namespace sessions');
@@ -564,6 +631,30 @@ export function createAuth(input) {
         emit({ type: 'createTestUser', email: input.email, userId: result.userId });
         return result;
     };
+    /**
+     * Runs its own transaction, as `resetPassword` does. No hosted-login
+     * handoff: the broker's `/act-as` either finishes the auth request
+     * directly or refuses outright, so there is nothing for `finishOrHandoff`
+     * to catch here.
+     */
+    const actAs = async ({ actorId, userId, next }, requestHeaders) => {
+        const onActAs = options().onActAs;
+        if (!onActAs)
+            throw new Error('@wtfalch/auth: onActAs is required to use actAs');
+        const flow = await serverFlow();
+        const callbackUrl = await broker().actAs({ authRequestId: flow.id, actorId, userId });
+        // Audited only once `finish` has made the session: a failed `finish` leaves no
+        // `act_as.started` for an attempt the caller sees as failed, and a retry logs once.
+        const completed = await finish(callbackUrl, flow, safeNextPath(next, options().afterLogin), requestHeaders);
+        await onActAs({
+            type: 'act_as.started',
+            actor: actorId,
+            target: userId,
+            client: options().clientId,
+            time: Date.now(),
+        });
+        return completed;
+    };
     /**
      * An admin's reset for somebody in this app's own organisation whom
      * `requestPasswordReset` cannot otherwise get back in -- nobody at the
@@ -945,6 +1036,7 @@ export function createAuth(input) {
         callback,
         complete,
         logout,
+        backchannelLogout,
         verify,
         link,
         followLink,
@@ -954,6 +1046,7 @@ export function createAuth(input) {
         sendLink,
         invite,
         createTestUser,
+        actAs,
         handle,
         read,
         readCookie,
@@ -994,6 +1087,45 @@ function redirect(location, cookies, status = 302) {
         headers.append('Set-Cookie', cookie.header);
     return new Response(null, { status, headers });
 }
+const NO_STORE = { 'Cache-Control': 'no-store' };
+/** A logout token is a few hundred bytes; this is generous and still small. */
+const BACKCHANNEL_LOGOUT_MAX_BODY_BYTES = 16 * 1024;
+/** The request body as text, or null when it is larger than `max` bytes. Stops reading at the cap. */
+async function readBounded(request, max) {
+    const declared = Number(request.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > max)
+        return null;
+    if (!request.body)
+        return '';
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+/** A back-channel logout endpoint's 400 error body, per OpenID Connect Back-Channel Logout 1.0 §2.6. */
+function backchannelLogoutError(error, description, status = 400) {
+    return new Response(JSON.stringify({ error, error_description: description }), {
+        status,
+        headers: { 'content-type': 'application/json', ...NO_STORE },
+    });
+}
 function matches(rule, pathname) {
     if (!rule)
         return false;
@@ -1070,6 +1202,8 @@ function userFrom(claims) {
     };
 }
 // The token itself is bad, as opposed to the keys being unreachable or rotating.
+/** The most a `/start` form body may hold: a path, a hint and three short fields. */
+const START_BODY_MAX = 4096;
 function isNavigation(request) {
     const mode = request.headers.get('sec-fetch-mode');
     if (mode && mode !== 'navigate')

package/dist/broker.d.ts

@@ -146,6 +146,12 @@ export declare class Broker {
     }): Promise<{
         userId: string;
     }>;
+    /** The service half of `Auth['actAs']`: a session for the target, finishing `authRequestId`. */
+    actAs(input: {
+        authRequestId: string;
+        actorId: string;
+        userId: string;
+    }): Promise<string>;
     sendReset(email: string, next: string): Promise<unknown>;
     sendVerification(email: string, next: string): Promise<unknown>;
     /**

package/dist/broker.js

@@ -137,6 +137,11 @@ export class Broker {
     createTestUser(input) {
         return this.call('POST', '/test-users', input);
     }
+    /** The service half of `Auth['actAs']`: a session for the target, finishing `authRequestId`. */
+    async actAs(input) {
+        const { callbackUrl } = await this.call('POST', '/act-as', input);
+        return callbackUrl;
+    }
     sendReset(email, next) {
         return this.call('POST', '/reset/send', { email, next });
     }

package/dist/browser.d.ts

@@ -72,7 +72,7 @@ export interface BrowserAuthOptions {
      * origin `/auth` belongs to Stalwart and never reaches the app.
      */
     callbackPath?: string;
-    /** Scopes to ask for. `openid` is required; the rest is the app's business. */
+    /** Scopes to ask for. `openid` is required (`createBrowserAuth` throws without it); the rest is the app's business. */
     scope?: string;
     /**
      * Extra scopes appended to `scope` at `/authorize`, de-duplicated with it —
@@ -176,6 +176,16 @@ export interface BrowserAuth {
      * to the other's now-spent refresh token.
      */
     refresh(): Promise<RefreshOutcome>;
+    /**
+     * The issuer's sign-out URL carrying `id_token_hint` and
+     * `post_logout_redirect_uri`, built from the ID token this tab received at
+     * sign-in, or null when none is held (a session from before this existed, a
+     * namespace client, or after `forget()`). The token itself never leaves the
+     * SDK. Call it before `forget()`, which drops it; then send the browser there.
+     * The URL is the issuer's fixed `/oidc/v1/end_session`; `postLogoutRedirectUri`
+     * must be registered for the client at the issuer.
+     */
+    endSessionUrl(postLogoutRedirectUri: string): string | null;
     /** Drop the session, and do not silently take another in this tab. Awaits
      *  the store's writes and invalidates pending sign-in/refresh completions.
      * After it resolves, an older write cannot restore the forgotten session. */

package/dist/browser.js

@@ -49,13 +49,17 @@ function verifier() {
     return base64url(crypto.getRandomValues(new Uint8Array(32)).buffer);
 }
 function publicSession(session) {
-    const { refreshToken, ...rest } = session;
+    const { refreshToken, idToken, ...rest } = session;
     return rest;
 }
 // Instances using the same store and context share cancellation and refreshes.
 // The network is outside this queue: forget must not wait for a token response.
 const coordinators = new WeakMap();
 export function createBrowserAuth(options) {
+    // The nonce check reads the ID token, and the issuer sends one only for `openid`.
+    // Without it every sign-in would be refused after the code exchange, so refuse here.
+    if (!(options.scope ?? 'openid').split(/\s+/).includes('openid'))
+        throw new Error('createBrowserAuth: scope must include openid');
     if (options.namespace) {
         // The namespace path coordinates a shared session across tabs and
         // clients through fixed `sessionStorage`/`localStorage` keys (see
@@ -232,6 +236,8 @@ export function createBrowserAuth(options) {
                 accessToken: token.access_token,
                 expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
                 refreshToken: token.refresh_token,
+                // A refresh response may carry a new ID token; otherwise the one from sign-in stays.
+                idToken: token.id_token ?? session.idToken,
             };
             await store.set(tokenKey, JSON.stringify(next));
             if (!current(generation))
@@ -242,6 +248,15 @@ export function createBrowserAuth(options) {
     return {
         accountChanged: () => false,
         currentSession,
+        endSessionUrl(postLogoutRedirectUri) {
+            const idToken = readStored()?.idToken;
+            if (!idToken)
+                return null;
+            const url = new URL(`${options.issuer.replace(/\/$/, '')}/oidc/v1/end_session`);
+            url.searchParams.set('id_token_hint', idToken);
+            url.searchParams.set('post_logout_redirect_uri', postLogoutRedirectUri);
+            return url.toString();
+        },
         silentSignInAvailable,
         async trySilentSignIn(returnTo = window.location.pathname) {
             if (!silentSignInAvailable())
@@ -344,6 +359,7 @@ export function createBrowserAuth(options) {
                     accessToken: token.access_token,
                     expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
                     refreshToken: token.refresh_token,
+                    idToken: token.id_token,
                 };
                 await store.set(tokenKey, JSON.stringify(session));
                 if (!current(generation))

package/dist/config.d.ts

@@ -32,6 +32,20 @@ export type AuthEvent =
     email: string;
     userId: string;
 };
+/**
+ * `actAs`'s own audit record: who asked (`actor`), who they viewed the app
+ * as (`target`), which client the session was opened for, and when. Unlike
+ * `AuthEvent`, this has exactly one variant and one writer (`onActAs`),
+ * because act-as is the one call here that must never go unrecorded -- see
+ * `onActAs`'s own doc comment for what that changes.
+ */
+export interface ActAsEvent {
+    type: 'act_as.started';
+    actor: string;
+    target: string;
+    client: string;
+    time: number;
+}
 /**
  * Why `accessToken` refused: no session (no cookie in cookie mode, no live
  * record behind the namespace handle in namespace mode), a session with no
@@ -70,11 +84,11 @@ export interface AuthOptions {
      * `appKey`; unused without it. Every replica of the app must share one.
      */
     sessionStore?: SessionStore;
-    /** This app's origin, e.g. https://portal.valet.wtfalch.dev. Every URL the SDK builds starts here, never from the request's Host. */
+    /** This app's origin, e.g. https://portal.example.test. Every URL the SDK builds starts here, never from the request's Host. */
     appUrl: string | undefined;
-    /** From scripts/provisioned.json. */
+    /** From the stack's provisioned.json. */
     clientId: string | undefined;
-    /** From scripts/provisioned.json. Sent as a scope and checked on every token. */
+    /** From the stack's provisioned.json. Sent as a scope and checked on every token. */
     organizationId: string | undefined;
     /**
      * Extra scopes appended to `scopeFor`'s fixed set, on both the
@@ -111,7 +125,12 @@ export interface AuthOptions {
     afterLogin?: string;
     /** Default /. Must be a registered post-logout URI. */
     afterLogout?: string;
-    /** Where a failed callback lands, with ?auth_error=<reason>. Default /. */
+    /**
+     * Where a failed callback lands, with `?auth_error=<reason>`, and `&next=<path>`
+     * when the failed sign-in had a transaction. `next` is a same-origin path, but anyone
+     * can open this page with a `next` of their own: run it through `safeNextPath` before
+     * building a link. Default /.
+     */
     onError?: string;
     /** Where a verified email link lands. Default /. */
     afterVerify?: string;
@@ -137,6 +156,16 @@ export interface AuthOptions {
      * the call it rode in on.
      */
     onAuthEvent?: (event: AuthEvent) => void;
+    /**
+     * Required to call `actAs`. Unlike `onAuthEvent`, this IS awaited, and a
+     * throw or a rejection fails the `actAs` call -- the whole point of
+     * act-as is that it never happens off the record, so a session nobody's
+     * audit trail caught must not go live silently. The broker has already
+     * made the session and finished the auth request by the time this runs;
+     * a failure here cannot undo that, only stop the SDK from handing the
+     * browser the result.
+     */
+    onActAs?: (event: ActAsEvent) => Promise<void>;
 }
 export interface ResolvedOptions {
     namespace: ReturnType<typeof resolveNamespaceContext> | null;
@@ -174,6 +203,7 @@ export interface ResolvedOptions {
     secure: boolean;
     fetch: typeof fetch;
     onAuthEvent: ((event: AuthEvent) => void) | null;
+    onActAs: ((event: ActAsEvent) => Promise<void>) | null;
 }
 export declare function resolveOptions(options: AuthOptions): ResolvedOptions;
 /**

package/dist/config.js

@@ -61,6 +61,7 @@ export function resolveOptions(options) {
         secure: appUrl.protocol === 'https:',
         fetch: options.fetch ?? globalThis.fetch,
         onAuthEvent: options.onAuthEvent ?? null,
+        onActAs: options.onActAs ?? null,
     };
 }
 function required(value, name) {