fastify-txstate 3.6.9 → 4.0.1

package/lib/jwt-auth.js

@@ -0,0 +1,491 @@
+import { createCipheriv, createDecipheriv, createHash, createPublicKey, createSecretKey, randomBytes } from 'node:crypto';
+import { createRemoteJWKSet, decodeJwt, importJWK, jwtVerify } from 'jose';
+import { Cache, isBlank, isNotBlank, toArray } from 'txstate-utils';
+// Cookie names are owned here; oauth.ts and unified-auth.ts import them so the random
+// fallbacks don't drift between modules in deployments that don't set the env vars.
+export const oauthCookieName = process.env.OAUTH_COOKIE_NAME ?? randomBytes(16).toString('hex');
+export const refreshCookieName = oauthCookieName + '_rt';
+export const accessTokenCookieName = oauthCookieName + '_at';
+export const uaCookieName = process.env.UA_COOKIE_NAME ?? randomBytes(16).toString('hex');
+const oauthCookieRegex = new RegExp(`${oauthCookieName}=([^;]+)`, 'v');
+const refreshCookieRegex = new RegExp(`${refreshCookieName}=([^;]+)`, 'v');
+const accessTokenCookieRegex = new RegExp(`${accessTokenCookieName}=([^;]+)`, 'v');
+const uaCookieRegex = new RegExp(`${uaCookieName}=([^;]+)`, 'v');
+let cookieEncryptionKey;
+if (isNotBlank(process.env.OAUTH_COOKIE_SECRET)) {
+    cookieEncryptionKey = createHash('sha256').update(process.env.OAUTH_COOKIE_SECRET).digest();
+}
+export 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');
+}
+export 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;
+    }
+}
+let hasInit = false;
+const issuerConfigByIss = new Map();
+const verifyKeyByIss = new Map();
+const issuerInternalUrls = new Map();
+function inferType(config) {
+    if (config.type)
+        return config.type;
+    if (config.iss === 'unified-auth')
+        return 'unified-auth';
+    if (isNotBlank(config.secret))
+        return 'secret';
+    if (isNotBlank(config.publicKey))
+        return 'publicKey';
+    if (isNotBlank(config.url))
+        return 'jwks';
+    throw new Error(`Could not infer type for JWT issuer ${config.iss}. Set "type" explicitly or provide one of url/publicKey/secret.`);
+}
+export function toInternalUrl(url) {
+    for (const [external, internal] of issuerInternalUrls) {
+        if (url.startsWith(external))
+            return internal + url.slice(external.length);
+    }
+    return url;
+}
+export function getOAuthIssuerUrls() {
+    init();
+    const urls = [];
+    for (const config of issuerConfigByIss.values()) {
+        if (config.type === 'oauth' && config.url)
+            urls.push(config.url);
+    }
+    return urls;
+}
+export function getIssuerConfig(iss) {
+    init();
+    const config = issuerConfigByIss.get(iss);
+    if (!config)
+        return undefined;
+    return {
+        iss: config.iss,
+        url: config.url,
+        validateUrl: config.validateUrl,
+        logoutUrl: config.logoutUrl
+    };
+}
+export async function getOAuthDiscovery(issuerUrl) {
+    init();
+    return await discoveryCache.get(issuerUrl);
+}
+const jwksRemoteCache = new Cache(async (jwksUri) => createRemoteJWKSet(new URL(toInternalUrl(jwksUri))), { freshseconds: 3600 });
+const uaJwkCache = new Cache(async (url) => {
+    const { keys } = await (await fetch(toInternalUrl(url))).json();
+    const map = {};
+    for (const jwk of keys) {
+        if (jwk.kid)
+            map[jwk.kid] = await importJWK(jwk);
+    }
+    return map;
+});
+function uaRemoteJWKSet(url) {
+    return async (header) => {
+        const map = await uaJwkCache.get(url);
+        return map[header.kid];
+    };
+}
+const discoveryCache = new Cache(async (issuerUrl) => {
+    const base = issuerUrl.endsWith('/') ? issuerUrl : issuerUrl + '/';
+    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 });
+function buildLogoutUrl(config, type) {
+    if (isNotBlank(config.logoutUrl)) {
+        return config.url ? new URL(config.logoutUrl, config.url) : new URL(config.logoutUrl);
+    }
+    if (type === 'unified-auth') {
+        if (isNotBlank(process.env.UA_URL))
+            return new URL(process.env.UA_URL + '/logout');
+        if (config.url)
+            return new URL('logout', config.url);
+    }
+    return undefined;
+}
+function csvEnv(value) {
+    return value?.split(',').map(s => s.trim()).filter(isNotBlank) ?? [];
+}
+function issuersFromEnv() {
+    const result = [];
+    if (isNotBlank(process.env.UA_URL)) {
+        result.push({
+            iss: 'unified-auth',
+            type: 'unified-auth',
+            url: process.env.UA_URL,
+            internalUrl: isNotBlank(process.env.UA_URL_INTERNAL) ? process.env.UA_URL_INTERNAL : undefined
+        });
+    }
+    if (isNotBlank(process.env.OAUTH_URLS)) {
+        const internalByExternal = new Map();
+        for (const pair of csvEnv(process.env.OAUTH_INTERNAL_URLS)) {
+            const eq = pair.indexOf('=');
+            if (eq > 0)
+                internalByExternal.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+        }
+        for (const url of csvEnv(process.env.OAUTH_URLS)) {
+            result.push({
+                iss: url,
+                type: 'oauth',
+                url,
+                internalUrl: internalByExternal.get(url)
+            });
+        }
+    }
+    if (isNotBlank(process.env.JWT_SECRET)) {
+        result.push({
+            iss: 'jwt-secret',
+            type: 'secret',
+            secret: process.env.JWT_SECRET
+        });
+    }
+    if (isNotBlank(process.env.JWT_PUBLIC_KEY)) {
+        // accept PEM with literal \n escapes for env-var friendliness
+        result.push({
+            iss: 'jwt-public-key',
+            type: 'publicKey',
+            publicKey: process.env.JWT_PUBLIC_KEY.replace(/\\n/gv, '\n')
+        });
+    }
+    return result;
+}
+export function init() {
+    if (hasInit)
+        return;
+    hasInit = true;
+    const globalAudiences = csvEnv(process.env.JWT_TRUSTED_AUDIENCES);
+    const globalClientIds = csvEnv(process.env.JWT_TRUSTED_CLIENTIDS);
+    const jsonIssuers = process.env.JWT_TRUSTED_ISSUERS
+        ? toArray(JSON.parse(process.env.JWT_TRUSTED_ISSUERS))
+        : [];
+    // env-derived issuers first, then JSON-derived — JSON entries with the same iss override.
+    for (const issuer of [...issuersFromEnv(), ...jsonIssuers]) {
+        const type = inferType(issuer);
+        if (isNotBlank(issuer.url) && isNotBlank(issuer.internalUrl)) {
+            issuerInternalUrls.set(issuer.url, issuer.internalUrl);
+        }
+        switch (type) {
+            case 'unified-auth':
+                if (!issuer.url)
+                    throw new Error(`unified-auth issuer ${issuer.iss} requires url`);
+                verifyKeyByIss.set(issuer.iss, uaRemoteJWKSet(issuer.url));
+                break;
+            case 'oauth':
+                if (!issuer.url)
+                    throw new Error(`oauth issuer ${issuer.iss} requires url`);
+                // verify key resolved per request via discovery
+                break;
+            case 'jwks':
+                if (!issuer.url)
+                    throw new Error(`jwks issuer ${issuer.iss} requires url`);
+                verifyKeyByIss.set(issuer.iss, createRemoteJWKSet(new URL(toInternalUrl(issuer.url))));
+                break;
+            case 'publicKey':
+                if (!issuer.publicKey)
+                    throw new Error(`publicKey issuer ${issuer.iss} requires publicKey`);
+                verifyKeyByIss.set(issuer.iss, createPublicKey(issuer.publicKey));
+                break;
+            case 'secret':
+                if (!issuer.secret)
+                    throw new Error(`secret issuer ${issuer.iss} requires secret`);
+                verifyKeyByIss.set(issuer.iss, createSecretKey(Buffer.from(issuer.secret, 'ascii')));
+                break;
+        }
+        const validateUrl = type === 'unified-auth'
+            ? (isNotBlank(issuer.validateUrl) ? new URL(issuer.validateUrl, issuer.url) : new URL('validateToken', issuer.url))
+            : undefined;
+        const audiences = new Set([...(issuer.audiences ?? []), ...globalAudiences]);
+        const clientIds = new Set([...(issuer.clientIds ?? []), ...globalClientIds]);
+        issuerConfigByIss.set(issuer.iss, {
+            type,
+            iss: issuer.iss,
+            url: issuer.url,
+            validateUrl,
+            logoutUrl: buildLogoutUrl(issuer, type),
+            audiences: audiences.size ? audiences : undefined,
+            clientIds: clientIds.size ? clientIds : undefined
+        });
+    }
+}
+function checkAudience(aud, audiences, req) {
+    if (!audiences?.size)
+        return true;
+    // RFC 7519: a consumer accepts a token if it identifies itself in the aud claim, so
+    // any single trusted audience appearing in the token is sufficient — additional
+    // untrusted audiences alongside it do not cause rejection.
+    if (!toArray(aud).some(a => audiences.has(a))) {
+        req.log.warn(`Received token with untrusted audience: ${String(aud)}`);
+        return false;
+    }
+    return true;
+}
+function checkClientId(clientId, clientIds, req) {
+    if (!clientIds?.size)
+        return true;
+    if (!clientIds.has(clientId)) {
+        req.log.warn(`Received token with untrusted client_id: ${String(clientId)}`);
+        return false;
+    }
+    return true;
+}
+async function resolveVerifyKey(config) {
+    if (config.type === 'oauth') {
+        if (!config.url)
+            return undefined;
+        const discovery = await discoveryCache.get(config.url);
+        if (!discovery?.jwks_uri)
+            return undefined;
+        return { key: await jwksRemoteCache.get(discovery.jwks_uri), discovery };
+    }
+    const key = verifyKeyByIss.get(config.iss);
+    return key ? { key } : undefined;
+}
+const tokenCache = new Cache(async (token, req) => {
+    const claims = decodeJwt(token);
+    if (!claims.iss) {
+        req.log.warn('Received token without an issuer claim.');
+        return undefined;
+    }
+    const config = issuerConfigByIss.get(claims.iss);
+    if (!config) {
+        req.log.warn(`Received token with untrusted issuer: ${claims.iss}`);
+        return undefined;
+    }
+    try {
+        const resolved = await resolveVerifyKey(config);
+        if (!resolved) {
+            req.log.warn(`Could not resolve verification key for issuer ${claims.iss}`);
+            return undefined;
+        }
+        const { payload } = await jwtVerify(token, resolved.key);
+        if (!checkAudience(payload.aud, config.audiences, req))
+            return undefined;
+        if (!checkClientId(payload.client_id, config.clientIds, req))
+            return undefined;
+        return { payload, config, discovery: resolved.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 });
+const validateCache = new Cache(async (token, payload) => {
+    const config = payload.iss ? issuerConfigByIss.get(payload.iss) : undefined;
+    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(Date.now() - 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.');
+});
+async function tryRefresh(req, expiredIss) {
+    const m = req.headers.cookie?.match(refreshCookieRegex);
+    if (!m)
+        return undefined;
+    const refreshToken = unwrapRefreshToken(m[1]);
+    if (!refreshToken)
+        return undefined;
+    const clientId = process.env.OAUTH_COOKIE_CLIENT_ID;
+    if (!clientId)
+        return undefined;
+    const candidate = (expiredIss && issuerConfigByIss.get(expiredIss)?.type === 'oauth')
+        ? issuerConfigByIss.get(expiredIss)
+        : [...issuerConfigByIss.values()].find(c => c.type === 'oauth');
+    if (!candidate?.url)
+        return undefined;
+    const discovery = await discoveryCache.get(candidate.url);
+    if (!discovery?.token_endpoint)
+        return undefined;
+    const body = {
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: clientId
+    };
+    const clientSecret = process.env.OAUTH_COOKIE_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;
+        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`);
+        }
+        if (tokens.refresh_token) {
+            req.pendingOAuthCookies.push(`${refreshCookieName}=${wrapRefreshToken(tokens.refresh_token)}; Path=/; Secure; HttpOnly; SameSite=Lax`);
+        }
+        const cached = await tokenCache.get(tokens.id_token, req);
+        if (!cached)
+            return undefined;
+        if (cached.payload.exp && cached.payload.exp * 1000 <= Date.now())
+            return undefined;
+        return { token: tokens.id_token, payload: cached.payload, config: cached.config, discovery: cached.discovery };
+    }
+    catch (e) {
+        req.log.error(e);
+        return undefined;
+    }
+}
+function tokenFromReq(req) {
+    const m = req.headers.authorization?.match(/^bearer (.*)$/iv);
+    if (m)
+        return m[1];
+    const oauthM = req.headers.cookie?.match(oauthCookieRegex);
+    if (oauthM)
+        return oauthM[1];
+    const uaM = req.headers.cookie?.match(uaCookieRegex);
+    if (uaM)
+        return uaM[1];
+}
+function accessTokenFromReq(req) {
+    const m = req.headers.cookie?.match(accessTokenCookieRegex);
+    if (!m)
+        return undefined;
+    return unwrapRefreshToken(m[1]);
+}
+function authIssuerConfig(config, discovery) {
+    const logoutUrl = config.type === 'oauth' && isNotBlank(discovery?.end_session_endpoint)
+        ? new URL(discovery.end_session_endpoint)
+        : config.logoutUrl;
+    return {
+        iss: config.iss,
+        url: config.url,
+        validateUrl: config.validateUrl,
+        logoutUrl
+    };
+}
+function buildAuthInfo(result, extraClaims) {
+    const { token, payload, config, discovery } = result;
+    return {
+        ...extraClaims?.(payload),
+        token,
+        issuerConfig: authIssuerConfig(config, discovery),
+        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 jwtAuthenticateInternal(req, extraClaims) {
+    init();
+    const token = tokenFromReq(req);
+    if (!token)
+        return undefined;
+    let result;
+    const cached = await tokenCache.get(token, req);
+    if (!cached) {
+        // jwtVerify rejects expired tokens — try a refresh if we have a refresh-token cookie
+        try {
+            const { iss } = decodeJwt(token);
+            result = await tryRefresh(req, iss ?? undefined);
+        }
+        catch { /* not a JWT */ }
+    }
+    else if (cached.payload.exp && cached.payload.exp * 1000 <= Date.now()) {
+        // belt-and-suspenders: catch tokens that expired between cache and now
+        result = await tryRefresh(req, cached.payload.iss);
+    }
+    else {
+        result = { token, payload: cached.payload, config: cached.config, discovery: cached.discovery };
+    }
+    if (!result)
+        return undefined;
+    await validateCache.get(result.token, result.payload);
+    const authInfo = buildAuthInfo(result, extraClaims);
+    authInfo.accessToken = accessTokenFromReq(req);
+    return authInfo;
+}
+// Routes contributed by registerOAuthCookieRoutes / registerUaCookieRoutes. The
+// authenticator returned by jwtAuthenticate consults these at request time so that
+// registration order (factory vs. route registration) doesn't matter.
+export const registeredExceptRoutes = new Set();
+export const registeredOptionalRoutes = new Set();
+/**
+ * Build an `authenticate` function that validates JWTs from the Authorization Bearer
+ * header or a session cookie. Supports any mix of issuer types via the
+ * JWT_TRUSTED_ISSUERS env var:
+ *
+ *   - 'oauth'         — OAuth/OIDC provider with .well-known auto-discovery
+ *   - 'jwks'          — JWKS endpoint URL (no discovery)
+ *   - 'unified-auth'  — TxState Unified Auth (JWKS + /validateToken poll for deauth)
+ *   - 'publicKey'     — PEM-encoded asymmetric public key
+ *   - 'secret'        — symmetric HMAC secret
+ *
+ * Usage:
+ *   new Server({ authenticate: jwtAuthenticate({ authenticateAll: true }) })
+ *
+ * Or with no options:
+ *   new Server({ authenticate: jwtAuthenticate() })
+ *
+ * Calling `registerOAuthCookieRoutes` or `registerUaCookieRoutes` automatically excludes
+ * their callback/redirect routes from authentication requirements and marks their logout
+ * routes as optional, so you do not need to configure that here.
+ *
+ * If a refresh-token cookie is present (set by registerOAuthCookieRoutes) and the access
+ * token has expired, the returned authenticator transparently exchanges the refresh
+ * token for a new access token and queues the replacement cookies on
+ * `req.pendingOAuthCookies`. The onSend hook installed by registerOAuthCookieRoutes
+ * flushes those cookies onto the response.
+ */
+export function jwtAuthenticate(options) {
+    const exceptRoutes = new Set(options?.exceptRoutes);
+    const optionalRoutes = new Set(options?.optionalRoutes);
+    return async (req) => {
+        const url = req.routeOptions.url;
+        if (exceptRoutes.has(url) || registeredExceptRoutes.has(url))
+            return undefined;
+        const auth = await jwtAuthenticateInternal(req, options?.extraClaims);
+        if (options?.authenticateAll && !optionalRoutes.has(url) && !registeredOptionalRoutes.has(url) && isBlank(auth?.username)) {
+            throw new Error('Request requires authentication.');
+        }
+        return auth;
+    };
+}

package/lib/oauth.d.ts

@@ -0,0 +1,49 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type FastifyInstanceTyped } from './server.ts';
+export interface IssuerChoice {
+    issuerUrl: string;
+    redirectHref: string;
+}
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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 declare function registerOAuthCookieRoutes(app: FastifyInstanceTyped, options?: {
+    /** Scopes to always include in the authorization request, merged with any scopes
+     *  the client passes via the `scope` query parameter. */
+    scopes?: string[];
+    /** When multiple issuers are configured and the client doesn't specify one,
+     *  this function is called to render a login selection page. It receives an array
+     *  of issuer URLs with their corresponding redirect hrefs and should return an HTML
+     *  string. If not provided, the first trusted issuer is used. */
+    loginPage?: (issuers: IssuerChoice[]) => string;
+}): void;
+/**
+ * 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 declare function requireCookieAuthOAuth(req: FastifyRequest, res: FastifyReply): Promise<boolean>;