@web-ts-toolkit/access-router 0.64.0 → 0.65.1

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/llms.txt CHANGED
@@ -18,7 +18,8 @@
18
18
  - [Names with different jobs](README.md#names-with-different-jobs) · [skim: deprecated compatibility no-op](README.md#skim-compatibility-no-op)
19
19
  - [Runtime isolation and nullish grants](README.md#default-runtime-vs-isolated-runtime) · [Factory overloads](README.md#createrouter-overloads) · [Optional raw-document metadata getter](README.md#optional-permissions-plugin)
20
20
  - [Operation matrix and fallback](README.md#basic-and-advanced-operation-access) · [Live setters](README.md#live-updates-and-option-snapshots)
21
- - [Unsafe comparison switches](README.md#temporary-unsafe-readlist-performance-switches) · [Initial output-copy opt-outs](README.md#temporary-unsafe-initial-output-snapshot-copy-switches): six comparison flags plus two independent default-false `unsafeSkipListInitialOutputSnapshotCopy` / `unsafeSkipReadInitialOutputSnapshotCopy` server model/default options. Copy omission requires the corresponding OutputSnapshotChecks skip; otherwise dormant and still copies/compares. READ retries and authenticated descendants retain the origin's captured mode. Bounded shape admission and exact ownership/graph identities remain, but native/BSON normalization/wire-validation observations are omitted and can change authorization outcomes. Proxies/Map/Set/unproven graphs use copy fallback. Source/configuration/callback/grant/getter/response copies remain; no general clone bypass or client/per-call authority. Warns on active/dormant transitions; rollback affects new calls only. See the prerequisite table and per-model example before opting in.
21
+ - [Unsafe comparison switches](README.md#temporary-unsafe-readlist-performance-switches) · [Initial output-copy opt-outs](README.md#temporary-unsafe-initial-output-snapshot-copy-switches): original six comparison/two copy groups keep their independent contracts with the matching new authorization fast-path flag OFF (or dormant). Copy omission requires the corresponding OutputSnapshotChecks skip; otherwise dormant and still copies/compares. READ retries/authenticated descendants retain origin capture. Bounded shape admission/exact graph identities and detached source/callback/grant/getter/response copies remain in that original mode; native/BSON normalization/wire observations can be omitted and change outcomes. Proxies/Map/Set/unproven graphs may copy. Server model/default literal-true only; no client/per-call authority. See the prerequisite table before opting in.
22
+ - [Experimental unsafe READ/LIST authorization fast paths](README.md#experimental-unsafe-readlist-authorization-fast-paths) · [Runnable LIST/READ prerequisites, rollback and handle warnings](README.md#runnable-listread-prerequisites-rollback-and-handle-warnings): third independent optional boolean pair `unsafeUseListAuthorizationFastPath` / `unsafeUseReadAuthorizationFastPath`, default false, literal server true only. Each needs ALL FOUR matching DocumentSnapshotChecks/OutputSnapshotChecks/NestedDocumentSnapshotChecks/InitialOutputSnapshotCopy skips; false is off, true with any missing is dormant, never auto-enables prerequisites. READ-to-list retries remain READ; genuine related/embedded stages inherit origin capture before hooks/awaits, independent calls own theirs. Active ordinary lean source/hook input, grants and shallow diagnostic context leaves are borrowed; captured config/scope views reused. No trusted stage snapshot/current-descendant walk. Exact root/tuple checks and issued-document membership remain: removed original children may still be found, replacements get no handle, root helpers filter current values with stale memo/shared grants even after rollback. Rules/row/target gates/original actor/mandatory per-root/target hooks/getters remain; unrelated rows/targets do not cache by ID. Copied rows/grants/value fallbacks, hydration/getter document views/return staging/private argument-four isolation/JSON normalization remain; not every row zero-copy or a general clone bypass. New selected work has 20,000-slot/issued-root and depth-100 budgets, not full unvisited source/grant/context bounds. Mutation/stale decisions/descendant replacement/lost native observations can turn denial into allowance. Writes/write-derived output/dedicated subdocuments/fresh raw helpers strict; control-slot presence rejects, business fields inert. Explicit model false overrides defaults, undefined restores inheritance. Warns active/dormant/missing transitions; rollback only new calls, and original skip flags require separate restoration. Experimental performance-first: benchmark your workload, no universal gain, security equivalence or v0.51.0 parity; no publication-fusion API.
22
23
  - [Data list/read](README.md#data-routers) · [Data ownership/native values](README.md#in-memory-data-ownership) · [Runnable data example](README.md#runnable-data-router-split)
23
24
  - [Root batches: maxOrderGroups bounds both group count and numeric order](README.md#root-batch-bounds)
24
25
  - [Request validation and OpenAPI](README.md#request-validation-and-openapi) · [AJV sync/async contract](README.md#ajv-validation-contract)
@@ -29,7 +30,7 @@
29
30
  - [Fixed/related modes and value caveat](README.md#breaking-release-server-owned-hydration): includes/post-save subdocument visibility stay lean; raw parents/lifecycle documents stay hydrated; $$sq uses target public configuration; populate inherits its parent query. Plain finalized results do not imply identical schema defaults/getters/transforms/init-hook values or a measured speedup.
30
31
  - [Finalized permissions alias](README.md#finalized-permissions-alias): non-enumerable value alias to already-exposed canonical metadata, including dotted paths, independent of hydration/plugin. Stripping suppresses it; business/virtual/include collisions win. Package copies preserve it where metadata exists; no metadata synthesis or arbitrary-copy/client-wrapper promise. The optional Mongoose raw getter is separate.
31
32
  - [Trusted service authorization](README.md#trusted-service-authorization) · [Request admission](README.md#public-request-admission-and-backend-options): policy is server-only; wire/default control slots reject it.
32
- - [Selection, grants and document handles](README.md#selection-grants-and-document-results) · [Runnable Mongo authorization example](README.md#runnable-authorization-and-handle-reuse)
33
+ - [Selection, grants and document handles](README.md#selection-grants-and-document-results) · [Runnable Mongo authorization example](README.md#runnable-authorization-and-handle-reuse): default/copied handles validate unchanged graphs; active trusted handles retain only exact root authority/issued membership and borrowed context/grants. Fresh raw policy is not retained-handle authority.
33
34
  - [Independent mutation input](README.md#independent-mutation-input-authority) · [Scoped subdocuments](README.md#dedicated-subdocument-authorization) · [Successful hidden-write responses](README.md#subdocument-writes-with-hidden-responses)
34
35
  - [Row scope vs query transformation](README.md#backend-row-authorization-and-filter-migration) · [Denial vs miss](README.md#denial-and-request-validation) · [Whole-value distinct](README.md#distinct-whole-value-request-authorization)
35
36
  - [Removed overrides migration](README.md#breaking-release-service-overrides-migration) · [Named helper migration and data compatibility](README.md#breaking-release-named-helpers-and-default-behavior)
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@web-ts-toolkit/access-router",
3
3
  "description": "ACL-aware Express routers and in-memory data services for Mongoose-backed APIs",
4
4
  "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/access-router",
5
- "version": "0.64.0",
5
+ "version": "0.65.1",
6
6
  "sideEffects": [
7
7
  "./**/index.js",
8
8
  "./**/index.mjs",
@@ -57,8 +57,8 @@
57
57
  "node": ">=22"
58
58
  },
59
59
  "dependencies": {
60
- "@web-ts-toolkit/express-json-router": "0.64.0",
61
- "@web-ts-toolkit/utils": "0.64.0",
60
+ "@web-ts-toolkit/express-json-router": "0.65.1",
61
+ "@web-ts-toolkit/utils": "0.65.1",
62
62
  "just-diff": "^6.0.2",
63
63
  "mongoose-schema-jsonschema": "^4.0.1",
64
64
  "sift": "^17.1.3",
@@ -378,6 +378,11 @@ type ModelValidateHook = ValidateHook<ModelRequest>;
378
378
  * with alwaysSelectFields. Integrated output resolves once per document/access stage,
379
379
  * independently of skim or metadata serialization; use the result's document handle
380
380
  * for later picks after input/metadata trim. Backend grants do not forge user metadata.
381
+ * With an active unsafe READ/LIST authorization fast path, ordinary lean projected
382
+ * input and the returned grant map are borrowed; field decisions/reads/owning embedded
383
+ * children share grants and context leaves. Mutation across callbacks/awaits can turn
384
+ * denial into allowance. Shallow-unproven inputs/grants may copy once without rerunning
385
+ * the hook. Off/dormant calls retain their existing copying behavior.
381
386
  */
382
387
  type ModelDocPermissionsHook = DocPermissionsHook<ModelRequest>;
383
388
  type ModelChangeHook = ChangeHook<ModelRequest>;
@@ -409,6 +414,9 @@ type ModelVirtualRecordAccess = 'default' | ModelVirtualAccess;
409
414
  * permissions, selection, and effective access before parent getters run.
410
415
  * Declaration-scoped private inputs use the getter's fourth argument, never
411
416
  * this context or its document-authorization metadata.
417
+ * Active unsafe query fast paths retain separate getter document views, but diagnostic
418
+ * context/grant/native leaves may alias across callbacks; this context is not an
419
+ * immutable authority snapshot or a place to set server options.
412
420
  */
413
421
  interface ModelVirtualContext extends ModelHookContext {
414
422
  receivingModelName: string;
@@ -504,6 +512,10 @@ type ModelVirtualPopulateInputs<TModel = unknown, TPopulated extends VirtualPopu
504
512
  * present null/empty refs and missing target rows yield null/[]/null array slots.
505
513
  * Private values are not implicitly transported to output or authorization metadata;
506
514
  * an authorized getter can deliberately return a computed value using them.
515
+ * Even in an active unsafe authorization fast path, the stable base, separate
516
+ * per-getter document views, return staging and private argument-four isolation remain.
517
+ * Context/grant leaves can still be borrowed and mutate later decisions; document-view
518
+ * isolation does not restore source/grant/context or descendant-integrity guarantees.
507
519
  */
508
520
  type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends VirtualPopulateMap<TModel, TPopulated> = Record<never, never>> = (this: ModelRequest, doc: ModelVirtualDoc<TModel>, permissions: AccessRouterPermissions, context: ModelVirtualContext, populated?: ModelVirtualPopulateInputs<TModel, TPopulated>) => MaybePromise<TValue | undefined>;
509
521
  /**
@@ -513,13 +525,15 @@ type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends V
513
525
  * `['contacts.sub.displayName']`). Dotted paths and virtual-to-virtual
514
526
  * dependencies are rejected at configuration time.
515
527
  *
516
- * The getter runs after `toObject()`/lean normalization and after internal
528
+ * The getter runs after hydrated `toObject()` where applicable and after internal
517
529
  * document-permissions computation, with global permissions available and
518
530
  * before `decorate`/`decorateAll`/tasks. Only the returned field value is
519
531
  * committed via document-aware helpers: `undefined` (or a throw) omits the
520
532
  * field fail-closed and computed values never persist. Getters see an
521
533
  * isolated plain-object view for both lean and hydrated results; mutating the
522
534
  * input has no implicit effect on response data or lifecycle snapshots.
535
+ * Off/dormant results retain whole lean-source normalization; active trusted queries
536
+ * omit that authorization pass, not the separate getter views/private-input isolation.
523
537
  *
524
538
  * Annotate a descriptor separately with `TPopulated` to type its private fourth
525
539
  * getter argument, then assign it to ordinary `ModelVirtuals`. The optional
@@ -749,6 +763,7 @@ declare class AccessRuntime {
749
763
  private publishDefaultModelOptions;
750
764
  private warnSnapshotFlag;
751
765
  private deferSnapshotWarnings;
766
+ private authorizationFastPathModes;
752
767
  private initialOutputCopyModes;
753
768
  private createModelOptions;
754
769
  private getOrCreateModelOptions;
@@ -1045,13 +1060,16 @@ type OutputAuthorization<TModel = unknown, TVirtuals extends object = Record<nev
1045
1060
  declare const documentAuthorizationBrand: unique symbol;
1046
1061
  /**
1047
1062
  * Package-issued same-execution output handle, authenticated by private runtime state.
1048
- * Bound to request/runtime/model, projected document snapshot, scope and access stage.
1063
+ * Bound to request/runtime/model, scope and access stage. Default/copied records also
1064
+ * bind a projected document snapshot and exact output graph; active trusted records
1065
+ * instead have exact root association and issued-document membership, no stage snapshot.
1049
1066
  * Obtain it from an internal result context, never from DTO metadata or JSON. It is
1050
1067
  * an opaque consumer handle, not a constructor, reusable call policy or wire token.
1051
1068
  * It reuses full document grants and memoized decisions after ownerId/private inputs
1052
- * and permission metadata are trimmed. Use the original unchanged output or a
1053
- * package-created helper subset; caller spreads, matching IDs, changed values, another
1054
- * row/call/access or pre-/post-write stages cannot establish validity and reject.
1069
+ * and permission metadata are trimmed. Use the original associated root or a
1070
+ * package-created helper subset; caller spreads, matching IDs, another row/call/access
1071
+ * or pre-/post-write stages cannot establish validity and reject. Default/copied records
1072
+ * additionally reject graph changes; the active trusted contract below deliberately does not.
1055
1073
  * A list/read handle with its server unsafeSkipListDocumentSnapshotChecks or
1056
1074
  * unsafeSkipReadDocumentSnapshotChecks flag enabled retains that weakened source-
1057
1075
  * mutation policy; independent output-value/ownership checks still apply. Turning a setting
@@ -1067,19 +1085,36 @@ declare const documentAuthorizationBrand: unique symbol;
1067
1085
  * and exact graph ownership, but omit this pass's native/BSON normalization and
1068
1086
  * validation observations. Source/callback/grant copies remain detached; unproven
1069
1087
  * graphs or open ownership bindings fall back to copying. Retained handles keep this mode.
1088
+ * These are the original flags' contracts alone. A genuinely active
1089
+ * unsafeUseListAuthorizationFastPath/unsafeUseReadAuthorizationFastPath trusted row
1090
+ * instead borrows source/grants/context leaves and keeps only exact root authority,
1091
+ * not descendant graph integrity. Its handle filters current values with potentially
1092
+ * stale decisions/shared grants after descendant replacement. Removed issued children
1093
+ * can remain discoverable; replacements/spreads/other rows receive no child authority.
1094
+ * Copied fallback records keep graph checks; fresh raw-policy helpers remain strict.
1095
+ * Rollback changes new calls only: an issued trusted handle does not regain stronger
1096
+ * protections. Its mutable grant/context leaves may be borrowed between callbacks;
1097
+ * changed native observations or stale decisions can turn denial into allowance.
1070
1098
  */
1071
1099
  interface DocumentAuthorization {
1072
1100
  readonly [documentAuthorizationBrand]: true;
1073
1101
  }
1074
- /** Internal output context; public serializers omit it and no authority is attached to data. */
1102
+ /**
1103
+ * Internal output context; public serializers omit it and no authority is attached to data.
1104
+ * Active trusted queries use shallow diagnostic shells with borrowed source/grant leaves;
1105
+ * snapshot-named properties are not detached immutable snapshots in that mode.
1106
+ */
1075
1107
  interface ServiceOutputContext extends ModelHookContext {
1076
1108
  /** Non-enumerable, non-writable handle for this output row/scope/access stage. */
1077
1109
  readonly documentAuthorization: DocumentAuthorization;
1078
1110
  /**
1079
- * Look up an exact unchanged value in this result's output graph, including
1080
- * registered embedded/related copies. Unknown/stale values return undefined;
1111
+ * Default/copied result: look up an exact unchanged value in its output graph,
1112
+ * including registered embedded/related copies. Unknown/stale values return undefined;
1081
1113
  * scalar IDs/null/counts have no child handle. Pass a related handle to that
1082
1114
  * target model's helper at its output access. This method cannot issue new authority.
1115
+ * For an active trusted query root, lookup is fixed issued-document membership,
1116
+ * not current reachability: a removed original child can still be found and a
1117
+ * replacement cannot. Root/request/runtime/model/scope/access checks still apply.
1083
1118
  */
1084
1119
  getDocumentAuthorization(output: object): DocumentAuthorization | undefined;
1085
1120
  }
@@ -1113,7 +1148,7 @@ interface OutputPlanningOptions<TModel = unknown, TVirtuals extends object = Rec
1113
1148
  /**
1114
1149
  * Mutually exclusive named output filtering inputs: raw policy OR an issued handle.
1115
1150
  * Raw-policy evaluation (including `{}` for request mode) is a fresh call; only an
1116
- * issued handle reuses full document decisions from the immutable original call.
1151
+ * issued handle reuses full document decisions from the captured original call.
1117
1152
  * A fresh unassociated document needs suitable untrimmed projected hook inputs.
1118
1153
  * On recognized trimmed output, fresh evaluation retains unconditional request fields
1119
1154
  * and explicit grants but denies unresolved document-dependent rules without rerunning
@@ -1123,6 +1158,10 @@ interface OutputPlanningOptions<TModel = unknown, TVirtuals extends object = Rec
1123
1158
  * virtual getters, absent-value restoration, row checks or write grants. Omitted or
1124
1159
  * undefined options equal {} (fresh request-mode output), including on hydrated docs,
1125
1160
  * which are isolated rather than mutated. Positional baseFields have been removed.
1161
+ * A trusted fast-path handle filters current values with stale memo/shared grants and
1162
+ * remains usable on its exact associated root after descendant replacement/rollback;
1163
+ * it is not a current-graph or detached-callback-context guarantee. Fresh raw helpers
1164
+ * never acquire that weaker issued mode from server flags or DTO metadata.
1126
1165
  */
1127
1166
  type OutputFieldOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> = (OutputPlanningOptions<TModel, TVirtuals> & {
1128
1167
  readonly documentAuthorization?: never;
@@ -1214,6 +1253,8 @@ interface AuthorizationConfiguration {
1214
1253
  readonly unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
1215
1254
  readonly unsafeSkipListInitialOutputSnapshotCopy?: boolean;
1216
1255
  readonly unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
1256
+ readonly unsafeUseListAuthorizationFastPath?: boolean;
1257
+ readonly unsafeUseReadAuthorizationFastPath?: boolean;
1217
1258
  /** Opaque terminal private-input capture. Never related authority or public document metadata. */
1218
1259
  readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
1219
1260
  /** Held runtime model defaults, distinct from this model's resolved flags. */
@@ -1429,6 +1470,10 @@ declare class Service<TModel = unknown, TVirtuals extends object = Record<never,
1429
1470
  private requestSortFields;
1430
1471
  /** One output stage per row, independent of metadata and of pre-write admission. */
1431
1472
  private finalizeDirectOutput;
1473
+ /** Same modern finalizer/evaluators; source/grants/attachments are borrowed only by authenticated trusted rows. */
1474
+ private finalizeTrustedDirectOutput;
1475
+ /** Actual correlated inputs only, not an unconditional whole-source diagnostic snapshot. */
1476
+ private captureTrustedCorrelatedSource;
1432
1477
  private getEffectiveAllowedSortFields;
1433
1478
  /**
1434
1479
  * With `requireExplicitSelect`, an omitted client select behaves as an
@@ -2386,10 +2431,18 @@ interface Change {
2386
2431
  path: Array<string | number>;
2387
2432
  value?: unknown;
2388
2433
  }
2434
+ /**
2435
+ * Callback diagnostics, not a server-option or authority token. In an active unsafe
2436
+ * READ/LIST authorization fast path, shells are shallow and source/grant/native leaves
2437
+ * may be borrowed across callbacks/scopes. Snapshot-named properties do not promise
2438
+ * detached immutable values in that mode. Mutations can affect later values/decisions;
2439
+ * do not use this context to change captured operation/row authority or work limits.
2440
+ */
2389
2441
  interface ModelHookContext {
2390
2442
  modelName: string;
2391
2443
  mongooseModel: mongoose__default.Model<unknown>;
2392
2444
  operation?: string;
2445
+ /** Diagnostic source view; active trusted queries borrow it rather than deep-snapshotting it. */
2393
2446
  originalDocumentSnapshot?: Record<string, unknown>;
2394
2447
  finalDocumentSnapshot?: Record<string, unknown>;
2395
2448
  currentDocument?: ModelDocument;
@@ -2399,6 +2452,7 @@ interface ModelHookContext {
2399
2452
  allowedFields?: string[];
2400
2453
  modifiedPaths?: string[];
2401
2454
  changes?: Change[];
2455
+ /** Full hook grants; ordinary active trusted grants are shared, not isolated per callback/read. */
2402
2456
  docPermissions?: KeyValue;
2403
2457
  resolvedQuery?: {
2404
2458
  filter?: Filter;
@@ -3557,6 +3611,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3557
3611
  * Use only with trusted non-mutating application hooks, measure before rollout, and
3558
3612
  * restore `false` as soon as possible. Enabling logs a warning once per model transition.
3559
3613
  * Server model configuration only, never service.defaults, per-call or wire options.
3614
+ * Retained isolation guarantees here describe this flag alone, not the active
3615
+ * trusted runtime for unsafeUseListAuthorizationFastPath.
3560
3616
  */
3561
3617
  unsafeSkipListDocumentSnapshotChecks?: boolean;
3562
3618
  /**
@@ -3574,6 +3630,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3574
3630
  * read-like output) and fresh helpers stay strict. Warns per model/flag transition.
3575
3631
  * Server model or inherited model-default configuration only; never method defaults
3576
3632
  * or wire options.
3633
+ * Retained isolation guarantees describe this flag alone, not the active
3634
+ * trusted runtime for unsafeUseReadAuthorizationFastPath.
3577
3635
  */
3578
3636
  unsafeSkipReadDocumentSnapshotChecks?: boolean;
3579
3637
  /**
@@ -3587,6 +3645,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3587
3645
  * in server model/default configuration enables it and warns on effective transition.
3588
3646
  * READ/retries use unsafeSkipReadOutputSnapshotChecks; writes and fresh helpers stay
3589
3647
  * strict. Never set from request/per-call/method defaults. Revisit/remove promptly.
3648
+ * Retained copy/graph guarantees describe this flag alone, not the active
3649
+ * trusted runtime for unsafeUseListAuthorizationFastPath.
3590
3650
  */
3591
3651
  unsafeSkipListOutputSnapshotChecks?: boolean;
3592
3652
  /**
@@ -3597,6 +3657,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3597
3657
  * decisions; exact ownership/graph identities and permissions still run. Server
3598
3658
  * model/default literal `true` only; warns on effective enablement. Retained handles
3599
3659
  * keep their mode. Writes/fresh helpers stay strict. Revisit/remove promptly.
3660
+ * Retained copy/graph guarantees describe this flag alone, not the active
3661
+ * trusted runtime for unsafeUseReadAuthorizationFastPath.
3600
3662
  */
3601
3663
  unsafeSkipReadOutputSnapshotChecks?: boolean;
3602
3664
  /**
@@ -3610,6 +3672,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3610
3672
  * enables it; warns on transition. Rollback affects new calls, not captured descendants
3611
3673
  * or handles. READ uses its own flag; writes, dedicated subdocument operations and
3612
3674
  * fresh helpers stay strict. Never derive from requests. Revisit/remove promptly.
3675
+ * Retained copy/graph guarantees describe this flag alone, not the active
3676
+ * trusted runtime for unsafeUseListAuthorizationFastPath.
3613
3677
  */
3614
3678
  unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
3615
3679
  /**
@@ -3622,6 +3686,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3622
3686
  * remain. Server model/default literal `true` only; warns on effective enablement.
3623
3687
  * Writes/dedicated subdocument operations/fresh helpers stay strict; retained handles
3624
3688
  * keep their mode after rollback. Never set from requests. Revisit/remove promptly.
3689
+ * Retained copy/graph guarantees describe this flag alone, not the active
3690
+ * trusted runtime for unsafeUseReadAuthorizationFastPath.
3625
3691
  */
3626
3692
  unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
3627
3693
  /**
@@ -3636,6 +3702,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3636
3702
  * only; warns on activation. Captured before awaits; retained handles keep their
3637
3703
  * mode after rollback. READ/retries use their own flag; writes/fresh helpers stay
3638
3704
  * strict. Restore false promptly; never select from requests or method defaults.
3705
+ * Retained copy/shape/graph guarantees describe this flag alone, not the active
3706
+ * trusted runtime for unsafeUseListAuthorizationFastPath.
3639
3707
  */
3640
3708
  unsafeSkipListInitialOutputSnapshotCopy?: boolean;
3641
3709
  /**
@@ -3648,8 +3716,118 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3648
3716
  * remain. Proxies/Map/Set fall back to copying. Server model/default literal true
3649
3717
  * only; warns on activation/dormancy. Writes/fresh helpers stay strict. Captured
3650
3718
  * handles do not change on rollback. Never derive from requests; restore false.
3719
+ * Retained copy/shape/graph guarantees describe this flag alone, not the active
3720
+ * trusted runtime for unsafeUseReadAuthorizationFastPath.
3651
3721
  */
3652
3722
  unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
3723
+ /**
3724
+ * EXPERIMENTAL performance-first UNSAFE, default `false`; literal server model/default `true` only. LIST authorization
3725
+ * fast path requires ALL FOUR matching unsafeSkipListDocumentSnapshotChecks,
3726
+ * unsafeSkipListOutputSnapshotChecks, unsafeSkipListNestedDocumentSnapshotChecks and
3727
+ * unsafeSkipListInitialOutputSnapshotCopy options to be literal true. Otherwise dormant:
3728
+ * the original flags keep their independent behavior. Never enables prerequisites.
3729
+ * Explicit false overrides model defaults; undefined restores inheritance.
3730
+ *
3731
+ * Captured before hooks/awaits on find/public/root LIST origins; authenticated
3732
+ * embedded/populated/included outputs and issued handles retain that origin's mode
3733
+ * after rollback, not live target settings. Independent calls capture their own mode.
3734
+ * Independent READ queries/retries use unsafeUseReadAuthorizationFastPath. Writes,
3735
+ * write-derived output, new/create/update/upsert/delete, dedicated subdocuments and
3736
+ * fresh raw-policy helpers do not apply.
3737
+ * Never accepted in method defaults, per-call, policy, helper or wire controls.
3738
+ *
3739
+ * Eligible rows borrow projected source and ordinary hook grants, use shallow contexts,
3740
+ * and omit repeated snapshots, defensive isolation and descendant graph verification.
3741
+ * The trusted runtime retains operation/row/field rules, document hooks/getters,
3742
+ * cheap exact root binding and issued-handle membership, NOT detached source/grant/context
3743
+ * leaves or full descendant integrity. Borrowed values/grants/context, stale decisions,
3744
+ * descendant replacement and fewer native normalization/validation observations can
3745
+ * change outcomes, including denial becoming allowance. Full unvisited per-document
3746
+ * shape/bounds are lost; request/work and bounded new output-materialization limits
3747
+ * remain. Not a full ACL bypass or security-equivalent optimization. Warns on effective
3748
+ * activation/dormancy and missing-prerequisite changes, never per call or when off.
3749
+ * Measure with trusted application code and restore false promptly; already captured
3750
+ * calls/handles do not change. Shallow-unproven rows use compatible copied stages with
3751
+ * graph checks before hooks; selected reconstruction is bounded to 20,000 slots/issued
3752
+ * roots and depth 100. Selected unsupported values reject; invalid virtual returns omit.
3753
+ * Retained original children may remain discoverable after replacement; new objects
3754
+ * receive no child handle. Measure rather than assuming a speedup.
3755
+ * Ordinary grants are shared per field/read/owning embedded child; captured configuration
3756
+ * and scope views are reused. No trusted stage snapshot is issued. Native/BSON snapshot
3757
+ * wire/equality passes are omitted, but hydration, selected native/value fallbacks,
3758
+ * getter document views/return staging, private populated argument-four isolation and
3759
+ * JSON serialization can still copy/normalize. Active configuration is not a promise
3760
+ * every row is zero-copy; copied/trusted rows can coexist. No universal performance
3761
+ * gain or v0.51.0 equivalence/parity is promised. Turning false leaves the original
3762
+ * prerequisite skip flags unchanged; restore those independently for default protections.
3763
+ *
3764
+ * @example
3765
+ * ```ts
3766
+ * import { createAccessRuntime, type DefaultModelRouterOptions } from '@web-ts-toolkit/access-router';
3767
+ * const api = createAccessRuntime();
3768
+ * const list = {
3769
+ * unsafeSkipListDocumentSnapshotChecks: true,
3770
+ * unsafeSkipListOutputSnapshotChecks: true,
3771
+ * unsafeSkipListNestedDocumentSnapshotChecks: true,
3772
+ * unsafeSkipListInitialOutputSnapshotCopy: true,
3773
+ * unsafeUseListAuthorizationFastPath: true,
3774
+ * } satisfies DefaultModelRouterOptions;
3775
+ * api.setDefaultModelOptions(list); // all READ flags remain independently off
3776
+ * api.setDefaultModelOption('unsafeUseListAuthorizationFastPath', false);
3777
+ * // Rollback protects new calls only; existing handles retain the weaker mode.
3778
+ * ```
3779
+ */
3780
+ unsafeUseListAuthorizationFastPath?: boolean;
3781
+ /**
3782
+ * EXPERIMENTAL performance-first UNSAFE, default `false`; independent READ equivalent of unsafeUseListAuthorizationFastPath.
3783
+ * Requires ALL FOUR unsafeSkipReadDocumentSnapshotChecks, unsafeSkipReadOutputSnapshotChecks,
3784
+ * unsafeSkipReadNestedDocumentSnapshotChecks and unsafeSkipReadInitialOutputSnapshotCopy
3785
+ * options to be literal true; missing prerequisites leave it dormant without changing them.
3786
+ * Explicit false overrides model defaults; undefined restores inheritance.
3787
+ * Captured before hooks/awaits for findOne/findById/public/root reads, including READ-to-list
3788
+ * retries and authenticated embedded/related descendants, never from LIST/target settings.
3789
+ * Retained issued handles keep the captured mode; rollback affects new calls only.
3790
+ *
3791
+ * Eligible rows borrow source/ordinary hook grants, use shallow contexts and omit
3792
+ * repeated snapshots, defensive isolation and descendant graph verification.
3793
+ * The trusted runtime retains actual rules/hooks/getters, operation/row admission,
3794
+ * cheap exact root binding and issuance membership, not full descendant integrity or
3795
+ * detached source/grant/context leaves. Mutation, stale decisions, descendant replacement
3796
+ * and lost native observations can turn denial into allowance; full unvisited per-document
3797
+ * shape/bounds are lost. Request/work limits remain; selected reconstruction is bounded
3798
+ * to 20,000 slots/issued roots and depth 100. Shallow-unproven rows use compatible copied
3799
+ * stages with graph checks before hooks. Unsupported selected values reject; invalid
3800
+ * virtual returns omit. Removed issued children may remain discoverable; replacements
3801
+ * receive no child handle.
3802
+ * Writes/write-derived reads, new/create/update/upsert/delete, dedicated subdocuments
3803
+ * and fresh raw-policy helpers
3804
+ * stay inapplicable. Server model/default literal true only, never method defaults or
3805
+ * per-call/policy/helper/wire controls. Warns on effective activation/dormancy and
3806
+ * missing-prerequisite changes, never per call or when off;
3807
+ * restore false promptly and measure rather than assuming equivalent security or speed.
3808
+ * Grants/context/native leaves and captured scope/config views may be shared; there
3809
+ * is no trusted stage snapshot. Selected natives/hydration/getter views/return staging/
3810
+ * private argument-four isolation/JSON serialization still normalize or copy. Active
3811
+ * configuration is not an every-row zero-copy promise. No universal gain or v0.51.0
3812
+ * equivalence/parity. Rollback does not automatically restore the four original skips.
3813
+ *
3814
+ * @example
3815
+ * ```ts
3816
+ * import acl, { type DefaultModelRouterOptions } from '@web-ts-toolkit/access-router';
3817
+ * const read = {
3818
+ * unsafeSkipReadDocumentSnapshotChecks: true,
3819
+ * unsafeSkipReadOutputSnapshotChecks: true,
3820
+ * unsafeSkipReadNestedDocumentSnapshotChecks: true,
3821
+ * unsafeSkipReadInitialOutputSnapshotCopy: true,
3822
+ * unsafeUseReadAuthorizationFastPath: true,
3823
+ * } satisfies DefaultModelRouterOptions;
3824
+ * // User must already be registered on this runtime; never spread request options.
3825
+ * acl.setModelOptions('User', read); // LIST is not enabled
3826
+ * acl.setModelOption('User', 'unsafeUseReadAuthorizationFastPath', false);
3827
+ * // READ-to-list retries and retained handles keep the initiating READ capture.
3828
+ * ```
3829
+ */
3830
+ unsafeUseReadAuthorizationFastPath?: boolean;
3653
3831
  }
3654
3832
  interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
3655
3833
  'hydration.publicList'?: HydrationMode;
@@ -3770,6 +3948,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
3770
3948
  * for both output and document-permission access, independently of metadata flags.
3771
3949
  */
3772
3950
  alwaysSelectFields?: string[] | Record<string, string[]>;
3951
+ /**
3952
+ * Once-per-root/target projected document grants, independently of skim/metadata.
3953
+ * Active unsafe query fast paths borrow ordinary source/hook input and share returned
3954
+ * grants/context leaves across field decisions/reads/owning embedded children.
3955
+ * Mutation can change permission outcomes; see ModelDocPermissionsHook and the
3956
+ * unsafeUseListAuthorizationFastPath / unsafeUseReadAuthorizationFastPath contract.
3957
+ */
3773
3958
  docPermissions?: DocPermissions | ModelDocPermissionsHook;
3774
3959
  /**
3775
3960
  * Allowlist of `docPermissions`-hook keys exposed in API responses.