@stonyx/orm 0.3.2-beta.155 → 0.3.2-beta.157

package/src/types/orm-types.ts

@@ -252,6 +252,102 @@ export interface AccessContext {
    * from one that classified the request and found nothing.
    */
   operation: AccessOperation | undefined;
+
+  /**
+   * The record this route was addressed to, as the store key -- or `null` on a
+   * collection route, which is addressed to no record (abofs/stonyx-orm#236).
+   *
+   * IT IS ALREADY DECODED, AND THAT IS THE WHOLE POINT. Express decodes route
+   * PARAMETERS while leaving `request.path` raw, so a consumer comparing
+   * `request.path` against a literal compares an undecoded string against a
+   * decoded dispatch. `GET /owners/%61rchived` reached such a comparison as
+   * `/%61rchived`, walked past a `/archived` deny, and was dispatched as the
+   * record `archived` -- 200 with the record in full, and `DELETE` destroyed
+   * it, unauthenticated. 255 non-canonical spellings of an 8-character id
+   * decode to the same key, so a deny-list of spellings is the wrong shape.
+   *
+   * SO DO NOT NORMALISE THIS, AND DO NOT NORMALISE ANYTHING ELSE INSTEAD:
+   *
+   * - Do NOT decode it. Express decodes exactly ONCE, which is what a route
+   *   parameter means. `GET /owners/%2561rchived` is the legitimate id
+   *   `%61rchived`, not a second-order spelling of `archived`; a predicate that
+   *   decoded until stable would deny a record it was never asked about.
+   * - Do NOT case-fold it. A record id is a VALUE, not a literal route segment,
+   *   and express's `case sensitive routing` governs literal segments only.
+   *   With a distinct owner seeded at `ARCHIVED`, `.toLowerCase()` was measured
+   *   wrong in BOTH directions at once: `GET /owners/ARCHIVED` 403 (a false
+   *   deny, on the wrong record) and `GET /owners/%41RCHIVED` 200 (a false
+   *   allow, on that same record).
+   * - Do NOT derive it from `request.path` or the request target. Decoding the
+   *   whole path decodes THEN splits, while the router splits THEN decodes, so
+   *   `/owners/archived%2fx` -- a genuinely distinct record whose id is
+   *   `archived/x` -- was measured over-denied 403.
+   *
+   * IT IS `getId(request.params)`, BYTE FOR BYTE -- the same single coercion
+   * the store lookup uses, exactly as `operation` is the same `methodAccessMap`
+   * lookup the permission-array branch uses. The predicate and the dispatch
+   * therefore cannot disagree about which record a request addresses. Handing
+   * over the raw `request.params.id` instead would reintroduce that divergence
+   * on hex-shaped ids: `GET /animals/0x2391` looks up record `9105`.
+   *
+   * It inherits abofs/stonyx-orm#209 along with that coercion -- on a model
+   * declaring `id = attr('string')`, `'9107'` arrives here as the number
+   * `9107`. That is consistency WITH THE LOOKUP, which is the property this key
+   * exists to buy; it is not a defect to repair here.
+   *
+   * `null`, not `undefined`, on a collection route -- and the KEY IS ALWAYS
+   * PRESENT, the same rule `operation` states above. `auth()` always sets it,
+   * so a context arriving WITHOUT the key did not come from `auth()`: it was
+   * hand-assembled by a caller resolving the predicate through
+   * `Orm.instance.getAccess()`. That absence stays a distinguishable, deniable
+   * signal only because the framework never produces it.
+   *
+   * IT DISAGREES WITH THE HOOK VOCABULARY, AND NOT ONLY ON THE ABSENCE
+   * SPELLING. `HookContext.recordId` (`src/hooks.ts`) is an identically-named
+   * key on an identically-shaped context object, which is the exact
+   * configuration that makes `operation` fail-open shaped -- a hook sees
+   * `'get'` where `access()` sees `'read'`. An earlier revision of THIS
+   * docblock asserted the opposite ("here they AGREE... they differ in ONE way
+   * and it is the absence spelling"). That was measured false, in the fail-open
+   * direction, and it is corrected here rather than deleted.
+   *
+   * MEASURED over the live dispatch, before-hooks registered for all five
+   * operations on one model:
+   *
+   *     before:list    key ABSENT      ('recordId' in context === false)
+   *     before:get     key ABSENT      params={"id":"visible1"}
+   *     before:create  key ABSENT
+   *     before:update  key ABSENT      params={"id":"visible2"}
+   *     before:delete  recordId="visible3"
+   *     after:delete   recordId="visible3"
+   *
+   * `_withHooks` assigns `context.recordId` at exactly TWO sites in
+   * `src/orm-request.ts`, and BOTH sit inside an `operation === 'delete'`
+   * branch. So the two keys differ in COVERAGE, on four of five operations: on
+   * a hook context the key is absent for get, list, create and update, while
+   * this key is present on every route `auth()` classifies. The absence
+   * spelling is the smaller half of the difference, not the whole of it.
+   *
+   * AND THAT INVERTS THE ARGUMENT ABOVE WHEN IT IS READ ACROSS THE TWO. Here,
+   * a missing `recordId` means "did not come from `auth()`" and is deniable.
+   * On a hook context it means "this is a get / list / create / update" -- an
+   * ordinary request. A consumer who writes the hook-side half of the same
+   * rule --
+   *
+   *     beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)
+   *
+   * -- gets a deny that NEVER FIRES: measured, `PATCH /owners/visible2` -> 200,
+   * with `ctx.recordId === undefined` while the addressed record sits in
+   * `ctx.params`. The hook side is abofs/stonyx-orm#242 and is deliberately not
+   * repaired here. A predicate must not read `undefined` here as "collection",
+   * and nothing in this contract makes it safe to read the two keys as one key.
+   *
+   * IT NAMES WHICH RECORD, NOT WHICH SURFACE. `GET /owners/gina`,
+   * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` all
+   * carry `recordId: 'gina'`; the related-resource gap is abofs/stonyx-orm#196
+   * and is untouched by this key.
+   */
+  recordId: string | number | null;
 }
 
 /**