@web-ts-toolkit/access-router 0.66.0 → 0.67.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/MIGRATION.md +342 -30
- package/README.md +273 -137
- package/advanced.d.mts +1 -1
- package/advanced.d.ts +1 -1
- package/advanced.js +291 -59
- package/advanced.mjs +291 -59
- package/index.d.mts +26 -23
- package/index.d.ts +26 -23
- package/index.js +755 -409
- package/index.mjs +784 -441
- package/llms.txt +3 -1
- package/package.json +4 -4
- package/{parsers-BiFHfrNd.d.mts → parsers-fSBARZSn.d.mts} +245 -170
- package/{parsers-BiFHfrNd.d.ts → parsers-fSBARZSn.d.ts} +245 -170
package/MIGRATION.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Access router: breaking migration
|
|
2
2
|
|
|
3
|
-
This guide describes the **
|
|
4
|
-
|
|
3
|
+
This guide describes the **breaking contract implemented by this package**.
|
|
4
|
+
Deploy a tested matching application/library revision. There are no legacy
|
|
5
5
|
aliases or mixed-version rolling-compatibility flags. Start with `isolated`.
|
|
6
6
|
|
|
7
7
|
One engine captures actor/policy at operation entry, normalizes facts once per
|
|
@@ -10,6 +10,280 @@ its diagnostic context have **no reusable authorization authority**. Neither mod
|
|
|
10
10
|
is a callback sandbox, database transaction, rollback mechanism, external-cache
|
|
11
11
|
freshness guarantee, blanket security-equivalence claim or performance promise.
|
|
12
12
|
|
|
13
|
+
## Breaking change: nested operation access
|
|
14
|
+
|
|
15
|
+
**Hard removal, no compatibility period.** Flat operation-access variants and their
|
|
16
|
+
public flat-name type are removed. There are no aliases, automatic translation, or
|
|
17
|
+
warning-only deprecations. Model, model-default and data bulk/dotted/fluent updates
|
|
18
|
+
reject removed keys before publishing partial policy, including keys set to undefined.
|
|
19
|
+
|
|
20
|
+
### Replace flat variants with per-operation rules
|
|
21
|
+
|
|
22
|
+
Each operation accepts either a scalar `Validation` or an object with four optional
|
|
23
|
+
`Validation` members: `default`, `basic`, `advanced`, and `root`. `Validation` still
|
|
24
|
+
means boolean, permission string, permission-string array, or a synchronous/async
|
|
25
|
+
request-bound guard; the new structure is not limited to booleans.
|
|
26
|
+
|
|
27
|
+
Before (historical):
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
operationAccess: {
|
|
31
|
+
read: 'canRead',
|
|
32
|
+
basicRead: true,
|
|
33
|
+
advancedRead: 'admin',
|
|
34
|
+
subs: {
|
|
35
|
+
comments: { read: 'canReadComments', advancedRead: 'moderator' },
|
|
36
|
+
},
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
After (public target types, compiled through root and `./advanced` declarations):
|
|
41
|
+
|
|
42
|
+
<!-- doc-example: partial -->
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import type { OperationAccess, OperationAccessContext, OperationAccessRule } from '@web-ts-toolkit/access-router';
|
|
46
|
+
import type { OperationAccessVariants } from '@web-ts-toolkit/access-router/advanced';
|
|
47
|
+
|
|
48
|
+
const context: OperationAccessContext = 'root';
|
|
49
|
+
const read: OperationAccessVariants = {
|
|
50
|
+
default: 'canRead',
|
|
51
|
+
basic: true,
|
|
52
|
+
advanced: 'admin',
|
|
53
|
+
[context]: 'canRead', // optional: omitted root already falls back to default
|
|
54
|
+
};
|
|
55
|
+
const rule: OperationAccessRule = read;
|
|
56
|
+
const operationAccess: OperationAccess = {
|
|
57
|
+
read: rule,
|
|
58
|
+
subs: {
|
|
59
|
+
comments: {
|
|
60
|
+
read: { default: 'canReadComments', advanced: 'moderator' },
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
void operationAccess;
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Move the old base operation guard to its nested `default` when adding variant
|
|
68
|
+
members. An omitted `root` inherits that default, preserving the old root entry
|
|
69
|
+
guard; the explicit `root: 'canRead'` above is optional. Set `root: false` to deny
|
|
70
|
+
that target's read entries through the root/batch router independently of direct
|
|
71
|
+
read endpoints. Scalar operation rules, e.g. `read: 'canRead'`, remain supported.
|
|
72
|
+
|
|
73
|
+
| Removed operation-access keys | Replacement members |
|
|
74
|
+
| ----------------------------------- | ------------------------------------- |
|
|
75
|
+
| `basicList`, `advancedList` | `list.basic`, `list.advanced` |
|
|
76
|
+
| `basicRead`, `advancedRead` | `read.basic`, `read.advanced` |
|
|
77
|
+
| `basicCreate`, `advancedCreate` | `create.basic`, `create.advanced` |
|
|
78
|
+
| `basicUpdate`, `advancedUpdate` | `update.basic`, `update.advanced` |
|
|
79
|
+
| `basicUpsert`, `advancedUpsert` | `upsert.basic`, `upsert.advanced` |
|
|
80
|
+
| `basicCount`, `advancedCount` | `count.basic`, `count.advanced` |
|
|
81
|
+
| `basicDistinct`, `advancedDistinct` | `distinct.basic`, `distinct.advanced` |
|
|
82
|
+
|
|
83
|
+
Inside `subs.<field>`, replace the former four flat list/read variants in the same
|
|
84
|
+
way: `subs.comments.basicRead` becomes `subs.comments.read.basic`. Subdocument
|
|
85
|
+
create/update/delete also accept scalar-or-object rules. Defined field scalars such
|
|
86
|
+
as `subs.attachments: true` continue to supply that field's operation fallback.
|
|
87
|
+
Remove imports of the flat-name `RouteVariantAccess` type. Use
|
|
88
|
+
`OperationAccessContext`, `OperationAccessVariants` and `OperationAccessRule` from
|
|
89
|
+
the package root or `./advanced`, rather than concatenated key names.
|
|
90
|
+
Removed flat configuration keys reject with migration diagnostics rather than
|
|
91
|
+
being interpreted as custom accesses or automatically translated.
|
|
92
|
+
|
|
93
|
+
### Entry points and fallback
|
|
94
|
+
|
|
95
|
+
All seven pairs select independent members (paths relative to the target base):
|
|
96
|
+
|
|
97
|
+
| Operation | Basic direct endpoint | Advanced direct endpoint | Root entry member |
|
|
98
|
+
| ---------- | ---------------------- | --------------------------------------------- | ----------------- |
|
|
99
|
+
| `list` | `GET /` | `POST /__query` | `list.root` |
|
|
100
|
+
| `read` | `GET /:id` | `POST /__query/:id`, `POST /__query/__filter` | `read.root` |
|
|
101
|
+
| `create` | `POST /` | `POST /__mutation` | `create.root` |
|
|
102
|
+
| `update` | `PATCH /:id` | `PATCH /__mutation/:id` | `update.root` |
|
|
103
|
+
| `upsert` | `PUT /` | `PUT /__mutation` | `upsert.root` |
|
|
104
|
+
| `count` | `GET /count` | `POST /count` | `count.root` |
|
|
105
|
+
| `distinct` | `GET /distinct/:field` | `POST /distinct/:field` | `distinct.root` |
|
|
106
|
+
|
|
107
|
+
Paths are relative to the target's base path and use default route segments.
|
|
108
|
+
Data-router list/read and subdocument list/read follow the same context mapping.
|
|
109
|
+
HEAD follows its GET's basic member. Unpaired direct new/delete and subdocument mutation
|
|
110
|
+
routes choose `basic`; their root counterparts choose `root`. Both root
|
|
111
|
+
`subUpdate` and `subBulkUpdate` use the field's `update.root`. No new advanced
|
|
112
|
+
endpoint or root wire `op` name is introduced. Setting `advanced` on an unpaired
|
|
113
|
+
operation does not create an endpoint. Context is explicit server-owned dispatch
|
|
114
|
+
metadata, not inferred from POST or a caller-selected access string.
|
|
115
|
+
|
|
116
|
+
Top-level fallback is:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
operation.<basic | advanced | root>
|
|
120
|
+
-> operation.default (or the operation's scalar rule)
|
|
121
|
+
-> operationAccess.default (or scalar operationAccess shorthand)
|
|
122
|
+
-> deny
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Only `undefined` inherits. A selected false/empty-array/false-returning guard
|
|
126
|
+
denies immediately; it is not combined with another guard. An empty top-level
|
|
127
|
+
operation object can inherit `operationAccess.default`. Model runtime exact-path
|
|
128
|
+
defaults still participate before general fallback: a runtime-default
|
|
129
|
+
`read.advanced` can outrank a model's scalar `read` or `read.default`. Set the model's
|
|
130
|
+
own context member to override it. Configuration still replaces objects shallowly;
|
|
131
|
+
this is not recursive merging of model and runtime-default objects. The selected
|
|
132
|
+
operation object supplies its own `default`; a defined model `read: {}` does not
|
|
133
|
+
independently inherit a runtime `read.default`. A whole operation inherited by the
|
|
134
|
+
existing base lookup can supply its own default. These defaults always belong to
|
|
135
|
+
the same runtime as the model; they are not process-global catch-alls.
|
|
136
|
+
|
|
137
|
+
For a defined subdocument field, use its operation's context member, then its scalar
|
|
138
|
+
or nested `default`, then deny. Missing operations in a defined field object do
|
|
139
|
+
**not** inherit top-level operations or `operationAccess.default`. An absent field
|
|
140
|
+
rule uses the corresponding top-level operation/context. A field-level
|
|
141
|
+
`subs.comments.default` is not a new wildcard fallback, and scalar `subs` is not
|
|
142
|
+
made an umbrella guard. Existing runtime exact-path specificity still applies.
|
|
143
|
+
|
|
144
|
+
Omitting model `operationAccess` inherits configured model defaults; without any
|
|
145
|
+
applicable grant, model operations deny. `operationAccess: true` explicitly supplies
|
|
146
|
+
the scalar allow fallback. Explicit model `operationAccess: undefined` retains its
|
|
147
|
+
existing exact-key-only runtime fallback, not inheritance of runtime bare/outer
|
|
148
|
+
`.default` catch-alls. Data routers do not inherit model defaults. Invalid defined
|
|
149
|
+
JavaScript values deny instead of falling through to an allowed default.
|
|
150
|
+
|
|
151
|
+
The root router's **own** scalar `operationAccess` still guards the outer batch
|
|
152
|
+
endpoint. A target's `read.root` is an additional per-entry decision, not a
|
|
153
|
+
replacement for that outer guard. Root being POST does not select `advanced`.
|
|
154
|
+
Direct denials remain 401; root target denials keep per-entry unauthorized results.
|
|
155
|
+
Denied routes remain registered and visible in endpoint listings/OpenAPI.
|
|
156
|
+
|
|
157
|
+
<!-- doc-example: partial -->
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
import { createAccessRuntime } from '@web-ts-toolkit/access-router';
|
|
161
|
+
|
|
162
|
+
const api = createAccessRuntime();
|
|
163
|
+
const data = api.createDataRouter('Catalog', {
|
|
164
|
+
basePath: '/catalog',
|
|
165
|
+
idParam: 'id',
|
|
166
|
+
idField: 'id',
|
|
167
|
+
data: [{ id: 'one', name: 'One' }],
|
|
168
|
+
operationAccess: { list: true, read: { default: false, basic: false, advanced: false, root: true } },
|
|
169
|
+
permissionSchema: { id: true, name: true },
|
|
170
|
+
});
|
|
171
|
+
const batch = api.createRouter({ basePath: '/batch', operationAccess: 'canBatch' });
|
|
172
|
+
// Mount data.routes and batch.routes in an Express app with express.json().
|
|
173
|
+
// A root read still requires the independent outer canBatch guard; both direct reads deny.
|
|
174
|
+
void [data, batch];
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Keep transport entry separate from base policy
|
|
178
|
+
|
|
179
|
+
Existing context-free operation checks select the operation's scalar or nested
|
|
180
|
+
`default`, followed by the applicable outer fallback. They never choose `basic`,
|
|
181
|
+
`advanced`, or `root` merely because the initiating request used that entry point.
|
|
182
|
+
This includes existing populate/include target checks, private populated dependency
|
|
183
|
+
checks when required by target policy, READ-to-LIST retry, and subdocument mutation
|
|
184
|
+
response visibility. Existing populate-policy flags and trusted service admission
|
|
185
|
+
remain unchanged. Transport grants do not grant fields or related targets;
|
|
186
|
+
`permissionSchema`, row policy, and hook access names continue to use base operations.
|
|
187
|
+
|
|
188
|
+
For example, `read: { default: false, root: true }` permits root read entry, but does
|
|
189
|
+
not grant context-free target read admission. Use `default` deliberately when
|
|
190
|
+
migrating old base guards; putting them only under `basic` would change secondary
|
|
191
|
+
and root behavior.
|
|
192
|
+
|
|
193
|
+
### Update setters, not unrelated schema names
|
|
194
|
+
|
|
195
|
+
Replace `router.operationAccess('basicRead', false)` with
|
|
196
|
+
`router.operationAccess('read.basic', false)`. Replace
|
|
197
|
+
`router.setOption('operationAccess.advancedRead', rule)` with
|
|
198
|
+
`router.setOption('operationAccess.read.advanced', rule)`, and use the same nested
|
|
199
|
+
paths for runtime model/default/data setters. Nested `undefined` restores the
|
|
200
|
+
documented fallback; whole-object assignment remains shallow replacement.
|
|
201
|
+
|
|
202
|
+
<!-- doc-example: partial -->
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
import mongoose from 'mongoose';
|
|
206
|
+
import { createAccessRuntime } from '@web-ts-toolkit/access-router';
|
|
207
|
+
|
|
208
|
+
const api = createAccessRuntime();
|
|
209
|
+
const Post = mongoose.model('MigrationPost', new mongoose.Schema({ title: String, comments: [{ text: String }] }));
|
|
210
|
+
const router = api.createRouter(Post, {
|
|
211
|
+
operationAccess: {
|
|
212
|
+
default: false,
|
|
213
|
+
read: { default: 'canRead', basic: true, advanced: 'admin' },
|
|
214
|
+
subs: {
|
|
215
|
+
comments: { read: { default: 'canReadComments', root: false }, create: { basic: 'canComment', root: false } },
|
|
216
|
+
closed: {}, // missing operations deny; outer default never opens this field
|
|
217
|
+
attachments: true, // scalar field fallback; absent fields instead use top-level rules
|
|
218
|
+
},
|
|
219
|
+
},
|
|
220
|
+
});
|
|
221
|
+
router.operationAccess('read.basic', false);
|
|
222
|
+
router.operationAccess('subs.comments.read.advanced', 'moderator');
|
|
223
|
+
router.setOption('operationAccess.read.root', false);
|
|
224
|
+
router.operationAccess('read.basic', undefined); // clear a member, not a whole permission string assignment
|
|
225
|
+
api.setModelOption(Post.modelName, 'operationAccess.read', { default: 'canRead', root: false });
|
|
226
|
+
api.setDefaultModelOption('operationAccess.read.advanced', 'admin');
|
|
227
|
+
const data = api.createDataRouter('MigrationData', { data: [], operationAccess: true }); // scalar shorthand
|
|
228
|
+
data.setOption('operationAccess.read', { default: true, root: false }); // keep scalar meaning explicitly
|
|
229
|
+
data.runtime.setDataOption('MigrationData', 'operationAccess.read.basic', true);
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Updating beneath a scalar replaces it with an object; explicitly keep its old guard
|
|
233
|
+
under `default` if needed. Generic `getModelOption`/`getDataOption` remain raw generic
|
|
234
|
+
fallback lookups, not the final entry resolver (they can return an operation object).
|
|
235
|
+
Exact getters inspect a path; they do not evaluate a route. Setters remain live for
|
|
236
|
+
fresh work, construction snapshots remain frozen, and in-flight captured policy
|
|
237
|
+
retains its owning actor/runtime/defaults across updates.
|
|
238
|
+
|
|
239
|
+
Search operation-access configurations and their dotted/fluent paths for removed
|
|
240
|
+
flat names. Do **not** rename `requestSchemas.advancedRead`, request-schema exports,
|
|
241
|
+
client read/list method names, business fields, or permission names. Nested context
|
|
242
|
+
paths are configuration, not new request-selectable operations or populate access
|
|
243
|
+
values. Wire populate access remains `read`/`list`; retired and nested route-only
|
|
244
|
+
selectors must not become alternate target-authorization capabilities.
|
|
245
|
+
|
|
246
|
+
## Field permission maps are disabled by default
|
|
247
|
+
|
|
248
|
+
`disableFieldPermissions` now defaults to `true`. `_view`/`_edit` maps and their
|
|
249
|
+
placeholders are no longer computed or emitted, even when a request or method
|
|
250
|
+
default sets `includeFieldPermissions: true`. Permission enforcement and
|
|
251
|
+
`docPermissions`-hook keys (controlled by `includePermissions`) are unchanged.
|
|
252
|
+
|
|
253
|
+
To retain field maps, explicitly set `disableFieldPermissions: false` on the model
|
|
254
|
+
or use `api.setDefaultModelOptions({ disableFieldPermissions: false })` for runtime
|
|
255
|
+
model defaults. Use `stripPermissionsField: true` to remove the metadata field entirely.
|
|
256
|
+
|
|
257
|
+
## Replace global private-fetch inputs with document-permission descriptors
|
|
258
|
+
|
|
259
|
+
`alwaysSelectFields` is removed entirely: no option, dotted option, fluent setter,
|
|
260
|
+
default or compatibility alias. For each hook that needs extra projected data,
|
|
261
|
+
replace its function with `{ dependsOn: ['ownerId'], get: existingFunction }`.
|
|
262
|
+
Functions remain valid and add no private fetch inputs. Direct descriptors and
|
|
263
|
+
per-access/default/custom entries share the same contract; use `get`, not `getter`.
|
|
264
|
+
|
|
265
|
+
Only the active `docPermissionsAccess` supplies inputs (exact entry, then `default`
|
|
266
|
+
if undefined); it is not unioned with output/read or virtual access. Declare each
|
|
267
|
+
definition's actual inputs, not a global union. Hook/dependencies are captured as a
|
|
268
|
+
pair before awaits. Absent/empty dependencies add nothing. Missing/undefined values
|
|
269
|
+
never skip `get`. Inputs grant no output: selection and authorization still apply,
|
|
270
|
+
including exclusions and denied fields. Virtuals retain their own dependencies.
|
|
271
|
+
|
|
272
|
+
Use top-level persisted schema keys only, like virtuals. Dotted, unsafe, unknown and
|
|
273
|
+
virtual inputs reject. Move old nested paths such as `profile.ownerId` to the whole
|
|
274
|
+
`profile` container. Dotted access setters such as
|
|
275
|
+
`router.set('docPermissions.read', { dependsOn: ['ownerId'], get: hook })` replace
|
|
276
|
+
whole definitions; partial `.get`/`.dependsOn` edits reject. Those member names are
|
|
277
|
+
reserved, not custom accesses. Malformed definitions, including null/false or mixed
|
|
278
|
+
descriptor/access keys, reject rather than silently disabling calculation. To override
|
|
279
|
+
default with no facts, provide an exact callback returning `{}`. Move inputs used only by virtuals onto their virtual
|
|
280
|
+
descriptors; remove forced fields with no consumer rather than inventing a hook.
|
|
281
|
+
|
|
282
|
+
Embedded scopes inherit owning-document facts; dedicated subdocument routes prepare
|
|
283
|
+
their owning parent. Populate/include targets resolve their own hook and inputs.
|
|
284
|
+
Pre-/post-write stages stay independent; raw output helpers do no hidden query or
|
|
285
|
+
document-hook computation. See the [typed shapes](README.md#document-permission-dependencies-breaking-change).
|
|
286
|
+
|
|
13
287
|
## M1. Replace rich grants with immutable boolean facts
|
|
14
288
|
|
|
15
289
|
Before (historical, not a target example):
|
|
@@ -43,11 +317,13 @@ const salaryRule: FieldPermissionHook = function (permissions, facts) {
|
|
|
43
317
|
const api = createAccessRuntime();
|
|
44
318
|
api.setModelOptions('Employee', {
|
|
45
319
|
modelPermissionPrefix: 'doc:',
|
|
46
|
-
alwaysSelectFields: ['ownerId'], // fetched privately, not selected/authorized output
|
|
47
320
|
docPermissions: {
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
321
|
+
read: {
|
|
322
|
+
dependsOn: ['ownerId'], // fetched privately, not selected/authorized output
|
|
323
|
+
async get(doc): Promise<DocumentGrants> {
|
|
324
|
+
const membership = await loadMembership(this, doc);
|
|
325
|
+
return { canReadSalary: membership.canReadSalary === true };
|
|
326
|
+
},
|
|
51
327
|
},
|
|
52
328
|
},
|
|
53
329
|
permissionSchema: {
|
|
@@ -151,10 +427,13 @@ Removed from **output** contexts, with no renamed backing aliases:
|
|
|
151
427
|
data, query and diff fields. Use `ModelOutputHook` / `ModelOutputListHook` for
|
|
152
428
|
presentation annotations instead of lifecycle `ModelHook` / `ModelListHook`.
|
|
153
429
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
430
|
+
For output, `isolated` doc hooks get disposable detached views, including supported
|
|
431
|
+
mutable native leaves. In `trusted`, an admitted ordinary source/doc-hook input may
|
|
432
|
+
be borrowed: mutations can affect values and facts the hook computes. Only query-origin
|
|
433
|
+
trusted output leaves hidden unvisited source graphs unbounded. Write output and its
|
|
434
|
+
related targets always acquire a full bounded detached source first; trusted omits
|
|
435
|
+
only the subsequent disposable hook-view copy (see M4). The existing hydrated pre-write
|
|
436
|
+
UPDATE hook is unchanged; these output guarantees are not an input-hook sandbox.
|
|
158
437
|
**Only source borrowing relaxes**; captured actor, private policy and normalized
|
|
159
438
|
facts remain immutable. Neither Object.freeze nor a readonly native type makes
|
|
160
439
|
arbitrary Date/Buffer/BSON/Map methods immutable.
|
|
@@ -280,7 +559,7 @@ export function presentationSubset(rows: readonly { readonly name?: string }[])
|
|
|
280
559
|
```
|
|
281
560
|
|
|
282
561
|
For current document-dependent facts, use a **new normal LIST**, not either raw
|
|
283
|
-
recipe or an output grant. Configure `
|
|
562
|
+
recipe or an output grant. Configure the applicable `docPermissions.dependsOn` for
|
|
284
563
|
private hook inputs on the model; keep normal row policy. After an earlier LIST:
|
|
285
564
|
|
|
286
565
|
<!-- doc-example: partial -->
|
|
@@ -405,7 +684,6 @@ async function runOwnedAuthorizationExample() {
|
|
|
405
684
|
operationAccess: { read: true },
|
|
406
685
|
hydration: { findById: 'lean' },
|
|
407
686
|
modelPermissionPrefix: 'doc:',
|
|
408
|
-
alwaysSelectFields: ['ownerId'],
|
|
409
687
|
stripPermissionsField: true,
|
|
410
688
|
baseFilter: { read: () => ({ visible: true }) },
|
|
411
689
|
permissionSchema: {
|
|
@@ -415,12 +693,15 @@ async function runOwnedAuthorizationExample() {
|
|
|
415
693
|
allowance: { read: ['isHR', 'doc:canReadSalary'] }, // OR
|
|
416
694
|
},
|
|
417
695
|
docPermissions: {
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
696
|
+
read: {
|
|
697
|
+
dependsOn: ['ownerId'],
|
|
698
|
+
async get(doc, _permissions, context): Promise<DocumentGrants> {
|
|
699
|
+
hooks++;
|
|
700
|
+
assert.ok(Object.isFrozen(context));
|
|
701
|
+
assert.equal('currentDocument' in context, false);
|
|
702
|
+
const membership = await loadMembership(this, doc);
|
|
703
|
+
return { canReadSalary: membership.canReadSalary === true };
|
|
704
|
+
},
|
|
424
705
|
},
|
|
425
706
|
},
|
|
426
707
|
});
|
|
@@ -562,7 +843,12 @@ void readEmployeeForBusinessWork;
|
|
|
562
843
|
Related targets use **their own** captured policy/facts/mode; the unchanged
|
|
563
844
|
README runnable service/related example demonstrates separate scoped policies.
|
|
564
845
|
|
|
565
|
-
## M4.
|
|
846
|
+
## M4. Four independent server authorization modes
|
|
847
|
+
|
|
848
|
+
Keep `readAuthorizationMode` / `listAuthorizationMode`; configure
|
|
849
|
+
`createAuthorizationMode` / `updateAuthorizationMode` for CREATE/UPDATE **post-write
|
|
850
|
+
output only**. All four use `AuthorizationMode = 'isolated' | 'trusted'` and default
|
|
851
|
+
to isolated. There is no renamed-key migration, alias or separate UPSERT option.
|
|
566
852
|
|
|
567
853
|
Before: combinations of comparison/copy/fast-path booleans. There is **no one-to-one
|
|
568
854
|
mapping** for old mixed configurations and no dormant prerequisite combination.
|
|
@@ -572,8 +858,18 @@ mapping** for old mixed configurations and no dormant prerequisite combination.
|
|
|
572
858
|
```ts
|
|
573
859
|
import { createAccessRuntime } from '@web-ts-toolkit/access-router';
|
|
574
860
|
const api = createAccessRuntime();
|
|
575
|
-
api.setDefaultModelOptions({
|
|
576
|
-
|
|
861
|
+
api.setDefaultModelOptions({
|
|
862
|
+
readAuthorizationMode: 'isolated',
|
|
863
|
+
listAuthorizationMode: 'isolated',
|
|
864
|
+
createAuthorizationMode: 'isolated',
|
|
865
|
+
updateAuthorizationMode: 'isolated',
|
|
866
|
+
});
|
|
867
|
+
api.setModelOptions('Employee', {
|
|
868
|
+
readAuthorizationMode: 'isolated',
|
|
869
|
+
listAuthorizationMode: 'trusted',
|
|
870
|
+
createAuthorizationMode: 'trusted',
|
|
871
|
+
updateAuthorizationMode: 'isolated',
|
|
872
|
+
});
|
|
577
873
|
api.setModelOptions('Payroll', { readAuthorizationMode: 'isolated', listAuthorizationMode: 'isolated' });
|
|
578
874
|
api.setModelOption('Employee', 'listAuthorizationMode', undefined); // restore live default inheritance
|
|
579
875
|
api.setDefaultModelOption('listAuthorizationMode', 'isolated');
|
|
@@ -655,13 +951,29 @@ The new keys are also prohibited in HTTP/query/body/root-batch, per-call/helper,
|
|
|
655
951
|
method-default, include/populate and subquery **authority namespaces**. Persisted
|
|
656
952
|
business data/filter fields with the same names remain inert ordinary data.
|
|
657
953
|
|
|
658
|
-
Capture happens before hooks/awaits.
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
954
|
+
Capture happens before hooks/awaits. Root READ/LIST select their matching setting;
|
|
955
|
+
READ-to-LIST retry retains READ with a fresh stage. CREATE (including bulk) and
|
|
956
|
+
UPDATE select their settings only after persistence/lifecycle processing. Both
|
|
957
|
+
UPSERT branches select the executed branch's captured mode, retaining initiating
|
|
958
|
+
`operation: 'upsert'` and its branch accesses, not re-reading live configuration.
|
|
959
|
+
|
|
960
|
+
**Both write modes always acquire a full bounded detached source**, including mutable
|
|
961
|
+
native leaves. Trusted omits only the subsequent disposable document-hook view copy;
|
|
962
|
+
it cannot borrow live write documents, `_doc`, payloads or lifecycle snapshots.
|
|
963
|
+
Conversion failure at this boundary fails output rather than falling back to `_doc`.
|
|
964
|
+
Write-input authority, pre-write grants, the hydrated pre-write UPDATE hook,
|
|
965
|
+
validation/preparation/transform/save and lifecycle contracts are unchanged, not
|
|
966
|
+
newly detached or sandboxed. No implicit save/query/rollback is added; an output
|
|
967
|
+
error may occur **after persistence**, so do not automatically retry the write.
|
|
968
|
+
|
|
969
|
+
Embedded output inherits its genuine owner's mode/facts. Related targets select
|
|
970
|
+
their **own model's READ/LIST mode** at effective target access, including genuine
|
|
971
|
+
write-origin populate, with independent policy/facts. Parent mode cannot lower an
|
|
972
|
+
isolated target; a trusted target cannot mutate an isolated parent's source or live
|
|
973
|
+
write graph. Write-origin targets still require mandatory full bounded detachment:
|
|
974
|
+
the trusted-query exception for hidden unvisited graphs does not apply. Independent
|
|
975
|
+
callback service calls capture anew. NEW, helpers, dedicated subdocument origins,
|
|
976
|
+
COUNT/DELETE/DISTINCT and unsupported custom origins gain no trusted stage.
|
|
665
977
|
|
|
666
978
|
For decorators, configure modes on `@Router`/`@RouterOptions`, or factory
|
|
667
979
|
`defaultModelOptions`, never request input. Decorated hook `this` is the **class
|
|
@@ -669,7 +981,7 @@ instance**; obtain the original request with `@Request()`. See the matching
|
|
|
669
981
|
access-router-deco README's executable owned-authorization module.
|
|
670
982
|
|
|
671
983
|
Roll out a tested matching application/library revision, default isolated, inspect
|
|
672
|
-
workload behavior and then opt individual
|
|
984
|
+
workload behavior and then opt individual operation owners into trusted deliberately.
|
|
673
985
|
Switching back to isolated affects **new calls only**; in-flight captures do not
|
|
674
986
|
change. Deployment rollback requires a tested matching application **and library**
|
|
675
987
|
revision, not adding removed flags to this version or assuming mixed rolling safety.
|