fastify-txstate 4.0.0 → 4.0.1

package/lib/oauth.js

@@ -1,305 +1,49 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
-import { createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';
-import { Cache, isBlank, isNotBlank, htmlEncode } from 'txstate-utils';
+import { createHash, randomBytes } from 'node:crypto';
+import { decodeJwt } from 'jose';
+import { htmlEncode, isBlank, isNotBlank } from 'txstate-utils';
 import { apiBaseUrl, uiBaseUrl } from "./server.js";
-let hasInit = false;
-const trustedIssuers = new Set();
-const trustedAudiences = new Set();
-const trustedClients = new Set();
-const issuerInternalUrls = new Map();
-/** Rewrite a URL for server-to-server requests. Not for browser-facing URLs. */
-function toInternalUrl(url) {
-    for (const [external, internal] of issuerInternalUrls) {
-        if (url.startsWith(external))
-            return internal + url.slice(external.length);
-    }
-    return url;
-}
-const oauthCookieName = process.env.OAUTH_COOKIE_NAME ?? randomBytes(16).toString('hex');
-const oauthCookieNameRegex = new RegExp(`${oauthCookieName}=([^;]+)`, 'v');
-const refreshCookieName = oauthCookieName + '_rt';
-const refreshCookieRegex = new RegExp(`${refreshCookieName}=([^;]+)`, 'v');
-const accessTokenCookieName = oauthCookieName + '_at';
-const accessTokenCookieRegex = new RegExp(`${accessTokenCookieName}=([^;]+)`, 'v');
-let cookieEncryptionKey;
-function wrapRefreshToken(token) {
-    if (!cookieEncryptionKey)
-        return token;
-    const iv = randomBytes(12);
-    const cipher = createCipheriv('aes-256-gcm', cookieEncryptionKey, iv);
-    const encrypted = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    return Buffer.concat([iv, tag, encrypted]).toString('base64url');
-}
-function unwrapRefreshToken(value) {
-    if (!cookieEncryptionKey)
-        return value;
-    try {
-        const data = Buffer.from(value, 'base64url');
-        const iv = data.subarray(0, 12);
-        const tag = data.subarray(12, 28);
-        const encrypted = data.subarray(28);
-        const decipher = createDecipheriv('aes-256-gcm', cookieEncryptionKey, iv);
-        decipher.setAuthTag(tag);
-        return decipher.update(encrypted, undefined, 'utf8') + decipher.final('utf8');
-    }
-    catch {
-        return undefined;
-    }
-}
-const discoveryCache = new Cache(async (issuerUrl) => {
-    const base = issuerUrl.endsWith('/') ? issuerUrl : issuerUrl + '/';
-    // try OpenID Connect discovery first, then OAuth 2.0 Authorization Server Metadata
-    for (const path of ['.well-known/openid-configuration', '.well-known/oauth-authorization-server']) {
-        try {
-            const resp = await fetch(new URL(path, toInternalUrl(base)));
-            if (resp.ok) {
-                const doc = await resp.json();
-                if (isNotBlank(doc.jwks_uri))
-                    return doc;
-            }
-        }
-        catch { /* try next */ }
-    }
-    return undefined;
-}, { freshseconds: 3600 });
-const jwkSetCache = new Cache(async (jwksUri) => createRemoteJWKSet(new URL(toInternalUrl(jwksUri))), { freshseconds: 3600 });
-function checkAudience(aud, req) {
-    if (!trustedAudiences.size)
-        return true;
-    const audiences = Array.isArray(aud) ? aud : [aud];
-    if (!audiences.some(a => trustedAudiences.has(a))) {
-        req.log.warn(`Received token with untrusted audience: ${String(aud)}`);
-        return false;
-    }
-    return true;
-}
-function checkClientId(clientId, req) {
-    if (!trustedClients.size)
-        return true;
-    if (!trustedClients.has(clientId)) {
-        req.log.warn(`Received token with untrusted client_id: ${String(clientId)}.`);
-        return false;
-    }
-    return true;
-}
-const tokenCache = new Cache(async (token, req) => {
-    const claims = decodeJwt(token);
-    if (!claims.iss) {
-        req.log.warn('Received OAuth token without an issuer claim.');
-        return undefined;
-    }
-    if (!trustedIssuers.has(claims.iss)) {
-        req.log.warn(`Received token with untrusted issuer: ${claims.iss}`);
-        return undefined;
-    }
-    try {
-        const discovery = await discoveryCache.get(claims.iss);
-        if (!discovery?.jwks_uri)
-            return undefined;
-        const jwkSet = await jwkSetCache.get(discovery.jwks_uri);
-        const { payload } = await jwtVerify(token, jwkSet);
-        if (!checkAudience(payload.aud, req))
-            return undefined;
-        if (!checkClientId(payload.client_id, req))
-            return undefined;
-        return { payload, discovery };
-    }
-    catch (e) {
-        const code = e.code;
-        if (code !== 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED' && code !== 'ERR_JWT_EXPIRED')
-            req.log.error(e);
-        return undefined;
-    }
-}, { freshseconds: 3600 });
-function init() {
-    hasInit = true;
-    const issuers = process.env.OAUTH_TRUSTED_ISSUERS?.split(',').filter(isNotBlank).map(s => s.trim()) ?? [];
-    if (!issuers.length)
-        throw new Error('OAUTH_TRUSTED_ISSUERS environment variable must be set when using oauthAuthenticate. Provide a comma-separated list of trusted issuer URLs.');
-    for (const issuer of issuers) {
-        trustedIssuers.add(issuer);
-    }
-    // Note: some providers (e.g. Google) set `aud` on ID tokens to the OAuth client ID
-    // rather than a resource server URL. If accepting ID tokens from such providers, set
-    // OAUTH_TRUSTED_AUDIENCES to your OAuth client ID.
-    for (const audience of (process.env.OAUTH_TRUSTED_AUDIENCES?.split(',').filter(isNotBlank).map(s => s.trim()) ?? [])) {
-        trustedAudiences.add(audience);
-    }
-    for (const clientId of (process.env.OAUTH_TRUSTED_CLIENTIDS?.split(',').filter(isNotBlank).map(s => s.trim()) ?? [])) {
-        trustedClients.add(clientId);
-    }
-    // Map external issuer URLs to internal URLs for split-horizon DNS (e.g. communication inside a docker network)
-    for (const pair of (process.env.OAUTH_ISSUER_INTERNAL_URLS?.split(',').filter(isNotBlank).map(s => s.trim()) ?? [])) {
-        const eq = pair.indexOf('=');
-        if (eq > 0)
-            issuerInternalUrls.set(pair.slice(0, eq), pair.slice(eq + 1));
-    }
-    if (isNotBlank(process.env.OAUTH_COOKIE_SECRET)) {
-        cookieEncryptionKey = createHash('sha256').update(process.env.OAUTH_COOKIE_SECRET).digest();
-    }
-}
-function tokenFromReq(req) {
-    const m = req?.headers.authorization?.match(/^bearer (.*)$/iv);
-    if (m != null)
-        return m[1];
-    const m2 = req?.headers.cookie?.match(oauthCookieNameRegex);
-    if (m2 != null)
-        return m2[1];
-}
-function refreshTokenFromReq(req) {
-    const m = req.headers.cookie?.match(refreshCookieRegex);
-    if (!m)
-        return undefined;
-    return unwrapRefreshToken(m[1]);
-}
-function accessTokenFromReq(req) {
-    const m = req.headers.cookie?.match(accessTokenCookieRegex);
-    if (!m)
-        return undefined;
-    return unwrapRefreshToken(m[1]);
-}
-async function tryRefresh(req, expiredIssuer) {
-    const refreshToken = refreshTokenFromReq(req);
-    if (!refreshToken)
-        return undefined;
-    const clientId = process.env.OAUTH_CLIENT_ID;
-    if (!clientId)
-        return undefined;
-    const issuerUrl = (expiredIssuer && trustedIssuers.has(expiredIssuer)) ? expiredIssuer : [...trustedIssuers][0];
-    const discovery = await discoveryCache.get(issuerUrl);
-    if (!discovery?.token_endpoint)
-        return undefined;
-    const body = {
-        grant_type: 'refresh_token',
-        refresh_token: refreshToken,
-        client_id: clientId
-    };
-    const clientSecret = process.env.OAUTH_CLIENT_SECRET;
-    if (clientSecret)
-        body.client_secret = clientSecret;
-    try {
-        const tokenResp = await fetch(toInternalUrl(discovery.token_endpoint), {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-            body: new URLSearchParams(body)
-        });
-        if (!tokenResp.ok)
-            return undefined;
-        const tokens = await tokenResp.json();
-        if (!tokens.id_token)
-            return undefined;
-        // queue new cookies to be set on the response
-        req.pendingOAuthCookies = [
-            `${oauthCookieName}=${tokens.id_token}; Path=/; Secure; HttpOnly; SameSite=Lax`
-        ];
-        if (tokens.access_token) {
-            req.pendingOAuthCookies.push(`${accessTokenCookieName}=${wrapRefreshToken(tokens.access_token)}; Path=/; Secure; HttpOnly; SameSite=Lax`);
-        }
-        // some providers rotate the refresh token on each use
-        if (tokens.refresh_token) {
-            req.pendingOAuthCookies.push(`${refreshCookieName}=${wrapRefreshToken(tokens.refresh_token)}; Path=/; Secure; HttpOnly; SameSite=Lax`);
-        }
-        const result = await tokenCache.get(tokens.id_token, req);
-        if (!result)
-            return undefined;
-        if (result.payload.exp && result.payload.exp * 1000 <= Date.now())
-            return undefined;
-        return { token: tokens.id_token, payload: result.payload, discovery };
-    }
-    catch (e) {
-        req.log.error(e);
-        return undefined;
-    }
-}
-function buildAuthInfo(token, payload, discovery, extraClaims) {
-    const issuerConf = {
-        iss: payload.iss,
-        url: payload.iss,
-        logoutUrl: isNotBlank(discovery.end_session_endpoint) ? new URL(discovery.end_session_endpoint) : undefined
-    };
-    return {
-        ...extraClaims?.(payload),
-        token,
-        issuerConfig: issuerConf,
-        username: payload.sub,
-        sessionId: payload.sub + '-' + String(payload.iat),
-        sessionCreatedAt: payload.iat ? new Date(payload.iat * 1000) : undefined,
-        clientId: payload.client_id,
-        impersonatedBy: payload.act?.sub,
-        scope: payload.scope
-    };
-}
-async function oauthAuthenticateInternal(req, extraClaims) {
-    if (!hasInit)
-        init();
-    const token = tokenFromReq(req);
-    if (!token)
-        return undefined;
-    let result;
-    const cacheResult = await tokenCache.get(token, req);
-    if (!cacheResult) {
-        // jwtVerify rejects expired tokens, so the cache returns undefined — try to refresh
-        try {
-            const { iss } = decodeJwt(token);
-            result = await tryRefresh(req, iss ?? undefined);
-        }
-        catch { /* no result */ }
-    }
-    else if (cacheResult.payload.exp && cacheResult.payload.exp * 1000 <= Date.now()) {
-        // belt-and-suspenders: catch tokens that expired after being cached
-        result = await tryRefresh(req, cacheResult.payload.iss);
-    }
-    else {
-        result = { token, payload: cacheResult.payload, discovery: cacheResult.discovery };
-    }
-    if (!result)
-        return undefined;
-    const authInfo = buildAuthInfo(result.token, result.payload, result.discovery, extraClaims);
-    authInfo.accessToken = accessTokenFromReq(req);
-    return authInfo;
-}
+import { accessTokenCookieName, getOAuthDiscovery, getOAuthIssuerUrls, init, oauthCookieName, refreshCookieName, registeredExceptRoutes, registeredOptionalRoutes, toInternalUrl, wrapRefreshToken } from "./jwt-auth.js";
 /**
- * Authenticate requests using JWT tokens from any OAuth/OIDC provider. The token's
- * issuer claim is used to auto-discover the provider's JWKS endpoint for signature
- * verification.
+ * Register cookie-based OAuth login/logout endpoints. Uses the authorization code flow
+ * with PKCE (S256) to exchange a code for tokens, then stores the ID token in an HttpOnly
+ * cookie. The access token and refresh token are stored in separate cookies (optionally
+ * encrypted via OAUTH_COOKIE_SECRET) so that the ID token can be transparently refreshed
+ * by jwtAuthenticate when it expires, and the access token is available at
+ * `req.auth.accessToken` for calling provider APIs.
  *
- * Expects JWT tokens (access tokens or ID tokens) in the Authorization Bearer header
- * or in a cookie set by registerOAuthCookieRoutes.
+ * Requires OAUTH_COOKIE_CLIENT_ID environment variable. OAUTH_COOKIE_CLIENT_SECRET is
+ * optional — PKCE provides the security for the code exchange, but some providers require
+ * a client secret even with PKCE. OAUTH_COOKIE_SECRET is optional — if set, the access
+ * token and refresh token cookies are encrypted with AES-256-GCM; if not, they are stored
+ * as plaintext (still HttpOnly and Secure).
  *
- * For providers like Google that issue opaque access tokens, have the client send the
- * ID token instead — it's a standard JWT that proves the user's identity without
- * requiring a round-trip to the provider on every request.
+ * Trusted issuers are configured via OAUTH_URLS or JWT_TRUSTED_ISSUERS (see jwt-auth.ts).
+ *
+ * Registers three routes:
+ * - `/.oauthRedirect` - Redirects to the OAuth provider's login page. The client passes
+ *    `requestedUrl` (required) which is sent to the provider as the `state` parameter,
+ *    round-tripped back, and used as the redirect destination after login.
+ * - `/.oauthCallback` - Handles the provider's redirect, exchanges the code for tokens
+ *    using the PKCE code verifier. Sets the ID token (or JWT access token as fallback),
+ *    access token, and refresh token as cookies.
+ * - `/.oauthLogout` - Clears all OAuth cookies and redirects to the provider's logout
+ *    endpoint if available.
  */
-export async function oauthAuthenticate(req, options) {
-    if (options?.usingOAuthCookieRoutes) {
-        options.exceptRoutes ??= new Set();
-        options.exceptRoutes.add('/.oauthCallback');
-        options.exceptRoutes.add('/.oauthRedirect');
-        options.optionalRoutes ??= new Set();
-        options.optionalRoutes.add('/.oauthLogout');
-    }
-    if (options?.exceptRoutes?.has(req.routeOptions.url))
-        return undefined;
-    const auth = await oauthAuthenticateInternal(req, options?.extraClaims);
-    if (options?.authenticateAll && !options.optionalRoutes?.has(req.routeOptions.url) && isBlank(auth?.username)) {
-        throw new Error('Request requires authentication.');
-    }
-    return auth;
-}
 export function registerOAuthCookieRoutes(app, options) {
-    const clientId = process.env.OAUTH_CLIENT_ID;
+    const clientId = process.env.OAUTH_COOKIE_CLIENT_ID;
     if (!clientId)
-        throw new Error('OAUTH_CLIENT_ID environment variable must be set when using registerOAuthCookieRoutes.');
-    if (!hasInit)
-        init();
-    const clientSecret = process.env.OAUTH_CLIENT_SECRET;
+        throw new Error('OAUTH_COOKIE_CLIENT_ID environment variable must be set when using registerOAuthCookieRoutes.');
+    init();
+    const clientSecret = process.env.OAUTH_COOKIE_CLIENT_SECRET;
+    registeredExceptRoutes.add('/.oauthCallback');
+    registeredExceptRoutes.add('/.oauthRedirect');
+    registeredOptionalRoutes.add('/.oauthLogout');
     const callbackPath = '/.oauthCallback';
     const pkceVerifierCookieName = oauthCookieName + '_pkce';
     const pkceVerifierCookieRegex = new RegExp(`${pkceVerifierCookieName}=([A-Za-z0-9_-]+)`, 'v');
     const issuerCookieName = oauthCookieName + '_iss';
     const issuerCookieRegex = new RegExp(`${issuerCookieName}=([^;]+)`, 'v');
-    // flush any pending cookies set during token refresh
+    // flush any pending cookies queued during token refresh by jwtAuthenticate
     app.addHook('onSend', async (req, res) => {
         if (req.pendingOAuthCookies?.length) {
             for (const cookie of req.pendingOAuthCookies)
@@ -324,9 +68,12 @@ export function registerOAuthCookieRoutes(app, options) {
             void res.status(403);
             return 'Requested URL failed origin check.';
         }
+        const issuerUrls = getOAuthIssuerUrls();
+        if (!issuerUrls.length)
+            throw new Error('No OAuth issuers are configured. Set OAUTH_URLS or include oauth issuers in JWT_TRUSTED_ISSUERS.');
         // if multiple issuers and no issuer specified, show a login selection page
-        if (!req.query.issuer && trustedIssuers.size > 1 && options?.loginPage) {
-            const issuers = [...trustedIssuers].map(iss => {
+        if (!req.query.issuer && issuerUrls.length > 1 && options?.loginPage) {
+            const issuers = issuerUrls.map(iss => {
                 const redirectUrl = new URL(apiBaseUrl(req) + '/.oauthRedirect');
                 redirectUrl.searchParams.set('requestedUrl', req.query.requestedUrl);
                 if (req.query.scope)
@@ -337,10 +84,10 @@ export function registerOAuthCookieRoutes(app, options) {
             void res.type('text/html');
             return options.loginPage(issuers);
         }
-        const issuerUrl = req.query.issuer && trustedIssuers.has(req.query.issuer)
+        const issuerUrl = req.query.issuer && issuerUrls.includes(req.query.issuer)
             ? req.query.issuer
-            : [...trustedIssuers][0];
-        const discovery = await discoveryCache.get(issuerUrl);
+            : issuerUrls[0];
+        const discovery = await getOAuthDiscovery(issuerUrl);
         if (!discovery?.authorization_endpoint)
             throw new Error(`OAuth issuer ${issuerUrl} does not have an authorization endpoint.`);
         const codeVerifier = randomBytes(32).toString('base64url');
@@ -388,9 +135,10 @@ export function registerOAuthCookieRoutes(app, options) {
             return 'Missing PKCE code verifier. The login flow may have expired.';
         }
         const codeVerifier = verifierMatch[1];
+        const issuerUrls = getOAuthIssuerUrls();
         const issuerMatch = req.headers.cookie?.match(issuerCookieRegex);
-        const issuerUrl = issuerMatch ? decodeURIComponent(issuerMatch[1]) : [...trustedIssuers][0];
-        const discovery = await discoveryCache.get(issuerUrl);
+        const issuerUrl = issuerMatch ? decodeURIComponent(issuerMatch[1]) : issuerUrls[0];
+        const discovery = await getOAuthDiscovery(issuerUrl);
         if (!discovery?.token_endpoint)
             throw new Error(`OAuth issuer ${issuerUrl} does not have a token endpoint.`);
         const redirectUri = apiBaseUrl(req) + callbackPath;
@@ -505,3 +253,20 @@ export function registerOAuthCookieRoutes(app, options) {
 </html>`;
     });
 }
+/**
+ * This function is available for server-side view code instead of a client-side application
+ * using a framework. It will automatically redirect the user through the OAuth login flow
+ * (via /.oauthRedirect, which must be registered by registerOAuthCookieRoutes) and return
+ * true if they are not authenticated. Otherwise it simply returns false.
+ */
+export async function requireCookieAuthOAuth(req, res) {
+    if (isBlank(req.auth?.username)) {
+        const redirectUrl = new URL(apiBaseUrl(req) + '/.oauthRedirect');
+        redirectUrl.searchParams.set('requestedUrl', apiBaseUrl(req) + req.originalUrl);
+        void res.redirect(redirectUrl.toString());
+        return true;
+    }
+    else {
+        return false;
+    }
+}

package/lib/server.js

@@ -149,6 +149,7 @@ export default class Server {
             else
                 config.trustProxy = process.env.TRUST_PROXY;
         }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- ajvFormats cast is required by tsc even though eslint thinks otherwise
         config.ajv = { ...config.ajv, mode: undefined, plugins: [...(config.ajv?.plugins ?? []), ajvErrors, [ajvFormats, { mode: 'fast' }]], customOptions: { ...config.ajv?.customOptions, allErrors: true, strictSchema: false, coerceTypes: true } };
         this.healthCallback = config.checkHealth;
         this.app = fastify(config);

package/lib/unified-auth.d.ts

@@ -1,9 +1,11 @@
 import type { FastifyReply, FastifyRequest } from 'fastify';
-import { type IssuerConfig, type FastifyInstanceTyped, type FastifyTxStateAuthInfo } from './server.ts';
-export interface IssuerConfigRaw extends Omit<IssuerConfig, 'validateUrl' | 'logoutUrl'> {
-    validateUrl?: string;
-    logoutUrl?: string;
-}
+import { type FastifyInstanceTyped, type FastifyTxStateAuthInfo } from './server.ts';
+/**
+ * @deprecated Use `jwtAuthenticate(options)` instead. Note the new shape: `jwtAuthenticate`
+ * is now a factory that takes options up front and returns the authenticator function
+ * (`authenticate: jwtAuthenticate({ authenticateAll: true })`), so the options actually
+ * take effect when wired into `new Server({ authenticate })`.
+ */
 export declare function unifiedAuthenticate(req: FastifyRequest, options?: {
     authenticateAll?: boolean;
     exceptRoutes?: Set<string>;
@@ -11,7 +13,7 @@ export declare function unifiedAuthenticate(req: FastifyRequest, options?: {
     usingUaCookieRoutes?: boolean;
 }): Promise<FastifyTxStateAuthInfo | undefined>;
 /**
- * @deprecated Use unifiedAuthenticateWithOptions with { authenticateAll: true } instead.
+ * @deprecated Use `jwtAuthenticate({ authenticateAll: true })` instead.
  */
 export declare function unifiedAuthenticateAll(req: FastifyRequest): Promise<FastifyTxStateAuthInfo>;
 /**
@@ -19,5 +21,9 @@ export declare function unifiedAuthenticateAll(req: FastifyRequest): Promise<Fas
  * using a framework. It will automatically redirect the user to the Unified Auth login page
  * and return true if they are not authenticated. Otherwise it simply returns false.
  */
+export declare function requireCookieAuthUa(req: FastifyRequest, res: FastifyReply): Promise<boolean>;
+/**
+ * @deprecated Use requireCookieAuthUa instead.
+ */
 export declare function requireCookieAuth(req: FastifyRequest, res: FastifyReply): Promise<boolean>;
 export declare function registerUaCookieRoutes(app: FastifyInstanceTyped): void;

package/lib/unified-auth.js

@@ -1,176 +1,33 @@
-import { createPublicKey, createSecretKey, randomBytes } from 'node:crypto';
-import { createRemoteJWKSet, decodeJwt, jwtVerify, importJWK } from 'jose';
-import { Cache, htmlEncode, isBlank, isNotBlank, toArray } from 'txstate-utils';
+import { htmlEncode, isBlank, isNotBlank } from 'txstate-utils';
+import { getIssuerConfig, jwtAuthenticate, registeredExceptRoutes, registeredOptionalRoutes, uaCookieName } from "./jwt-auth.js";
 import { apiBaseUrl, uiBaseUrl } from "./server.js";
-let hasInit = false;
-const issuerKeys = new Map();
-const issuerConfig = new Map();
-const trustedClients = new Set();
-const uaCookieName = process.env.UA_COOKIE_NAME ?? randomBytes(16).toString('hex');
-const uaCookieNameRegex = new RegExp(`${uaCookieName}=([^;]+)`, 'v');
 function uaServiceUrl(req) {
     return apiBaseUrl(req) + '/.uaService';
 }
-const tokenCache = new Cache(async (token, req) => {
-    const claims = decodeJwt(token);
-    let verifyKey;
-    if (claims.iss && issuerKeys.has(claims.iss))
-        verifyKey = issuerKeys.get(claims.iss);
-    if (!verifyKey) {
-        req.log.warn(`Received token with issuer: ${claims.iss} but JWT secret could not be found. The server may be misconfigured or the user may have presented a JWT from an untrusted issuer.`);
-        return undefined;
-    }
-    try {
-        const { payload } = await jwtVerify(token, verifyKey);
-        if (trustedClients.size && !trustedClients.has(payload.client_id)) {
-            req.log.warn(`Received token with untrusted client_id: ${payload.client_id}.`);
-            return undefined;
-        }
-        return payload;
-    }
-    catch (e) {
-        // squelch expected token errors — bad signatures and expirations show as 401 in the access log
-        const code = e.code;
-        if (code !== 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED' && code !== 'ERR_JWT_EXPIRED')
-            req.log.error(e);
-        return undefined;
-    }
-}, { freshseconds: 3600 });
-const validateCache = new Cache(async (token, payload) => {
-    const config = issuerConfig.get(payload.iss);
-    if (!config?.validateUrl)
-        return;
-    // avoid checking for deauth until the token is more than 5 minutes old
-    if (new Date(payload.iat * 1000) > new Date(new Date().getTime() - 1000 * 60 * 5))
-        return;
-    const validateUrl = new URL(config.validateUrl);
-    validateUrl.searchParams.set('unifiedJwt', token);
-    const resp = await fetch(validateUrl);
-    const validate = await resp.json();
-    if (!validate.valid)
-        throw new Error(validate.reason ?? 'Your session has been ended on another device or in another browser tab/window. It\'s also possible your NetID is no longer active.');
-});
-const jwkCache = new Cache(async (url) => {
-    const { keys } = await (await fetch(url)).json();
-    const publicKeyByKid = {};
-    for (const jwk of keys) {
-        if (jwk.kid)
-            publicKeyByKid[jwk.kid] = await importJWK(jwk);
-    }
-    return publicKeyByKid;
-});
-function remoteJWKSet(jwkUrl) {
-    return async (protectedHeader) => {
-        const publicKeyByKid = await jwkCache.get(jwkUrl);
-        return publicKeyByKid[protectedHeader.kid];
-    };
-}
-function processIssuerConfig(config) {
-    if (config.iss === 'unified-auth') {
-        const validateUrl = isNotBlank(config.validateUrl)
-            ? new URL(config.validateUrl, config.url)
-            : new URL('validateToken', config.url);
-        const logoutUrl = isNotBlank(config.logoutUrl)
-            ? new URL(config.logoutUrl, config.url)
-            : isNotBlank(process.env.UA_URL)
-                ? new URL(process.env.UA_URL + '/logout')
-                : new URL('logout', config.url);
-        return {
-            ...config,
-            validateUrl,
-            logoutUrl
-        };
-    }
-    return {
-        ...config,
-        validateUrl: undefined,
-        logoutUrl: config.logoutUrl ? new URL(config.logoutUrl, config.url) : undefined
-    };
-}
-function init() {
-    hasInit = true;
-    if (process.env.JWT_TRUSTED_ISSUERS) {
-        const issuers = toArray(JSON.parse(process.env.JWT_TRUSTED_ISSUERS));
-        for (const issuer of issuers) {
-            issuerConfig.set(issuer.iss, processIssuerConfig(issuer));
-            if (issuer.iss === 'unified-auth')
-                issuerKeys.set(issuer.iss, remoteJWKSet(issuer.url));
-            else if (issuer.url)
-                issuerKeys.set(issuer.iss, createRemoteJWKSet(new URL(issuer.url)));
-            else if (issuer.publicKey)
-                issuerKeys.set(issuer.iss, createPublicKey(issuer.publicKey));
-            else if (issuer.secret)
-                issuerKeys.set(issuer.iss, createSecretKey(Buffer.from(issuer.secret, 'ascii')));
-        }
-    }
-    for (const clientId of (process.env.JWT_TRUSTED_CLIENTIDS?.split(',').filter(isNotBlank).map(clientId => clientId.trim()) ?? [])) {
-        trustedClients.add(clientId);
-    }
-}
-function tokenFromReq(req) {
-    const m = req?.headers.authorization?.match(/^bearer (.*)$/iv);
-    if (m != null)
-        return m[1];
-    const m2 = req?.headers.cookie?.match(uaCookieNameRegex);
-    if (m2 != null)
-        return m2[1];
-}
-async function unifiedAuthenticateInternal(req) {
-    if (!hasInit)
-        init();
-    const token = tokenFromReq(req);
-    if (!token)
-        return undefined;
-    const payload = await tokenCache.get(token, req);
-    if (!payload)
-        return undefined;
-    if (payload.exp && payload.exp * 1000 <= Date.now())
-        return undefined;
-    await validateCache.get(token, payload);
-    return {
-        token,
-        issuerConfig: payload.iss ? issuerConfig.get(payload.iss) : undefined,
-        username: payload.sub,
-        sessionId: payload.sub + '-' + payload.iat,
-        sessionCreatedAt: payload.iat ? new Date(payload.iat * 1000) : undefined,
-        clientId: payload.client_id,
-        impersonatedBy: payload.act?.sub,
-        scope: payload.scope
-    };
-}
+/**
+ * @deprecated Use `jwtAuthenticate(options)` instead. Note the new shape: `jwtAuthenticate`
+ * is now a factory that takes options up front and returns the authenticator function
+ * (`authenticate: jwtAuthenticate({ authenticateAll: true })`), so the options actually
+ * take effect when wired into `new Server({ authenticate })`.
+ */
 export async function unifiedAuthenticate(req, options) {
-    const auth = await unifiedAuthenticateInternal(req);
-    if (options?.usingUaCookieRoutes) {
-        options.exceptRoutes ??= new Set();
-        options.exceptRoutes.add('/.uaService');
-        options.exceptRoutes.add('/.uaRedirect');
-        options.optionalRoutes ??= new Set();
-        options.optionalRoutes.add('/.uaLogout');
-    }
-    const isNoAuthenticationRoute = options?.exceptRoutes?.has(req.routeOptions.url);
-    const requiresAuthenticationRoute = options?.authenticateAll
-        && !options.exceptRoutes?.has(req.routeOptions.url)
-        && !options.optionalRoutes?.has(req.routeOptions.url);
-    if (requiresAuthenticationRoute && isBlank(auth?.username)) {
-        throw new Error('Request requires authentication.');
-    }
-    return isNoAuthenticationRoute ? undefined : auth;
+    return await jwtAuthenticate(options)(req);
 }
 /**
- * @deprecated Use unifiedAuthenticateWithOptions with { authenticateAll: true } instead.
+ * @deprecated Use `jwtAuthenticate({ authenticateAll: true })` instead.
  */
 export async function unifiedAuthenticateAll(req) {
-    return (await unifiedAuthenticate(req, { authenticateAll: true }));
+    return (await jwtAuthenticate({ authenticateAll: true })(req));
 }
 /**
  * This function is available for server-side view code instead of a client-side application
  * using a framework. It will automatically redirect the user to the Unified Auth login page
  * and return true if they are not authenticated. Otherwise it simply returns false.
  */
-export async function requireCookieAuth(req, res) {
+export async function requireCookieAuthUa(req, res) {
     if (isBlank(req.auth?.username)) {
         const loginUrl = new URL(process.env.UA_URL + '/login');
-        loginUrl.searchParams.set('clientId', process.env.UA_CLIENTID);
+        loginUrl.searchParams.set('clientId', (process.env.UA_COOKIE_CLIENTID ?? process.env.UA_CLIENTID));
         loginUrl.searchParams.set('returnUrl', uaServiceUrl(req));
         loginUrl.searchParams.set('requestedUrl', req.originalUrl);
         void res.redirect(loginUrl.toString());
@@ -180,7 +37,16 @@ export async function requireCookieAuth(req, res) {
         return false;
     }
 }
+/**
+ * @deprecated Use requireCookieAuthUa instead.
+ */
+export async function requireCookieAuth(req, res) {
+    return await requireCookieAuthUa(req, res);
+}
 export function registerUaCookieRoutes(app) {
+    registeredExceptRoutes.add('/.uaService');
+    registeredExceptRoutes.add('/.uaRedirect');
+    registeredOptionalRoutes.add('/.uaLogout');
     app.get('/.uaLogout', {
         schema: {
             headers: {
@@ -262,8 +128,8 @@ export function registerUaCookieRoutes(app) {
         }
         const loginUrl = isNotBlank(process.env.UA_URL)
             ? new URL(process.env.UA_URL + '/login')
-            : new URL('login', issuerConfig.get('unified-auth')?.url);
-        loginUrl.searchParams.set('clientId', process.env.UA_CLIENTID ?? process.env.JWT_TRUSTED_CLIENTIDS.split(',')[0]);
+            : new URL('login', getIssuerConfig('unified-auth')?.url);
+        loginUrl.searchParams.set('clientId', process.env.UA_COOKIE_CLIENTID ?? process.env.UA_CLIENTID ?? process.env.JWT_TRUSTED_CLIENTIDS.split(',')[0]);
         const returnUrl = uaServiceUrl(req);
         loginUrl.searchParams.set('returnUrl', returnUrl);
         if (req.query.requestedUrl)