@aooth/arbac 0.1.70 → 0.1.72

package/dist/index.d.cts

@@ -86,18 +86,6 @@ declare function defineRole<TUserAttrs extends object = object, TScope extends o
  */
 declare function definePrivilege<TUserAttrs extends object = object, TScope extends object = object>(): <TArgs extends unknown[]>(factory: (...args: TArgs) => TArbacRule<TUserAttrs, TScope>[]) => ((...args: TArgs) => TPrivilegeFunction<TUserAttrs, TScope>);
 //#endregion
-//#region src/db-privileges.d.ts
-type ScopeFn<TUserAttrs, TScope> = (attrs: TUserAttrs, userId: string) => TScope;
-interface ScopeOpts<TUserAttrs, TScope> {
-  scope?: ScopeFn<TUserAttrs, TScope>;
-}
-/** Read-side actions on an `AsDbController` table: `query`, `pages`, `getOne`, `getOneComposite`, `meta`, `metaForm`. */
-declare function allowTableRead<TUserAttrs extends object = object, TScope extends object = object>(resource: string, opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
-/** All actions on an `AsDbController` table: read + `insert`, `update`, `replace`, `remove`, `removeComposite`. */
-declare function allowTableWrite<TUserAttrs extends object = object, TScope extends object = object>(resource: string, opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
-/** One or more declarative actions on the same table, sharing a scope. */
-declare function allowTableAction<TUserAttrs extends object = object, TScope extends object = object>(resource: string, name: string | string[], opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
-//#endregion
 //#region src/scope/types.d.ts
 /**
  * Mongo-style field projection: `{ field: 0 | 1 }`.
@@ -135,6 +123,98 @@ type TScopeFilter = Record<string, unknown>;
  */
 type ControlGate = boolean | readonly string[];
 //#endregion
+//#region src/db-privileges.d.ts
+/**
+ * Read-side handler actions of an `AsDbController` table: `query`, `pages`,
+ * `getOne`, `getOneComposite`, `geo`, `meta`, `metaForm`.
+ */
+declare const TABLE_READ_ACTIONS: readonly ["query", "pages", "getOne", "getOneComposite", "geo", "meta", "metaForm"];
+/** Write-side handler actions of an `AsDbController` table. */
+declare const TABLE_WRITE_ACTIONS: readonly ["insert", "update", "replace", "remove", "removeComposite"];
+/** The `/meta` + `/meta/form/:name` handler actions (a subset of {@link TABLE_READ_ACTIONS}). */
+declare const TABLE_META_ACTIONS: readonly ["meta", "metaForm"];
+/** Table operation names accepted by {@link allowTableOps} / {@link defineTableAccess}. */
+type TTableOp = "read" | "meta" | "insert" | "update" | "replace" | "remove";
+/**
+ * Operation → handler actions. `meta` is the form-metadata subset of `read`,
+ * for write-only principals that still render forms from `/meta`.
+ */
+declare const TABLE_OP_ACTIONS: Readonly<Record<TTableOp, readonly string[]>>;
+type ScopeFn<TUserAttrs, TScope> = (attrs: TUserAttrs, userId: string) => TScope;
+interface ScopeOpts<TUserAttrs, TScope> {
+  scope?: ScopeFn<TUserAttrs, TScope>;
+}
+/** Read-side actions on an `AsDbController` table — see {@link TABLE_READ_ACTIONS}. */
+declare function allowTableRead<TUserAttrs extends object = object, TScope extends object = object>(resource: string, opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
+/** All actions on an `AsDbController` table: read + `insert`, `update`, `replace`, `remove`, `removeComposite`. */
+declare function allowTableWrite<TUserAttrs extends object = object, TScope extends object = object>(resource: string, opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
+/**
+ * Selected operations on an `AsDbController` table, sharing a scope — e.g. an
+ * insert-only form principal: `allowTableOps("leads", ["insert", "meta"])`.
+ *
+ * - `read` → `query`, `pages`, `getOne`, `getOneComposite`, `geo`, `meta`, `metaForm`
+ * - `meta` → `meta`, `metaForm` (forms for principals without `read`)
+ * - `remove` → `remove`, `removeComposite`
+ * - `insert` / `update` / `replace` → the same-named action
+ *
+ * Throws on an unknown op name.
+ */
+declare function allowTableOps<TUserAttrs extends object = object, TScope extends object = object>(resource: string, ops: readonly TTableOp[], opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
+/** One or more declarative actions on the same table, sharing a scope. */
+declare function allowTableAction<TUserAttrs extends object = object, TScope extends object = object>(resource: string, name: string | string[], opts?: ScopeOpts<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
+/** The scope keys {@link defineTableAccess} conjoins instead of overriding. */
+interface TTableAccessScope {
+  filter?: TScopeFilter;
+  check?: TScopeFilter;
+}
+/** Write ops for {@link TTableAccessDef.write}: any {@link TTableOp} but `read`. */
+type TTableWriteOp = Exclude<TTableOp, "read">;
+type PartScopeFn<TUserAttrs, TScope> = ScopeFn<NoInfer<TUserAttrs>, NoInfer<TScope>>;
+/**
+ * Table policy for {@link defineTableAccess}. A part's own `scope` merges over
+ * the shared one (see there).
+ */
+interface TTableAccessDef<TUserAttrs, TScope> {
+  /** Shared scope — row filter, projection, controls, `with`, `check`, … — for every part. */
+  scope?: PartScopeFn<TUserAttrs, TScope>;
+  /** Read side — {@link TABLE_READ_ACTIONS}. */
+  read?: boolean | {
+    scope?: PartScopeFn<TUserAttrs, TScope>;
+  };
+  /**
+   * Write side: `true` = insert + update + replace + remove. An op list may
+   * add `meta` (forms for a principal without `read`).
+   */
+  write?: boolean | readonly TTableWriteOp[] | {
+    ops?: readonly TTableWriteOp[];
+    scope?: PartScopeFn<TUserAttrs, TScope>;
+  };
+  /** Declarative `@DbAction` names. */
+  actions?: readonly string[] | {
+    names: readonly string[];
+    scope?: PartScopeFn<TUserAttrs, TScope>;
+  };
+}
+/**
+ * One table policy → consistent rules for every endpoint of an
+ * `AsDbController` table. The shared `scope` (row filter + projection +
+ * controls + `with` + `check` …) applies to every part; a part's own `scope`
+ * merges over it — `filter` / `check` conjoined (`$and`), other keys from the
+ * part. An action granted by an earlier part (`read` → `write` → `actions`)
+ * is not repeated by a later one. Throws on an unknown write op.
+ *
+ * @example
+ * ```ts
+ * defineTableAccess<Attrs, ArbacDbScope<typeof Task>>("tasks", {
+ *   scope: (a) => ({ filter: { tenantId: a.tenantId }, projection: { secret: 0 } }),
+ *   read: true,
+ *   write: { ops: ["insert", "update"], scope: () => ({ allowedFields: ["title", "status"] }) },
+ *   actions: ["markDone"],
+ * });
+ * ```
+ */
+declare function defineTableAccess<TUserAttrs extends object = object, TScope extends TTableAccessScope = TTableAccessScope>(resource: string, def: TTableAccessDef<TUserAttrs, TScope>): TPrivilegeFunction<TUserAttrs, TScope>;
+//#endregion
 //#region src/scope/projection.d.ts
 type TProjectionMode = "include" | "exclude" | "empty";
 /**
@@ -326,6 +406,259 @@ declare function unionControlsPolicy(scopes: ReadonlyArray<{
  */
 declare function intersectControlsPolicy(a: Record<string, ControlGate>, b: Record<string, ControlGate>): Record<string, ControlGate>;
 //#endregion
+//#region src/scope/db-scope.d.ts
+/**
+ * The DB scope shape the scope algebra reads — structurally what
+ * `ArbacDbScope` (`@aooth/arbac-moost`) carries. Every facet is optional.
+ *
+ * @since 0.1.72
+ */
+interface TDbScope {
+  filter?: TScopeFilter;
+  check?: TScopeFilter;
+  projection?: object;
+  controls?: object;
+  allowedFields?: readonly string[];
+  set?: object;
+  nestedWrites?: readonly string[];
+  checkRefs?: true | readonly string[];
+  with?: object;
+}
+/**
+ * The built-in {@link TDbScope} keys — the facets the scope algebra itself
+ * combines. Any other key is a custom (declaration-merged) scope field, which
+ * {@link conjoinScopes} combines only through a registered
+ * {@link TScopeFieldRule}.
+ *
+ * @since 0.1.72
+ */
+declare const DB_SCOPE_KEYS: readonly string[];
+/**
+ * The conjunction rule of ONE custom scope field (a key an app adds to its
+ * scope type by declaration merging). {@link conjoinScopes} calls `conjoin`
+ * only when some scope on either side carries the field.
+ *
+ * @since 0.1.72
+ */
+interface TScopeFieldRule<S extends object = TDbScope> {
+  /**
+   * Optional ROW restriction the field implies: the filter a scope carrying
+   * `value` admits (`undefined` / `{}` = no row restriction). Folded into
+   * that scope's `filter` by {@link applyScopeFieldFilters} — ANDed within
+   * the scope, so the union across scopes stays an `$or`. An explicit
+   * `check` is left as written; an absent one follows the folded filter.
+   *
+   * Must depend ONLY on `(value, scope)` — never on request context: the
+   * result is cached process-wide per scope object. Put user-dependent data
+   * into the scope value from the role's scope predicate.
+   */
+  rowFilter?(value: unknown, scope: S): TScopeFilter | undefined;
+  /**
+   * Combine the field of two restrict-only sides into the ONE value the
+   * composite scope carries — never wider than either side. Each side is a
+   * scope LIST the app unions with its own rule (a scope without the field is
+   * typically unrestricted for it). In a credential attenuation `a` is the
+   * user's full authority and `b` the credential's view. Return `undefined`
+   * for "unrestricted" (the key is omitted).
+   */
+  conjoin(a: readonly S[], b: readonly S[]): unknown;
+}
+/**
+ * Thrown by {@link conjoinScopes} for a custom scope field without a
+ * conjunction rule — a server CONFIGURATION error (never a client error):
+ * the conjunction fails closed instead of dropping the field.
+ *
+ * @since 0.1.72
+ */
+declare class ScopeFieldConfigError extends Error {
+  /** The custom scope field without a rule. */
+  readonly field: string;
+  readonly name = "ScopeFieldConfigError";
+  constructor(
+  /** The custom scope field without a rule. */
+  field: string, message: string);
+}
+/** Custom scope field name → its {@link TScopeFieldRule}. @since 0.1.72 */
+type TScopeFieldRules<S extends object = TDbScope> = Readonly<Record<string, TScopeFieldRule<S>>>;
+/**
+ * The effective (unioned) policy of a list of DB scopes — one scope per
+ * allowing rule, so each facet unions ADDITIVELY (more roles = more access).
+ * Every facet's union rule is defined here once; facets compute lazily (a
+ * misconfigured facet throws only where it is used). An empty list is the
+ * identity (unrestricted) of every union — denial is decided before, by
+ * {@link normalizeScopes}.
+ *
+ * @since 0.1.72
+ */
+interface TEffectiveDbScope<S extends TDbScope = TDbScope> {
+  /** Row filter union (`$or`, {@link mergeScopeFilters}); `undefined` = unrestricted. */
+  readonly filter: TScopeFilter | undefined;
+  /**
+   * WITH CHECK union — each scope's `check`, defaulting to its `filter`
+   * (`{}` = no check); `undefined` = nothing to check.
+   */
+  readonly check: TScopeFilter | undefined;
+  /** Whether any scope sets an explicit `check`. */
+  readonly hasExplicitCheck: boolean;
+  /** Projection union ({@link unionProjections}); `{}` = every field. */
+  readonly projection: TProjection;
+  /** Controls union ({@link unionControlsPolicy}); an absent key = allowed. */
+  readonly controls: Record<string, ControlGate>;
+  /**
+   * Union of the `allowedFields` whitelists; `undefined` when no scope
+   * carries one (field-unrestricted writes).
+   */
+  readonly allowedFields: ReadonlySet<string> | undefined;
+  /** The `set` overlays, later scopes winning; `undefined` when none sets one. */
+  readonly set: Readonly<Record<string, unknown>> | undefined;
+  /** Union of the `nestedWrites` opt-ins. */
+  readonly nestedWrites: ReadonlySet<string>;
+  /**
+   * `checkRefs` entries EVERY scope enables (intersection of enforcement —
+   * a scope without the flag grants unconstrained writes of that FK);
+   * `true` = all. Names as written (a schema-aware caller resolves them).
+   */
+  readonly checkRefs: true | ReadonlySet<string>;
+  /** Relation names some scope declares a `with.<name>` sub-scope for. */
+  readonly withNames: ReadonlySet<string>;
+  /** The declared `with.<name>` sub-scopes (identity-stable per name). */
+  withScopes(name: string): readonly S[];
+}
+/**
+ * The {@link TEffectiveDbScope} of `scopes`, memoized per scopes ARRAY (an
+ * identity-stable per-request list reuses every computed facet).
+ *
+ * @since 0.1.72
+ */
+declare function effectiveScope<S extends TDbScope>(scopes: readonly S[]): TEffectiveDbScope<S>;
+/**
+ * Intersection of enforcement: an entry is enforced only when EVERY input
+ * enables it (`true` enables all). No input → nothing enforced.
+ *
+ * @since 0.1.72
+ */
+declare function intersectEnabled<K>(inputs: Iterable<true | ReadonlySet<K>>): true | Set<K>;
+/**
+ * The unified empty-scope rule for an evaluation outcome: denied → `undefined`;
+ * allowed with `scopes` absent (a scope-agnostic evaluator) → `[{}]`
+ * (unrestricted); a scope predicate that returned nothing contributes nothing
+ * (fail closed for that rule); allowed with no scope left → `undefined` (deny).
+ *
+ * @since 0.1.72
+ */
+declare function normalizeScopes<S extends object>(outcome: {
+  allowed: boolean;
+  scopes?: ReadonlyArray<S | null | undefined>;
+}): S[] | undefined;
+/**
+ * Several evaluations served as ONE surface (e.g. the handlers of one crud
+ * op): each normalized with {@link normalizeScopes}, the allowed ones'
+ * scopes concatenated — `undefined` when none allows.
+ *
+ * @since 0.1.72
+ */
+declare function unionOutcomes<S extends object>(outcomes: ReadonlyArray<{
+  allowed: boolean;
+  scopes?: ReadonlyArray<S | null | undefined>;
+}>): S[] | undefined;
+/** A row policy: the read / USING `filter` and the WITH CHECK `check` (defaults to `filter`). */
+interface TRowPolicy {
+  filter?: TScopeFilter;
+  check?: TScopeFilter;
+}
+/**
+ * Conjoin two row policies (`$and`, restrict-only): `filter = a.filter ∧
+ * b.filter`; the effective check `(a.check ?? a.filter) ∧ (b.check ??
+ * b.filter)`. `check` is set only when it differs from the conjoined
+ * `filter` (which an absent `check` defaults to) — `{}` when it is
+ * unrestricted while the filter is not.
+ *
+ * @since 0.1.72
+ */
+declare function conjoinRowPolicies(a: TRowPolicy, b: TRowPolicy): TRowPolicy;
+/** Options of {@link conjoinScopes}. */
+interface TConjoinScopesOptions<S extends TDbScope> {
+  /** Schema lookup to subtract a nested exclusion exactly (without it: fail closed). */
+  childrenOf?: TProjectionChildren;
+  /**
+   * Schema-aware `checkRefs` conjunction; default: the union of each side's
+   * {@link TEffectiveDbScope.checkRefs} names.
+   */
+  checkRefs?: (a: readonly S[], b: readonly S[]) => true | string[] | undefined;
+  /**
+   * Rules for custom (non-built-in) scope fields, applied at every level
+   * (`with` sub-scopes too). A custom field present on either side without a
+   * rule throws — it is never dropped (a dropped field reads as absent, i.e.
+   * typically unrestricted).
+   */
+  fields?: TScopeFieldRules<S>;
+}
+/**
+ * Conjoin two scope lists (credential attenuation: the user's ceiling ∧ the
+ * credential's narrowed view) into ONE composite scope. Each side is first
+ * unioned ({@link effectiveScope}), then the two results are CONJOINED facet
+ * by facet — never with the additive union helpers, which would widen:
+ *
+ * - `filter` / `check` — {@link conjoinRowPolicies};
+ * - `projection` — {@link intersectProjections} (no common field → the
+ *   first side's projection plus a match-nothing filter, never `{}`);
+ * - `controls` — {@link intersectControlsPolicy} (deny wins);
+ * - `allowedFields` — intersection (a side without a whitelist is unrestricted);
+ * - `nestedWrites` — intersection (a side without the key allows none);
+ * - `set` — combined, the FIRST side winning a key conflict;
+ * - `checkRefs` — enforced when EITHER side enforces it;
+ * - `with` — per relation, recursively; a relation declared by ONE side only
+ *   is marked {@link INHERITED_CONJUNCTION} (the silent side's inherited
+ *   grant on the related table must be conjoined at resolution time);
+ * - a custom field — its `opts.fields` rule; none registered → throws
+ *   (fail closed: never silently dropped).
+ *
+ * @since 0.1.72
+ */
+declare function conjoinScopes<S extends TDbScope>(a: readonly S[], b: readonly S[], opts?: TConjoinScopesOptions<S>): S;
+/** Options of {@link applyScopeFieldFilters}. @since 0.1.72 */
+interface TApplyScopeFieldFiltersOptions {
+  /**
+   * Called for a non-built-in scope key with no rule in `fields` (once per
+   * scope object carrying it) — e.g. to warn about a field that will fail
+   * the first attenuated conjunction.
+   */
+  onUnknownField?: (field: string) => void;
+}
+/**
+ * Fold every custom field's {@link TScopeFieldRule.rowFilter} into its
+ * scope's `filter` (`filter ∧ rowFilter(value, scope)`), recursively into
+ * `with` sub-scopes. Apply it per evaluated scope list — before any union or
+ * conjunction — so every row path sees the restriction. The custom value
+ * stays on the scope. Scopes are never mutated: a changed scope is a copy.
+ * Memoized per rule registry and scope object (process-wide), and
+ * idempotent (a folded scope folds to itself); without row rules (and no
+ * `onUnknownField`) the input list is returned as is.
+ *
+ * @since 0.1.72
+ */
+declare function applyScopeFieldFilters<S extends TDbScope>(scopes: readonly S[], fields: TScopeFieldRules<S> | undefined, opts?: TApplyScopeFieldFiltersOptions): readonly S[];
+/**
+ * Marks a `with.<rel>` sub-scope {@link conjoinScopes} built from ONE side's
+ * declaration. The other side is silent on the relation, so ITS policy for
+ * the joined rows is its inherited grant on the related table — unknown
+ * here. A resolver must conjoin the marked sub-scope with the caller's own
+ * grant on the related table (never apply it alone as parent authority);
+ * unresolved, the relation is hidden. See {@link needsInheritedConjunction}.
+ *
+ * @since 0.1.72
+ */
+declare const INHERITED_CONJUNCTION: unique symbol;
+/** A `with` sub-scope marked {@link INHERITED_CONJUNCTION}. @since 0.1.72 */
+declare function needsInheritedConjunction(scope: object): boolean;
+/**
+ * A stable string key for a JSON-like value (bigint-safe) — for
+ * de-duplicating filters / tuples and comparing them structurally.
+ *
+ * @since 0.1.72
+ */
+declare function stableKey(value: unknown): string;
+//#endregion
 //#region src/codegen/extract.d.ts
 interface TResourceActionMap {
   /** Map of resource string → Set of action strings */
@@ -361,4 +694,4 @@ interface TCodegenOptions {
  */
 declare function generateResourceTypes(map: TResourceActionMap, options?: TCodegenOptions): string;
 //#endregion
-export { type ControlGate, DENY_FILTER, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionChildren, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectProjections, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };
+export { type ControlGate, DB_SCOPE_KEYS, DENY_FILTER, INHERITED_CONJUNCTION, type RoleBuilder, ScopeFieldConfigError, TABLE_META_ACTIONS, TABLE_OP_ACTIONS, TABLE_READ_ACTIONS, TABLE_WRITE_ACTIONS, type TApplyScopeFieldFiltersOptions, type TCodegenOptions, type TConjoinScopesOptions, type TDbScope, type TEffectiveDbScope, type TPrivilegeFunction, type TProjection, type TProjectionChildren, type TProjectionMode, type TResourceActionMap, type TRowPolicy, type TScopeFieldRule, type TScopeFieldRules, type TScopeFilter, type TTableAccessDef, type TTableAccessScope, type TTableOp, type TTableWriteOp, allowTableAction, allowTableOps, allowTableRead, allowTableWrite, applyScopeFieldFilters, conjoinRowPolicies, conjoinScopeFilters, conjoinScopes, definePrivilege, defineRole, defineTableAccess, effectiveScope, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectEnabled, intersectProjections, isFieldAllowed, mergeScopeFilters, needsInheritedConjunction, normalizeScopes, restrictProjection, stableKey, unionControlsPolicy, unionOutcomes, unionProjections };