@wtfalch/auth 0.9.1 → 0.11.0

package/dist/auth.d.ts

@@ -2,6 +2,7 @@ import { type JWTPayload } from 'jose';
 import { type AuthRequest, type NewUser, type PeoplePage } from './broker.js';
 import { type AuthOptions } from './config.js';
 import { type SetCookie } from './cookies.js';
+import type { SessionRecord } from './sessions.js';
 export interface User {
     /** Present only for validated namespace sessions. Membership is app-owned. */
     namespaceId?: string;
@@ -14,6 +15,16 @@ export interface User {
     familyName: string | null;
     preferredUsername: string | null;
     organizationId: string;
+    /**
+     * When the person last proved who they were to the issuer, in seconds since
+     * the epoch, from the id token's `auth_time`. Null when the issuer did not
+     * send it, which OIDC allows unless the request carried `max_age` -- so a
+     * null is not evidence of freshness and `fresh()` treats it as stale.
+     *
+     * A refresh does not move it. It is when they authenticated, not when the
+     * token was minted.
+     */
+    authTime: number | null;
     claims: JWTPayload;
 }
 export interface ReadResult {
@@ -45,6 +56,10 @@ export type Gate = {
     reason?: 'account_changed' | 'unavailable';
 };
 export type Intent = 'login' | 'register';
+/** Seconds. `0` makes the issuer re-authenticate whatever it did a moment ago. */
+export type MaxAge = number;
+/** Allowlisted so a caller cannot smuggle an arbitrary OIDC prompt value through. */
+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';
@@ -65,6 +80,33 @@ export type SignUpResult = {
     error: SignUpError;
     message: string;
 };
+export type EmailChangeError = 'invalid' | 'email_taken' | 'too_many' | 'unavailable';
+export type EmailChangeResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: EmailChangeError;
+};
+export type ChangePasswordError = 'invalid_current_password' | 'invalid_password' | 'unavailable';
+export type ChangePasswordResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: ChangePasswordError;
+};
+export type DeletePasskeyResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: 'invalid';
+};
+/** One passkey as the issuer reports it -- `ready` or still mid-registration. */
+export interface Passkey {
+    readonly id: string;
+    readonly name: string;
+    /** `ready`, `not_ready` for a registration nobody finished, or `unknown` for a state a newer issuer added. Only `ready` signs anyone in. */
+    readonly state: string;
+}
 export interface PasskeyRegistrationStart {
     passkeyId: string;
     /** ZITADEL's `publicKeyCredentialCreationOptions`, opaque here -- `@wtfalch/auth/passkey`'s `createPasskey` knows its shape. */
@@ -127,8 +169,13 @@ export interface Auth {
     start(request: Request): Promise<Response>;
     /** GET {basePath}/callback */
     callback(request: Request): Promise<Response>;
-    /** The callback as data, for a server action that finishes the sign-in itself and sets the cookies. */
-    complete(callbackUrl: string, cookieHeader: string | null): Promise<Completed>;
+    /**
+     * The callback as data, for a server action that finishes the sign-in
+     * itself and sets the cookies. `requestHeaders`, when given, is the
+     * signing-in request's own headers -- namespace mode keeps its user agent
+     * and address on the new session record.
+     */
+    complete(callbackUrl: string, cookieHeader: string | null, requestHeaders?: Headers): Promise<Completed>;
     /** POST {basePath}/logout */
     logout(request: Request): Promise<Response>;
     /** GET {basePath}/verify?userId=&code= */
@@ -154,7 +201,7 @@ export interface Auth {
         sessionId: string;
         code: string;
         next?: string;
-    }): Promise<SignedIn>;
+    }, requestHeaders?: Headers): Promise<SignedIn>;
     /** 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. */
@@ -165,7 +212,7 @@ export interface Auth {
         code: string;
         password: string;
         next?: string;
-    }): Promise<SignedIn>;
+    }, requestHeaders?: Headers): Promise<SignedIn>;
     /** Emails a sign-in link. Needs a verified address. Says nothing about whether the address exists. */
     sendLink(email: string, next?: string): Promise<void>;
     /**
@@ -195,7 +242,19 @@ export interface Auth {
         refresh?: boolean;
     }): Promise<ReadResult>;
     gate(request: Request, rules?: GateRules): Promise<Gate>;
-    startUrl(next?: string | null, intent?: Intent): string;
+    /**
+     * `prompt` is allowlisted server-side too -- an unrecognised value is dropped, not forwarded.
+     * `maxAge` becomes OIDC `max_age`: the issuer re-authenticates anybody whose
+     * last authentication is older than that many seconds.
+     */
+    startUrl(next?: string | null, intent?: Intent, prompt?: Prompt, maxAge?: MaxAge): string;
+    /**
+     * Whether `user` authenticated within `maxAge` seconds. A user with no
+     * `authTime` is never fresh: the issuer only has to send the claim when the
+     * request asked for it, so its absence says nothing, and the safe reading of
+     * nothing is "send them back".
+     */
+    fresh(user: User | null, maxAge: MaxAge): boolean;
     /**
      * Where to send somebody when a sign-in step failed for a reason they
      * cannot fix by retrying it automatically: `onError` with `?auth_error=`,
@@ -230,6 +289,19 @@ export interface Auth {
      * straight back in.
      */
     revokeSessions(userId: string): Promise<number>;
+    /**
+     * The devices page: every live session belonging to whoever is signed in
+     * on `request`, newest first. Namespace mode only. Throws `AuthError`
+     * exactly as `startPasskeyRegistration` does for nobody signed in.
+     */
+    sessions(request: Request): Promise<SessionRecord[]>;
+    /**
+     * Ends one of the signed-in person's own sessions. A key for somebody
+     * else, another binding, or nothing at all is refused the same way --
+     * `AuthError('request', ...)` -- so a guess cannot tell an id that exists
+     * from one that does not.
+     */
+    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>;
     signIn(input: {
@@ -253,6 +325,39 @@ export interface Auth {
         credential: unknown;
         name: string;
     }): Promise<PasskeyRegistrationResult>;
+    /**
+     * Starts changing the address of whoever is signed in on `request` to
+     * `email`. A code is mailed to that NEW address, never to the old one --
+     * it is what proves they hold it -- and only `completeEmailChange` moves
+     * the live address once that code checks out. Until then the person's
+     * current address is untouched and keeps working, so a code that is lost
+     * or never used costs nothing. Same signed-in requirement as
+     * `startPasskeyRegistration`.
+     */
+    startEmailChange(request: Request, email: string): Promise<void>;
+    /** The other half of `startEmailChange`; moves the live address once `code` checks out. */
+    completeEmailChange(request: Request, code: string): Promise<EmailChangeResult>;
+    /**
+     * Changes the password of whoever is signed in on `request`. The issuer
+     * checks `currentPassword` itself, so this never opens a session just to
+     * find out -- a wrong one comes back as its own error, distinct from a
+     * `newPassword` the issuer's own policy rejects.
+     */
+    changePassword(request: Request, input: {
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<ChangePasswordResult>;
+    /**
+     * Every passkey this person has, `ready` or not. A person with no
+     * password who deletes their only `ready` passkey can lock themselves
+     * out of their own account -- the broker does not guard this and neither
+     * does the issuer, deliberately: whether that is a problem for this app
+     * is its call to make, not the SDK's. This returns enough to make that
+     * call -- an app can warn when the list holds exactly one `ready` entry.
+     */
+    passkeys(request: Request): Promise<Passkey[]>;
+    /** Removes one of this person's own passkeys. See `passkeys` for the lockout this does not guard against. */
+    deletePasskey(request: Request, id: string): Promise<DeletePasskeyResult>;
     /** The passkey half of `signIn`: a challenge to answer with `@wtfalch/auth/passkey`'s `getPasskey`. */
     startPasskeySignIn(input: {
         authRequestId: string;

package/dist/auth.js

@@ -2,9 +2,9 @@ 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, openSession, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealTransaction, sessionCookieName, transactionCookieName, } from './cookies.js';
+import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openRecord, openSession, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealTransaction, sessionCookieName, transactionCookieName, } from './cookies.js';
 import { namespaceSessions } from './namespace-session.js';
-import { AuthError, ORG_CLAIM, Oidc, scopeFor } from './oidc.js';
+import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, scopeFor } from './oidc.js';
 import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
 import { safeNextPath } from './redirect.js';
 export function createAuth(input) {
@@ -57,8 +57,8 @@ export function createAuth(input) {
         return brokerInstance;
     };
     const sessions = namespaceSessions({ options, oidc, broker });
-    const sessionCookie = (tokens) => options().namespace
-        ? sessions.create(tokens)
+    const sessionCookie = (tokens, requestHeaders) => options().namespace
+        ? sessions.create(tokens, requestHeaders)
         : sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken });
     /**
      * Signing in again replaces this binding's previous session outright: in
@@ -74,15 +74,27 @@ export function createAuth(input) {
             .catch((error) => console.error('@wtfalch/auth: could not end the replaced session', error));
     };
     const unavailable = () => new Response('Sign-in is unavailable for this workspace', { status: 503 });
-    const startUrl = (next, intent = 'login') => {
+    const startUrl = (next, intent = 'login', prompt, maxAge) => {
         const url = new URL(`${options().basePath}/start`, options().appUrl);
         const path = safeNextPath(next, '');
         if (path)
             url.searchParams.set('next', path);
         if (intent === 'register')
             url.searchParams.set('intent', 'register');
+        if (prompt)
+            url.searchParams.set('prompt', prompt);
+        if (maxAge !== undefined) {
+            assertMaxAge(maxAge);
+            url.searchParams.set('max_age', String(maxAge));
+        }
         return url.href;
     };
+    const fresh = (user, maxAge) => {
+        assertMaxAge(maxAge);
+        if (!user || user.authTime === null)
+            return false;
+        return Date.now() / 1000 - user.authTime <= maxAge + CLOCK_TOLERANCE;
+    };
     const start = async (request) => {
         if (!isNavigation(request))
             return new Response('Unauthorized', { status: 401 });
@@ -95,6 +107,8 @@ export function createAuth(input) {
         const codeVerifier = client.randomPKCECodeVerifier();
         const target = await oidc().authorizationUrl(state, nonce, codeVerifier, {
             create: params.get('intent') === 'register',
+            prompt: promptFrom(params.get('prompt')),
+            maxAge: maxAgeFrom(params.get('max_age')),
         });
         const transaction = await sealTransaction(options(), {
             st: state,
@@ -104,7 +118,7 @@ export function createAuth(input) {
         });
         return redirect(target.href, [transaction]);
     };
-    const complete = async (callbackUrl, cookieHeader) => {
+    const complete = async (callbackUrl, cookieHeader, requestHeaders) => {
         if (!validCallback(callbackUrl))
             return failure('request', []);
         const cleared = clearTransaction(options());
@@ -123,7 +137,7 @@ export function createAuth(input) {
                 nonce: transaction.nc,
                 codeVerifier: transaction.cv,
             });
-            session = await sessionCookie(tokens);
+            session = await sessionCookie(tokens, requestHeaders);
         }
         catch (error) {
             return failure(reasonOf(error), [cleared]);
@@ -140,26 +154,72 @@ export function createAuth(input) {
         // path and query are what it asked for, on the app's own origin.
         const { pathname, search } = new URL(request.url);
         const callbackUrl = new URL(`${pathname}${search}`, options().appUrl).href;
-        const { location, cookies } = await complete(callbackUrl, request.headers.get('cookie'));
+        const { location, cookies } = await complete(callbackUrl, request.headers.get('cookie'), request.headers);
         return redirect(location, cookies);
     };
+    /**
+     * The record's own id token, read before `sessions.end` revokes it. Namespace
+     * sessions never hand the raw token back to a caller -- `sessions.read`
+     * answers with claims, not the token itself -- so logout, the one place that
+     * needs it for `id_token_hint`, opens the record the same way `end` does.
+     */
+    const namespaceIdToken = async (value) => {
+        const store = options().sessionStore;
+        const key = store ? await sessions.keyOf(value) : null;
+        if (!store || !key)
+            return undefined;
+        const record = await store.get(key).catch(() => null);
+        const payload = record && (await openRecord(options(), key, record.payload).catch(() => null));
+        return payload?.idt;
+    };
+    /**
+     * Where a sign-out lands: the issuer's own logout, so its session ends and
+     * the next sign-in asks who again, rather than straight back to
+     * `afterLogout`. What this function can see fail -- no id token to hint
+     * with, no `end_session_endpoint` published, the issuer not answering --
+     * falls back to the plain redirect a sign-out has always ended with.
+     * Losing the issuer's co-operation is never a reason to fail somebody's
+     * sign-out.
+     *
+     * `afterLogout` not being a registered `post_logout_redirect_uri` is a
+     * failure this function cannot see: that request reaches the issuer, which
+     * is free to answer with its own error page instead of a redirect back.
+     * Registering it (docs/adopting.md) is what prevents that, not a check
+     * here -- cookie mode has no registry to check against at runtime, and
+     * namespace mode already refuses to start with a binding whose
+     * `afterLogout` is not registered.
+     */
+    const endIssuerSession = async (idToken, cookies) => {
+        const afterLogout = new URL(options().afterLogout, options().appUrl).href;
+        const target = idToken
+            ? await oidc()
+                .endSessionUrl(idToken, afterLogout)
+                .catch(() => null)
+            : null;
+        return redirect(target?.href ?? afterLogout, cookies, 303);
+    };
     const logout = async (request) => {
         if (!isSameOrigin(request, options().appUrl.origin)) {
             return new Response('Forbidden', { status: 403 });
         }
         const value = cookieFrom(request.headers.get('cookie'), sessionCookieName(options()));
         if (options().namespace) {
+            const idToken = await namespaceIdToken(value);
             // Revoked in the store first: that is what ends copies of the cookie too.
-            if ((await sessions.end(value)) === 'changed')
+            // `sessions.end` reaches the store, which can be briefly unreachable --
+            // and a sign-out that 500s over that leaves the browser's own cookie
+            // standing, which is worse than the record surviving a moment longer.
+            const status = await sessions.end(value).catch(() => 'ended');
+            if (status === 'changed')
                 return new Response('Account changed', { status: 409 });
-            return redirect(new URL(options().afterLogout, options().appUrl).href, [clearSession(options())], 303);
+            return endIssuerSession(idToken, [clearSession(options())]);
         }
         const session = await openSession(options(), value);
         if (session?.rt)
             await broker()
                 .revoke(session.rt)
                 .catch(() => { });
-        return redirect(new URL(options().afterLogout, options().appUrl).href, [clearSession(options())], 303);
+        return endIssuerSession(session?.idt, [clearSession(options())]);
     };
     const verify = async (request) => {
         const params = new URL(request.url).searchParams;
@@ -227,8 +287,10 @@ export function createAuth(input) {
             return { user: null, cookies: [] };
         const now = Math.floor(Date.now() / 1000);
         const exp = expiryOf(session.idt);
+        const iat = issuedAtOf(session.idt);
         const valid = exp !== null && exp > now - 60;
-        const due = exp === null || exp - options().refreshWindow <= now;
+        const stale = iat !== null && now - iat >= options().freshness;
+        const due = exp === null || exp - options().refreshWindow <= now || stale;
         if (due && refresh && session.rt) {
             try {
                 const tokens = await oidc().refresh(session.rt);
@@ -239,9 +301,17 @@ export function createAuth(input) {
                 return { user: boundUser(tokens.claims), cookies: [cookie] };
             }
             catch (error) {
-                // A failed refresh never clears the cookie: a valid token carries on, and a dead one is replaced by the next sign-in.
                 if (error instanceof AuthError)
                     return { user: null, cookies: [clearSession(options())] };
+                // Under the issuer's own rotation nobody else can have spent this
+                // token, so a refusal is final -- the account is disabled or the
+                // grant is gone, and it stays denied on every request from here.
+                // The cookie is left alone though: a losing request in a genuine
+                // race must not blank out whatever cookie the winner's response is
+                // setting for the browser to pick up next.
+                if (isOAuthRefusal(error))
+                    return { user: null, cookies: [] };
+                // A network error or a 5xx: the current token carries on, never past its own expiry.
                 if (!valid)
                     return { user: null, cookies: [] };
             }
@@ -299,6 +369,19 @@ export function createAuth(input) {
             throw new Error('@wtfalch/auth: revokeSessions needs namespace sessions');
         return sessions.revokeSubject(userId);
     };
+    const listSessions = async (request) => {
+        if (!options().namespace)
+            throw new Error('@wtfalch/auth: sessions needs namespace sessions');
+        const user = await currentUser(request);
+        return sessions.listSessions(user.id);
+    };
+    const endSession = async (request, key) => {
+        if (!options().namespace)
+            throw new Error('@wtfalch/auth: endSession needs namespace sessions');
+        const user = await currentUser(request);
+        if (!(await sessions.endSession(key, user.id)))
+            throw new AuthError('request', 'session does not belong to the signed-in person');
+    };
     const authRequest = (id) => broker().authRequest(id);
     /**
      * An OIDC flow this app starts and finishes itself, for a person arriving
@@ -323,7 +406,7 @@ export function createAuth(input) {
         return { id, state, nonce, verifier };
     };
     /** Exchanges a callback the service issued, and seals the cookie. */
-    const finish = async (callbackUrl, flow, next) => {
+    const finish = async (callbackUrl, flow, next, requestHeaders) => {
         if (!validCallback(callbackUrl))
             throw new AuthError('request', 'callback does not match namespace binding');
         const tokens = await oidc().exchange(new URL(callbackUrl).searchParams, {
@@ -331,7 +414,7 @@ export function createAuth(input) {
             nonce: flow.nonce,
             codeVerifier: flow.verifier,
         });
-        const cookie = await sessionCookie(tokens);
+        const cookie = await sessionCookie(tokens, requestHeaders);
         return { location: new URL(next, options().appUrl).href, cookies: [cookie] };
     };
     const hostedUrl = (id) => {
@@ -342,9 +425,9 @@ export function createAuth(input) {
     const needsHostedLogin = (error) => error instanceof BrokerError && error.error === 'hosted_login_required';
     // Email/reset flows started on the server must transfer their PKCE transaction
     // to the browser before handing off to the issuer's full authentication UI.
-    const finishOrHandoff = async (action, flow, next) => {
+    const finishOrHandoff = async (action, flow, next, requestHeaders) => {
         try {
-            return await finish(await action(), flow, next);
+            return await finish(await action(), flow, next, requestHeaders);
         }
         catch (error) {
             if (!needsHostedLogin(error))
@@ -367,10 +450,10 @@ export function createAuth(input) {
     const requestPasswordReset = (email, next) => quietly(() => broker().sendReset(email, safeNextPath(next, '')));
     const sendLink = (email, next) => quietly(() => broker().sendLink(email, safeNextPath(next, '')));
     const invite = (input) => broker().invite({ ...input, next: safeNextPath(input.next, '') });
-    const resetPassword = async ({ userId, code, password, next, }) => {
+    const resetPassword = async ({ userId, code, password, next, }, requestHeaders) => {
         try {
             const flow = await serverFlow();
-            const completed = await finishOrHandoff(() => broker().completeReset({ authRequestId: flow.id, userId, code, password }), flow, safeNextPath(next, options().afterLogin));
+            const completed = await finishOrHandoff(() => broker().completeReset({ authRequestId: flow.id, userId, code, password }), flow, safeNextPath(next, options().afterLogin), requestHeaders);
             return { ok: true, ...completed };
         }
         catch (error) {
@@ -383,10 +466,10 @@ export function createAuth(input) {
             return { ok: false, error: 'unavailable', message: 'the sign-in service did not answer' };
         }
     };
-    const followLink = async ({ sessionId, code, next, }) => {
+    const followLink = async ({ sessionId, code, next }, requestHeaders) => {
         try {
             const flow = await serverFlow();
-            const completed = await finishOrHandoff(() => broker().followLink({ authRequestId: flow.id, sessionId, code }), flow, safeNextPath(next, options().afterLogin));
+            const completed = await finishOrHandoff(() => broker().followLink({ authRequestId: flow.id, sessionId, code }), flow, safeNextPath(next, options().afterLogin), requestHeaders);
             return { ok: true, ...completed };
         }
         catch (error) {
@@ -406,7 +489,7 @@ export function createAuth(input) {
             sessionId,
             code,
             next: params.get('next') ?? undefined,
-        });
+        }, request.headers);
         return result.ok ? redirect(result.location, result.cookies) : failed('link', []);
     };
     const signIn = async ({ authRequestId, email, password, }) => {
@@ -480,6 +563,62 @@ export function createAuth(input) {
             throw error;
         }
     };
+    const startEmailChange = async (request, email) => {
+        const user = await currentUser(request);
+        await broker().startEmailChange(user.id, email);
+    };
+    const completeEmailChange = async (request, code) => {
+        const user = await currentUser(request);
+        try {
+            await broker().completeEmailChange(user.id, code);
+            return { ok: true };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.error === 'email_taken') {
+                return { ok: false, error: 'email_taken' };
+            }
+            if (error instanceof BrokerError && error.error === 'too_many') {
+                return { ok: false, error: 'too_many' };
+            }
+            if (error instanceof BrokerError && error.status < 500) {
+                return { ok: false, error: 'invalid' };
+            }
+            return { ok: false, error: 'unavailable' };
+        }
+    };
+    const changePassword = async (request, input) => {
+        const user = await currentUser(request);
+        try {
+            await broker().changePassword({ userId: user.id, ...input });
+            return { ok: true };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.error === 'invalid_current_password') {
+                return { ok: false, error: 'invalid_current_password' };
+            }
+            if (error instanceof BrokerError && error.status < 500) {
+                return { ok: false, error: 'invalid_password' };
+            }
+            return { ok: false, error: 'unavailable' };
+        }
+    };
+    const passkeys = async (request) => {
+        const user = await currentUser(request);
+        const result = await broker().passkeys(user.id);
+        return result.passkeys;
+    };
+    const deletePasskey = async (request, id) => {
+        const user = await currentUser(request);
+        try {
+            await broker().deletePasskey(user.id, id);
+            return { ok: true };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.status < 500)
+                return { ok: false, error: 'invalid' };
+            throw error;
+        }
+    };
     const startPasskeySignIn = async ({ authRequestId, email, }) => {
         try {
             const { sessionId, options } = await broker().startPasskeySignIn({ authRequestId, email });
@@ -548,7 +687,7 @@ export function createAuth(input) {
             return { status: 'unavailable', cookies: [cleared] };
         let session;
         try {
-            session = await sessionCookie(outcome.tokens);
+            session = await sessionCookie(outcome.tokens, request.headers);
         }
         catch (error) {
             return { status: 'failed', reason: reasonOf(error), cookies: [cleared] };
@@ -588,15 +727,23 @@ export function createAuth(input) {
         readCookie,
         gate,
         startUrl,
+        fresh,
         errorUrl,
         people,
         setPersonActive,
         revokeSessions,
+        sessions: listSessions,
+        endSession,
         authRequest,
         signIn,
         signUp,
         startPasskeyRegistration,
         finishPasskeyRegistration,
+        startEmailChange,
+        completeEmailChange,
+        changePassword,
+        passkeys,
+        deletePasskey,
         startPasskeySignIn,
         finishPasskeySignIn,
         startQrSignIn,
@@ -632,6 +779,55 @@ function expiryOf(idToken) {
         return null;
     }
 }
+// Age, not time left: a disabled or revoked account must not ride out a
+// long-lived token just because it still has plenty of time on the clock.
+function issuedAtOf(idToken) {
+    try {
+        const [, payload] = idToken.split('.');
+        const json = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));
+        return typeof json.iat === 'number' ? json.iat : null;
+    }
+    catch {
+        return null;
+    }
+}
+const PROMPTS = ['select_account', 'login'];
+function promptFrom(raw) {
+    return PROMPTS.includes(raw ?? '') ? raw : undefined;
+}
+// A year. Past that the bound is doing nothing, and an absurd value is a
+// caller getting it wrong rather than a request to honour.
+const MAX_AGE_CEILING = 31_536_000;
+/**
+ * The same sixty seconds `Oidc.verify` allows a token's own claims. `auth_time`
+ * comes off the issuer's clock and is compared against this server's, so a
+ * bound checked to the exact second would flip on skew alone.
+ *
+ * It also makes `maxAge: 0` terminate. Zero asks the issuer to authenticate
+ * the person again; they then spend a second or two coming back, and a check
+ * with no slack would find them already stale and send them round again,
+ * forever. The tolerance is why the round trip can ever satisfy the bound.
+ */
+const CLOCK_TOLERANCE = 60;
+function maxAgeFrom(raw) {
+    if (raw === null || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0 || value > MAX_AGE_CEILING)
+        return undefined;
+    return value;
+}
+/**
+ * A bad `maxAge` from app code is a mistake in the app, and the loud failure is
+ * the cheap one. Left alone it is silent and expensive: `startUrl` would drop
+ * the value, the issuer would be asked for nothing, the person would come back
+ * exactly as stale, and the gate would send them again.
+ */
+function assertMaxAge(value) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_AGE_CEILING) {
+        throw new AuthError('request', `maxAge must be whole seconds from 0 to ${MAX_AGE_CEILING}`);
+    }
+}
 function userFrom(claims) {
     const str = (key) => typeof claims[key] === 'string' ? claims[key] : null;
     return {
@@ -643,6 +839,7 @@ function userFrom(claims) {
         familyName: str('family_name'),
         preferredUsername: str('preferred_username'),
         organizationId: String(claims[ORG_CLAIM]),
+        authTime: typeof claims.auth_time === 'number' ? claims.auth_time : null,
         claims,
     };
 }

package/dist/broker.d.ts

@@ -123,6 +123,22 @@ export declare class Broker {
         revoked?: string[];
     }>;
     verifyEmail(userId: string, code: string): Promise<unknown>;
+    /** Mails a code to `email`, never to the address it would replace -- see `Auth['startEmailChange']`. */
+    startEmailChange(userId: string, email: string): Promise<unknown>;
+    completeEmailChange(userId: string, code: string): Promise<unknown>;
+    changePassword(input: {
+        userId: string;
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<unknown>;
+    passkeys(userId: string): Promise<{
+        passkeys: {
+            id: string;
+            name: string;
+            state: string;
+        }[];
+    }>;
+    deletePasskey(userId: string, passkeyId: string): Promise<unknown>;
     /** A public client revoking its own token: no key, no service. */
     revoke(refreshToken: string): Promise<void>;
 }

package/dist/broker.js

@@ -123,6 +123,22 @@ export class Broker {
     verifyEmail(userId, code) {
         return this.call('POST', '/verify', { userId, code });
     }
+    /** Mails a code to `email`, never to the address it would replace -- see `Auth['startEmailChange']`. */
+    startEmailChange(userId, email) {
+        return this.call('POST', '/email/change/send', { userId, email });
+    }
+    completeEmailChange(userId, code) {
+        return this.call('POST', '/email/change/complete', { userId, code });
+    }
+    changePassword(input) {
+        return this.call('POST', '/password/change', input);
+    }
+    passkeys(userId) {
+        return this.call('GET', '/passkeys', { userId });
+    }
+    deletePasskey(userId, passkeyId) {
+        return this.call('POST', '/passkeys/delete', { userId, passkeyId });
+    }
     /** A public client revoking its own token: no key, no service. */
     async revoke(refreshToken) {
         await this.options.fetch(`${this.options.issuer}/oauth/v2/revoke`, {

package/dist/config.d.ts

@@ -43,6 +43,12 @@ export interface AuthOptions {
     sessionMaxAge?: number;
     /** Refresh when the id token has fewer seconds left than this. Default 300. */
     refreshWindow?: number;
+    /**
+     * Refresh when the id token is older than this, however far it is from
+     * expiry -- the propagation bound for a disabled or revoked account.
+     * Default 300. Both modes.
+     */
+    freshness?: number;
     fetch?: typeof fetch;
 }
 export interface ResolvedOptions {
@@ -74,6 +80,7 @@ export interface ResolvedOptions {
     brokerUrl: string;
     sessionMaxAge: number;
     refreshWindow: number;
+    freshness: number;
     secure: boolean;
     fetch: typeof fetch;
 }