@atscript/moost-db 0.1.56 → 0.1.57

package/dist/index.cjs

@@ -473,13 +473,6 @@ let AsReadableController = class AsReadableController {
 			}
 		};
 	}
-	/**
-	* Whether this controller is read-only (no write endpoints).
-	* Returns `true` by default; {@link AsDbController} overrides to `false`.
-	*/
-	_isReadOnly() {
-		return true;
-	}
 	_queryControlsValidator;
 	_pagesControlsValidator;
 	_getOneControlsValidator;
@@ -539,37 +532,31 @@ let AsReadableController = class AsReadableController {
 		return item;
 	}
 	/**
-	* **GET /meta** — returns the bound interface's metadata envelope.
-	*
-	* Base implementation delegates to {@link buildMetaResponse}, which subclasses
-	* override to add source-specific fields (relations, searchable flags, etc.).
-	* The response is cached on the instance; async overrides must cache any
-	* extra enrichment themselves.
+	* **GET /meta** — returns the bound interface's metadata envelope. The
+	* static envelope is cached; {@link applyMetaOverlay} runs per request so
+	* subclasses can prune the response by principal.
 	*/
 	async meta() {
-		if (this._metaResponse) return this._metaResponse;
-		const response = await this.buildMetaResponse();
-		this._metaResponse = response;
-		return response;
+		if (!this._metaResponse) this._metaResponse = this.buildMetaResponse();
+		return this.applyMetaOverlay(this._metaResponse);
 	}
 	/**
 	* Builds the `/meta` payload. Override in subclasses to populate source-specific
-	* fields. Defaults return a minimal envelope with the serialized type and the
-	* read-only flag; value-help dicts populate their capability hints here.
-	* Subclasses that fully replace the envelope must call {@link buildActions}
-	* directly so `@DbAction*` decorators still surface.
+	* fields. Subclasses that fully replace the envelope must call
+	* {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
+	* decorators and CRUD permissions still surface.
 	*/
-	async buildMetaResponse() {
+	buildMetaResponse() {
 		return {
 			searchable: false,
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: [],
-			readOnly: this._isReadOnly(),
 			relations: [],
 			fields: {},
 			type: this.getSerializedType(),
-			actions: this.buildActions()
+			actions: this.buildActions(),
+			crud: this.buildCrud()
 		};
 	}
 	/**
@@ -580,6 +567,25 @@ let AsReadableController = class AsReadableController {
 	buildActions() {
 		return discoverActions(this.constructor, this.app, this.logger);
 	}
+	/**
+	* Declares the built-in CRUD operations this controller exposes. Subclasses
+	* override to add their keys; the bare base only exposes `/meta`. See
+	* `docs/http/permissions.md` for the wire shape and overlay rules.
+	*/
+	buildCrud() {
+		return {};
+	}
+	/**
+	* Per-request overlay applied to the cached `/meta` envelope. Default no-op.
+	* Subclasses may shallow-clone and prune `crud` keys, `crud[op]` arrays, or
+	* `actions[]` based on the current request principal (read via Moost
+	* composables). The cached envelope MUST NOT be mutated — see
+	* `docs/http/permissions.md` for the full contract, including the
+	* "discoverability only" caveat.
+	*/
+	applyMetaOverlay(meta) {
+		return meta;
+	}
 };
 __decorate([
 	(0, _moostjs_event_http.Get)("meta"),
@@ -658,6 +664,23 @@ const ReadableController = (readable, prefix) => {
 */
 const ViewController = ReadableController;
 //#endregion
+//#region src/permissions/crud-controls.ts
+/**
+* Static control whitelists per read op. Each list is the matching DTO's
+* `$`-properties (stripped) plus the URL-grammar extras (`filter`,
+* `insights`, `groupBy`) that bypass the DTO. The DTO is the single source of
+* truth — adding a `$control` there auto-extends the whitelist here.
+*/
+const dtoControls = (Dto) => [...Dto.type.props.keys()].map((k) => k.startsWith("$") ? k.slice(1) : k);
+const QUERY_CONTROLS = [
+	"filter",
+	"insights",
+	...dtoControls(QueryControlsDto),
+	"groupBy"
+];
+const PAGES_CONTROLS = ["filter", ...dtoControls(PagesControlsDto)];
+const ONE_CONTROLS = dtoControls(GetOneControlsDto);
+//#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
@@ -907,7 +930,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* vector-searchable flags, field-descriptor-derived filter/sort hints, and
 	* the configured primary keys.
 	*/
-	async buildMetaResponse() {
+	buildMetaResponse() {
 		const relations = [];
 		for (const [name, rel] of this.readable.relations) relations.push({
 			name,
@@ -932,11 +955,19 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			vectorSearchable: this.readable.isVectorSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
 			primaryKeys: [...this.readable.primaryKeys],
-			readOnly: this._isReadOnly(),
 			relations,
 			fields,
 			type: this.getSerializedType(),
-			actions: this.buildActions()
+			actions: this.buildActions(),
+			crud: this.buildCrud()
+		};
+	}
+	buildCrud() {
+		return {
+			...super.buildCrud(),
+			query: [...QUERY_CONTROLS],
+			pages: [...PAGES_CONTROLS],
+			one: [...ONE_CONTROLS]
 		};
 	}
 };
@@ -986,8 +1017,14 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 	constructor(table, app) {
 		super(table, app);
 	}
-	_isReadOnly() {
-		return false;
+	buildCrud() {
+		return {
+			...super.buildCrud(),
+			insert: [],
+			update: [],
+			replace: [],
+			remove: []
+		};
 	}
 	/**
 	* Intercepts write operations. Return `undefined` to abort.
@@ -1204,7 +1241,7 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 	* client picker UI (which controls to render); the server does not enforce
 	* these flags at request time.
 	*/
-	async buildMetaResponse() {
+	buildMetaResponse() {
 		const fields = {};
 		for (const [path, meta] of this.fieldMeta) fields[path] = {
 			sortable: meta.has("ui.dict.sortable"),
@@ -1215,16 +1252,24 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: this.primaryKey ? [this.primaryKey] : [],
-			readOnly: this._isReadOnly(),
 			relations: [],
 			fields,
 			type: this.getSerializedType(),
-			actions: []
+			actions: [],
+			crud: this.buildCrud()
 		};
 	}
 	buildActions() {
 		return [];
 	}
+	buildCrud() {
+		return {
+			...super.buildCrud(),
+			query: [...QUERY_CONTROLS],
+			pages: [...PAGES_CONTROLS],
+			one: [...ONE_CONTROLS]
+		};
+	}
 };
 __decorate([
 	(0, _moostjs_event_http.Get)("query"),
@@ -1705,6 +1750,9 @@ exports.DbActions = DbActions;
 exports.DbRowActions = DbRowActions;
 exports.DbRowsActions = DbRowsActions;
 exports.DbTableActions = DbTableActions;
+exports.ONE_CONTROLS = ONE_CONTROLS;
+exports.PAGES_CONTROLS = PAGES_CONTROLS;
+exports.QUERY_CONTROLS = QUERY_CONTROLS;
 exports.READABLE_DEF = READABLE_DEF;
 exports.ReadableController = ReadableController;
 exports.TABLE_DEF = TABLE_DEF;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as _atscript_typescript_utils0 from "@atscript/typescript/utils";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, Validator } from "@atscript/typescript/utils";
 import * as _uniqu_url0 from "@uniqu/url";
-import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
@@ -88,11 +88,6 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * to customise.
    */
   protected getSerializeOptions(): TSerializeOptions;
-  /**
-   * Whether this controller is read-only (no write endpoints).
-   * Returns `true` by default; {@link AsDbController} overrides to `false`.
-   */
-  protected _isReadOnly(): boolean;
   private _queryControlsValidator?;
   private _pagesControlsValidator?;
   private _getOneControlsValidator?;
@@ -111,28 +106,39 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
-   * **GET /meta** — returns the bound interface's metadata envelope.
-   *
-   * Base implementation delegates to {@link buildMetaResponse}, which subclasses
-   * override to add source-specific fields (relations, searchable flags, etc.).
-   * The response is cached on the instance; async overrides must cache any
-   * extra enrichment themselves.
+   * **GET /meta** — returns the bound interface's metadata envelope. The
+   * static envelope is cached; {@link applyMetaOverlay} runs per request so
+   * subclasses can prune the response by principal.
    */
   meta(): Promise<TMetaResponse>;
   /**
    * Builds the `/meta` payload. Override in subclasses to populate source-specific
-   * fields. Defaults return a minimal envelope with the serialized type and the
-   * read-only flag; value-help dicts populate their capability hints here.
-   * Subclasses that fully replace the envelope must call {@link buildActions}
-   * directly so `@DbAction*` decorators still surface.
+   * fields. Subclasses that fully replace the envelope must call
+   * {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
+   * decorators and CRUD permissions still surface.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
   /**
    * Discovers `@DbAction*` and `@DbActions`-style class metadata on this
    * controller and produces the `actions` array. Returns `[]` for value-help
    * controllers — see {@link AsValueHelpController#buildMetaResponse}.
    */
   protected buildActions(): TDbActionInfo$1[];
+  /**
+   * Declares the built-in CRUD operations this controller exposes. Subclasses
+   * override to add their keys; the bare base only exposes `/meta`. See
+   * `docs/http/permissions.md` for the wire shape and overlay rules.
+   */
+  protected buildCrud(): TCrudPermissions$1;
+  /**
+   * Per-request overlay applied to the cached `/meta` envelope. Default no-op.
+   * Subclasses may shallow-clone and prune `crud` keys, `crud[op]` arrays, or
+   * `actions[]` based on the current request principal (read via Moost
+   * composables). The cached envelope MUST NOT be mutated — see
+   * `docs/http/permissions.md` for the full contract, including the
+   * "discoverability only" caveat.
+   */
+  protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -204,7 +210,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * vector-searchable flags, field-descriptor-derived filter/sort hints, and
    * the configured primary keys.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
+  protected buildCrud(): TCrudPermissions$1;
 }
 //#endregion
 //#region src/as-db.controller.d.ts
@@ -222,7 +229,7 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   /** Reference to the underlying table (typed for write access). */
   protected get table(): AtscriptDbTable<T>;
   constructor(table: AtscriptDbTable<T>, app: Moost);
-  protected _isReadOnly(): boolean;
+  protected buildCrud(): TCrudPermissions$1;
   /**
    * Intercepts write operations. Return `undefined` to abort.
    * May be async (e.g. to enrich payloads from session / permissions).
@@ -344,8 +351,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    * client picker UI (which controls to render); the server does not enforce
    * these flags at request time.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
   protected buildActions(): never[];
+  protected buildCrud(): TCrudPermissions$1;
 }
 //#endregion
 //#region src/as-json-value-help.controller.d.ts
@@ -599,4 +607,9 @@ interface PkValidationSource {
   fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, PkValidationSource, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, TDbActionsEntry, TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, validationErrorTransform };
+//#region src/permissions/crud-controls.d.ts
+declare const QUERY_CONTROLS: readonly string[];
+declare const PAGES_CONTROLS: readonly string[];
+declare const ONE_CONTROLS: readonly string[];
+//#endregion
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, PkValidationSource, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, TDbActionsEntry, TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, validationErrorTransform };

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
 import * as _uniqu_url0 from "@uniqu/url";
-import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
 
 //#region src/as-readable.controller.d.ts
 /**
@@ -88,11 +88,6 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * to customise.
    */
   protected getSerializeOptions(): TSerializeOptions;
-  /**
-   * Whether this controller is read-only (no write endpoints).
-   * Returns `true` by default; {@link AsDbController} overrides to `false`.
-   */
-  protected _isReadOnly(): boolean;
   private _queryControlsValidator?;
   private _pagesControlsValidator?;
   private _getOneControlsValidator?;
@@ -111,28 +106,39 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
-   * **GET /meta** — returns the bound interface's metadata envelope.
-   *
-   * Base implementation delegates to {@link buildMetaResponse}, which subclasses
-   * override to add source-specific fields (relations, searchable flags, etc.).
-   * The response is cached on the instance; async overrides must cache any
-   * extra enrichment themselves.
+   * **GET /meta** — returns the bound interface's metadata envelope. The
+   * static envelope is cached; {@link applyMetaOverlay} runs per request so
+   * subclasses can prune the response by principal.
    */
   meta(): Promise<TMetaResponse>;
   /**
    * Builds the `/meta` payload. Override in subclasses to populate source-specific
-   * fields. Defaults return a minimal envelope with the serialized type and the
-   * read-only flag; value-help dicts populate their capability hints here.
-   * Subclasses that fully replace the envelope must call {@link buildActions}
-   * directly so `@DbAction*` decorators still surface.
+   * fields. Subclasses that fully replace the envelope must call
+   * {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
+   * decorators and CRUD permissions still surface.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
   /**
    * Discovers `@DbAction*` and `@DbActions`-style class metadata on this
    * controller and produces the `actions` array. Returns `[]` for value-help
    * controllers — see {@link AsValueHelpController#buildMetaResponse}.
    */
   protected buildActions(): TDbActionInfo$1[];
+  /**
+   * Declares the built-in CRUD operations this controller exposes. Subclasses
+   * override to add their keys; the bare base only exposes `/meta`. See
+   * `docs/http/permissions.md` for the wire shape and overlay rules.
+   */
+  protected buildCrud(): TCrudPermissions$1;
+  /**
+   * Per-request overlay applied to the cached `/meta` envelope. Default no-op.
+   * Subclasses may shallow-clone and prune `crud` keys, `crud[op]` arrays, or
+   * `actions[]` based on the current request principal (read via Moost
+   * composables). The cached envelope MUST NOT be mutated — see
+   * `docs/http/permissions.md` for the full contract, including the
+   * "discoverability only" caveat.
+   */
+  protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -204,7 +210,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * vector-searchable flags, field-descriptor-derived filter/sort hints, and
    * the configured primary keys.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
+  protected buildCrud(): TCrudPermissions$1;
 }
 //#endregion
 //#region src/as-db.controller.d.ts
@@ -222,7 +229,7 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   /** Reference to the underlying table (typed for write access). */
   protected get table(): AtscriptDbTable<T>;
   constructor(table: AtscriptDbTable<T>, app: Moost);
-  protected _isReadOnly(): boolean;
+  protected buildCrud(): TCrudPermissions$1;
   /**
    * Intercepts write operations. Return `undefined` to abort.
    * May be async (e.g. to enrich payloads from session / permissions).
@@ -344,8 +351,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    * client picker UI (which controls to render); the server does not enforce
    * these flags at request time.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
   protected buildActions(): never[];
+  protected buildCrud(): TCrudPermissions$1;
 }
 //#endregion
 //#region src/as-json-value-help.controller.d.ts
@@ -599,4 +607,9 @@ interface PkValidationSource {
   fieldDescriptors: readonly TDbFieldMeta[];
 }
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, type PkValidationSource, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, validationErrorTransform };
+//#region src/permissions/crud-controls.d.ts
+declare const QUERY_CONTROLS: readonly string[];
+declare const PAGES_CONTROLS: readonly string[];
+declare const ONE_CONTROLS: readonly string[];
+//#endregion
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, type PkValidationSource, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, validationErrorTransform };

package/dist/index.mjs

@@ -472,13 +472,6 @@ let AsReadableController = class AsReadableController {
 			}
 		};
 	}
-	/**
-	* Whether this controller is read-only (no write endpoints).
-	* Returns `true` by default; {@link AsDbController} overrides to `false`.
-	*/
-	_isReadOnly() {
-		return true;
-	}
 	_queryControlsValidator;
 	_pagesControlsValidator;
 	_getOneControlsValidator;
@@ -538,37 +531,31 @@ let AsReadableController = class AsReadableController {
 		return item;
 	}
 	/**
-	* **GET /meta** — returns the bound interface's metadata envelope.
-	*
-	* Base implementation delegates to {@link buildMetaResponse}, which subclasses
-	* override to add source-specific fields (relations, searchable flags, etc.).
-	* The response is cached on the instance; async overrides must cache any
-	* extra enrichment themselves.
+	* **GET /meta** — returns the bound interface's metadata envelope. The
+	* static envelope is cached; {@link applyMetaOverlay} runs per request so
+	* subclasses can prune the response by principal.
 	*/
 	async meta() {
-		if (this._metaResponse) return this._metaResponse;
-		const response = await this.buildMetaResponse();
-		this._metaResponse = response;
-		return response;
+		if (!this._metaResponse) this._metaResponse = this.buildMetaResponse();
+		return this.applyMetaOverlay(this._metaResponse);
 	}
 	/**
 	* Builds the `/meta` payload. Override in subclasses to populate source-specific
-	* fields. Defaults return a minimal envelope with the serialized type and the
-	* read-only flag; value-help dicts populate their capability hints here.
-	* Subclasses that fully replace the envelope must call {@link buildActions}
-	* directly so `@DbAction*` decorators still surface.
+	* fields. Subclasses that fully replace the envelope must call
+	* {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
+	* decorators and CRUD permissions still surface.
 	*/
-	async buildMetaResponse() {
+	buildMetaResponse() {
 		return {
 			searchable: false,
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: [],
-			readOnly: this._isReadOnly(),
 			relations: [],
 			fields: {},
 			type: this.getSerializedType(),
-			actions: this.buildActions()
+			actions: this.buildActions(),
+			crud: this.buildCrud()
 		};
 	}
 	/**
@@ -579,6 +566,25 @@ let AsReadableController = class AsReadableController {
 	buildActions() {
 		return discoverActions(this.constructor, this.app, this.logger);
 	}
+	/**
+	* Declares the built-in CRUD operations this controller exposes. Subclasses
+	* override to add their keys; the bare base only exposes `/meta`. See
+	* `docs/http/permissions.md` for the wire shape and overlay rules.
+	*/
+	buildCrud() {
+		return {};
+	}
+	/**
+	* Per-request overlay applied to the cached `/meta` envelope. Default no-op.
+	* Subclasses may shallow-clone and prune `crud` keys, `crud[op]` arrays, or
+	* `actions[]` based on the current request principal (read via Moost
+	* composables). The cached envelope MUST NOT be mutated — see
+	* `docs/http/permissions.md` for the full contract, including the
+	* "discoverability only" caveat.
+	*/
+	applyMetaOverlay(meta) {
+		return meta;
+	}
 };
 __decorate([
 	Get("meta"),
@@ -657,6 +663,23 @@ const ReadableController = (readable, prefix) => {
 */
 const ViewController = ReadableController;
 //#endregion
+//#region src/permissions/crud-controls.ts
+/**
+* Static control whitelists per read op. Each list is the matching DTO's
+* `$`-properties (stripped) plus the URL-grammar extras (`filter`,
+* `insights`, `groupBy`) that bypass the DTO. The DTO is the single source of
+* truth — adding a `$control` there auto-extends the whitelist here.
+*/
+const dtoControls = (Dto) => [...Dto.type.props.keys()].map((k) => k.startsWith("$") ? k.slice(1) : k);
+const QUERY_CONTROLS = [
+	"filter",
+	"insights",
+	...dtoControls(QueryControlsDto),
+	"groupBy"
+];
+const PAGES_CONTROLS = ["filter", ...dtoControls(PagesControlsDto)];
+const ONE_CONTROLS = dtoControls(GetOneControlsDto);
+//#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
@@ -906,7 +929,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* vector-searchable flags, field-descriptor-derived filter/sort hints, and
 	* the configured primary keys.
 	*/
-	async buildMetaResponse() {
+	buildMetaResponse() {
 		const relations = [];
 		for (const [name, rel] of this.readable.relations) relations.push({
 			name,
@@ -931,11 +954,19 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			vectorSearchable: this.readable.isVectorSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
 			primaryKeys: [...this.readable.primaryKeys],
-			readOnly: this._isReadOnly(),
 			relations,
 			fields,
 			type: this.getSerializedType(),
-			actions: this.buildActions()
+			actions: this.buildActions(),
+			crud: this.buildCrud()
+		};
+	}
+	buildCrud() {
+		return {
+			...super.buildCrud(),
+			query: [...QUERY_CONTROLS],
+			pages: [...PAGES_CONTROLS],
+			one: [...ONE_CONTROLS]
 		};
 	}
 };
@@ -985,8 +1016,14 @@ let AsDbController = class AsDbController extends AsDbReadableController {
 	constructor(table, app) {
 		super(table, app);
 	}
-	_isReadOnly() {
-		return false;
+	buildCrud() {
+		return {
+			...super.buildCrud(),
+			insert: [],
+			update: [],
+			replace: [],
+			remove: []
+		};
 	}
 	/**
 	* Intercepts write operations. Return `undefined` to abort.
@@ -1203,7 +1240,7 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 	* client picker UI (which controls to render); the server does not enforce
 	* these flags at request time.
 	*/
-	async buildMetaResponse() {
+	buildMetaResponse() {
 		const fields = {};
 		for (const [path, meta] of this.fieldMeta) fields[path] = {
 			sortable: meta.has("ui.dict.sortable"),
@@ -1214,16 +1251,24 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 			vectorSearchable: false,
 			searchIndexes: [],
 			primaryKeys: this.primaryKey ? [this.primaryKey] : [],
-			readOnly: this._isReadOnly(),
 			relations: [],
 			fields,
 			type: this.getSerializedType(),
-			actions: []
+			actions: [],
+			crud: this.buildCrud()
 		};
 	}
 	buildActions() {
 		return [];
 	}
+	buildCrud() {
+		return {
+			...super.buildCrud(),
+			query: [...QUERY_CONTROLS],
+			pages: [...PAGES_CONTROLS],
+			one: [...ONE_CONTROLS]
+		};
+	}
 };
 __decorate([
 	Get("query"),
@@ -1666,4 +1711,4 @@ function classLevelActions(dict, forcedLevel) {
 	});
 }
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, validationErrorTransform };
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, discoverActions, validationErrorTransform };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -55,7 +55,7 @@
     "@uniqu/core": "^0.1.5",
     "@wooksjs/http-body": "^0.7.10",
     "moost": "^0.6.8",
-    "@atscript/db": "^0.1.56"
+    "@atscript/db": "^0.1.57"
   },
   "scripts": {
     "postinstall": "asc -f dts",