fastify-txstate 3.2.0 → 3.2.1

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

@@ -21,6 +21,7 @@ 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 node_fs_1 = __importDefault(require("node:fs"));
 const node_http_1 = __importDefault(require("node:http"));
@@ -63,7 +64,7 @@ exports.prodLogger = {
 };
 class Server {
     constructor(config = {}) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         this.config = config;
         this.https = false;
         this.errorHandlers = [];
@@ -99,7 +100,7 @@ class Server {
             else
                 config.trustProxy = process.env.TRUST_PROXY;
         }
-        config.ajv = { ...config.ajv, plugins: [...((_c = (_b = (_a = config.ajv) === null || _a === void 0 ? void 0 : _a.plugins) === null || _b === void 0 ? void 0 : _b.filter(p => p !== ajv_errors_1.default)) !== null && _c !== void 0 ? _c : []), ajv_errors_1.default], customOptions: { ...(_d = config.ajv) === null || _d === void 0 ? void 0 : _d.customOptions, allErrors: true, strictSchema: false } };
+        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 => {
@@ -135,9 +136,9 @@ class Server {
             route.schema = newSchema;
         });
         if (!config.skipOriginCheck && !process.env.SKIP_ORIGIN_CHECK) {
-            this.setValidOrigins([...((_e = config.validOrigins) !== null && _e !== void 0 ? _e : []), ...((_g = (_f = process.env.VALID_ORIGINS) === null || _f === void 0 ? void 0 : _f.split(',')) !== null && _g !== void 0 ? _g : [])]);
-            this.setValidOriginHosts([...((_h = config.validOriginHosts) !== null && _h !== void 0 ? _h : []), ...((_k = (_j = process.env.VALID_ORIGIN_HOSTS) === null || _j === void 0 ? void 0 : _j.split(',')) !== null && _k !== void 0 ? _k : [])]);
-            this.setValidOriginSuffixes([...((_l = config.validOriginSuffixes) !== null && _l !== void 0 ? _l : []), ...((_o = (_m = process.env.VALID_ORIGIN_SUFFIXES) === null || _m === void 0 ? void 0 : _m.split(',')) !== null && _o !== void 0 ? _o : [])]);
+            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, _b;
                 res.extraLogInfo = {};

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "fastify-txstate",
-  "version": "3.2.0",
+  "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": "node -r ts-node/register --no-warnings testserver/index.ts"
@@ -22,6 +24,7 @@
     "@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",
     "fastify-plugin": "^4.5.1",
     "http-status-codes": "^2.1.4",