@zudojs/errors 1.3.2 → 1.4.0

package/dist/utils/errorSerializer.core.js

@@ -2,10 +2,11 @@
  * Converts errors into safe, predictable serialized structures.
  */
 import { BaseError } from "../base/core/baseError.core.js";
-import { pickErrorMetadata, redactErrorMetadata, } from "../base/core/errorMetadata.core.js";
+import { redactErrorMetadata } from "../base/core/errorMetadata.core.js";
 import { isGenuineSerializedBaseError, MAX_CAUSE_DEPTH, toJSONWithFrame, } from "../base/core/baseError.serialize.js";
 import { redactCauseFields, redactCauseValue, } from "../base/core/errorCause.redact.js";
 import { normalizeUnknownError } from "./errorSerializer.factory.js";
+import { selectPublicIssues, selectPublicMetadata, } from "./errorSerializer.public.js";
 export { createErrorSerializer, serializeError, serializePublicError, normalizeUnknownError, } from "./errorSerializer.factory.js";
 /** Converts errors into safe, predictable serialized structures. */
 export class ErrorSerializer {
@@ -16,6 +17,7 @@ export class ErrorSerializer {
     redactSensitiveData;
     sensitiveKeyPattern;
     publicMetadataKeys;
+    exposeMetadata;
     constructor(options = {}) {
         this.includeStack = options.includeStack ?? false;
         this.includeCause = options.includeCause ?? false;
@@ -24,6 +26,7 @@ export class ErrorSerializer {
         this.redactSensitiveData = options.redactSensitiveData ?? true;
         this.sensitiveKeyPattern = options.sensitiveKeyPattern;
         this.publicMetadataKeys = options.publicMetadataKeys;
+        this.exposeMetadata = options.exposeMetadata ?? false;
     }
     /**
      * Serializes an error for internal logging or monitoring.
@@ -39,18 +42,22 @@ export class ErrorSerializer {
     /**
      * Serializes an error for an untrusted API client.
      *
-     * Never includes a stack or cause. Metadata is only included when the error
-     * is exposable (or when `publicMetadataKeys` allow-lists specific keys) and
-     * is always redacted.
+     * Never includes a stack or cause. Metadata is included only for keys
+     * allow-listed by `publicMetadataKeys`, or, with `exposeMetadata`, for
+     * errors with `expose: true`; either way it is redacted. The `issues` of an
+     * exposable validation or schema error are included with submitted values
+     * replaced by type descriptions.
      */
     serializePublic(error) {
         const metadata = this.publicMetadata(error);
+        const issues = selectPublicIssues(error);
         return {
             code: error.code,
             message: error.expose ? error.message : this.safeMessage,
             category: error.category,
             statusCode: error.statusCode,
             ...(metadata !== undefined ? { metadata } : {}),
+            ...(issues !== undefined ? { issues } : {}),
         };
     }
     /** Serializes an unknown thrown value. */
@@ -116,20 +123,12 @@ export class ErrorSerializer {
     publicMetadata(error) {
         if (!this.includeMetadata)
             return undefined;
-        let metadata;
-        if (this.publicMetadataKeys !== undefined) {
-            metadata = pickErrorMetadata(error.metadata, this.publicMetadataKeys);
-        }
-        else if (error.expose) {
-            metadata = error.metadata;
-        }
-        else {
-            return undefined;
-        }
-        const redacted = this.redactSensitiveData
-            ? this.redactMetadata(metadata)
-            : metadata;
-        return Object.keys(redacted).length > 0 ? redacted : undefined;
+        return selectPublicMetadata(error, {
+            publicMetadataKeys: this.publicMetadataKeys,
+            exposeMetadata: this.exposeMetadata,
+            redactSensitiveData: this.redactSensitiveData,
+            sensitiveKeyPattern: this.sensitiveKeyPattern,
+        });
     }
     /** Removes commonly sensitive metadata fields (recursively). */
     redactMetadata(metadata) {
@@ -138,4 +137,3 @@ export class ErrorSerializer {
         });
     }
 }
-//# sourceMappingURL=errorSerializer.core.js.map

package/dist/utils/errorSerializer.factory.d.ts

@@ -13,4 +13,3 @@ export declare function serializeError(error: BaseError, options?: ErrorSerializ
 export declare function serializePublicError(error: BaseError, options?: ErrorSerializerOptions): PublicErrorResponse;
 /** Converts an unknown thrown value into a BaseError. */
 export declare function normalizeUnknownError(value: unknown): BaseError;
-//# sourceMappingURL=errorSerializer.factory.d.ts.map

package/dist/utils/errorSerializer.factory.js

@@ -19,4 +19,3 @@ export function serializePublicError(error, options = {}) {
 export function normalizeUnknownError(value) {
     return normalizeUnknownToBaseError(value);
 }
-//# sourceMappingURL=errorSerializer.factory.js.map

package/dist/utils/errorSerializer.public.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Decides what an untrusted client may see of an error's metadata and
+ * issues. Shared by `ErrorSerializer.serializePublic` and
+ * `ErrorHandler.toPublicResult` so the two never disagree.
+ */
+import type { BaseError } from "../base/core/baseError.core.js";
+import type { ErrorMetadata } from "../base/core/errorMetadata.type.js";
+/** The options that govern public metadata selection. */
+export interface PublicMetadataPolicy {
+    /** Keys copied into the public output for every error. */
+    readonly publicMetadataKeys?: readonly string[];
+    /** Copy the whole (redacted) metadata of errors with `expose: true`. */
+    readonly exposeMetadata?: boolean;
+    /** Redact sensitive keys. Defaults to true. */
+    readonly redactSensitiveData?: boolean;
+    /** Pattern used to detect sensitive metadata keys. */
+    readonly sensitiveKeyPattern?: RegExp;
+}
+/**
+ * Metadata allowed in a public response, or `undefined` when there is none.
+ *
+ * `publicMetadataKeys` allow-lists specific keys for exposed and non-exposed
+ * errors alike. Without it, metadata is included only when `exposeMetadata`
+ * is set and the error is exposable. `expose: true` on its own reveals no
+ * metadata: it says the *message* is safe for a client, and errors routinely
+ * carry decline codes, upstream ids and internal state in the metadata of an
+ * exposed error. Until round 12 that metadata was published whenever
+ * `expose` was true.
+ */
+export declare function selectPublicMetadata(error: BaseError, policy: PublicMetadataPolicy): Readonly<ErrorMetadata> | undefined;
+/**
+ * The issue list of an exposable validation or schema error, or `undefined`.
+ *
+ * `ValidationError.issues` and `SchemaError.issues` are the part of a 400 a
+ * client actually needs, and the public serializer used to drop them. Any
+ * exposable error carrying an `issues` array qualifies, so errors from a
+ * second copy of this package are covered too. Submitted values inside the
+ * issues (`value`, `received`, `input`, `actual`) are replaced by a type
+ * description, exactly as the errors' own `toJSON()` does.
+ */
+export declare function selectPublicIssues(error: BaseError): readonly unknown[] | undefined;

package/dist/utils/errorSerializer.public.js

@@ -0,0 +1,54 @@
+/**
+ * Decides what an untrusted client may see of an error's metadata and
+ * issues. Shared by `ErrorSerializer.serializePublic` and
+ * `ErrorHandler.toPublicResult` so the two never disagree.
+ */
+import { pickErrorMetadata, redactErrorMetadata, } from "../base/core/errorMetadata.core.js";
+import { redactIssueValues, toJsonSafeIssues, } from "../domain/shared/domainError.helpers.js";
+/**
+ * Metadata allowed in a public response, or `undefined` when there is none.
+ *
+ * `publicMetadataKeys` allow-lists specific keys for exposed and non-exposed
+ * errors alike. Without it, metadata is included only when `exposeMetadata`
+ * is set and the error is exposable. `expose: true` on its own reveals no
+ * metadata: it says the *message* is safe for a client, and errors routinely
+ * carry decline codes, upstream ids and internal state in the metadata of an
+ * exposed error. Until round 12 that metadata was published whenever
+ * `expose` was true.
+ */
+export function selectPublicMetadata(error, policy) {
+    let metadata;
+    if (policy.publicMetadataKeys !== undefined) {
+        metadata = pickErrorMetadata(error.metadata, policy.publicMetadataKeys);
+    }
+    else if (policy.exposeMetadata === true && error.expose) {
+        metadata = error.metadata;
+    }
+    else {
+        return undefined;
+    }
+    const visible = policy.redactSensitiveData === false
+        ? metadata
+        : redactErrorMetadata(metadata, {
+            sensitiveKeyPattern: policy.sensitiveKeyPattern,
+        });
+    return Object.keys(visible).length > 0 ? visible : undefined;
+}
+/**
+ * The issue list of an exposable validation or schema error, or `undefined`.
+ *
+ * `ValidationError.issues` and `SchemaError.issues` are the part of a 400 a
+ * client actually needs, and the public serializer used to drop them. Any
+ * exposable error carrying an `issues` array qualifies, so errors from a
+ * second copy of this package are covered too. Submitted values inside the
+ * issues (`value`, `received`, `input`, `actual`) are replaced by a type
+ * description, exactly as the errors' own `toJSON()` does.
+ */
+export function selectPublicIssues(error) {
+    if (!error.expose)
+        return undefined;
+    const issues = error.issues;
+    if (!Array.isArray(issues) || issues.length === 0)
+        return undefined;
+    return redactIssueValues(toJsonSafeIssues(issues));
+}

package/dist/utils/errorSerializer.types.d.ts

@@ -21,10 +21,21 @@ export interface ErrorSerializerOptions {
      * Metadata keys allowed in public output.
      *
      * When provided, only these keys are copied into `PublicErrorResponse.metadata`
-     * (for exposed and non-exposed errors alike). When omitted, metadata is only
-     * included for errors with `expose: true`, and never for non-exposed errors.
+     * (for exposed and non-exposed errors alike). This is the recommended way
+     * to publish metadata: name the keys a client may see.
      */
     readonly publicMetadataKeys?: readonly string[];
+    /**
+     * Copy the whole (redacted) metadata of errors with `expose: true` into
+     * `PublicErrorResponse.metadata`. Defaults to false.
+     *
+     * This was the behaviour before round 12 and is a data-exposure risk:
+     * `expose` says the message is safe for a client, not that everything put
+     * in `metadata` (decline codes, upstream ids, internal state) is. Prefer
+     * `publicMetadataKeys`; enable this only for errors whose metadata is
+     * written for clients. Ignored when `publicMetadataKeys` is set.
+     */
+    readonly exposeMetadata?: boolean;
 }
 /** Public error representation suitable for an API response. */
 export interface PublicErrorResponse {
@@ -33,8 +44,13 @@ export interface PublicErrorResponse {
     readonly category: ErrorCategory;
     readonly statusCode: number;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * Validation or schema issues of an exposable error (`ValidationError`,
+     * `SchemaError` and any error carrying an `issues` array), with submitted
+     * values replaced by type descriptions. Absent for non-exposed errors.
+     */
+    readonly issues?: readonly unknown[];
 }
 /** Internal serialized error representation. */
 export interface InternalErrorResponse extends SerializedBaseError {
 }
-//# sourceMappingURL=errorSerializer.types.d.ts.map

package/dist/utils/errorSerializer.types.js

@@ -2,4 +2,3 @@
  * Error serializer types and interfaces.
  */
 import { ErrorCategory } from "../base/types/errorCategory.type.js";
-//# sourceMappingURL=errorSerializer.types.js.map

package/dist/utils/errorUtils.extraction.d.ts

@@ -14,4 +14,3 @@ export declare function getRootCause(value: unknown): unknown;
 export declare function getRootBaseError(value: unknown): BaseError | undefined;
 /** Extracts a plain object of useful error diagnostics. */
 export declare function getErrorDiagnostics(value: unknown): Record<string, unknown>;
-//# sourceMappingURL=errorUtils.extraction.d.ts.map

package/dist/utils/errorUtils.extraction.js

@@ -88,4 +88,3 @@ export function getErrorDiagnostics(value) {
     }
     return diagnostics;
 }
-//# sourceMappingURL=errorUtils.extraction.js.map

package/dist/utils/errorUtils.helper.d.ts

@@ -4,4 +4,3 @@
 export { isErrorLike, isOperationalError, isExposableError, isServerError, isClientError, hasErrorCategory, hasErrorSeverity, } from "./errorUtils.typeCheck.js";
 export { getErrorMessage, getErrorName, getErrorStack, getRootCause, getRootBaseError, getErrorDiagnostics, } from "./errorUtils.extraction.js";
 export { toError, withErrorContext, tryCatch, tryCatchAsync, normalizeToBaseError, } from "./errorUtils.transform.js";
-//# sourceMappingURL=errorUtils.helper.d.ts.map

package/dist/utils/errorUtils.helper.js

@@ -4,4 +4,3 @@
 export { isErrorLike, isOperationalError, isExposableError, isServerError, isClientError, hasErrorCategory, hasErrorSeverity, } from "./errorUtils.typeCheck.js";
 export { getErrorMessage, getErrorName, getErrorStack, getRootCause, getRootBaseError, getErrorDiagnostics, } from "./errorUtils.extraction.js";
 export { toError, withErrorContext, tryCatch, tryCatchAsync, normalizeToBaseError, } from "./errorUtils.transform.js";
-//# sourceMappingURL=errorUtils.helper.js.map

package/dist/utils/errorUtils.transform.d.ts

@@ -24,4 +24,3 @@ export declare function tryCatchAsync<T>(operation: () => T | Promise<T>): Promi
 }>;
 /** Converts an unknown thrown value into a BaseError. */
 export declare function normalizeToBaseError(value: unknown): BaseError;
-//# sourceMappingURL=errorUtils.transform.d.ts.map

package/dist/utils/errorUtils.transform.js

@@ -37,4 +37,3 @@ export async function tryCatchAsync(operation) {
 export function normalizeToBaseError(value) {
     return normalizeUnknownToBaseError(value);
 }
-//# sourceMappingURL=errorUtils.transform.js.map

package/dist/utils/errorUtils.typeCheck.d.ts

@@ -21,4 +21,3 @@ export declare function isClientError(value: unknown): boolean;
 export declare function hasErrorCategory(value: unknown, category: ErrorCategory): boolean;
 /** Returns whether an error has a specific severity. */
 export declare function hasErrorSeverity(value: unknown, severity: ErrorSeverity): boolean;
-//# sourceMappingURL=errorUtils.typeCheck.d.ts.map

package/dist/utils/errorUtils.typeCheck.js

@@ -40,4 +40,3 @@ export function hasErrorCategory(value, category) {
 export function hasErrorSeverity(value, severity) {
     return isBaseError(value) && value.severity === severity;
 }
-//# sourceMappingURL=errorUtils.typeCheck.js.map

package/dist/utils/index.d.ts

@@ -7,4 +7,3 @@ export * from "./errorHandler.core.js";
 export * from "./errorMapper.core.js";
 export * from "./errorSerializer.core.js";
 export * from "./errorUtils.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -7,4 +7,3 @@ export * from "./errorHandler.core.js";
 export * from "./errorMapper.core.js";
 export * from "./errorSerializer.core.js";
 export * from "./errorUtils.helper.js";
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/errors",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Shared error base class, error codes, and error handling utilities for the Zudojs framework.",
   "type": "module",
   "main": "./dist/index.js",