@aooth/arbac-moost 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,334 @@
+import { n as ArbacUserProviderToken, t as ArbacUserProvider } from "./user.provider-JpI5dD6Z.mjs";
+import { Arbac, Arbac as Arbac$1, TArbacCompiledRule, TArbacEvalResult, TArbacRole, TArbacRoleForResource, TArbacRule, arbacPatternToRegex } from "@aooth/arbac-core";
+import { TAuthGuardDef } from "@moostjs/event-http";
+import { EventContext } from "@wooksjs/event-core";
+import { Mate, TMateParamMeta, TMoostMetadata } from "moost";
+import { ControlGate, ControlGate as ControlGate$1, TProjection, TScopeFilter } from "@aooth/arbac";
+import { AsDbController, AsDbReadableController } from "@atscript/moost-db";
+import { NavPropsOf, OwnPropsOf, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { TMetaResponse } from "@atscript/db";
+
+//#region src/arbac.composables.d.ts
+interface ArbacBindings {
+  getScopes: <TScope extends object>() => TScope[] | undefined;
+  setScopes: <TScope extends object>(scope: TScope[] | undefined) => void;
+  evaluate: <TScope extends object>(opts?: {
+    resource?: string;
+    action?: string;
+  }) => Promise<{
+    allowed: boolean;
+    scopes?: TScope[];
+    userId: string;
+  }>;
+  /**
+   * Throw-on-deny variant of {@link evaluate}. Returns the same shape on
+   * `allowed: true`; throws `HttpError(403)` otherwise.
+   *
+   * Use this in handlers/steps that want a hard short-circuit on deny.
+   * Use {@link evaluate} when you need to inspect `allowed` (e.g. to merge
+   * with another policy, to filter UI metadata, or to fall through to a
+   * different authorization path).
+   */
+  evaluateOrThrow: <TScope extends object>(opts?: {
+    resource?: string;
+    action?: string;
+  }) => Promise<{
+    allowed: true;
+    scopes?: TScope[];
+    userId: string;
+  }>;
+  resource: string;
+  action: string;
+  isPublic: boolean;
+}
+/**
+ * Composable for ARBAC utilities within Moost handlers and interceptors.
+ *
+ * Exposes scope read/write, lazy `evaluate`, and the resolved
+ * resource/action/public flags derived from the current controller +
+ * method metadata.
+ *
+ * Resource/action/isPublic are recomputed on every call because WF events
+ * dispatch multiple step handlers under one `EventContext` — each step
+ * mutates the controller-context method via `setControllerContext`, so any
+ * per-ctx memo would lock in the first dispatched method's metadata (e.g.
+ * the `@Public()` WF_FLOW body) and incorrectly bypass ARBAC on the gated
+ * step handlers. Scope read/write goes through `arbacScopesKey` directly
+ * so it still lives on the per-event slot.
+ */
+declare const useArbac: (_ctx?: EventContext) => ArbacBindings;
+//#endregion
+//#region src/arbac.decorator.d.ts
+/**
+ * ARBAC checks authorization, not authentication, so the transport
+ * declaration is empty — pair with an upstream auth guard (e.g. JWT
+ * bearer) that publishes the principal.
+ *
+ * Runs for every event kind (HTTP, WF, CLI, WS). The `arbacPublic` mate
+ * flag (written by auth-moost's combined `@Public()`) is the only bypass —
+ * apply it to controllers/handlers that should remain reachable without an
+ * evaluated rule (e.g. login/recovery workflows, health probes).
+ */
+declare const arbacAuthorizeInterceptor: TAuthGuardDef;
+/** Wrapped via `Authenticate` so `@moostjs/swagger` picks up the auth-guard metadata. */
+declare const ArbacAuthorize: () => ClassDecorator & MethodDecorator;
+/**
+ * Decorator to specify a resource id for ARBAC evaluation. Apply to a
+ * controller class or a handler method.
+ */
+declare const ArbacResource: (name: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Decorator to specify an action id for ARBAC evaluation. Typically applied
+ * at the method level.
+ */
+declare const ArbacAction: (name: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+//#endregion
+//#region src/arbac.mate.d.ts
+/**
+ * ARBAC metadata fields attached to classes and methods by ARBAC decorators.
+ *
+ * Augments the shared `TMoostMetadata` workspace via TypeScript declaration
+ * merging so other moost-aware tooling (and `getArbacMate()` readers) sees
+ * these fields with full type safety.
+ */
+interface TArbacMeta {
+  arbacResourceId?: string;
+  arbacActionId?: string;
+  arbacPublic?: boolean;
+}
+declare module "moost" {
+  interface TMoostMetadata extends TArbacMeta {}
+}
+type ArbacMate = Mate<TMoostMetadata & {
+  params: TMateParamMeta[];
+}, TMoostMetadata & {
+  params: TMateParamMeta[];
+}>;
+/**
+ * Returns the shared `Mate` instance typed with ARBAC metadata fields.
+ *
+ * All ARBAC decorators write through this typed wrapper so reads and writes
+ * stay type-checked against `TArbacMeta`.
+ */
+declare function getArbacMate(): ArbacMate;
+//#endregion
+//#region src/db/scope-types.d.ts
+/**
+ * Unwrap a `NavPropsOf<T>[K]` value to its target model type:
+ * `Comment[]` → `Comment`, `Task` → `Task`. Used to recurse `with.<K>` into
+ * the joined model's own type so per-relation scopes get typed against the
+ * RIGHT entity (not the array wrapper).
+ */
+type NavTarget<U> = U extends readonly (infer V)[] ? V : U;
+/**
+ * True only when `T` is `unknown` (or `any`). `unknown extends T` holds for
+ * both. Callers use this to pick the legacy untyped shape when no model is
+ * annotated.
+ */
+type IsUnknown<T> = unknown extends T ? true : false;
+/**
+ * Permissive own-field key set. With a typed `T`, autocompletes against
+ * `keyof OwnPropsOf<T>` while still accepting dotted-path projections like
+ * `mfa.value` via the `(string & {})` escape hatch. With `T = unknown`,
+ * `OwnPropsOf<unknown>` collapses to `unknown` so `keyof` is `never` →
+ * falls back to plain `string`.
+ */
+type OwnFieldKey<T> = keyof OwnPropsOf<T> extends never ? string : (keyof OwnPropsOf<T> & string) | (string & {});
+/**
+ * Same idiom for nav relation names. `NavPropsOf<unknown>` is
+ * `Record<string, never>`, so its `keyof` is `string` — the typed branch
+ * still resolves to plain `string` (the `(string & {})` escape collapses
+ * with `string`).
+ */
+type NavRelationKey<T> = keyof NavPropsOf<T> extends never ? string : (keyof NavPropsOf<T> & string) | (string & {});
+/**
+ * Typed projection keyed by own-field paths (with dotted-path escape).
+ * Falls back to the legacy `TProjection = Record<string, 0 | 1>` for
+ * untyped scopes so existing callers that pass the result straight to
+ * `unionProjections` / `restrictProjection` keep compiling.
+ */
+type ProjectionOf<T> = IsUnknown<T> extends true ? TProjection : Partial<Record<OwnFieldKey<T>, 0 | 1>>;
+/**
+ * Typed control gates: `$with` against nav names, `$select` against own
+ * fields, other `$`-prefixed controls passthrough. Falls back to the
+ * legacy untyped `Record<string, ControlGate>` for `T = unknown` so
+ * internal helpers (`unionControlsPolicy`) and existing untyped call
+ * sites keep compiling.
+ */
+type ControlsOf<T> = IsUnknown<T> extends true ? Record<string, ControlGate$1> : {
+  $with?: Array<NavRelationKey<T>> | boolean;
+  $select?: Array<OwnFieldKey<T>> | boolean;
+  $groupBy?: ControlGate$1;
+  $having?: ControlGate$1;
+  [key: `$${string}`]: ControlGate$1 | Array<string> | undefined;
+};
+//#endregion
+//#region src/db/as-arbac-db-controller.d.ts
+/**
+ * Contract returned by an ARBAC role's scope predicate on a DB-backed resource.
+ *
+ * Apps can extend this interface with their own fields via TypeScript
+ * declaration merging — both at role-definition time (returned from
+ * `role.allow(...)`) and at consumption time (custom controller overrides
+ * reading `scopes[i].myCustomField` get full type safety):
+ *
+ * @example
+ * ```ts
+ * declare module '@aooth/arbac-moost' {
+ *   interface ArbacDbScope {
+ *     tenantId?: string
+ *   }
+ * }
+ * ```
+ */
+interface ArbacDbScope<T = unknown> {
+  filter?: TScopeFilter;
+  projection?: ProjectionOf<T>;
+  set?: Partial<Record<OwnFieldKey<T>, unknown>>;
+  allowedFields?: Array<OwnFieldKey<T>>;
+  /**
+   * Per-control gates for Uniquery URL controls (`$with`, `$groupBy`, `$having`, …).
+   * Evaluated by {@link AsArbacDbController.validateControls} before query execution;
+   * a violation throws `HttpError(403)`.
+   *
+   * Per-key semantics ({@link ControlGate}):
+   *   - absent / `true` — allowed.
+   *   - `false` — denied entirely.
+   *   - `readonly string[]` — whitelist (e.g. `{ $with: ['comments'] }` allows
+   *     `?$with=comments`, rejects `?$with=tasks`). Supported only for `$with`
+   *     (relation names) and `$groupBy` (column names) in v1.
+   *
+   * Across roles, gates union additively (silence wins) via {@link unionControlsPolicy}.
+   *
+   * @example `{ controls: { $with: false } }` — disable $with for this role.
+   * @example `{ controls: { $with: ['comments', 'owner'] } }` — restrict relations.
+   */
+  controls?: ControlsOf<T>;
+  /**
+   * Per-relation sub-scopes applied when the request expands a relation via
+   * `?$with=<name>`. Recursive — each sub-scope has the same shape and can
+   * declare its own `with` for nested expansions (e.g. tasks → comments → task).
+   *
+   * **Authority model**: the PARENT scope owns the policy for joined rows.
+   * arbac-moost does NOT re-evaluate ARBAC against the joined resource's own
+   * scopes — that would be a confusing indirection and a perf hit. Whatever
+   * the parent declares here is what surfaces from the expansion.
+   *
+   * **Union across roles**: when multiple roles allow the same parent table,
+   * their `with[name]` sub-scopes are unioned at every nested level using the
+   * existing `unionProjections` / `mergeScopeFilters` / `unionControlsPolicy`
+   * primitives (additive: broader access wins, same rules as the parent).
+   *
+   * **Silence wins**: if no role declares `with.<name>`, expansion is
+   * unrestricted (matches `controls.$with` whitelist semantics; the gate
+   * still applies if declared).
+   */
+  with?: WithOf<T>;
+}
+/**
+ * Per-relation sub-scope map. For `T = unknown` falls back to the legacy
+ * untyped `Record<string, ArbacDbScope>`. With a typed `T`, each known
+ * relation key gets its scope typed against the joined model (via
+ * `NavTarget` to unwrap arrays), while arbitrary `(string & {})` keys
+ * keep the untyped escape hatch. Lives here (not in `scope-types.ts`)
+ * because it must reference `ArbacDbScope` recursively.
+ */
+type WithOf<T> = unknown extends T ? Record<string, ArbacDbScope> : { [K in NavRelationKey<T>]?: K extends keyof NavPropsOf<T> ? ArbacDbScope<NavTarget<NavPropsOf<T>[K]>> : ArbacDbScope };
+declare class AsArbacDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> extends AsDbController<T> {
+  protected transformFilter(filter: Record<string, unknown> | undefined): Promise<Record<string, unknown>>;
+  protected transformProjection(projection?: TProjection): TProjection | undefined | Promise<TProjection | undefined>;
+  /**
+   * Enforce per-role `ArbacDbScope.controls` gates against the parsed Uniquery
+   * controls of a request. Runs after the base validator (which checks the
+   * controls DTO shape) and BEFORE the query/aggregation pipeline executes.
+   *
+   * `transformFilter` runs first on every read endpoint and caches the
+   * evaluated scopes via `arbac.setScopes(...)`, so we read those scopes
+   * directly here without re-evaluating ARBAC.
+   *
+   * On a violation we throw `HttpError(403)`. moost-db's `query` / `pages` /
+   * `getOne` handlers do NOT wrap `validateParsed` in try/catch, so the
+   * thrown error bubbles to moost which translates it to a 403 response.
+   */
+  protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
+  protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
+  protected onWrite(action: "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany", data: unknown): Promise<unknown>;
+  protected onRemove(id: unknown): Promise<unknown>;
+  private assertInScope;
+  private identifierFields;
+}
+/**
+ * Test-friendly internal helper — exported for unit tests and helper
+ * composition; regular consumers should not call this directly.
+ *
+ * Enforce a per-control policy against a parsed Uniquery `controls` map.
+ *
+ * Throws `HttpError(403)` on the first violation. Pure (no DI) so it is
+ * trivially unit-testable; `validateControls` wires it up to the controller's
+ * cached scopes.
+ *
+ * Semantics per gate (see {@link ControlGate}):
+ *   - `true` (or absent — dropped by `unionControlsPolicy`): allow.
+ *   - `false`: deny if the control is used at all.
+ *   - `readonly string[]`: allow only the listed values; reject any other.
+ *
+ * "Used" means the control key is present AND non-empty (an empty array is
+ * treated as not used, matching how the parser leaves missing controls).
+ */
+declare function enforceControlsPolicy(policy: Record<string, ControlGate$1>, controls: Record<string, unknown>): void;
+/**
+ * Test-friendly internal helper — exported for unit tests and helper
+ * composition; regular consumers should not call this directly.
+ *
+ * Extract the set of "named values" from a Uniquery control payload, for
+ * use against a whitelist gate.
+ *
+ * Currently supported (matches `WHITELISTABLE_CONTROLS` in `unionControlsPolicy`):
+ *   - `$with` — array of `{ name, … }` objects (per `TypedWithRelation`,
+ *     see `@uniqu/core` parser at `parseWithSegment`); we extract `name`.
+ *     Bare strings are tolerated for forward compatibility.
+ *   - `$groupBy` — array of column names (strings). Returned as-is.
+ *
+ * For unknown controls we return an empty array; the caller then enforces
+ * `false`-only semantics (controlled by `unionControlsPolicy`'s whitelist
+ * gate, which throws if a non-whitelistable control receives a string[]).
+ */
+declare function extractUsedControlValues(key: string, value: unknown): string[];
+/**
+ * Test-friendly internal helper — exported for unit tests and helper
+ * composition; regular consumers should not call this directly.
+ *
+ * Apply the union of `allowedFields` whitelists (with `preserveFields`
+ * always preserved) and overlay each scope's `set` overrides. Returns a
+ * shallow copy; original `data` is not mutated.
+ */
+declare function applyAllowedFieldsAndSet(data: unknown, scopes: ArbacDbScope[], preserveFields?: readonly string[]): unknown;
+//#endregion
+//#region src/db/as-arbac-db-readable-controller.d.ts
+/**
+ * Read-only mirror of {@link AsArbacDbController} for view-style controllers
+ * built on top of `@atscript/moost-db`'s {@link AsDbReadableController}.
+ * Applies the same filter / projection / controls overlays — no write-side
+ * hooks because the parent exposes none.
+ */
+declare class AsArbacDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> extends AsDbReadableController<T> {
+  protected transformFilter(filter: Record<string, unknown> | undefined): Promise<Record<string, unknown>>;
+  protected transformProjection(projection?: TProjection): TProjection | undefined | Promise<TProjection | undefined>;
+  protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
+}
+//#endregion
+//#region src/moost-arbac.d.ts
+/**
+ * A DI-enabled extension of the `Arbac` class for use within Moost.
+ *
+ * Allows ARBAC (Advanced Role-Based Access Control) to be injected into
+ * Moost services and controllers via the framework's dependency-injection
+ * container. Defaults to the SINGLETON scope so all handlers share one
+ * registry of roles/resources.
+ *
+ * @template TUserAttrs - The type representing user attributes relevant to access control.
+ * @template TScope - The type representing access control scopes.
+ */
+declare class MoostArbac<TUserAttrs extends object, TScope extends object> extends Arbac$1<TUserAttrs, TScope> {}
+//#endregion
+export { Arbac, ArbacAction, ArbacAuthorize, ArbacDbScope, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, type ControlGate, type ControlsOf, MoostArbac, type NavRelationKey, type NavTarget, type OwnFieldKey, type ProjectionOf, type TArbacCompiledRule, type TArbacEvalResult, TArbacMeta, type TArbacRole, type TArbacRoleForResource, type TArbacRule, applyAllowedFieldsAndSet, arbacAuthorizeInterceptor, arbacPatternToRegex, enforceControlsPolicy, extractUsedControlValues, getArbacMate, useArbac };