@web-ts-toolkit/access-router 0.55.0 → 0.56.0

package/llms.txt

@@ -35,8 +35,9 @@
 - [Includes/count cardinality](README.md#include-cardinality) · [Bounded numeric Map counts and Set-to-number migration](README.md#numeric-grouped-count-service-api-breaking-migration) · [Source/attachment provenance](README.md#safe-include-output-paths)
 - [Correlated includes and literal escapes](README.md#correlated-includes) · [Nested writes and trusted hooks](README.md#nested-updates-and-trusted-hooks)
 - [Virtuals, literal-filter preservation and output compatibility](README.md#virtuals-computed-fields) · [Request/runtime reentrant hook chains](README.md#hook-admission-and-reentrant-service-calls) · [Separate persistence limits](README.md#persistence-concurrency-and-resource-limits)
-- [Private populated dependencies](README.md#private-populated-dependencies) · [Runnable three-shape example](README.md#runnable-private-dependency-example): server virtual `dependsOnPopulate: [{ path, select? }]`, automatically retained scope-local static ObjectId ref/1D array, eagerly registered same-runtime/same-connection target. Explicit `ModelVirtualDescriptor<Source, Value, { ref: Target }>` types only optional getter argument four (`populated = {}`); argument one/local dependsOn and persisted/write/public types stay unchanged. New root/advanced types: ModelVirtualPopulateDependency, ModelVirtualPopulateInputs. No client/query authority or new entrypoint.
-- [Private target/read/selection rules](README.md#target-authority-selection-and-reconstruction): original actor's captured base read and request tenant rows, independent from public match/access/authorization.related; compatible fetch union never changes original public output. Ordinary populate returns its authorized original mask, otherwise restore exact selected/permitted IDs/arrays or omit hidden refs. Each getter gets only its declared mask; no implicit DTO/handle/metadata/hook/task transport, only its authorized deliberate return. No recursive private target virtuals; unavailable private inputs omit virtuals without retrying successful writes. See README for 1/-1/empty selection, errors, inheritance, fixed hydration differences and measured compatible-group batching (not constant across independent correlated queries).
+- [Private populated dependencies](README.md#private-populated-dependencies) · [Runnable example](README.md#runnable-private-dependency-example): server virtual `dependsOnPopulate: [{ path, select? }]`, automatically retained scope-local static ObjectId ref/1D array, eagerly registered same-runtime/same-connection target. Explicit `ModelVirtualDescriptor<Source, Value, { ref: Target }>` types only optional getter argument four (`populated = {}`); argument one/local dependsOn and persisted/write/public types stay unchanged. Root/advanced types: ModelVirtualPopulateDependency, ModelVirtualPopulateInputs. No client/query authority or new entrypoint.
+- [Runtime private-read mode](README.md#runtime-private-read-mode): `api.setGlobalOptions({ requireReadOperationAccessForPopulateDependencies: false })` opts out of private target operationAccess.read only; default true, only literal false bypasses, malformed JS/undefined stays conservative true. Typed GlobalOptions/exact setters/getters; server/runtime-only, isolated and captured with source/target/query intent before awaits, including nested output. Not requireRegisteredPopulateModels: eager private registration/static declarations remain. Source/target input-field permissions are already bypassed; virtual output authorization and request baseFilter.read/overrideFilter.read/retained IDs still govern. False + virtual-only selection adds no operation check solely to fetch.
+- [Private target/read/selection rules](README.md#target-authority-selection-and-reconstruction) · [Release compatibility](README.md#release-compatibility-dependency-reference-omission): BOTH modes apply an independent captured caller target BASE-read visibility gate to active selected/applicable dependency refs. Source unselected/denied -> omit; target read denied/failed -> omit entire ref INCLUDING ID, outranking list/custom populate access and public related-operation grants. Read allowed + ordinary population -> original authorized mask; read allowed + no population -> exact original refs/arrays/nulls/misses/order/duplicates/presence. This intentionally supersedes prior D1 denied-ID fallback even in default mode; no active plan/no feature keeps ordinary behavior. Private availability/getter outcomes never grant reference output. Compatible positive fetch unions retain separate masks/private request row scope, independent of public match/access/related grants. Each getter gets only its declared fourth-argument mask; no implicit DTO/handle/metadata/hook/task transport, only its authorized deliberate return. No recursive private target virtuals or successful-write retries. See README for selection/errors/inheritance/native isolation/hydration caveats and measured compatible-group batching.
 
 ## Additional examples
 

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.55.0",
+  "version": "0.56.0",
   "sideEffects": [
     "./**/index.js",
     "./**/index.mjs",
@@ -57,8 +57,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.55.0",
-    "@web-ts-toolkit/utils": "0.55.0",
+    "@web-ts-toolkit/express-json-router": "0.56.0",
+    "@web-ts-toolkit/utils": "0.56.0",
     "just-diff": "^6.0.2",
     "mongoose-schema-jsonschema": "^4.0.1",
     "sift": "^17.1.3",

package/{parsers-BrVRL2fg.d.mts → parsers-BXKoUKMa.d.mts}

@@ -420,10 +420,19 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
  * and traversal through target refs are rejected. `_id` is included unless excluded.
  * Static string refs must bind the actual same-connection ObjectId model; register
  * its model instance AND options first. Validation is eager/atomic, including setters.
- * This grants getter input fields only, not public population or output fields.
- * Target operationAccess.read, overrideFilter.read and baseFilter.read still use
- * the original actor's request authority/tenant scope, independently of ordinary
+ * This bypasses source/target input-field permissions, not the virtual's own output
+ * authorization. GlobalOptions.requireReadOperationAccessForPopulateDependencies defaults
+ * to true, requiring the captured caller's target base operationAccess.read for private
+ * loading. Only literal false bypasses that gate; private-only loading then adds no
+ * operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
+ * retained source IDs always use request authority/tenant scope, independently of ordinary
  * populate match/access and authorization.related. Private target virtuals never run.
+ * In both modes, active selected/applicable dependency refs denied caller-context base
+ * read visibility are omitted entirely, including IDs; public list/custom access or a
+ * related-operation grant cannot override this. Allowed selected/permitted refs keep the
+ * original authorized populate mask or exact original refs. No active plan keeps ordinary
+ * behavior. The mode and source/target policy are captured before awaits; registration
+ * remains mandatory independently of requireRegisteredPopulateModels.
  */
 interface ModelVirtualPopulateDependency<TModel = unknown> {
     /** Top-level ref relative to this virtual's scope; no dotted source paths. Retained automatically. */
@@ -468,7 +477,7 @@ type ModelVirtualPopulateInputs<TModel = unknown, TPopulated extends VirtualPopu
  * It is separate from `doc`, whose persisted/public-related typing is unchanged.
  * The runtime supplies it (empty without a declaration); the empty default generic
  * guesses no target shape. Optionality preserves legacy three-argument direct calls
- * and callbacks. Absent source refs or unavailable target reads skip invocation;
+ * and callbacks. Absent source refs or unavailable private inputs skip invocation;
  * present null/empty refs and missing target rows yield null/[]/null array slots.
  * Private values are not implicitly transported to output or authorization metadata;
  * an authorized getter can deliberately return a computed value using them.
@@ -494,7 +503,8 @@ type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends V
  * generic never changes the persisted model, write types or public output.
  * Use `populated = {}` or guard undefined to retain three-argument direct calls.
  * See the shipped README's "Private populated dependencies" for registration,
- * all three public reference shapes, target read/row gates and absence/error rules.
+ * reference omission/population/ID shapes, captured private-read mode, mandatory row
+ * gates and absence/error rules. Private computation does not imply reference visibility.
  *
  * @example
  * ```ts
@@ -1143,6 +1153,10 @@ interface AuthorizationConfiguration {
     readonly catalog: AuthorizationFieldCatalog;
     /** Opaque terminal private-input capture. Never related authority or public document metadata. */
     readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
+    /** Runtime-owned private input admission mode, not public output/related authority. */
+    readonly requireReadOperationAccessForPopulateDependencies?: boolean;
+    /** Independent ordinary-populate registration posture from the same global snapshot. */
+    readonly requireRegisteredPopulateModels?: boolean;
     readonly documentPermissionField?: string;
     /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
     readonly [key: string]: unknown;
@@ -3116,7 +3130,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization and resource settings, configured with
+ * Runtime-wide request initialization, private-input policy and resource settings, configured with
  * api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
  * options. Object assignment is shallow; nested requestComplexity replaces as a unit.
  */
@@ -3134,6 +3148,39 @@ interface GlobalOptions {
     globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
     /** Require populate target models to be registered in the active runtime. Defaults to `true`. */
     requireRegisteredPopulateModels?: boolean;
+    /**
+     * Require the original caller's target base `operationAccess.read` before loading
+     * declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
+     * `false` bypasses that operation gate; undefined/malformed JS values normalize to
+     * `true`. Source/target input-field permissions are already bypassed by the server
+     * declaration; the virtual's own output authorization still applies. Target request-mode
+     * `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
+     * Captured with source/target policy and query intent before the first await, including
+     * nested output scopes. In-flight calls retain their mode; later calls see updates.
+     * Runtime-isolated server configuration only: no caller/query or per-model override.
+     *
+     * In BOTH modes, references in an active selected/applicable dependency plan require
+     * source selection/field permission AND the captured caller-context target base read
+     * grant. Denied/failed read visibility omits the entire reference, including its ID,
+     * even with ordinary list/custom populate access or a public related-operation grant.
+     * Allowed read keeps the original authorized public populate mask, or exact original
+     * refs without population. No active dependency plan leaves ordinary behavior intact.
+     * False-mode private-only loading adds no operation check solely for that fetch.
+     * This never grants public fields, row/write authority or query controls. Registration
+     * and static input declarations remain required, independently of requireRegisteredPopulateModels.
+     *
+     * @example
+     * ```ts
+     * import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
+     * const api = createAccessRuntime();
+     * const policy = { requireReadOperationAccessForPopulateDependencies: false } satisfies GlobalOptions;
+     * api.setGlobalOptions(policy); // privileged computation inputs; no public target-read grant
+     * const snapshot: GlobalOptions = api.getGlobalOptions();
+     * api.setGlobalOption('requireReadOperationAccessForPopulateDependencies', true);
+     * void snapshot; // stored snapshot; read again to observe the setter
+     * ```
+     */
+    requireReadOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3441,8 +3488,12 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
      * { ref: Target }> separately, then assign here; persisted/write/public types
      * stay unchanged. Register target models/options first in this runtime. Source
-     * refs are retained automatically; target base read/tenant gates still apply.
-     * The original public selection/population is preserved, including ID restoration.
+     * refs are retained automatically. GlobalOptions.requireReadOperationAccessForPopulateDependencies
+     * defaults to true; false bypasses only private target-operation admission, never
+     * request read-row filters/retained IDs. In both modes an active dependency ref's
+     * denied caller-context target base read omits the entire ref, including its ID.
+     * Allowed refs keep the original authorized populate mask or exact original IDs;
+     * unselected/denied source fields remain hidden. No active plan keeps ordinary behavior.
      *
      * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
      * ```ts

package/{parsers-BrVRL2fg.d.ts → parsers-BXKoUKMa.d.ts}

@@ -420,10 +420,19 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
  * and traversal through target refs are rejected. `_id` is included unless excluded.
  * Static string refs must bind the actual same-connection ObjectId model; register
  * its model instance AND options first. Validation is eager/atomic, including setters.
- * This grants getter input fields only, not public population or output fields.
- * Target operationAccess.read, overrideFilter.read and baseFilter.read still use
- * the original actor's request authority/tenant scope, independently of ordinary
+ * This bypasses source/target input-field permissions, not the virtual's own output
+ * authorization. GlobalOptions.requireReadOperationAccessForPopulateDependencies defaults
+ * to true, requiring the captured caller's target base operationAccess.read for private
+ * loading. Only literal false bypasses that gate; private-only loading then adds no
+ * operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
+ * retained source IDs always use request authority/tenant scope, independently of ordinary
  * populate match/access and authorization.related. Private target virtuals never run.
+ * In both modes, active selected/applicable dependency refs denied caller-context base
+ * read visibility are omitted entirely, including IDs; public list/custom access or a
+ * related-operation grant cannot override this. Allowed selected/permitted refs keep the
+ * original authorized populate mask or exact original refs. No active plan keeps ordinary
+ * behavior. The mode and source/target policy are captured before awaits; registration
+ * remains mandatory independently of requireRegisteredPopulateModels.
  */
 interface ModelVirtualPopulateDependency<TModel = unknown> {
     /** Top-level ref relative to this virtual's scope; no dotted source paths. Retained automatically. */
@@ -468,7 +477,7 @@ type ModelVirtualPopulateInputs<TModel = unknown, TPopulated extends VirtualPopu
  * It is separate from `doc`, whose persisted/public-related typing is unchanged.
  * The runtime supplies it (empty without a declaration); the empty default generic
  * guesses no target shape. Optionality preserves legacy three-argument direct calls
- * and callbacks. Absent source refs or unavailable target reads skip invocation;
+ * and callbacks. Absent source refs or unavailable private inputs skip invocation;
  * present null/empty refs and missing target rows yield null/[]/null array slots.
  * Private values are not implicitly transported to output or authorization metadata;
  * an authorized getter can deliberately return a computed value using them.
@@ -494,7 +503,8 @@ type ModelVirtualGetter<TModel = unknown, TValue = unknown, TPopulated extends V
  * generic never changes the persisted model, write types or public output.
  * Use `populated = {}` or guard undefined to retain three-argument direct calls.
  * See the shipped README's "Private populated dependencies" for registration,
- * all three public reference shapes, target read/row gates and absence/error rules.
+ * reference omission/population/ID shapes, captured private-read mode, mandatory row
+ * gates and absence/error rules. Private computation does not imply reference visibility.
  *
  * @example
  * ```ts
@@ -1143,6 +1153,10 @@ interface AuthorizationConfiguration {
     readonly catalog: AuthorizationFieldCatalog;
     /** Opaque terminal private-input capture. Never related authority or public document metadata. */
     readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
+    /** Runtime-owned private input admission mode, not public output/related authority. */
+    readonly requireReadOperationAccessForPopulateDependencies?: boolean;
+    /** Independent ordinary-populate registration posture from the same global snapshot. */
+    readonly requireRegisteredPopulateModels?: boolean;
     readonly documentPermissionField?: string;
     /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
     readonly [key: string]: unknown;
@@ -3116,7 +3130,7 @@ interface AccessRouterLogger {
     isLevelEnabled?: (level: string) => boolean;
 }
 /**
- * Runtime-wide request initialization and resource settings, configured with
+ * Runtime-wide request initialization, private-input policy and resource settings, configured with
  * api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
  * options. Object assignment is shallow; nested requestComplexity replaces as a unit.
  */
@@ -3134,6 +3148,39 @@ interface GlobalOptions {
     globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
     /** Require populate target models to be registered in the active runtime. Defaults to `true`. */
     requireRegisteredPopulateModels?: boolean;
+    /**
+     * Require the original caller's target base `operationAccess.read` before loading
+     * declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
+     * `false` bypasses that operation gate; undefined/malformed JS values normalize to
+     * `true`. Source/target input-field permissions are already bypassed by the server
+     * declaration; the virtual's own output authorization still applies. Target request-mode
+     * `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
+     * Captured with source/target policy and query intent before the first await, including
+     * nested output scopes. In-flight calls retain their mode; later calls see updates.
+     * Runtime-isolated server configuration only: no caller/query or per-model override.
+     *
+     * In BOTH modes, references in an active selected/applicable dependency plan require
+     * source selection/field permission AND the captured caller-context target base read
+     * grant. Denied/failed read visibility omits the entire reference, including its ID,
+     * even with ordinary list/custom populate access or a public related-operation grant.
+     * Allowed read keeps the original authorized public populate mask, or exact original
+     * refs without population. No active dependency plan leaves ordinary behavior intact.
+     * False-mode private-only loading adds no operation check solely for that fetch.
+     * This never grants public fields, row/write authority or query controls. Registration
+     * and static input declarations remain required, independently of requireRegisteredPopulateModels.
+     *
+     * @example
+     * ```ts
+     * import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
+     * const api = createAccessRuntime();
+     * const policy = { requireReadOperationAccessForPopulateDependencies: false } satisfies GlobalOptions;
+     * api.setGlobalOptions(policy); // privileged computation inputs; no public target-read grant
+     * const snapshot: GlobalOptions = api.getGlobalOptions();
+     * api.setGlobalOption('requireReadOperationAccessForPopulateDependencies', true);
+     * void snapshot; // stored snapshot; read again to observe the setter
+     * ```
+     */
+    requireReadOperationAccessForPopulateDependencies?: boolean;
     logger?: AccessRouterLogger;
     /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
     requestComplexity?: RequestComplexityOptions;
@@ -3441,8 +3488,12 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
      * that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
      * { ref: Target }> separately, then assign here; persisted/write/public types
      * stay unchanged. Register target models/options first in this runtime. Source
-     * refs are retained automatically; target base read/tenant gates still apply.
-     * The original public selection/population is preserved, including ID restoration.
+     * refs are retained automatically. GlobalOptions.requireReadOperationAccessForPopulateDependencies
+     * defaults to true; false bypasses only private target-operation admission, never
+     * request read-row filters/retained IDs. In both modes an active dependency ref's
+     * denied caller-context target base read omits the entire ref, including its ID.
+     * Allowed refs keep the original authorized populate mask or exact original IDs;
+     * unselected/denied source fields remain hidden. No active plan keeps ordinary behavior.
      *
      * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
      * ```ts