@stonyx/orm 0.3.2-alpha.53 → 0.3.2-alpha.55

package/README.md

@@ -381,6 +381,97 @@ export default class GlobalAccess {
 }
 ```
 
+
+### The access context (second argument)
+
+`access()` is called with **two** arguments:
+
+```js
+access(request, { model, operation })
+```
+
+The second is the **access context** — the structural facts about the request,
+which the framework already holds at authorization time. Read these instead of
+parsing anything.
+
+| Key | Value |
+|---|---|
+| `model` | The model this route was mounted for, as a **model name**: kebab-case, exactly as declared under `config.orm.paths.model` and keyed in the store — `'owner'`, `'animal'`, `'phone-number'`. **Not** the pluralized, dasherized, mount-prefixed *route* name. |
+| `operation` | One of **`'read'`, `'create'`, `'update'`, `'delete'`** — and no second vocabulary. Never an HTTP method name like `'GET'`. `undefined` when the dispatched method has no entry in the framework's method map. |
+
+So a predicate can be written without reference to any URL:
+
+```js
+export default class OwnerAccess {
+  models = ['owner'];
+
+  access(request, { model, operation }) {
+    if (model === 'owner' && operation === 'read') {
+      return record => record.id !== 'angela';
+    }
+
+    return ['read'];
+  }
+}
+```
+
+There is no string to parse, no variant to miss, and no way to fail open through
+a URL shape nobody anticipated. `model` is fixed at mount time and no request
+can influence it — not a mount prefix, not a query string, not a case-varied
+path, not an absolute-form request target.
+
+The four `operation` values are the same four strings the permission-array
+return shape is written in (`['read', 'create', 'update', 'delete']`), because
+both come from one method map inside the framework. The two forms cannot
+disagree about the same request.
+
+**`operation` is `undefined`, never defaulted, for an unmapped method.** Express
+delivers `HEAD` to the `GET` handler, so this is reachable. It is deliberately
+not defaulted to `'read'`: a fabricated operation would turn an unclassified
+request into an authorized one. Treat `undefined` as *not classified* and deny.
+
+**The second argument is additive.** JavaScript ignores extra arguments, so an
+existing `access(request)` predicate keeps working exactly as it did. Nothing
+needs to be migrated to keep running — but note that argument **one** is still
+the raw request, so the warning in
+[Identifying the collection](#identifying-the-collection) still applies to any
+predicate that reads it.
+
+#### `record` is not in the context
+
+Deliberately, and it is not an oversight. `auth()` runs after route matching but
+**before any handler executes**, so nothing has been fetched yet. Supplying a
+record would force a pre-fetch on every request — a second store hit, a new
+failure mode, and an ordering change in the middle of an authorization path.
+
+It is also unnecessary: the **function** return shape already *is* the
+per-record hook. Return `(record) => boolean` and the handlers apply it to every
+record the request touches. Auth-time and record-time are separate decision
+points, and the contract keeps them separate.
+
+#### Reaching another model's predicate
+
+The model → predicate map is published on the ORM instance at boot, before any
+route is mounted, so a predicate can be resolved by model name and asked about a
+request routed to a *different* model:
+
+```js
+import Orm from '@stonyx/orm';
+
+const predicate = Orm.instance.getAccess('animal');
+const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+```
+
+`Orm.instance.getAccess(modelName)` returns the predicate, or `undefined` when
+that model has no access class. The raw map is `Orm.instance.accessFiles`, keyed
+by model name; prefer `getAccess()`.
+
+Passing the context explicitly is what makes the answer **model-correct**. A
+predicate that identifies its collection from the request would otherwise answer
+about the collection the request is *addressed to* while being asked about
+another one — and per the five variants below, it answers wrong in the direction
+that grants access.
+
 ### Return values
 
 | `access()` returns | Effect |
@@ -512,14 +603,20 @@ sub-paths beneath the mount, as the `/archived` deny above does.
   one collection is writable and another is filtered on a field the first can
   set. Blocking it requires checking animal 21 against the **animal** model's
   predicate while servicing an **owners** route — cross-model access resolution,
-  which the current contract cannot express: `access()` never receives the model
-  structurally ([#202](https://github.com/abofs/stonyx-orm/issues/202)) and
-  `setup-rest-server.ts` discards the model→predicate map at boot
-  ([#196](https://github.com/abofs/stonyx-orm/issues/196)). Tracked as
-  [#207](https://github.com/abofs/stonyx-orm/issues/207), blocked on that chain
-  (#202 → #196 → #207). Until it lands, do not rely on a filter to keep a record
-  unmodifiable; keep the *writable* collections' predicates as tight as the
-  hidden ones.
+  which the contract could not express before
+  [#202](https://github.com/abofs/stonyx-orm/issues/202): `access()` never
+  received the model structurally and `setup-rest-server.ts` discarded the
+  model→predicate map at boot. **#202 has landed and both halves now exist** —
+  see [The access context](#the-access-context-second-argument): `context.model`
+  makes the answer model-correct and `Orm.instance.getAccess(modelName)` makes
+  another model's predicate reachable. **The mechanism exists; the ORM does not
+  yet use it on this path.** The re-parenting write above is still unblocked —
+  that enforcement is
+  [#196](https://github.com/abofs/stonyx-orm/issues/196) and
+  [#207](https://github.com/abofs/stonyx-orm/issues/207), which were blocked on
+  #202 and are now unblocked. Until they land, do not rely on a filter to keep a
+  record unmodifiable; keep the *writable* collections' predicates as tight as
+  the hidden ones.
 - **Authorization by identifying the collection is a consumer-side
   reconstruction of information the framework already holds.** `access()`
   receives a transport artifact and is asked to work out which model, which

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod } from './types/orm-types.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };

package/dist/main.d.ts

@@ -1,4 +1,5 @@
 import Store from './store.js';
+import type { AccessFunction } from './types/orm-types.js';
 interface OrmOptions {
     dbType?: string;
 }
@@ -32,12 +33,58 @@ export default class Orm {
     views: Record<string, unknown>;
     transforms: Record<string, (value: unknown) => unknown>;
     warnings: Set<string>;
+    /**
+     * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+     *
+     * Populated by `setup-rest-server.ts` at boot, from the access classes under
+     * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+     * and reachable before the first request can be served. The mapping is
+     * one-to-one by construction: setup-rest-server throws if two access classes
+     * claim the same model.
+     *
+     * Keys are model names as declared and stored (kebab-case, e.g.
+     * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+     *
+     * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+     * setup-rest-server that was discarded when that function returned, so at
+     * request time there was no way to get from a model name to that model's
+     * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+     * That made cross-model authorization -- asking model X's predicate about a
+     * request routed to model Y -- inexpressible, which is the capability
+     * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+     *
+     * Empty when the REST server is disabled, or when no access configuration
+     * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+     */
+    accessFiles: Record<string, AccessFunction>;
     options: OrmOptions;
     sqlDb?: SqlDb;
     db?: OrmDB | SqlDb;
     private _persistErrorHandler;
     constructor(options?: OrmOptions);
     init(): Promise<void>;
+    /**
+     * Resolve a model's `access` predicate by model name (abofs/stonyx-orm#202).
+     *
+     * This is the supported way to reach another model's predicate while
+     * servicing a request routed to a different model. Call it with the model
+     * name and invoke the result with the live request and an explicit context
+     * naming THAT model:
+     *
+     * ```js
+     * const predicate = Orm.instance.getAccess('animal');
+     * const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+     * ```
+     *
+     * Passing the context is not optional in practice. A predicate that
+     * identifies its collection from the request would otherwise answer about the
+     * collection the request is ADDRESSED TO -- owners -- while being asked about
+     * animals, and per #202's thesis it answers wrong in the granting direction.
+     *
+     * @param modelName - Model name as declared and stored (kebab-case).
+     * @returns The predicate, or `undefined` when the model has no access class.
+     */
+    getAccess(modelName: string): AccessFunction | undefined;
     startup(): Promise<void>;
     shutdown(): Promise<void>;
     static get db(): OrmDB | SqlDb;

package/dist/main.js

@@ -38,6 +38,30 @@ export default class Orm {
     views = {};
     transforms = { ...baseTransforms };
     warnings = new Set();
+    /**
+     * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+     *
+     * Populated by `setup-rest-server.ts` at boot, from the access classes under
+     * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+     * and reachable before the first request can be served. The mapping is
+     * one-to-one by construction: setup-rest-server throws if two access classes
+     * claim the same model.
+     *
+     * Keys are model names as declared and stored (kebab-case, e.g.
+     * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+     *
+     * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+     * setup-rest-server that was discarded when that function returned, so at
+     * request time there was no way to get from a model name to that model's
+     * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+     * That made cross-model authorization -- asking model X's predicate about a
+     * request routed to model Y -- inexpressible, which is the capability
+     * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+     *
+     * Empty when the REST server is disabled, or when no access configuration
+     * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+     */
+    accessFiles = {};
     options;
     sqlDb;
     db;
@@ -145,6 +169,30 @@ export default class Orm {
         Orm.ready = await Promise.all(promises);
         Orm.initialized = true;
     }
+    /**
+     * Resolve a model's `access` predicate by model name (abofs/stonyx-orm#202).
+     *
+     * This is the supported way to reach another model's predicate while
+     * servicing a request routed to a different model. Call it with the model
+     * name and invoke the result with the live request and an explicit context
+     * naming THAT model:
+     *
+     * ```js
+     * const predicate = Orm.instance.getAccess('animal');
+     * const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+     * ```
+     *
+     * Passing the context is not optional in practice. A predicate that
+     * identifies its collection from the request would otherwise answer about the
+     * collection the request is ADDRESSED TO -- owners -- while being asked about
+     * animals, and per #202's thesis it answers wrong in the granting direction.
+     *
+     * @param modelName - Model name as declared and stored (kebab-case).
+     * @returns The predicate, or `undefined` when the model has no access class.
+     */
+    getAccess(modelName) {
+        return this.accessFiles[modelName];
+    }
     async startup() {
         if (this.sqlDb)
             await this.sqlDb.startup();

package/dist/orm-request.d.ts

@@ -2,6 +2,62 @@
  * REST request handling and access enforcement for @stonyx/orm.
  *
  * ---------------------------------------------------------------------------
+ * THE `access()` CONTRACT: `access(request, { model, operation })`
+ * ---------------------------------------------------------------------------
+ * `auth()` calls your predicate with TWO arguments. The second is the access
+ * CONTEXT -- the structural facts about the request, which the framework
+ * already holds and which you should read INSTEAD of parsing anything:
+ *
+ *   context.model     The model this route was mounted for, as a model name:
+ *                     kebab-case, exactly as declared under
+ *                     `config.orm.paths.model` and keyed in the store --
+ *                     `'owner'`, `'animal'`, `'phone-number'`. NOT the
+ *                     pluralised, dasherized, mount-prefixed ROUTE name. It is
+ *                     read from the OrmRequest instance, fixed at mount time,
+ *                     and no request can influence it.
+ *
+ *   context.operation The operation being authorised. Exactly one of the four
+ *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
+ *                     there is no second vocabulary, and it is never an HTTP
+ *                     method name like `'GET'`. These are the same four
+ *                     strings the permission-array return shape is written in
+ *                     (`['read', 'create']`), because both come from the one
+ *                     `methodAccessMap` below.
+ *
+ *                     `undefined` when the dispatched method has no entry in
+ *                     that map. Express delivers `HEAD` to the `GET` handler,
+ *                     so this is reachable. It is left undefined rather than
+ *                     defaulted on purpose -- a fabricated `'read'` would turn
+ *                     an unclassified request into an authorised one. Treat
+ *                     `undefined` as "not classified" and deny.
+ *
+ * So a consumer writes `if (model === 'owner' && operation === 'read')`. There
+ * is no string to parse, no variant to miss, and no way to fail open through a
+ * URL shape nobody anticipated.
+ *
+ * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
+ * matching but BEFORE any handler executes (`@stonyx/rest-server`
+ * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
+ * record would force a pre-fetch on every request, a second store hit and an
+ * ordering change in the middle of an authorization path. It is also
+ * unnecessary: the FUNCTION return shape already is the per-record hook. Return
+ * `(record) => boolean` and the handlers apply it to every record the request
+ * touches. Auth-time and record-time are separate decision points.
+ *
+ * THE SECOND ARGUMENT IS ADDITIVE. JavaScript ignores extra arguments, so an
+ * existing `access(request)` predicate keeps working exactly as before. The
+ * warning immediately below is therefore still live: `request` is still
+ * argument ONE, and reading it is still how predicates fail open.
+ *
+ * To reach ANOTHER model's predicate -- e.g. to check an animal while servicing
+ * an owners route -- use the boot-time registry:
+ *
+ *     const predicate = Orm.instance.getAccess('animal');
+ *     const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+ *
+ * Passing the context explicitly is what makes that answer model-CORRECT.
+ *
+ * ---------------------------------------------------------------------------
  * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
  * ---------------------------------------------------------------------------
  * `auth()` below hands your `access(request)` a raw transport artifact and asks
@@ -59,6 +115,7 @@
  * See `### Known limitations` in README.
  */
 import { Request } from '@stonyx/rest-server';
+import type { AccessFunction } from './types/orm-types.js';
 interface OrmRequest$ extends Request {
     protocol?: string;
     method: string;
@@ -73,13 +130,12 @@ interface OrmRequest$ extends Request {
     };
     get(header: string): string;
 }
-type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
 type HandlerFn = (request: OrmRequest$, state: {
     [key: string]: unknown;
 }) => unknown | Promise<unknown>;
 export default class OrmRequest extends Request {
     model: string;
-    access: (request: unknown) => AccessMethod;
+    access: AccessFunction;
     handlers: {
         [key: string]: {
             [key: string]: HandlerFn;
@@ -87,7 +143,7 @@ export default class OrmRequest extends Request {
     };
     constructor({ model, access }: {
         model: string;
-        access: (request: unknown) => AccessMethod;
+        access: AccessFunction;
     });
     private _withHooks;
     private _generateRelationshipRoutes;

package/dist/orm-request.js

@@ -2,6 +2,62 @@
  * REST request handling and access enforcement for @stonyx/orm.
  *
  * ---------------------------------------------------------------------------
+ * THE `access()` CONTRACT: `access(request, { model, operation })`
+ * ---------------------------------------------------------------------------
+ * `auth()` calls your predicate with TWO arguments. The second is the access
+ * CONTEXT -- the structural facts about the request, which the framework
+ * already holds and which you should read INSTEAD of parsing anything:
+ *
+ *   context.model     The model this route was mounted for, as a model name:
+ *                     kebab-case, exactly as declared under
+ *                     `config.orm.paths.model` and keyed in the store --
+ *                     `'owner'`, `'animal'`, `'phone-number'`. NOT the
+ *                     pluralised, dasherized, mount-prefixed ROUTE name. It is
+ *                     read from the OrmRequest instance, fixed at mount time,
+ *                     and no request can influence it.
+ *
+ *   context.operation The operation being authorised. Exactly one of the four
+ *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
+ *                     there is no second vocabulary, and it is never an HTTP
+ *                     method name like `'GET'`. These are the same four
+ *                     strings the permission-array return shape is written in
+ *                     (`['read', 'create']`), because both come from the one
+ *                     `methodAccessMap` below.
+ *
+ *                     `undefined` when the dispatched method has no entry in
+ *                     that map. Express delivers `HEAD` to the `GET` handler,
+ *                     so this is reachable. It is left undefined rather than
+ *                     defaulted on purpose -- a fabricated `'read'` would turn
+ *                     an unclassified request into an authorised one. Treat
+ *                     `undefined` as "not classified" and deny.
+ *
+ * So a consumer writes `if (model === 'owner' && operation === 'read')`. There
+ * is no string to parse, no variant to miss, and no way to fail open through a
+ * URL shape nobody anticipated.
+ *
+ * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
+ * matching but BEFORE any handler executes (`@stonyx/rest-server`
+ * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
+ * record would force a pre-fetch on every request, a second store hit and an
+ * ordering change in the middle of an authorization path. It is also
+ * unnecessary: the FUNCTION return shape already is the per-record hook. Return
+ * `(record) => boolean` and the handlers apply it to every record the request
+ * touches. Auth-time and record-time are separate decision points.
+ *
+ * THE SECOND ARGUMENT IS ADDITIVE. JavaScript ignores extra arguments, so an
+ * existing `access(request)` predicate keeps working exactly as before. The
+ * warning immediately below is therefore still live: `request` is still
+ * argument ONE, and reading it is still how predicates fail open.
+ *
+ * To reach ANOTHER model's predicate -- e.g. to check an animal while servicing
+ * an owners route -- use the boot-time registry:
+ *
+ *     const predicate = Orm.instance.getAccess('animal');
+ *     const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+ *
+ * Passing the context explicitly is what makes that answer model-CORRECT.
+ *
+ * ---------------------------------------------------------------------------
  * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
  * ---------------------------------------------------------------------------
  * `auth()` below hands your `access(request)` a raw transport artifact and asks
@@ -1036,9 +1092,41 @@ export default class OrmRequest extends Request {
         // 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.
+        // -------------------------------------------------------------------------
+        // #202 -- hand the consumer the STRUCTURAL facts, not just the transport.
+        //
+        // Both members are already in hand here. `model` is `this.model`, the name
+        // setup-rest-server mounted this route for; `operation` is the SAME
+        // `methodAccessMap` lookup the permission-array branch at the bottom of
+        // this method performs, so the predicate form and the array form cannot
+        // answer differently about the same request.
+        //
+        // NEITHER IS DERIVED FROM THE REQUEST TARGET, and that is the whole point.
+        // Deriving `model` here from `request.baseUrl` (or from the mounted route
+        // name, or from `getPluralName(this.model)`) would move all five fail-open
+        // variants listed in this file's header OUT of the consumer and INTO the
+        // framework, where every consumer inherits them at once. `this.model` is
+        // assigned once at mount time and no request can influence it.
+        //
+        // `operation` is left UNDEFINED for a method with no entry in
+        // `methodAccessMap`, rather than defaulted. Express delivers HEAD to the
+        // GET handler, so an unmapped method really does reach this line; a
+        // `?? 'read'` here would hand the consumer a fabricated authorisation fact
+        // and turn an unclassified request into an authorised one. Undefined is
+        // the honest answer.
+        //
+        // `record` is deliberately absent -- see `AccessContext` in
+        // src/types/orm-types.ts. Nothing is fetched at this point and adding a
+        // lookup here would put a store read in the middle of an authorization
+        // path. The function return shape below IS the per-record hook.
+        // -------------------------------------------------------------------------
+        const context = {
+            model: this.model,
+            operation: methodAccessMap[request.method],
+        };
         let access;
         try {
-            access = this.access(request);
+            access = this.access(request, context);
         }
         catch (error) {
             // Same reasoning as `isDenied`: fail closed, but say so. An `access()`

package/dist/setup-rest-server.js

@@ -1,5 +1,5 @@
 import { waitForModule } from 'stonyx';
-import { store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
 import OrmRequest from './orm-request.js';
 import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
@@ -35,6 +35,28 @@ export default async function (route, accessPath, metaRoute) {
         log.error?.(error instanceof Error ? error.message : String(error));
         log.warn?.('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
     }
+    // -------------------------------------------------------------------------
+    // #202 -- the registry has to survive this function.
+    //
+    // `accessFiles` used to be a function-local that was discarded at the return
+    // below, so the only thing that ever saw it was the mount loop. Each mounted
+    // OrmRequest then held its OWN model's predicate and nothing held the map, so
+    // at request time there was no route from a model NAME to that model's
+    // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
+    // ask model X's predicate about a request routed to model Y.
+    //
+    // Published BEFORE `waitForModule('rest-server')` and before the mount loop,
+    // deliberately. That module may already be listening by the time it reports
+    // ready, so assigning after the mounts would leave a window in which a route
+    // exists and the registry does not.
+    //
+    // Assigned unconditionally, including when the try above failed and the map
+    // is empty or partial: the mount loop below is driven by this exact object,
+    // so whatever is reachable through `Orm.instance` is by construction the same
+    // set of predicates that is actually enforcing. A guard here that skipped the
+    // assignment would let the registry go silently missing, which is precisely
+    // the failure #202's AC8 exists to catch.
+    Orm.instance.accessFiles = accessFiles;
     await waitForModule('rest-server');
     // Remove "/" prefix and name mount point accordingly
     const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);

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

@@ -162,3 +162,70 @@ export interface SnapshotEntry {
     source?: string;
     viewQuery?: string;
 }
+/**
+ * The shapes a consumer `access()` predicate may return.
+ *
+ * - `false` (or any falsy value) -- deny, 403.
+ * - `true` -- allow, with no per-record filter.
+ * - a permission string or array of them, drawn from the same four verbs as
+ *   {@link AccessContext.operation}. A BARE STRING IS ONE PERMISSION, not a
+ *   grant of all four.
+ * - a `(record) => boolean` predicate -- allow, and filter every record the
+ *   request touches through it.
+ *
+ * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
+ */
+export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+/**
+ * The structural facts about the request being authorised, handed to a consumer
+ * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
+ *
+ * These are the facts the framework already holds at authorisation time. Before
+ * #202 a consumer had to reconstruct both of them by string-matching a URL, and
+ * five independent fail-open variants of that reconstruction were found in one
+ * three-line documented example -- each one wrong in the direction that GRANTS
+ * access. Read these instead; there is nothing to parse and no variant to miss.
+ *
+ * `record` is deliberately NOT a member. `auth()` runs after route matching but
+ * before any handler executes (`@stonyx/rest-server` `src/request.ts:58-60`),
+ * so nothing has been fetched yet -- carrying a record here would force a
+ * pre-fetch on every request. It is also unnecessary: the `(record) => boolean`
+ * return shape of {@link AccessMethod} already IS the per-record hook, applied
+ * by the handlers. Auth-time and record-time are separate decision points.
+ */
+export interface AccessContext {
+    /**
+     * The model this route was mounted for, e.g. `'owner'` or `'phone-number'`.
+     *
+     * Model names are kebab-case, as declared under `config.orm.paths.model` and
+     * keyed in the store -- NOT the pluralised, mount-prefixed route name. It is
+     * read from the `OrmRequest` instance and is never derived from the request
+     * target, so a mount prefix, a case-varied path, a query string or an
+     * absolute-form request-target cannot change it.
+     */
+    model: string;
+    /**
+     * The operation being authorised: `'read'`, `'create'`, `'update'` or
+     * `'delete'`, and no second vocabulary. These are exactly the values of
+     * `methodAccessMap` in `src/orm-request.ts`, which is also what the
+     * permission-array return shape is matched against -- so the two forms cannot
+     * disagree.
+     *
+     * `undefined` when the dispatched method has no entry in that map. Express
+     * delivers `HEAD` to the `GET` handler, so this is reachable. It is left
+     * undefined rather than defaulted on purpose: a fabricated `'read'` would
+     * turn an unclassified request into an authorised one.
+     */
+    operation?: string;
+}
+/**
+ * A consumer `access()` predicate.
+ *
+ * `context` is optional in the type because the second argument is ADDITIVE:
+ * JavaScript ignores extra arguments, so every pre-#202 single-argument
+ * predicate keeps working untouched. Changing the FIRST argument instead would
+ * have been the breaking form, and a predicate that can no longer identify its
+ * collection falls through to a full CRUD grant -- so the "safer" breaking
+ * change would have converted every unmigrated predicate into a fail-open.
+ */
+export type AccessFunction = (request: unknown, context?: AccessContext) => AccessMethod;

package/package.json

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

package/src/index.ts

@@ -27,6 +27,7 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod } from './types/orm-types.js'; // access() contract (#202)
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers

package/src/main.ts

@@ -25,6 +25,7 @@ import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
 import { setup } from '@stonyx/events';
+import type { AccessFunction } from './types/orm-types.js';
 
 interface OrmOptions {
   dbType?: string;
@@ -68,6 +69,32 @@ export default class Orm {
   views: Record<string, unknown> = {};
   transforms: Record<string, (value: unknown) => unknown> = { ...baseTransforms };
   warnings: Set<string> = new Set();
+
+  /**
+   * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+   *
+   * Populated by `setup-rest-server.ts` at boot, from the access classes under
+   * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+   * and reachable before the first request can be served. The mapping is
+   * one-to-one by construction: setup-rest-server throws if two access classes
+   * claim the same model.
+   *
+   * Keys are model names as declared and stored (kebab-case, e.g.
+   * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+   *
+   * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+   * setup-rest-server that was discarded when that function returned, so at
+   * request time there was no way to get from a model name to that model's
+   * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+   * That made cross-model authorization -- asking model X's predicate about a
+   * request routed to model Y -- inexpressible, which is the capability
+   * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+   *
+   * Empty when the REST server is disabled, or when no access configuration
+   * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+   */
+  accessFiles: Record<string, AccessFunction> = {};
+
   options!: OrmOptions;
   sqlDb?: SqlDb;
   db?: OrmDB | SqlDb;
@@ -195,6 +222,31 @@ export default class Orm {
     Orm.initialized = true;
   }
 
+  /**
+   * Resolve a model's `access` predicate by model name (abofs/stonyx-orm#202).
+   *
+   * This is the supported way to reach another model's predicate while
+   * servicing a request routed to a different model. Call it with the model
+   * name and invoke the result with the live request and an explicit context
+   * naming THAT model:
+   *
+   * ```js
+   * const predicate = Orm.instance.getAccess('animal');
+   * const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+   * ```
+   *
+   * Passing the context is not optional in practice. A predicate that
+   * identifies its collection from the request would otherwise answer about the
+   * collection the request is ADDRESSED TO -- owners -- while being asked about
+   * animals, and per #202's thesis it answers wrong in the granting direction.
+   *
+   * @param modelName - Model name as declared and stored (kebab-case).
+   * @returns The predicate, or `undefined` when the model has no access class.
+   */
+  getAccess(modelName: string): AccessFunction | undefined {
+    return this.accessFiles[modelName];
+  }
+
   async startup(): Promise<void> {
     if (this.sqlDb) await this.sqlDb.startup();
   }

package/src/orm-request.ts

@@ -2,6 +2,62 @@
  * REST request handling and access enforcement for @stonyx/orm.
  *
  * ---------------------------------------------------------------------------
+ * THE `access()` CONTRACT: `access(request, { model, operation })`
+ * ---------------------------------------------------------------------------
+ * `auth()` calls your predicate with TWO arguments. The second is the access
+ * CONTEXT -- the structural facts about the request, which the framework
+ * already holds and which you should read INSTEAD of parsing anything:
+ *
+ *   context.model     The model this route was mounted for, as a model name:
+ *                     kebab-case, exactly as declared under
+ *                     `config.orm.paths.model` and keyed in the store --
+ *                     `'owner'`, `'animal'`, `'phone-number'`. NOT the
+ *                     pluralised, dasherized, mount-prefixed ROUTE name. It is
+ *                     read from the OrmRequest instance, fixed at mount time,
+ *                     and no request can influence it.
+ *
+ *   context.operation The operation being authorised. Exactly one of the four
+ *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
+ *                     there is no second vocabulary, and it is never an HTTP
+ *                     method name like `'GET'`. These are the same four
+ *                     strings the permission-array return shape is written in
+ *                     (`['read', 'create']`), because both come from the one
+ *                     `methodAccessMap` below.
+ *
+ *                     `undefined` when the dispatched method has no entry in
+ *                     that map. Express delivers `HEAD` to the `GET` handler,
+ *                     so this is reachable. It is left undefined rather than
+ *                     defaulted on purpose -- a fabricated `'read'` would turn
+ *                     an unclassified request into an authorised one. Treat
+ *                     `undefined` as "not classified" and deny.
+ *
+ * So a consumer writes `if (model === 'owner' && operation === 'read')`. There
+ * is no string to parse, no variant to miss, and no way to fail open through a
+ * URL shape nobody anticipated.
+ *
+ * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
+ * matching but BEFORE any handler executes (`@stonyx/rest-server`
+ * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
+ * record would force a pre-fetch on every request, a second store hit and an
+ * ordering change in the middle of an authorization path. It is also
+ * unnecessary: the FUNCTION return shape already is the per-record hook. Return
+ * `(record) => boolean` and the handlers apply it to every record the request
+ * touches. Auth-time and record-time are separate decision points.
+ *
+ * THE SECOND ARGUMENT IS ADDITIVE. JavaScript ignores extra arguments, so an
+ * existing `access(request)` predicate keeps working exactly as before. The
+ * warning immediately below is therefore still live: `request` is still
+ * argument ONE, and reading it is still how predicates fail open.
+ *
+ * To reach ANOTHER model's predicate -- e.g. to check an animal while servicing
+ * an owners route -- use the boot-time registry:
+ *
+ *     const predicate = Orm.instance.getAccess('animal');
+ *     const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+ *
+ * Passing the context explicitly is what makes that answer model-CORRECT.
+ *
+ * ---------------------------------------------------------------------------
  * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
  * ---------------------------------------------------------------------------
  * `auth()` below hands your `access(request)` a raw transport artifact and asks
@@ -66,7 +122,7 @@ import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
-import type { OrmRecord } from './types/orm-types.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod } from './types/orm-types.js';
 import { isOrmRecord } from './utils.js';
 
 interface OrmRequest$ extends Request {
@@ -94,7 +150,6 @@ interface JsonApiResponse {
   included?: unknown[];
 }
 
-type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
 type HandlerFn = (request: OrmRequest$, state: { [key: string]: unknown }) => unknown | Promise<unknown>;
 
 const methodAccessMap: { [key: string]: string } = {
@@ -455,10 +510,10 @@ function isDenied(filter: unknown, record: unknown): boolean {
 
 export default class OrmRequest extends Request {
   model: string;
-  access: (request: unknown) => AccessMethod;
+  access: AccessFunction;
   handlers: { [key: string]: { [key: string]: HandlerFn } };
 
-  constructor({ model, access }: { model: string; access: (request: unknown) => AccessMethod }) {
+  constructor({ model, access }: { model: string; access: AccessFunction }) {
     super(...arguments as unknown as unknown[]);
 
     this.model = model;
@@ -1155,9 +1210,42 @@ export default class OrmRequest extends Request {
     // 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.
+    // -------------------------------------------------------------------------
+    // #202 -- hand the consumer the STRUCTURAL facts, not just the transport.
+    //
+    // Both members are already in hand here. `model` is `this.model`, the name
+    // setup-rest-server mounted this route for; `operation` is the SAME
+    // `methodAccessMap` lookup the permission-array branch at the bottom of
+    // this method performs, so the predicate form and the array form cannot
+    // answer differently about the same request.
+    //
+    // NEITHER IS DERIVED FROM THE REQUEST TARGET, and that is the whole point.
+    // Deriving `model` here from `request.baseUrl` (or from the mounted route
+    // name, or from `getPluralName(this.model)`) would move all five fail-open
+    // variants listed in this file's header OUT of the consumer and INTO the
+    // framework, where every consumer inherits them at once. `this.model` is
+    // assigned once at mount time and no request can influence it.
+    //
+    // `operation` is left UNDEFINED for a method with no entry in
+    // `methodAccessMap`, rather than defaulted. Express delivers HEAD to the
+    // GET handler, so an unmapped method really does reach this line; a
+    // `?? 'read'` here would hand the consumer a fabricated authorisation fact
+    // and turn an unclassified request into an authorised one. Undefined is
+    // the honest answer.
+    //
+    // `record` is deliberately absent -- see `AccessContext` in
+    // src/types/orm-types.ts. Nothing is fetched at this point and adding a
+    // lookup here would put a store read in the middle of an authorization
+    // path. The function return shape below IS the per-record hook.
+    // -------------------------------------------------------------------------
+    const context: AccessContext = {
+      model: this.model,
+      operation: methodAccessMap[request.method],
+    };
+
     let access: AccessMethod;
     try {
-      access = this.access(request);
+      access = this.access(request, context);
     } catch (error) {
       // Same reasoning as `isDenied`: fail closed, but say so. An `access()`
       // that throws denies EVERY request to the collection, and a silent 403

package/src/setup-rest-server.ts

@@ -1,5 +1,5 @@
 import { waitForModule } from 'stonyx';
-import { store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
 import OrmRequest from './orm-request.js';
 import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
@@ -7,14 +7,20 @@ import { forEachFileImport } from '@stonyx/utils/file';
 import { dbKey } from './db.js';
 import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
+import type { AccessFunction } from './types/orm-types.js';
 
 interface AccessInstance {
   models: string[] | '*';
-  access: (request: unknown) => unknown;
+  /**
+   * The consumer predicate. Called as `access(request, { model, operation })`
+   * -- the second argument is additive (abofs/stonyx-orm#202), so a predicate
+   * declared with a single parameter is still valid and still works.
+   */
+  access: AccessFunction;
 }
 
 export default async function(route: string, accessPath: string, metaRoute: boolean): Promise<void> {
-  const accessFiles: Record<string, (request: unknown) => unknown> = {};
+  const accessFiles: Record<string, AccessFunction> = {};
 
   try {
     await forEachFileImport(accessPath, (accessClass: unknown) => {
@@ -41,6 +47,29 @@ export default async function(route: string, accessPath: string, metaRoute: bool
     log.warn?.('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
   }
 
+  // -------------------------------------------------------------------------
+  // #202 -- the registry has to survive this function.
+  //
+  // `accessFiles` used to be a function-local that was discarded at the return
+  // below, so the only thing that ever saw it was the mount loop. Each mounted
+  // OrmRequest then held its OWN model's predicate and nothing held the map, so
+  // at request time there was no route from a model NAME to that model's
+  // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
+  // ask model X's predicate about a request routed to model Y.
+  //
+  // Published BEFORE `waitForModule('rest-server')` and before the mount loop,
+  // deliberately. That module may already be listening by the time it reports
+  // ready, so assigning after the mounts would leave a window in which a route
+  // exists and the registry does not.
+  //
+  // Assigned unconditionally, including when the try above failed and the map
+  // is empty or partial: the mount loop below is driven by this exact object,
+  // so whatever is reachable through `Orm.instance` is by construction the same
+  // set of predicates that is actually enforcing. A guard here that skipped the
+  // assignment would let the registry go silently missing, which is precisely
+  // the failure #202's AC8 exists to catch.
+  Orm.instance.accessFiles = accessFiles;
+
   await waitForModule('rest-server');
 
   // Remove "/" prefix and name mount point accordingly

package/src/types/orm-types.ts

@@ -168,3 +168,74 @@ export interface SnapshotEntry {
   source?: string;
   viewQuery?: string;
 }
+
+/**
+ * The shapes a consumer `access()` predicate may return.
+ *
+ * - `false` (or any falsy value) -- deny, 403.
+ * - `true` -- allow, with no per-record filter.
+ * - a permission string or array of them, drawn from the same four verbs as
+ *   {@link AccessContext.operation}. A BARE STRING IS ONE PERMISSION, not a
+ *   grant of all four.
+ * - a `(record) => boolean` predicate -- allow, and filter every record the
+ *   request touches through it.
+ *
+ * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
+ */
+export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+
+/**
+ * The structural facts about the request being authorised, handed to a consumer
+ * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
+ *
+ * These are the facts the framework already holds at authorisation time. Before
+ * #202 a consumer had to reconstruct both of them by string-matching a URL, and
+ * five independent fail-open variants of that reconstruction were found in one
+ * three-line documented example -- each one wrong in the direction that GRANTS
+ * access. Read these instead; there is nothing to parse and no variant to miss.
+ *
+ * `record` is deliberately NOT a member. `auth()` runs after route matching but
+ * before any handler executes (`@stonyx/rest-server` `src/request.ts:58-60`),
+ * so nothing has been fetched yet -- carrying a record here would force a
+ * pre-fetch on every request. It is also unnecessary: the `(record) => boolean`
+ * return shape of {@link AccessMethod} already IS the per-record hook, applied
+ * by the handlers. Auth-time and record-time are separate decision points.
+ */
+export interface AccessContext {
+  /**
+   * The model this route was mounted for, e.g. `'owner'` or `'phone-number'`.
+   *
+   * Model names are kebab-case, as declared under `config.orm.paths.model` and
+   * keyed in the store -- NOT the pluralised, mount-prefixed route name. It is
+   * read from the `OrmRequest` instance and is never derived from the request
+   * target, so a mount prefix, a case-varied path, a query string or an
+   * absolute-form request-target cannot change it.
+   */
+  model: string;
+
+  /**
+   * The operation being authorised: `'read'`, `'create'`, `'update'` or
+   * `'delete'`, and no second vocabulary. These are exactly the values of
+   * `methodAccessMap` in `src/orm-request.ts`, which is also what the
+   * permission-array return shape is matched against -- so the two forms cannot
+   * disagree.
+   *
+   * `undefined` when the dispatched method has no entry in that map. Express
+   * delivers `HEAD` to the `GET` handler, so this is reachable. It is left
+   * undefined rather than defaulted on purpose: a fabricated `'read'` would
+   * turn an unclassified request into an authorised one.
+   */
+  operation?: string;
+}
+
+/**
+ * A consumer `access()` predicate.
+ *
+ * `context` is optional in the type because the second argument is ADDITIVE:
+ * JavaScript ignores extra arguments, so every pre-#202 single-argument
+ * predicate keeps working untouched. Changing the FIRST argument instead would
+ * have been the breaking form, and a predicate that can no longer identify its
+ * collection falls through to a full CRUD grant -- so the "safer" breaking
+ * change would have converted every unmigrated predicate into a fail-open.
+ */
+export type AccessFunction = (request: unknown, context?: AccessContext) => AccessMethod;