@cullet/erp-core 1.3.0 → 1.5.0

package/src/core/errors/authorization-error.ts

@@ -158,6 +158,32 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * 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 {
+        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

package/src/core/errors/error-codes.ts

@@ -8,6 +8,7 @@ const ErrorCodes = {
     authorization: {
         forbidden: "sec.authz.forbidden",
         policyDenied: "sec.authz.policy_denied",
+        missingRole: "sec.authz.missing_role",
         missingCapability: "sec.authz.missing_capability",
         outOfScope: "sec.authz.out_of_scope",
     },

package/src/core/errors/utils/json-safe.ts

@@ -30,18 +30,23 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
 
     const type = typeof value;
 
-    // Primitives
-    if (type === "string" || type === "number" || type === "boolean") {
+    // Primitives (non-finite numbers are not JSON-representable — placeholder)
+    if (type === "number") {
+        return Number.isFinite(value)
+            ? (value as number)
+            : NON_SERIALIZABLE_PLACEHOLDER;
+    }
+    if (type === "string" || type === "boolean") {
         return value as JsonSafeValue;
     }
 
+    // `undefined` only reaches here as an array item: object properties with
+    // undefined values are omitted by the plain-object branch below. Both
+    // mirror `JSON.stringify` semantics.
+    if (value === undefined) return null;
+
     // Non-serializable primitives
-    if (
-        type === "bigint" ||
-        type === "function" ||
-        type === "symbol" ||
-        value === undefined
-    ) {
+    if (type === "bigint" || type === "function" || type === "symbol") {
         return NON_SERIALIZABLE_PLACEHOLDER;
     }
 
@@ -69,6 +74,7 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
     seen.add(value);
     const result: Record<string, JsonSafeValue> = {};
     for (const [key, val] of Object.entries(value)) {
+        if (val === undefined) continue;
         result[key] = sanitizeValue(val, seen);
     }
     seen.delete(value);
@@ -82,11 +88,14 @@ function sanitizeValue(value: unknown, seen: WeakSet<object>): JsonSafeValue {
 /**
  * Ensures metadata is JSON-serializable.
  *
- * **Allowed:** string, number, boolean, null, arrays, and plain objects.
+ * **Allowed:** finite number, string, boolean, null, arrays, and plain objects.
+ *
+ * **Dropped (mirroring `JSON.stringify`):** object properties whose value is
+ * `undefined` (the key is omitted); an `undefined` array item becomes `null`.
  *
  * **Converted to placeholder:** Date, BigInt, class instances, functions,
- * symbols, undefined, and circular references (which would otherwise make
- * `JSON.stringify` throw).
+ * symbols, non-finite numbers (`NaN`/`Infinity`), and circular references
+ * (which would otherwise make `JSON.stringify` throw).
  *
  * @throws {TypeError} If `input` is not a plain object at the root level.
  */

package/src/core/index.ts

@@ -9,6 +9,13 @@ export {
     type ValueObjectPluginContract,
 } from "./domain/value-object.js";
 export * from "./domain/rulesets/index.js";
+// RBAC primitives (zod-free). Re-exported from the root for convenience;
+// consumers that want to stay off `zod` should prefer the dedicated `./rbac`
+// subpath, since the root barrel pulls in `./policies` (and therefore `zod`).
+export * from "./rbac/index.js";
+// ABAC primitives (zod-free), same rationale as RBAC re: the dedicated `./abac`
+// subpath for staying off `zod`.
+export * from "./abac/index.js";
 export * from "./plugins/index.js";
 export * from "./versioning/index.js";
 // NOTE: `./policies` re-exports Result/Ok/Err/Outcome/CommonOutcomeStatus and

package/src/core/policies/engines/v1/condition-evaluator.ts

@@ -1,5 +1,8 @@
 import { PolicyContextPath } from "../../context/index.js";
-import { PolicyDateUtils } from "../../utils/index.js";
+// Import the date util directly (not the utils barrel): the barrel re-exports
+// PolicyHashing, whose node:crypto import would needlessly drag a Node-only
+// API into the zod-free ./abac subpath.
+import { PolicyDateUtils } from "../../utils/date.js";
 import { Result } from "../../../result/result.js";
 
 import type {
@@ -213,6 +216,32 @@ export class ConditionEvaluatorV1 {
         return Result.err(message);
     }
 
+    private static containsInvalidDate(value: unknown): boolean {
+        if (value instanceof Date) {
+            return !PolicyDateUtils.isValid(value);
+        }
+        if (Array.isArray(value)) {
+            return value.some((item) =>
+                ConditionEvaluatorV1.containsInvalidDate(item),
+            );
+        }
+        return false;
+    }
+
+    // Valid Dates become their ISO string so equality/set operators compare
+    // instants instead of references; every other value passes through.
+    private static normalizeDateOperand(value: unknown): unknown {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) =>
+                ConditionEvaluatorV1.normalizeDateOperand(item),
+            );
+        }
+        return value;
+    }
+
     private reportDateOperandError(
         node: ConditionLeafNode,
         actual: unknown,
@@ -527,6 +556,32 @@ export class ConditionEvaluatorV1 {
                 return this.reportInvalidSetOperand(node, actual);
             }
 
+            if (
+                node.op === "eq" ||
+                node.op === "neq" ||
+                node.op === "in" ||
+                node.op === "notIn"
+            ) {
+                // A Date operand would otherwise compare by reference and
+                // silently never match. Normalize valid Dates (either side,
+                // including set items) to their ISO string; an invalid Date is
+                // a context/configuration error, like the relational path.
+                if (
+                    ConditionEvaluatorV1.containsInvalidDate(actual) ||
+                    ConditionEvaluatorV1.containsInvalidDate(node.value)
+                ) {
+                    return this.reportDateOperandError(node, actual);
+                }
+
+                return Result.ok(
+                    this.evaluateOperator(
+                        ConditionEvaluatorV1.normalizeDateOperand(actual),
+                        node.op,
+                        ConditionEvaluatorV1.normalizeDateOperand(node.value),
+                    ),
+                );
+            }
+
             return Result.ok(
                 this.evaluateOperator(actual, node.op, node.value),
             );

package/src/core/rbac/access-request.ts

@@ -0,0 +1,32 @@
+import type { RequestedBy } from "../application/commands/requested-by.js";
+
+import type { Permission } from "./domain/permission.js";
+import type { Scope } from "./domain/scope.js";
+
+/**
+ * The question put to the {@link RbacAuthorizer}: *may this actor perform this
+ * action on this resource, in this scope?* Carries the audit-friendly business
+ * `action` label alongside the concrete {@link Permission} it requires, and
+ * references the target by type/id only (never the full payload).
+ */
+interface AccessRequest {
+    /** Who is acting — reused as the RBAC subject, no separate `Actor` type. */
+    readonly actor: RequestedBy;
+
+    /** Stable business action for auditing, e.g. `"order.cancel"`. */
+    readonly action: string;
+
+    /**
+     * The permission the action requires, e.g. `Permission.of("orders:cancel")`.
+     * Never a wildcard — only the *granted* permissions on roles may wildcard.
+     */
+    readonly required: Permission;
+
+    /** The target resource, identified without leaking its payload. */
+    readonly resource?: { readonly type: string; readonly id?: string };
+
+    /** The scope the resource lives in, e.g. `Scope.of("school:123")`. */
+    readonly scope: Scope;
+}
+
+export type { AccessRequest };

package/src/core/rbac/authorizer.ts

@@ -0,0 +1,91 @@
+import {
+    AuthorizationError,
+    type AuthorizationRequirement,
+} from "../errors/authorization-error.js";
+import { ValidationCode } from "../exceptions/validation-code.js";
+import { InvalidValueException } from "../exceptions/validation-exception.js";
+import { ValidationField } from "../exceptions/validation-field.js";
+import { Result } from "../result/result.js";
+
+import type { AccessRequest } from "./access-request.js";
+import type { Grant } from "./domain/grant.js";
+
+const REQUIRED_FIELD = ValidationField.of("required");
+
+/**
+ * The pure RBAC decisor. Given an {@link AccessRequest} and the {@link Grant}s
+ * already loaded for the actor, it answers "may this actor do this?" with no
+ * I/O — no storage, no network, no clock — returning a {@link Result}. An
+ * authorization *decision* is never thrown, always a value, mirroring the
+ * "errors as values" contract of `UseCase`/`PolicyService`. Loading the grants
+ * is the consumer's job (behind an `AuthorizerPort` adapter); this class only
+ * decides.
+ *
+ * The one thing it *does* throw is {@link InvalidValueException} when the caller
+ * misuses the API by passing a wildcard `required` permission — that is a
+ * programming error surfaced loudly, not an authorization outcome.
+ */
+class RbacAuthorizer {
+    /**
+     * Decides the request against the supplied grants. The checks run
+     * role → capability → scope so the denial reason is the most informative
+     * one available:
+     *
+     * 1. no grant for the actor → `missing_role`;
+     * 2. has grants but none grants the permission → `missing_capability`;
+     * 3. grants the permission but not in scope → `out_of_scope`;
+     * 4. otherwise → ALLOW (`Result.ok`).
+     *
+     * @throws {@link InvalidValueException} when `request.required` is a wildcard
+     *   permission (only *granted* permissions may wildcard, never the *required*
+     *   one).
+     */
+    authorize(
+        request: AccessRequest,
+        grants: readonly Grant[],
+    ): Result<void, AuthorizationError> {
+        if (request.required.hasWildcard()) {
+            throw new InvalidValueException(
+                REQUIRED_FIELD,
+                ValidationCode.INVALID_FORMAT,
+                `AccessRequest.required must be a concrete permission, not a wildcard, got "${request.required.toPrimitive()}"`,
+            );
+        }
+
+        const required: AuthorizationRequirement = {
+            capability: request.required.toPrimitive(),
+            scope: request.scope.toPrimitive(),
+        };
+        const metadata = {
+            action: request.action,
+            resource: request.resource,
+            actor: { userId: request.actor.raw },
+            required,
+        };
+
+        const actorGrants = grants.filter((grant) =>
+            grant.appliesTo(request.actor),
+        );
+        if (actorGrants.length === 0) {
+            return Result.err(AuthorizationError.missingRole(metadata));
+        }
+
+        const withPermission = actorGrants.filter((grant) =>
+            grant.role.grants(request.required),
+        );
+        if (withPermission.length === 0) {
+            return Result.err(AuthorizationError.missingCapability(metadata));
+        }
+
+        const inScope = withPermission.filter((grant) =>
+            grant.scope.includes(request.scope),
+        );
+        if (inScope.length === 0) {
+            return Result.err(AuthorizationError.outOfScope(metadata));
+        }
+
+        return Result.ok(undefined);
+    }
+}
+
+export { RbacAuthorizer };

package/src/core/rbac/domain/grant.ts

@@ -0,0 +1,96 @@
+import { RequestedBy } from "../../application/commands/requested-by.js";
+import { ValueObject } from "../../domain/value-object.js";
+
+import { Role, type RoleProps } from "./role.js";
+import { Scope } from "./scope.js";
+
+/**
+ * The serializable shape a consumer persists and loads: the actor's identity
+ * (`RequestedBy.raw`), the role they hold (as {@link RoleProps}), and the scope
+ * the role applies in (the {@link Scope} string).
+ */
+type GrantProps = {
+    readonly subject: string;
+    readonly role: RoleProps;
+    readonly scope: string;
+};
+
+/**
+ * A role binding — it ties one actor to one {@link Role} within one
+ * {@link Scope}. This is the unit the consumer stores (a `(subject, role,
+ * scope)` row) and rehydrates into the pure decisor; the kit itself persists
+ * nothing.
+ *
+ * A zod-free value object built through {@link of} from live
+ * `RequestedBy`/`Role`/`Scope` objects; the getters reconstruct those objects
+ * back from the frozen primitive form.
+ */
+class Grant extends ValueObject<GrantProps, GrantProps> {
+    // The live objects are rehydrated once, at construction, and cached — the
+    // decisor reads `role`/`scope` at least once per grant, so parsing lazily on
+    // each getter access would re-parse the same frozen primitives repeatedly.
+    private readonly _subject: RequestedBy;
+    private readonly _role: Role;
+    private readonly _scope: Scope;
+
+    private constructor(props: GrantProps) {
+        super(props);
+        this._subject = RequestedBy.parse(this.value.subject);
+        this._role = Role.fromProps(this.value.role);
+        this._scope = Scope.of(this.value.scope);
+        this.finalize();
+    }
+
+    static of(params: {
+        subject: RequestedBy;
+        role: Role;
+        scope: Scope;
+    }): Grant {
+        return new Grant({
+            subject: params.subject.raw,
+            role: params.role.toPrimitive(),
+            scope: params.scope.toPrimitive(),
+        });
+    }
+
+    /**
+     * Rebuilds a grant from its serialized {@link GrantProps} — the inverse of
+     * {@link toPrimitive}, symmetric to {@link Role.fromProps}. Each part is
+     * re-validated (subject through {@link RequestedBy.parse}, role through
+     * {@link Role.fromProps}, scope through {@link Scope.of}), so a malformed
+     * payload still fails loudly.
+     */
+    static fromProps(props: GrantProps): Grant {
+        return new Grant(props);
+    }
+
+    get subject(): RequestedBy {
+        return this._subject;
+    }
+
+    get role(): Role {
+        return this._role;
+    }
+
+    get scope(): Scope {
+        return this._scope;
+    }
+
+    /** Whether this grant belongs to `actor`. */
+    appliesTo(actor: RequestedBy): boolean {
+        return this.value.subject === actor.raw;
+    }
+
+    toPrimitive(): GrantProps {
+        return {
+            subject: this.value.subject,
+            role: {
+                name: this.value.role.name,
+                permissions: [...this.value.role.permissions],
+            },
+            scope: this.value.scope,
+        };
+    }
+}
+
+export { Grant, type GrantProps };

package/src/core/rbac/domain/permission-set.ts

@@ -0,0 +1,67 @@
+import type { Grant } from "./grant.js";
+import type { Permission } from "./permission.js";
+
+/**
+ * The flattened, deduplicated permissions an actor effectively holds across a
+ * set of {@link Grant}s, together with the role names that contributed them.
+ *
+ * Pure resolution, isolated from the decisor so the "roles → permissions"
+ * collapse can be tested on its own. Build through {@link fromGrants}; pre-filter
+ * the grants to a single actor first when that matters (the set does not know
+ * which actor it describes).
+ */
+class PermissionSet {
+    private constructor(
+        private readonly permissions: readonly Permission[],
+        private readonly _roleNames: readonly string[],
+    ) {}
+
+    /**
+     * Collapses the roles across `grants` into one permission set. Permissions
+     * are deduplicated by their primitive form and role names by value, both
+     * preserving first-seen order.
+     */
+    static fromGrants(grants: readonly Grant[]): PermissionSet {
+        const permissions: Permission[] = [];
+        const seenPermissions = new Set<string>();
+        const roleNames: string[] = [];
+        const seenRoles = new Set<string>();
+
+        for (const grant of grants) {
+            const role = grant.role;
+
+            if (!seenRoles.has(role.name)) {
+                seenRoles.add(role.name);
+                roleNames.push(role.name);
+            }
+
+            for (const permission of role.permissions) {
+                const primitive = permission.toPrimitive();
+                if (seenPermissions.has(primitive)) continue;
+                seenPermissions.add(primitive);
+                permissions.push(permission);
+            }
+        }
+
+        return new PermissionSet(permissions, roleNames);
+    }
+
+    /** Whether any held permission {@link Permission.implies | implies} `required`. */
+    has(required: Permission): boolean {
+        return this.permissions.some((permission) =>
+            permission.implies(required),
+        );
+    }
+
+    /** The effective permissions, deduplicated. */
+    toArray(): readonly Permission[] {
+        return this.permissions;
+    }
+
+    /** The names of the roles that contributed to this set, deduplicated. */
+    get roleNames(): readonly string[] {
+        return this._roleNames;
+    }
+}
+
+export { PermissionSet };

package/src/core/rbac/domain/permission.ts

@@ -0,0 +1,119 @@
+import { ValidationCode } from "../../exceptions/validation-code.js";
+import { InvalidValueException } from "../../exceptions/validation-exception.js";
+import { ValidationField } from "../../exceptions/validation-field.js";
+import { ValueObject } from "../../domain/value-object.js";
+
+/** The two halves of a permission: what is acted on, and what is done to it. */
+type PermissionProps = {
+    readonly resource: string;
+    readonly action: string;
+};
+
+const PERMISSION_FIELD = ValidationField.of("permission");
+
+// A segment is either a whole-segment wildcard (`*`) or a run of lowercase
+// alphanumerics, hyphens and underscores. Partial wildcards (`ord*`) are
+// rejected on purpose: a `*` only ever stands for an entire segment.
+const SEGMENT_PATTERN = /^(?:\*|[a-z0-9_-]+)$/u;
+
+/**
+ * A `"<resource>:<action>"` capability such as `"orders:cancel"`, with a
+ * single-level wildcard. Either segment may be the whole-segment wildcard `*`
+ * (`"orders:*"`, `"*:cancel"`, `"*:*"`), which is what lets a broad grant cover
+ * a narrower requirement — see {@link implies}.
+ *
+ * A zod-free value object: it validates its own format on construction
+ * (throwing {@link InvalidValueException}) and is frozen thereafter. Build one
+ * through {@link of} (from a raw `"resource:action"` string) or {@link for}
+ * (from already-separated parts); the constructor is private.
+ */
+class Permission extends ValueObject<PermissionProps, string> {
+    private constructor(props: PermissionProps) {
+        super(props);
+        this.finalize();
+    }
+
+    /**
+     * Parses a `"resource:action"` string. Throws {@link InvalidValueException}
+     * when the string is blank, lacks exactly one `:`, or carries an invalid
+     * segment.
+     */
+    static of(raw: string): Permission {
+        if (typeof raw !== "string" || raw.trim().length === 0) {
+            throw new InvalidValueException(
+                PERMISSION_FIELD,
+                ValidationCode.BLANK,
+                `permission must be a non-empty "resource:action" string, got "${raw}"`,
+            );
+        }
+
+        const parts = raw.split(":");
+        if (parts.length !== 2) {
+            throw new InvalidValueException(
+                PERMISSION_FIELD,
+                ValidationCode.INVALID_FORMAT,
+                `permission must have exactly one ":" separating resource and action, got "${raw}"`,
+            );
+        }
+
+        return Permission.for(parts[0], parts[1]);
+    }
+
+    /**
+     * Builds from already-separated `resource` and `action` parts. Each must be
+     * a valid segment (`[a-z0-9_-]+` or the whole-segment wildcard `*`).
+     */
+    static for(resource: string, action: string): Permission {
+        Permission.assertSegment(resource, "resource");
+        Permission.assertSegment(action, "action");
+        return new Permission({ resource, action });
+    }
+
+    private static assertSegment(
+        value: string,
+        label: "resource" | "action",
+    ): void {
+        if (typeof value !== "string" || !SEGMENT_PATTERN.test(value)) {
+            throw new InvalidValueException(
+                PERMISSION_FIELD.nested(label),
+                ValidationCode.INVALID_FORMAT,
+                `permission ${label} must match [a-z0-9_-]+ or be the whole-segment wildcard "*" (no partial wildcards), got "${value}"`,
+            );
+        }
+    }
+
+    get resource(): string {
+        return this.value.resource;
+    }
+
+    get action(): string {
+        return this.value.action;
+    }
+
+    /**
+     * Whether holding this permission grants `other`. A `*` segment matches any
+     * value in the same position, so `"orders:*"` implies `"orders:cancel"` and
+     * `"*:*"` implies everything. Concrete segments must match exactly.
+     */
+    implies(other: Permission): boolean {
+        return (
+            (this.resource === "*" || this.resource === other.resource) &&
+            (this.action === "*" || this.action === other.action)
+        );
+    }
+
+    /**
+     * Whether either segment is the whole-segment wildcard `*`. A *granted*
+     * permission may wildcard (see {@link implies}); a *required* one may not —
+     * `RbacAuthorizer` rejects a wildcard requirement as caller misuse.
+     */
+    hasWildcard(): boolean {
+        return this.value.resource === "*" || this.value.action === "*";
+    }
+
+    toPrimitive(): string {
+        return `${this.value.resource}:${this.value.action}`;
+    }
+}
+
+export { Permission, type PermissionProps };