@nextrush/errors 3.0.7 → 4.0.0-beta.1

package/src/factory.ts

@@ -11,35 +11,92 @@ import {
   BadGatewayError,
   BadRequestError,
   ConflictError,
+  ExpectationFailedError,
+  FailedDependencyError,
   ForbiddenError,
   GatewayTimeoutError,
+  GoneError,
+  HttpVersionNotSupportedError,
+  ImATeapotError,
+  InsufficientStorageError,
   InternalServerError,
+  LengthRequiredError,
+  LockedError,
+  LoopDetectedError,
   MethodNotAllowedError,
+  NetworkAuthRequiredError,
+  NotAcceptableError,
+  NotExtendedError,
   NotFoundError,
   NotImplementedError,
+  PayloadTooLargeError,
+  PaymentRequiredError,
+  PreconditionFailedError,
+  PreconditionRequiredError,
+  ProxyAuthRequiredError,
+  RangeNotSatisfiableError,
+  RequestHeaderFieldsTooLargeError,
+  RequestTimeoutError,
   ServiceUnavailableError,
+  TooEarlyError,
   TooManyRequestsError,
   UnauthorizedError,
+  UnavailableForLegalReasonsError,
   UnprocessableEntityError,
+  UnsupportedMediaTypeError,
+  UpgradeRequiredError,
+  UriTooLongError,
+  VariantAlsoNegotiatesError,
   type HttpErrorOptions,
 } from './http-errors';
 
 /**
- * HTTP status code to error class mapping
+ * HTTP status code to error class mapping.
+ *
+ * @remarks
+ * Covers every status that has a dedicated typed class so {@link createError}
+ * returns the correctly-coded instance (audit E-3). `405` is handled separately
+ * because {@link MethodNotAllowedError} has a divergent constructor signature.
  */
 const ERROR_MAP: Record<number, new (message?: string, options?: HttpErrorOptions) => HttpError> = {
   400: BadRequestError,
   401: UnauthorizedError,
+  402: PaymentRequiredError,
   403: ForbiddenError,
   404: NotFoundError,
+  406: NotAcceptableError,
+  407: ProxyAuthRequiredError,
+  408: RequestTimeoutError,
   409: ConflictError,
+  410: GoneError,
+  411: LengthRequiredError,
+  412: PreconditionFailedError,
+  413: PayloadTooLargeError,
+  414: UriTooLongError,
+  415: UnsupportedMediaTypeError,
+  416: RangeNotSatisfiableError,
+  417: ExpectationFailedError,
+  418: ImATeapotError,
   422: UnprocessableEntityError,
+  423: LockedError,
+  424: FailedDependencyError,
+  425: TooEarlyError,
+  426: UpgradeRequiredError,
+  428: PreconditionRequiredError,
   429: TooManyRequestsError,
+  431: RequestHeaderFieldsTooLargeError,
+  451: UnavailableForLegalReasonsError,
   500: InternalServerError,
   501: NotImplementedError,
   502: BadGatewayError,
   503: ServiceUnavailableError,
   504: GatewayTimeoutError,
+  505: HttpVersionNotSupportedError,
+  506: VariantAlsoNegotiatesError,
+  507: InsufficientStorageError,
+  508: LoopDetectedError,
+  510: NotExtendedError,
+  511: NetworkAuthRequiredError,
 };
 
 /**

package/src/header-validation.ts

@@ -0,0 +1,24 @@
+/**
+ * @nextrush/errors - Header Validation Error
+ *
+ * @packageDocumentation
+ */
+
+import { NextRushError } from './base';
+
+/**
+ * Thrown when a header field name or value fails RFC 9110 grammar
+ * validation (field-name token grammar, field-value grammar — no control
+ * characters, no leading/trailing whitespace, no obs-fold).
+ *
+ * @remarks
+ * A rejected write here means the application (or a framework internal) is
+ * constructing an invalid header, not that a client sent bad input — so this
+ * is a 500-class programming error, not a validation-issue-list shape like
+ * {@link ValidationError}.
+ */
+export class HeaderValidationError extends NextRushError {
+  constructor(message: string) {
+    super(message, { status: 500, code: 'HEADER_VALIDATION_ERROR', expose: false });
+  }
+}

package/src/http-errors.ts

@@ -16,6 +16,12 @@ export interface HttpErrorOptions {
   expose?: boolean;
   details?: Record<string, unknown>;
   cause?: unknown;
+  /** Correlation/request identifier (audit E-5). */
+  requestId?: string;
+  /** Distributed-trace identifier (audit E-5). */
+  traceId?: string;
+  /** ISO-8601 creation timestamp (audit E-5). */
+  timestamp?: string;
 }
 
 // =============================================================================

package/src/index.ts

@@ -9,6 +9,12 @@
 // Base classes
 export { HttpError, NextRushError, getHttpStatusMessage } from './base';
 
+// Header validation
+export { HeaderValidationError } from './header-validation';
+
+// Central error-code registry
+export { ERROR_CODES, GENERIC_ERROR_CODE, VALIDATION_ERROR_CODE, codeForStatus } from './codes';
+
 // HTTP errors - 4xx
 export {
   BadRequestError,
@@ -91,11 +97,4 @@ export {
 } from './factory';
 
 // Middleware
-export {
-  catchAsync,
-  errorHandler,
-  notFoundHandler,
-  type ErrorContext,
-  type ErrorHandlerOptions,
-  type ErrorMiddleware,
-} from './middleware';
+export { errorHandler, notFoundHandler, type ErrorHandlerOptions } from './middleware';

package/src/middleware.ts

@@ -7,29 +7,9 @@
  */
 
 import type { Context, Middleware, Next } from '@nextrush/types';
+import { SECURITY_AUDIT, type SecurityAuditVerdict } from '@nextrush/types';
 import { HttpError, NextRushError, getHttpStatusMessage } from './base';
 
-/**
- * Minimal context interface for error handling.
- *
- * @deprecated Use `Context` from `@nextrush/types` instead.
- * Kept for backward compatibility — will be removed in v4.
- */
-export interface ErrorContext {
-  method: string;
-  path: string;
-  status: number;
-  json: (data: unknown) => void;
-}
-
-/**
- * Error handler middleware function type.
- *
- * @deprecated Use `Middleware` from `@nextrush/types` instead.
- * Kept for backward compatibility — will be removed in v4.
- */
-export type ErrorMiddleware = Middleware;
-
 /**
  * Error handler options
  */
@@ -37,6 +17,21 @@ export interface ErrorHandlerOptions {
   /** Include stack trace in development */
   includeStack?: boolean;
 
+  /**
+   * Whether the application is running in production (SEC-14).
+   *
+   * @remarks
+   * `@nextrush/errors` has no access to `app.isProduction` on its own — the
+   * caller threads it through explicitly, mirroring `@nextrush/core`'s
+   * `writeDefaultErrorResponse(opts.isProduction)`. When `true`, a truthy
+   * `includeStack` is ignored (fail closed) and a single warning is logged
+   * once per process, rather than once per request. Defaults to `false` so
+   * existing callers that don't pass this option keep today's behavior.
+   *
+   * @default false
+   */
+  isProduction?: boolean;
+
   /** Custom error logger */
   logger?: (error: Error, ctx: Context) => void;
 
@@ -75,9 +70,14 @@ function defaultLogger(error: Error, ctx: Context): void {
  * ```
  */
 export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
-  const { includeStack = false, logger = defaultLogger, transform, handlers } = options;
+  const { includeStack = false, isProduction = false, logger = defaultLogger, transform, handlers } = options;
 
-  return async (ctx: Context, next: Next): Promise<void> => {
+  // SEC-14: warn once per process, not once per request — a per-request
+  // warning on a hot error path floods logs for no added value once the
+  // misconfiguration is known.
+  let warnedIncludeStackInProduction = false;
+
+  const handler: Middleware = async (ctx: Context, next: Next): Promise<void> => {
     try {
       await next();
     } catch (error) {
@@ -116,6 +116,12 @@ export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
 
       if (transform) {
         body = transform(err, ctx);
+      } else if (err instanceof NextRushError) {
+        // Delegate to the error's own toJSON() — this is the single source of
+        // truth for what a given error type serializes to (e.g. ValidationError
+        // adds `issues` while stripping `received`). Duplicating that shape here
+        // would silently drift out of sync with subclass overrides.
+        body = err.toJSON();
       } else {
         body = {
           error: expose ? err.name : getHttpStatusMessage(status),
@@ -127,8 +133,21 @@ export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
         if (expose && details) {
           body.details = details;
         }
+      }
 
-        if (includeStack && err.stack) {
+      if (includeStack && err.stack) {
+        // SEC-14: fail closed — a stack trace is ignored in production
+        // regardless of the caller's configuration, since it maps internal
+        // paths, package layout, and dependency versions for the client.
+        if (isProduction) {
+          if (!warnedIncludeStackInProduction) {
+            warnedIncludeStackInProduction = true;
+            console.warn(
+              '[@nextrush/errors] includeStack: true was ignored because isProduction is true. ' +
+                'Stack traces are never emitted in production regardless of configuration.'
+            );
+          }
+        } else {
           body.stack = err.stack.split('\n').map((line) => line.trim());
         }
       }
@@ -136,6 +155,34 @@ export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
       ctx.json(body);
     }
   };
+
+  /**
+   * Boot-time verdict for `includeStack: true` (task 8.1): the per-request
+   * guard (SEC-14, line ~140 above) only fires when `isProduction` is
+   * explicitly passed to this call — an app that never threads
+   * `app.options.env` through never gets that guard's warning even in a real
+   * production deployment. This is the gap the boot audit closes.
+   */
+  function auditVerdict(): SecurityAuditVerdict {
+    if (includeStack && !isProduction) {
+      return {
+        level: 'warn',
+        message:
+          'errorHandler({ includeStack: true }) was constructed without isProduction — the ' +
+          'per-request guard that ignores includeStack in production never fires unless ' +
+          "isProduction is explicitly threaded through (e.g. isProduction: app.isProduction). " +
+          'Wire it, or this instance will leak stack traces in production.',
+      };
+    }
+    return { level: 'ok' };
+  }
+
+  Object.defineProperty(handler, SECURITY_AUDIT, {
+    value: auditVerdict,
+    enumerable: false,
+  });
+
+  return handler;
 }
 
 /**
@@ -162,22 +209,3 @@ export function notFoundHandler(message = 'Not Found'): Middleware {
   };
 }
 
-/**
- * Catch async errors wrapper for route handlers
- *
- * @example
- * ```typescript
- * router.get('/users/:id', catchAsync(async (ctx) => {
- *   const user = await db.users.findById(ctx.params.id);
- *   if (!user) throw new NotFoundError('User not found');
- *   ctx.json(user);
- * }));
- * ```
- *
- * @deprecated This wrapper is redundant — async errors propagate naturally
- * through the middleware chain and are caught by `errorHandler()`. Use the
- * handler directly instead.
- */
-export function catchAsync(handler: (ctx: Context, next: Next) => Promise<void>): Middleware {
-  return handler;
-}

package/src/validation.ts

@@ -37,7 +37,8 @@ export class ValidationError extends NextRushError {
       code: 'VALIDATION_ERROR',
       expose: true,
     });
-    this.issues = issues;
+    // Freeze a snapshot so issues are immutable after construction (audit E-6).
+    this.issues = Object.freeze([...issues]) as ValidationIssue[];
   }
 
   /**