@web-ts-toolkit/access-router 0.66.0 → 0.67.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,6 +20,7 @@ ACL-aware Express routers and in-memory data services for Mongoose-backed APIs.
20
20
  **Private virtual inputs:** [Populated dependencies and runnable example](#private-populated-dependencies)
21
21
 
22
22
  **Migration:** [Removed overrides](#breaking-release-service-overrides-migration) ·
23
+ [Nested operation rules](MIGRATION.md#breaking-change-nested-operation-access) ·
23
24
  [Server-owned hydration](#breaking-release-server-owned-hydration) ·
24
25
  [Target-owned populate flags](#breaking-release-populate-policy-migration) ·
25
26
  [Named helpers](#breaking-release-named-helpers-and-default-behavior) ·
@@ -146,10 +147,9 @@ package-managed execution, falling back to `defaultRuntime` outside it.
146
147
  captured runtime model default → true. Explicit `undefined` restores inheritance;
147
148
  omission retains an override. Data assignment has no model-default layer.
148
149
  2. **Dotted setters update one path copy-on-write.** Use
149
- `router.setOption('operationAccess.basicRead', false)` to keep sibling rules,
150
- or pass `undefined` to restore lookup fallback. Property helpers such as
151
- `router.operationAccess('basicRead', false)` are for defined values; use
152
- `set`/`setOption` for undefined. Updating a path beneath a scalar starts an
150
+ `router.setOption('operationAccess.read.basic', false)` to keep sibling members,
151
+ or pass `undefined` to restore lookup fallback. Two-argument property helpers such as
152
+ `router.operationAccess('read.basic', undefined)` also clear that member. Updating a path beneath a scalar starts an
153
153
  object; use a `default` entry to retain a broad fallback. Dotted keys belong in
154
154
  setter arguments, not flat constructor-object properties.
155
155
  3. **Lookup is not a deep merge.** Generic nested option/hook lookup uses the
@@ -159,9 +159,9 @@ package-managed execution, falling back to `defaultRuntime` outside it.
159
159
  stored parent is also absent. `getExactModelOption` instead checks just the
160
160
  exact stored path, then the same runtime-default path; `getExactDataOption`
161
161
  checks only the stored path. `getDefaultModelOption` is exact. **Route guards
162
- have their own resolver:** exact variant (including exact model-default
163
- fallback) → base exact/`.default`/shorthand. A default variant can therefore
164
- outrank a model's base rule. See the [full precedence](#variant-and-base-fallback),
162
+ have their own resolver:** exact context member (including same-owner exact model-default
163
+ fallback) → operation scalar/`default` → outer `.default`/shorthand → deny. A runtime context member can
164
+ outrank a model's operation default. See the [full precedence](#variant-and-base-fallback),
165
165
  including closed [subdocument rules](#subdocument-field-precedence).
166
166
  4. **Method values resolve with `??`.** At each service resolver a non-nullish
167
167
  supplied property wins over that method's `defaults` bucket, then its built-in
@@ -175,8 +175,10 @@ package-managed execution, falling back to `defaultRuntime` outside it.
175
175
  Public `_upsert` uses the public create or update bucket for its branch; trusted
176
176
  `upsert` has `upsertArgs`/`upsertOptions`. There is no `publicUpsertOptions` bucket.
177
177
  5. **Metadata posture is absolute.** Model `stripPermissionsField: true` removes
178
- the entire output metadata field; `disableFieldPermissions: true` suppresses
179
- `_view`/`_edit` computation. They win over per-call flags and method defaults.
178
+ the entire output metadata field; `disableFieldPermissions` defaults to `true`
179
+ and suppresses `_view`/`_edit` computation and output, including placeholders. They win over
180
+ per-call flags and method defaults. Set `disableFieldPermissions: false` on a
181
+ model or with `setDefaultModelOptions` to allow field maps.
180
182
  Internal authorization and full document grants still run.
181
183
 
182
184
  The supported `Defaults` buckets are `findArgs`/`findOptions`,
@@ -259,42 +261,83 @@ Express routes. `parentPath` supplies the external prefix for route metadata/log
259
261
  mount that prefix in Express yourself. Live `idField`/`resolveIdFilter` change lookup
260
262
  behavior rather than route shape.
261
263
 
262
- ### Owned READ/LIST authorization modes
264
+ ### Owned authorization modes
263
265
 
264
- There is one document-stage engine and exactly two independent server options:
265
- `readAuthorizationMode` / `listAuthorizationMode`, each `'isolated' | 'trusted'`,
266
- default **isolated**. See the shipped [breaking migration guide](MIGRATION.md) for
267
- before/after examples, all ten removed flags, errors and rollout guidance. No old
268
- flag combination, dormant mode, output handle or compatibility alias remains.
266
+ One document-stage engine has four independent server model/default-model settings,
267
+ all `AuthorizationMode = 'isolated' | 'trusted'`, default **isolated**:
268
+
269
+ | Setting | Current scope |
270
+ | ------------------------- | -------------------------------------------------------------------------------------------------- |
271
+ | `readAuthorizationMode` | Root READ output; READ-to-LIST retry retains this capture. |
272
+ | `listAuthorizationMode` | Root LIST output. |
273
+ | `createAuthorizationMode` | Post-persistence/lifecycle CREATE output, including bulk rows and UPSERT's executed create branch. |
274
+ | `updateAuthorizationMode` | Post-persistence/lifecycle UPDATE output and UPSERT's executed update branch. |
275
+
276
+ The READ/LIST names stay unchanged. There is no fifth UPSERT setting, alternate
277
+ spelling or compatibility alias. The broader names do not authorize input or other
278
+ phase relaxation. See the shipped [migration guide](MIGRATION.md) for the current
279
+ contract, removed unsafe flags and checked workflows.
269
280
 
270
281
  <!-- doc-example: partial -->
271
282
 
272
283
  ```ts
273
284
  import { createAccessRuntime } from '@web-ts-toolkit/access-router';
274
285
  const api = createAccessRuntime();
275
- api.setDefaultModelOptions({ readAuthorizationMode: 'isolated', listAuthorizationMode: 'isolated' });
276
- api.setModelOptions('Employee', { readAuthorizationMode: 'isolated', listAuthorizationMode: 'trusted' });
286
+ api.setDefaultModelOptions({
287
+ readAuthorizationMode: 'isolated',
288
+ listAuthorizationMode: 'isolated',
289
+ createAuthorizationMode: 'isolated',
290
+ updateAuthorizationMode: 'isolated',
291
+ });
292
+ api.setModelOptions('Employee', {
293
+ readAuthorizationMode: 'isolated',
294
+ listAuthorizationMode: 'trusted',
295
+ createAuthorizationMode: 'trusted',
296
+ updateAuthorizationMode: 'isolated',
297
+ });
277
298
  api.setModelOptions('Payroll', { readAuthorizationMode: 'isolated', listAuthorizationMode: 'isolated' });
278
299
  api.setModelOption('Employee', 'listAuthorizationMode', undefined); // inherit the live default
279
300
  api.setModelOption('Employee', 'readAuthorizationMode', 'isolated'); // NEW calls only
280
301
  ```
281
302
 
282
- Isolated owns bounded detached projected source and gives document hooks disposable
283
- views. Trusted may borrow admitted ordinary projected source/doc-hook input: mutations
284
- can affect values/calculated facts; hidden unvisited graphs are not whole-document
285
- bounded. **Both own actor, private policy and normalized frozen boolean facts**, enforce
303
+ Isolated owns bounded detached source and gives document-permission output hooks
304
+ disposable views. Trusted may borrow admitted ordinary source/doc-hook input:
305
+ mutations can affect response values and facts calculated from that source. Only
306
+ **query-origin** trusted output can leave hidden unvisited graphs unbounded.
307
+
308
+ **Both write modes always acquire a full bounded detached post-write source**, including
309
+ mutable native leaves, before output callbacks. Trusted omits only the subsequent
310
+ disposable document-hook view copy; it never lends live write documents, `_doc`, payloads
311
+ or lifecycle snapshots. Conversion failure at this boundary fails output rather than
312
+ borrowing `_doc`. This also applies to write-origin populated targets, even when their
313
+ mode is selected by READ/LIST. A hidden graph can therefore fail write-output admission
314
+ even if a trusted query would not visit it. No source-copy saving is promised; without
315
+ an exposed document hook there may be no copy saving.
316
+
317
+ **Both own actor, private policy and normalized frozen boolean facts**, enforce
286
318
  original actor, rows/fields/targets and selected/native 20,000-slot/depth-100 bounds.
287
319
  Both retain separate getter views, return staging and private argument-four isolation.
288
320
  No sandbox, transaction, rollback, external freshness or blanket security equivalence.
289
321
 
290
- Capture precedes hooks/awaits. Genuine embedded scopes inherit their owner; related
291
- targets use their own captured model/access mode and policy, not their parent's mode.
292
- READ-to-LIST retry keeps initiating READ mode with a fresh stage. Independent service
293
- calls capture anew. Writes/new/dedicated subdocuments always stay isolated.
322
+ Capture precedes hooks/awaits, including both possible UPSERT modes. Selecting the
323
+ executed branch retains initiating `operation: 'upsert'` and branch-specific access;
324
+ it does not re-read settings after saving or turn a write response into a READ call.
325
+ Genuine embedded scopes inherit their owner's mode/facts. Related targets use their
326
+ **own model's captured READ/LIST mode** at effective target access, including genuine
327
+ write-origin populate, with independent policy/facts. Parent mode cannot lower an
328
+ isolated target; a trusted target cannot mutate an isolated parent's source or live
329
+ write graph. Independent nested READ/LIST service calls capture anew.
330
+
331
+ Write-input admission, pre-write grants and the **hydrated pre-write UPDATE hook**,
332
+ validation, preparation, transform/save and lifecycle hooks are unchanged, not newly
333
+ detached or sandboxed. NEW, helpers, dedicated subdocument origins, COUNT, DELETE,
334
+ DISTINCT and unsupported custom origins gain no trusted stage. No implicit save,
335
+ query or rollback is added. **Output authorization can fail after the write commits**;
336
+ reconcile stored business state rather than automatically retrying the write.
294
337
 
295
338
  Only literal enum strings or undefined restoration are valid. Bulk setters reject
296
339
  atomically. Retired controls reject by presence, even false/undefined/inherited/
297
- non-enumerable. New/old selectors are prohibited in HTTP/root/per-call/helper/defaults/
340
+ non-enumerable. Mode/retired selectors are prohibited in HTTP/root/per-call/helper/defaults/
298
341
  include/populate/subquery authority slots; same-named business fields remain data.
299
342
  Trusted transitions warn once per effective owner/access; logger failures cannot abort.
300
343
  Switching to isolated affects new calls, not in-flight captures. Rollback means a tested
@@ -337,7 +380,7 @@ separate from both objects. Root entries keep `target`, `name`, base `op`, `filt
337
380
  | Names | Deliberate distinction |
338
381
  | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
339
382
  | `operationAccess` / `permissionSchema` / `authorization` | Route entry / request field rules / explicit server-only per-call authority. An entry grant does not grant fields or related targets. |
340
- | `select` / `alwaysSelectFields` / virtual `dependsOn` | Desired output / private persisted hook inputs / scoped getter dependencies. Fetching a value grants no output authority. |
383
+ | `select` / `docPermissions.dependsOn` / virtual `dependsOn` | Desired output / private document-hook inputs / scoped getter dependencies. Fetching a value grants no output authority. |
341
384
  | `baseFilter` / `overrideFilter` | Request row scope / ordinary-query transform. Trusted rows replace only the former; the transform still runs once and false stays terminal. |
342
385
  | `idParam` / `idField` / `resolveIdFilter` | Express parameter name / lookup field / custom identifier-to-filter hook. A callable resolver takes precedence over `idField`; otherwise lookup uses that field (model default `_id`). |
343
386
  | `requestPermissionField` / `documentPermissionField` / `docPermissions` | Request grant storage / serialized document metadata path / hook producing full internal document grants. Metadata flags affect exposure, not authority. |
@@ -537,8 +580,9 @@ order input returns BadRequest before entry dispatch.
537
580
 
538
581
  Groups run in ascending order; within a group operations may run concurrently.
539
582
  Results retain input indices/order, with each entry's `statusCode` and public
540
- `result` inside the HTTP 200 batch response. Root entries use base operation guards,
541
- not basic/advanced variant names. Batches are non-transactional: an unexpected
583
+ `result` inside the HTTP 200 batch response. Root entries keep base operation names
584
+ but select target `operation.root`, falling back to its scalar/default. The root's
585
+ own scalar guard is a separate outer admission check. Batches are non-transactional: an unexpected
542
586
  rejection can leave already-committed writes. Hook and persistence work also obey
543
587
  their separate [request/runtime limits](#persistence-concurrency-and-resource-limits).
544
588
 
@@ -611,6 +655,73 @@ stay false while ordinary population skips only target operation admission with
611
655
  `requireOperationAccessForPopulateQueries: false`. See the [two-flag policy matrix](#runtime-populate-operation-policies)
612
656
  and [runnable Document example](#runnable-private-dependency-example).
613
657
 
658
+ ### Document-permission dependencies (breaking change)
659
+
660
+ `alwaysSelectFields` is removed, including its fluent setter and dotted options.
661
+ Move each private input onto the calculation that uses it: `docPermissions` accepts
662
+ a synchronous/asynchronous function or `{ dependsOn?, get }`, directly or in a
663
+ per-access map. The spelling is **`get`**, like virtuals, not `getter`.
664
+
665
+ <!-- doc-example: partial -->
666
+
667
+ ```ts
668
+ import type {
669
+ ModelDocPermissionsDescriptor,
670
+ ModelDocPermissionsDefinition,
671
+ ModelDocPermissionsAccessRecord,
672
+ ModelRouter,
673
+ ModelRouterOptions,
674
+ } from '@web-ts-toolkit/access-router';
675
+
676
+ interface Order {
677
+ ownerId: string;
678
+ profile: { tenantId: string };
679
+ }
680
+ const owner: ModelDocPermissionsDescriptor<Order> = {
681
+ dependsOn: ['ownerId', 'profile'], // whole top-level container for nested input
682
+ get(doc, permissions, context) {
683
+ void [this.macl, context.operation]; // original request this; unchanged hook arguments
684
+ return {
685
+ owner:
686
+ permissions.has('admin') ||
687
+ (doc !== null && typeof doc === 'object' && 'ownerId' in doc && doc.ownerId === 'alice'),
688
+ };
689
+ },
690
+ };
691
+ const definition: ModelDocPermissionsDefinition<Order> = owner;
692
+ const accesses: ModelDocPermissionsAccessRecord<Order> = {
693
+ default: definition,
694
+ read: owner,
695
+ list: async () => ({ owner: false }), // function: no additional fetch inputs
696
+ inspection: owner, // trusted custom access
697
+ };
698
+ const direct: ModelRouterOptions<Order> = { docPermissions: definition };
699
+ const mapped: ModelRouterOptions<Order> = { docPermissions: accesses };
700
+ declare const router: ModelRouter<Order>;
701
+ router.docPermissions(owner).docPermissions('read', owner);
702
+ router.setOption('docPermissions.inspection', owner); // replace the entire definition
703
+ void [direct, mapped];
704
+ ```
705
+
706
+ Dependencies use model-local **top-level persisted schema keys**, like virtuals.
707
+ Dotted, unsafe, unknown and virtual names reject; declare `profile`, not
708
+ `profile.tenantId`. `dependsOn` absent/empty adds no fetch inputs. A missing or
709
+ undefined value **never skips the document hook** (unlike virtual dependency
710
+ skipping). Declared inputs remain private when unrequested, excluded or denied;
711
+ they grant no output authority and do not select a virtual.
712
+
713
+ The active **`docPermissionsAccess`** selects the exact definition, then `default`
714
+ when the exact entry is undefined; a direct function/descriptor applies to every
715
+ access. Hook and dependencies are captured together before awaits. Dependencies
716
+ are **not unioned** with output/virtual access or inherited from a different entry.
717
+ `get`/`dependsOn` are reserved descriptor members, not custom access names.
718
+ Dotted access setters replace whole definitions; partial `.get`/`.dependsOn` edits
719
+ reject. Malformed definitions (including null/false or mixed descriptor/access keys)
720
+ reject instead of silently disabling calculation. Embedded scopes inherit owning-document facts; populate/include targets
721
+ resolve their own definitions. Dedicated subdocument routes still prepare the
722
+ owning parent. Pre-write and post-write stages are independent. Raw output helpers
723
+ perform no hidden query or document-hook calculation.
724
+
614
725
  ### Selection, grants and document results
615
726
 
616
727
  For business fields, output is **selected AND (request-authorized OR explicitly
@@ -642,7 +753,8 @@ scalar value when that root is selected.
642
753
 
643
754
  Planning defers document-dependent rules and never runs permission functions or
644
755
  virtual getters. Document hooks receive projected input: configure additional
645
- persisted hook dependencies with `alwaysSelectFields`. Internal dependency fetches
756
+ persisted hook dependencies with `docPermissions.dependsOn` (on the applicable
757
+ definition). Internal dependency fetches
646
758
  do not grant output, even when the same path is also a private include join key.
647
759
  Captured row/document hooks retain exact-access → `.default` → bare-hook resolution;
648
760
  only an undefined entry falls through. Omitted/undefined helper options now use the
@@ -694,7 +806,7 @@ empty facts; that is not current-document proof. Metadata (`getDocPermissions` i
694
806
  is DATA, not authority. Never replace a retired handle with unrestricted/client grants.
695
807
 
696
808
  For current document-dependent authorization use a new normal read/list with suitable
697
- selection and private `alwaysSelectFields` hook inputs. For presentation just use the
809
+ selection and private `docPermissions.dependsOn` hook inputs. For presentation just use the
698
810
  already-filtered DTO: no extra query, but no claim of current checks. See the executable
699
811
  guide for exact **0/0 helper** versus **+1 read/+1 hook** refresh counts.
700
812
 
@@ -1006,11 +1118,13 @@ async function runServiceAuthorizationExample() {
1006
1118
  return filter;
1007
1119
  },
1008
1120
  },
1009
- alwaysSelectFields: { read: ['ownerId'] }, // private projected document-hook input
1010
1121
  docPermissions: {
1011
- read: (doc) => {
1012
- documentHookCalls++;
1013
- return { owner: doc !== null && typeof doc === 'object' && 'ownerId' in doc && doc.ownerId === 'alice' };
1122
+ read: {
1123
+ dependsOn: ['ownerId'], // private projected document-hook input
1124
+ get: (doc) => {
1125
+ documentHookCalls++;
1126
+ return { owner: doc !== null && typeof doc === 'object' && 'ownerId' in doc && doc.ownerId === 'alice' };
1127
+ },
1014
1128
  },
1015
1129
  },
1016
1130
  permissionSchema: { status: { read: 'owner' }, internalNote: false, summary: false },
@@ -1388,7 +1502,7 @@ hook, losing otherwise allowed persisted fields. Full internal document grants
1388
1502
  are now resolved once per projected document/access stage regardless of `skim`,
1389
1503
  `includePermissions`, `includeFieldPermissions`, stripping or exposed-key limits.
1390
1504
  Only serialized metadata changes with those settings. Configure required private
1391
- hook inputs with `alwaysSelectFields`; the published DTO is data, not an authorization
1505
+ hook inputs with `docPermissions.dependsOn`; the published DTO is data, not an authorization
1392
1506
  certificate after those inputs and `_permissions` are removed. A later raw helper pick
1393
1507
  uses captured global permissions, frozen empty document facts and explicit output-only
1394
1508
  server policy, not retained document decisions. For current document-dependent facts,
@@ -1713,10 +1827,16 @@ query params; only `includePermissions`/`includeFieldPermissions`/`populateAcces
1713
1827
 
1714
1828
  ## Basic and advanced operation access
1715
1829
 
1716
- Configure generated endpoint guards in `operationAccess`. A base rule such as `read`
1717
- covers both variants unless an exact `basicRead` or `advancedRead` rule overrides it.
1718
- Variants authorize **route entry**; field grants remain in `permissionSchema` under
1719
- base names such as `read` and `list`.
1830
+ Configure generated endpoint guards in `operationAccess`. Each operation accepts a
1831
+ scalar `Validation` or `{ default?, basic?, advanced?, root? }`, with a `Validation`
1832
+ at each member. `basic`, `advanced` and `root` independently authorize **entry**;
1833
+ `default` supplies context-free base checks and entry fallback. Field grants remain
1834
+ in `permissionSchema` under base names such as `read` and `list`.
1835
+
1836
+ This is a hard breaking replacement of the former flat API, not an alias or
1837
+ translation layer. See the shipped [migration and seven mapping pairs](MIGRATION.md#breaking-change-nested-operation-access).
1838
+ Public `OperationAccessContext`, `OperationAccessVariants` and `OperationAccessRule`
1839
+ are exported from root and `./advanced`.
1720
1840
 
1721
1841
  <!-- doc-example: partial -->
1722
1842
 
@@ -1732,20 +1852,20 @@ const baseOnly = {
1732
1852
  // Among top-level routes, deny GET /users/:id only; both advanced read POSTs inherit read: true.
1733
1853
  const advancedReadsOnly = {
1734
1854
  basePath: '/users',
1735
- operationAccess: { list: true, read: true, basicRead: false },
1855
+ operationAccess: { list: true, read: { default: true, basic: false } },
1736
1856
  permissionSchema: { name: true },
1737
1857
  } satisfies ModelRouterOptions;
1738
1858
 
1739
1859
  // Keep GET /users, deny POST /users/__query.
1740
1860
  const basicListsOnly = {
1741
1861
  basePath: '/users',
1742
- operationAccess: { list: true, read: true, advancedList: false },
1862
+ operationAccess: { list: { default: true, advanced: false }, read: true },
1743
1863
  permissionSchema: { name: true },
1744
1864
  } satisfies ModelRouterOptions;
1745
1865
  // Pass one of these objects to acl.createRouter(UserModel, options).
1746
1866
  ```
1747
1867
 
1748
- `basicRead: false` does not affect list, new, count, distinct, or mutation routes;
1868
+ `read.basic: false` does not affect list, new, count, distinct, or mutation routes;
1749
1869
  their own guards still apply. Subdocument reads follow the field precedence below.
1750
1870
  Denied operations return **HTTP 401 Unauthorized**
1751
1871
  before validation/service dispatch. Every route stays registered in
@@ -1759,55 +1879,61 @@ Paths are relative to `basePath`, with model defaults `idParam: 'id'`,
1759
1879
  Changing those route-shape options changes paths, not guard names. For data routers,
1760
1880
  set `idParam: 'id'` explicitly to use the illustrated identifier paths.
1761
1881
 
1762
- | Base guard | Basic endpoint → override | Advanced endpoint → override |
1763
- | ----------------- | ------------------------------------------------ | -------------------------------------------------------------- |
1764
- | `list` | `GET /` → `basicList` | `POST /__query` → `advancedList` |
1765
- | `read` | `GET /:id` → `basicRead` | `POST /__query/:id`, `POST /__query/__filter` → `advancedRead` |
1766
- | `create` | `POST /` → `basicCreate` | `POST /__mutation` → `advancedCreate` |
1767
- | `update` | `PATCH /:id` → `basicUpdate` | `PATCH /__mutation/:id` → `advancedUpdate` |
1768
- | `upsert` | `PUT /` → `basicUpsert` | `PUT /__mutation` → `advancedUpsert` |
1769
- | `count` | `GET /count` → `basicCount` | `POST /count` → `advancedCount` |
1770
- | `distinct` | `GET /distinct/:field` → `basicDistinct` | `POST /distinct/:field` → `advancedDistinct` |
1771
- | `subs.<sub>.list` | `GET /:id/<sub>` → `subs.<sub>.basicList` | `POST /:id/<sub>/__query` → `subs.<sub>.advancedList` |
1772
- | `subs.<sub>.read` | `GET /:id/<sub>/:subId` → `subs.<sub>.basicRead` | `POST /:id/<sub>/:subId/__query` → `subs.<sub>.advancedRead` |
1773
-
1774
- Model routers support all fourteen top-level keys. Data routers implement only
1775
- list/read: `basicList`, `advancedList`, `basicRead`, and `advancedRead`, including
1776
- both advanced read paths. Each model subdocument field supports four nested
1777
- list/read keys. Filtered count/distinct POSTs are advanced even without `__query`.
1778
-
1779
- Unpaired routes retain their base guards:
1780
-
1781
- | Endpoint | Guard |
1782
- | --------------------------------------------- | ------------------- |
1783
- | `GET /new` | `new` |
1784
- | `DELETE /:id` | `delete` |
1785
- | `POST /:id/<sub>` | `subs.<sub>.create` |
1786
- | `PATCH /:id/<sub>`, `PATCH /:id/<sub>/:subId` | `subs.<sub>.update` |
1787
- | `DELETE /:id/<sub>/:subId` | `subs.<sub>.delete` |
1882
+ | Operation | Basic endpoint → member | Advanced endpoint → member | Root entry member |
1883
+ | ----------------- | ------------------------------------------------- | --------------------------------------------------------------- | ---------------------- |
1884
+ | `list` | `GET /` → `list.basic` | `POST /__query` → `list.advanced` | `list.root` |
1885
+ | `read` | `GET /:id` → `read.basic` | `POST /__query/:id`, `POST /__query/__filter` → `read.advanced` | `read.root` |
1886
+ | `create` | `POST /` → `create.basic` | `POST /__mutation` → `create.advanced` | `create.root` |
1887
+ | `update` | `PATCH /:id` → `update.basic` | `PATCH /__mutation/:id` → `update.advanced` | `update.root` |
1888
+ | `upsert` | `PUT /` → `upsert.basic` | `PUT /__mutation` → `upsert.advanced` | `upsert.root` |
1889
+ | `count` | `GET /count` → `count.basic` | `POST /count` → `count.advanced` | `count.root` |
1890
+ | `distinct` | `GET /distinct/:field` → `distinct.basic` | `POST /distinct/:field` → `distinct.advanced` | `distinct.root` |
1891
+ | `subs.<sub>.list` | `GET /:id/<sub>` → `subs.<sub>.list.basic` | `POST /:id/<sub>/__query` → `subs.<sub>.list.advanced` | `subs.<sub>.list.root` |
1892
+ | `subs.<sub>.read` | `GET /:id/<sub>/:subId` → `subs.<sub>.read.basic` | `POST /:id/<sub>/:subId/__query` → `subs.<sub>.read.advanced` | `subs.<sub>.read.root` |
1893
+
1894
+ Data routers implement list/read with the same members, including both advanced
1895
+ read paths. Filtered count/distinct POSTs are advanced even without `__query`.
1896
+ Context is explicit server-owned dispatch metadata, never inferred from method or
1897
+ caller-supplied selectors. Root POST does not select advanced.
1898
+
1899
+ Unpaired routes also use operation objects; direct entry selects basic:
1900
+
1901
+ | Endpoint | Guard |
1902
+ | --------------------------------------------- | ------------------------- |
1903
+ | `GET /new` | `new.basic` |
1904
+ | `DELETE /:id` | `delete.basic` |
1905
+ | `POST /:id/<sub>` | `subs.<sub>.create.basic` |
1906
+ | `PATCH /:id/<sub>`, `PATCH /:id/<sub>/:subId` | `subs.<sub>.update.basic` |
1907
+ | `DELETE /:id/<sub>/:subId` | `subs.<sub>.delete.basic` |
1908
+
1909
+ Their root counterparts select `root`; both `subUpdate` and `subBulkUpdate` use
1910
+ `subs.<sub>.update.root`. An `advanced` member does not create an unpaired endpoint.
1788
1911
 
1789
1912
  ### Variant and base fallback
1790
1913
 
1791
- 1. Read the exact variant from the owning runtime (model lookup includes the
1792
- runtime's exact model-default path).
1793
- 2. Only if that value is `undefined`, use the existing base operation resolution:
1794
- exact base rule → `operationAccess.default` → scalar `operationAccess` shorthand.
1795
- If no valid guard resolves, deny.
1914
+ 1. Select the exact operation context member, e.g. `read.advanced`. Model lookup
1915
+ checks the model, then its owning runtime's same exact model-default path.
1916
+ 2. Only if undefined, select the operation's scalar rule or its object's `default`.
1917
+ 3. If still undefined, use outer `operationAccess.default` or scalar shorthand.
1918
+ 4. With no applicable valid guard, deny. An empty top-level operation object can
1919
+ use the outer fallback; malformed defined JavaScript values deny without fallback.
1796
1920
 
1797
1921
  The selected variant **replaces** the base guard; the two are not combined or both
1798
1922
  evaluated. Explicit false, an empty array, or a guard returning false is terminal.
1799
1923
  Omitted and explicit undefined variants inherit. With no runtime-default variants
1800
1924
  or other fallback configured:
1801
1925
 
1802
- | Rules | Basic list | Advanced list | Root list entry |
1803
- | ---------------------------------- | ---------- | ------------- | --------------- |
1804
- | `list: true` | allowed | allowed | allowed |
1805
- | `list: false` | denied | denied | denied |
1806
- | `list: true, basicList: false` | denied | allowed | allowed |
1807
- | `list: true, advancedList: false` | allowed | denied | allowed |
1808
- | `list: false, basicList: true` | allowed | denied | denied |
1809
- | only `basicList: true` | allowed | denied | denied |
1810
- | `list: true, basicList: undefined` | allowed | allowed | allowed |
1926
+ | Rules | Basic list | Advanced list | Root list entry |
1927
+ | ------------------------------------------- | ---------- | ------------- | --------------- |
1928
+ | `list: true` | allowed | allowed | allowed |
1929
+ | `list: false` | denied | denied | denied |
1930
+ | `list: { default: true, basic: false }` | denied | allowed | allowed |
1931
+ | `list: { default: true, advanced: false }` | allowed | denied | allowed |
1932
+ | `list: { default: false, basic: true }` | allowed | denied | denied |
1933
+ | `list: { basic: true }` | allowed | denied | denied |
1934
+ | `list: { default: true, basic: undefined }` | allowed | allowed | allowed |
1935
+ | `list: { default: false, root: true }` | denied | denied | allowed |
1936
+ | `list: { default: true, root: false }` | allowed | allowed | denied |
1811
1937
 
1812
1938
  All rule values use `Validation`: `boolean | string | string[] | GuardHook`.
1813
1939
  Space-separated permission strings AND their names; arrays OR their entries.
@@ -1833,12 +1959,12 @@ acl.setGlobalOptions({
1833
1959
  });
1834
1960
  const permissionBased = {
1835
1961
  operationAccess: {
1836
- list: true,
1837
- read: true,
1838
- advancedList: 'isAdmin',
1839
- advancedRead: ['canReadDetails', 'isAdmin'],
1840
- advancedUpdate: async function (permissions) {
1841
- return permissions.has('isAdmin') && this.headers['x-write-mode'] === 'advanced';
1962
+ list: { default: true, advanced: 'isAdmin' },
1963
+ read: { default: true, advanced: ['canReadDetails', 'isAdmin'], root: false },
1964
+ update: {
1965
+ advanced: async function (permissions) {
1966
+ return permissions.has('isAdmin') && this.headers['x-write-mode'] === 'advanced';
1967
+ },
1842
1968
  },
1843
1969
  },
1844
1970
  permissionSchema: { name: { list: true, read: true } },
@@ -1857,26 +1983,28 @@ import acl, { type ModelRouterOptions } from '@web-ts-toolkit/access-router';
1857
1983
 
1858
1984
  const shorthand = { operationAccess: 'canUseApi' } satisfies ModelRouterOptions;
1859
1985
  const withDefault = {
1860
- operationAccess: { default: 'canUseApi', list: true, basicRead: false },
1986
+ operationAccess: { default: 'canUseApi', list: true, read: { basic: false } },
1861
1987
  } satisfies ModelRouterOptions;
1862
1988
 
1863
1989
  acl.setDefaultModelOptions({ operationAccess: { list: true, read: true } });
1864
- acl.setDefaultModelOption('operationAccess.advancedRead', 'isAdmin');
1865
- const defaultRead = acl.getDefaultModelOption('operationAccess.advancedRead');
1990
+ acl.setDefaultModelOption('operationAccess.read', { default: true, advanced: 'isAdmin' });
1991
+ const defaultRead = acl.getDefaultModelOption('operationAccess.read.advanced');
1866
1992
  const defaultsSnapshot = acl.getDefaultModelOptions();
1867
1993
  ```
1868
1994
 
1869
1995
  Model options use shallow assignment. Supplying an `operationAccess` object
1870
1996
  replaces that stored object rather than recursively merging default siblings.
1871
- Exact variant lookup separately falls back to the runtime's **same exact path**:
1872
- a runtime-default `advancedRead` can therefore outrank a model's `read`, `default`,
1873
- or scalar shorthand unless the model defines its own `advancedRead`.
1874
-
1875
- Defaults copied into a model's stored options stay there until updated. Changing
1876
- runtime defaults does not broadcast replacements to existing model values;
1877
- setting a stored variant to undefined can expose a live runtime-default variant
1878
- before base fallback. `getDefaultModelOption` reads the requested path exactly;
1879
- it does not resolve variant/base aliases or `operationAccess.default`.
1997
+ Exact context lookup separately falls back to the runtime's **same exact path**:
1998
+ a runtime-default `read.advanced` can outrank a model's scalar `read` or
1999
+ `read.default` unless the model defines its own `read.advanced`. This does not
2000
+ recursively merge defaults: model `read: {}` never independently inherits a runtime
2001
+ `read.default`. A whole operation inherited through existing base lookup can supply
2002
+ its own default. Clearing a context member can expose the live exact runtime default.
2003
+
2004
+ Omitted model `operationAccess` inherits configured model defaults; without grants,
2005
+ the built-in model policy denies. Explicit whole-model `operationAccess: undefined`
2006
+ permits runtime exact-operation fallback, but not a runtime bare/outer `.default`
2007
+ catch-all. `getDefaultModelOption` reads the requested path exactly, not an entry decision.
1880
2008
  `getDefaultModelOptions()` returns a frozen snapshot. Data routers use only their
1881
2009
  own options and never inherit model defaults.
1882
2010
 
@@ -1884,16 +2012,15 @@ own options and never inherit model defaults.
1884
2012
 
1885
2013
  For a basic list of `comments`, resolve:
1886
2014
 
1887
- 1. Exact `subs.comments.basicList`.
1888
- 2. Exact `subs.comments.list`.
1889
- 3. Defined `subs.comments`: evaluate a scalar guard; an object without the
1890
- applicable key **denies**, even if top-level list/variants allow.
1891
- 4. Only for an absent field rule, top-level exact `basicList`.
1892
- 5. Existing top-level base `list` fallback.
2015
+ 1. Exact `subs.comments.list.basic`, including the same-owner exact runtime default.
2016
+ 2. The field operation's scalar rule or nested `list.default`.
2017
+ 3. A field scalar supplies its operation fallback. A defined field object with no
2018
+ applicable operation/default **denies**, even if top-level list/outer default allow.
2019
+ 4. Only for an absent field rule, use the corresponding top-level operation/context.
1893
2020
 
1894
- The same ordering applies to advanced list and both read variants. No nested
1895
- `.default` fallback is introduced. Exact field lookups retain model-default
1896
- specificity; an inherited defined field also stays closed. The legacy scalar `subs` umbrella is still
2021
+ The same ordering applies to advanced/root and all field operations. Exact runtime
2022
+ specificity precedes scalar fallback. Empty field operation objects stay closed;
2023
+ `subs.comments.default` is not a field wildcard. The legacy scalar `subs` umbrella is still
1897
2024
  accepted, but **does not guard absent fields**; their fallback bypasses it and
1898
2025
  uses top-level rules. Use explicit per-field rules to guard a field.
1899
2026
 
@@ -1907,7 +2034,7 @@ const subdocumentRules = {
1907
2034
  list: true,
1908
2035
  read: true,
1909
2036
  subs: {
1910
- comments: { list: true, read: true, basicList: false, advancedRead: 'isAdmin' },
2037
+ comments: { list: { default: true, basic: false }, read: { default: true, advanced: 'isAdmin', root: false } },
1911
2038
  // Closed object: both items list routes are denied despite top-level list: true.
1912
2039
  items: { read: true },
1913
2040
  attachments: 'isAdmin',
@@ -1928,36 +2055,36 @@ import acl from '@web-ts-toolkit/access-router';
1928
2055
  // User must already be registered with this runtime.
1929
2056
  const router = acl.createRouter('User', {
1930
2057
  basePath: '/users',
1931
- operationAccess: { list: true, read: true },
2058
+ operationAccess: { list: { default: true }, read: { default: true } },
1932
2059
  permissionSchema: { name: true },
1933
2060
  });
1934
2061
 
1935
- router.operationAccess('basicRead', false); // Update one key, keep list/read rules.
1936
- router.operationAccess('subs.comments.basicRead', false);
1937
- router.set('operationAccess.advancedList', 'isAdmin');
1938
- router.setOption('operationAccess.basicRead', undefined); // Restore inheritance.
1939
- acl.setModelOption('User', 'operationAccess.basicRead', false);
2062
+ router.operationAccess('read.basic', false); // Update one member, keep list/read defaults.
2063
+ router.operationAccess('subs.comments.read.basic', false);
2064
+ router.set('operationAccess.list.advanced', 'isAdmin');
2065
+ router.setOption('operationAccess.read.basic', undefined); // Restore fallback.
2066
+ acl.setModelOption('User', 'operationAccess.read.root', false);
1940
2067
 
1941
2068
  // All object forms replace the whole operationAccess object, not a deep merge.
1942
- router.operationAccess({ list: true, read: true, basicRead: false });
1943
- router.setOptions({ operationAccess: { list: true, read: true, advancedList: false } });
2069
+ router.operationAccess({ list: true, read: { default: true, basic: false } });
2070
+ router.setOptions({ operationAccess: { list: { default: true, advanced: false }, read: true } });
1944
2071
 
1945
2072
  const current = router.runtime.getModelOptions('User');
1946
- const exactVariant = router.runtime.getExactModelOption('User', 'operationAccess.basicRead');
2073
+ const exactVariant = router.runtime.getExactModelOption('User', 'operationAccess.read.basic');
1947
2074
  ```
1948
2075
 
1949
2076
  `set({ operationAccess: ... })` and `setOption('operationAccess', ...)` have the
1950
2077
  same shallow replacement semantics. Dotted paths are setter arguments, not flat
1951
2078
  properties in constructor options. Updating a nested path under a scalar shorthand
1952
2079
  starts an object; retain a `default` rule if you want the prior broad fallback.
1953
- Use `set`/`setOption` with undefined to clear a variant; the two-argument property
1954
- helper is intended for defined values.
2080
+ Use any two-argument member setter with undefined to clear that member. Whole-operation
2081
+ setters accept a scalar or a rule object, e.g. `operationAccess('read', { default: true, root: false })`.
1955
2082
 
1956
2083
  `router.options` is the frozen **construction-time** snapshot. Options getter
1957
2084
  results are also frozen snapshots; data native-valued properties return detached copies
1958
2085
  on access as described above. Fetch again for current stored values. Ordinary
1959
2086
  `getModelOption`/`getDataOption` use generic nested-option fallback, not the
1960
- route-specific variant-to-base resolver. Exact getters inspect the variant path
2087
+ final nested operation-entry resolver and can return a raw operation object. Exact getters inspect a member path
1961
2088
  (including exact model-default fallback). Request guards read live runtime values.
1962
2089
  Data router setters use the same forms; its owning runtime provides
1963
2090
  `setDataOption`, `getDataOptions`, and `getExactDataOption`.
@@ -1968,22 +2095,26 @@ Data router setters use the same forms; its owning runtime provides
1968
2095
  checks retain base accesses. A variant grant does not grant fields or bypass
1969
2096
  target authorization.
1970
2097
  - Model `_read`/`_readFilter` misses with `tryList: true` still require **base
1971
- `list`** to retry. `list: false, advancedList: true` cannot grant retry;
1972
- `list: true, basicList: false` cannot block it. Forbidden/BadRequest never retry.
1973
- - Upsert keeps its create/update branch policy; authorizing `advancedUpsert` does
1974
- not also require `advancedCreate` or `advancedUpdate`.
2098
+ `list` scalar/default** to retry. `list: { default: false, advanced: true }` cannot grant retry;
2099
+ `list: { default: true, basic: false }` cannot block it. Forbidden/BadRequest never retry.
2100
+ - Upsert keeps its create/update branch policy; authorizing `upsert.advanced` does
2101
+ not also require `create.advanced` or `update.advanced`.
1975
2102
  - Subdocument mutation-response visibility uses base parent/subdocument read/list
1976
2103
  checks. Disabling basic reads does not hide otherwise readable output. Base
1977
2104
  response denial can still yield a successful null/empty response after a write
1978
2105
  (see [Subdocument writes with hidden responses](#subdocument-writes-with-hidden-responses)).
1979
- - Root batches use existing operation names and target base entry checks, with
1980
- entry 401 inside the HTTP 200 batch envelope. Variants are not new root `op`
2106
+ - Root batches use existing operation names and target `root` entry checks, with
2107
+ entry 401 inside the HTTP 200 batch envelope. Context members are not new root `op`
1981
2108
  values. Direct service calls remain trusted application calls with their
1982
- existing checks; they do not infer basic/advanced access from `req.method`.
2109
+ existing checks; they do not infer entry context from `req.method` or gain blanket entry guards.
2110
+ - Existing populate/include/private-dependency checks use operation scalar/default
2111
+ when target flags require admission. A target `{ default: false, root: true }`
2112
+ grants root entry only, not context-free related admission. Flags and trusted-service
2113
+ bypasses remain unchanged; secondary checks never implicitly choose transport members.
1983
2114
 
1984
2115
  **Populate selectors:** wire `options.populateAccess` and descriptor `access`
1985
2116
  accept only `'list' | 'read'` (`PopulateAccess` from `/advanced`). The shared Core
1986
- populate boundary also rejects all fourteen reserved variant names in effective
2117
+ populate boundary also rejects retired flat names and reserved nested context-member paths in effective
1987
2118
  option/descriptor access, including generic options forwarded by legacy includes
1988
2119
  and subqueries, before target persistence. Other trusted, non-reserved custom
1989
2120
  access strings keep their existing runtime behavior. Invalid selectors return
@@ -1993,7 +2124,7 @@ omitting it, so nested invalid selectors cannot disappear from the result.
1993
2124
 
1994
2125
  ### Runnable data-router split
1995
2126
 
1996
- This database-free example exercises the same four data keys after installation:
2127
+ This database-free example exercises nested data read members after installation:
1997
2128
 
1998
2129
  <!-- doc-example: complete-runtime -->
1999
2130
 
@@ -2008,7 +2139,7 @@ const router = runtime.createDataRouter('VariantFruit', {
2008
2139
  idParam: 'id',
2009
2140
  idField: 'id',
2010
2141
  data: [{ id: 'apple', name: 'Apple' }],
2011
- operationAccess: { list: true, read: true, basicRead: false },
2142
+ operationAccess: { list: true, read: { default: true, basic: false } },
2012
2143
  permissionSchema: { id: true, name: true },
2013
2144
  });
2014
2145
  const app = express();
@@ -2029,7 +2160,7 @@ try {
2029
2160
  if (basic.status !== 401 || advanced.status !== 200) throw new Error('Read split failed');
2030
2161
  const fruit = await advanced.json();
2031
2162
  if (fruit.name !== 'Apple') throw new Error('Expected the authorized fruit');
2032
- router.operationAccess('basicRead', true);
2163
+ router.operationAccess('read.basic', true);
2033
2164
  if ((await fetch(`${url}/apple`)).status !== 200) throw new Error('Live update failed');
2034
2165
  } finally {
2035
2166
  await new Promise<void>((resolve, reject) => {
@@ -2056,8 +2187,13 @@ Two router options lock down permission metadata regardless of client input or
2056
2187
  per-operation `defaults`: `stripPermissionsField: true` removes the whole
2057
2188
  permissions field from outputs (equivalent to `includePermissions: false` with
2058
2189
  the field — including its placeholder — deleted; enforcement still runs), and
2059
- `disableFieldPermissions: true` never computes `_view`/`_edit` maps while still
2060
- honoring `includePermissions` for `docPermissions`-hook keys.
2190
+ `disableFieldPermissions: true` (the default) neither computes nor emits
2191
+ `_view`/`_edit` maps (including placeholders) while still honoring `includePermissions` for
2192
+ `docPermissions`-hook keys. When no keys are included, the permissions field is
2193
+ an empty object; use `stripPermissionsField: true` to remove it entirely. This
2194
+ applies to regular model routes, root batch items, and direct service calls. Set
2195
+ `disableFieldPermissions: false` on the model or runtime model defaults to opt in
2196
+ to field maps; `includeFieldPermissions` then controls whether they are requested.
2061
2197
 
2062
2198
  ## Main Exports
2063
2199
 
@@ -2073,7 +2209,7 @@ Root entrypoint (`@web-ts-toolkit/access-router`):
2073
2209
  - `permissionsPlugin` — optional Mongoose metadata alias; [role and usage](#optional-permissions-plugin)
2074
2210
  - logger helpers: `redactFilter`, `redactPayload`, `safeStringify`, `isLevelEnabled` + `OpLogContext` type
2075
2211
  - option helpers: `setGlobalOptions`, `setGlobalOption`, `getGlobalOptions`, `getGlobalOption`, `setModelOptions`, `setModelOption`, `getModelOptions`, `getModelOption`, `getModelNames`, `getModelJsonSchema`, `setDefaultModelOptions`, `setDefaultModelOption`, `getDefaultModelOptions`, `getDefaultModelOption`
2076
- - route-policy types: `OperationAccess`, `SubOperationAccess`, `Validation`, `GuardHook`, `RouteVariantAccess`, `ModelRouterOptions`, `DefaultModelRouterOptions`, `DataRouterOptions`, `ExtendedModelRouterOptions`, `ExtendedDefaultModelRouterOptions`, and `ExtendedDataRouterOptions` for typed setters; `PermissionSchema` / `FieldOperationAccess` are separate base-operation field grants. These types are also available from `/advanced`.
2212
+ - route-policy types: `OperationAccess`, `SubOperationAccess`, `OperationAccessContext`, `OperationAccessVariants`, `OperationAccessRule`, `OperationAccessPaths`, `OperationAccessSetter`, `Validation`, `GuardHook`, `ModelRouterOptions`, `DefaultModelRouterOptions`, `DataRouterOptions`, `ExtendedModelRouterOptions`, `ExtendedDefaultModelRouterOptions`, and `ExtendedDataRouterOptions` for typed setters; `PermissionSchema` / `FieldOperationAccess` are separate base-operation field grants. These types are also available from `/advanced`.
2077
2213
  - fetch configuration types (also `/advanced`): `HydrationMode`, `ModelHydrationOptions` — server-owned model/default configuration, never per-call/wire options.
2078
2214
  - virtual types (also `/advanced`): `ModelVirtualGetter`, `ModelVirtualDescriptor`, `ModelVirtualAccessRecord`, `ModelVirtualLeaf`, `ModelVirtuals`, `ModelVirtualDoc`, `ModelVirtualContext`, `ModelVirtualPopulateDependency`, `ModelVirtualPopulateInputs`. Explicit private target maps type only the fourth getter argument; see [Private populated dependencies](#private-populated-dependencies).
2079
2215
  - trusted service policy types (also `/advanced`): `ServiceAuthorization` (reads), `MutationAuthorization` (update/upsert), `CreateAuthorization`, `InputFieldAuthorization`, `InputFieldPath`, `OutputAuthorization`, `FieldAuthorization`, `RowAuthorization`, `OperationAuthorization`, `RelatedAuthorization`, `OutputFieldPath`. Input paths use persisted types only; output paths also include virtuals. Unknown models have an explicit runtime-validated string fallback; grant arrays may be readonly.