@web-ts-toolkit/access-router 0.47.1 → 0.48.0

package/llms.txt

@@ -171,7 +171,8 @@ Business boundary contracts (see the corresponding README sections):
 - `Service.exists`: terminal explicit/base/override false now returns a Forbidden ErrorResult before adapter dispatch in both includeId modes (previously successful false/null). Allowed matches/misses remain true/false, or `{ _id }`/null with includeId. Check success before data.
 - Public `_read`/`_readFilter` tryList never retries Forbidden/BadRequest. Authorized misses retain list fallback and its operation guard. `_upsert` with _id propagates denied exists as Forbidden (previously Unauthorized); allowed miss remains Unauthorized, with no create in either case. Generated direct/root-entry denial status is 403 (root envelope 200). Custom Express routes must map ErrorResult codes to HTTP status themselves; res.json does not do this automatically.
 - Shared-request cross-runtime composition keeps independent state: runtime B never reuses runtime A's permissions or base-filter cache, even with the same `requestPermissionField` name. Same-runtime middleware repeats reuse state without rerunning `globalPermissions`. Pre-populated request permission fields are application-supplied and preserved.
-- Advanced mutation routes persist the final parsed body: nested `data` validators run before the whole-body (`default`) validator, and only final `data`/`select`/`populate`/`tasks` plus allowed `options` (`includePermissions`/`populateAccess`, plus `returningAll` for update/upsert) reach the service. Missing body options fall back to `returning_all`/`include_permissions` query params.
+- Advanced mutation routes persist the final parsed body: nested `data` validators run before the whole-body (`default`) validator, and only final `data`/`select`/`populate`/`tasks` plus allowed `options` (`includePermissions`/`includeFieldPermissions`/`populateAccess`, plus `returningAll` for update/upsert) reach the service. Missing body options fall back to `returning_all`/`include_permissions` query params. Simple GET routes also accept `include_field_permissions` query params.
+- Router permission-output postures (absolute over client input and per-operation `defaults`): `stripPermissionsField: true` removes the whole permissions field from outputs (output matches `includePermissions: false` with the field, including its placeholder, deleted; enforcement still runs); `disableFieldPermissions: true` never computes `_view`/`_edit` maps while `includePermissions` still controls `docPermissions`-hook keys.
 - `package.json` declares `sideEffects` array listing the bundled runtime entries that run the lazy `mongoose-schema-jsonschema` patch on first runtime construction — bundlers must retain those entries
 
 ## Pointers

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/access-router",
   "description": "ACL-aware Express routers and in-memory data services for Mongoose-backed APIs",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/access-router",
-  "version": "0.47.1",
+  "version": "0.48.0",
   "sideEffects": [
     "./**/index.js",
     "./**/index.mjs",
@@ -57,8 +57,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.47.1",
-    "@web-ts-toolkit/utils": "0.47.1",
+    "@web-ts-toolkit/express-json-router": "0.48.0",
+    "@web-ts-toolkit/utils": "0.48.0",
     "just-diff": "^6.0.2",
     "mongoose-schema-jsonschema": "^4.0.1",
     "sift": "^17.1.3",

package/{parsers-BidvJUu7.d.mts → parsers-D6iK8khR.d.mts}

@@ -39,8 +39,28 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     }): any;
     protected createModelAdapter(modelName: string): any;
     protected getModelRouterOptions(modelName: string): ModelRouterOptions<TModel>;
+    /**
+     * Router-level permission output postures (see `ModelRouterOptions`).
+     * Absolute: they win over client input and per-operation `defaults`.
+     */
+    getPermissionsPosture(): {
+        stripPermissionsField: boolean;
+        disableFieldPermissions: boolean;
+    };
+    /**
+     * Router posture `stripPermissionsField`: drop the whole document
+     * permissions field (including the empty placeholder) from output instead
+     * of emitting permission metadata. Returns true when applied.
+     */
+    private stripPermissionsOutput;
     private asServiceHookContext;
     private getEffectiveAllowedSortFields;
+    /**
+     * With `requireExplicitSelect`, an omitted client select behaves as an
+     * `_id`-only projection, yielding field-less rows. Explicit selects pass
+     * through untouched.
+     */
+    protected resolveEffectiveSelect(select: Projection | undefined): Projection | undefined;
     private beginOp;
     private completeOp;
     constructor(req: ModelRequest, modelName: string);
@@ -54,6 +74,7 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     }, options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     }): Promise<SingleResult<TModel>>;
     /**
      * Update at authorized policy paths: admitted leaves preserve omitted siblings;
@@ -157,6 +178,7 @@ declare class PublicService<TModel = unknown> extends Service<TModel> {
     }, options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     }): Promise<SingleResult<PublicOutput<TModel>>>;
     _read<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(id: string, args?: Omit<PublicReadArgs, 'select' | 'populate'> & {
         select?: TSelect;
@@ -398,22 +420,28 @@ type ListQueryInput = {
     page_size?: string;
     skim?: 'true' | 'false';
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
     include_count?: 'true' | 'false';
     include_extra_headers?: 'true' | 'false';
 };
 type CreateQueryInput = {
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type ReadQueryInput = {
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
     try_list?: 'true' | 'false';
 };
 type UpdateQueryInput = {
     returning_all?: 'true' | 'false';
+    include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type UpsertQueryInput = {
     returning_all?: 'true' | 'false';
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type AdvancedListBody = {
     filter?: Filter | unknown[];
@@ -429,6 +457,7 @@ type AdvancedListBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         includeCount?: boolean;
         includeExtraHeaders?: boolean;
         populateAccess?: unknown;
@@ -447,6 +476,7 @@ type AdvancedReadFilterBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         tryList?: boolean;
         populateAccess?: unknown;
     };
@@ -459,6 +489,7 @@ type AdvancedReadBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         tryList?: boolean;
         populateAccess?: unknown;
     };
@@ -470,6 +501,7 @@ type AdvancedCreateBody = {
     tasks?: Task | Task[];
     options?: {
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         populateAccess?: unknown;
     };
 };
@@ -481,6 +513,7 @@ type AdvancedUpdateBody = {
     options?: {
         returningAll?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         populateAccess?: unknown;
     };
 };
@@ -492,6 +525,7 @@ type AdvancedUpsertBody = {
     options?: {
         returningAll?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         populateAccess?: unknown;
     };
 };
@@ -952,6 +986,15 @@ interface CreateArgs extends Omit<PublicCreateArgs, 'select' | 'tasks'> {
 interface PublicCreateOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     populateAccess?: PopulateAccess;
 }
 interface CreateOptions extends PublicCreateOptions {
@@ -971,6 +1014,15 @@ interface PublicListArgs {
 interface PublicListOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     includeCount?: boolean;
     populateAccess?: PopulateAccess;
     lean?: boolean;
@@ -987,6 +1039,15 @@ interface PublicReadOptions {
     populateAccess?: PopulateAccess;
     lean?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     /** Retry an authorized read miss with list access (default true); requires list operation access. Forbidden/BadRequest never retry. */
     tryList?: boolean;
 }
@@ -1018,6 +1079,15 @@ interface PublicUpdateOptions {
     skim?: boolean;
     returningAll?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     populateAccess?: PopulateAccess;
 }
 interface PublicUpsertOptions extends PublicUpdateOptions {
@@ -1302,6 +1372,7 @@ interface RootModelNewQueryEntry extends RootQueryEntryBase<'model', 'new'> {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     };
 }
 interface RootModelListQueryEntry extends RootQueryEntryBase<'model', 'list'> {
@@ -1431,7 +1502,7 @@ interface Task {
     options?: Record<string, unknown>;
 }
 interface AccessRouterBaseRequest extends AccessRouterRequest {
-    query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
+    query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_field_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
 }
 interface ModelRequest extends AccessRouterBaseRequest {
     macl: Core;
@@ -1522,6 +1593,15 @@ interface FindArgs<T = unknown> {
 interface FindOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     includeCount?: boolean;
     populateAccess?: PopulateAccess;
     lean?: boolean;
@@ -1544,6 +1624,15 @@ interface FindOneOptions {
     skim?: boolean;
     lean?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
 }
 interface FindByIdArgs<T = unknown> {
     select?: Projection;
@@ -1716,6 +1805,18 @@ interface DefaultModelRouterOptions<TModel = unknown> {
     mutationRouteSegment?: string;
     operationAccess?: Validation | OperationAccess;
     modelPermissionPrefix?: string;
+    /**
+     * When `true`, list/read/update requests without an explicit `select` return
+     * field-less rows (only `_id`, plus the permission field when requested)
+     * instead of all allowed fields. Applies to plain and advanced PATCH
+     * (returned updated record honors `select`, including `?select=` on plain
+     * PATCH and body `select` on advanced PATCH). Only an omitted (`undefined`)
+     * select triggers this; explicit selects — including backend `defaults` and
+     * an explicitly empty string/array (which keep their current meaning) — are
+     * unaffected. Counts, ordering, includes and permission enforcement are
+     * unchanged. Defaults to `false`.
+     */
+    requireExplicitSelect?: boolean;
     /**
      * Extra fields allowed in `sort` regardless of `list`/`read` field policy.
      * Merged as a union with permission-derived allowed fields (`id`/`_id` are
@@ -1729,6 +1830,25 @@ interface DefaultModelRouterOptions<TModel = unknown> {
      * Defaults to `false` (strict: disallowed sort returns `BadRequest`).
      */
     stripDisallowedSort?: boolean;
+    /**
+     * When `true`, the document permissions field (`documentPermissionField`,
+     * default `_permissions`) is removed from all outputs — including its empty
+     * placeholder — and client `includePermissions`/`includeFieldPermissions`
+     * input (query params, body/root-batch options and service-direct options)
+     * as well as per-operation `defaults` are ignored (both resolve to `false`).
+     * Output matches `includePermissions: false` with the permissions field
+     * removed entirely. Enforcement still runs; only output metadata is
+     * affected. Defaults to `false`.
+     */
+    stripPermissionsField?: boolean;
+    /**
+     * When `true`, client `includeFieldPermissions` input (query params,
+     * body/root-batch options and service-direct options) as well as
+     * per-operation `defaults` are ignored and field maps (`_view`/`_edit`)
+     * are never computed. `docPermissions`-hook keys still follow
+     * `includePermissions`. Defaults to `false`.
+     */
+    disableFieldPermissions?: boolean;
 }
 interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
     'operationAccess.default'?: Validation;
@@ -1754,6 +1874,16 @@ interface ModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions
     permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
     alwaysSelectFields?: string[];
     docPermissions?: DocPermissions | ModelDocPermissionsHook;
+    /**
+     * Allowlist of `docPermissions`-hook keys exposed in API responses.
+     * Enforcement always uses the full hook map; only serialization is reduced,
+     * after all grant computations and decorate hooks have run. `_view`/`_edit`
+     * are always kept. `undefined` (default) exposes everything (current
+     * behavior); any array (including `[]`) exposes `_view`/`_edit` plus the
+     * listed keys. Note `guard()` conditions on stripped doc-level keys fail
+     * closed — allowlist any key a custom route guard evaluates.
+     */
+    exposedDocPermissionKeys?: string[];
     baseFilter?: ModelBaseFilterHook | Record<string, ModelBaseFilterHook>;
     overrideFilter?: ModelOverrideFilterHook | Record<string, ModelOverrideFilterHook>;
     decorate?: ModelHook<TModel> | Record<string, ModelHook<TModel>>;

package/{parsers-BidvJUu7.d.ts → parsers-D6iK8khR.d.ts}

@@ -39,8 +39,28 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     }): any;
     protected createModelAdapter(modelName: string): any;
     protected getModelRouterOptions(modelName: string): ModelRouterOptions<TModel>;
+    /**
+     * Router-level permission output postures (see `ModelRouterOptions`).
+     * Absolute: they win over client input and per-operation `defaults`.
+     */
+    getPermissionsPosture(): {
+        stripPermissionsField: boolean;
+        disableFieldPermissions: boolean;
+    };
+    /**
+     * Router posture `stripPermissionsField`: drop the whole document
+     * permissions field (including the empty placeholder) from output instead
+     * of emitting permission metadata. Returns true when applied.
+     */
+    private stripPermissionsOutput;
     private asServiceHookContext;
     private getEffectiveAllowedSortFields;
+    /**
+     * With `requireExplicitSelect`, an omitted client select behaves as an
+     * `_id`-only projection, yielding field-less rows. Explicit selects pass
+     * through untouched.
+     */
+    protected resolveEffectiveSelect(select: Projection | undefined): Projection | undefined;
     private beginOp;
     private completeOp;
     constructor(req: ModelRequest, modelName: string);
@@ -54,6 +74,7 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     }, options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     }): Promise<SingleResult<TModel>>;
     /**
      * Update at authorized policy paths: admitted leaves preserve omitted siblings;
@@ -157,6 +178,7 @@ declare class PublicService<TModel = unknown> extends Service<TModel> {
     }, options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     }): Promise<SingleResult<PublicOutput<TModel>>>;
     _read<TSelect extends Projection | undefined = undefined, TPopulate extends Populate[] | string | undefined = undefined>(id: string, args?: Omit<PublicReadArgs, 'select' | 'populate'> & {
         select?: TSelect;
@@ -398,22 +420,28 @@ type ListQueryInput = {
     page_size?: string;
     skim?: 'true' | 'false';
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
     include_count?: 'true' | 'false';
     include_extra_headers?: 'true' | 'false';
 };
 type CreateQueryInput = {
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type ReadQueryInput = {
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
     try_list?: 'true' | 'false';
 };
 type UpdateQueryInput = {
     returning_all?: 'true' | 'false';
+    include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type UpsertQueryInput = {
     returning_all?: 'true' | 'false';
     include_permissions?: 'true' | 'false';
+    include_field_permissions?: 'true' | 'false';
 };
 type AdvancedListBody = {
     filter?: Filter | unknown[];
@@ -429,6 +457,7 @@ type AdvancedListBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         includeCount?: boolean;
         includeExtraHeaders?: boolean;
         populateAccess?: unknown;
@@ -447,6 +476,7 @@ type AdvancedReadFilterBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         tryList?: boolean;
         populateAccess?: unknown;
     };
@@ -459,6 +489,7 @@ type AdvancedReadBody = {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         tryList?: boolean;
         populateAccess?: unknown;
     };
@@ -470,6 +501,7 @@ type AdvancedCreateBody = {
     tasks?: Task | Task[];
     options?: {
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         populateAccess?: unknown;
     };
 };
@@ -481,6 +513,7 @@ type AdvancedUpdateBody = {
     options?: {
         returningAll?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         populateAccess?: unknown;
     };
 };
@@ -492,6 +525,7 @@ type AdvancedUpsertBody = {
     options?: {
         returningAll?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
         populateAccess?: unknown;
     };
 };
@@ -952,6 +986,15 @@ interface CreateArgs extends Omit<PublicCreateArgs, 'select' | 'tasks'> {
 interface PublicCreateOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     populateAccess?: PopulateAccess;
 }
 interface CreateOptions extends PublicCreateOptions {
@@ -971,6 +1014,15 @@ interface PublicListArgs {
 interface PublicListOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     includeCount?: boolean;
     populateAccess?: PopulateAccess;
     lean?: boolean;
@@ -987,6 +1039,15 @@ interface PublicReadOptions {
     populateAccess?: PopulateAccess;
     lean?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     /** Retry an authorized read miss with list access (default true); requires list operation access. Forbidden/BadRequest never retry. */
     tryList?: boolean;
 }
@@ -1018,6 +1079,15 @@ interface PublicUpdateOptions {
     skim?: boolean;
     returningAll?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     populateAccess?: PopulateAccess;
 }
 interface PublicUpsertOptions extends PublicUpdateOptions {
@@ -1302,6 +1372,7 @@ interface RootModelNewQueryEntry extends RootQueryEntryBase<'model', 'new'> {
     options?: {
         skim?: boolean;
         includePermissions?: boolean;
+        includeFieldPermissions?: boolean;
     };
 }
 interface RootModelListQueryEntry extends RootQueryEntryBase<'model', 'list'> {
@@ -1431,7 +1502,7 @@ interface Task {
     options?: Record<string, unknown>;
 }
 interface AccessRouterBaseRequest extends AccessRouterRequest {
-    query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
+    query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_field_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
 }
 interface ModelRequest extends AccessRouterBaseRequest {
     macl: Core;
@@ -1522,6 +1593,15 @@ interface FindArgs<T = unknown> {
 interface FindOptions {
     skim?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
     includeCount?: boolean;
     populateAccess?: PopulateAccess;
     lean?: boolean;
@@ -1544,6 +1624,15 @@ interface FindOneOptions {
     skim?: boolean;
     lean?: boolean;
     includePermissions?: boolean;
+    /**
+     * Include field-level `_view`/`_edit` maps. Defaults to `includePermissions`
+     * when omitted. `includePermissions: true` + `includeFieldPermissions: false`
+     * keeps `docPermissions`-hook keys but omits `_view`/`_edit` entirely.
+     * Enabling field maps also computes doc permissions as grant input (even
+     * under skim or when `includePermissions` is false), so the maps match the
+     * `includePermissions: true` output.
+     */
+    includeFieldPermissions?: boolean;
 }
 interface FindByIdArgs<T = unknown> {
     select?: Projection;
@@ -1716,6 +1805,18 @@ interface DefaultModelRouterOptions<TModel = unknown> {
     mutationRouteSegment?: string;
     operationAccess?: Validation | OperationAccess;
     modelPermissionPrefix?: string;
+    /**
+     * When `true`, list/read/update requests without an explicit `select` return
+     * field-less rows (only `_id`, plus the permission field when requested)
+     * instead of all allowed fields. Applies to plain and advanced PATCH
+     * (returned updated record honors `select`, including `?select=` on plain
+     * PATCH and body `select` on advanced PATCH). Only an omitted (`undefined`)
+     * select triggers this; explicit selects — including backend `defaults` and
+     * an explicitly empty string/array (which keep their current meaning) — are
+     * unaffected. Counts, ordering, includes and permission enforcement are
+     * unchanged. Defaults to `false`.
+     */
+    requireExplicitSelect?: boolean;
     /**
      * Extra fields allowed in `sort` regardless of `list`/`read` field policy.
      * Merged as a union with permission-derived allowed fields (`id`/`_id` are
@@ -1729,6 +1830,25 @@ interface DefaultModelRouterOptions<TModel = unknown> {
      * Defaults to `false` (strict: disallowed sort returns `BadRequest`).
      */
     stripDisallowedSort?: boolean;
+    /**
+     * When `true`, the document permissions field (`documentPermissionField`,
+     * default `_permissions`) is removed from all outputs — including its empty
+     * placeholder — and client `includePermissions`/`includeFieldPermissions`
+     * input (query params, body/root-batch options and service-direct options)
+     * as well as per-operation `defaults` are ignored (both resolve to `false`).
+     * Output matches `includePermissions: false` with the permissions field
+     * removed entirely. Enforcement still runs; only output metadata is
+     * affected. Defaults to `false`.
+     */
+    stripPermissionsField?: boolean;
+    /**
+     * When `true`, client `includeFieldPermissions` input (query params,
+     * body/root-batch options and service-direct options) as well as
+     * per-operation `defaults` are ignored and field maps (`_view`/`_edit`)
+     * are never computed. `docPermissions`-hook keys still follow
+     * `includePermissions`. Defaults to `false`.
+     */
+    disableFieldPermissions?: boolean;
 }
 interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
     'operationAccess.default'?: Validation;
@@ -1754,6 +1874,16 @@ interface ModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions
     permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
     alwaysSelectFields?: string[];
     docPermissions?: DocPermissions | ModelDocPermissionsHook;
+    /**
+     * Allowlist of `docPermissions`-hook keys exposed in API responses.
+     * Enforcement always uses the full hook map; only serialization is reduced,
+     * after all grant computations and decorate hooks have run. `_view`/`_edit`
+     * are always kept. `undefined` (default) exposes everything (current
+     * behavior); any array (including `[]`) exposes `_view`/`_edit` plus the
+     * listed keys. Note `guard()` conditions on stripped doc-level keys fail
+     * closed — allowlist any key a custom route guard evaluates.
+     */
+    exposedDocPermissionKeys?: string[];
     baseFilter?: ModelBaseFilterHook | Record<string, ModelBaseFilterHook>;
     overrideFilter?: ModelOverrideFilterHook | Record<string, ModelOverrideFilterHook>;
     decorate?: ModelHook<TModel> | Record<string, ModelHook<TModel>>;