@stonyx/rest-server 0.2.1-alpha.20 → 0.2.1-alpha.22

package/README.md

@@ -79,59 +79,75 @@ Configuration is read from `stonyx/config` under `restServer`:
 |      `origin`     | **String \| Array** | `'*'`       | CORS origin(s) allowed                                     |
 |    `methods`      | **String**          | `'GET,POST,PATCH,PUT,DELETE'` | CORS allowed methods                              |
 | `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 [Case-Sensitive Routing](#case-sensitive-routing) — **disabling this re-opens a security hole**. |
+| `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. |
 |  `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   |
 
-### Case-Sensitive Routing
+### Route Matching Strictness
 
-Routes match **case-sensitively by default**. `GET /users` reaches a route
-mounted at `/users`; `GET /Users` does not reach that mount, and
-`GET /users/Success` does not reach a `/success` handler registered inside it.
+Routes match **case-sensitively and strictly by default**. Two settings, both
+on, both applied at both express construction sites:
 
-Read [What this does not do](#what-this-does-not-do) before you rely on that
-sentence. Two things it does not say: "does not reach the handler" is not the
-same as "404", and casing is only one of the two ways express matches more
-loosely than the authorization predicates written against it.
+| axis | setting | 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` |
 
-This is deliberate and security-relevant. Express matches case-insensitively by
-default, which means any authorization written against the request URL can be
-walked past by changing the case of the request:
+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.
+
+This is deliberate and security-relevant. Express matches both case-insensitively
+and slash-insensitively by default, which means any authorization written
+against the request URL can be walked past by changing the case of the request,
+or by appending one character:
 
 ```
-GET    /owners/angela  -> 404      (correctly filtered)
-GET    /OwNeRs/angela  -> 200      (full record)
-DELETE /ANIMALS/22     -> 204      (record destroyed)
+GET    /owners/angela   -> 404      (correctly filtered)
+GET    /OwNeRs/angela   -> 200      (full record)     <- closed by case sensitive routing
+GET    /owners/angela/  -> 200      (full record)     <- closed by strict routing
+DELETE /ANIMALS/22      -> 204      (record destroyed)
+DELETE /animals/22/     -> 204      (record destroyed)
 ```
 
 The consumer's predicate is stricter than the router that dispatched the
 request, so the router hands the handler a request the predicate would have
-rejected. Case-sensitive matching closes the **casing** half of that asymmetry:
-the path a handler sees can only ever be the exact registered casing.
-
-It does not close the asymmetry itself. Express exposes `case sensitive
-routing` and `strict routing` as a pair of loose-by-default router settings and
-this change sets only the first, so the identical bypass is still reachable by
-appending a slash. Measured on this release against this repo's own fixture:
+rejected. Measured against this repo's own fixture, before and after:
 
 ```
-GET /private/failure   -> 505      (auth hook fires, request blocked)
-GET /private/failure/  -> 200      (auth hook never fires, handler runs)
+                          before   after
+GET /private/failure        505      505    (auth hook fires, request blocked)
+GET /private/failure/       200      404    (auth hook never fired; now a miss)
+GET /private/FAILURE        200      200    (absorbed by /:id — see below)
 ```
 
-That is the same defect, one character instead of a case shift — translated to
-the example above, `DELETE /animals/22` is filtered and `DELETE /animals/22/`
-destroys the record. It is tracked as
-[#50](https://github.com/abofs/stonyx-rest-server/issues/50) and is not fixed
-here; it is a second consumer-visible behaviour change that needs its own flag
-and its own release note.
-
-**So do not drop a URL-normalizing defence you already have on the strength of
-this section.** If your authorization compares `req.path` or `req.originalUrl`,
-keep whatever normalization you have until #50 ships.
+For a handler that authorizes on `req.path`, the path it sees can now only ever
+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
 
+**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:
+
+```
+GET /public   -> req.path '/'   req.originalUrl '/public'
+GET /public/  -> req.path '/'   req.originalUrl '/public/'
+```
+
+Express's router applies mount-prefix matching with `strict: false`
+unconditionally (`router@2.2.0`, `index.js:400-401`), 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.
+
 **It does not normalize path *parameter values*.** If your `auth()` hook rejects
 `params.id === 'restricted'`, then `GET /private/RESTRICTED` still reaches the
 handler — the router matched the route correctly, and `restricted` and
@@ -148,36 +164,64 @@ repo's AC5 asserts exactly that. A class exposing `/orders/summary` alongside
 database lookup. The param route's own `auth()` hook still runs, so this is an
 expectation defect rather than a bypass — but plan for a reroute, not a 404.
 
-**It does not cover trailing slashes.** See
-[#50](https://github.com/abofs/stonyx-rest-server/issues/50) above.
+Note the two axes differ here. A *trailing slash* is not absorbed by `/:id`,
+because `/:id` is equally strict: `GET /private/failure/` misses `/failure` and
+misses `/:id`, and is a true 404.
+
+**It does not redirect or rewrite** mixed-case or trailing-slash requests to
+their canonical form. Whether `/Users` is a typo to forgive or an attack to
+reject is an application policy decision, and encoding it here would mint
+another variant of the bug above.
 
-**It does not redirect or rewrite** mixed-case requests to their canonical
-casing. Whether `/Users` is a typo to forgive or an attack to reject is an
-application policy decision, and encoding it here would mint another variant of
-the bug above.
+#### Upgrading: behaviour changes
+
+Both settings change which requests match, so both are consumer-visible.
+
+**`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
+than a 404 you will read about in a log: if a Kubernetes liveness probe, an ELB
+target-group health check or an uptime monitor is pointed at the trailing-slash
+form, it starts failing and the deployment gets marked unhealthy and cycled.
+This module emits no request logging, so the only symptom is the probe going
+red. **Check your probe URLs before upgrading.**
+
+Also affected:
+
+- **Param routes.** `/resource/:id/` no longer matches. Any client calling
+  `/private/restricted/` gets a 404 where it previously got the param route.
+- **Trailing-slash-normalizing proxies.** nginx `try_files`/`rewrite`, Apache
+  `DirectorySlash On` and some CDN edge rules append a slash; behind one of
+  those, every route stops matching at once.
+- **Mount paths from filenames.** With `camelCaseRoutes` truthy, `phone-number.ts`
+  mounts at `/phoneNumber`, so `GET /phonenumber` returns 404; with it falsy,
+  `Users.ts` mounts at `/Users`, so `GET /users` returns 404.
+
+A request that stops matching returns express's default `404 Cannot GET /x` with
+no log line and no stack, so it looks like a deploy that dropped a route.
 
 #### Opting out
 
+Two separate flags, one per axis:
+
 ```bash
-REST_CASE_SENSITIVE_ROUTES=false
+REST_CASE_SENSITIVE_ROUTES=false   # restores case-insensitive matching (#47)
+REST_STRICT_ROUTES=false           # restores trailing-slash tolerance (#50)
 ```
 
-**This restores the vulnerability described above** — any URL-based
-authorization in your application becomes bypassable by changing case. It
-exists as a one-line remediation for an existing deployment, not as a
-configuration to run on.
+or equivalently `restServer: { caseSensitiveRoutes: false, strictRoutes: false }`.
 
-You need it if clients call your endpoints with casing that does not match the
-mount path. Mount paths come from filenames, so this is not hypothetical:
+**They are deliberately separate keys, and neither implies the other.** 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.
 
-- with `camelCaseRoutes` truthy, `phone-number.ts` mounts at `/phoneNumber`, and
-  `GET /phonenumber` now returns 404
-- with `camelCaseRoutes` falsy, filenames are used verbatim, so
-  `Users.ts` mounts at `/Users` and `GET /users` now returns 404
-
-A request that stops matching returns express's default `404 Cannot GET /x` with
-no log line and no stack, so it looks like a deploy that dropped a route. Set
-the flag to restore service, then fix the client's casing and remove the flag.
+**Each flag restores the corresponding vulnerability described above** — the
+URL-based authorization in your application becomes bypassable along that axis
+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.
 
 ### Running Behind a Load Balancer
 

package/config/environment.js

@@ -5,6 +5,7 @@ const {
   REST_HEALTH_CHECK_DISABLE,
   REST_PORT,
   REST_REQUEST_PATH,
+  REST_STRICT_ROUTES,
   REST_TRUST_PROXY
 } = process.env;
 
@@ -31,6 +32,37 @@ const config = {
   // 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',
+
+  // Secure by default, same polarity and same reasoning as caseSensitiveRoutes
+  // above: routes match strictly, so a trailing slash cannot walk past a
+  // consumer's URL-based authorization (abofs/stonyx-rest-server#50).
+  //
+  // BEHAVIOUR CHANGE for consumers upgrading: `/health/` now returns 404, and
+  // param routes like `/resource/:id/` no longer match. Opt out with
+  // REST_STRICT_ROUTES=false only as a temporary remediation. It is a separate
+  // key from REST_CASE_SENSITIVE_ROUTES on purpose -- opting out of slash
+  // strictness must not silently re-open #47's case bypass.
+  //
+  // 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 /
+  // 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).
+  // 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
+  // subprocess-based env isolation this repo does not have; any fix must keep a
+  // live assertion on this default.
+  strictRoutes: REST_STRICT_ROUTES !== 'false',
+
   enableHealthCheck: REST_HEALTH_CHECK_DISABLE !== 'true',
   origin: REST_CORS_ORIGIN ?? '*',
   methods: REST_CORS_METHODS ?? 'GET,POST,PATCH,PUT,DELETE',

package/dist/route-matching.d.ts

@@ -29,7 +29,49 @@ import type { Express } from 'express';
  *
  * Note `express({ caseSensitive: true })` does NOT work: express 5's
  * `createApplication()` takes zero arguments and forwards nothing. The app
- * setting is the only mechanism.
+ * setting is the only mechanism. The same is true of `strict`.
+ *
+ * ---
+ *
+ * `strict routing` (abofs/stonyx-rest-server#50) closes the same class of
+ * authorization bypass for a TRAILING SLASH: `GET /private/failure` was denied
+ * by a consumer's auth hook while `GET /private/failure/` reached the guarded
+ * handler, because the hook compares `req.path` against `/failure`.
+ *
+ * It is a SEPARATE key from `caseSensitiveRoutes`, not a rename and not a
+ * reuse. Coupling them would force any consumer who legitimately needs
+ * trailing-slash tolerance -- a load balancer probing `/health/`, a
+ * slash-normalizing proxy -- to re-open #47's case bypass to get it. Case
+ * insensitivity is almost never intentional; slash tolerance frequently is.
+ *
+ * The two settings do NOT share the #47 split above, and this is the one thing
+ * not to carry across from that fix. For `strict routing`:
+ *
+ *   - The CHILD site (Request's constructor) closes the entire security
+ *     defect on its own. The parent site does nothing for it.
+ *   - The PARENT site (RestServer's constructor) closes exactly one thing in
+ *     this repo: `/health/`, the only route registered directly on the parent
+ *     app. It has no security role here; do not describe it as having one.
+ *
+ * The cause is concrete: router@2.2.0 `index.js:400-401` hardcodes
+ * `strict: false, end: false` for `Router.prototype.use`, so mount segments
+ * are structurally strict-immune. That is the OPPOSITE of `sensitive`, which
+ * `use()` does forward (line 399) and which is why #47's parent site closed
+ * `/PUBLIC/...`. Both sites still get both 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 "fixes" it: the mount-segment trailing
+ * slash (`/public/`) can never be closed by this setting, and does not need to
+ * be. For both `/public` and `/public/` the mounted sub-app receives
+ * `req.path === '/'`, so a `req.path` auth hook sees no difference and there is
+ * no asymmetry. A test asserting `/public/` -> 404 could never pass. The
+ * residual is `req.originalUrl`, which DOES differ; that is disclosed in the
+ * README rather than silently closed over.
+ *
+ * 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
+ * config predates the key.
  */
 export default function applyRouteMatching(api: Express): void;
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAE7D"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG7D"}

package/dist/route-matching.js

@@ -29,10 +29,54 @@ import config from 'stonyx/config';
  *
  * Note `express({ caseSensitive: true })` does NOT work: express 5's
  * `createApplication()` takes zero arguments and forwards nothing. The app
- * setting is the only mechanism.
+ * setting is the only mechanism. The same is true of `strict`.
+ *
+ * ---
+ *
+ * `strict routing` (abofs/stonyx-rest-server#50) closes the same class of
+ * authorization bypass for a TRAILING SLASH: `GET /private/failure` was denied
+ * by a consumer's auth hook while `GET /private/failure/` reached the guarded
+ * handler, because the hook compares `req.path` against `/failure`.
+ *
+ * It is a SEPARATE key from `caseSensitiveRoutes`, not a rename and not a
+ * reuse. Coupling them would force any consumer who legitimately needs
+ * trailing-slash tolerance -- a load balancer probing `/health/`, a
+ * slash-normalizing proxy -- to re-open #47's case bypass to get it. Case
+ * insensitivity is almost never intentional; slash tolerance frequently is.
+ *
+ * The two settings do NOT share the #47 split above, and this is the one thing
+ * not to carry across from that fix. For `strict routing`:
+ *
+ *   - The CHILD site (Request's constructor) closes the entire security
+ *     defect on its own. The parent site does nothing for it.
+ *   - The PARENT site (RestServer's constructor) closes exactly one thing in
+ *     this repo: `/health/`, the only route registered directly on the parent
+ *     app. It has no security role here; do not describe it as having one.
+ *
+ * The cause is concrete: router@2.2.0 `index.js:400-401` hardcodes
+ * `strict: false, end: false` for `Router.prototype.use`, so mount segments
+ * are structurally strict-immune. That is the OPPOSITE of `sensitive`, which
+ * `use()` does forward (line 399) and which is why #47's parent site closed
+ * `/PUBLIC/...`. Both sites still get both 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 "fixes" it: the mount-segment trailing
+ * slash (`/public/`) can never be closed by this setting, and does not need to
+ * be. For both `/public` and `/public/` the mounted sub-app receives
+ * `req.path === '/'`, so a `req.path` auth hook sees no difference and there is
+ * no asymmetry. A test asserting `/public/` -> 404 could never pass. The
+ * residual is `req.originalUrl`, which DOES differ; that is disclosed in the
+ * README rather than silently closed over.
+ *
+ * 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
+ * config predates the key.
  */
 export default function applyRouteMatching(api) {
     if (config.restServer?.caseSensitiveRoutes !== false)
         api.set('case sensitive routing', true);
+    if (config.restServer?.strictRoutes !== false)
+        api.set('strict routing', true);
 }
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;AAChG,CAAC"}
+{"version":3,"file":"route-matching.js","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,eAAe,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;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"}

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.20",
+  "version": "0.2.1-alpha.22",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "stonyx": "0.2.3-beta.77"
+    "stonyx": "0.2.3-beta.78"
   },
   "devDependencies": {
     "@stonyx/utils": "0.2.3-beta.26",