@stonyx/rest-server 0.2.1-beta.91 → 0.2.1-beta.92

package/README.md

@@ -81,23 +81,30 @@ Configuration is read from `stonyx/config` under `restServer`:
 | `enableHealthCheck` |   **Boolean**     | `true`      | Register `GET /health` endpoint (disable via `REST_HEALTH_CHECK_DISABLE=true`) |
 | `caseSensitiveRoutes` | **Boolean**   | `true`      | Match route paths case-sensitively. Disable via `REST_CASE_SENSITIVE_ROUTES=false`. See [Route Matching Strictness](#route-matching-strictness) — **disabling this re-opens a security hole**. |
 | `strictRoutes`    | **Boolean**   | `true`      | Match route paths strictly, so a trailing slash does not match a route registered without one. Disable via `REST_STRICT_ROUTES=false`. See [Route Matching Strictness](#route-matching-strictness) — **disabling this re-opens a security hole**, and note `GET /health/` now 404s. |
+| `canonicalRoutes` | **Boolean**   | `true`      | Reject a request whose raw target is not the canonical path express matched, before your `auth` hook runs. Disable via `REST_CANONICAL_ROUTES=false`. See [Route Matching Strictness](#route-matching-strictness) — **disabling this re-opens a security hole**, and note `GET /route/` at a mount root and every absolute-form request target now 404 on the routes this module registers (see the scope limit under [Upgrading](#upgrading-behaviour-changes)). |
 |  `trustProxy`   |     **Boolean**     | `false`     | Trust reverse proxy headers (e.g. `X-Forwarded-Proto`). Enable via `REST_TRUST_PROXY=true` when running behind a load balancer such as AWS ALB/ELB to ensure correct protocol detection. |
 |    `statusMap`    |      **Object**     | `{}`        | Optional mapping of HTTP status codes to custom messages   |
 
 ### Route Matching Strictness
 
-Routes match **case-sensitively and strictly by default**. Two settings, both
-on, both applied at both express construction sites:
+Routes match **case-sensitively, strictly, and only at their canonical target
+by default**. Three controls, all on:
 
-| axis | setting | example that no longer matches |
+| axis | control | example that no longer matches |
 |---|---|---|
-| casing | `case sensitive routing` | `GET /users/Success` -> does not reach `/success` |
-| trailing slash | `strict routing` | `GET /users/success/` -> does not reach `/success` |
+| casing | `case sensitive routing` (setting) | `GET /users/Success` -> does not reach `/success` |
+| trailing slash | `strict routing` (setting) | `GET /users/success/` -> does not reach `/success` |
+| canonical target | `canonicalRoutes` (per-request check) | `GET /users/` and `GET http://host/users` -> do not reach the mounted `/users` class |
+
+The first two are express settings applied at both construction sites. The
+third is **not a setting** — no express setting can express it — it is a
+per-request comparison of the raw request target against the path express
+matched, run ahead of your `auth` hook. See
+[`src/route-matching.ts`](src/route-matching.ts).
 
 Read [What this does not do](#what-this-does-not-do) and
-[Upgrading](#upgrading-behaviour-changes) before you rely on that. Two things
-the table does not say: "does not reach the handler" is not the same as "404",
-and one edge of the trailing-slash axis is **not** closed and cannot be.
+[Upgrading](#upgrading-behaviour-changes) before you rely on that. One thing the
+table does not say: "does not reach the handler" is not the same as "404".
 
 This is deliberate and security-relevant. Express matches both case-insensitively
 and slash-insensitively by default, which means any authorization written
@@ -128,11 +135,10 @@ be the exact registered spelling, in the exact registered casing, with no
 trailing slash. That closes [#47](https://github.com/abofs/stonyx-rest-server/issues/47)
 and [#50](https://github.com/abofs/stonyx-rest-server/issues/50).
 
-#### What this does not do
+#### The canonical-target check (`canonicalRoutes`)
 
-**It does not close the trailing slash on a mount root, and no setting can.**
-This is the one edge that remains open, so do not read the section above as
-closing the class outright:
+**No express *setting* closes the trailing slash on a mount root**, and that has
+not changed:
 
 ```
 GET /public   -> req.path '/'   req.originalUrl '/public'
@@ -144,16 +150,62 @@ unconditionally (`router@2.2.0`; the file-and-line citation is in
 [`docs/project-structure.md`](docs/project-structure.md) § *Strict routing
 (#50)*), so both forms reach the mounted route class and both arrive with
 `req.path === '/'`. A hook authorizing on `req.path` cannot tell them apart, so
-for that hook there is no asymmetry to exploit. **A hook comparing
-`req.originalUrl` still sees two different strings, and `strictRoutes` does not
-change that.** If your authorization compares `req.originalUrl` rather than
-`req.path`, keep whatever URL normalization you have.
+for that hook there is no asymmetry to exploit — and there is nothing for
+`strict routing` to reject. **A hook comparing `req.originalUrl` sees two
+different strings**, and that was a live authorization bypass.
+
+`canonicalRoutes` closes it, as a per-request check rather than a setting
+([#54](https://github.com/abofs/stonyx-rest-server/issues/54)). Before your
+`auth` hook runs, the raw request target is compared against the path express
+matched, and a mismatch is rejected as a plain 404. It closes **two** vectors
+against `req.originalUrl` — the field express does not normalize:
+
+```
+                                   before   after
+GET /admin                           401      401   (hook fires, request blocked)
+GET /admin/                          200      404   (hook never fired; now a miss)
+GET http://host/admin                200      404   (absolute-form; hook never fired)
+GET http://host/admin/settings       200      404   (absolute-form; every route from a request class)
+```
+
+The second vector is the one to check first. [RFC 9112
+§3.2.2](https://www.rfc-editor.org/rfc/rfc9112#section-3.2.2) permits an
+**absolute-form** request target, express routes it, and it hands your hook the
+whole URI — `req.originalUrl === "http://host/admin"`. Unlike the mount-root
+slash, that affects **every route mounted from a request class**, not one edge.
+The qualifier is a registration-site limit, not a special case for one URL: the
+check runs inside the handlers this module registers, so anything you register
+directly on `RestServer.instance.api` is outside it. In this repo that is
+`/health` alone, and `GET http://host/health` still returns 200 — measured.
+
+The target is compared **raw**. It is not parsed, normalized or resolved first:
+normalizing it would launder exactly the string your hook is exposed to and
+re-open the absolute-form vector by construction. Only the query string is
+removed before comparison, so `GET /admin?x=1` still reaches your hook — **strip
+the query yourself** if your hook compares `req.originalUrl` against a fixed
+path, or it will not match (see [Consumer
+Contracts](#consumer-contracts)). Rejections are indistinguishable from a
+genuine miss by design; see [Upgrading](#upgrading-behaviour-changes).
+
+Routes registered *with* a literal trailing slash are unaffected — their
+canonical target carries the slash. So are index-mounted route classes and
+query strings on canonical paths.
+
+**Param routes: "unaffected" means "no regression", not "no residual".**
+`/resource/:id` keeps matching exactly as it did. But percent-encoding is not
+normalized on either side of the comparison — express decodes only
+`req.params`, not `req.path` and not `req.originalUrl` — so `target` and
+`canonical` are *both* the encoded string and this check passes the request
+through by construction. Measured on a hook that authorizes on
+`req.originalUrl` with the query correctly stripped, on a `/:id` route:
+`GET /enc/secret` → 401, `GET /enc/%73ecret` → **200 with the guarded handler
+running unauthenticated**, identically before and after this change. It is a
+residual, not something `canonicalRoutes` introduced, and it is **wider** than
+the two vectors above: `%73` defeats a `req.path` hook as well. Tracked as
+[#56](https://github.com/abofs/stonyx-rest-server/issues/56) — until it ships,
+do not read a param-segment route class as covered on this axis.
 
-No *setting* closes this, but the module can:
-[#54](https://github.com/abofs/stonyx-rest-server/issues/54) tracks closing it
-with a canonical-path check ahead of the `auth` hook. Until that ships, an
-`originalUrl` hook is bypassed by one character — `GET /admin` denied,
-`GET /admin/` reaching the route class's index handler.
+#### What this does not do
 
 **It does not normalize path *parameter values*.** If your `auth()` hook rejects
 `params.id === 'restricted'`, then `GET /private/RESTRICTED` still reaches the
@@ -182,7 +234,36 @@ another variant of the bug above.
 
 #### Upgrading: behaviour changes
 
-Both settings change which requests match, so both are consumer-visible.
+All three controls change which requests match, so all three are
+consumer-visible.
+
+**Clients or forward proxies sending absolute-form request targets now get 404
+on every route mounted from a request class.** `GET http://host/admin HTTP/1.1`
+is a legal request target
+([RFC 9112 §3.2.2](https://www.rfc-editor.org/rfc/rfc9112#section-3.2.2)), and
+express used to route it. It is now rejected on every route this module
+registers — for a client that emits it, this is a total outage, not a partial
+one, and it is the largest blast radius in this change. The one carve-out is a
+**registration site**, not a route: the check lives in the handlers mounted from
+your request classes, so anything registered directly on
+`RestServer.instance.api` never reaches it. `GET /health` is the only such route
+in this repo, and `GET http://host/health` still returns 200 — so do not use it
+to confirm the new rejection is live, and do not assume an authorized route you
+registered on `api` yourself is covered. Reverse proxies in normal use (nginx,
+HAProxy, AWS ALB) send origin-form and are unaffected; **forward** proxies and
+hand-rolled HTTP clients are the exposure. Remediation is
+`REST_CANONICAL_ROUTES=false`, or fix the client.
+
+**`GET /route/` at a mounted route class's root now returns 404.** Previously
+200. If a client appends a trailing slash to a mount root, it stops working.
+
+Both rejections are **indistinguishable from a route that was never
+registered** — same status, same `Content-Type`, same headers — which is the
+intended security property: a distinguishable rejection is an oracle telling an
+attacker the route exists and was merely spelled wrong. Combined with this
+module emitting **no request logging**, a broken client shows up as a bare
+`Cannot GET …` with nothing at all on the server side. **Check this first if
+routes start 404ing after upgrade.**
 
 **`GET /health/` now returns 404.** `GET /health` is unaffected. This is the
 change most likely to page someone, and it is an **availability** problem rather
@@ -208,21 +289,31 @@ no log line and no stack, so it looks like a deploy that dropped a route.
 
 #### Opting out
 
-Two separate flags, one per axis:
+Three separate flags, one per axis:
 
 ```bash
 REST_CASE_SENSITIVE_ROUTES=false   # restores case-insensitive matching (#47)
 REST_STRICT_ROUTES=false           # restores trailing-slash tolerance (#50)
+REST_CANONICAL_ROUTES=false        # restores non-canonical request targets (#54)
 ```
 
-or equivalently `restServer: { caseSensitiveRoutes: false, strictRoutes: false }`.
+or equivalently
+`restServer: { caseSensitiveRoutes: false, strictRoutes: false, canonicalRoutes: false }`.
 
-**They are deliberately separate keys, and neither implies the other.** Slash
+**They are deliberately separate keys, and none implies the others.** Slash
 tolerance is a legitimate need — a health-check URL you cannot change today is
 the common case. Casing tolerance almost never is. Folding them into one flag
 would force anyone who needs the first to accept the second, which is why a
 consumer who took the `#47` opt-out still has to set `REST_STRICT_ROUTES=false`
-separately to keep trailing slashes working.
+separately to keep trailing slashes working. `REST_CANONICAL_ROUTES=false` is
+separate for the same reason: a consumer who needs mount-root slash tolerance
+should not have to re-open `#50`'s sub-path bypass to get it.
+
+`REST_CANONICAL_ROUTES=false` is a **temporary remediation**, not a
+configuration to run on. It re-opens both `#54` vectors at once — the mount-root
+slash *and* the absolute-form target — against any hook authorizing on
+`req.originalUrl`. It is env-only, so restoring service does not need a
+redeploy; use it to stop the bleeding, then fix the client and remove it.
 
 **Each flag restores the corresponding vulnerability described above** — the
 URL-based authorization in your application becomes bypassable along that axis
@@ -230,6 +321,22 @@ again. They exist as one-line remediations for an existing deployment, not as a
 configuration to run on. Set the flag to restore service, then fix the client
 and remove the flag.
 
+### Consumer Contracts
+
+Three things this module deliberately does **not** do for you. Each is a state
+the framework permits, only your own discipline prevents, and that produces **no
+error and no log** when that discipline lapses — so they are collected here
+rather than left implied by the sections above.
+
+| you must | because | symptom if you don't |
+|---|---|---|
+| **Strip the query string** before comparing `req.originalUrl` to a fixed path in an `auth` hook | `canonicalRoutes` compares the query-*stripped* target — a query string is a legitimately variable part of a request target, and rejecting on it would 404 every `?`-carrying request | `GET /admin?x=1` reaches your guarded handler **unauthenticated**, 200, no error, no log. Measured identical before and after `canonicalRoutes` |
+| **Compare param values with the same decoding and casing you look them up with** | express decodes only `req.params`; `req.path` and `req.originalUrl` both stay percent-encoded, and param *values* are never case-normalized | `GET /orders/%73ecret` runs the handler with `id === "secret"` while your hook compared `%73ecret` and did not match — unauthenticated 200. Tracked as [#56](https://github.com/abofs/stonyx-rest-server/issues/56) |
+| **Return `undefined` from `auth()` to mean "authorized"** — never `0` | any integer return is sent as the HTTP status | returning `0` sends a `0` status rather than allowing the request |
+
+`test/sample/requests/admin.ts` in this repo is the worked example of a
+correctly-written `originalUrl` hook for the first row.
+
 ### Running Behind a Load Balancer
 
 When your application runs behind a reverse proxy or load balancer (e.g. AWS ALB/ELB), the load balancer terminates SSL and forwards requests to your server over HTTP internally. This means Express sees `http` as the protocol even though the original client request used `https`.

package/config/environment.js

@@ -1,4 +1,5 @@
 const {
+  REST_CANONICAL_ROUTES,
   REST_CASE_SENSITIVE_ROUTES,
   REST_CORS_ORIGIN,
   REST_CORS_METHODS,
@@ -22,13 +23,20 @@ const config = {
   // stubs `caseSensitiveRoutes` to `undefined` and src/route-matching.ts reads
   // `!== false`, so AC6 guards the source's read and not this default.
   // Measured: pin `caseSensitiveRoutes: true` in test/config/environment.ts AND
-  // invert this line, and the suite reports 28 pass / 0 fail. A naive pin makes
+  // invert this line, and the suite reports 34 pass / 0 fail. A naive pin makes
   // an insecure published default completely invisible to a green suite --
   // quieter and weaker, which is the outcome pinning was supposed to prevent.
+  // Inverting this line ALONE, unpinned, reports 31 pass / 3 fail (#47's AC3,
+  // AC4 and AC5; AC6 green).
   //
   // The cost of leaving it unpinned is that the suite is ambient-sensitive here
-  // (`REST_CASE_SENSITIVE_ROUTES=false pnpm test` => 25 pass / 3 fail), but it
-  // fails LOUDLY, so there is no false green. Closing #43 for this key needs
+  // (`REST_CASE_SENSITIVE_ROUTES=false pnpm test` => 31 pass / 3 fail), but it
+  // fails LOUDLY, so there is no false green.
+  //
+  // Every count in this block was re-measured against the 34-test suite at
+  // #54's head. PASS totals here move whenever a test is ADDED anywhere in the
+  // repo -- the FAIL counts are the load-bearing half. Re-measure, do not
+  // adjust by arithmetic, when this block next looks stale. Closing #43 for this key needs
   // the subprocess-based env isolation this repo does not yet have; any fix
   // must keep a live assertion on this default.
   caseSensitiveRoutes: REST_CASE_SENSITIVE_ROUTES !== 'false',
@@ -46,23 +54,83 @@ const config = {
   // DELIBERATELY NOT PINNED in test/config/environment.ts -- do not "fix" this
   // as part of abofs/stonyx-rest-server#43. Same trap as the key above, and now
   // measured for both: pin `strictRoutes: true` in test/config/environment.ts
-  // AND invert this line to `=== 'true'`, and the suite reports 31 pass /
+  // AND invert this line to `=== 'true'`, and the suite reports 34 pass /
   // 0 fail. A naive pin makes an insecure published default completely
   // invisible to a green suite.
   //
-  // Unpinned, inverting this line alone turns #50's AC1 and AC2 red (29/2).
+  // Unpinned, inverting this line alone turns #50's AC1 and AC2 red (32/2).
   // AC3 stays GREEN under that mutation, because AC3 sets `strictRoutes` on the
   // config object directly and so guards src/route-matching.ts's READ rather
   // than this default -- the two assertions cover different halves and neither
   // subsumes the other.
   //
   // The cost is that the suite is ambient-sensitive here
-  // (`REST_STRICT_ROUTES=false pnpm test` => 29 pass / 2 fail), but it fails
-  // LOUDLY, so there is no false green. Closing #43 for either key needs
+  // (`REST_STRICT_ROUTES=false pnpm test` => 32 pass / 2 fail), but it fails
+  // LOUDLY, so there is no false green. All counts in this block re-measured
+  // against the 34-test suite at #54's head; the FAIL count is the load-bearing
+  // half, since PASS totals move whenever a test is added anywhere. Closing #43 for either key needs
   // subprocess-based env isolation this repo does not have; any fix must keep a
   // live assertion on this default.
   strictRoutes: REST_STRICT_ROUTES !== 'false',
 
+  // Secure by default, same polarity and same reasoning as the two keys above:
+  // a request whose RAW target is not the canonical path express matched is
+  // rejected with a plain 404 before the consumer's `auth` hook runs
+  // (abofs/stonyx-rest-server#54). This is NOT an express setting -- it is a
+  // per-request check in src/route-matching.ts (`shouldRejectTarget`), called
+  // from the handler closure in src/request.ts.
+  //
+  // BEHAVIOUR CHANGE for consumers upgrading, on TWO axes:
+  //   1. `GET /route/` at a mounted route class's ROOT now returns 404.
+  //   2. Clients or forward proxies emitting an ABSOLUTE-FORM request target
+  //      (`GET http://host/admin HTTP/1.1`, RFC 9112 3.2.2) now receive 404 on
+  //      every route registered through Request.registerCalls(). That is a
+  //      REGISTRATION-SITE limit, not a carve-out for one URL: /health is
+  //      registered directly on the parent app (src/main.ts) and still answers
+  //      200 to an absolute-form target -- and so would any route a consumer
+  //      registers on the public RestServer.instance.api itself. This is the
+  //      larger blast radius: for such a client it is a total outage, not a
+  //      partial one. Reverse proxies in normal use
+  //      (nginx, HAProxy, ALB) send origin-form and are unaffected.
+  // This module emits no request log, so both look like a dropped route.
+  //
+  // Opt out with REST_CANONICAL_ROUTES=false only as a temporary remediation --
+  // it RE-OPENS the bypass. Separate key from REST_STRICT_ROUTES and
+  // REST_CASE_SENSITIVE_ROUTES on purpose: coupling it to strictness would
+  // force a consumer who needs mount-root slash tolerance to also re-open #50's
+  // sub-path bypass.
+  //
+  // Note trustProxy below deliberately uses `=== 'true'` instead. That is not
+  // an inconsistency to "fix": its safe default is FALSY, so a truthy check
+  // already fails closed for it. The rule is "the guard must fail toward the
+  // safe value", not "all guards look alike".
+  //
+  // DELIBERATELY NOT PINNED in test/config/environment.ts -- do not "fix" this
+  // as part of abofs/stonyx-rest-server#43. Same trap as the two keys above,
+  // and now measured for all three: pin `canonicalRoutes: true` in
+  // test/config/environment.ts AND invert this line to `=== 'true'`, and the
+  // suite reports 34 pass / 0 fail while an insecure default ships. The pin is
+  // quieter AND weaker than no pin, which is the outcome pinning was supposed
+  // to prevent.
+  //
+  // Unpinned, inverting this line alone reports 32 pass / 2 fail: #54's
+  // integration AC1 and #50's AC2. AC2 (unit) stays GREEN under that mutation,
+  // because it sets `canonicalRoutes` on the config object directly and so
+  // guards src/route-matching.ts's READ rather than this default -- the two
+  // assertions cover different halves and neither subsumes the other.
+  // Conversely, weakening the READ to `=== true` reports 33 pass / 1 fail with
+  // AC2 as the only failure and AC1 fully green. All four counts in this block
+  // were re-measured on the #54 branch head after the AC1.11/AC1.12 assertions
+  // were added; the suite is 34 tests, and the FAIL count is the load-bearing
+  // half.
+  //
+  // The cost is that the suite is ambient-sensitive here
+  // (`REST_CANONICAL_ROUTES=false pnpm test` => 32 pass / 2 fail), but it fails
+  // LOUDLY, so there is no false green. Closing #43 for any of the three keys
+  // needs subprocess-based env isolation this repo does not have; any fix must
+  // keep a live assertion on this default.
+  canonicalRoutes: REST_CANONICAL_ROUTES !== 'false',
+
   enableHealthCheck: REST_HEALTH_CHECK_DISABLE !== 'true',
   origin: REST_CORS_ORIGIN ?? '*',
   methods: REST_CORS_METHODS ?? 'GET,POST,PATCH,PUT,DELETE',

package/dist/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,IAAI,cAAc,EAAE,KAAK,QAAQ,IAAI,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAOlH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;AAC3F,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC,CAAC,CAAC;AAE9F,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,SAAS,SAAmB;IAEnC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY;IASlD,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWrE,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAG,aAAa,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;;IAmB3B,aAAa,IAAI,IAAI;CAqDtB"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,IAAI,cAAc,EAAE,KAAK,QAAQ,IAAI,eAAe,EAAqB,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAOrI,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;AAC3F,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC,CAAC,CAAC;AAE9F,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,SAAS,SAAmB;IAEnC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY;IASlD,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWrE,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAG,aAAa,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;;IA4B3B,aAAa,IAAI,IAAI;CA4FtB"}

package/dist/request.js

@@ -1,7 +1,7 @@
 import express from 'express';
 import config from 'stonyx/config';
 import { makeArray } from '@stonyx/utils/object';
-import applyRouteMatching from './route-matching.js';
+import applyRouteMatching, { shouldRejectTarget } from './route-matching.js';
 const METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
 export default class Request {
     static stateProp = '__stonyxState';
@@ -28,7 +28,7 @@ export default class Request {
     constructor() {
         const api = express();
         api.disable('x-powered-by');
-        // Applies BOTH route-matching settings: case sensitive routing
+        // Applies BOTH route-matching SETTINGS: case sensitive routing
         // (abofs/stonyx-rest-server#47) and strict routing (#50). For #47 this
         // call closes sub-paths (/public/SUCCESS) and the parent's call closes the
         // mount segment; for #50 THIS call closes the entire trailing-slash
@@ -36,6 +36,15 @@ export default class Request {
         // role. Must stay in the constructor: registerCalls() materializes this
         // router, and a set applied afterwards has no effect. The parent app's
         // setting does not reach here -- see src/route-matching.ts.
+        //
+        // The third route-matching control, `canonicalRoutes` (#54), is NOT applied
+        // here and must not be moved here. It is not an express setting, and its
+        // timing contract is the opposite of these two: it is read PER REQUEST
+        // inside the handler closure in registerCalls() below, via
+        // shouldRejectTarget(). These two are constructor-timed because a late
+        // `set` is silently ineffective; that hazard does not exist for #54, and
+        // reading it per request is what lets the unit AC flip the flag between
+        // probes.
         applyRouteMatching(api);
         this.expressInstance = api;
     }
@@ -48,7 +57,46 @@ export default class Request {
                 continue;
             }
             for (const [route, handler] of Object.entries(handlers)) {
-                expressInstance[method](route, async (req, res) => {
+                expressInstance[method](route, async (req, res, next) => {
+                    // abofs/stonyx-rest-server#54 -- reject a request whose RAW target is
+                    // not the canonical path express matched, closing two authorization
+                    // bypasses against hooks that authorize on `req.originalUrl`: the
+                    // mount-root trailing slash and the absolute-form request target.
+                    //
+                    // Three properties of this line are load-bearing. Each is named with
+                    // the ONE assertion that turns red when it is removed -- assertion
+                    // numbers in `test/integration/rest-server-test.ts` AC1, so the claim
+                    // is checkable rather than a promise that coverage exists somewhere:
+                    //
+                    //   1. It runs OUTSIDE `if (this.auth)`. Gating it on the hook would
+                    //      leave `GET /public/` at 200 and make a security control depend
+                    //      on an unrelated consumer choice. Killed by AC1.6, which probes
+                    //      a route class with no hook.
+                    //   2. It runs BEFORE that block, not merely outside it. This is a
+                    //      SEPARATE property from 1 and needs its own probe: AC1.6 is on
+                    //      a hookless class, so it stays green if this line is merely
+                    //      moved BELOW the block. Measured with it moved: the suite was
+                    //      34 pass / 0 fail while `GET http://HOST/private/failure`
+                    //      answered 505 -- the consumer's hook status, which is the same
+                    //      oracle class as 3, and the hook itself ran on a request this
+                    //      module was about to reject. Killed by AC1.11.
+                    //   3. It rejects with `next('router')`, NOT sendStatusResponse() or
+                    //      res.sendStatus(404). Measured: sendStatus returns
+                    //      `text/plain "Not Found"` while a genuine miss returns
+                    //      `text/html <pre>Cannot GET ...</pre>` -- a working ORACLE
+                    //      telling an attacker the route exists but was spelled wrong.
+                    //      next('router') exits this sub-app's router into finalhandler
+                    //      and is shape-identical to a real miss (same status, same
+                    //      Content-Type, same CSP header). Routing it through
+                    //      sendStatusResponse() would additionally re-introduce the
+                    //      oracle for any consumer who sets a 404 in `statusMap`.
+                    //      Killed by AC1.5.
+                    //
+                    // Properties 1 and 2 were previously stated here as a single item
+                    // asserted to have "its own red-able assertion". It did not: only
+                    // half of it was covered. Do not re-merge them.
+                    if (shouldRejectTarget(req))
+                        return next('router');
                     // Run auth after route matching so request.params is populated
                     if (this.auth) {
                         const status = this.auth(req, getState(req));

package/dist/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"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"}

package/dist/route-matching.d.ts

@@ -1,4 +1,4 @@
-import type { Express } from 'express';
+import type { Express, Request as ExpressRequest } from 'express';
 /**
  * Applies this module's route-matching settings to an express app.
  *
@@ -63,20 +63,19 @@ import type { Express } from 'express';
  * settings (they share this function), but the justification differs and the
  * tests are built on the measured split, not on the analogy.
  *
- * Consequence worth stating so nobody expects this setting to cover it: the
- * mount-segment trailing slash (`/public/`) cannot be closed by an express
- * SETTING. For both `/public` and `/public/` the mounted sub-app receives
- * `req.path === '/'`, so a `req.path` auth hook sees no difference, and a test
- * asserting `/public/` -> 404 could never pass.
- *
- * That is NOT the same as saying the edge is harmless or unclosable.
- * `req.originalUrl` does differ, and a hook authorizing on it is bypassed by
- * one character -- measured: `GET /admin` -> 401, `GET /admin/` -> 200 with the
- * guarded handler running unauthenticated. That is a live bypass of the same
- * class as #47 and #50, and it IS closable by this module: a canonical-path
- * check ahead of the `auth` call in `Request.registerCalls()`, or opt-in
- * normalizing middleware. It is tracked as abofs/stonyx-rest-server#54. Do not
- * close it here, and do not read this note as saying it cannot be closed.
+ * Consequence worth stating so nobody expects this SETTING to cover it: no
+ * express setting rejects the mount-segment trailing slash (`/public/`). For
+ * both `/public` and `/public/` the mounted sub-app receives `req.path === '/'`,
+ * so a `req.path` auth hook sees no difference and there is nothing for the
+ * setting to reject. That statement is still true, and it is still the reason
+ * `applyRouteMatching()` is not the fix site for that edge.
+ *
+ * The edge itself is CLOSED, by `shouldRejectTarget()` below rather than by a
+ * setting (abofs/stonyx-rest-server#54). `req.originalUrl` does differ between
+ * the two spellings, and a hook authorizing on it was bypassed by one
+ * character -- measured: `GET /admin` -> 401, `GET /admin/` -> 200 with the
+ * guarded handler running unauthenticated. `GET /public/` now returns 404, and
+ * the integration AC asserts exactly that.
  *
  * Both guards are `!== false` for the same reason: these flags default to the
  * truthy direction, so a truthy check fails OPEN for a consumer whose shipped
@@ -87,4 +86,60 @@ import type { Express } from 'express';
  * fail-open guard leaves every integration assertion green.
  */
 export default function applyRouteMatching(api: Express): void;
+/**
+ * Decides whether a request must be rejected because its RAW request target is
+ * not the canonical path express matched (abofs/stonyx-rest-server#54).
+ *
+ * Closes two live authorization bypasses against a consumer hook that
+ * authorizes on `req.originalUrl` -- the field express does NOT normalize:
+ *
+ *   1. mount-root trailing slash    GET /admin/                  -> was 200
+ *   2. absolute-form request target GET http://host/admin        -> was 200
+ *      (RFC 9112 3.2.2; hits EVERY route, not just the mount root)
+ *
+ * Both were measured reaching the guarded handler unauthenticated while
+ * `GET /admin` was denied 401.
+ *
+ * COMPARE THE RAW TARGET; DO NOT PARSE IT. Any implementation reaching for
+ * `new URL(req.originalUrl, base).pathname` to "get the path" re-opens vector 2
+ * BY CONSTRUCTION: parsing normalizes the exact string the consumer's hook is
+ * exposed to, so the check would compare a laundered value while the hook still
+ * sees the raw one. Measured: the narrow `endsWith('/')` form closes 1 and
+ * leaves 2 at 200.
+ *
+ * `req.baseUrl + req.path` is likewise NOT usable as the left-hand side. It is
+ * `/admin/` for BOTH spellings of vector 1 -- `originalUrl` is the only field
+ * that differs, which is precisely why the bypass exists. A check built on
+ * `baseUrl + path` cannot see its own defect.
+ *
+ * TIMING CONTRACT -- DELIBERATELY DIFFERENT FROM ITS TWO SIBLINGS. This lives
+ * beside `applyRouteMatching()` for the same "one place anchors it" reason, but
+ * deliberately OUTSIDE it: that function's contract is *apply express settings
+ * to an app*, it is called from two constructors, and this is neither a setting
+ * nor constructor-timed. `caseSensitiveRoutes`/`strictRoutes` are read once in a
+ * constructor and are silently ineffective if applied late; this flag is read
+ * PER REQUEST, inside the handler closure. There is no lazy-materialisation
+ * hazard here, so do not carry that constraint across.
+ *
+ * The caller must reject with `next('router')`, NOT `res.sendStatus(404)`, and
+ * must run this BEFORE `this.auth` as well as outside `if (this.auth)` -- those
+ * are two separate properties with two separate assertions (AC1.11 and AC1.6);
+ * see src/request.ts.
+ *
+ * Guard polarity is `!== false`, matching both siblings, for the same measured
+ * reason: the secure value is the TRUTHY one, so a plain truthy check fails
+ * OPEN for any consumer whose shipped `restServer` block predates the key --
+ * the state every existing consumer is in, and reachable in practice because
+ * the stonyx loader only merges a module's `config/environment.js` for modules
+ * in devDependencies. `trustProxy` deliberately differs (`=== 'true'`): its safe
+ * default is FALSY, so a truthy check already fails closed for it. The rule is
+ * "the guard must fail toward the safe value", not "all guards look alike" --
+ * preserve the asymmetry.
+ *
+ * The integration tier cannot see a fail-open guard here: with the shipped
+ * default `true`, `=== true` leaves every integration assertion green. Only
+ * `test/unit/request-test.ts` AC2 can, and it probes BOTH failure shapes --
+ * key present-and-`undefined` and key absent as an own property.
+ */
+export declare function shouldRejectTarget(req: ExpressRequest): boolean;
 //# sourceMappingURL=route-matching.d.ts.map

package/dist/route-matching.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-matching.d.ts","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG7D"}
+{"version":3,"file":"route-matching.d.ts","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,SAAS,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAuB/D"}

package/dist/route-matching.js

@@ -63,20 +63,19 @@ import config from 'stonyx/config';
  * settings (they share this function), but the justification differs and the
  * tests are built on the measured split, not on the analogy.
  *
- * Consequence worth stating so nobody expects this setting to cover it: the
- * mount-segment trailing slash (`/public/`) cannot be closed by an express
- * SETTING. For both `/public` and `/public/` the mounted sub-app receives
- * `req.path === '/'`, so a `req.path` auth hook sees no difference, and a test
- * asserting `/public/` -> 404 could never pass.
- *
- * That is NOT the same as saying the edge is harmless or unclosable.
- * `req.originalUrl` does differ, and a hook authorizing on it is bypassed by
- * one character -- measured: `GET /admin` -> 401, `GET /admin/` -> 200 with the
- * guarded handler running unauthenticated. That is a live bypass of the same
- * class as #47 and #50, and it IS closable by this module: a canonical-path
- * check ahead of the `auth` call in `Request.registerCalls()`, or opt-in
- * normalizing middleware. It is tracked as abofs/stonyx-rest-server#54. Do not
- * close it here, and do not read this note as saying it cannot be closed.
+ * Consequence worth stating so nobody expects this SETTING to cover it: no
+ * express setting rejects the mount-segment trailing slash (`/public/`). For
+ * both `/public` and `/public/` the mounted sub-app receives `req.path === '/'`,
+ * so a `req.path` auth hook sees no difference and there is nothing for the
+ * setting to reject. That statement is still true, and it is still the reason
+ * `applyRouteMatching()` is not the fix site for that edge.
+ *
+ * The edge itself is CLOSED, by `shouldRejectTarget()` below rather than by a
+ * setting (abofs/stonyx-rest-server#54). `req.originalUrl` does differ between
+ * the two spellings, and a hook authorizing on it was bypassed by one
+ * character -- measured: `GET /admin` -> 401, `GET /admin/` -> 200 with the
+ * guarded handler running unauthenticated. `GET /public/` now returns 404, and
+ * the integration AC asserts exactly that.
  *
  * Both guards are `!== false` for the same reason: these flags default to the
  * truthy direction, so a truthy check fails OPEN for a consumer whose shipped
@@ -92,4 +91,81 @@ export default function applyRouteMatching(api) {
     if (config.restServer?.strictRoutes !== false)
         api.set('strict routing', true);
 }
+/**
+ * Decides whether a request must be rejected because its RAW request target is
+ * not the canonical path express matched (abofs/stonyx-rest-server#54).
+ *
+ * Closes two live authorization bypasses against a consumer hook that
+ * authorizes on `req.originalUrl` -- the field express does NOT normalize:
+ *
+ *   1. mount-root trailing slash    GET /admin/                  -> was 200
+ *   2. absolute-form request target GET http://host/admin        -> was 200
+ *      (RFC 9112 3.2.2; hits EVERY route, not just the mount root)
+ *
+ * Both were measured reaching the guarded handler unauthenticated while
+ * `GET /admin` was denied 401.
+ *
+ * COMPARE THE RAW TARGET; DO NOT PARSE IT. Any implementation reaching for
+ * `new URL(req.originalUrl, base).pathname` to "get the path" re-opens vector 2
+ * BY CONSTRUCTION: parsing normalizes the exact string the consumer's hook is
+ * exposed to, so the check would compare a laundered value while the hook still
+ * sees the raw one. Measured: the narrow `endsWith('/')` form closes 1 and
+ * leaves 2 at 200.
+ *
+ * `req.baseUrl + req.path` is likewise NOT usable as the left-hand side. It is
+ * `/admin/` for BOTH spellings of vector 1 -- `originalUrl` is the only field
+ * that differs, which is precisely why the bypass exists. A check built on
+ * `baseUrl + path` cannot see its own defect.
+ *
+ * TIMING CONTRACT -- DELIBERATELY DIFFERENT FROM ITS TWO SIBLINGS. This lives
+ * beside `applyRouteMatching()` for the same "one place anchors it" reason, but
+ * deliberately OUTSIDE it: that function's contract is *apply express settings
+ * to an app*, it is called from two constructors, and this is neither a setting
+ * nor constructor-timed. `caseSensitiveRoutes`/`strictRoutes` are read once in a
+ * constructor and are silently ineffective if applied late; this flag is read
+ * PER REQUEST, inside the handler closure. There is no lazy-materialisation
+ * hazard here, so do not carry that constraint across.
+ *
+ * The caller must reject with `next('router')`, NOT `res.sendStatus(404)`, and
+ * must run this BEFORE `this.auth` as well as outside `if (this.auth)` -- those
+ * are two separate properties with two separate assertions (AC1.11 and AC1.6);
+ * see src/request.ts.
+ *
+ * Guard polarity is `!== false`, matching both siblings, for the same measured
+ * reason: the secure value is the TRUTHY one, so a plain truthy check fails
+ * OPEN for any consumer whose shipped `restServer` block predates the key --
+ * the state every existing consumer is in, and reachable in practice because
+ * the stonyx loader only merges a module's `config/environment.js` for modules
+ * in devDependencies. `trustProxy` deliberately differs (`=== 'true'`): its safe
+ * default is FALSY, so a truthy check already fails closed for it. The rule is
+ * "the guard must fail toward the safe value", not "all guards look alike" --
+ * preserve the asymmetry.
+ *
+ * The integration tier cannot see a fail-open guard here: with the shipped
+ * default `true`, `=== true` leaves every integration assertion green. Only
+ * `test/unit/request-test.ts` AC2 can, and it probes BOTH failure shapes --
+ * key present-and-`undefined` and key absent as an own property.
+ */
+export function shouldRejectTarget(req) {
+    // Written as `!== false` rather than `=== false` on purpose: the polarity is
+    // the load-bearing part and it should read identically to the two guards in
+    // applyRouteMatching() above.
+    const enforced = config.restServer?.canonicalRoutes !== false;
+    if (!enforced)
+        return false;
+    // Raw, unparsed. Only the query string is removed, by string split.
+    const target = req.originalUrl.split('?')[0];
+    // At a mount root express reports `req.path === '/'` while the canonical
+    // target is the bare mount segment, so the two are not simply concatenated.
+    //
+    // `&& req.baseUrl` is load-bearing and is NOT a redundant truthiness guard.
+    // A route class named `index` mounts at '/' (src/main.ts `mountRoute()`),
+    // and that is the one mount shape where `req.baseUrl` is ''. Without the
+    // conjunct, `GET /` compares the raw target '/' against a canonical of '' and
+    // the APPLICATION ROOT is rejected. Measured before it had a guard: shipped
+    // `GET /` -> 200, conjunct dropped -> 404, suite 34 pass / 0 fail BOTH ways.
+    // Killed now by AC1.12, against `test/sample/requests/index.ts`.
+    const canonical = req.path === '/' && req.baseUrl ? req.baseUrl : req.baseUrl + req.path;
+    return target !== canonical;
+}
 //# sourceMappingURL=route-matching.js.map

package/dist/route-matching.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-matching.js","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,eAAe,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAY;IACrD,IAAI,MAAM,CAAC,UAAU,EAAE,mBAAmB,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,UAAU,EAAE,YAAY,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;AACjF,CAAC"}
+{"version":3,"file":"route-matching.js","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,eAAe,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAY;IACrD,IAAI,MAAM,CAAC,UAAU,EAAE,mBAAmB,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,UAAU,EAAE,YAAY,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAmB;IACpD,6EAA6E;IAC7E,4EAA4E;IAC5E,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,eAAe,KAAK,KAAK,CAAC;IAC9D,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5B,oEAAoE;IACpE,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7C,yEAAyE;IACzE,4EAA4E;IAC5E,EAAE;IACF,4EAA4E;IAC5E,0EAA0E;IAC1E,yEAAyE;IACzE,8EAA8E;IAC9E,4EAA4E;IAC5E,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC;IAEzF,OAAO,MAAM,KAAK,SAAS,CAAC;AAC9B,CAAC"}

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.91",
+  "version": "0.2.1-beta.92",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",