@web-ts-toolkit/access-router 0.60.0 → 0.62.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 +362 -80
- package/advanced.d.mts +1 -1
- package/advanced.d.ts +1 -1
- package/advanced.js +272 -130
- package/advanced.mjs +272 -130
- package/index.d.mts +25 -17
- package/index.d.ts +25 -17
- package/index.js +807 -419
- package/index.mjs +750 -362
- package/llms.txt +4 -2
- package/package.json +3 -3
- package/{parsers-bP4gXehf.d.mts → parsers-Bdq0jg69.d.mts} +255 -79
- package/{parsers-bP4gXehf.d.ts → parsers-Bdq0jg69.d.ts} +255 -79
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import
|
|
2
|
+
import * as mongoose from 'mongoose';
|
|
3
|
+
import mongoose__default, { Model, Schema } from 'mongoose';
|
|
3
4
|
import express from 'express';
|
|
4
5
|
|
|
5
6
|
interface BooleanObject {
|
|
@@ -168,7 +169,7 @@ type WithDefaultId<T> = T extends object ? T & {
|
|
|
168
169
|
*/
|
|
169
170
|
type WithVirtuals<TModel, TVirtuals extends object = Record<never, never>> = TModel & Partial<TVirtuals>;
|
|
170
171
|
type PublicOutput<T, TVirtuals extends object = Record<never, never>> = WithVirtuals<T, TVirtuals> extends object ? WithVirtuals<T, TVirtuals> & Record<string, unknown> : Record<string, unknown>;
|
|
171
|
-
type ModelDocument<TModel = unknown> =
|
|
172
|
+
type ModelDocument<TModel = unknown> = mongoose__default.Document & TModel;
|
|
172
173
|
type TrimLeft<S extends string> = S extends ` ${infer Rest}` ? TrimLeft<Rest> : S;
|
|
173
174
|
type TrimRight<S extends string> = S extends `${infer Rest} ` ? TrimRight<Rest> : S;
|
|
174
175
|
type Trim<S extends string> = TrimLeft<TrimRight<S>>;
|
|
@@ -324,6 +325,21 @@ type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclu
|
|
|
324
325
|
type Include = LegacyInclude | CorrelatedInclude;
|
|
325
326
|
type FindAccess = 'list' | 'read';
|
|
326
327
|
type PopulateAccess = 'list' | 'read';
|
|
328
|
+
/**
|
|
329
|
+
* Ordinary public population intent, not model/authorization configuration.
|
|
330
|
+
* Static string refs resolve on the source model's connection and must match the
|
|
331
|
+
* exact target registered/configured in the owning runtime with an effective object
|
|
332
|
+
* permissionSchema. Explicit Model-valued schema refs can cross connections when
|
|
333
|
+
* that exact instance is configured in the same runtime. Missing/mismatched targets
|
|
334
|
+
* fail before target I/O or initiating writes; the validated model is pinned in flight.
|
|
335
|
+
* Dynamic callback/refPath refs cannot be statically bound before I/O and reject
|
|
336
|
+
* with a controlled configuration diagnostic.
|
|
337
|
+
* The actual target's requireOperationAccessForPopulateQueries controls only operation
|
|
338
|
+
* admission. Fields, document grants, rows, original selection, match and reference IDs
|
|
339
|
+
* remain enforced; direct/root target guards stay independent. Callers cannot supply
|
|
340
|
+
* a model or either populate policy flag here. Private dependsOnPopulate declarations
|
|
341
|
+
* have a narrower one-hop static-string ObjectId/same-connection contract.
|
|
342
|
+
*/
|
|
327
343
|
interface Populate {
|
|
328
344
|
path: string;
|
|
329
345
|
select?: Projection;
|
|
@@ -420,8 +436,10 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
|
|
|
420
436
|
* and traversal through target refs are rejected. `_id` is included unless excluded.
|
|
421
437
|
* Static string refs must bind the actual same-connection ObjectId model; register
|
|
422
438
|
* its model instance AND options first. Validation is eager/atomic, including setters.
|
|
439
|
+
* Model-valued/cross-connection refs supported by ordinary population are outside
|
|
440
|
+
* this private declaration's static-string, same-connection limit.
|
|
423
441
|
* This bypasses source/target input-field permissions, not the virtual's own output
|
|
424
|
-
* authorization.
|
|
442
|
+
* authorization. The target model's requireOperationAccessForPopulateDependencies defaults
|
|
425
443
|
* to true, requiring the captured caller's target base operationAccess.read for private
|
|
426
444
|
* loading. Only literal false bypasses that gate; private-only loading then adds no
|
|
427
445
|
* operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
|
|
@@ -432,9 +450,11 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
|
|
|
432
450
|
* admitted ordinary population owns the slot (then its original public mask/miss applies).
|
|
433
451
|
* Strict private denial, row/query/getter failure and deferred virtual denial cannot hide
|
|
434
452
|
* permitted IDs. Only source unselection/field denial omits them; there is no extra target
|
|
435
|
-
* base-read visibility gate.
|
|
436
|
-
* independently controls ordinary target operation admission.
|
|
437
|
-
*
|
|
453
|
+
* base-read visibility gate. The target model's requireOperationAccessForPopulateQueries
|
|
454
|
+
* independently controls ordinary target operation admission. Each target resolves its
|
|
455
|
+
* override → captured runtime model default → true; undefined restores inheritance.
|
|
456
|
+
* Source flags do not propagate: Document's private User ref uses User's dependency flag.
|
|
457
|
+
* Both flags and source/target policy are captured before awaits; registration and an effective object permissionSchema
|
|
438
458
|
* remain mandatory. Private inputs never implicitly enter hooks, handles or metadata.
|
|
439
459
|
*/
|
|
440
460
|
interface ModelVirtualPopulateDependency<TModel = unknown> {
|
|
@@ -645,6 +665,8 @@ declare class AccessRuntime {
|
|
|
645
665
|
private readonly globalOptions;
|
|
646
666
|
private readonly defaultModelOptions;
|
|
647
667
|
private readonly modelOptions;
|
|
668
|
+
private readonly modelOptionOverrides;
|
|
669
|
+
private pendingSnapshotWarnings?;
|
|
648
670
|
private readonly modelJsonSchemas;
|
|
649
671
|
private readonly dataOptions;
|
|
650
672
|
private readonly modelRefs;
|
|
@@ -653,9 +675,9 @@ declare class AccessRuntime {
|
|
|
653
675
|
private readonly modelInstances;
|
|
654
676
|
private readonly openApiRegistry;
|
|
655
677
|
private openApiPathPrefix;
|
|
656
|
-
registerModelInstance<TModel>(modelName: string, model:
|
|
678
|
+
registerModelInstance<TModel>(modelName: string, model: mongoose__default.Model<TModel>): void;
|
|
657
679
|
hasModelInstance(modelName: string): boolean;
|
|
658
|
-
getModelInstance<TModel = unknown>(modelName: string):
|
|
680
|
+
getModelInstance<TModel = unknown>(modelName: string): mongoose__default.Model<TModel> | null;
|
|
659
681
|
registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
|
|
660
682
|
/**
|
|
661
683
|
* Compose OpenAPI paths while synchronously constructing mounted routers.
|
|
@@ -699,8 +721,9 @@ declare class AccessRuntime {
|
|
|
699
721
|
globalOptions: GlobalOptions;
|
|
700
722
|
defaultModelOptions: DefaultModelRouterOptions;
|
|
701
723
|
modelOptions: Record<string, ModelRouterOptions>;
|
|
724
|
+
modelOptionOverrides: Record<string, ModelRouterOptions>;
|
|
702
725
|
dataOptions: Record<string, DataRouterOptions>;
|
|
703
|
-
modelInstances: Record<string,
|
|
726
|
+
modelInstances: Record<string, mongoose__default.Model<unknown>>;
|
|
704
727
|
modelJsonSchemas: Record<string, Record<string, unknown>>;
|
|
705
728
|
modelRefs: Record<string, ModelReferenceMap>;
|
|
706
729
|
modelSubs: Record<string, string[]>;
|
|
@@ -716,15 +739,22 @@ declare class AccessRuntime {
|
|
|
716
739
|
setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
|
|
717
740
|
getGlobalOptions(): GlobalOptions;
|
|
718
741
|
getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
|
|
719
|
-
/** Update model
|
|
742
|
+
/** Update inherited model defaults shallowly. Explicit model values and captured calls are unchanged. */
|
|
720
743
|
setDefaultModelOptions(options: DefaultModelRouterOptions): void;
|
|
721
744
|
setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
|
|
722
745
|
getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
|
|
723
746
|
getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
|
|
747
|
+
private resolveModelOptions;
|
|
748
|
+
private validateModelOptions;
|
|
749
|
+
private publishDefaultModelOptions;
|
|
750
|
+
private warnSnapshotFlag;
|
|
751
|
+
private deferSnapshotWarnings;
|
|
752
|
+
private initialOutputCopyModes;
|
|
724
753
|
private createModelOptions;
|
|
725
754
|
private getOrCreateModelOptions;
|
|
726
755
|
/**
|
|
727
|
-
*
|
|
756
|
+
* Update explicit model overrides shallowly; undefined restores default inheritance
|
|
757
|
+
* (operationAccess preserves its existing exact-key-only default fallback). A supplied
|
|
728
758
|
* operationAccess/defaults object replaces that whole value. Defaults accept only
|
|
729
759
|
* query/presentation settings; virtual configuration is validated before assignment.
|
|
730
760
|
* Existing router.options remains its construction-time snapshot. Fresh model-service
|
|
@@ -732,7 +762,7 @@ declare class AccessRuntime {
|
|
|
732
762
|
*/
|
|
733
763
|
setModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): void;
|
|
734
764
|
setModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): void;
|
|
735
|
-
/** Frozen
|
|
765
|
+
/** Frozen model/default snapshot; populate flags remain raw overrides. Read again for current values. */
|
|
736
766
|
getModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
|
|
737
767
|
/**
|
|
738
768
|
* Generic stored exact → parent.default → parent lookup; only undefined falls through.
|
|
@@ -1024,8 +1054,19 @@ declare const documentAuthorizationBrand: unique symbol;
|
|
|
1024
1054
|
* row/call/access or pre-/post-write stages cannot establish validity and reject.
|
|
1025
1055
|
* A list/read handle with its server unsafeSkipListDocumentSnapshotChecks or
|
|
1026
1056
|
* unsafeSkipReadDocumentSnapshotChecks flag enabled retains that weakened source-
|
|
1027
|
-
* mutation policy; output
|
|
1057
|
+
* mutation policy; independent output-value/ownership checks still apply. Turning a setting
|
|
1028
1058
|
* off affects new calls, not an existing handle or captured read-to-list retry.
|
|
1059
|
+
* Independent unsafeSkipListOutputSnapshotChecks / unsafeSkipReadOutputSnapshotChecks
|
|
1060
|
+
* can also retain weakened output-value checks (graph identities still checked).
|
|
1061
|
+
* unsafeSkipListNestedDocumentSnapshotChecks / unsafeSkipReadNestedDocumentSnapshotChecks
|
|
1062
|
+
* retain weakened source checks on query descendants, using the initiating model's
|
|
1063
|
+
* mode. In-place value mutations can therefore reuse stale grants/decisions.
|
|
1064
|
+
* unsafeSkipListInitialOutputSnapshotCopy / unsafeSkipReadInitialOutputSnapshotCopy
|
|
1065
|
+
* additionally omit eligible initial output snapshots only when the corresponding
|
|
1066
|
+
* output-value comparison skip is enabled. They retain bounded structural admission
|
|
1067
|
+
* and exact graph ownership, but omit this pass's native/BSON normalization and
|
|
1068
|
+
* validation observations. Source/callback/grant copies remain detached; unproven
|
|
1069
|
+
* graphs or open ownership bindings fall back to copying. Retained handles keep this mode.
|
|
1029
1070
|
*/
|
|
1030
1071
|
interface DocumentAuthorization {
|
|
1031
1072
|
readonly [documentAuthorizationBrand]: true;
|
|
@@ -1099,6 +1140,11 @@ type AllowedOutputFieldOptions<TModel = unknown, TVirtuals extends object = Reco
|
|
|
1099
1140
|
readonly purpose: 'output';
|
|
1100
1141
|
};
|
|
1101
1142
|
|
|
1143
|
+
/** Package-private model-default capture. Never use a source model's resolved flags as defaults. */
|
|
1144
|
+
|
|
1145
|
+
/** Function identity survives authorization snapshot copying, retaining one owner capture. */
|
|
1146
|
+
type PopulatePolicyDefaultsToken = () => void;
|
|
1147
|
+
|
|
1102
1148
|
/** Package-private D2 validation/capture. Terminal persisted inputs, never output grants or target I/O. */
|
|
1103
1149
|
|
|
1104
1150
|
interface VirtualPopulateTarget {
|
|
@@ -1162,11 +1208,19 @@ interface AuthorizationConfiguration {
|
|
|
1162
1208
|
/** Captured server model option; alone it never issues relaxed document authority. */
|
|
1163
1209
|
readonly unsafeSkipListDocumentSnapshotChecks?: boolean;
|
|
1164
1210
|
readonly unsafeSkipReadDocumentSnapshotChecks?: boolean;
|
|
1211
|
+
readonly unsafeSkipListOutputSnapshotChecks?: boolean;
|
|
1212
|
+
readonly unsafeSkipReadOutputSnapshotChecks?: boolean;
|
|
1213
|
+
readonly unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
|
|
1214
|
+
readonly unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
|
|
1215
|
+
readonly unsafeSkipListInitialOutputSnapshotCopy?: boolean;
|
|
1216
|
+
readonly unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
|
|
1165
1217
|
/** Opaque terminal private-input capture. Never related authority or public document metadata. */
|
|
1166
1218
|
readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
|
|
1167
|
-
/**
|
|
1219
|
+
/** Held runtime model defaults, distinct from this model's resolved flags. */
|
|
1220
|
+
readonly populatePolicyDefaults?: PopulatePolicyDefaultsToken;
|
|
1221
|
+
/** Target-owned private input admission mode, not public output/related authority. */
|
|
1168
1222
|
readonly requireOperationAccessForPopulateDependencies?: boolean;
|
|
1169
|
-
/** Independent ordinary-populate operation admission
|
|
1223
|
+
/** Independent target-owned ordinary-populate operation admission. */
|
|
1170
1224
|
readonly requireOperationAccessForPopulateQueries?: boolean;
|
|
1171
1225
|
readonly documentPermissionField?: string;
|
|
1172
1226
|
/** Captured permission schema, virtual descriptors, always-select and metadata posture. */
|
|
@@ -1177,6 +1231,8 @@ interface AuthorizationRelatedTarget {
|
|
|
1177
1231
|
readonly path: string;
|
|
1178
1232
|
readonly modelName: string;
|
|
1179
1233
|
readonly configuration: AuthorizationConfiguration;
|
|
1234
|
+
/** Actual source-ref target or include receiver, captured with this runtime's configuration. */
|
|
1235
|
+
readonly model?: mongoose.Model<unknown>;
|
|
1180
1236
|
/** Effective include args/options, resolved with that target's captured defaults. */
|
|
1181
1237
|
readonly queryIntent?: ModelServiceIntent;
|
|
1182
1238
|
/** Existing include operation gate, resolved synchronously with its target. */
|
|
@@ -2332,7 +2388,7 @@ interface Change {
|
|
|
2332
2388
|
}
|
|
2333
2389
|
interface ModelHookContext {
|
|
2334
2390
|
modelName: string;
|
|
2335
|
-
mongooseModel:
|
|
2391
|
+
mongooseModel: mongoose__default.Model<unknown>;
|
|
2336
2392
|
operation?: string;
|
|
2337
2393
|
originalDocumentSnapshot?: Record<string, unknown>;
|
|
2338
2394
|
finalDocumentSnapshot?: Record<string, unknown>;
|
|
@@ -3140,9 +3196,12 @@ interface AccessRouterLogger {
|
|
|
3140
3196
|
isLevelEnabled?: (level: string) => boolean;
|
|
3141
3197
|
}
|
|
3142
3198
|
/**
|
|
3143
|
-
* Runtime-wide request initialization
|
|
3199
|
+
* Runtime-wide request initialization and resource settings, configured with
|
|
3144
3200
|
* api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
|
|
3145
3201
|
* options. Object assignment is shallow; nested requestComplexity replaces as a unit.
|
|
3202
|
+
* Populate operation flags belong to the actual target's ModelRouterOptions or
|
|
3203
|
+
* DefaultModelRouterOptions. Stale global setters (including api.set) reject them
|
|
3204
|
+
* with migration guidance to setModelOptions / setDefaultModelOptions.
|
|
3146
3205
|
*/
|
|
3147
3206
|
interface GlobalOptions {
|
|
3148
3207
|
/** Request grant-storage property (default `_permissions`), distinct from documentPermissionField. */
|
|
@@ -3156,57 +3215,6 @@ interface GlobalOptions {
|
|
|
3156
3215
|
* context. Generated routers do not authenticate client claims for this hook.
|
|
3157
3216
|
*/
|
|
3158
3217
|
globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
|
|
3159
|
-
/**
|
|
3160
|
-
* Require the caller's effective target operation (`read`, supported `list` or trusted
|
|
3161
|
-
* custom access) for ordinary query population (default `true`). Only literal `false`
|
|
3162
|
-
* skips that admission gate; source entry/field authorization, target field/document
|
|
3163
|
-
* grants, row/base/transform policies, original selection, match and mandatory reference
|
|
3164
|
-
* IDs still constrain output. Denied population retains selected/permitted original
|
|
3165
|
-
* source IDs; admitted population misses return null/filtered arrays, not restored IDs.
|
|
3166
|
-
* Targets always require an actual Mongoose model and ACL configuration with an
|
|
3167
|
-
* effective object permissionSchema in this runtime; `{}` closes business fields.
|
|
3168
|
-
* Runtime-owned and captured before awaits, independently of private dependency
|
|
3169
|
-
* admission. A configuration-only Document needs no HTTP routes. Its denied direct/root
|
|
3170
|
-
* read/list operations stay denied. No per-model/query/client override.
|
|
3171
|
-
*/
|
|
3172
|
-
requireOperationAccessForPopulateQueries?: boolean;
|
|
3173
|
-
/**
|
|
3174
|
-
* Require the original caller's target base `operationAccess.read` before loading
|
|
3175
|
-
* declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
|
|
3176
|
-
* `false` bypasses that operation gate; undefined/malformed JS values normalize to
|
|
3177
|
-
* `true`. Source/target input-field permissions are already bypassed by the server
|
|
3178
|
-
* declaration; the virtual's own output authorization still applies. Target request-mode
|
|
3179
|
-
* `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
|
|
3180
|
-
* Captured with source/target policy and query intent before the first await, including
|
|
3181
|
-
* nested output scopes. In-flight calls retain their mode; later calls see updates.
|
|
3182
|
-
* Runtime-isolated server configuration only: no caller/query or per-model override.
|
|
3183
|
-
*
|
|
3184
|
-
* Neither mode changes ordinary reference shape: selected/permitted parent fields keep
|
|
3185
|
-
* exact original IDs (including array order, duplicates, missing IDs and nulls) when no
|
|
3186
|
-
* admitted ordinary population owns them. Private denial, row/query/getter failure or
|
|
3187
|
-
* deferred virtual denial cannot hide those IDs. Omit only for parent unselection/field
|
|
3188
|
-
* denial; admitted public DTO/null/filtered-array results retain their original masks.
|
|
3189
|
-
* There is no additional target-base-read reference-visibility gate. False-mode loading
|
|
3190
|
-
* adds no operation check solely for its private fetch. Private fourth-argument inputs
|
|
3191
|
-
* never implicitly enter DTOs, hooks, handles, snapshots or permission metadata.
|
|
3192
|
-
* An actual registered model, effective object permissionSchema and static declarations
|
|
3193
|
-
* remain mandatory, independently of requireOperationAccessForPopulateQueries.
|
|
3194
|
-
*
|
|
3195
|
-
* @example
|
|
3196
|
-
* ```ts
|
|
3197
|
-
* import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
|
|
3198
|
-
* const api = createAccessRuntime();
|
|
3199
|
-
* const policy = {
|
|
3200
|
-
* requireOperationAccessForPopulateQueries: true,
|
|
3201
|
-
* requireOperationAccessForPopulateDependencies: false,
|
|
3202
|
-
* } satisfies GlobalOptions;
|
|
3203
|
-
* api.setGlobalOptions(policy); // private computation; denied public population retains permitted IDs
|
|
3204
|
-
* const snapshot: GlobalOptions = api.getGlobalOptions();
|
|
3205
|
-
* api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
|
|
3206
|
-
* void snapshot; // stored snapshot; read again to observe the setter
|
|
3207
|
-
* ```
|
|
3208
|
-
*/
|
|
3209
|
-
requireOperationAccessForPopulateDependencies?: boolean;
|
|
3210
3218
|
logger?: AccessRouterLogger;
|
|
3211
3219
|
/** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
|
|
3212
3220
|
requestComplexity?: RequestComplexityOptions;
|
|
@@ -3337,8 +3345,9 @@ type HydrationMode = 'lean' | 'hydrated';
|
|
|
3337
3345
|
* Set through ModelRouterOptions/DefaultModelRouterOptions and their whole-record
|
|
3338
3346
|
* or exact hydration.<method> setters (including existing model/default decorators).
|
|
3339
3347
|
* A supplied record replaces the previous record shallowly; omitted/undefined
|
|
3340
|
-
* members use built-ins, not an older/default record. Whole-record undefined
|
|
3341
|
-
*
|
|
3348
|
+
* members use built-ins, not an older/default record. Whole-model-record undefined
|
|
3349
|
+
* restores default-model inheritance; default-record undefined clears that default.
|
|
3350
|
+
* Invalid records/keys/modes throw before publication. Fresh calls observe owner
|
|
3342
3351
|
* updates; in-flight calls retain their captured configuration.
|
|
3343
3352
|
* Includes stay fixed lean; raw parents/lifecycle stages stay hydrated; subdocument
|
|
3344
3353
|
* post-save visibility stays lean. Populate inherits its parent query; $$sq uses
|
|
@@ -3360,7 +3369,17 @@ interface ModelHydrationOptions {
|
|
|
3360
3369
|
/** Internal findById defaults to hydrated; does not inherit findOne's setting. */
|
|
3361
3370
|
findById?: HydrationMode;
|
|
3362
3371
|
}
|
|
3363
|
-
/**
|
|
3372
|
+
/**
|
|
3373
|
+
* Inherited model defaults; data/root routers do not inherit these. Unspecified model
|
|
3374
|
+
* options follow later default updates for new calls. Explicit values (including false,
|
|
3375
|
+
* null, empty objects/arrays) win; setting a model option to undefined restores inheritance.
|
|
3376
|
+
* Exception: explicitly cleared operationAccess retains its exact-key-only default fallback;
|
|
3377
|
+
* a runtime catch-all/default guard is not an exact fallback in that mode.
|
|
3378
|
+
* Nested objects replace shallowly. Existing calls/handles and router.options keep their
|
|
3379
|
+
* captured snapshots; changing defaults does not rebuild already-mounted route paths.
|
|
3380
|
+
* The two populate operation flags retain raw override values in model snapshots;
|
|
3381
|
+
* their effective policy is resolved separately against the captured model defaults.
|
|
3382
|
+
*/
|
|
3364
3383
|
interface DefaultModelRouterOptions<TModel = unknown> {
|
|
3365
3384
|
/**
|
|
3366
3385
|
* Default business-field policy when a model's permissionSchema is undefined.
|
|
@@ -3370,6 +3389,85 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3370
3389
|
permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
|
|
3371
3390
|
/** Server-owned fetch choices, captured per call. Not a per-call or method-default option. */
|
|
3372
3391
|
hydration?: ModelHydrationOptions;
|
|
3392
|
+
/**
|
|
3393
|
+
* This target model requires the caller's effective operation (`read`, supported
|
|
3394
|
+
* `list` or trusted custom access) for ordinary query population (built-in default `true`).
|
|
3395
|
+
* Only literal `false` skips that admission gate; source entry/field authorization,
|
|
3396
|
+
* target field/document grants, row/base/transform policies, original selection,
|
|
3397
|
+
* match and mandatory reference IDs still constrain output. Denied population retains
|
|
3398
|
+
* permitted original IDs; admitted population misses return null/filtered arrays.
|
|
3399
|
+
* Targets always require an actual registered Mongoose model and an effective object permissionSchema;
|
|
3400
|
+
* `{}` closes business fields. A configuration-only Document needs no HTTP routes;
|
|
3401
|
+
* denied direct/root read/list operations stay denied.
|
|
3402
|
+
* Static string refs resolve on the source connection and must match that runtime's
|
|
3403
|
+
* configured instance. Explicit Model-valued ordinary refs can cross connections
|
|
3404
|
+
* when that exact model is registered/configured in the same runtime. The validated
|
|
3405
|
+
* model stays pinned through in-flight population; callers cannot supply a model.
|
|
3406
|
+
*
|
|
3407
|
+
* Target override → captured runtime model default → true. Explicit undefined clears
|
|
3408
|
+
* the override and restores inheritance; omission preserves it. Malformed non-undefined
|
|
3409
|
+
* JavaScript values become true. Defaults are captured before source/target option
|
|
3410
|
+
* reads and the first await; later top-level calls observe changes. getModelOptions and
|
|
3411
|
+
* router.options retain raw flag overrides; getModelOption reads the live default.
|
|
3412
|
+
* Source/sibling flags cannot relax
|
|
3413
|
+
* this target. Configure with setModelOptions/setDefaultModelOptions, never global,
|
|
3414
|
+
* per-query, service.defaults or client controls. Independent of private dependencies.
|
|
3415
|
+
*/
|
|
3416
|
+
requireOperationAccessForPopulateQueries?: boolean;
|
|
3417
|
+
/**
|
|
3418
|
+
* This target model requires the original caller's base `operationAccess.read` before
|
|
3419
|
+
* loading declared private `dependsOnPopulate` inputs (built-in default `true`). Only
|
|
3420
|
+
* literal boolean `false` bypasses that operation gate. Target override → captured
|
|
3421
|
+
* runtime model default → true; explicit undefined clears the override to inherit,
|
|
3422
|
+
* omission preserves it, and malformed JS values other than undefined normalize true.
|
|
3423
|
+
* Runtime-isolated server configuration on the actual target, not the source model;
|
|
3424
|
+
* set runtime defaults with setDefaultModelOptions. Global setters reject these keys.
|
|
3425
|
+
* Captured with source/target policy before the first await; nested stages retain the
|
|
3426
|
+
* capture and later top-level calls refresh. No caller/query or service.defaults control.
|
|
3427
|
+
* Project refs to Document use Document's flags; Document's own private User ref
|
|
3428
|
+
* uses User's dependency flag, never Project's or Document's bypass.
|
|
3429
|
+
* Source/target input-field permissions are bypassed only by the declaration; the
|
|
3430
|
+
* virtual's output authorization still applies. Target request-mode `baseFilter.read`,
|
|
3431
|
+
* `overrideFilter.read` and retained reference IDs always constrain rows.
|
|
3432
|
+
*
|
|
3433
|
+
* Neither mode changes ordinary reference shape: selected/permitted parent fields keep
|
|
3434
|
+
* exact original IDs (including order, duplicates, missing IDs and nulls) when no admitted
|
|
3435
|
+
* ordinary population owns them. Private denial, row/query/getter failure or deferred
|
|
3436
|
+
* virtual denial cannot hide those IDs. There is no additional target-base-read reference-visibility gate.
|
|
3437
|
+
* Private fourth-argument inputs never implicitly enter DTOs, hooks, handles or metadata.
|
|
3438
|
+
* An actual registered model, effective object permissionSchema and static declarations
|
|
3439
|
+
* remain mandatory, independently of requireOperationAccessForPopulateQueries.
|
|
3440
|
+
*
|
|
3441
|
+
* @example
|
|
3442
|
+
* ```ts
|
|
3443
|
+
* import mongoose from 'mongoose';
|
|
3444
|
+
* import { createAccessRuntime, type DefaultModelRouterOptions } from '@web-ts-toolkit/access-router';
|
|
3445
|
+
* const api = createAccessRuntime();
|
|
3446
|
+
* const defaults = {
|
|
3447
|
+
* requireOperationAccessForPopulateQueries: true,
|
|
3448
|
+
* requireOperationAccessForPopulateDependencies: true,
|
|
3449
|
+
* } satisfies DefaultModelRouterOptions;
|
|
3450
|
+
* api.setDefaultModelOptions(defaults);
|
|
3451
|
+
* const Document = mongoose.model('Document', new mongoose.Schema({ name: String }));
|
|
3452
|
+
* const User = mongoose.model('User', new mongoose.Schema({ name: String }));
|
|
3453
|
+
* api.registerModelInstance(Document.modelName, Document);
|
|
3454
|
+
* api.registerModelInstance(User.modelName, User);
|
|
3455
|
+
* api.setModelOptions(Document.modelName, {
|
|
3456
|
+
* operationAccess: { read: false, list: false }, permissionSchema: { name: true },
|
|
3457
|
+
* requireOperationAccessForPopulateQueries: false,
|
|
3458
|
+
* requireOperationAccessForPopulateDependencies: false,
|
|
3459
|
+
* });
|
|
3460
|
+
* api.setModelOptions(User.modelName, {
|
|
3461
|
+
* operationAccess: { read: false, list: false }, permissionSchema: {},
|
|
3462
|
+
* requireOperationAccessForPopulateQueries: true,
|
|
3463
|
+
* requireOperationAccessForPopulateDependencies: true,
|
|
3464
|
+
* });
|
|
3465
|
+
* api.setModelOption(Document.modelName, 'requireOperationAccessForPopulateDependencies', undefined); // inherit again
|
|
3466
|
+
* // Administrative default changes apply to later calls on existing unoverridden models.
|
|
3467
|
+
* api.setDefaultModelOption('requireOperationAccessForPopulateDependencies', false);
|
|
3468
|
+
* ```
|
|
3469
|
+
*/
|
|
3470
|
+
requireOperationAccessForPopulateDependencies?: boolean;
|
|
3373
3471
|
/** Maximum returned list rows (default 1000), independent of exact match/count totals. */
|
|
3374
3472
|
listHardLimit?: number;
|
|
3375
3473
|
/**
|
|
@@ -3450,9 +3548,10 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3450
3548
|
* skips repeated projected-document snapshot comparisons for this model's top-level
|
|
3451
3549
|
* `find`/public/root list responses. Captured before awaits; list-origin handles keep
|
|
3452
3550
|
* that mode. Single reads use the independent unsafeSkipReadDocumentSnapshotChecks
|
|
3453
|
-
* setting.
|
|
3551
|
+
* setting. Embedded/related source stages and output values have separate flags.
|
|
3552
|
+
* Writes and fresh standalone helpers stay strict.
|
|
3454
3553
|
*
|
|
3455
|
-
* Row/field permissions, exact ownership/binding, output
|
|
3554
|
+
* Row/field permissions, exact ownership/binding, independent output-value checks
|
|
3456
3555
|
* and detached callback/grant copies still run. However, source changes during a
|
|
3457
3556
|
* callback/await are no longer detected: stale grants/decisions may authorize output.
|
|
3458
3557
|
* Use only with trusted non-mutating application hooks, measure before rollout, and
|
|
@@ -3467,15 +3566,90 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3467
3566
|
* this setting, not unsafeSkipListDocumentSnapshotChecks. Captured before awaits;
|
|
3468
3567
|
* read-origin handles and retries keep that mode. List operations use their own flag.
|
|
3469
3568
|
*
|
|
3470
|
-
* Permission rules, exact ownership/binding, output-
|
|
3569
|
+
* Permission rules, exact ownership/binding, independent output-value checks and
|
|
3471
3570
|
* detached callback/grant copies still run. Source changes during callbacks/awaits
|
|
3472
3571
|
* can leave stale grants/decisions and incorrectly authorized output. Use only with
|
|
3473
3572
|
* trusted non-mutating hooks, measure before rollout and restore `false` promptly.
|
|
3474
|
-
*
|
|
3475
|
-
*
|
|
3476
|
-
* model-
|
|
3573
|
+
* Embedded/related source stages use separate nested flags. Writes (including
|
|
3574
|
+
* read-like output) and fresh helpers stay strict. Warns per model/flag transition.
|
|
3575
|
+
* Server model or inherited model-default configuration only; never method defaults
|
|
3576
|
+
* or wire options.
|
|
3477
3577
|
*/
|
|
3478
3578
|
unsafeSkipReadDocumentSnapshotChecks?: boolean;
|
|
3579
|
+
/**
|
|
3580
|
+
* TEMPORARY UNSAFE (default `false`): skip output VALUE snapshot comparisons in
|
|
3581
|
+
* top-level LIST responses and their embedded/populated/included descendants.
|
|
3582
|
+
* Exact output associations, graph identities, bindings and permission rules remain;
|
|
3583
|
+
* scalar/native in-place mutations can now reuse stale decisions and expose data.
|
|
3584
|
+
* Source checks and detached callback/grant/output copies remain. Initial output
|
|
3585
|
+
* snapshots also remain unless unsafeSkipListInitialOutputSnapshotCopy is active.
|
|
3586
|
+
* Captured before awaits; handles keep this mode after rollback. Only literal `true`
|
|
3587
|
+
* in server model/default configuration enables it and warns on effective transition.
|
|
3588
|
+
* READ/retries use unsafeSkipReadOutputSnapshotChecks; writes and fresh helpers stay
|
|
3589
|
+
* strict. Never set from request/per-call/method defaults. Revisit/remove promptly.
|
|
3590
|
+
*/
|
|
3591
|
+
unsafeSkipListOutputSnapshotChecks?: boolean;
|
|
3592
|
+
/**
|
|
3593
|
+
* TEMPORARY UNSAFE (default `false`): READ equivalent of unsafeSkipListOutputSnapshotChecks,
|
|
3594
|
+
* including findOne/findById, public/root reads, read-to-list retries and their
|
|
3595
|
+
* embedded/populated/included outputs. Uses the initiating READ model's captured
|
|
3596
|
+
* setting, not LIST or target-model settings. Value mutations may reuse stale
|
|
3597
|
+
* decisions; exact ownership/graph identities and permissions still run. Server
|
|
3598
|
+
* model/default literal `true` only; warns on effective enablement. Retained handles
|
|
3599
|
+
* keep their mode. Writes/fresh helpers stay strict. Revisit/remove promptly.
|
|
3600
|
+
*/
|
|
3601
|
+
unsafeSkipReadOutputSnapshotChecks?: boolean;
|
|
3602
|
+
/**
|
|
3603
|
+
* TEMPORARY UNSAFE (default `false`): skip repeated SOURCE snapshot comparisons for
|
|
3604
|
+
* embedded/populated/included document stages reached from a top-level LIST.
|
|
3605
|
+
* The initiating model's captured setting applies recursively, not target-model
|
|
3606
|
+
* flags. Parent source and all output-value checks remain independently configured;
|
|
3607
|
+
* parent snapshots still include nested values. Permission rules, exact binding,
|
|
3608
|
+
* initial source snapshots and detached copies remain. Child mutation can leave stale
|
|
3609
|
+
* grants/decisions and expose data. Only server model/default literal `true`
|
|
3610
|
+
* enables it; warns on transition. Rollback affects new calls, not captured descendants
|
|
3611
|
+
* or handles. READ uses its own flag; writes, dedicated subdocument operations and
|
|
3612
|
+
* fresh helpers stay strict. Never derive from requests. Revisit/remove promptly.
|
|
3613
|
+
*/
|
|
3614
|
+
unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
|
|
3615
|
+
/**
|
|
3616
|
+
* TEMPORARY UNSAFE (default `false`): READ equivalent of
|
|
3617
|
+
* unsafeSkipListNestedDocumentSnapshotChecks, including read-to-list retries.
|
|
3618
|
+
* Recursively skips embedded/populated/included SOURCE comparisons using the
|
|
3619
|
+
* initiating READ model's captured setting, independently of LIST, root source
|
|
3620
|
+
* and output-value flags. Parent comparisons may still observe child mutation.
|
|
3621
|
+
* Stale grants/decisions can expose data; permissions, identities and detached copies
|
|
3622
|
+
* remain. Server model/default literal `true` only; warns on effective enablement.
|
|
3623
|
+
* Writes/dedicated subdocument operations/fresh helpers stay strict; retained handles
|
|
3624
|
+
* keep their mode after rollback. Never set from requests. Revisit/remove promptly.
|
|
3625
|
+
*/
|
|
3626
|
+
unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
|
|
3627
|
+
/**
|
|
3628
|
+
* TEMPORARY UNSAFE (default `false`): omit the initial output-association snapshot
|
|
3629
|
+
* copy for eligible LIST outputs and their authenticated descendants. Active only
|
|
3630
|
+
* with unsafeSkipListOutputSnapshotChecks=true; otherwise dormant (warns).
|
|
3631
|
+
* Skips this pass's native/BSON normalization and validation observations, which
|
|
3632
|
+
* can change exceptions, side effects and permission outcomes. Exact ownership,
|
|
3633
|
+
* bounded shape admission and graph identities remain; proxies/Map/Set and open
|
|
3634
|
+
* ownership bindings use the original copy fallback. Source snapshots and detached
|
|
3635
|
+
* hook/grant/response copies remain. Not a general clone bypass. Server model/default literal true
|
|
3636
|
+
* only; warns on activation. Captured before awaits; retained handles keep their
|
|
3637
|
+
* mode after rollback. READ/retries use their own flag; writes/fresh helpers stay
|
|
3638
|
+
* strict. Restore false promptly; never select from requests or method defaults.
|
|
3639
|
+
*/
|
|
3640
|
+
unsafeSkipListInitialOutputSnapshotCopy?: boolean;
|
|
3641
|
+
/**
|
|
3642
|
+
* TEMPORARY UNSAFE (default `false`): READ equivalent of
|
|
3643
|
+
* unsafeSkipListInitialOutputSnapshotCopy, including READ-to-list retries and
|
|
3644
|
+
* authenticated embedded/populated/included outputs. Requires the independent
|
|
3645
|
+
* unsafeSkipReadOutputSnapshotChecks=true. Uses the initiating READ model's
|
|
3646
|
+
* captured setting, not LIST/target flags. Omits initial native normalization
|
|
3647
|
+
* observations; ownership/bounds/identities and detached callback/source copies
|
|
3648
|
+
* remain. Proxies/Map/Set fall back to copying. Server model/default literal true
|
|
3649
|
+
* only; warns on activation/dormancy. Writes/fresh helpers stay strict. Captured
|
|
3650
|
+
* handles do not change on rollback. Never derive from requests; restore false.
|
|
3651
|
+
*/
|
|
3652
|
+
unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
|
|
3479
3653
|
}
|
|
3480
3654
|
interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
|
|
3481
3655
|
'hydration.publicList'?: HydrationMode;
|
|
@@ -3515,6 +3689,8 @@ interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultMod
|
|
|
3515
3689
|
* named method query/presentation defaults. Trusted service authorization is per-call.
|
|
3516
3690
|
* Router setters update live behavior shallowly; router.options retains its frozen
|
|
3517
3691
|
* construction-time snapshot. Route-shape options require constructing a new router.
|
|
3692
|
+
* Populate flags govern this model when it is the actual target, not refs leaving it.
|
|
3693
|
+
* Their model snapshots retain raw overrides; operation capture resolves live defaults.
|
|
3518
3694
|
*/
|
|
3519
3695
|
interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends DefaultModelRouterOptions<TModel> {
|
|
3520
3696
|
modelName?: string;
|
|
@@ -3553,13 +3729,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
|
|
|
3553
3729
|
* that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
|
|
3554
3730
|
* { ref: Target }> separately, then assign here; persisted/write/public types
|
|
3555
3731
|
* stay unchanged. Register target models/options first in this runtime. Source
|
|
3556
|
-
* refs are retained automatically.
|
|
3732
|
+
* refs are retained automatically. The actual target's requireOperationAccessForPopulateDependencies
|
|
3557
3733
|
* defaults to true; false bypasses only private target-operation admission, never
|
|
3558
3734
|
* request read-row filters/retained IDs. Neither mode changes ordinary reference
|
|
3559
3735
|
* shape: admitted population keeps its original authorized mask/miss; otherwise
|
|
3560
3736
|
* selected/permitted parent fields keep exact original IDs, even on private failure.
|
|
3561
3737
|
* Only unselected/field-denied source refs are omitted. Query operation admission is
|
|
3562
|
-
* independently controlled by
|
|
3738
|
+
* independently controlled by that target's requireOperationAccessForPopulateQueries.
|
|
3563
3739
|
*
|
|
3564
3740
|
* @example Shortest typed happy-path (persisted model lacks `fullAddress`):
|
|
3565
3741
|
* ```ts
|