@nextrush/errors 3.0.7 → 4.0.0-beta.1

package/src/__tests__/middleware.test.ts

@@ -5,7 +5,8 @@
 import type { Context } from '@nextrush/types';
 import { describe, expect, it, vi } from 'vitest';
 import { BadRequestError, InternalServerError, NotFoundError } from '../http-errors';
-import { catchAsync, errorHandler, notFoundHandler } from '../middleware';
+import { errorHandler, notFoundHandler } from '../middleware';
+import { ValidationError } from '../validation';
 
 function createMockContext(): Context {
   const ctx = {
@@ -119,6 +120,88 @@ describe('errorHandler', () => {
       const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
       expect(jsonCall.stack).toBeUndefined();
     });
+
+    // SEC-14: includeStack: true must be a no-op in production, not honored
+    // unconditionally — a stack trace is a map of internal paths/dependency
+    // versions, and the previous behavior handed that map to any client the
+    // moment a deploy forgot to flip includeStack off.
+    describe('production guard (SEC-14)', () => {
+      it('ignores includeStack: true in production and logs exactly one warning', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const handler = errorHandler({ includeStack: true, isProduction: true });
+        const ctx = createMockContext();
+
+        await handler(ctx, async () => {
+          throw new BadRequestError('Invalid');
+        });
+
+        const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+        expect(jsonCall.stack).toBeUndefined();
+        // The default 4xx logger also calls console.warn — isolate the
+        // SEC-14 guard's own warning by content rather than call count.
+        const sec14Warnings = warnSpy.mock.calls.filter((call) =>
+          String(call[0]).includes('includeStack')
+        );
+        expect(sec14Warnings).toHaveLength(1);
+        warnSpy.mockRestore();
+      });
+
+      it('warns only once across multiple requests in production, not once per request', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const handler = errorHandler({ includeStack: true, isProduction: true });
+
+        for (let i = 0; i < 3; i++) {
+          const ctx = createMockContext();
+          await handler(ctx, async () => {
+            throw new BadRequestError('Invalid');
+          });
+        }
+
+        const sec14Warnings = warnSpy.mock.calls.filter((call) =>
+          String(call[0]).includes('includeStack')
+        );
+        expect(sec14Warnings).toHaveLength(1);
+        warnSpy.mockRestore();
+      });
+
+      it('preserves development behavior — stack is present when isProduction is false', async () => {
+        const handler = errorHandler({ includeStack: true, isProduction: false });
+        const ctx = createMockContext();
+
+        await handler(ctx, async () => {
+          throw new BadRequestError('Invalid');
+        });
+
+        const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+        expect(jsonCall.stack).toBeDefined();
+      });
+
+      it('preserves development behavior when isProduction is omitted (default)', async () => {
+        const handler = errorHandler({ includeStack: true });
+        const ctx = createMockContext();
+
+        await handler(ctx, async () => {
+          throw new BadRequestError('Invalid');
+        });
+
+        const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+        expect(jsonCall.stack).toBeDefined();
+      });
+
+      it('a plain (non-HttpError) Error never exposes its message in production, with or without includeStack', async () => {
+        const handler = errorHandler({ includeStack: true, isProduction: true });
+        const ctx = createMockContext();
+
+        await handler(ctx, async () => {
+          throw new Error('internal db connection string: postgres://secret');
+        });
+
+        const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+        expect(jsonCall.stack).toBeUndefined();
+        expect(JSON.stringify(jsonCall)).not.toContain('postgres://secret');
+        expect(jsonCall.message).toBe('Internal Server Error');
+      });
+    });
   });
 
   describe('logger option', () => {
@@ -177,6 +260,42 @@ describe('errorHandler', () => {
     });
   });
 
+  describe('ValidationError serialization (regression)', () => {
+    it('includes `issues` in the response body for a ValidationError', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new ValidationError([
+          { path: 'body.email', message: 'Invalid email address' },
+          { path: 'body.name', message: 'Name is required' },
+        ]);
+      });
+
+      const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(jsonCall.issues).toEqual([
+        { path: 'body.email', message: 'Invalid email address' },
+        { path: 'body.name', message: 'Name is required' },
+      ]);
+      expect(jsonCall.code).toBe('VALIDATION_ERROR');
+      expect(ctx.status).toBe(400);
+    });
+
+    it('never leaks the raw `received` value for a ValidationError', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new ValidationError([
+          { path: 'body.password', message: 'Invalid', received: 'super-secret-value' },
+        ]);
+      });
+
+      const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(JSON.stringify(jsonCall)).not.toContain('super-secret-value');
+    });
+  });
+
   describe('handlers option', () => {
     it('should use custom handler for specific error type', async () => {
       const customHandler = vi.fn();
@@ -303,38 +422,6 @@ describe('notFoundHandler', () => {
   });
 });
 
-describe('catchAsync', () => {
-  it('should pass through successful handlers', async () => {
-    const innerHandler = vi.fn().mockResolvedValue(undefined);
-    const handler = catchAsync(innerHandler);
-    const ctx = createMockContext();
-
-    await handler(ctx, noop);
-
-    expect(innerHandler).toHaveBeenCalledWith(ctx, noop);
-  });
-
-  it('should re-throw errors', async () => {
-    const error = new NotFoundError('Not found');
-    const innerHandler = vi.fn().mockRejectedValue(error);
-    const handler = catchAsync(innerHandler);
-    const ctx = createMockContext();
-
-    await expect(handler(ctx, noop)).rejects.toThrow(error);
-  });
-
-  it('should pass next to inner handler', async () => {
-    const innerHandler = vi.fn().mockResolvedValue(undefined);
-    const handler = catchAsync(innerHandler);
-    const ctx = createMockContext();
-    const next = vi.fn();
-
-    await handler(ctx, next);
-
-    expect(innerHandler).toHaveBeenCalledWith(ctx, next);
-  });
-});
-
 describe('Integration scenarios', () => {
   it('should work with errorHandler and notFoundHandler together', async () => {
     const errHandler = errorHandler();

package/src/__tests__/public-surface.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @nextrush/errors - Public API surface test
+ *
+ * Locks the exported symbol set from `src/index.ts`. If this test fails, the
+ * public API has changed. Intentional changes require an explicit update to
+ * the expected list below, plus a changeset for a published package.
+ */
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import * as errorsApi from '../index';
+import type { ErrorHandlerOptions } from '../index';
+import type { HttpErrorOptions } from '../index';
+import type { ValidationIssue } from '../index';
+
+describe('Public API surface (runtime exports)', () => {
+  it('exports exactly the intended runtime symbols', () => {
+    const actualExports = Object.keys(errorsApi).sort();
+
+    // SEALED: intentional public runtime API surface.
+    const expectedRuntime = [
+      // Base classes + helper
+      'HttpError',
+      'NextRushError',
+      'getHttpStatusMessage',
+
+      // Header validation
+      'HeaderValidationError',
+
+      // Central error-code registry
+      'ERROR_CODES',
+      'GENERIC_ERROR_CODE',
+      'VALIDATION_ERROR_CODE',
+      'codeForStatus',
+
+      // HTTP errors — 4xx
+      'BadRequestError',
+      'ConflictError',
+      'ExpectationFailedError',
+      'FailedDependencyError',
+      'ForbiddenError',
+      'GoneError',
+      'ImATeapotError',
+      'LengthRequiredError',
+      'LockedError',
+      'MethodNotAllowedError',
+      'NotAcceptableError',
+      'NotFoundError',
+      'PayloadTooLargeError',
+      'PaymentRequiredError',
+      'PreconditionFailedError',
+      'PreconditionRequiredError',
+      'ProxyAuthRequiredError',
+      'RangeNotSatisfiableError',
+      'RequestHeaderFieldsTooLargeError',
+      'RequestTimeoutError',
+      'TooEarlyError',
+      'TooManyRequestsError',
+      'UnauthorizedError',
+      'UnavailableForLegalReasonsError',
+      'UnprocessableEntityError',
+      'UnsupportedMediaTypeError',
+      'UpgradeRequiredError',
+      'UriTooLongError',
+
+      // HTTP errors — 5xx
+      'BadGatewayError',
+      'GatewayTimeoutError',
+      'HttpVersionNotSupportedError',
+      'InsufficientStorageError',
+      'InternalServerError',
+      'LoopDetectedError',
+      'NetworkAuthRequiredError',
+      'NotExtendedError',
+      'NotImplementedError',
+      'ServiceUnavailableError',
+      'VariantAlsoNegotiatesError',
+
+      // Validation errors
+      'InvalidEmailError',
+      'InvalidUrlError',
+      'LengthError',
+      'PatternError',
+      'RangeValidationError',
+      'RequiredFieldError',
+      'TypeMismatchError',
+      'ValidationError',
+
+      // Factory functions
+      'badGateway',
+      'badRequest',
+      'conflict',
+      'createError',
+      'forbidden',
+      'gatewayTimeout',
+      'getErrorStatus',
+      'getSafeErrorMessage',
+      'internalError',
+      'isHttpError',
+      'methodNotAllowed',
+      'notFound',
+      'serviceUnavailable',
+      'tooManyRequests',
+      'unauthorized',
+      'unprocessableEntity',
+
+      // Middleware
+      'errorHandler',
+      'notFoundHandler',
+    ].sort();
+
+    expect(actualExports).toEqual(expectedRuntime);
+  });
+});
+
+describe('Public API surface (type-only exports)', () => {
+  it('the type-only surface stays importable from the barrel', () => {
+    // Compile-time only: removing/renaming any of these in src/index.ts fails
+    // this file to type-check.
+    type Surface = [HttpErrorOptions, ValidationIssue, ErrorHandlerOptions];
+    expectTypeOf<Surface>().not.toBeNever();
+  });
+});

package/src/__tests__/security-audit-contribution.test.ts

@@ -0,0 +1,40 @@
+/**
+ * @nextrush/errors - Boot-time security audit contribution (task 8.1/8.2)
+ *
+ * `errorHandler()` tags its returned middleware with a {@link SECURITY_AUDIT}
+ * check so `Application.ready()` warns, in production, when `includeStack:
+ * true` was configured but `isProduction` was never wired to this instance —
+ * the per-request guard (task 7.8) only fires when the caller explicitly
+ * passes `isProduction: true`, so an app that forgets to thread it never
+ * gets the per-request warning even in a real production deployment. The
+ * boot audit catches exactly that omission.
+ */
+import { describe, expect, it } from 'vitest';
+import { SECURITY_AUDIT, type SecurityAuditCheck } from '@nextrush/types';
+import { errorHandler } from '../middleware';
+
+function auditOf(mw: unknown): SecurityAuditCheck {
+  const check = (mw as Record<typeof SECURITY_AUDIT, SecurityAuditCheck>)[SECURITY_AUDIT];
+  expect(typeof check).toBe('function');
+  return check;
+}
+
+describe('errorHandler() — security-boundaries boot audit contribution', () => {
+  it('reports a warn-level verdict for includeStack: true with isProduction never wired', () => {
+    const mw = errorHandler({ includeStack: true });
+    const verdict = auditOf(mw)();
+
+    expect(verdict.level).toBe('warn');
+    expect(verdict).toMatchObject({ message: expect.stringContaining('includeStack') });
+  });
+
+  it('reports ok when includeStack: true is paired with an explicit isProduction', () => {
+    const mw = errorHandler({ includeStack: true, isProduction: true });
+    expect(auditOf(mw)()).toEqual({ level: 'ok' });
+  });
+
+  it('reports ok for the default options (includeStack: false)', () => {
+    const mw = errorHandler();
+    expect(auditOf(mw)()).toEqual({ level: 'ok' });
+  });
+});

package/src/base.ts

@@ -6,10 +6,52 @@
  * @packageDocumentation
  */
 
+import { codeForStatus } from './codes';
+
+/** Options accepted by {@link NextRushError.hydrate} when reconstructing errors. */
+interface HydrateOptions {
+  status?: number;
+  code?: string;
+  details?: Record<string, unknown>;
+  requestId?: string;
+  traceId?: string;
+  timestamp?: string;
+}
+
 const V8Error = Error as ErrorConstructor & {
   captureStackTrace?: (targetObject: object, constructorOpt?: Function) => void;
 };
 
+/** Maximum depth walked when serializing a `cause` chain (audit E-2). */
+const MAX_CAUSE_DEPTH = 5;
+
+/**
+ * Serialize an error `cause` chain into a plain, JSON-safe object.
+ *
+ * @remarks
+ * Walks nested `cause` links up to {@link MAX_CAUSE_DEPTH}, guards against
+ * cyclic chains via a visited set, and only surfaces `name`/`message`/`code`
+ * so no unexpected enumerable properties (or secrets on ad-hoc error objects)
+ * leak. Returns `undefined` when there is nothing meaningful to serialize.
+ */
+function serializeCause(cause: unknown, seen: Set<unknown>, depth: number): unknown {
+  if (cause === undefined || cause === null || depth >= MAX_CAUSE_DEPTH) return undefined;
+  if (typeof cause !== 'object') return { message: String(cause) };
+  if (seen.has(cause)) return undefined; // cycle guard
+  seen.add(cause);
+
+  const err = cause as { name?: unknown; message?: unknown; code?: unknown; cause?: unknown };
+  const out: Record<string, unknown> = {};
+  if (typeof err.name === 'string') out.name = err.name;
+  if (typeof err.message === 'string') out.message = err.message;
+  if (typeof err.code === 'string') out.code = err.code;
+
+  const nested = serializeCause(err.cause, seen, depth + 1);
+  if (nested !== undefined) out.cause = nested;
+
+  return out;
+}
+
 /**
  * Base error class for all NextRush errors
  */
@@ -29,6 +71,15 @@ export class NextRushError extends Error {
   /** Original error that caused this error */
   readonly cause?: unknown;
 
+  /** Correlation/request identifier for tracing across boundaries (audit E-5). */
+  readonly requestId?: string;
+
+  /** Distributed-trace identifier (audit E-5). */
+  readonly traceId?: string;
+
+  /** ISO-8601 timestamp of when the error was created, when supplied. */
+  readonly timestamp?: string;
+
   constructor(
     message: string,
     options: {
@@ -37,15 +88,25 @@ export class NextRushError extends Error {
       expose?: boolean;
       details?: Record<string, unknown>;
       cause?: unknown;
+      requestId?: string;
+      traceId?: string;
+      timestamp?: string;
     } = {}
   ) {
-    super(message);
+    // Pass cause to the native Error constructor so `util.inspect` / logging
+    // tooling walks the chain natively, in addition to our own `cause` field.
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
     this.name = this.constructor.name;
     this.status = options.status ?? 500;
     this.code = options.code ?? 'INTERNAL_ERROR';
     this.expose = options.expose ?? this.status < 500;
-    this.details = options.details;
+    // Freeze a shallow snapshot so the error owns immutable details and the
+    // caller's object cannot be mutated through the error (audit E-6).
+    this.details = options.details ? Object.freeze({ ...options.details }) : undefined;
     this.cause = options.cause;
+    this.requestId = options.requestId;
+    this.traceId = options.traceId;
+    this.timestamp = options.timestamp;
 
     // Maintain proper stack trace for V8
     // Skip for common client errors (4xx with expose=true) to reduce overhead.
@@ -71,9 +132,66 @@ export class NextRushError extends Error {
       json.details = this.details;
     }
 
+    // Surface the cause chain for diagnosability, but only on exposed errors —
+    // a non-exposed 5xx cause may contain internal detail (audit E-2). Server
+    // -side logging should read `error.cause` directly, which is never gated.
+    if (this.expose && this.cause !== undefined) {
+      const serialized = serializeCause(this.cause, new Set(), 0);
+      if (serialized !== undefined) {
+        json.cause = serialized;
+      }
+    }
+
+    // Correlation identifiers are safe to surface and are the primary handle
+    // for cross-service debugging (audit E-5). Only emitted when set, so the
+    // default serialized shape is unchanged.
+    if (this.requestId !== undefined) json.requestId = this.requestId;
+    if (this.traceId !== undefined) json.traceId = this.traceId;
+    if (this.timestamp !== undefined) json.timestamp = this.timestamp;
+
     return json;
   }
 
+  /**
+   * Reconstruct a {@link NextRushError} from a serialized {@link toJSON} payload
+   * (audit E-7).
+   *
+   * @remarks
+   * Enables cross-service transport: a downstream service can rebuild a typed
+   * error (with a working `instanceof NextRushError`) from the JSON it received,
+   * rather than being left with an opaque plain object. `message` falls back to
+   * a generic string when the source error was not exposed.
+   *
+   * @param json - A payload previously produced by {@link toJSON}.
+   * @returns A reconstructed {@link NextRushError}.
+   */
+  static fromJSON(json: Record<string, unknown>): NextRushError {
+    return NextRushError.hydrate(json, (message, options) => new NextRushError(message, options));
+  }
+
+  /**
+   * Shared hydration logic for {@link fromJSON} across the hierarchy.
+   * @internal
+   */
+  protected static hydrate<T extends NextRushError>(
+    json: Record<string, unknown>,
+    build: (message: string, options: HydrateOptions) => T
+  ): T {
+    const status = typeof json.status === 'number' ? json.status : 500;
+    const message = typeof json.message === 'string' ? json.message : getHttpStatusMessage(status);
+    return build(message, {
+      status,
+      code: typeof json.code === 'string' ? json.code : undefined,
+      details:
+        json.details !== null && typeof json.details === 'object'
+          ? (json.details as Record<string, unknown>)
+          : undefined,
+      requestId: typeof json.requestId === 'string' ? json.requestId : undefined,
+      traceId: typeof json.traceId === 'string' ? json.traceId : undefined,
+      timestamp: typeof json.timestamp === 'string' ? json.timestamp : undefined,
+    });
+  }
+
   /**
    * Create a response-safe version of the error
    */
@@ -149,14 +267,41 @@ export class HttpError extends NextRushError {
       expose?: boolean;
       details?: Record<string, unknown>;
       cause?: unknown;
+      requestId?: string;
+      traceId?: string;
+      timestamp?: string;
     } = {}
   ) {
     super(message ?? getHttpStatusMessage(status), {
       status,
-      code: options.code ?? `HTTP_${status}`,
+      code: options.code ?? codeForStatus(status),
       expose: options.expose ?? status < 500,
       details: options.details,
       cause: options.cause,
+      requestId: options.requestId,
+      traceId: options.traceId,
+      timestamp: options.timestamp,
     });
   }
+
+  /**
+   * Reconstruct an {@link HttpError} from a serialized {@link NextRushError.toJSON}
+   * payload (audit E-7).
+   *
+   * @param json - A payload previously produced by `toJSON()`.
+   * @returns A reconstructed {@link HttpError}.
+   */
+  static override fromJSON(json: Record<string, unknown>): HttpError {
+    return NextRushError.hydrate(
+      json,
+      (message, options) =>
+        new HttpError(options.status ?? 500, message, {
+          code: options.code,
+          details: options.details,
+          requestId: options.requestId,
+          traceId: options.traceId,
+          timestamp: options.timestamp,
+        })
+    );
+  }
 }

package/src/codes.ts

@@ -0,0 +1,77 @@
+/**
+ * @nextrush/errors - Central Error Code Registry
+ *
+ * Single source of truth mapping HTTP status codes to their canonical,
+ * machine-readable error codes (audit E-4). Both the typed error classes and
+ * the {@link createError} factory resolve codes through this registry, so a
+ * given status maps to exactly one code regardless of construction path.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Canonical error code for each supported HTTP status.
+ *
+ * @remarks
+ * Keep this in sync with the typed classes in `http-errors.ts`. The
+ * `audit-fixes` test suite asserts `createError(status).code === ERROR_CODES[status]`
+ * for every entry, so drift between a class and this registry fails CI.
+ */
+export const ERROR_CODES: Readonly<Record<number, string>> = Object.freeze({
+  400: 'BAD_REQUEST',
+  401: 'UNAUTHORIZED',
+  402: 'PAYMENT_REQUIRED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  405: 'METHOD_NOT_ALLOWED',
+  406: 'NOT_ACCEPTABLE',
+  407: 'PROXY_AUTH_REQUIRED',
+  408: 'REQUEST_TIMEOUT',
+  409: 'CONFLICT',
+  410: 'GONE',
+  411: 'LENGTH_REQUIRED',
+  412: 'PRECONDITION_FAILED',
+  413: 'PAYLOAD_TOO_LARGE',
+  414: 'URI_TOO_LONG',
+  415: 'UNSUPPORTED_MEDIA_TYPE',
+  416: 'RANGE_NOT_SATISFIABLE',
+  417: 'EXPECTATION_FAILED',
+  418: 'IM_A_TEAPOT',
+  422: 'UNPROCESSABLE_ENTITY',
+  423: 'LOCKED',
+  424: 'FAILED_DEPENDENCY',
+  425: 'TOO_EARLY',
+  426: 'UPGRADE_REQUIRED',
+  428: 'PRECONDITION_REQUIRED',
+  429: 'TOO_MANY_REQUESTS',
+  431: 'REQUEST_HEADER_FIELDS_TOO_LARGE',
+  451: 'UNAVAILABLE_FOR_LEGAL_REASONS',
+  500: 'INTERNAL_SERVER_ERROR',
+  501: 'NOT_IMPLEMENTED',
+  502: 'BAD_GATEWAY',
+  503: 'SERVICE_UNAVAILABLE',
+  504: 'GATEWAY_TIMEOUT',
+  505: 'HTTP_VERSION_NOT_SUPPORTED',
+  506: 'VARIANT_ALSO_NEGOTIATES',
+  507: 'INSUFFICIENT_STORAGE',
+  508: 'LOOP_DETECTED',
+  510: 'NOT_EXTENDED',
+  511: 'NETWORK_AUTH_REQUIRED',
+});
+
+/**
+ * Resolve the canonical error code for an HTTP status.
+ *
+ * @param status - HTTP status code.
+ * @returns The registered canonical code, or `HTTP_<status>` for statuses with
+ *   no dedicated class.
+ */
+export function codeForStatus(status: number): string {
+  return ERROR_CODES[status] ?? `HTTP_${status}`;
+}
+
+/** Generic internal-error code used when no status-specific code applies. */
+export const GENERIC_ERROR_CODE = 'INTERNAL_ERROR';
+
+/** Canonical code for validation failures. */
+export const VALIDATION_ERROR_CODE = 'VALIDATION_ERROR';