@zudojs/errors 1.0.1 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Shared error base class, error codes, and error handling utilities for the Zudojs framework.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-errors](https://zudojs.oyinlola.site/docs/packages-errors) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-errors.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -29,7 +35,7 @@ try {
   await work();
 } catch (thrown) {
   const error = toBaseError(thrown).withMetadata({ requestId });
-  logger.error(error.toLogObject()); // stack + cause chain, for trusted logs
+  logger.error(error.toLogObject()); // stack + cause chain, sensitive metadata redacted
   res.status(error.statusCode).json(serializePublicError(error));
   // -> { code, message, category, statusCode } — no stack, no cause,
   //    and no metadata unless the error is exposable (or keys are allow-listed)
@@ -41,8 +47,9 @@ try {
 - `BaseError` with stable `code`, `category`, `severity`, `statusCode`, `expose`, `isOperational`, deep-frozen `metadata` and `cause`
 - `ErrorCode`, `ErrorCategory` and `ErrorSeverity` enums with guards (`isErrorCode`, ...)
 - Domain, infrastructure and system error families (access, state, HTTP, database, network, container, adapter, crypto, ...) with factories and type guards
+- Base classes for other packages' error families, so their `instanceof` checks match: `TransactionError` (+ 10 subclasses), `MiddlewareLimitExceededError` / `MiddlewareDepthExceededError` / `MiddlewareRateLimitError` / `MiddlewareAbortedError`, `TraversalLimitError`, `HttpMiddlewareError` / `HttpMiddlewarePipelineError` / `HttpRequestGuardError`, `OpenAPIError`, `AuthError`, `OAuthError` (with `ErrorCode.OAUTH_*`), `CqrsError`, `ObservabilityError`, `InvalidConstantError` / `ConstantContextError`, and the `zudojs-cli` errors `CLIValidationError` / `CLIGenerationError` / `CLINotInProjectError` / `CLITemplateError`
 - `withMetadata()` copies any error (including subclasses with custom constructors) with extra metadata
-- Serialization: `toJSON()`/`toLogObject()` for trusted logs (cycle-safe cause chains), `serializePublicError` / `ErrorSerializer` / `ErrorHandler.toPublicResult` for untrusted clients (recursive redaction, metadata allow-list)
+- Serialization: `toJSON()`/`toLogObject()` for trusted logs (cycle-safe cause chains truncated with `"[MaxDepth]"` after 8 levels across the whole chain; metadata under sensitive keys, sensitive keys in object causes and submitted issue values are redacted, so `JSON.stringify(error)` is safe to log), `serializePublicError` / `ErrorSerializer` / `ErrorHandler.toPublicResult` for untrusted clients (recursive redaction, metadata allow-list)
 - Metadata utilities: `createErrorMetadata`, `mergeErrorMetadata`, `sanitizeErrorMetadata` (drops unsupported values) and `redactErrorMetadata` (removes secrets)
 - Normalization (`toBaseError`, `normalizeUnknownError`, `ErrorHandler.normalize`) that keeps the thrown value as `cause` and classifies unknown failures as internal, non-operational 500s
 - Error mapping registry (`ErrorMapperRegistry`, `mapErrorType`, declarative `ErrorMapping`)

package/dist/base/core/baseError.core.d.ts

@@ -45,11 +45,23 @@ export declare class BaseError extends Error {
      * Converts the error into a serializable representation.
      *
      * Intended for trusted internal logging: includes the stack trace and the
-     * cause chain (depth-limited and cycle-safe). Use `ErrorSerializer`
-     * (`serializePublicError`) for anything sent to an untrusted client.
+     * cause chain (cycle-safe, and truncated with `"[MaxDepth]"` after 8
+     * levels counted across the whole chain, BaseError causes included).
+     *
+     * Metadata values under sensitive keys (`password`, `authorization`,
+     * `token`, ...) and sensitive keys inside plain-object causes are replaced
+     * with `"[REDACTED]"`, because `JSON.stringify(error)` and `res.json(error)`
+     * call this implicitly. The raw values stay on `error.metadata` and
+     * `error.cause`. Use `ErrorSerializer` (`serializePublicError`) for anything
+     * sent to an untrusted client.
      */
     toJSON(): SerializedBaseError;
-    /** Returns the error as a plain object for internal logging. */
+    /**
+     * Returns the error as a plain object for internal logging.
+     *
+     * Same output as {@link BaseError.toJSON}, so sensitive metadata is
+     * redacted.
+     */
     toLogObject(): SerializedBaseError;
     /** Returns a concise error description. */
     toString(): string;
@@ -57,7 +69,9 @@ export declare class BaseError extends Error {
 /**
  * Serializes nested Error causes while avoiding recursive failures.
  *
- * Cause chains are cycle-safe and truncated after `MAX_CAUSE_DEPTH` levels.
+ * Cause chains are cycle-safe and truncated after 8 levels counted from
+ * `depth`; BaseError causes continue the count rather than restarting it.
+ * Plain-object causes are redacted.
  */
 export declare function serializeErrorCause(cause: unknown, depth?: number): SerializedBaseError | unknown;
 //# sourceMappingURL=baseError.core.d.ts.map

package/dist/base/core/baseError.core.js

@@ -1,17 +1,14 @@
 import { ErrorCategory } from "../types/errorCategory.type.js";
 import { ErrorCode } from "../types/errorCode.type.js";
 import { ErrorSeverity } from "../types/errorSeverity.type.js";
-import { createErrorMetadata, serializeErrorMetadata, } from "./errorMetadata.core.js";
+import { createErrorMetadata, redactErrorMetadata, serializeErrorMetadata, } from "./errorMetadata.core.js";
+import { beginSerializing, serializeCauseAt, takeSerializationFrame, } from "./baseError.serialize.js";
 /**
  * Brand used to recognise BaseError instances across duplicated copies of
  * this package (for example when two versions of `@zudojs/errors` are
  * installed side by side and `instanceof` fails across the boundary).
  */
 export const BASE_ERROR_BRAND = Symbol.for("@zudojs/errors.BaseError");
-/** Maximum depth of cause chains included in serialized output. */
-const MAX_CAUSE_DEPTH = 8;
-/** Errors currently being serialized (guards against cyclic cause chains). */
-const serializing = new WeakSet();
 /**
  * Base error class shared by all Zudojs application errors.
  *
@@ -97,10 +94,19 @@ export class BaseError extends Error {
      * Converts the error into a serializable representation.
      *
      * Intended for trusted internal logging: includes the stack trace and the
-     * cause chain (depth-limited and cycle-safe). Use `ErrorSerializer`
-     * (`serializePublicError`) for anything sent to an untrusted client.
+     * cause chain (cycle-safe, and truncated with `"[MaxDepth]"` after 8
+     * levels counted across the whole chain, BaseError causes included).
+     *
+     * Metadata values under sensitive keys (`password`, `authorization`,
+     * `token`, ...) and sensitive keys inside plain-object causes are replaced
+     * with `"[REDACTED]"`, because `JSON.stringify(error)` and `res.json(error)`
+     * call this implicitly. The raw values stay on `error.metadata` and
+     * `error.cause`. Use `ErrorSerializer` (`serializePublicError`) for anything
+     * sent to an untrusted client.
      */
     toJSON() {
+        const frame = takeSerializationFrame();
+        const metadata = serializeErrorMetadata(this.metadata);
         const base = {
             name: this.name,
             message: this.message,
@@ -110,23 +116,30 @@ export class BaseError extends Error {
             statusCode: this.statusCode,
             expose: this.expose,
             isOperational: this.isOperational,
-            metadata: serializeErrorMetadata(this.metadata),
+            metadata: frame.redact ? { ...redactErrorMetadata(metadata) } : metadata,
             ...(this.stack ? { stack: this.stack } : {}),
         };
         if (this.cause === undefined)
             return base;
-        if (serializing.has(this)) {
+        const release = beginSerializing(this);
+        if (release === undefined)
             return { ...base, cause: "[Circular]" };
-        }
-        serializing.add(this);
         try {
-            return { ...base, cause: serializeErrorCause(this.cause, 1) };
+            return {
+                ...base,
+                cause: serializeCauseAt(this.cause, frame.depth + 1, frame.redact, BASE_ERROR_BRAND),
+            };
         }
         finally {
-            serializing.delete(this);
+            release();
         }
     }
-    /** Returns the error as a plain object for internal logging. */
+    /**
+     * Returns the error as a plain object for internal logging.
+     *
+     * Same output as {@link BaseError.toJSON}, so sensitive metadata is
+     * redacted.
+     */
     toLogObject() {
         return this.toJSON();
     }
@@ -149,39 +162,11 @@ function normalizeStatusCode(statusCode) {
 /**
  * Serializes nested Error causes while avoiding recursive failures.
  *
- * Cause chains are cycle-safe and truncated after `MAX_CAUSE_DEPTH` levels.
+ * Cause chains are cycle-safe and truncated after 8 levels counted from
+ * `depth`; BaseError causes continue the count rather than restarting it.
+ * Plain-object causes are redacted.
  */
 export function serializeErrorCause(cause, depth = 1) {
-    if (depth > MAX_CAUSE_DEPTH)
-        return "[MaxDepth]";
-    if (cause instanceof BaseError) {
-        if (serializing.has(cause))
-            return "[Circular]";
-        return cause.toJSON();
-    }
-    if (cause instanceof Error) {
-        if (serializing.has(cause))
-            return "[Circular]";
-        serializing.add(cause);
-        try {
-            return {
-                name: cause.name,
-                message: cause.message,
-                ...(cause.stack ? { stack: cause.stack } : {}),
-                ...(cause.cause !== undefined
-                    ? { cause: serializeErrorCause(cause.cause, depth + 1) }
-                    : {}),
-            };
-        }
-        finally {
-            serializing.delete(cause);
-        }
-    }
-    if (cause !== null && typeof cause === "object") {
-        if (serializing.has(cause))
-            return "[Circular]";
-        return cause;
-    }
-    return cause;
+    return serializeCauseAt(cause, depth, true, BASE_ERROR_BRAND);
 }
 //# sourceMappingURL=baseError.core.js.map

package/dist/base/core/baseError.serialize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Depth- and redaction-aware serialization of BaseError cause chains.
+ *
+ * `BaseError.toJSON()` takes no arguments (it is called implicitly by
+ * `JSON.stringify`), and subclasses override it as
+ * `{ ...super.toJSON(), extra }`. To carry the chain depth and the redaction
+ * mode through those overrides, the caller parks a frame here immediately
+ * before invoking `toJSON()`, and `BaseError.toJSON` consumes it on entry.
+ * Serialization is synchronous, so the frame cannot leak across calls.
+ *
+ * Internal to `@zudojs/errors`: not re-exported from the package barrel.
+ *
+ * @module base/core/baseError.serialize
+ */
+/**
+ * Maximum depth of the cause chain included in serialized output, counted
+ * across the WHOLE chain (BaseError and native causes alike).
+ */
+export declare const MAX_CAUSE_DEPTH = 8;
+/** How a `toJSON()` call should serialize. */
+export interface SerializationFrame {
+    /** Depth of the error being serialized; the outermost error is 0. */
+    readonly depth: number;
+    /** Whether metadata, issues and object causes are redacted. */
+    readonly redact: boolean;
+}
+/** Structural shape of a BaseError, recognised by its `toJSON`. */
+interface JsonableError extends Error {
+    toJSON(): object;
+}
+/** Consumes the frame parked for the current `toJSON()` call. */
+export declare function takeSerializationFrame(): SerializationFrame;
+/** Marks an error as in-progress for cycle detection; returns a release. */
+export declare function beginSerializing(error: object): (() => void) | undefined;
+/**
+ * Calls `error.toJSON()` with an explicit frame and records the result as a
+ * genuine serialized BaseError.
+ */
+export declare function toJSONWithFrame(error: JsonableError, frame: SerializationFrame): Record<string, unknown>;
+/**
+ * Whether `value` came from a BaseError's `toJSON` via this module, as
+ * opposed to an arbitrary object that merely has the same field names.
+ */
+export declare function isGenuineSerializedBaseError(value: object): boolean;
+/**
+ * Serializes one cause at `depth`, carrying the depth into BaseError causes
+ * so the limit applies across the whole chain. Recursion is bounded by
+ * {@link MAX_CAUSE_DEPTH}, so even a 20 000-deep chain cannot overflow the
+ * stack.
+ */
+export declare function serializeCauseAt(cause: unknown, depth: number, redact: boolean, brand: symbol): unknown;
+export {};
+//# sourceMappingURL=baseError.serialize.d.ts.map

package/dist/base/core/baseError.serialize.js

@@ -0,0 +1,109 @@
+/**
+ * Depth- and redaction-aware serialization of BaseError cause chains.
+ *
+ * `BaseError.toJSON()` takes no arguments (it is called implicitly by
+ * `JSON.stringify`), and subclasses override it as
+ * `{ ...super.toJSON(), extra }`. To carry the chain depth and the redaction
+ * mode through those overrides, the caller parks a frame here immediately
+ * before invoking `toJSON()`, and `BaseError.toJSON` consumes it on entry.
+ * Serialization is synchronous, so the frame cannot leak across calls.
+ *
+ * Internal to `@zudojs/errors`: not re-exported from the package barrel.
+ *
+ * @module base/core/baseError.serialize
+ */
+import { redactCauseValue } from "./errorCause.redact.js";
+/**
+ * Maximum depth of the cause chain included in serialized output, counted
+ * across the WHOLE chain (BaseError and native causes alike).
+ */
+export const MAX_CAUSE_DEPTH = 8;
+const DEFAULT_FRAME = Object.freeze({
+    depth: 0,
+    redact: true,
+});
+let pendingFrame;
+/** Errors currently being serialized (guards against cyclic cause chains). */
+const serializing = new WeakSet();
+/** Serialized objects genuinely produced by a BaseError's `toJSON`. */
+const producedByBaseError = new WeakSet();
+/** Consumes the frame parked for the current `toJSON()` call. */
+export function takeSerializationFrame() {
+    const frame = pendingFrame ?? DEFAULT_FRAME;
+    pendingFrame = undefined;
+    return frame;
+}
+/** Marks an error as in-progress for cycle detection; returns a release. */
+export function beginSerializing(error) {
+    if (serializing.has(error))
+        return undefined;
+    serializing.add(error);
+    return () => serializing.delete(error);
+}
+/**
+ * Calls `error.toJSON()` with an explicit frame and records the result as a
+ * genuine serialized BaseError.
+ */
+export function toJSONWithFrame(error, frame) {
+    pendingFrame = frame;
+    try {
+        const result = error.toJSON();
+        producedByBaseError.add(result);
+        return result;
+    }
+    finally {
+        pendingFrame = undefined;
+    }
+}
+/**
+ * Whether `value` came from a BaseError's `toJSON` via this module, as
+ * opposed to an arbitrary object that merely has the same field names.
+ */
+export function isGenuineSerializedBaseError(value) {
+    return producedByBaseError.has(value);
+}
+function isBaseErrorLike(value, brand) {
+    return (value instanceof Error &&
+        value[brand] === true &&
+        typeof value.toJSON === "function");
+}
+/**
+ * Serializes one cause at `depth`, carrying the depth into BaseError causes
+ * so the limit applies across the whole chain. Recursion is bounded by
+ * {@link MAX_CAUSE_DEPTH}, so even a 20 000-deep chain cannot overflow the
+ * stack.
+ */
+export function serializeCauseAt(cause, depth, redact, brand) {
+    if (depth > MAX_CAUSE_DEPTH)
+        return "[MaxDepth]";
+    if (isBaseErrorLike(cause, brand)) {
+        if (serializing.has(cause))
+            return "[Circular]";
+        return toJSONWithFrame(cause, { depth, redact });
+    }
+    if (cause instanceof Error) {
+        const release = beginSerializing(cause);
+        if (release === undefined)
+            return "[Circular]";
+        try {
+            return {
+                name: cause.name,
+                message: cause.message,
+                ...(cause.stack ? { stack: cause.stack } : {}),
+                ...(cause.cause !== undefined
+                    ? { cause: serializeCauseAt(cause.cause, depth + 1, redact, brand) }
+                    : {}),
+            };
+        }
+        finally {
+            release();
+        }
+    }
+    if (cause !== null && typeof cause === "object") {
+        if (serializing.has(cause))
+            return "[Circular]";
+        return redact ? redactCauseValue(cause, undefined) : cause;
+    }
+    return cause;
+}
+//# sourceMappingURL=baseError.serialize.js.map

package/dist/base/core/errorCause.redact.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Redaction of non-BaseError cause values (plain objects, arrays).
+ *
+ * Internal to `@zudojs/errors`: shared by `BaseError.toJSON` and
+ * `ErrorSerializer`, not re-exported from the package barrel.
+ *
+ * @module base/core/errorCause.redact
+ */
+/**
+ * Redacts sensitive keys inside a record without changing its shape:
+ * primitives, dates and class instances are kept, plain objects and arrays
+ * are walked, cycles stop at `"[Circular]"`, prototype keys are dropped.
+ *
+ * The walk is depth-bounded exactly as metadata cloning is: a subtree past
+ * {@link MAX_METADATA_DEPTH} becomes `"[MaxDepth]"`. Without that bound a
+ * parsed request body attached as a cause could overflow the stack *inside*
+ * the serializer, turning a logged error into an uncaught `RangeError`.
+ */
+export declare function redactCauseFields(fields: Record<string, unknown>, pattern: RegExp | undefined, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
+/**
+ * Redacts one cause value: arrays and plain objects are walked, every other
+ * value is returned unchanged. Walking stops at {@link MAX_METADATA_DEPTH}.
+ */
+export declare function redactCauseValue(value: unknown, pattern: RegExp | undefined, seen?: WeakSet<object>, depth?: number): unknown;
+//# sourceMappingURL=errorCause.redact.d.ts.map

package/dist/base/core/errorCause.redact.js

@@ -0,0 +1,75 @@
+/**
+ * Redaction of non-BaseError cause values (plain objects, arrays).
+ *
+ * Internal to `@zudojs/errors`: shared by `BaseError.toJSON` and
+ * `ErrorSerializer`, not re-exported from the package barrel.
+ *
+ * @module base/core/errorCause.redact
+ */
+import { isForbiddenMetadataKey, isSensitiveMetadataKey, MAX_METADATA_DEPTH, REDACTED_METADATA_VALUE, } from "./errorMetadata.core.js";
+/** Marker substituted for a cause subtree deeper than {@link MAX_METADATA_DEPTH}. */
+const MAX_DEPTH_VALUE = "[MaxDepth]";
+/** Plain objects (Object.prototype or null prototype) are walked; anything else is kept as-is. */
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Redacts sensitive keys inside a record without changing its shape:
+ * primitives, dates and class instances are kept, plain objects and arrays
+ * are walked, cycles stop at `"[Circular]"`, prototype keys are dropped.
+ *
+ * The walk is depth-bounded exactly as metadata cloning is: a subtree past
+ * {@link MAX_METADATA_DEPTH} becomes `"[MaxDepth]"`. Without that bound a
+ * parsed request body attached as a cause could overflow the stack *inside*
+ * the serializer, turning a logged error into an uncaught `RangeError`.
+ */
+export function redactCauseFields(fields, pattern, seen = new WeakSet(), depth = 0) {
+    const result = {};
+    for (const key of Object.keys(fields)) {
+        if (isForbiddenMetadataKey(key))
+            continue;
+        const sensitive = pattern === undefined
+            ? isSensitiveMetadataKey(key)
+            : isSensitiveMetadataKey(key, pattern);
+        result[key] = sensitive
+            ? REDACTED_METADATA_VALUE
+            : redactCauseValue(fields[key], pattern, seen, depth + 1);
+    }
+    return result;
+}
+/**
+ * Redacts one cause value: arrays and plain objects are walked, every other
+ * value is returned unchanged. Walking stops at {@link MAX_METADATA_DEPTH}.
+ */
+export function redactCauseValue(value, pattern, seen = new WeakSet(), depth = 0) {
+    if (Array.isArray(value)) {
+        if (depth > MAX_METADATA_DEPTH)
+            return MAX_DEPTH_VALUE;
+        if (seen.has(value))
+            return "[Circular]";
+        seen.add(value);
+        try {
+            return value.map((entry) => redactCauseValue(entry, pattern, seen, depth + 1));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (!isPlainRecord(value))
+        return value;
+    if (depth > MAX_METADATA_DEPTH)
+        return MAX_DEPTH_VALUE;
+    if (seen.has(value))
+        return "[Circular]";
+    seen.add(value);
+    try {
+        return redactCauseFields(value, pattern, seen, depth);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+//# sourceMappingURL=errorCause.redact.js.map

package/dist/base/types/errorCode.type.d.ts

@@ -114,6 +114,7 @@ export declare enum ErrorCode {
     EVENT_REGISTRY_DISPOSED = "ERR_EVENT_REGISTRY_DISPOSED",
     EVENT_BUS_DISPOSED = "ERR_EVENT_BUS_DISPOSED",
     EVENT_SUBSCRIPTION_CLOSED = "ERR_EVENT_SUBSCRIPTION_CLOSED",
+    EVENT_LISTENER_LIMIT_EXCEEDED = "ERR_EVENT_LISTENER_LIMIT_EXCEEDED",
     EVENT_TIMEOUT = "ERR_EVENT_TIMEOUT",
     EVENT_SERIALIZATION_FAILED = "ERR_EVENT_SERIALIZATION_FAILED",
     EVENT_DESERIALIZATION_FAILED = "ERR_EVENT_DESERIALIZATION_FAILED",
@@ -370,7 +371,16 @@ export declare enum ErrorCode {
     HTTP_CLIENT_REQUEST_BODY_TIMEOUT = "ERR_HTTP_CLIENT_REQUEST_BODY_TIMEOUT",
     HTTP_CLIENT_UNSUPPORTED_PROTOCOL = "ERR_HTTP_CLIENT_UNSUPPORTED_PROTOCOL",
     HTTP_CLIENT_INVALID_HEADER = "ERR_HTTP_CLIENT_INVALID_HEADER",
-    HTTP_CLIENT_INVALID_CONTENT_TYPE = "ERR_HTTP_CLIENT_INVALID_CONTENT_TYPE"
+    HTTP_CLIENT_INVALID_CONTENT_TYPE = "ERR_HTTP_CLIENT_INVALID_CONTENT_TYPE",
+    OAUTH_CONFIGURATION_INVALID = "OAUTH_CONFIGURATION_INVALID",
+    OAUTH_ENDPOINT_NOT_ALLOWED = "OAUTH_ENDPOINT_NOT_ALLOWED",
+    OAUTH_REDIRECT_URI_NOT_ALLOWED = "OAUTH_REDIRECT_URI_NOT_ALLOWED",
+    OAUTH_STATE_MISMATCH = "OAUTH_STATE_MISMATCH",
+    OAUTH_PKCE_INVALID = "OAUTH_PKCE_INVALID",
+    OAUTH_PROVIDER_REJECTED = "OAUTH_PROVIDER_REJECTED",
+    OAUTH_PROVIDER_RESPONSE_INVALID = "OAUTH_PROVIDER_RESPONSE_INVALID",
+    OAUTH_RESPONSE_TOO_LARGE = "OAUTH_RESPONSE_TOO_LARGE",
+    OAUTH_NETWORK = "OAUTH_NETWORK"
 }
 /**
  * Determines whether a value is a valid Zudojs error code.

package/dist/base/types/errorCode.type.js

@@ -120,6 +120,7 @@ export var ErrorCode;
     ErrorCode["EVENT_REGISTRY_DISPOSED"] = "ERR_EVENT_REGISTRY_DISPOSED";
     ErrorCode["EVENT_BUS_DISPOSED"] = "ERR_EVENT_BUS_DISPOSED";
     ErrorCode["EVENT_SUBSCRIPTION_CLOSED"] = "ERR_EVENT_SUBSCRIPTION_CLOSED";
+    ErrorCode["EVENT_LISTENER_LIMIT_EXCEEDED"] = "ERR_EVENT_LISTENER_LIMIT_EXCEEDED";
     ErrorCode["EVENT_TIMEOUT"] = "ERR_EVENT_TIMEOUT";
     ErrorCode["EVENT_SERIALIZATION_FAILED"] = "ERR_EVENT_SERIALIZATION_FAILED";
     ErrorCode["EVENT_DESERIALIZATION_FAILED"] = "ERR_EVENT_DESERIALIZATION_FAILED";
@@ -410,6 +411,17 @@ export var ErrorCode;
     ErrorCode["HTTP_CLIENT_UNSUPPORTED_PROTOCOL"] = "ERR_HTTP_CLIENT_UNSUPPORTED_PROTOCOL";
     ErrorCode["HTTP_CLIENT_INVALID_HEADER"] = "ERR_HTTP_CLIENT_INVALID_HEADER";
     ErrorCode["HTTP_CLIENT_INVALID_CONTENT_TYPE"] = "ERR_HTTP_CLIENT_INVALID_CONTENT_TYPE";
+    // OAuth2 client. Values match `@zudojs/auth-oauth`'s `OAuthErrorCode`
+    // strings exactly (no `ERR_` prefix) so that package can adopt them.
+    ErrorCode["OAUTH_CONFIGURATION_INVALID"] = "OAUTH_CONFIGURATION_INVALID";
+    ErrorCode["OAUTH_ENDPOINT_NOT_ALLOWED"] = "OAUTH_ENDPOINT_NOT_ALLOWED";
+    ErrorCode["OAUTH_REDIRECT_URI_NOT_ALLOWED"] = "OAUTH_REDIRECT_URI_NOT_ALLOWED";
+    ErrorCode["OAUTH_STATE_MISMATCH"] = "OAUTH_STATE_MISMATCH";
+    ErrorCode["OAUTH_PKCE_INVALID"] = "OAUTH_PKCE_INVALID";
+    ErrorCode["OAUTH_PROVIDER_REJECTED"] = "OAUTH_PROVIDER_REJECTED";
+    ErrorCode["OAUTH_PROVIDER_RESPONSE_INVALID"] = "OAUTH_PROVIDER_RESPONSE_INVALID";
+    ErrorCode["OAUTH_RESPONSE_TOO_LARGE"] = "OAUTH_RESPONSE_TOO_LARGE";
+    ErrorCode["OAUTH_NETWORK"] = "OAUTH_NETWORK";
 })(ErrorCode || (ErrorCode = {}));
 /** Precomputed set of every error code value. */
 const ERROR_CODE_VALUES = new Set(Object.values(ErrorCode));

package/dist/domain/access/authError.base.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Base authentication-package error. Defaults to 401, category
+ * `authentication`, exposed; every default can be overridden.
+ */
+import { BaseError } from "../../base/core/baseError.core.js";
+import { ErrorCategory } from "../../base/types/errorCategory.type.js";
+import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
+import type { ErrorMetadata } from "../../base/core/errorMetadata.type.js";
+/** Options accepted by {@link AuthError} and its subclasses. */
+export interface AuthErrorOptions {
+    readonly code?: ErrorCode;
+    readonly category?: ErrorCategory;
+    readonly severity?: ErrorSeverity;
+    readonly statusCode?: number;
+    readonly expose?: boolean;
+    readonly isOperational?: boolean;
+    readonly metadata?: ErrorMetadata;
+    readonly cause?: unknown;
+}
+/** Base error for all auth-related failures. */
+export declare class AuthError extends BaseError {
+    constructor(message: string, options?: AuthErrorOptions);
+}
+//# sourceMappingURL=authError.base.d.ts.map

package/dist/domain/access/authError.base.js

@@ -0,0 +1,26 @@
+/**
+ * Base authentication-package error. Defaults to 401, category
+ * `authentication`, exposed; every default can be overridden.
+ */
+import { BaseError } from "../../base/core/baseError.core.js";
+import { ErrorCategory } from "../../base/types/errorCategory.type.js";
+import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
+/** Base error for all auth-related failures. */
+export class AuthError extends BaseError {
+    constructor(message, options) {
+        super(message, {
+            code: options?.code ?? ErrorCode.AUTHENTICATION,
+            category: options?.category ?? ErrorCategory.AUTHENTICATION,
+            severity: options?.severity ?? ErrorSeverity.ERROR,
+            statusCode: options?.statusCode ?? 401,
+            expose: options?.expose ?? true,
+            ...(options?.isOperational !== undefined
+                ? { isOperational: options.isOperational }
+                : {}),
+            metadata: options?.metadata,
+            cause: options?.cause,
+        });
+    }
+}
+//# sourceMappingURL=authError.base.js.map

package/dist/domain/access/index.d.ts

@@ -6,4 +6,6 @@
 export * from "./authentication.error.js";
 export * from "./authorization.error.js";
 export * from "./rateLimit.error.js";
+export * from "./authError.base.js";
+export * from "./oauthError.base.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/domain/access/index.js

@@ -6,4 +6,6 @@
 export * from "./authentication.error.js";
 export * from "./authorization.error.js";
 export * from "./rateLimit.error.js";
+export * from "./authError.base.js";
+export * from "./oauthError.base.js";
 //# sourceMappingURL=index.js.map

package/dist/domain/access/oauthError.base.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Base OAuth2 client error, on the shared hierarchy.
+ *
+ * Matches `@zudojs/auth-oauth`'s local `OAuthError` (name, `code`,
+ * `statusCode`, `expose` defaults), so that package can extend this class
+ * instead of `Error`. Codes are the `ErrorCode.OAUTH_*` members, whose values
+ * equal that package's `OAuthErrorCode` strings.
+ */
+import { BaseError } from "../../base/core/baseError.core.js";
+/** Options accepted by {@link OAuthError}. */
+export interface OAuthErrorOptions {
+    readonly code?: string;
+    readonly statusCode?: number;
+    readonly expose?: boolean;
+    readonly cause?: unknown;
+}
+/**
+ * Base error for every OAuth2 failure. Defaults: 400, exposed, code
+ * `OAUTH_PROVIDER_REJECTED`.
+ */
+export declare class OAuthError extends BaseError {
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+//# sourceMappingURL=oauthError.base.d.ts.map

package/dist/domain/access/oauthError.base.js

@@ -0,0 +1,30 @@
+/**
+ * Base OAuth2 client error, on the shared hierarchy.
+ *
+ * Matches `@zudojs/auth-oauth`'s local `OAuthError` (name, `code`,
+ * `statusCode`, `expose` defaults), so that package can extend this class
+ * instead of `Error`. Codes are the `ErrorCode.OAUTH_*` members, whose values
+ * equal that package's `OAuthErrorCode` strings.
+ */
+import { BaseError } from "../../base/core/baseError.core.js";
+import { ErrorCategory } from "../../base/types/errorCategory.type.js";
+import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
+/**
+ * Base error for every OAuth2 failure. Defaults: 400, exposed, code
+ * `OAUTH_PROVIDER_REJECTED`.
+ */
+export class OAuthError extends BaseError {
+    constructor(message, options) {
+        super(message, {
+            code: options?.code ?? ErrorCode.OAUTH_PROVIDER_REJECTED,
+            category: ErrorCategory.AUTHENTICATION,
+            severity: ErrorSeverity.ERROR,
+            statusCode: options?.statusCode ?? 400,
+            expose: options?.expose ?? true,
+            cause: options?.cause,
+        });
+        this.name = "OAuthError";
+    }
+}
+//# sourceMappingURL=oauthError.base.js.map