@stonyx/orm 0.3.2-alpha.48 → 0.3.2-alpha.49

package/README.md

@@ -309,29 +309,240 @@ import setupRestServer from '@stonyx/orm/setup-rest-server';
 await setupRestServer('/', './access');
 ```
 
-Access classes define models and provide custom filtering/authorization logic:
+Access classes define models and provide custom filtering/authorization logic.
+
+> **The URL-matching in this example is a stopgap. Read
+> [Matching the url](#matching-the-url) before copying it.** The same three-line
+> example has failed **open** in four distinct ways during one review, each found
+> only after the previous was fixed. The sample below closes all four; that is
+> not the same as being safe. 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 no URL to parse.
 
 ```js
+import config from 'stonyx/config';
+
+// Build the mount prefix from the SAME value the ORM mounts under, and compare
+// lower-cased. Both are load-bearing — see "Matching the url".
+function collectionPrefix(name) {
+  const route = config.orm.restServer.route ?? '/';
+  const trimmed = String(route).replace(/^\/+|\/+$/g, '');
+
+  return `${trimmed === '' ? '' : `/${trimmed}`}/${name}`.toLowerCase();
+}
+
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
   access(request) {
+    // `originalUrl`, not `url` — `url` is mount-relative, so a prefix match
+    // against it is ALWAYS false. Query string stripped, because `originalUrl`
+    // carries it. Lower-cased, because the router matched case-insensitively
+    // and a matcher stricter than the router can be walked past. Every one of
+    // those three omissions fails OPEN.
+    const path = String(request.originalUrl ?? '').split('?')[0].toLowerCase();
+    const owners = collectionPrefix('owners');
+
     // false → 403 for the whole request
-    if (request.url.startsWith('/admin')) return false;
+    if (path.startsWith(`${owners}/archived`)) return false;
 
-    // A function is a per-record filter. It is enforced on the collection, on
-    // GET/PATCH/DELETE by id, and on both relationship route families. Match on
-    // the url prefix so record routes get the predicate too. Rejected records
-    // are 404 on record routes and 403 on POST.
-    if (request.url.startsWith('/owners')) return record => record.id !== 'angela';
+    // A function is a per-record filter. Anchored on a `/` boundary so it
+    // cannot also match `/owners-archive`. Rejected records are 404 on record
+    // routes, 403 on POST.
+    if (path === owners || path.startsWith(`${owners}/`)) {
+      return record => record.id !== 'angela';
+    }
 
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
-> `include` (sideloading) does not yet apply the included model's own access
-> filter — see [#196](https://github.com/abofs/stonyx-orm/issues/196).
+### Return values
+
+| `access()` returns | Effect |
+|---|---|
+| `false` (or any falsy value) | `403` for the whole request |
+| `true` | full access, no filter |
+| `['read', 'create', 'update', 'delete']` | the listed operations only; anything else is `403` |
+| `'read'` (a bare string) | **one** permission, equivalent to `['read']` |
+| a function | a per-record filter — see below |
+| anything else | `403` — unknown shapes fail **closed** |
+
+A `throw` inside `access()` is a **denial**, not a 500.
+
+### Filter functions
+
+A function return value is a **per-record predicate**, and it is enforced on
+every endpoint that is addressed to a record — not only on the collection:
+
+| Endpoint | A record the predicate rejects |
+|---|---|
+| `GET /:models` | omitted from the collection |
+| `GET /:models/:id` | `404` |
+| `GET /:models/:id/{relationship}` | `404` — the **addressed** record is filtered, not the related one |
+| `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 nothing is left in the store |
+
+**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
+exists to a caller who is not allowed to know that, which turns the filter into
+an existence oracle: `404` means "no such record", `403` means "there is one and
+it is not yours". Every status on a record route must therefore be identical for
+"filtered out" and "does not exist" — including `DELETE`, which is why deleting
+a record that never existed also returns 404 rather than 204.
+
+`POST` is the one exception and returns **403**, because 404 on a mounted
+collection route is indistinguishable from "model not mounted" — a genuinely
+different failure a developer needs to diagnose.
+
+**A client-supplied `id` on `POST` is refused with `403` whenever a function
+filter is in force.** This is the part that keeps `POST` from being an
+enumeration oracle, and it is worth understanding rather than working around.
+The duplicate-id check has to run before the filter, and it sees records the
+filter hides, so the *status* of a `POST` otherwise leaks whether an id is
+taken:
+
+| `POST /animals` with a payload the caller may create | before | now |
+|---|---|---|
+| an id held by a record the filter **hides** | `403` | `403` |
+| an id that is **free** | `200` | `403` |
+| an id held by a record the caller **can see** | `409` | `403` |
+
+Three outcomes, one request per id, the whole id space. Filtering only the
+*collision* status narrows that to callers who cannot create a record they are
+allowed to see; it does not close it. It cannot be closed while a caller both
+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.
+
+### Matching the url
+
+**This section describes a pattern the framework should not be asking you to
+implement.** It has produced four separate fail-open defects, listed below,
+each found only after the previous was fixed, and there is no reason to believe
+the list is complete. [#202](https://github.com/abofs/stonyx-orm/issues/202)
+replaces it. Until then, all four rules apply and each one, omitted, fails
+**open**.
+
+**1. Match `request.originalUrl`, never `request.url`.**
+`RestServer.mountRoute` mounts each model as an Express **sub-app**, so by the
+time `access()` runs the mount path has been stripped from `request.url`:
+
+| request | `request.url` | `request.originalUrl` |
+|---|---|---|
+| `GET /owners` | `/` | `/owners` |
+| `GET /owners/angela` | `/angela` | `/owners/angela` |
+| `GET /owners/angela/pets` | `/angela/pets` | `/owners/angela/pets` |
+
+`request.url.startsWith('/owners')` is therefore **always false**: the branch
+never fires, `access()` falls through to whatever it returns last, and a filter
+that looks correct enforces nothing on any surface.
+
+**2. Strip the query string, and match the prefix rather than the exact url.**
+The predicate has to be returned for record routes too, so
+`url.endsWith('/owners')` leaves `/owners/angela` unguarded — and `originalUrl`
+carries the query string, so a bare `=== '/owners'` misses
+`/owners?filter[age]=30` and lets a filtered collection through unfiltered.
+Anchoring on the path portion covers both without also matching
+`/owners-archive`.
+
+**3. Compare lower-cased.** `RestServer` mounts with a bare `express()`, whose
+default is `caseSensitive: false`, while `originalUrl` preserves the caller's
+case. A case-sensitive matcher is stricter than the router that dispatched the
+request, so it can simply be stepped around:
+
+```
+GET    /owners/angela  -> 404          GET    /OwNeRs/angela -> 200, angela in full
+GET    /owners         -> filtered     GET    /OWNERS        -> unfiltered
+DELETE /animals/22     -> 404          DELETE /ANIMALS/22    -> 204, record destroyed
+```
+
+Lower-case the **path** only. Record ids are case-sensitive and must be compared
+at their real case. The router-side fix is tracked as
+[stonyx-rest-server#47](https://github.com/abofs/stonyx-rest-server/issues/47).
+
+**4. Build the prefix from the configured mount route.** With
+`ORM_REST_ROUTE=/api` the urls above become `/api/owners/...`, and a sample
+hard-coded to `/owners` matches nothing — environment-specifically, which is
+harder to notice than failing everywhere.
+
+Note what this must *not* be. An earlier version of this document suggested
+`` `${config.orm.restServer.route}owners` ``. For the default route that is
+`/owners` and looks correct; for `ORM_REST_ROUTE=/api` it evaluates to
+**`/apiowners`**, so a reader who followed the correction exactly still failed
+open and believed they had handled it. Join on `/` and collapse the duplicate,
+as `collectionPrefix()` above does.
+
+### Known limitations
+
+- **Authorization by URL matching is a consumer-side reconstruction of
+  information the framework already holds.** `access()` receives a transport
+  artifact and is asked to re-derive, correctly and defensively, which model,
+  which operation and which record the request addresses. The four rules above
+  are the four ways that reconstruction has been observed to fail open so far.
+  Tracked as [#202](https://github.com/abofs/stonyx-orm/issues/202).
+- **Related and included records are not filtered.** The predicate is evaluated
+  against the record the route is *addressed to*. `GET /animals/1/owner`,
+  `GET /animals/1/relationships/owner` and `?include=owner` all serialize the
+  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.
+- **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
+  `beforeHook('get', ...)` read-through cache can answer past the filter.
+- **`beforeHook('create', ...)` still runs for a `POST` that is denied.** For
+  `create` there is no record to test until the handler has built one, so the
+  denial is not knowable in time. Every *after*-hook is gated, and every
+  before-hook on `update` and `delete` is gated; before-`create` is the one
+  exception. A before-`create` hook must not assume the create will succeed.
+- **A caller can still learn that a collection *has* a per-record filter**, by
+  observing `403` rather than `409`/`200` for an id-bearing `POST`. That
+  discloses a configuration fact, not the existence of any record.
+- **Enforcement is post-fetch.** The record is loaded and then tested, which
+  leaves a small timing difference between a hidden record and one that never
+  existed. Tracked as [#197](https://github.com/abofs/stonyx-orm/issues/197).
+
+### Breaking changes in 0.4.0
+
+There is no changelog or release-notes channel yet
+([stonyx-workflows#17](https://github.com/abofs/stonyx-workflows/issues/17)), so
+they are recorded here.
+
+1. **`DELETE /{collection}/{id}` on a record that does not exist returns `404`
+   instead of `204`.** This affects **every** consumer issuing a DELETE against
+   any mounted collection, whether or not an access filter is configured, and
+   `models: '*'` mounts every model by default. It is not optional: if a denied
+   delete returned 404 while a missing one returned 204, the pair would be a
+   perfect existence oracle and the filter would be worthless.
+2. **After-hooks no longer fire for a write that failed** — denied, missing,
+   `400` or `409`. Previously `afterHook('delete', ...)` ran with a populated
+   `context.recordId` on a request that deleted nothing, so a consumer cascade
+   destroyed children behind a 404.
+3. **`POST` with a client-supplied `id` returns `403` when a function-style
+   `access` filter is in force**, whatever the payload and whether or not the id
+   exists. Only affects function-style `access` users. See
+   [Filter functions](#filter-functions) for why, and let the server assign the
+   id instead. `409`-on-duplicate is unchanged for everyone else.
+4. **Function-style `access` is now enforced on all seven surfaces.** Records
+   previously reachable by id despite being filtered from the collection now
+   return 404. Only affects function-style `access` users, for whom the old
+   behaviour was the bypass.
+5. **A predicate that throws is treated as a denial** rather than propagating to
+   Express's default 500 handler. So is an `access()` that throws.
+6. **`access()` returning a bare string is one permission, not full access.**
+   `AccessMethod` declares `string` legal, and it previously fell through every
+   branch and granted all four operations — `return 'read'` allowed `DELETE`.
+   It is now equivalent to `['read']`. Any other unrecognised shape (an object,
+   a number) now returns `403` rather than granting full access.
 
 ### Include Parameter (Sideloading Relationships)
 

package/dist/orm-request.js

@@ -56,6 +56,30 @@ function getId(params) {
         return id;
     return parseInt(id);
 }
+/**
+ * Normalise a caller-supplied BODY id to the key the store will hold it under.
+ *
+ * `getId()` above is params-shaped: it takes `{ id?: string }` off the URL,
+ * where the value is always a string and a falsy one means "no id". A JSON body
+ * id is neither -- it can arrive as a number, and `0` is a legitimate id that
+ * `getId()` would flatten to `''`.
+ *
+ * WHY THIS EXISTS AT ALL. createHandler used to look the collision up with the
+ * RAW body value while every other surface normalised through `getId()`. The
+ * store is a Map keyed by the coerced value, so `store.find(model, '21')` misses
+ * the entry held under `21` and the duplicate check is skipped by typing the id
+ * as a string. On `dev` that silently overwrote the colliding record and
+ * answered 200; combined with the denied-create rollback added for #190 it
+ * became an unauthenticated DELETE of any id. Normalising here is half of that
+ * fix -- see the rollback in createHandler for the other half.
+ */
+function normalizeBodyId(id) {
+    if (typeof id === 'number')
+        return id;
+    if (typeof id !== 'string' || id.trim() === '')
+        return id;
+    return isNaN(id) ? id : parseInt(id, 10);
+}
 function buildResponse(data, includeParam, recordOrRecords, options = {}) {
     const { links, baseUrl } = options;
     const response = { data };
@@ -202,7 +226,17 @@ function createFilterPredicate(filters) {
 function isDenied(filter, record) {
     if (typeof filter !== 'function')
         return false;
-    return !filter(record);
+    // A predicate that throws is treated as a denial. Unguarded, a throw escapes
+    // to express's default handler, which answers 500 (with a stack trace outside
+    // NODE_ENV=production) while a missing id still answers 404 -- so a
+    // record-dependent throw re-separates "hidden" from "does not exist" and
+    // hands back the oracle this whole change exists to close.
+    try {
+        return !filter(record);
+    }
+    catch {
+        return true;
+    }
 }
 export default class OrmRequest extends Request {
     model;
@@ -256,9 +290,48 @@ export default class OrmRequest extends Request {
                 return 400; // Bad request
             const fieldsMap = parseFields(query);
             const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
-            // Check for duplicate ID
-            if (id !== undefined && await store.find(model, id))
-                return 409; // Conflict
+            // GATE 0 -- the POST existence oracle.
+            //
+            // The duplicate check runs before the filter and `store.find` sees hidden
+            // records, so POST leaks existence through its STATUS. A previous revision
+            // filtered the collision status (403 when the colliding record is denied,
+            // 409 when it is visible) and that is NOT sufficient, because the status
+            // of a create is a third outcome. With a payload the caller is permitted
+            // to create -- the normative case for a per-tenant filter, and the case an
+            // attacker picks -- all three are distinguishable in ONE request per id:
+            //
+            //   POST /animals {id:22,   owner:'gina'} -> 403   a HIDDEN record has this id
+            //   POST /animals {id:9500, owner:'gina'} -> 200   this id is FREE
+            //   POST /animals {id:8,    owner:'gina'} -> 409   a VISIBLE record has this id
+            //
+            // Filtering only the collision status narrows that to callers who cannot
+            // create a record they are allowed to see. It does not close it.
+            //
+            // It cannot be closed while a caller both chooses the id and learns
+            // whether the create succeeded: a successful create must answer
+            // differently from a refused one. So when a per-record filter is in force
+            // the caller does not get to choose the id at all. The refusal is
+            // UNCONDITIONAL and happens BEFORE any store lookup, so no status, and no
+            // lookup cost, can depend on whether that id exists. 403 -- the same
+            // status as a denied create -- so the two cannot be separated either.
+            //
+            // Scoped to function-style `access` because that is exactly the population
+            // the oracle exists for: with no per-record filter there are no hidden
+            // records, and 409 discloses nothing GET /:id does not already.
+            //
+            // RESIDUAL, stated rather than implied: a caller can still learn that a
+            // collection HAS a per-record filter (403 rather than 409/200 for an
+            // id-bearing POST). That discloses a configuration fact, not a record.
+            // See README `### Known limitations`.
+            if (id !== undefined) {
+                if (typeof filter === 'function')
+                    return 403; // Forbidden
+                // `normalizeBodyId`, not the raw value: a string-typed id misses the
+                // store's numeric key, which skipped this check entirely.
+                const existing = await store.find(model, normalizeBodyId(id));
+                if (existing)
+                    return 409; // Conflict
+            }
             const { id: _ignoredId, ...sanitizedAttributes } = attributes || {};
             // Extract relationship IDs from JSON:API relationships object
             if (rels) {
@@ -270,10 +343,19 @@ export default class OrmRequest extends Request {
                 }
             }
             const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
+            // Slot count BEFORE the write. `createRecord` writes to the store before
+            // the predicate can run, and the rollback below must be able to prove the
+            // slot it removes is one THIS REQUEST created. Identity alone cannot
+            // prove it: when `assignRecordId` lands on an occupied id, `createRecord`
+            // mutates the existing OrmRecord IN PLACE, so `store.get(...) === record`
+            // is true for a record the request did not create. The map's size is the
+            // only O(1) signal that distinguishes an insert from an overwrite.
+            const slotsBefore = store.get(model)?.size ?? 0;
             const created = createRecord(model, recordAttributes, { serialize: false, _skipAutoPersist: true });
             const record = isOrmRecord(created) ? created : null;
             if (!record)
                 return 500;
+            const createdNewSlot = (store.get(model)?.size ?? 0) > slotsBefore;
             // 403 here, NOT 404. The oracle argument does not apply to create: there
             // is no pre-existing record whose existence could leak, the caller
             // supplied the attributes, and 404 on a mounted collection route is
@@ -284,7 +366,26 @@ export default class OrmRequest extends Request {
             // the predicate can run, so returning 403 alone would leave the record
             // behind: a worse bug than the bypass being fixed.
             if (isDenied(filter, record)) {
-                store.remove(model, record.id, { _skipAutoPersist: true });
+                // ROLL BACK BY IDENTITY, NEVER BY ID. `store.remove(model, record.id)`
+                // on its own is a write primitive keyed by a value the caller may have
+                // supplied: with the raw-id collision bypass above, a denied
+                // `POST {"id":"21"}` answered 403 and DELETED hidden record 21 -- an
+                // unauthenticated deletion primitive across the whole id space, created
+                // by adding a rollback to a lookup that could be skipped.
+                //
+                // Both conditions are required and neither implies the other:
+                //   createdNewSlot -- the store grew, so this request inserted rather
+                //                     than overwrote. Guards `assignRecordId` picking an
+                //                     id that is already taken (it returns
+                //                     last-INSERTED + 1, not max + 1, so a store whose
+                //                     insertion order is not ascending collides) -- see
+                //                     abofs/stonyx-orm#203.
+                //   identity       -- the slot still holds the object we just created,
+                //                     so nothing between createRecord and here replaced
+                //                     it.
+                if (createdNewSlot && store.get(model, record.id) === record) {
+                    store.remove(model, record.id, { _skipAutoPersist: true });
+                }
                 return 403;
             }
             return { data: record.toJSON?.({ fields: modelFields }) };
@@ -296,6 +397,13 @@ export default class OrmRequest extends Request {
             // Checked BEFORE any attribute is applied. 404 rather than 403 for the
             // same reason as GET /:id -- 403 would disclose both that the record
             // exists and that this caller specifically is excluded.
+            //
+            // NOT redundant behind GATE 1, and not defence in depth either: GATE 1's
+            // verdict is computed BEFORE the before-hook loop runs, and a before-hook
+            // is a published extension point that can change the answer -- by
+            // mutating the record, or against a predicate that closes over
+            // per-request state. This is the only re-evaluation after that window.
+            // Pinned by assertion 32; deleting it turns a 404 into an applied update.
             if (isDenied(filter, found))
                 return 404;
             const record = found;
@@ -339,6 +447,9 @@ export default class OrmRequest extends Request {
             // reports success for a request that changed nothing.
             if (!record)
                 return 404;
+            // Re-evaluated after the before-hook loop, exactly as in updateHandler --
+            // GATE 1 decided before the hooks ran. Pinned by assertion 33; deleting it
+            // turns a 404 into a destroyed record.
             if (isDenied(filter, record))
                 return 404;
             store.remove(model, getId(params), { _skipAutoPersist: true });
@@ -366,9 +477,36 @@ export default class OrmRequest extends Request {
             };
         }
     }
-    // Wraps a handler with before/after hook execution
+    // Wraps a handler with before/after hook execution.
+    //
+    // ===========================================================================
+    // TWO AUTHORIZATION GATES, AND EVERY EXECUTOR SITS BEHIND ONE OF THEM (#190)
+    //
+    // The defect this function was fixed for is NOT "a delete persists past a
+    // 404". It is that _withHooks has SEVERAL executors downstream of the
+    // handler, and originally the handler's response gated none of them. Three
+    // exist today:
+    //
+    //   1. sqlDb.persist          -- issues real SQL against the backing store
+    //   2. the after-hook pipeline -- the PUBLISHED consumer extension point;
+    //                                a cascade delete, a webhook, a search-index
+    //                                purge. `context.recordId` and
+    //                                `context.oldState` are populated for it.
+    //   3. Orm.db.save()          -- a full serialize-and-write of the store
+    //
+    // Gating them one at a time is how this keeps regressing, so the rule is:
+    // compute denial ONCE at each point where it becomes knowable, and keep every
+    // executor downstream of a gate. If you add a fourth executor to this
+    // function, it goes below GATE 2 or it is a security bug.
+    //
+    // GATE 1 (pre-handler) is required because before-hooks and `context.oldState`
+    // run/are built BEFORE the handler can consult the filter. Without it a denied
+    // DELETE still handed the hidden record's full contents to consumer code.
+    // GATE 2 (post-handler) covers everything the handler's status can reach.
+    // ===========================================================================
     _withHooks(operation, handler) {
         return async (request, state) => {
+            const { filter } = (state || {});
             // Build context object for hooks
             const context = {
                 model: this.model,
@@ -382,6 +520,26 @@ export default class OrmRequest extends Request {
             // Capture old state for operations that modify data
             if (operation === 'update' || operation === 'delete') {
                 const existingRecord = await store.find(this.model, getId(request.params));
+                // GATE 1 -- pre-handler. This record fetch already happened for
+                // oldState, so the check is free.
+                //
+                // Returning here rather than letting updateHandler/deleteHandler
+                // produce the same 404 is the point: everything between here and there
+                // is an executor the caller is not authorized to reach.
+                //   - context.oldState is a deep copy of the HIDDEN RECORD'S CONTENTS.
+                //     Building it and handing it to a before-hook discloses exactly what
+                //     the filter exists to hide.
+                //   - context.recordId is populated for delete BEFORE the handler runs,
+                //     which is the same shape as the sqlDb landmine one layer up:
+                //     `afterHook('delete', ctx => cascadeDelete(ctx.recordId))` destroys
+                //     children behind a correct 404.
+                //   - a before-hook may return a value and short-circuit, which would
+                //     otherwise return a response without the filter ever executing.
+                //
+                // 404, not 403, for the same reason as getSingleHandler: the status for
+                // "exists but filtered out" must equal "does not exist".
+                if (existingRecord && isDenied(filter, existingRecord))
+                    return 404;
                 if (existingRecord) {
                     // Deep copy the record's data to preserve old state
                     context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
@@ -404,19 +562,25 @@ export default class OrmRequest extends Request {
             if (operation === 'update' && response?.data) {
                 context.record = store.get(this.model, getId(request.params));
             }
-            // Persist to SQL database for all write operations (create/update/delete)
+            // GATE 2 -- post-handler. A denied or failed handler returns a bare status
+            // integer, and no executor below may run for one.
+            //
+            // `>= 400` deliberately covers every failure status, not just the
+            // authorization ones: a 400 (POST with no `type`) and a 409 (duplicate id)
+            // are equally requests in which nothing happened, and a persist or a
+            // cascade hook for one of them is just as wrong.
+            const denied = Number.isInteger(response) && response >= 400;
+            // EXECUTOR 1 -- SQL persistence, for all write operations.
             //
-            // A denied or failed handler returns a bare status integer and MUST NOT
-            // reach persist. `response` is passed to sqlDb.persist below, but it is
-            // dropped at the driver boundary: _persistDelete(modelName, context) never
-            // receives it and guards only on context.recordId -- which _withHooks set
-            // above, BEFORE the handler ran. Without this gate a correct 404 still
-            // issues DELETE FROM ... WHERE id = ? on every SQL backend.
+            // `response` is passed to sqlDb.persist below, but it is dropped at the
+            // driver boundary: _persistDelete(modelName, context) never receives it
+            // and guards only on context.recordId -- which _withHooks set above,
+            // BEFORE the handler ran. Without this gate a correct 404 still issues
+            // DELETE FROM ... WHERE id = ? on every SQL backend.
             //
             // No file-backed test can observe that, because Orm.instance.sqlDb is
             // null in file/directory mode. See the stubbed-sqlDb assertions in
             // test/unit/access-filter-enforcement-test.ts.
-            const denied = Number.isInteger(response) && response >= 400;
             const sqlDb = Orm.instance.sqlDb;
             if (sqlDb && WRITE_OPERATIONS.has(operation) && !denied) {
                 await sqlDb.persist(operation, this.model, context, response);
@@ -439,12 +603,29 @@ export default class OrmRequest extends Request {
                 // For delete, the record may no longer exist, but we have oldState
                 context.recordId = getId(request.params);
             }
-            // Run after hooks sequentially
-            for (const hook of getAfterHooks(operation, this.model)) {
-                await hook(context);
+            // EXECUTOR 2 -- the after-hook pipeline. This is the published consumer
+            // extension point (`afterHook` is exported from @stonyx/orm and from
+            // ./hooks), so it is the executor with the widest possible blast radius:
+            // a cascade delete, a webhook, a token revocation, a search-index purge.
+            //
+            // BEHAVIOUR CHANGE (#190): after-hooks no longer fire for a request that
+            // failed. Previously `afterHook('delete', ...)` ran with a populated
+            // context.recordId on a 404, so a consumer cascade destroyed children for
+            // a request that deleted nothing. Firing a hook named "after<operation>"
+            // for an operation that did not occur is a booby trap, and the denied case
+            // is unreachable-before-#190 while the missing case is inherited debt --
+            // both are closed by the same gate. `context.response` therefore only ever
+            // carries a success status into a hook.
+            if (!denied) {
+                for (const hook of getAfterHooks(operation, this.model)) {
+                    await hook(context);
+                }
             }
-            // Auto-save DB after write operations when configured
-            if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation)) {
+            // EXECUTOR 3 -- file/directory autosave. Ungated this let an
+            // unauthenticated caller force a full serialize-and-write of the entire
+            // store on every DELETE of any id, with no record touched: amplification
+            // rather than corruption, but the same root cause and the same fix.
+            if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation) && !denied) {
                 await Orm.db.save();
             }
             return response;
@@ -523,35 +704,59 @@ export default class OrmRequest extends Request {
                 };
             };
         }
-        // Catch-all for invalid relationship names on related resource route
-        routes[`/:id/:relationship`] = async (request, { filter } = {}) => {
-            const record = await store.find(model, getId(request.params));
-            if (!record)
-                return 404;
-            if (isDenied(filter, record))
-                return 404;
-            // If we reach here, relationship doesn't exist (valid ones were registered above)
-            return 404;
-        };
-        // Catch-all for invalid relationship names on relationship linkage route
-        routes[`/:id/relationships/:relationship`] = async (request, { filter } = {}) => {
-            const record = await store.find(model, getId(request.params));
-            if (!record)
-                return 404;
-            if (isDenied(filter, record))
-                return 404;
-            return 404;
-        };
+        // Catch-alls for invalid relationship names. Every valid relationship was
+        // registered above, so reaching either of these means the relationship does
+        // not exist and the answer is 404 regardless of the record.
+        //
+        // These deliberately carry NO access check and no store lookup. An earlier
+        // revision of #190 added `if (isDenied(filter, record)) return 404` here for
+        // symmetry with the seven real surfaces, but both branches returned 404, so
+        // the guard was unobservable by construction -- a mutation deleting it
+        // survived the entire suite because no test that could distinguish it can
+        // exist. Unkillable code in an authorization diff reads as coverage and is
+        // not, so it is gone; skipping the lookup also removes the timing difference
+        // between an existing and a missing parent.
+        //
+        // IF THIS ROUTE EVER RETURNS ANYTHING OTHER THAN A CONSTANT 404, it becomes
+        // the eighth surface and must filter the parent first, exactly like
+        // `/:id/{relationship}` above.
+        routes[`/:id/:relationship`] = async () => 404;
+        routes[`/:id/relationships/:relationship`] = async () => 404;
         return routes;
     }
     auth(request, state) {
-        const access = this.access(request);
+        // A consumer `access()` that throws is a DENIAL, matching `isDenied` one
+        // layer down. Unguarded it propagates to express's default handler, which
+        // answers 500 -- and the documented sample itself can throw
+        // (`request.originalUrl.split(...)` when originalUrl is absent), so the
+        // failure mode is reachable by following the docs.
+        let access;
+        try {
+            access = this.access(request);
+        }
+        catch {
+            return 403; // Forbidden
+        }
         if (!access)
             return 403;
-        if (Array.isArray(access) && !access.includes(methodAccessMap[request.method]))
-            return 403;
-        if (typeof access === 'function')
+        if (typeof access === 'function') {
             state.filter = access;
+            return undefined;
+        }
+        if (access === true)
+            return undefined;
+        // `AccessMethod` declares `string` legal and it fell through every branch
+        // above, returning undefined -- i.e. FULL CRUD, no filter. `return 'read'`
+        // is the natural reading of a type that lists `string` first, and it
+        // granted DELETE. A bare string is one permission, not a grant of all four.
+        const permitted = typeof access === 'string' ? [access] : access;
+        // Anything that is not a permission array by this point -- an object, a
+        // number, a Symbol -- is a consumer mistake, and the only safe reading of a
+        // shape the contract does not define is a denial. Fail CLOSED.
+        if (!Array.isArray(permitted))
+            return 403;
+        if (!permitted.includes(methodAccessMap[request.method]))
+            return 403;
         return undefined;
     }
 }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.48",
+  "version": "0.3.2-alpha.49",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,10 +61,10 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.81",
+    "@stonyx/cron": "0.2.1-beta.84",
     "@stonyx/events": "0.1.1-beta.52",
     "@stonyx/utils": "0.2.3-beta.26",
-    "stonyx": "0.2.3-beta.76"
+    "stonyx": "0.2.3-beta.77"
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0",
@@ -91,7 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.80",
+    "@stonyx/rest-server": "0.2.1-beta.83",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",

package/src/orm-request.ts

@@ -92,6 +92,30 @@ function getId(params: { id?: string; [key: string]: unknown }): string | number
   return parseInt(id);
 }
 
+/**
+ * Normalise a caller-supplied BODY id to the key the store will hold it under.
+ *
+ * `getId()` above is params-shaped: it takes `{ id?: string }` off the URL,
+ * where the value is always a string and a falsy one means "no id". A JSON body
+ * id is neither -- it can arrive as a number, and `0` is a legitimate id that
+ * `getId()` would flatten to `''`.
+ *
+ * WHY THIS EXISTS AT ALL. createHandler used to look the collision up with the
+ * RAW body value while every other surface normalised through `getId()`. The
+ * store is a Map keyed by the coerced value, so `store.find(model, '21')` misses
+ * the entry held under `21` and the duplicate check is skipped by typing the id
+ * as a string. On `dev` that silently overwrote the colliding record and
+ * answered 200; combined with the denied-create rollback added for #190 it
+ * became an unauthenticated DELETE of any id. Normalising here is half of that
+ * fix -- see the rollback in createHandler for the other half.
+ */
+function normalizeBodyId(id: string | number): string | number {
+  if (typeof id === 'number') return id;
+  if (typeof id !== 'string' || id.trim() === '') return id;
+
+  return isNaN(id as unknown as number) ? id : parseInt(id, 10);
+}
+
 function buildResponse(
   data: unknown,
   includeParam: string | undefined,
@@ -266,7 +290,16 @@ function createFilterPredicate(filters: Filter[]): ((record: { [key: string]: un
 function isDenied(filter: unknown, record: unknown): boolean {
   if (typeof filter !== 'function') return false;
 
-  return !(filter as (record: unknown) => boolean)(record);
+  // A predicate that throws is treated as a denial. Unguarded, a throw escapes
+  // to express's default handler, which answers 500 (with a stack trace outside
+  // NODE_ENV=production) while a missing id still answers 404 -- so a
+  // record-dependent throw re-separates "hidden" from "does not exist" and
+  // hands back the oracle this whole change exists to close.
+  try {
+    return !(filter as (record: unknown) => boolean)(record);
+  } catch {
+    return true;
+  }
 }
 
 export default class OrmRequest extends Request {
@@ -336,8 +369,47 @@ export default class OrmRequest extends Request {
       const fieldsMap = parseFields(query);
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
-      // Check for duplicate ID
-      if (id !== undefined && await store.find(model, id)) return 409; // Conflict
+      // GATE 0 -- the POST existence oracle.
+      //
+      // The duplicate check runs before the filter and `store.find` sees hidden
+      // records, so POST leaks existence through its STATUS. A previous revision
+      // filtered the collision status (403 when the colliding record is denied,
+      // 409 when it is visible) and that is NOT sufficient, because the status
+      // of a create is a third outcome. With a payload the caller is permitted
+      // to create -- the normative case for a per-tenant filter, and the case an
+      // attacker picks -- all three are distinguishable in ONE request per id:
+      //
+      //   POST /animals {id:22,   owner:'gina'} -> 403   a HIDDEN record has this id
+      //   POST /animals {id:9500, owner:'gina'} -> 200   this id is FREE
+      //   POST /animals {id:8,    owner:'gina'} -> 409   a VISIBLE record has this id
+      //
+      // Filtering only the collision status narrows that to callers who cannot
+      // create a record they are allowed to see. It does not close it.
+      //
+      // It cannot be closed while a caller both chooses the id and learns
+      // whether the create succeeded: a successful create must answer
+      // differently from a refused one. So when a per-record filter is in force
+      // the caller does not get to choose the id at all. The refusal is
+      // UNCONDITIONAL and happens BEFORE any store lookup, so no status, and no
+      // lookup cost, can depend on whether that id exists. 403 -- the same
+      // status as a denied create -- so the two cannot be separated either.
+      //
+      // Scoped to function-style `access` because that is exactly the population
+      // the oracle exists for: with no per-record filter there are no hidden
+      // records, and 409 discloses nothing GET /:id does not already.
+      //
+      // RESIDUAL, stated rather than implied: a caller can still learn that a
+      // collection HAS a per-record filter (403 rather than 409/200 for an
+      // id-bearing POST). That discloses a configuration fact, not a record.
+      // See README `### Known limitations`.
+      if (id !== undefined) {
+        if (typeof filter === 'function') return 403; // Forbidden
+
+        // `normalizeBodyId`, not the raw value: a string-typed id misses the
+        // store's numeric key, which skipped this check entirely.
+        const existing = await store.find(model, normalizeBodyId(id));
+        if (existing) return 409; // Conflict
+      }
 
       const { id: _ignoredId, ...sanitizedAttributes } = attributes || {};
 
@@ -352,10 +424,22 @@ export default class OrmRequest extends Request {
       }
 
       const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
+
+      // Slot count BEFORE the write. `createRecord` writes to the store before
+      // the predicate can run, and the rollback below must be able to prove the
+      // slot it removes is one THIS REQUEST created. Identity alone cannot
+      // prove it: when `assignRecordId` lands on an occupied id, `createRecord`
+      // mutates the existing OrmRecord IN PLACE, so `store.get(...) === record`
+      // is true for a record the request did not create. The map's size is the
+      // only O(1) signal that distinguishes an insert from an overwrite.
+      const slotsBefore = (store.get(model) as Map<string | number, unknown> | undefined)?.size ?? 0;
+
       const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
       const record = isOrmRecord(created) ? created : null;
       if (!record) return 500;
 
+      const createdNewSlot = ((store.get(model) as Map<string | number, unknown> | undefined)?.size ?? 0) > slotsBefore;
+
       // 403 here, NOT 404. The oracle argument does not apply to create: there
       // is no pre-existing record whose existence could leak, the caller
       // supplied the attributes, and 404 on a mounted collection route is
@@ -366,7 +450,27 @@ export default class OrmRequest extends Request {
       // the predicate can run, so returning 403 alone would leave the record
       // behind: a worse bug than the bypass being fixed.
       if (isDenied(filter, record)) {
-        store.remove(model, record.id as string | number, { _skipAutoPersist: true });
+        // ROLL BACK BY IDENTITY, NEVER BY ID. `store.remove(model, record.id)`
+        // on its own is a write primitive keyed by a value the caller may have
+        // supplied: with the raw-id collision bypass above, a denied
+        // `POST {"id":"21"}` answered 403 and DELETED hidden record 21 -- an
+        // unauthenticated deletion primitive across the whole id space, created
+        // by adding a rollback to a lookup that could be skipped.
+        //
+        // Both conditions are required and neither implies the other:
+        //   createdNewSlot -- the store grew, so this request inserted rather
+        //                     than overwrote. Guards `assignRecordId` picking an
+        //                     id that is already taken (it returns
+        //                     last-INSERTED + 1, not max + 1, so a store whose
+        //                     insertion order is not ascending collides) -- see
+        //                     abofs/stonyx-orm#203.
+        //   identity       -- the slot still holds the object we just created,
+        //                     so nothing between createRecord and here replaced
+        //                     it.
+        if (createdNewSlot && store.get(model, record.id as string | number) === record) {
+          store.remove(model, record.id as string | number, { _skipAutoPersist: true });
+        }
+
         return 403;
       }
 
@@ -379,6 +483,13 @@ export default class OrmRequest extends Request {
       // Checked BEFORE any attribute is applied. 404 rather than 403 for the
       // same reason as GET /:id -- 403 would disclose both that the record
       // exists and that this caller specifically is excluded.
+      //
+      // NOT redundant behind GATE 1, and not defence in depth either: GATE 1's
+      // verdict is computed BEFORE the before-hook loop runs, and a before-hook
+      // is a published extension point that can change the answer -- by
+      // mutating the record, or against a predicate that closes over
+      // per-request state. This is the only re-evaluation after that window.
+      // Pinned by assertion 32; deleting it turns a 404 into an applied update.
       if (isDenied(filter, found)) return 404;
       const record = found;
       const { attributes, relationships: rels } = (body?.data || {}) as {
@@ -426,6 +537,9 @@ export default class OrmRequest extends Request {
       // Returning 204 for a denied delete was rejected instead: it falsely
       // reports success for a request that changed nothing.
       if (!record) return 404;
+      // Re-evaluated after the before-hook loop, exactly as in updateHandler --
+      // GATE 1 decided before the hooks ran. Pinned by assertion 33; deleting it
+      // turns a 404 into a destroyed record.
       if (isDenied(filter, record)) return 404;
 
       store.remove(model, getId(params), { _skipAutoPersist: true });
@@ -457,9 +571,37 @@ export default class OrmRequest extends Request {
     }
   }
 
-  // Wraps a handler with before/after hook execution
+  // Wraps a handler with before/after hook execution.
+  //
+  // ===========================================================================
+  // TWO AUTHORIZATION GATES, AND EVERY EXECUTOR SITS BEHIND ONE OF THEM (#190)
+  //
+  // The defect this function was fixed for is NOT "a delete persists past a
+  // 404". It is that _withHooks has SEVERAL executors downstream of the
+  // handler, and originally the handler's response gated none of them. Three
+  // exist today:
+  //
+  //   1. sqlDb.persist          -- issues real SQL against the backing store
+  //   2. the after-hook pipeline -- the PUBLISHED consumer extension point;
+  //                                a cascade delete, a webhook, a search-index
+  //                                purge. `context.recordId` and
+  //                                `context.oldState` are populated for it.
+  //   3. Orm.db.save()          -- a full serialize-and-write of the store
+  //
+  // Gating them one at a time is how this keeps regressing, so the rule is:
+  // compute denial ONCE at each point where it becomes knowable, and keep every
+  // executor downstream of a gate. If you add a fourth executor to this
+  // function, it goes below GATE 2 or it is a security bug.
+  //
+  // GATE 1 (pre-handler) is required because before-hooks and `context.oldState`
+  // run/are built BEFORE the handler can consult the filter. Without it a denied
+  // DELETE still handed the hidden record's full contents to consumer code.
+  // GATE 2 (post-handler) covers everything the handler's status can reach.
+  // ===========================================================================
   private _withHooks(operation: string, handler: HandlerFn): HandlerFn {
     return async (request: OrmRequest$, state: { [key: string]: unknown }) => {
+      const { filter } = (state || {}) as { filter?: unknown };
+
       // Build context object for hooks
       const context: HookContext = {
         model: this.model,
@@ -474,6 +616,27 @@ export default class OrmRequest extends Request {
       // Capture old state for operations that modify data
       if (operation === 'update' || operation === 'delete') {
         const existingRecord = await store.find(this.model, getId(request.params)) as OrmRecord | undefined;
+
+        // GATE 1 -- pre-handler. This record fetch already happened for
+        // oldState, so the check is free.
+        //
+        // Returning here rather than letting updateHandler/deleteHandler
+        // produce the same 404 is the point: everything between here and there
+        // is an executor the caller is not authorized to reach.
+        //   - context.oldState is a deep copy of the HIDDEN RECORD'S CONTENTS.
+        //     Building it and handing it to a before-hook discloses exactly what
+        //     the filter exists to hide.
+        //   - context.recordId is populated for delete BEFORE the handler runs,
+        //     which is the same shape as the sqlDb landmine one layer up:
+        //     `afterHook('delete', ctx => cascadeDelete(ctx.recordId))` destroys
+        //     children behind a correct 404.
+        //   - a before-hook may return a value and short-circuit, which would
+        //     otherwise return a response without the filter ever executing.
+        //
+        // 404, not 403, for the same reason as getSingleHandler: the status for
+        // "exists but filtered out" must equal "does not exist".
+        if (existingRecord && isDenied(filter, existingRecord)) return 404;
+
         if (existingRecord) {
           // Deep copy the record's data to preserve old state
           context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
@@ -500,19 +663,26 @@ export default class OrmRequest extends Request {
         context.record = store.get(this.model, getId(request.params));
       }
 
-      // Persist to SQL database for all write operations (create/update/delete)
+      // GATE 2 -- post-handler. A denied or failed handler returns a bare status
+      // integer, and no executor below may run for one.
+      //
+      // `>= 400` deliberately covers every failure status, not just the
+      // authorization ones: a 400 (POST with no `type`) and a 409 (duplicate id)
+      // are equally requests in which nothing happened, and a persist or a
+      // cascade hook for one of them is just as wrong.
+      const denied = Number.isInteger(response) && (response as number) >= 400;
+
+      // EXECUTOR 1 -- SQL persistence, for all write operations.
       //
-      // A denied or failed handler returns a bare status integer and MUST NOT
-      // reach persist. `response` is passed to sqlDb.persist below, but it is
-      // dropped at the driver boundary: _persistDelete(modelName, context) never
-      // receives it and guards only on context.recordId -- which _withHooks set
-      // above, BEFORE the handler ran. Without this gate a correct 404 still
-      // issues DELETE FROM ... WHERE id = ? on every SQL backend.
+      // `response` is passed to sqlDb.persist below, but it is dropped at the
+      // driver boundary: _persistDelete(modelName, context) never receives it
+      // and guards only on context.recordId -- which _withHooks set above,
+      // BEFORE the handler ran. Without this gate a correct 404 still issues
+      // DELETE FROM ... WHERE id = ? on every SQL backend.
       //
       // No file-backed test can observe that, because Orm.instance.sqlDb is
       // null in file/directory mode. See the stubbed-sqlDb assertions in
       // test/unit/access-filter-enforcement-test.ts.
-      const denied = Number.isInteger(response) && (response as number) >= 400;
       const sqlDb = Orm.instance.sqlDb;
       if (sqlDb && WRITE_OPERATIONS.has(operation) && !denied) {
         await sqlDb.persist(operation, this.model, context, response);
@@ -535,13 +705,30 @@ export default class OrmRequest extends Request {
         context.recordId = getId(request.params);
       }
 
-      // Run after hooks sequentially
-      for (const hook of getAfterHooks(operation, this.model)) {
-        await hook(context);
+      // EXECUTOR 2 -- the after-hook pipeline. This is the published consumer
+      // extension point (`afterHook` is exported from @stonyx/orm and from
+      // ./hooks), so it is the executor with the widest possible blast radius:
+      // a cascade delete, a webhook, a token revocation, a search-index purge.
+      //
+      // BEHAVIOUR CHANGE (#190): after-hooks no longer fire for a request that
+      // failed. Previously `afterHook('delete', ...)` ran with a populated
+      // context.recordId on a 404, so a consumer cascade destroyed children for
+      // a request that deleted nothing. Firing a hook named "after<operation>"
+      // for an operation that did not occur is a booby trap, and the denied case
+      // is unreachable-before-#190 while the missing case is inherited debt --
+      // both are closed by the same gate. `context.response` therefore only ever
+      // carries a success status into a hook.
+      if (!denied) {
+        for (const hook of getAfterHooks(operation, this.model)) {
+          await hook(context);
+        }
       }
 
-      // Auto-save DB after write operations when configured
-      if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation)) {
+      // EXECUTOR 3 -- file/directory autosave. Ungated this let an
+      // unauthenticated caller force a full serialize-and-write of the entire
+      // store on every DELETE of any id, with no record touched: amplification
+      // rather than corruption, but the same root cause and the same fix.
+      if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation) && !denied) {
         await (Orm.db as { save(): Promise<void> }).save();
       }
 
@@ -629,34 +816,60 @@ export default class OrmRequest extends Request {
       };
     }
 
-    // Catch-all for invalid relationship names on related resource route
-    routes[`/:id/:relationship`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
-      const record = await store.find(model, getId(request.params));
-      if (!record) return 404;
-      if (isDenied(filter, record)) return 404;
-
-      // If we reach here, relationship doesn't exist (valid ones were registered above)
-      return 404;
-    };
-
-    // Catch-all for invalid relationship names on relationship linkage route
-    routes[`/:id/relationships/:relationship`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
-      const record = await store.find(model, getId(request.params));
-      if (!record) return 404;
-      if (isDenied(filter, record)) return 404;
-
-      return 404;
-    };
+    // Catch-alls for invalid relationship names. Every valid relationship was
+    // registered above, so reaching either of these means the relationship does
+    // not exist and the answer is 404 regardless of the record.
+    //
+    // These deliberately carry NO access check and no store lookup. An earlier
+    // revision of #190 added `if (isDenied(filter, record)) return 404` here for
+    // symmetry with the seven real surfaces, but both branches returned 404, so
+    // the guard was unobservable by construction -- a mutation deleting it
+    // survived the entire suite because no test that could distinguish it can
+    // exist. Unkillable code in an authorization diff reads as coverage and is
+    // not, so it is gone; skipping the lookup also removes the timing difference
+    // between an existing and a missing parent.
+    //
+    // IF THIS ROUTE EVER RETURNS ANYTHING OTHER THAN A CONSTANT 404, it becomes
+    // the eighth surface and must filter the parent first, exactly like
+    // `/:id/{relationship}` above.
+    routes[`/:id/:relationship`] = async () => 404;
+    routes[`/:id/relationships/:relationship`] = async () => 404;
 
     return routes;
   }
 
   auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
-    const access = this.access(request);
+    // A consumer `access()` that throws is a DENIAL, matching `isDenied` one
+    // layer down. Unguarded it propagates to express's default handler, which
+    // answers 500 -- and the documented sample itself can throw
+    // (`request.originalUrl.split(...)` when originalUrl is absent), so the
+    // failure mode is reachable by following the docs.
+    let access: AccessMethod;
+    try {
+      access = this.access(request);
+    } catch {
+      return 403; // Forbidden
+    }
 
     if (!access) return 403;
-    if (Array.isArray(access) && !access.includes(methodAccessMap[request.method])) return 403;
-    if (typeof access === 'function') state.filter = access;
+    if (typeof access === 'function') {
+      state.filter = access;
+      return undefined;
+    }
+    if (access === true) return undefined;
+
+    // `AccessMethod` declares `string` legal and it fell through every branch
+    // above, returning undefined -- i.e. FULL CRUD, no filter. `return 'read'`
+    // is the natural reading of a type that lists `string` first, and it
+    // granted DELETE. A bare string is one permission, not a grant of all four.
+    const permitted = typeof access === 'string' ? [access] : access;
+
+    // Anything that is not a permission array by this point -- an object, a
+    // number, a Symbol -- is a consumer mistake, and the only safe reading of a
+    // shape the contract does not define is a denial. Fail CLOSED.
+    if (!Array.isArray(permitted)) return 403;
+    if (!permitted.includes(methodAccessMap[request.method])) return 403;
+
     return undefined;
   }
 }