fastify-txstate 3.6.9 → 4.0.0

package/lib/index.js

@@ -1,422 +1,8 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.prodLogger = exports.devLogger = void 0;
-const ajv_1 = __importDefault(require("ajv"));
-const swagger_1 = __importDefault(require("@fastify/swagger"));
-const swagger_ui_1 = __importDefault(require("@fastify/swagger-ui"));
-const fastify_shared_1 = require("@txstate-mws/fastify-shared");
-const ajv_errors_1 = __importDefault(require("ajv-errors"));
-const ajv_formats_1 = __importDefault(require("ajv-formats"));
-const fastify_1 = require("fastify");
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_http_1 = __importDefault(require("node:http"));
-const txstate_utils_1 = require("txstate-utils");
-const error_1 = require("./error");
-exports.devLogger = {
-    level: 'info',
-    info: (msg) => { console.info(msg.req ? `${msg.req.method} ${msg.req.url}` : msg.res ? `${msg.res.statusCode} - ${msg.responseTime}` : msg); },
-    error: console.error,
-    debug: console.debug,
-    fatal: console.error,
-    warn: console.warn,
-    trace: console.trace,
-    silent: (msg) => { },
-    child(bindings, options) { return this; }
-};
-exports.prodLogger = {
-    level: 'info',
-    serializers: {
-        req(req) {
-            return {
-                method: req.method,
-                url: req.url.replace(/(token|unifiedJwt)=[\w.]+/i, '$1=redacted'),
-                remoteAddress: req.ip,
-                traceparent: req.headers.traceparent
-            };
-        },
-        res(res) {
-            return {
-                statusCode: res.statusCode,
-                url: res.request?.url.replace(/(token|unifiedJwt)=[\w.]+/i, '$1=redacted'),
-                length: Number((0, txstate_utils_1.toArray)(res.getHeader?.('content-length'))[0]),
-                ...res.extraLogInfo,
-                auth: (0, txstate_utils_1.omit)(res.request?.auth ?? res.extraLogInfo?.auth ?? {}, 'token', 'issuerConfig')
-            };
-        }
-    }
-};
-class Server {
-    config;
-    https = false;
-    errorHandlers = [];
-    healthMessage;
-    healthCallback;
-    shuttingDown = false;
-    sigHandler;
-    validOrigins = {};
-    validOriginHosts = {};
-    validOriginSuffixes = new Set();
-    swaggerEndpoint;
-    app;
-    constructor(config = {}) {
-        this.config = config;
-        try {
-            const key = node_fs_1.default.readFileSync('/securekeys/private.key');
-            const cert = node_fs_1.default.readFileSync('/securekeys/cert.pem');
-            config.https = {
-                ...config.https,
-                allowHTTP1: true,
-                key,
-                cert,
-                minVersion: 'TLSv1.2'
-            };
-            config.http2 = true;
-            this.https = true;
-        }
-        catch (e) {
-            this.https = false;
-            delete config.https;
-        }
-        if (typeof config.logger === 'undefined') {
-            config.logger = process.env.NODE_ENV === 'development'
-                ? exports.devLogger
-                : exports.prodLogger;
-        }
-        if (process.env.TRUST_PROXY != null) {
-            if (['true', '1'].includes(process.env.TRUST_PROXY))
-                config.trustProxy = true;
-            else
-                config.trustProxy = process.env.TRUST_PROXY;
-        }
-        config.ajv = { ...config.ajv, plugins: [...(config.ajv?.plugins ?? []), ajv_errors_1.default, [ajv_formats_1.default, { mode: 'fast' }]], customOptions: { ...config.ajv?.customOptions, allErrors: true, strictSchema: false, coerceTypes: true } };
-        this.healthCallback = config.checkHealth;
-        this.app = (0, fastify_1.fastify)(config);
-        this.app.addHook('onRoute', route => {
-            if (!route.schema?.body)
-                return;
-            const missingResponse = route.schema?.response == null;
-            const response400 = (0, txstate_utils_1.set)(fastify_shared_1.validatedResponse.properties.messages, 'description', 'Basic validation failure. This means that the UI provided input that failed validation as defined in the openapi specification published by the API. The UI is at fault and should be re-coded to avoid sending invalid data.');
-            let newSchema = (0, txstate_utils_1.set)(route.schema ?? {}, 'response.400', response400);
-            const response422 = (0, txstate_utils_1.set)(fastify_shared_1.validatedResponse, 'description', 'Validation failure. This means that the user provided an invalid object. The user should be shown their error so that they can correct it.');
-            newSchema = (0, txstate_utils_1.set)(newSchema, 'response.422', response422);
-            if (missingResponse) {
-                newSchema.response['200'] = {
-                    description: 'Success. Return type has not been specified.',
-                    type: 'object'
-                };
-            }
-            route.schema = newSchema;
-        });
-        this.app.addHook('preValidation', (req, res, done) => {
-            if (req.body != null && req.routeOptions.schema?.body)
-                (0, txstate_utils_1.destroyNulls)(req.body);
-            done();
-        });
-        // use Ajv to validate responses instead of @fastify/json-fast-stringify since ajv does
-        // a better job with recursive types and we don't want to have different behavior between
-        // input and output validation
-        const ajv = new ajv_1.default(config.ajv.customOptions);
-        for (const pluginConfig of config.ajv.plugins ?? []) {
-            const [plugin, opts] = (0, txstate_utils_1.toArray)(pluginConfig);
-            plugin(ajv, opts);
-        }
-        this.app.setSerializerCompiler((route) => {
-            const schema = route.schema;
-            const validate = schema == null ? ajv.compile({ type: 'object' }) : ajv.compile(schema);
-            return data => {
-                /**
-                 * Ajv unfortunately treats optional properties as non-nullable, so they're allowed to
-                 * be undefined but not allowed to be null. Worse, with `coerceTypes`, null will be converted
-                 * to empty string or 0 or false. This is silly behavior, so we're converting all nulls to
-                 * undefined before we validate.
-                 */
-                if (schema != null)
-                    (0, txstate_utils_1.destroyNulls)((0, txstate_utils_1.stringifyDates)(data));
-                if (!validate(data))
-                    throw new Error('Output validation failed. ' + validate.errors?.[0].instancePath + ': ' + validate.errors?.[0].message);
-                return JSON.stringify(data);
-            };
-        });
-        this.app.addHook('onRequest', (req, res, done) => {
-            res.extraLogInfo = {};
-            done();
-        });
-        if (!config.skipOriginCheck && !process.env.SKIP_ORIGIN_CHECK) {
-            this.setValidOrigins([...(config.validOrigins ?? []), ...(process.env.VALID_ORIGINS?.split(',') ?? [])]);
-            this.setValidOriginHosts([...(config.validOriginHosts ?? []), ...(process.env.VALID_ORIGIN_HOSTS?.split(',') ?? [])]);
-            this.setValidOriginSuffixes([...(config.validOriginSuffixes ?? []), ...(process.env.VALID_ORIGIN_SUFFIXES?.split(',') ?? [])]);
-            this.app.addHook('onRequest', async (req, res) => {
-                if (!req.headers.origin)
-                    return;
-                let passed = this.validOrigins[req.headers.origin];
-                if (!passed && req.headers.origin === 'null')
-                    passed = process.env.NODE_ENV === 'development';
-                else if (!passed) {
-                    const parsedOrigin = new URL(req.headers.origin);
-                    if (req.hostname.replace(/:\d+$/, '') === parsedOrigin.hostname)
-                        passed = true;
-                    if (this.validOriginHosts[parsedOrigin.hostname])
-                        passed = true;
-                    if (!passed && this.validOriginSuffixes.size > 0) {
-                        const originParts = parsedOrigin.hostname.split('.');
-                        for (let i = 0; i < originParts.length; i++) {
-                            const suffix = originParts.slice(i).join('.');
-                            if (this.validOriginSuffixes.has(suffix))
-                                passed = true;
-                        }
-                    }
-                }
-                if (!passed && config.checkOrigin?.(req))
-                    passed = true;
-                if (!passed) {
-                    await res.status(403).send('Origin check failed. Suspected XSRF attack.');
-                    return res;
-                }
-                else {
-                    void res.header('Access-Control-Allow-Origin', req.headers.origin);
-                    void res.header('Access-Control-Max-Age', '600'); // ask browser to skip pre-flights for 10 minutes after a yes
-                    if (req.headers['access-control-request-method'])
-                        void res.header('access-control-allow-methods', req.headers['access-control-request-method']);
-                    if (req.headers['access-control-request-headers'])
-                        void res.header('Access-Control-Allow-Headers', req.headers['access-control-request-headers']);
-                }
-            });
-            this.app.options('*', async (req, res) => {
-                await res.send();
-            });
-        }
-        if (config.authenticate) {
-            const authenticatedMethods = {
-                GET: true,
-                POST: true,
-                PUT: true,
-                PATCH: true,
-                DELETE: true
-            };
-            this.app.addHook('onRequest', async (req, res) => {
-                if (!authenticatedMethods[req.method] || (0, txstate_utils_1.isBlank)(req.routeOptions.url) || req.routeOptions.url === '/health' || req.routeOptions.url === '/.uaService' || (this.swaggerEndpoint && req.routeOptions.url?.startsWith(this.swaggerEndpoint)))
-                    return;
-                try {
-                    req.auth = await config.authenticate(req);
-                }
-                catch (e) {
-                    await res.status(401).send('Failed to authenticate.');
-                    return res;
-                }
-            });
-        }
-        this.app.addHook('onSend', this.https && process.env.NODE_ENV !== 'development'
-            ? async (_, resp) => {
-                void resp.removeHeader('X-Powered-By');
-                void resp.header('Strict-Transport-Security', 'max-age=31536000');
-                if (resp.getHeader('content-type') === 'text/html')
-                    void resp.type('text/html; charset=utf-8');
-            }
-            : async (_, resp) => {
-                void resp.removeHeader('X-Powered-By');
-                if (resp.getHeader('content-type') === 'text/html')
-                    void resp.type('text/html; charset=utf-8');
-            });
-        this.app.setNotFoundHandler((req, res) => { void res.status(404).send('Not Found.'); });
-        this.app.setErrorHandler(async (err, req, res) => {
-            req.log.warn(err);
-            for (const errorHandler of this.errorHandlers) {
-                if (!res.sent)
-                    await errorHandler(err, req, res);
-            }
-            if (!res.sent) {
-                if (err instanceof error_1.FailedValidationError) {
-                    await res.status(err.statusCode).send(err.errors);
-                }
-                else if (err instanceof error_1.ValidationError) {
-                    await res.status(err.statusCode).send({ success: false, messages: [{ message: err.message, path: err.path, type: err.type ?? 'error' }] });
-                }
-                else if (err instanceof error_1.ValidationErrors) {
-                    await res.status(err.statusCode).send({ success: false, messages: err.errors });
-                }
-                else if (err instanceof error_1.HttpError) {
-                    await res.status(err.statusCode).send(err.message);
-                }
-                else if (err.code === 'FST_ERR_VALIDATION') {
-                    const developerErrors = [];
-                    const userErrors = [];
-                    for (const v of err.validation ?? []) {
-                        if (v.keyword === 'errorMessage') {
-                            for (const ov of v.params.errors) {
-                                if (['type', 'additionalProperties', 'minProperties'].includes(ov.keyword))
-                                    developerErrors.push({ ...ov, message: v.message });
-                                else if (ov.keyword === 'required')
-                                    userErrors.push({ ...ov, message: 'This field is required.' });
-                                else
-                                    userErrors.push({ ...ov, message: v.message });
-                            }
-                        }
-                        else {
-                            if (['type', 'additionalProperties', 'minProperties'].includes(v.keyword))
-                                developerErrors.push(v);
-                            else if (v.keyword === 'required')
-                                userErrors.push({ ...v, message: 'This field is required.' });
-                            else
-                                userErrors.push(v);
-                        }
-                    }
-                    if (userErrors.length)
-                        await res.status(422).send({ success: false, messages: userErrors.map(error_1.fstValidationToMessage) });
-                    else
-                        await res.status(400).send(developerErrors.map(error_1.fstValidationToMessage));
-                }
-                else if (err.statusCode) {
-                    await res.status(err.statusCode).send(new error_1.HttpError(err.statusCode).message);
-                }
-                else {
-                    await res.status(500).send('Internal Server Error.');
-                }
-            }
-        });
-        this.app.get('/health', { logLevel: 'warn' }, async (req, res) => {
-            if (this.shuttingDown) {
-                res.log.warn('Returning 503 on /health because we are shutting down/restarting.');
-                void res.status(503);
-                return 'MAINTENANCE';
-            }
-            else if (this.healthMessage) {
-                res.log.error(this.healthMessage);
-                void res.status(500);
-                return this.healthMessage;
-            }
-            else if (this.healthCallback) {
-                const resp = await this.healthCallback();
-                const [status, msg] = typeof resp === 'string' ? [500, resp] : [resp?.status, resp?.message];
-                if (!!msg || !!status) {
-                    res.log.error(resp, 'Health check callback failed.');
-                    void res.status(status ?? 500);
-                    return msg ?? 'FAIL';
-                }
-            }
-            return 'OK';
-        });
-        this.sigHandler = () => {
-            this.close().then(() => {
-                process.exit();
-            }).catch(e => { console.error(e); });
-        };
-        process.on('SIGTERM', this.sigHandler);
-        process.on('SIGINT', this.sigHandler);
-    }
-    async start(port) {
-        const customPort = port ?? parseInt(process.env.PORT ?? '0');
-        await this.app.ready();
-        this.app.swagger?.();
-        if (customPort) {
-            await this.app.listen({ port: customPort, host: '0.0.0.0' });
-        }
-        else if (this.https) {
-            // redirect 80 to 443
-            node_http_1.default.createServer((req, res) => {
-                res.writeHead(301, { Location: 'https://' + (req?.headers?.host?.replace(/:\d+$/, '') ?? '') + (req.url ?? '') });
-                res.end();
-            }).listen(80);
-            await this.app.listen({ port: 443, host: '0.0.0.0' });
-        }
-        else {
-            await this.app.listen({ port: 80, host: '0.0.0.0' });
-        }
-    }
-    addErrorHandler(handler) {
-        this.errorHandlers.push(handler);
-    }
-    setUnhealthy(message) {
-        this.healthMessage = message;
-    }
-    setHealthy() {
-        this.healthMessage = undefined;
-    }
-    setValidOrigins(origins) {
-        this.validOrigins = origins.reduce((validOrigins, origin) => ({ ...validOrigins, [origin]: true }), {});
-    }
-    setValidOriginHosts(hosts) {
-        this.validOriginHosts = hosts.reduce((validHosts, host) => ({ ...validHosts, [host]: true }), {});
-    }
-    setValidOriginSuffixes(suffixes) {
-        this.validOriginSuffixes.clear();
-        for (const s of suffixes)
-            this.validOriginSuffixes.add(s.replace(/^\./, ''));
-    }
-    async swagger(opts) {
-        let openapi = opts?.openapi ?? {};
-        if (this.config.authenticate != null) {
-            openapi = (0, txstate_utils_1.set)(openapi, 'components.securitySchemes', {
-                unifiedAuth: {
-                    type: 'http',
-                    scheme: 'bearer',
-                    bearerFormat: 'JWT',
-                    description: `Enter a token obtained from the TxState Unified Authentication service. An easy way to do
-this is log into this application and use dev tools to pull your token from the Authorization header.`
-                }
-            });
-            // Apply the security globally to all operations
-            openapi.security = [{ unifiedAuth: [] }];
-        }
-        function findRefs(obj, id) {
-            if (obj == null)
-                return undefined;
-            if (obj.$id?.length)
-                id = obj.$id;
-            if (obj.$ref === '#' && id?.length) {
-                obj.type = 'string';
-                obj.enum = [id];
-                delete obj.$ref;
-            }
-            else {
-                for (const val of Object.values(obj)) {
-                    if (typeof val === 'object' && !(val instanceof Date))
-                        findRefs(val, id);
-                }
-            }
-            return obj;
-        }
-        await this.app.register(swagger_1.default, {
-            openapi,
-            transform(transformArgs) {
-                const newSchema = findRefs((0, txstate_utils_1.clone)(transformArgs.schema));
-                return { ...transformArgs, schema: newSchema };
-            }
-        });
-        this.swaggerEndpoint = opts?.path ?? opts?.ui?.routePrefix ?? '/docs';
-        await this.app.register(swagger_ui_1.default, { ...opts?.ui, routePrefix: this.swaggerEndpoint });
-    }
-    async close(softSeconds) {
-        if (typeof softSeconds === 'undefined')
-            softSeconds = parseInt(process.env.LOAD_BALANCE_TIMEOUT ?? '0');
-        process.removeListener('SIGTERM', this.sigHandler);
-        process.removeListener('SIGINT', this.sigHandler);
-        if (softSeconds) {
-            this.shuttingDown = true;
-            await (0, txstate_utils_1.sleep)(softSeconds);
-        }
-        await this.app.close();
-    }
-}
-exports.default = Server;
-__exportStar(require("./analytics"), exports);
-__exportStar(require("./error"), exports);
-__exportStar(require("./filestorage"), exports);
-__exportStar(require("./unified-auth"), exports);
-__exportStar(require("./postformdata"), exports);
+export { default } from "./server.js";
+export * from "./server.js";
+export * from "./analytics.js";
+export * from "./error.js";
+export * from "./filestorage.js";
+export * from "./unified-auth.js";
+export * from "./oauth.js";
+export * from "./postformdata.js";

package/lib/oauth.d.ts

@@ -0,0 +1,71 @@
+import type { FastifyRequest } from 'fastify';
+import { type FastifyTxStateAuthInfo, type FastifyInstanceTyped } from './server.ts';
+declare module 'fastify' {
+    interface FastifyRequest {
+        pendingOAuthCookies?: string[];
+    }
+}
+/**
+ * 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.
+ *
+ * Expects JWT tokens (access tokens or ID tokens) in the Authorization Bearer header
+ * or in a cookie set by registerOAuthCookieRoutes.
+ *
+ * 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.
+ */
+export declare function oauthAuthenticate(req: FastifyRequest, options?: {
+    /** If true, all requests require authentication, except routes listed in exceptRoutes or optionalRoutes. */
+    authenticateAll?: boolean;
+    /** Routes that skip authentication entirely. They will not receive an auth object. */
+    exceptRoutes?: Set<string>;
+    /** Routes that do not require authentication, but will fill req.auth if a session is available. */
+    optionalRoutes?: Set<string>;
+    /** Set this true if you are using registerOAuthCookieRoutes and authenticateAll. */
+    usingOAuthCookieRoutes?: boolean;
+    /** Receives the full JWT payload and returns extra properties to merge into the auth object.
+     *  If you use this, you should also set OAUTH_TRUSTED_AUDIENCES to prevent tokens from
+     *  other applications carrying unexpected authorization claims. */
+    extraClaims?: (payload: Record<string, unknown>) => Record<string, unknown>;
+}): Promise<FastifyTxStateAuthInfo | undefined>;
+/**
+ * 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
+ * when it expires and the access token is available at `req.auth.accessToken` for calling
+ * provider APIs.
+ *
+ * Requires OAUTH_CLIENT_ID environment variable. OAUTH_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).
+ *
+ * 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 interface IssuerChoice {
+    issuerUrl: string;
+    redirectHref: string;
+}
+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;