@stonyx/orm 0.3.2-alpha.67 → 0.3.2-alpha.68

package/README.md

@@ -864,7 +864,50 @@ per-record filter. An input you cannot identify must **deny**.
   related record without resolving that model's own access class, so a filter on
   `/owners` does not hide an owner reached through `/animals`. Tracked as
   [#196](https://github.com/abofs/stonyx-orm/issues/196), which covers
-  `include=`, related-resource routes and relationship-linkage routes.
+  `include=`, related-resource routes and relationship-linkage routes. This is
+  **membership** — whether the related resource is served at all — and it is a
+  different question from which ids a document may *name*, immediately below.
+- **Relationship linkage is filtered on the four request-bound read surfaces,
+  and only there.** A document's `relationships.*.data` used to publish the id
+  of every related record unconditionally, so a record hidden on every one of
+  its own surfaces was still named inside another model's document — with no
+  `include=`, no relationship route and no query string
+  ([#234](https://github.com/abofs/stonyx-orm/issues/234)). It is now filtered
+  through the related model's own access class on `GET /:models`,
+  `GET /:models/:id` and both `GET /:models/:id/{relationship}` shapes. A
+  filtered-out relationship is **indistinguishable from a genuinely empty one** —
+  an emptied `hasMany` is `data: []` and an emptied `belongsTo` is `data: null`,
+  both **keeping their `links`**, which are built from the serialized record's
+  own id and never from the related one. Nothing errors and no status changes,
+  because throwing here would be an existence oracle *and* would throw out of
+  the enclosing `JSON.stringify`. **Not yet covered:** `included`
+  ([#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
+  resource appears there at all), the `POST`/`PATCH` response documents, and
+  `GET /:models/:id/relationships/{relationship}`, whose *primary data* is
+  linkage ([#196](https://github.com/abofs/stonyx-orm/issues/196)).
+- **A bare `toJSON()` still emits unfiltered linkage, and that is deliberate.**
+  `Record.toJSON()` **applies** a verdict; it never **resolves** one. It has no
+  request, and the documented `access()` contract permits a predicate to read
+  one — the sample in this README does, for its sub-path rule — so a filter
+  resolved inside `toJSON()` denies *permitted* records rather than hidden ones
+  (measured: 967 → 964, all three failures over-denials). `toJSON` is also the
+  `JSON.stringify` hook, so `JSON.stringify(record)`, `res.json(record)` and
+  `console.log(JSON.stringify(record))` reach it with a **string** in the
+  options slot and have no syntactic place to pass a verdict. The no-argument
+  call therefore returns the pre-#234 document unchanged. Fail-closed by default
+  is not available either: `Orm.instance.accessFunctions` is `{}` in any process
+  that never ran `setup-rest-server` — a CLI, an SQL-only process, a test — so
+  it would empty every relationship on every document in processes with no REST
+  surface to protect. Closing the residual means moving JSON:API serialization
+  **off** the `toJSON` name, tracked as
+  [#230](https://github.com/abofs/stonyx-orm/issues/230). If you hand a `Record`
+  to an untrusted consumer, serialize it through the REST layer or pass your own
+  resolved `linkage` option.
+- **`format()` and `serialize()` are deliberately not filtered, and must stay
+  that way.** `format()` is the **persistence** path — its output is what
+  `Orm.db.save()` writes to disk — so applying an access filter there would
+  write a truncated database. That is **data loss**, not disclosure prevention.
+  Neither method appears anywhere in the REST response path.
 - **A before-hook that returns a value short-circuits the request.** On write
   operations addressed to a record the filter is consulted first, so a hook
   cannot answer for a record the caller may not see. On reads it is not, so a

package/dist/access-verdict.d.ts

@@ -0,0 +1,57 @@
+import type { AccessMethod, AccessOperation } from './types/orm-types.js';
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+    granted: boolean;
+    filter?: (record: unknown) => boolean;
+}
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * the consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key, not the input.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export declare function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict;
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite: `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay distinct, where `` `${type}:${id}` ``
+ * would collapse them and let one model's verdict answer for another record.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export declare function createLinkageFilter(request: unknown): LinkageFilter;

package/dist/access-verdict.js

@@ -0,0 +1,185 @@
+/**
+ * The shared access-verdict primitive (abofs/stonyx-orm#234).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
+ * ---------------------------------------------------------------------------
+ * A consumer `access()` may return six differently-shaped things -- `false`, a
+ * bare permission string, a permission array, `true`, a per-record function, or
+ * something the contract does not define at all -- and the reading of each one
+ * is a security decision. `auth()` has held that reading inline since #190.
+ * Every surface that needs to ask "may this caller see model X's record?" needs
+ * the SAME reading, or the second copy becomes an unreviewed second
+ * authorization vocabulary that answers differently about the same value.
+ *
+ * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
+ * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
+ * rebase onto it rather than re-deriving it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
+ * ---------------------------------------------------------------------------
+ * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
+ * style choice, it is forced, and it was measured before it was decided:
+ *
+ *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
+ *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
+ *
+ * and all three reds were over-denial of PERMITTED records, not the leak. Two
+ * independent reasons:
+ *
+ *   1. `toJSON()` has no request. The shipped, documented sample reads
+ *      `request.path` for its `/archived` sub-path rule -- the one read of
+ *      argument one the README sanctions -- and fail-closes when it is absent.
+ *      Measured against the live registry:
+ *
+ *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
+ *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
+ *
+ *      Same predicate object, two models, two different degradation modes,
+ *      chosen by the consumer. Without a request there is no trustworthy
+ *      answer to get.
+ *
+ *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
+ *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
+ *      An implicit caller has no syntactic place to pass anything
+ *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
+ *      byte-identical to what shipped, which also rules out fail-closed by
+ *      default: `Orm.instance.accessFunctions` is `{}` in any process that
+ *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
+ *      fail-closed default would empty every relationship on every document in
+ *      processes that have no REST surface to protect.
+ *
+ * The caller -- which still holds the request -- resolves the predicate,
+ * interprets it here, caches the answer, and hands `toJSON()` an already-decided
+ * `(type, record) => boolean`.
+ */
+import Orm from '@stonyx/orm';
+import log from 'stonyx/log';
+const DENIED = Object.freeze({ granted: false });
+const GRANTED = Object.freeze({ granted: true });
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export function interpretAccess(access, operation) {
+    if (!access)
+        return DENIED;
+    // The function return shape IS the per-record hook. Grant the request and
+    // carry the predicate; the caller applies it per record.
+    if (typeof access === 'function')
+        return { granted: true, filter: access };
+    if (access === true)
+        return GRANTED;
+    // `AccessMethod` declares `string` legal and it fell through every branch
+    // above. A bare string is ONE permission, not a grant of all four -- reading
+    // it as a full grant is what once let `return 'read'` authorise DELETE.
+    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 DENIED;
+    if (!permitted.includes(operation))
+        return DENIED;
+    return GRANTED;
+}
+/**
+ * Resolve model `type`'s verdict for a read, against the live `request`.
+ *
+ * Fails closed on both ambiguous inputs:
+ *
+ *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
+ *     unrestricted". `setup-rest-server` catches an access-class load failure,
+ *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
+ *     both "no access class claims this model" and "the class that claims it
+ *     failed to load" -- and the caller cannot tell them apart. Deny.
+ *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
+ *     a throw is a denial, logged, never a 500 and never a grant.
+ *
+ * NOTE ON CROSS-MODEL ASKS. The predicate is asked about `type` while the
+ * request in hand was dispatched to a DIFFERENT model's route. Since #222 this
+ * repo's fixture reads `context.model` and answers correctly; a consumer's
+ * arity-1 predicate does not, and there is no supported way to tell which kind
+ * was resolved (the boot-time arity warning is abofs/stonyx-orm#213). A
+ * consequence to expect rather than debug: the fixture's surviving `request.path`
+ * read means asking the OWNER predicate on a request dispatched to
+ * `GET /animals/archived` returns a bare `false`. That is a whole-request deny
+ * bleeding across models -- harmless, because it is the fail-closed direction,
+ * and it is treated as "deny this linkage", not as an error.
+ */
+function resolveVerdict(request, type) {
+    const predicate = Orm.instance?.getAccess?.(type);
+    if (typeof predicate !== 'function')
+        return DENIED;
+    let access;
+    try {
+        access = predicate(request, { model: type, operation: 'read' });
+    }
+    catch (error) {
+        log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+        return DENIED;
+    }
+    return interpretAccess(access, 'read');
+}
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite: `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay distinct, where `` `${type}:${id}` ``
+ * would collapse them and let one model's verdict answer for another record.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export function createLinkageFilter(request) {
+    const byType = new Map();
+    return function isLinkable(type, record) {
+        let entry = byType.get(type);
+        if (!entry) {
+            entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
+            byType.set(type, entry);
+        }
+        const { verdict, decisions } = entry;
+        if (!verdict.granted)
+            return false;
+        if (!verdict.filter)
+            return true;
+        const id = record?.id;
+        const cached = decisions.get(id);
+        if (cached !== undefined)
+            return cached;
+        let allowed;
+        try {
+            allowed = Boolean(verdict.filter(record));
+        }
+        catch (error) {
+            // A predicate that throws is a denial -- the same reading `isDenied` uses
+            // one layer down. Logged, because a predicate that throws on every record
+            // empties every relationship and, silently, that is indistinguishable
+            // from a database with no relationships in it.
+            log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+            allowed = false;
+        }
+        decisions.set(id, allowed);
+        return allowed;
+    };
+}

package/dist/orm-request.js

@@ -219,6 +219,7 @@ import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
+import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 const methodAccessMap = {
     GET: 'read',
     POST: 'create',
@@ -561,7 +562,13 @@ export default class OrmRequest extends Request {
             if (queryFilterPredicate)
                 recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
             const baseUrl = getBaseUrl(request);
-            const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
+            // ONE filter per REQUEST, not one per record: it carries the per-type
+            // verdict cache and the per-(type, id) decision cache, and both are
+            // worthless if it is rebuilt inside the map. Measured on this exact
+            // surface with no `include=`: 48 linkage entries collapse to 7 distinct
+            // (type, id) pairs.
+            const linkage = createLinkageFilter(request);
+            const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl, linkage }));
             return buildResponse(data, request.query?.include, recordsToReturn, {
                 links: { self: `${baseUrl}/${pluralizedModel}` },
                 baseUrl
@@ -579,7 +586,13 @@ export default class OrmRequest extends Request {
             const fieldsMap = parseFields(request.query);
             const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
             const baseUrl = getBaseUrl(request);
-            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
+            const linkage = createLinkageFilter(request);
+            // `buildResponse` is deliberately NOT given the linkage filter. It builds
+            // `included`, and WHETHER A RESOURCE APPEARS THERE AT ALL is membership,
+            // which belongs to abofs/stonyx-orm#233 -- see this file's #234 note and
+            // the ownership boundary in that issue. Only the PRIMARY document's
+            // linkage is filtered here.
+            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
                 baseUrl
             });
@@ -1166,15 +1179,21 @@ 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.
+                const linkage = createLinkageFilter(request);
                 let data;
                 if (info.isArray) {
                     // hasMany - return array
                     const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-                    data = related.map(r => r.toJSON?.({ baseUrl }));
+                    data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
                 }
                 else {
                     // belongsTo - return single or null
-                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
+                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
                 }
                 return {
                     links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
@@ -1285,26 +1304,23 @@ export default class OrmRequest extends Request {
             log.error?.(`[@stonyx/orm] access() threw for model "${this.model}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
             return 403; // Forbidden
         }
-        if (!access)
-            return 403;
-        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]))
+        // THE READING OF THE RETURN SHAPE LIVES IN ONE PLACE (#234).
+        //
+        // It used to be inline here, and it was the only copy, which was fine while
+        // `auth()` was the only thing that had to ask. It is not any more: the
+        // linkage path has to ask model X's predicate about model X's records while
+        // servicing a request routed to model Y, and a second inline copy of these
+        // six branches would be a second authorization vocabulary -- one that can
+        // drift, and that reviewers would have to notice had drifted. The branch
+        // order in `interpretAccess` is this block, moved, not rewritten.
+        const verdict = interpretAccess(access, methodAccessMap[request.method]);
+        if (!verdict.granted)
             return 403;
+        // The function return shape is the per-record hook, and `state` is the
+        // whole transport for it: @stonyx/rest-server memoises one state object per
+        // request and hands the same one to `auth()` and to the handler.
+        if (verdict.filter)
+            state.filter = verdict.filter;
         return undefined;
     }
 }

package/dist/record.d.ts

@@ -2,6 +2,18 @@ import type Serializer from './serializer.js';
 interface ToJSONOptions {
     fields?: Set<string>;
     baseUrl?: string;
+    /**
+     * An ALREADY-RESOLVED linkage decision, supplied by a caller that holds the
+     * request (abofs/stonyx-orm#234). Returning `false` for a related record
+     * drops that record's `{ type, id }` from `relationships.*.data`.
+     *
+     * This method APPLIES a verdict; it never RESOLVES one -- see
+     * `src/access-verdict.ts` for the two measured reasons it cannot. ABSENT is
+     * the default and the default is TODAY'S DOCUMENT, unchanged, because
+     * `toJSON` is also the `JSON.stringify` hook and an implicit caller has no
+     * syntactic place to pass this (abofs/stonyx-orm#230).
+     */
+    linkage?: (type: string, record: unknown) => boolean;
 }
 interface SerializeOptions {
     update?: boolean;

package/dist/record.js

@@ -65,7 +65,13 @@ export default class Record {
     toJSON(options = {}) {
         if (!this.__serialized)
             throw new Error('Record must be serialized before being converted to JSON');
-        const { fields, baseUrl } = options;
+        // DESTRUCTURED FROM A VALUE THAT IS NOT ALWAYS AN OBJECT. `toJSON` is the
+        // ECMAScript serialization hook, so `JSON.stringify({ data: record })`
+        // arrives here as `toJSON('data')` -- a STRING in the options slot.
+        // Destructuring a string yields `undefined` for every key, which is exactly
+        // the no-argument default, so the implicit path keeps working and keeps
+        // emitting today's document (abofs/stonyx-orm#230).
+        const { fields, baseUrl, linkage } = options;
         const { __data: data } = this;
         const modelName = this.__model.__name;
         const pluralizedModelName = getPluralName(modelName);
@@ -87,9 +93,20 @@ export default class Record {
         for (const [key, childRecord] of Object.entries(this.__relationships)) {
             if (fields && !fields.has(key))
                 continue;
+            // The linkage decision is applied HERE, alongside the existing
+            // `__model` liveness check, and it produces exactly the shapes that
+            // check already produces: a dropped hasMany member leaves `data: []`,
+            // a dropped belongsTo leaves `data: null`. Both already ship -- a
+            // genuinely-empty hasMany emits `data: []` with links, and a cleaned
+            // belongsTo emits `data: null` -- so a filtered relationship is
+            // BYTE-IDENTICAL to an empty one and there is no new wire shape and no
+            // oracle. It never throws: a throw here escapes the enclosing
+            // `JSON.stringify` and takes `console.log` and `Orm.db.save()`'s
+            // neighbours with it, which is a far worse failure mode than a status.
+            const isLinkable = (r) => !linkage || linkage(r.__model.__name, r);
             const relationshipData = Array.isArray(childRecord)
-                ? childRecord.filter((r) => r?.__model).map((r) => ({ type: r.__model.__name, id: r.id }))
-                : (childRecord && childRecord.__model) ? { type: childRecord.__model.__name, id: childRecord.id } : null;
+                ? childRecord.filter((r) => r?.__model).filter(isLinkable).map((r) => ({ type: r.__model.__name, id: r.id }))
+                : (childRecord && childRecord.__model && isLinkable(childRecord)) ? { type: childRecord.__model.__name, id: childRecord.id } : null;
             // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
             const dasherizedKey = camelCaseToKebabCase(key);
             relationships[dasherizedKey] = { data: relationshipData };

package/dist/types/orm-types.d.ts

@@ -87,9 +87,18 @@ export interface OrmRecord {
         __pendingSqlId?: boolean;
     };
     __relationships: Record<string, unknown>;
+    /**
+     * `linkage` is an ALREADY-RESOLVED decision supplied by a caller that holds
+     * the request (abofs/stonyx-orm#234): return `false` for a related record and
+     * its `{ type, id }` is dropped from `relationships.*.data`. Omitting it is
+     * the default, and the default is the pre-#234 document unchanged -- this
+     * method is also the `JSON.stringify` hook, so an implicit caller has no
+     * syntactic place to pass it (abofs/stonyx-orm#230).
+     */
     toJSON?(options?: {
         fields?: Set<string>;
         baseUrl?: string;
+        linkage?: (type: string, record: unknown) => boolean;
     }): Record<string, unknown>;
     [key: string]: unknown;
 }

package/package.json

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

package/src/access-verdict.ts

@@ -0,0 +1,222 @@
+/**
+ * The shared access-verdict primitive (abofs/stonyx-orm#234).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
+ * ---------------------------------------------------------------------------
+ * A consumer `access()` may return six differently-shaped things -- `false`, a
+ * bare permission string, a permission array, `true`, a per-record function, or
+ * something the contract does not define at all -- and the reading of each one
+ * is a security decision. `auth()` has held that reading inline since #190.
+ * Every surface that needs to ask "may this caller see model X's record?" needs
+ * the SAME reading, or the second copy becomes an unreviewed second
+ * authorization vocabulary that answers differently about the same value.
+ *
+ * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
+ * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
+ * rebase onto it rather than re-deriving it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
+ * ---------------------------------------------------------------------------
+ * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
+ * style choice, it is forced, and it was measured before it was decided:
+ *
+ *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
+ *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
+ *
+ * and all three reds were over-denial of PERMITTED records, not the leak. Two
+ * independent reasons:
+ *
+ *   1. `toJSON()` has no request. The shipped, documented sample reads
+ *      `request.path` for its `/archived` sub-path rule -- the one read of
+ *      argument one the README sanctions -- and fail-closes when it is absent.
+ *      Measured against the live registry:
+ *
+ *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
+ *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
+ *
+ *      Same predicate object, two models, two different degradation modes,
+ *      chosen by the consumer. Without a request there is no trustworthy
+ *      answer to get.
+ *
+ *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
+ *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
+ *      An implicit caller has no syntactic place to pass anything
+ *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
+ *      byte-identical to what shipped, which also rules out fail-closed by
+ *      default: `Orm.instance.accessFunctions` is `{}` in any process that
+ *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
+ *      fail-closed default would empty every relationship on every document in
+ *      processes that have no REST surface to protect.
+ *
+ * The caller -- which still holds the request -- resolves the predicate,
+ * interprets it here, caches the answer, and hands `toJSON()` an already-decided
+ * `(type, record) => boolean`.
+ */
+import Orm from '@stonyx/orm';
+import log from 'stonyx/log';
+import type { AccessMethod, AccessOperation } from './types/orm-types.js';
+
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+  granted: boolean;
+  filter?: (record: unknown) => boolean;
+}
+
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * the consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key, not the input.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;
+
+const DENIED: AccessVerdict = Object.freeze({ granted: false });
+const GRANTED: AccessVerdict = Object.freeze({ granted: true });
+
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict {
+  if (!access) return DENIED;
+
+  // The function return shape IS the per-record hook. Grant the request and
+  // carry the predicate; the caller applies it per record.
+  if (typeof access === 'function') return { granted: true, filter: access as (record: unknown) => boolean };
+
+  if (access === true) return GRANTED;
+
+  // `AccessMethod` declares `string` legal and it fell through every branch
+  // above. A bare string is ONE permission, not a grant of all four -- reading
+  // it as a full grant is what once let `return 'read'` authorise DELETE.
+  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 DENIED;
+  if (!permitted.includes(operation as string)) return DENIED;
+
+  return GRANTED;
+}
+
+/**
+ * Resolve model `type`'s verdict for a read, against the live `request`.
+ *
+ * Fails closed on both ambiguous inputs:
+ *
+ *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
+ *     unrestricted". `setup-rest-server` catches an access-class load failure,
+ *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
+ *     both "no access class claims this model" and "the class that claims it
+ *     failed to load" -- and the caller cannot tell them apart. Deny.
+ *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
+ *     a throw is a denial, logged, never a 500 and never a grant.
+ *
+ * NOTE ON CROSS-MODEL ASKS. The predicate is asked about `type` while the
+ * request in hand was dispatched to a DIFFERENT model's route. Since #222 this
+ * repo's fixture reads `context.model` and answers correctly; a consumer's
+ * arity-1 predicate does not, and there is no supported way to tell which kind
+ * was resolved (the boot-time arity warning is abofs/stonyx-orm#213). A
+ * consequence to expect rather than debug: the fixture's surviving `request.path`
+ * read means asking the OWNER predicate on a request dispatched to
+ * `GET /animals/archived` returns a bare `false`. That is a whole-request deny
+ * bleeding across models -- harmless, because it is the fail-closed direction,
+ * and it is treated as "deny this linkage", not as an error.
+ */
+function resolveVerdict(request: unknown, type: string): AccessVerdict {
+  const predicate = Orm.instance?.getAccess?.(type);
+  if (typeof predicate !== 'function') return DENIED;
+
+  let access: AccessMethod;
+
+  try {
+    access = predicate(request, { model: type, operation: 'read' });
+  } catch (error) {
+    log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+
+    return DENIED;
+  }
+
+  return interpretAccess(access, 'read');
+}
+
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite: `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay distinct, where `` `${type}:${id}` ``
+ * would collapse them and let one model's verdict answer for another record.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export function createLinkageFilter(request: unknown): LinkageFilter {
+  const byType = new Map<string, { verdict: AccessVerdict; decisions: Map<unknown, boolean> }>();
+
+  return function isLinkable(type: string, record: unknown): boolean {
+    let entry = byType.get(type);
+
+    if (!entry) {
+      entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
+      byType.set(type, entry);
+    }
+
+    const { verdict, decisions } = entry;
+
+    if (!verdict.granted) return false;
+    if (!verdict.filter) return true;
+
+    const id = (record as { id?: unknown } | null)?.id;
+    const cached = decisions.get(id);
+    if (cached !== undefined) return cached;
+
+    let allowed: boolean;
+
+    try {
+      allowed = Boolean(verdict.filter(record));
+    } catch (error) {
+      // A predicate that throws is a denial -- the same reading `isDenied` uses
+      // one layer down. Logged, because a predicate that throws on every record
+      // empties every relationship and, silently, that is indistinguishable
+      // from a database with no relationships in it.
+      log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+
+      allowed = false;
+    }
+
+    decisions.set(id, allowed);
+
+    return allowed;
+  };
+}

package/src/orm-request.ts

@@ -221,6 +221,7 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
+import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -633,7 +634,14 @@ export default class OrmRequest extends Request {
       if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
 
       const baseUrl = getBaseUrl(request);
-      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
+
+      // ONE filter per REQUEST, not one per record: it carries the per-type
+      // verdict cache and the per-(type, id) decision cache, and both are
+      // worthless if it is rebuilt inside the map. Measured on this exact
+      // surface with no `include=`: 48 linkage entries collapse to 7 distinct
+      // (type, id) pairs.
+      const linkage = createLinkageFilter(request);
+      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl, linkage }));
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
@@ -653,7 +661,14 @@ export default class OrmRequest extends Request {
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       const baseUrl = getBaseUrl(request);
-      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
+      const linkage = createLinkageFilter(request);
+
+      // `buildResponse` is deliberately NOT given the linkage filter. It builds
+      // `included`, and WHETHER A RESOURCE APPEARS THERE AT ALL is membership,
+      // which belongs to abofs/stonyx-orm#233 -- see this file's #234 note and
+      // the ownership boundary in that issue. Only the PRIMARY document's
+      // linkage is filtered here.
+      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
         baseUrl
       });
@@ -1283,14 +1298,21 @@ 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.
+        const linkage = createLinkageFilter(request);
+
         let data: unknown;
         if (info.isArray) {
           // hasMany - return array
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl }));
+          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
           // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
+          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
         }
 
         return {
@@ -1407,24 +1429,23 @@ export default class OrmRequest extends Request {
       return 403; // Forbidden
     }
 
-    if (!access) return 403;
-    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;
+    // THE READING OF THE RETURN SHAPE LIVES IN ONE PLACE (#234).
+    //
+    // It used to be inline here, and it was the only copy, which was fine while
+    // `auth()` was the only thing that had to ask. It is not any more: the
+    // linkage path has to ask model X's predicate about model X's records while
+    // servicing a request routed to model Y, and a second inline copy of these
+    // six branches would be a second authorization vocabulary -- one that can
+    // drift, and that reviewers would have to notice had drifted. The branch
+    // order in `interpretAccess` is this block, moved, not rewritten.
+    const verdict = interpretAccess(access, methodAccessMap[request.method]);
+
+    if (!verdict.granted) return 403;
+
+    // The function return shape is the per-record hook, and `state` is the
+    // whole transport for it: @stonyx/rest-server memoises one state object per
+    // request and hands the same one to `auth()` and to the handler.
+    if (verdict.filter) state.filter = verdict.filter;
 
     return undefined;
   }

package/src/record.ts

@@ -7,6 +7,18 @@ import type Serializer from './serializer.js';
 interface ToJSONOptions {
   fields?: Set<string>;
   baseUrl?: string;
+  /**
+   * An ALREADY-RESOLVED linkage decision, supplied by a caller that holds the
+   * request (abofs/stonyx-orm#234). Returning `false` for a related record
+   * drops that record's `{ type, id }` from `relationships.*.data`.
+   *
+   * This method APPLIES a verdict; it never RESOLVES one -- see
+   * `src/access-verdict.ts` for the two measured reasons it cannot. ABSENT is
+   * the default and the default is TODAY'S DOCUMENT, unchanged, because
+   * `toJSON` is also the `JSON.stringify` hook and an implicit caller has no
+   * syntactic place to pass this (abofs/stonyx-orm#230).
+   */
+  linkage?: (type: string, record: unknown) => boolean;
 }
 
 interface SerializeOptions {
@@ -116,7 +128,13 @@ export default class Record {
   toJSON(options: ToJSONOptions = {}): JSONAPIResult {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
 
-    const { fields, baseUrl } = options;
+    // DESTRUCTURED FROM A VALUE THAT IS NOT ALWAYS AN OBJECT. `toJSON` is the
+    // ECMAScript serialization hook, so `JSON.stringify({ data: record })`
+    // arrives here as `toJSON('data')` -- a STRING in the options slot.
+    // Destructuring a string yields `undefined` for every key, which is exactly
+    // the no-argument default, so the implicit path keeps working and keeps
+    // emitting today's document (abofs/stonyx-orm#230).
+    const { fields, baseUrl, linkage } = options;
     const { __data: data } = this;
     const modelName = this.__model.__name;
     const pluralizedModelName = getPluralName(modelName);
@@ -138,9 +156,21 @@ export default class Record {
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
 
+      // The linkage decision is applied HERE, alongside the existing
+      // `__model` liveness check, and it produces exactly the shapes that
+      // check already produces: a dropped hasMany member leaves `data: []`,
+      // a dropped belongsTo leaves `data: null`. Both already ship -- a
+      // genuinely-empty hasMany emits `data: []` with links, and a cleaned
+      // belongsTo emits `data: null` -- so a filtered relationship is
+      // BYTE-IDENTICAL to an empty one and there is no new wire shape and no
+      // oracle. It never throws: a throw here escapes the enclosing
+      // `JSON.stringify` and takes `console.log` and `Orm.db.save()`'s
+      // neighbours with it, which is a far worse failure mode than a status.
+      const isLinkable = (r: Record) => !linkage || linkage(r.__model.__name, r);
+
       const relationshipData = Array.isArray(childRecord)
-        ? childRecord.filter((r: Record) => r?.__model).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
-        : (childRecord && (childRecord as Record).__model) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
+        ? childRecord.filter((r: Record) => r?.__model).filter(isLinkable).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : (childRecord && (childRecord as Record).__model && isLinkable(childRecord as Record)) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
 
       // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
       const dasherizedKey = camelCaseToKebabCase(key);

package/src/types/orm-types.ts

@@ -89,7 +89,15 @@ export interface OrmRecord {
   __model?: { __name: string };
   __data: Record<string, unknown> & { id?: string | number; __pendingSqlId?: boolean };
   __relationships: Record<string, unknown>;
-  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): Record<string, unknown>;
+  /**
+   * `linkage` is an ALREADY-RESOLVED decision supplied by a caller that holds
+   * the request (abofs/stonyx-orm#234): return `false` for a related record and
+   * its `{ type, id }` is dropped from `relationships.*.data`. Omitting it is
+   * the default, and the default is the pre-#234 document unchanged -- this
+   * method is also the `JSON.stringify` hook, so an implicit caller has no
+   * syntactic place to pass it (abofs/stonyx-orm#230).
+   */
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string; linkage?: (type: string, record: unknown) => boolean }): Record<string, unknown>;
   [key: string]: unknown;
 }