@cullet/erp-core 1.3.0 → 1.5.0

package/dist/composite-authorizer.d.ts

@@ -0,0 +1,216 @@
+import { t as RequestedBy } from "./requested-by.js";
+import { t as AuthorizationError } from "./authorization-error.js";
+import { r as Result } from "./result.js";
+import { T as PolicyContext, j as ConditionNode, t as CoreConfig } from "./core-config.js";
+import { t as ValueObject } from "./value-object.js";
+import { n as AccessRequest, t as AuthorizerPort } from "./authorizer.port.js";
+
+//#region src/core/abac/abac-request.d.ts
+/**
+ * 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;
+}
+//#endregion
+//#region src/core/application/ports/abac-authorizer.port.d.ts
+/**
+ * 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>>;
+}
+//#endregion
+//#region src/core/abac/attributes.d.ts
+/**
+ * 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.
+ */
+declare function abacContext(request: AbacRequest): PolicyContext;
+//#endregion
+//#region src/core/abac/domain/rule.d.ts
+/** 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;
+};
+/**
+ * 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.
+ */
+declare class AbacRule extends ValueObject<AbacRuleProps, AbacRuleProps> {
+  private constructor();
+  /**
+   * 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;
+  private static assertConditionShape;
+  private static rejectCondition;
+  get id(): string;
+  get version(): number;
+  get effect(): RuleEffect;
+  /** The condition tree evaluated against a request's flattened attributes. */
+  get condition(): ConditionNode;
+  get description(): string | undefined;
+  toPrimitive(): AbacRuleProps;
+}
+//#endregion
+//#region src/core/abac/combining.d.ts
+/**
+ * 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.
+ */
+type CombiningAlgorithm = "deny-overrides" | "permit-overrides" | "first-applicable";
+/** The resolved decision plus the rule (if any) that produced it. */
+//#endregion
+//#region src/core/abac/domain/policy-set.d.ts
+/**
+ * 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}.
+ */
+declare class AbacPolicySet {
+  private readonly _rules;
+  private readonly _algorithm;
+  private readonly _defaultEffect;
+  private constructor();
+  static of(rules: readonly AbacRule[], options?: {
+    readonly algorithm?: CombiningAlgorithm;
+    readonly defaultEffect?: RuleEffect;
+  }): AbacPolicySet;
+  get rules(): readonly AbacRule[];
+  get algorithm(): CombiningAlgorithm;
+  get defaultEffect(): RuleEffect;
+}
+//#endregion
+//#region src/core/abac/authorizer.d.ts
+/** 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.
+ */
+declare class AbacAuthorizer {
+  private readonly coreConfig;
+  constructor(params?: {
+    readonly coreConfig?: CoreConfig;
+  });
+  authorize(request: AbacRequest, policies: AbacPolicySet): Result<AbacDecision, AuthorizationError>;
+}
+//#endregion
+//#region src/core/abac/composite-authorizer.d.ts
+/**
+ * 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.
+ */
+declare class CompositeAuthorizer {
+  private readonly rbac;
+  private readonly abac;
+  constructor(rbac: AuthorizerPort, abac: AbacAuthorizerPort);
+  authorize(request: CompositeAccessRequest): Promise<Result<void, AuthorizationError>>;
+}
+//#endregion
+export { AbacPolicySet as a, AbacRuleProps as c, AbacAuthorizerPort as d, AbacAttributes as f, AbacDecision as i, RuleEffect as l, CompositeAuthorizer as n, CombiningAlgorithm as o, AbacRequest as p, AbacAuthorizer as r, AbacRule as s, CompositeAccessRequest as t, abacContext as u };
+//# sourceMappingURL=composite-authorizer.d.ts.map