@aooth/arbac-moost 0.1.7 → 0.1.9

package/dist/index.mjs

@@ -1,10 +1,102 @@
-import { n as ArbacUserProviderToken, r as __decorate, t as ArbacUserProvider } from "./user.provider-CGWueNjx.mjs";
+import { n as ArbacUserProviderToken, r as __decorate, t as ArbacUserProvider } from "./user.provider-BiM5P8fl.mjs";
 import { Arbac, Arbac as Arbac$1, arbacPatternToRegex } from "@aooth/arbac-core";
 import { Authenticate, HttpError } from "@moostjs/event-http";
 import { current, key } from "@wooksjs/event-core";
 import { Inherit, Injectable, TInterceptorPriority, defineBeforeInterceptor, getConstructor, getInstanceOwnMethods, getMoostMate, useControllerContext, useLogger } from "moost";
-import { mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections } from "@aooth/arbac";
+import { conjoinScopeFilters, intersectControlsPolicy, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections } from "@aooth/arbac";
 import { AsDbController, AsDbReadableController } from "@atscript/moost-db";
+//#region src/attenuation.ts
+/**
+* Conjoin the full-authority scopes (`userScopes`, the ceiling) and the
+* credential's narrowed scopes (`credScopes`) into ONE composite
+* `ArbacDbScope`. A row/field/control is admitted only if BOTH passes admit
+* it — the normative restrict-only clip that closes the attr-widen hole.
+*
+* Each side is first UNIONed with the existing additive helpers (today's
+* machinery), then the two RESULTS are CONJOINED with the dedicated combiners
+* ({@link conjoinScopeFilters} `$and`, {@link restrictProjection} field ∩,
+* {@link intersectControlsPolicy} deny-wins, `with` recursion) — never the
+* additive union helpers, which would silently widen.
+*
+* Returned as a single-element list so every downstream scope-application
+* site (which UNIONs the cached scope list per facet) sees the identity of a
+* one-element union — i.e. the conjunction — with no change to those sites.
+*/
+function conjoinArbacDbScopes(userScopes, credScopes) {
+	const filter = conjoinScopeFilters(mergeScopeFilters(userScopes.map((s) => s.filter ?? {})), mergeScopeFilters(credScopes.map((s) => s.filter ?? {})));
+	const projection = restrictProjection(unionProjections(...userScopes.map((s) => s.projection ?? {})), unionProjections(...credScopes.map((s) => s.projection ?? {})));
+	const controls = intersectControlsPolicy(unionControlsPolicy(userScopes), unionControlsPolicy(credScopes));
+	const allowedFields = intersectAllowedFields(userScopes, credScopes);
+	const set = combineSet(userScopes, credScopes);
+	const withMap = conjoinWith(userScopes, credScopes);
+	const s = {};
+	if (filter && Object.keys(filter).length > 0) s.filter = filter;
+	if (Object.keys(projection).length > 0) s.projection = projection;
+	if (Object.keys(controls).length > 0) s.controls = controls;
+	if (allowedFields) s.allowedFields = allowedFields;
+	if (set) s.set = set;
+	if (withMap) s.with = withMap;
+	return [s];
+}
+/**
+* Intersect the two sides' `allowedFields` write-whitelists (the credential
+* may write FEWER fields). A side with no whitelist is unrestricted (all
+* fields), so the other side wins; both restricting → set intersection.
+*/
+function intersectAllowedFields(userScopes, credScopes) {
+	const u = unionAllowedFields(userScopes);
+	const c = unionAllowedFields(credScopes);
+	if (u === void 0) return c;
+	if (c === void 0) return u;
+	const cset = new Set(c);
+	return [...new Set(u)].filter((f) => cset.has(f)).toSorted();
+}
+function unionAllowedFields(scopes) {
+	let set;
+	for (const s of scopes) if (Array.isArray(s.allowedFields)) {
+		set ??= /* @__PURE__ */ new Set();
+		for (const f of s.allowedFields) set.add(f);
+	}
+	return set ? [...set] : void 0;
+}
+/**
+* Combine the two sides' `set` overlays. `set` forces field values on writes;
+* both sides' forced constraints apply, and on a key conflict the USER's value
+* wins so the credential can only ADD constraints, never override the owner's.
+*/
+function combineSet(userScopes, credScopes) {
+	const u = unionSet(userScopes);
+	const c = unionSet(credScopes);
+	if (!u && !c) return void 0;
+	return {
+		...c,
+		...u
+	};
+}
+function unionSet(scopes) {
+	let out;
+	for (const s of scopes) if (s.set) {
+		out ??= {};
+		Object.assign(out, s.set);
+	}
+	return out;
+}
+/**
+* Recurse the conjunction into joined-resource sub-scopes. A relation declared
+* on only one side is conjoined against the other side's silence (unrestricted
+* = identity), so a credential can narrow a relation the user left open but
+* never widen one the user restricted.
+*/
+function conjoinWith(userScopes, credScopes) {
+	const relNames = /* @__PURE__ */ new Set();
+	for (const s of userScopes) if (s.with) for (const k of Object.keys(s.with)) relNames.add(k);
+	for (const s of credScopes) if (s.with) for (const k of Object.keys(s.with)) relNames.add(k);
+	if (relNames.size === 0) return void 0;
+	const out = {};
+	for (const rel of relNames) out[rel] = conjoinArbacDbScopes(userScopes.map((s) => s.with?.[rel]).filter(Boolean), credScopes.map((s) => s.with?.[rel]).filter(Boolean))[0];
+	return out;
+}
+//#endregion
 //#region src/moost-arbac.ts
 let MoostArbac = class MoostArbac extends Arbac$1 {};
 MoostArbac = __decorate([Injectable()], MoostArbac);
@@ -52,15 +144,28 @@ const useArbac = (_ctx) => {
 		if (!effectiveAction) throw new Error("useArbac().evaluate(): `action` is required — could not be resolved from controller/method metadata. Pass it explicitly.");
 		const [user, arbac] = await Promise.all([cc.instantiate(ArbacUserProviderToken), cc.instantiate(MoostArbac)]);
 		const userId = await user.getUserId();
+		const att = user.getAttenuation ? await user.getAttenuation() : void 0;
+		const attenuate = att && (att.roles !== void 0 || att.attrs !== void 0) ? {
+			roles: att.roles,
+			attrs: att.attrs
+		} : void 0;
+		const result = await arbac.evaluate({
+			resource: effectiveResource,
+			action: effectiveAction
+		}, {
+			id: userId,
+			roles: await user.getRoles(userId),
+			attrs: (id) => user.getAttrs(id),
+			attenuate
+		});
+		if (result.allowed && result.credScopes !== void 0) return {
+			allowed: true,
+			scopes: conjoinArbacDbScopes(result.scopes ?? [], result.credScopes),
+			userId
+		};
 		return {
-			...await arbac.evaluate({
-				resource: effectiveResource,
-				action: effectiveAction
-			}, {
-				id: userId,
-				roles: await user.getRoles(userId),
-				attrs: (id) => user.getAttrs(id)
-			}),
+			allowed: result.allowed,
+			scopes: result.scopes,
 			userId
 		};
 	};
@@ -516,4 +621,4 @@ let AsArbacDbReadableController = class AsArbacDbReadableController extends AsDb
 };
 AsArbacDbReadableController = __decorate([Inherit()], AsArbacDbReadableController);
 //#endregion
-export { Arbac, ArbacAction, ArbacAuthorize, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, MoostArbac, applyAllowedFieldsAndSet, arbacAuthorizeInterceptor, arbacPatternToRegex, enforceControlsPolicy, extractUsedControlValues, getArbacMate, useArbac };
+export { Arbac, ArbacAction, ArbacAuthorize, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, MoostArbac, applyAllowedFieldsAndSet, arbacAuthorizeInterceptor, arbacPatternToRegex, conjoinArbacDbScopes, enforceControlsPolicy, extractUsedControlValues, getArbacMate, useArbac };

package/dist/plugin.d.mts

@@ -16,6 +16,29 @@ import { TAtscriptPlugin } from "@atscript/core";
  *   (1) `@arbac.userId`, (2) the single field of the `@db.table.preferredId.uniqueIndex`
  *   group, (3) `@meta.id` — first match wins.
  *
+ * Credential-side (restrict-only attenuation — a credential authorizes for
+ * strictly LESS than its owning user; soundness is the engine's scope
+ * conjunction, these only mark WHERE the narrowing inputs live):
+ *
+ * - `@arbac.attenuate.role` — marks the ONE credential field holding the
+ *   assumed-role SUBSET (`string[]`). Intersected with the user's roles
+ *   (fail-closed: a claimed role the user lacks is dropped). Exactly one per
+ *   type — multiple declarations throw at boot.
+ * - `@arbac.attenuate.attr "userAttrName"` — marks a credential field whose
+ *   value narrows the named USER attribute. The string argument is the target
+ *   key in the user model's `@arbac.attribute` keyspace (validated to exist at
+ *   boot). Multiple fields may each carry it, targeting different attrs.
+ *
+ * This plugin also registers the `@aooth.user.*` identity-handle namespace
+ * (read by `getAoothUserHandleSpec`) so `.as` user models can mark their login
+ * handles name-agnostically:
+ *
+ * - `@aooth.user.email` — the field is the EMAIL login/recovery handle. Resolved
+ *   by annotation (not by being literally named `email`). MUST carry
+ *   `@db.index.unique` (unique-when-present); without it the handle is disabled
+ *   with a warning. At most one per type.
+ * - `@aooth.user.phone` — the PHONE login/recovery handle, same contract.
+ *
  * Install in `atscript.config.ts`:
  *
  * ```ts

package/dist/plugin.mjs

@@ -15,6 +15,29 @@ import { AnnotationSpec } from "@atscript/core";
 *   (1) `@arbac.userId`, (2) the single field of the `@db.table.preferredId.uniqueIndex`
 *   group, (3) `@meta.id` — first match wins.
 *
+* Credential-side (restrict-only attenuation — a credential authorizes for
+* strictly LESS than its owning user; soundness is the engine's scope
+* conjunction, these only mark WHERE the narrowing inputs live):
+*
+* - `@arbac.attenuate.role` — marks the ONE credential field holding the
+*   assumed-role SUBSET (`string[]`). Intersected with the user's roles
+*   (fail-closed: a claimed role the user lacks is dropped). Exactly one per
+*   type — multiple declarations throw at boot.
+* - `@arbac.attenuate.attr "userAttrName"` — marks a credential field whose
+*   value narrows the named USER attribute. The string argument is the target
+*   key in the user model's `@arbac.attribute` keyspace (validated to exist at
+*   boot). Multiple fields may each carry it, targeting different attrs.
+*
+* This plugin also registers the `@aooth.user.*` identity-handle namespace
+* (read by `getAoothUserHandleSpec`) so `.as` user models can mark their login
+* handles name-agnostically:
+*
+* - `@aooth.user.email` — the field is the EMAIL login/recovery handle. Resolved
+*   by annotation (not by being literally named `email`). MUST carry
+*   `@db.index.unique` (unique-when-present); without it the handle is disabled
+*   with a warning. At most one per type.
+* - `@aooth.user.phone` — the PHONE login/recovery handle, same contract.
+*
 * Install in `atscript.config.ts`:
 *
 * ```ts
@@ -26,23 +49,54 @@ function arbacPlugin() {
 	return {
 		name: "aoothjs-arbac",
 		config() {
-			return { annotations: { arbac: {
-				role: new AnnotationSpec({
-					description: "Marks this field as THE source of role identifiers for ARBAC evaluation. Two shapes are supported: inline (string | string[]) or @db.rel.from nav prop. Exactly one @arbac.role field per type — multiple declarations throw at boot.",
-					nodeType: ["prop"],
-					multiple: false
-				}),
-				attribute: new AnnotationSpec({
-					description: "Marks this field as a user attribute used by ARBAC scope evaluation. The field name becomes the attribute key. Multiple fields are merged.",
-					nodeType: ["prop"],
-					multiple: false
-				}),
-				userId: new AnnotationSpec({
-					description: "Overrides which field provides the user identifier for ARBAC. Resolution chain: @arbac.userId → @db.table.preferredId.uniqueIndex field → @meta.id.",
-					nodeType: ["prop"],
-					multiple: false
-				})
-			} } };
+			return { annotations: {
+				arbac: {
+					role: new AnnotationSpec({
+						description: "Marks this field as THE source of role identifiers for ARBAC evaluation. Two shapes are supported: inline (string | string[]) or @db.rel.from nav prop. Exactly one @arbac.role field per type — multiple declarations throw at boot.",
+						nodeType: ["prop"],
+						multiple: false
+					}),
+					attribute: new AnnotationSpec({
+						description: "Marks this field as a user attribute used by ARBAC scope evaluation. The field name becomes the attribute key. Multiple fields are merged.",
+						nodeType: ["prop"],
+						multiple: false
+					}),
+					userId: new AnnotationSpec({
+						description: "Overrides which field provides the user identifier for ARBAC. Resolution chain: @arbac.userId → @db.table.preferredId.uniqueIndex field → @meta.id.",
+						nodeType: ["prop"],
+						multiple: false
+					}),
+					attenuate: {
+						role: new AnnotationSpec({
+							description: "Marks the credential field holding the assumed-role SUBSET (string[]) for restrict-only ARBAC attenuation. Intersected with the user's roles (fail-closed). Exactly one @arbac.attenuate.role field per type — multiple declarations throw at boot.",
+							nodeType: ["prop"],
+							multiple: false
+						}),
+						attr: new AnnotationSpec({
+							description: "Marks a credential field whose value narrows the named USER attribute for restrict-only ARBAC attenuation. The argument is the target key in the user model's @arbac.attribute keyspace (validated to exist at boot). Multiple fields may each carry it, targeting different attrs.",
+							nodeType: ["prop"],
+							multiple: false,
+							argument: {
+								name: "userAttr",
+								type: "string",
+								description: "Target user-attribute key (a field annotated @arbac.attribute on the user model)."
+							}
+						})
+					}
+				},
+				aooth: { user: {
+					email: new AnnotationSpec({
+						description: "Marks this field as the EMAIL login/recovery handle. The framework resolves the field by this annotation (name-agnostic) for findByHandle / recovery / signup. The field MUST carry @db.index.unique (unique-when-present) — a handle must resolve to at most one row; without a unique index the email handle is DISABLED with a warning. At most one @aooth.user.email field per type — multiple declarations throw at boot.",
+						nodeType: ["prop"],
+						multiple: false
+					}),
+					phone: new AnnotationSpec({
+						description: "Marks this field as the PHONE login/recovery handle. Same resolution + unique-index contract as @aooth.user.email (disabled with a warning when the field lacks @db.index.unique). At most one @aooth.user.phone field per type — multiple throw at boot.",
+						nodeType: ["prop"],
+						multiple: false
+					})
+				} }
+			} };
 		}
 	};
 }

package/dist/user-Dzu_08g0.mjs

@@ -0,0 +1,15 @@
+import { defineAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
+import "@aooth/user/atscript-db/model.as";
+//#region src/atscript/models/user.as
+var AoothArbacUserCredentials = class {
+	static __is_atscript_annotated_type = true;
+	static type = {};
+	static metadata = /* @__PURE__ */ new Map();
+	static id = "AoothArbacUserCredentials";
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+defineAnnotatedType("object", AoothArbacUserCredentials).prop("id", defineAnnotatedType().designType("string").tags("string").annotate("meta.id", true).annotate("db.default.uuid", true).$type).prop("username", defineAnnotatedType().designType("string").tags("string").annotate("db.index.unique", "username_idx", true).$type).prop("version", defineAnnotatedType().designType("number").tags("int", "number").annotate("db.column.version", true).annotate("expect.int", true).$type).prop("password", defineAnnotatedType("object").prop("hash", defineAnnotatedType().designType("string").tags("string").$type).prop("history", defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).prop("lastChanged", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("isInitial", defineAnnotatedType().designType("boolean").tags("boolean").$type).annotate("db.patch.strategy", "merge").$type).prop("account", defineAnnotatedType("object").prop("active", defineAnnotatedType().designType("boolean").tags("boolean").$type).prop("locked", defineAnnotatedType().designType("boolean").tags("boolean").$type).prop("lockReason", defineAnnotatedType().designType("string").tags("string").$type).prop("lockEnds", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("failedLoginAttempts", defineAnnotatedType().designType("number").tags("number").$type).prop("lastLogin", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("pendingInvitation", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).annotate("db.patch.strategy", "merge").$type).prop("mfa", defineAnnotatedType("object").prop("methods", defineAnnotatedType("array").of(defineAnnotatedType("object").prop("name", defineAnnotatedType().designType("string").tags("string").$type).prop("confirmed", defineAnnotatedType().designType("boolean").tags("boolean").$type).prop("value", defineAnnotatedType().designType("string").tags("string").$type).prop("lastUsedWindow", defineAnnotatedType().designType("number").tags("int", "number").annotate("expect.int", true).optional().$type).$type).$type).prop("defaultMethod", defineAnnotatedType().designType("string").tags("string").$type).prop("autoSend", defineAnnotatedType().designType("boolean").tags("boolean").$type).annotate("db.patch.strategy", "merge").$type).prop("trustedDevices", defineAnnotatedType("array").of(defineAnnotatedType("object").prop("token", defineAnnotatedType().designType("string").tags("string").$type).prop("ip", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("issuedAt", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("expiresAt", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("name", defineAnnotatedType().designType("string").tags("string").optional().$type).$type).annotate("db.patch.strategy", "merge").optional().$type).prop("roles", defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).annotate("arbac.role", true).$type);
+//#endregion
+export { AoothArbacUserCredentials as t };

package/dist/{user.provider-CGWueNjx.mjs → user.provider-BiM5P8fl.mjs}

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.129.0/helpers/decorate.js
+//#region \0@oxc-project+runtime@0.133.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/user.provider-CKPMp3G8.d.mts

@@ -0,0 +1,314 @@
+import { TClassConstructor } from "moost";
+import { ControlGate, TProjection, TScopeFilter } from "@aooth/arbac";
+import { AsDbController } from "@atscript/moost-db";
+import { NavPropsOf, OwnPropsOf, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { TMetaResponse } from "@atscript/db";
+
+//#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> : {
+  $with?: Array<NavRelationKey<T>> | boolean;
+  $select?: Array<OwnFieldKey<T>> | boolean;
+  $groupBy?: ControlGate;
+  $having?: ControlGate;
+  [key: `$${string}`]: ControlGate | 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>;
+  /**
+   * Translate `@uniqu/url` parser failures into HTTP 400 instead of letting them
+   * bubble as 500. The base `parseQueryString` calls `parseUrl()` directly with
+   * no try/catch, so a malformed `?status=...` (e.g. unquoted single quote at a
+   * non-string position) surfaces as a server error — misleading, since the
+   * server is fine and the client sent bad input.
+   *
+   * Narrow targeting: only `SyntaxError` raised from inside the parser is
+   * remapped. Other errors (e.g. a programmer-introduced TypeError in a future
+   * override) still bubble as 500. SQL-injection-shaped payloads remain safely
+   * handled either way — see SEC-17 for the parameterisation invariant; this
+   * override is an orthogonal robustness pin around the parse step.
+   */
+  protected parseQueryString(url: string): ReturnType<AsDbController<T>["parseQueryString"]>;
+  /**
+   * Same parser-error → 400 remap as {@link parseQueryString}, applied to the
+   * `/one` and `/one?…` code paths which use `parseControlsOnlyFromUrl`.
+   */
+  protected parseControlsOnlyFromUrl(url: string): ReturnType<AsDbController<T>["parseControlsOnlyFromUrl"]>;
+  /**
+   * 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>, 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/attenuation.d.ts
+/**
+ * The restrict-only ARBAC attenuation carried by a credential — its assumed
+ * role SUBSET and narrowing attribute overrides. Sourced into evaluation via
+ * the optional `ArbacUserProvider.getAttenuation()` hook (typically built by
+ * walking the credential model's `@arbac.attenuate.*`-annotated typed root
+ * fields with {@link extractAttenuation}), it NARROWS (never expands) the
+ * principal — see the engine's `evaluate({ attenuate })` for the restrict-only
+ * outcome-intersection.
+ *
+ * - `roles` — assume a SUBSET of the user's roles. `[]` = no roles (deny-all,
+ *   fail-closed); an OMITTED key = keep all the user's roles (attrs-only
+ *   narrowing); a role the user lacks is dropped by the intersection.
+ * - `attrs` — extra/overriding inputs to scope predicates, keyed by the target
+ *   user-attribute name, intended to narrow scopes. They are merged LOCALLY
+ *   into the credential pass only and clipped by the scope conjunction, so they
+ *   can never widen beyond the user.
+ */
+interface AoothArbacClaims {
+  roles?: string[];
+  attrs?: Record<string, unknown>;
+}
+/**
+ * Conjoin the full-authority scopes (`userScopes`, the ceiling) and the
+ * credential's narrowed scopes (`credScopes`) into ONE composite
+ * `ArbacDbScope`. A row/field/control is admitted only if BOTH passes admit
+ * it — the normative restrict-only clip that closes the attr-widen hole.
+ *
+ * Each side is first UNIONed with the existing additive helpers (today's
+ * machinery), then the two RESULTS are CONJOINED with the dedicated combiners
+ * ({@link conjoinScopeFilters} `$and`, {@link restrictProjection} field ∩,
+ * {@link intersectControlsPolicy} deny-wins, `with` recursion) — never the
+ * additive union helpers, which would silently widen.
+ *
+ * Returned as a single-element list so every downstream scope-application
+ * site (which UNIONs the cached scope list per facet) sees the identity of a
+ * one-element union — i.e. the conjunction — with no change to those sites.
+ */
+declare function conjoinArbacDbScopes(userScopes: ArbacDbScope[], credScopes: ArbacDbScope[]): ArbacDbScope[];
+//#endregion
+//#region src/user.provider.d.ts
+/**
+ * Abstract base class for providing user data required for ARBAC evaluations.
+ *
+ * Consumers must extend this class and implement the three abstract methods
+ * to plug their own authentication/identity layer into the ARBAC authorize
+ * interceptor. The subclass must re-apply `@Injectable()` (moost does not
+ * inherit decorator metadata) and be registered via Moost's
+ * `setReplaceRegistry` (or `@Replace`) so DI resolves the concrete provider.
+ *
+ * @template TUserAttrs - The type representing user attributes relevant to access control.
+ */
+declare abstract class ArbacUserProvider<TUserAttrs extends object = object> {
+  /**
+   * Retrieves the unique identifier of the current user.
+   */
+  abstract getUserId(): string | Promise<string>;
+  /**
+   * Retrieves the roles assigned to a user based on their ID.
+   *
+   * @param id - The user ID.
+   */
+  abstract getRoles(id: string): string[] | Promise<string[]>;
+  /**
+   * Retrieves the attributes associated with a user based on their ID.
+   *
+   * @param id - The user ID.
+   */
+  abstract getAttrs(id: string): TUserAttrs | Promise<TUserAttrs>;
+  /**
+   * OPTIONAL: source the credential's restrict-only ARBAC attenuation for the
+   * current request. When it returns claims, `useArbac().evaluate()` runs the
+   * engine's dual-pass outcome-intersection so the credential can do/see/affect
+   * strictly LESS than its owning user; returning `undefined` (the default —
+   * this method is unimplemented on the base/atscript providers) means "no
+   * narrowing", i.e. the credential authorizes with the user's full authority.
+   *
+   * `arbac-moost` is auth-agnostic, so the base class does NOT read the auth
+   * layer. A consumer wires it up by overriding this to read the credential's
+   * typed root fields and return their attenuation — typically
+   * `extractAttenuation(CredentialModel, useAuth().getAuthContext())`, which
+   * walks the model's `@arbac.attenuate.*`-annotated fields (from
+   * `@aooth/arbac-moost/atscript`). The restrict-only intersection happens in
+   * the engine regardless, so an app cannot get the safety wrong here.
+   */
+  getAttenuation?(): AoothArbacClaims | undefined | Promise<AoothArbacClaims | undefined>;
+}
+/**
+ * DI token form of {@link ArbacUserProvider}. The class itself is `abstract`,
+ * so it does not satisfy moost's `TClassConstructor` (`new (...) => T`)
+ * structurally; this re-typed alias is the supported way to pass the base
+ * class to `cc.instantiate(...)`, `createReplaceRegistry(...)`, `@Replace(...)`,
+ * etc. Runtime resolves to the concrete subclass registered via DI.
+ */
+declare const ArbacUserProviderToken: TClassConstructor<ArbacUserProvider>;
+//#endregion
+export { ArbacDbScope as a, enforceControlsPolicy as c, NavRelationKey as d, NavTarget as f, conjoinArbacDbScopes as i, extractUsedControlValues as l, ProjectionOf as m, ArbacUserProviderToken as n, AsArbacDbController as o, OwnFieldKey as p, AoothArbacClaims as r, applyAllowedFieldsAndSet as s, ArbacUserProvider as t, ControlsOf as u };