@aooth/arbac-moost 0.1.1

package/dist/index.mjs

@@ -0,0 +1,470 @@
+import { n as ArbacUserProviderToken, r as __decorate, t as ArbacUserProvider } from "./user.provider-CGWueNjx.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 { AsDbController, AsDbReadableController } from "@atscript/moost-db";
+//#region src/moost-arbac.ts
+let MoostArbac = class MoostArbac extends Arbac$1 {};
+MoostArbac = __decorate([Injectable()], MoostArbac);
+//#endregion
+//#region src/arbac.composables.ts
+/**
+* Writable slot holding the evaluated scopes for the current event.
+*
+* Module-level `key()` per the `@wooksjs/event-core` slot system. The
+* authorize interceptor calls `setScopes(...)` after a successful evaluate;
+* downstream `@ArbacScopes()` resolvers read it back from the same event context.
+*/
+const arbacScopesKey = key("arbac.scopes");
+/**
+* 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.
+*/
+const useArbac = (_ctx) => {
+	const ctx = _ctx ?? current();
+	const cc = useControllerContext(ctx);
+	const getScopes = () => ctx.has(arbacScopesKey) ? ctx.get(arbacScopesKey) : void 0;
+	const setScopes = (scope) => {
+		ctx.set(arbacScopesKey, scope);
+	};
+	const cMeta = cc.getControllerMeta();
+	const mMeta = cc.getMethodMeta();
+	const resource = mMeta?.arbacResourceId || cMeta?.arbacResourceId || cMeta?.id || getConstructor(cc.getController()).name;
+	const action = mMeta?.arbacActionId || mMeta?.atscript_db_action?.name || cMeta?.arbacActionId || mMeta?.id || (cc.getMethod() ?? "");
+	const isPublic = mMeta?.arbacPublic || cMeta?.arbacPublic || false;
+	const evaluate = async (opts) => {
+		const effectiveResource = opts?.resource || resource;
+		const effectiveAction = opts?.action || action;
+		if (!effectiveResource) throw new Error("useArbac().evaluate(): `resource` is required — could not be resolved from controller/method metadata. Pass it explicitly.");
+		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();
+		return {
+			...await arbac.evaluate({
+				resource: effectiveResource,
+				action: effectiveAction
+			}, {
+				id: userId,
+				roles: await user.getRoles(userId),
+				attrs: (id) => user.getAttrs(id)
+			}),
+			userId
+		};
+	};
+	const evaluateOrThrow = async (opts) => {
+		const result = await evaluate(opts);
+		if (!result.allowed) throw new HttpError(403, `Forbidden: ${opts?.resource || resource}/${opts?.action || action}`);
+		return {
+			...result,
+			allowed: true
+		};
+	};
+	return {
+		getScopes,
+		setScopes,
+		evaluate,
+		evaluateOrThrow,
+		resource,
+		action,
+		isPublic
+	};
+};
+//#endregion
+//#region src/arbac.mate.ts
+/**
+* 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`.
+*/
+function getArbacMate() {
+	return getMoostMate();
+}
+//#endregion
+//#region src/arbac.decorator.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).
+*/
+const arbacAuthorizeInterceptor = Object.assign(defineBeforeInterceptor(async () => {
+	const ctx = current();
+	const { setScopes, evaluate, resource, action, isPublic } = useArbac(ctx);
+	if (!action || !resource || isPublic) return;
+	const logger = useLogger("arbac", ctx);
+	try {
+		const { allowed, scopes, userId } = await evaluate();
+		logger.debug(`[${userId}] ${allowed ? "Authorized" : "Blocked"} "${resource}" : "${action}"`);
+		if (!allowed) throw new HttpError(403, `Insufficient privileges for action "${action}" on resource "${resource}"`);
+		setScopes(scopes);
+	} catch (error) {
+		if (error instanceof HttpError) throw error;
+		logger.warn(String(error));
+		throw new HttpError(401, error instanceof Error ? error.message : String(error));
+	}
+}, TInterceptorPriority.GUARD), { __authTransports: {} });
+/** Wrapped via `Authenticate` so `@moostjs/swagger` picks up the auth-guard metadata. */
+const ArbacAuthorize = () => Authenticate(arbacAuthorizeInterceptor);
+/**
+* Decorator to specify a resource id for ARBAC evaluation. Apply to a
+* controller class or a handler method.
+*/
+const ArbacResource = (name) => getArbacMate().decorate("arbacResourceId", name);
+/**
+* Decorator to specify an action id for ARBAC evaluation. Typically applied
+* at the method level.
+*/
+const ArbacAction = (name) => getArbacMate().decorate("arbacActionId", name);
+//#endregion
+//#region src/db/shared-read-helpers.ts
+/** Filter that matches no rows; used when ARBAC denies the request. */
+const DENY_FILTER = { $or: [] };
+/** Single point of access to the per-event scope cache. */
+function readCachedScopes() {
+	return useArbac().getScopes() ?? [];
+}
+/**
+* Full body of `transformFilter` for both ARBAC DB controllers: evaluate
+* ARBAC once, cache the scopes for the per-event hooks that follow
+* (`transformProjection`, `validateControls`), and merge the user filter
+* with the union of scope filters.
+*
+* Wraps the merge with `$and` (not object spread) so a top-level
+* `$or`/`$and`/`$not` in `filter` cannot drop the scope's sibling field
+* keys when @uniqu/core's `walkFilter` short-circuits on logical
+* operators (see BUG-2). Returns a match-nothing filter on denial so the
+* downstream pipeline returns an empty result set without leaking rows.
+*/
+async function transformArbacFilter(filter) {
+	const arbac = useArbac();
+	const { allowed, scopes } = await arbac.evaluate();
+	if (!allowed) return DENY_FILTER;
+	arbac.setScopes(scopes);
+	const scopeList = scopes ?? [];
+	const merged = scopeList.length > 0 ? mergeScopeFilters(scopeList.map((s) => s.filter ?? {})) : void 0;
+	const userFilter = filter && Object.keys(filter).length > 0 ? filter : void 0;
+	if (!merged) return userFilter ?? {};
+	if (!userFilter) return merged;
+	return { $and: [merged, userFilter] };
+}
+/**
+* Union the per-scope `projection` whitelists and restrict the user-supplied
+* projection to that union. Returns the original projection untouched when
+* no scope declares a projection (so caller sees the unrestricted shape).
+*/
+function applyArbacProjection(projection, scopes) {
+	if (scopes.length === 0) return projection;
+	const allowed = unionProjections(...scopes.map((s) => s.projection ?? {}));
+	if (Object.keys(allowed).length === 0) return projection;
+	return restrictProjection(projection ?? {}, allowed);
+}
+/**
+* Enforce the union of per-scope `controls` gates against the parsed
+* Uniquery controls. Throws `HttpError(403)` on the first violation.
+*/
+function applyArbacControls(controls, scopes) {
+	if (scopes.length === 0) return;
+	enforceControlsPolicy(unionControlsPolicy(scopes), controls);
+}
+/**
+* Walk the user-supplied `$with` items in `controls` and inject per-relation
+* filter/projection/controls/nested-$with from the role scopes' `with` field.
+*
+* Mutates `controls` in place (matches the `validateControls` contract).
+* Throws `HttpError(403)` if a per-relation control policy is violated
+* (delegates to `enforceControlsPolicy` like top-level `applyArbacControls`).
+*
+* Silence wins: if no role declares `with.<name>` for a relation, that entry
+* passes through unchanged. The outermost check skips the entire walk when no
+* scope declares `with` at all — this is the common case on every read.
+*/
+function applyArbacRelationScopes(controls, scopes) {
+	if (scopes.length === 0) return;
+	const withArr = controls.$with;
+	if (!Array.isArray(withArr) || withArr.length === 0) return;
+	if (!scopes.some((s) => s.with)) return;
+	for (const raw of withArr) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw;
+		if (typeof entry.name !== "string") continue;
+		const subScopes = collectSubScopes(scopes, entry.name);
+		if (subScopes.length === 0) continue;
+		const subFilter = mergeScopeFilters(subScopes.map((s) => s.filter ?? {}));
+		if (subFilter) {
+			const userFilter = entry.filter && Object.keys(entry.filter).length > 0 ? entry.filter : void 0;
+			entry.filter = userFilter ? { $and: [subFilter, userFilter] } : subFilter;
+		}
+		const entryControls = entry.controls ?? {};
+		const restricted = applyArbacProjection(normalizeSelect(entryControls.$select), subScopes);
+		if (restricted !== void 0) {
+			entryControls.$select = restricted;
+			entry.controls = entryControls;
+		}
+		enforceControlsPolicy(unionControlsPolicy(subScopes), entryControls);
+		applyArbacRelationScopes(entryControls, subScopes);
+	}
+}
+/** Pick `scopes[i].with?.[name]`, dropping undefined. */
+function collectSubScopes(scopes, name) {
+	const out = [];
+	for (const s of scopes) {
+		const sub = s.with?.[name];
+		if (sub) out.push(sub);
+	}
+	return out;
+}
+/**
+* `$select` may be an array of field names (uniquery inclusion list) or a
+* `TProjection` object. `applyArbacProjection` / `restrictProjection` operate
+* on the object form, so normalize the array to `{ field: 1 }` first. Returns
+* undefined if the input is empty (caller treats as "no projection set").
+*/
+function normalizeSelect(value) {
+	if (value === void 0 || value === null) return void 0;
+	if (Array.isArray(value)) {
+		const out = {};
+		for (const item of value) if (typeof item === "string") out[item] = 1;
+		return Object.keys(out).length > 0 ? out : void 0;
+	}
+	if (typeof value === "object") return value;
+}
+//#endregion
+//#region src/db/as-arbac-db-controller.ts
+let AsArbacDbController = class AsArbacDbController extends AsDbController {
+	transformFilter(filter) {
+		return transformArbacFilter(filter);
+	}
+	transformProjection(projection) {
+		return applyArbacProjection(projection, readCachedScopes());
+	}
+	/**
+	* 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.
+	*/
+	validateControls(controls, type) {
+		const baseErr = super.validateControls(controls, type);
+		if (baseErr) return baseErr;
+		const scopes = readCachedScopes();
+		applyArbacControls(controls, scopes);
+		applyArbacRelationScopes(controls, scopes);
+	}
+	async applyMetaOverlay(meta) {
+		const arbac = useArbac();
+		const actionToMethodMeta = collectActionMetaByName();
+		const crudKeys = Object.keys(meta.crud);
+		const [actionResults, crudResults] = await Promise.all([Promise.all(meta.actions.map((entry) => {
+			const methodMeta = actionToMethodMeta.get(entry.name);
+			const arbacAction = methodMeta?.arbacActionId ?? methodMeta?.id ?? entry.name;
+			return arbac.evaluate({ action: arbacAction });
+		})), Promise.all(crudKeys.map((key) => arbac.evaluate({ action: key })))]);
+		const filteredActions = [];
+		for (let i = 0; i < meta.actions.length; i++) if (actionResults[i].allowed) filteredActions.push(meta.actions[i]);
+		const filteredCrud = {};
+		for (let i = 0; i < crudKeys.length; i++) if (crudResults[i].allowed) filteredCrud[crudKeys[i]] = meta.crud[crudKeys[i]];
+		return {
+			...meta,
+			actions: filteredActions,
+			crud: filteredCrud
+		};
+	}
+	async onWrite(action, data) {
+		const scopes = readCachedScopes();
+		if (action !== "insert" && action !== "insertMany") await this.assertInScope(data, scopes);
+		return applyAllowedFieldsAndSet(data, scopes, this.identifierFields());
+	}
+	async onRemove(id) {
+		await this.assertInScope(id, readCachedScopes());
+		return id;
+	}
+	async assertInScope(idOrIds, scopes) {
+		const scopeFilter = mergeScopeFilters(scopes.map((s) => s.filter ?? {}));
+		if (!scopeFilter) return;
+		const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];
+		const idFilters = ids.map((id) => this.table.resolveIdFilter(id));
+		if (idFilters.some((f) => !f)) throw new HttpError(404, "Not found");
+		const idFilter = idFilters.length === 1 ? idFilters[0] : { $or: idFilters };
+		if (await this.table.count({ filter: { $and: [idFilter, scopeFilter] } }) < ids.length) throw new HttpError(404, "Not found");
+	}
+	identifierFields() {
+		const ctor = this.constructor;
+		const cached = identifierFieldsCache.get(ctor);
+		if (cached) return cached;
+		const out = /* @__PURE__ */ new Set();
+		for (const ident of this.table.identifications) for (const f of ident.fields) out.add(f);
+		const arr = [...out];
+		identifierFieldsCache.set(ctor, arr);
+		return arr;
+	}
+};
+AsArbacDbController = __decorate([Inherit()], AsArbacDbController);
+const identifierFieldsCache = /* @__PURE__ */ new WeakMap();
+const actionMetaByClassCache = /* @__PURE__ */ new WeakMap();
+function collectActionMetaByName() {
+	const cc = useControllerContext();
+	const instance = cc.getController();
+	const ctor = getConstructor(instance);
+	const cached = actionMetaByClassCache.get(ctor);
+	if (cached) return cached;
+	const map = /* @__PURE__ */ new Map();
+	const ctrlMeta = cc.getControllerMeta();
+	for (const entry of ctrlMeta?.atscript_db_actions ?? []) map.set(entry.name, {});
+	for (const methodName of getInstanceOwnMethods(instance)) {
+		if (typeof methodName !== "string") continue;
+		const m = cc.getMethodMeta(methodName);
+		if (!m) continue;
+		const actionMeta = m.atscript_db_action;
+		if (actionMeta?.name) map.set(actionMeta.name, {
+			arbacActionId: m.arbacActionId,
+			id: m.id
+		});
+	}
+	actionMetaByClassCache.set(ctor, map);
+	return map;
+}
+/**
+* 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).
+*/
+function enforceControlsPolicy(policy, controls) {
+	if (Object.keys(policy).length === 0) return;
+	for (const [key, gate] of Object.entries(policy)) {
+		const used = controls[key];
+		if (used === void 0 || used === null) continue;
+		if (Array.isArray(used) && used.length === 0) continue;
+		if (gate === false) throw new HttpError(403, `Control "${key}" is not allowed for your role`);
+		if (Array.isArray(gate)) {
+			const usedValues = extractUsedControlValues(key, used);
+			for (const v of usedValues) if (!gate.includes(v)) throw new HttpError(403, `Control "${key}=${v}" is not allowed for your role`);
+		}
+	}
+}
+/**
+* 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[]).
+*/
+function extractUsedControlValues(key, value) {
+	if (!Array.isArray(value)) return [];
+	if (key === "$with") {
+		const out = [];
+		for (const entry of value) if (typeof entry === "string") out.push(entry);
+		else if (typeof entry?.name === "string") out.push(entry.name);
+		return out;
+	}
+	if (key === "$groupBy") return value.filter((x) => typeof x === "string");
+	return [];
+}
+/**
+* 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.
+*/
+function applyAllowedFieldsAndSet(data, scopes, preserveFields = []) {
+	if (scopes.length === 0) return data;
+	const prepared = prepareScopeOverlay(scopes, preserveFields);
+	if (Array.isArray(data)) return data.map((row) => applyPreparedOverlay(row, prepared));
+	return applyPreparedOverlay(data, prepared);
+}
+function prepareScopeOverlay(scopes, preserveFields) {
+	let union = null;
+	for (const s of scopes) if (Array.isArray(s.allowedFields)) {
+		if (!union) union = /* @__PURE__ */ new Set();
+		for (const f of s.allowedFields) union.add(f);
+	}
+	if (union) for (const f of preserveFields) union.add(f);
+	let setOverrides = null;
+	for (const s of scopes) if (s.set) {
+		if (!setOverrides) setOverrides = {};
+		Object.assign(setOverrides, s.set);
+	}
+	return {
+		union,
+		setOverrides
+	};
+}
+function applyPreparedOverlay(data, prepared) {
+	if (Array.isArray(data)) return data.map((row) => applyPreparedOverlay(row, prepared));
+	if (!data || typeof data !== "object") return data;
+	const merged = { ...data };
+	if (prepared.union) {
+		for (const k of Object.keys(merged)) if (!prepared.union.has(k)) delete merged[k];
+	}
+	if (prepared.setOverrides) Object.assign(merged, prepared.setOverrides);
+	return merged;
+}
+//#endregion
+//#region src/db/as-arbac-db-readable-controller.ts
+let AsArbacDbReadableController = class AsArbacDbReadableController extends AsDbReadableController {
+	transformFilter(filter) {
+		return transformArbacFilter(filter);
+	}
+	transformProjection(projection) {
+		return applyArbacProjection(projection, readCachedScopes());
+	}
+	validateControls(controls, type) {
+		const baseErr = super.validateControls(controls, type);
+		if (baseErr) return baseErr;
+		const scopes = readCachedScopes();
+		applyArbacControls(controls, scopes);
+		applyArbacRelationScopes(controls, scopes);
+	}
+};
+AsArbacDbReadableController = __decorate([Inherit()], AsArbacDbReadableController);
+//#endregion
+export { Arbac, ArbacAction, ArbacAuthorize, ArbacResource, ArbacUserProvider, ArbacUserProviderToken, AsArbacDbController, AsArbacDbReadableController, MoostArbac, applyAllowedFieldsAndSet, arbacAuthorizeInterceptor, arbacPatternToRegex, enforceControlsPolicy, extractUsedControlValues, getArbacMate, useArbac };

package/dist/plugin.d.mts

@@ -0,0 +1,28 @@
+import { TAtscriptPlugin } from "@atscript/core";
+
+//#region src/plugin.d.ts
+/**
+ * Registers the `@arbac.*` annotation namespace for `@aooth/arbac-moost`:
+ *
+ * - `@arbac.role` — field is the source of role identifiers. Exactly one
+ *   field per type. Two valid shapes:
+ *     - inline `string | string[]` — values are read directly,
+ *     - `@db.rel.from` nav prop (1:N to a role table) — provider auto-injects
+ *       `controls.$with` and pulls role names off the joined records.
+ *   Multiple `@arbac.role` declarations throw at spec computation time.
+ * - `@arbac.attribute` — field becomes a user attribute keyed by its prop name.
+ *   Multiple `@arbac.attribute` fields are merged into the `UserAttrs` map.
+ * - `@arbac.userId` — overrides the user-id source. Resolution order is
+ *   (1) `@arbac.userId`, (2) the single field of the `@db.table.preferredId.uniqueIndex`
+ *   group, (3) `@meta.id` — first match wins.
+ *
+ * Install in `atscript.config.ts`:
+ *
+ * ```ts
+ * import arbacPlugin from '@aooth/arbac-moost/plugin'
+ * export default { plugins: [arbacPlugin()] }
+ * ```
+ */
+declare function arbacPlugin(): TAtscriptPlugin;
+//#endregion
+export { arbacPlugin as default };

package/dist/plugin.mjs

@@ -0,0 +1,50 @@
+import { AnnotationSpec } from "@atscript/core";
+//#region src/plugin.ts
+/**
+* Registers the `@arbac.*` annotation namespace for `@aooth/arbac-moost`:
+*
+* - `@arbac.role` — field is the source of role identifiers. Exactly one
+*   field per type. Two valid shapes:
+*     - inline `string | string[]` — values are read directly,
+*     - `@db.rel.from` nav prop (1:N to a role table) — provider auto-injects
+*       `controls.$with` and pulls role names off the joined records.
+*   Multiple `@arbac.role` declarations throw at spec computation time.
+* - `@arbac.attribute` — field becomes a user attribute keyed by its prop name.
+*   Multiple `@arbac.attribute` fields are merged into the `UserAttrs` map.
+* - `@arbac.userId` — overrides the user-id source. Resolution order is
+*   (1) `@arbac.userId`, (2) the single field of the `@db.table.preferredId.uniqueIndex`
+*   group, (3) `@meta.id` — first match wins.
+*
+* Install in `atscript.config.ts`:
+*
+* ```ts
+* import arbacPlugin from '@aooth/arbac-moost/plugin'
+* export default { plugins: [arbacPlugin()] }
+* ```
+*/
+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
+				})
+			} } };
+		}
+	};
+}
+//#endregion
+export { arbacPlugin as default };

package/dist/user-CFXfHtsb.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("username", defineAnnotatedType().designType("string").tags("string").annotate("db.index.unique", "username_idx", 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).$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

@@ -0,0 +1,31 @@
+//#region \0@oxc-project+runtime@0.129.0/helpers/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);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/user.provider.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.
+*/
+var ArbacUserProvider = class {};
+/**
+* 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.
+*/
+const ArbacUserProviderToken = ArbacUserProvider;
+//#endregion
+export { ArbacUserProviderToken as n, __decorate as r, ArbacUserProvider as t };

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

@@ -0,0 +1,42 @@
+import { TClassConstructor } from "moost";
+
+//#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>;
+}
+/**
+ * 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 { ArbacUserProviderToken as n, ArbacUserProvider as t };