@cullet/erp-core 1.3.0 → 1.5.0

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

@@ -0,0 +1,101 @@
+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";
+
+import { Permission } from "./permission.js";
+
+/**
+ * The serializable shape of a role: a name plus its permissions kept as their
+ * primitive `"resource:action"` strings (so the role round-trips through JSON
+ * and stays deep-frozen). The {@link Role.permissions} getter rehydrates them
+ * back into {@link Permission} objects.
+ */
+type RoleProps = {
+    readonly name: string;
+    readonly permissions: readonly string[];
+};
+
+const ROLE_FIELD = ValidationField.of("role");
+
+/**
+ * A named bundle of {@link Permission}s — `"cashier"`, `"manager"`, `"admin"`.
+ * There is **no role hierarchy** in v1: a role grants exactly the permissions
+ * it lists (wildcards included). Duplicate permissions are collapsed on
+ * construction, preserving first-seen order.
+ *
+ * A zod-free value object. Build through {@link of}; reconstruct a serialized
+ * one through {@link fromProps}.
+ */
+class Role extends ValueObject<RoleProps, RoleProps> {
+    // Parsed once, at construction, and cached: the decisor calls `grants` (and
+    // `PermissionSet` reads `permissions`) repeatedly, so re-parsing the stored
+    // strings on every access would be wasted work.
+    private readonly _permissions: readonly Permission[];
+
+    private constructor(props: RoleProps) {
+        super(props);
+        this._permissions = this.value.permissions.map(Permission.of);
+        this.finalize();
+    }
+
+    /**
+     * Builds a role from a name and its permissions. Throws
+     * {@link InvalidValueException} when the name is blank. Duplicate
+     * permissions are deduplicated.
+     */
+    static of(name: string, permissions: readonly Permission[]): Role {
+        if (typeof name !== "string" || name.trim().length === 0) {
+            throw new InvalidValueException(
+                ROLE_FIELD,
+                ValidationCode.BLANK,
+                `role name must be a non-empty string, got "${name}"`,
+            );
+        }
+
+        const seen = new Set<string>();
+        const deduped: string[] = [];
+        for (const permission of permissions) {
+            const primitive = permission.toPrimitive();
+            if (seen.has(primitive)) continue;
+            seen.add(primitive);
+            deduped.push(primitive);
+        }
+
+        return new Role({ name, permissions: deduped });
+    }
+
+    /**
+     * Rebuilds a role from its serialized {@link RoleProps} — the inverse of
+     * {@link toPrimitive}. Each stored string is re-parsed through
+     * {@link Permission.of}, so a malformed payload still fails loudly.
+     */
+    static fromProps(props: RoleProps): Role {
+        return Role.of(props.name, props.permissions.map(Permission.of));
+    }
+
+    get name(): string {
+        return this.value.name;
+    }
+
+    /** The role's permissions, rehydrated from their stored primitive form. */
+    get permissions(): readonly Permission[] {
+        return this._permissions;
+    }
+
+    /** Whether any permission in this role {@link Permission.implies | implies} `required`. */
+    grants(required: Permission): boolean {
+        return this._permissions.some((permission) =>
+            permission.implies(required),
+        );
+    }
+
+    toPrimitive(): RoleProps {
+        return {
+            name: this.value.name,
+            permissions: [...this.value.permissions],
+        };
+    }
+}
+
+export { Role, type RoleProps };

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

@@ -0,0 +1,84 @@
+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 wrapped, already-validated scope string (`"type:id"` or `"*"`). */
+type ScopeProps = { readonly raw: string };
+
+const SCOPE_FIELD = ValidationField.of("scope");
+
+// "type:id": a lowercase type segment, a colon, then a non-empty id. The id
+// charset is permissive enough for UUIDs and numeric keys (`school:42`,
+// `tenant:550e8400-e29b-41d4-a716-446655440000`).
+const SCOPE_PATTERN = /^[a-z][a-z0-9_-]*:[A-Za-z0-9._-]+$/u;
+
+/**
+ * Where a grant (or a target resource) lives, aligned with
+ * `AuthorizationRequirement.scope` and the policy `PolicyScope`
+ * (`tenantId`/`schoolId`): `"tenant:{id}"`, `"school:{id}"`, or the global
+ * `"*"`.
+ *
+ * v1 keeps containment ({@link includes}) flat — the global scope contains
+ * everything, and any other scope contains only itself. A real hierarchy
+ * (`tenant` ⊇ `school`) is a deliberately deferred extension point.
+ */
+class Scope extends ValueObject<ScopeProps, string> {
+    private constructor(props: ScopeProps) {
+        super(props);
+        this.finalize();
+    }
+
+    /** Validates `"type:id"` or the global `"*"`, throwing on anything else. */
+    static of(raw: string): Scope {
+        if (typeof raw !== "string" || raw.trim().length === 0) {
+            throw new InvalidValueException(
+                SCOPE_FIELD,
+                ValidationCode.BLANK,
+                `scope must be a non-empty "type:id" string or "*", got "${raw}"`,
+            );
+        }
+
+        if (raw !== "*" && !SCOPE_PATTERN.test(raw)) {
+            throw new InvalidValueException(
+                SCOPE_FIELD,
+                ValidationCode.INVALID_FORMAT,
+                `scope must be "type:id" (e.g. "school:42") or the global "*", got "${raw}"`,
+            );
+        }
+
+        return new Scope({ raw });
+    }
+
+    /** The global scope `"*"`, which {@link includes} every other scope. */
+    static global(): Scope {
+        return new Scope({ raw: "*" });
+    }
+
+    /** The type segment, or `"*"` for the global scope. */
+    get type(): string {
+        if (this.value.raw === "*") return "*";
+        return this.value.raw.slice(0, this.value.raw.indexOf(":"));
+    }
+
+    /** The id segment, or `undefined` for the global scope. */
+    get id(): string | undefined {
+        if (this.value.raw === "*") return undefined;
+        return this.value.raw.slice(this.value.raw.indexOf(":") + 1);
+    }
+
+    /**
+     * Whether this scope contains `target`. The global scope contains
+     * everything; any other scope contains only an exact match of itself.
+     */
+    includes(target: Scope): boolean {
+        if (this.value.raw === "*") return true;
+        return this.value.raw === target.value.raw;
+    }
+
+    toPrimitive(): string {
+        return this.value.raw;
+    }
+}
+
+export { Scope, type ScopeProps };

package/src/core/rbac/index.ts

@@ -0,0 +1,15 @@
+// Barrel for the zod-free RBAC module: the pure domain primitives, the pure
+// decisor, the optional policy bridge, and the AuthorizerPort seam (which
+// physically lives under application/ports/ but is surfaced here as the RBAC
+// public home).
+
+export type { AuthorizerPort } from "../application/ports/authorizer.port.js";
+
+export type { AccessRequest } from "./access-request.js";
+export { RbacAuthorizer } from "./authorizer.js";
+export { Grant, type GrantProps } from "./domain/grant.js";
+export { Permission, type PermissionProps } from "./domain/permission.js";
+export { PermissionSet } from "./domain/permission-set.js";
+export { Role, type RoleProps } from "./domain/role.js";
+export { Scope, type ScopeProps } from "./domain/scope.js";
+export { rbacContextFields } from "./policy-bridge.js";

package/src/core/rbac/policy-bridge.ts

@@ -0,0 +1,44 @@
+import type { RequestedBy } from "../application/commands/requested-by.js";
+
+import type { Grant } from "./domain/grant.js";
+import { PermissionSet } from "./domain/permission-set.js";
+
+/**
+ * Projects an actor's RBAC facts into flat {@link PolicyContext}-style fields so
+ * a declarative gate policy can reason over them (ABAC) — without importing the
+ * policy engine or `zod`. It only builds a plain object; the consumer merges it
+ * into `seed.fields` of `PolicyService.evaluate(...)`.
+ *
+ * The grants are filtered to `actor` first, so passing an actor's full grant
+ * list (or a mixed one) is safe.
+ *
+ * **Wildcards are projected literally — they are NOT expanded.** `actor.roles`
+ * and `actor.permissions` are the exact stored strings, so a permission such as
+ * `"orders:*"` or `"*:*"` appears verbatim. A gate condition like
+ * `{ field: "actor.permissions", op: "in", value: "orders:cancel" }` does a
+ * *literal* membership test and will therefore NOT match a holder of
+ * `"orders:*"`. Open-ended wildcards cannot be enumerated into a finite list, so
+ * for wildcard-aware checks either match on the finite `actor.roles` instead, or
+ * make the wildcard-aware decision with `RbacAuthorizer` (which knows
+ * {@link Permission.implies}) and use the gate only for the extra ABAC
+ * conditions.
+ *
+ * @returns `{ "actor.id", "actor.roles", "actor.permissions" }`, where roles and
+ *   permissions are plain string arrays (wildcards left literal).
+ */
+export function rbacContextFields(
+    actor: RequestedBy,
+    grants: readonly Grant[],
+): Record<string, unknown> {
+    const set = PermissionSet.fromGrants(
+        grants.filter((grant) => grant.appliesTo(actor)),
+    );
+
+    return {
+        "actor.id": actor.raw,
+        "actor.roles": [...set.roleNames],
+        "actor.permissions": set
+            .toArray()
+            .map((permission) => permission.toPrimitive()),
+    };
+}

package/src/core/shared/hashing.ts

@@ -1,65 +1,11 @@
 import { createHash } from "node:crypto";
 
-const CIRCULAR_STRUCTURE_MESSAGE =
-    "Cannot stably stringify a circular structure";
+import { stableStringify } from "./stable-stringify.js";
 
 function sha256Hex(value: string): string {
     return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-// `seen` holds the current traversal branch so true cycles are rejected while
-// repeated (acyclic) references are still serialized — matching JSON.stringify.
-function sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {
-    if (Array.isArray(value)) {
-        if (seen.has(value)) {
-            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
-        }
-        seen.add(value);
-        const mapped = value.map((item) => sortKeysDeep(item, seen));
-        seen.delete(value);
-        return mapped;
-    }
-
-    if (value instanceof Date) {
-        return value;
-    }
-
-    if (value && typeof value === "object") {
-        if (seen.has(value)) {
-            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
-        }
-        seen.add(value);
-        const record = value as Record<string, unknown>;
-        const ordered = Object.create(null) as Record<string, unknown>;
-
-        for (const key of Object.keys(record).sort()) {
-            ordered[key] = sortKeysDeep(record[key], seen);
-        }
-        seen.delete(value);
-
-        return ordered;
-    }
-
-    return value;
-}
-
-/**
- * Deterministic JSON string with object keys sorted recursively, so key order
- * does not affect the output.
- *
- * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
- * functions and symbols are dropped, non-finite numbers become `null`, `bigint`
- * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
- * collapse to the same string — for collision-resistant hashing use
- * `PolicyHashing.canonicalJson` (policies/utils), which rejects those values
- * up front.
- *
- * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
- */
-function stableStringify(value: unknown): string {
-    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));
-}
-
 function payloadHash(value: unknown): string {
     return sha256Hex(stableStringify(value));
 }

package/src/core/shared/stable-stringify.ts

@@ -0,0 +1,57 @@
+const CIRCULAR_STRUCTURE_MESSAGE =
+    "Cannot stably stringify a circular structure";
+
+// `seen` holds the current traversal branch so true cycles are rejected while
+// repeated (acyclic) references are still serialized — matching JSON.stringify.
+function sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+        }
+        seen.add(value);
+        const mapped = value.map((item) => sortKeysDeep(item, seen));
+        seen.delete(value);
+        return mapped;
+    }
+
+    if (value instanceof Date) {
+        return value;
+    }
+
+    if (value && typeof value === "object") {
+        if (seen.has(value)) {
+            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+        }
+        seen.add(value);
+        const record = value as Record<string, unknown>;
+        const ordered = Object.create(null) as Record<string, unknown>;
+
+        for (const key of Object.keys(record).sort()) {
+            ordered[key] = sortKeysDeep(record[key], seen);
+        }
+        seen.delete(value);
+
+        return ordered;
+    }
+
+    return value;
+}
+
+/**
+ * Deterministic JSON string with object keys sorted recursively, so key order
+ * does not affect the output.
+ *
+ * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
+ * functions and symbols are dropped, non-finite numbers become `null`, `bigint`
+ * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
+ * collapse to the same string — for collision-resistant hashing use
+ * `PolicyHashing.canonicalJson` (policies/utils), which rejects those values
+ * up front.
+ *
+ * @throws {TypeError} On circular references (mirroring `JSON.stringify`).
+ */
+function stableStringify(value: unknown): string {
+    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));
+}
+
+export { stableStringify };

package/src/core/shared/uuid.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical RFC-4122 UUID (versions 1–5, variant 8/9/a/b), matched
+ * case-insensitively. The single source of truth for the UUID format —
+ * `UuidIdentifier` (domain ids) and `RequestedBy` (command actor) both
+ * validate against this pattern, so an identity accepted at the application
+ * boundary is always one the domain also considers valid.
+ */
+const UUID_PATTERN =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export { UUID_PATTERN };

package/src/examples/application/authorize-cancel-order-abac.example.ts

@@ -0,0 +1,107 @@
+/**
+ * End-to-end reference for the ABAC seam: a concrete {@link Command} that refines
+ * a mutation through an {@link AbacAuthorizerPort} — deciding on the *attributes*
+ * of the request (the order's live status, the environment) rather than a static
+ * capability.
+ *
+ * Unlike the RBAC example, the aggregate is loaded *before* authorizing: ABAC
+ * reasons over resource state, so that state has to exist first. A denial comes
+ * back as `Result.err(AuthorizationError)` (translated to a 403 at the edge); a
+ * missing aggregate or a repository failure stays in band as `Result.err` too —
+ * the "errors as values" contract, never a thrown exception.
+ *
+ * Consumers import these symbols from `@cullet/erp-core` and
+ * `@cullet/erp-core/abac`; inside the kit we use relative paths so the example
+ * stays compilable and test-covered, guarding the README/KIT_CONTEXT snippet
+ * against rot.
+ */
+import type { AbacAuthorizerPort } from "../../core/abac/index.js";
+import { Command, type CommandInput } from "../../core/application/index.js";
+import type { ResultRepository } from "../../core/application/index.js";
+import { AuthorizationError } from "../../core/errors/authorization-error.js";
+import { NotFoundError } from "../../core/errors/not-found-error.js";
+import { Result } from "../../core/result/result.js";
+
+// ─── Minimal domain ─────────────────────────────────────────────────────────
+
+type OrderStatus = "OPEN" | "CANCELLED";
+
+interface Order {
+    readonly id: string;
+    readonly status: OrderStatus;
+    readonly locked: boolean;
+}
+
+// ─── Command contract ────────────────────────────────────────────────────────
+
+interface CancelOrderInput extends CommandInput {
+    readonly orderId: string;
+    /** An environment attribute the composition root resolves from its clock. */
+    readonly businessHours: boolean;
+}
+
+type CancelOrderError = NotFoundError | AuthorizationError;
+
+// ─── The use case ─────────────────────────────────────────────────────────────
+
+class CancelOrder extends Command<
+    CancelOrderInput,
+    Result<Order, CancelOrderError>
+> {
+    constructor(
+        private readonly orders: ResultRepository<
+            Order,
+            string,
+            CancelOrderError
+        >,
+        private readonly authorizer: AbacAuthorizerPort,
+    ) {
+        super();
+    }
+
+    protected async execute(
+        input: CancelOrderInput,
+    ): Promise<Result<Order, CancelOrderError>> {
+        // 1. Load the aggregate — its live state feeds the ABAC decision.
+        const found = await this.orders.findById(input.orderId);
+        if (found.isErr()) {
+            return found;
+        }
+
+        const order = found.getOrThrow();
+        if (!order) {
+            return Result.err(
+                new NotFoundError("Order", { id: input.orderId }),
+            );
+        }
+
+        // 2. Gate on attributes: the order's status/lock plus the environment.
+        //    `CommandInput.requestedBy` is the ABAC subject.
+        const allowed = await this.authorizer.authorize({
+            actor: input.requestedBy,
+            action: "order.cancel",
+            resource: { type: "Order", id: order.id },
+            attributes: {
+                resource: { status: order.status, locked: order.locked },
+                environment: { businessHours: input.businessHours },
+            },
+        });
+        if (allowed.isErr()) {
+            // AuthorizationError → 403 at the boundary.
+            return Result.err(allowed.error);
+        }
+
+        // 3. Mutate and persist. A version conflict on save also surfaces as
+        //    Result.err — never an exception crossing the boundary.
+        const cancelled: Order = { ...order, status: "CANCELLED" };
+        const saved = await this.orders.save(cancelled);
+        if (saved.isErr()) {
+            return saved;
+        }
+
+        return Result.ok(cancelled);
+    }
+}
+
+export { CancelOrder };
+export type { CancelOrderError, CancelOrderInput, Order, OrderStatus };

package/src/examples/application/authorize-cancel-order.example.ts

@@ -0,0 +1,101 @@
+/**
+ * End-to-end reference for the RBAC seam: a concrete {@link Command} that gates
+ * a mutation through an {@link AuthorizerPort} before touching the aggregate.
+ *
+ * Flow: ask the injected authorizer whether the actor may cancel the order →
+ * load the aggregate → mutate and persist. An authorization denial comes back
+ * as `Result.err(AuthorizationError)` (translated to a 403 at the edge), and a
+ * missing aggregate or a repository failure stays in band as `Result.err`
+ * too — the "errors as values" contract, never a thrown exception.
+ *
+ * Consumers import these symbols from `@cullet/erp-core` and
+ * `@cullet/erp-core/rbac`; inside the kit we use relative paths so the example
+ * stays compilable and test-covered, guarding the README/KIT_CONTEXT snippet
+ * against rot.
+ */
+import { Command, type CommandInput } from "../../core/application/index.js";
+import type { ResultRepository } from "../../core/application/index.js";
+import type { AuthorizerPort } from "../../core/application/ports/authorizer.port.js";
+import { AuthorizationError } from "../../core/errors/authorization-error.js";
+import { NotFoundError } from "../../core/errors/not-found-error.js";
+import { Permission, Scope } from "../../core/rbac/index.js";
+import { Result } from "../../core/result/result.js";
+
+// ─── Minimal domain ─────────────────────────────────────────────────────────
+
+type OrderStatus = "OPEN" | "CANCELLED";
+
+interface Order {
+    readonly id: string;
+    readonly status: OrderStatus;
+}
+
+// ─── Command contract ────────────────────────────────────────────────────────
+
+interface CancelOrderInput extends CommandInput {
+    readonly orderId: string;
+    readonly schoolId: string;
+}
+
+type CancelOrderError = NotFoundError | AuthorizationError;
+
+// ─── The use case ─────────────────────────────────────────────────────────────
+
+class CancelOrder extends Command<
+    CancelOrderInput,
+    Result<Order, CancelOrderError>
+> {
+    constructor(
+        private readonly orders: ResultRepository<
+            Order,
+            string,
+            CancelOrderError
+        >,
+        private readonly authorizer: AuthorizerPort,
+    ) {
+        super();
+    }
+
+    protected async execute(
+        input: CancelOrderInput,
+    ): Promise<Result<Order, CancelOrderError>> {
+        // 1. Gate the action. `CommandInput.requestedBy` is the RBAC actor.
+        const allowed = await this.authorizer.authorize({
+            actor: input.requestedBy,
+            action: "order.cancel",
+            required: Permission.of("orders:cancel"),
+            resource: { type: "Order", id: input.orderId },
+            scope: Scope.of(`school:${input.schoolId}`),
+        });
+        if (allowed.isErr()) {
+            // AuthorizationError → 403 at the boundary.
+            return Result.err(allowed.error);
+        }
+
+        // 2. Load the aggregate. Infra failures stay in band as Result.err.
+        const found = await this.orders.findById(input.orderId);
+        if (found.isErr()) {
+            return found;
+        }
+
+        const order = found.getOrThrow();
+        if (!order) {
+            return Result.err(
+                new NotFoundError("Order", { id: input.orderId }),
+            );
+        }
+
+        // 3. Mutate and persist. A version conflict on save also surfaces as
+        //    Result.err — never an exception crossing the boundary.
+        const cancelled: Order = { ...order, status: "CANCELLED" };
+        const saved = await this.orders.save(cancelled);
+        if (saved.isErr()) {
+            return saved;
+        }
+
+        return Result.ok(cancelled);
+    }
+}
+
+export { CancelOrder };
+export type { CancelOrderError, CancelOrderInput, Order, OrderStatus };

package/src/rbac/index.ts

@@ -0,0 +1 @@
+export * from "../core/rbac/index.js";

package/src/version.ts

@@ -4,4 +4,4 @@
 // Mantemos a versao aqui, dentro de src/, para que a copia full-control seja
 // auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um
 // `../package.json` que deixaria de existir no projeto consumidor.
-export const version = "1.3.0";
+export const version = "1.5.0";