@stonyx/orm 0.3.2-alpha.73 → 0.3.2-alpha.75

package/README.md

@@ -452,7 +452,11 @@ 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';
+    // `record.id !== 18` hides one animal whose OWNER is permitted. It is the
+    // fixture that makes the `hasMany` half of the relationship-route rules
+    // observable: gina is served, animal 18 is not, and every surface that
+    // names gina's pets has to drop it.
+    if (model === 'animal') return record => record.owner?.id !== 'restricted' && record.id !== 18;
 
     // Allows full access to all calls that don't match any of the above conditions
     return ['read', 'create', 'update', 'delete'];
@@ -921,15 +925,67 @@ per-record filter. An input you cannot identify must **deny**.
   operation and which record the request addresses. The five variants above are
   the five ways that 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. 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.
+- **The two relationship route families now resolve the *related* model's own
+  access class — `GET /:models/:id/{relationship}` and
+  `GET /:models/:id/relationships/{relationship}`**
+  ([#232](https://github.com/abofs/stonyx-orm/issues/232)). This is
+  **membership**: the related resource is the route's *primary* data, so the
+  filter decides whether it is served at all, not merely which ids a document
+  may name. A denied `hasMany` member is **dropped from the array** — the result
+  is shaped exactly like a genuinely empty relationship, `links` intact, no
+  `errors` member, same status. A denied `belongsTo` target answers **404**, the
+  same status the route already answered for a denied parent and for a parent
+  that does not exist. The `/relationships/` family built its `{type, id}` by
+  hand rather than through `toJSON()`, which is why the linkage filter shipped in
+  [#234](https://github.com/abofs/stonyx-orm/issues/234) did not reach it.
+
+  Before this, both families served a record hidden on every one of its own
+  surfaces, in full, from another model's route, at **zero query parameters**.
+  The severe case is a model **claimed by no access class**: `getAccess()`
+  returns `undefined`, no route is mounted for it at all, and it was still
+  readable as a related resource — a collection the consumer deliberately never
+  exposed.
+
+  **Residual on the `belongsTo` shape, stated rather than left to be found:** a
+  denied target answers 404 while a genuinely *absent* one answers 200 with
+  `data: null`, so those two cases are distinguishable. That asymmetry is
+  inherited — a denied *parent* has always answered 404 while an existing parent
+  with an empty relationship answers 200 — and changing it is a change to this
+  module's whole spelling of denial, not to these two routes.
+
+  **Per-record denies for a related resource are not expressible.** A predicate resolved for a
+  related resource on these routes receives `recordId: null` and a `request`
+  whose `params` name a record of a **different model**. So the inputs it has
+  are the model name, the operation and the request — and **a rule that needs to
+  know *which* related record it is being asked about cannot be written**.
+  Model-level denies (`return false` for a model) work. Request-level denies (a
+  rule reading a header, a tenant, the method) work. The per-record **filter**
+  shape works too — `access()` may return a function, and that function receives
+  the whole record, id included. What does not work is branching on the record's
+  identity *before* returning, because `access()` is not told it.
+
+  This is not an oversight and it is not closed here. The verdict is resolved
+  **once per type**, cached, before any record has been examined — a `hasMany`
+  related-resource route returns many records of one type, so seeding `recordId`
+  from a record would let the first one decide the context for all of them. The
+  rule the framework holds to is: **`recordId` may name a record only where the
+  route addresses exactly one record of the model being asked about.** That is
+  true for `GET /owners/{id}`, false for linkage, and false for a `hasMany`
+  related-resource route.
+
+- **`?include=` records are still not filtered — the relationship routes now
+  are.** *Re-specified by [#232](https://github.com/abofs/stonyx-orm/issues/232);
+  the sentence this replaces said all three surfaces were unfiltered, and two of
+  them no longer are.* `GET /animals/1/owner` and
+  `GET /animals/1/relationships/owner` resolve the related model's own access
+  class (see the bullet above). **`?include=owner` still does not**: it
+  serializes the related record without resolving that class, so a filter on
+  `/owners` does not hide an owner reached through `?include=` on `/animals`.
+  Tracked as [#233](https://github.com/abofs/stonyx-orm/issues/233), the
+  remaining child of [#196](https://github.com/abofs/stonyx-orm/issues/196).
+  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
@@ -988,10 +1044,14 @@ per-record filter. An input you cannot identify must **deny**.
     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).
+  - ~~**`GET /:models/:id/relationships/{relationship}`**~~ — **covered as of
+    [#232](https://github.com/abofs/stonyx-orm/issues/232)**, together with
+    `GET /:models/:id/{relationship}`. Left in place rather than deleted because
+    this list is what a reader consults to find out what is *not* covered, and a
+    silently vanishing entry reads as an entry that was never there. Its
+    *primary data* is linkage, so filtering it was a **membership** decision —
+    which is why it belonged to #232 and not to
+    [#234](https://github.com/abofs/stonyx-orm/issues/234).
 - **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

package/dist/orm-request.js

@@ -1245,21 +1245,77 @@ export default class OrmRequest extends Request {
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
                 const baseUrl = getBaseUrl(request);
-                // LINKAGE ONLY. This filter decides which ids the emitted documents may
-                // NAME in their own `relationships.*.data`; it does NOT decide whether
-                // the related records themselves are served -- that is the parent-only
-                // filtering this route has done since #190, and widening it to the
-                // related record is abofs/stonyx-orm#196.
+                // ONE FILTER, TWO JOBS, AND abofs/stonyx-orm#232 IS THE SECOND ONE.
+                //
+                // As LINKAGE (#234) it decides which ids the emitted documents may NAME
+                // in their own `relationships.*.data`. As MEMBERSHIP (this issue) it
+                // decides whether the related record is served here AT ALL -- the
+                // related resource is PRIMARY data on this route, so there is no
+                // linkage-consistency question to answer separately.
+                //
+                // Until #232 this route filtered only the PARENT, so a record its own
+                // model's predicate hides was served in full from another model's
+                // route, at ZERO query parameters. Measured on dev @ 8dda5d6:
+                //
+                //     GET /owners/angela          -> 404
+                //     GET /animals/1/owner        -> 200, owner:angela, full attributes
+                //     GET /traits/2/tag           -> 200, a model NO access class
+                //                                    claims, on a collection that has
+                //                                    no mounted route at all
+                //
+                // ARGUMENT ONE IS THE LIVE REQUEST, NOT A DERIVED ONE. A fabricated
+                // request addressing the RELATED resource was the original design and
+                // it is dropped: #241 removed the shipped fixture's read of argument
+                // one, so a fabricated value changes nothing it could observe, and
+                // test/unit/linkage-verdict-test.ts:484 pins the predicate as receiving
+                // the live request BY IDENTITY. `createLinkageFilter` is also a
+                // published public export (src/index.ts) whose resolution granularity
+                // is per TYPE; supplying a per-RECORD request would mean widening it,
+                // which takes a consumer `access()` from ~2 calls to ~7 on a plain
+                // `GET /animals`. That is a separate, consumer-visible story.
+                //
+                // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
+                // `recordId` is `null` here and the request names a record of a
+                // DIFFERENT model, so a consumer predicate can express a model-level or
+                // a request-level deny for a related resource, but NOT a per-record
+                // one. README.md and docs/usage-patterns.md say so; a ledger assertion
+                // in test/unit/relationship-route-access-test.ts keeps them saying it.
                 const linkage = createLinkageFilter(request);
+                // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED. `isLinkable` is
+                // keyed on the model name; without one there is no predicate to ask,
+                // and an unidentifiable input must never be the permissive path.
+                const isLinkable = (r) => {
+                    const type = r.__model?.__name;
+                    return typeof type === 'string' && type !== '' && linkage(type, r);
+                };
                 let data;
                 if (info.isArray) {
-                    // hasMany - return array
+                    // hasMany - return array, MINUS the members this caller may not see.
+                    // Dropped, never errored: the result is byte-identical to a genuinely
+                    // empty relationship, so this route is not an existence oracle.
                     const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-                    data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
+                    data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
                 }
                 else {
-                    // belongsTo - return single or null
-                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+                    // belongsTo - return single or null. A DENIED target is 404, the same
+                    // status this route already returns for a denied PARENT and for a
+                    // parent that does not exist, and the same status the related
+                    // record's own route answers.
+                    //
+                    // KNOWN RESIDUAL, stated here because it is the one place a reader
+                    // will look: 404 is distinguishable from a relationship that is
+                    // genuinely EMPTY, which answers 200 with `data: null`. So a caller
+                    // can tell "there is a target you may not see" from "there is no
+                    // target". That asymmetry is inherited -- a denied PARENT has always
+                    // answered 404 while an existing parent with an empty relationship
+                    // answers 200 -- and closing it is a change to the module's whole
+                    // denial spelling, not to this route.
+                    if (!isOrmRecord(relatedData))
+                        data = null;
+                    else if (!isLinkable(relatedData))
+                        return 404;
+                    else
+                        data = relatedData.toJSON?.({ baseUrl, linkage });
                 }
                 return {
                     links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
@@ -1275,17 +1331,35 @@ export default class OrmRequest extends Request {
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
                 const baseUrl = getBaseUrl(request);
+                // THE ONLY ONE OF THE FOUR READ SURFACES THAT DOES NOT GO THROUGH
+                // `toJSON()`. It builds `{ type, id }` BY HAND, which is why #234's
+                // linkage filter never reached it and why this half belongs to
+                // abofs/stonyx-orm#232 rather than to #234: on this route the linkage
+                // IS the primary data of an opt-in request, so filtering it changes the
+                // route's MEMBERSHIP semantics, not the ids named inside somebody
+                // else's document.
+                //
+                // Same filter, same argument-one decision, same residual as
+                // `/:id/{relationship}` above -- read the block there.
+                const linkage = createLinkageFilter(request);
+                const isLinkable = (r) => {
+                    const type = r.__model?.__name;
+                    return typeof type === 'string' && type !== '' && linkage(type, r);
+                };
                 let data;
                 if (info.isArray) {
                     // hasMany - return array of linkage objects
                     const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
                     data = related
                         .filter((r) => Boolean(r.__model))
+                        .filter(isLinkable)
                         .map(r => ({ type: r.__model.__name, id: r.id }));
                 }
                 else {
                     // belongsTo - return single linkage or null
                     if (isOrmRecord(relatedData) && relatedData.__model) {
+                        if (!isLinkable(relatedData))
+                            return 404;
                         data = { type: relatedData.__model.__name, id: relatedData.id };
                     }
                     else {

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.73",
+  "version": "0.3.2-alpha.75",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/orm-request.ts

@@ -1364,21 +1364,76 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
-        // LINKAGE ONLY. This filter decides which ids the emitted documents may
-        // NAME in their own `relationships.*.data`; it does NOT decide whether
-        // the related records themselves are served -- that is the parent-only
-        // filtering this route has done since #190, and widening it to the
-        // related record is abofs/stonyx-orm#196.
+        // ONE FILTER, TWO JOBS, AND abofs/stonyx-orm#232 IS THE SECOND ONE.
+        //
+        // As LINKAGE (#234) it decides which ids the emitted documents may NAME
+        // in their own `relationships.*.data`. As MEMBERSHIP (this issue) it
+        // decides whether the related record is served here AT ALL -- the
+        // related resource is PRIMARY data on this route, so there is no
+        // linkage-consistency question to answer separately.
+        //
+        // Until #232 this route filtered only the PARENT, so a record its own
+        // model's predicate hides was served in full from another model's
+        // route, at ZERO query parameters. Measured on dev @ 8dda5d6:
+        //
+        //     GET /owners/angela          -> 404
+        //     GET /animals/1/owner        -> 200, owner:angela, full attributes
+        //     GET /traits/2/tag           -> 200, a model NO access class
+        //                                    claims, on a collection that has
+        //                                    no mounted route at all
+        //
+        // ARGUMENT ONE IS THE LIVE REQUEST, NOT A DERIVED ONE. A fabricated
+        // request addressing the RELATED resource was the original design and
+        // it is dropped: #241 removed the shipped fixture's read of argument
+        // one, so a fabricated value changes nothing it could observe, and
+        // test/unit/linkage-verdict-test.ts:484 pins the predicate as receiving
+        // the live request BY IDENTITY. `createLinkageFilter` is also a
+        // published public export (src/index.ts) whose resolution granularity
+        // is per TYPE; supplying a per-RECORD request would mean widening it,
+        // which takes a consumer `access()` from ~2 calls to ~7 on a plain
+        // `GET /animals`. That is a separate, consumer-visible story.
+        //
+        // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
+        // `recordId` is `null` here and the request names a record of a
+        // DIFFERENT model, so a consumer predicate can express a model-level or
+        // a request-level deny for a related resource, but NOT a per-record
+        // one. README.md and docs/usage-patterns.md say so; a ledger assertion
+        // in test/unit/relationship-route-access-test.ts keeps them saying it.
         const linkage = createLinkageFilter(request);
 
+        // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED. `isLinkable` is
+        // keyed on the model name; without one there is no predicate to ask,
+        // and an unidentifiable input must never be the permissive path.
+        const isLinkable = (r: OrmRecord) => {
+          const type = (r as { __model?: { __name?: string } }).__model?.__name;
+
+          return typeof type === 'string' && type !== '' && linkage(type, r);
+        };
+
         let data: unknown;
         if (info.isArray) {
-          // hasMany - return array
+          // hasMany - return array, MINUS the members this caller may not see.
+          // Dropped, never errored: the result is byte-identical to a genuinely
+          // empty relationship, so this route is not an existence oracle.
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
+          data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
-          // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+          // belongsTo - return single or null. A DENIED target is 404, the same
+          // status this route already returns for a denied PARENT and for a
+          // parent that does not exist, and the same status the related
+          // record's own route answers.
+          //
+          // KNOWN RESIDUAL, stated here because it is the one place a reader
+          // will look: 404 is distinguishable from a relationship that is
+          // genuinely EMPTY, which answers 200 with `data: null`. So a caller
+          // can tell "there is a target you may not see" from "there is no
+          // target". That asymmetry is inherited -- a denied PARENT has always
+          // answered 404 while an existing parent with an empty relationship
+          // answers 200 -- and closing it is a change to the module's whole
+          // denial spelling, not to this route.
+          if (!isOrmRecord(relatedData)) data = null;
+          else if (!isLinkable(relatedData)) return 404;
+          else data = relatedData.toJSON?.({ baseUrl, linkage });
         }
 
         return {
@@ -1396,16 +1451,36 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
+        // THE ONLY ONE OF THE FOUR READ SURFACES THAT DOES NOT GO THROUGH
+        // `toJSON()`. It builds `{ type, id }` BY HAND, which is why #234's
+        // linkage filter never reached it and why this half belongs to
+        // abofs/stonyx-orm#232 rather than to #234: on this route the linkage
+        // IS the primary data of an opt-in request, so filtering it changes the
+        // route's MEMBERSHIP semantics, not the ids named inside somebody
+        // else's document.
+        //
+        // Same filter, same argument-one decision, same residual as
+        // `/:id/{relationship}` above -- read the block there.
+        const linkage = createLinkageFilter(request);
+        const isLinkable = (r: OrmRecord) => {
+          const type = (r as { __model?: { __name?: string } }).__model?.__name;
+
+          return typeof type === 'string' && type !== '' && linkage(type, r);
+        };
+
         let data: unknown;
         if (info.isArray) {
           // hasMany - return array of linkage objects
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
           data = related
             .filter((r): r is OrmRecord & { __model: { __name: string } } => Boolean(r.__model))
+            .filter(isLinkable)
             .map(r => ({ type: r.__model.__name, id: r.id }));
         } else {
           // belongsTo - return single linkage or null
           if (isOrmRecord(relatedData) && relatedData.__model) {
+            if (!isLinkable(relatedData)) return 404;
+
             data = { type: relatedData.__model.__name, id: relatedData.id };
           } else {
             data = null;