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

package/dist/index.d.ts

@@ -9,7 +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 type { AccessContext, AccessFunction, AccessMethod, AccessOperation } 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

@@ -81,8 +81,23 @@ export default class Orm {
      * collection the request is ADDRESSED TO -- owners -- while being asked about
      * animals, and per #202's thesis it answers wrong in the granting direction.
      *
+     * OWN PROPERTIES ONLY. A bare `this.accessFiles[modelName]` walks the
+     * prototype chain, so `getAccess('constructor')` resolved `Object` and
+     * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+     * callable, and the documented `predicate?.(request, ctx)` pattern then
+     * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+     * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+     * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+     * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+     * which would have made a one-field body an authorization bypass. Guarded
+     * here at the read point rather than by constructing the map with a null
+     * prototype, because the field is public and reassignable and the guard has
+     * to hold whatever object it is holding.
+     *
      * @param modelName - Model name as declared and stored (kebab-case).
-     * @returns The predicate, or `undefined` when the model has no access class.
+     * @returns The predicate, or `undefined` when no predicate could be resolved
+     *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+     *   note above. Treat it as deny.
      */
     getAccess(modelName: string): AccessFunction | undefined;
     startup(): Promise<void>;

package/dist/main.js

@@ -187,10 +187,27 @@ export default class Orm {
      * collection the request is ADDRESSED TO -- owners -- while being asked about
      * animals, and per #202's thesis it answers wrong in the granting direction.
      *
+     * OWN PROPERTIES ONLY. A bare `this.accessFiles[modelName]` walks the
+     * prototype chain, so `getAccess('constructor')` resolved `Object` and
+     * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+     * callable, and the documented `predicate?.(request, ctx)` pattern then
+     * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+     * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+     * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+     * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+     * which would have made a one-field body an authorization bypass. Guarded
+     * here at the read point rather than by constructing the map with a null
+     * prototype, because the field is public and reassignable and the guard has
+     * to hold whatever object it is holding.
+     *
      * @param modelName - Model name as declared and stored (kebab-case).
-     * @returns The predicate, or `undefined` when the model has no access class.
+     * @returns The predicate, or `undefined` when no predicate could be resolved
+     *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+     *   note above. Treat it as deny.
      */
     getAccess(modelName) {
+        if (!Object.hasOwn(this.accessFiles, modelName))
+            return undefined;
         return this.accessFiles[modelName];
     }
     async startup() {

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

@@ -176,6 +176,20 @@ export interface SnapshotEntry {
  * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
  */
 export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+/**
+ * The closed vocabulary `AccessContext.operation` is drawn from
+ * (abofs/stonyx-orm#202).
+ *
+ * A literal union rather than `string`, so the guarantee the prose makes is the
+ * one the compiler enforces: a consumer who writes `operation === 'GET'` or
+ * `operation === 'get'` -- the hook vocabulary, see below -- gets a compile
+ * error instead of a comparison that never matches. A predicate that stops
+ * matching falls through to the permission array, so the misreading is
+ * fail-open shaped.
+ *
+ * In-repo precedent: `PersistErrorDetail.operation` in `src/main.ts`.
+ */
+export type AccessOperation = 'read' | 'create' | 'update' | 'delete';
 /**
  * The structural facts about the request being authorised, handed to a consumer
  * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
@@ -205,27 +219,47 @@ export interface AccessContext {
      */
     model: string;
     /**
-     * The operation being authorised: `'read'`, `'create'`, `'update'` or
-     * `'delete'`, and no second vocabulary. These are exactly the values of
+     * The operation being authorised. Exactly one of the four {@link
+     * AccessOperation} verbs, or `undefined`. 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.
      *
+     * NOT the hook vocabulary. `HookContext.operation` (`src/hooks.ts`) 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'`. "No second vocabulary" is a
+     * statement about the ACCESS path only.
+     *
      * `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.
+     *
+     * The KEY is required even though the value may be undefined: `auth()` always
+     * sets it, and a context that simply omitted it would be indistinguishable
+     * from one that classified the request and found nothing.
      */
-    operation?: string;
+    operation: AccessOperation | undefined;
 }
 /**
  * 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.
+ * 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.
+ *
+ * `context` is nonetheless REQUIRED in the type, and that costs back-compat
+ * nothing. TypeScript already lets a fewer-parameter implementation satisfy a
+ * more-parameter signature, so an arity-1 predicate assigns to this type
+ * cleanly -- measured under `--strict`. What the `?` bought was the opposite of
+ * safety: it silently permitted `getAccess('animal')?.(request)` at the CALL
+ * site, i.e. exactly the omission {@link AccessContext} exists to prevent, and
+ * that call gets the model-wrong answer. Required, a caller that drops the
+ * context gets `TS2554: Expected 2 arguments, but got 1`.
  */
-export type AccessFunction = (request: unknown, context?: AccessContext) => AccessMethod;
+export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;

package/package.json

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

package/src/index.ts

@@ -27,7 +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 type { AccessContext, AccessFunction, AccessMethod, AccessOperation } 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

@@ -240,10 +240,27 @@ export default class Orm {
    * collection the request is ADDRESSED TO -- owners -- while being asked about
    * animals, and per #202's thesis it answers wrong in the granting direction.
    *
+   * OWN PROPERTIES ONLY. A bare `this.accessFiles[modelName]` walks the
+   * prototype chain, so `getAccess('constructor')` resolved `Object` and
+   * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+   * callable, and the documented `predicate?.(request, ctx)` pattern then
+   * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+   * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+   * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+   * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+   * which would have made a one-field body an authorization bypass. Guarded
+   * here at the read point rather than by constructing the map with a null
+   * prototype, because the field is public and reassignable and the guard has
+   * to hold whatever object it is holding.
+   *
    * @param modelName - Model name as declared and stored (kebab-case).
-   * @returns The predicate, or `undefined` when the model has no access class.
+   * @returns The predicate, or `undefined` when no predicate could be resolved
+   *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+   *   note above. Treat it as deny.
    */
   getAccess(modelName: string): AccessFunction | undefined {
+    if (!Object.hasOwn(this.accessFiles, modelName)) return undefined;
+
     return this.accessFiles[modelName];
   }
 

package/src/orm-request.ts

@@ -122,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, AccessContext, AccessFunction, AccessMethod } from './types/orm-types.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
 import { isOrmRecord } from './utils.js';
 
 interface OrmRequest$ extends Request {
@@ -152,7 +152,7 @@ interface JsonApiResponse {
 
 type HandlerFn = (request: OrmRequest$, state: { [key: string]: unknown }) => unknown | Promise<unknown>;
 
-const methodAccessMap: { [key: string]: string } = {
+const methodAccessMap: { [key: string]: AccessOperation } = {
   GET: 'read',
   POST: 'create',
   DELETE: 'delete',

package/src/types/orm-types.ts

@@ -184,6 +184,21 @@ export interface SnapshotEntry {
  */
 export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
 
+/**
+ * The closed vocabulary `AccessContext.operation` is drawn from
+ * (abofs/stonyx-orm#202).
+ *
+ * A literal union rather than `string`, so the guarantee the prose makes is the
+ * one the compiler enforces: a consumer who writes `operation === 'GET'` or
+ * `operation === 'get'` -- the hook vocabulary, see below -- gets a compile
+ * error instead of a comparison that never matches. A predicate that stops
+ * matching falls through to the permission array, so the misreading is
+ * fail-open shaped.
+ *
+ * In-repo precedent: `PersistErrorDetail.operation` in `src/main.ts`.
+ */
+export type AccessOperation = 'read' | 'create' | 'update' | 'delete';
+
 /**
  * The structural facts about the request being authorised, handed to a consumer
  * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
@@ -214,28 +229,48 @@ export interface AccessContext {
   model: string;
 
   /**
-   * The operation being authorised: `'read'`, `'create'`, `'update'` or
-   * `'delete'`, and no second vocabulary. These are exactly the values of
+   * The operation being authorised. Exactly one of the four {@link
+   * AccessOperation} verbs, or `undefined`. 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.
    *
+   * NOT the hook vocabulary. `HookContext.operation` (`src/hooks.ts`) 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'`. "No second vocabulary" is a
+   * statement about the ACCESS path only.
+   *
    * `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.
+   *
+   * The KEY is required even though the value may be undefined: `auth()` always
+   * sets it, and a context that simply omitted it would be indistinguishable
+   * from one that classified the request and found nothing.
    */
-  operation?: string;
+  operation: AccessOperation | undefined;
 }
 
 /**
  * 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.
+ * 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.
+ *
+ * `context` is nonetheless REQUIRED in the type, and that costs back-compat
+ * nothing. TypeScript already lets a fewer-parameter implementation satisfy a
+ * more-parameter signature, so an arity-1 predicate assigns to this type
+ * cleanly -- measured under `--strict`. What the `?` bought was the opposite of
+ * safety: it silently permitted `getAccess('animal')?.(request)` at the CALL
+ * site, i.e. exactly the omission {@link AccessContext} exists to prevent, and
+ * that call gets the model-wrong answer. Required, a caller that drops the
+ * context gets `TS2554: Expected 2 arguments, but got 1`.
  */
-export type AccessFunction = (request: unknown, context?: AccessContext) => AccessMethod;
+export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;

package/src/types/stonyx-rest-server.d.ts

@@ -5,7 +5,20 @@ declare module '@stonyx/rest-server' {
 
   interface RouteOptions {
     name: string;
-    options?: { model: string; access: (request: unknown) => unknown } | Record<string, unknown>;
+    /**
+     * `access` is the two-argument post-#202 shape. This is the THIRD place the
+     * contract is declared (`AccessInstance.access` in
+     * `src/setup-rest-server.ts` and `OrmRequest.access` in
+     * `src/orm-request.ts` are the other two) and it is the one `mountRoute` is
+     * actually called through, at `src/setup-rest-server.ts`. It kept the
+     * pre-#202 single-argument signature after the other two migrated; the
+     * union with `Record<string, unknown>` meant nothing broke, which is
+     * exactly why it would have drifted silently.
+     *
+     * Spelled structurally rather than as `AccessFunction`: an ambient
+     * `declare module` block cannot carry an `import type`.
+     */
+    options?: { model: string; access: (request: unknown, context: { model: string; operation: string | undefined }) => unknown } | Record<string, unknown>;
   }
 
   export default class RestServer {