@cullet/erp-core 1.3.0 → 1.5.0

package/dist/app-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.js","names":[],"sources":["../src/core/errors/error-codes.ts","../src/core/errors/utils/json-safe.ts","../src/core/errors/app-error.ts"],"sourcesContent":["const ErrorCodes = {\n    authentication: {\n        missingToken: \"sec.authn.missing_token\",\n        invalidToken: \"sec.authn.invalid_token\",\n        expiredToken: \"sec.authn.expired_token\",\n        invalidCredentials: \"sec.authn.invalid_credentials\",\n    },\n    authorization: {\n        forbidden: \"sec.authz.forbidden\",\n        policyDenied: \"sec.authz.policy_denied\",\n        missingRole: \"sec.authz.missing_role\",\n        missingCapability: \"sec.authz.missing_capability\",\n        outOfScope: \"sec.authz.out_of_scope\",\n    },\n    businessRuleViolation: \"business_rule_violation\",\n    conflict: {\n        alreadyExists: \"conf.already_exists\",\n        duplicate: \"conf.duplicate\",\n        uniqueViolation: \"conf.unique_violation\",\n    },\n    idempotency: {\n        keyMissing: \"idemp.key_missing\",\n        inProgress: \"idemp.in_progress\",\n        payloadMismatch: \"idemp.payload_mismatch\",\n        replayNotSupported: \"idemp.replay_not_supported\",\n    },\n    integration: {\n        timeout: \"int.timeout\",\n        unreachable: \"int.unreachable\",\n        badResponse: \"int.bad_response\",\n    },\n    legacyIncompatible: \"legacy_incompatible\",\n    notFound: \"not_found\",\n    serialization: {\n        deserializePrefix: \"ser.des\",\n        serializePrefix: \"ser.ser\",\n    },\n    temporal: {\n        expired: \"tmp.expired\",\n        notYetValid: \"tmp.not_yet_valid\",\n    },\n    unexpected: \"unexpected\",\n    validation: \"validation_error\",\n} as const;\n\ntype SerializationCodeDirection = \"deserialize\" | \"serialize\";\n\nfunction serializationErrorCode(\n    direction: SerializationCodeDirection,\n    category: string,\n): string {\n    const prefix =\n        direction === \"deserialize\"\n            ? ErrorCodes.serialization.deserializePrefix\n            : ErrorCodes.serialization.serializePrefix;\n\n    return `${prefix}.${category}`;\n}\n\nexport { ErrorCodes, serializationErrorCode };\nexport type { SerializationCodeDirection };\n","// Utilities for ensuring metadata is JSON-serializable.\n\nimport type { JsonSafeRecord, JsonSafeValue } from \"../types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst NON_SERIALIZABLE_PLACEHOLDER = \"[NonSerializable]\";\nconst CIRCULAR_REFERENCE_PLACEHOLDER = \"[Circular]\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n    if (value === null || typeof value !== \"object\") return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n}\n\n// `seen` tracks the ancestors on the current traversal branch (a DFS path), not\n// every object visited. This collapses true circular references to a placeholder\n// while still serializing the same object referenced more than once across\n// sibling branches (a DAG) — matching `JSON.stringify`, which only rejects\n// cycles, not shared references.\nfunction sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {\n    // Null passthrough\n    if (value === null) return null;\n\n    const type = typeof value;\n\n    // Primitives (non-finite numbers are not JSON-representable — placeholder)\n    if (type === \"number\") {\n        return Number.isFinite(value)\n            ? (value as number)\n            : NON_SERIALIZABLE_PLACEHOLDER;\n    }\n    if (type === \"string\" || type === \"boolean\") {\n        return value as JsonSafeValue;\n    }\n\n    // `undefined` only reaches here as an array item: object properties with\n    // undefined values are omitted by the plain-object branch below. Both\n    // mirror `JSON.stringify` semantics.\n    if (value === undefined) return null;\n\n    // Non-serializable primitives\n    if (type === \"bigint\" || type === \"function\" || type === \"symbol\") {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Arrays (recursive)\n    if (Array.isArray(value)) {\n        if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n        seen.add(value);\n        const sanitized = value.map((item) => sanitizeValue(item, seen));\n        seen.delete(value);\n        return sanitized;\n    }\n\n    // Date → placeholder (could also use .toISOString() if preferred)\n    if (value instanceof Date) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Class instances and non-plain objects → placeholder\n    if (!isPlainObject(value)) {\n        return NON_SERIALIZABLE_PLACEHOLDER;\n    }\n\n    // Plain object (recursive)\n    if (seen.has(value)) return CIRCULAR_REFERENCE_PLACEHOLDER;\n    seen.add(value);\n    const result: Record<string, JsonSafeValue> = {};\n    for (const [key, val] of Object.entries(value)) {\n        if (val === undefined) continue;\n        result[key] = sanitizeValue(val, seen);\n    }\n    seen.delete(value);\n    return result;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Public API\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Ensures metadata is JSON-serializable.\n *\n * **Allowed:** finite number, string, boolean, null, arrays, and plain objects.\n *\n * **Dropped (mirroring `JSON.stringify`):** object properties whose value is\n * `undefined` (the key is omitted); an `undefined` array item becomes `null`.\n *\n * **Converted to placeholder:** Date, BigInt, class instances, functions,\n * symbols, non-finite numbers (`NaN`/`Infinity`), and circular references\n * (which would otherwise make `JSON.stringify` throw).\n *\n * @throws {TypeError} If `input` is not a plain object at the root level.\n */\nfunction assertJsonSafeMetadata(input: unknown): JsonSafeRecord {\n    if (input === undefined) {\n        return {};\n    }\n\n    if (!isPlainObject(input)) {\n        throw new TypeError(\n            \"metadata must be a plain object (Record<string, unknown>).\",\n        );\n    }\n\n    return sanitizeValue(input, new WeakSet<object>()) as JsonSafeRecord;\n}\n\nexport {\n    assertJsonSafeMetadata,\n    CIRCULAR_REFERENCE_PLACEHOLDER,\n    NON_SERIALIZABLE_PLACEHOLDER,\n};\n","// Base application error for the domain/application layer.\n// Encapsulates a code, optional cause, and JSON-safe metadata.\n\nimport type {\n    AppErrorOptions,\n    ErrorSeverity,\n    JsonSafeRecord,\n} from \"./types.js\";\nimport { assertJsonSafeMetadata } from \"./utils/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AppError (abstract base class)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Root of the application/domain error hierarchy. Every error the system raises\n * on purpose extends `AppError`, which gives callers a single `instanceof` to\n * catch and a uniform, serializable shape to log and transport.\n *\n * Beyond the native `Error` message it carries a stable `code` (the contract the\n * outside world matches on), an optional non-leaking `publicMessage`, a\n * severity, JSON-safe `metadata`, and the correlation/request/command ids that\n * stitch an error back to the request that produced it. The metadata is\n * validated as JSON-safe on construction, so a logger can serialize any\n * `AppError` without hitting a circular reference or a non-serializable value.\n *\n * Abstract on purpose: callers should throw a specific subclass (e.g.\n * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are\n * meaningful, never a bare `AppError`.\n */\nabstract class AppError extends Error {\n    public readonly code: string;\n    public readonly cause?: unknown;\n    public readonly metadata?: JsonSafeRecord;\n    public readonly type?: string;\n    public readonly severity?: ErrorSeverity;\n    public readonly createdAtIso: string;\n    public readonly publicMessage?: string;\n    /**\n     * Identifies a single execution \"story\" in the system. All operations\n     * related to the same logical flow must share the same correlationId.\n     */\n    public readonly correlationId?: string;\n    /**\n     * Identifies a specific technical request attempt (each retry may produce\n     * a new requestId), even when the correlationId stays the same.\n     */\n    public readonly requestId?: string;\n    /**\n     * Marks the business intent / idempotency key; stays the same across\n     * technical retries and multiple requests that represent the same intent.\n     */\n    public readonly commandId?: string;\n\n    /**\n     * Builds the common error envelope shared by every subclass.\n     *\n     * `name` is taken from `new.target` so the thrown instance reports its\n     * concrete subclass name (not `\"AppError\"`), and the prototype is re-pinned\n     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to\n     * older targets where extending built-ins breaks the chain. `createdAtIso`\n     * defaults to now, and `metadata` is validated as JSON-safe so the error is\n     * always serializable.\n     *\n     * Declared `protected`: instantiate a concrete subclass, never `AppError`.\n     *\n     * @param message - The internal, developer-facing message.\n     * @param code - The stable machine-readable code callers match on.\n     * @param options - Optional cause, metadata, severity, and correlation ids.\n     * @throws When `options.metadata` contains a value that is not JSON-safe.\n     */\n    protected constructor(\n        message: string,\n        code: string,\n        options?: AppErrorOptions,\n    ) {\n        super(message);\n\n        this.name = new.target.name;\n        this.code = code;\n        this.cause = options?.cause;\n        this.type = options?.type;\n        this.severity = options?.severity;\n        this.correlationId = options?.correlationId;\n        this.requestId = options?.requestId;\n        this.commandId = options?.commandId;\n        this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();\n        this.publicMessage = options?.publicMessage;\n\n        this.metadata = options?.metadata\n            ? assertJsonSafeMetadata(options.metadata)\n            : undefined;\n\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n\n    /**\n     * Returns a JSON-safe representation of the error.\n     * Does NOT include `cause` by default (to avoid leaking internal details).\n     */\n    public toJSON(): Record<string, unknown> {\n        const payload: Record<string, unknown> = {\n            name: this.name,\n            code: this.code,\n            message: this.message,\n            createdAtIso: this.createdAtIso,\n        };\n\n        // Optional fields are emitted only when defined, so the serialized\n        // shape never carries `undefined`-valued keys (consistent with how the\n        // correlation/request/command ids are handled).\n        if (this.type !== undefined) payload.type = this.type;\n        if (this.severity !== undefined) payload.severity = this.severity;\n        if (this.publicMessage !== undefined)\n            payload.publicMessage = this.publicMessage;\n        if (this.metadata !== undefined) payload.metadata = this.metadata;\n        if (this.correlationId !== undefined)\n            payload.correlationId = this.correlationId;\n        if (this.requestId !== undefined) payload.requestId = this.requestId;\n        if (this.commandId !== undefined) payload.commandId = this.commandId;\n\n        return payload;\n    }\n}\n\nexport { AppError };\n"],"mappings":"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"}

package/dist/application/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_use_case = require("../use-case.cjs");
+const require_requested_by = require("../requested-by.cjs");
 const require_temporal_use_case = require("../temporal-use-case.cjs");
 Object.defineProperty(exports, "Command", {
 	enumerable: true,
@@ -13,7 +14,7 @@ Object.defineProperty(exports, "Query", {
 		return require_temporal_use_case.Query;
 	}
 });
-exports.RequestedBy = require_temporal_use_case.RequestedBy;
+exports.RequestedBy = require_requested_by.RequestedBy;
 exports.TemporalUseCase = require_temporal_use_case.TemporalUseCase;
 Object.defineProperty(exports, "UseCase", {
 	enumerable: true,

package/dist/application/index.d.cts

@@ -1,2 +1,3 @@
-import { A as MetricLabels, C as RequestedByKind, D as TraceAttributeValue, E as UseCaseObservability, M as LogPayload, N as LoggerPort, O as TraceSpan, S as RequestedBy, T as UseCase, _ as PolicyEvaluationOutput, a as TemporalContext, b as Command, c as CacheStrategy, d as mapPolicyEvaluationError, f as TemporalHistory, g as PolicyEvaluationInput, h as ResultRepository, i as CreateTemporalContextInput, j as MetricsPort, k as TracerPort, l as Page, m as Repository, n as TemporalUseCaseInput, o as assertTemporalContext, p as TemporalRepository, r as TemporalizedContextSeed, s as createTemporalContext, t as TemporalUseCase, u as Query, v as PolicyPort, w as MaybePromise, x as CommandInput, y as PolicyPortError } from "../temporal-use-case.cjs";
+import { n as RequestedByKind, t as RequestedBy } from "../requested-by.cjs";
+import { A as LogPayload, C as UseCase, D as TracerPort, E as TraceSpan, O as MetricLabels, S as MaybePromise, T as TraceAttributeValue, _ as PolicyEvaluationOutput, a as TemporalContext, b as Command, c as CacheStrategy, d as mapPolicyEvaluationError, f as TemporalHistory, g as PolicyEvaluationInput, h as ResultRepository, i as CreateTemporalContextInput, j as LoggerPort, k as MetricsPort, l as Page, m as Repository, n as TemporalUseCaseInput, o as assertTemporalContext, p as TemporalRepository, r as TemporalizedContextSeed, s as createTemporalContext, t as TemporalUseCase, u as Query, v as PolicyPort, w as UseCaseObservability, x as CommandInput, y as PolicyPortError } from "../temporal-use-case.cjs";
 export { CacheStrategy, Command, CommandInput, CreateTemporalContextInput, LogPayload, LoggerPort, MaybePromise, MetricLabels, MetricsPort, Page, PolicyEvaluationInput, PolicyEvaluationOutput, PolicyPort, PolicyPortError, Query, Repository, RequestedBy, RequestedByKind, ResultRepository, TemporalContext, TemporalHistory, TemporalRepository, TemporalUseCase, TemporalUseCaseInput, TemporalizedContextSeed, TraceAttributeValue, TraceSpan, TracerPort, UseCase, UseCaseObservability, assertTemporalContext, createTemporalContext, mapPolicyEvaluationError };

package/dist/application/index.d.ts

@@ -1,2 +1,3 @@
-import { A as MetricLabels, C as RequestedByKind, D as TraceAttributeValue, E as UseCaseObservability, M as LogPayload, N as LoggerPort, O as TraceSpan, S as RequestedBy, T as UseCase, _ as PolicyEvaluationOutput, a as TemporalContext, b as Command, c as CacheStrategy, d as mapPolicyEvaluationError, f as TemporalHistory, g as PolicyEvaluationInput, h as ResultRepository, i as CreateTemporalContextInput, j as MetricsPort, k as TracerPort, l as Page, m as Repository, n as TemporalUseCaseInput, o as assertTemporalContext, p as TemporalRepository, r as TemporalizedContextSeed, s as createTemporalContext, t as TemporalUseCase, u as Query, v as PolicyPort, w as MaybePromise, x as CommandInput, y as PolicyPortError } from "../temporal-use-case.js";
+import { n as RequestedByKind, t as RequestedBy } from "../requested-by.js";
+import { A as LogPayload, C as UseCase, D as TracerPort, E as TraceSpan, O as MetricLabels, S as MaybePromise, T as TraceAttributeValue, _ as PolicyEvaluationOutput, a as TemporalContext, b as Command, c as CacheStrategy, d as mapPolicyEvaluationError, f as TemporalHistory, g as PolicyEvaluationInput, h as ResultRepository, i as CreateTemporalContextInput, j as LoggerPort, k as MetricsPort, l as Page, m as Repository, n as TemporalUseCaseInput, o as assertTemporalContext, p as TemporalRepository, r as TemporalizedContextSeed, s as createTemporalContext, t as TemporalUseCase, u as Query, v as PolicyPort, w as UseCaseObservability, x as CommandInput, y as PolicyPortError } from "../temporal-use-case.js";
 export { CacheStrategy, Command, CommandInput, CreateTemporalContextInput, LogPayload, LoggerPort, MaybePromise, MetricLabels, MetricsPort, Page, PolicyEvaluationInput, PolicyEvaluationOutput, PolicyPort, PolicyPortError, Query, Repository, RequestedBy, RequestedByKind, ResultRepository, TemporalContext, TemporalHistory, TemporalRepository, TemporalUseCase, TemporalUseCaseInput, TemporalizedContextSeed, TraceAttributeValue, TraceSpan, TracerPort, UseCase, UseCaseObservability, assertTemporalContext, createTemporalContext, mapPolicyEvaluationError };

package/dist/application/index.js

@@ -1,3 +1,4 @@
 import { t as UseCase } from "../use-case.js";
-import { a as mapPolicyEvaluationError, i as Query, n as assertTemporalContext, o as Command, r as createTemporalContext, s as RequestedBy, t as TemporalUseCase } from "../temporal-use-case.js";
+import { t as RequestedBy } from "../requested-by.js";
+import { a as mapPolicyEvaluationError, i as Query, n as assertTemporalContext, o as Command, r as createTemporalContext, t as TemporalUseCase } from "../temporal-use-case.js";
 export { Command, Query, RequestedBy, TemporalUseCase, UseCase, assertTemporalContext, createTemporalContext, mapPolicyEvaluationError };

package/dist/authorization-error.cjs

@@ -0,0 +1,157 @@
+const require_app_error = require("./app-error.cjs");
+//#region src/core/errors/authorization-error.ts
+/**
+* Raised when an authenticated actor is not allowed to perform a business
+* action — the "you may not" error, distinct from authentication ("who are
+* you"). Maps to an HTTP 403 at the edge.
+*
+* The discriminating {@link reason} records *why* access was denied (a flat
+* forbid, a missing role/capability, an out-of-scope target, or a policy
+* decision) so the boundary can shape the response without re-deriving it. The
+* metadata is deliberately built around a stable business `action` and a
+* type/id resource reference rather than an HTTP route or full payload, keeping
+* sensitive data out of logs. Instances are frozen. Construct through the
+* static factories, never directly.
+*/
+var AuthorizationError = class AuthorizationError extends require_app_error.AppError {
+	constructor(params) {
+		super(params.message, params.code, {
+			cause: params.cause,
+			metadata: params.metadata,
+			type: params.type,
+			severity: params.severity,
+			correlationId: params.correlationId,
+			requestId: params.requestId,
+			commandId: params.commandId,
+			createdAtIso: params.createdAtIso,
+			publicMessage: params.publicMessage
+		});
+		this.reason = params.reason;
+		Object.freeze(this);
+	}
+	/**
+	* A flat denial with no more specific reason — the actor simply may not
+	* perform this action. Reach for a more precise factory
+	* ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+	* {@link AuthorizationError.policyDenied}) when the cause is known.
+	*/
+	static forbidden(input) {
+		return new AuthorizationError({
+			message: "Action not allowed",
+			code: require_app_error.ErrorCodes.authorization.forbidden,
+			reason: "forbidden",
+			metadata: {
+				reason: "forbidden",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The action was denied by an evaluated policy. Captures the deciding
+	* policy's id, version, and evaluation instant into the metadata (with
+	* `decision: "deny"`) so the denial is auditable back to the exact policy
+	* that produced it.
+	*
+	* @param input - Factory options plus the required `policyId`,
+	*   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+	*/
+	static policyDenied(input) {
+		return new AuthorizationError({
+			message: "Action denied by policy",
+			code: require_app_error.ErrorCodes.authorization.policyDenied,
+			reason: "policy_denied",
+			metadata: {
+				reason: "policy_denied",
+				...extractMetadataOnly(input),
+				decision: "deny"
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor holds no role at all that bears on the action — the most basic
+	* denial, distinct from {@link AuthorizationError.missingCapability} (which
+	* means the actor *has* roles, just none granting the required capability).
+	* The expected {@link AuthorizationRequirement} is recorded so the boundary
+	* can tell the caller what grant is missing.
+	*
+	* @param input - Factory options plus the `required` role/capability/scope.
+	*/
+	static missingRole(input) {
+		return new AuthorizationError({
+			message: "Missing required role to perform the action",
+			code: require_app_error.ErrorCodes.authorization.missingRole,
+			reason: "missing_role",
+			metadata: {
+				reason: "missing_role",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor lacks a required role or capability. The expected
+	* {@link AuthorizationRequirement} is recorded so the boundary can tell the
+	* caller precisely what grant is missing.
+	*
+	* @param input - Factory options plus the `required` role/capability/scope.
+	*/
+	static missingCapability(input) {
+		return new AuthorizationError({
+			message: "Insufficient capability to perform the action",
+			code: require_app_error.ErrorCodes.authorization.missingCapability,
+			reason: "missing_capability",
+			metadata: {
+				reason: "missing_capability",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor may perform the action in general, but not on *this* target —
+	* the resource falls outside the actor's permitted scope (e.g. a different
+	* school or tenant than the one they are bound to).
+	*
+	* @param input - Factory options plus the optional `required` scope that the
+	*   target failed to satisfy.
+	*/
+	static outOfScope(input) {
+		return new AuthorizationError({
+			message: "Action outside the allowed scope",
+			code: require_app_error.ErrorCodes.authorization.outOfScope,
+			reason: "out_of_scope",
+			metadata: {
+				reason: "out_of_scope",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+};
+function extractAppErrorOptions(options) {
+	return {
+		cause: options?.cause,
+		type: options?.type,
+		severity: options?.severity,
+		correlationId: options?.correlationId,
+		requestId: options?.requestId,
+		commandId: options?.commandId,
+		createdAtIso: options?.createdAtIso,
+		publicMessage: options?.publicMessage
+	};
+}
+function extractMetadataOnly(input) {
+	const { cause, type, severity, correlationId, requestId, commandId, createdAtIso, publicMessage, ...metadata } = input;
+	return metadata;
+}
+//#endregion
+Object.defineProperty(exports, "AuthorizationError", {
+	enumerable: true,
+	get: function() {
+		return AuthorizationError;
+	}
+});
+
+//# sourceMappingURL=authorization-error.cjs.map

package/dist/authorization-error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-error.cjs","names":["AppError","ErrorCodes"],"sources":["../src/core/errors/authorization-error.ts"],"sourcesContent":["import { AppError } from \"./app-error.js\";\nimport { ErrorCodes } from \"./error-codes.js\";\nimport type { AppErrorOptions, ErrorSeverity } from \"./types.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Types\n// ─────────────────────────────────────────────────────────────────────────────\n\ntype AuthorizationErrorReason =\n    | \"forbidden\"\n    | \"missing_role\"\n    | \"missing_capability\"\n    | \"out_of_scope\"\n    | \"outside_time_window\"\n    | \"policy_denied\"\n    | \"unknown\";\n\ntype AuthorizationRequirement = {\n    role?: string;\n    capability?: string;\n    scope?: string; // e.g.: \"school:{id}\" or \"class:{id}\"\n};\n\ntype AuthorizationErrorMetadata = {\n    reason: AuthorizationErrorReason;\n\n    /** Stable action you evaluated (not an HTTP route — a \"business action\") */\n    action: string;\n\n    /** Resource identification (without leaking the full payload) */\n    resource?: { type: string; id?: string };\n\n    /** Optional: actor (do not include sensitive data) */\n    actor?: { userId: string; role?: string };\n\n    /** Optional: expected requirement */\n    required?: AuthorizationRequirement;\n\n    /** Optional: policy (when you already have PolicyEvaluation or similar) */\n    policyId?: string;\n    policyVersion?: number;\n    evaluatedAtIso?: string;\n    decision?: \"allow\" | \"deny\";\n    reasonCode?: string;\n\n    /** Optional: additional non-sensitive info */\n    details?: string;\n};\n\n/**\n * Options for AuthorizationError factory methods.\n * Combines metadata fields (except 'reason') with common AppError options.\n */\ntype AuthorizationErrorFactoryOptions = Omit<\n    AuthorizationErrorMetadata,\n    \"reason\"\n> &\n    Omit<AppErrorOptions, \"metadata\">;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// AuthorizationError\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Raised when an authenticated actor is not allowed to perform a business\n * action — the \"you may not\" error, distinct from authentication (\"who are\n * you\"). Maps to an HTTP 403 at the edge.\n *\n * The discriminating {@link reason} records *why* access was denied (a flat\n * forbid, a missing role/capability, an out-of-scope target, or a policy\n * decision) so the boundary can shape the response without re-deriving it. The\n * metadata is deliberately built around a stable business `action` and a\n * type/id resource reference rather than an HTTP route or full payload, keeping\n * sensitive data out of logs. Instances are frozen. Construct through the\n * static factories, never directly.\n */\nclass AuthorizationError extends AppError {\n    public readonly reason: AuthorizationErrorReason;\n\n    private constructor(params: {\n        message: string;\n        code: string;\n        reason: AuthorizationErrorReason;\n        metadata: AuthorizationErrorMetadata;\n        cause?: unknown;\n        type?: string;\n        severity?: ErrorSeverity;\n        correlationId?: string;\n        requestId?: string;\n        commandId?: string;\n        createdAtIso?: string;\n        publicMessage?: string;\n    }) {\n        super(params.message, params.code, {\n            cause: params.cause,\n            metadata: params.metadata,\n            type: params.type,\n            severity: params.severity,\n            correlationId: params.correlationId,\n            requestId: params.requestId,\n            commandId: params.commandId,\n            createdAtIso: params.createdAtIso,\n            publicMessage: params.publicMessage,\n        });\n\n        this.reason = params.reason;\n        Object.freeze(this);\n    }\n\n    // ─────────────────────────────────────────────────────────────────────────\n    // Factories\n    // ─────────────────────────────────────────────────────────────────────────\n\n    /**\n     * A flat denial with no more specific reason — the actor simply may not\n     * perform this action. Reach for a more precise factory\n     * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},\n     * {@link AuthorizationError.policyDenied}) when the cause is known.\n     */\n    static forbidden(\n        input: AuthorizationErrorFactoryOptions,\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action not allowed\",\n            code: ErrorCodes.authorization.forbidden,\n            reason: \"forbidden\",\n            metadata: { reason: \"forbidden\", ...extractMetadataOnly(input) },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The action was denied by an evaluated policy. Captures the deciding\n     * policy's id, version, and evaluation instant into the metadata (with\n     * `decision: \"deny\"`) so the denial is auditable back to the exact policy\n     * that produced it.\n     *\n     * @param input - Factory options plus the required `policyId`,\n     *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.\n     */\n    static policyDenied(\n        input: AuthorizationErrorFactoryOptions & {\n            policyId: string;\n            policyVersion: number;\n            evaluatedAtIso: string;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action denied by policy\",\n            code: ErrorCodes.authorization.policyDenied,\n            reason: \"policy_denied\",\n            metadata: {\n                reason: \"policy_denied\",\n                ...extractMetadataOnly(input),\n                decision: \"deny\",\n            },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor holds no role at all that bears on the action — the most basic\n     * denial, distinct from {@link AuthorizationError.missingCapability} (which\n     * means the actor *has* roles, just none granting the required capability).\n     * The expected {@link AuthorizationRequirement} is recorded so the boundary\n     * can tell the caller what grant is missing.\n     *\n     * @param input - Factory options plus the `required` role/capability/scope.\n     */\n    static missingRole(\n        input: AuthorizationErrorFactoryOptions & {\n            required: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Missing required role to perform the action\",\n            code: ErrorCodes.authorization.missingRole,\n            reason: \"missing_role\",\n            metadata: {\n                reason: \"missing_role\",\n                ...extractMetadataOnly(input),\n            },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor lacks a required role or capability. The expected\n     * {@link AuthorizationRequirement} is recorded so the boundary can tell the\n     * caller precisely what grant is missing.\n     *\n     * @param input - Factory options plus the `required` role/capability/scope.\n     */\n    static missingCapability(\n        input: AuthorizationErrorFactoryOptions & {\n            required: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Insufficient capability to perform the action\",\n            code: ErrorCodes.authorization.missingCapability,\n            reason: \"missing_capability\",\n            metadata: {\n                reason: \"missing_capability\",\n                ...extractMetadataOnly(input),\n            },\n            ...extractAppErrorOptions(input),\n        });\n    }\n\n    /**\n     * The actor may perform the action in general, but not on *this* target —\n     * the resource falls outside the actor's permitted scope (e.g. a different\n     * school or tenant than the one they are bound to).\n     *\n     * @param input - Factory options plus the optional `required` scope that the\n     *   target failed to satisfy.\n     */\n    static outOfScope(\n        input: AuthorizationErrorFactoryOptions & {\n            required?: AuthorizationRequirement;\n        },\n    ): AuthorizationError {\n        return new AuthorizationError({\n            message: \"Action outside the allowed scope\",\n            code: ErrorCodes.authorization.outOfScope,\n            reason: \"out_of_scope\",\n            metadata: { reason: \"out_of_scope\", ...extractMetadataOnly(input) },\n            ...extractAppErrorOptions(input),\n        });\n    }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\nfunction extractAppErrorOptions(options?: Partial<AppErrorOptions>) {\n    return {\n        cause: options?.cause,\n        type: options?.type,\n        severity: options?.severity,\n        correlationId: options?.correlationId,\n        requestId: options?.requestId,\n        commandId: options?.commandId,\n        createdAtIso: options?.createdAtIso,\n        publicMessage: options?.publicMessage,\n    };\n}\n\nfunction extractMetadataOnly(\n    input: AuthorizationErrorFactoryOptions,\n): Omit<AuthorizationErrorMetadata, \"reason\"> {\n    const {\n        cause,\n        type,\n        severity,\n        correlationId,\n        requestId,\n        commandId,\n        createdAtIso,\n        publicMessage,\n        ...metadata\n    } = input;\n    return metadata;\n}\n\nexport { AuthorizationError };\nexport type {\n    AuthorizationErrorMetadata,\n    AuthorizationErrorReason,\n    AuthorizationRequirement,\n};\n"],"mappings":";;;;;;;;;;;;;;;AA4EA,IAAM,qBAAN,MAAM,2BAA2BA,kBAAAA,SAAS;CAGtC,YAAoB,QAajB;EACC,MAAM,OAAO,SAAS,OAAO,MAAM;GAC/B,OAAO,OAAO;GACd,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,UAAU,OAAO;GACjB,eAAe,OAAO;GACtB,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB,cAAc,OAAO;GACrB,eAAe,OAAO;EAC1B,CAAC;EAED,KAAK,SAAS,OAAO;EACrB,OAAO,OAAO,IAAI;CACtB;;;;;;;CAYA,OAAO,UACH,OACkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAMC,kBAAAA,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IAAE,QAAQ;IAAa,GAAG,oBAAoB,KAAK;GAAE;GAC/D,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;;;CAWA,OAAO,aACH,OAKkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAMA,kBAAAA,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;IAC5B,UAAU;GACd;GACA,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;;;CAWA,OAAO,YACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAMA,kBAAAA,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;GAChC;GACA,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;CASA,OAAO,kBACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAMA,kBAAAA,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IACN,QAAQ;IACR,GAAG,oBAAoB,KAAK;GAChC;GACA,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;;;;;;;;;CAUA,OAAO,WACH,OAGkB;EAClB,OAAO,IAAI,mBAAmB;GAC1B,SAAS;GACT,MAAMA,kBAAAA,WAAW,cAAc;GAC/B,QAAQ;GACR,UAAU;IAAE,QAAQ;IAAgB,GAAG,oBAAoB,KAAK;GAAE;GAClE,GAAG,uBAAuB,KAAK;EACnC,CAAC;CACL;AACJ;AAMA,SAAS,uBAAuB,SAAoC;CAChE,OAAO;EACH,OAAO,SAAS;EAChB,MAAM,SAAS;EACf,UAAU,SAAS;EACnB,eAAe,SAAS;EACxB,WAAW,SAAS;EACpB,WAAW,SAAS;EACpB,cAAc,SAAS;EACvB,eAAe,SAAS;CAC5B;AACJ;AAEA,SAAS,oBACL,OAC0C;CAC1C,MAAM,EACF,OACA,MACA,UACA,eACA,WACA,WACA,cACA,eACA,GAAG,aACH;CACJ,OAAO;AACX"}

package/dist/authorization-error.d.cts

@@ -0,0 +1,113 @@
+import { n as AppErrorOptions, t as AppError } from "./app-error.cjs";
+
+//#region src/core/errors/authorization-error.d.ts
+type AuthorizationErrorReason = "forbidden" | "missing_role" | "missing_capability" | "out_of_scope" | "outside_time_window" | "policy_denied" | "unknown";
+type AuthorizationRequirement = {
+  role?: string;
+  capability?: string;
+  scope?: string;
+};
+type AuthorizationErrorMetadata = {
+  reason: AuthorizationErrorReason;
+  /** Stable action you evaluated (not an HTTP route — a "business action") */
+  action: string;
+  /** Resource identification (without leaking the full payload) */
+  resource?: {
+    type: string;
+    id?: string;
+  };
+  /** Optional: actor (do not include sensitive data) */
+  actor?: {
+    userId: string;
+    role?: string;
+  };
+  /** Optional: expected requirement */
+  required?: AuthorizationRequirement;
+  /** Optional: policy (when you already have PolicyEvaluation or similar) */
+  policyId?: string;
+  policyVersion?: number;
+  evaluatedAtIso?: string;
+  decision?: "allow" | "deny";
+  reasonCode?: string;
+  /** Optional: additional non-sensitive info */
+  details?: string;
+};
+/**
+ * Options for AuthorizationError factory methods.
+ * Combines metadata fields (except 'reason') with common AppError options.
+ */
+type AuthorizationErrorFactoryOptions = Omit<AuthorizationErrorMetadata, "reason"> & Omit<AppErrorOptions, "metadata">;
+/**
+ * Raised when an authenticated actor is not allowed to perform a business
+ * action — the "you may not" error, distinct from authentication ("who are
+ * you"). Maps to an HTTP 403 at the edge.
+ *
+ * The discriminating {@link reason} records *why* access was denied (a flat
+ * forbid, a missing role/capability, an out-of-scope target, or a policy
+ * decision) so the boundary can shape the response without re-deriving it. The
+ * metadata is deliberately built around a stable business `action` and a
+ * type/id resource reference rather than an HTTP route or full payload, keeping
+ * sensitive data out of logs. Instances are frozen. Construct through the
+ * static factories, never directly.
+ */
+declare class AuthorizationError extends AppError {
+  readonly reason: AuthorizationErrorReason;
+  private constructor();
+  /**
+   * A flat denial with no more specific reason — the actor simply may not
+   * perform this action. Reach for a more precise factory
+   * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+   * {@link AuthorizationError.policyDenied}) when the cause is known.
+   */
+  static forbidden(input: AuthorizationErrorFactoryOptions): AuthorizationError;
+  /**
+   * The action was denied by an evaluated policy. Captures the deciding
+   * policy's id, version, and evaluation instant into the metadata (with
+   * `decision: "deny"`) so the denial is auditable back to the exact policy
+   * that produced it.
+   *
+   * @param input - Factory options plus the required `policyId`,
+   *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+   */
+  static policyDenied(input: AuthorizationErrorFactoryOptions & {
+    policyId: string;
+    policyVersion: number;
+    evaluatedAtIso: string;
+  }): AuthorizationError;
+  /**
+   * The actor holds no role at all that bears on the action — the most basic
+   * denial, distinct from {@link AuthorizationError.missingCapability} (which
+   * means the actor *has* roles, just none granting the required capability).
+   * The expected {@link AuthorizationRequirement} is recorded so the boundary
+   * can tell the caller what grant is missing.
+   *
+   * @param input - Factory options plus the `required` role/capability/scope.
+   */
+  static missingRole(input: AuthorizationErrorFactoryOptions & {
+    required: AuthorizationRequirement;
+  }): AuthorizationError;
+  /**
+   * The actor lacks a required role or capability. The expected
+   * {@link AuthorizationRequirement} is recorded so the boundary can tell the
+   * caller precisely what grant is missing.
+   *
+   * @param input - Factory options plus the `required` role/capability/scope.
+   */
+  static missingCapability(input: AuthorizationErrorFactoryOptions & {
+    required: AuthorizationRequirement;
+  }): AuthorizationError;
+  /**
+   * The actor may perform the action in general, but not on *this* target —
+   * the resource falls outside the actor's permitted scope (e.g. a different
+   * school or tenant than the one they are bound to).
+   *
+   * @param input - Factory options plus the optional `required` scope that the
+   *   target failed to satisfy.
+   */
+  static outOfScope(input: AuthorizationErrorFactoryOptions & {
+    required?: AuthorizationRequirement;
+  }): AuthorizationError;
+}
+//#endregion
+export { AuthorizationRequirement as i, AuthorizationErrorMetadata as n, AuthorizationErrorReason as r, AuthorizationError as t };
+//# sourceMappingURL=authorization-error.d.cts.map

package/dist/authorization-error.d.ts

@@ -0,0 +1,113 @@
+import { n as AppErrorOptions, t as AppError } from "./app-error.js";
+
+//#region src/core/errors/authorization-error.d.ts
+type AuthorizationErrorReason = "forbidden" | "missing_role" | "missing_capability" | "out_of_scope" | "outside_time_window" | "policy_denied" | "unknown";
+type AuthorizationRequirement = {
+  role?: string;
+  capability?: string;
+  scope?: string;
+};
+type AuthorizationErrorMetadata = {
+  reason: AuthorizationErrorReason;
+  /** Stable action you evaluated (not an HTTP route — a "business action") */
+  action: string;
+  /** Resource identification (without leaking the full payload) */
+  resource?: {
+    type: string;
+    id?: string;
+  };
+  /** Optional: actor (do not include sensitive data) */
+  actor?: {
+    userId: string;
+    role?: string;
+  };
+  /** Optional: expected requirement */
+  required?: AuthorizationRequirement;
+  /** Optional: policy (when you already have PolicyEvaluation or similar) */
+  policyId?: string;
+  policyVersion?: number;
+  evaluatedAtIso?: string;
+  decision?: "allow" | "deny";
+  reasonCode?: string;
+  /** Optional: additional non-sensitive info */
+  details?: string;
+};
+/**
+ * Options for AuthorizationError factory methods.
+ * Combines metadata fields (except 'reason') with common AppError options.
+ */
+type AuthorizationErrorFactoryOptions = Omit<AuthorizationErrorMetadata, "reason"> & Omit<AppErrorOptions, "metadata">;
+/**
+ * Raised when an authenticated actor is not allowed to perform a business
+ * action — the "you may not" error, distinct from authentication ("who are
+ * you"). Maps to an HTTP 403 at the edge.
+ *
+ * The discriminating {@link reason} records *why* access was denied (a flat
+ * forbid, a missing role/capability, an out-of-scope target, or a policy
+ * decision) so the boundary can shape the response without re-deriving it. The
+ * metadata is deliberately built around a stable business `action` and a
+ * type/id resource reference rather than an HTTP route or full payload, keeping
+ * sensitive data out of logs. Instances are frozen. Construct through the
+ * static factories, never directly.
+ */
+declare class AuthorizationError extends AppError {
+  readonly reason: AuthorizationErrorReason;
+  private constructor();
+  /**
+   * A flat denial with no more specific reason — the actor simply may not
+   * perform this action. Reach for a more precise factory
+   * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+   * {@link AuthorizationError.policyDenied}) when the cause is known.
+   */
+  static forbidden(input: AuthorizationErrorFactoryOptions): AuthorizationError;
+  /**
+   * The action was denied by an evaluated policy. Captures the deciding
+   * policy's id, version, and evaluation instant into the metadata (with
+   * `decision: "deny"`) so the denial is auditable back to the exact policy
+   * that produced it.
+   *
+   * @param input - Factory options plus the required `policyId`,
+   *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+   */
+  static policyDenied(input: AuthorizationErrorFactoryOptions & {
+    policyId: string;
+    policyVersion: number;
+    evaluatedAtIso: string;
+  }): AuthorizationError;
+  /**
+   * The actor holds no role at all that bears on the action — the most basic
+   * denial, distinct from {@link AuthorizationError.missingCapability} (which
+   * means the actor *has* roles, just none granting the required capability).
+   * The expected {@link AuthorizationRequirement} is recorded so the boundary
+   * can tell the caller what grant is missing.
+   *
+   * @param input - Factory options plus the `required` role/capability/scope.
+   */
+  static missingRole(input: AuthorizationErrorFactoryOptions & {
+    required: AuthorizationRequirement;
+  }): AuthorizationError;
+  /**
+   * The actor lacks a required role or capability. The expected
+   * {@link AuthorizationRequirement} is recorded so the boundary can tell the
+   * caller precisely what grant is missing.
+   *
+   * @param input - Factory options plus the `required` role/capability/scope.
+   */
+  static missingCapability(input: AuthorizationErrorFactoryOptions & {
+    required: AuthorizationRequirement;
+  }): AuthorizationError;
+  /**
+   * The actor may perform the action in general, but not on *this* target —
+   * the resource falls outside the actor's permitted scope (e.g. a different
+   * school or tenant than the one they are bound to).
+   *
+   * @param input - Factory options plus the optional `required` scope that the
+   *   target failed to satisfy.
+   */
+  static outOfScope(input: AuthorizationErrorFactoryOptions & {
+    required?: AuthorizationRequirement;
+  }): AuthorizationError;
+}
+//#endregion
+export { AuthorizationRequirement as i, AuthorizationErrorMetadata as n, AuthorizationErrorReason as r, AuthorizationError as t };
+//# sourceMappingURL=authorization-error.d.ts.map

package/dist/authorization-error.js

@@ -0,0 +1,152 @@
+import { r as ErrorCodes, t as AppError } from "./app-error.js";
+//#region src/core/errors/authorization-error.ts
+/**
+* Raised when an authenticated actor is not allowed to perform a business
+* action — the "you may not" error, distinct from authentication ("who are
+* you"). Maps to an HTTP 403 at the edge.
+*
+* The discriminating {@link reason} records *why* access was denied (a flat
+* forbid, a missing role/capability, an out-of-scope target, or a policy
+* decision) so the boundary can shape the response without re-deriving it. The
+* metadata is deliberately built around a stable business `action` and a
+* type/id resource reference rather than an HTTP route or full payload, keeping
+* sensitive data out of logs. Instances are frozen. Construct through the
+* static factories, never directly.
+*/
+var AuthorizationError = class AuthorizationError extends AppError {
+	constructor(params) {
+		super(params.message, params.code, {
+			cause: params.cause,
+			metadata: params.metadata,
+			type: params.type,
+			severity: params.severity,
+			correlationId: params.correlationId,
+			requestId: params.requestId,
+			commandId: params.commandId,
+			createdAtIso: params.createdAtIso,
+			publicMessage: params.publicMessage
+		});
+		this.reason = params.reason;
+		Object.freeze(this);
+	}
+	/**
+	* A flat denial with no more specific reason — the actor simply may not
+	* perform this action. Reach for a more precise factory
+	* ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+	* {@link AuthorizationError.policyDenied}) when the cause is known.
+	*/
+	static forbidden(input) {
+		return new AuthorizationError({
+			message: "Action not allowed",
+			code: ErrorCodes.authorization.forbidden,
+			reason: "forbidden",
+			metadata: {
+				reason: "forbidden",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The action was denied by an evaluated policy. Captures the deciding
+	* policy's id, version, and evaluation instant into the metadata (with
+	* `decision: "deny"`) so the denial is auditable back to the exact policy
+	* that produced it.
+	*
+	* @param input - Factory options plus the required `policyId`,
+	*   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+	*/
+	static policyDenied(input) {
+		return new AuthorizationError({
+			message: "Action denied by policy",
+			code: ErrorCodes.authorization.policyDenied,
+			reason: "policy_denied",
+			metadata: {
+				reason: "policy_denied",
+				...extractMetadataOnly(input),
+				decision: "deny"
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor holds no role at all that bears on the action — the most basic
+	* denial, distinct from {@link AuthorizationError.missingCapability} (which
+	* means the actor *has* roles, just none granting the required capability).
+	* The expected {@link AuthorizationRequirement} is recorded so the boundary
+	* can tell the caller what grant is missing.
+	*
+	* @param input - Factory options plus the `required` role/capability/scope.
+	*/
+	static missingRole(input) {
+		return new AuthorizationError({
+			message: "Missing required role to perform the action",
+			code: ErrorCodes.authorization.missingRole,
+			reason: "missing_role",
+			metadata: {
+				reason: "missing_role",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor lacks a required role or capability. The expected
+	* {@link AuthorizationRequirement} is recorded so the boundary can tell the
+	* caller precisely what grant is missing.
+	*
+	* @param input - Factory options plus the `required` role/capability/scope.
+	*/
+	static missingCapability(input) {
+		return new AuthorizationError({
+			message: "Insufficient capability to perform the action",
+			code: ErrorCodes.authorization.missingCapability,
+			reason: "missing_capability",
+			metadata: {
+				reason: "missing_capability",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+	/**
+	* The actor may perform the action in general, but not on *this* target —
+	* the resource falls outside the actor's permitted scope (e.g. a different
+	* school or tenant than the one they are bound to).
+	*
+	* @param input - Factory options plus the optional `required` scope that the
+	*   target failed to satisfy.
+	*/
+	static outOfScope(input) {
+		return new AuthorizationError({
+			message: "Action outside the allowed scope",
+			code: ErrorCodes.authorization.outOfScope,
+			reason: "out_of_scope",
+			metadata: {
+				reason: "out_of_scope",
+				...extractMetadataOnly(input)
+			},
+			...extractAppErrorOptions(input)
+		});
+	}
+};
+function extractAppErrorOptions(options) {
+	return {
+		cause: options?.cause,
+		type: options?.type,
+		severity: options?.severity,
+		correlationId: options?.correlationId,
+		requestId: options?.requestId,
+		commandId: options?.commandId,
+		createdAtIso: options?.createdAtIso,
+		publicMessage: options?.publicMessage
+	};
+}
+function extractMetadataOnly(input) {
+	const { cause, type, severity, correlationId, requestId, commandId, createdAtIso, publicMessage, ...metadata } = input;
+	return metadata;
+}
+//#endregion
+export { AuthorizationError as t };
+
+//# sourceMappingURL=authorization-error.js.map