nucleus-core-ts 0.10.151 → 0.10.152

package/dist/src/Client/Proxy/authz.d.ts

@@ -1,3 +1,5 @@
+import { pathMatchesTemplate } from '../../Shared/routeMatch';
+import { type RoutePathRefusal } from '../../Shared/routePath';
 import type { ManifestRoute, ProxyAuthorizeConfig, ProxyLogger } from './types';
 /**
  * Reverse-proxy claim-gate. Enforces the discovered `{serviceId}.{tag}.{op}` claims
@@ -13,8 +15,13 @@ export type { ManifestRoute, ProxyAuthorizeConfig } from './types';
 export declare function verifyJwtHS256(token: string, secret: string): Record<string, unknown> | null;
 /** Hierarchical prefix match: a shorter claim grants longer actions (`agent` ⇒ `agent.x.y`). */
 export declare function claimSatisfies(userClaims: string[], required: string): boolean;
-/** True when a concrete request path matches a templated OpenAPI path (params = wildcards). */
-export declare function pathMatchesTemplate(template: string, concrete: string): boolean;
+/** The route rule the IDP's discovery applies too: one copy, in src/Shared/routeMatch.ts. */
+export { pathMatchesTemplate };
+/**
+ * The action a request requires, or null when no route maps it. Matched on the path the
+ * backend routes (`%2F` decoded), the raw spelling only when that maps nothing:
+ * src/Shared/routeMatch.ts `findRouteAction`.
+ */
 export declare function findRequiredAction(manifest: ManifestRoute[], method: string, path: string): string | null;
 export interface AccessDecision {
     decision: 'allow' | 'deny';
@@ -23,6 +30,9 @@ export interface AccessDecision {
     /** When a ClaimGuard caused the denial, the guard's action (e.g. `token_spent_today`) so the
      *  client can render a human-readable message. */
     guard?: string;
+    /** Set with reason `ambiguous-path`: which reading of the path differs between routers.
+     *  The proxy answers it 400, in audit mode too (routePathOf in src/Shared/routePath.ts). */
+    pathRefusal?: RoutePathRefusal;
 }
 /**
  * Pure authorization decision. `claims`/`roles` are ALREADY resolved by the caller

package/dist/src/Client/Proxy/authz.js

@@ -10,6 +10,8 @@ function _define_property(obj, key, value) {
     return obj;
 }
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { findRouteAction, pathMatchesTemplate } from '../../Shared/routeMatch';
+import { routePathOf } from '../../Shared/routePath';
 /** HS256-verify a JWT and return its payload, or null if invalid/expired/tampered. */ export function verifyJwtHS256(token, secret) {
     const parts = token.split('.');
     if (parts.length !== 3) return null;
@@ -29,40 +31,13 @@ import { createHmac, timingSafeEqual } from 'node:crypto';
 /** Hierarchical prefix match: a shorter claim grants longer actions (`agent` ⇒ `agent.x.y`). */ export function claimSatisfies(userClaims, required) {
     return userClaims.some((uc)=>required === uc || required.startsWith(`${uc}.`));
 }
-/** True when a concrete request path matches a templated OpenAPI path (params = wildcards). */ export function pathMatchesTemplate(template, concrete) {
-    const t = template.replace(/\/+$/, '').split('/');
-    const c = concrete.replace(/\/+$/, '').split('/');
-    if (t.length !== c.length) return false;
-    for(let i = 0; i < t.length; i++){
-        const seg = t[i];
-        if (seg === undefined) return false;
-        if (seg.startsWith('{') && seg.endsWith('}')) {
-            // A path parameter must bind a REAL, non-empty segment. An empty segment (from a
-            // `//` double slash) is never a valid binding — reject it so the route stays
-            // unmapped (fail-closed) instead of over-matching the parameterized route's claim.
-            if (c[i] === '' || c[i] === undefined) return false;
-            continue;
-        }
-        if (seg !== c[i]) return false;
-    }
-    return true;
-}
-/** Count full-segment `{param}` wildcards — fewer = more specific (more literal segments). */ function templateSpecificity(template) {
-    return template.replace(/\/+$/, '').split('/').filter((s)=>s.startsWith('{') && s.endsWith('}')).length;
-}
-export function findRequiredAction(manifest, method, path) {
-    const m = method.toUpperCase();
-    const matches = manifest.filter((r)=>r.method === m && pathMatchesTemplate(r.path, path));
-    if (matches.length === 0) return null;
-    // MOST-SPECIFIC wins (never first-match): a literal route (`/files/admin`) must beat a
-    // parameterized sibling (`/files/{id}`) regardless of manifest order — else a request to
-    // an admin endpoint resolves to the weaker by-id claim (privilege escalation). Rank by
-    // fewest `{param}` segments, deterministic tiebreak on path for equal specificity.
-    matches.sort((a, b)=>{
-        const d = templateSpecificity(a.path) - templateSpecificity(b.path);
-        return d !== 0 ? d : a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
-    });
-    return matches[0]?.action ?? null;
+/** The route rule the IDP's discovery applies too: one copy, in src/Shared/routeMatch.ts. */ export { pathMatchesTemplate };
+/**
+ * The action a request requires, or null when no route maps it. Matched on the path the
+ * backend routes (`%2F` decoded), the raw spelling only when that maps nothing:
+ * src/Shared/routeMatch.ts `findRouteAction`.
+ */ export function findRequiredAction(manifest, method, path) {
+    return findRouteAction(manifest, method, path);
 }
 function matchesGlob(path, patterns) {
     if (!patterns?.length) return false;
@@ -86,11 +61,26 @@ function matchesGlob(path, patterns) {
  * this stays mode-agnostic and easy to test.
  */ export function evaluateAccess(args) {
     const { manifest, method, path, authenticated, roles, claims, onUnmapped, publicPaths, godminRole, suppressedClaims, firedGuards } = args;
-    if (matchesGlob(path, publicPaths)) return {
-        decision: 'allow',
-        reason: 'public',
-        action: null
-    };
+    // The route is decided on the path the backend routes, never the raw bytes: `%2F` is a
+    // separator to uvicorn, so a raw match let `/api%2Fv1/x` off its template and onto
+    // onUnmapped. A path that means different routes to different readers is refused outright,
+    // before any other rule, whoever asks (src/Shared/routePath.ts).
+    const routed = routePathOf(path);
+    if (!routed.ok) {
+        return {
+            decision: 'deny',
+            reason: 'ambiguous-path',
+            action: null,
+            pathRefusal: routed.refusal
+        };
+    }
+    if (matchesGlob(routed.path, publicPaths)) {
+        return {
+            decision: 'allow',
+            reason: 'public',
+            action: null
+        };
+    }
     const action = findRequiredAction(manifest, method, path);
     if (action === null) {
         // Fail CLOSED when the manifest has never loaded — an empty manifest from an unreachable

package/dist/src/Client/Proxy/httpProxy.js

@@ -1,6 +1,7 @@
 import { evaluateAccess, ManifestCache, RoleClaimsCache, resolveClaimsFromRoles, verifyJwtHS256 } from './authz';
 import { canBufferForRetry, timeoutForBody } from './largeBody';
 import { failureOfStatus, refreshFailureResponse } from './refreshOutcome';
+import { cookieWithRefreshedToken } from './retryCookie';
 import { createProxyLogger, matchPath, parseCookies, redactSecrets, rewritePath } from './utils';
 async function fetchSuppressedClaims(url, cookieHeader, logger) {
     const empty = {
@@ -367,6 +368,23 @@ export function createHttpProxyHandler(config) {
             firedGuards: suppression?.firedGuards
         });
         if (decision.decision === 'allow') return null;
+        // A path the gate cannot map the way the backend will is refused in either mode: under
+        // audit the gate still names guards (claim_guard below is enforced there), and a path
+        // that reads as another route downstream would carry a request past one.
+        if (decision.reason === 'ambiguous-path') {
+            logger.warn(`[authz] 400 ambiguous-path ${req.method} ${path} (${decision.pathRefusal})`);
+            return new Response(JSON.stringify({
+                success: false,
+                message: 'Bad Request',
+                reason: 'ambiguous_path',
+                detail: decision.pathRefusal ?? null
+            }), {
+                status: 400,
+                headers: {
+                    'content-type': 'application/json'
+                }
+            });
+        }
         const detail = `${req.method} ${path} (${decision.reason}${decision.guard ? ` guard=${decision.guard}` : ''}${decision.action ? ` need ${decision.action}` : ''})`;
         // A ClaimGuard block is a HARD, live condition: enforce it even while the general gate is
         // auditing. Every other would-block (missing-claim, unmapped) still only logs in audit mode.
@@ -737,6 +755,11 @@ export function createHttpProxyHandler(config) {
                         const refreshResult = attempt.result;
                         const retryHeaders = buildHeaders(req, target, clientIp);
                         injectToken(retryHeaders, refreshResult.accessToken, tokenHeaderName);
+                        // One token per retry: the cookie that carried the stale one carries the new one,
+                        // or a backend that compares the two refuses the retry (retryCookie.ts).
+                        const retryCookie = cookieWithRefreshedToken(retryHeaders.get('cookie'), accessCookieName, accessToken, refreshResult.accessToken);
+                        if (retryCookie) retryHeaders.set('cookie', retryCookie);
+                        else retryHeaders.delete('cookie');
                         logger.info(`[TokenRefresh] Retrying ${req.method} ${path} with new token`);
                         const retryResponse = await forwardRequest(finalUrl, req.method, retryHeaders, bodyForRetry ? new Response(bodyForRetry).body : null, timeout, followRedirects, req.signal);
                         const retryDuration = performance.now() - startTime;

package/dist/src/Client/Proxy/index.d.ts

@@ -1,3 +1,11 @@
+export type { RoutePath, RoutePathRefusal } from '../../Shared/routePath';
+/**
+ * The path a backend routes and the claim gate's own decision, for a consumer that gates
+ * or previews requests the way this proxy does (a portal's spend guard, an IDP's
+ * enforcement preview) instead of keeping a copy that drifts.
+ */
+export { asgiRoutePath, routePathOf } from '../../Shared/routePath';
+export { claimSatisfies, evaluateAccess, findRequiredAction, pathMatchesTemplate, resolveClaimsFromRoles, } from './authz';
 export { createHttpProxyHandler } from './httpProxy';
 export type { RefreshFailure } from './refreshOutcome';
 export { failureOfStatus, refreshFailureResponse, sessionEndCookies } from './refreshOutcome';

package/dist/src/Client/Proxy/index.js

@@ -1,3 +1,9 @@
+/**
+ * The path a backend routes and the claim gate's own decision, for a consumer that gates
+ * or previews requests the way this proxy does (a portal's spend guard, an IDP's
+ * enforcement preview) instead of keeping a copy that drifts.
+ */ export { asgiRoutePath, routePathOf } from '../../Shared/routePath';
+export { claimSatisfies, evaluateAccess, findRequiredAction, pathMatchesTemplate, resolveClaimsFromRoles } from './authz';
 export { createHttpProxyHandler } from './httpProxy';
 export { failureOfStatus, refreshFailureResponse, sessionEndCookies } from './refreshOutcome';
 export { createProxyServer, defaultProxyConfig } from './server';

package/dist/src/Client/Proxy/retryCookie.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Cookie header a request is RETRIED with after a refresh.
+ *
+ * WHY THIS EXISTS. A 401 is answered by refreshing the token and sending the request
+ * again with the new one as its Bearer. Until 0.10.152 the retry copied the caller's
+ * Cookie header as it arrived, so the backend got the NEW token in `Authorization` and
+ * the OLD one in the `access_token` cookie. A backend that checks both refuses that pair
+ * outright (the Vorion LLM answers CALLER_PROOF_CONFLICT: "the Bearer token and the
+ * access-token cookie differ"), so the retry failed every time and every visit after
+ * an idle half hour spent a refresh-token rotation for nothing.
+ *
+ * The retry now carries one token: every cookie that held the token the first attempt
+ * sent — the access cookie by name, and any fallback cookie it was read from — holds the
+ * refreshed one. Nothing is added: a request that sent no access cookie retries without
+ * one, the Bearer carries the token. Every other cookie, and the order, is kept.
+ */
+export declare function cookieWithRefreshedToken(cookieHeader: string | null, accessCookieName: string, staleToken: string | undefined, freshToken: string): string | null;

package/dist/src/Client/Proxy/retryCookie.js

@@ -0,0 +1,27 @@
+/**
+ * The Cookie header a request is RETRIED with after a refresh.
+ *
+ * WHY THIS EXISTS. A 401 is answered by refreshing the token and sending the request
+ * again with the new one as its Bearer. Until 0.10.152 the retry copied the caller's
+ * Cookie header as it arrived, so the backend got the NEW token in `Authorization` and
+ * the OLD one in the `access_token` cookie. A backend that checks both refuses that pair
+ * outright (the Vorion LLM answers CALLER_PROOF_CONFLICT: "the Bearer token and the
+ * access-token cookie differ"), so the retry failed every time and every visit after
+ * an idle half hour spent a refresh-token rotation for nothing.
+ *
+ * The retry now carries one token: every cookie that held the token the first attempt
+ * sent — the access cookie by name, and any fallback cookie it was read from — holds the
+ * refreshed one. Nothing is added: a request that sent no access cookie retries without
+ * one, the Bearer carries the token. Every other cookie, and the order, is kept.
+ */ export function cookieWithRefreshedToken(cookieHeader, accessCookieName, staleToken, freshToken) {
+    if (!cookieHeader) return cookieHeader;
+    return cookieHeader.split(';').map((part)=>{
+        const pair = part.trim();
+        const eq = pair.indexOf('=');
+        if (eq <= 0) return pair;
+        const name = pair.slice(0, eq).trim();
+        const value = pair.slice(eq + 1).trim();
+        const stale = name === accessCookieName || staleToken !== undefined && value === staleToken;
+        return stale ? `${name}=${freshToken}` : pair;
+    }).filter((pair)=>pair.length > 0).join('; ');
+}

package/dist/src/Services/Authorization/EndpointDiscovery/index.d.ts

@@ -8,6 +8,7 @@
  * be found by the `{serviceId}.` prefix during reconcile. `serviceId` therefore MUST
  * NOT be an HTTP-method word (get/post/put/patch/delete/toggle/bulk).
  */
+import { pathMatchesTemplate } from '../../../Shared/routeMatch';
 import { type FetchOpenApiOptions } from './fetch';
 export interface ClaimSpec {
     action: string;
@@ -37,15 +38,15 @@ export interface ParseOptions {
  * operationIds (method+path is unique within an OpenAPI doc).
  */
 export declare function parseOpenApiToClaims(serviceId: string, doc: OpenApiDoc, opts?: ParseOptions): ClaimSpec[];
-/** True when a concrete request path matches a templated OpenAPI path. */
-export declare function pathMatchesTemplate(template: string, concrete: string): boolean;
+/** True when a concrete request path matches a templated OpenAPI path (src/Shared/routeMatch.ts). */
+export { pathMatchesTemplate };
 /**
  * Given the claim specs for a service and an incoming (method, concrete-path),
  * return the required claim action, or null when no route matches (the caller
- * decides allow/deny for unmapped routes). When several templates match, the
- * MOST-SPECIFIC one wins (never first-declared): a literal route must beat a
- * parameterized sibling so `/files/admin` requires its own claim, not `/files/{id}`'s.
- * This MUST stay in lockstep with the proxy's findRequiredAction (Client/Proxy/authz.ts).
+ * decides allow/deny for unmapped routes). The most specific template wins, and the
+ * path is matched as the backend routes it (`%2F` decoded) before its raw spelling.
+ * It is the proxy's own rule (Client/Proxy/authz.ts `findRequiredAction`): both call
+ * `findRouteAction` in src/Shared/routeMatch.ts, so they cannot drift apart.
  */
 export declare function matchRouteToAction(specs: ClaimSpec[], method: string, concretePath: string): string | null;
 /** An existing claim row as seen during reconcile. */

package/dist/src/Shared/routeMatch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which discovered route a request is: the one rule the proxy's claim gate
+ * (`src/Client/Proxy/authz.ts` `findRequiredAction`) and the IDP's discovery
+ * (`src/Services/Authorization/EndpointDiscovery` `matchRouteToAction`) both apply.
+ * They used to carry a copy each, kept "in lockstep" by a comment; one copy is how
+ * they stay the same.
+ */
+/** One route: an OpenAPI method + templated path, and the claim action it requires. */
+export interface RouteRow {
+    action: string;
+    path: string;
+    method: string;
+}
+/** True when a concrete request path matches a templated OpenAPI path (params = wildcards). */
+export declare function pathMatchesTemplate(template: string, concrete: string): boolean;
+/**
+ * The action a request requires, or null when no route maps it.
+ *
+ * Matched first on the path the backend routes ({@link asgiRoutePath}: `%2F` is a
+ * separator there), so an encoded separator can no longer move a request off its
+ * template. Only when that path maps nothing is the raw path tried: a Starlette
+ * `{p:path}` parameter takes `a%2Fb` as one value, and the manifest, built from
+ * `/openapi.json` where FastAPI strips the converter, shows it as one `{p}` segment —
+ * matching the raw spelling keeps such a request on the route it always mapped to.
+ * The raw path can therefore only ADD a requirement the decoded one lacked.
+ */
+export declare function findRouteAction<R extends RouteRow>(routes: readonly R[], method: string, path: string): string | null;

package/dist/src/Shared/routeMatch.js

@@ -0,0 +1,53 @@
+import { asgiRoutePath } from './routePath';
+const isParameter = (segment)=>segment.startsWith('{') && segment.endsWith('}');
+const segmentsOf = (path)=>path.replace(/\/+$/, '').split('/');
+/** True when a concrete request path matches a templated OpenAPI path (params = wildcards). */ export function pathMatchesTemplate(template, concrete) {
+    const t = segmentsOf(template);
+    const c = segmentsOf(concrete);
+    if (t.length !== c.length) return false;
+    for(let i = 0; i < t.length; i++){
+        const seg = t[i];
+        if (seg === undefined) return false;
+        if (isParameter(seg)) {
+            // A path parameter must bind a REAL, non-empty segment. An empty segment (from a
+            // `//` double slash) is never a valid binding — reject it so the route stays
+            // unmapped (fail-closed) instead of over-matching the parameterized route's claim.
+            if (c[i] === '' || c[i] === undefined) return false;
+            continue;
+        }
+        if (seg !== c[i]) return false;
+    }
+    return true;
+}
+/** Count full-segment `{param}` wildcards — fewer = more specific (more literal segments). */ function templateSpecificity(template) {
+    return segmentsOf(template).filter(isParameter).length;
+}
+function mostSpecificAction(routes, method, path) {
+    const matches = routes.filter((r)=>r.method === method && pathMatchesTemplate(r.path, path));
+    // MOST-SPECIFIC wins (never first-match): a literal route (`/files/admin`) must beat a
+    // parameterized sibling (`/files/{id}`) regardless of manifest order — else a request to
+    // an admin endpoint resolves to the weaker by-id claim (privilege escalation). Rank by
+    // fewest `{param}` segments, deterministic tiebreak on path for equal specificity.
+    matches.sort((a, b)=>{
+        const d = templateSpecificity(a.path) - templateSpecificity(b.path);
+        return d !== 0 ? d : a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+    });
+    return matches[0]?.action ?? null;
+}
+/**
+ * The action a request requires, or null when no route maps it.
+ *
+ * Matched first on the path the backend routes ({@link asgiRoutePath}: `%2F` is a
+ * separator there), so an encoded separator can no longer move a request off its
+ * template. Only when that path maps nothing is the raw path tried: a Starlette
+ * `{p:path}` parameter takes `a%2Fb` as one value, and the manifest, built from
+ * `/openapi.json` where FastAPI strips the converter, shows it as one `{p}` segment —
+ * matching the raw spelling keeps such a request on the route it always mapped to.
+ * The raw path can therefore only ADD a requirement the decoded one lacked.
+ */ export function findRouteAction(routes, method, path) {
+    const m = method.toUpperCase();
+    const routed = asgiRoutePath(path);
+    const action = mostSpecificAction(routes, m, routed);
+    if (action !== null || routed === path) return action;
+    return mostSpecificAction(routes, m, path);
+}

package/dist/src/Shared/routePath.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The path a backend router sees, computed from the raw path a proxy forwards.
+ *
+ * WHY THIS EXISTS. A proxy that gates by route must match the request against the
+ * route the BACKEND will serve, not against the bytes on the wire. The services behind
+ * the claim gate are FastAPI on uvicorn, and uvicorn percent-decodes the raw path once
+ * (`urllib.parse.unquote`) before Starlette picks a route: `/api%2Fv1/x` is served by the
+ * `/api/v1/x` route. Matching the raw path made `%2F` a way off a guarded template and
+ * onto `onUnmapped` (nucleus-core-ts 0.10.151 and earlier).
+ *
+ * The WHATWG URL parser has already resolved `.`, `..` and their `%2e` spellings before
+ * a proxy reads `url.pathname`. What survives it are encoded separators: `%2F`, `%5C`,
+ * and dot segments that only appear once those are decoded (`x%2F..%2Fy`).
+ *
+ * Two answers:
+ * - {@link asgiRoutePath}: the one decode uvicorn applies, nothing more;
+ * - {@link routePathOf}: that decode, or a refusal when the path means different routes
+ *   to different readers. Starlette does not resolve a decoded `..`, some proxies and
+ *   frameworks do; `\` is a separator to some servers and text to others; and a path
+ *   whose second decode adds a separator is one hop away from another route. None of
+ *   those shapes is sent by a client that is not looking for the difference, so they
+ *   are refused rather than guessed.
+ *
+ * Lives in `src/Shared` because the proxy entry (`nucleus-core-ts/proxy`) is transpiled
+ * file by file and may import only its own folder and this one (nucleus.config.ts).
+ */
+/**
+ * One pass of CPython 3.11 `urllib.parse.unquote`, the decode uvicorn applies:
+ * - a run of valid `%XX` escapes becomes its bytes read as UTF-8; bytes that are not
+ *   valid UTF-8 become U+FFFD (`errors='replace'`), and a leading BOM is kept;
+ * - `%` not followed by two hex digits stays literal;
+ * - one pass only: `%252F` becomes the text `%2F`, never a separator.
+ * It never throws, where `decodeURIComponent` does on a malformed escape.
+ */
+export declare function asgiRoutePath(rawPath: string): string;
+/** Why a path was refused: which reading would differ between routers. */
+export type RoutePathRefusal = 'dot-segment' | 'backslash' | 'double-encoded';
+export type RoutePath = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    refusal: RoutePathRefusal;
+};
+/**
+ * The path to match routes against, or the reason it cannot be matched safely.
+ *
+ * `ok` carries {@link asgiRoutePath} of the input. Refused:
+ * - `dot-segment`: the decode produced a `.` or `..` segment;
+ * - `backslash`: the decode produced a `\`;
+ * - `double-encoded`: decoding the result again (up to eight more times) would add a
+ *   `/`, a `\` or a dot segment — `%252F`, `%255C`, `%252E%252E` between slashes.
+ * A further decode that changes only text inside a segment (`%2541` → `%41` → `A`)
+ * moves no route boundary and is not refused.
+ */
+export declare function routePathOf(rawPath: string): RoutePath;

package/dist/src/Shared/routePath.js

@@ -0,0 +1,97 @@
+/**
+ * The path a backend router sees, computed from the raw path a proxy forwards.
+ *
+ * WHY THIS EXISTS. A proxy that gates by route must match the request against the
+ * route the BACKEND will serve, not against the bytes on the wire. The services behind
+ * the claim gate are FastAPI on uvicorn, and uvicorn percent-decodes the raw path once
+ * (`urllib.parse.unquote`) before Starlette picks a route: `/api%2Fv1/x` is served by the
+ * `/api/v1/x` route. Matching the raw path made `%2F` a way off a guarded template and
+ * onto `onUnmapped` (nucleus-core-ts 0.10.151 and earlier).
+ *
+ * The WHATWG URL parser has already resolved `.`, `..` and their `%2e` spellings before
+ * a proxy reads `url.pathname`. What survives it are encoded separators: `%2F`, `%5C`,
+ * and dot segments that only appear once those are decoded (`x%2F..%2Fy`).
+ *
+ * Two answers:
+ * - {@link asgiRoutePath}: the one decode uvicorn applies, nothing more;
+ * - {@link routePathOf}: that decode, or a refusal when the path means different routes
+ *   to different readers. Starlette does not resolve a decoded `..`, some proxies and
+ *   frameworks do; `\` is a separator to some servers and text to others; and a path
+ *   whose second decode adds a separator is one hop away from another route. None of
+ *   those shapes is sent by a client that is not looking for the difference, so they
+ *   are refused rather than guessed.
+ *
+ * Lives in `src/Shared` because the proxy entry (`nucleus-core-ts/proxy`) is transpiled
+ * file by file and may import only its own folder and this one (nucleus.config.ts).
+ */ const escapeRun = /(?:%[0-9A-Fa-f]{2})+/g;
+const utf8 = new TextDecoder('utf-8', {
+    ignoreBOM: true
+});
+/** How many further decodes are checked for a separator that would appear. */ const DECODE_ROUNDS = 8;
+/**
+ * One pass of CPython 3.11 `urllib.parse.unquote`, the decode uvicorn applies:
+ * - a run of valid `%XX` escapes becomes its bytes read as UTF-8; bytes that are not
+ *   valid UTF-8 become U+FFFD (`errors='replace'`), and a leading BOM is kept;
+ * - `%` not followed by two hex digits stays literal;
+ * - one pass only: `%252F` becomes the text `%2F`, never a separator.
+ * It never throws, where `decodeURIComponent` does on a malformed escape.
+ */ export function asgiRoutePath(rawPath) {
+    return rawPath.replace(escapeRun, (run)=>{
+        const bytes = new Uint8Array(run.length / 3);
+        for(let i = 0; i < bytes.length; i++){
+            bytes[i] = Number.parseInt(run.slice(i * 3 + 1, i * 3 + 3), 16);
+        }
+        return utf8.decode(bytes);
+    });
+}
+function shapeOf(path) {
+    const segments = path.split('/');
+    return {
+        segments: segments.length,
+        dots: segments.some((segment)=>segment === '.' || segment === '..'),
+        backslash: path.includes('\\')
+    };
+}
+/**
+ * The path to match routes against, or the reason it cannot be matched safely.
+ *
+ * `ok` carries {@link asgiRoutePath} of the input. Refused:
+ * - `dot-segment`: the decode produced a `.` or `..` segment;
+ * - `backslash`: the decode produced a `\`;
+ * - `double-encoded`: decoding the result again (up to eight more times) would add a
+ *   `/`, a `\` or a dot segment — `%252F`, `%255C`, `%252E%252E` between slashes.
+ * A further decode that changes only text inside a segment (`%2541` → `%41` → `A`)
+ * moves no route boundary and is not refused.
+ */ export function routePathOf(rawPath) {
+    const routed = asgiRoutePath(rawPath);
+    if (routed === rawPath) return {
+        ok: true,
+        path: routed
+    };
+    const shape = shapeOf(routed);
+    if (shape.dots) return {
+        ok: false,
+        refusal: 'dot-segment'
+    };
+    if (shape.backslash) return {
+        ok: false,
+        refusal: 'backslash'
+    };
+    let current = routed;
+    for(let round = 0; round < DECODE_ROUNDS; round++){
+        const next = asgiRoutePath(current);
+        if (next === current) break;
+        const later = shapeOf(next);
+        if (later.segments !== shape.segments || later.dots || later.backslash) {
+            return {
+                ok: false,
+                refusal: 'double-encoded'
+            };
+        }
+        current = next;
+    }
+    return {
+        ok: true,
+        path: routed
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleus-core-ts",
-  "version": "0.10.151",
+  "version": "0.10.152",
   "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
   "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
   "license": "SEE LICENSE IN LICENSE",