@wtfalch/auth 0.9.1 → 0.11.0

package/dist/config.js

@@ -55,6 +55,7 @@ export function resolveOptions(options) {
         brokerUrl: (options.brokerUrl ?? `${(options.issuer ?? ISSUER).replace(/\/$/, '')}/api`).replace(/\/$/, ''),
         sessionMaxAge: seconds(options.sessionMaxAge, 'sessionMaxAge', 30 * 24 * 60 * 60),
         refreshWindow: seconds(options.refreshWindow, 'refreshWindow', 5 * 60),
+        freshness: seconds(options.freshness, 'freshness', 5 * 60),
         secure: appUrl.protocol === 'https:',
         fetch: options.fetch ?? globalThis.fetch,
     };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type QrPollResult, type QrPollStatus, type QrSignInStart, type ReadResult, type ResetError, type SignInError, type SignInResult, type SignUpError, type SignUpResult, type SignedIn, type User, createAuth, } from './auth.js';
+export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type MaxAge, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, type QrPollResult, type QrPollStatus, type QrSignInStart, type ReadResult, type ResetError, type SignInError, type SignInResult, type SignUpError, type SignUpResult, type SignedIn, type User, createAuth, } from './auth.js';
 export { type AuthOptions, ISSUER } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';

package/dist/namespace-session.d.ts

@@ -3,6 +3,7 @@ import { type Broker } from './broker.js';
 import type { ResolvedOptions } from './config.js';
 import { type SetCookie } from './cookies.js';
 import { type Oidc, type Tokens } from './oidc.js';
+import type { SessionRecord } from './sessions.js';
 /** How long a binding status answer is trusted. The propagation bound for a suspension. */
 export declare const STATUS_FRESH_MS = 60000;
 /** How long the last good answer carries on while the service cannot be asked. */
@@ -34,9 +35,11 @@ export declare function namespaceSessions(deps: {
     broker: () => Broker;
 }): {
     bindingActive: () => Promise<boolean>;
-    create: (tokens: Tokens) => Promise<SetCookie>;
+    create: (tokens: Tokens, requestHeaders?: Headers) => Promise<SetCookie>;
     end: (value: string | undefined) => Promise<"ended" | "changed" | "none">;
     read: (value: string | undefined, force?: boolean) => Promise<SessionRead>;
     revokeSubject: (subject: string) => Promise<number>;
+    listSessions: (subject: string) => Promise<SessionRecord[]>;
+    endSession: (key: string, subject: string) => Promise<boolean>;
     keyOf: (value: string | undefined) => Promise<string | null>;
 };

package/dist/namespace-session.js

@@ -1,7 +1,7 @@
 import * as client from 'openid-client';
 import { BrokerError } from './broker.js';
 import { contextDigest, digest, openHandle, openRecord, sealHandle, sealRecord, } from './cookies.js';
-import { AuthError } from './oidc.js';
+import { AuthError, isOAuthRefusal } from './oidc.js';
 /** How long a binding status answer is trusted. The propagation bound for a suspension. */
 export const STATUS_FRESH_MS = 60_000;
 /** How long the last good answer carries on while the service cannot be asked. */
@@ -127,10 +127,15 @@ export function namespaceSessions(deps) {
                 .revoke(refreshToken)
                 .catch(() => { });
     };
-    /** A new record and the cookie that points at it. */
-    const create = async (tokens) => {
+    /**
+     * A new record and the cookie that points at it. `requestHeaders` is
+     * whatever the request that signed the person in carried; omitted where
+     * none exists (there is no browser request behind a server-initiated flow).
+     */
+    const create = async (tokens, requestHeaders) => {
         const sid = client.randomState();
         const key = await digest(sid);
+        const at = now();
         await store().create({
             key,
             context: await contextDigest(options()),
@@ -138,8 +143,12 @@ export function namespaceSessions(deps) {
             generation: 0,
             leaseUntil: null,
             payload: await seal(key, tokens),
-            expiresAt: now() + options().sessionMaxAge,
+            expiresAt: at + options().sessionMaxAge,
             revokedAt: null,
+            createdAt: at,
+            lastSeenAt: at,
+            userAgent: requestHeaders?.get('user-agent') ?? null,
+            ip: ipFrom(requestHeaders),
         });
         return sealHandle(options(), sid);
     };
@@ -156,9 +165,32 @@ export function namespaceSessions(deps) {
         return 'ended';
     };
     const revokeSubject = async (subject) => store().revokeSubject(await contextDigest(options()), subject, now());
+    /** A subject's live sessions under this binding, newest first: the devices page. */
+    const listSessions = async (subject) => store().listSubject(await contextDigest(options()), subject);
+    /**
+     * Ends one of a subject's sessions. Resolves whether it did: false for a
+     * key that is unknown, already over, somebody else's, or another binding's
+     * -- the same answer either way, so a guess at another person's key cannot
+     * be told apart from a stranger's.
+     */
+    const endSession = async (key, subject) => {
+        const record = await store().get(key);
+        if (!record ||
+            record.subject !== subject ||
+            record.context !== (await contextDigest(options())))
+            return false;
+        await store().revoke(key, now());
+        return true;
+    };
     // ---- refresh ------------------------------------------------------------
-    const definitive = (error) => error instanceof AuthError ||
-        (error instanceof client.ResponseBodyError && error.error === 'invalid_grant');
+    /**
+     * Under the lease nobody else can have spent the token, so any 4xx the
+     * issuer answers with is the grant itself gone -- the account disabled, the
+     * refresh token revoked -- never a rival request. This issuer does not
+     * reserve `invalid_grant` for that: a deactivated user and a dead refresh
+     * token both come back `invalid_request`, so only the status class counts.
+     */
+    const definitive = (error) => error instanceof AuthError || isOAuthRefusal(error);
     /**
      * Refresh under the lease. Resolves the freshest usable tokens: new ones,
      * another request's, or null when the session is over. While another
@@ -250,8 +282,10 @@ export function namespaceSessions(deps) {
         if (!loaded)
             return { kind: 'none' };
         const exp = expiryOf(loaded.tokens.idt);
+        const iat = issuedAtOf(loaded.tokens.idt);
         const valid = exp !== null && exp > now() - 60;
-        const due = force || exp === null || exp - options().refreshWindow <= now();
+        const stale = iat !== null && now() - iat >= options().freshness;
+        const due = force || exp === null || exp - options().refreshWindow <= now() || stale;
         if (due && loaded.tokens.rt) {
             loaded = await refresh(loaded, valid);
             if (!loaded)
@@ -264,7 +298,31 @@ export function namespaceSessions(deps) {
             return { kind: 'none' };
         }
     };
-    return { bindingActive, create, end, read, revokeSubject, keyOf };
+    return { bindingActive, create, end, read, revokeSubject, listSessions, endSession, keyOf };
+}
+/**
+ * These apps sit behind a proxy, so the client never reaches this process
+ * directly. `x-real-ip` first: a proxy that sets it overwrites rather than
+ * appends, so it cannot be a client-supplied value riding along underneath
+ * the real one. Otherwise the rightmost `x-forwarded-for` hop -- the one the
+ * nearest proxy itself observed and prepended, not the leftmost one, which
+ * is exactly the entry a client sends and controls, so trusting it would
+ * let anyone write whatever address they like into this record. There is no
+ * trusted-proxy config -- this value is only ever as trustworthy as
+ * whatever sits in front of the app.
+ */
+function ipFrom(headers) {
+    const realIp = headers?.get('x-real-ip');
+    if (realIp)
+        return realIp;
+    const forwarded = headers?.get('x-forwarded-for');
+    if (!forwarded)
+        return null;
+    const hops = forwarded
+        .split(',')
+        .map((hop) => hop.trim())
+        .filter(Boolean);
+    return hops.length > 0 ? hops[hops.length - 1] : null;
 }
 function expiryOf(idToken) {
     try {
@@ -276,3 +334,15 @@ 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;
+    }
+}

package/dist/next.d.ts

@@ -1,6 +1,7 @@
 import { type NextRequest, NextResponse } from 'next/server';
-import { type Auth, type AuthRequest, type GateRules, type Intent, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type QrPollStatus, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
+import { type Auth, type AuthRequest, type ChangePasswordResult, type DeletePasskeyResult, type EmailChangeResult, type GateRules, type Intent, type MaxAge, type NewUser, type Passkey, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, type QrPollStatus, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
 import type { AuthOptions } from './config.js';
+import type { SessionRecord } from './sessions.js';
 type SearchParams = Record<string, string | string[] | undefined>;
 export interface QrSignIn {
     url: string;
@@ -21,6 +22,25 @@ export interface NextAuth {
     getUser: () => Promise<User | null>;
     /** The user, or a redirect to sign in with `next` to come back to. */
     requireUser: (next?: string) => Promise<User>;
+    /**
+     * The user, but only if they authenticated within `maxAge` seconds;
+     * otherwise a redirect that makes the issuer ask them again. Put it in front
+     * of an action somebody holding a borrowed laptop must not be able to take:
+     * changing the password, changing the email, removing a passkey.
+     *
+     * Somebody whose id token carries no `auth_time` is sent back too. The
+     * issuer only has to send that claim when the request asked for it, so its
+     * absence proves nothing, and the first round trip fixes it for good.
+     *
+     * **Pass the page's `searchParams`.** They carry the mark that says this
+     * person has already been sent once; without them a person the issuer will
+     * not re-authenticate is sent round the same loop for ever. See the
+     * implementation for why that is not hypothetical here.
+     */
+    requireFreshUser: (maxAge: MaxAge, opts?: {
+        next?: string;
+        searchParams?: SearchParams | Promise<SearchParams>;
+    }) => Promise<User>;
     /**
      * For the app's login and register pages: the auth request the issuer sent
      * the browser with, or a redirect that starts one. Pass the page's searchParams.
@@ -28,6 +48,7 @@ export interface NextAuth {
     authRequest: (searchParams: SearchParams | Promise<SearchParams>, opts?: {
         next?: string;
         intent?: Intent;
+        prompt?: Prompt;
     }) => Promise<AuthRequest>;
     /** For a server action: redirects into the app on success, returns the error otherwise. */
     signIn: (input: {
@@ -63,6 +84,13 @@ export interface NextAuth {
     people: Auth['people'];
     /** Deactivate or reactivate somebody in this app's organisation. */
     setPersonActive: Auth['setPersonActive'];
+    /** The devices page: the signed-in person's own live sessions, newest first. Namespace mode only. */
+    sessions: () => Promise<SessionRecord[]>;
+    /**
+     * Ends one of the signed-in person's own sessions. Throws `AuthError('request', ...)`
+     * for a key that is somebody else's, another binding's, or does not exist.
+     */
+    endSession: (key: string) => Promise<void>;
     /** Sets the password from a reset link, signs the person in, and redirects. */
     resetPassword: (input: {
         userId: string;
@@ -85,6 +113,19 @@ export interface NextAuth {
         credential: unknown;
         name: string;
     }) => Promise<PasskeyRegistrationResult>;
+    /** See `Auth['startEmailChange']`: mails a code to the new address and leaves the old one working until `completeEmailChange` checks it. */
+    startEmailChange: (email: string) => Promise<void>;
+    /** The other half of `startEmailChange`. */
+    completeEmailChange: (code: string) => Promise<EmailChangeResult>;
+    /** Changes the signed-in person's password. See `Auth['changePassword']` for how a wrong current password is told apart from a rejected new one. */
+    changePassword: (input: {
+        currentPassword: string;
+        newPassword: string;
+    }) => Promise<ChangePasswordResult>;
+    /** See `Auth['passkeys']`: enough to warn when this is the only one left. */
+    passkeys: () => Promise<Passkey[]>;
+    /** Removes one of this person's own passkeys. */
+    deletePasskey: (id: string) => Promise<DeletePasskeyResult>;
     /** The passkey half of `signIn`: a challenge to answer with `@wtfalch/auth/passkey`'s `getPasskey`. */
     startPasskeySignIn: (input: {
         authRequestId: string;
@@ -116,4 +157,4 @@ export interface NextAuth {
     }>;
 }
 export declare function nextAuth(options: AuthOptions): NextAuth;
-export type { Auth, AuthOptions, AuthRequest, GateRules, Intent, NewUser, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, QrPollStatus, User, };
+export type { Auth, AuthOptions, AuthRequest, ChangePasswordResult, DeletePasskeyResult, EmailChangeResult, GateRules, Intent, MaxAge, NewUser, Passkey, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, Prompt, QrPollStatus, SessionRecord, User, };

package/dist/next.js

@@ -1,10 +1,16 @@
-import { cookies } from 'next/headers';
+import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
 import { NextResponse } from 'next/server';
 import { createAuth, } from './auth.js';
 import { BrokerError } from './broker.js';
 import { withCookies } from './cookies.js';
 import { AuthError } from './oidc.js';
+/** On the page a step-up returns to: this person has been sent once already. */
+const STEP_UP_PARAM = 'auth_stepup';
+function marked(next) {
+    const path = next ?? '/';
+    return `${path}${path.includes('?') ? '&' : '?'}${STEP_UP_PARAM}=1`;
+}
 /**
  * Which of the two failures it was, in the vocabulary `auth_error` already
  * uses. A refusal under 500 is about this request — the broker says unknown,
@@ -63,6 +69,30 @@ export function nextAuth(options) {
             redirect(auth.startUrl(next));
         return user;
     };
+    /**
+     * One redirect, never two. The second one is the loop.
+     *
+     * The gate has exactly the shape `authRequest` warns about below, and the
+     * same price: send somebody to the issuer because they are stale, and if
+     * they come back no fresher, the next render sends them again. Nothing
+     * errors and nothing is logged. An issuer that declines to honour `max_age`,
+     * or one that omits `auth_time` from the token it mints afterwards, turns
+     * the gate into that loop for every person who reaches it.
+     *
+     * So the redirect marks the return address, and a person who arrives already
+     * marked gets an `AuthError` instead of another redirect. The app shows them
+     * something and they click. A human click cannot loop.
+     */
+    const requireFreshUser = async (maxAge, opts = {}) => {
+        const user = await requireUser(opts.next);
+        if (auth.fresh(user, maxAge))
+            return user;
+        const params = opts.searchParams ? await opts.searchParams : undefined;
+        if (params?.[STEP_UP_PARAM] !== undefined) {
+            throw new AuthError('stale', 'Could not confirm a recent sign-in');
+        }
+        redirect(auth.startUrl(marked(opts.next), 'login', undefined, maxAge));
+    };
     /**
      * The auth request the issuer sent the browser here with.
      *
@@ -93,7 +123,7 @@ export function nextAuth(options) {
         // Nobody has started a flow yet. This cannot loop: the issuer always
         // sends the browser back carrying an id.
         if (!id)
-            redirect(auth.startUrl(opts.next, opts.intent));
+            redirect(auth.startUrl(opts.next, opts.intent, opts.prompt));
         try {
             return await auth.authRequest(id);
         }
@@ -105,11 +135,8 @@ export function nextAuth(options) {
     // A server action cannot redirect into a route handler, so the callback runs here and the cookies are set on the action's response.
     const finish = async (callbackUrl) => {
         const store = await cookies();
-        const header = store
-            .getAll()
-            .map((c) => `${c.name}=${c.value}`)
-            .join('; ');
-        const { location, cookies: set } = await auth.complete(callbackUrl, header);
+        const request = await requestFromCookies();
+        const { location, cookies: set } = await auth.complete(callbackUrl, request.headers.get('cookie'), request.headers);
         for (const c of set) {
             if (c.value)
                 store.set(c.name, c.value, c.attributes);
@@ -119,20 +146,37 @@ export function nextAuth(options) {
         const url = new URL(location);
         redirect(`${url.pathname}${url.search}`);
     };
-    // The passkey routes take a `Request`; a server action has none of its
-    // own, only what `cookies()` already exposes for this request. Only the
-    // cookie header matters to `read`, so a synthetic request carrying just
-    // that is exactly as good as the real one.
+    // The passkey and session routes take a `Request`; a server action has
+    // none of its own, only what `cookies()`/`headers()` already expose for
+    // this invocation. `cookies()` (not the incoming `cookie` header) is the
+    // source of truth for the jar, since it reflects whatever this action has
+    // already set or cleared; the device headers `namespaceSessions` reads on
+    // sign-in come along too, so a session created from a server action still
+    // gets a real user agent and address.
     const requestFromCookies = async () => {
         const store = await cookies();
-        const header = store
+        const cookieHeader = store
             .getAll()
             .map((c) => `${c.name}=${c.value}`)
             .join('; ');
-        return new Request('http://localhost/', header ? { headers: { cookie: header } } : undefined);
+        const requestHeaders = new Headers();
+        if (cookieHeader)
+            requestHeaders.set('cookie', cookieHeader);
+        const incoming = await headers();
+        for (const name of ['user-agent', 'x-forwarded-for', 'x-real-ip']) {
+            const value = incoming.get(name);
+            if (value)
+                requestHeaders.set(name, value);
+        }
+        return new Request('http://localhost/', { headers: requestHeaders });
     };
     const startPasskeyRegistration = async () => auth.startPasskeyRegistration(await requestFromCookies());
     const finishPasskeyRegistration = async (input) => auth.finishPasskeyRegistration(await requestFromCookies(), input);
+    const startEmailChange = async (email) => auth.startEmailChange(await requestFromCookies(), email);
+    const completeEmailChange = async (code) => auth.completeEmailChange(await requestFromCookies(), code);
+    const changePassword = async (input) => auth.changePassword(await requestFromCookies(), input);
+    const passkeys = async () => auth.passkeys(await requestFromCookies());
+    const deletePasskey = async (id) => auth.deletePasskey(await requestFromCookies(), id);
     const finishPasskeySignIn = async (input) => {
         const result = await auth.finishPasskeySignIn(input);
         if (result.ok) {
@@ -143,7 +187,7 @@ export function nextAuth(options) {
         return { error: result.error };
     };
     const resetPassword = async (input) => {
-        const result = await auth.resetPassword(input);
+        const result = await auth.resetPassword(input, (await requestFromCookies()).headers);
         if (!result.ok)
             return { error: result.error, message: result.message };
         const store = await cookies();
@@ -198,12 +242,15 @@ export function nextAuth(options) {
         }
         return reason ? { status, reason } : { status };
     };
+    const sessionsList = async () => auth.sessions(await requestFromCookies());
+    const endSession = async (key) => auth.endSession(await requestFromCookies(), key);
     return {
         auth,
         handlers: { GET: auth.handle, POST: auth.handle },
         proxy,
         getUser,
         requireUser,
+        requireFreshUser,
         authRequest,
         signIn,
         signUp,
@@ -213,9 +260,16 @@ export function nextAuth(options) {
         invite: auth.invite,
         people: auth.people,
         setPersonActive: auth.setPersonActive,
+        sessions: sessionsList,
+        endSession,
         resetPassword,
         startPasskeyRegistration,
         finishPasskeyRegistration,
+        startEmailChange,
+        completeEmailChange,
+        changePassword,
+        passkeys,
+        deletePasskey,
         startPasskeySignIn: auth.startPasskeySignIn,
         finishPasskeySignIn,
         startQrSignIn,

package/dist/oidc.d.ts

@@ -1,6 +1,14 @@
 import * as jose from 'jose';
 import type { ResolvedOptions } from './config.js';
 export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
+/**
+ * How long a rotated refresh token still answers with the tokens it rotated
+ * to. A request that started just before another one finished the same
+ * rotation would otherwise present the now-dead token and be refused as if
+ * the grant were revoked; this is the single-process fix. A second server,
+ * or a request more than a minute behind, still gets the real refusal.
+ */
+export declare const ROTATION_CACHE_MS = 60000;
 /** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
 export declare function scopeFor(organizationId: string): string;
 export interface Tokens {
@@ -13,12 +21,15 @@ export declare class Oidc {
     private configuration;
     private jwks;
     private refreshing;
+    private rotated;
     constructor(options: ResolvedOptions);
     private config;
     private keys;
     get redirectUri(): URL;
-    authorizationUrl(state: string, nonce: string, codeVerifier: string, { create }?: {
+    authorizationUrl(state: string, nonce: string, codeVerifier: string, { create, prompt, maxAge, }?: {
         create?: boolean;
+        prompt?: 'select_account' | 'login';
+        maxAge?: number;
     }): Promise<URL>;
     exchange(callbackParams: URLSearchParams, transaction: {
         state: string;
@@ -26,14 +37,35 @@ export declare class Oidc {
         codeVerifier: string;
     }): Promise<Tokens>;
     refresh(refreshToken: string): Promise<Tokens>;
+    /**
+     * The issuer's RP-Initiated Logout URL, or null when discovery publishes no
+     * `end_session_endpoint` -- an issuer is free not to support it, and a
+     * sign-out has to succeed either way.
+     */
+    endSessionUrl(idToken: string, postLogoutRedirectUri: string): Promise<URL | null>;
     private tokensFrom;
     verify(idToken: string): Promise<jose.JWTPayload>;
     private assertOrganization;
 }
 export type AuthErrorReason = 'expired' | 'state' | 'denied' | 'exchange' | 'organization' | 'cookie' | 'request' | 'account_changed' | 'unavailable'
 /** No session at all -- distinct from `account_changed`/`unavailable`, which `requireUser` already covers by redirecting instead. */
- | 'unauthenticated';
+ | 'unauthenticated'
+/** Came back from a step-up no fresher than it went. Never redirect on this: that is the loop. */
+ | 'stale';
 export declare class AuthError extends Error {
     readonly reason: AuthErrorReason;
     constructor(reason: AuthErrorReason, message: string);
 }
+/**
+ * A refusal from the token endpoint itself -- the grant is gone, the account
+ * is disabled -- as opposed to the issuer being unreachable, rate-limiting,
+ * or having a bad day. Keyed on the HTTP status alone, never the body: a
+ * WAF or CDN in front of the issuer can answer a genuine refusal as HTML,
+ * which oauth4webapi cannot parse as an OAuth error, but it still hands back
+ * the response that carried the status. Trusting only a parsed `error` field
+ * would treat that case as an outage and let the old bug back in through a
+ * path nobody would look at. 429 is excluded on purpose: "come back later"
+ * is never a statement that the grant is dead, and this issuer's own rate
+ * limiting must not permanently revoke a session.
+ */
+export declare function isOAuthRefusal(error: unknown): boolean;

package/dist/oidc.js

@@ -1,6 +1,14 @@
 import * as jose from 'jose';
 import * as client from 'openid-client';
 export const ORG_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
+/**
+ * How long a rotated refresh token still answers with the tokens it rotated
+ * to. A request that started just before another one finished the same
+ * rotation would otherwise present the now-dead token and be refused as if
+ * the grant were revoked; this is the single-process fix. A second server,
+ * or a request more than a minute behind, still gets the real refusal.
+ */
+export const ROTATION_CACHE_MS = 60_000;
 /** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
 export function scopeFor(organizationId) {
     return [
@@ -17,6 +25,7 @@ export class Oidc {
     configuration = null;
     jwks = null;
     refreshing = new Map();
+    rotated = new Map();
     constructor(options) {
         this.options = options;
     }
@@ -53,9 +62,10 @@ export class Oidc {
     get redirectUri() {
         return new URL(`${this.options.basePath}/callback`, this.options.appUrl);
     }
-    async authorizationUrl(state, nonce, codeVerifier, { create = false } = {}) {
+    async authorizationUrl(state, nonce, codeVerifier, { create = false, prompt, maxAge, } = {}) {
         return client.buildAuthorizationUrl(await this.config(), {
-            ...(create ? { prompt: 'create' } : {}),
+            ...(create ? { prompt: 'create' } : prompt ? { prompt } : {}),
+            ...(maxAge === undefined ? {} : { max_age: String(maxAge) }),
             redirect_uri: this.redirectUri.href,
             scope: scopeFor(this.options.organizationId),
             state,
@@ -78,16 +88,41 @@ export class Oidc {
     }
     // Parallel requests holding the same refresh token share one grant; the issuer rotates it, so a second grant would fail.
     refresh(refreshToken) {
+        const asked = Date.now();
+        for (const [token, entry] of this.rotated)
+            if (entry.until <= asked)
+                this.rotated.delete(token);
+        const cached = this.rotated.get(refreshToken);
+        if (cached)
+            return Promise.resolve(cached.tokens);
         let pending = this.refreshing.get(refreshToken);
         if (!pending) {
             pending = this.config()
                 .then((config) => client.refreshTokenGrant(config, refreshToken))
                 .then((response) => this.tokensFrom(response, refreshToken))
+                .then((tokens) => {
+                this.rotated.set(refreshToken, { tokens, until: Date.now() + ROTATION_CACHE_MS });
+                return tokens;
+            })
                 .finally(() => this.refreshing.delete(refreshToken));
             this.refreshing.set(refreshToken, pending);
         }
         return pending;
     }
+    /**
+     * The issuer's RP-Initiated Logout URL, or null when discovery publishes no
+     * `end_session_endpoint` -- an issuer is free not to support it, and a
+     * sign-out has to succeed either way.
+     */
+    async endSessionUrl(idToken, postLogoutRedirectUri) {
+        const config = await this.config();
+        if (!config.serverMetadata().end_session_endpoint)
+            return null;
+        return client.buildEndSessionUrl(config, {
+            id_token_hint: idToken,
+            post_logout_redirect_uri: postLogoutRedirectUri,
+        });
+    }
     tokensFrom(response, previousRefreshToken) {
         const claims = response.claims();
         if (!response.id_token || !claims) {
@@ -130,3 +165,25 @@ export class AuthError extends Error {
         this.name = 'AuthError';
     }
 }
+/**
+ * A refusal from the token endpoint itself -- the grant is gone, the account
+ * is disabled -- as opposed to the issuer being unreachable, rate-limiting,
+ * or having a bad day. Keyed on the HTTP status alone, never the body: a
+ * WAF or CDN in front of the issuer can answer a genuine refusal as HTML,
+ * which oauth4webapi cannot parse as an OAuth error, but it still hands back
+ * the response that carried the status. Trusting only a parsed `error` field
+ * would treat that case as an outage and let the old bug back in through a
+ * path nobody would look at. 429 is excluded on purpose: "come back later"
+ * is never a statement that the grant is dead, and this issuer's own rate
+ * limiting must not permanently revoke a session.
+ */
+export function isOAuthRefusal(error) {
+    const status = statusOf(error);
+    return status !== undefined && status >= 400 && status < 500 && status !== 429;
+}
+function statusOf(error) {
+    if (error instanceof client.ResponseBodyError)
+        return error.status;
+    const cause = error instanceof Error ? error.cause : undefined;
+    return cause instanceof Response ? cause.status : undefined;
+}

package/dist/sessions.d.ts

@@ -32,19 +32,33 @@ export interface SessionRecord {
     expiresAt: number;
     /** Unix seconds, or null while the session is live. */
     revokedAt: number | null;
+    /**
+     * Unix seconds the record was made, or null for a row written before this
+     * column existed. Nullable so an old row keeps working unmigrated.
+     */
+    createdAt: number | null;
+    /** Unix seconds, bumped whenever `advance` succeeds. Null for the same reason as `createdAt`. */
+    lastSeenAt: number | null;
+    /** The signing-in request's `User-Agent`, or null if it sent none or the row predates this column. */
+    userAgent: string | null;
+    /** The signing-in request's address as the proxy in front reported it, or null. See `ipFrom` in namespace-session.ts for how much to trust it. */
+    ip: string | null;
 }
 export type SessionUpdate = Pick<SessionRecord, 'payload' | 'expiresAt' | 'leaseUntil'>;
 export interface SessionStore {
     create(record: SessionRecord): Promise<void>;
     get(key: string): Promise<SessionRecord | null>;
     /**
-     * Replace the payload, expiry and lease, and bump the generation, only if the
-     * record is still at `generation` and not revoked. Resolves whether it did.
+     * Replace the payload, expiry and lease, bump the generation and touch
+     * `lastSeenAt`, only if the record is still at `generation` and not
+     * revoked. Resolves whether it did.
      */
     advance(key: string, generation: number, next: SessionUpdate): Promise<boolean>;
     revoke(key: string, at: number): Promise<void>;
     /** Revoke every live record for this subject under this binding context. Resolves how many. */
     revokeSubject(context: string, subject: string, at: number): Promise<number>;
+    /** Live (not revoked, not expired) records for this subject under this binding context, newest first: the devices page. */
+    listSubject(context: string, subject: string): Promise<SessionRecord[]>;
 }
 /**
  * One process only. For tests and a single-instance development server: two
@@ -52,7 +66,13 @@ export interface SessionStore {
  */
 export declare function createMemorySessionStore(): SessionStore;
 /** The table `createPostgresSessionStore` expects. Run it in the app's own migrations. */
-export declare const POSTGRES_SESSION_TABLE = "create table if not exists wtfalch_auth_sessions (\n  key text primary key,\n  context text not null,\n  subject text not null,\n  generation integer not null,\n  payload text not null,\n  expires_at bigint not null,\n  lease_until bigint,\n  revoked_at bigint\n);\ncreate index if not exists wtfalch_auth_sessions_subject on wtfalch_auth_sessions (context, subject);\ncreate index if not exists wtfalch_auth_sessions_expiry on wtfalch_auth_sessions (expires_at);";
+export declare const POSTGRES_SESSION_TABLE = "create table if not exists wtfalch_auth_sessions (\n  key text primary key,\n  context text not null,\n  subject text not null,\n  generation integer not null,\n  payload text not null,\n  expires_at bigint not null,\n  lease_until bigint,\n  revoked_at bigint,\n  created_at bigint,\n  last_seen_at bigint,\n  user_agent text,\n  ip text\n);\ncreate index if not exists wtfalch_auth_sessions_subject on wtfalch_auth_sessions (context, subject);\ncreate index if not exists wtfalch_auth_sessions_expiry on wtfalch_auth_sessions (expires_at);";
+/**
+ * `POSTGRES_SESSION_TABLE` already has these columns for a fresh table. A
+ * consumer whose table predates them runs this once, in its own migrations,
+ * to catch up; `add column if not exists` makes it safe to run again.
+ */
+export declare const POSTGRES_SESSION_MIGRATION_1 = "alter table wtfalch_auth_sessions add column if not exists created_at bigint;\nalter table wtfalch_auth_sessions add column if not exists last_seen_at bigint;\nalter table wtfalch_auth_sessions add column if not exists user_agent text;\nalter table wtfalch_auth_sessions add column if not exists ip text;";
 type Row = Record<string, unknown>;
 /**
  * Postgres through whatever driver the app already has. `query` runs one