@cullet/erp-core 1.3.0 → 1.4.0

package/dist/authorizer.port.d.cts

@@ -0,0 +1,130 @@
+import { t as RequestedBy } from "./requested-by.cjs";
+import { t as AuthorizationError } from "./authorization-error.cjs";
+import { r as Result } from "./result.cjs";
+import { t as ValueObject } from "./value-object.cjs";
+
+//#region src/core/rbac/domain/permission.d.ts
+/** The two halves of a permission: what is acted on, and what is done to it. */
+type PermissionProps = {
+  readonly resource: string;
+  readonly action: string;
+};
+/**
+ * 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.
+ */
+declare class Permission extends ValueObject<PermissionProps, string> {
+  private constructor();
+  /**
+   * 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;
+  /**
+   * 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;
+  private static assertSegment;
+  get resource(): string;
+  get action(): string;
+  /**
+   * 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;
+  /**
+   * 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;
+  toPrimitive(): string;
+}
+//#endregion
+//#region src/core/rbac/domain/scope.d.ts
+/** The wrapped, already-validated scope string (`"type:id"` or `"*"`). */
+type ScopeProps = {
+  readonly raw: string;
+};
+/**
+ * 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.
+ */
+declare class Scope extends ValueObject<ScopeProps, string> {
+  private constructor();
+  /** Validates `"type:id"` or the global `"*"`, throwing on anything else. */
+  static of(raw: string): Scope;
+  /** The global scope `"*"`, which {@link includes} every other scope. */
+  static global(): Scope;
+  /** The type segment, or `"*"` for the global scope. */
+  get type(): string;
+  /** The id segment, or `undefined` for the global scope. */
+  get id(): string | undefined;
+  /**
+   * Whether this scope contains `target`. The global scope contains
+   * everything; any other scope contains only an exact match of itself.
+   */
+  includes(target: Scope): boolean;
+  toPrimitive(): string;
+}
+//#endregion
+//#region src/core/rbac/access-request.d.ts
+/**
+ * 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;
+}
+//#endregion
+//#region src/core/application/ports/authorizer.port.d.ts
+/**
+ * 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>>;
+}
+//#endregion
+export { Permission as a, ScopeProps as i, AccessRequest as n, PermissionProps as o, Scope as r, AuthorizerPort as t };
+//# sourceMappingURL=authorizer.port.d.cts.map

package/dist/authorizer.port.d.ts

@@ -0,0 +1,130 @@
+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 ValueObject } from "./value-object.js";
+
+//#region src/core/rbac/domain/permission.d.ts
+/** The two halves of a permission: what is acted on, and what is done to it. */
+type PermissionProps = {
+  readonly resource: string;
+  readonly action: string;
+};
+/**
+ * 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.
+ */
+declare class Permission extends ValueObject<PermissionProps, string> {
+  private constructor();
+  /**
+   * 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;
+  /**
+   * 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;
+  private static assertSegment;
+  get resource(): string;
+  get action(): string;
+  /**
+   * 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;
+  /**
+   * 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;
+  toPrimitive(): string;
+}
+//#endregion
+//#region src/core/rbac/domain/scope.d.ts
+/** The wrapped, already-validated scope string (`"type:id"` or `"*"`). */
+type ScopeProps = {
+  readonly raw: string;
+};
+/**
+ * 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.
+ */
+declare class Scope extends ValueObject<ScopeProps, string> {
+  private constructor();
+  /** Validates `"type:id"` or the global `"*"`, throwing on anything else. */
+  static of(raw: string): Scope;
+  /** The global scope `"*"`, which {@link includes} every other scope. */
+  static global(): Scope;
+  /** The type segment, or `"*"` for the global scope. */
+  get type(): string;
+  /** The id segment, or `undefined` for the global scope. */
+  get id(): string | undefined;
+  /**
+   * Whether this scope contains `target`. The global scope contains
+   * everything; any other scope contains only an exact match of itself.
+   */
+  includes(target: Scope): boolean;
+  toPrimitive(): string;
+}
+//#endregion
+//#region src/core/rbac/access-request.d.ts
+/**
+ * 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;
+}
+//#endregion
+//#region src/core/application/ports/authorizer.port.d.ts
+/**
+ * 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>>;
+}
+//#endregion
+export { Permission as a, ScopeProps as i, AccessRequest as n, PermissionProps as o, Scope as r, AuthorizerPort as t };
+//# sourceMappingURL=authorizer.port.d.ts.map

package/dist/composite-authorizer.d.cts

@@ -0,0 +1,216 @@
+import { t as RequestedBy } from "./requested-by.cjs";
+import { t as AuthorizationError } from "./authorization-error.cjs";
+import { r as Result } from "./result.cjs";
+import { T as PolicyContext, j as ConditionNode, t as CoreConfig } from "./core-config.cjs";
+import { t as ValueObject } from "./value-object.cjs";
+import { n as AccessRequest, t as AuthorizerPort } from "./authorizer.port.cjs";
+
+//#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.cts.map