@stonyx/rest-server 0.2.1-alpha.25 → 0.2.1-alpha.26

package/README.md

@@ -82,24 +82,27 @@ Configuration is read from `stonyx/config` under `restServer`:
 | `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)). |
+| `canonicalEncoding` | **Boolean**   | `true`      | Reject a request whose raw target percent-encodes an RFC 3986 §2.3 *unreserved* character (`A-Z a-z 0-9 - . _ ~`), before your `auth` hook runs. Disable via `REST_CANONICAL_ENCODING=false`. See [Route Matching Strictness](#route-matching-strictness) — **disabling this re-opens a security hole**, and note that a client over-encoding an unreserved character in a path now gets 404 (see [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, strictly, and only at their canonical target
-by default**. Three controls, all on:
+Routes match **case-sensitively, strictly, only at their canonical target, and
+only at their canonical spelling by default**. Four controls, all on:
 
 | axis | control | example that no longer matches |
 |---|---|---|
 | 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 |
+| percent-encoding | `canonicalEncoding` (per-request check) | `GET /users/%73ecret` -> does not reach `/users/:id` with `id === "secret"` |
 
-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
+The first two are express settings applied at both construction sites. The last
+two are **not settings** — no express setting can express either — they are
+per-request checks run ahead of your `auth` hook: one compares the raw request
+target against the path express matched, the other rejects a raw target that
+percent-encodes a character which never needs encoding. See
 [`src/route-matching.ts`](src/route-matching.ts).
 
 Read [What this does not do](#what-this-does-not-do) and
@@ -191,19 +194,75 @@ 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.
+**Param routes: "unaffected" means "no regression".** `/resource/:id` keeps
+matching exactly as it did. `canonicalRoutes` is structurally blind to how a
+param value is *spelled* — express decodes only `req.params`, so `target` and
+`canonical` are both the same encoded string and this comparison passes the
+request through by construction. That axis has its own control, below.
+
+#### The percent-encoding check (`canonicalEncoding`)
+
+Express decodes **`req.params` and nothing else**. `req.path` and
+`req.originalUrl` both stay percent-encoded, so an `auth` hook comparing either
+of them against a fixed string was walked past by re-spelling the id:
+
+```
+                          before   after
+GET /enc/secret             401      401   (hook fires, request blocked)
+GET /enc/%73ecret           200      404   (hook never fired; handler got id "secret")
+GET /enc/%73%65%63%72%65%74 200      404
+GET /private/%66ailure      200      404   (guard missed; absorbed by a sibling /:id)
+```
+
+`canonicalEncoding` closes it
+([#56](https://github.com/abofs/stonyx-rest-server/issues/56)). Before your
+`auth` hook runs, the query-stripped raw target is rejected as a plain 404 if it
+contains a percent-triplet whose octet is an
+[RFC 3986 §2.3](https://www.rfc-editor.org/rfc/rfc3986#section-2.3)
+**unreserved** character — `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, `~`. Those are
+exactly the characters a URI generator must **not** encode and a normalizer
+**must** decode, so nothing a client is required to send is affected.
+
+**This is not a list of spellings, it is a family.** For an id of *n* bytes
+there are `∏(1 + vᵢ) − 1` non-canonical spellings, where a byte whose hex
+carries a letter digit has two (`m`, `%6d`, `%6D`). Measured against unfixed
+code: **63 of 63** spellings of `secret` returned 200, and **71 of 71** of
+`admin`. Enumerating them in your own hook is not a remedy.
+
+**Three things it deliberately does not reject:**
+
+```
+GET /enc/sec%2fret   -> 200  id "sec/ret"    %2f is RESERVED — must stay encodable
+GET /enc/a%2Bb       -> 200  id "a+b"        %2B is RESERVED
+GET /enc/%2573ecret  -> 200  id "%73ecret"   express decodes exactly ONCE
+GET /enc/x?name=%61  -> 200  id "x"          the query string is stripped, not scanned
+GET /enc/%zz         -> 400                  malformed escapes are the router's 400, unchanged
+```
+
+If you were tempted to write `decodeURIComponent(req.path)` in your hook: the
+first line is why not. The router **splits then decodes**, so `sec%2fret` is one
+segment naming the id `sec/ret`; a hook that decodes then splits sees two
+segments and denies a request the router routed somewhere else entirely. And a
+hook that decodes *until stable* denies line three, which is a legitimately
+distinct id.
+
+**The residual, stated plainly: this does not give each id one spelling.**
+Because reserved characters must stay encodable, two different raw targets can
+still name the same record:
+
+```
+GET /enc/a+b        -> 200  id "a+b"
+GET /enc/a%2Bb      -> 200  id "a+b"       <- two accepted spellings, one id
+GET /enc/sec%2fret  -> 200  id "sec/ret"
+GET /enc/sec%2Fret  -> 200  id "sec/ret"   <- hex-digit case, same id again
+```
+
+**So a hook comparing a raw path string is still unsound for any id containing a
+reserved character, and `req.params` is the sound comparison.** `req.params` is
+decoded by express and is populated *before* your `auth` hook runs, by design —
+compare that, and none of this applies to you. This module cannot close the
+residual for you without 404ing encodings clients are entitled to send; see
+[Consumer Contracts](#consumer-contracts).
 
 #### What this does not do
 
@@ -234,9 +293,22 @@ another variant of the bug above.
 
 #### Upgrading: behaviour changes
 
-All three controls change which requests match, so all three are
+All four controls change which requests match, so all four are
 consumer-visible.
 
+**A client that over-encodes an unreserved character in a path now gets 404.**
+`GET /public/url-params/%61/b/c` returns **404** where it previously returned
+200 — measured on this repo's own fixture. `%61` is `a`, and
+[RFC 3986 §2.3](https://www.rfc-editor.org/rfc/rfc3986#section-2.3) says a
+generator must not encode it, so no correct client emits this. Some do anyway:
+over-eager `encodeURIComponent` on an id that never needed it, a URL builder
+that percent-encodes everything, or a client library normalizing in the wrong
+direction. Reserved characters are **unaffected** — `%2f`, `%2B`, `%25` and
+every non-ASCII byte still route, and so does anything in the query string.
+Remediation is `REST_CANONICAL_ENCODING=false`, or fix the client. Like the two
+below, the rejection is **indistinguishable from a route that was never
+registered**, and this module emits no request logging.
+
 **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
@@ -289,16 +361,17 @@ no log line and no stack, so it looks like a deploy that dropped a route.
 
 #### Opting out
 
-Three separate flags, one per axis:
+Four 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)
+REST_CANONICAL_ENCODING=false      # restores percent-encoded spellings (#56)
 ```
 
 or equivalently
-`restServer: { caseSensitiveRoutes: false, strictRoutes: false, canonicalRoutes: false }`.
+`restServer: { caseSensitiveRoutes: false, strictRoutes: false, canonicalRoutes: false, canonicalEncoding: false }`.
 
 **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
@@ -315,6 +388,18 @@ 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.
 
+**`REST_CANONICAL_ENCODING=false` re-opens the `#56` bypass, and it is the
+widest of the four.** With it set, `GET /users/%73ecret` reaches your `/:id`
+handler with `id === "secret"` while your hook compared `%73ecret` and did not
+match — and it does that against a hook comparing `req.path` **or**
+`req.originalUrl`, on every route class with a param segment. The other three
+flags each re-open one field's worth of exposure; this one re-opens both. It is
+also **independent** of `REST_CANONICAL_ROUTES`: if you have to set that one for
+an absolute-form-emitting forward proxy, you keep this one on, which is exactly
+why they are separate keys. If you must set it, the mitigation that costs you
+nothing is to compare `req.params` in your hook rather than a raw path string —
+`req.params` is decoded and was never exposed to this.
+
 **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
@@ -331,7 +416,8 @@ 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) |
+| **Compare `req.params`, not a raw path string** | express decodes only `req.params`; `req.path` and `req.originalUrl` both stay percent-encoded. `canonicalEncoding` (#56) rejects an over-encoded *unreserved* character, but **reserved** characters must stay encodable, so one decoded id still has more than one accepted spelling: `GET /orders/a+b` and `GET /orders/a%2Bb` both run the handler with `id === "a+b"`, and `sec%2fret` / `sec%2Fret` both give `sec/ret` | your hook compares one spelling, the request arrives in another, and the handler runs **unauthenticated** — 200, no error, no log. Comparing `req.params.id` instead is immune by construction, and it is populated before `auth()` runs |
+| **Compare param values with the same casing you look them up with** | param *values* are never case-normalized, and record ids are legitimately case-sensitive | `GET /orders/SECRET` runs the handler with `id === "SECRET"` while your hook compared `secret`. Note that lower-casing the value is **not** the fix: it false-denies a genuinely distinct `SECRET` record and, measured in a sibling module, false-allowed an encoded spelling at the same time |
 | **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

package/config/environment.js

@@ -1,4 +1,5 @@
 const {
+  REST_CANONICAL_ENCODING,
   REST_CANONICAL_ROUTES,
   REST_CASE_SENSITIVE_ROUTES,
   REST_CORS_ORIGIN,
@@ -131,6 +132,74 @@ const config = {
   // keep a live assertion on this default.
   canonicalRoutes: REST_CANONICAL_ROUTES !== 'false',
 
+  // Secure by default, same polarity and same reasoning as the three keys
+  // above: a request whose RAW target percent-encodes an RFC 3986 2.3
+  // UNRESERVED character (ALPHA / DIGIT / "-" / "." / "_" / "~") is rejected
+  // with a plain 404 before the consumer's `auth` hook runs
+  // (abofs/stonyx-rest-server#56). Like canonicalRoutes this is NOT an express
+  // setting -- it is a per-request check in src/route-matching.ts
+  // (`shouldRejectEncoding`), called from the handler closure in
+  // src/request.ts.
+  //
+  // What it closes: express decodes `req.params` and NOTHING else, so a
+  // consumer hook comparing `req.path` OR `req.originalUrl` was walked past by
+  // re-spelling an id -- `GET /enc/secret` -> 401 while
+  // `GET /enc/%73ecret` -> 200 with the guarded handler running
+  // unauthenticated and `req.params.id === 'secret'`. The spelling family is
+  // PROD(1 + v_i) - 1 per id, measured at 63 spellings for `secret` and 71 for
+  // `admin`, ALL of them 200 before this key existed. It is EXCLUSIVE to route
+  // classes carrying a `:param` segment; literal routes and mount segments
+  // match raw and were never reachable this way.
+  //
+  // BEHAVIOUR CHANGE for consumers upgrading, on a FOURTH axis:
+  //   Any client that over-encodes an unreserved character in a path now gets
+  //   404. Measured on this repo's own fixture:
+  //   `GET /public/url-params/%61/b/c` -> 404 (was 200). Over-encoding an
+  //   unreserved character is never required by RFC 3986 -- a normaliser MUST
+  //   decode these (6.2.2.2) -- so the blast radius is smaller than #54's,
+  //   whose absolute-form vector hits a real deployment shape. It is still a
+  //   breaking change and it is documented as one in the README.
+  //
+  // Opt out with REST_CANONICAL_ENCODING=false only as a temporary remediation
+  // -- it RE-OPENS the bypass. SEPARATE key from REST_CANONICAL_ROUTES on
+  // purpose, and this one is not a symmetry argument but a measurement: with
+  // the rule gated on `canonicalRoutes` instead of its own key,
+  // `REST_CANONICAL_ROUTES=false` returns `GET /enc/%73ecret` to 200 -- and
+  // that flag is exactly what a consumer behind an absolute-form-emitting
+  // forward proxy must set to stay up. Folding the two would hand precisely
+  // those consumers the encoding bypass as the price. Killed by
+  // test/unit/request-test.ts AC5.
+  //
+  // DELIBERATELY NOT PINNED in test/config/environment.ts -- do not "fix" this
+  // as part of abofs/stonyx-rest-server#43. Both halves RE-MEASURED for this
+  // key rather than inferred from the three above, against the 41-test suite
+  // at #56's head:
+  //   (a) invert this line to `=== 'true'` ALONE, unpinned:
+  //       36 pass / 5 fail -- #56's integration AC1 and AC2, unit AC5 and AC6,
+  //       and [Unit] Config AC7. It fails LOUDLY, so there is no false green.
+  //   (b) pin `canonicalEncoding: true` in test/config/environment.ts AND
+  //       invert this line: 40 pass / 1 fail, and the ONE failure is
+  //       [Unit] Config AC7 -- every behavioural assertion goes green because
+  //       the pin supplies the secure value the suite then observes. Measured
+  //       again with test/unit/config-test.ts removed: 40 pass / 0 fail, a
+  //       fully green suite shipping an insecure default. That is the trap, and
+  //       AC7 is the only thing standing between this key and it.
+  //
+  // Conversely, weakening the READ in src/route-matching.ts to `=== true`
+  // reports 40 pass / 1 fail with unit AC6 as the only failure and every
+  // integration assertion green -- the two guard different halves and neither
+  // subsumes the other. Closing #43 for any of the four keys needs the
+  // subprocess-based env isolation this repo does not have; any fix must keep a
+  // live assertion on this default.
+  //
+  // FOUR security-relevant keys now, all defaulting on, all disable-able, none
+  // pinned. Per docs/framework/testing.md the pinned set has to be evaluated as
+  // a SET rather than key by key; [Unit] Config AC7 asserts all four together
+  // for that reason. Whoever takes #43 inherits four keys and this paragraph as
+  // the reason they are unpinned, rather than finding four and assuming
+  // neglect.
+  canonicalEncoding: REST_CANONICAL_ENCODING !== '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,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"}
+{"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;CAsHtB"}

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, { shouldRejectTarget } from './route-matching.js';
+import applyRouteMatching, { shouldRejectEncoding, shouldRejectTarget } from './route-matching.js';
 const METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
 export default class Request {
     static stateProp = '__stonyxState';
@@ -97,6 +97,32 @@ export default class Request {
                     // half of it was covered. Do not re-merge them.
                     if (shouldRejectTarget(req))
                         return next('router');
+                    // abofs/stonyx-rest-server#56 -- reject a request whose RAW target
+                    // spells an UNRESERVED character (RFC 3986 2.3) as a percent-triplet,
+                    // closing the authorization bypass against a hook that compares
+                    // `req.path` OR `req.originalUrl` on any route class with a `:param`
+                    // segment. Express decodes only `req.params`, so both raw fields see
+                    // `%73ecret` while the handler is given `secret`.
+                    //
+                    // A SEPARATE line and a SEPARATE predicate from #54's above, and it
+                    // must stay that way. Extending shouldRejectTarget()'s comparison
+                    // cannot reach this: `target === canonical` for EVERY one of these
+                    // spellings, because both sides carry the same encoded string.
+                    // Reading #54's key here is worse than useless -- measured, gating
+                    // this rule on `canonicalRoutes` returns `GET /enc/%73ecret` to 200
+                    // under `REST_CANONICAL_ROUTES=false`, which is exactly the flag an
+                    // absolute-form-proxy consumer must set. Killed by
+                    // `test/unit/request-test.ts` AC5.
+                    //
+                    // The same three load-bearing properties as the line above apply
+                    // verbatim -- outside `if (this.auth)`, BEFORE it, and rejecting with
+                    // `next('router')` rather than a sendStatus that answers `text/plain`
+                    // and becomes an oracle. They are killed here by
+                    // `test/integration/rest-server-test.ts` #56 AC1.4 (the shape
+                    // deep-equal against a genuine miss) and AC1.5 (`/private/%66ailure`
+                    // -> 404 rather than the hook's own status), on a class WITH a hook.
+                    if (shouldRejectEncoding(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

@@ -77,13 +77,14 @@ import type { Express, Request as ExpressRequest } from 'express';
  * 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
+ * All four guards in this file 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. Both are also asserted at the unit tier for BOTH
+ * config predates the key. All are also asserted at the unit tier for BOTH
  * failure shapes -- key present-and-`undefined` and key absent as an own
- * property -- in `test/unit/request-test.ts` (#47's AC6, #50's AC3). The
- * integration tier cannot see either: with the shipped default `true`, a
- * fail-open guard leaves every integration assertion green.
+ * property -- in `test/unit/request-test.ts` (#47's AC6, #50's AC3, #54's AC2,
+ * #56's AC6). The integration tier cannot see any of them: with the shipped
+ * default `true`, a fail-open guard leaves every integration assertion green.
  */
 export default function applyRouteMatching(api: Express): void;
 /**
@@ -126,7 +127,7 @@ export default function applyRouteMatching(api: Express): void;
  * 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
+ * Guard polarity is `!== false`, matching its three 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
@@ -142,4 +143,80 @@ export default function applyRouteMatching(api: Express): void;
  * key present-and-`undefined` and key absent as an own property.
  */
 export declare function shouldRejectTarget(req: ExpressRequest): boolean;
+/**
+ * Decides whether a request must be rejected because its RAW request target
+ * spells an unreserved character as a percent-triplet
+ * (abofs/stonyx-rest-server#56).
+ *
+ * Closes a live authorization bypass on any route class carrying a `:param`
+ * segment. Express decodes `req.params` and NOTHING else -- `req.path` and
+ * `req.originalUrl` both stay percent-encoded -- so a consumer hook comparing
+ * either of those raw fields was walked past by re-spelling the id:
+ *
+ *   GET /enc/secret     -> 401  (hook fires)
+ *   GET /enc/%73ecret   -> 200  guarded handler, unauthenticated, id "secret"
+ *
+ * Both hook shapes are affected and neither is safer than the other; there is
+ * no spelling that defeats one and not the same-id comparison in the other.
+ * A third shape is worse still: a LITERAL guarded route co-registered with a
+ * sibling `/:id` (this repo's own `test/sample/requests/private.ts`) has the
+ * encoded spelling miss the literal layer and be ABSORBED by the param route,
+ * so the guard is walked past without the guarded handler ever running --
+ * measured `GET /private/failure` -> 505 vs `GET /private/%66ailure` -> 200.
+ *
+ * THE RULE IS AN UNRESERVED-OCTET SCAN, NOT A DECODE-AND-COMPARE. Two wrong
+ * implementations were built and measured, and each breaks a legitimate
+ * request:
+ *
+ *   1. `decodeURIComponent(target) !== target` -- rejects `/enc/sec%2fret`
+ *      (404), which names the DISTINCT id `sec/ret`. The router SPLITS then
+ *      DECODES; a whole-target decode decodes then splits, and the two
+ *      disagree about `%2f` by construction. Killed by AC3.
+ *   2. decode until stable -- rejects `/enc/%2573ecret` (404), which names the
+ *      legitimate id `%73ecret`. Express decodes EXACTLY ONCE, so `%2561` is
+ *      not a bypass and a loop invents a false deny. Killed by AC4.
+ *
+ * WHY THIS IS NOT PART OF `shouldRejectTarget()` (#54), and why extending that
+ * comparison cannot work: for `GET /enc/%73ecret`, `originalUrl` is
+ * `/enc/%73ecret`, `baseUrl` is `/enc` and `path` is `/%73ecret`, so
+ * `target === canonical` -- both sides carry the SAME encoded string. The
+ * comparison is structurally blind to this axis and no change to it can see it.
+ *
+ * WHY IT IS A FOURTH KEY AND NOT A REUSE OF `canonicalRoutes`. Measured with
+ * the rule implemented correctly but gated on #54's key:
+ * `REST_CANONICAL_ROUTES=false` returns `GET /enc/%73ecret` to 200. That flag
+ * is exactly what a consumer behind an absolute-form-emitting forward proxy
+ * must set, so folding the two would hand precisely those consumers the
+ * encoding bypass as the price of staying up. Same argument the block above
+ * makes for why #50 is not a rename of #47. Pinned by
+ * `test/unit/request-test.ts` AC5, which also asserts -- in that same state --
+ * that #54's own vector IS re-opened, so an implementation that simply ignores
+ * `canonicalRoutes` cannot pass it vacuously.
+ *
+ * TIMING CONTRACT: identical to `shouldRejectTarget()` and NOT to the two
+ * settings above. Read per request, inside the handler closure in
+ * `Request.registerCalls()`; there is no lazy-materialisation hazard, so do not
+ * move it into `applyRouteMatching()`. The caller must reject with
+ * `next('router')`, and must run this BEFORE `this.auth` as well as outside
+ * `if (this.auth)` -- see src/request.ts.
+ *
+ * Guard polarity is `!== false`, matching all three siblings, for the same
+ * measured reason: the secure value is the TRUTHY one, so `=== true` fails OPEN
+ * for any consumer whose shipped `restServer` block predates the key. The
+ * integration tier CANNOT see that mutation -- with the shipped default `true`
+ * every integration assertion stays green -- so it is `test/unit/request-test.ts`
+ * AC6 that kills it, probing the key present-and-`undefined` and absent as an
+ * own property separately.
+ *
+ * WHAT THIS DOES NOT CLOSE, stated here rather than left implied. It cannot
+ * give each decoded id exactly one accepted spelling, because reserved
+ * characters must remain encodable: `/enc/a+b` and `/enc/a%2Bb` both name the
+ * id `a+b`, and `/enc/sec%2fret` and `/enc/sec%2Fret` both name `sec/ret`. So a
+ * hook comparing a raw path string REMAINS UNSOUND for any id containing a
+ * reserved character, and `req.params` -- which express decodes, and which is
+ * populated before `auth()` runs -- is the sound idiom. That residual is the
+ * consumer's comparison to own; the module cannot close it without 404ing
+ * encodings clients are required to emit.
+ */
+export declare function shouldRejectEncoding(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,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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;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;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAkBjE"}

package/dist/route-matching.js

@@ -77,13 +77,14 @@ import config from 'stonyx/config';
  * 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
+ * All four guards in this file 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. Both are also asserted at the unit tier for BOTH
+ * config predates the key. All are also asserted at the unit tier for BOTH
  * failure shapes -- key present-and-`undefined` and key absent as an own
- * property -- in `test/unit/request-test.ts` (#47's AC6, #50's AC3). The
- * integration tier cannot see either: with the shipped default `true`, a
- * fail-open guard leaves every integration assertion green.
+ * property -- in `test/unit/request-test.ts` (#47's AC6, #50's AC3, #54's AC2,
+ * #56's AC6). The integration tier cannot see any of them: with the shipped
+ * default `true`, a fail-open guard leaves every integration assertion green.
  */
 export default function applyRouteMatching(api) {
     if (config.restServer?.caseSensitiveRoutes !== false)
@@ -131,7 +132,7 @@ export default function applyRouteMatching(api) {
  * 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
+ * Guard polarity is `!== false`, matching its three 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
@@ -168,4 +169,120 @@ export function shouldRejectTarget(req) {
     const canonical = req.path === '/' && req.baseUrl ? req.baseUrl : req.baseUrl + req.path;
     return target !== canonical;
 }
+// RFC 3986 §2.3 UNRESERVED = ALPHA / DIGIT / "-" / "." / "_" / "~".
+//
+// These are the characters a URI generator MUST NOT percent-encode and that a
+// normaliser MUST decode (§6.2.2.2), so an encoded one carries no information
+// a client is ever required to send. Everything else -- every RESERVED
+// character and every non-ASCII octet -- stays encodable, which is the whole
+// reason this is an allowlist of octets rather than a ban on triplets. See
+// `shouldRejectEncoding()` below.
+const UNRESERVED_OCTET = /^[A-Za-z0-9\-._~]$/;
+// A percent-triplet: `%` followed by exactly two hex digits, either case.
+//
+// A `%` can never be part of ANOTHER triplet's hex digits, because `%` is not a
+// hex digit -- so scanning left to right without skipping cannot produce an
+// overlapping false match. `%2561` therefore yields exactly one candidate
+// (`%25`), which is the property AC4 pins.
+//
+// Malformed and over-long escapes (`%zz`, `%`, `%6`, `%c1%a1`, `%e0%81%a1`) are
+// deliberately NOT this function's business: `router@2.2.0`'s `decodeParam`
+// (lib/layer.js:225) answers 400 for them before any handler or hook runs.
+// Verified here rather than imported -- measured 400 both before and after this
+// change. None of those octets is unreserved, and the first three are not valid
+// triplets at all, so the rule does not touch them either way.
+const PERCENT_TRIPLET = /%([0-9A-Fa-f]{2})/g;
+/**
+ * Decides whether a request must be rejected because its RAW request target
+ * spells an unreserved character as a percent-triplet
+ * (abofs/stonyx-rest-server#56).
+ *
+ * Closes a live authorization bypass on any route class carrying a `:param`
+ * segment. Express decodes `req.params` and NOTHING else -- `req.path` and
+ * `req.originalUrl` both stay percent-encoded -- so a consumer hook comparing
+ * either of those raw fields was walked past by re-spelling the id:
+ *
+ *   GET /enc/secret     -> 401  (hook fires)
+ *   GET /enc/%73ecret   -> 200  guarded handler, unauthenticated, id "secret"
+ *
+ * Both hook shapes are affected and neither is safer than the other; there is
+ * no spelling that defeats one and not the same-id comparison in the other.
+ * A third shape is worse still: a LITERAL guarded route co-registered with a
+ * sibling `/:id` (this repo's own `test/sample/requests/private.ts`) has the
+ * encoded spelling miss the literal layer and be ABSORBED by the param route,
+ * so the guard is walked past without the guarded handler ever running --
+ * measured `GET /private/failure` -> 505 vs `GET /private/%66ailure` -> 200.
+ *
+ * THE RULE IS AN UNRESERVED-OCTET SCAN, NOT A DECODE-AND-COMPARE. Two wrong
+ * implementations were built and measured, and each breaks a legitimate
+ * request:
+ *
+ *   1. `decodeURIComponent(target) !== target` -- rejects `/enc/sec%2fret`
+ *      (404), which names the DISTINCT id `sec/ret`. The router SPLITS then
+ *      DECODES; a whole-target decode decodes then splits, and the two
+ *      disagree about `%2f` by construction. Killed by AC3.
+ *   2. decode until stable -- rejects `/enc/%2573ecret` (404), which names the
+ *      legitimate id `%73ecret`. Express decodes EXACTLY ONCE, so `%2561` is
+ *      not a bypass and a loop invents a false deny. Killed by AC4.
+ *
+ * WHY THIS IS NOT PART OF `shouldRejectTarget()` (#54), and why extending that
+ * comparison cannot work: for `GET /enc/%73ecret`, `originalUrl` is
+ * `/enc/%73ecret`, `baseUrl` is `/enc` and `path` is `/%73ecret`, so
+ * `target === canonical` -- both sides carry the SAME encoded string. The
+ * comparison is structurally blind to this axis and no change to it can see it.
+ *
+ * WHY IT IS A FOURTH KEY AND NOT A REUSE OF `canonicalRoutes`. Measured with
+ * the rule implemented correctly but gated on #54's key:
+ * `REST_CANONICAL_ROUTES=false` returns `GET /enc/%73ecret` to 200. That flag
+ * is exactly what a consumer behind an absolute-form-emitting forward proxy
+ * must set, so folding the two would hand precisely those consumers the
+ * encoding bypass as the price of staying up. Same argument the block above
+ * makes for why #50 is not a rename of #47. Pinned by
+ * `test/unit/request-test.ts` AC5, which also asserts -- in that same state --
+ * that #54's own vector IS re-opened, so an implementation that simply ignores
+ * `canonicalRoutes` cannot pass it vacuously.
+ *
+ * TIMING CONTRACT: identical to `shouldRejectTarget()` and NOT to the two
+ * settings above. Read per request, inside the handler closure in
+ * `Request.registerCalls()`; there is no lazy-materialisation hazard, so do not
+ * move it into `applyRouteMatching()`. The caller must reject with
+ * `next('router')`, and must run this BEFORE `this.auth` as well as outside
+ * `if (this.auth)` -- see src/request.ts.
+ *
+ * Guard polarity is `!== false`, matching all three siblings, for the same
+ * measured reason: the secure value is the TRUTHY one, so `=== true` fails OPEN
+ * for any consumer whose shipped `restServer` block predates the key. The
+ * integration tier CANNOT see that mutation -- with the shipped default `true`
+ * every integration assertion stays green -- so it is `test/unit/request-test.ts`
+ * AC6 that kills it, probing the key present-and-`undefined` and absent as an
+ * own property separately.
+ *
+ * WHAT THIS DOES NOT CLOSE, stated here rather than left implied. It cannot
+ * give each decoded id exactly one accepted spelling, because reserved
+ * characters must remain encodable: `/enc/a+b` and `/enc/a%2Bb` both name the
+ * id `a+b`, and `/enc/sec%2fret` and `/enc/sec%2Fret` both name `sec/ret`. So a
+ * hook comparing a raw path string REMAINS UNSOUND for any id containing a
+ * reserved character, and `req.params` -- which express decodes, and which is
+ * populated before `auth()` runs -- is the sound idiom. That residual is the
+ * consumer's comparison to own; the module cannot close it without 404ing
+ * encodings clients are required to emit.
+ */
+export function shouldRejectEncoding(req) {
+    // `!== false`, not `=== false` and not a truthy check: the polarity is the
+    // load-bearing part and it should read identically to the three guards above.
+    const enforced = config.restServer?.canonicalEncoding !== false;
+    if (!enforced)
+        return false;
+    // Raw, unparsed, and only the query string removed -- by string split, for
+    // the same reason #54 gives: parsing would launder the exact string the
+    // consumer's hook is exposed to. The query is stripped because a query string
+    // is a legitimately variable part of a request target and may carry any
+    // encoding at all; `?name=%61` is a normal request and must not 404.
+    const target = req.originalUrl.split('?')[0];
+    for (const [, hex] of target.matchAll(PERCENT_TRIPLET)) {
+        if (UNRESERVED_OCTET.test(String.fromCharCode(parseInt(hex, 16))))
+            return true;
+    }
+    return false;
+}
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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;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;AAED,oEAAoE;AACpE,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,uEAAuE;AACvE,6EAA6E;AAC7E,2EAA2E;AAC3E,kCAAkC;AAClC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAE9C,0EAA0E;AAC1E,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,0EAA0E;AAC1E,2CAA2C;AAC3C,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,2EAA2E;AAC3E,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAmB;IACtD,2EAA2E;IAC3E,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,iBAAiB,KAAK,KAAK,CAAC;IAChE,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5B,2EAA2E;IAC3E,wEAAwE;IACxE,8EAA8E;IAC9E,wEAAwE;IACxE,qEAAqE;IACrE,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7C,KAAK,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACvD,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAI,EAAE,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAClF,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

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