fastify-txstate 3.6.9 → 4.0.1

package/lib/index.js

@@ -1,422 +1,9 @@
-"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 "./jwt-auth.js";
+export * from "./unified-auth.js";
+export * from "./oauth.js";
+export * from "./postformdata.js";

package/lib/jwt-auth.d.ts

@@ -0,0 +1,98 @@
+import type { FastifyRequest } from 'fastify';
+import { type JWTPayload } from 'jose';
+import type { FastifyTxStateAuthInfo, IssuerConfig } from './server.ts';
+export interface OAuthDiscovery {
+    issuer: string;
+    jwks_uri: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    end_session_endpoint?: string;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        pendingOAuthCookies?: string[];
+    }
+}
+export declare const oauthCookieName: string;
+export declare const refreshCookieName: string;
+export declare const accessTokenCookieName: string;
+export declare const uaCookieName: string;
+export declare function wrapRefreshToken(token: string): string;
+export declare function unwrapRefreshToken(value: string): string | undefined;
+type JwtIssuerType = 'oauth' | 'jwks' | 'unified-auth' | 'publicKey' | 'secret';
+export interface JwtIssuerConfigRaw {
+    iss: string;
+    /** Explicitly set the issuer type. Optional — when omitted, the type is inferred:
+     *  iss === 'unified-auth' → 'unified-auth'; secret → 'secret'; publicKey → 'publicKey';
+     *  url → 'jwks'. Set type: 'oauth' to enable OAuth/OIDC auto-discovery via
+     *  .well-known/openid-configuration on the issuer URL. */
+    type?: JwtIssuerType;
+    /** Issuer URL. For 'oauth' this is the issuer (.well-known/openid-configuration is
+     *  fetched relative to it). For 'jwks' this is the JWKS endpoint directly. For
+     *  'unified-auth' this is the UA service URL. */
+    url?: string;
+    /** PEM-encoded public key (publicKey type). */
+    publicKey?: string;
+    /** Symmetric HMAC secret (secret type). */
+    secret?: string;
+    /** Override URL for the unified-auth /validateToken poll. Resolved relative to `url`. */
+    validateUrl?: string;
+    /** End-session URL surfaced as `req.auth.issuerConfig.logoutUrl`. For 'oauth' issuers
+     *  this is auto-discovered; set this only to override. Resolved relative to `url`. */
+    logoutUrl?: string;
+    /** Server-to-server URL prefix override for split-horizon DNS (e.g. talking to the
+     *  issuer over a docker-internal hostname while the browser uses the public URL). */
+    internalUrl?: string;
+    /** If set, only accept tokens whose `aud` claim contains one of these values. */
+    audiences?: string[];
+    /** If set, only accept tokens whose `client_id` claim matches one of these values. */
+    clientIds?: string[];
+}
+export declare function toInternalUrl(url: string): string;
+export declare function getOAuthIssuerUrls(): string[];
+export declare function getIssuerConfig(iss: string): IssuerConfig | undefined;
+export declare function getOAuthDiscovery(issuerUrl: string): Promise<OAuthDiscovery | undefined>;
+export declare function init(): void;
+export interface JwtAuthenticateOptions {
+    /** 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>;
+    /** Receives the full JWT payload and returns extra properties to merge into the auth object.
+     *  If you use this, set per-issuer `audiences` to prevent tokens from other applications
+     *  carrying unexpected authorization claims. */
+    extraClaims?: (payload: JWTPayload) => Record<string, unknown>;
+}
+export declare const registeredExceptRoutes: Set<string>;
+export declare const registeredOptionalRoutes: Set<string>;
+/**
+ * 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 declare function jwtAuthenticate(options?: JwtAuthenticateOptions): (req: FastifyRequest) => Promise<FastifyTxStateAuthInfo | undefined>;
+export {};