@cullet/erp-core 1.3.0 → 1.5.0

package/dist/policy-bridge.d.cts

@@ -0,0 +1,185 @@
+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";
+import { a as Permission, n as AccessRequest, r as Scope } from "./authorizer.port.cjs";
+
+//#region src/core/rbac/domain/role.d.ts
+
+/**
+ * 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[];
+};
+/**
+ * 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}.
+ */
+declare class Role extends ValueObject<RoleProps, RoleProps> {
+  private readonly _permissions;
+  private constructor();
+  /**
+   * 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;
+  /**
+   * 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;
+  get name(): string;
+  /** The role's permissions, rehydrated from their stored primitive form. */
+  get permissions(): readonly Permission[];
+  /** Whether any permission in this role {@link Permission.implies | implies} `required`. */
+  grants(required: Permission): boolean;
+  toPrimitive(): RoleProps;
+}
+//#endregion
+//#region src/core/rbac/domain/grant.d.ts
+/**
+ * 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.
+ */
+declare class Grant extends ValueObject<GrantProps, GrantProps> {
+  private readonly _subject;
+  private readonly _role;
+  private readonly _scope;
+  private constructor();
+  static of(params: {
+    subject: RequestedBy;
+    role: Role;
+    scope: Scope;
+  }): Grant;
+  /**
+   * 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;
+  get subject(): RequestedBy;
+  get role(): Role;
+  get scope(): Scope;
+  /** Whether this grant belongs to `actor`. */
+  appliesTo(actor: RequestedBy): boolean;
+  toPrimitive(): GrantProps;
+}
+//#endregion
+//#region src/core/rbac/authorizer.d.ts
+/**
+ * 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.
+ */
+declare 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>;
+}
+//#endregion
+//#region src/core/rbac/domain/permission-set.d.ts
+/**
+ * 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).
+ */
+declare class PermissionSet {
+  private readonly permissions;
+  private readonly _roleNames;
+  private constructor();
+  /**
+   * 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;
+  /** Whether any held permission {@link Permission.implies | implies} `required`. */
+  has(required: Permission): boolean;
+  /** The effective permissions, deduplicated. */
+  toArray(): readonly Permission[];
+  /** The names of the roles that contributed to this set, deduplicated. */
+  get roleNames(): readonly string[];
+}
+//#endregion
+//#region src/core/rbac/policy-bridge.d.ts
+/**
+ * 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).
+ */
+declare function rbacContextFields(actor: RequestedBy, grants: readonly Grant[]): Record<string, unknown>;
+//#endregion
+export { GrantProps as a, Grant as i, PermissionSet as n, Role as o, RbacAuthorizer as r, RoleProps as s, rbacContextFields as t };
+//# sourceMappingURL=policy-bridge.d.cts.map

package/dist/policy-bridge.d.ts

@@ -0,0 +1,185 @@
+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";
+import { a as Permission, n as AccessRequest, r as Scope } from "./authorizer.port.js";
+
+//#region src/core/rbac/domain/role.d.ts
+
+/**
+ * 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[];
+};
+/**
+ * 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}.
+ */
+declare class Role extends ValueObject<RoleProps, RoleProps> {
+  private readonly _permissions;
+  private constructor();
+  /**
+   * 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;
+  /**
+   * 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;
+  get name(): string;
+  /** The role's permissions, rehydrated from their stored primitive form. */
+  get permissions(): readonly Permission[];
+  /** Whether any permission in this role {@link Permission.implies | implies} `required`. */
+  grants(required: Permission): boolean;
+  toPrimitive(): RoleProps;
+}
+//#endregion
+//#region src/core/rbac/domain/grant.d.ts
+/**
+ * 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.
+ */
+declare class Grant extends ValueObject<GrantProps, GrantProps> {
+  private readonly _subject;
+  private readonly _role;
+  private readonly _scope;
+  private constructor();
+  static of(params: {
+    subject: RequestedBy;
+    role: Role;
+    scope: Scope;
+  }): Grant;
+  /**
+   * 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;
+  get subject(): RequestedBy;
+  get role(): Role;
+  get scope(): Scope;
+  /** Whether this grant belongs to `actor`. */
+  appliesTo(actor: RequestedBy): boolean;
+  toPrimitive(): GrantProps;
+}
+//#endregion
+//#region src/core/rbac/authorizer.d.ts
+/**
+ * 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.
+ */
+declare 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>;
+}
+//#endregion
+//#region src/core/rbac/domain/permission-set.d.ts
+/**
+ * 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).
+ */
+declare class PermissionSet {
+  private readonly permissions;
+  private readonly _roleNames;
+  private constructor();
+  /**
+   * 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;
+  /** Whether any held permission {@link Permission.implies | implies} `required`. */
+  has(required: Permission): boolean;
+  /** The effective permissions, deduplicated. */
+  toArray(): readonly Permission[];
+  /** The names of the roles that contributed to this set, deduplicated. */
+  get roleNames(): readonly string[];
+}
+//#endregion
+//#region src/core/rbac/policy-bridge.d.ts
+/**
+ * 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).
+ */
+declare function rbacContextFields(actor: RequestedBy, grants: readonly Grant[]): Record<string, unknown>;
+//#endregion
+export { GrantProps as a, Grant as i, PermissionSet as n, Role as o, RbacAuthorizer as r, RoleProps as s, rbacContextFields as t };
+//# sourceMappingURL=policy-bridge.d.ts.map