@wtfalch/auth 0.10.0 → 0.11.0

package/dist/auth.d.ts

@@ -15,6 +15,16 @@ export interface User {
     familyName: string | null;
     preferredUsername: string | null;
     organizationId: string;
+    /**
+     * When the person last proved who they were to the issuer, in seconds since
+     * the epoch, from the id token's `auth_time`. Null when the issuer did not
+     * send it, which OIDC allows unless the request carried `max_age` -- so a
+     * null is not evidence of freshness and `fresh()` treats it as stale.
+     *
+     * A refresh does not move it. It is when they authenticated, not when the
+     * token was minted.
+     */
+    authTime: number | null;
     claims: JWTPayload;
 }
 export interface ReadResult {
@@ -46,6 +56,8 @@ export type Gate = {
     reason?: 'account_changed' | 'unavailable';
 };
 export type Intent = 'login' | 'register';
+/** Seconds. `0` makes the issuer re-authenticate whatever it did a moment ago. */
+export type MaxAge = number;
 /** Allowlisted so a caller cannot smuggle an arbitrary OIDC prompt value through. */
 export type Prompt = 'select_account' | 'login';
 export type SignInError = 'invalid_credentials' | 'too_many' | 'request' | 'unavailable';
@@ -230,8 +242,19 @@ export interface Auth {
         refresh?: boolean;
     }): Promise<ReadResult>;
     gate(request: Request, rules?: GateRules): Promise<Gate>;
-    /** `prompt` is allowlisted server-side too -- an unrecognised value is dropped, not forwarded. */
-    startUrl(next?: string | null, intent?: Intent, prompt?: Prompt): string;
+    /**
+     * `prompt` is allowlisted server-side too -- an unrecognised value is dropped, not forwarded.
+     * `maxAge` becomes OIDC `max_age`: the issuer re-authenticates anybody whose
+     * last authentication is older than that many seconds.
+     */
+    startUrl(next?: string | null, intent?: Intent, prompt?: Prompt, maxAge?: MaxAge): string;
+    /**
+     * Whether `user` authenticated within `maxAge` seconds. A user with no
+     * `authTime` is never fresh: the issuer only has to send the claim when the
+     * request asked for it, so its absence says nothing, and the safe reading of
+     * nothing is "send them back".
+     */
+    fresh(user: User | null, maxAge: MaxAge): boolean;
     /**
      * Where to send somebody when a sign-in step failed for a reason they
      * cannot fix by retrying it automatically: `onError` with `?auth_error=`,

package/dist/auth.js

@@ -74,7 +74,7 @@ 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', prompt) => {
+    const startUrl = (next, intent = 'login', prompt, maxAge) => {
         const url = new URL(`${options().basePath}/start`, options().appUrl);
         const path = safeNextPath(next, '');
         if (path)
@@ -83,8 +83,18 @@ export function createAuth(input) {
             url.searchParams.set('intent', 'register');
         if (prompt)
             url.searchParams.set('prompt', prompt);
+        if (maxAge !== undefined) {
+            assertMaxAge(maxAge);
+            url.searchParams.set('max_age', String(maxAge));
+        }
         return url.href;
     };
+    const fresh = (user, maxAge) => {
+        assertMaxAge(maxAge);
+        if (!user || user.authTime === null)
+            return false;
+        return Date.now() / 1000 - user.authTime <= maxAge + CLOCK_TOLERANCE;
+    };
     const start = async (request) => {
         if (!isNavigation(request))
             return new Response('Unauthorized', { status: 401 });
@@ -98,6 +108,7 @@ export function createAuth(input) {
         const target = await oidc().authorizationUrl(state, nonce, codeVerifier, {
             create: params.get('intent') === 'register',
             prompt: promptFrom(params.get('prompt')),
+            maxAge: maxAgeFrom(params.get('max_age')),
         });
         const transaction = await sealTransaction(options(), {
             st: state,
@@ -716,6 +727,7 @@ export function createAuth(input) {
         readCookie,
         gate,
         startUrl,
+        fresh,
         errorUrl,
         people,
         setPersonActive,
@@ -783,6 +795,39 @@ const PROMPTS = ['select_account', 'login'];
 function promptFrom(raw) {
     return PROMPTS.includes(raw ?? '') ? raw : undefined;
 }
+// A year. Past that the bound is doing nothing, and an absurd value is a
+// caller getting it wrong rather than a request to honour.
+const MAX_AGE_CEILING = 31_536_000;
+/**
+ * The same sixty seconds `Oidc.verify` allows a token's own claims. `auth_time`
+ * comes off the issuer's clock and is compared against this server's, so a
+ * bound checked to the exact second would flip on skew alone.
+ *
+ * It also makes `maxAge: 0` terminate. Zero asks the issuer to authenticate
+ * the person again; they then spend a second or two coming back, and a check
+ * with no slack would find them already stale and send them round again,
+ * forever. The tolerance is why the round trip can ever satisfy the bound.
+ */
+const CLOCK_TOLERANCE = 60;
+function maxAgeFrom(raw) {
+    if (raw === null || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0 || value > MAX_AGE_CEILING)
+        return undefined;
+    return value;
+}
+/**
+ * A bad `maxAge` from app code is a mistake in the app, and the loud failure is
+ * the cheap one. Left alone it is silent and expensive: `startUrl` would drop
+ * the value, the issuer would be asked for nothing, the person would come back
+ * exactly as stale, and the gate would send them again.
+ */
+function assertMaxAge(value) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_AGE_CEILING) {
+        throw new AuthError('request', `maxAge must be whole seconds from 0 to ${MAX_AGE_CEILING}`);
+    }
+}
 function userFrom(claims) {
     const str = (key) => typeof claims[key] === 'string' ? claims[key] : null;
     return {
@@ -794,6 +839,7 @@ function userFrom(claims) {
         familyName: str('family_name'),
         preferredUsername: str('preferred_username'),
         organizationId: String(claims[ORG_CLAIM]),
+        authTime: typeof claims.auth_time === 'number' ? claims.auth_time : null,
         claims,
     };
 }

package/dist/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/next.d.ts

@@ -1,5 +1,5 @@
 import { type NextRequest, NextResponse } from 'next/server';
-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 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>;
@@ -22,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.
@@ -29,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: {
@@ -137,4 +157,4 @@ export interface NextAuth {
     }>;
 }
 export declare function nextAuth(options: AuthOptions): NextAuth;
-export type { Auth, AuthOptions, AuthRequest, ChangePasswordResult, DeletePasskeyResult, EmailChangeResult, GateRules, Intent, NewUser, Passkey, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, QrPollStatus, SessionRecord, 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

@@ -5,6 +5,12 @@ 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);
         }
@@ -220,6 +250,7 @@ export function nextAuth(options) {
         proxy,
         getUser,
         requireUser,
+        requireFreshUser,
         authRequest,
         signIn,
         signUp,

package/dist/oidc.d.ts

@@ -26,9 +26,10 @@ export declare class Oidc {
     private config;
     private keys;
     get redirectUri(): URL;
-    authorizationUrl(state: string, nonce: string, codeVerifier: string, { create, prompt }?: {
+    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;
@@ -48,7 +49,9 @@ export declare class Oidc {
 }
 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);

package/dist/oidc.js

@@ -62,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, prompt } = {}) {
+    async authorizationUrl(state, nonce, codeVerifier, { create = false, prompt, maxAge, } = {}) {
         return client.buildAuthorizationUrl(await this.config(), {
             ...(create ? { prompt: 'create' } : prompt ? { prompt } : {}),
+            ...(maxAge === undefined ? {} : { max_age: String(maxAge) }),
             redirect_uri: this.redirectUri.href,
             scope: scopeFor(this.options.organizationId),
             state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.10.0",
+  "version": "0.11.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",