@wtfalch/auth 0.9.0 → 0.10.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;
@@ -45,6 +46,8 @@ export type Gate = {
     reason?: 'account_changed' | 'unavailable';
 };
 export type Intent = 'login' | 'register';
+/** 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 +68,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 +157,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 +189,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 +200,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 +230,8 @@ 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. */
+    startUrl(next?: string | null, intent?: Intent, prompt?: Prompt): string;
     /**
      * 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 +266,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 +302,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,13 +74,15 @@ 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) => {
         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);
         return url.href;
     };
     const start = async (request) => {
@@ -95,6 +97,7 @@ 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')),
         });
         const transaction = await sealTransaction(options(), {
             st: state,
@@ -104,7 +107,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 +126,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]);
@@ -135,26 +138,77 @@ export function createAuth(input) {
         };
     };
     const callback = async (request) => {
-        const { location, cookies } = await complete(request.url, request.headers.get('cookie'));
+        // Behind a proxy the request can arrive as http:// or on an internal host,
+        // and `validCallback` would refuse it. The browser reached this app, so the
+        // 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'), 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;
@@ -222,8 +276,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);
@@ -234,9 +290,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: [] };
             }
@@ -294,6 +358,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
@@ -318,7 +395,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, {
@@ -326,7 +403,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) => {
@@ -337,9 +414,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))
@@ -362,10 +439,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) {
@@ -378,10 +455,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) {
@@ -401,7 +478,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, }) => {
@@ -475,6 +552,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 });
@@ -543,7 +676,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] };
@@ -587,11 +720,18 @@ export function createAuth(input) {
         people,
         setPersonActive,
         revokeSessions,
+        sessions: listSessions,
+        endSession,
         authRequest,
         signIn,
         signUp,
         startPasskeyRegistration,
         finishPasskeyRegistration,
+        startEmailChange,
+        completeEmailChange,
+        changePassword,
+        passkeys,
+        deletePasskey,
         startPasskeySignIn,
         finishPasskeySignIn,
         startQrSignIn,
@@ -627,6 +767,22 @@ 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;
+}
 function userFrom(claims) {
     const str = (key) => typeof claims[key] === 'string' ? claims[key] : null;
     return {

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;
 }

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/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 NewUser, type Passkey, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, 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;
@@ -63,6 +64,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 +93,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 +137,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, NewUser, Passkey, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, QrPollStatus, SessionRecord, User, };

package/dist/next.js

@@ -1,4 +1,4 @@
-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';
@@ -105,11 +105,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 +116,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 +157,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,6 +212,8 @@ 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 },
@@ -213,9 +229,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,14 @@ 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 }?: {
         create?: boolean;
+        prompt?: 'select_account' | 'login';
     }): Promise<URL>;
     exchange(callbackParams: URLSearchParams, transaction: {
         state: string;
@@ -26,6 +36,12 @@ 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;
@@ -37,3 +53,16 @@ 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,9 @@ 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 } = {}) {
         return client.buildAuthorizationUrl(await this.config(), {
-            ...(create ? { prompt: 'create' } : {}),
+            ...(create ? { prompt: 'create' } : prompt ? { prompt } : {}),
             redirect_uri: this.redirectUri.href,
             scope: scopeFor(this.options.organizationId),
             state,
@@ -78,16 +87,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 +164,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

package/dist/sessions.js

@@ -24,7 +24,12 @@ export function createMemorySessionStore() {
             const record = records.get(key);
             if (!record || record.revokedAt !== null || record.generation !== generation)
                 return false;
-            records.set(key, { ...record, ...next, generation: generation + 1 });
+            records.set(key, {
+                ...record,
+                ...next,
+                generation: generation + 1,
+                lastSeenAt: Math.floor(Date.now() / 1000),
+            });
             return true;
         },
         async revoke(key, at) {
@@ -41,6 +46,16 @@ export function createMemorySessionStore() {
                 }
             return count;
         },
+        async listSubject(context, subject) {
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            return [...records.values()]
+                .filter((r) => r.context === context &&
+                r.subject === subject &&
+                r.revokedAt === null &&
+                r.expiresAt > nowSeconds)
+                .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))
+                .map((r) => ({ ...r }));
+        },
     };
 }
 /** The table `createPostgresSessionStore` expects. Run it in the app's own migrations. */
@@ -52,11 +67,25 @@ export const POSTGRES_SESSION_TABLE = `create table if not exists wtfalch_auth_s
   payload text not null,
   expires_at bigint not null,
   lease_until bigint,
-  revoked_at bigint
+  revoked_at bigint,
+  created_at bigint,
+  last_seen_at bigint,
+  user_agent text,
+  ip text
 );
 create index if not exists wtfalch_auth_sessions_subject on wtfalch_auth_sessions (context, subject);
 create 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 const POSTGRES_SESSION_MIGRATION_1 = `alter table wtfalch_auth_sessions add column if not exists created_at bigint;
+alter table wtfalch_auth_sessions add column if not exists last_seen_at bigint;
+alter table wtfalch_auth_sessions add column if not exists user_agent text;
+alter table wtfalch_auth_sessions add column if not exists ip text;`;
 const nullable = (value) => value === null || value === undefined ? null : Number(value);
+const nullableString = (value) => value === null || value === undefined ? null : String(value);
 /**
  * Postgres through whatever driver the app already has. `query` runs one
  * parameterised statement and resolves its rows:
@@ -77,14 +106,19 @@ export function createPostgresSessionStore(input) {
         expiresAt: Number(row.expires_at),
         leaseUntil: nullable(row.lease_until),
         revokedAt: nullable(row.revoked_at),
+        createdAt: nullable(row.created_at),
+        lastSeenAt: nullable(row.last_seen_at),
+        userAgent: nullableString(row.user_agent),
+        ip: nullableString(row.ip),
     });
     return {
         async create(r) {
             await query(`delete from wtfalch_auth_sessions where key in
            (select key from wtfalch_auth_sessions where expires_at <= $1 limit 100)`, [Math.floor(Date.now() / 1000)]);
             await query(`insert into wtfalch_auth_sessions
-           (key, context, subject, generation, payload, expires_at, lease_until, revoked_at)
-         values ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+           (key, context, subject, generation, payload, expires_at, lease_until, revoked_at,
+            created_at, last_seen_at, user_agent, ip)
+         values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)`, [
                 r.key,
                 r.context,
                 r.subject,
@@ -93,6 +127,10 @@ export function createPostgresSessionStore(input) {
                 r.expiresAt,
                 r.leaseUntil,
                 r.revokedAt,
+                r.createdAt,
+                r.lastSeenAt,
+                r.userAgent,
+                r.ip,
             ]);
         },
         async get(key) {
@@ -101,9 +139,17 @@ export function createPostgresSessionStore(input) {
         },
         async advance(key, generation, next) {
             const rows = await query(`update wtfalch_auth_sessions
-            set payload = $3, expires_at = $4, lease_until = $5, generation = generation + 1
+            set payload = $3, expires_at = $4, lease_until = $5, generation = generation + 1,
+                last_seen_at = $6
           where key = $1 and generation = $2 and revoked_at is null
-          returning key`, [key, generation, next.payload, next.expiresAt, next.leaseUntil]);
+          returning key`, [
+                key,
+                generation,
+                next.payload,
+                next.expiresAt,
+                next.leaseUntil,
+                Math.floor(Date.now() / 1000),
+            ]);
             return rows.length === 1;
         },
         async revoke(key, at) {
@@ -115,5 +161,11 @@ export function createPostgresSessionStore(input) {
           returning key`, [context, subject, at]);
             return rows.length;
         },
+        async listSubject(context, subject) {
+            const rows = await query(`select * from wtfalch_auth_sessions
+          where context = $1 and subject = $2 and revoked_at is null and expires_at > $3
+          order by created_at desc nulls last`, [context, subject, Math.floor(Date.now() / 1000)]);
+            return rows.map(record);
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Sign in against auth.wtfalch.dev: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",