@aooth/arbac-moost 0.1.73 → 0.1.75

package/dist/atscript/index.d.mts

@@ -1,4 +1,4 @@
-import { r as AoothArbacClaims, t as ArbacUserProvider } from "../user.provider-NMSzynGK.mjs";
+import { r as AoothArbacClaims, t as ArbacUserProvider } from "../user.provider-D0ySI_-A.mjs";
 import { TAtscriptAnnotatedType, TAtscriptTypeObject, TMetadataMap, TValidatorOptions, Validator } from "@atscript/typescript/utils";
 import { AoothUserCredentials } from "@aooth/user/atscript-db/model.as";
 //#region src/atscript/auto-provider.d.ts

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { _ as ProjectionOf, a as conjoinArbacDbScopes, b as TArbacMeta, c as ArbacDbScope, d as extractUsedControlValues, f as applyAllowedFieldsAndSet, g as OwnFieldKey, h as NavTarget, i as ConjoinArbacDbScopesOptions, l as AsArbacDbController, m as NavRelationKey, n as ArbacUserProviderToken, o as RefForeignKey, p as ControlsOf, r as AoothArbacClaims, s as RefTableSource, t as ArbacUserProvider, u as enforceControlsPolicy, v as ARBAC_DELEGATED_AUTH, x as getArbacMate, y as ArbacDelegatedAuth } from "./user.provider-NMSzynGK.mjs";
+import { _ as ProjectionOf, a as conjoinArbacDbScopes, b as TArbacMeta, c as ArbacDbScope, d as extractUsedControlValues, f as applyAllowedFieldsAndSet, g as OwnFieldKey, h as NavTarget, i as ConjoinArbacDbScopesOptions, l as AsArbacDbController, m as NavRelationKey, n as ArbacUserProviderToken, o as RefForeignKey, p as ControlsOf, r as AoothArbacClaims, s as RefTableSource, t as ArbacUserProvider, u as enforceControlsPolicy, v as ARBAC_DELEGATED_AUTH, x as getArbacMate, y as ArbacDelegatedAuth } from "./user.provider-D0ySI_-A.mjs";
 import { Arbac, Arbac as Arbac$1, TArbacCompiledRule, TArbacEvalResult, TArbacEvalResult as TArbacEvalResult$1, TArbacRole, TArbacRoleForResource, TArbacRule, arbacPatternToRegex } from "@aooth/arbac-core";
+import { ControlGate, TProjection, TScopeFieldRules, TScopeFilter, conjoinScopeFilters } from "@aooth/arbac";
 import { TAuthGuardDef } from "@moostjs/event-http";
 import { EventContext } from "@wooksjs/event-core";
-import { ControlGate, TProjection, TScopeFieldRules, TScopeFilter } from "@aooth/arbac";
-import { FilterExpr, TDbRemoveGuardContext, TDbWriteCheckContext, TDbWriteGuardContext, TDeleteOptions, TMetaResponse, TRowResolveOptions, TWriteOptions } from "@atscript/db";
-import { AsDbReadableController, AsJsonValueHelpController, AsValueHelpController, TDbControlsType, TDbIndexFieldPaths, TDbRequestContext, ValueHelpSelect } from "@atscript/moost-db";
-import { TAtscriptAnnotatedType, TAtscriptDataType } from "@atscript/typescript/utils";
+import { FilterExpr, TDbRemoveGuardContext, TDbWriteCheckContext, TDbWriteGuardContext, TDeleteOptions, TMetaResponse, TRowResolveOptions, TWriteOptions, UniqueryControls } from "@atscript/db";
+import { AsDbReadableController, AsJsonValueHelpController, AsValueHelpController, TDbActionScopeContext, TDbControlsType, TDbIndexFieldPaths, TDbRequestContext, ValueHelpSelect } from "@atscript/moost-db";
+import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
 //#region src/db/visibility.d.ts
 /**
  * The slice of an atscript-db readable (table / view) the visibility walk
@@ -54,8 +54,6 @@ interface VisibilityTableSource {
    * @since 0.1.72
    */
   jsonParents?: ReadonlySet<string>;
-  /** Whether the adapter searches natively (`/meta` search-surface pruning). @since 0.1.72 */
-  isSearchable?(): boolean;
 }
 /** Relation name → the visibility its joined rows obey, or `null` when hidden. */
 type ArbacRelationResolution = ReadonlyMap<string, MetaVisibility | null>;
@@ -291,6 +289,7 @@ declare const ArbacResource: (name: string) => MethodDecorator & ClassDecorator
 declare const ArbacAction: (name: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 //#endregion
 //#region src/db/as-arbac-db-readable-controller.d.ts
+type TSelect = UniqueryControls["$select"];
 /**
  * Read-only mirror of {@link AsArbacDbController} for view-style controllers
  * built on top of `@atscript/moost-db`'s {@link AsDbReadableController}.
@@ -303,17 +302,25 @@ declare class AsArbacDbReadableController<T extends TAtscriptAnnotatedType = TAt
   /** Same contract as {@link AsArbacDbController.prepareRequest}. */
   protected prepareRequest(ctx: TDbRequestContext): Promise<void>;
   /** Same contract as {@link AsArbacDbController.transformFilter}. */
-  protected transformFilter(filter: Record<string, unknown> | undefined): Record<string, unknown>;
+  protected transformFilter(filter: Record<string, unknown> | undefined): FilterExpr | Promise<FilterExpr>;
+  /** Same contract as {@link AsArbacDbController.transformRelationFilter}. Since 0.1.74. */
+  protected transformRelationFilter(path: string, filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
   /** Same contract as {@link AsArbacDbController.transformProjection}. */
-  protected transformProjection(projection?: TProjection): TProjection | undefined;
+  protected transformProjection(projection?: TSelect): TSelect | undefined | Promise<TSelect | undefined>;
   /** Same contract as {@link AsArbacDbController.validateControls}. */
   protected validateControls(controls: Record<string, unknown>, type: TDbControlsType): string | undefined;
   /** Same contract as {@link AsArbacDbController.applyMetaOverlay}. */
   protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
+  /**
+   * `GET /meta/form/:name` under the `/meta` overlay's pointer rule: a form
+   * prop's `ref` / `ui.valueHelp` binding to a table the caller cannot read
+   * (or whose named fields they cannot see) is stripped.
+   */
+  metaForm(name: string): Promise<TSerializedAnnotatedType>;
   /** Same contract as {@link AsArbacDbController.authorizeForm}. */
   protected authorizeForm(_name: string, actionNames: readonly string[]): Promise<boolean>;
   /** Same contract as {@link AsArbacDbController.actionRowScope}. */
-  protected actionRowScope(name: string): Promise<Record<string, unknown> | undefined>;
+  protected actionRowScope(name: string, _ctx?: TDbActionScopeContext): Promise<Record<string, unknown> | undefined>;
   /** Same contract as {@link AsArbacDbController.allowedActions}. */
   protected allowedActions(names: readonly string[]): Promise<string[]>;
   /** Same contract as {@link AsArbacDbController.[ARBAC_DELEGATED_AUTH]}. */
@@ -358,23 +365,20 @@ declare class AsArbacDbReadableController<T extends TAtscriptAnnotatedType = TAt
  */
 declare abstract class AsArbacValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsValueHelpController<T, DataType> {
   private _arbacHost?;
+  /** Makes this controller the binding / `ref` policy source for its bound type's ARBAC resource. */
+  protected readonly _arbacValueHelpTarget: true;
   private get arbacHost();
   protected prepareRequest(_ctx: TDbRequestContext): Promise<void>;
-  protected transformFilter(filter: FilterExpr): FilterExpr;
-  protected transformProjection(select: ValueHelpSelect<DataType> | undefined): ValueHelpSelect<DataType> | undefined;
+  /** Same contract as {@link AsArbacDbController.transformFilter}. */
+  protected transformFilter(filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
+  protected transformProjection(select: ValueHelpSelect<DataType> | undefined): ValueHelpSelect<DataType> | undefined | Promise<ValueHelpSelect<DataType> | undefined>;
   protected hasField(path: string): boolean;
   protected validateControls(controls: Record<string, unknown>, type: TDbControlsType): string | undefined;
   protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
-  runQuery(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType[]>;
-  runPages(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | {
-    data: DataType[];
-    page: number;
-    itemsPerPage: number;
-    pages: number;
-    count: number;
-  }>;
-  runGetOne(id: string): Promise<DataType | import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody>>;
-  runGetOneComposite(query: Record<string, string>): Promise<DataType | import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody>>;
+  runQuery(url: string): ReturnType<AsValueHelpController<T, DataType>["runQuery"]>;
+  runPages(url: string): ReturnType<AsValueHelpController<T, DataType>["runPages"]>;
+  runGetOne(id: string): ReturnType<AsValueHelpController<T, DataType>["runGetOne"]>;
+  runGetOneComposite(query: Record<string, string>): ReturnType<AsValueHelpController<T, DataType>["runGetOneComposite"]>;
 }
 /**
  * ARBAC-scoped mirror of `@atscript/moost-db`'s
@@ -396,23 +400,20 @@ declare abstract class AsArbacValueHelpController<T extends TAtscriptAnnotatedTy
  */
 declare class AsArbacJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsJsonValueHelpController<T, DataType> {
   private _arbacHost?;
+  /** Makes this controller the binding / `ref` policy source for its bound type's ARBAC resource. */
+  protected readonly _arbacValueHelpTarget: true;
   private get arbacHost();
   protected prepareRequest(_ctx: TDbRequestContext): Promise<void>;
-  protected transformFilter(filter: FilterExpr): FilterExpr;
-  protected transformProjection(select: ValueHelpSelect<DataType> | undefined): ValueHelpSelect<DataType> | undefined;
+  /** Same contract as {@link AsArbacDbController.transformFilter}. */
+  protected transformFilter(filter: FilterExpr): FilterExpr | Promise<FilterExpr>;
+  protected transformProjection(select: ValueHelpSelect<DataType> | undefined): ValueHelpSelect<DataType> | undefined | Promise<ValueHelpSelect<DataType> | undefined>;
   protected hasField(path: string): boolean;
   protected validateControls(controls: Record<string, unknown>, type: TDbControlsType): string | undefined;
   protected applyMetaOverlay(meta: TMetaResponse): Promise<TMetaResponse>;
-  runQuery(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType[]>;
-  runPages(url: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | {
-    data: DataType[];
-    page: number;
-    itemsPerPage: number;
-    pages: number;
-    count: number;
-  }>;
-  runGetOne(id: string): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType>;
-  runGetOneComposite(query: Record<string, string>): Promise<import("@wooksjs/event-http").HttpError<import("@wooksjs/event-http").TWooksErrorBody> | DataType>;
+  runQuery(url: string): ReturnType<AsJsonValueHelpController<T, DataType>["runQuery"]>;
+  runPages(url: string): ReturnType<AsJsonValueHelpController<T, DataType>["runPages"]>;
+  runGetOne(id: string): ReturnType<AsJsonValueHelpController<T, DataType>["runGetOne"]>;
+  runGetOneComposite(query: Record<string, string>): ReturnType<AsJsonValueHelpController<T, DataType>["runGetOneComposite"]>;
 }
 //#endregion
 //#region src/db/relation-policy.d.ts
@@ -488,18 +489,17 @@ declare function pruneMetaByVisibility(meta: TMetaResponse, vis: MetaVisibility,
  *    `crud` already advertises no read surface, and write-only principals
  *    still need `type` for their insert/update forms. PK + `preferredId` are
  *    never pruned.
- * 3. The search surface: `searchIndexes` reading a hidden field are dropped,
- *    `searchable` / `vectorSearchable` / `geoSearchable` recomputed, and the
- *    `query` / `pages` control lists lose the controls that became unusable
- *    (`crud.geo` goes when no geo index is left).
+ *
+ * The search surface (`searchIndexes`, `searchable`, `vectorSearchable`,
+ * `geoSearchable`) is narrowed by moost-db itself (≥ 0.1.147, under the
+ * overridden `hasField`), after this overlay.
  *
  * @param source - the controller's `this.readable` (identifiers, relations
  *   and schema rules are derived from it); an identifier set (the 0.1.67
  *   signature) still works, without them
- * @param indexes - the controller's `indexFieldPaths()`; defaults to calling
- *   it on the current controller when it has one
+ * @param _indexes - @deprecated ignored since 0.1.74 (moost-db prunes the search surface)
  */
-declare function applyArbacMetaOverlay(meta: TMetaResponse, source: VisibilityTableSource | ReadonlySet<string>, indexes?: readonly TDbIndexFieldPaths[]): Promise<TMetaResponse>;
+declare function applyArbacMetaOverlay(meta: TMetaResponse, source: VisibilityTableSource | ReadonlySet<string>, _indexes?: readonly TDbIndexFieldPaths[]): Promise<TMetaResponse>;
 /**
  * Test-friendly internal helper — exported for unit tests and helper
  * composition; regular consumers should not call this directly.
@@ -566,7 +566,18 @@ declare function isScopedFieldVisible(scopes: ArbacDbScope[], path: string, sour
  * action id / row is read): resolve the request's scopes
  * ({@link resolveRequestScopes} — 403 on denial, `arbacPublic` does not
  * bypass) and, on read endpoints, the `$with` relation policy for the
- * requested relations.
+ * requested relations — the `$with` entries and, since 0.1.74, the
+ * relations the client filter's relational predicates name (`ctx.filter`):
+ * a predicate on a relation is allowed exactly when `$with` of it is (same
+ * visibility, same `controls.$with` gates).
+ *
+ * Delegated endpoints (no grant of their own): `"availableActions"`
+ * (`GET /meta/actions…`) — some row-level action grant (or, on a
+ * `@DbActionsFrom` controller, none: its own part lists nothing);
+ * `"delegatedAction"` (`POST /delegated-actions/:name`, since 0.1.74) — the
+ * controller's READ grant, since the route only resolves which of the
+ * caller's readable rows match the query; the action itself is authorized
+ * by its source controller on every batch.
  *
  * @since 0.1.72
  */
@@ -593,12 +604,17 @@ declare function arbacAllowedActions(names: readonly string[]): Promise<string[]
  * `@DbAction` `name` may run on — the filter of the caller's grant on the
  * action ({@link actionArbacIds}: every handler method of the action, or a
  * class-level entry's fallback ids), including custom-field row filters and
- * credential attenuation. No grant → a match-nothing filter (fail closed);
- * an unrestricted grant → `undefined`. When the current request IS that
- * action (its resolved scopes are the same evaluation), the row overlay
+ * credential attenuation. Several grants union (`$or`); attenuation is
+ * already intersected into each. No grant → a match-nothing filter (fail
+ * closed); an unrestricted grant → `undefined`. When the current request IS
+ * that action (its resolved scopes are the same evaluation), the row overlay
  * already applies it → `undefined`. Equal filters are returned as ONE
  * object per request.
  *
+ * Candidate-free on purpose (evaluated once per action per event) — see
+ * `AsArbacDbController.actionRowScope` to bound an action by its candidate
+ * rows.
+ *
  * @since 0.1.72
  */
 declare function arbacActionRowScope(name: string): Promise<Record<string, unknown> | undefined>;
@@ -610,6 +626,20 @@ declare function arbacActionRowScope(name: string): Promise<Record<string, unkno
  * @since 0.1.72
  */
 declare function arbacRowFilter(filter: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * Body of the ARBAC DB controllers' `transformRelationFilter` (since 0.1.74):
+ * the operand of a CLIENT relational predicate at `path` (`ticket`,
+ * `ticket.team`, `tickets.issues` inside `$with=tickets(…)`) CONJOINED
+ * with the row filter of the related rows the caller may see there — the
+ * same policy `$with` of that relation applies: a declared `with.<rel>`
+ * sub-scope, else the caller's own read grant on the related table. So
+ * `$some` matches, and `$none` excludes, only on rows the caller could
+ * load. A relation the request did not resolve answers like an unknown
+ * field (400 — the request gate rejects it first).
+ *
+ * @since 0.1.74
+ */
+declare function arbacRelationFilter(path: string, filter: FilterExpr, readable: VisibilityTableSource): FilterExpr;
 //#endregion
 //#region src/db/shared-read-helpers.d.ts
 /**
@@ -683,9 +713,14 @@ interface ArbacWriteTable {
  * - `checkRefs` — every enforced FK the write sets must reference rows the
  *   caller can read on the target table (→ 403);
  * - WITH CHECK when the adapter cannot roll back — validated here, before
- *   the write (see {@link checkArbacWrite} for the transactional path).
+ *   the write (see {@link checkArbacWrite} for the transactional path);
+ * - WITH CHECK of an insert, even on a transactional adapter, evaluated on
+ *   the submitted rows before the write when the in-memory evaluator can
+ *   model it (a forbidden row → 403, never a duplicate-key 409; since
+ *   0.1.75) — and, with `ignoreConflicts` (`?$onConflict=ignore`), refused
+ *   whenever it cannot, since the post-write check never sees skipped rows.
  */
-declare function guardArbacWrite(ctx: TDbWriteGuardContext, scopes: readonly ArbacDbScope[], table: ArbacWriteTable, refs: RefTableSource): Promise<void>;
+declare function guardArbacWrite(ctx: TDbWriteGuardContext, scopes: readonly ArbacDbScope[], table: ArbacWriteTable, refs: RefTableSource, ignoreConflicts?: boolean): Promise<void>;
 /**
  * WITH CHECK after the write, inside its transaction: every written row must
  * match the scopes' `check` (default `filter`) — else 403 and the write rolls
@@ -753,11 +788,16 @@ interface ArbacDbScopeHelpers<T = unknown> {
    * enforcement the ARBAC DB controllers' CRUD writes get — nested writes
    * (`nestedWrites`, 403), USING (pre-image in scope, 404), `checkRefs` (403)
    * and WITH CHECK (403, rolled back). `allowedFields` / `set` are not applied
-   * — overlay {@link set} yourself.
+   * — overlay {@link set} yourself. For `insertMany(rows, { onConflict: "ignore" })`
+   * pass the same `{ onConflict: "ignore" }`: conflicting rows are skipped, so
+   * a check that cannot be evaluated before the write refuses the batch
+   * (since 0.1.75).
    *
    * @since 0.1.72
    */
-  writeOptions<Row extends object = Record<string, unknown>>(table: ArbacGuardedTable): TWriteOptions<Row>;
+  writeOptions<Row extends object = Record<string, unknown>>(table: ArbacGuardedTable, opts?: {
+    onConflict?: "ignore";
+  }): TWriteOptions<Row>;
   /**
    * `TDeleteOptions` for `table.deleteOne` in a handler: the id is pinned
    * among in-scope rows and the row must match the scope filter (else 404) —
@@ -848,4 +888,4 @@ declare class MoostArbac<TUserAttrs extends object, TScope extends object> exten
   getScopeFields(): TScopeFieldRules<TScope>;
 }
 //#endregion
-export { ARBAC_DELEGATED_AUTH, type AoothArbacClaims, Arbac, ArbacAction, ArbacAuthorize, ArbacDbScope, type ArbacDbScopeHelpers, ArbacDelegatedAuth, ArbacEvaluateOptions, type ArbacGuardedTable, type ArbacRelationResolution, ArbacResource, type ArbacScopedTable, ArbacUserProvider, ArbacUserProviderToken, type ArbacWriteTable, AsArbacDbController, AsArbacDbReadableController, AsArbacJsonValueHelpController, AsArbacValueHelpController, type ConjoinArbacDbScopesOptions, type ControlGate, type ControlsOf, type MetaVisibility, MoostArbac, type NavRelationKey, type NavTarget, type OwnFieldKey, type ProjectionOf, type RefForeignKey, type RefTableSource, type ScopeVisibilityOptions, type TArbacCompiledRule, type TArbacEvalResult, TArbacMeta, type TArbacRole, type TArbacRoleForResource, type TArbacRule, type VisibilityTableSource, applyAllowedFieldsAndSet, applyArbacControls, applyArbacMetaOverlay, applyArbacProjection, applyArbacRelationScopes, arbacActionRowScope, arbacAllowedActions, arbacAuthorizeInterceptor, arbacPatternToRegex, arbacRowFilter, authorizeArbacForm, buildScopeVisibility, cachedRequestScopes, checkArbacWrite, collectMethodNames, collectWithGrantNames, collectWritableFields, conjoinArbacDbScopes, enforceControlsPolicy, extractUsedControlValues, getArbacMate, getArbacScopes, guardArbacRemove, guardArbacWrite, isMetaFieldVisible, isScopedFieldVisible, metaAlwaysVisibleFields, prepareArbacRequest, pruneMetaByVisibility, registerArbacDbTarget, requestFieldVisible, requireRequestScopes, resolveHandlerArbacIds, resolveRequestScopes, unionScopeProjection, useArbac, useArbacDbScope };
+export { ARBAC_DELEGATED_AUTH, type AoothArbacClaims, Arbac, ArbacAction, ArbacAuthorize, ArbacDbScope, type ArbacDbScopeHelpers, ArbacDelegatedAuth, ArbacEvaluateOptions, type ArbacGuardedTable, type ArbacRelationResolution, ArbacResource, type ArbacScopedTable, ArbacUserProvider, ArbacUserProviderToken, type ArbacWriteTable, AsArbacDbController, AsArbacDbReadableController, AsArbacJsonValueHelpController, AsArbacValueHelpController, type ConjoinArbacDbScopesOptions, type ControlGate, type ControlsOf, type MetaVisibility, MoostArbac, type NavRelationKey, type NavTarget, type OwnFieldKey, type ProjectionOf, type RefForeignKey, type RefTableSource, type ScopeVisibilityOptions, type TArbacCompiledRule, type TArbacEvalResult, TArbacMeta, type TArbacRole, type TArbacRoleForResource, type TArbacRule, type VisibilityTableSource, applyAllowedFieldsAndSet, applyArbacControls, applyArbacMetaOverlay, applyArbacProjection, applyArbacRelationScopes, arbacActionRowScope, arbacAllowedActions, arbacAuthorizeInterceptor, arbacPatternToRegex, arbacRelationFilter, arbacRowFilter, authorizeArbacForm, buildScopeVisibility, cachedRequestScopes, checkArbacWrite, collectMethodNames, collectWithGrantNames, collectWritableFields, conjoinArbacDbScopes, conjoinScopeFilters, enforceControlsPolicy, extractUsedControlValues, getArbacMate, getArbacScopes, guardArbacRemove, guardArbacWrite, isMetaFieldVisible, isScopedFieldVisible, metaAlwaysVisibleFields, prepareArbacRequest, pruneMetaByVisibility, registerArbacDbTarget, requestFieldVisible, requireRequestScopes, resolveHandlerArbacIds, resolveRequestScopes, unionScopeProjection, useArbac, useArbacDbScope };