fastify-txstate 3.6.9 → 4.0.1

package/lib/oauth.js

@@ -0,0 +1,272 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { decodeJwt } from 'jose';
+import { htmlEncode, isBlank, isNotBlank } from 'txstate-utils';
+import { apiBaseUrl, uiBaseUrl } from "./server.js";
+import { accessTokenCookieName, getOAuthDiscovery, getOAuthIssuerUrls, init, oauthCookieName, refreshCookieName, registeredExceptRoutes, registeredOptionalRoutes, toInternalUrl, wrapRefreshToken } from "./jwt-auth.js";
+/**
+ * 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 function registerOAuthCookieRoutes(app, options) {
+    const clientId = process.env.OAUTH_COOKIE_CLIENT_ID;
+    if (!clientId)
+        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 queued during token refresh by jwtAuthenticate
+    app.addHook('onSend', async (req, res) => {
+        if (req.pendingOAuthCookies?.length) {
+            for (const cookie of req.pendingOAuthCookies)
+                void res.header('Set-Cookie', cookie);
+        }
+    });
+    app.get('/.oauthRedirect', {
+        schema: {
+            querystring: {
+                type: 'object',
+                properties: {
+                    requestedUrl: { type: 'string', format: 'uri' },
+                    scope: { type: 'string' },
+                    issuer: { type: 'string', format: 'uri' }
+                },
+                required: ['requestedUrl'],
+                additionalProperties: false
+            }
+        }
+    }, async (req, res) => {
+        if (req.originChecker && !req.originChecker.check(req.query.requestedUrl, req.hostname)) {
+            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 && 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)
+                    redirectUrl.searchParams.set('scope', req.query.scope);
+                redirectUrl.searchParams.set('issuer', iss);
+                return { issuerUrl: iss, redirectHref: redirectUrl.toString() };
+            });
+            void res.type('text/html');
+            return options.loginPage(issuers);
+        }
+        const issuerUrl = req.query.issuer && issuerUrls.includes(req.query.issuer)
+            ? req.query.issuer
+            : 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');
+        const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+        const redirectUri = apiBaseUrl(req) + callbackPath;
+        const authUrl = new URL(discovery.authorization_endpoint);
+        authUrl.searchParams.set('response_type', 'code');
+        authUrl.searchParams.set('client_id', clientId);
+        authUrl.searchParams.set('redirect_uri', redirectUri);
+        const isGoogle = discovery.authorization_endpoint.includes('accounts.google.com');
+        const scopeParts = new Set((req.query.scope ?? 'openid').split(' '));
+        for (const s of options?.scopes ?? [])
+            scopeParts.add(s);
+        if (!isGoogle && !req.query.scope)
+            scopeParts.add('offline_access');
+        authUrl.searchParams.set('scope', [...scopeParts].join(' '));
+        authUrl.searchParams.set('state', req.query.requestedUrl);
+        authUrl.searchParams.set('code_challenge', codeChallenge);
+        authUrl.searchParams.set('code_challenge_method', 'S256');
+        if (isGoogle) {
+            authUrl.searchParams.set('access_type', 'offline');
+            authUrl.searchParams.set('prompt', 'consent');
+        }
+        // store the code verifier and chosen issuer in short-lived HttpOnly cookies
+        void res.header('Set-Cookie', `${pkceVerifierCookieName}=${codeVerifier}; Path=${callbackPath}; Secure; HttpOnly; SameSite=Lax; Max-Age=600`);
+        void res.header('Set-Cookie', `${issuerCookieName}=${encodeURIComponent(issuerUrl)}; Path=${callbackPath}; Secure; HttpOnly; SameSite=Lax; Max-Age=600`);
+        return await res.redirect(authUrl.toString());
+    });
+    app.get(callbackPath, {
+        schema: {
+            querystring: {
+                type: 'object',
+                properties: {
+                    code: { type: 'string' },
+                    state: { type: 'string' }
+                },
+                required: ['code', 'state'],
+                additionalProperties: false
+            }
+        }
+    }, async (req, res) => {
+        const verifierMatch = req.headers.cookie?.match(pkceVerifierCookieRegex);
+        if (!verifierMatch) {
+            void res.status(403);
+            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]) : 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;
+        const body = {
+            grant_type: 'authorization_code',
+            code: req.query.code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: codeVerifier
+        };
+        if (clientSecret)
+            body.client_secret = clientSecret;
+        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) {
+            req.log.error(`OAuth token exchange failed: ${tokenResp.status} ${await tokenResp.text()}`);
+            void res.status(502);
+            return 'OAuth token exchange failed.';
+        }
+        const tokens = await tokenResp.json();
+        // prefer id_token, fall back to access_token if it's a JWT (some providers
+        // like Okta and Microsoft issue JWT access tokens)
+        let sessionToken = tokens.id_token;
+        if (!sessionToken && tokens.access_token) {
+            try {
+                decodeJwt(tokens.access_token);
+                sessionToken = tokens.access_token;
+            }
+            catch { /* not a JWT, can't use it */ }
+        }
+        if (!sessionToken) {
+            req.log.error('OAuth token response did not include a usable JWT (no id_token and access_token is not a JWT).');
+            void res.status(502);
+            return 'OAuth provider did not return a usable JWT.';
+        }
+        const destination = isNotBlank(req.query.state) ? req.query.state : uiBaseUrl(req);
+        const cookies = [
+            `${oauthCookieName}=${sessionToken}; Path=/; Secure; HttpOnly; SameSite=Lax`,
+            `${pkceVerifierCookieName}=; Path=${callbackPath}; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT`,
+            `${issuerCookieName}=; Path=${callbackPath}; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT`
+        ];
+        if (tokens.access_token) {
+            cookies.push(`${accessTokenCookieName}=${wrapRefreshToken(tokens.access_token)}; Path=/; Secure; HttpOnly; SameSite=Lax`);
+        }
+        if (tokens.refresh_token) {
+            cookies.push(`${refreshCookieName}=${wrapRefreshToken(tokens.refresh_token)}; Path=/; Secure; HttpOnly; SameSite=Lax`);
+        }
+        for (const cookie of cookies)
+            void res.header('Set-Cookie', cookie);
+        void res.type('text/html');
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=${htmlEncode(destination)}">
+  <title>Logging in...</title>
+</head>
+<body>
+</body>
+</html>`;
+    });
+    app.get('/.oauthLogout', {
+        schema: {
+            querystring: {
+                type: 'object',
+                properties: {
+                    returnUrl: { type: 'string', format: 'uri' }
+                },
+                additionalProperties: false
+            },
+            headers: {
+                type: 'object',
+                properties: {
+                    cookie: { type: 'string', pattern: `${oauthCookieName}=[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+` }
+                },
+                required: ['cookie']
+            }
+        }
+    }, async (req, res) => {
+        if (req.query.returnUrl && req.originChecker && !req.originChecker.check(req.query.returnUrl, req.hostname)) {
+            void res.status(403);
+            return 'Return URL failed origin check.';
+        }
+        const postLogoutDestination = req.query.returnUrl ?? uiBaseUrl(req);
+        let redirectUrl = postLogoutDestination;
+        if (req.auth?.issuerConfig?.logoutUrl) {
+            const logoutUrl = new URL(req.auth.issuerConfig.logoutUrl);
+            if (isNotBlank(req.auth.token))
+                logoutUrl.searchParams.set('id_token_hint', req.auth.token);
+            logoutUrl.searchParams.set('post_logout_redirect_uri', postLogoutDestination);
+            redirectUrl = logoutUrl.toString();
+        }
+        const cookies = [
+            `${oauthCookieName}=; Path=/; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT`,
+            `${accessTokenCookieName}=; Path=/; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT`,
+            `${refreshCookieName}=; Path=/; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT`
+        ];
+        for (const cookie of cookies)
+            void res.header('Set-Cookie', cookie);
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=${htmlEncode(redirectUrl)}">
+  <title>Logging out...</title>
+</head>
+<body>
+</body>
+</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/postformdata.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.postFormData = postFormData;
-const node_stream_1 = require("node:stream");
-const web_1 = require("node:stream/web");
-async function postFormData(url, fields, headers = {}) {
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
+export async function postFormData(url, fields, headers = {}) {
     const encoder = new TextEncoder();
     const boundary = `${Math.random().toString(36).substring(2, 15)}${Math.random().toString(36).substring(2, 15)}`;
     const footer = `--${boundary}--\r\n`;
@@ -18,7 +15,7 @@ async function postFormData(url, fields, headers = {}) {
     }
     let i = 0;
     let part = 'header';
-    const stream = new web_1.ReadableStream({
+    const stream = new ReadableStream({
         async pull(controller) {
             if (i === chunks.length) {
                 controller.enqueue(encoder.encode(footer));
@@ -31,27 +28,26 @@ async function postFormData(url, fields, headers = {}) {
                     part = 'content';
                 }
                 else if (part === 'content') {
-                    const { value, done } = await chunk.contentReader.read();
-                    if (done)
+                    const result = await chunk.contentReader.read();
+                    if (result.done)
                         part = 'footer';
                     else
-                        controller.enqueue(value);
+                        controller.enqueue(result.value);
                 }
-                else if (part === 'footer') {
+                else {
                     controller.enqueue(encoder.encode(chunk.footer));
-                    i++;
+                    i += 1;
                     part = 'header';
                 }
             }
         },
         cancel() {
             for (const chunk of chunks) {
-                if (chunk.contentReader.cancel) {
-                    chunk.contentReader.cancel();
-                }
+                void chunk.contentReader.cancel();
             }
         }
     });
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- duplex and node ReadableStream aren't in standard RequestInit types
     return await fetch(url, {
         method: 'POST',
         headers,
@@ -74,12 +70,12 @@ class FormDataChunk {
         if (isFileField(field)) {
             this.header += `; filename="${field.filename ?? field.name}"\r\nContent-Type: ${field.filetype ?? 'application/octet-stream'}`;
             this.contentsize = field.filesize;
-            this.contentReader = (field.value instanceof node_stream_1.Readable ? web_1.ReadableStream.from(field.value) : field.value).getReader();
+            this.contentReader = (field.value instanceof Readable ? ReadableStream.from(field.value) : field.value).getReader();
         }
         else {
             const encoded = encoder.encode(field.value);
             this.contentsize = encoded.length;
-            this.contentReader = new web_1.ReadableStream({
+            this.contentReader = new ReadableStream({
                 start: controller => {
                     controller.enqueue(encoded);
                     controller.close();

package/{lib-esm/index.d.ts → lib/server.d.ts}

@@ -1,12 +1,22 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import { type FastifyDynamicSwaggerOptions } from '@fastify/swagger';
 import { type FastifySwaggerUiOptions } from '@fastify/swagger-ui';
 import type { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts';
-import { type FastifyInstance, type FastifyRequest, type FastifyReply, type FastifyServerOptions, type FastifyLoggerOptions, type FastifyBaseLogger, type RawServerDefault } from 'fastify';
+import { type FastifyInstance, type FastifyRequest, type FastifyReply, type FastifyServerOptions, type FastifyBaseLogger, type RawServerDefault } from 'fastify';
+import pino from 'pino';
 import http from 'node:http';
 import type http2 from 'node:http2';
 type ErrorHandler = (error: Error, req: FastifyRequest, res: FastifyReply) => Promise<void>;
+/**
+ * Get the base URL for this API. Uses PUBLIC_URL if set, otherwise derives
+ * from the request's protocol and hostname.
+ */
+export declare function apiBaseUrl(req: FastifyRequest): string;
+/**
+ * Get the base URL for the UI that this API serves. Uses UI_URL if set,
+ * otherwise assumes the API lives at a subpath (e.g. /api) and the UI is
+ * one level up. Falls back to the API base URL if there's no parent path.
+ */
+export declare function uiBaseUrl(req: FastifyRequest): string;
 export interface FastifyTxStateAuthInfo {
     /**
      * The primary identifier for the user that is making the request, after processing
@@ -27,6 +37,13 @@ export interface FastifyTxStateAuthInfo {
      * If all else fails, you can sha256 the session token with a salt.
      */
     sessionId: string;
+    /**
+     * The date that the session was created, if available. This is useful for considering
+     * tokens before a certain date as invalid. For instance, if you want a logout action
+     * to invalidate all tokens created until that point, you can compare this field against
+     * the last time they logged out.
+     */
+    sessionCreatedAt?: Date;
     /**
      * Some authentication systems allow administrators to impersonate regular users, so that
      * they can see what that user sees and troubleshoot issues. We still want to log the administrator
@@ -45,6 +62,39 @@ export interface FastifyTxStateAuthInfo {
      * this field can help log requests that are authenticated with the other application's token.
      */
     clientId?: string;
+    /**
+     * A string that designates the current session as one that has limited authorization. The application will
+     * be responsible for checking this field and restricting appropriately.
+     *
+     * For example, a user who authenticated via non-standard mechanism might be given a scope of 'altlogin' and
+     * only a portion of the application's functionality would be available to them.
+     */
+    scope?: string;
+    /**
+     * The token or key that was used to authenticate the request. This is useful for
+     * making sub-requests to other APIs that can authenticate with the same token.
+     */
+    token: string;
+    /**
+     * The issuer configuration for the token, if applicable. This helps you generate
+     * a proper logout url in multi-issuer environments.
+     */
+    issuerConfig?: IssuerConfig;
+    /**
+     * The OAuth access token, if available. This is useful when your API needs to make
+     * requests to the provider's APIs on behalf of the user (e.g. Google Drive, Microsoft
+     * Graph). Only populated when using cookie-based OAuth with a provider that returns
+     * an access token during the code exchange.
+     */
+    accessToken?: string;
+}
+export interface IssuerConfig {
+    iss: string;
+    url?: string;
+    publicKey?: string;
+    secret?: string;
+    validateUrl?: URL;
+    logoutUrl?: URL;
 }
 export interface FastifyTxStateOptions extends Partial<FastifyServerOptions> {
     https?: http2.SecureServerOptions;
@@ -82,39 +132,24 @@ export interface FastifyTxStateOptions extends Partial<FastifyServerOptions> {
 declare module 'fastify' {
     interface FastifyRequest {
         auth?: FastifyTxStateAuthInfo;
+        originChecker?: OriginChecker;
     }
     interface FastifyReply {
         extraLogInfo: any;
     }
 }
-export declare const devLogger: {
-    level: string;
-    info: (msg: any) => void;
-    error: {
-        (...data: any[]): void;
-        (message?: any, ...optionalParams: any[]): void;
-    };
-    debug: {
-        (...data: any[]): void;
-        (message?: any, ...optionalParams: any[]): void;
-    };
-    fatal: {
-        (...data: any[]): void;
-        (message?: any, ...optionalParams: any[]): void;
-    };
-    warn: {
-        (...data: any[]): void;
-        (message?: any, ...optionalParams: any[]): void;
-    };
-    trace: {
-        (...data: any[]): void;
-        (message?: any, ...optionalParams: any[]): void;
-    };
-    silent: (msg: any) => void;
-    child(bindings: any, options?: any): any;
-};
-export declare const prodLogger: FastifyLoggerOptions;
-export type FastifyInstanceTyped = FastifyInstance<RawServerDefault, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, FastifyBaseLogger, JsonSchemaToTsProvider>;
+export declare const devLogger: pino.Logger<never, boolean>;
+export declare const prodLogger: pino.Logger<never, boolean>;
+export type FastifyInstanceTyped = FastifyInstance<RawServerDefault, http.IncomingMessage, http.ServerResponse, FastifyBaseLogger, JsonSchemaToTsProvider>;
+export declare class OriginChecker {
+    protected validOrigins: Record<string, boolean>;
+    protected validOriginHosts: Record<string, boolean>;
+    protected validOriginSuffixes: Set<string>;
+    setValidOrigins(origins: string[]): void;
+    setValidOriginHosts(hosts: string[]): void;
+    setValidOriginSuffixes(suffixes: string[]): void;
+    check(hostname: string, requestHostname?: string): boolean;
+}
 export type TxServer = Server;
 export default class Server {
     protected config: FastifyTxStateOptions & {
@@ -129,9 +164,8 @@ export default class Server {
     } | undefined>;
     protected shuttingDown: boolean;
     protected sigHandler: (signal: any) => void;
-    protected validOrigins: Record<string, boolean>;
-    protected validOriginHosts: Record<string, boolean>;
-    protected validOriginSuffixes: Set<string>;
+    protected originChecker: OriginChecker;
+    protected swaggerEndpoint: string | undefined;
     app: FastifyInstanceTyped;
     constructor(config?: FastifyTxStateOptions & {
         http2?: true;
@@ -150,6 +184,4 @@ export default class Server {
     }): Promise<void>;
     close(softSeconds?: number): Promise<void>;
 }
-export * from './analytics';
-export * from './error';
-export * from './unified-auth';
+export {};