@cullet/erp-core 1.2.0 → 1.4.0

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 };

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/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.2.0";
+export const version = "1.4.0";