shelving 1.267.4 → 1.267.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.267.4",
+	"version": "1.267.6",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/router/Router.js

@@ -37,6 +37,7 @@ function _matchRoute(routes, fallback, meta, path = meta.path, depth = 0) {
         if (typeof Route === "string") {
             if (depth > 10)
                 throw new UnexpectedError("Infinite redirect loop", { received: route, expected: path, caller: _matchRoute });
+            // `placeholders` are already decoded by `matchPathTemplate`, so re-encode them into the redirect path with `renderPathTemplate` — the symmetric partner of the match above.
             return _matchRoute(routes, fallback, meta, renderPathTemplate(Route, placeholders), depth + 1);
         }
         // React element — render as-is.

package/ui/router/Router.tsx

@@ -61,6 +61,7 @@ function _matchRoute(
 		// String value is a redirect; re-run matching with the new path. Guard against infinite redirect loops by limiting depth.
 		if (typeof Route === "string") {
 			if (depth > 10) throw new UnexpectedError("Infinite redirect loop", { received: route, expected: path, caller: _matchRoute });
+			// `placeholders` are already decoded by `matchPathTemplate`, so re-encode them into the redirect path with `renderPathTemplate` — the symmetric partner of the match above.
 			return _matchRoute(routes, fallback, meta, renderPathTemplate(Route, placeholders), depth + 1);
 		}
 

package/util/template.d.ts

@@ -53,11 +53,13 @@ export declare function matchTemplate(template: string, target: string, caller?:
  * Match a path-shaped template against a target path.
  * - Like `matchTemplate()`, but with `/` segment semantics: non-catchall placeholders cannot span path segments; catchall placeholders can.
  * - A trailing catchall (e.g. `/files/{...path}`) also matches when the trailing separator is absent (e.g. `/files`), with the catchall value as `""`.
+ * - Matched values are **percent-decoded** (the inverse of `renderPathTemplate()`'s encoding), so a round trip is lossless: `matchPathTemplate(t, renderPathTemplate(t, values))` returns the original values. Catchall values keep their `/` separators (each segment is decoded).
+ * - Returns `undefined` if `target` is not validly percent-encoded (e.g. a bare `%` or `%zz`), treating a malformed path as a non-match.
  *
  * @param template The path-shaped template string, e.g. `/users/{name}`.
  * @param target The path containing values, e.g. `/users/Dave`.
  * @param caller Function to attribute a thrown error to (defaults to `matchPathTemplate` itself).
- * @returns An object containing values (e.g. `{ name: "Dave" }`), or `undefined` if no match.
+ * @returns An object containing decoded values (e.g. `{ name: "Dave" }`), or `undefined` if no match.
  * @throws {ValueError} If two template placeholders are not separated by at least one character.
  * @example matchPathTemplate("/users/{name}", "/users/Dave") // { name: "Dave" }
  * @see https://shelving.cc/util/template/matchPathTemplate
@@ -96,14 +98,23 @@ export declare function matchPathTemplates(templates: Iterable<AbsolutePath> & N
  */
 export declare function renderTemplate(template: string, values: TemplateValues, caller?: AnyCaller): string;
 /**
- * Render a path-shaped template. Behaviourally identical to `renderTemplate()` — substitution doesn't need separator awareness — but provided as a sibling to `matchPathTemplate()` so callers can pair them.
+ * Render a path-shaped template, percent-encoding each substituted value so it stays within its path segment.
+ *
+ * Unlike `renderTemplate()`, each placeholder value is run through `encodeURIComponent()` before substitution.
+ * This stops a value that contains `/`, `?`, `#`, `%`, or control characters from escaping its segment and
+ * altering the resolved URL — i.e. path traversal to a different endpoint, or query/fragment injection — when
+ * the result is resolved against a base URL (e.g. by `ClientAPIProvider`). Catchall placeholders (`**`,
+ * `{...path}`, …) legitimately span segments, so each `/`-separated part is encoded but the separators are kept.
+ *
+ * Note: because `encodeURIComponent()` does not encode `.`, a value that is exactly `.` or `..` still renders as
+ * `.`/`..`; callers that treat a placeholder as a trusted single segment should validate against those.
  *
  * @param template The path-shaped template including placeholders, e.g. `/users/{name}`.
  * @param values An object containing values (functions are called, everything else converted to string), or a function or string to use for all placeholders.
  * @param caller Function to attribute a thrown error to (defaults to `renderPathTemplate` itself).
- * @returns The rendered path, e.g. `/users/Dave`.
+ * @returns The rendered path with each value percent-encoded, e.g. `/users/Dave`.
  * @throws {RequiredError} If a placeholder in the template string is not specified in values.
- * @example renderPathTemplate("/users/{name}", { name: "Dave" }) // "/users/Dave"
+ * @example renderPathTemplate("/users/{name}", { name: "a/b" }) // "/users/a%2Fb"
  * @see https://shelving.cc/util/template/renderPathTemplate
  */
 export declare function renderPathTemplate(template: AbsolutePath, values: TemplateValues, caller?: AnyCaller): AbsolutePath;

package/util/template.js

@@ -83,25 +83,40 @@ function _getPlaceholder({ name }) {
  * @see https://shelving.cc/util/template/matchTemplate
  */
 export function matchTemplate(template, target, caller = matchTemplate) {
-    return _matchTemplate(template, target, "", caller);
+    return _matchTemplate(template, target, "", false, caller);
 }
 /**
  * Match a path-shaped template against a target path.
  * - Like `matchTemplate()`, but with `/` segment semantics: non-catchall placeholders cannot span path segments; catchall placeholders can.
  * - A trailing catchall (e.g. `/files/{...path}`) also matches when the trailing separator is absent (e.g. `/files`), with the catchall value as `""`.
+ * - Matched values are **percent-decoded** (the inverse of `renderPathTemplate()`'s encoding), so a round trip is lossless: `matchPathTemplate(t, renderPathTemplate(t, values))` returns the original values. Catchall values keep their `/` separators (each segment is decoded).
+ * - Returns `undefined` if `target` is not validly percent-encoded (e.g. a bare `%` or `%zz`), treating a malformed path as a non-match.
  *
  * @param template The path-shaped template string, e.g. `/users/{name}`.
  * @param target The path containing values, e.g. `/users/Dave`.
  * @param caller Function to attribute a thrown error to (defaults to `matchPathTemplate` itself).
- * @returns An object containing values (e.g. `{ name: "Dave" }`), or `undefined` if no match.
+ * @returns An object containing decoded values (e.g. `{ name: "Dave" }`), or `undefined` if no match.
  * @throws {ValueError} If two template placeholders are not separated by at least one character.
  * @example matchPathTemplate("/users/{name}", "/users/Dave") // { name: "Dave" }
  * @see https://shelving.cc/util/template/matchPathTemplate
  */
 export function matchPathTemplate(template, target, caller = matchPathTemplate) {
-    return _matchTemplate(template, target, "/", caller);
+    return _matchTemplate(template, target, "/", true, caller);
 }
-function _matchTemplate(template, target, separator, caller) {
+/**
+ * Decode a matched path value — the inverse of `renderPathTemplate()`'s `encodeURIComponent`.
+ * - Catchall values keep their `/` separators (each segment is decoded independently, mirroring the per-segment encode).
+ * - Returns `undefined` for malformed percent-encoding (e.g. a bare `%` or `%zz`), so the caller can reject the whole match.
+ */
+function _decodePathValue(value, catchall) {
+    try {
+        return catchall ? value.split("/").map(decodeURIComponent).join("/") : decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function _matchTemplate(template, target, separator, decode, caller) {
     // Get separators and placeholders from template.
     const chunks = _splitTemplateCached(template, caller);
     const firstChunk = chunks[0];
@@ -134,7 +149,18 @@ function _matchTemplate(template, target, separator, caller) {
             if (separator && value.includes(separator))
                 return undefined; // Non-catchall placeholders can't span separators (when one is configured).
         }
-        values[name] = value;
+        // In path mode, percent-decode the (still-encoded) value so it round-trips with `renderPathTemplate()`; a
+        // malformed encoding rejects the whole match. The separator check above runs on the encoded value first,
+        // so an encoded `%2F` can't smuggle a separator into a non-catchall segment.
+        if (decode) {
+            const decoded = _decodePathValue(value, catchall);
+            if (decoded === undefined)
+                return undefined;
+            values[name] = decoded;
+        }
+        else {
+            values[name] = value;
+        }
         startIndex = stopIndex + post.length;
     }
     if (startIndex < target.length)
@@ -191,14 +217,14 @@ export function renderTemplate(template, values, caller = renderTemplate) {
     let output = template;
     if (isFunction(values)) {
         for (const { name, placeholder } of chunks)
-            output = output.replace(placeholder, values(name));
+            output = output.replace(placeholder, _escapeReplacement(values(name)));
     }
     else if (isData(values)) {
         for (const { name, placeholder } of chunks) {
             const v = getString(getDataProp(values, name));
             if (v === undefined)
                 throw new RequiredError(`Template placeholder "${name}" not found in object`, { received: values, name, caller });
-            output = output.replace(placeholder, v);
+            output = output.replace(placeholder, _escapeReplacement(v));
         }
     }
     else if (isArray(values)) {
@@ -206,7 +232,7 @@ export function renderTemplate(template, values, caller = renderTemplate) {
             const v = getString(values[Number(name)]);
             if (v === undefined)
                 throw new RequiredError(`Template placeholder "${name}" not found in array`, { received: values, name, caller });
-            output = output.replace(placeholder, v);
+            output = output.replace(placeholder, _escapeReplacement(v));
         }
     }
     else {
@@ -214,21 +240,62 @@ export function renderTemplate(template, values, caller = renderTemplate) {
         if (v === undefined)
             throw new RequiredError(`Template value must be string`, { received: values, caller });
         for (const { placeholder } of chunks)
-            output = output.replace(placeholder, v);
+            output = output.replace(placeholder, _escapeReplacement(v));
     }
     return output;
 }
 /**
- * Render a path-shaped template. Behaviourally identical to `renderTemplate()` — substitution doesn't need separator awareness — but provided as a sibling to `matchPathTemplate()` so callers can pair them.
+ * Escape `$` in a `String.prototype.replace()` replacement value so it's inserted literally.
+ * - Without this, `$&`, `$'`, `` $` ``, `$1`, `$$` in a (often user-supplied) value are interpreted as replacement
+ *   patterns and pull surrounding template text into the value's slot.
+ * - Cheap: only rewrites when a `$` is actually present, so the common case is a single scan with no allocation.
+ */
+function _escapeReplacement(value) {
+    return value.includes("$") ? value.replaceAll("$", "$$$$") : value;
+}
+/**
+ * Render a path-shaped template, percent-encoding each substituted value so it stays within its path segment.
+ *
+ * Unlike `renderTemplate()`, each placeholder value is run through `encodeURIComponent()` before substitution.
+ * This stops a value that contains `/`, `?`, `#`, `%`, or control characters from escaping its segment and
+ * altering the resolved URL — i.e. path traversal to a different endpoint, or query/fragment injection — when
+ * the result is resolved against a base URL (e.g. by `ClientAPIProvider`). Catchall placeholders (`**`,
+ * `{...path}`, …) legitimately span segments, so each `/`-separated part is encoded but the separators are kept.
+ *
+ * Note: because `encodeURIComponent()` does not encode `.`, a value that is exactly `.` or `..` still renders as
+ * `.`/`..`; callers that treat a placeholder as a trusted single segment should validate against those.
  *
  * @param template The path-shaped template including placeholders, e.g. `/users/{name}`.
  * @param values An object containing values (functions are called, everything else converted to string), or a function or string to use for all placeholders.
  * @param caller Function to attribute a thrown error to (defaults to `renderPathTemplate` itself).
- * @returns The rendered path, e.g. `/users/Dave`.
+ * @returns The rendered path with each value percent-encoded, e.g. `/users/Dave`.
  * @throws {RequiredError} If a placeholder in the template string is not specified in values.
- * @example renderPathTemplate("/users/{name}", { name: "Dave" }) // "/users/Dave"
+ * @example renderPathTemplate("/users/{name}", { name: "a/b" }) // "/users/a%2Fb"
  * @see https://shelving.cc/util/template/renderPathTemplate
  */
 export function renderPathTemplate(template, values, caller = renderPathTemplate) {
-    return renderTemplate(template, values, caller);
+    const chunks = _splitTemplateCached(template, caller);
+    if (!chunks.length)
+        return template;
+    let output = template;
+    for (const { name, placeholder, catchall } of chunks) {
+        const value = _getTemplateValue(values, name, caller);
+        const encoded = catchall ? value.split("/").map(encodeURIComponent).join("/") : encodeURIComponent(value);
+        // Use a replacer function so `$` sequences in the (already-encoded) value are never treated as special replacement patterns.
+        output = output.replace(placeholder, () => encoded);
+    }
+    return output;
+}
+/** Resolve the string value for a single template placeholder from `TemplateValues` (mirrors `renderTemplate()`'s per-name resolution). */
+function _getTemplateValue(values, name, caller) {
+    const value = isFunction(values)
+        ? values(name)
+        : isData(values)
+            ? getString(getDataProp(values, name))
+            : isArray(values)
+                ? getString(values[Number(name)])
+                : getString(values);
+    if (value === undefined)
+        throw new RequiredError(`Template placeholder "${name}" not found`, { received: values, name, caller });
+    return value;
 }