@stonyx/orm 0.3.2-alpha.93 → 0.3.2-alpha.95

package/README.md

@@ -318,16 +318,90 @@ await setupRestServer('/', './access');
 Access classes define models and provide custom filtering/authorization logic:
 
 ```js
-export default class GlobalAccess {
-  models = ['owner', 'animal'];
+export default class OwnerAccess {
+  models = ['owner'];
 
   access(request) {
-    if (request.url.endsWith('/owner/angela')) return false;
+    // `access` runs after route matching, so `request.params` is populated and
+    // `id` has already been URL-decoded. Authorize on it, never on a URL.
+    const { id } = request.params;
+
+    // `id` is still raw client text. Normalise it the way the record lookup
+    // does, or your predicate and the lookup disagree — see "Numeric ids" below.
+    // No radix on parseInt: that is deliberate, and it must stay that way.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+
+    // Returning false explicitly denies access to this record
+    if (recordId === 'angela') return false;
+
+    // No `id` means the collection route. Returning a function plugs it in to
+    // the response object as a filter. NOTE: a function return authorizes the
+    // request outright — the operations list below is not consulted — so this
+    // branch permits POST /owners as well as reads.
+    if (recordId === undefined) return record => record.id !== 'angela';
+
+    // Returning a list of operations allows full access to everything else
+    return ['read', 'create', 'update', 'delete'];
+  }
+}
+```
+
+**Do not authorize on the request URL.** `request.url` is rewritten relative to
+the mount point, so inside the REST server it is `/angela`, not `/owners/angela`
+— a suffix comparison against it never matches and the request falls through to
+whatever the method returns next. `request.originalUrl` keeps the full path but
+is still the raw text the client sent, so it varies with query strings
+(`/owners?x=1`), trailing slashes (`/owners/angela/`), casing (`/OwNeRs/angela`,
+which Express routes to the same handler) and percent-encoding
+(`/owners/%61ngela`). Each of those is a plain address-bar request, and each one
+slips past a URL predicate. `request.params.id` is identical for all of them.
+
+**One access class per model when the rules are model-specific.** `access()`
+receives only the request, and the request does not carry the model name in any
+form that is safe to match on — `request.baseUrl` is the mount text as the
+client spelled it (`/OWNERS`), not the model. A class may still list several
+models in `models` when they share one rule.
+
+**Numeric ids: normalise before you compare.** `request.params.id` is raw text
+from the client. When it looks numeric the ORM coerces it — `isNaN(id) ? id :
+parseInt(id)` — *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`,
+`7e0`, `0x7`, `+7`, `%207` (a leading space), `%09 7` (a tab) and `7%0A` (a
+trailing newline) all address record `7`, while a `===` against the raw text
+matches only the one spelling you wrote down. Every other spelling falls through
+to whatever your method returns next — which, in the shape above, is a full CRUD
+grant. All of them are plain address-bar requests.
+
+Two details are load-bearing. `parseInt` is called with **no radix**, so `0x7`
+is `7` and not `0`; writing `parseInt(id, 10)` in your predicate re-opens the
+hex spelling. And the coercion applies only when the id looks numeric, so a
+model with string ids (like `owner` above) is unaffected — which is exactly why
+this is easy to miss. Normalise the same way the lookup does:
+
+```javascript
+export default class AnimalAccess {
+  models = ['animal'];
+
+  access(request) {
+    const { id } = request.params;
+
+    // Agrees with the lookup for every spelling of 7 above. Compare the
+    // coerced value, which for a numeric-id model is a number, not a string.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+
+    if (recordId === 7) return false;
+
+    if (recordId === undefined) return record => record.id !== 7;
+
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
+The sample above is executed verbatim against a live server by
+`test/integration/readme-access/`, which reads it out of this file: the request
+`DELETE /owners/angela` is asserted to return 403 with the record intact, along
+with each of the spellings named above.
+
 ### Upgrading: behaviour changes
 
 **Advertised `links.self` / `links.related` now carry the REST mount route.**

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.93",
+  "version": "0.3.2-alpha.95",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,8 +61,8 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.95",
-    "@stonyx/events": "0.1.1-beta.52",
+    "@stonyx/cron": "0.2.1-beta.98",
+    "@stonyx/events": "0.1.1-beta.54",
     "@stonyx/utils": "0.2.3-beta.26",
     "stonyx": "0.2.3-beta.81"
   },
@@ -91,7 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.98",
+    "@stonyx/rest-server": "0.2.1-beta.100",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",
@@ -103,8 +103,10 @@
   "scripts": {
     "build": "tsc",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts' && ORM_TEST_ROUTE=/ pnpm test:mounted && ORM_TEST_ROUTE=/api pnpm test:mounted && ORM_TEST_ROUTE=api pnpm test:mounted && ORM_TEST_ROUTE=/api/v1 pnpm test:mounted && ORM_TEST_ROUTE=/api/ pnpm test:mounted",
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts' && ORM_TEST_ROUTE=/ pnpm test:mounted && ORM_TEST_ROUTE=/api pnpm test:mounted && ORM_TEST_ROUTE=api pnpm test:mounted && ORM_TEST_ROUTE=/api/v1 pnpm test:mounted && ORM_TEST_ROUTE=/api/ pnpm test:mounted && pnpm test:readme && pnpm test:reference",
     "test:mounted": "node --import tsx/esm --import ./test/integration/mounted-route/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/mounted-route/links-mounted.ts' 'test/zz-exit-test.ts'",
+    "test:readme": "node --import tsx/esm --import ./test/integration/readme-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/readme-access/readme-sample.ts' 'test/zz-exit-test.ts'",
+    "test:reference": "node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/zz-exit-test.ts'",
     "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }