@stonyx/orm 0.3.2-beta.160 → 0.3.2-beta.162

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.
@@ -1,274 +1,3 @@
1
- /**
2
- * REST request handling and access enforcement for @stonyx/orm.
3
- *
4
- * ---------------------------------------------------------------------------
5
- * THE `access()` CONTRACT: `access(request, { model, operation })`
6
- * ---------------------------------------------------------------------------
7
- * `auth()` calls your predicate with TWO arguments. The second is the access
8
- * CONTEXT -- the structural facts about the request, which the framework
9
- * already holds and which you should read INSTEAD of parsing anything:
10
- *
11
- * context.model The model this route was mounted for, as a model name:
12
- * kebab-case, exactly as declared under
13
- * `config.orm.paths.model` and keyed in the store --
14
- * `'owner'`, `'animal'`, `'phone-number'`. NOT the
15
- * pluralised, dasherized, mount-prefixed ROUTE name. It is
16
- * read from the OrmRequest instance, fixed at mount time,
17
- * and no request can influence it.
18
- *
19
- * context.operation The operation being authorised. Exactly one of the four
20
- * verbs `'read'`, `'create'`, `'update'`, `'delete'` --
21
- * no second vocabulary ON THIS PATH, and never an HTTP
22
- * method name like `'GET'`. These are the same four
23
- * strings the permission-array return shape is written in
24
- * (`['read', 'create']`), because both come from the one
25
- * `methodAccessMap` below.
26
- *
27
- * NOT the hook vocabulary. `HookContext.operation`
28
- * (`src/hooks.ts`, documented under "Hook Context Object"
29
- * in the README) carries `'list' | 'get' | 'create' |
30
- * 'update' | 'delete'` on an identically-named key of an
31
- * identically-shaped context object, and the access
32
- * vocabulary collapses `list` and `get` into `'read'`. For
33
- * one `GET /animals/1` a hook sees `'get'` and `access()`
34
- * sees `'read'`, so a predicate cannot tell a collection
35
- * read from a record read. `AccessOperation` makes
36
- * `operation === 'get'` a compile error for a TypeScript
37
- * consumer, because a predicate that stops matching falls
38
- * through to the permission array -- the misreading is
39
- * fail-open shaped.
40
- *
41
- * `undefined` when the dispatched method has no entry in
42
- * that map. Express delivers `HEAD` to the `GET` handler,
43
- * so this is reachable. It is left undefined rather than
44
- * defaulted on purpose -- a fabricated `'read'` would turn
45
- * an unclassified request into an authorised one. Treat
46
- * `undefined` as "not classified" and deny.
47
- *
48
- * So a consumer writes `if (model === 'owner' && operation === 'read')`. There
49
- * is no string to parse, no variant to miss, and no way to fail open through a
50
- * URL shape nobody anticipated.
51
- *
52
- * WHAT THE CONTEXT DOES NOT TELL YOU: WHICH SURFACE. It names the model and
53
- * the verb, not the route. Measured over the live router, six surfaces produce
54
- * one identical context:
55
- *
56
- * GET /owners { model: 'owner', operation: 'read' }
57
- * GET /owners/gina { model: 'owner', operation: 'read' }
58
- * GET /owners/gina/pets { model: 'owner', operation: 'read' }
59
- * GET /owners/gina/relationships/pets { model: 'owner', operation: 'read' }
60
- * GET /owners/archived { model: 'owner', operation: 'read' }
61
- * GET /owners/gina?include=pets { model: 'owner', operation: 'read' }
62
- *
63
- * So a rule that depends on the SUB-PATH still needs `request.path` -- which is
64
- * mount-relative and query-free, and is the one read of argument one the
65
- * warning below sanctions. This repo's own fixture has such a rule: its
66
- * `/archived` deny cannot be expressed from the context alone, and a predicate
67
- * migrated to context-only would silently drop it, turning a deny into an
68
- * allow.
69
- *
70
- * THE RELATED-RESOURCE HALF OF THAT SENTENCE IS NOW OUT OF DATE AND IS
71
- * CORRECTED HERE RATHER THAN DELETED. Both relationship route families resolve
72
- * the RELATED model's own access class and ask it
73
- * `{ model: <related>, operation: 'read', recordId: null }`
74
- * (abofs/stonyx-orm#232), so those surfaces no longer serve another model's
75
- * records under `model: 'owner'` unexamined. What the context still gives no
76
- * signal of is WHICH related record is being asked about -- `recordId` is
77
- * `null` there and `request.params` names a record of a different model. See
78
- * `AccessContext.recordId` in ./types/orm-types.ts for the full statement of
79
- * that limit. `?include=` is still unfiltered and is abofs/stonyx-orm#233 /
80
- * #235.
81
- *
82
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237, AND KEPT FOR THE
83
- * CONSTRAINT IT STATES RATHER THAN AS A DESCRIPTION OF THE CODE. The context
84
- * now also carries `recordId` -- the DECODED route-parameter id, see
85
- * `AccessContext.recordId` in ./types/orm-types.ts -- so the fixture's
86
- * `/archived` deny IS expressible from the context alone, and the shipped
87
- * sample no longer reads `request.path` at all. Retiring this wording WITH the
88
- * measurement that retires it, rather than by deletion, is
89
- * abofs/stonyx-orm#238.
90
- *
91
- * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
92
- * matching but BEFORE any handler executes (`@stonyx/rest-server`
93
- * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
94
- * record would force a pre-fetch on every request, a second store hit and an
95
- * ordering change in the middle of an authorization path. It is also
96
- * unnecessary: the FUNCTION return shape already is the per-record hook. Return
97
- * `(record) => boolean` and the handlers apply it to every record the request
98
- * touches. Auth-time and record-time are separate decision points.
99
- *
100
- * THE SECOND ARGUMENT IS ADDITIVE. JavaScript ignores extra arguments, so an
101
- * existing `access(request)` predicate keeps working exactly as before. The
102
- * warning immediately below is therefore still live: `request` is still
103
- * argument ONE, and reading it is still how predicates fail open.
104
- *
105
- * To reach ANOTHER model's predicate -- e.g. to check an animal while servicing
106
- * an owners route -- use the boot-time registry:
107
- *
108
- * const predicate = Orm.instance.getAccess('animal');
109
- * if (!predicate) return deny;
110
- * const verdict = predicate(request, { model: 'animal', operation: 'read' });
111
- *
112
- * `undefined` means NO PREDICATE COULD BE RESOLVED for that name -- which
113
- * includes the case where the model has an access class that failed to load,
114
- * because `setup-rest-server.ts` catches a load failure, warns, and publishes
115
- * whatever partial map it had. It does NOT mean the model is unrestricted.
116
- * Treat it as DENY, the same way `operation === undefined` is treated above.
117
- *
118
- * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not make
119
- * the answer model-correct on its own -- the resolved predicate has to READ it.
120
- * Measured against an ARITY-1 predicate, on a request express dispatched to
121
- * `GET /owners/angela`, asked about ANIMALS:
122
- *
123
- * getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
124
- * -> record => record.id !== 'angela' && record.id !== 'restricted'
125
- *
126
- * That is the OWNERS filter, and it returns `true` for animal 21 -- the record
127
- * hidden on every animal surface. Under a mount that predicate recognises
128
- * neither way it is worse: it falls through to
129
- * `['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
130
- * context was supplied and the answer is not the animal answer, and it is wrong
131
- * in the GRANTING direction, because that predicate is arity-1 and identifies
132
- * its collection from the request. (Asserted on a live dispatch by AC9 in
133
- * test/integration/orm-test.ts, against a deliberately arity-1 predicate.)
134
- *
135
- * This repo's own sample access class has since been MIGRATED to read the
136
- * context (abofs/stonyx-orm#222), so `getAccess('animal')` here now answers
137
- * with the animal filter. That is not true of a consumer tree: an arity-1
138
- * predicate keeps working -- the second argument is additive -- and the caller
139
- * has no supported way to tell which kind it got. The boot-time arity warning
140
- * that surfaces one is abofs/stonyx-orm#221.
141
- * So: pass the context, and do not treat a resolved predicate's answer as
142
- * model-specific until that predicate has been migrated to read the context.
143
- *
144
- * ---------------------------------------------------------------------------
145
- * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
146
- * ---------------------------------------------------------------------------
147
- * You do not have to. `auth()` below hands your predicate the ACCESS CONTEXT as
148
- * argument two, and `context.model` already names the collection -- see the
149
- * contract section above. Argument ONE is still the raw transport artifact, and
150
- * everything from here to the end of this banner is the record of what happened
151
- * when predicates worked the collection out from it. IT IS HISTORY, NOT
152
- * GUIDANCE: do not write any of it into a new predicate. Every attempt to
153
- * identify the collection by parsing the request target has failed OPEN. Five
154
- * distinct variants of the same three-line example have now been found, each
155
- * after the previous was fixed, by five different people:
156
- *
157
- * 1. `request.url` is mount-relative under `RestServer.mountRoute`, so a
158
- * prefix match against it is ALWAYS false.
159
- * 2. `request.originalUrl` carries the query string, so an anchored equality
160
- * check misses `/owners?filter[age]=30`.
161
- * 3. The router is a bare `express()` (`caseSensitive: false`) while a
162
- * hand-written matcher is case-SENSITIVE, so `GET /OwNeRs/angela` walks
163
- * past it. Router-side: abofs/stonyx-rest-server#47.
164
- * 4. Under a configured `ORM_REST_ROUTE` a hard-coded `/owners` matches
165
- * nothing -- environment-specifically, which is worse.
166
- * 5. HTTP/1.1 permits an ABSOLUTE-FORM request-target. Express routes on
167
- * `parseurl(req).pathname`, but `originalUrl` is the raw target, so
168
- * `GET http://anything.example/owners/angela` reaches the handler with
169
- * `originalUrl === 'http://anything.example/owners/angela'`. A `/owners`
170
- * prefix match is false, `access()` falls through to whatever it returns
171
- * last, and the record comes back in full. It walks past a hard
172
- * `return false` deny the same way.
173
- *
174
- * The fix is not a sixth rule, and it is not a better string to match. It is to
175
- * stop identifying the collection at all: read `context.model`. That is a claim
176
- * about IDENTIFYING THE COLLECTION, not about the sample as a whole -- the
177
- * `/archived` SUB-PATH rule is still a string match, and abofs/stonyx-orm#228 is
178
- * a sixth spelling that gets past it.
179
- *
180
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: the `/archived` rule is
181
- * no longer a string match against the request target -- it compares the
182
- * decoded `recordId` the framework supplies -- and abofs/stonyx-orm#228 is
183
- * CLOSED. Retirement of this wording: abofs/stonyx-orm#238.
184
- *
185
- * An intermediate revision of the sample read `request.baseUrl` -- the mount
186
- * Express ACTUALLY MATCHED. That closed all five variants (no query string,
187
- * not mount-relative, unaffected by absolute-form, already carrying the
188
- * configured `ORM_REST_ROUTE` prefix), but it was a transport artifact
189
- * standing in for a structural fact and the sample no longer does it.
190
- * `context.model` IS the structural fact, so variants 1, 2, 4 and 5 are
191
- * unconstructible against a migrated predicate rather than handled.
192
- *
193
- * VARIANT 3 SURVIVES, and is deliberately not in that list. It is the general
194
- * shape "a hand-written matcher normalises differently from the router", and a
195
- * migrated predicate still runs one string comparison for any SUB-PATH rule --
196
- * in the shipped sample, the `/archived` deny. That comparison folds case but
197
- * does not decode, so `GET /owners/%61rchived` steps past it. See the
198
- * normalisation paragraph below and abofs/stonyx-orm#228.
199
- *
200
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237. Variant 3 lived in that
201
- * one string comparison, and the comparison is gone: the sample compares the
202
- * decoded `recordId`. Left standing rather than edited because the same
203
- * "variant 3 survives" wording sits at four sites -- this header, README.md
204
- * twice, and test/sample/access/global-access.ts -- three of which SHIP, so
205
- * retiring one of four leaves the shipped copies contradicting each other.
206
- * Retiring all four WITH their measurement is abofs/stonyx-orm#238.
207
- *
208
- * ONE READ OF ARGUMENT ONE SURVIVES, AND IT MUST: `request.path`. It is
209
- * mount-relative and query-free, and it is for rules that distinguish SUB-PATHS
210
- * beneath the mount. The context names which model and which verb, NOT which
211
- * route, so the sample's `/archived` deny cannot be expressed from the context
212
- * alone and a context-ONLY rewrite would silently turn that deny into an allow.
213
- *
214
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: NO read of argument one
215
- * survives in the shipped sample. `recordId` names WHICH RECORD the route was
216
- * addressed to, so the `/archived` deny is expressible from the context alone
217
- * -- and it still must not be dropped; expressible is not optional. Retirement
218
- * of this wording: abofs/stonyx-orm#238.
219
- *
220
- * NORMALISE THE WAY THE ROUTER DOES, AND CASE-FOLDING ALONE IS NOT THAT. The
221
- * sample lower-cases before comparing, because a matcher stricter than the
222
- * case-insensitive router can be stepped around. That closes the case gap only.
223
- * Express sets `request.path` from the RAW, UNDECODED pathname while the router
224
- * DECODES `:id`, so `GET /owners/%61rchived` reaches a `path === '/archived'`
225
- * comparison as `/%61rchived` and walks past the deny. That gap is live in the
226
- * sample and is tracked as abofs/stonyx-orm#228; the `.toLowerCase()` is not a
227
- * complete normalisation recipe. Compare record ids at their real case.
228
- *
229
- * DO NOT FOLLOW THE PARAGRAPH ABOVE. SUPERSEDED 2026-09-01 BY
230
- * abofs/stonyx-orm#236/#237, and flagged here rather than merely dated because
231
- * it is an INSTRUCTION, not a stale observation. `.toLowerCase()` on the access
232
- * path was measured WRONG IN BOTH DIRECTIONS AT ONCE: with a distinct owner
233
- * seeded at `ARCHIVED`, `GET /owners/ARCHIVED` was a false DENY on the wrong
234
- * record and `GET /owners/%41RCHIVED` a false ALLOW on that same record. A
235
- * record id is a VALUE, not a literal route segment, and express's
236
- * `case sensitive routing` governs literal segments only. Compare
237
- * `context.recordId` AS IT ARRIVES: do not case-fold it, do not decode it, do
238
- * not derive it from `request.path`. `AccessContext.recordId` in
239
- * ./types/orm-types.ts is the contract and says "Do NOT case-fold it"; the same
240
- * published tarball ships both files, and THIS paragraph is the one that is
241
- * wrong. Retiring it WITH its measurement is abofs/stonyx-orm#238.
242
- *
243
- * `?? ''` is not a defence. It converts an absent request target into an empty
244
- * string, which matches no collection, which falls through to the permission
245
- * array -- a total grant. An input you cannot identify must DENY, and that
246
- * applies to BOTH arguments: since #202 the guard and the read can sit on
247
- * different objects, and a guard on argument two does not protect a read of
248
- * argument one. The sample returns `false` for an absent `model` AND for an
249
- * absent or non-string `request.path`, rather than falling through either way.
250
- *
251
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237 as to WHAT is guarded --
252
- * the principle is unchanged. The sample no longer reads `request.path`, so it
253
- * returns `false` for an absent `model` AND for an absent `recordId`
254
- * (`undefined`, the one spelling `auth()` never produces). Retirement of this
255
- * wording: abofs/stonyx-orm#238.
256
- *
257
- * THE REAL FIX IS abofs/stonyx-orm#202: `access()` should receive the model,
258
- * the operation and the record. Prefer the array shape (`['read']`) or `false`
259
- * until #202 lands; the function shape is what requires any matching at all.
260
- *
261
- * The enforcement gates in this file (GATE 0/1/2, the create rollback, the
262
- * per-handler `isDenied` re-checks) are correct independently of that -- they
263
- * enforce whatever predicate you return. The stopgap is the part where YOU have
264
- * to work out which predicate to return.
265
- *
266
- * AND A PREDICATE IS NOT A GUARANTEE THAT A HIDDEN RECORD CANNOT BE MODIFIED.
267
- * It is evaluated against the record the route is ADDRESSED TO, on that model
268
- * only. A write to a DIFFERENT collection can still re-parent a hidden record
269
- * and de-hide it -- abofs/stonyx-orm#207, which is blocked on #202 and #196.
270
- * See `### Known limitations` in README.
271
- */
272
1
  import { Request } from '@stonyx/rest-server';
273
2
  import Orm, { store, createRecord, updateRecord } from '@stonyx/orm';
274
3
  import { camelCaseToKebabCase } from '@stonyx/utils/string';
@@ -276,10 +5,8 @@ import { getPluralName } from './plural-registry.js';
276
5
  import { getBeforeHooks, getAfterHooks } from './hooks.js';
277
6
  import type { HookContext } from './hooks.js';
278
7
  import config from 'stonyx/config';
279
- import log from 'stonyx/log';
280
- import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
281
- import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
282
- import { interpretAccess, createLinkageFilter } from './access-verdict.js';
8
+ import type { OrmRecord } from './types/orm-types.js';
9
+ import { isOrmRecord } from './utils.js';
283
10
 
284
11
  interface OrmRequest$ extends Request {
285
12
  protocol?: string;
@@ -306,9 +33,10 @@ interface JsonApiResponse {
306
33
  included?: unknown[];
307
34
  }
308
35
 
36
+ type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
309
37
  type HandlerFn = (request: OrmRequest$, state: { [key: string]: unknown }) => unknown | Promise<unknown>;
310
38
 
311
- const methodAccessMap: { [key: string]: AccessOperation } = {
39
+ const methodAccessMap: { [key: string]: string } = {
312
40
  GET: 'read',
313
41
  POST: 'create',
314
42
  DELETE: 'delete',
@@ -356,128 +84,21 @@ function getBaseUrl(request: OrmRequest$): string {
356
84
  return `${protocol}://${host}`;
357
85
  }
358
86
 
359
- /**
360
- * The ONE coercion from a caller-supplied id to the key the store holds it
361
- * under. Every id-bearing surface in this file goes through it, and none has a
362
- * copy: `getId()` (URL params), `normalizeBodyId()` (JSON body), and the
363
- * post-create `context.record` lookup in `_withHooks`.
364
- *
365
- * WHY IT IS SHARED RATHER THAN DUPLICATED. `getId()` and `normalizeBodyId()`
366
- * each had their own arithmetic, and they disagreed: `parseInt(id)` versus
367
- * `parseInt(id, 10)`. On a hex-shaped id that is a two-record difference --
368
- *
369
- * GET /animals/0x2391 -> record 9105 (getId -> parseInt('0x2391') = 9105)
370
- * POST /animals {"id":"0x2391"} -> lookup under 0 (normalize -> parseInt('0x2391',10) = 0)
371
- * -> a MISS, so the duplicate check was skipped and
372
- * createRecord OVERWROTE 9105 in place, answering 200
373
- *
374
- * -- a narrower form of the raw-versus-normalised divergence that the body-id
375
- * normalisation was added to close, reintroduced by the fix for it. Two
376
- * coercions that must agree cannot be kept in agreement by review; they have to
377
- * be one function. Pinned by assertion 43.
378
- *
379
- * The third copy was found later and in a quieter place: `_withHooks` populated
380
- * `context.record` for `create` with `isNaN(id) ? id : parseInt(id)` -- this
381
- * function's body, inlined verbatim, feeding `store.get`. It was equivalent on
382
- * every input reachable there, which is exactly what the two that DID diverge
383
- * looked like until someone tried a hex id.
384
- *
385
- * SHARING IT IS NOT THE SAME AS IT BEING RIGHT EVERYWHERE. On a model declaring
386
- * `id = attr('string')` a numeric-looking id is filed under the STRING key, so
387
- * this coercion resolves `'9107'` to `9107` and the post-create lookup misses:
388
- * `context.record` is `undefined` for an after-`create` hook. Inherited -- the
389
- * inlined copy computed the same thing -- and NOT fixed here, because picking
390
- * the right coercion needs the model's declared id type, which is the same
391
- * structural information abofs/stonyx-orm#202 is about. Filed as
392
- * abofs/stonyx-orm#209 and pinned by assertion 50, so closing it turns a test
393
- * red rather than passing silently.
394
- *
395
- * `parseInt` and not `Number`, deliberately, and the anchor is NOT `getId`.
396
- * It is `src/transforms.ts:7` -- `number: (value) => parseInt(value as string)`,
397
- * also radix-less -- because that transform is what actually produces the store
398
- * KEY a record is filed under. `getId` merely agrees with it. They differ from
399
- * `Number` on `'1e3'` (1 vs 1000) and `'9105.5'` (9105 vs 9105.5), so switching
400
- * this function to `Number` would make the lookup key disagree with the landing
401
- * key on those shapes.
402
- *
403
- * THE CHANGE THAT WOULD BREAK THIS: adding a radix to `transforms.number`
404
- * (`parseInt(value, 10)`). That is a one-word edit in a file with no connection
405
- * to authorization, it would silently reopen the hex divergence in the other
406
- * direction, and this comment would still read as correct. Assertion 45 pins
407
- * the transform's radix-less shape directly, so that edit turns a test red
408
- * rather than shipping.
409
- *
410
- * The reason `parseInt` is safe here is the `isNaN` gate in front of it:
411
- * `parseInt('9105h')` is `9105`, and truncating a partially-valid id into a
412
- * DIFFERENT VALID key is exactly how a collision lookup gets skipped. The gate
413
- * rejects it as a string instead, so nothing is ever truncated. That gate, not
414
- * the parser, is the load-bearing half -- assertion 43 pins it.
415
- */
416
- function coerceId(id: string): string | number {
417
- if (isNaN(id as unknown as number)) return id;
418
-
419
- return parseInt(id);
420
- }
421
-
422
87
  function getId(params: { id?: string; [key: string]: unknown }): string | number {
423
88
  const id = params.id;
424
89
  if (!id) return '';
90
+ if (isNaN(id as unknown as number)) return id;
425
91
 
426
- return coerceId(id);
427
- }
428
-
429
- /**
430
- * Normalise a caller-supplied BODY id to the key the store will hold it under.
431
- *
432
- * `getId()` above is params-shaped: it takes `{ id?: string }` off the URL,
433
- * where the value is always a string and a falsy one means "no id". A JSON body
434
- * id is neither -- it can arrive as a number, and `0` is a legitimate id that
435
- * `getId()` would flatten to `''`.
436
- *
437
- * WHY THIS EXISTS AT ALL. createHandler used to look the collision up with the
438
- * RAW body value while every other surface normalised through `getId()`. The
439
- * store is a Map keyed by the coerced value, so `store.find(model, '21')` misses
440
- * the entry held under `21` and the duplicate check is skipped by typing the id
441
- * as a string. On `dev` that silently overwrote the colliding record and
442
- * answered 200; combined with the denied-create rollback added for #190 it
443
- * became an unauthenticated DELETE of any id. Normalising here is half of that
444
- * fix -- see the rollback in createHandler for the other half.
445
- *
446
- * It shares `coerceId` with `getId` so the two surfaces cannot drift apart
447
- * again, and differs from `getId` in exactly ONE place, below.
448
- */
449
- function normalizeBodyId(id: string | number): string | number {
450
- // Non-strings pass through untouched: a JSON body id can arrive as a number,
451
- // and `getId`'s falsy-flatten must NOT apply to it -- `0` is a legitimate id
452
- // and `getId` would turn it into `''`. (assertion 30 sweeps id `0`.)
453
- if (typeof id !== 'string') return id;
454
-
455
- // THE ONE DIVERGENCE FROM `getId`, and it mirrors rather than contradicts it:
456
- // `getId` maps a falsy param to `''`, and `''` is the only string a body can
457
- // carry that means "no id" -- `createRecord` treats it as absent and assigns a
458
- // server id. Coercing it instead would make it address a real slot, because
459
- // `parseInt('')` is `NaN` and a record CAN be held under `NaN` (a truthy but
460
- // non-numeric id such as `' '` survives `assignRecordId`'s falsy guard and
461
- // then NaNs in the id transform). So `POST {"id":""}` would answer 409 against
462
- // an unrelated record it never named. Pinned by assertion 44.
463
- //
464
- // Note what is deliberately NOT special-cased here any more: whitespace.
465
- // `id.trim() === ''` used to short-circuit `' '` as well, which made the
466
- // body surface DISAGREE with the URL surface -- `getId({id:' '})` is `NaN`,
467
- // so `' '` addresses the NaN slot on every other route while the collision
468
- // lookup missed it. Same class of bug as the hex divergence above.
469
- if (id === '') return id;
470
-
471
- return coerceId(id);
92
+ return parseInt(id);
472
93
  }
473
94
 
474
95
  function buildResponse(
475
96
  data: unknown,
476
97
  includeParam: string | undefined,
477
98
  recordOrRecords: OrmRecord | OrmRecord[],
478
- options: { links?: { [key: string]: string }; baseUrl?: string; linkage?: LinkageFilter } = {}
99
+ options: { links?: { [key: string]: string }; baseUrl?: string } = {}
479
100
  ): JsonApiResponse {
480
- const { links, baseUrl, linkage } = options;
101
+ const { links, baseUrl } = options;
481
102
  const response: JsonApiResponse = { data };
482
103
 
483
104
  // Add top-level links
@@ -492,53 +113,7 @@ function buildResponse(
492
113
 
493
114
  const includedRecords = collectIncludedRecords(recordOrRecords, includes);
494
115
  if (includedRecords.length > 0) {
495
- // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
496
- // line is one story's and the line above it is another's
497
- // (abofs/stonyx-orm#235 and #233 respectively).
498
- //
499
- // - WHICH RESOURCES REACH THIS ARRAY is decided by
500
- // `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
501
- // #233's, and it is deliberately untouched here: a hidden owner is
502
- // still a member of `included` after this change. Pinned green by
503
- // `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
504
- // - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
505
- // `relationships.*.data` is LINKAGE -- the same question #234 answers
506
- // for the primary document -- and that is what the `linkage` option
507
- // below decides. Before it, `GET /animals/1?include=owner,owner.pets`
508
- // filtered the primary document's `owner.data` to `null` and then
509
- // handed back eight PERMITTED animals in `included` each naming
510
- // `{"type":"owner","id":"angela"}` -- angela's whole `pets` set,
511
- // `[1, 3, 7, 10, 11, 15, 17, 20]`. `included` itself is NINE
512
- // resources there: those eight animals plus the hidden owner, whose
513
- // membership is #233's and not an animal. Neither #233 nor #234
514
- // closes that.
515
- //
516
- // THE FILTER IS THE CALLER'S, PASSED IN, NOT BUILT HERE. Both call sites
517
- // already hold one for the primary document, and sharing it is what keeps
518
- // the per-type verdict cache and the per-(type, id) decision cache alive
519
- // across the primary document AND the sideload -- one verdict resolution
520
- // per type for the whole response, pinned by `[GUARD] #235 C1`. Building a
521
- // fresh filter here would resolve the consumer's `access()` once per
522
- // included record instead.
523
- //
524
- // `linkage` IS OPTIONAL IN THE TYPE AND IS NOT OPTIONAL IN PRACTICE.
525
- // Stating it precisely because the opposite claim stood here in an earlier
526
- // draft of this change: BOTH of this function's callers supply a filter
527
- // (`getCollectionHandler` and `getSingleHandler`, the only two), so the
528
- // `undefined` branch has no live caller in this module today. It is
529
- // optional so that omitting it degrades to the PRE-#234 document rather
530
- // than to a denial -- `Record.toJSON` reads an ABSENT option as "no verdict
531
- // was supplied" and emits linkage in full.
532
- //
533
- // WHAT IT MUST NEVER BE HANDED IS A NON-FUNCTION. `toJSON` does NOT read a
534
- // non-function as absent: `Object.prototype.toString.call(linkage)` must be
535
- // `'[object Function]'`, and anything else -- `null`, an `AsyncFunction`,
536
- // and INCLUDING the primitive `true` -- DENIES every relationship on the
537
- // document and logs once. `toJSON({ linkage: true })` emits `null` linkage.
538
- // So do not "simplify" this to a boolean, and do not make it default to
539
- // `true`: both spellings look like "allow everything" and mean the exact
540
- // opposite (abofs/stonyx-orm#224).
541
- response.included = includedRecords.map(record => record.toJSON?.({ baseUrl, linkage }));
116
+ response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
542
117
  }
543
118
 
544
119
  return response;
@@ -676,46 +251,12 @@ function createFilterPredicate(filters: Filter[]): ((record: { [key: string]: un
676
251
  });
677
252
  }
678
253
 
679
- /**
680
- * A function-style `access` return is a per-record predicate, and it is only
681
- * meaningful if every surface that can hand a record to a caller consults it.
682
- * Before #190 exactly one of seven did.
683
- *
684
- * Enforcement is deliberately post-fetch. `access` returns an opaque JS
685
- * predicate and `store.findAll(model, conditions)` accepts only an equality
686
- * conditions object that the SQL drivers translate to a WHERE clause, so
687
- * query-layer enforcement would require a breaking change to the published
688
- * `access` contract. That belongs in #197, not in a security patch. Six of the
689
- * seven surfaces fetch by primary key anyway, so this costs exactly one row.
690
- */
691
- function isDenied(filter: unknown, record: unknown): boolean {
692
- if (typeof filter !== 'function') return false;
693
-
694
- // A predicate that throws is treated as a denial. Unguarded, a throw escapes
695
- // to express's default handler, which answers 500 (with a stack trace outside
696
- // NODE_ENV=production) while a missing id still answers 404 -- so a
697
- // record-dependent throw re-separates "hidden" from "does not exist" and
698
- // hands back the oracle this whole change exists to close.
699
- try {
700
- return !(filter as (record: unknown) => boolean)(record);
701
- } catch (error) {
702
- // Denied, but not silently. A consumer predicate that throws on every
703
- // record turns the whole collection into a 404 wall, and with no
704
- // diagnostic that is indistinguishable from an empty database. `stonyx/log`
705
- // is the module convention (see setup-rest-server.ts); optional-call
706
- // because a consumer may not have configured the log types.
707
- log.error?.(`[@stonyx/orm] access filter threw for model -- denying. ${error instanceof Error ? error.message : String(error)}`);
708
-
709
- return true;
710
- }
711
- }
712
-
713
254
  export default class OrmRequest extends Request {
714
255
  model: string;
715
- access: AccessFunction;
256
+ access: (request: unknown) => AccessMethod;
716
257
  handlers: { [key: string]: { [key: string]: HandlerFn } };
717
258
 
718
- constructor({ model, access }: { model: string; access: AccessFunction }) {
259
+ constructor({ model, access }: { model: string; access: (request: unknown) => AccessMethod }) {
719
260
  super(...arguments as unknown as unknown[]);
720
261
 
721
262
  this.model = model;
@@ -738,62 +279,29 @@ export default class OrmRequest extends Request {
738
279
  if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
739
280
 
740
281
  const baseUrl = getBaseUrl(request);
741
-
742
- // ONE filter per REQUEST, not one per record: it carries the per-type
743
- // verdict cache and the per-(type, id) decision cache, and both are
744
- // worthless if it is rebuilt inside the map. Measured on this exact
745
- // surface with no `include=`: 48 linkage entries collapse to 7 distinct
746
- // (type, id) pairs.
747
- const linkage = createLinkageFilter(request);
748
- const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl, linkage }));
282
+ const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
749
283
 
750
284
  return buildResponse(data, request.query?.include, recordsToReturn, {
751
285
  links: { self: `${baseUrl}/${pluralizedModel}` },
752
- baseUrl,
753
- // THE SAME filter object the primary documents above were serialized
754
- // with, deliberately: it carries the caches, and rebuilding one here
755
- // would re-resolve every type (abofs/stonyx-orm#235).
756
- linkage
286
+ baseUrl
757
287
  });
758
288
  };
759
289
 
760
- const getSingleHandler: HandlerFn = async (request, { filter }) => {
290
+ const getSingleHandler: HandlerFn = async (request) => {
761
291
  const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
762
292
  if (!record) return 404;
763
- // 404, never 403: the status for "exists but filtered out" must be
764
- // identical to "does not exist", or the fix trades an authorization
765
- // bypass for a narrower existence oracle.
766
- if (isDenied(filter, record)) return 404;
767
293
 
768
294
  const fieldsMap = parseFields(request.query);
769
295
  const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
770
296
 
771
297
  const baseUrl = getBaseUrl(request);
772
- const linkage = createLinkageFilter(request);
773
-
774
- // `buildResponse` IS given the filter now (abofs/stonyx-orm#235), and it
775
- // is the SAME object the primary document is serialized with -- one
776
- // verdict per type for the whole response, sideload included.
777
- //
778
- // The boundary that remains, so the next reader does not have to derive
779
- // it: this closes what a record already in `included` may NAME. WHETHER a
780
- // resource appears in `included` at all is MEMBERSHIP and it is
781
- // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
782
- // Neither question closes the other.
783
- return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
298
+ return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
784
299
  links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
785
- baseUrl,
786
- linkage
300
+ baseUrl
787
301
  });
788
302
  };
789
303
 
790
- const createHandler: HandlerFn = async (request, { filter }) => {
791
- // BOUND, not destructured (abofs/stonyx-orm#235). `HandlerFn` has always
792
- // delivered the request as argument one; this handler simply discarded
793
- // the binding, which is why its response document named ids every read
794
- // surface withholds. `createLinkageFilter` needs the live request and
795
- // there is no signature change involved in giving it one.
796
- const { body, query } = request;
304
+ const createHandler: HandlerFn = async ({ body, query }) => {
797
305
  const { type, id, attributes, relationships: rels } = (body?.data || {}) as {
798
306
  type?: string;
799
307
  id?: string | number;
@@ -806,113 +314,14 @@ export default class OrmRequest extends Request {
806
314
  const fieldsMap = parseFields(query);
807
315
  const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
808
316
 
809
- // GATE 0 -- the POST existence oracle.
810
- //
811
- // The duplicate check runs before the filter and `store.find` sees hidden
812
- // records, so POST leaks existence through its STATUS. A previous revision
813
- // filtered the collision status (403 when the colliding record is denied,
814
- // 409 when it is visible) and that is NOT sufficient, because the status
815
- // of a create is a third outcome. With a payload the caller is permitted
816
- // to create -- the normative case for a per-tenant filter, and the case an
817
- // attacker picks -- all three are distinguishable in ONE request per id:
818
- //
819
- // POST /animals {id:22, owner:'gina'} -> 403 a HIDDEN record has this id
820
- // POST /animals {id:9500, owner:'gina'} -> 200 this id is FREE
821
- // POST /animals {id:8, owner:'gina'} -> 409 a VISIBLE record has this id
822
- //
823
- // Filtering only the collision status narrows that to callers who cannot
824
- // create a record they are allowed to see. It does not close it.
825
- //
826
- // It cannot be closed while a caller both chooses the id and learns
827
- // whether the create succeeded: a successful create must answer
828
- // differently from a refused one. So when a per-record filter is in force
829
- // the caller does not get to choose the id at all. The refusal is
830
- // UNCONDITIONAL and happens BEFORE any store lookup, so no status, and no
831
- // lookup cost, can depend on whether that id exists. 403 -- the same
832
- // status as a denied create -- so the two cannot be separated either.
833
- //
834
- // BOTH HALVES OF THAT ARE PINNED, because both were once asserted here and
835
- // pinned by nothing:
836
- //
837
- // status -- assertion 22 sweeps payload x id x id-type, plus `null`.
838
- // latency -- assertion 41 asserts NO `store.find` is issued on this
839
- // path. Moving the refusal to after a lookup and returning
840
- // the same 403 left the suite green while re-opening a
841
- // hit-versus-miss timing difference on every id-bearing POST,
842
- // which is what would turn #197 from a ~0.06ms post-fetch
843
- // residual into a live timing oracle on create.
844
- //
845
- // AND THE GUARANTEE IS ONLY AS WIDE AS THE CHANNELS IT COVERS. It reads on
846
- // the `id` member of the resource object, so it holds only while that is
847
- // the ONLY way a caller id can reach `createRecord`. It was not: the
848
- // relationships loop below re-admitted one under `key === "id"` and the
849
- // gate never fired. Both strips -- `attributes.id` and `relationships.id`
850
- // -- are therefore part of THIS gate, not tidiness, and assertion 39 pins
851
- // them. Adding a third channel without a strip re-opens the oracle.
852
- //
853
- // Scoped to function-style `access` because that is exactly the population
854
- // the oracle exists for: with no per-record filter there are no hidden
855
- // records, and 409 discloses nothing GET /:id does not already.
856
- //
857
- // RESIDUALS, stated rather than implied.
858
- //
859
- // - a caller can still learn that a collection HAS a per-record filter
860
- // (403 rather than 409/200 for an id-bearing POST). That discloses a
861
- // configuration fact, not a record.
862
- // - this gate is about ids arriving on THIS model's create route. It
863
- // says nothing about a write to ANOTHER collection: a `POST /owners`
864
- // carrying `relationships: {pets: {data: {id: 21}}}` -- or
865
- // `attributes: {pets: [21, 22]}`, which never enters the
866
- // relationships loop at all -- re-parents hidden animal 21 onto an
867
- // owner the caller may write, which changes the very field the
868
- // animals predicate reads and DE-HIDES it. Blocking that needs animal
869
- // 21 checked against the ANIMAL model's predicate while servicing an
870
- // OWNERS route, i.e. cross-model access resolution: abofs/stonyx-orm
871
- // #207, blocked on #202 (`access` receives the model structurally)
872
- // and #196 (setup-rest-server discards the model->predicate map at
873
- // boot). NOT closed here, and no comment in this file may say it is.
874
- //
875
- // See README `### Known limitations`.
876
- if (id !== undefined) {
877
- if (typeof filter === 'function') return 403; // Forbidden
878
-
879
- // `normalizeBodyId`, not the raw value: a string-typed id misses the
880
- // store's numeric key, which skipped this check entirely.
881
- const existing = await store.find(model, normalizeBodyId(id));
882
- if (existing) return 409; // Conflict
883
- }
317
+ // Check for duplicate ID
318
+ if (id !== undefined && await store.find(model, id)) return 409; // Conflict
884
319
 
885
320
  const { id: _ignoredId, ...sanitizedAttributes } = attributes || {};
886
321
 
887
- // Extract relationship IDs from JSON:API relationships object.
888
- //
889
- // `key` comes VERBATIM from the request body, so `id` is stripped here for
890
- // exactly the same reason it is stripped from `attributes` on the line
891
- // above -- and it must be, or GATE 0 is walked around by moving one field:
892
- //
893
- // POST /animals {"id":21, ...} -> 403 GATE 0 fires
894
- // POST /animals {"relationships":{"id":{"data":{"id":21}}},
895
- // "attributes":{"owner":"gina"}} -> 200 BYPASS
896
- //
897
- // Top-level `id` stayed `undefined`, so GATE 0 never fired and the
898
- // collision lookup never ran; `createRecord` took its last-entry-wins
899
- // branch, overwrote hidden record 21 in place and reset its `owner` to a
900
- // value the caller chose -- de-hiding it permanently. That is #190 itself,
901
- // on the create surface. Pinned by assertion 39.
902
- //
903
- // The `id` member of the resource object is now the ONLY channel a caller
904
- // id can arrive on FOR THIS MODEL'S OWN CREATE ROUTE, which is what makes
905
- // GATE 0's guarantee checkable rather than merely asserted. It is not a
906
- // statement about the record's reachability in general -- a relationship
907
- // write on another collection reaches it without ever touching this
908
- // handler (abofs/stonyx-orm#207). INHERITED from `dev`, which carries this
909
- // loop verbatim; the general form -- the loop accepts any key, not just
910
- // `id`, so a body key that is not a declared relationship is still
911
- // mass-assigned -- is abofs/stonyx-orm#204.
322
+ // Extract relationship IDs from JSON:API relationships object
912
323
  if (rels) {
913
324
  for (const [key, value] of Object.entries(rels)) {
914
- if (key === 'id') continue;
915
-
916
325
  const relData = value?.data;
917
326
  if (relData && relData.id !== undefined) {
918
327
  (sanitizedAttributes as { [key: string]: unknown })[key] = relData.id;
@@ -921,169 +330,16 @@ export default class OrmRequest extends Request {
921
330
  }
922
331
 
923
332
  const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
924
-
925
- // Slot count BEFORE the write. `createRecord` writes to the store before
926
- // the predicate can run, and the rollback below must be able to prove the
927
- // slot it removes is one THIS REQUEST created. Identity alone cannot
928
- // prove it: when `assignRecordId` lands on an occupied id, `createRecord`
929
- // mutates the existing OrmRecord IN PLACE, so `store.get(...) === record`
930
- // is true for a record the request did not create. The map's size is the
931
- // only O(1) signal that distinguishes an insert from an overwrite.
932
- const slotsBefore = store.get(model)?.size ?? 0;
933
-
934
- // THE ONE `createRecord` FAILURE THIS ROUTE ANSWERS RATHER THAN
935
- // PROPAGATES, and it is narrow on purpose.
936
- //
937
- // `assignRecordId` throws when it cannot derive a free store key for a
938
- // server-assigned id. Unguarded that rejection is auto-forwarded -- there
939
- // is no catch here, none in @stonyx/rest-server's dispatcher
940
- // (dist/request.js:41-70), and express 5 hands it to its default error
941
- // handler, which serialises the STACK, with absolute install paths and the
942
- // internal module graph, to an unauthenticated caller outside
943
- // NODE_ENV=production. That is the hazard :553-558 already names in this
944
- // file, and every sibling refusal in this handler returns an integer
945
- // status instead. So this one returns 409, matching the client-duplicate
946
- // refusal at :713: the caller asked for a record and the collection has no
947
- // id to give it.
948
- //
949
- // MATCHED ON THE SHARED PREFIX, not on a literal, and NOT by catching
950
- // everything: `createRecord` also throws for "ORM is not ready", a
951
- // read-only view and an unregistered model store, and turning any of those
952
- // into a 409 would report a configuration fault as a conflict. Anything
953
- // else is re-thrown unchanged.
954
- let created;
955
-
956
- try {
957
- created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
958
- } catch (error) {
959
- if (!(error instanceof Error) || !error.message.startsWith(NO_FREE_ID_ERROR)) throw error;
960
-
961
- // Not silently. A collection that can no longer assign an id is a
962
- // configuration fault (a non-injective id transform), and a bare 409
963
- // with no diagnostic is indistinguishable from an ordinary duplicate.
964
- log.error?.(`[@stonyx/orm] ${error.message}`);
965
-
966
- return 409; // Conflict
967
- }
968
-
333
+ const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
969
334
  const record = isOrmRecord(created) ? created : null;
970
335
  if (!record) return 500;
971
336
 
972
- const createdNewSlot = (store.get(model)?.size ?? 0) > slotsBefore;
973
-
974
- // 403 here, NOT 404. The oracle argument does not apply to create: there
975
- // is no pre-existing record whose existence could leak, the caller
976
- // supplied the attributes, and 404 on a mounted collection route is
977
- // indistinguishable from "model not mounted" -- a genuinely different
978
- // failure a developer needs to diagnose.
979
- //
980
- // The rollback is not optional. createRecord writes to the store BEFORE
981
- // the predicate can run, so returning 403 alone would leave the record
982
- // behind: a worse bug than the bypass being fixed.
983
- if (isDenied(filter, record)) {
984
- // ROLL BACK BY IDENTITY, NEVER BY ID. `store.remove(model, record.id)`
985
- // on its own is a write primitive keyed by a value the caller may have
986
- // supplied: with the raw-id collision bypass above, a denied
987
- // `POST {"id":"21"}` answered 403 and DELETED hidden record 21 -- an
988
- // unauthenticated deletion primitive across the whole id space, created
989
- // by adding a rollback to a lookup that could be skipped.
990
- //
991
- // Both conditions are required and neither implies the other:
992
- // createdNewSlot -- the store grew, so this request inserted rather
993
- // than overwrote. SURVIVOR AS OF #203, AND THAT IS
994
- // WHAT THIS NOTE IS FOR. It used to be killable:
995
- // `assignRecordId` returned last-INSERTED + 1, so a
996
- // server-assigned id could land on an occupied slot,
997
- // `createRecord` updated in place, and removing this
998
- // half turned access-filter-enforcement-test.ts
999
- // assertion 31 red. #203 closed that: the
1000
- // server-assigned path now walks past occupied keys,
1001
- // so no create reaching here can overwrite. Measured
1002
- // -- delete `createdNewSlot &&` below: `dev` gives
1003
- // 55 pass / 1 fail with assertion 31 RED, this tree
1004
- // gives 56 pass / 0 fail, GREEN.
1005
- // KEPT ANYWAY, AND NOT FOR THE OLD REASON. Without
1006
- // it a denied create becomes `store.remove` on a key
1007
- // the caller may have influenced, which :815-820
1008
- // records as having been an unauthenticated deletion
1009
- // primitive across the whole id space. BECOMES
1010
- // KILLABLE AGAIN the moment any caller-supplied id
1011
- // can reach `createRecord` from this handler --
1012
- // which is exactly what has-many.ts:65 and
1013
- // belongs-to.ts:45 already do for ANOTHER model's
1014
- // store (abofs/stonyx-orm#207), and what a third
1015
- // un-stripped id channel would do for this one
1016
- // (#204). Do not delete it on the strength of #203
1017
- // being closed; that is the reasoning :862-867 warns
1018
- // about, one level up.
1019
- // identity -- the slot still holds the object we just created,
1020
- // so nothing between createRecord and here replaced
1021
- // it. Deleting this half SURVIVES the suite, and it
1022
- // is kept anyway. WHY IT IS REDUNDANT: there is no
1023
- // `await` anywhere between `slotsBefore` and
1024
- // `store.remove` -- the whole window is synchronous,
1025
- // so it is atomic under Node's event loop; before-
1026
- // `create` hooks run BEFORE the handler
1027
- // (`_withHooks` runs its hook loop ahead of
1028
- // `await handler(...)`), and a consumer predicate
1029
- // inside `isDenied` runs AFTER `createdNewSlot` is
1030
- // computed and cannot flip it. That is a property of
1031
- // THIS function, not of GATE 0 -- an earlier note
1032
- // credited GATE 0, which was both wrong (a caller id
1033
- // reached createRecord through the relationships
1034
- // loop, #204) and the wrong kind of reason: a guard
1035
- // justified on code sixty lines upstream gets
1036
- // silently re-armed when that code moves.
1037
- // SO IT BECOMES REACHABLE IF AN `await` IS
1038
- // INTRODUCED HERE, which is the change a future
1039
- // editor would actually make. Stated here rather
1040
- // than by reference: `docs/` is not in `files`, so
1041
- // a pointer into it resolves to nothing for anyone
1042
- // who installed this package. README carries the
1043
- // consumer-facing half.
1044
- if (createdNewSlot && store.get(model, record.id as string | number) === record) {
1045
- store.remove(model, record.id as string | number, { _skipAutoPersist: true });
1046
- }
1047
-
1048
- return 403;
1049
- }
1050
-
1051
- // The filter is built HERE, per invocation, and never hoisted into the
1052
- // OrmRequest constructor where the other per-mount values live: a verdict
1053
- // cached across requests answers a second caller with the first caller's
1054
- // authorization (src/access-verdict.ts says so at the constructor an
1055
- // implementer would reach for).
1056
- //
1057
- // AND IT IS BUILT AFTER `createRecord`, AFTER THE ROLLBACK WINDOW AND
1058
- // AFTER `isDenied`, so the record is in its final form at the call. The
1059
- // filter is lazy per type and per (type, id), so it cannot observe a
1060
- // pre-write state even if it were built earlier.
1061
- //
1062
- // `fields` is passed here and NOT in `updateHandler`: the two handlers
1063
- // are asymmetric on purpose (`updateHandler` has no `fieldsMap` in
1064
- // scope), and a single copy-pasted wiring would drop it from one of them.
1065
- return { data: record.toJSON?.({ fields: modelFields, linkage: createLinkageFilter(request) }) };
337
+ return { data: record.toJSON?.({ fields: modelFields }) };
1066
338
  };
1067
339
 
1068
- const updateHandler: HandlerFn = async (request, { filter }) => {
1069
- // Bound rather than destructured, for the reason given in
1070
- // `createHandler` above (abofs/stonyx-orm#235). `PATCH /animals/1`
1071
- // returned 200 naming angela seconds after `GET /animals/1` returned
1072
- // `owner.data: null` for the same record -- one HTTP verb apart.
1073
- const { body, params } = request;
340
+ const updateHandler: HandlerFn = async ({ body, params }) => {
1074
341
  const found = await store.find(model, getId(params));
1075
342
  if (!found || !isOrmRecord(found)) return 404;
1076
- // Checked BEFORE any attribute is applied. 404 rather than 403 for the
1077
- // same reason as GET /:id -- 403 would disclose both that the record
1078
- // exists and that this caller specifically is excluded.
1079
- //
1080
- // NOT redundant behind GATE 1, and not defence in depth either: GATE 1's
1081
- // verdict is computed BEFORE the before-hook loop runs, and a before-hook
1082
- // is a published extension point that can change the answer -- by
1083
- // mutating the record, or against a predicate that closes over
1084
- // per-request state. This is the only re-evaluation after that window.
1085
- // Pinned by assertion 32; deleting it turns a 404 into an applied update.
1086
- if (isDenied(filter, found)) return 404;
1087
343
  const record = found;
1088
344
  const { attributes, relationships: rels } = (body?.data || {}) as {
1089
345
  attributes?: { [key: string]: unknown };
@@ -1106,19 +362,6 @@ export default class OrmRequest extends Request {
1106
362
  if (rels) {
1107
363
  const relUpdates: { [key: string]: unknown } = {};
1108
364
  for (const [key, value] of Object.entries(rels)) {
1109
- // The same missing key filter as createHandler's, and as the
1110
- // attribute loop directly above -- which already had it, while this
1111
- // loop did not. A PATCH carrying
1112
- // `relationships:{"id":{"data":{"id":9101}}}` reached `updateRecord`
1113
- // and RE-KEYED the record: the object held under store key 9102 then
1114
- // reported id 9101, so a visible record claimed a hidden record's
1115
- // identity on every surface that reads `record.id` rather than the map
1116
- // key. Gated by GATE 1 on the addressed record, so it is store
1117
- // corruption rather than a filter bypass -- but it is the same one-line
1118
- // omission two handlers apart. Pinned by assertion 40; INHERITED from
1119
- // `dev`; abofs/stonyx-orm#204.
1120
- if (key === 'id') continue;
1121
-
1122
365
  const relData = value?.data;
1123
366
  if (relData && relData.id !== undefined) {
1124
367
  relUpdates[key] = relData.id;
@@ -1129,41 +372,11 @@ export default class OrmRequest extends Request {
1129
372
  }
1130
373
  }
1131
374
 
1132
- // No `fields` and no `baseUrl`, both unchanged: `updateHandler` has no
1133
- // `fieldsMap` in scope, and adding `baseUrl` would put `links` on a
1134
- // document that has never carried them -- an unrelated behaviour change.
1135
- // #224 AC6's "emits `data: []` WITH links" is a statement about the READ
1136
- // surfaces; on these two handlers a filtered relationship and a
1137
- // genuinely-empty one are both a bare `{ data }`, which is what makes
1138
- // them indistinguishable here too.
1139
- return { data: record.toJSON?.({ linkage: createLinkageFilter(request) }) };
375
+ return { data: record.toJSON?.() };
1140
376
  };
1141
377
 
1142
- const deleteHandler: HandlerFn = async ({ params }, { filter }) => {
1143
- // Coerced ONCE. `getId(params)` was evaluated twice here -- once to find
1144
- // the record and once to remove it -- and a coercion evaluated repeatedly
1145
- // is a coercion that can be edited in one place and not the other, which
1146
- // is the defect `coerceId` exists to prevent.
1147
- const recordId = getId(params);
1148
- const record = await store.find(model, recordId) as OrmRecord | undefined;
1149
-
1150
- // BEHAVIOUR CHANGE (#190): a DELETE of a record that never existed
1151
- // returned 204 before this change. It now returns 404, matching the
1152
- // denied case below. This is deliberate and load-bearing -- if a denied
1153
- // delete returned 404 while a missing one returned 204, the pair would be
1154
- // a perfect existence oracle and the whole fix would be worthless.
1155
- // Returning 204 for a denied delete was rejected instead: it falsely
1156
- // reports success for a request that changed nothing.
1157
- if (!record) return 404;
1158
- // Re-evaluated after the before-hook loop, exactly as in updateHandler --
1159
- // GATE 1 decided before the hooks ran. Pinned by assertion 33; deleting it
1160
- // turns a 404 into a destroyed record.
1161
- if (isDenied(filter, record)) return 404;
1162
-
1163
- // Removed by the id of the record actually fetched, not by re-deriving it
1164
- // from the params a second time: the record the filter tested and the
1165
- // record removed are then provably the same one.
1166
- store.remove(model, record.id as string | number, { _skipAutoPersist: true });
378
+ const deleteHandler: HandlerFn = ({ params }) => {
379
+ store.remove(model, getId(params), { _skipAutoPersist: true });
1167
380
  return 204;
1168
381
  };
1169
382
 
@@ -1192,65 +405,9 @@ export default class OrmRequest extends Request {
1192
405
  }
1193
406
  }
1194
407
 
1195
- // Wraps a handler with before/after hook execution.
1196
- //
1197
- // ===========================================================================
1198
- // TWO AUTHORIZATION GATES, AND EVERY EXECUTOR SITS BEHIND ONE OF THEM (#190)
1199
- //
1200
- // The defect this function was fixed for is NOT "a delete persists past a
1201
- // 404". It is that _withHooks has SEVERAL executors downstream of the
1202
- // handler, and originally the handler's response gated none of them. Three
1203
- // exist today:
1204
- //
1205
- // 1. sqlDb.persist -- issues real SQL against the backing store
1206
- // 2. the after-hook pipeline -- the PUBLISHED consumer extension point;
1207
- // a cascade delete, a webhook, a search-index
1208
- // purge. `context.recordId` and
1209
- // `context.oldState` are populated for it.
1210
- // 3. Orm.db.save() -- a full serialize-and-write of the store
1211
- //
1212
- // Gating them one at a time is how this keeps regressing, so the rule is:
1213
- // compute denial ONCE at each point where it becomes knowable, and keep every
1214
- // executor downstream of a gate. If you add a fourth executor to this
1215
- // function, it goes below GATE 2 or it is a security bug.
1216
- //
1217
- // GATE 1 (pre-handler) is required because before-hooks and `context.oldState`
1218
- // run/are built BEFORE the handler can consult the filter. Without it a denied
1219
- // DELETE still handed the hidden record's full contents to consumer code.
1220
- // GATE 2 (post-handler) covers everything the handler's status can reach.
1221
- // ===========================================================================
408
+ // Wraps a handler with before/after hook execution
1222
409
  private _withHooks(operation: string, handler: HandlerFn): HandlerFn {
1223
410
  return async (request: OrmRequest$, state: { [key: string]: unknown }) => {
1224
- // `|| {}` so this function behaves like the relationship routes below,
1225
- // which declare `state` with a `= {}` default. It is unkillable through
1226
- // the rest-server dispatcher, which always passes `getState(req)`; it is
1227
- // listed as such in the guards-redundant-by-construction table rather
1228
- // than left silently unkillable, and it defends the WHOLE function (the
1229
- // context, the snapshot and the handler call all read `callState`) rather
1230
- // than one destructure that the next line would throw past anyway.
1231
- const callState = (state || {}) as { [key: string]: unknown };
1232
-
1233
- // ---------------------------------------------------------------------
1234
- // THE AUTHORIZATION SNAPSHOT. Read ONCE, here, before any consumer code
1235
- // can run.
1236
- //
1237
- // `callState` is the object `auth()` planted the filter in, and it is
1238
- // also handed to every before-hook as `context.state` -- a published,
1239
- // WRITABLE extension point. So `state.filter` is an INPUT to the
1240
- // authorization decision, not only an output channel, and re-reading it
1241
- // after the hook loop lets a consumer hook disarm the filter:
1242
- //
1243
- // beforeHook('get', 'animal', ctx => { delete ctx.state.filter })
1244
- // -> GET /animals/21 turned 404 into 200
1245
- // -> GET /animals turned 20 records into 22
1246
- //
1247
- // GATE 1 already used this snapshot, so writes held; the READ handlers
1248
- // re-destructured `filter` from the live bag and did not. Everything
1249
- // downstream now reads `filter` from here, and the handler is handed
1250
- // `handlerState` below -- never `callState`.
1251
- // ---------------------------------------------------------------------
1252
- const { filter } = callState as { filter?: unknown };
1253
-
1254
411
  // Build context object for hooks
1255
412
  const context: HookContext = {
1256
413
  model: this.model,
@@ -1259,37 +416,12 @@ export default class OrmRequest extends Request {
1259
416
  params: request.params,
1260
417
  body: request.body,
1261
418
  query: request.query,
1262
- // Deliberately the LIVE object: `redirect` and `pipe` are read back off
1263
- // it by @stonyx/rest-server after the handler returns, so hooks must be
1264
- // able to write to it. What must not happen is the authorization
1265
- // decision reading it back, which is what the snapshot above prevents.
1266
- state: callState,
419
+ state,
1267
420
  };
1268
421
 
1269
422
  // Capture old state for operations that modify data
1270
423
  if (operation === 'update' || operation === 'delete') {
1271
424
  const existingRecord = await store.find(this.model, getId(request.params)) as OrmRecord | undefined;
1272
-
1273
- // GATE 1 -- pre-handler. This record fetch already happened for
1274
- // oldState, so the check is free.
1275
- //
1276
- // Returning here rather than letting updateHandler/deleteHandler
1277
- // produce the same 404 is the point: everything between here and there
1278
- // is an executor the caller is not authorized to reach.
1279
- // - context.oldState is a deep copy of the HIDDEN RECORD'S CONTENTS.
1280
- // Building it and handing it to a before-hook discloses exactly what
1281
- // the filter exists to hide.
1282
- // - context.recordId is populated for delete BEFORE the handler runs,
1283
- // which is the same shape as the sqlDb landmine one layer up:
1284
- // `afterHook('delete', ctx => cascadeDelete(ctx.recordId))` destroys
1285
- // children behind a correct 404.
1286
- // - a before-hook may return a value and short-circuit, which would
1287
- // otherwise return a response without the filter ever executing.
1288
- //
1289
- // 404, not 403, for the same reason as getSingleHandler: the status for
1290
- // "exists but filtered out" must equal "does not exist".
1291
- if (existingRecord && isDenied(filter, existingRecord)) return 404;
1292
-
1293
425
  if (existingRecord) {
1294
426
  // Deep copy the record's data to preserve old state
1295
427
  context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
@@ -1309,52 +441,16 @@ export default class OrmRequest extends Request {
1309
441
  }
1310
442
 
1311
443
  // Execute main handler
1312
- // The handler receives the SNAPSHOT, never the live bag. `filter` is
1313
- // assigned LAST so it wins over anything a before-hook wrote to
1314
- // `callState.filter` -- including a `delete`, which the spread would
1315
- // otherwise carry through as an absent key. Every other key a hook adds
1316
- // is still visible to the handler; only the authorization input is
1317
- // pinned.
1318
- const handlerState = { ...callState, filter };
1319
- const response = await handler(request, handlerState);
444
+ const response = await handler(request, state);
1320
445
 
1321
446
  // Set context.record for update BEFORE persist so SQL drivers can read it
1322
447
  if (operation === 'update' && (response as JsonApiResponse)?.data) {
1323
448
  context.record = store.get(this.model, getId(request.params));
1324
449
  }
1325
450
 
1326
- // GATE 2 -- post-handler. A denied or failed handler returns a bare status
1327
- // integer, and no executor below may run for one.
1328
- //
1329
- // `>= 400` deliberately covers every failure status, not just the
1330
- // authorization ones: a 400 (POST with no `type`) and a 409 (duplicate id)
1331
- // are equally requests in which nothing happened, and a persist or a
1332
- // cascade hook for one of them is just as wrong.
1333
- // `Number.isInteger` is a TYPE guard, not a behaviour guard, and it is
1334
- // unkillable TODAY: the only non-integer a handler in this file can
1335
- // return is a `{ data, links }` object, and `{} >= 400` is `false` by JS
1336
- // coercion, so dropping it changes no reachable outcome. It is kept
1337
- // because `>=` coerces rather than rejects, and the shapes it coerces
1338
- // are not obvious -- `[500] >= 400` is TRUE, so a handler that one day
1339
- // returned an array would have every response read as a denial. Listed
1340
- // as an equivalent mutant rather than left to read as coverage; it
1341
- // becomes killable the moment a handler returns anything array-like or
1342
- // numeric-string-like.
1343
- const denied = Number.isInteger(response) && (response as number) >= 400;
1344
-
1345
- // EXECUTOR 1 -- SQL persistence, for all write operations.
1346
- //
1347
- // `response` is passed to sqlDb.persist below, but it is dropped at the
1348
- // driver boundary: _persistDelete(modelName, context) never receives it
1349
- // and guards only on context.recordId -- which _withHooks set above,
1350
- // BEFORE the handler ran. Without this gate a correct 404 still issues
1351
- // DELETE FROM ... WHERE id = ? on every SQL backend.
1352
- //
1353
- // No file-backed test can observe that, because Orm.instance.sqlDb is
1354
- // null in file/directory mode. See the stubbed-sqlDb assertions in
1355
- // test/unit/access-filter-enforcement-test.ts.
451
+ // Persist to SQL database for all write operations (create/update/delete)
1356
452
  const sqlDb = Orm.instance.sqlDb;
1357
- if (sqlDb && WRITE_OPERATIONS.has(operation) && !denied) {
453
+ if (sqlDb && WRITE_OPERATIONS.has(operation)) {
1358
454
  await sqlDb.persist(operation, this.model, context, response);
1359
455
  }
1360
456
 
@@ -1368,45 +464,20 @@ export default class OrmRequest extends Request {
1368
464
  } else if (operation === 'create' && (response as JsonApiResponse)?.data && ((response as { data: { id?: unknown } }).data.id)) {
1369
465
  // For create, get the record from store using the ID from the response
1370
466
  const responseData = (response as { data: { id: string | number } }).data;
1371
- // `normalizeBodyId`, not a copy of its body. This line WAS
1372
- // `isNaN(id) ? id : parseInt(id)` -- `coerceId` inlined verbatim, a
1373
- // third coercion feeding a store lookup, sitting under a docblock that
1374
- // said neither surface had a copy. Equivalent on every input that can
1375
- // reach this truthy-guarded branch (`21`->`21`, `'21'`->`21`,
1376
- // `'angela'`->`'angela'`; `''` and `0` cannot reach it), so this is a
1377
- // de-duplication rather than a behaviour change -- and that is the
1378
- // point: the two that disagreed were equivalent on every input anyone
1379
- // checked, too.
1380
- context.record = store.get(this.model, normalizeBodyId(responseData.id) as string | number);
467
+ const recordId = isNaN(responseData.id as unknown as number) ? responseData.id : parseInt(responseData.id as string);
468
+ context.record = store.get(this.model, recordId);
1381
469
  } else if (operation === 'delete') {
1382
470
  // For delete, the record may no longer exist, but we have oldState
1383
471
  context.recordId = getId(request.params);
1384
472
  }
1385
473
 
1386
- // EXECUTOR 2 -- the after-hook pipeline. This is the published consumer
1387
- // extension point (`afterHook` is exported from @stonyx/orm and from
1388
- // ./hooks), so it is the executor with the widest possible blast radius:
1389
- // a cascade delete, a webhook, a token revocation, a search-index purge.
1390
- //
1391
- // BEHAVIOUR CHANGE (#190): after-hooks no longer fire for a request that
1392
- // failed. Previously `afterHook('delete', ...)` ran with a populated
1393
- // context.recordId on a 404, so a consumer cascade destroyed children for
1394
- // a request that deleted nothing. Firing a hook named "after<operation>"
1395
- // for an operation that did not occur is a booby trap, and the denied case
1396
- // is unreachable-before-#190 while the missing case is inherited debt --
1397
- // both are closed by the same gate. `context.response` therefore only ever
1398
- // carries a success status into a hook.
1399
- if (!denied) {
1400
- for (const hook of getAfterHooks(operation, this.model)) {
1401
- await hook(context);
1402
- }
474
+ // Run after hooks sequentially
475
+ for (const hook of getAfterHooks(operation, this.model)) {
476
+ await hook(context);
1403
477
  }
1404
478
 
1405
- // EXECUTOR 3 -- file/directory autosave. Ungated this let an
1406
- // unauthenticated caller force a full serialize-and-write of the entire
1407
- // store on every DELETE of any id, with no record touched: amplification
1408
- // rather than corruption, but the same root cause and the same fix.
1409
- if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation) && !denied) {
479
+ // Auto-save DB after write operations when configured
480
+ if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation)) {
1410
481
  await (Orm.db as { save(): Promise<void> }).save();
1411
482
  }
1412
483
 
@@ -1426,118 +497,21 @@ export default class OrmRequest extends Request {
1426
497
  const dasherizedName = camelCaseToKebabCase(relationshipName);
1427
498
 
1428
499
  // Related resource route: GET /:id/{relationship}
1429
- //
1430
- // These generated routes are not wrapped by _withHooks, which is why they
1431
- // were the least obvious two of the seven unguarded surfaces in #190.
1432
- // They are still dispatched by @stonyx/rest-server as
1433
- // `handler(req, getState(req))`, so `state` -- and therefore the filter
1434
- // planted by auth() -- has always been available here; it was simply
1435
- // never declared or read.
1436
- routes[`/:id/${dasherizedName}`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
500
+ routes[`/:id/${dasherizedName}`] = async (request: OrmRequest$) => {
1437
501
  const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
1438
502
  if (!record) return 404;
1439
- // Filtering the PARENT: a caller who may not see the record may not see
1440
- // what it is related to either.
1441
- if (isDenied(filter, record)) return 404;
1442
503
 
1443
504
  const relatedData = record.__relationships[relationshipName];
1444
505
  const baseUrl = getBaseUrl(request);
1445
506
 
1446
- // ONE FILTER, TWO JOBS, AND abofs/stonyx-orm#232 IS THE SECOND ONE.
1447
- //
1448
- // As LINKAGE (#234) it decides which ids the emitted documents may NAME
1449
- // in their own `relationships.*.data`. As MEMBERSHIP (this issue) it
1450
- // decides whether the related record is served here AT ALL -- the
1451
- // related resource is PRIMARY data on this route, so there is no
1452
- // linkage-consistency question to answer separately.
1453
- //
1454
- // Until #232 this route filtered only the PARENT, so a record its own
1455
- // model's predicate hides was served in full from another model's
1456
- // route, at ZERO query parameters. Measured on dev @ 8dda5d6:
1457
- //
1458
- // GET /owners/angela -> 404
1459
- // GET /animals/1/owner -> 200, owner:angela, full attributes
1460
- // GET /traits/2/tag -> 200, a model NO access class
1461
- // claims, on a collection that has
1462
- // no mounted route at all
1463
- //
1464
- // ARGUMENT ONE IS THE LIVE REQUEST, NOT A DERIVED ONE. A fabricated
1465
- // request addressing the RELATED resource was the original design and
1466
- // it is dropped: #241 removed the shipped fixture's read of argument
1467
- // one, so a fabricated value changes nothing it could observe.
1468
- // `createLinkageFilter` is also a published public export
1469
- // (src/index.ts) whose resolution granularity is per TYPE; supplying a
1470
- // per-RECORD request would mean widening it, which takes a consumer
1471
- // `access()` from ~2 calls to ~7 on a plain `GET /animals`. That is a
1472
- // separate, consumer-visible story.
1473
- //
1474
- // GUARDED BY OWN-PROPERTY IDENTITY, NOT BY THE #234 AC13 PIN. That pin
1475
- // (test/unit/linkage-verdict-test.ts, `strictEqual(seen[0].request,
1476
- // READ_REQUEST)`) calls `createLinkageFilter` DIRECTLY, so it pins the
1477
- // function's pass-through and constrains no call site -- an earlier
1478
- // revision of this comment cited it for this decision and was wrong.
1479
- // `Object.create(request)` here measured 1015 / 0 with nothing red.
1480
- // test/integration/orm-test.ts, `#232 AC9`, now asserts that the object
1481
- // the predicate is handed OWNS `params` (`Object.hasOwn`) and has
1482
- // nothing request-shaped behind it on the prototype chain. A derived
1483
- // request inherits `params` -- so it satisfies every value assertion
1484
- // there -- and reds on those two. Measured: with the derived request in
1485
- // place, 1014 / 1, and that one is this guard.
1486
- //
1487
- // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
1488
- // `recordId` is `null` here and the request names a record of a
1489
- // DIFFERENT model, so a consumer predicate can express a model-level or
1490
- // a request-level deny for a related resource, but NOT a per-record
1491
- // one. README.md and docs/usage-patterns.md say so; a ledger assertion
1492
- // in test/unit/relationship-route-access-test.ts keeps them saying it.
1493
- const linkage = createLinkageFilter(request);
1494
-
1495
- // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED. `isLinkable` is
1496
- // keyed on the model name; without one there is no predicate to ask,
1497
- // and an unidentifiable input must never be the permissive path.
1498
- const isLinkable = (r: OrmRecord) => {
1499
- const type = (r as { __model?: { __name?: string } }).__model?.__name;
1500
-
1501
- return typeof type === 'string' && type !== '' && linkage(type, r);
1502
- };
1503
-
1504
507
  let data: unknown;
1505
508
  if (info.isArray) {
1506
- // hasMany - return array, MINUS the members this caller may not see.
1507
- // Dropped, never errored: the result is byte-identical to a genuinely
1508
- // empty relationship, so this route is not an existence oracle.
509
+ // hasMany - return array
1509
510
  const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
1510
- data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
511
+ data = related.map(r => r.toJSON?.({ baseUrl }));
1511
512
  } else {
1512
- // belongsTo - return single or null. A DENIED target is `data: null`,
1513
- // BYTE-IDENTICAL to a relationship that is genuinely empty, for the
1514
- // same reason the hasMany branch above drops rather than errors: this
1515
- // route must not be an existence oracle for the RELATED record.
1516
- //
1517
- // THE OTHER SPELLING WAS 404 AND IT WAS MEASURED AS A DISCLOSURE.
1518
- // Unauthenticated, zero query parameters, one request each, on `tag`
1519
- // -- the model with no route mounted at all, which is exactly what
1520
- // #240 AC5 exists to protect:
1521
- //
1522
- // GET /traits/1/tag [ABSENT] -> 200 application/json len 68
1523
- // GET /traits/2/tag [DENIED] -> 404 text/plain len 9
1524
- //
1525
- // and `GET /traits/1` and `GET /traits/2` both report
1526
- // `relationships.tag = {"data":null}` byte-identical modulo the id,
1527
- // because #234 closed THAT oracle deliberately. A 404 here would let
1528
- // a caller ask which of those two nulls was a denial. Under
1529
- // `data: null` the pair closes completely: 200/200, same
1530
- // content-type, same content-length, bodies identical modulo the
1531
- // parent id the caller put in the URL. It opens nothing -- `links`
1532
- // are entirely parent-derived, there is no `meta` and no counts.
1533
- //
1534
- // This is also what README.md's module-wide rule already demanded:
1535
- // every status on a record route must be identical for filtered-out
1536
- // and does-not-exist. The route now CONFORMS to that rule rather than
1537
- // carving an exception out of it.
1538
- if (!isOrmRecord(relatedData)) data = null;
1539
- else if (!isLinkable(relatedData)) data = null;
1540
- else data = relatedData.toJSON?.({ baseUrl, linkage });
513
+ // belongsTo - return single or null
514
+ data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
1541
515
  }
1542
516
 
1543
517
  return {
@@ -1547,100 +521,23 @@ export default class OrmRequest extends Request {
1547
521
  };
1548
522
 
1549
523
  // Relationship linkage route: GET /:id/relationships/{relationship}
1550
- //
1551
- // NO `linkage` FILTER FROM abofs/stonyx-orm#235, AND THAT IS A SCOPE
1552
- // BOUNDARY RATHER THAN AN OVERSIGHT -- abofs/stonyx-orm#232 OWNS THIS
1553
- // ROUTE, and PR #247 is IN FLIGHT against it in this same sprint. If you
1554
- // are reading this after #247 landed, the filtering below is #232's and
1555
- // this note records why it was never #235's to add.
1556
- //
1557
- // The three sites #235 does own -- `buildResponse`'s `included`, and the
1558
- // two write handlers, `POST /:models` and `PATCH /:models/:id` -- all
1559
- // reach the filter through `record.toJSON()`, which is where the
1560
- // `linkage` OPTION is applied.
1561
- //
1562
- // The related-resource branch above ALSO passes a `linkage` filter, and
1563
- // it is NOT one of those three: it is abofs/stonyx-orm#234's code and
1564
- // predates this change. `git diff 8dda5d6..HEAD -- src/orm-request.ts`
1565
- // leaves that branch byte-unchanged.
1566
- //
1567
- // This branch builds its `{ type, id }` objects BY
1568
- // HAND and never calls `toJSON` at all, so the `linkage` option cannot
1569
- // reach it -- whatever this route filters, it has to filter itself, which
1570
- // is precisely why doing so is a separate change with a separate owner.
1571
- //
1572
- // It is also a DIFFERENT QUESTION. Everywhere #235 touches, linkage is
1573
- // metadata ABOUT a document. Here the linkage IS the primary data, so
1574
- // dropping an entry is a MEMBERSHIP decision about what this route
1575
- // serves -- the same class as abofs/stonyx-orm#233 and #196, not the
1576
- // class #234/#235 close. That is why it is absent from #224 §2a's
1577
- // seven-site inventory.
1578
- //
1579
- // MEASURED, so the next person does not re-derive it. Against this
1580
- // branch's baseline of 1011/0, wiring `createLinkageFilter` into the
1581
- // belongsTo branch below takes the suite to 1009/2, reddening
1582
- // `[GUARD] #235 X2` and the
1583
- // `GET /animals/:id/relationships/owner returns relationship linkage`
1584
- // test -- the latter is #232's own reproduction, not a regression.
1585
- //
1586
- // THE BASELINE IS QUOTED WITH THE RESULT BECAUSE AN EARLIER REVISION OF
1587
- // THIS COMMENT SAID 993/2 AND SHIPPED IT. This file lands in consumers'
1588
- // `node_modules`, so a wrong number here is a wrong number in the
1589
- // published package. 993+2 = 995 is the DEV baseline, carried over from
1590
- // a branch on which `[GUARD] #235 X2` does not exist. A pass/fail pair
1591
- // with no baseline beside it cannot be checked by reading, which is how
1592
- // it survived three artifacts and a review; the qualitative claim was
1593
- // right the whole time and only the count was wrong.
1594
- //
1595
- // `[GUARD] #235 X2` in test/integration/orm-test.ts pins the OWNERSHIP
1596
- // BOUNDARY here rather than this route's current answer, so that it
1597
- // survives #247 landing. Read its comment before changing it.
1598
- routes[`/:id/relationships/${dasherizedName}`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
524
+ routes[`/:id/relationships/${dasherizedName}`] = async (request: OrmRequest$) => {
1599
525
  const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
1600
526
  if (!record) return 404;
1601
- if (isDenied(filter, record)) return 404;
1602
527
 
1603
528
  const relatedData = record.__relationships[relationshipName];
1604
529
  const baseUrl = getBaseUrl(request);
1605
530
 
1606
- // THE ONE READ SURFACE THAT DOES NOT GO THROUGH `toJSON()`. It builds
1607
- // `{ type, id }` BY HAND, which is why #234's linkage filter never
1608
- // reached it and why this half belongs to abofs/stonyx-orm#232 rather
1609
- // than to #234: on this route the linkage IS the primary data of an
1610
- // opt-in request, so filtering it changes the route's MEMBERSHIP
1611
- // semantics, not the ids named inside somebody else's document.
1612
- //
1613
- // DELIBERATELY NOT STATED AS A COUNT. README.md's Consumer Contracts
1614
- // section enumerates the surfaces on which the framework resolves a
1615
- // verdict and hands it to `toJSON()`, and that enumeration GROWS --
1616
- // abofs/stonyx-orm#235 adds the two write handlers and the `included`
1617
- // records. This route is not on that list under any count, because it
1618
- // never calls `toJSON()`: whatever it filters, it filters here. A
1619
- // number written into this comment would be false the next time that
1620
- // list changes, and the README already carries the enumeration.
1621
- //
1622
- // Same filter, same argument-one decision, same residual as
1623
- // `/:id/{relationship}` above -- read the block there.
1624
- const linkage = createLinkageFilter(request);
1625
- const isLinkable = (r: OrmRecord) => {
1626
- const type = (r as { __model?: { __name?: string } }).__model?.__name;
1627
-
1628
- return typeof type === 'string' && type !== '' && linkage(type, r);
1629
- };
1630
-
1631
531
  let data: unknown;
1632
532
  if (info.isArray) {
1633
533
  // hasMany - return array of linkage objects
1634
534
  const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
1635
535
  data = related
1636
536
  .filter((r): r is OrmRecord & { __model: { __name: string } } => Boolean(r.__model))
1637
- .filter(isLinkable)
1638
537
  .map(r => ({ type: r.__model.__name, id: r.id }));
1639
538
  } else {
1640
- // belongsTo - return single linkage or null. A DENIED target is
1641
- // `data: null`, indistinguishable from a genuinely empty one -- see
1642
- // the measured oracle in the `/:id/{relationship}` block above.
1643
- if (isOrmRecord(relatedData) && relatedData.__model && isLinkable(relatedData)) {
539
+ // belongsTo - return single linkage or null
540
+ if (isOrmRecord(relatedData) && relatedData.__model) {
1644
541
  data = { type: relatedData.__model.__name, id: relatedData.id };
1645
542
  } else {
1646
543
  data = null;
@@ -1657,140 +554,32 @@ export default class OrmRequest extends Request {
1657
554
  };
1658
555
  }
1659
556
 
1660
- // Catch-alls for invalid relationship names. Every valid relationship was
1661
- // registered above, so reaching either of these means the relationship does
1662
- // not exist and the answer is 404 regardless of the record.
1663
- //
1664
- // These deliberately carry NO access check and no store lookup. An earlier
1665
- // revision of #190 added `if (isDenied(filter, record)) return 404` here for
1666
- // symmetry with the seven real surfaces, but both branches returned 404, so
1667
- // the guard was unobservable by construction -- a mutation deleting it
1668
- // survived the entire suite because no test that could distinguish it can
1669
- // exist. Unkillable code in an authorization diff reads as coverage and is
1670
- // not, so it is gone; skipping the lookup also removes the timing difference
1671
- // between an existing and a missing parent.
1672
- //
1673
- // IF THIS ROUTE EVER RETURNS ANYTHING OTHER THAN A CONSTANT 404, it becomes
1674
- // the eighth surface and must filter the parent first, exactly like
1675
- // `/:id/{relationship}` above.
1676
- routes[`/:id/:relationship`] = async () => 404;
1677
- routes[`/:id/relationships/:relationship`] = async () => 404;
1678
-
1679
- return routes;
1680
- }
557
+ // Catch-all for invalid relationship names on related resource route
558
+ routes[`/:id/:relationship`] = async (request: OrmRequest$) => {
559
+ const record = await store.find(model, getId(request.params));
560
+ if (!record) return 404;
1681
561
 
1682
- auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
1683
- // A consumer `access()` that throws is a DENIAL, matching `isDenied` one
1684
- // layer down. Unguarded it propagates to express's default handler, which
1685
- // answers 500 -- and the documented sample itself can throw
1686
- // (`request.originalUrl.split(...)` when originalUrl is absent), so the
1687
- // failure mode is reachable by following the docs.
1688
- // -------------------------------------------------------------------------
1689
- // #202 -- hand the consumer the STRUCTURAL facts, not just the transport.
1690
- //
1691
- // Both members are already in hand here. `model` is `this.model`, the name
1692
- // setup-rest-server mounted this route for; `operation` is the SAME
1693
- // `methodAccessMap` lookup the permission-array branch at the bottom of
1694
- // this method performs, so the predicate form and the array form cannot
1695
- // answer differently about the same request.
1696
- //
1697
- // NEITHER IS DERIVED FROM THE REQUEST TARGET, and that is the whole point.
1698
- // Deriving `model` here from `request.baseUrl` (or from the mounted route
1699
- // name, or from `getPluralName(this.model)`) would move all five fail-open
1700
- // variants listed in this file's header OUT of the consumer and INTO the
1701
- // framework, where every consumer inherits them at once. `this.model` is
1702
- // assigned once at mount time and no request can influence it.
1703
- //
1704
- // `operation` is left UNDEFINED for a method with no entry in
1705
- // `methodAccessMap`, rather than defaulted. Express delivers HEAD to the
1706
- // GET handler, so an unmapped method really does reach this line; a
1707
- // `?? 'read'` here would hand the consumer a fabricated authorisation fact
1708
- // and turn an unclassified request into an authorised one. Undefined is
1709
- // the honest answer.
1710
- //
1711
- // `record` is deliberately absent -- see `AccessContext` in
1712
- // src/types/orm-types.ts. Nothing is fetched at this point and adding a
1713
- // lookup here would put a store read in the middle of an authorization
1714
- // path. The function return shape below IS the per-record hook.
1715
- //
1716
- // -------------------------------------------------------------------------
1717
- // #236 -- `recordId`, the DECODED route-parameter id, for the same reason.
1718
- //
1719
- // WHICH RECORD is the third structural fact the framework already holds and
1720
- // the consumer was left to re-derive, and re-deriving it failed OPEN. The
1721
- // documented sample compared `request.path` -- the RAW, undecoded pathname
1722
- // -- against a literal `/archived`, while the router DECODES `:id`. So
1723
- // `GET /owners/%61rchived` walked past the deny and was dispatched as the
1724
- // record `archived`: 200 with the record in full, and DELETE answered 204
1725
- // with the record destroyed, unauthenticated. Four spellings measured, all
1726
- // four through; 255 non-canonical spellings of that 8-character id decode
1727
- // to the same key, so this was never a deny-list of one.
1728
- //
1729
- // TWO CONSUMER-SIDE NORMALISATIONS WERE MEASURED WRONG IN OPPOSITE
1730
- // DIRECTIONS, which is the argument for doing it once, here.
1731
- // `.toLowerCase()` case-folds a route-parameter VALUE on the axis that
1732
- // governs literal SEGMENTS: with a distinct owner seeded at `ARCHIVED`,
1733
- // `GET /owners/ARCHIVED` was a false DENY on the wrong record and
1734
- // `GET /owners/%41RCHIVED` a false ALLOW on that same one.
1735
- // `decodeURIComponent(request.path)` decodes THEN splits while the router
1736
- // splits THEN decodes, so it over-denied `/owners/archived%2fx` -- 403 for
1737
- // a genuinely distinct record. Failing closed there was luck, not design.
1738
- //
1739
- // `getId(request.params)` AND NOT `request.params.id`, for exactly the
1740
- // reason `operation` is a `methodAccessMap` lookup: it is the SAME single
1741
- // coercion the store lookup one layer down performs, so the predicate and
1742
- // the dispatch cannot disagree about which record a request addresses.
1743
- // The raw string would reintroduce that divergence on hex-shaped ids --
1744
- // `GET /animals/0x2391` looks up record `9105`.
1745
- //
1746
- // NOTHING HERE PARSES THE REQUEST TARGET EITHER. `request.params` is what
1747
- // the router matched, so a mount prefix, an absolute-form target, a query
1748
- // string or a case-varied mount cannot move this value -- the same
1749
- // guarantee `model` carries, by the same means.
1750
- //
1751
- // `null` and not `undefined` on a collection route, so the KEY IS ALWAYS
1752
- // PRESENT -- the rule `operation`'s own docblock already establishes. A
1753
- // context reaching a predicate WITHOUT the key therefore did not come from
1754
- // here; it was hand-assembled by a caller resolving the predicate through
1755
- // `Orm.instance.getAccess()`, and that absence stays deniable only because
1756
- // `auth()` never produces it.
1757
- // -------------------------------------------------------------------------
1758
- const context: AccessContext = {
1759
- model: this.model,
1760
- operation: methodAccessMap[request.method],
1761
- recordId: request.params && 'id' in request.params ? getId(request.params) : null,
562
+ // If we reach here, relationship doesn't exist (valid ones were registered above)
563
+ return 404;
1762
564
  };
1763
565
 
1764
- let access: AccessMethod;
1765
- try {
1766
- access = this.access(request, context);
1767
- } catch (error) {
1768
- // Same reasoning as `isDenied`: fail closed, but say so. An `access()`
1769
- // that throws denies EVERY request to the collection, and a silent 403
1770
- // wall is the hardest possible thing to diagnose from the outside.
1771
- log.error?.(`[@stonyx/orm] access() threw for model "${this.model}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
1772
-
1773
- return 403; // Forbidden
1774
- }
566
+ // Catch-all for invalid relationship names on relationship linkage route
567
+ routes[`/:id/relationships/:relationship`] = async (request: OrmRequest$) => {
568
+ const record = await store.find(model, getId(request.params));
569
+ if (!record) return 404;
1775
570
 
1776
- // THE READING OF THE RETURN SHAPE LIVES IN ONE PLACE (#234).
1777
- //
1778
- // It used to be inline here, and it was the only copy, which was fine while
1779
- // `auth()` was the only thing that had to ask. It is not any more: the
1780
- // linkage path has to ask model X's predicate about model X's records while
1781
- // servicing a request routed to model Y, and a second inline copy of these
1782
- // six branches would be a second authorization vocabulary -- one that can
1783
- // drift, and that reviewers would have to notice had drifted. The branch
1784
- // order in `interpretAccess` is this block, moved, not rewritten.
1785
- const verdict = interpretAccess(access, methodAccessMap[request.method]);
571
+ return 404;
572
+ };
1786
573
 
1787
- if (!verdict.granted) return 403;
574
+ return routes;
575
+ }
1788
576
 
1789
- // The function return shape is the per-record hook, and `state` is the
1790
- // whole transport for it: @stonyx/rest-server memoises one state object per
1791
- // request and hands the same one to `auth()` and to the handler.
1792
- if (verdict.filter) state.filter = verdict.filter;
577
+ auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
578
+ const access = this.access(request);
1793
579
 
580
+ if (!access) return 403;
581
+ if (Array.isArray(access) && !access.includes(methodAccessMap[request.method])) return 403;
582
+ if (typeof access === 'function') state.filter = access;
1794
583
  return undefined;
1795
584
  }
1796
585
  }