@web-ts-toolkit/access-router 0.68.0 → 0.69.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/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.68.0",
5
+ "version": "0.69.0",
6
6
  "sideEffects": [
7
7
  "./**/index.js",
8
8
  "./**/index.mjs",
@@ -57,8 +57,8 @@
57
57
  "node": ">=24"
58
58
  },
59
59
  "dependencies": {
60
- "@web-ts-toolkit/express-json-router": "0.68.0",
61
- "@web-ts-toolkit/utils": "0.68.0",
60
+ "@web-ts-toolkit/express-json-router": "0.69.0",
61
+ "@web-ts-toolkit/utils": "0.69.0",
62
62
  "just-diff": "^6.0.2",
63
63
  "mongoose-schema-jsonschema": "^4.0.1",
64
64
  "sift": "^17.1.3",
@@ -341,13 +341,24 @@ type PopulateAccess = 'list' | 'read';
341
341
  * remain enforced; direct/root target guards stay independent. Callers cannot supply
342
342
  * a model or either populate policy flag here. Private dependsOnPopulate declarations
343
343
  * have a narrower one-hop static-string ObjectId/same-connection contract.
344
+ * Service population checks the source relationship under its owning parent's
345
+ * effective output-field access, selection, captured authority and document facts,
346
+ * not this descriptor's target access. Read-to-list fallback uses source list fields;
347
+ * create/update responses use read fields without changing their separate virtual
348
+ * or docPermissions accesses. Target access never grants source visibility, and a
349
+ * visible source never grants target operations, rows or fields. Request-only
350
+ * genPopulate instead uses positional access for source admission, without current document facts.
351
+ * Denied source output is omitted; permitted refs retain IDs if population is not
352
+ * admitted. Admitted target misses stay scalar null or filtered reference arrays.
344
353
  */
345
354
  interface Populate {
346
355
  path: string;
347
356
  select?: Projection;
348
357
  match?: unknown;
358
+ /** Target only: overrides query populateAccess, then the existing method/operation default. */
349
359
  access?: PopulateAccess;
350
360
  }
361
+ /** Dedicated subdocument population remains path/select-only, with no target access selector. */
351
362
  interface SubPopulate {
352
363
  path: string;
353
364
  select?: Projection;
@@ -3158,8 +3169,12 @@ interface SubdocumentDeleteAuthorization<P = unknown, C = unknown> {
3158
3169
  /**
3159
3170
  * Named request-only genPopulate options. Omission/undefined uses the root scope.
3160
3171
  * Use ordinary response segments (['contacts']), not positional ['contacts', 'sub'].
3172
+ * Positional access (default read) authorizes source request fields and supplies the
3173
+ * target default; descriptor access overrides only the target. No document hooks,
3174
+ * current document facts or captured parent output execution are available here.
3161
3175
  * Source fields, target operation/rows and persisted target fields retain request
3162
3176
  * checks. For explicit source/target output authority, use service query options.
3177
+ * scopePath is the only supported option; there is no separate sourceAccess option.
3163
3178
  */
3164
3179
  interface PopulatePlanningOptions {
3165
3180
  readonly scopePath?: readonly string[];
@@ -3278,7 +3293,12 @@ declare class Base<TModel = unknown, TVirtuals extends object = Record<never, ne
3278
3293
  genFilter(access?: BaseFilterAccess, filter?: Filter<TModel>): Promise<Filter<TModel>>;
3279
3294
  getIdentifier(): string | null;
3280
3295
  genIDFilter(id: string): Promise<Filter<TModel>>;
3281
- /** Request-only population; named scopePath uses response segments, never positional subPaths. */
3296
+ /**
3297
+ * Request-only population: positional access (default read) admits source fields
3298
+ * and supplies the target default; descriptor access overrides only the target.
3299
+ * No document hooks, current document facts or captured parent output execution.
3300
+ * The only option, scopePath, uses response segments, never positional subPaths.
3301
+ */
3282
3302
  genPopulate(access?: SelectAccess, populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<Populate[]>;
3283
3303
  /**
3284
3304
  * Fresh output-only planner: selection stays independent of additive server authority.
@@ -3522,7 +3542,12 @@ declare class Core {
3522
3542
  genQuerySelect<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, access: SelectAccess, targetFields?: Projection, options?: OutputPlanningOptions<TModel, TVirtuals>): Promise<string[]>;
3523
3543
  /** Persisted request-only populate admission; fetch planning is not field authority. */
3524
3544
  private requestPopulateSelect;
3525
- /** Request-only population. Use named response scopePath; positional subPaths are removed. */
3545
+ /**
3546
+ * Request-only population: positional access admits source fields and supplies
3547
+ * the target default; descriptor access overrides only the target. No document
3548
+ * hooks, current document facts or captured parent output execution. Only named
3549
+ * response scopePath is supported; positional subPaths are removed.
3550
+ */
3526
3551
  genPopulate(modelName: string, access?: SelectAccess | BaseFilterAccess, _populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<Populate[]>;
3527
3552
  validate(modelName: string, allowedData: unknown, access: ValidateAccess, context: ModelHookContext): Promise<boolean | unknown[]>;
3528
3553
  prepare<T>(modelName: string, allowedData: T, access: PrepareAccess, context: ModelHookContext): Promise<T>;
@@ -341,13 +341,24 @@ type PopulateAccess = 'list' | 'read';
341
341
  * remain enforced; direct/root target guards stay independent. Callers cannot supply
342
342
  * a model or either populate policy flag here. Private dependsOnPopulate declarations
343
343
  * have a narrower one-hop static-string ObjectId/same-connection contract.
344
+ * Service population checks the source relationship under its owning parent's
345
+ * effective output-field access, selection, captured authority and document facts,
346
+ * not this descriptor's target access. Read-to-list fallback uses source list fields;
347
+ * create/update responses use read fields without changing their separate virtual
348
+ * or docPermissions accesses. Target access never grants source visibility, and a
349
+ * visible source never grants target operations, rows or fields. Request-only
350
+ * genPopulate instead uses positional access for source admission, without current document facts.
351
+ * Denied source output is omitted; permitted refs retain IDs if population is not
352
+ * admitted. Admitted target misses stay scalar null or filtered reference arrays.
344
353
  */
345
354
  interface Populate {
346
355
  path: string;
347
356
  select?: Projection;
348
357
  match?: unknown;
358
+ /** Target only: overrides query populateAccess, then the existing method/operation default. */
349
359
  access?: PopulateAccess;
350
360
  }
361
+ /** Dedicated subdocument population remains path/select-only, with no target access selector. */
351
362
  interface SubPopulate {
352
363
  path: string;
353
364
  select?: Projection;
@@ -3158,8 +3169,12 @@ interface SubdocumentDeleteAuthorization<P = unknown, C = unknown> {
3158
3169
  /**
3159
3170
  * Named request-only genPopulate options. Omission/undefined uses the root scope.
3160
3171
  * Use ordinary response segments (['contacts']), not positional ['contacts', 'sub'].
3172
+ * Positional access (default read) authorizes source request fields and supplies the
3173
+ * target default; descriptor access overrides only the target. No document hooks,
3174
+ * current document facts or captured parent output execution are available here.
3161
3175
  * Source fields, target operation/rows and persisted target fields retain request
3162
3176
  * checks. For explicit source/target output authority, use service query options.
3177
+ * scopePath is the only supported option; there is no separate sourceAccess option.
3163
3178
  */
3164
3179
  interface PopulatePlanningOptions {
3165
3180
  readonly scopePath?: readonly string[];
@@ -3278,7 +3293,12 @@ declare class Base<TModel = unknown, TVirtuals extends object = Record<never, ne
3278
3293
  genFilter(access?: BaseFilterAccess, filter?: Filter<TModel>): Promise<Filter<TModel>>;
3279
3294
  getIdentifier(): string | null;
3280
3295
  genIDFilter(id: string): Promise<Filter<TModel>>;
3281
- /** Request-only population; named scopePath uses response segments, never positional subPaths. */
3296
+ /**
3297
+ * Request-only population: positional access (default read) admits source fields
3298
+ * and supplies the target default; descriptor access overrides only the target.
3299
+ * No document hooks, current document facts or captured parent output execution.
3300
+ * The only option, scopePath, uses response segments, never positional subPaths.
3301
+ */
3282
3302
  genPopulate(access?: SelectAccess, populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<Populate[]>;
3283
3303
  /**
3284
3304
  * Fresh output-only planner: selection stays independent of additive server authority.
@@ -3522,7 +3542,12 @@ declare class Core {
3522
3542
  genQuerySelect<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, access: SelectAccess, targetFields?: Projection, options?: OutputPlanningOptions<TModel, TVirtuals>): Promise<string[]>;
3523
3543
  /** Persisted request-only populate admission; fetch planning is not field authority. */
3524
3544
  private requestPopulateSelect;
3525
- /** Request-only population. Use named response scopePath; positional subPaths are removed. */
3545
+ /**
3546
+ * Request-only population: positional access admits source fields and supplies
3547
+ * the target default; descriptor access overrides only the target. No document
3548
+ * hooks, current document facts or captured parent output execution. Only named
3549
+ * response scopePath is supported; positional subPaths are removed.
3550
+ */
3526
3551
  genPopulate(modelName: string, access?: SelectAccess | BaseFilterAccess, _populate?: Populate | Populate[] | string | null, options?: PopulatePlanningOptions): Promise<Populate[]>;
3527
3552
  validate(modelName: string, allowedData: unknown, access: ValidateAccess, context: ModelHookContext): Promise<boolean | unknown[]>;
3528
3553
  prepare<T>(modelName: string, allowedData: T, access: PrepareAccess, context: ModelHookContext): Promise<T>;