@stonyx/orm 0.3.2-beta.160 → 0.3.2-beta.162

package/dist/orm-request.d.ts

@@ -1,276 +1,4 @@
-/**
- * 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'` --
- *                     no second vocabulary ON THIS PATH, and 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.
- *
- *                     NOT the hook vocabulary. `HookContext.operation`
- *                     (`src/hooks.ts`, documented under "Hook Context Object"
- *                     in the README) carries `'list' | 'get' | 'create' |
- *                     'update' | 'delete'` on an identically-named key of an
- *                     identically-shaped context object, and the access
- *                     vocabulary collapses `list` and `get` into `'read'`. For
- *                     one `GET /animals/1` a hook sees `'get'` and `access()`
- *                     sees `'read'`, so a predicate cannot tell a collection
- *                     read from a record read. `AccessOperation` makes
- *                     `operation === 'get'` a compile error for a TypeScript
- *                     consumer, because a predicate that stops matching falls
- *                     through to the permission array -- the misreading is
- *                     fail-open shaped.
- *
- *                     `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.
- *
- * WHAT THE CONTEXT DOES NOT TELL YOU: WHICH SURFACE. It names the model and
- * the verb, not the route. Measured over the live router, six surfaces produce
- * one identical context:
- *
- *     GET /owners                          { model: 'owner', operation: 'read' }
- *     GET /owners/gina                     { model: 'owner', operation: 'read' }
- *     GET /owners/gina/pets                { model: 'owner', operation: 'read' }
- *     GET /owners/gina/relationships/pets  { model: 'owner', operation: 'read' }
- *     GET /owners/archived                 { model: 'owner', operation: 'read' }
- *     GET /owners/gina?include=pets        { model: 'owner', operation: 'read' }
- *
- * So a rule that depends on the SUB-PATH still needs `request.path` -- which is
- * mount-relative and query-free, and is the one read of argument one the
- * warning below sanctions. This repo's own fixture has such a rule: its
- * `/archived` deny cannot be expressed from the context alone, and a predicate
- * migrated to context-only would silently drop it, turning a deny into an
- * allow.
- *
- * THE RELATED-RESOURCE HALF OF THAT SENTENCE IS NOW OUT OF DATE AND IS
- * CORRECTED HERE RATHER THAN DELETED. Both relationship route families resolve
- * the RELATED model's own access class and ask it
- * `{ model: <related>, operation: 'read', recordId: null }`
- * (abofs/stonyx-orm#232), so those surfaces no longer serve another model's
- * records under `model: 'owner'` unexamined. What the context still gives no
- * signal of is WHICH related record is being asked about -- `recordId` is
- * `null` there and `request.params` names a record of a different model. See
- * `AccessContext.recordId` in ./types/orm-types.ts for the full statement of
- * that limit. `?include=` is still unfiltered and is abofs/stonyx-orm#233 /
- * #235.
- *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237, AND KEPT FOR THE
- * CONSTRAINT IT STATES RATHER THAN AS A DESCRIPTION OF THE CODE. The context
- * now also carries `recordId` -- the DECODED route-parameter id, see
- * `AccessContext.recordId` in ./types/orm-types.ts -- so the fixture's
- * `/archived` deny IS expressible from the context alone, and the shipped
- * sample no longer reads `request.path` at all. Retiring this wording WITH the
- * measurement that retires it, rather than by deletion, is
- * abofs/stonyx-orm#238.
- *
- * `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');
- *     if (!predicate) return deny;
- *     const verdict = predicate(request, { model: 'animal', operation: 'read' });
- *
- * `undefined` means NO PREDICATE COULD BE RESOLVED for that name -- which
- * includes the case where the model has an access class that failed to load,
- * because `setup-rest-server.ts` catches a load failure, warns, and publishes
- * whatever partial map it had. It does NOT mean the model is unrestricted.
- * Treat it as DENY, the same way `operation === undefined` is treated above.
- *
- * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not make
- * the answer model-correct on its own -- the resolved predicate has to READ it.
- * Measured against an ARITY-1 predicate, on a request express dispatched to
- * `GET /owners/angela`, asked about ANIMALS:
- *
- *     getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
- *       ->  record => record.id !== 'angela' && record.id !== 'restricted'
- *
- * That is the OWNERS filter, and it returns `true` for animal 21 -- the record
- * hidden on every animal surface. Under a mount that predicate recognises
- * neither way it is worse: it falls through to
- * `['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
- * context was supplied and the answer is not the animal answer, and it is wrong
- * in the GRANTING direction, because that predicate is arity-1 and identifies
- * its collection from the request. (Asserted on a live dispatch by AC9 in
- * test/integration/orm-test.ts, against a deliberately arity-1 predicate.)
- *
- * This repo's own sample access class has since been MIGRATED to read the
- * context (abofs/stonyx-orm#222), so `getAccess('animal')` here now answers
- * with the animal filter. That is not true of a consumer tree: an arity-1
- * predicate keeps working -- the second argument is additive -- and the caller
- * has no supported way to tell which kind it got. The boot-time arity warning
- * that surfaces one is abofs/stonyx-orm#221.
- * So: pass the context, and do not treat a resolved predicate's answer as
- * model-specific until that predicate has been migrated to read the context.
- *
- * ---------------------------------------------------------------------------
- * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
- * ---------------------------------------------------------------------------
- * You do not have to. `auth()` below hands your predicate the ACCESS CONTEXT as
- * argument two, and `context.model` already names the collection -- see the
- * contract section above. Argument ONE is still the raw transport artifact, and
- * everything from here to the end of this banner is the record of what happened
- * when predicates worked the collection out from it. IT IS HISTORY, NOT
- * GUIDANCE: do not write any of it into a new predicate. Every attempt to
- * identify the collection by parsing the request target has failed OPEN. Five
- * distinct variants of the same three-line example have now been found, each
- * after the previous was fixed, by five different people:
- *
- *   1. `request.url` is mount-relative under `RestServer.mountRoute`, so a
- *      prefix match against it is ALWAYS false.
- *   2. `request.originalUrl` carries the query string, so an anchored equality
- *      check misses `/owners?filter[age]=30`.
- *   3. The router is a bare `express()` (`caseSensitive: false`) while a
- *      hand-written matcher is case-SENSITIVE, so `GET /OwNeRs/angela` walks
- *      past it. Router-side: abofs/stonyx-rest-server#47.
- *   4. Under a configured `ORM_REST_ROUTE` a hard-coded `/owners` matches
- *      nothing -- environment-specifically, which is worse.
- *   5. HTTP/1.1 permits an ABSOLUTE-FORM request-target. Express routes on
- *      `parseurl(req).pathname`, but `originalUrl` is the raw target, so
- *      `GET http://anything.example/owners/angela` reaches the handler with
- *      `originalUrl === 'http://anything.example/owners/angela'`. A `/owners`
- *      prefix match is false, `access()` falls through to whatever it returns
- *      last, and the record comes back in full. It walks past a hard
- *      `return false` deny the same way.
- *
- * The fix is not a sixth rule, and it is not a better string to match. It is to
- * stop identifying the collection at all: read `context.model`. That is a claim
- * about IDENTIFYING THE COLLECTION, not about the sample as a whole -- the
- * `/archived` SUB-PATH rule is still a string match, and abofs/stonyx-orm#228 is
- * a sixth spelling that gets past it.
- *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: the `/archived` rule is
- * no longer a string match against the request target -- it compares the
- * decoded `recordId` the framework supplies -- and abofs/stonyx-orm#228 is
- * CLOSED. Retirement of this wording: abofs/stonyx-orm#238.
- *
- *   An intermediate revision of the sample read `request.baseUrl` -- the mount
- *   Express ACTUALLY MATCHED. That closed all five variants (no query string,
- *   not mount-relative, unaffected by absolute-form, already carrying the
- *   configured `ORM_REST_ROUTE` prefix), but it was a transport artifact
- *   standing in for a structural fact and the sample no longer does it.
- *   `context.model` IS the structural fact, so variants 1, 2, 4 and 5 are
- *   unconstructible against a migrated predicate rather than handled.
- *
- *   VARIANT 3 SURVIVES, and is deliberately not in that list. It is the general
- *   shape "a hand-written matcher normalises differently from the router", and a
- *   migrated predicate still runs one string comparison for any SUB-PATH rule --
- *   in the shipped sample, the `/archived` deny. That comparison folds case but
- *   does not decode, so `GET /owners/%61rchived` steps past it. See the
- *   normalisation paragraph below and abofs/stonyx-orm#228.
- *
- *   SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237. Variant 3 lived in that
- *   one string comparison, and the comparison is gone: the sample compares the
- *   decoded `recordId`. Left standing rather than edited because the same
- *   "variant 3 survives" wording sits at four sites -- this header, README.md
- *   twice, and test/sample/access/global-access.ts -- three of which SHIP, so
- *   retiring one of four leaves the shipped copies contradicting each other.
- *   Retiring all four WITH their measurement is abofs/stonyx-orm#238.
- *
- * ONE READ OF ARGUMENT ONE SURVIVES, AND IT MUST: `request.path`. It is
- * mount-relative and query-free, and it is for rules that distinguish SUB-PATHS
- * beneath the mount. The context names which model and which verb, NOT which
- * route, so the sample's `/archived` deny cannot be expressed from the context
- * alone and a context-ONLY rewrite would silently turn that deny into an allow.
- *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: NO read of argument one
- * survives in the shipped sample. `recordId` names WHICH RECORD the route was
- * addressed to, so the `/archived` deny is expressible from the context alone
- * -- and it still must not be dropped; expressible is not optional. Retirement
- * of this wording: abofs/stonyx-orm#238.
- *
- * NORMALISE THE WAY THE ROUTER DOES, AND CASE-FOLDING ALONE IS NOT THAT. The
- * sample lower-cases before comparing, because a matcher stricter than the
- * case-insensitive router can be stepped around. That closes the case gap only.
- * Express sets `request.path` from the RAW, UNDECODED pathname while the router
- * DECODES `:id`, so `GET /owners/%61rchived` reaches a `path === '/archived'`
- * comparison as `/%61rchived` and walks past the deny. That gap is live in the
- * sample and is tracked as abofs/stonyx-orm#228; the `.toLowerCase()` is not a
- * complete normalisation recipe. Compare record ids at their real case.
- *
- * DO NOT FOLLOW THE PARAGRAPH ABOVE. SUPERSEDED 2026-09-01 BY
- * abofs/stonyx-orm#236/#237, and flagged here rather than merely dated because
- * it is an INSTRUCTION, not a stale observation. `.toLowerCase()` on the access
- * path was measured WRONG IN BOTH DIRECTIONS AT ONCE: with a distinct owner
- * seeded at `ARCHIVED`, `GET /owners/ARCHIVED` was a false DENY on the wrong
- * record and `GET /owners/%41RCHIVED` a false ALLOW on that same record. A
- * record id is a VALUE, not a literal route segment, and express's
- * `case sensitive routing` governs literal segments only. Compare
- * `context.recordId` AS IT ARRIVES: do not case-fold it, do not decode it, do
- * not derive it from `request.path`. `AccessContext.recordId` in
- * ./types/orm-types.ts is the contract and says "Do NOT case-fold it"; the same
- * published tarball ships both files, and THIS paragraph is the one that is
- * wrong. Retiring it WITH its measurement is abofs/stonyx-orm#238.
- *
- * `?? ''` is not a defence. It converts an absent request target into an empty
- * string, which matches no collection, which falls through to the permission
- * array -- a total grant. An input you cannot identify must DENY, and that
- * applies to BOTH arguments: since #202 the guard and the read can sit on
- * different objects, and a guard on argument two does not protect a read of
- * argument one. The sample returns `false` for an absent `model` AND for an
- * absent or non-string `request.path`, rather than falling through either way.
- *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237 as to WHAT is guarded --
- * the principle is unchanged. The sample no longer reads `request.path`, so it
- * returns `false` for an absent `model` AND for an absent `recordId`
- * (`undefined`, the one spelling `auth()` never produces). Retirement of this
- * wording: abofs/stonyx-orm#238.
- *
- * THE REAL FIX IS abofs/stonyx-orm#202: `access()` should receive the model,
- * the operation and the record. Prefer the array shape (`['read']`) or `false`
- * until #202 lands; the function shape is what requires any matching at all.
- *
- * The enforcement gates in this file (GATE 0/1/2, the create rollback, the
- * per-handler `isDenied` re-checks) are correct independently of that -- they
- * enforce whatever predicate you return. The stopgap is the part where YOU have
- * to work out which predicate to return.
- *
- * AND A PREDICATE IS NOT A GUARANTEE THAT A HIDDEN RECORD CANNOT BE MODIFIED.
- * It is evaluated against the record the route is ADDRESSED TO, on that model
- * only. A write to a DIFFERENT collection can still re-parent a hidden record
- * and de-hide it -- abofs/stonyx-orm#207, which is blocked on #202 and #196.
- * 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;
@@ -285,12 +13,13 @@ 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: AccessFunction;
+    access: (request: unknown) => AccessMethod;
     handlers: {
         [key: string]: {
             [key: string]: HandlerFn;
@@ -298,7 +27,7 @@ export default class OrmRequest extends Request {
     };
     constructor({ model, access }: {
         model: string;
-        access: AccessFunction;
+        access: (request: unknown) => AccessMethod;
     });
     private _withHooks;
     private _generateRelationshipRoutes;