@setu-ts/exceptions 0.0.0-stage → 0.10.0

package/dist/formatters/rfc9457-formatter.d.ts

@@ -0,0 +1,29 @@
+import type { ErrorHandlerFormatter } from './error-formatter.ts';
+export { ERROR_TYPE_BASE } from './problem-details.ts';
+export type { ProblemDetails } from './problem-details.ts';
+/**
+ * Format an error as RFC 9457 Problem Details.
+ *
+ * `type` is `about:blank` for problems whose only semantics are their status
+ * code, and the framework validation problem type when the error carries an
+ * `errors` extension. Every other member is assembled identically to the
+ * deprecated RFC 7807 formatter.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @returns An RFC 9457 Problem Details body
+ * @example
+ * ```typescript
+ * rfc9457Formatter(notFound('User 42 does not exist'), ctx);
+ * // {
+ * //   type: 'about:blank',
+ * //   title: 'Not Found',
+ * //   status: 404,
+ * //   detail: 'User 42 does not exist',
+ * //   instance: '/users/42',
+ * // }
+ * ```
+ * @since 0.1.0
+ */
+export declare const rfc9457Formatter: ErrorHandlerFormatter;
+//# sourceMappingURL=rfc9457-formatter.d.ts.map

package/dist/formatters/rfc9457-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfc9457-formatter.d.ts","sourceRoot":"","sources":["../../src/formatters/rfc9457-formatter.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAQlE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAmB3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,EAAE,qBAGyC,CAAC"}

package/dist/formatters/rfc9457-formatter.js

@@ -0,0 +1,43 @@
+import { ABOUT_BLANK, buildProblemDetails, VALIDATION_TYPE, } from "./problem-details.js";
+export { ERROR_TYPE_BASE } from "./problem-details.js";
+/**
+ * Resolves the RFC 9457 `type` member.
+ *
+ * An {@linkcode HttpError} carries no problem-type identity beyond its status
+ * code, so a URI minted from that status would identify nothing the `status`
+ * member does not already convey — which is exactly the case RFC 9457 §4.2
+ * registers `about:blank` for. The one exception is the body produced by
+ * `validationError()`, which defines an `errors` extension member and is
+ * therefore a distinct problem type deserving its own URI.
+ *
+ * @param _statusCode - The HTTP status code (not used; the status member carries it)
+ * @param hasErrors - Whether the error carries a validation `errors` extension
+ * @returns `about:blank`, or the validation problem type URI
+ */
+const resolveRfc9457Type = (_statusCode, hasErrors) => hasErrors ? VALIDATION_TYPE : ABOUT_BLANK;
+/**
+ * Format an error as RFC 9457 Problem Details.
+ *
+ * `type` is `about:blank` for problems whose only semantics are their status
+ * code, and the framework validation problem type when the error carries an
+ * `errors` extension. Every other member is assembled identically to the
+ * deprecated RFC 7807 formatter.
+ *
+ * @param error - The thrown error to format
+ * @param ctx - Optional request context (used for `instance`)
+ * @returns An RFC 9457 Problem Details body
+ * @example
+ * ```typescript
+ * rfc9457Formatter(notFound('User 42 does not exist'), ctx);
+ * // {
+ * //   type: 'about:blank',
+ * //   title: 'Not Found',
+ * //   status: 404,
+ * //   detail: 'User 42 does not exist',
+ * //   instance: '/users/42',
+ * // }
+ * ```
+ * @since 0.1.0
+ */
+export const rfc9457Formatter = (error, ctx) => buildProblemDetails(error, ctx, resolveRfc9457Type);
+//# sourceMappingURL=rfc9457-formatter.js.map

package/dist/formatters/rfc9457-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfc9457-formatter.js","sourceRoot":"","sources":["../../src/formatters/rfc9457-formatter.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,WAAW,EACX,mBAAmB,EAEnB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;GAaG;AACH,MAAM,kBAAkB,GAAG,CAAC,WAAmB,EAAE,SAAkB,EAAU,EAAE,CAC7E,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA0B,CACrD,KAAY,EACZ,GAAqB,EACL,EAAE,CAAC,mBAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module
+ *
+ * Exception factory functions, `HttpError`, error formatters, and the global
+ * error handler middleware.
+ *
+ * This is a **plain package** (not a plugin) — it depends on
+ * `@setu-ts/common` only and exposes types, factories, and a
+ * middleware factory. Register the middleware via the application's pipeline:
+ *
+ * ```typescript
+ * import { errorHandler } from '@setu-ts/exceptions';
+ *
+ * app.middleware.add(errorHandler({ format: 'rfc9457' }), {
+ *   priority: 0,
+ *   name: 'error-handler',
+ * });
+ * ```
+ *
+ * Every export here is public API and documented in PUBLIC_API.md
+ * (AI_GUIDELINES §10).
+ */
+export { HttpError } from './errors/http-error.ts';
+export type { HttpErrorInit, ValidationError } from './errors/http-error.ts';
+export { badRequest, conflict, forbidden, internalServerError, notFound, notImplemented, serviceUnavailable, STATUS_TITLES, statusTitle, tooManyRequests, unauthorized, validationError, } from './errors/exceptions.ts';
+export { defaultFormatter, selectFormatter } from './formatters/error-formatter.ts';
+export type { DefaultErrorBody, ErrorFormat, ErrorHandlerFormatter, } from './formatters/error-formatter.ts';
+export { ERROR_TYPE_BASE, rfc9457Formatter } from './formatters/rfc9457-formatter.ts';
+export type { ProblemDetails } from './formatters/rfc9457-formatter.ts';
+export { rfc7807Formatter } from './formatters/rfc7807-formatter.ts';
+export { errorHandler } from './middleware/error-handler.ts';
+export type { ErrorHandlerOptions } from './middleware/error-handler.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG7E,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,eAAe,EACf,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACpF,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACtF,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAGrE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @module
+ *
+ * Exception factory functions, `HttpError`, error formatters, and the global
+ * error handler middleware.
+ *
+ * This is a **plain package** (not a plugin) — it depends on
+ * `@setu-ts/common` only and exposes types, factories, and a
+ * middleware factory. Register the middleware via the application's pipeline:
+ *
+ * ```typescript
+ * import { errorHandler } from '@setu-ts/exceptions';
+ *
+ * app.middleware.add(errorHandler({ format: 'rfc9457' }), {
+ *   priority: 0,
+ *   name: 'error-handler',
+ * });
+ * ```
+ *
+ * Every export here is public API and documented in PUBLIC_API.md
+ * (AI_GUIDELINES §10).
+ */
+// Error type
+export { HttpError } from "./errors/http-error.js";
+// Exception factories
+export { badRequest, conflict, forbidden, internalServerError, notFound, notImplemented, serviceUnavailable, STATUS_TITLES, statusTitle, tooManyRequests, unauthorized, validationError, } from "./errors/exceptions.js";
+// Formatters
+export { defaultFormatter, selectFormatter } from "./formatters/error-formatter.js";
+export { ERROR_TYPE_BASE, rfc9457Formatter } from "./formatters/rfc9457-formatter.js";
+export { rfc7807Formatter } from "./formatters/rfc7807-formatter.js";
+// Middleware
+export { errorHandler } from "./middleware/error-handler.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,aAAa;AACb,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,sBAAsB;AACtB,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,eAAe,EACf,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAMpF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAEtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Global error-handler middleware factory.
+ *
+ * Returns a {@linkcode MiddlewareFunction} that wraps `next()` in a try/catch,
+ * so any error thrown by downstream middleware or the route handler is caught,
+ * logged (when a logger is registered), formatted, and sent as a JSON error
+ * response. Register it as the **outermost** middleware (lowest priority number)
+ * so it wraps the entire pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { errorHandler } from '@setu-ts/exceptions';
+ *
+ * app.middleware.add(errorHandler({
+ *   format: 'rfc9457',
+ *   includeStackTrace: config.get('NODE_ENV') === 'development',
+ *   logErrors: true,
+ * }), { priority: 0, name: 'error-handler' });
+ * ```
+ *
+ * @module
+ */
+import type { HandlerResult, IRequestContext, MiddlewareFunction } from '@setu-ts/common';
+import { HttpError } from '../errors/http-error.ts';
+import { type ErrorFormat, type ErrorHandlerFormatter } from '../formatters/error-formatter.ts';
+/**
+ * Options for the {@linkcode errorHandler} middleware factory.
+ *
+ * @since 0.1.0
+ */
+export interface ErrorHandlerOptions {
+    /**
+     * The error body format: `'default'`, `'rfc9457'`, the deprecated
+     * `'rfc7807'`, or a custom formatter function. Defaults to `'default'`.
+     */
+    readonly format?: ErrorFormat | ErrorHandlerFormatter;
+    /**
+     * When `true`, the error `stack` trace is included in the response body.
+     * **Never** enable this in production — pass a config-derived boolean (e.g.
+     * `config.get('NODE_ENV') === 'development'`), never read `process.env`
+     * directly (AI_GUIDELINES §4.1). Defaults to `false`.
+     *
+     * Note the stack is the _secondary_ disclosure: the primary one is the
+     * error **message**, which for a failed query carries the SQL and its bound
+     * parameter values. Masking that is `maskInternalErrors`' job.
+     *
+     * The two compose safely, and masking wins: an error masked by
+     * {@linkcode ErrorHandlerOptions.maskInternalErrors} carries **no** stack in
+     * the body even when this option is `true`, because a stack begins with the
+     * very message that was masked. Set `maskInternalErrors: false` to see the
+     * stack of an internal error.
+     */
+    readonly includeStackTrace?: boolean;
+    /**
+     * When `true` (the default), a caught value that was **not** an
+     * {@linkcode HttpError} and resolves to a status `>= 500` is masked in the
+     * response: its `detail`/`message` becomes the status title
+     * (`'Internal Server Error'`) and the raw message — which for a failed
+     * query carries the SQL and its bound parameter values — is dropped from the
+     * body. The log is unaffected: `logErrors` still records the unmasked error
+     * and its cause chain, so an operator loses nothing unless `logErrors` is
+     * _also_ `false`, the configuration that already logs nothing.
+     *
+     * A deliberately thrown `HttpError` is never masked — `instanceof HttpError`
+     * is the line between "the developer wrote this for a caller" and "this
+     * escaped from a driver". `false` restores the previous behaviour verbatim.
+     */
+    readonly maskInternalErrors?: boolean;
+    /**
+     * When `true` (the default), logs once at `warn` below 500 and `error`
+     * otherwise. Without a logger, only 5xx reaches runtime.reportError.
+     */
+    readonly logErrors?: boolean;
+    /**
+     * Lets the application write its own response for a caught error. The hook
+     * receives the normalized error after status hints, internal-error masking,
+     * and status resolution, so `error.statusCode` is safe to serve. Return a
+     * {@linkcode HandlerResult} produced by `ctx.response` to use that response;
+     * it may resolve that result asynchronously. Return or resolve to `undefined`
+     * to fall through to the configured formatter unchanged.
+     *
+     * The hook owns its returned response's status, headers, and body. It is
+     * called only for errors caught by this middleware, not responder-based
+     * terminals such as an unmatched-path `404`.
+     */
+    readonly respond?: (error: HttpError, ctx: IRequestContext) => HandlerResult | undefined | Promise<HandlerResult | undefined>;
+}
+/**
+ * Creates a global error-handler middleware.
+ *
+ * Behavior:
+ * 1. Calls `next()` inside a try/catch.
+ * 2. If `next()` throws an `HttpError`, its `statusCode` is used as-is.
+ * 3. If `next()` throws any other `Error`, it is wrapped in a `500`
+ *    `internalServerError` carrying the original as `cause`.
+ * 4. When configured, lets the application write its own response. A returned
+ *    or resolved `HandlerResult` short-circuits formatting; `undefined` falls
+ *    through.
+ * 5. When `logErrors` is on and a logger is registered, the unmasked error is
+ *    logged with the status the selected response serves.
+ * 6. Otherwise, formats the error via {@linkcode selectFormatter}, optionally
+ *    enriches it with a `stack` trace, and sends it with the right status and
+ *    content type. The middleware **returns a `HandlerResult`** (short-circuit)
+ *    and never re-invokes `next()`.
+ *
+ * @param options - Error handler configuration
+ * @returns A middleware function
+ * @since 0.1.0
+ */
+export declare function errorHandler(options?: ErrorHandlerOptions): MiddlewareFunction;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EACV,aAAa,EAEb,eAAe,EAEf,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAUzB,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAOpD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAE3B,MAAM,kCAAkC,CAAC;AAI1C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,qBAAqB,CAAC;IACtD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,eAAe,KACjB,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACrE;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAkK9E"}

package/dist/middleware/error-handler.js

@@ -0,0 +1,221 @@
+import { brandErrorResponder, CAPABILITIES, ERROR_RESPONDER_STATE_KEY, httpStatusHintOf, resolveResponseStatus, serializeError, } from '@setu-ts/common';
+import { HttpError } from "../errors/http-error.js";
+import { internalServerError, statusTitle } from "../errors/exceptions.js";
+import { buildErrorFromInit, createErrorResponder, thrownErrorStatus, } from "./error-responder-impl.js";
+import { selectFormatter, } from "../formatters/error-formatter.js";
+import { rfc9457Formatter } from "../formatters/rfc9457-formatter.js";
+import { rfc7807Formatter } from "../formatters/rfc7807-formatter.js";
+/** The `application/problem+json` content type for Problem Details responses. */
+const PROBLEM_JSON = 'application/problem+json';
+/** The default JSON content type. */
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+/**
+ * The formatters whose bodies are Problem Details and therefore require the
+ * `application/problem+json` media type (RFC 9457 §3).
+ *
+ * Membership is keyed on the RESOLVED formatter rather than on the format
+ * string, because both formatters are exported: `format: rfc9457Formatter`
+ * passes a reference and must carry the same media type as `format: 'rfc9457'`.
+ * A body served as `application/json` is ignored by generic problem-details
+ * clients, so a formatter missing from this set is a silent interoperability
+ * defect rather than a visible failure.
+ */
+const PROBLEM_DETAILS_FORMATTERS = new Set([
+    rfc9457Formatter,
+    rfc7807Formatter,
+]);
+/**
+ * Creates a global error-handler middleware.
+ *
+ * Behavior:
+ * 1. Calls `next()` inside a try/catch.
+ * 2. If `next()` throws an `HttpError`, its `statusCode` is used as-is.
+ * 3. If `next()` throws any other `Error`, it is wrapped in a `500`
+ *    `internalServerError` carrying the original as `cause`.
+ * 4. When configured, lets the application write its own response. A returned
+ *    or resolved `HandlerResult` short-circuits formatting; `undefined` falls
+ *    through.
+ * 5. When `logErrors` is on and a logger is registered, the unmasked error is
+ *    logged with the status the selected response serves.
+ * 6. Otherwise, formats the error via {@linkcode selectFormatter}, optionally
+ *    enriches it with a `stack` trace, and sends it with the right status and
+ *    content type. The middleware **returns a `HandlerResult`** (short-circuit)
+ *    and never re-invokes `next()`.
+ *
+ * @param options - Error handler configuration
+ * @returns A middleware function
+ * @since 0.1.0
+ */
+export function errorHandler(options) {
+    const format = options?.format ?? 'default';
+    const includeStackTrace = options?.includeStackTrace ?? false;
+    const maskInternalErrors = options?.maskInternalErrors ?? true;
+    const logErrors = options?.logErrors ?? true;
+    const respond = options?.respond;
+    const formatter = selectFormatter(format);
+    const contentType = PROBLEM_DETAILS_FORMATTERS.has(formatter) ? PROBLEM_JSON : JSON_CONTENT_TYPE;
+    // The responder is built ONCE at factory time from the formatter and content
+    // type already resolved above, and published per request below: one
+    // `Map.set` of a pre-built object, not a re-resolution (AI_GUIDELINES §14).
+    const responder = createErrorResponder(formatter, contentType);
+    const handleError = async (ctx, next) => {
+        // Publish the responder BEFORE `next()` so every site inside the pipeline
+        // — the kernel's own terminals and every short-circuiting middleware —
+        // answers in this application's configured format (M70f).
+        ctx.state.set(ERROR_RESPONDER_STATE_KEY, responder);
+        try {
+            await next();
+            return;
+        }
+        catch (rawError) {
+            // Normalize: HttpError passes through, anything else becomes a 500.
+            const isHttpError = rawError instanceof HttpError;
+            const error = isHttpError
+                ? rawError
+                : internalServerError(rawError instanceof Error ? rawError.message : 'Internal Server Error', rawError instanceof Error ? rawError : undefined);
+            // A thrower that cannot import this package states the status its own
+            // error means by branding it with an `HttpStatusHint` (M89b) — the seam
+            // `@setu-ts/database-plugin` uses for its query-shape refusals, which
+            // are caller errors and were answered as masked 500s. The hint carries
+            // its own caller-safe `detail`, so the response is built from THAT and
+            // never from the error's message, and `buildErrorFromInit` is the same
+            // constructor `respondWithError` reaches: one mapping, one body shape.
+            //
+            // Read only for a non-`HttpError`. A deliberately thrown `HttpError`
+            // already states its own status, and letting a brand override it would
+            // give one error two answers.
+            const hint = isHttpError ? undefined : httpStatusHintOf(rawError);
+            // Mask a driver-shaped 500 for the response: the raw message becomes the
+            // status title so the body carries neither the statement nor the values.
+            // A deliberately thrown HttpError is never masked, and a 4xx is left
+            // alone — only a non-HttpError with status >= 500 is rewritten.
+            //
+            // A hinted error is exempt, and the exemption is narrow by construction
+            // rather than by trust: what it serves is the hint's own `detail`, a
+            // fixed sentence the brand site wrote, never the `Error`'s message. So
+            // there is no driver diagnostic in the body for masking to remove. It is
+            // checked FIRST because a hinted 501 satisfies all three masking clauses
+            // and would otherwise be rewritten into the exact symptom this closes.
+            let responseError = error;
+            if (hint !== undefined) {
+                responseError = buildErrorFromInit(hint);
+            }
+            else if (maskInternalErrors && !isHttpError && error.statusCode >= 500) {
+                // Preserve the log's cause chain without leaking the message. `cause`
+                // is `unknown` on `Error`; only an `Error` value is a valid
+                // `HttpError` cause, so narrow rather than cast.
+                const cause = error.cause instanceof Error ? error.cause : undefined;
+                responseError = new HttpError(error.statusCode, statusTitle(error.statusCode), undefined, cause);
+            }
+            // An `HttpError` carries whatever status its thrower passed: the
+            // constructor validates nothing, and its own JSDoc says the factory
+            // functions are what "guarantee a correct status code". So
+            // `throw new HttpError(4004, ...)` — a typo for `404` — reached
+            // `response.status()` and threw `RangeError` out of the one `catch` that
+            // exists to contain throws. The status is clamped BEFORE the log and the
+            // body are built, so the logged status, the body's own status member and
+            // the written status are one number. Rebuilding rather than clamping at
+            // the write also makes `responseError === error` false, which suppresses
+            // the stack — correct by that check's own stated invariant, since the
+            // error being SERVED is no longer the error that was LOGGED.
+            const servedStatus = resolveResponseStatus(thrownErrorStatus(rawError).requested, ctx);
+            if (servedStatus !== responseError.statusCode) {
+                responseError = new HttpError(servedStatus, responseError.message, responseError.details, responseError.cause instanceof Error ? responseError.cause : undefined);
+            }
+            // The hook sees the same safe error and served status that the formatter
+            // would receive. It can perform asynchronous view rendering; only
+            // `undefined` means "use the framework formatter". A hook failure stays
+            // an application failure, but records the original caught diagnostic
+            // before it propagates to the surrounding pipeline.
+            let result;
+            try {
+                result = await respond?.(responseError, ctx);
+            }
+            catch (hookError) {
+                if (logErrors) {
+                    logError(ctx, error, responseError.statusCode);
+                }
+                throw hookError;
+            }
+            if (result !== undefined) {
+                // The application-owned result can choose a status different from the
+                // normalized error (for example a 418 HTML page for a caught 500), so
+                // inspect the completed writer rather than reporting the fallback.
+                if (logErrors) {
+                    logError(ctx, error, ctx.response.snapshot().status);
+                }
+                return result;
+            }
+            // Log the unmasked diagnostic and cause chain, with the status the
+            // formatter below will actually serve. A hint may change a normalized
+            // `500` to `501`, so logging the pre-hint status would mislead operators.
+            if (logErrors) {
+                logError(ctx, error, responseError.statusCode);
+            }
+            const body = formatter(responseError, ctx);
+            // Masking wins over `includeStackTrace`. A stack's first line is
+            // `<name>: <message>`, so attaching the unmasked error's stack would put
+            // the SQL and its bound parameter values straight back into the body that
+            // was just masked — defeating the mask through the one option documented
+            // as unsafe in production. A masked error therefore carries no stack at
+            // all; the unmasked one is in the log, where `logErrors` already sent it.
+            //
+            // The condition is `responseError === error` rather than `!masked`
+            // because a hinted response is the second case with the same property:
+            // its body deliberately carries the brand site's sentence and not the
+            // error's own text, and a stack's first line is `<name>: <message>`. So
+            // the stack is attached exactly when the error being SERVED is the error
+            // that was LOGGED, which is the invariant both exclusions want.
+            if (includeStackTrace && responseError === error && error.stack !== undefined) {
+                body.stack = error.stack;
+            }
+            // Serialize and send via `.send(bytes)` rather than `.json(body)` so
+            // the content-type header we set is not overwritten by json()'s own
+            // `application/json` default — RFC 9457 requires `application/problem+json`.
+            const bytes = new TextEncoder().encode(JSON.stringify(body));
+            return ctx.response
+                .status(responseError.statusCode)
+                .header('content-type', contentType)
+                .send(bytes);
+        }
+    };
+    // Brand the middleware with the SAME responder it publishes into `ctx.state`
+    // below, so the kernel can seed it into the state of the pre-pipeline sites
+    // — the drain `503`, the malformed-request `400`, and the request-lifecycle
+    // hooks — which run before this middleware and would otherwise always take
+    // the fallback shape (M70f re-review, findings 1 & 2).
+    brandErrorResponder(handleError, responder);
+    return handleError;
+}
+/**
+ * Logs once through the registered logger, or the runtime sink for 5xx when
+ * no logger is registered. Handled 4xx without a logger stays silent.
+ *
+ * @param ctx - The request context
+ * @param error - The error to log, carrying the unmasked message and cause
+ * @param statusCode - The status actually served, which a hint may have changed
+ */
+function logError(ctx, error, statusCode) {
+    if (!ctx.services.has(CAPABILITIES.LOGGER)) {
+        if (statusCode >= 500 && ctx.services.has(CAPABILITIES.RUNTIME)) {
+            ctx.services.get(CAPABILITIES.RUNTIME).reportError?.({
+                level: 'error',
+                ...serializeError(error),
+                statusCode,
+                requestId: ctx.id,
+                method: ctx.request.method,
+                path: ctx.request.path,
+            });
+        }
+        return;
+    }
+    const logger = ctx.services.get(CAPABILITIES.LOGGER);
+    // Serialize the cause (X2-5): a raw `Error` in log metadata renders as `{}`
+    // under `JSON.stringify` because `message`/`stack` are non-enumerable.
+    logger[statusCode < 500 ? 'warn' : 'error'](error.message, {
+        statusCode,
+        requestId: ctx.id,
+        ...(error.cause !== undefined && { cause: serializeError(error.cause) }),
+    });
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"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"}

package/dist/middleware/error-responder-impl.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The `exceptions` implementation of the request-scoped error responder seam
+ * (M70f).
+ *
+ * This module is **internal**: it is not exported from `src/index.ts`. The
+ * interface it satisfies (`IErrorResponder`), the state key, the init type, and
+ * the `respondWithError` free function all live in `@setu-ts/common`; exporting
+ * the implementation as well would give one concept two public names. A
+ * `barrel-exports.test.ts` assertion pins that it stays out of the barrel.
+ *
+ * @module
+ */
+import type { ErrorResponseInit, IErrorResponder } from '@setu-ts/common';
+import { HttpError } from '../errors/http-error.ts';
+import type { ErrorHandlerFormatter } from '../formatters/error-formatter.ts';
+/** The pure thrown-value rule, shared by serving and request-log prediction. */
+export declare function thrownErrorStatus(error: unknown): {
+    requested: number;
+    status: number;
+};
+/**
+ * Builds the {@linkcode HttpError} that carries one error response's status,
+ * title and disclosure.
+ *
+ * This is the single owner of that mapping, and it has **two** callers: the
+ * responder below, and `errorHandler`'s status-hint path (M89b), which answers
+ * a thrown error branded with an `HttpStatusHint` — a type that IS an
+ * `ErrorResponseInit`. Sharing it is what makes the two agree: a hinted throw
+ * and a `respondWithError` call carrying the same values produce byte-identical
+ * bodies under `default`, `rfc9457`, `rfc7807` and any custom formatter. A
+ * second hand-rolled construction would silently diverge — the `default`
+ * formatter reads `details.detail` while the Problem Details formatters read
+ * the {@linkcode RESPONDER_DETAIL} symbol, so getting either half wrong loses
+ * the disclosure in exactly one format.
+ *
+ * @param init - The status, title, disclosure and optional structured details
+ * @returns An `HttpError` every formatter renders with the disclosure intact
+ */
+export declare function buildErrorFromInit(init: ErrorResponseInit): HttpError;
+/**
+ * Builds an {@linkcode IErrorResponder} from the formatter and content type
+ * that `errorHandler` has **already** resolved at factory time.
+ *
+ * The responder keeps the `HttpError` construction inside the only package that
+ * owns it: it builds an `HttpError` from the init (so `buildProblemDetails` sees
+ * a real `statusCode` and the validation `errors` extension, and
+ * `maskInternalErrors` would never mask a deliberately 4xx), runs the resolved
+ * formatter over it, and writes status, `content-type` and the serialized body
+ * — the same three-step tail `errorHandler`'s catch path performs.
+ *
+ * @param formatter - The resolved error formatter
+ * @param contentType - The resolved response content type
+ * @returns A responder publishing the application's error format
+ * @since 0.1.0
+ */
+export declare function createErrorResponder(formatter: ErrorHandlerFormatter, contentType: string): IErrorResponder;
+//# sourceMappingURL=error-responder-impl.d.ts.map

package/dist/middleware/error-responder-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-responder-impl.d.ts","sourceRoot":"","sources":["../../src/middleware/error-responder-impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAEV,iBAAiB,EACjB,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAW9E,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcvF;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAiCrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,qBAAqB,EAChC,WAAW,EAAE,MAAM,GAClB,eAAe,CA2CjB"}