@stonyx/orm 0.3.2-alpha.62 → 0.3.2-alpha.63

package/README.md

@@ -315,24 +315,15 @@ Access classes define models and provide custom filtering/authorization logic.
 > [Identifying the collection](#identifying-the-collection) before copying this.**
 > Every attempt to identify the collection by parsing the request target has
 > failed **open** — five distinct variants of this same example, each found only
-> after the previous was fixed, by five different people. That section is now a
-> record of what not to do, not a matching recipe: the sample below reads `model`
-> from [the access context](#the-access-context-second-argument) and never looks
-> at the mount at all, so all five variants are **unconstructible** against it
-> rather than merely handled.
+> after the previous was fixed, by five different people. The sample below does
+> not parse anything: it reads `request.baseUrl`, the mount Express actually
+> matched.
 >
 > 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
 > identify. Until it lands, prefer the array shape (`['read']`) or `false` where
 > you can: the **function** shape is the one that requires any matching at all.
->
-> The one read of argument **one** that survives is `request.path`, for the
-> `/archived` sub-path deny — and it has to. The context names which model and
-> which verb, not which route, so that deny **cannot be expressed from the
-> context alone** and a context-only rewrite would silently turn it into an
-> allow.
->
 > 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.
@@ -346,39 +337,27 @@ Access classes define models and provide custom filtering/authorization logic.
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
-  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. Nothing below parses anything, so none of the five fail-open
-    // variants recorded in the header is constructible against this predicate
-    // any more; they are history, not rules to follow.
-    //
-    // `operation` is destructured to name the whole contract at the point of
-    // 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. `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.
-    if (typeof model !== 'string' || model === '') return false;
-
-    if (model === 'owner') {
-      // 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. 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. false → 403 for the whole
-      // request.
-      //
-      // 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.
-      const path = String(request.path ?? '').toLowerCase();
+  access(request) {
+    // `request.baseUrl` is the mount Express matched — `/owners`, or
+    // `/api/owners` under ORM_REST_ROUTE=/api. Never parse `originalUrl`: it is
+    // the raw request target and can be absolute-form.
+    const mount = request.baseUrl;
+
+    // FAIL CLOSED. If Express did not tell us what it matched we are not behind
+    // the mount we think we are, and an unidentifiable request denies rather
+    // than falling through to the CRUD grant at the bottom.
+    if (typeof mount !== 'string' || mount === '') return false;
+
+    // Lower-cased because the router matched case-INSENSITIVELY, and a matcher
+    // stricter than the router that dispatched the request can be stepped
+    // around. The PATH only — record ids stay at their real case below.
+    const collection = mount.toLowerCase();
 
+    // `request.path` is mount-relative and query-free, so sub-path rules need no
+    // prefix arithmetic either. false → 403 for the whole request.
+    const path = String(request.path ?? '').toLowerCase();
+
+    if (collection.endsWith('/owners')) {
       if (path === '/archived' || path.startsWith('/archived/')) return false;
 
       // Returning a function plugs it in as a per-record filter, and it is
@@ -394,7 +373,7 @@ export default class GlobalAccess {
     // inert. Deliberately NO `?? record.owner` fallback: accepting the raw
     // shape as well as the resolved one would absorb a resolution regression
     // silently, which is exactly what blinded this fixture before.
-    if (model === 'animal') return record => record.owner?.id !== 'restricted';
+    if (collection.endsWith('/animals')) return record => record.owner?.id !== 'restricted';
 
     // Allows full access to all calls that don't match any of the above conditions
     return ['read', 'create', 'update', 'delete'];
@@ -544,10 +523,9 @@ sample, `getAccess('owner') === getAccess('animal')`.
 #### Passing the context makes a model-correct answer *possible*
 
 It does not make the answer model-correct on its own. **The resolved predicate
-has to read the context.** Against a predicate that ignores it the failure is
-measurable. On a request Express dispatched to `GET /owners/angela`, asked about
-**animals**, the sample as it shipped before
-[#222](https://github.com/abofs/stonyx-orm/issues/222) answered:
+has to read the context.** Measured against the access class shipped with this
+repo, on a request Express dispatched to `GET /owners/angela`, asked about
+**animals**:
 
 ```
 getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
@@ -555,26 +533,18 @@ getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
 ```
 
 That is the **owners** filter, and it returns `true` for animal 21 — the record
-hidden on every animal surface. Under a mount such a predicate recognizes
-neither way it is worse still: it falls through to
-`['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
-context was supplied and the answer is not the animal answer, and it is wrong in
-the direction that **grants** — because that predicate was single-argument and
-identified its collection from the request, so it answered about the collection
-the request was *addressed to* while being asked about another one.
-
-The sample shipped with this repo has since been migrated to read the context,
-and the same call now answers with the **animal** filter:
-
-```
-getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
-  ->  record => record.owner?.id !== 'restricted'
-```
-
-A single-argument predicate remains the default in every consumer tree, and a
-caller has no supported way to tell which kind it resolved. The boot-time arity
-warning that surfaces one is
-[#221](https://github.com/abofs/stonyx-orm/issues/221).
+hidden on every animal surface. Under a mount that predicate recognizes neither
+way it is worse still: it falls through to
+`['read', 'create', 'update', 'delete']`, a full CRUD grant.
+
+Either way the context was supplied and the answer is not the animal answer, and
+it is wrong in the direction that **grants**. That predicate is single-argument
+and identifies its collection from the request, so it answered about the
+collection the request is *addressed to* while being asked about another one.
+Every predicate in this repo, and in every consumer tree, is single-argument on
+the day this ships, and a caller has no supported way to tell which kind it
+resolved. The boot-time arity warning that would surface it is
+[#213](https://github.com/abofs/stonyx-orm/issues/213).
 
 So: pass the context, and do not treat a resolved predicate's answer as
 model-specific until that predicate has been migrated to read it.
@@ -611,7 +581,7 @@ a write to a *different* collection can still re-parent one. See
 | `GET /:models/:id/relationships/{relationship}` | `404` — same |
 | `PATCH /:models/:id` | `404`, no attribute is applied |
 | `DELETE /:models/:id` | `404`, the record is not removed and no SQL `DELETE` is issued |
-| `POST /:models` | `403`, and a record **this request inserted** is rolled back — see [Known limitations](#known-limitations) for the case where it did not insert one |
+| `POST /:models` | `403`, and a record **this request inserted** is rolled back — see [Known limitations](#known-limitations) for why the rollback is conditional |
 
 **Denied record-level requests return 404, not 403.** This is deliberate and it
 is the property most easily "improved" away. 403 would confirm that the record
@@ -645,23 +615,35 @@ chooses the id and learns whether the create succeeded — so under a filter the
 caller does not choose the id. The refusal happens before any store lookup, so
 neither the status nor the response time depends on whether the id exists.
 
-Let the server assign the id and read it back from the response. Callers with no
-function-style filter are unaffected: `409` on a duplicate id and `200` on a free
-one both behave exactly as before.
+Let the server assign the id and read it back from the response — and read it
+back rather than predicting it, because the value it returns is documented but
+not stable across model kinds: a numeric-id model gets `max + 1` (or, at the
+numeric ceiling, the lowest free integer), and a string-id model gets
+`<model>-<n>`. See breaking change 8.
+
+**What a server-assigned id is not.** It is not a secret. On a string-id
+collection it is dense and enumerable from `1`, where previously it inherited
+whatever entropy the last-inserted id happened to carry — a UUID-seeded store
+answered a UUID-derived key. If a collection has **no** `access` config its
+record-level routes are ungated, so the id was the only thing standing between
+an unauthenticated caller and `GET`/`PATCH`/`DELETE` on a record. That was never
+a control and must not become one; configure `access`.
+
+**And the id itself is an occupancy signal.** `assignRecordId` reads the whole
+store, not the caller's filtered view — it never sees `state.filter` — so the id
+it returns is a function of records the caller may not be permitted to read. On
+a string-id collection the assigned `n` is the smallest positive integer whose
+key is free, which tells the caller that every key below it is taken, hidden or
+not. Closing that requires the assignment to be filter-aware, which is a change
+to the `access` contract rather than a fix; it is stated here rather than left
+to be discovered. Callers with no function-style filter are unaffected — there
+are no hidden records to disclose.
 
 ### Identifying the collection
 
-**Do not reconstruct the request path — and since
-[#202](https://github.com/abofs/stonyx-orm/issues/202) you do not have to
-identify the collection at all.** Read `model` from
-[the access context](#the-access-context-second-argument): it is fixed at mount
-time, no request can influence it, and there is nothing left to parse.
-
-**Everything below is the record of what happened when this sample did parse
-it.** It is kept as history, not as a recipe — none of these matching strategies
-should be written into a new predicate. Every version of this sample that tried
-to identify the collection from the request target failed **open**, and each
-variant was found only after the previous one was fixed:
+**Do not reconstruct the request path.** Every version of this sample that tried
+to has failed **open**, and each variant was found only after the previous one
+was fixed:
 
 | # | Variant | Why it fails open |
 |---|---|---|
@@ -671,19 +653,13 @@ variant was found only after the previous one was fixed:
 | 4 | hard-coded `/owners` | With `ORM_REST_ROUTE=/api` every url becomes `/api/owners/...` and the sample matches nothing — environment-specifically, which is harder to notice than failing everywhere. The remediation this document used to give was itself broken: `` `${config.orm.restServer.route}owners` `` evaluates to **`/apiowners`**, so a reader who followed the correction exactly still failed open and believed they had handled it. |
 | 5 | any match on `originalUrl` at all | HTTP/1.1 permits an **absolute-form** request-target. Express routes on `parseurl(req).pathname`, so the request dispatches normally — but `originalUrl` is the raw target. `GET http://anything.example/owners/angela` yields `originalUrl === 'http://anything.example/owners/angela'`, which has no `/owners` prefix. Measured: the record came back in full, `DELETE` succeeded, and it walked past a hard `return false` deny the same way. |
 
-**The fix is not a sixth rule, and it is not a better string to match.** It is
-to stop identifying the collection at all.
+**The fix is not a sixth rule.** It is to stop parsing:
 
-An intermediate revision read **`request.baseUrl`** — the mount Express
-*actually matched*. That closed all five variants: it carries no query string
-(variant 2), it is not mount-relative (variant 1), it already contains the
-configured `ORM_REST_ROUTE` prefix (variant 4 — there is nothing left to derive,
-so `/apiowners` is unconstructible), and it is unaffected by an absolute-form
-target (variant 5). It was still a transport artifact standing in for a
-structural fact, and it is **no longer what the sample does**: the sample reads
-`model`, so all five variants are unconstructible against it rather than
-handled. The table below is retained as the measured evidence behind the five
-variants, not because any of these values should be matched on:
+**Use `request.baseUrl`.** It is the mount Express *actually matched* when it
+dispatched the request. It carries no query string (variant 2), it is not
+mount-relative (variant 1), it already contains the configured `ORM_REST_ROUTE`
+prefix (variant 4 — there is nothing left to derive, so `/apiowners` is
+unconstructible), and it is unaffected by an absolute-form target (variant 5).
 
 | request | `request.url` | `request.originalUrl` | `request.baseUrl` | `request.path` |
 |---|---|---|---|---|
@@ -694,23 +670,21 @@ variants, not because any of 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` |
 
-**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
-names which model and which verb, **not which route**, so that deny *cannot be
-expressed from the context alone*, and a context-only rewrite would silently turn
-it into an allow. Lower-case it before comparing: the router matched
-case-insensitively, so a case-sensitive sub-path rule is stricter than the router
-that dispatched the request and can be stepped around. Record ids are
-case-sensitive and must be compared at their real case.
-
-**Fail closed on anything you cannot identify.**
-`String(request.originalUrl ?? '')` was once added here to stop a `TypeError`,
-and it traded fail-closed for fail-**open**: an empty string matched no
-collection, so `access()` fell through to the permission array and granted full
-CRUD. The same rule now applies to the context — the sample returns `false` for
-an absent `model` rather than falling through. An input you cannot identify must
-**deny**.
+Two rules remain, and they are the whole list:
+
+**1. Compare lower-cased.** `baseUrl` is the text the caller sent, not the
+registered mount — `GET /OwNeRs/angela` yields `/OwNeRs`. The router matched it
+case-insensitively, so a case-sensitive comparison here is stricter than the
+router and can be walked past. Lower-case the **mount and path only**; record ids
+are case-sensitive and must be compared at their real case.
+
+**2. Fail closed when `baseUrl` is absent.** `String(request.originalUrl ?? '')`
+was added to stop a `TypeError`, and it traded fail-closed for fail-**open**: an
+empty string matches no collection, so `access()` fell through to the permission
+array and granted full CRUD. An input you cannot identify must **deny**.
+
+Use `request.path` — mount-relative and query-free — if you need to distinguish
+sub-paths beneath the mount, as the `/archived` deny above does.
 
 ### Known limitations
 
@@ -733,14 +707,11 @@ an absent `model` rather than falling through. An input you cannot identify must
   see [The access context](#the-access-context-second-argument):
   `Orm.instance.getAccess(modelName)` makes another model's predicate
   **reachable**, and `context.model` makes a **model-correct answer possible** —
-  possible, not guaranteed: the resolved predicate has to read the context. The
-  sample shipped with this repo now does
-  ([#222](https://github.com/abofs/stonyx-orm/issues/222)), so
-  `getAccess('animal')` answers with the animal filter; a predicate that ignores
-  the second argument still answers about the collection the request is
-  addressed to, and the boot-time warning that surfaces one is
-  [#221](https://github.com/abofs/stonyx-orm/issues/221). **The mechanism
-  exists; the ORM does not yet use it on this path.** The re-parenting write above is still
+  possible, not guaranteed: the resolved predicate has to read the context, and
+  every predicate in tree is still single-argument
+  ([#213](https://github.com/abofs/stonyx-orm/issues/213)), so today it answers
+  about the collection the request is addressed to. **The mechanism exists; the
+  ORM does not yet use it on this path.** The re-parenting write above is still
   **not refused** — that enforcement is
   [#196](https://github.com/abofs/stonyx-orm/issues/196) and
   [#207](https://github.com/abofs/stonyx-orm/issues/207), which were blocked on
@@ -792,9 +763,10 @@ an absent `model` rather than falling through. An input you cannot identify must
   transform output differs from its lookup key is the same defect. Filtered
   collections are unaffected — breaking change 3 refuses any client-supplied id
   — so this reaches consumers with **no** function-style filter. Tracked as
-  [#205](https://github.com/abofs/stonyx-orm/issues/205), alongside
-  [#203](https://github.com/abofs/stonyx-orm/issues/203), which is the other way
-  a create can land on an id nobody named.
+  [#205](https://github.com/abofs/stonyx-orm/issues/205). Its sibling
+  [#203](https://github.com/abofs/stonyx-orm/issues/203) — a **server-assigned**
+  id landing on an occupied slot — is **fixed**; see breaking change 8. #205 is
+  the client-supplied half and is still open.
 - **`context.record` is `undefined` for an after-`create` hook when a string-id
   model is given a numeric-looking id.** The post-create lookup uses the same id
   coercion as every other surface, which resolves `'9107'` to the number `9107`,
@@ -804,15 +776,18 @@ an absent `model` rather than falling through. An input you cannot identify must
   [#209](https://github.com/abofs/stonyx-orm/issues/209).
 - **A denied `POST` rolls back only a record it *inserted*.** The rollback
   requires the store to have grown, because removing by id alone is a write
-  primitive keyed by a caller-supplied value. When `assignRecordId` lands a
-  **server-assigned** id on an occupied slot
-  ([#203](https://github.com/abofs/stonyx-orm/issues/203) — it returns
-  last-*inserted* + 1, not max + 1, so a store whose insertion order is not
-  ascending collides), `createRecord` updates that record **in place**: the map
-  does not grow, the rollback correctly declines to remove a record this request
-  did not create, and the `403` leaves the caller's attributes on someone else's
-  record. Narrow — it needs a non-ascending insertion order — but it is the
-  reachability condition, so it is stated rather than implied.
+  primitive keyed by a caller-supplied value. **The reachability condition this
+  bullet used to state is gone**: it was
+  [#203](https://github.com/abofs/stonyx-orm/issues/203) — `assignRecordId`
+  returned last-*inserted* + 1, so a server-assigned id could land on an
+  occupied slot and `createRecord` would update it in place — and #203 is fixed
+  (breaking change 8). A server-assigned create can no longer overwrite, so on a
+  collection whose only id channel is `createHandler` this guard has no
+  observable effect today. It is kept because a caller-supplied id reaching
+  `createRecord` from another route — a relationship write,
+  [#207](https://github.com/abofs/stonyx-orm/issues/207) — puts the condition
+  back, and without the guard a denied `403` would delete a record the request
+  did not create.
 
 ### Breaking changes
 
@@ -873,6 +848,39 @@ they are recorded here.
    population breaking changes 3 and 4 explicitly exempt. If you were relying on
    a hex-shaped or whitespace-padded id creating a second record, it never did.
 
+8. **Server-assigned ids change value on string-id models, and the create route
+   gains a `409`.** Two consumer-visible changes from
+   [#203](https://github.com/abofs/stonyx-orm/issues/203).
+
+   **The value.** A `POST` with no `id` against a model declaring
+   `id = attr('string')` previously produced the *last-inserted* id with `1`
+   concatenated onto it — an owner store holding `['gina', 'bob']` answered
+   `'bob1'`. It now answers `'owner-1'`: the model name, a hyphen, and the
+   lowest positive integer whose landing key is free. **No test in this repo
+   pinned the old value**, so a consumer relying on it gets no failing test, no
+   deprecation and no other signal — which is why it is recorded here. Numeric
+   id models (`id = attr('number')`, the default) are unaffected in shape: they
+   still get an integer, but it is now the **maximum** existing id plus one
+   rather than the last-inserted id plus one, which is the defect #203 is about.
+
+   The value is deliberately **not** numeric-looking, and that is not cosmetic.
+   Every id-bearing surface resolves a numeric-looking string id to a **number**
+   (`GET /owners/1` looks up `1`), while a string-id model files its records
+   under the **string** key `'1'`. A server-assigned `'1'` would therefore be a
+   record that was created successfully and could not be fetched, updated or
+   deleted by id, and whose after-`create` hook received
+   `context.record === undefined`
+   ([#209](https://github.com/abofs/stonyx-orm/issues/209)).
+
+   **The status.** `POST /{collection}` can now answer `409` for a reason other
+   than a duplicate id: the server could not derive a free id. That requires a
+   **non-injective** id transform — one that maps distinct candidates onto the
+   same store key, such as `boolean`, or anything you registered on
+   `Orm.instance.transforms` and named as an id type. It is a configuration
+   fault rather than a request fault; the message is logged through
+   `stonyx/log`. Previously this case threw out of the handler and express
+   answered `500` with a stack trace.
+
 ### Include Parameter (Sideloading Relationships)
 
 The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.