fastify-txstate 3.1.9 → 3.2.1

package/lib/analytics.d.ts

@@ -0,0 +1,33 @@
+import { type InteractionEvent } from '@txstate-mws/fastify-shared';
+import type { FastifyBaseLogger, FastifyInstance } from 'fastify';
+import { type IBrowser, type IDevice, type IOS } from 'ua-parser-js';
+import { type FastifyTxStateAuthInfo } from '.';
+export interface StoredInteractionEvent extends InteractionEvent {
+    '@timestamp': string;
+    appName: string;
+    environment: string;
+    browser: IBrowser;
+    device: IDevice;
+    os: IOS;
+    user: {
+        remoteip: string;
+        ga?: string;
+    } & FastifyTxStateAuthInfo;
+}
+export declare class AnalyticsClient {
+    push(events: StoredInteractionEvent[]): Promise<void>;
+}
+export declare class LoggingAnalyticsClient extends AnalyticsClient {
+    protected logger: FastifyBaseLogger;
+    constructor(logger: FastifyBaseLogger);
+    push(events: StoredInteractionEvent[]): Promise<void>;
+}
+export declare class ElasticAnalyticsClient extends AnalyticsClient {
+    private readonly elasticClient;
+    constructor();
+    push(events: StoredInteractionEvent[]): Promise<void>;
+}
+export declare function analyticsPlugin(fastify: FastifyInstance, opts: {
+    appName: string;
+    analyticsClient?: AnalyticsClient;
+}, done: (err?: Error) => void): void;

package/lib/analytics.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyticsPlugin = exports.ElasticAnalyticsClient = exports.LoggingAnalyticsClient = exports.AnalyticsClient = void 0;
+const elasticsearch_1 = __importDefault(require("@elastic/elasticsearch"));
+const fastify_shared_1 = require("@txstate-mws/fastify-shared");
+const txstate_utils_1 = require("txstate-utils");
+const ua_parser_js_1 = require("ua-parser-js");
+class AnalyticsClient {
+    async push(events) {
+        for (const event of events)
+            console.info('analytics event:', JSON.stringify((0, txstate_utils_1.pick)(event, 'eventType', 'screen', 'action', 'target')));
+    }
+}
+exports.AnalyticsClient = AnalyticsClient;
+class LoggingAnalyticsClient extends AnalyticsClient {
+    constructor(logger) {
+        super();
+        this.logger = logger;
+    }
+    async push(events) {
+        for (const event of events)
+            this.logger.info({ analyticsEvent: event });
+    }
+}
+exports.LoggingAnalyticsClient = LoggingAnalyticsClient;
+class ElasticAnalyticsClient extends AnalyticsClient {
+    constructor() {
+        var _a, _b;
+        super();
+        this.elasticClient = new elasticsearch_1.default.Client({
+            node: process.env.ELASTICSEARCH_URL,
+            auth: {
+                username: (_a = process.env.ELASTICSEARCH_USER) !== null && _a !== void 0 ? _a : 'elastic',
+                password: (_b = process.env.ELASTICSEARCH_PASS) !== null && _b !== void 0 ? _b : 'not_provided'
+            }
+        });
+    }
+    async push(events) {
+        if (events.length)
+            await this.elasticClient.bulk({ body: events.reduce((acc, event) => { var _a; acc.push({ index: { _index: (_a = process.env.ELASTICSEARCH_USEREVENTS_INDEX) !== null && _a !== void 0 ? _a : 'interaction-analytics' } }, event); return acc; }, []) });
+    }
+}
+exports.ElasticAnalyticsClient = ElasticAnalyticsClient;
+function analyticsPlugin(fastify, opts, done) {
+    var _a;
+    const environment = process.env.NODE_ENV;
+    if ((0, txstate_utils_1.isBlank)(environment))
+        throw new Error('Must set NODE_ENV when reporting analytics.');
+    const eventQueue = [];
+    const analyticsClient = (_a = opts.analyticsClient) !== null && _a !== void 0 ? _a : ((0, txstate_utils_1.isBlank)(process.env.ELASTICSEARCH_URL)
+        ? environment === 'development'
+            ? new AnalyticsClient()
+            : new LoggingAnalyticsClient(fastify.log)
+        : new ElasticAnalyticsClient());
+    const UACache = new txstate_utils_1.Cache(async (ua) => {
+        const parser = new ua_parser_js_1.UAParser(ua);
+        return parser.getResult();
+    }, { freshseconds: 86400, staleseconds: 864000 });
+    async function flushQueue() {
+        const eventQueueSlice = [...eventQueue];
+        try {
+            eventQueue.length = 0;
+            const eventsToStore = [];
+            for (const queueItem of eventQueueSlice) {
+                const uaInfo = await UACache.get(queueItem.ua);
+                eventsToStore.push({
+                    ...queueItem.event,
+                    '@timestamp': queueItem.time,
+                    appName: opts.appName,
+                    environment,
+                    ...(0, txstate_utils_1.pick)(uaInfo, 'browser', 'device', 'os'),
+                    user: {
+                        remoteip: queueItem.remoteIp,
+                        ga: queueItem.gaCookie,
+                        ...queueItem.auth
+                    }
+                });
+            }
+            if (eventsToStore.length)
+                await analyticsClient.push(eventsToStore);
+        }
+        catch (e) {
+            eventQueue.push(...eventQueueSlice);
+            console.error(e);
+        }
+        finally {
+            setTimeout(() => { void flushQueue(); }, 5000);
+        }
+    }
+    setTimeout(() => { void flushQueue(); }, 5000);
+    function queueEvents(auth, headers, remoteIp, events) {
+        var _a, _b, _c;
+        for (const event of events) {
+            eventQueue.push({
+                event,
+                remoteIp,
+                ua: (_a = headers['user-agent']) !== null && _a !== void 0 ? _a : '',
+                time: new Date().toISOString(),
+                gaCookie: (_c = (_b = headers.cookie) === null || _b === void 0 ? void 0 : _b.replace(/^.*?(?:_ga=([^;]+))?.*$/, '$1')) !== null && _c !== void 0 ? _c : '',
+                auth
+            });
+        }
+    }
+    fastify.post('/analytics', { schema: { body: { type: 'array', items: fastify_shared_1.interactionEvent }, response: { 202: { type: 'string', enum: ['OK'] } } } }, async (req, res) => {
+        const { auth } = req;
+        queueEvents(auth !== null && auth !== void 0 ? auth : { username: 'unauthenticated' }, req.headers, req.ip, req.body);
+        res.statusCode = 202;
+        return 'OK';
+    });
+    done();
+}
+exports.analyticsPlugin = analyticsPlugin;

package/lib/error.d.ts

@@ -0,0 +1,10 @@
+export declare class HttpError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message?: string);
+}
+type ValidationErrors = Record<string, string[]>;
+export declare class FailedValidationError extends HttpError {
+    errors: ValidationErrors;
+    constructor(errors: ValidationErrors);
+}
+export {};

package/lib/error.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FailedValidationError = exports.HttpError = void 0;
+const http_status_codes_1 = require("http-status-codes");
+class HttpError extends Error {
+    constructor(statusCode, message) {
+        if (!message) {
+            if (statusCode === 401)
+                message = 'Authentication is required.';
+            else if (statusCode === 403)
+                message = 'You are not authorized for that.';
+            else
+                message = (0, http_status_codes_1.getReasonPhrase)(statusCode);
+        }
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+exports.HttpError = HttpError;
+class FailedValidationError extends HttpError {
+    constructor(errors) {
+        super(422, 'Validation failure.');
+        this.errors = errors;
+    }
+}
+exports.FailedValidationError = FailedValidationError;

package/lib/index.d.ts

@@ -0,0 +1,153 @@
+/// <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 http from 'node:http';
+import type http2 from 'node:http2';
+type ErrorHandler = (error: Error, req: FastifyRequest, res: FastifyReply) => Promise<void>;
+export interface FastifyTxStateAuthInfo {
+    /**
+     * The primary identifier for the user that is making the request, after processing
+     * their session token / JWT.
+     */
+    username: string;
+    /**
+     * This should be an identifier for the particular session, so that the same user
+     * on different devices/browsers/tabs can be distinguished from one another.
+     *
+     * It should NOT be usable as a cookie or bearer token, as it will appear in logs. If you
+     * use JSON Web Tokens, an easy thing is to combine the username with the `iat` issued
+     * date to create something unique but not useful to attackers.
+     *
+     * For lookup tokens, you can do the same `${username}-${createdAt}` after looking up
+     * the session in your database.
+     *
+     * If all else fails, you can sha256 the session token with a salt.
+     */
+    sessionId: string;
+    /**
+     * 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
+     * with any actions they take while impersonating someone, for auditing purposes, so you should
+     * fill this field when applicable.
+     *
+     * This will also be available at `req.auth.impersonatedBy`, so it is possible for your API
+     * to implement complicated authorization rules based on whether a user is being impersonated.
+     * It sort of defeats the purpose of impersonation, but used sparingly it could prevent administrators
+     * from making mistakes.
+     */
+    impersonatedBy?: string;
+    /**
+     * If your API may be accessed by a different client application, such that the user is actually logged
+     * into that application instead of yours, but you accept that application's session tokens, filling
+     * this field can help log requests that are authenticated with the other application's token.
+     */
+    clientId?: string;
+}
+export interface FastifyTxStateOptions extends Partial<FastifyServerOptions> {
+    https?: http2.SecureServerOptions;
+    validOrigins?: string[];
+    validOriginHosts?: string[];
+    validOriginSuffixes?: string[];
+    skipOriginCheck?: boolean;
+    checkOrigin?: (req: FastifyRequest) => boolean;
+    /**
+     * Run an asynchronous function to check the health of the service.
+     *
+     * Return a non-empty error message to trigger unhealthy status.
+     *
+     * Setting a health message with setUnhealthy will override this and prevent it from being executed.
+     */
+    checkHealth?: () => Promise<string | {
+        status?: number;
+        message?: string;
+    } | undefined>;
+    /**
+     * Run an async function to get authentication information out of the request
+     * object. Should return an object with at least a username and sessionid (see FastifyTxStateAuthInfo
+     * for further detail).
+     *
+     * The return object will be added to the request object as `req.auth` for later
+     * use in your route handlers. It will also be added to the logs in production.
+     *
+     * IMPORTANT: It is not advisable to return excessive amounts of data here, nor anything
+     * particularly sensitive, since it will all be included in every log entry.
+     *
+     * If this function throws, the client will receive a 401 response.
+     */
+    authenticate?: <T extends FastifyTxStateAuthInfo>(req: FastifyRequest) => Promise<T | undefined>;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        auth?: FastifyTxStateAuthInfo;
+    }
+    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 default class Server {
+    protected config: FastifyTxStateOptions & {
+        http2?: true;
+    };
+    protected https: boolean;
+    protected errorHandlers: ErrorHandler[];
+    protected healthMessage?: string;
+    protected healthCallback?: () => Promise<string | {
+        status?: number;
+        message?: string;
+    } | undefined>;
+    protected shuttingDown: boolean;
+    protected sigHandler: (signal: any) => void;
+    protected validOrigins: Record<string, boolean>;
+    protected validOriginHosts: Record<string, boolean>;
+    protected validOriginSuffixes: Set<string>;
+    app: FastifyInstance<RawServerDefault, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, FastifyBaseLogger, JsonSchemaToTsProvider>;
+    constructor(config?: FastifyTxStateOptions & {
+        http2?: true;
+    });
+    start(port?: number): Promise<void>;
+    addErrorHandler(handler: ErrorHandler): void;
+    setUnhealthy(message: string): void;
+    setHealthy(): void;
+    setValidOrigins(origins: string[]): void;
+    setValidOriginHosts(hosts: string[]): void;
+    setValidOriginSuffixes(suffixes: string[]): void;
+    swagger(opts?: {
+        path?: string;
+        openapi?: FastifyDynamicSwaggerOptions['openapi'];
+        ui?: FastifySwaggerUiOptions;
+    }): Promise<void>;
+    close(softSeconds?: number): Promise<void>;
+}
+export * from './analytics';
+export * from './error';
+export * from './unified-auth';

package/lib/index.js

@@ -1,13 +1,33 @@
 "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.FailedValidationError = exports.HttpError = exports.prodLogger = exports.devLogger = void 0;
+exports.prodLogger = exports.devLogger = void 0;
+const swagger_1 = __importDefault(require("@fastify/swagger"));
+const swagger_ui_1 = __importDefault(require("@fastify/swagger-ui"));
+const ajv_errors_1 = __importDefault(require("ajv-errors"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
 const fastify_1 = require("fastify");
-const fs_1 = __importDefault(require("fs"));
-const http_1 = __importDefault(require("http"));
-const http_status_codes_1 = require("http-status-codes");
+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");
+const unified_auth_1 = require("./unified-auth");
 exports.devLogger = {
     level: 'info',
     info: (msg) => { console.info(msg.req ? `${msg.req.method} ${msg.req.url}` : msg.res ? `${msg.res.statusCode} - ${msg.responseTime}` : msg); },
@@ -25,25 +45,27 @@ exports.prodLogger = {
         req(req) {
             return {
                 method: req.method,
-                url: req.url.replace(/token=[\w.]+/, 'token=redacted'),
+                url: req.url.replace(/(token|unifiedJwt)=[\w.]+/i, '$1=redacted'),
                 remoteAddress: req.ip,
                 traceparent: req.headers.traceparent
             };
         },
         res(res) {
-            var _a, _b;
+            var _a, _b, _c, _d;
             return {
                 statusCode: res.statusCode,
-                url: (_a = res.request) === null || _a === void 0 ? void 0 : _a.url.replace(/token=[\w.]+/, 'token=redacted'),
-                length: (_b = res.getHeader) === null || _b === void 0 ? void 0 : _b.call(res, 'content-length'),
-                ...res.extraLogInfo
+                url: (_a = res.request) === null || _a === void 0 ? void 0 : _a.url.replace(/(token|unifiedJwt)=[\w.]+/i, '$1=redacted'),
+                length: Number((0, txstate_utils_1.toArray)((_b = res.getHeader) === null || _b === void 0 ? void 0 : _b.call(res, 'content-length'))[0]),
+                ...res.extraLogInfo,
+                auth: (_d = (_c = res.request) === null || _c === void 0 ? void 0 : _c.auth) !== null && _d !== void 0 ? _d : res.extraLogInfo.auth
             };
         }
     }
 };
 class Server {
     constructor(config = {}) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        this.config = config;
         this.https = false;
         this.errorHandlers = [];
         this.shuttingDown = false;
@@ -51,8 +73,8 @@ class Server {
         this.validOriginHosts = {};
         this.validOriginSuffixes = new Set();
         try {
-            const key = fs_1.default.readFileSync('/securekeys/private.key');
-            const cert = fs_1.default.readFileSync('/securekeys/cert.pem');
+            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,
@@ -78,14 +100,47 @@ class Server {
             else
                 config.trustProxy = process.env.TRUST_PROXY;
         }
+        config.ajv = { ...config.ajv, plugins: [...((_b = (_a = config.ajv) === null || _a === void 0 ? void 0 : _a.plugins) !== null && _b !== void 0 ? _b : []), ajv_errors_1.default, [ajv_formats_1.default, { mode: 'fast' }]], customOptions: { ...(_c = config.ajv) === null || _c === void 0 ? void 0 : _c.customOptions, allErrors: true, strictSchema: false } };
         this.healthCallback = config.checkHealth;
         this.app = (0, fastify_1.fastify)(config);
+        this.app.addHook('onRoute', route => {
+            var _a, _b, _c;
+            if (!((_a = route.schema) === null || _a === void 0 ? void 0 : _a.body))
+                return;
+            const missingResponse = ((_b = route.schema) === null || _b === void 0 ? void 0 : _b.response) == null;
+            const newSchema = (0, txstate_utils_1.set)((_c = route.schema) !== null && _c !== void 0 ? _c : {}, 'response.422', {
+                description: 'Validation failure.',
+                type: 'object',
+                properties: {
+                    errors: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                type: { type: 'string', enum: ['error', 'warning', 'success', 'system'], example: 'error' },
+                                message: { type: 'string', example: 'must be an integer' },
+                                path: { type: 'string', example: 'cart.item.0.quantity', description: 'Dot-separated path to the field in the request body that caused the validation error.' }
+                            },
+                            required: ['type', 'message'],
+                            additionalProperties: false
+                        }
+                    }
+                }
+            });
+            if (missingResponse) {
+                newSchema.response['200'] = {
+                    description: 'Success. Return type has not been specified.',
+                    type: 'null'
+                };
+            }
+            route.schema = newSchema;
+        });
         if (!config.skipOriginCheck && !process.env.SKIP_ORIGIN_CHECK) {
-            this.setValidOrigins([...((_a = config.validOrigins) !== null && _a !== void 0 ? _a : []), ...((_c = (_b = process.env.VALID_ORIGINS) === null || _b === void 0 ? void 0 : _b.split(',')) !== null && _c !== void 0 ? _c : [])]);
-            this.setValidOriginHosts([...((_d = config.validOriginHosts) !== null && _d !== void 0 ? _d : []), ...((_f = (_e = process.env.VALID_ORIGIN_HOSTS) === null || _e === void 0 ? void 0 : _e.split(',')) !== null && _f !== void 0 ? _f : [])]);
-            this.setValidOriginSuffixes([...((_g = config.validOriginSuffixes) !== null && _g !== void 0 ? _g : []), ...((_j = (_h = process.env.VALID_ORIGIN_SUFFIXES) === null || _h === void 0 ? void 0 : _h.split(',')) !== null && _j !== void 0 ? _j : [])]);
+            this.setValidOrigins([...((_d = config.validOrigins) !== null && _d !== void 0 ? _d : []), ...((_f = (_e = process.env.VALID_ORIGINS) === null || _e === void 0 ? void 0 : _e.split(',')) !== null && _f !== void 0 ? _f : [])]);
+            this.setValidOriginHosts([...((_g = config.validOriginHosts) !== null && _g !== void 0 ? _g : []), ...((_j = (_h = process.env.VALID_ORIGIN_HOSTS) === null || _h === void 0 ? void 0 : _h.split(',')) !== null && _j !== void 0 ? _j : [])]);
+            this.setValidOriginSuffixes([...((_k = config.validOriginSuffixes) !== null && _k !== void 0 ? _k : []), ...((_m = (_l = process.env.VALID_ORIGIN_SUFFIXES) === null || _l === void 0 ? void 0 : _l.split(',')) !== null && _m !== void 0 ? _m : [])]);
             this.app.addHook('preHandler', async (req, res) => {
-                var _a;
+                var _a, _b;
                 res.extraLogInfo = {};
                 if (!req.headers.origin)
                     return;
@@ -119,6 +174,13 @@ class Server {
                     if (req.headers['access-control-request-headers'])
                         void res.header('Access-Control-Allow-Headers', req.headers['access-control-request-headers']);
                 }
+                try {
+                    req.auth = await ((_b = config.authenticate) === null || _b === void 0 ? void 0 : _b.call(config, req));
+                }
+                catch (e) {
+                    await res.status(401).send('Failed to authenticate.');
+                    return res;
+                }
             });
             this.app.options('*', async (req, res) => {
                 await res.send();
@@ -138,20 +200,24 @@ class Server {
             });
         this.app.setNotFoundHandler((req, res) => { void res.status(404).send('Not Found.'); });
         this.app.setErrorHandler(async (err, req, res) => {
+            var _a, _b;
             req.log.warn(err);
             for (const errorHandler of this.errorHandlers) {
                 if (!res.sent)
                     await errorHandler(err, req, res);
             }
             if (!res.sent) {
-                if (err instanceof FailedValidationError) {
+                if (err instanceof error_1.FailedValidationError) {
                     await res.status(err.statusCode).send(err.errors);
                 }
-                else if (err instanceof HttpError) {
+                else if (err instanceof error_1.HttpError) {
                     await res.status(err.statusCode).send(err.message);
                 }
+                else if (err.code === 'FST_ERR_VALIDATION') {
+                    await res.status(422).send({ errors: (_b = (_a = err.validation) === null || _a === void 0 ? void 0 : _a.map(err => ({ message: err.message, path: err.instancePath.substring(1).replace(/\//g, '.'), type: 'error' }))) !== null && _b !== void 0 ? _b : [] });
+                }
                 else if (err.statusCode) {
-                    await res.status(err.statusCode).send(new HttpError(err.statusCode).message);
+                    await res.status(err.statusCode).send(new error_1.HttpError(err.statusCode).message);
                 }
                 else {
                     await res.status(500).send('Internal Server Error.');
@@ -189,14 +255,16 @@ class Server {
         process.on('SIGINT', this.sigHandler);
     }
     async start(port) {
-        var _a;
+        var _a, _b, _c;
         const customPort = port !== null && port !== void 0 ? port : parseInt((_a = process.env.PORT) !== null && _a !== void 0 ? _a : '0');
+        await this.app.ready();
+        (_c = (_b = this.app).swagger) === null || _c === void 0 ? void 0 : _c.call(_b);
         if (customPort) {
             await this.app.listen({ port: customPort, host: '0.0.0.0' });
         }
         else if (this.https) {
             // redirect 80 to 443
-            http_1.default.createServer((req, res) => {
+            node_http_1.default.createServer((req, res) => {
                 var _a, _b, _c, _d;
                 res.writeHead(301, { Location: 'https://' + ((_c = (_b = (_a = req === null || req === void 0 ? void 0 : req.headers) === null || _a === void 0 ? void 0 : _a.host) === null || _b === void 0 ? void 0 : _b.replace(/:\d+$/, '')) !== null && _c !== void 0 ? _c : '') + ((_d = req.url) !== null && _d !== void 0 ? _d : '') });
                 res.end();
@@ -227,6 +295,25 @@ class Server {
         for (const s of suffixes)
             this.validOriginSuffixes.add(s);
     }
+    async swagger(opts) {
+        var _a, _b, _c, _d;
+        let openapi = (_a = opts === null || opts === void 0 ? void 0 : opts.openapi) !== null && _a !== void 0 ? _a : {};
+        if (this.config.authenticate === unified_auth_1.unifiedAuthenticate) {
+            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: [] }];
+        }
+        await this.app.register(swagger_1.default, { openapi });
+        await this.app.register(swagger_ui_1.default, { ...opts === null || opts === void 0 ? void 0 : opts.ui, routePrefix: (_d = (_b = opts === null || opts === void 0 ? void 0 : opts.path) !== null && _b !== void 0 ? _b : (_c = opts === null || opts === void 0 ? void 0 : opts.ui) === null || _c === void 0 ? void 0 : _c.routePrefix) !== null && _d !== void 0 ? _d : '/docs' });
+    }
     async close(softSeconds) {
         var _a;
         if (typeof softSeconds === 'undefined')
@@ -235,31 +322,12 @@ class Server {
         process.removeListener('SIGINT', this.sigHandler);
         if (softSeconds) {
             this.shuttingDown = true;
-            await new Promise(resolve => setTimeout(resolve, softSeconds * 1000));
+            await (0, txstate_utils_1.sleep)(softSeconds);
         }
         await this.app.close();
     }
 }
 exports.default = Server;
-class HttpError extends Error {
-    constructor(statusCode, message) {
-        if (!message) {
-            if (statusCode === 401)
-                message = 'Authentication is required.';
-            else if (statusCode === 403)
-                message = 'You are not authorized for that.';
-            else
-                message = (0, http_status_codes_1.getReasonPhrase)(statusCode);
-        }
-        super(message);
-        this.statusCode = statusCode;
-    }
-}
-exports.HttpError = HttpError;
-class FailedValidationError extends HttpError {
-    constructor(errors) {
-        super(422, 'Validation failure.');
-        this.errors = errors;
-    }
-}
-exports.FailedValidationError = FailedValidationError;
+__exportStar(require("./analytics"), exports);
+__exportStar(require("./error"), exports);
+__exportStar(require("./unified-auth"), exports);

package/lib/unified-auth.d.ts

@@ -0,0 +1,61 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { type KeyObject } from 'crypto';
+import { type FastifyRequest } from 'fastify';
+import { type JWTPayload, type JWTVerifyGetKey, type KeyLike } from 'jose';
+import { Cache } from 'txstate-utils';
+import { type FastifyTxStateAuthInfo } from '.';
+declare class MockContext<AuthType = any> {
+    auth?: AuthType;
+    constructor(auth: any);
+    waitForAuth(): Promise<AuthType | undefined>;
+    static init(): void;
+}
+interface IssuerConfig {
+    iss: string;
+    url?: string;
+    publicKey?: string;
+    secret?: string;
+    validateUrl: URL;
+}
+declare class Context<AuthType extends FastifyTxStateAuthInfo = FastifyTxStateAuthInfo> extends MockContext<AuthType> {
+    private readonly authPromise;
+    protected static jwtVerifyKey: KeyObject | undefined;
+    protected static issuerKeys: Map<string, KeyLike | JWTVerifyGetKey>;
+    protected static issuerConfig: Map<string, any>;
+    protected static tokenCache: Cache<string, any, {
+        req?: FastifyRequest<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown, import("fastify").FastifyBaseLogger, import("fastify/types/type-provider").ResolveFastifyRequestType<import("fastify").FastifyTypeProviderDefault, import("fastify").FastifySchema, import("fastify").RouteGenericInterface>> | undefined;
+        ctx: Context;
+    }>;
+    constructor(req?: FastifyRequest);
+    waitForAuth(): Promise<AuthType | undefined>;
+    static init(): void;
+    /**
+     * If implemented, this method will be called on startup, once per configured issuer. It receives
+     * the issuer configuration from the JWT_TRUSTED_ISSUERS environment variable and allows you to manipulate
+     * the configuration before storing it.
+     *
+     * Once stored, whatever you create may be used in your custom validateToken method. For example,
+     * you might want to create an in-memory URL object with an issuer's URL so that it can be manipulated
+     * easily to send validation checks to the issuer.
+     */
+    static processIssuerConfig: undefined | ((config: any) => any);
+    /**
+     * If implemented, this method is called after a token's signature is checked and passes. You would
+     * typically implement this method to check whether the user has manually signed out, or the token has
+     * been otherwise deauthorized before its expiration date.
+     *
+     * If the token is not valid, this method should throw an error with an appropriate message.
+     */
+    static validateToken: undefined | ((token: string, issuerConfig: any, claims: JWTPayload) => void | Promise<void>);
+    tokenFromReq(req?: FastifyRequest): string | undefined;
+    authFromReq(req?: FastifyRequest): Promise<AuthType | undefined>;
+    authFromPayload(payload: JWTPayload): Promise<AuthType>;
+}
+declare class TxStateUAuthContext extends Context {
+    static processIssuerConfig(config: IssuerConfig): IssuerConfig;
+    static validateToken(token: string, issuerConfig: IssuerConfig, claims: any): Promise<void>;
+    authFromPayload(payload: JWTPayload): Promise<FastifyTxStateAuthInfo>;
+}
+export declare function unifiedAuthenticate(req: FastifyRequest, ContextClass?: typeof TxStateUAuthContext): Promise<FastifyTxStateAuthInfo | undefined>;
+export {};

package/lib/unified-auth.js

@@ -0,0 +1,138 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unifiedAuthenticate = void 0;
+const crypto_1 = require("crypto");
+const jose_1 = require("jose");
+const txstate_utils_1 = require("txstate-utils");
+function cleanPem(secretOrPem) {
+    return secretOrPem === null || secretOrPem === void 0 ? void 0 : secretOrPem.replace(/(-+BEGIN [\w\s]+ KEY-+)\s*(.*?)\s*(-+END [\w\s]+ KEY-+)/, '$1\n$2\n$3');
+}
+class MockContext {
+    constructor(auth) {
+        this.auth = auth;
+    }
+    async waitForAuth() {
+        return this.auth;
+    }
+    static init() { }
+}
+class Context extends MockContext {
+    constructor(req) {
+        super(undefined);
+        this.authPromise = this.authFromReq(req);
+    }
+    async waitForAuth() {
+        this.auth = await this.authPromise;
+        return this.auth;
+    }
+    static init() {
+        var _b;
+        let secret = cleanPem(process.env.JWT_SECRET_VERIFY);
+        if (secret != null) {
+            _a.jwtVerifyKey = (0, crypto_1.createPublicKey)(secret);
+        }
+        else {
+            secret = cleanPem(process.env.JWT_SECRET);
+            if (secret != null) {
+                try {
+                    _a.jwtVerifyKey = (0, crypto_1.createPublicKey)(secret);
+                }
+                catch (e) {
+                    console.info('JWT_SECRET was not a private key, treating it as symmetric.');
+                    _a.jwtVerifyKey = (0, crypto_1.createSecretKey)(Buffer.from(secret, 'ascii'));
+                }
+            }
+        }
+        if (process.env.JWT_TRUSTED_ISSUERS) {
+            const issuers = (0, txstate_utils_1.toArray)(JSON.parse(process.env.JWT_TRUSTED_ISSUERS));
+            for (const issuer of issuers) {
+                this.issuerConfig.set(issuer.iss, (_b = this.processIssuerConfig) === null || _b === void 0 ? void 0 : _b.call(this, (0, txstate_utils_1.omit)(issuer, 'publicKey', 'secret')));
+                if (issuer.url)
+                    this.issuerKeys.set(issuer.iss, (0, jose_1.createRemoteJWKSet)(new URL(issuer.url)));
+                else if (issuer.publicKey)
+                    this.issuerKeys.set(issuer.iss, (0, crypto_1.createPublicKey)(issuer.publicKey));
+                else if (issuer.secret)
+                    this.issuerKeys.set(issuer.iss, (0, crypto_1.createSecretKey)(Buffer.from(issuer.secret, 'ascii')));
+            }
+        }
+    }
+    tokenFromReq(req) {
+        var _b;
+        const m = (_b = req === null || req === void 0 ? void 0 : req.headers.authorization) === null || _b === void 0 ? void 0 : _b.match(/^bearer (.*)$/i);
+        return m === null || m === void 0 ? void 0 : m[1];
+    }
+    async authFromReq(req) {
+        const token = this.tokenFromReq(req);
+        if (!token)
+            return undefined;
+        return this.constructor.tokenCache.get(token, { req, ctx: this });
+    }
+    async authFromPayload(payload) {
+        return payload;
+    }
+}
+_a = Context;
+Context.issuerKeys = new Map();
+Context.issuerConfig = new Map();
+Context.tokenCache = new txstate_utils_1.Cache(async (token, { req, ctx }) => {
+    var _b, _c;
+    // `this` is always the Context class, even if we are making instances of a subclass of Context
+    // we need to get the instance's constructor instead in case it has overridden one of our
+    // static methods/variables
+    const ctxStatic = ctx.constructor;
+    const logger = (_b = req === null || req === void 0 ? void 0 : req.log) !== null && _b !== void 0 ? _b : console;
+    let verifyKey = _a.jwtVerifyKey;
+    try {
+        const claims = (0, jose_1.decodeJwt)(token);
+        if (claims.iss && ctxStatic.issuerKeys.has(claims.iss))
+            verifyKey = ctxStatic.issuerKeys.get(claims.iss);
+        if (!verifyKey) {
+            logger.info(`Received token with issuer: ${claims.iss} but JWT secret could not be found. The server may be misconfigured or the user may have presented a JWT from an untrusted issuer.`);
+            return undefined;
+        }
+        await ((_c = ctxStatic.validateToken) === null || _c === void 0 ? void 0 : _c.call(ctxStatic, token, ctxStatic.issuerConfig.get(claims.iss), claims));
+        const { payload } = await (0, jose_1.jwtVerify)(token, verifyKey);
+        return await ctx.authFromPayload(payload);
+    }
+    catch (e) {
+        // squelch errors about bad tokens, we can already see the 401 in the log
+        if (e.code !== 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED')
+            logger.error(e);
+        return undefined;
+    }
+}, { freshseconds: 10 });
+class TxStateUAuthContext extends Context {
+    static processIssuerConfig(config) {
+        var _b;
+        if (config.iss === 'unified-auth') {
+            config.validateUrl = new URL((_b = config.url) !== null && _b !== void 0 ? _b : '');
+            config.validateUrl.pathname = '/validateToken';
+        }
+        return config;
+    }
+    static async validateToken(token, issuerConfig, claims) {
+        var _b;
+        if (claims.iss === 'unified-auth') {
+            const validateUrl = new URL(issuerConfig.validateUrl);
+            validateUrl.searchParams.set('unifiedJwt', token);
+            const resp = await fetch(validateUrl);
+            const validate = await resp.json();
+            if (!validate.valid)
+                throw new Error((_b = validate.reason) !== null && _b !== void 0 ? _b : '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 authFromPayload(payload) {
+        return {
+            username: payload.sub,
+            sessionId: payload.sub + '-' + payload.iat,
+            clientId: payload.client_id,
+            impersonatedBy: payload.impersonatedBy
+        };
+    }
+}
+async function unifiedAuthenticate(req, ContextClass = TxStateUAuthContext) {
+    const ctx = new ContextClass(req);
+    return ctx.waitForAuth();
+}
+exports.unifiedAuthenticate = unifiedAuthenticate;

package/lib-esm/index.d.ts

@@ -1,7 +1,51 @@
 /// <reference types="node" />
-import { type FastifyInstance, type FastifyRequest, type FastifyReply, type FastifyServerOptions, type FastifyLoggerOptions } from 'fastify';
-import type http2 from 'http2';
+/// <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 http from 'node:http';
+import type http2 from 'node:http2';
 type ErrorHandler = (error: Error, req: FastifyRequest, res: FastifyReply) => Promise<void>;
+export interface FastifyTxStateAuthInfo {
+    /**
+     * The primary identifier for the user that is making the request, after processing
+     * their session token / JWT.
+     */
+    username: string;
+    /**
+     * This should be an identifier for the particular session, so that the same user
+     * on different devices/browsers/tabs can be distinguished from one another.
+     *
+     * It should NOT be usable as a cookie or bearer token, as it will appear in logs. If you
+     * use JSON Web Tokens, an easy thing is to combine the username with the `iat` issued
+     * date to create something unique but not useful to attackers.
+     *
+     * For lookup tokens, you can do the same `${username}-${createdAt}` after looking up
+     * the session in your database.
+     *
+     * If all else fails, you can sha256 the session token with a salt.
+     */
+    sessionId: string;
+    /**
+     * 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
+     * with any actions they take while impersonating someone, for auditing purposes, so you should
+     * fill this field when applicable.
+     *
+     * This will also be available at `req.auth.impersonatedBy`, so it is possible for your API
+     * to implement complicated authorization rules based on whether a user is being impersonated.
+     * It sort of defeats the purpose of impersonation, but used sparingly it could prevent administrators
+     * from making mistakes.
+     */
+    impersonatedBy?: string;
+    /**
+     * If your API may be accessed by a different client application, such that the user is actually logged
+     * into that application instead of yours, but you accept that application's session tokens, filling
+     * this field can help log requests that are authenticated with the other application's token.
+     */
+    clientId?: string;
+}
 export interface FastifyTxStateOptions extends Partial<FastifyServerOptions> {
     https?: http2.SecureServerOptions;
     validOrigins?: string[];
@@ -20,8 +64,25 @@ export interface FastifyTxStateOptions extends Partial<FastifyServerOptions> {
         status?: number;
         message?: string;
     } | undefined>;
+    /**
+     * Run an async function to get authentication information out of the request
+     * object. Should return an object with at least a username and sessionid (see FastifyTxStateAuthInfo
+     * for further detail).
+     *
+     * The return object will be added to the request object as `req.auth` for later
+     * use in your route handlers. It will also be added to the logs in production.
+     *
+     * IMPORTANT: It is not advisable to return excessive amounts of data here, nor anything
+     * particularly sensitive, since it will all be included in every log entry.
+     *
+     * If this function throws, the client will receive a 401 response.
+     */
+    authenticate?: <T extends FastifyTxStateAuthInfo>(req: FastifyRequest) => Promise<T | undefined>;
 }
 declare module 'fastify' {
+    interface FastifyRequest {
+        auth?: FastifyTxStateAuthInfo;
+    }
     interface FastifyReply {
         extraLogInfo: any;
     }
@@ -54,6 +115,9 @@ export declare const devLogger: {
 };
 export declare const prodLogger: FastifyLoggerOptions;
 export default class Server {
+    protected config: FastifyTxStateOptions & {
+        http2?: true;
+    };
     protected https: boolean;
     protected errorHandlers: ErrorHandler[];
     protected healthMessage?: string;
@@ -66,7 +130,7 @@ export default class Server {
     protected validOrigins: Record<string, boolean>;
     protected validOriginHosts: Record<string, boolean>;
     protected validOriginSuffixes: Set<string>;
-    app: FastifyInstance;
+    app: FastifyInstance<RawServerDefault, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, FastifyBaseLogger, JsonSchemaToTsProvider>;
     constructor(config?: FastifyTxStateOptions & {
         http2?: true;
     });
@@ -77,15 +141,13 @@ export default class Server {
     setValidOrigins(origins: string[]): void;
     setValidOriginHosts(hosts: string[]): void;
     setValidOriginSuffixes(suffixes: string[]): void;
+    swagger(opts?: {
+        path?: string;
+        openapi?: FastifyDynamicSwaggerOptions['openapi'];
+        ui?: FastifySwaggerUiOptions;
+    }): Promise<void>;
     close(softSeconds?: number): Promise<void>;
 }
-export declare class HttpError extends Error {
-    statusCode: number;
-    constructor(statusCode: number, message?: string);
-}
-type ValidationErrors = Record<string, string[]>;
-export declare class FailedValidationError extends HttpError {
-    errors: ValidationErrors;
-    constructor(errors: ValidationErrors);
-}
-export {};
+export * from './analytics';
+export * from './error';
+export * from './unified-auth';

package/lib-esm/index.js

@@ -4,4 +4,9 @@ export const devLogger = ftxst.devLogger
 export const prodLogger = ftxst.prodLogger
 export const HttpError = ftxst.HttpError
 export const FailedValidationError = ftxst.FailedValidationError
+export const unifiedAuthenticate = ftxst.unifiedAuthenticate
+export const analyticsPlugin = ftxst.analyticsPlugin
+export const AnalyticsClient = ftxst.AnalyticsClient
+export const LoggingAnalyticsClient = ftxst.LoggingAnalyticsClient
+export const ElasticAnalyticsClient = ftxst.ElasticAnalyticsClient
 export default ftxst.default

package/package.json

@@ -1,31 +1,46 @@
 {
   "name": "fastify-txstate",
-  "version": "3.1.9",
+  "version": "3.2.1",
   "description": "A small wrapper for fastify providing a set of common conventions & utility functions we use.",
   "exports": {
-    "types": "./lib-esm/index.d.ts",
-    "require": "./lib/index.js",
-    "import": "./lib-esm/index.js"
+    ".": {
+      "types": "./lib/index.d.ts",
+      "require": "./lib/index.js",
+      "import": "./lib-esm/index.js"
+    }
   },
-  "types": "./lib-esm/index.d.ts",
+  "types": "./lib/index.d.ts",
   "scripts": {
     "prepublishOnly": "npm run build",
-    "build": "rm -rf lib && tsc && mv lib/index.d.ts lib-esm/index.d.ts",
+    "build": "rm -rf lib && tsc",
     "test": "./test.sh",
     "mocha": "TS_NODE_PROJECT=test/tsconfig.json mocha -r ts-node/register test/**/*.ts",
-    "testserver": "ts-node-script testserver/index.ts"
+    "testserver": "node -r ts-node/register --no-warnings testserver/index.ts"
   },
   "dependencies": {
+    "@elastic/elasticsearch": "^8.12.2",
+    "@fastify/swagger": "^8.14.0",
+    "@fastify/swagger-ui": "^3.0.0",
+    "@fastify/type-provider-json-schema-to-ts": "^3.0.0",
+    "@txstate-mws/fastify-shared": "^1.0.4",
+    "ajv-errors": "^3.0.0",
+    "ajv-formats": "^2.1.1",
     "fastify": "^4.9.2",
-    "http-status-codes": "^2.1.4"
+    "fastify-plugin": "^4.5.1",
+    "http-status-codes": "^2.1.4",
+    "jose": "^5.2.3",
+    "txstate-utils": "^1.8.15",
+    "ua-parser-js": "^1.0.37"
   },
   "devDependencies": {
     "@types/chai": "^4.2.14",
     "@types/mocha": "^10.0.0",
-    "@types/node": "^16.7.2",
-    "axios": ">=0.20.0",
+    "@types/node": "^20.0.0",
+    "@types/ua-parser-js": ">=0.7.39",
+    "axios": "^1.6.8",
     "chai": "^4.2.0",
-    "eslint-config-standard-with-typescript": "^34.0.0",
+    "eslint-config-standard-with-typescript": "^43.0.0",
+    "json-schema-to-ts": "^3.0.1",
     "mocha": "^10.0.0",
     "ts-node": "^10.2.1",
     "typescript": "^5.0.4"