@cullet/erp-core 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cullet/erp-core",
-    "version": "1.2.0",
+    "version": "1.4.0",
     "description": "Núcleo arquitetural para ERP em TypeScript — entidades, value objects, erros tipados e policies declaráveis sobre clean architecture.",
     "type": "module",
     "repository": {
@@ -8,60 +8,205 @@
         "url": "git+https://github.com/fabiano-eduardo/cullet.git",
         "directory": "packages/erp-core"
     },
-    "main": "./dist/index.js",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
     "types": "./dist/index.d.ts",
+    "typesVersions": {
+        "*": {
+            "abac": [
+                "./dist/abac/index.d.ts"
+            ],
+            "application": [
+                "./dist/application/index.d.ts"
+            ],
+            "domain": [
+                "./dist/domain/index.d.ts"
+            ],
+            "errors": [
+                "./dist/errors/index.d.ts"
+            ],
+            "exceptions": [
+                "./dist/exceptions/index.d.ts"
+            ],
+            "exceptions/validation-field": [
+                "./dist/exceptions/validation-field.d.ts"
+            ],
+            "plugins": [
+                "./dist/plugins/index.d.ts"
+            ],
+            "policies": [
+                "./dist/policies/index.d.ts"
+            ],
+            "policies/engines": [
+                "./dist/policies/engines/index.d.ts"
+            ],
+            "policies/engines/v1/gate": [
+                "./dist/policies/engines/v1/gate/index.d.ts"
+            ],
+            "rbac": [
+                "./dist/rbac/index.d.ts"
+            ],
+            "result": [
+                "./dist/result/index.d.ts"
+            ],
+            "rulesets": [
+                "./dist/rulesets/index.d.ts"
+            ],
+            "versioning": [
+                "./dist/versioning/index.d.ts"
+            ]
+        }
+    },
     "exports": {
         ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        },
+        "./abac": {
+            "import": {
+                "types": "./dist/abac/index.d.ts",
+                "default": "./dist/abac/index.js"
+            },
+            "require": {
+                "types": "./dist/abac/index.d.cts",
+                "default": "./dist/abac/index.cjs"
+            }
         },
         "./application": {
-            "types": "./dist/application/index.d.ts",
-            "import": "./dist/application/index.js"
+            "import": {
+                "types": "./dist/application/index.d.ts",
+                "default": "./dist/application/index.js"
+            },
+            "require": {
+                "types": "./dist/application/index.d.cts",
+                "default": "./dist/application/index.cjs"
+            }
         },
         "./domain": {
-            "types": "./dist/domain/index.d.ts",
-            "import": "./dist/domain/index.js"
+            "import": {
+                "types": "./dist/domain/index.d.ts",
+                "default": "./dist/domain/index.js"
+            },
+            "require": {
+                "types": "./dist/domain/index.d.cts",
+                "default": "./dist/domain/index.cjs"
+            }
         },
         "./errors": {
-            "types": "./dist/errors/index.d.ts",
-            "import": "./dist/errors/index.js"
+            "import": {
+                "types": "./dist/errors/index.d.ts",
+                "default": "./dist/errors/index.js"
+            },
+            "require": {
+                "types": "./dist/errors/index.d.cts",
+                "default": "./dist/errors/index.cjs"
+            }
         },
         "./exceptions": {
-            "types": "./dist/exceptions/index.d.ts",
-            "import": "./dist/exceptions/index.js"
+            "import": {
+                "types": "./dist/exceptions/index.d.ts",
+                "default": "./dist/exceptions/index.js"
+            },
+            "require": {
+                "types": "./dist/exceptions/index.d.cts",
+                "default": "./dist/exceptions/index.cjs"
+            }
         },
         "./exceptions/validation-field": {
-            "types": "./dist/exceptions/validation-field.d.ts",
-            "import": "./dist/exceptions/validation-field.js"
+            "import": {
+                "types": "./dist/exceptions/validation-field.d.ts",
+                "default": "./dist/exceptions/validation-field.js"
+            },
+            "require": {
+                "types": "./dist/exceptions/validation-field.d.cts",
+                "default": "./dist/exceptions/validation-field.cjs"
+            }
         },
         "./plugins": {
-            "types": "./dist/plugins/index.d.ts",
-            "import": "./dist/plugins/index.js"
+            "import": {
+                "types": "./dist/plugins/index.d.ts",
+                "default": "./dist/plugins/index.js"
+            },
+            "require": {
+                "types": "./dist/plugins/index.d.cts",
+                "default": "./dist/plugins/index.cjs"
+            }
         },
         "./policies": {
-            "types": "./dist/policies/index.d.ts",
-            "import": "./dist/policies/index.js"
+            "import": {
+                "types": "./dist/policies/index.d.ts",
+                "default": "./dist/policies/index.js"
+            },
+            "require": {
+                "types": "./dist/policies/index.d.cts",
+                "default": "./dist/policies/index.cjs"
+            }
         },
         "./policies/engines": {
-            "types": "./dist/policies/engines/index.d.ts",
-            "import": "./dist/policies/engines/index.js"
+            "import": {
+                "types": "./dist/policies/engines/index.d.ts",
+                "default": "./dist/policies/engines/index.js"
+            },
+            "require": {
+                "types": "./dist/policies/engines/index.d.cts",
+                "default": "./dist/policies/engines/index.cjs"
+            }
         },
         "./policies/engines/v1/gate": {
-            "types": "./dist/policies/engines/v1/gate/index.d.ts",
-            "import": "./dist/policies/engines/v1/gate/index.js"
+            "import": {
+                "types": "./dist/policies/engines/v1/gate/index.d.ts",
+                "default": "./dist/policies/engines/v1/gate/index.js"
+            },
+            "require": {
+                "types": "./dist/policies/engines/v1/gate/index.d.cts",
+                "default": "./dist/policies/engines/v1/gate/index.cjs"
+            }
+        },
+        "./rbac": {
+            "import": {
+                "types": "./dist/rbac/index.d.ts",
+                "default": "./dist/rbac/index.js"
+            },
+            "require": {
+                "types": "./dist/rbac/index.d.cts",
+                "default": "./dist/rbac/index.cjs"
+            }
         },
         "./result": {
-            "types": "./dist/result/index.d.ts",
-            "import": "./dist/result/index.js"
+            "import": {
+                "types": "./dist/result/index.d.ts",
+                "default": "./dist/result/index.js"
+            },
+            "require": {
+                "types": "./dist/result/index.d.cts",
+                "default": "./dist/result/index.cjs"
+            }
         },
         "./rulesets": {
-            "types": "./dist/rulesets/index.d.ts",
-            "import": "./dist/rulesets/index.js"
+            "import": {
+                "types": "./dist/rulesets/index.d.ts",
+                "default": "./dist/rulesets/index.js"
+            },
+            "require": {
+                "types": "./dist/rulesets/index.d.cts",
+                "default": "./dist/rulesets/index.cjs"
+            }
         },
         "./versioning": {
-            "types": "./dist/versioning/index.d.ts",
-            "import": "./dist/versioning/index.js"
+            "import": {
+                "types": "./dist/versioning/index.d.ts",
+                "default": "./dist/versioning/index.js"
+            },
+            "require": {
+                "types": "./dist/versioning/index.d.cts",
+                "default": "./dist/versioning/index.cjs"
+            }
         },
         "./package.json": "./package.json"
     },

package/src/abac/index.ts

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

package/src/core/abac/abac-request.ts

@@ -0,0 +1,29 @@
+import type { RequestedBy } from "../application/commands/requested-by.js";
+
+/**
+ * The attribute bags an ABAC decision reasons over, grouped by the four standard
+ * categories. Each is a flat record; {@link abacContext} nests them under
+ * `subject` / `resource` / `action` / `env` so a rule's condition can reference
+ * fields like `resource.status` or `env.businessHours`.
+ */
+type AbacAttributes = {
+    readonly subject?: Record<string, unknown>;
+    readonly resource?: Record<string, unknown>;
+    readonly action?: Record<string, unknown>;
+    readonly environment?: Record<string, unknown>;
+};
+
+/**
+ * The question put to the {@link AbacAuthorizer}: *do these attributes authorize
+ * this action?* Carries the acting {@link RequestedBy} (reused as the subject),
+ * an audit-friendly `action` label, an optional type/id resource reference, and
+ * the {@link AbacAttributes} the rules evaluate.
+ */
+interface AbacRequest {
+    readonly actor: RequestedBy;
+    readonly action: string;
+    readonly resource?: { readonly type: string; readonly id?: string };
+    readonly attributes: AbacAttributes;
+}
+
+export type { AbacAttributes, AbacRequest };

package/src/core/abac/attributes.ts

@@ -0,0 +1,39 @@
+import type { PolicyContext } from "../policies/engines/gate-types.js";
+
+import type { AbacRequest } from "./abac-request.js";
+
+/**
+ * Flattens an {@link AbacRequest} into the nested {@link PolicyContext} the
+ * condition evaluator reads (it resolves dotted fields like `resource.status` by
+ * walking nested objects). The actor lands as `subject.id`; the four attribute
+ * bags nest under `subject` / `resource` / `action` / `env`; a `resource`
+ * reference adds `resource.type` / `resource.id`. The actor id and the resource
+ * reference win over any same-named keys in the attribute bags.
+ *
+ * Consumers fold dynamic facts (e.g. RBAC roles/permissions derived from grants,
+ * or a computed `ownerIsActor` flag) into `attributes.subject` / `resource` so
+ * rules can reference `subject.roles`, `resource.ownerIsActor`, and the like.
+ */
+export function abacContext(request: AbacRequest): PolicyContext {
+    const attributes = request.attributes;
+
+    const subject: Record<string, unknown> = {
+        ...attributes.subject,
+        id: request.actor.raw,
+    };
+
+    const resource: Record<string, unknown> = { ...attributes.resource };
+    if (request.resource) {
+        resource.type = request.resource.type;
+        if (request.resource.id !== undefined) {
+            resource.id = request.resource.id;
+        }
+    }
+
+    return {
+        subject,
+        resource,
+        action: { ...attributes.action },
+        env: { ...attributes.environment },
+    };
+}

package/src/core/abac/authorizer.ts

@@ -0,0 +1,108 @@
+import { type CoreConfig, coreConfig } from "../config/index.js";
+import { AuthorizationError } from "../errors/authorization-error.js";
+import { ConditionEvaluatorV1 } from "../policies/engines/v1/condition-evaluator.js";
+import { Result } from "../result/result.js";
+
+import type { AbacRequest } from "./abac-request.js";
+import { abacContext } from "./attributes.js";
+import { combine, type CombiningAlgorithm } from "./combining.js";
+import type { AbacPolicySet } from "./domain/policy-set.js";
+import type { AbacRule } from "./domain/rule.js";
+
+// ABAC reuses the gate engine's v1 condition matcher; the version stamps the
+// evaluation reports the shared reporter emits.
+const ENGINE_VERSION = 1;
+
+/** The successful decision returned by {@link AbacAuthorizer.authorize}. */
+interface AbacDecision {
+    /** The audited business action that was allowed. */
+    readonly action: string;
+    readonly effect: "PERMIT";
+    /** The id of the rule that permitted, or `"<default>"` when the set's default did. */
+    readonly matchedRule: string;
+    readonly algorithm: CombiningAlgorithm;
+    /** When the decision was made, ISO-8601. */
+    readonly grantedAtIso: string;
+}
+
+/**
+ * The pure ABAC decisor. Given an {@link AbacRequest} and an
+ * {@link AbacPolicySet}, it flattens the request's attributes into a context,
+ * matches each rule's condition with the gate engine's pure condition evaluator
+ * (reused, not reimplemented), resolves the effects through the set's combining
+ * algorithm, and returns a {@link Result} — never throwing, mirroring the
+ * "errors as values" contract of `RbacAuthorizer`/`GateEngineV1`.
+ *
+ * A denial maps to {@link AuthorizationError.policyDenied}, attributed to the
+ * deciding rule's `id`/`version`; a condition-evaluation failure (a missing
+ * attribute, a wrong-typed operand) fails closed as
+ * {@link AuthorizationError.forbidden}. Loading the dynamic attributes is the
+ * consumer's job (behind an `AbacAuthorizerPort` adapter); this class only decides.
+ */
+class AbacAuthorizer {
+    private readonly coreConfig: CoreConfig;
+
+    constructor(params: { readonly coreConfig?: CoreConfig } = {}) {
+        this.coreConfig = params.coreConfig ?? coreConfig;
+    }
+
+    authorize(
+        request: AbacRequest,
+        policies: AbacPolicySet,
+    ): Result<AbacDecision, AuthorizationError> {
+        const context = abacContext(request);
+        const evaluator = new ConditionEvaluatorV1(
+            context,
+            this.coreConfig.getConditionEvaluationOptions(ENGINE_VERSION),
+        );
+
+        const applicable: AbacRule[] = [];
+        for (const rule of policies.rules) {
+            const matched = evaluator.evaluate(rule.condition);
+            if (matched.isErr()) {
+                // Fail closed: a technical evaluation error is never a silent PERMIT.
+                return Result.err(
+                    AuthorizationError.forbidden({
+                        action: request.action,
+                        resource: request.resource,
+                        actor: { userId: request.actor.raw },
+                        details: matched.errorOrNull() ?? undefined,
+                    }),
+                );
+            }
+            if (matched.getOrThrow()) {
+                applicable.push(rule);
+            }
+        }
+
+        const { effect, decidingRule } = combine(
+            policies.algorithm,
+            applicable,
+            policies.defaultEffect,
+        );
+
+        if (effect === "PERMIT") {
+            return Result.ok({
+                action: request.action,
+                effect: "PERMIT",
+                matchedRule: decidingRule?.id ?? "<default>",
+                algorithm: policies.algorithm,
+                grantedAtIso: new Date().toISOString(),
+            });
+        }
+
+        return Result.err(
+            AuthorizationError.policyDenied({
+                policyId: decidingRule?.id ?? "<default-deny>",
+                policyVersion: decidingRule?.version ?? 0,
+                evaluatedAtIso: new Date().toISOString(),
+                action: request.action,
+                resource: request.resource,
+                actor: { userId: request.actor.raw },
+                reasonCode: decidingRule?.id,
+            }),
+        );
+    }
+}
+
+export { AbacAuthorizer, type AbacDecision };

package/src/core/abac/combining.ts

@@ -0,0 +1,63 @@
+import type { AbacRule, RuleEffect } from "./domain/rule.js";
+
+/**
+ * How an {@link AbacPolicySet} resolves several applicable rules into one effect.
+ *
+ * - `deny-overrides` (default, secure): any applicable DENY wins; otherwise the
+ *   first PERMIT; otherwise the set's default effect.
+ * - `permit-overrides`: any applicable PERMIT wins; otherwise the first DENY;
+ *   otherwise the default effect.
+ * - `first-applicable`: the effect of the first rule that matches; otherwise the
+ *   default effect.
+ */
+export type CombiningAlgorithm =
+    | "deny-overrides"
+    | "permit-overrides"
+    | "first-applicable";
+
+/** The resolved decision plus the rule (if any) that produced it. */
+export interface CombineResult {
+    readonly effect: RuleEffect;
+    readonly decidingRule?: AbacRule;
+}
+
+function firstWithEffect(
+    rules: readonly AbacRule[],
+    effect: RuleEffect,
+): AbacRule | undefined {
+    return rules.find((rule) => rule.effect === effect);
+}
+
+/**
+ * Applies `algorithm` to the already-matched `applicable` rules, falling back to
+ * `defaultEffect` when the algorithm reaches no rule-backed decision. Pure and
+ * total; the returned `decidingRule` is absent exactly when `defaultEffect` was
+ * used.
+ */
+export function combine(
+    algorithm: CombiningAlgorithm,
+    applicable: readonly AbacRule[],
+    defaultEffect: RuleEffect,
+): CombineResult {
+    switch (algorithm) {
+        case "deny-overrides": {
+            const deny = firstWithEffect(applicable, "DENY");
+            if (deny) return { effect: "DENY", decidingRule: deny };
+            const permit = firstWithEffect(applicable, "PERMIT");
+            if (permit) return { effect: "PERMIT", decidingRule: permit };
+            return { effect: defaultEffect };
+        }
+        case "permit-overrides": {
+            const permit = firstWithEffect(applicable, "PERMIT");
+            if (permit) return { effect: "PERMIT", decidingRule: permit };
+            const deny = firstWithEffect(applicable, "DENY");
+            if (deny) return { effect: "DENY", decidingRule: deny };
+            return { effect: defaultEffect };
+        }
+        case "first-applicable": {
+            const first = applicable[0];
+            if (first) return { effect: first.effect, decidingRule: first };
+            return { effect: defaultEffect };
+        }
+    }
+}

package/src/core/abac/composite-authorizer.ts

@@ -0,0 +1,45 @@
+import { Result } from "../result/result.js";
+import type { AbacAuthorizerPort } from "../application/ports/abac-authorizer.port.js";
+import type { AuthorizerPort } from "../application/ports/authorizer.port.js";
+import type { AuthorizationError } from "../errors/authorization-error.js";
+import type { AccessRequest } from "../rbac/access-request.js";
+
+import type { AbacAttributes } from "./abac-request.js";
+
+/**
+ * The request a {@link CompositeAuthorizer} accepts — one object that satisfies
+ * both the RBAC {@link AccessRequest} (its `required`/`scope`) and the ABAC
+ * request (its `attributes`).
+ */
+type CompositeAccessRequest = AccessRequest & {
+    readonly attributes: AbacAttributes;
+};
+
+/**
+ * Runs a coarse RBAC check first, then refines with ABAC — the standard hybrid
+ * "does the actor hold the capability, *and* do the attributes allow it here?"
+ * flow. Short-circuits with the RBAC denial when the actor is not even capable,
+ * so the boundary sees the most specific 403.
+ *
+ * Only the two port interfaces are referenced (both erased at runtime), so this
+ * pulls in no RBAC/ABAC engine code of its own — it just sequences the seams the
+ * consumer wires up.
+ */
+class CompositeAuthorizer {
+    constructor(
+        private readonly rbac: AuthorizerPort,
+        private readonly abac: AbacAuthorizerPort,
+    ) {}
+
+    async authorize(
+        request: CompositeAccessRequest,
+    ): Promise<Result<void, AuthorizationError>> {
+        const coarse = await this.rbac.authorize(request);
+        if (coarse.isErr()) {
+            return coarse;
+        }
+        return this.abac.authorize(request);
+    }
+}
+
+export { CompositeAuthorizer, type CompositeAccessRequest };

package/src/core/abac/domain/policy-set.ts

@@ -0,0 +1,52 @@
+import type { CombiningAlgorithm } from "../combining.js";
+
+import type { AbacRule, RuleEffect } from "./rule.js";
+
+/**
+ * An ordered collection of {@link AbacRule}s plus how to combine them
+ * ({@link CombiningAlgorithm}) and what to decide when no rule applies
+ * ({@link defaultEffect}). This is where ABAC goes beyond a single gate
+ * condition: several PERMIT/DENY rules resolved by an explicit algorithm.
+ *
+ * Closed by default — the combining algorithm defaults to `"deny-overrides"` and
+ * the default effect to `"DENY"`, so a request matching nothing is denied. A
+ * plain holder (not a value object); build through {@link of}.
+ */
+class AbacPolicySet {
+    private constructor(
+        private readonly _rules: readonly AbacRule[],
+        private readonly _algorithm: CombiningAlgorithm,
+        private readonly _defaultEffect: RuleEffect,
+    ) {
+        Object.freeze(this._rules);
+        Object.freeze(this);
+    }
+
+    static of(
+        rules: readonly AbacRule[],
+        options: {
+            readonly algorithm?: CombiningAlgorithm;
+            readonly defaultEffect?: RuleEffect;
+        } = {},
+    ): AbacPolicySet {
+        return new AbacPolicySet(
+            [...rules],
+            options.algorithm ?? "deny-overrides",
+            options.defaultEffect ?? "DENY",
+        );
+    }
+
+    get rules(): readonly AbacRule[] {
+        return this._rules;
+    }
+
+    get algorithm(): CombiningAlgorithm {
+        return this._algorithm;
+    }
+
+    get defaultEffect(): RuleEffect {
+        return this._defaultEffect;
+    }
+}
+
+export { AbacPolicySet };