fastify-txstate 3.5.0 → 3.5.1

package/lib/analytics.js

@@ -3,7 +3,8 @@ 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;
+exports.ElasticAnalyticsClient = exports.LoggingAnalyticsClient = exports.AnalyticsClient = void 0;
+exports.analyticsPlugin = analyticsPlugin;
 const elasticsearch_1 = __importDefault(require("@elastic/elasticsearch"));
 const fastify_shared_1 = require("@txstate-mws/fastify-shared");
 const txstate_utils_1 = require("txstate-utils");
@@ -114,4 +115,3 @@ function analyticsPlugin(fastify, opts, done) {
     });
     done();
 }
-exports.analyticsPlugin = analyticsPlugin;

package/lib/error.d.ts

@@ -15,8 +15,8 @@ export declare class FailedValidationError extends HttpError {
 }
 export declare class ValidationError extends HttpError {
     path?: string | undefined;
-    type?: "error" | "success" | "warning" | "system" | undefined;
-    constructor(message: string, path?: string | undefined, type?: "error" | "success" | "warning" | "system" | undefined);
+    type?: ValidationMessage["type"] | undefined;
+    constructor(message: string, path?: string | undefined, type?: ValidationMessage["type"] | undefined);
 }
 export declare class ValidationErrors extends HttpError {
     errors: ValidationMessage[];

package/lib/error.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fstValidationToMessage = exports.ValidationErrors = exports.ValidationError = exports.FailedValidationError = exports.HttpError = void 0;
+exports.ValidationErrors = exports.ValidationError = exports.FailedValidationError = exports.HttpError = void 0;
+exports.fstValidationToMessage = fstValidationToMessage;
 const http_status_codes_1 = require("http-status-codes");
 class HttpError extends Error {
     statusCode;
@@ -54,4 +55,3 @@ function fstValidationToMessage(v) {
     const instancePath = v.keyword === 'required' ? v.instancePath + '/' + v.params.missingProperty : v.instancePath;
     return { message: v.message, path: instancePath.substring(1).replace(/\//g, '.'), type: 'error' };
 }
-exports.fstValidationToMessage = fstValidationToMessage;

package/lib/index.d.ts

@@ -1,5 +1,3 @@
-/// <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';
@@ -45,6 +43,14 @@ export interface FastifyTxStateAuthInfo {
      * this field can help log requests that are authenticated with the other application's token.
      */
     clientId?: string;
+    /**
+     * A string that designates the current session as one that has limited authorization. The application will
+     * be responsible for checking this field and restricting appropriately.
+     *
+     * For example, a user who authenticated via non-standard mechanism might be given a scope of 'altlogin' and
+     * only a portion of the application's functionality would be available to them.
+     */
+    scope?: string;
 }
 export interface FastifyTxStateOptions extends Partial<FastifyServerOptions> {
     https?: http2.SecureServerOptions;
@@ -112,7 +118,7 @@ export declare const devLogger: {
         (message?: any, ...optionalParams: any[]): void;
     };
     silent: (msg: any) => void;
-    child(bindings: any, options?: any): any;
+    child(bindings: any, options?: any): /*elided*/ any;
 };
 export declare const prodLogger: FastifyLoggerOptions;
 export type FastifyInstanceTyped = FastifyInstance<RawServerDefault, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, FastifyBaseLogger, JsonSchemaToTsProvider>;

package/lib/index.js

@@ -292,12 +292,12 @@ class Server {
         });
         this.app.get('/health', { logLevel: 'warn' }, async (req, res) => {
             if (this.shuttingDown) {
-                res.log.info('Returning 503 on /health because we are shutting down/restarting.');
+                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.info(this.healthMessage);
+                res.log.error(this.healthMessage);
                 void res.status(500);
                 return this.healthMessage;
             }
@@ -305,7 +305,7 @@ class Server {
                 const resp = await this.healthCallback();
                 const [status, msg] = typeof resp === 'string' ? [500, resp] : [resp?.status, resp?.message];
                 if (!!msg || !!status) {
-                    res.log.info(resp, 'Health check callback failed.');
+                    res.log.error(resp, 'Health check callback failed.');
                     void res.status(status ?? 500);
                     return msg ?? 'FAIL';
                 }
@@ -394,9 +394,9 @@ this is log into this application and use dev tools to pull your token from the
         }
         await this.app.register(swagger_1.default, {
             openapi,
-            transform({ schema, url, route, swaggerObject, openapiObject }) {
-                const newSchema = findRefs((0, txstate_utils_1.clone)(schema));
-                return { schema: newSchema, url, route, swaggerObject, openapiObject };
+            transform(transformArgs) {
+                const newSchema = findRefs((0, txstate_utils_1.clone)(transformArgs.schema));
+                return { ...transformArgs, schema: newSchema };
             }
         });
         this.swaggerEndpoint = opts?.path ?? opts?.ui?.routePrefix ?? '/docs';

package/lib/unified-auth.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerUaCookieRoutes = exports.requireCookieAuth = exports.unifiedAuthenticateAll = exports.unifiedAuthenticate = exports.uaCookieName = void 0;
+exports.uaCookieName = void 0;
+exports.unifiedAuthenticate = unifiedAuthenticate;
+exports.unifiedAuthenticateAll = unifiedAuthenticateAll;
+exports.requireCookieAuth = requireCookieAuth;
+exports.registerUaCookieRoutes = registerUaCookieRoutes;
 const crypto_1 = require("crypto");
 const jose_1 = require("jose");
 const txstate_utils_1 = require("txstate-utils");
@@ -65,7 +69,7 @@ function remoteJWKSet(jwkUrl) {
 function processIssuerConfig(config) {
     if (config.iss === 'unified-auth') {
         config.validateUrl = new URL(config.url ?? '');
-        config.validateUrl.pathname = '/validateToken';
+        config.validateUrl.pathname = [...config.validateUrl.pathname.split('/').slice(0, -1), 'validateToken'].join('/');
     }
     return config;
 }
@@ -112,17 +116,16 @@ async function unifiedAuthenticate(req) {
         username: payload.sub,
         sessionId: payload.sub + '-' + payload.iat,
         clientId: payload.client_id,
-        impersonatedBy: payload.act?.sub
+        impersonatedBy: payload.act?.sub,
+        scope: payload.scope
     };
 }
-exports.unifiedAuthenticate = unifiedAuthenticate;
 async function unifiedAuthenticateAll(req) {
     const auth = await unifiedAuthenticate(req);
     if (!auth?.username.length)
         throw new Error('All requests require authentication.');
     return auth;
 }
-exports.unifiedAuthenticateAll = unifiedAuthenticateAll;
 async function requireCookieAuth(req, res) {
     if (req.auth === undefined || req.auth.username.length === 0) {
         await res
@@ -134,7 +137,6 @@ async function requireCookieAuth(req, res) {
         return false;
     }
 }
-exports.requireCookieAuth = requireCookieAuth;
 function registerUaCookieRoutes(app) {
     app.get('/.uaLogout', {
         schema: {
@@ -182,4 +184,3 @@ function registerUaCookieRoutes(app) {
             .redirect(decodeURIComponent(m[1]));
     });
 }
-exports.registerUaCookieRoutes = registerUaCookieRoutes;

package/lib-esm/index.d.ts

@@ -0,0 +1,155 @@
+/// <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?: (req: FastifyRequest) => Promise<FastifyTxStateAuthInfo | 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 type FastifyInstanceTyped = FastifyInstance<RawServerDefault, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, FastifyBaseLogger, JsonSchemaToTsProvider>;
+export type TxServer = Server;
+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: FastifyInstanceTyped;
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-txstate",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "A small wrapper for fastify providing a set of common conventions & utility functions we use.",
   "exports": {
     ".": {
@@ -36,7 +36,7 @@
   "devDependencies": {
     "@types/chai": "^4.2.14",
     "@types/mocha": "^10.0.0",
-    "@types/node": "^20.0.0",
+    "@types/node": "^22.0.0",
     "axios": "^1.6.8",
     "chai": "^4.2.0",
     "eslint-config-standard-with-typescript": "^43.0.0",