@fluixi/oauth2 1.0.0-alpha.1 → 1.0.0-alpha.100

package/dist/server.js

@@ -32,22 +32,176 @@ import { createSessionCookie } from '@fluixi/session/server';
 import { safeReturnTo } from './return-to.js';
 import { applyClientAuth, } from './client-auth.js';
 import { discover } from './discovery.js';
+import { idTokenClaims, logoutTokenVerifier, memoryLogouts } from './backchannel.js';
 import { createPkcePair, createStateValue, expiryFrom, timingSafeEqual } from './pkce.js';
 import { OAuthError } from './types.js';
+import { createDpopKey, exportDpopKey, importDpopKey, nonceFrom, proofFor } from './dpop.js';
+import { defineModule } from '@fluixi/start/app';
+/** Ends the state of a sign-in started again after an answer the browser had no flow for. */
+const RETRY_MARK = '.retry';
+const PROMPTS = new Set(['none', 'login', 'consent', 'select_account']);
+/** What a `prompt=none` request ends with when the provider would have to ask the visitor. */
+const SILENT_REFUSALS = new Set([
+    'login_required',
+    'consent_required',
+    'interaction_required',
+    'account_selection_required',
+]);
 /**
- * The middleware.
- *
- * Handles `<basePath>/login`, `/callback`, `/refresh`, `/me` and `/logout`, and passes
- * anything else along untouched.
+ * The cookie saying the provider was just asked silently and knew nobody. It holds the
+ * `session_state` that answer carried, which the page watches for a later sign-in. It
+ * expires soon on purpose: kept for the browser session, it hid a sign-in made at the
+ * provider while no page was open to notice.
  */
-export function oauthRoutes(config) {
+function checkedCookie(config, sessionState) {
+    const name = `${config.cookieName ?? 'fx_session'}_checked`;
+    const secure = config.secureCookie ?? process.env.NODE_ENV === 'production';
+    const maxAge = Math.max(0, Math.floor(config.silentRecheck ?? 60));
+    const value = sessionState ?? '1';
+    return { name, header: `${name}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax${secure ? '; Secure' : ''}` };
+}
+/** A `session_state` as Session Management builds it, `<hash>.<salt>`; anything else is dropped. */
+function sessionStateFrom(url) {
+    const value = url.searchParams.get('session_state');
+    return value && /^[\w-]{1,128}\.[\w-]{1,64}$/.test(value) ? value : undefined;
+}
+/** A document load, as opposed to a fetch, an asset or a form post. */
+function isPageRequest(request) {
+    if (request.method !== 'GET')
+        return false;
+    const dest = request.headers.get('sec-fetch-dest');
+    if (dest)
+        return dest === 'document';
+    return (request.headers.get('accept') ?? '').includes('text/html');
+}
+function cookieValue(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const [key, ...rest] = part.trim().split('=');
+        if (key === name)
+            return rest.join('=');
+    }
+    return undefined;
+}
+function hasCookie(request, name) {
+    return cookieValue(request, name) !== undefined;
+}
+/** Whether `pathname` is `path` or below it. */
+function under(pathname, path) {
+    return pathname === path || pathname.startsWith(path.endsWith('/') ? path : `${path}/`);
+}
+/** Where `signIn` sends a signed-out visitor's page request, or null to render it as is. */
+function signInRedirect(request, config) {
+    if (!isPageRequest(request))
+        return null;
+    const url = new URL(request.url);
     const base = (config.basePath ?? '/auth').replace(/\/$/, '');
-    const scopes = config.scopes ?? ['openid', 'profile', 'email'];
-    const cookie = createSessionCookie({
-        secret: config.cookieSecret,
-        name: config.cookieName,
-        secure: config.secureCookie,
-    });
+    const guarded = (config.protectedPaths ?? []).some((path) => under(url.pathname, path));
+    const mode = guarded ? 'required' : (config.signIn ?? 'manual');
+    if (mode === 'manual')
+        return null;
+    if ([base, ...(config.publicPaths ?? [])].some((path) => under(url.pathname, path)))
+        return null;
+    // Back from a refused sign-in: show the page and its error, or a required sign-in would
+    // send the visitor straight back to the provider, which refuses again, in a loop.
+    if (url.searchParams.has('auth_error'))
+        return null;
+    if (mode === 'silent' && hasCookie(request, checkedCookie(config).name))
+        return null;
+    const login = new URLSearchParams({ returnTo: url.pathname + url.search });
+    if (mode === 'silent')
+        login.set('prompt', 'none');
+    return new Response(null, { status: 302, headers: { location: `${base}/login?${login}` } });
+}
+/**
+ * Nonces providers asked for, per origin, shared by the routes and `sessionLocals`. A nonce
+ * is the server's to set (RFC 9449 §8, §9), so the latest one it sent is the one to use.
+ */
+const dpopNonces = new Map();
+/** Put a proof for this request on `headers`, with the nonce this origin last asked for. */
+async function prove(headers, key, method, url, accessToken) {
+    headers.dpop = await proofFor(key, { method, url, accessToken, nonce: dpopNonces.get(new URL(url).origin) });
+}
+/** Record a nonce the server sent. True when it refused the request with one not seen before. */
+function learnNonce(url, response) {
+    const offered = nonceFrom(response);
+    if (!offered)
+        return false;
+    const origin = new URL(url).origin;
+    const fresh = offered !== dpopNonces.get(origin);
+    dpopNonces.set(origin, offered);
+    return fresh && !response.ok;
+}
+/**
+ * Sends a request with the session's access token: as a bearer token, or with a DPoP proof
+ * for this method and URL when the token is bound to the session's key. A nonce the server
+ * asks for is learned and the request sent once more, so the body must be one that can be
+ * sent twice (a string, not a stream).
+ */
+async function sendAs(session, input, init = {}) {
+    const url = String(input);
+    const method = (init.method ?? 'GET').toUpperCase();
+    const key = session.dpop && session.tokenType?.toLowerCase() === 'dpop' ? await importDpopKey(session.dpop) : null;
+    const send = async () => {
+        const credentials = {
+            authorization: `${key ? 'DPoP' : 'Bearer'} ${session.accessToken}`,
+        };
+        if (key)
+            await prove(credentials, key, method, url, session.accessToken);
+        const headers = new Headers(init.headers);
+        for (const [name, value] of Object.entries(credentials))
+            headers.set(name, value);
+        return fetch(url, { ...init, method, headers });
+    };
+    let response = await send();
+    if (key && learnNonce(url, response))
+        response = await send();
+    return response;
+}
+const withToken = (url, session) => sendAs(session, url);
+/**
+ * The provider did not process the token request: it answered 429 or 5xx, or the connection
+ * never opened. The same request may be sent again after `retryAfterMs`.
+ */
+class ProviderUnavailable extends OAuthError {
+    retryAfterMs;
+    constructor(retryAfterMs) {
+        super('The authorization server is unavailable.', 'temporarily_unavailable');
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * The request may have been processed, but its answer is unusable: it timed out, the
+ * connection broke after it was sent, or a success came back without an access token. A
+ * refresh token sent this way may already have been rotated.
+ */
+class AnswerLost extends OAuthError {
+    constructor(what) {
+        super(`The token request's answer was lost (${what}).`, 'answer_lost');
+    }
+}
+/** Connection failures that happen before the request is sent. */
+const NOT_SENT = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ENETUNREACH', 'EHOSTUNREACH', 'UND_ERR_CONNECT_TIMEOUT']);
+const RETRY_DEFAULT_MS = 5_000;
+const RETRY_MAX_MS = 300_000;
+/** The pause a 429 or 5xx asks for (`Retry-After`, seconds or a date), within sane bounds. */
+function retryAfter(response) {
+    const header = response.headers.get('retry-after');
+    if (!header)
+        return RETRY_DEFAULT_MS;
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - Date.now();
+    return Number.isFinite(ms) ? Math.min(Math.max(ms, 1_000), RETRY_MAX_MS) : RETRY_DEFAULT_MS;
+}
+/** What a failed `fetch` means for the request: never sent, or possibly processed. */
+function unanswered(error) {
+    const code = error?.cause?.code;
+    if (code && NOT_SENT.has(code))
+        return new ProviderUnavailable(RETRY_DEFAULT_MS);
+    return new AnswerLost(code ?? (error instanceof Error ? error.name : 'no answer'));
+}
+/** Endpoints, client authentication and the token request, for the routes and `sessionLocals`. */
+function tokenClient(config) {
+    const timeoutMs = config.tokenTimeoutMs ?? 10_000;
     let endpoints = config.endpoints ?? null;
     const resolve = async () => {
         if (endpoints)
@@ -58,10 +212,6 @@ export function oauthRoutes(config) {
         endpoints = await discover(config.issuer);
         return endpoints;
     };
-    const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), {
-        status,
-        headers: { 'content-type': 'application/json', ...headers },
-    });
     const clientAuth = {
         clientId: config.clientId,
         // `client_secret_post` by default here, which is what this half has always sent, so
@@ -72,32 +222,198 @@ export function oauthRoutes(config) {
         keyId: config.keyId,
         assertionAlgorithm: config.assertionAlgorithm,
     };
-    async function tokenRequest(body) {
+    async function tokenRequest(body, key = null) {
         const { token } = await resolve();
-        const headers = {
-            'content-type': 'application/x-www-form-urlencoded',
+        // Built afresh for a retry: a `private_key_jwt` assertion carries a `jti`, and sending
+        // the same one twice can be refused as a replay.
+        const attempt = async () => {
+            const headers = {
+                'content-type': 'application/x-www-form-urlencoded',
+            };
+            const form = new URLSearchParams(body);
+            await applyClientAuth(clientAuth, token, headers, form);
+            if (key)
+                await prove(headers, key, 'POST', token);
+            return fetch(token, { method: 'POST', headers, body: form.toString(), signal: AbortSignal.timeout(timeoutMs) });
         };
-        const form = new URLSearchParams(body);
-        await applyClientAuth(clientAuth, token, headers, form);
-        const response = await fetch(token, { method: 'POST', headers, body: form.toString() });
-        const payload = (await response.json().catch(() => ({})));
+        let response;
+        let payload = null;
+        try {
+            response = await attempt();
+            if (key && learnNonce(token, response))
+                response = await attempt();
+            if (response.status === 429 || response.status >= 500)
+                throw new ProviderUnavailable(retryAfter(response));
+            payload = (await response.json().catch(() => null));
+        }
+        catch (error) {
+            throw error instanceof OAuthError ? error : unanswered(error);
+        }
         if (!response.ok) {
-            throw new OAuthError(String(payload.error ?? 'token_request_failed'), String(payload.error ?? 'token_request_failed'));
+            throw new OAuthError(String(payload?.error ?? 'token_request_failed'), String(payload?.error ?? 'token_request_failed'));
+        }
+        // A token endpoint's success always carries one (RFC 6749 5.1). Anything else (a proxy's
+        // page, a truncated body) is not a session, and the provider may have rotated the token.
+        if (typeof payload?.access_token !== 'string' || !payload.access_token) {
+            throw new AnswerLost('a success without an access token');
         }
         return payload;
     }
+    return { resolve, tokenRequest, clientAuth };
+}
+/**
+ * Renewals in flight or just finished, by the refresh token they spent. The provider rotates
+ * refresh tokens and treats a second use of one as theft, revoking the whole family: requests
+ * that arrive together with the same expired cookie (a page and its server functions) must
+ * share one renewal, and one that arrives a moment later with the old cookie still gets its
+ * result. One process only; replicas need the provider to allow a short reuse window.
+ */
+const renewals = new Map();
+const RENEWAL_REUSE_MS = 30_000;
+/** How long a refused or possibly rotated refresh token stays recorded, so it is not sent again. */
+const SPENT_MS = 5 * 60_000;
+/** The session with fresh tokens, or null when the provider refuses to renew it. */
+function renew(current, tokenRequest) {
+    const refreshToken = current.refreshToken;
+    const now = Date.now();
+    for (const [key, entry] of renewals)
+        if (entry.until <= now)
+            renewals.delete(key);
+    const known = renewals.get(refreshToken);
+    if (known)
+        return known.result;
+    const result = (async () => {
+        // The key that obtained the refresh token, or the provider refuses the refresh.
+        const key = current.dpop ? await importDpopKey(current.dpop) : null;
+        const payload = await tokenRequest({ grant_type: 'refresh_token', refresh_token: refreshToken }, key);
+        return {
+            accessToken: String(payload.access_token ?? ''),
+            // A provider that rotates refresh tokens sends a new one; one that does not
+            // expects the old one to keep working.
+            refreshToken: typeof payload.refresh_token === 'string' ? payload.refresh_token : refreshToken,
+            idToken: typeof payload.id_token === 'string' ? payload.id_token : current.idToken,
+            expiresAt: expiryFrom(payload.expires_in),
+            tokenType: typeof payload.token_type === 'string' ? payload.token_type : current.tokenType,
+            dpop: current.dpop,
+            sessionState: current.sessionState,
+        };
+    })().catch((error) => {
+        // Not processed (the provider down or busy): nothing was spent. Ask again after the pause.
+        if (error instanceof ProviderUnavailable) {
+            renewals.set(refreshToken, { until: Date.now() + error.retryAfterMs, result });
+            throw error;
+        }
+        // Refused, or answered in a way that was lost after the provider may have rotated the
+        // token: the session is over either way. Sending the token again would be a replay, which
+        // the provider answers by ending every session of this sign-in.
+        if (error instanceof OAuthError) {
+            renewals.set(refreshToken, { until: Date.now() + SPENT_MS, result });
+            return null;
+        }
+        renewals.delete(refreshToken);
+        throw error;
+    });
+    renewals.set(refreshToken, { until: now + RENEWAL_REUSE_MS, result });
+    return result;
+}
+/** Renewed a little before it runs out, so a request does not reach an API with a dying token. */
+const EXPIRY_SKEW_MS = 30_000;
+const expired = (session) => session.expiresAt !== undefined && session.expiresAt - EXPIRY_SKEW_MS <= Date.now();
+/**
+ * The middleware.
+ *
+ * Handles `<basePath>/login`, `/callback`, `/refresh`, `/me`, `/session-check` and
+ * `/logout`, and passes anything else along untouched.
+ */
+// One default store per configuration, so the routes and sessionLocals built from it share it.
+const defaultLogouts = new WeakMap();
+function logoutsOf(config) {
+    if (config.logouts)
+        return config.logouts;
+    let store = defaultLogouts.get(config);
+    if (!store)
+        defaultLogouts.set(config, (store = memoryLogouts()));
+    return store;
+}
+/** Whether the provider has ended this session over the back channel. */
+async function endedAtProvider(config, session) {
+    const id = idTokenClaims(session.idToken);
+    if (!id.sid && !id.sub)
+        return false;
+    return logoutsOf(config).ended({ sid: id.sid, sub: id.sub, since: (id.iat ?? 0) * 1000 });
+}
+export function oauthRoutes(config) {
+    const { resolve, tokenRequest, clientAuth } = tokenClient(config);
+    const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', ...headers },
+    });
+    const base = (config.basePath ?? '/auth').replace(/\/$/, '');
+    const scopes = config.scopes ?? ['openid', 'profile', 'email'];
+    const cookie = createSessionCookie({
+        secret: config.cookieSecret,
+        name: config.cookieName,
+        secure: config.secureCookie,
+    });
     return async function middleware(request, next) {
         const url = new URL(request.url);
         if (!url.pathname.startsWith(`${base}/`))
             return next();
         const route = url.pathname.slice(base.length);
         const session = async () => {
-            return cookie.read(request);
+            const current = await cookie.read(request);
+            return current && (await endedAtProvider(config, current)) ? null : current;
         };
+        if (route === '/backchannel-logout') {
+            // The provider, server to server: a session this app took part in has ended there.
+            const headers = { 'cache-control': 'no-store' };
+            if (request.method !== 'POST')
+                return json({ error: 'invalid_request' }, 405, headers);
+            try {
+                const form = await request.formData();
+                const token = form.get('logout_token');
+                if (typeof token !== 'string' || !token)
+                    throw new Error('no logout_token');
+                const endpoints = await resolve();
+                const issuer = endpoints.issuer ?? config.issuer;
+                if (!issuer)
+                    throw new Error('no issuer');
+                if (!endpoints.jwks)
+                    throw new Error('no jwks_uri');
+                // Read fresh for each logout (they are rare), so a rotated key is always known.
+                const jwks = (await (await fetch(endpoints.jwks)).json());
+                const entry = await logoutTokenVerifier({ issuer, clientId: config.clientId, jwks })(token);
+                await logoutsOf(config).add(entry);
+                return new Response(null, { status: 200, headers });
+            }
+            catch {
+                return json({ error: 'invalid_request' }, 400, headers);
+            }
+        }
         if (route === '/login') {
-            const { authorization } = await resolve();
+            let authorization;
+            try {
+                ({ authorization } = await resolve());
+            }
+            catch (error) {
+                if (!(error instanceof OAuthError) || error.code !== 'discovery_unreachable')
+                    throw error;
+                // The provider is down: back to the app, which can say so, rather than an error page.
+                const back = safeReturnTo(url.searchParams.get('returnTo'), {
+                    fallback: config.defaultReturnTo ?? '/',
+                    origin: url.origin,
+                    allowedOrigins: config.allowedReturnOrigins,
+                });
+                const target = new URL(back, url.origin);
+                target.searchParams.set('auth_error', 'provider_unreachable');
+                const location = target.origin === url.origin ? target.pathname + target.search : target.toString();
+                return new Response(null, { status: 302, headers: { location } });
+            }
             const { verifier, challenge } = await createPkcePair();
-            const state = createStateValue();
+            // A retry carries its mark in the state itself: the one place that survives the trip
+            // when the cookie does not, so a second failed attempt is told apart from the first.
+            const retry = url.searchParams.get('retry') === '1';
+            const state = createStateValue() + (retry ? RETRY_MARK : '');
             const target = new URL(authorization);
             target.searchParams.set('response_type', 'code');
             target.searchParams.set('client_id', config.clientId);
@@ -106,6 +422,10 @@ export function oauthRoutes(config) {
             target.searchParams.set('state', state);
             target.searchParams.set('code_challenge', challenge);
             target.searchParams.set('code_challenge_method', 'S256');
+            // Only the values OpenID Connect defines; anything else from the query string is dropped.
+            const prompt = url.searchParams.get('prompt');
+            if (prompt && PROMPTS.has(prompt))
+                target.searchParams.set('prompt', prompt);
             // The verifier goes in the cookie, which is the only thing that survives the trip
             // and is not readable by the page.
             const pendingCookie = await cookie.write({
@@ -120,6 +440,7 @@ export function oauthRoutes(config) {
                         origin: url.origin,
                         allowedOrigins: config.allowedReturnOrigins,
                     }) || undefined,
+                    silent: prompt === 'none' || undefined,
                 },
             }, 
             // Ten minutes: long enough to sign in, short enough that an abandoned attempt
@@ -137,26 +458,71 @@ export function oauthRoutes(config) {
             const current = await session();
             const pending = current?.pending;
             const error = url.searchParams.get('error');
-            if (error)
-                return json({ error }, 400);
+            if (error) {
+                // Back to the page the flow started from, never a JSON answer the visitor reads.
+                const ours = !!pending && timingSafeEqual(pending.state, url.searchParams.get('state') ?? '');
+                let location = safeReturnTo(ours ? pending.returnTo ?? config.defaultReturnTo : config.defaultReturnTo, {
+                    fallback: '/',
+                    origin: url.origin,
+                    allowedOrigins: config.allowedReturnOrigins,
+                });
+                const headers = new Headers();
+                headers.append('set-cookie', cookie.clear());
+                if (ours && pending.silent && SILENT_REFUSALS.has(error)) {
+                    // Nobody signed in at the provider: remember it was asked, and show the page as is.
+                    headers.append('set-cookie', checkedCookie(config, sessionStateFrom(url)).header);
+                }
+                else {
+                    const target = new URL(location, url.origin);
+                    target.searchParams.set('auth_error', error);
+                    location = target.origin === url.origin ? target.pathname + target.search : target.toString();
+                }
+                headers.set('location', location);
+                return new Response(null, { status: 302, headers });
+            }
             const code = url.searchParams.get('code');
             const state = url.searchParams.get('state');
             if (!code)
                 return json({ error: 'no_code' }, 400);
             if (!pending || !state || !timingSafeEqual(pending.state, state)) {
-                return json({ error: 'state_mismatch' }, 400);
+                // An answer this browser has no flow for: its cookie expired (a sign-in that took longer
+                // than ten minutes, a provider page refreshed long after), or another tab started a
+                // newer one. Already signed in, the answer is a leftover. Otherwise start again once,
+                // and only then give up, on a page rather than with JSON.
+                const home = safeReturnTo(config.defaultReturnTo, { fallback: '/', origin: url.origin, allowedOrigins: config.allowedReturnOrigins });
+                if (current?.accessToken)
+                    return new Response(null, { status: 302, headers: { location: home } });
+                if (!state?.endsWith(RETRY_MARK)) {
+                    return new Response(null, { status: 302, headers: { location: `${base}/login?retry=1` } });
+                }
+                const target = new URL(home, url.origin);
+                target.searchParams.set('auth_error', 'state_mismatch');
+                return new Response(null, {
+                    status: 302,
+                    headers: {
+                        location: target.origin === url.origin ? target.pathname + target.search : target.toString(),
+                        'set-cookie': cookie.clear(),
+                    },
+                });
             }
+            // The token is bound here, at the exchange, so this is where the session's key is made.
+            const key = config.dpop
+                ? await createDpopKey(config.dpopAlgorithm, { extractable: true })
+                : null;
             const payload = await tokenRequest({
                 grant_type: 'authorization_code',
                 code,
                 redirect_uri: config.redirectUri,
                 code_verifier: pending.verifier,
-            });
+            }, key);
             const signedIn = await cookie.write({
                 accessToken: String(payload.access_token ?? ''),
                 refreshToken: typeof payload.refresh_token === 'string' ? payload.refresh_token : undefined,
                 idToken: typeof payload.id_token === 'string' ? payload.id_token : undefined,
                 expiresAt: expiryFrom(payload.expires_in),
+                tokenType: typeof payload.token_type === 'string' ? payload.token_type : undefined,
+                dpop: key ? await exportDpopKey(key) : undefined,
+                sessionState: sessionStateFrom(url),
             });
             return new Response(null, {
                 status: 302,
@@ -177,21 +543,10 @@ export function oauthRoutes(config) {
             const current = await session();
             if (!current?.refreshToken)
                 return json({ error: 'no_session' }, 401);
-            const payload = await tokenRequest({
-                grant_type: 'refresh_token',
-                refresh_token: current.refreshToken,
-            });
-            const refreshed = await cookie.write({
-                accessToken: String(payload.access_token ?? ''),
-                // A provider that rotates refresh tokens sends a new one; one that does not
-                // expects the old one to keep working.
-                refreshToken: typeof payload.refresh_token === 'string'
-                    ? payload.refresh_token
-                    : current.refreshToken,
-                idToken: current.idToken,
-                expiresAt: expiryFrom(payload.expires_in),
-            });
-            return json({ ok: true }, 200, { 'set-cookie': refreshed });
+            const renewed = await renew(current, tokenRequest);
+            if (!renewed)
+                return json({ error: 'refresh_refused' }, 401, { 'set-cookie': cookie.clear() });
+            return json({ ok: true }, 200, { 'set-cookie': await cookie.write(renewed) });
         }
         if (route === '/me') {
             const current = await session();
@@ -200,14 +555,22 @@ export function oauthRoutes(config) {
             const { userinfo } = await resolve();
             if (!userinfo)
                 return json({ error: 'no_userinfo' }, 501);
-            const response = await fetch(userinfo, {
-                headers: { authorization: `Bearer ${current.accessToken}` },
-            });
+            const response = await withToken(userinfo, current);
             if (!response.ok)
                 return json({ error: 'userinfo_failed' }, response.status);
             const claims = (await response.json());
             return json(config.mapUser ? config.mapUser(claims, current.accessToken) : claims);
         }
+        if (route === '/session-check') {
+            // What the page needs to watch the provider's session: its check page, this client,
+            // and the last answer's session_state, signed in or not. Nothing secret: the state is
+            // a salted hash bound to this origin.
+            const { checkSession } = await resolve().catch(() => ({ checkSession: undefined }));
+            const current = await session();
+            const checked = cookieValue(request, checkedCookie(config).name);
+            const state = current?.accessToken ? current.sessionState : checked !== '1' ? checked : undefined;
+            return json({ frame: checkSession ?? null, clientId: config.clientId, state: state ?? null });
+        }
         if (route === '/revoke') {
             const current = await session();
             const hint = url.searchParams.get('hint') === 'access_token' ? 'access_token' : 'refresh_token';
@@ -248,18 +611,21 @@ export function oauthRoutes(config) {
             }
             // Max-Age=0 is what removes it. Clearing the value alone leaves a cookie behind.
             const cleared = cookie.clear();
+            // Signed out on purpose: `silent` must not sign them straight back in.
+            const headers = new Headers();
+            headers.append('set-cookie', cleared);
+            headers.append('set-cookie', checkedCookie(config).header);
             if (endSession && current?.idToken) {
                 const target = new URL(endSession);
                 target.searchParams.set('id_token_hint', current.idToken);
                 if (config.defaultReturnTo) {
                     target.searchParams.set('post_logout_redirect_uri', config.defaultReturnTo);
                 }
-                return new Response(null, {
-                    status: 302,
-                    headers: { location: target.toString(), 'set-cookie': cleared },
-                });
+                headers.set('location', target.toString());
+                return new Response(null, { status: 302, headers });
             }
-            return json({ ok: true }, 200, { 'set-cookie': cleared });
+            headers.set('content-type', 'application/json');
+            return new Response(JSON.stringify({ ok: true }), { status: 200, headers });
         }
         return next();
     };
@@ -295,6 +661,7 @@ export function sessionLocals(config) {
         name: config.cookieName,
         secure: config.secureCookie,
     });
+    const { tokenRequest } = tokenClient(config);
     const ttl = config.userCacheMs ?? 30_000;
     /**
      * Keyed by the access token, which this process already holds in the cookie it just
@@ -322,25 +689,78 @@ export function sessionLocals(config) {
     return async function middleware(request, next) {
         const { getRequestLocals } = await import('@fluixi/server');
         const locals = getRequestLocals(request);
-        const session = await cookie.read(request);
+        let session = await cookie.read(request);
+        // What the browser's cookie must become: renewed tokens, or nothing.
+        let setCookie;
+        const respond = async (response) => {
+            if (!setCookie)
+                return response;
+            const copy = new Response(response.body, response);
+            copy.headers.append('set-cookie', setCookie);
+            return copy;
+        };
+        const renewOrDrop = async (current) => {
+            const renewed = current.refreshToken ? await renew(current, tokenRequest) : null;
+            setCookie = renewed ? await cookie.write(renewed) : cookie.clear();
+            return renewed;
+        };
+        // An access token lives minutes, the session days: renew it here, on the request that
+        // finds it expired, rather than rendering a signed-in visitor as nobody.
+        // Set when the provider could not renew now: the session stays, it is retried later.
+        let paused = false;
+        const keep = (current) => (error) => {
+            if (error instanceof ProviderUnavailable)
+                paused = true;
+            return current;
+        };
+        if (session?.accessToken && expired(session)) {
+            session = await renewOrDrop(session).catch(keep(session));
+        }
         // Written either way. A route that reads locals should find "nobody" rather than
         // nothing, so the absent case and the signed-out case look the same to it.
-        if (!session?.accessToken) {
+        const signedOut = async () => {
+            const redirect = signInRedirect(request, config);
+            if (redirect)
+                return respond(redirect);
             locals.auth = { user: null, session: null };
-            return next();
+            return respond(await next());
+        };
+        if (!session?.accessToken)
+            return signedOut();
+        // Ended at the provider (back-channel logout): this session is over too.
+        if (await endedAtProvider(config, session)) {
+            setCookie = cookie.clear();
+            session = null;
+            return signedOut();
         }
-        const cached = cache.get(session.accessToken);
+        // Server code calls the app's APIs as this user with it; the token itself stays here.
+        const live = session;
+        const fetchAs = (input, init) => sendAs(live, input, init);
+        const cached = cache.get(live.accessToken);
         if (cached && cached.until > Date.now()) {
-            locals.auth = { user: cached.user, session: { expiresAt: session.expiresAt } };
-            return next();
+            locals.auth = { user: cached.user, session: { expiresAt: live.expiresAt }, fetch: fetchAs };
+            return respond(await next());
         }
         let user = null;
+        let unreachable = false;
         try {
             const endpoints = config.endpoints ?? (config.issuer ? await discover(config.issuer) : null);
             if (endpoints?.userinfo) {
-                const response = await fetch(endpoints.userinfo, {
-                    headers: { authorization: `Bearer ${session.accessToken}` },
-                });
+                let response = await withToken(endpoints.userinfo, session);
+                // Refused before its time (revoked, a clock apart): renew once, and when that is
+                // refused too the session is over, so the visitor goes the signed-out way.
+                if (response.status === 401 && !setCookie && !paused) {
+                    session = await renewOrDrop(session).catch(keep(session));
+                    if (!session)
+                        return signedOut();
+                    response = await withToken(endpoints.userinfo, session);
+                }
+                if (response.status === 401) {
+                    // Not renewable just now: signed out for this request, renewed on a later one.
+                    if (!paused)
+                        setCookie = cookie.clear();
+                    return signedOut();
+                }
                 if (response.ok) {
                     const claims = (await response.json());
                     user = config.mapUser ? config.mapUser(claims, session.accessToken) : claims;
@@ -352,9 +772,42 @@ export function sessionLocals(config) {
         }
         catch {
             // A provider that is unreachable should not take the page down with it. The render
-            // proceeds as signed out, and the client retries on its own.
+            // proceeds as signed out, and the client retries on its own; `unreachable` tells
+            // server code it is not the visitor who is signed out.
+            unreachable = true;
         }
-        locals.auth = { user, session: user ? { expiresAt: session.expiresAt } : null };
-        return next();
+        if (!session)
+            return signedOut();
+        const current = session;
+        const fetchCurrent = (input, init) => sendAs(current, input, init);
+        locals.auth = user
+            ? { user, session: { expiresAt: current.expiresAt }, fetch: fetchCurrent }
+            : { user: null, session: null, ...(unreachable ? { unreachable: true } : {}) };
+        return respond(await next());
     };
 }
+/**
+ * The request's auth, for server code: a route's data loader, a server function, an API route.
+ * Reads the current request's locals, or `request`'s when one is given.
+ *
+ * ```ts
+ * const { fetch } = await requestAuth();
+ * const projects = await fetch?.(`${apiUrl}/projects`).then((r) => r.json());
+ * ```
+ */
+export async function requestAuth(request) {
+    const { getLocals, getRequestLocals } = await import('@fluixi/server');
+    const locals = (request ? getRequestLocals(request) : getLocals());
+    return locals.auth ?? { user: null, session: null };
+}
+/**
+ * The server half of `authModule`, listed in `src/app.config.server.ts`: the routes and the
+ * session middleware that `tokens: 'server'` needs, in the order they have to run.
+ *
+ * `oauthRoutes` first, so a request to the login route is answered rather than having its
+ * session resolved on the way past.
+ */
+export function authServerModule(config) {
+    return defineModule({ name: 'oauth2-server', middleware: [oauthRoutes(config), sessionLocals(config)] });
+}
+export { memoryLogouts } from './backchannel.js';