@wtfalch/auth 0.16.0 → 0.20.0

package/README.md

@@ -1,6 +1,6 @@
 # @wtfalch/auth
 
-Sign in against [auth.wtfalch.dev](https://auth.wtfalch.dev) from a Next.js app.
+Sign in against a self-hosted ZITADEL issuer from a Next.js app.
 
 A thin OIDC client for one self-hosted ZITADEL instance, plus a client for the
 sign-in service that sits in front of it. Apps host their own password sign-in
@@ -25,6 +25,7 @@ import { nextAuth } from '@wtfalch/auth/next';
 
 export const { handlers, proxy, getUser, requireUser, signIn } = nextAuth({
   appUrl: process.env.APP_URL,
+  issuer: process.env.AUTH_ISSUER,
   clientId: process.env.AUTH_CLIENT_ID,
   organizationId: process.env.AUTH_ORGANIZATION_ID,
   cookieSecret: process.env.AUTH_COOKIE_SECRET,
@@ -40,6 +41,39 @@ 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.
 
+## One-time passwords
+
+An account created with `changeRequired: true` holds a one-time password.
+Signing in with it gives no session and no token. `signIn`,
+`signInWithPassword` and `signUp` answer
+`{ ok: false, error: 'password_change_required', changeToken }` (in `nextAuth`,
+`{ error, changeToken }`). Show a "choose a new password" form and call
+`setNewPassword({ authRequestId, changeToken, newPassword })` (or
+`setNewPasswordHeadless({ changeToken, newPassword })`, as `signInWithPassword`
+is to `signIn`). It needs no old password and signs the person in. The
+`changeToken` is good for 5 minutes. The one-time password itself stops working
+72 hours after it was set (or after the account was created, when the issuer
+reports no password date): sign-in then answers `invalid_credentials`. The
+person recovers through an owner or Archon reset, which sets the flag again, or
+their own forgot-password reset. The limit covers every sign-in that goes
+through the broker, including hosted-login handoffs; a sign-in made at the
+issuer itself, which never reaches the broker, is not covered. `changeToken`s
+live in the broker's memory, so the broker must run as one replica. The browser `SignInOutcome` is unchanged: it never
+sees the password.
+
+## Clearing cookies in Server Actions
+
+The Next adapter writes every core cookie description with its attributes,
+including an empty value and `maxAge: 0` for clearing. Transaction, QR, email-link
+and session cookies keep their root path, host-only scope, HttpOnly and SameSite
+settings. HTTPS cookies also keep Secure and the `__Host-` prefix; local HTTP
+cookies use ordinary names without Secure. This applies to callback completion,
+password reset and QR actions, including namespace sessions.
+
+Next supports expiring cookies through
+[`cookies().set`](https://nextjs.org/docs/app/api-reference/functions/cookies#deleting-cookies).
+The adapter passes the core attributes through for clearing as well as writes.
+
 ## MFA and hosted login
 
 The broker checks the organisation's login policy and enrolled authentication
@@ -60,6 +94,15 @@ Auth-request lookup failures lead to the configured error page with
 `auth_error=request` or `auth_error=unavailable`. That page should show a
 retry link; it must not automatically restart authorization.
 
+When a sign-in fails after it started (reasons such as `state`, `unavailable`,
+`exchange`, `denied`, `organization`, `cookie`), the error URL is
+`<onError>?auth_error=<reason>&next=<path>`. `next` is the page the person came
+for, always a path starting with one `/`, URL-encoded as a single parameter, and
+present only when the sealed value is a safe same-origin path. An `onError` that
+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.
+
 ## In a browser app
 
 `@wtfalch/auth/browser` is the other half: a public PKCE client for an app that
@@ -70,7 +113,7 @@ across the estate's subdomains**.
 import { createBrowserAuth } from '@wtfalch/auth/browser';
 
 const auth = createBrowserAuth({
-  issuer: 'https://auth.wtfalch.dev',
+  issuer: 'https://auth.example.com',
   clientId: '…',              // this app's client id at the issuer
   callbackPath: '/signed-in', // when `/auth/callback` is not yours to host
 });
@@ -108,7 +151,7 @@ behaviour above exactly, so a caller that sets none of them sees no change.
 
 ```ts
 const auth = createBrowserAuth({
-  issuer: 'https://auth.wtfalch.dev',
+  issuer: 'https://auth.example.com',
   clientId: '…',
   open: (url) => Browser.open({ url }),   // Capacitor's system-browser opener
   store: capacitorSecureStore,            // see "Storage stays synchronous" below
@@ -122,9 +165,11 @@ const auth = createBrowserAuth({
 - **`store`** replaces the `sessionStorage` wrapper that holds the token,
   verifier, return path and silent-tried mark, with a plain
   `{ get, set, drop }` shape — `get` synchronous, `set`/`drop` allowed to
-  return a promise (see "Storage: `get` stays synchronous" below). Two
-  `createBrowserAuth` instances given different stores never see each other's
-  values — one app's session cannot leak into another's held in the same tab.
+  return a promise (see "Storage: `get` stays synchronous" below). Custom
+  stores retain the existing `wtfalch.auth.*` keys. Supply separate
+  backing storage per client context; different wrappers around the same
+  backing keys share values. Reuse the same store object for instances that
+  should coordinate pending operations.
 - **`refresh()`**, a new method on the returned client, posts the
   `refresh_token` grant and stores the session it gets back — awaiting the
   store's write before it resolves, so an app that awaits `refresh()` knows
@@ -147,7 +192,36 @@ const auth = createBrowserAuth({
   sign-in, so this only matters there.
 - **`forget()`** is now `Promise<void>` rather than `void`, the one signature
   change here: it awaits the store's writes, the same as `completeSignIn()`
-  and `refresh()`.
+  and `refresh()`. It also cancels pending authorization, completion and
+  refresh operations in the same store/context before cleanup starts.
+
+**Default storage and clients on one origin.** Legacy browser clients now use
+versioned `sessionStorage` keys bound to issuer, client ID, origin, callback URI
+and the requested scope set (including extra scopes). Matching contexts share
+sessions, pending proof/return path and the silent-attempt mark; different
+contexts keep each of those separate. Scope order and repeated scopes do not
+create a new context. Old unbound `wtfalch.auth.*` default values are ignored,
+with no automatic migration: users sign in once after upgrading. Custom stores
+keep their established keys and need separate backing storage per context.
+
+Instances using the same default context or the same custom store object share
+write coordination and refresh requests within this loaded SDK. `forget()`
+invalidates pending generations immediately, removes the token and pending
+proof/return path, and sets the silent-attempt mark. Network responses are
+checked before committing. If an async store write has already started,
+`forget()` waits for it and then removes its result; await `forget()` before
+reading the final state. A cancelled completion returns `kind: 'error'`; a
+cancelled refresh returns `kind: 'refused'` without deleting a newer session.
+A deliberate new sign-in replaces the previous pending generation. Custom
+stores must resolve their write promises only after the writes have landed;
+a stalled store can also stall cleanup. This is local cancellation; issuer
+requests already sent may still complete upstream.
+
+Namespace clients keep their existing coordination: per-context session keys,
+a shared service marker and pending transaction state across tabs. A late
+response must still own that pending state. Forgetting a stale namespace
+context preserves a different active context. Namespace mode continues to
+reject custom stores and retain no refresh token.
 
 **Storage: `get` stays synchronous; `set` and `drop` may be async.**
 `currentSession()` and `silentSignInAvailable()` are synchronous methods on
@@ -250,3 +324,24 @@ against a real issuer.
 ## Licence
 
 Private to the wtfalch estate.
+
+## Checking HTTPS transaction removal
+
+From the repository root, build the SDK and run the isolated browser fixture:
+
+```sh
+pnpm --filter @wtfalch/auth build
+pnpm --filter @wtfalch/auth test:cookie-browser
+```
+
+This needs OpenSSL and an installed Chromium browser. The fixture uses Google
+Chrome on macOS when available, otherwise Playwright's installed Chromium.
+Set `AUTH_COOKIE_BROWSER_EXECUTABLE` to use another Chromium executable. It
+creates a temporary self-signed certificate, listens only on loopback and
+maps a test hostname to that server in the test browser. Certificate errors
+are ignored only in the isolated browser context. Pages can contact only the
+fixture origin; no issuer or deployed account is used. The adapter and Next
+cookie serializer are real, while authentication results use dummy fixtures.
+Legacy, namespace and ordinary-cookie cases check transaction removal and
+session preservation. The browser, server and temporary certificate files
+are cleaned up after the run. This browser check is separate from `pnpm check`.

package/dist/auth.d.ts

@@ -63,6 +63,18 @@ export type Prompt = 'select_account' | 'login';
 export type SignInError = 'invalid_credentials' | 'too_many' | 'request' | 'unavailable';
 export type ResetError = 'invalid_code' | 'invalid_password' | 'unavailable';
 export type SignUpError = 'registration_closed' | 'email_taken' | 'username_taken' | 'username_invalid' | 'invalid' | 'request' | 'unavailable';
+/**
+ * The credential was right, but it is a one-time password: the person holds
+ * no session and no token, and nothing else is let through, until
+ * `setNewPassword` (or `setNewPasswordHeadless`) is called with `changeToken`.
+ * The token proves the issuer just verified that password. It is single use,
+ * bound to this app and good for a few minutes.
+ */
+export interface PasswordChangeRequired {
+    ok: false;
+    error: 'password_change_required';
+    changeToken: string;
+}
 export type SignInResult = {
     ok: true;
     redirectTo: string;
@@ -70,7 +82,7 @@ export type SignInResult = {
 } | {
     ok: false;
     error: SignInError;
-};
+} | PasswordChangeRequired;
 export type SignUpResult = {
     ok: true;
     redirectTo: string;
@@ -79,6 +91,18 @@ export type SignUpResult = {
     ok: false;
     error: SignUpError;
     message: string;
+} | (PasswordChangeRequired & {
+    message: string;
+});
+/** `invalid_token`: unknown, spent, expired or another app's. `invalid_password`: the issuer refused the new one; the token still works for a few more tries. */
+export type SetNewPasswordError = 'invalid_token' | 'invalid_password' | 'unavailable';
+export type SetNewPasswordResult = {
+    ok: true;
+    redirectTo: string;
+    hosted?: true;
+} | {
+    ok: false;
+    error: SetNewPasswordError;
 };
 export type EmailChangeError = 'invalid' | 'email_taken' | 'too_many' | 'unavailable';
 export type EmailChangeResult = {
@@ -207,7 +231,9 @@ export interface Auth {
         sessionId: string;
         code: string;
         next?: string;
-    }, requestHeaders?: Headers): Promise<SignedIn>;
+    }, requestHeaders?: Headers): Promise<SignedIn | (PasswordChangeRequired & {
+        message: string;
+    })>;
     /**
      * `signIn` as data, for a caller with no browser to carry through the OIDC
      * redirect -- a CLI, a desktop app, or a server signing in on a person's
@@ -222,7 +248,9 @@ export interface Auth {
         email: string;
         password: string;
         next?: string;
-    }, requestHeaders?: Headers): Promise<SignedIn<SignInError>>;
+    }, requestHeaders?: Headers): Promise<SignedIn<SignInError> | (PasswordChangeRequired & {
+        message: string;
+    })>;
     /** Emails a fresh verification link. Says nothing about whether the address exists. */
     resendVerification(email: string, next?: string): Promise<void>;
     /** Emails a password-reset link to {basePath}/reset?userId=&code=. Says nothing about whether the address exists. */
@@ -250,6 +278,7 @@ export interface Auth {
     }): Promise<{
         userId: string;
         invited: boolean;
+        personalEmailStored: boolean;
     }>;
     handle(request: Request): Promise<Response>;
     /**
@@ -303,6 +332,17 @@ export interface Auth {
         userId: string;
         state: string;
     }>;
+    /**
+     * An admin's reset for somebody in this app's own organisation whom
+     * `requestPasswordReset` cannot otherwise get back in -- returns a fresh
+     * one-time password the caller is trusted to deliver some other way,
+     * rather than mailing it. Refused for a user outside this app's
+     * organisation.
+     */
+    adminResetPassword(userId: string): Promise<{
+        userId: string;
+        password: string;
+    }>;
     /**
      * Namespace mode: end every session this person has in this service, on
      * every replica, at their next request. Deactivating someone does this too.
@@ -330,6 +370,23 @@ export interface Auth {
         email: string;
         password: string;
     }): Promise<SignInResult>;
+    /**
+     * After `signIn` answered `password_change_required`: sets the person's own
+     * password from that state, with no old password, then signs them in
+     * exactly as `signIn` does. Only a `changeToken` from a sign-in this app
+     * just saw succeed works.
+     */
+    setNewPassword(input: {
+        authRequestId: string;
+        changeToken: string;
+        newPassword: string;
+    }): Promise<SetNewPasswordResult>;
+    /** `setNewPassword` for a caller with no browser, as `signInWithPassword` is to `signIn`. */
+    setNewPasswordHeadless(input: {
+        changeToken: string;
+        newPassword: string;
+        next?: string;
+    }, requestHeaders?: Headers): Promise<SignedIn<SetNewPasswordError>>;
     signUp(input: {
         authRequestId: string;
     } & NewUser): Promise<SignUpResult>;
@@ -440,4 +497,14 @@ export interface Auth {
     accessToken(cookieValue: string): Promise<AccessTokenResult>;
 }
 export declare function createAuth(input: AuthOptions): Auth;
+/**
+ * The freshness bound `startEmailChange`, `completeEmailChange`,
+ * `changePassword`, `startPasskeyRegistration`, `finishPasskeyRegistration`
+ * and `deletePasskey` enforce internally (`currentFreshUser`) -- the same
+ * five minutes docs/adopting.md's Step-up section demonstrates for
+ * `requireFreshUser`. Exported so a page gating one of these calls with its
+ * own `requireFreshUser` can pass the identical bound rather than a second
+ * number that might drift from this one.
+ */
+export declare const STEP_UP_MAX_AGE: MaxAge;
 export type { AuthRequest, NewUser, SetCookie };

package/dist/auth.js

@@ -2,7 +2,7 @@ import { errors } from 'jose';
 import * as client from 'openid-client';
 import { Broker, BrokerError } from './broker.js';
 import { resolveOptions, } from './config.js';
-import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openRecord, openSession, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealTransaction, sessionCookieName, transactionCookieName, } from './cookies.js';
+import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openRecord, openSession, openSilent, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealSilent, sealTransaction, sessionCookieName, silentCookieName, transactionCookieName, } from './cookies.js';
 import { namespaceSessions } from './namespace-session.js';
 import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, scopeFor } from './oidc.js';
 import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
@@ -122,12 +122,19 @@ export function createAuth(input) {
             return unavailable();
         const params = new URL(request.url).searchParams;
         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
+        // (register, a prompt, max_age) is interactive by definition.
+        const silent = (await openSilent(options(), cookieFrom(request.headers.get('cookie'), silentCookieName(options())))) === 'try' &&
+            !params.has('intent') &&
+            !params.has('prompt') &&
+            !params.has('max_age');
         const state = client.randomState();
         const nonce = client.randomNonce();
         const codeVerifier = client.randomPKCECodeVerifier();
         const target = await oidc().authorizationUrl(state, nonce, codeVerifier, {
             create: params.get('intent') === 'register',
-            prompt: promptFrom(params.get('prompt')),
+            prompt: silent ? 'none' : promptFrom(params.get('prompt')),
             maxAge: maxAgeFrom(params.get('max_age')),
         });
         const transaction = await sealTransaction(options(), {
@@ -135,8 +142,13 @@ export function createAuth(input) {
             nc: nonce,
             cv: codeVerifier,
             nx: next,
+            ...(silent ? { sl: true } : {}),
         });
-        return redirect(target.href, [transaction]);
+        // Whatever a silent pass returns, it is the gate's last: `done` sends the next sign-in to the interactive path.
+        return redirect(target.href, [
+            transaction,
+            ...(silent ? [await sealSilent(options(), 'done')] : []),
+        ]);
     };
     const complete = async (callbackUrl, cookieHeader, requestHeaders) => {
         if (!validCallback(callbackUrl))
@@ -147,9 +159,18 @@ export function createAuth(input) {
             return failure('expired', options().namespace ? [] : [cleared]);
         const params = new URL(callbackUrl).searchParams;
         if (params.get('state') !== transaction.st)
-            return failure('state', options().namespace ? [] : [cleared]);
+            return failure('state', options().namespace ? [] : [cleared], transaction.nx);
         if (options().namespace && !(await sessions.bindingActive()))
-            return failure('unavailable', [cleared]);
+            return failure('unavailable', [cleared], transaction.nx);
+        // A silent pass the issuer refused (login_required, interaction_required,
+        // consent_required, or any other error) is not a failure: sign in the normal
+        // way, once. `done` is already set, so `/start` will not go silent again.
+        if (transaction.sl && params.has('error')) {
+            return {
+                location: startUrl(transaction.nx),
+                cookies: [...(options().namespace ? [] : [cleared]), await sealSilent(options(), 'done')],
+            };
+        }
         let session;
         try {
             const tokens = await oidc().exchange(params, {
@@ -160,7 +181,7 @@ export function createAuth(input) {
             session = await sessionCookie(tokens, requestHeaders);
         }
         catch (error) {
-            return failure(reasonOf(error), [cleared]);
+            return failure(reasonOf(error), [cleared], transaction.nx);
         }
         await replacePreviousSession(cookieHeader);
         return {
@@ -221,13 +242,15 @@ export function createAuth(input) {
      */
     const endIssuerSession = async (idToken, cookies) => {
         const afterLogout = new URL(options().afterLogout, options().appUrl).href;
+        // A signed-out person is never silently signed back in: `done` keeps the gate interactive for the marker's life, even if the issuer's own logout fails.
+        const all = [...cookies, await sealSilent(options(), 'done')];
         if (!idToken) {
-            return redirect(new URL('/logout', options().issuer).href, cookies, 303);
+            return redirect(new URL('/logout', options().issuer).href, all, 303);
         }
         const target = await oidc()
             .endSessionUrl(idToken, afterLogout)
             .catch(() => null);
-        return redirect(target?.href ?? afterLogout, cookies, 303);
+        return redirect(target?.href ?? afterLogout, all, 303);
     };
     const logout = async (request) => {
         if (!isSameOrigin(request, options().appUrl.origin)) {
@@ -370,7 +393,15 @@ export function createAuth(input) {
             return { kind: 'deny', cookies, reason: 'unavailable' };
         if (!isNavigation(request))
             return { kind: 'deny', cookies };
-        return { kind: 'redirect', location: startUrl(`${url.pathname}${url.search}`), cookies };
+        // First visit without a session: ask for one silent pass. The marker is
+        // sealed, so only the gate can set it, and any marker (even a spent one)
+        // keeps the next redirect interactive.
+        const tried = await openSilent(options(), cookieFrom(request.headers.get('cookie'), silentCookieName(options())));
+        return {
+            kind: 'redirect',
+            location: startUrl(`${url.pathname}${url.search}`),
+            cookies: tried ? cookies : [...cookies, await sealSilent(options(), 'try')],
+        };
     };
     /**
      * The person signed in on `request`, for the passkey routes -- never a
@@ -388,6 +419,29 @@ export function createAuth(input) {
             throw new AuthError('unauthenticated', 'sign in to use a passkey');
         return user;
     };
+    /**
+     * `currentUser`, plus the same freshness bound `requireFreshUser` enforces
+     * at the page level -- `STEP_UP_MAX_AGE` old at most. The six calls below
+     * that change a credential or an enrolled factor take this instead of
+     * `currentUser`, because a leaked-but-still-live session is enough to
+     * reach any of them directly (a Server Action, or any other route that
+     * never rendered a page gated by `requireFreshUser`) -- only the app's own
+     * page code stood between that session and the change, and nothing here
+     * required it to.
+     *
+     * `requireFreshUser`'s redirect-then-retry only makes sense with a browser
+     * navigation behind it, which a direct call has none of, so a stale
+     * session here is `AuthError('stale', ...)` outright rather than a
+     * redirect: the app shows something to click, exactly as it must already
+     * do for `unauthenticated`.
+     */
+    const currentFreshUser = async (request) => {
+        const user = await currentUser(request);
+        if (!fresh(user, STEP_UP_MAX_AGE)) {
+            throw new AuthError('stale', 'Confirm your identity again before this change');
+        }
+        return user;
+    };
     const people = (options) => broker().people(options);
     const setPersonActive = async (userId, active) => {
         const result = await broker().setPersonActive(userId, active);
@@ -485,6 +539,20 @@ export function createAuth(input) {
         emit({ type: 'invite', email: input.email, userId: result.userId, invited: result.invited });
         return result;
     };
+    /**
+     * An admin's reset for somebody in this app's own organisation whom
+     * `requestPasswordReset` cannot otherwise get back in -- nobody at the
+     * mailbox a personal address or the login address itself would reach.
+     * Refused for a user outside this app's organisation, exactly as
+     * `setPersonActive` is. The password is a one-time one: the person must
+     * choose their own at next sign-in, same as an invite's. Audited with the
+     * target's id and never the password itself.
+     */
+    const adminResetPassword = async (userId) => {
+        const result = await broker().adminResetPassword(userId);
+        emit({ type: 'adminResetPassword', userId: result.userId });
+        return result;
+    };
     const resetPassword = async ({ userId, code, password, next, }, requestHeaders) => {
         try {
             const flow = await serverFlow();
@@ -508,6 +576,9 @@ export function createAuth(input) {
             return { ok: true, ...completed };
         }
         catch (error) {
+            const change = changeRequired(error);
+            if (change)
+                return { ...change, message: 'choose a new password to continue' };
             if (error instanceof BrokerError && error.status < 500) {
                 return { ok: false, error: 'invalid_code', message: error.detail ?? error.error };
             }
@@ -525,7 +596,12 @@ export function createAuth(input) {
             code,
             next: params.get('next') ?? undefined,
         }, request.headers);
-        return result.ok ? redirect(result.location, result.cookies) : failed('link', []);
+        if (result.ok)
+            return redirect(result.location, result.cookies);
+        // A redirect cannot carry the token (it would sit in a URL), so the
+        // person is sent to the error page to sign in with their password, which
+        // answers with the token as data.
+        return failed(result.error === 'password_change_required' ? result.error : 'link', []);
     };
     const signIn = async ({ authRequestId, email, password, }) => {
         try {
@@ -538,9 +614,40 @@ export function createAuth(input) {
                 emit({ type: 'signIn', email });
                 return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
             }
+            const change = changeRequired(error);
+            if (change)
+                return change;
             return { ok: false, error: signInError(error) };
         }
     };
+    const setNewPassword = async ({ authRequestId, changeToken, newPassword, }) => {
+        try {
+            const redirectTo = await broker().setNewPassword({ authRequestId, changeToken, newPassword });
+            return { ok: true, redirectTo };
+        }
+        catch (error) {
+            if (needsHostedLogin(error))
+                return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
+            return { ok: false, error: setNewPasswordError(error) };
+        }
+    };
+    const setNewPasswordHeadless = async ({ changeToken, newPassword, next }, requestHeaders) => {
+        try {
+            const flow = await serverFlow();
+            const completed = await finishOrHandoff(() => broker().setNewPassword({ authRequestId: flow.id, changeToken, newPassword }), flow, safeNextPath(next, options().afterLogin), requestHeaders);
+            return { ok: true, ...completed };
+        }
+        catch (error) {
+            const code = setNewPasswordError(error);
+            return {
+                ok: false,
+                error: code,
+                message: code !== 'unavailable' && error instanceof BrokerError
+                    ? (error.detail ?? error.error)
+                    : 'the sign-in service did not answer',
+            };
+        }
+    };
     const signInWithPassword = async ({ email, password, next }, requestHeaders) => {
         try {
             const flow = await serverFlow();
@@ -549,6 +656,9 @@ export function createAuth(input) {
             return { ok: true, ...completed };
         }
         catch (error) {
+            const change = changeRequired(error);
+            if (change)
+                return { ...change, message: 'choose a new password to continue' };
             const code = signInError(error);
             // `signInError` collapses everything the broker can say into one of
             // four codes; only a real `BrokerError` carries a sentence worth
@@ -571,6 +681,9 @@ export function createAuth(input) {
                 emit({ type: 'signUp', email: user.email });
                 return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
             }
+            const change = changeRequired(error);
+            if (change)
+                return { ...change, message: 'choose a new password to continue' };
             if (error instanceof BrokerError && error.error === 'email_taken') {
                 return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
             }
@@ -594,11 +707,11 @@ export function createAuth(input) {
         }
     };
     const startPasskeyRegistration = async (request) => {
-        const user = await currentUser(request);
+        const user = await currentFreshUser(request);
         return broker().startPasskeyRegistration(user.id);
     };
     const finishPasskeyRegistration = async (request, input) => {
-        const user = await currentUser(request);
+        const user = await currentFreshUser(request);
         // Built from named fields, never spread: `input` crosses a trust
         // boundary (a Next.js Server Action does not enforce its TS parameter
         // types on the wire), and a spread after `userId: user.id` would let a
@@ -626,11 +739,11 @@ export function createAuth(input) {
         }
     };
     const startEmailChange = async (request, email) => {
-        const user = await currentUser(request);
+        const user = await currentFreshUser(request);
         await broker().startEmailChange(user.id, email);
     };
     const completeEmailChange = async (request, code) => {
-        const user = await currentUser(request);
+        const user = await currentFreshUser(request);
         try {
             await broker().completeEmailChange(user.id, code);
             return { ok: true };
@@ -649,7 +762,7 @@ export function createAuth(input) {
         }
     };
     const changePassword = async (request, input) => {
-        const user = await currentUser(request);
+        const user = await currentFreshUser(request);
         try {
             await broker().changePassword({ userId: user.id, ...input });
             return { ok: true };
@@ -670,7 +783,7 @@ export function createAuth(input) {
         return result.passkeys;
     };
     const deletePasskey = async (request, id) => {
-        const user = await currentUser(request);
+        const user = await currentFreshUser(request);
         try {
             await broker().deletePasskey(user.id, id);
             return { ok: true };
@@ -700,7 +813,7 @@ export function createAuth(input) {
         catch (error) {
             if (needsHostedLogin(error))
                 return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
-            return { ok: false, error: signInError(error) };
+            return changeRequired(error) ?? { ok: false, error: signInError(error) };
         }
     };
     const startQrSignIn = async () => {
@@ -792,9 +905,13 @@ export function createAuth(input) {
             cookies,
         };
     };
-    const failure = (reason, cookies) => {
+    /** `next`, when it is a safe same-origin path, rides on the error URL so the error page can offer a retry to it. */
+    const failure = (reason, cookies, next) => {
         const url = new URL(options().onError, options().appUrl);
         url.searchParams.set('auth_error', reason);
+        const retry = safeNextPath(next, '');
+        if (retry)
+            url.searchParams.set('next', retry);
         return { location: url.href, cookies };
     };
     /** `failure`'s location on its own, for a caller that redirects rather than answering. */
@@ -828,11 +945,14 @@ export function createAuth(input) {
         errorUrl,
         people,
         setPersonActive,
+        adminResetPassword,
         revokeSessions,
         sessions: listSessions,
         endSession,
         authRequest,
         signIn,
+        setNewPassword,
+        setNewPasswordHeadless,
         signInWithPassword,
         signUp,
         startPasskeyRegistration,
@@ -908,6 +1028,16 @@ const MAX_AGE_CEILING = 31_536_000;
  * forever. The tolerance is why the round trip can ever satisfy the bound.
  */
 const CLOCK_TOLERANCE = 60;
+/**
+ * The freshness bound `startEmailChange`, `completeEmailChange`,
+ * `changePassword`, `startPasskeyRegistration`, `finishPasskeyRegistration`
+ * and `deletePasskey` enforce internally (`currentFreshUser`) -- the same
+ * five minutes docs/adopting.md's Step-up section demonstrates for
+ * `requireFreshUser`. Exported so a page gating one of these calls with its
+ * own `requireFreshUser` can pass the identical bound rather than a second
+ * number that might drift from this one.
+ */
+export const STEP_UP_MAX_AGE = 300;
 function maxAgeFrom(raw) {
     if (raw === null || raw.trim() === '')
         return undefined;
@@ -975,6 +1105,23 @@ async function quietly(act) {
         throw error;
     }
 }
+/** The broker's refusal for a verified one-time password, with the proof of that to send back. */
+function changeRequired(error) {
+    return error instanceof BrokerError &&
+        error.error === 'password_change_required' &&
+        error.changeToken
+        ? { ok: false, error: 'password_change_required', changeToken: error.changeToken }
+        : null;
+}
+function setNewPasswordError(error) {
+    if (error instanceof BrokerError && error.error === 'invalid_token')
+        return 'invalid_token';
+    if (error instanceof BrokerError && error.error === 'invalid_password')
+        return 'invalid_password';
+    if (error instanceof BrokerError && error.status === 401)
+        return 'invalid_token';
+    return 'unavailable';
+}
 function signInError(error) {
     if (error instanceof BrokerError && error.error === 'request')
         return 'request';