@cullet/erp-core 1.2.0 → 1.4.0

package/src/core/abac/domain/rule.ts

@@ -0,0 +1,197 @@
+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 type {
+    ConditionNode,
+    ConditionOp,
+} from "../../policies/engines/v1/condition-types.js";
+
+/** Whether a matching {@link AbacRule} permits or denies the action. */
+type RuleEffect = "PERMIT" | "DENY";
+
+/**
+ * The serializable shape of a rule: a stable `id`/`version` (surfaced on a
+ * denial as `policyId`/`policyVersion`), the {@link RuleEffect}, and the
+ * {@link ConditionNode} that decides whether the rule applies to a request's
+ * flattened attributes.
+ */
+type AbacRuleProps = {
+    readonly id: string;
+    readonly version: number;
+    readonly effect: RuleEffect;
+    readonly condition: ConditionNode;
+    readonly description?: string;
+};
+
+const RULE_FIELD = ValidationField.of("abacRule");
+
+const CONDITION_OPS = new Set<ConditionOp>([
+    "eq",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "notIn",
+    "isNull",
+    "isNotNull",
+]);
+
+const RULE_EFFECTS = new Set<RuleEffect>(["PERMIT", "DENY"]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A single attribute-based rule: an {@link RuleEffect} that takes hold when its
+ * {@link ConditionNode} matches the request's flattened attributes. The
+ * condition reuses the gate/compute condition DSL (`{ field, op, value }` leaves
+ * combined with `and`/`or`/`not`), so a consumer learns one condition language
+ * across the whole kit.
+ *
+ * A zod-free value object: it validates its own shape on construction (throwing
+ * {@link InvalidValueException}) and is deep-frozen thereafter. Because rules are
+ * authored in TypeScript — trusted data, not untrusted JSON — the structural
+ * check is a hand-rolled walk of the condition tree rather than a schema parse.
+ * Build one through {@link of}; the constructor is private.
+ */
+class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
+    private constructor(props: AbacRuleProps) {
+        super(props);
+        this.finalize();
+    }
+
+    /**
+     * Builds a rule, validating that `id` is non-blank, `version` is an integer
+     * ≥ 1, `effect` is `"PERMIT"`/`"DENY"`, and `condition` is a well-formed
+     * condition node. Throws {@link InvalidValueException} otherwise.
+     */
+    static of(props: AbacRuleProps): AbacRule {
+        if (typeof props.id !== "string" || props.id.trim().length === 0) {
+            throw new InvalidValueException(
+                RULE_FIELD.nested("id"),
+                ValidationCode.BLANK,
+                `abac rule id must be a non-empty string, got "${props.id}"`,
+            );
+        }
+
+        if (!Number.isInteger(props.version) || props.version < 1) {
+            throw new InvalidValueException(
+                RULE_FIELD.nested("version"),
+                ValidationCode.OUT_OF_RANGE,
+                `abac rule version must be an integer >= 1, got "${props.version}"`,
+            );
+        }
+
+        if (!RULE_EFFECTS.has(props.effect)) {
+            throw new InvalidValueException(
+                RULE_FIELD.nested("effect"),
+                ValidationCode.INVALID_FORMAT,
+                `abac rule effect must be "PERMIT" or "DENY", got "${String(props.effect)}"`,
+            );
+        }
+
+        AbacRule.assertConditionShape(props.condition);
+
+        return new AbacRule(props);
+    }
+
+    // Mirrors what the shared condition evaluator would reject at eval time
+    // (empty and/or nodes, malformed leaves) but fails fast at construction.
+    private static assertConditionShape(node: unknown): void {
+        if (!isPlainObject(node)) {
+            AbacRule.rejectCondition(
+                "abac rule condition must be a leaf { field, op } or an { and | or | not } node",
+            );
+        }
+
+        if ("and" in node || "or" in node) {
+            const key = "and" in node ? "and" : "or";
+            const children = node[key];
+            if (!Array.isArray(children) || children.length === 0) {
+                AbacRule.rejectCondition(
+                    `abac rule "${key}" node must hold a non-empty array of child conditions`,
+                );
+            }
+            for (const child of children) {
+                AbacRule.assertConditionShape(child);
+            }
+            return;
+        }
+
+        if ("not" in node) {
+            AbacRule.assertConditionShape(node.not);
+            return;
+        }
+
+        if ("field" in node && "op" in node) {
+            if (
+                typeof node.field !== "string" ||
+                node.field.trim().length === 0
+            ) {
+                AbacRule.rejectCondition(
+                    `abac rule condition leaf "field" must be a non-empty string, got "${String(node.field)}"`,
+                );
+            }
+            if (
+                typeof node.op !== "string" ||
+                !CONDITION_OPS.has(node.op as ConditionOp)
+            ) {
+                AbacRule.rejectCondition(
+                    `abac rule condition leaf "op" is not a supported operator, got "${String(node.op)}"`,
+                );
+            }
+            return;
+        }
+
+        AbacRule.rejectCondition(
+            "abac rule condition must be a leaf { field, op } or an { and | or | not } node",
+        );
+    }
+
+    private static rejectCondition(message: string): never {
+        throw new InvalidValueException(
+            RULE_FIELD.nested("condition"),
+            ValidationCode.INVALID_FORMAT,
+            message,
+        );
+    }
+
+    get id(): string {
+        return this.value.id;
+    }
+
+    get version(): number {
+        return this.value.version;
+    }
+
+    get effect(): RuleEffect {
+        return this.value.effect;
+    }
+
+    /** The condition tree evaluated against a request's flattened attributes. */
+    get condition(): ConditionNode {
+        return this.value.condition as ConditionNode;
+    }
+
+    get description(): string | undefined {
+        return this.value.description;
+    }
+
+    toPrimitive(): AbacRuleProps {
+        return {
+            id: this.value.id,
+            version: this.value.version,
+            effect: this.value.effect,
+            condition: this.value.condition as ConditionNode,
+            ...(this.value.description !== undefined
+                ? { description: this.value.description }
+                : {}),
+        };
+    }
+}
+
+export { AbacRule, type AbacRuleProps, type RuleEffect };

package/src/core/abac/index.ts

@@ -0,0 +1,21 @@
+// Barrel for the zod-free ABAC module: the pure rule/policy-set primitives, the
+// combining algorithms, the attribute→context flattening, the pure decisor, the
+// optional RBAC+ABAC composite, and the AbacAuthorizerPort seam (which physically
+// lives under application/ports/ but is surfaced here as the ABAC public home).
+
+export type { AbacAuthorizerPort } from "../application/ports/abac-authorizer.port.js";
+
+export type { AbacAttributes, AbacRequest } from "./abac-request.js";
+export { abacContext } from "./attributes.js";
+export { AbacAuthorizer, type AbacDecision } from "./authorizer.js";
+export type { CombiningAlgorithm } from "./combining.js";
+export {
+    type CompositeAccessRequest,
+    CompositeAuthorizer,
+} from "./composite-authorizer.js";
+export { AbacPolicySet } from "./domain/policy-set.js";
+export {
+    AbacRule,
+    type AbacRuleProps,
+    type RuleEffect,
+} from "./domain/rule.js";

package/src/core/application/ports/abac-authorizer.port.ts

@@ -0,0 +1,20 @@
+import type { AbacRequest } from "../../abac/abac-request.js";
+import type { AuthorizationError } from "../../errors/authorization-error.js";
+import type { Result } from "../../result/result.js";
+
+/**
+ * The seam an application layer injects to authorize an action by attributes —
+ * symmetric to {@link AuthorizerPort} (RBAC). The use case depends only on this
+ * contract; an adapter in the consumer's stack resolves the dynamic attributes
+ * (resource state, environment, RBAC facts) and delegates the decision to the
+ * pure `AbacAuthorizer`.
+ *
+ * Returns the decision as a {@link Result}: `ok(void)` when permitted, or
+ * `err(AuthorizationError)` carrying `reason: "policy_denied"` (or `"forbidden"`
+ * on a fail-closed evaluation error) that the HTTP boundary maps to a 403.
+ */
+interface AbacAuthorizerPort {
+    authorize(request: AbacRequest): Promise<Result<void, AuthorizationError>>;
+}
+
+export type { AbacAuthorizerPort };

package/src/core/application/ports/authorizer.port.ts

@@ -0,0 +1,22 @@
+import type { AuthorizationError } from "../../errors/authorization-error.js";
+import type { AccessRequest } from "../../rbac/access-request.js";
+import type { Result } from "../../result/result.js";
+
+/**
+ * The seam an application layer injects to authorize an action — symmetric to
+ * {@link PolicyPort}. The use case depends only on this contract; an adapter in
+ * the consumer's stack loads the actor's grants (from its own store) and
+ * delegates the decision to the pure `RbacAuthorizer`.
+ *
+ * Returns the decision as a {@link Result}: `ok(void)` when allowed, or
+ * `err(AuthorizationError)` carrying the discriminated `reason` the HTTP
+ * boundary maps to a 403. Promised here under `[extension-points]` in
+ * KIT_CONTEXT.md.
+ */
+interface AuthorizerPort {
+    authorize(
+        request: AccessRequest,
+    ): Promise<Result<void, AuthorizationError>>;
+}
+
+export type { AuthorizerPort };

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