@crabcrop/url 0.1.0 → 0.2.0

package/README.md

@@ -48,7 +48,10 @@ const group = purgeGroupSignature("your-secret", "thumb");
 
 // Upload signatures for the server's PUT /upload/<signature>/<name>
 // endpoint live in a third domain, under their own derived subkey.
+// Pass an expiry (unix seconds) for a token that stops working
+// then; its path is /upload/<signature>/exp:<expiry>/<name>.
 const upload = uploadSignature("your-secret", "heroes/photo.jpg");
+const expiring = uploadSignature("your-secret", "heroes/photo.jpg", 1893456000);
 ```
 
 Pass `null` as the secret to produce the literal `unsafe` signature segment, for servers running with `CRABCROP_ALLOW_UNSAFE` or in presets-only mode.

package/dist/index.d.ts

@@ -16,9 +16,12 @@ export declare function sign(secret: string, remainder: string): string;
  */
 export declare function purgeSignature(secret: string, target: string): string;
 /**
- * The purge-group signature for a cache group: a purge
- * signature over the literal string `purge-group/<group>`,
- * which appears nowhere in the request URL. The helper
+ * The purge-group signature for a cache group: HMAC-SHA256
+ * of the group name under a subkey derived from the secret
+ * (the raw HMAC of the secret over the label
+ * `crabcrop/purge-group-key`), its own domain beside the
+ * purge subkey, so a per-target purge signature can never
+ * be transplanted to the purge-group endpoint. The helper
  * exists so nobody has to know the signed string. This is
  * the signature segment for
  * `POST /purge-group/<signature>/<group>`.
@@ -31,8 +34,17 @@ export declare function purgeGroupSignature(secret: string, group: string): stri
  * so neither an image signature nor a purge signature can
  * ever be replayed as an upload signature. This is the
  * signature segment for `PUT /upload/<signature>/<name>`.
+ *
+ * With `expires` (unix seconds), the signature covers
+ * `exp:<expires>/<name>` instead, and the request path is
+ * `PUT /upload/<signature>/exp:<expires>/<name>`: the
+ * expiry sits inside the signed string, so it can neither
+ * be stripped nor extended, and the server refuses the
+ * upload once that second is reached. Delegated upload
+ * tokens should always use the expiring form; without it
+ * a token replays until the secret rotates.
  */
-export declare function uploadSignature(secret: string, name: string): string;
+export declare function uploadSignature(secret: string, name: string, expires?: number): string;
 export interface BuildOptions {
     /** Unix-seconds expiry, emitted as a leading `exp:` segment. */
     expires?: number;

package/dist/index.js

@@ -26,15 +26,19 @@ export function purgeSignature(secret, target) {
     return createHmac("sha256", subkey).update(target, "utf8").digest("hex");
 }
 /**
- * The purge-group signature for a cache group: a purge
- * signature over the literal string `purge-group/<group>`,
- * which appears nowhere in the request URL. The helper
+ * The purge-group signature for a cache group: HMAC-SHA256
+ * of the group name under a subkey derived from the secret
+ * (the raw HMAC of the secret over the label
+ * `crabcrop/purge-group-key`), its own domain beside the
+ * purge subkey, so a per-target purge signature can never
+ * be transplanted to the purge-group endpoint. The helper
  * exists so nobody has to know the signed string. This is
  * the signature segment for
  * `POST /purge-group/<signature>/<group>`.
  */
 export function purgeGroupSignature(secret, group) {
-    return purgeSignature(secret, `purge-group/${group}`);
+    const subkey = Buffer.from(sign(secret, "crabcrop/purge-group-key"), "hex");
+    return createHmac("sha256", subkey).update(group, "utf8").digest("hex");
 }
 /**
  * The upload signature for an object name: HMAC-SHA256 of
@@ -43,10 +47,20 @@ export function purgeGroupSignature(secret, group) {
  * so neither an image signature nor a purge signature can
  * ever be replayed as an upload signature. This is the
  * signature segment for `PUT /upload/<signature>/<name>`.
+ *
+ * With `expires` (unix seconds), the signature covers
+ * `exp:<expires>/<name>` instead, and the request path is
+ * `PUT /upload/<signature>/exp:<expires>/<name>`: the
+ * expiry sits inside the signed string, so it can neither
+ * be stripped nor extended, and the server refuses the
+ * upload once that second is reached. Delegated upload
+ * tokens should always use the expiring form; without it
+ * a token replays until the secret rotates.
  */
-export function uploadSignature(secret, name) {
+export function uploadSignature(secret, name, expires) {
     const subkey = Buffer.from(sign(secret, "crabcrop/upload-key"), "hex");
-    return createHmac("sha256", subkey).update(name, "utf8").digest("hex");
+    const signed = expires === undefined ? name : `exp:${expires}/${name}`;
+    return createHmac("sha256", subkey).update(signed, "utf8").digest("hex");
 }
 /** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
 export function isValidKeyId(id) {
@@ -175,8 +189,14 @@ export function verifyUrlSignature(secret, input) {
         return matches(secret);
     }
     if (signature.keyId !== undefined) {
-        const candidate = secret[signature.keyId];
-        return candidate === undefined ? false : matches(candidate);
+        // Own properties only: key IDs are attacker-shaped text
+        // (`constructor`, `toString`, `__proto__` are all legal
+        // IDs), and an inherited lookup would hand a non-string
+        // to the HMAC and throw instead of answering false.
+        const candidate = Object.hasOwn(secret, signature.keyId)
+            ? secret[signature.keyId]
+            : undefined;
+        return typeof candidate === "string" ? matches(candidate) : false;
     }
     return Object.values(secret).some(matches);
 }

package/dist/operations.js

@@ -89,10 +89,13 @@ function encodeArg(text) {
 }
 function className(what, name) {
     const trimmed = name.trim();
-    if (trimmed.length < 1 ||
-        trimmed.length > 64 ||
-        !/^[\p{L}\p{N} _.\-/]+$/u.test(trimmed)) {
-        fail(what, name, "1 to 64 characters of letters, digits, space, `_`, `.`, `-`, `/`");
+    // The server's bound is on UTF-8 bytes, not UTF-16 code
+    // units: a name of multibyte characters can pass a
+    // length check here and still be rejected there, so
+    // measure the encoded form, as the explainer does.
+    const bytes = new TextEncoder().encode(trimmed).length;
+    if (bytes < 1 || bytes > 64 || !/^[\p{L}\p{N} _.\-/]+$/u.test(trimmed)) {
+        fail(what, name, "1 to 64 UTF-8 bytes of letters, digits, space, `_`, `.`, `-`, `/`");
     }
     return encodeArg(name);
 }
@@ -175,8 +178,12 @@ export const ops = {
     },
     /** `preset:thumb`; expands server-side. */
     preset(name) {
-        if (name === "" || name.includes("/") || name.includes(":")) {
-            fail("preset name", name, "a non-empty preset name without `/` or `:`");
+        // The server can only configure names from this
+        // charset (its preset file validation), so anything
+        // outside it is a reference that can only ever answer
+        // unknown_preset; refuse it here instead.
+        if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+            fail("preset name", name, "letters, digits, `_`, `-` (the server's preset name charset)");
         }
         return `preset:${name}`;
     },

package/package.json

@@ -21,7 +21,7 @@
     "test": "node --test"
   },
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "devDependencies": {
     "@types/node": "^26.6.5",
     "typescript": "^5.9.3"