@stonyx/orm 0.3.2-alpha.70 → 0.3.2-alpha.71

package/README.md

@@ -325,19 +325,6 @@ Access classes define models and provide custom filtering/authorization logic.
 > deny — which folds case but does not decode, so `GET /owners/%61rchived` steps
 > past it ([#228](https://github.com/abofs/stonyx-orm/issues/228)).
 >
-> **Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
-> [#237](https://github.com/abofs/stonyx-orm/issues/237), and left standing rather
-> than rewritten.** Both claims above are now false: `#228` is **closed**, and the
-> one string comparison variant 3 lived in is gone — the sample below compares the
-> **decoded `recordId`** the access context supplies, so there is no comparison
-> left to step around. The paragraph about `request.path` further down is
-> superseded the same way. Nothing here is deleted because the same "variant 3
-> survives" wording sits at four sites (this file twice, `src/orm-request.ts`, and
-> the test fixture) and retiring one of four leaves the shipped copies
-> contradicting each other; retiring all four **with the measurement that retires
-> them** is [#238](https://github.com/abofs/stonyx-orm/issues/238), which also owns
-> this blockquote and the reference section below.
->
 > That is still a stopgap. **The real fix is
 > [#202](https://github.com/abofs/stonyx-orm/issues/202)** — `access()` should
 > receive the model, the operation and the record, so there is nothing to
@@ -350,14 +337,6 @@ Access classes define models and provide custom filtering/authorization logic.
 > context alone** and a context-only rewrite would silently turn it into an
 > allow.
 >
-> **Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
-> [#237](https://github.com/abofs/stonyx-orm/issues/237)** — see the dated note
-> above. No read of argument **one** survives in the sample below: the context
-> carries `recordId`, the decoded route-parameter id, so the `/archived` deny **is**
-> expressible from the context alone. It still must not be dropped — expressible is
-> not optional. Retirement of this wording:
-> [#238](https://github.com/abofs/stonyx-orm/issues/238).
->
 > The same warning is repeated at the top of `src/orm-request.ts`, which ships;
 > the longer write-up in `docs/usage-patterns.md` does **not** ship, so this
 > README and that source header are the two copies a consumer sees.
@@ -371,73 +350,66 @@ Access classes define models and provide custom filtering/authorization logic.
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
-  access(request, { model, operation, recordId }) {
+  access(request, { model, operation }) {
     // `model` is the model this route was mounted for. It is assigned once, at
     // mount time, and no request can influence it — not a mount prefix, not a
     // query string, not a case-varied path, not an absolute-form request
-    // target. `recordId` is the record this route was ADDRESSED TO, decoded by
-    // the router and coerced to the key the store lookup uses. Nothing below
-    // parses anything, and since abofs/stonyx-orm#236 nothing below reads
-    // argument one AT ALL. Variants 1, 2, 4 and 5 were already unconstructible;
-    // the sub-path STRING COMPARISON that variant 3 lived in is gone too,
-    // replaced by a comparison against the decoded id. Retiring the "variant 3
-    // survives" wording at the four sites that still carry it — with the
-    // measurement that retires it, rather than by deletion — is
-    // abofs/stonyx-orm#238.
+    // target. Nothing below parses anything, so variants 1, 2, 4 and 5 are not
+    // constructible against this predicate any more — they are history, not
+    // rules to follow. VARIANT 3 IS THE EXCEPTION AND THE CLAIM IS NARROWER
+    // THAN IT WAS: a matcher stricter than the router can still be stepped
+    // around, because the sub-path rule below is still a string comparison.
+    // Case is handled; percent-encoding is not — abofs/stonyx-orm#228.
     //
     // `operation` is destructured to name the whole contract at the point of
-    // use. This sample's rules are per-model and per-record rather than
+    // use. This sample's rules are per-model and per-sub-path rather than
     // per-verb, so it does not branch on it; the permission array at the bottom
     // is where the verb is answered.
 
-    // FAIL CLOSED ON AN UNIDENTIFIABLE MODEL. `model` is absent for any caller
-    // that resolved this predicate without supplying the context, and a request
-    // this function cannot identify DENIES rather than falling through to the
-    // CRUD grant at the bottom. An unidentifiable input must never be the
-    // permissive path.
+    // FAIL CLOSED ON ARGUMENT TWO. `model` is absent for any caller that
+    // resolved this predicate without supplying the context, and a request this
+    // function cannot identify DENIES rather than falling through to the CRUD
+    // grant at the bottom. An unidentifiable input must never be the permissive
+    // path. Argument ONE is guarded at its own read, below — this guard does
+    // not cover it.
     if (typeof model !== 'string' || model === '') return false;
 
     if (model === 'owner') {
-      // FAIL CLOSED ON AN ABSENT `recordId` TOO, AND `undefined` IS THE ONLY
-      // SPELLING OF ABSENT. `auth()` ALWAYS sets the key — `null` on a
-      // collection route, which is addressed to no record — so `undefined`
-      // means the context did not come from `auth()`: it was hand-assembled by
-      // a caller resolving this predicate through the documented
-      // `Orm.instance.getAccess()` path. Letting that through would fall
-      // straight to the per-record filter below, which is a DENY becoming an
-      // ALLOW. This is the same rule the old guard on `request.path` enforced,
-      // moved to the argument this predicate now actually reads.
-      if (recordId === undefined) return false;
-
-      // THE `/archived` DENY, EXPRESSED AGAINST THE DECODED ID. It used to be
-      // `request.path.toLowerCase()` compared against `'/archived'`, and that
-      // was wrong in both directions at once.
-      //
-      // TOO PERMISSIVE: express sets `request.path` from the RAW pathname while
-      // the router DECODES `:id`, so `GET /owners/%61rchived` reached the
-      // comparison as `/%61rchived`, walked past the deny and was dispatched as
-      // the record `archived` — 200 with the record in full, and DELETE
-      // answered 204 with the record DESTROYED, unauthenticated. 255
-      // non-canonical spellings of that 8-character id decode to the same key,
-      // so no deny-list of spellings was ever going to close it.
+      // The context names WHICH MODEL and WHICH VERB — not which route. Six
+      // distinct owner surfaces produce one identical context, so a rule that
+      // depends on the SUB-PATH still needs argument one. `request.path` is
+      // mount-relative and query-free, and it is the one read of the raw
+      // request the README sanctions. false → 403 for the whole request.
       //
-      // TOO STRICT: a record id is a VALUE, not a literal route segment, and
-      // express's `case sensitive routing` governs literal segments only. With
-      // a distinct owner seeded at `ARCHIVED`, the `.toLowerCase()` 403'd
-      // `GET /owners/ARCHIVED` — the wrong record — while still admitting
-      // `GET /owners/%41RCHIVED`, the same record encoded.
+      // THIS DENY CANNOT BE EXPRESSED FROM THE CONTEXT ALONE. Migrating it away
+      // does not remove a rule, it turns a deny into an ALLOW, silently.
       //
-      // SO DO NOT NORMALISE `recordId`. It is already decoded, exactly ONCE,
-      // which is what a route parameter means: `/owners/%2561rchived` is the
-      // legitimate id `%61rchived`, and decoding until stable would deny it. Do
-      // not case-fold it. Do not rebuild it from `request.path` — decoding the
-      // whole path decodes THEN splits while the router splits THEN decodes,
-      // which over-denies the distinct record at `/owners/archived%2fx`.
+      // FAIL CLOSED ON ARGUMENT ONE TOO. The guard above covers the context;
+      // this one covers the request, and since #202 they are two different
+      // objects. A caller that resolves this predicate through the documented
+      // `Orm.instance.getAccess()` path and hand-assembles a request can supply
+      // a perfectly valid context with no usable `path` — and
+      // `String(request.path ?? '')` is then `''`, which matches no sub-path
+      // rule and falls straight through to the per-record filter below. That is
+      // a DENY becoming an ALLOW. An input this function cannot identify DENIES,
+      // whichever ARGUMENT it arrived on — which is also why the `?? ''` this
+      // file's header condemns does not appear below.
+      if (typeof request?.path !== 'string' || request.path === '') return false;
+
+      // Lower-cased because the router matched case-insensitively, so a
+      // case-sensitive rule here would be stricter than the router and could be
+      // stepped around.
       //
-      // THE DENY IS NOW EXPRESSIBLE FROM THE CONTEXT ALONE, which is exactly
-      // what `recordId` bought — and it still must not be dropped. Deleting it
-      // does not remove a rule loudly, it turns a deny into an ALLOW, silently.
-      if (recordId === 'archived') return false;
+      // CASE-FOLDING ALONE IS NOT A SUFFICIENT NORMALISATION, and this line is
+      // not a recipe for one. Express sets `request.path` from the RAW pathname
+      // while the router DECODES `:id`, so `GET /owners/%61rchived` reaches this
+      // comparison as `/%61rchived`, walks past the deny, and is dispatched as
+      // the record `archived` — abofs/stonyx-orm#228. A matcher must normalise
+      // the way the router that dispatched the request does. Record ids are
+      // case-sensitive and must be compared at their real case.
+      const path = request.path.toLowerCase();
+
+      if (path === '/archived' || path.startsWith('/archived/')) return false;
 
       // Returning a function plugs it in as a per-record filter, and it is
       // enforced on every surface addressed to one of these records:
@@ -520,16 +492,6 @@ access class shipped with this repo has such a rule: its `/archived` deny
 **cannot be expressed from the context alone**, and a predicate migrated to
 context-only would silently drop it — a deny becoming an allow.
 
-**Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
-[#237](https://github.com/abofs/stonyx-orm/issues/237).** The context also carries
-`recordId` — the record this route was addressed to, already decoded — so the
-`/archived` deny **is** expressible from the context alone, and the shipped sample
-no longer reads `request.path`. The full contract is `AccessContext.recordId` in
-`src/types/orm-types.ts`, which ships. This section — the signature, the key table
-and this paragraph — is corrected by
-[#238](https://github.com/abofs/stonyx-orm/issues/238); the pointer is here because
-what it currently says is an instruction, and the instruction is wrong.
-
 Note also that the related-resource and `?include=` surfaces serve *another
 model's* records under `model: 'owner'`, and the context gives a predicate no
 signal that it is authorizing a related-resource route. That is
@@ -825,17 +787,6 @@ these values should be matched on:
 | `GET http://anything.example/owners/angela` | `http://anything.example/angela` | `http://anything.example/owners/angela` | `/owners` | `/angela` |
 | `GET /api/animals/22` (`ORM_REST_ROUTE=/api`) | `/22` | `/api/animals/22` | `/api/animals` | `/22` |
 
-**Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
-[#237](https://github.com/abofs/stonyx-orm/issues/237) — "Variant 3 survives" above,
-and the two paragraphs below, are no longer true.** The access context now carries
-`recordId`, the **decoded** route-parameter id, and the sample compares against it:
-the one string comparison variant 3 lived in is gone, `#228` is **closed**, and no
-read of argument one survives in the sample. The wording is left standing rather
-than deleted because it appears at four sites (this file twice,
-`src/orm-request.ts`, and the test fixture) and retiring one of four leaves the
-shipped copies contradicting each other; retiring all four **with the measurement
-that retires them** is [#238](https://github.com/abofs/stonyx-orm/issues/238).
-
 **One read of argument one survives, and it must: `request.path`.** It is
 mount-relative and query-free, and it is for rules that distinguish **sub-paths**
 beneath the mount — as the `/archived` deny in the sample above does. The context
@@ -855,20 +806,6 @@ comparison as `/%61rchived`, walks past the deny, and is dispatched as the recor
 `.toLowerCase()` there as a complete normalisation recipe.** Record ids are
 case-sensitive and must be compared at their real case.
 
-**Do not follow the two paragraphs above — superseded 2026-09-01 by
-[#236](https://github.com/abofs/stonyx-orm/issues/236) /
-[#237](https://github.com/abofs/stonyx-orm/issues/237).** They are *instructions*,
-not merely stale observations, which is why this note is louder than a date. The
-sample no longer reads `request.path` and no longer calls `.toLowerCase()` on
-anything it compares: `.toLowerCase()` was measured wrong in **both directions at
-once** — with a distinct owner seeded at `ARCHIVED`, `GET /owners/ARCHIVED` was a
-false **deny** on the wrong record and `GET /owners/%41RCHIVED` a false **allow**
-on that same record. Compare `recordId` **as it arrives**: do not case-fold it, do
-not decode it, do not derive it from `request.path`. The contract is
-`AccessContext.recordId` in `src/types/orm-types.ts`, which ships and says "Do NOT
-case-fold it". Retirement of this wording, with its measurement:
-[#238](https://github.com/abofs/stonyx-orm/issues/238).
-
 **Fail closed on anything you cannot identify — on *either* argument.**
 `String(request.originalUrl ?? '')` was once added here to stop a `TypeError`,
 and it traded fail-closed for fail-**open**: an empty string matched no
@@ -927,7 +864,97 @@ per-record filter. An input you cannot identify must **deny**.
   related record without resolving that model's own access class, so a filter on
   `/owners` does not hide an owner reached through `/animals`. Tracked as
   [#196](https://github.com/abofs/stonyx-orm/issues/196), which covers
-  `include=`, related-resource routes and relationship-linkage routes.
+  `include=`, related-resource routes and relationship-linkage routes. This is
+  **membership** — whether the related resource is served at all — and it is a
+  different question from which ids a document may *name*, immediately below.
+- **Relationship linkage is filtered on the four request-bound read surfaces,
+  and only there.** A document's `relationships.*.data` used to publish the id
+  of every related record unconditionally, so a record hidden on every one of
+  its own surfaces was still named inside another model's document — with no
+  `include=`, no relationship route and no query string
+  ([#234](https://github.com/abofs/stonyx-orm/issues/234)). The ORM now resolves
+  the **related** model's own access class on `GET /:models`, `GET /:models/:id`
+  and both `GET /:models/:id/{relationship}` shapes, and asks it
+  `{ model: <related>, operation: 'read' }`. An unresolvable class
+  (`getAccess()` → `undefined`) and a predicate that throws both **deny**. A
+  filtered-out relationship is **indistinguishable from a genuinely empty one** —
+  an emptied `hasMany` is `data: []` and an emptied `belongsTo` is `data: null`,
+  both **keeping their `links`**, which are built from the serialized record's
+  own id and never from the related one. Nothing errors and no status changes,
+  because throwing here would be an existence oracle *and* would throw out of
+  the enclosing `JSON.stringify`.
+
+  **That resolves the right class; it does not guarantee a model-correct
+  answer, and the failure direction is not the safe one.** Only a predicate that
+  *reads* `context.model` can answer about the model it was asked about — see
+  [Passing the context makes a model-correct answer *possible*](#passing-the-context-makes-a-model-correct-answer-possible)
+  above. A **single-argument predicate remains the default in every consumer
+  tree**, it identifies its collection from the request, and asked about
+  `owner` on a request dispatched to `/animals` it answers about **animals**.
+  Measured against this repo's own fixture with an arity-1 predicate registered
+  for `owner`: `GET /owners` correctly returns `["gina","michael","bob"]` while
+  `GET /animals/1` returns `owner.data {"type":"owner","id":"angela"}` — the
+  #234 defect, on the #234 surface, after the #234 fix. This is not a
+  regression (the id was published unconditionally before), it cannot be fixed
+  from this side, and the signal that surfaces such a predicate is
+  [#221](https://github.com/abofs/stonyx-orm/issues/221) /
+  [#213](https://github.com/abofs/stonyx-orm/issues/213). **Migrate your
+  predicates to read the context before relying on this filter.** A migrated,
+  context-reading predicate degrades the other way — it can over-deny a
+  *permitted* related record, which is recorded in the release notes as a
+  breaking change.
+
+  **Not yet covered, and each one still publishes ids the surfaces above
+  withhold:**
+
+  - **`included`** — [#235](https://github.com/abofs/stonyx-orm/issues/235). A
+    permitted record sideloaded by `?include=` emits its **own**
+    `relationships.*.data` unfiltered, so `GET /animals/1?include=owner,owner.pets`
+    returns `owner.data: null` on the primary document and then names angela in
+    `included`, along with eight permitted animals that each name
+    `{"type":"owner","id":"angela"}`. Separately,
+    [#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
+    resource appears in `included` **at all** — that is membership, a different
+    question, and following it will not lead you to this residual.
+  - **The `POST`/`PATCH` response documents** —
+    [#235](https://github.com/abofs/stonyx-orm/issues/235). `createHandler` and
+    `updateHandler` destructure the request rather than binding it, so wiring
+    them needs a signature change rather than an argument. Until then **one HTTP
+    verb defeats the filter on the same record**: measured, `GET /animals/1`
+    returns `owner.data: null` and `PATCH /animals/1` returns **200 naming
+    angela**, seconds apart, with no query string and no relationship route. Any
+    caller who can read a record can also write it and be handed the id the read
+    withheld.
+  - **`GET /:models/:id/relationships/{relationship}`**, whose *primary data* is
+    linkage, so filtering it is a **membership** decision —
+    [#232](https://github.com/abofs/stonyx-orm/issues/232), the filed child of
+    [#196](https://github.com/abofs/stonyx-orm/issues/196).
+- **A bare `toJSON()` still emits unfiltered linkage, and that is deliberate.**
+  `Record.toJSON()` **applies** a verdict; it never **resolves** one. It has no
+  request, and the documented `access()` contract permits a predicate to read
+  one — the sample in this README does, for its sub-path rule — so a filter
+  resolved inside `toJSON()` denies *permitted* records rather than hidden ones
+  (measured: 967 → 964, all three failures over-denials). `toJSON` is also the
+  `JSON.stringify` hook, so `JSON.stringify(record)`, `res.json(record)` and
+  `console.log(JSON.stringify(record))` reach it with a **string** in the
+  options slot and have no syntactic place to pass a verdict. The no-argument
+  call therefore returns the pre-#234 document unchanged. Fail-closed by default
+  is not available either: `Orm.instance.accessFunctions` is `{}` in any process
+  that never ran `setup-rest-server` — a CLI, an SQL-only process, a test — so
+  it would empty every relationship on every document in processes with no REST
+  surface to protect. Closing the residual means moving JSON:API serialization
+  **off** the `toJSON` name, tracked as
+  [#230](https://github.com/abofs/stonyx-orm/issues/230). If you hand a `Record`
+  to an untrusted consumer, serialize it through the REST layer, or resolve a
+  verdict with the **exported** `createLinkageFilter(request)` and pass it as
+  the `linkage` option — do not write your own reading of `access()`. This is a
+  consumer obligation with no signal when it lapses; it is stated once, in full,
+  under [Consumer Contracts](#consumer-contracts) below.
+- **`format()` and `serialize()` are deliberately not filtered, and must stay
+  that way.** `format()` is the **persistence** path — its output is what
+  `Orm.db.save()` writes to disk — so applying an access filter there would
+  write a truncated database. That is **data loss**, not disclosure prevention.
+  Neither method appears anywhere in the REST response path.
 - **A before-hook that returns a value short-circuits the request.** On write
   operations addressed to a record the filter is consulted first, so a hook
   cannot answer for a record the caller may not see. On reads it is not, so a
@@ -986,6 +1013,80 @@ per-record filter. An input you cannot identify must **deny**.
   back, and without the guard a denied `403` would delete a record the request
   did not create.
 
+### Consumer Contracts
+
+Obligations this package **cannot enforce**, where nothing fails, warns or
+changes shape when a consumer omits them. One place, findable, per
+`quality.md` rule 2 — if you are relying on `@stonyx/orm` for access control,
+read all of these.
+
+#### `Record.toJSON()` does not filter relationship linkage unless you pass a verdict
+
+**The framework owns this on four surfaces. You own it everywhere else.**
+
+`GET /:models`, `GET /:models/:id` and both `GET /:models/:id/{relationship}`
+shapes resolve a linkage verdict and pass it to `toJSON()` for you. Any other
+path to a document — `JSON.stringify(record)`, `res.json(record)`,
+`console.log(record)`, a custom route, a queue payload, a websocket frame —
+calls `toJSON()` with no verdict, and **the no-verdict document names every
+related id, including records hidden on every one of their own surfaces**
+([#234](https://github.com/abofs/stonyx-orm/issues/234)). That default is
+deliberate and cannot be inverted; the reasons are in
+[Known limitations](#known-limitations) above.
+
+**There is no signal when you omit it.** `linkage` is optional, absent is the
+default, the default is the unfiltered document, and a filtered relationship is
+byte-identical to a genuinely empty one — so nothing on the wire distinguishes
+"filtered" from "forgotten".
+
+Do this:
+
+```js
+import { createLinkageFilter } from '@stonyx/orm';
+
+// `request` is the live request the caller was authorised against. The verdict
+// is REQUEST-SCOPED: build one per request and never cache it across requests,
+// or a second caller is answered with the first caller's authorization.
+const linkage = createLinkageFilter(request);
+
+res.json({ data: record.toJSON({ baseUrl, linkage }) });
+```
+
+Not this:
+
+```js
+// A second, unreviewed reading of access(). It will drift from the one in
+// src/access-verdict.ts, and it will drift in consumer code where no reviewer
+// of this repository will ever see it.
+const linkage = (type, r) => Orm.instance.getAccess(type)?.(request)?.(r) ?? true;
+```
+
+**`linkage` is validated, and an unusable value DENIES.** `undefined` means "no
+verdict supplied" and emits today's document. Any other non-function — `null`,
+`0`, `false`, `''`, `true`, a string, an object — drops **all** linkage on that
+document and logs. This matters because `null` is the natural return of a
+resolver that could not resolve a session: it used to be read as "absent" and
+emit the full document silently.
+
+#### A predicate that ignores `context.model` makes cross-model resolution GRANT
+
+The linkage filter above asks the **related** model's access class the
+model-correct question, but only a predicate that *reads*
+[`context.model`](#the-access-context-second-argument) can give a model-correct
+answer. A single-argument predicate identifies its collection from the request
+and therefore answers about the collection the request was *addressed to* —
+which is the direction that **grants**. Measured, and worked through in
+[Known limitations](#known-limitations). There is no boot-time warning yet
+([#221](https://github.com/abofs/stonyx-orm/issues/221)). **Migrate your
+predicates to the two-argument contract.**
+
+#### `format()` and `serialize()` are never filtered, by design
+
+They are the persistence path. Do not hand their output to an untrusted
+consumer, and do not add a filter to them — `Orm.db.save()` writes `format()`
+output to disk, so filtering there is data loss rather than disclosure
+prevention.
+
 ### Breaking changes
 
 These land in the next published build. There is no changelog or release-notes channel yet
@@ -1195,6 +1296,13 @@ GET /animals/1
 #### Limitations
 
 - Only available on GET endpoints (not POST/PATCH)
+- **`included` records are not access-filtered, on either question.** Whether a
+  resource appears in `included` at all is
+  [#233](https://github.com/abofs/stonyx-orm/issues/233); a record that *is*
+  permitted still emits its **own** `relationships.*.data` unfiltered, so
+  `?include=` republishes ids the primary document withholds
+  ([#235](https://github.com/abofs/stonyx-orm/issues/235)). See
+  [Consumer Contracts](#consumer-contracts).
 
 ## Lifecycle Hooks
 
@@ -1249,16 +1357,6 @@ Each hook receives a context object with comprehensive information:
 - It contains a deep copy of the record's state **before** the operation executes (captured before the `before` hook fires)
 - The deep copy is created via JSON serialization (`JSON.parse(JSON.stringify())`) to ensure complete isolation
 - For `delete` operations, `recordId` is provided in after hooks since the record may no longer exist in the store
-- **`context.recordId` here is NOT `AccessContext.recordId`.** Same name, same-shaped
-  object, different coverage: `_withHooks` sets this key **only** under
-  `operation === 'delete'`, so on `get` / `list` / `create` / `update` the key is
-  **absent** — `beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)`
-  never fires (measured: `PATCH /owners/{id}` → 200 with `ctx.recordId === undefined`
-  and the id sitting in `ctx.params`). The access context, by contrast, carries
-  `recordId` on every route it classifies and spells absence as `null`, never
-  `undefined`. Tracked as
-  [#242](https://github.com/abofs/stonyx-orm/issues/242); see
-  `AccessContext.recordId` in `src/types/orm-types.ts` for the other side.
 - `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous field values
 
 ### Usage Examples

package/dist/access-verdict.d.ts

@@ -0,0 +1,59 @@
+import type { AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+    granted: boolean;
+    filter?: (record: unknown) => boolean;
+}
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export declare function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict;
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite. `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay DISTINCT, where `` `${type}:${id}` `` --
+ * or a bare `String(id)` -- collapses them onto one entry and answers the second
+ * record with the first record's verdict.
+ *
+ * WHAT THAT DOES AND DOES NOT PROTECT. It cannot cross MODELS. `decisions` is
+ * already partitioned per type by `byType`, so a composite key inside a per-type
+ * map is one-to-one with the raw one and no owner's verdict could ever answer
+ * for an animal -- the claim that once stood here. The real exposure is narrower
+ * and entirely WITHIN one model: two records of the same type whose ids differ
+ * only by JavaScript type, which a per-record predicate may legitimately answer
+ * differently about (an id read off a JSON body is a string; the same id
+ * assigned by the server is a number). Pinned by unit assertion, because this
+ * fixture cannot produce the collision on its own -- `owner` ids are strings and
+ * `animal` ids are numbers.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export declare function createLinkageFilter(request: unknown): LinkageFilter;