@cullet/erp-core 1.3.0 → 1.4.0

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

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()),
+    };
+}