@wtfalch/auth 0.32.0 → 0.34.0

package/README.md

@@ -293,9 +293,43 @@ at `/auth/desktop/redeem`.
   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.** A multi-replica app passes its Postgres client to
+  `createPostgresDesktopHandoffStore(client, { capacity, ttlMs, pollGapMs })`
+  and runs `DESKTOP_HANDOFFS_TABLE_SQL` once in a migration. The client is two
+  methods, so any driver fits: `query(text, values)` resolves to the rows, and
+  `transaction(fn)` runs `fn` with the same `query` shape on one connection,
+  committing when `fn` returns and rolling back when it throws. With `pg`:
+
+  ```ts
+  const client: DesktopHandoffSqlClient = {
+    query: async (text, values) => (await pool.query(text, [...values])).rows,
+    async transaction(fn) {
+      const connection = await pool.connect();
+      try {
+        await connection.query('BEGIN');
+        const result = await fn({
+          query: async (text, values) => (await connection.query(text, [...values])).rows,
+        });
+        await connection.query('COMMIT');
+        return result;
+      } catch (error) {
+        await connection.query('ROLLBACK');
+        throw error;
+      } finally {
+        connection.release();
+      }
+    },
+  };
+  ```
+
+  The table is Boule's and Archon's `desktop_handoffs` with a `caller_hash text`
+  column; an app that has the table without it runs
+  `ALTER TABLE desktop_handoffs ADD COLUMN IF NOT EXISTS caller_hash text`. Test
+  any store, this one included, with `checkDesktopHandoffStore`.
 - **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.
+  concurrent redeems both get the cookie. `createMemoryDesktopHandoffStore`
+  serves one process only.
 - **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
@@ -433,6 +467,56 @@ A phone that is already signed in can also approve a new device from a QR
 code, the issuer's OAuth device grant opted into per namespace binding with
 `qrSignIn: true`, through `startQrSignIn` and `pollQrSignIn`.
 
+## Workspaces for your app's customers
+
+An app with `workspaces` on its entry gets `WORKSPACES_URL`, `WORKSPACES_API_KEY`
+and `AUTH_ORGANIZATION_ID`. `@wtfalch/auth/workspaces` calls the broker with them.
+The app keeps the current workspace id itself; this one holds it in a cookie.
+
+```ts
+import { cookies } from 'next/headers';
+import { workspaces, WorkspacesError } from '@wtfalch/auth/workspaces';
+import { auth } from './auth'; // your createAuth() instance
+
+const ws = workspaces(); // throws at once if an env value is missing
+
+export async function currentWorkspace(request: Request) {
+  const { user } = await auth.read(request);
+  if (!user) return null;
+  const id = (await cookies()).get('workspace')?.value;
+  const role = id ? await ws.access(id, user) : null; // never trust the cookie alone
+  return id && role ? { id, role } : null;
+}
+
+export async function createWorkspace(request: Request, name: string) {
+  const { user } = await auth.read(request);
+  if (!user) throw new Error('Sign in first.');
+  const made = await ws.create({ name, owner: user });
+  (await cookies()).set('workspace', made.id, { httpOnly: true, sameSite: 'lax', secure: true });
+  return made;
+}
+
+export async function inviteBy(request: Request, id: string, email: string) {
+  const { user } = await auth.read(request);
+  if (!user) throw new Error('Sign in first.');
+  try {
+    await ws.invite(id, { email, role: 'member', actor: user }); // the broker mails the link
+  } catch (error) {
+    if (error instanceof WorkspacesError && error.status === 403) return 'Only an owner can invite.';
+    throw error;
+  }
+}
+// On the page behind `inviteUrl?token=`: await ws.accept(token, user) -> { workspaceId, role }
+
+// Any member: who is in the workspace -> [{ sub, email, name, role }] (name is null; email is '' only for a creator from before this existed)
+await ws.members(id, user);
+// Owner only:
+await ws.invitations(id, user); // pending -> [{ id, email, role, createdAt, expiresAt }]
+await ws.revokeInvitation(id, invitationId, user); // the emailed link stops working
+await ws.rename(id, 'New name', user);
+await ws.archive(id, user); // leaves listFor; every later call on it fails with status 410
+```
+
 ## Preview routes
 
 For apps on live/idle releases. The balancer sends a request with the `bg_preview=1` cookie to the idle slot, after asking the live slot whether the person may see it.
@@ -441,16 +525,15 @@ For apps on live/idle releases. The balancer sends a request with the `bg_previe
 import { createPreviewRoutes } from '@wtfalch/auth';
 
 export const preview = createPreviewRoutes({
-  readSession: async (request) => (await auth.read(request, { refresh: false })).user,
-  mayPreview: (session) => canPreview(session), // `releases:preview` in the app's production authz
-  appOrigin: 'https://app.example.test', // required: the app's own origin, the one `appUrl` names
+  auth, // the app's own `createAuth(...)` instance
+  mayPreview: (user) => canPreview(user), // `releases:preview` in the app's production authz
 });
 // GET    /api/foundry/preview-check -> preview.check  (200, 401 no session, 403 otherwise)
 // POST   /api/foundry/preview       -> preview.set    (204 and the cookie, same-origin only)
 // DELETE /api/foundry/preview       -> preview.clear  (204, same-origin only, no permission needed)
 ```
 
-Answers carry no body and `cache-control: no-store`. A reader or permission check that throws answers 403 and logs one fixed line with the error name only. `appOrigin` is required and is never read from the request. `PREVIEW_COOKIE`, `PREVIEW_CHECK_PATH` and `PREVIEW_PATH` are exported too.
+Answers carry no body and `cache-control: no-store`. A reader or permission check that throws answers 403 and logs one fixed line with the error name only. The session is read through `auth` (without refreshing), and the trusted origin and the cookie's `Secure` rule come from its `appUrl`, never from the request. They are read on the first request, so `next build` importing this module with no environment set does not throw. A request from another origin is refused with 403 and no log line. `PREVIEW_COOKIE`, `PREVIEW_CHECK_PATH` and `PREVIEW_PATH` are exported too.
 
 ## Documentation
 

package/dist/auth.d.ts

@@ -151,6 +151,45 @@ export type PasskeySignInStart = {
     ok: false;
     error: SignInError;
 };
+/** What a fresh sign-in step needs the caller to do. `cookies` are always to be set, success or not. */
+export type FreshOutcome = {
+    ok: true;
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    error: SignInError | 'other_person' | 'invalid_code';
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    secondFactor: {
+        token: string;
+        methods: 'totp'[];
+    };
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    hosted: true;
+    next?: string;
+    cookies: SetCookie[];
+};
+export type FreshStart = {
+    ok: true;
+    authRequestId: string;
+    loginHint: string;
+    passkey: boolean;
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    hosted: true;
+    cookies: SetCookie[];
+};
+export type FreshPasskeyStart = {
+    ok: true;
+    options: unknown;
+    cookies: SetCookie[];
+} | Exclude<FreshOutcome, {
+    ok: true;
+}>;
 export interface Completed {
     location: string;
     cookies: SetCookie[];
@@ -195,6 +234,10 @@ export interface QrPollResult {
 }
 export interface Auth {
     readonly sessionCookieName: string;
+    /** The app's own origin, from `appUrl`. Read on first use, so it throws only if `appUrl` is missing or malformed. */
+    readonly appOrigin: string;
+    /** Whether this app's cookies carry `Secure`: true when `appUrl` is https. The same rule the session cookie uses. */
+    readonly cookiesSecure: boolean;
     /** GET {basePath}/start?next=&intent= : begins the OIDC flow; the issuer sends the browser to {basePath}/login?authRequest= */
     start(request: Request): Promise<Response>;
     /** GET {basePath}/callback */
@@ -421,6 +464,35 @@ export interface Auth {
     endSession(request: Request, key: string): Promise<void>;
     /** The auth request the issuer sent the browser here with. Refuses one for another application. */
     authRequest(id: string): Promise<AuthRequest>;
+    /**
+     * Starts a `prompt=login` auth request for whoever is signed in on `request`
+     * and seals its PKCE transaction in a cookie. Nothing redirects. `hosted`
+     * means the modal cannot be used: nobody is signed in, or the issuer did not
+     * start a request. The other four calls take the same `request` and the
+     * `authRequestId` this returned.
+     */
+    startFreshSignIn(request: Request, opts?: {
+        next?: string;
+    }): Promise<FreshStart>;
+    /** The password step. The email is the signed-in person's own, never an argument. */
+    finishFreshSignIn(request: Request, input: {
+        authRequestId: string;
+        password: string;
+    }): Promise<FreshOutcome>;
+    /** A passkey challenge for the signed-in person; `finishFreshPasskey` answers it. */
+    startFreshPasskey(request: Request, input: {
+        authRequestId: string;
+    }): Promise<FreshPasskeyStart>;
+    finishFreshPasskey(request: Request, input: {
+        authRequestId: string;
+        credential: unknown;
+    }): Promise<FreshOutcome>;
+    /** The code step after a `secondFactor` outcome. */
+    verifyFreshSecondFactor(request: Request, input: {
+        authRequestId: string;
+        token: string;
+        code: string;
+    }): Promise<FreshOutcome>;
     signIn(input: {
         authRequestId: string;
         email: string;

package/dist/auth.js

@@ -1,4 +1,5 @@
 import * as client from 'openid-client';
+import { declaredWithin, readBounded } from './body.js';
 import { Broker, BrokerError } from './broker.js';
 import { resolveOptions, } from './config.js';
 import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openRecord, openSession, openSilent, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealSilent, sealTransaction, sessionCookieName, silentCookieName, transactionCookieName, } from './cookies.js';
@@ -6,7 +7,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 { isSameOrigin, safeLoginHint, safeNextPath } from './redirect.js';
-import { expiryOf, issuedAtOf, recheckSeconds, timeoutSignal } from './util.js';
+import { NO_STORE, 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;
@@ -142,11 +143,11 @@ export function createAuth(input) {
         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)
+        if (!declaredWithin(request, START_BODY_MAX))
             return new Response('Payload Too Large', { status: 413 });
-        const text = await request.text();
-        if (text.length > START_BODY_MAX)
+        // The declared length is a hint; the read itself stops at the cap.
+        const text = await readBounded(request, START_BODY_MAX);
+        if (text === null)
             return new Response('Payload Too Large', { status: 413 });
         return new URLSearchParams(text);
     };
@@ -546,13 +547,13 @@ export function createAuth(input) {
      * An OIDC flow this app starts and finishes itself, for a person arriving
      * from an email rather than from a browser the app sent to the issuer.
      */
-    const serverFlow = async () => {
+    const serverFlow = async (authorization = {}) => {
         if (options().namespace && !(await sessions.bindingActive()))
             throw new AuthError('unavailable', 'the namespace binding is not active');
         const state = client.randomState();
         const nonce = client.randomNonce();
         const verifier = client.randomPKCECodeVerifier();
-        const target = await oidc().authorizationUrl(state, nonce, verifier);
+        const target = await oidc().authorizationUrl(state, nonce, verifier, authorization);
         const response = await options().fetch(target.href, {
             redirect: 'manual',
             signal: timeoutSignal(),
@@ -612,6 +613,187 @@ export function createAuth(input) {
             };
         }
     };
+    /**
+     * The fresh sign-in is the modal's version of `/auth/start` + `/auth/callback`:
+     * the same PKCE transaction, started and finished on the server, so the page
+     * never navigates. The transaction cookie holds the auth request id (`ar`),
+     * and every step refuses an id that is not that one.
+     */
+    const freshContext = async (request, authRequestId) => {
+        const { user } = await read(request, { refresh: false });
+        const transaction = await openTransaction(options(), cookieFrom(request.headers.get('cookie'), transactionCookieName(options())));
+        if (!user?.email)
+            return {
+                kind: 'refused',
+                outcome: { ok: false, hosted: true, next: transaction?.nx, cookies: [] },
+            };
+        if (!transaction || transaction.ar === undefined || transaction.ar !== authRequestId)
+            return { kind: 'refused', outcome: { ok: false, error: 'request', cookies: [] } };
+        return { kind: 'ready', user, email: user.email, transaction };
+    };
+    const startFreshSignIn = async (request, opts = {}) => {
+        const { user } = await read(request, { refresh: false });
+        const loginHint = user?.email ? safeLoginHint(user.email) : undefined;
+        if (!user || !loginHint)
+            return { ok: false, hosted: true, cookies: [] };
+        let flow;
+        try {
+            flow = await serverFlow({ prompt: 'login', loginHint });
+        }
+        catch (error) {
+            console.error('@wtfalch/auth: could not start a fresh sign-in', error instanceof Error ? error.name : 'unknown');
+            return { ok: false, hosted: true, cookies: [] };
+        }
+        const cookie = await sealTransaction(options(), {
+            st: flow.state,
+            nc: flow.nonce,
+            cv: flow.verifier,
+            nx: safeNextPath(opts.next, options().afterLogin),
+            ar: flow.id,
+        });
+        let passkey = false;
+        try {
+            await broker().startPasskeySignIn({ authRequestId: flow.id, email: user.email });
+            passkey = true;
+        }
+        catch (error) {
+            if (!(error instanceof BrokerError && error.status < 500)) {
+                console.error('@wtfalch/auth: could not check for a passkey', error instanceof Error ? error.name : 'unknown');
+            }
+        }
+        return { ok: true, authRequestId: flow.id, loginHint, passkey, cookies: [cookie] };
+    };
+    /** Turns what the broker said into the outcome the modal acts on. */
+    const freshFailure = (error, cookies = [], next) => {
+        if (error instanceof BrokerError) {
+            if (needsHostedLogin(error) || error.error === 'password_change_required')
+                return { ok: false, hosted: true, next, cookies };
+            if (error.error === 'second_factor_required') {
+                if (error.secondFactor?.methods.includes('totp'))
+                    return {
+                        ok: false,
+                        secondFactor: { token: error.secondFactor.token, methods: ['totp'] },
+                        cookies,
+                    };
+                return { ok: false, hosted: true, next, cookies };
+            }
+            if (error.error === 'invalid_code')
+                return { ok: false, error: 'invalid_code', cookies };
+            if (error.error === 'invalid')
+                return { ok: false, error: 'request', cookies };
+        }
+        else {
+            console.error('@wtfalch/auth: a fresh sign-in step failed', error instanceof Error ? error.name : 'unknown');
+        }
+        return { ok: false, error: signInError(error), cookies };
+    };
+    /**
+     * Exchanges the callback and, only when it is the same person, replaces the
+     * session. The check comes before the session is made, so another person's
+     * sign-in leaves no record behind in namespace mode either.
+     */
+    const completeFresh = async (request, callbackUrl, user, transaction) => {
+        const cleared = clearTransaction(options());
+        if (!validCallback(callbackUrl))
+            return { ok: false, error: 'request', cookies: [cleared] };
+        if (options().namespace && !(await sessions.bindingActive()))
+            return { ok: false, error: 'unavailable', cookies: [cleared] };
+        let tokens;
+        try {
+            tokens = await oidc().exchange(new URL(callbackUrl).searchParams, {
+                state: transaction.st,
+                nonce: transaction.nc,
+                codeVerifier: transaction.cv,
+            });
+        }
+        catch (error) {
+            console.error('@wtfalch/auth: the fresh sign-in could not be exchanged', error instanceof Error ? error.name : 'unknown');
+            return { ok: false, error: 'request', cookies: [cleared] };
+        }
+        if (String(tokens.claims.sub) !== user.id)
+            return { ok: false, error: 'other_person', cookies: [cleared] };
+        const session = await sessionCookie(tokens, request.headers);
+        await replacePreviousSession(request.headers.get('cookie'));
+        return { ok: true, cookies: [cleared, session] };
+    };
+    const finishFreshSignIn = async (request, input) => {
+        const context = await freshContext(request, input.authRequestId);
+        if (context.kind === 'refused')
+            return context.outcome;
+        let callbackUrl;
+        try {
+            callbackUrl = await broker().signIn({
+                authRequestId: input.authRequestId,
+                email: context.email,
+                password: input.password,
+                secondFactor: true,
+            });
+        }
+        catch (error) {
+            return freshFailure(error, [], context.transaction.nx);
+        }
+        return completeFresh(request, callbackUrl, context.user, context.transaction);
+    };
+    const startFreshPasskey = async (request, input) => {
+        const context = await freshContext(request, input.authRequestId);
+        if (context.kind === 'refused')
+            return context.outcome;
+        try {
+            const { sessionId, options: challenge } = await broker().startPasskeySignIn({
+                authRequestId: input.authRequestId,
+                email: context.email,
+            });
+            const cookie = await sealTransaction(options(), {
+                st: context.transaction.st,
+                nc: context.transaction.nc,
+                cv: context.transaction.cv,
+                nx: context.transaction.nx,
+                ar: input.authRequestId,
+                fp: sessionId,
+            });
+            return { ok: true, options: challenge, cookies: [cookie] };
+        }
+        catch (error) {
+            return freshFailure(error, [], context.transaction.nx);
+        }
+    };
+    const finishFreshPasskey = async (request, input) => {
+        const context = await freshContext(request, input.authRequestId);
+        if (context.kind === 'refused')
+            return context.outcome;
+        if (!context.transaction.fp)
+            return { ok: false, error: 'request', cookies: [] };
+        let callbackUrl;
+        try {
+            callbackUrl = await broker().finishPasskeySignIn({
+                authRequestId: input.authRequestId,
+                sessionId: context.transaction.fp,
+                credential: input.credential,
+                secondFactor: true,
+            });
+        }
+        catch (error) {
+            return freshFailure(error, [], context.transaction.nx);
+        }
+        return completeFresh(request, callbackUrl, context.user, context.transaction);
+    };
+    const verifyFreshSecondFactor = async (request, input) => {
+        const context = await freshContext(request, input.authRequestId);
+        if (context.kind === 'refused')
+            return context.outcome;
+        let callbackUrl;
+        try {
+            callbackUrl = await broker().verifySecondFactor({
+                authRequestId: input.authRequestId,
+                token: input.token,
+                code: input.code,
+            });
+        }
+        catch (error) {
+            return freshFailure(error, [], context.transaction.nx);
+        }
+        return completeFresh(request, callbackUrl, context.user, context.transaction);
+    };
     const resendVerification = (email, next) => quietly(() => broker().sendVerification(email, safeNextPath(next, '')));
     const requestPasswordReset = (email, next) => quietly(() => broker().sendReset(email, safeNextPath(next, '')));
     const sendLink = (email, next) => quietly(() => broker().sendLink(email, safeNextPath(next, '')));
@@ -1032,6 +1214,12 @@ export function createAuth(input) {
         get sessionCookieName() {
             return sessionCookieName(options());
         },
+        get appOrigin() {
+            return options().appUrl.origin;
+        },
+        get cookiesSecure() {
+            return options().secure;
+        },
         start,
         callback,
         complete,
@@ -1061,6 +1249,11 @@ export function createAuth(input) {
         sessions: listSessions,
         endSession,
         authRequest,
+        startFreshSignIn,
+        finishFreshSignIn,
+        startFreshPasskey,
+        finishFreshPasskey,
+        verifyFreshSecondFactor,
         signIn,
         setNewPassword,
         setNewPasswordHeadless,
@@ -1087,38 +1280,8 @@ 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 }), {

package/dist/body.d.ts

@@ -0,0 +1,5 @@
+/** Bounded request bodies: the one place the package decides how much of a request it will read. */
+/** True when the request declares a plain decimal length of at most `max`. A missing or odd length is refused too. */
+export declare function declaredWithin(request: Request, max: number): boolean;
+/** The request body as text, or null when it is larger than `max` bytes. Stops reading at the cap. */
+export declare function readBounded(request: Request, max: number): Promise<string | null>;

package/dist/body.js

@@ -0,0 +1,35 @@
+/** Bounded request bodies: the one place the package decides how much of a request it will read. */
+/** True when the request declares a plain decimal length of at most `max`. A missing or odd length is refused too. */
+export function declaredWithin(request, max) {
+    const length = request.headers.get('content-length');
+    return length !== null && /^\d{1,9}$/.test(length) && Number(length) <= max;
+}
+/** The request body as text, or null when it is larger than `max` bytes. Stops reading at the cap. */
+export 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);
+}

package/dist/broker.d.ts

@@ -49,9 +49,19 @@ export declare class BrokerError extends Error {
     readonly detail?: string | undefined;
     /** Only `password_change_required` carries one: see `setNewPassword`. */
     readonly changeToken?: string | undefined;
+    /** Only `second_factor_required` carries these: see `Broker.signIn`'s `secondFactor`. */
+    readonly secondFactor?: {
+        token: string;
+        methods: string[];
+    } | undefined;
     constructor(status: number, error: string, detail?: string | undefined, 
     /** Only `password_change_required` carries one: see `setNewPassword`. */
-    changeToken?: string | undefined);
+    changeToken?: string | undefined, 
+    /** Only `second_factor_required` carries these: see `Broker.signIn`'s `secondFactor`. */
+    secondFactor?: {
+        token: string;
+        methods: string[];
+    } | undefined);
 }
 /**
  * The privileged half, over HTTP. The app holds a key that reaches its own
@@ -76,10 +86,16 @@ export declare class Broker {
         password: string;
     }>;
     authRequest(id: string): Promise<AuthRequest>;
+    /**
+     * `secondFactor: true` asks the service to answer 403 `second_factor_required`
+     * (a token to send to `verifySecondFactor`) where it would otherwise answer
+     * `hosted_login_required` only because of an enrolled one-time-code factor.
+     */
     signIn(input: {
         authRequestId: string;
         email: string;
         password: string;
+        secondFactor?: true;
     }): Promise<string>;
     /** The call after `password_change_required`: no old password, only the token that sign-in answered with. */
     setNewPassword(input: {
@@ -113,6 +129,13 @@ export declare class Broker {
         authRequestId: string;
         sessionId: string;
         credential: unknown;
+        secondFactor?: true;
+    }): Promise<string>;
+    /** The code half of a `second_factor_required` answer; finishes the auth request like `signIn`. */
+    verifySecondFactor(input: {
+        authRequestId: string;
+        token: string;
+        code: string;
     }): Promise<string>;
     followLink(input: {
         authRequestId: string;

package/dist/broker.js

@@ -4,14 +4,18 @@ export class BrokerError extends Error {
     error;
     detail;
     changeToken;
+    secondFactor;
     constructor(status, error, detail, 
     /** Only `password_change_required` carries one: see `setNewPassword`. */
-    changeToken) {
+    changeToken, 
+    /** Only `second_factor_required` carries these: see `Broker.signIn`'s `secondFactor`. */
+    secondFactor) {
         super(detail ?? error);
         this.status = status;
         this.error = error;
         this.detail = detail;
         this.changeToken = changeToken;
+        this.secondFactor = secondFactor;
         this.name = 'BrokerError';
     }
 }
@@ -53,7 +57,14 @@ export class Broker {
             throw new BrokerError(response.status, 'unavailable', `non-JSON response from ${path}`);
         }
         if (!response.ok) {
-            throw new BrokerError(response.status, String(data.error ?? 'unavailable'), data.message, typeof data.changeToken === 'string' ? data.changeToken : undefined);
+            throw new BrokerError(response.status, String(data.error ?? 'unavailable'), data.message, typeof data.changeToken === 'string' ? data.changeToken : undefined, data.error === 'second_factor_required' && typeof data.token === 'string'
+                ? {
+                    token: data.token,
+                    methods: Array.isArray(data.methods)
+                        ? data.methods.filter((m) => typeof m === 'string')
+                        : [],
+                }
+                : undefined);
         }
         return data;
     }
@@ -75,6 +86,11 @@ export class Broker {
     authRequest(id) {
         return this.call('GET', '/auth-request', { id });
     }
+    /**
+     * `secondFactor: true` asks the service to answer 403 `second_factor_required`
+     * (a token to send to `verifySecondFactor`) where it would otherwise answer
+     * `hosted_login_required` only because of an enrolled one-time-code factor.
+     */
     async signIn(input) {
         const { callbackUrl } = await this.call('POST', '/sign-in', input);
         return callbackUrl;
@@ -113,6 +129,11 @@ export class Broker {
         const { callbackUrl } = await this.call('POST', '/passkey/finish', input);
         return callbackUrl;
     }
+    /** The code half of a `second_factor_required` answer; finishes the auth request like `signIn`. */
+    async verifySecondFactor(input) {
+        const { callbackUrl } = await this.call('POST', '/second-factor/verify', input);
+        return callbackUrl;
+    }
     async followLink(input) {
         const { callbackUrl } = await this.call('POST', '/link/follow', input);
         return callbackUrl;