@aooth/arbac 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,282 @@
+import { TArbacRole, TArbacRule } from "@aooth/arbac-core";
+export * from "@aooth/arbac-core";
+
+//#region src/define-role.d.ts
+/**
+ * A privilege function produces an array of rules when called.
+ * Created by `definePrivilege()` or manually.
+ */
+type TPrivilegeFunction<TUserAttrs, TScope> = () => TArbacRule<TUserAttrs, TScope>[];
+/**
+ * Fluent builder produced by {@link defineRole}.
+ *
+ * All methods return `this` so they can be chained. Rules are emitted in the order
+ * the corresponding `.allow()`, `.deny()`, and `.use()` calls were made — this matters
+ * for engines that respect rule order (deny-first / first-match-wins variants).
+ */
+interface RoleBuilder<TUserAttrs, TScope> {
+  /**
+   * Set the role id (required). Calling `.id()` more than once overwrites the
+   * previous value — the last call wins.
+   */
+  id(id: string): RoleBuilder<TUserAttrs, TScope>;
+  /** Set the human-readable role name. Optional. */
+  name(name: string): RoleBuilder<TUserAttrs, TScope>;
+  /** Set the role description. Optional. */
+  describe(description: string): RoleBuilder<TUserAttrs, TScope>;
+  /**
+   * Append an allow rule for a (resource, action) pair, with an optional scope
+   * function that derives a scope object from user attrs.
+   */
+  allow(resource: string, action: string, scope?: (attrs: TUserAttrs, userId: string) => TScope): RoleBuilder<TUserAttrs, TScope>;
+  /** Append a deny rule (`effect: 'deny'`) for a (resource, action) pair. */
+  deny(resource: string, action: string): RoleBuilder<TUserAttrs, TScope>;
+  /**
+   * Splice in rules from one or more privilege functions (see
+   * {@link definePrivilege}). Privileges are expanded inline in call order.
+   *
+   * Two overloads:
+   * 1. **Strict** — all privileges share the role's `TScope`. Preserves
+   *    bidirectional inference of `TUserAttrs` and `TScope` into bare-generic
+   *    privilege calls like `allowTableWrite("tasks", { scope: (attrs) => … })`.
+   * 2. **Variadic tuple** — privileges may carry independent per-arg scope
+   *    shapes (e.g. `ArbacDbScope<Task>` next to `ArbacDbScope<Comment>`).
+   *    Used when typed-table privileges don't structurally match the role
+   *    pin. Runtime storage type-erases through a cast.
+   */
+  use(...privileges: TPrivilegeFunction<TUserAttrs, TScope>[]): RoleBuilder<TUserAttrs, TScope>;
+  use<TScopes extends readonly unknown[]>(...privileges: { [K in keyof TScopes]: TPrivilegeFunction<TUserAttrs, TScopes[K]> }): RoleBuilder<TUserAttrs, TScope>;
+  /**
+   * Finalize and return a plain {@link TArbacRole} object suitable for
+   * `Arbac.registerRole`. Throws if `.id()` was never called.
+   */
+  build(): TArbacRole<TUserAttrs, TScope>;
+}
+/**
+ * Start building a new role.
+ *
+ * @example
+ * const editor = defineRole<MyAttrs, MyScope>()
+ *   .id("editor")
+ *   .name("Editor")
+ *   .use(allowTableWrite("articles"))
+ *   .deny("articles", "publish")
+ *   .build();
+ */
+declare function defineRole<TUserAttrs extends object = object, TScope extends object = object>(): RoleBuilder<TUserAttrs, TScope>;
+//#endregion
+//#region src/define-privilege.d.ts
+/**
+ * Define a reusable privilege factory.
+ *
+ * Double-call pattern: first call pins TUserAttrs/TScope generics,
+ * second call infers TArgs from the factory function.
+ *
+ * @example
+ * const canManageUsers = definePrivilege<MyAttrs, MyScope>()(
+ *   (scope: (attrs: MyAttrs, userId: string) => MyScope) => [
+ *     { resource: "users", action: "read", scope },
+ *     { resource: "users", action: "update", scope },
+ *   ]
+ * );
+ *
+ * defineRole<MyAttrs, MyScope>()
+ *   .id("manager")
+ *   .use(canManageUsers((attrs) => ({ dept: attrs.dept })))
+ *   .build();
+ */
+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 }`.
+ * - All 1s = inclusion mode (only listed fields allowed)
+ * - All 0s = exclusion mode (listed fields denied, rest allowed)
+ * - Mixing 0 and 1 in a single projection is invalid.
+ *
+ * Structurally compatible with @uniqu/core SelectExpr in object form.
+ */
+type TProjection = Record<string, 0 | 1>;
+/**
+ * A filter expression compatible with @uniqu/core FilterExpr.
+ * Comparison leaf: `{ field: value }` or `{ field: { $op: value } }`
+ * Logical branch: `{ $or: [...] }` | `{ $and: [...] }` | `{ $not: ... }`
+ */
+type TScopeFilter = Record<string, unknown>;
+/**
+ * Per-control policy in a resource scope.
+ *
+ * Used inside `ArbacDbScope.controls` (in `@aooth/arbac-moost`) to gate
+ * Uniquery URL controls (`$with`, `$groupBy`, `$having`, …) on a per-role basis.
+ *
+ * Semantics:
+ * - **silence** (key absent / `undefined`) — no opinion → allow.
+ * - `true` — explicit allow (same effect as silence; useful for documentation).
+ * - `false` — explicit deny; using the control fails 403.
+ * - `readonly string[]` — whitelist mode; only the listed values are allowed.
+ *   E.g., `{ $with: ['comments'] }` permits `?$with=comments` but rejects
+ *   `?$with=tasks` with 403.
+ *
+ * Whitelist arrays are supported only for controls whose value is a list of
+ * named entities (notably `$with` for relation names and `$groupBy` for
+ * column names). For other controls (e.g. `$having`) only boolean gates are
+ * supported in v1; supplying a whitelist throws at scope-evaluation time.
+ */
+type ControlGate = boolean | readonly string[];
+//#endregion
+//#region src/scope/projection.d.ts
+type TProjectionMode = "include" | "exclude" | "empty";
+/**
+ * Determine whether a projection is in inclusion mode (all 1s),
+ * exclusion mode (all 0s), or empty (`{}`, no restriction).
+ *
+ * @throws when a single projection mixes 0 and 1 values
+ */
+declare function getProjectionMode(proj: TProjection): TProjectionMode;
+/**
+ * Check whether a dot-path field is allowed by a projection.
+ *
+ * Inclusion mode: a field is allowed if it, any of its parents, or any of its children
+ *   is explicitly listed.
+ * Exclusion mode: a field is allowed unless it or any of its parents is excluded.
+ * Empty projection: every field is allowed.
+ */
+declare function isFieldAllowed(field: string, projection: TProjection): boolean;
+/**
+ * Combines projections from multiple RBAC role grants under additive semantics:
+ * more roles = broader access. Each projection represents a set of allowed fields:
+ * include-mode `{a:1}` allows `{a}`; exclude-mode `{a:0}` allows `universe \ {a}`;
+ * empty `{}` allows the universe.
+ *
+ * A field is effectively allowed if any input grants it. Equivalently, a field
+ * stays excluded only if (a) no include-mode role grants it explicitly, AND (b)
+ * every exclude-mode role excludes it.
+ *
+ * Output mode:
+ * - All-include input → include-mode result (union of include keys)
+ * - At least one exclude-mode → exclude-mode result (or `{}` if no fields excluded)
+ * - Empty input or any universal grant `{}` → `{}` (universe)
+ *
+ * Within a single projection, mixing 1 and 0 keys is an error (call sites should
+ * normalize first). Across projections, mixing modes is supported and resolves
+ * via the additive rule above.
+ *
+ * @throws when a single projection mixes 1 and 0 keys, or contains an invalid value
+ */
+declare function unionProjections(...projections: TProjection[]): TProjection;
+/**
+ * Restrict a desired projection to only fields allowed by an access-control projection.
+ *
+ * The result is the intersection of the two projections: only fields that pass both
+ * `desired` and `accessControl` survive. Either side may be empty (unrestricted), in
+ * which case the other side is returned. Mixed include/exclude modes are normalized
+ * to a single result projection.
+ *
+ * @param desired - the projection the caller asked for
+ * @param accessControl - the projection allowed by RBAC
+ */
+declare function restrictProjection(desired: TProjection, accessControl: TProjection): TProjection;
+//#endregion
+//#region src/scope/filter.d.ts
+/**
+ * Merge multiple scope filters into a single filter using `$or` semantics.
+ *
+ * In RBAC, if multiple roles grant access with different filters,
+ * the user can see records matching ANY of them — hence `$or`.
+ *
+ * Behaviour:
+ * - Empty input → `undefined` (no filter)
+ * - Any empty filter → `undefined` (one role grants unrestricted access)
+ * - Single filter → returned as-is
+ * - All filters single-keyed on the same primitive field → `{ field: { $in: [...] } }`
+ * - Otherwise → `{ $or: [...] }`
+ *
+ * @returns the merged filter, or `undefined` for unrestricted access
+ */
+declare function mergeScopeFilters(scopes: TScopeFilter[]): TScopeFilter | undefined;
+//#endregion
+//#region src/scope/controls.d.ts
+/**
+ * Union per-role `controls` policies. Additive RBAC semantics: more roles =
+ * broader access, mirroring how `mergeScopeFilters` and `unionProjections`
+ * combine other parts of an `ArbacDbScope`.
+ *
+ * Resolution per control key:
+ *   1. Collect each scope's value for the key (including `undefined` for
+ *      silent scopes — i.e., scopes that have a `controls` map but no entry
+ *      for this key).
+ *   2. If any value is `undefined` or `true` → return `true` (full allow).
+ *      Silence and explicit allow both mean "this role has no objection".
+ *   3. Else (every scope is `false` or `string[]`):
+ *      - If all are `false` → return `false` (full deny).
+ *      - Else collect every `string[]` into a single sorted, de-duplicated
+ *        array; return that array. (Roles that say `false` don't contribute
+ *        positively; roles with whitelists do.)
+ *
+ * Scopes that omit the `controls` map entirely are treated as silent on
+ * EVERY key — i.e., they grant unrestricted control usage. As a result, if
+ * even a single scope in the input lacks a `controls` map, the result is
+ * always `{}` (no restrictions).
+ *
+ * Whitelist support is restricted to {@link WHITELISTABLE_CONTROLS}. Passing
+ * a whitelist for any other control throws — the gate cannot be enforced
+ * meaningfully in v1, so the misuse is rejected loudly at scope-merge time.
+ *
+ * @returns merged policy keyed by control name. Keys absent from the result
+ *          mean "no opinion → fully allowed". The caller should treat a
+ *          missing key the same as `true`.
+ *
+ * @throws when a non-whitelistable control is given a `readonly string[]` gate.
+ */
+declare function unionControlsPolicy(scopes: ReadonlyArray<{
+  controls?: Record<string, ControlGate>;
+}>): Record<string, ControlGate>;
+//#endregion
+//#region src/codegen/extract.d.ts
+interface TResourceActionMap {
+  /** Map of resource string → Set of action strings */
+  resources: Map<string, Set<string>>;
+  /** All unique resource strings */
+  allResources: Set<string>;
+  /** All unique action strings */
+  allActions: Set<string>;
+}
+/**
+ * Extract all resource and action strings from role definitions.
+ *
+ * @param roles - Array of built role definitions
+ * @param options.includeWildcards - If false (default), skip entries containing `*` or `**`
+ */
+declare function extractResourceActions(roles: TArbacRole<unknown, unknown>[], options?: {
+  includeWildcards?: boolean;
+}): TResourceActionMap;
+//#endregion
+//#region src/codegen/generate.d.ts
+interface TCodegenOptions {
+  /** Name for the resource union type. Default: "Resource" */
+  resourceTypeName?: string;
+  /** Name for the action union type. Default: "Action" */
+  actionTypeName?: string;
+  /** Whether to generate a resource-to-actions map type. Default: true */
+  resourceActionMap?: boolean;
+  /** Header comment. Default: "// Auto-generated by @aooth/arbac codegen" */
+  header?: string;
+}
+/**
+ * Generate TypeScript source defining union types for resources and actions.
+ */
+declare function generateResourceTypes(map: TResourceActionMap, options?: TCodegenOptions): string;
+//#endregion
+export { type ControlGate, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, definePrivilege, defineRole, extractResourceActions, generateResourceTypes, getProjectionMode, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };

package/dist/index.d.mts

@@ -0,0 +1,282 @@
+import { TArbacRole, TArbacRule } from "@aooth/arbac-core";
+export * from "@aooth/arbac-core";
+
+//#region src/define-role.d.ts
+/**
+ * A privilege function produces an array of rules when called.
+ * Created by `definePrivilege()` or manually.
+ */
+type TPrivilegeFunction<TUserAttrs, TScope> = () => TArbacRule<TUserAttrs, TScope>[];
+/**
+ * Fluent builder produced by {@link defineRole}.
+ *
+ * All methods return `this` so they can be chained. Rules are emitted in the order
+ * the corresponding `.allow()`, `.deny()`, and `.use()` calls were made — this matters
+ * for engines that respect rule order (deny-first / first-match-wins variants).
+ */
+interface RoleBuilder<TUserAttrs, TScope> {
+  /**
+   * Set the role id (required). Calling `.id()` more than once overwrites the
+   * previous value — the last call wins.
+   */
+  id(id: string): RoleBuilder<TUserAttrs, TScope>;
+  /** Set the human-readable role name. Optional. */
+  name(name: string): RoleBuilder<TUserAttrs, TScope>;
+  /** Set the role description. Optional. */
+  describe(description: string): RoleBuilder<TUserAttrs, TScope>;
+  /**
+   * Append an allow rule for a (resource, action) pair, with an optional scope
+   * function that derives a scope object from user attrs.
+   */
+  allow(resource: string, action: string, scope?: (attrs: TUserAttrs, userId: string) => TScope): RoleBuilder<TUserAttrs, TScope>;
+  /** Append a deny rule (`effect: 'deny'`) for a (resource, action) pair. */
+  deny(resource: string, action: string): RoleBuilder<TUserAttrs, TScope>;
+  /**
+   * Splice in rules from one or more privilege functions (see
+   * {@link definePrivilege}). Privileges are expanded inline in call order.
+   *
+   * Two overloads:
+   * 1. **Strict** — all privileges share the role's `TScope`. Preserves
+   *    bidirectional inference of `TUserAttrs` and `TScope` into bare-generic
+   *    privilege calls like `allowTableWrite("tasks", { scope: (attrs) => … })`.
+   * 2. **Variadic tuple** — privileges may carry independent per-arg scope
+   *    shapes (e.g. `ArbacDbScope<Task>` next to `ArbacDbScope<Comment>`).
+   *    Used when typed-table privileges don't structurally match the role
+   *    pin. Runtime storage type-erases through a cast.
+   */
+  use(...privileges: TPrivilegeFunction<TUserAttrs, TScope>[]): RoleBuilder<TUserAttrs, TScope>;
+  use<TScopes extends readonly unknown[]>(...privileges: { [K in keyof TScopes]: TPrivilegeFunction<TUserAttrs, TScopes[K]> }): RoleBuilder<TUserAttrs, TScope>;
+  /**
+   * Finalize and return a plain {@link TArbacRole} object suitable for
+   * `Arbac.registerRole`. Throws if `.id()` was never called.
+   */
+  build(): TArbacRole<TUserAttrs, TScope>;
+}
+/**
+ * Start building a new role.
+ *
+ * @example
+ * const editor = defineRole<MyAttrs, MyScope>()
+ *   .id("editor")
+ *   .name("Editor")
+ *   .use(allowTableWrite("articles"))
+ *   .deny("articles", "publish")
+ *   .build();
+ */
+declare function defineRole<TUserAttrs extends object = object, TScope extends object = object>(): RoleBuilder<TUserAttrs, TScope>;
+//#endregion
+//#region src/define-privilege.d.ts
+/**
+ * Define a reusable privilege factory.
+ *
+ * Double-call pattern: first call pins TUserAttrs/TScope generics,
+ * second call infers TArgs from the factory function.
+ *
+ * @example
+ * const canManageUsers = definePrivilege<MyAttrs, MyScope>()(
+ *   (scope: (attrs: MyAttrs, userId: string) => MyScope) => [
+ *     { resource: "users", action: "read", scope },
+ *     { resource: "users", action: "update", scope },
+ *   ]
+ * );
+ *
+ * defineRole<MyAttrs, MyScope>()
+ *   .id("manager")
+ *   .use(canManageUsers((attrs) => ({ dept: attrs.dept })))
+ *   .build();
+ */
+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 }`.
+ * - All 1s = inclusion mode (only listed fields allowed)
+ * - All 0s = exclusion mode (listed fields denied, rest allowed)
+ * - Mixing 0 and 1 in a single projection is invalid.
+ *
+ * Structurally compatible with @uniqu/core SelectExpr in object form.
+ */
+type TProjection = Record<string, 0 | 1>;
+/**
+ * A filter expression compatible with @uniqu/core FilterExpr.
+ * Comparison leaf: `{ field: value }` or `{ field: { $op: value } }`
+ * Logical branch: `{ $or: [...] }` | `{ $and: [...] }` | `{ $not: ... }`
+ */
+type TScopeFilter = Record<string, unknown>;
+/**
+ * Per-control policy in a resource scope.
+ *
+ * Used inside `ArbacDbScope.controls` (in `@aooth/arbac-moost`) to gate
+ * Uniquery URL controls (`$with`, `$groupBy`, `$having`, …) on a per-role basis.
+ *
+ * Semantics:
+ * - **silence** (key absent / `undefined`) — no opinion → allow.
+ * - `true` — explicit allow (same effect as silence; useful for documentation).
+ * - `false` — explicit deny; using the control fails 403.
+ * - `readonly string[]` — whitelist mode; only the listed values are allowed.
+ *   E.g., `{ $with: ['comments'] }` permits `?$with=comments` but rejects
+ *   `?$with=tasks` with 403.
+ *
+ * Whitelist arrays are supported only for controls whose value is a list of
+ * named entities (notably `$with` for relation names and `$groupBy` for
+ * column names). For other controls (e.g. `$having`) only boolean gates are
+ * supported in v1; supplying a whitelist throws at scope-evaluation time.
+ */
+type ControlGate = boolean | readonly string[];
+//#endregion
+//#region src/scope/projection.d.ts
+type TProjectionMode = "include" | "exclude" | "empty";
+/**
+ * Determine whether a projection is in inclusion mode (all 1s),
+ * exclusion mode (all 0s), or empty (`{}`, no restriction).
+ *
+ * @throws when a single projection mixes 0 and 1 values
+ */
+declare function getProjectionMode(proj: TProjection): TProjectionMode;
+/**
+ * Check whether a dot-path field is allowed by a projection.
+ *
+ * Inclusion mode: a field is allowed if it, any of its parents, or any of its children
+ *   is explicitly listed.
+ * Exclusion mode: a field is allowed unless it or any of its parents is excluded.
+ * Empty projection: every field is allowed.
+ */
+declare function isFieldAllowed(field: string, projection: TProjection): boolean;
+/**
+ * Combines projections from multiple RBAC role grants under additive semantics:
+ * more roles = broader access. Each projection represents a set of allowed fields:
+ * include-mode `{a:1}` allows `{a}`; exclude-mode `{a:0}` allows `universe \ {a}`;
+ * empty `{}` allows the universe.
+ *
+ * A field is effectively allowed if any input grants it. Equivalently, a field
+ * stays excluded only if (a) no include-mode role grants it explicitly, AND (b)
+ * every exclude-mode role excludes it.
+ *
+ * Output mode:
+ * - All-include input → include-mode result (union of include keys)
+ * - At least one exclude-mode → exclude-mode result (or `{}` if no fields excluded)
+ * - Empty input or any universal grant `{}` → `{}` (universe)
+ *
+ * Within a single projection, mixing 1 and 0 keys is an error (call sites should
+ * normalize first). Across projections, mixing modes is supported and resolves
+ * via the additive rule above.
+ *
+ * @throws when a single projection mixes 1 and 0 keys, or contains an invalid value
+ */
+declare function unionProjections(...projections: TProjection[]): TProjection;
+/**
+ * Restrict a desired projection to only fields allowed by an access-control projection.
+ *
+ * The result is the intersection of the two projections: only fields that pass both
+ * `desired` and `accessControl` survive. Either side may be empty (unrestricted), in
+ * which case the other side is returned. Mixed include/exclude modes are normalized
+ * to a single result projection.
+ *
+ * @param desired - the projection the caller asked for
+ * @param accessControl - the projection allowed by RBAC
+ */
+declare function restrictProjection(desired: TProjection, accessControl: TProjection): TProjection;
+//#endregion
+//#region src/scope/filter.d.ts
+/**
+ * Merge multiple scope filters into a single filter using `$or` semantics.
+ *
+ * In RBAC, if multiple roles grant access with different filters,
+ * the user can see records matching ANY of them — hence `$or`.
+ *
+ * Behaviour:
+ * - Empty input → `undefined` (no filter)
+ * - Any empty filter → `undefined` (one role grants unrestricted access)
+ * - Single filter → returned as-is
+ * - All filters single-keyed on the same primitive field → `{ field: { $in: [...] } }`
+ * - Otherwise → `{ $or: [...] }`
+ *
+ * @returns the merged filter, or `undefined` for unrestricted access
+ */
+declare function mergeScopeFilters(scopes: TScopeFilter[]): TScopeFilter | undefined;
+//#endregion
+//#region src/scope/controls.d.ts
+/**
+ * Union per-role `controls` policies. Additive RBAC semantics: more roles =
+ * broader access, mirroring how `mergeScopeFilters` and `unionProjections`
+ * combine other parts of an `ArbacDbScope`.
+ *
+ * Resolution per control key:
+ *   1. Collect each scope's value for the key (including `undefined` for
+ *      silent scopes — i.e., scopes that have a `controls` map but no entry
+ *      for this key).
+ *   2. If any value is `undefined` or `true` → return `true` (full allow).
+ *      Silence and explicit allow both mean "this role has no objection".
+ *   3. Else (every scope is `false` or `string[]`):
+ *      - If all are `false` → return `false` (full deny).
+ *      - Else collect every `string[]` into a single sorted, de-duplicated
+ *        array; return that array. (Roles that say `false` don't contribute
+ *        positively; roles with whitelists do.)
+ *
+ * Scopes that omit the `controls` map entirely are treated as silent on
+ * EVERY key — i.e., they grant unrestricted control usage. As a result, if
+ * even a single scope in the input lacks a `controls` map, the result is
+ * always `{}` (no restrictions).
+ *
+ * Whitelist support is restricted to {@link WHITELISTABLE_CONTROLS}. Passing
+ * a whitelist for any other control throws — the gate cannot be enforced
+ * meaningfully in v1, so the misuse is rejected loudly at scope-merge time.
+ *
+ * @returns merged policy keyed by control name. Keys absent from the result
+ *          mean "no opinion → fully allowed". The caller should treat a
+ *          missing key the same as `true`.
+ *
+ * @throws when a non-whitelistable control is given a `readonly string[]` gate.
+ */
+declare function unionControlsPolicy(scopes: ReadonlyArray<{
+  controls?: Record<string, ControlGate>;
+}>): Record<string, ControlGate>;
+//#endregion
+//#region src/codegen/extract.d.ts
+interface TResourceActionMap {
+  /** Map of resource string → Set of action strings */
+  resources: Map<string, Set<string>>;
+  /** All unique resource strings */
+  allResources: Set<string>;
+  /** All unique action strings */
+  allActions: Set<string>;
+}
+/**
+ * Extract all resource and action strings from role definitions.
+ *
+ * @param roles - Array of built role definitions
+ * @param options.includeWildcards - If false (default), skip entries containing `*` or `**`
+ */
+declare function extractResourceActions(roles: TArbacRole<unknown, unknown>[], options?: {
+  includeWildcards?: boolean;
+}): TResourceActionMap;
+//#endregion
+//#region src/codegen/generate.d.ts
+interface TCodegenOptions {
+  /** Name for the resource union type. Default: "Resource" */
+  resourceTypeName?: string;
+  /** Name for the action union type. Default: "Action" */
+  actionTypeName?: string;
+  /** Whether to generate a resource-to-actions map type. Default: true */
+  resourceActionMap?: boolean;
+  /** Header comment. Default: "// Auto-generated by @aooth/arbac codegen" */
+  header?: string;
+}
+/**
+ * Generate TypeScript source defining union types for resources and actions.
+ */
+declare function generateResourceTypes(map: TResourceActionMap, options?: TCodegenOptions): string;
+//#endregion
+export { type ControlGate, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, definePrivilege, defineRole, extractResourceActions, generateResourceTypes, getProjectionMode, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };