@crabcrop/url 0.6.0 → 0.8.0

package/README.md

@@ -5,7 +5,7 @@ Build and sign [crabcrop](https://github.com/dayvson/crabcrop) URLs from TypeScr
 ## Usage
 
 ```ts
-import { buildURL, buildSrcSet, purgeGroupSignature, purgeSignature, sign, uploadSignature, verifyUrlSignature } from "@crabcrop/url";
+import { buildSealedURL, buildURL, buildSrcSet, purgeGroupSignature, purgeSignature, seal, sign, unseal, uploadSignature, verifyUrlSignature } from "@crabcrop/url";
 
 // A signed URL. The operation string is passed verbatim and may
 // contain several segments and preset: references.
@@ -52,6 +52,19 @@ const group = purgeGroupSignature("your-secret", "thumb");
 // 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);
+
+// Sealed URLs (issue #255): the whole remainder encrypted into an
+// opaque token in the signature slot, for public links whose recipe
+// should stay unreadable. The server serves the sealed and plain
+// forms of one render from the same cache entry.
+const sealedUrl = buildSealedURL(
+  "https://images.example.com",
+  "your-secret",
+  "300x200",
+  "https://example.com/photo.jpg",
+  { name: "photo.jpg" },
+);
+const remainder = unseal("your-secret", seal("your-secret", "300x200/https://example.com/photo.jpg"));
 ```
 
 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/explain.js

@@ -22,6 +22,7 @@ export const FILTER_DESCRIPTIONS = {
     pixelatefaces: "pixelate detected faces (needs a face model on the server)",
     blurclass: "blur every detected object of the named class (needs a detection model on the server)",
     pixelateclass: "pixelate every detected object of the named class (needs a detection model on the server)",
+    recolorclass: "recolor every detected object of the named class to the given color (needs a detection model on the server)",
     removebg: "remove the background (needs an AI model on the server)",
     keep_profile: "keep the source color profile instead of converting to sRGB",
     upscale: "AI upscale by the given factor (needs an AI model on the server)",
@@ -48,6 +49,7 @@ export const FILTER_DESCRIPTIONS = {
     blur_region: "gaussian-blur the rectangle (x,y,w,h) in pixels at this point in the chain (redaction)",
     overlay: "composite another image over the result: (url,x,y,alpha,blend[,width %]) with blend normal, multiply, screen, or overlay",
     pixelate_region: "pixelate the rectangle (x,y,w,h) in pixels at this point in the chain (redaction)",
+    remove_region: "erase the rectangle (x,y,w,h) in pixels at this point in the chain and inpaint it from the surrounding pixels (AI region removal)",
 };
 const MAX_DIMENSION = 16383;
 function parseDimension(part) {
@@ -313,8 +315,27 @@ function validateFilter(name, args) {
                 ? null
                 : bad;
         }
+        case "recolorclass": {
+            if (args === null)
+                return bad;
+            const cut = args.lastIndexOf(",");
+            if (cut < 0)
+                return bad;
+            if (!/^[0-9a-fA-F]{6}$/.test(args.slice(cut + 1)))
+                return bad;
+            const decoded = percentDecodable(args.slice(0, cut));
+            if (decoded === null)
+                return bad;
+            const name = decoded.trim();
+            return name.length >= 1 &&
+                new TextEncoder().encode(name).length <= 64 &&
+                /^[\p{L}\p{N} _.\-/]+$/u.test(name)
+                ? null
+                : bad;
+        }
         case "blur_region":
-        case "pixelate_region": {
+        case "pixelate_region":
+        case "remove_region": {
             if (args === null)
                 return bad;
             const parts = args.split(",");

package/dist/index.d.ts

@@ -63,6 +63,71 @@ export declare function isValidKeyId(id: string): boolean;
  * followed by the hex tag `sign` computes.
  */
 export declare function signWithKeyId(secret: string, keyId: string, remainder: string): string;
+/**
+ * The largest remainder {@link seal} will encrypt, in bytes
+ * (issue #255). A recipe longer than this belongs in a
+ * preset; the cap also bounds the token a server must
+ * decode.
+ */
+export declare const MAX_SEALED_REMAINDER = 2048;
+/**
+ * Seal a remainder into a token segment with a
+ * caller-supplied nonce: `s1.<base64url(nonce ||
+ * ciphertext || tag)>`, AES-256-GCM under the derived seal
+ * subkey with the fixed associated data `crabcrop/sealed/1`.
+ *
+ * DANGER: a nonce must never repeat under one secret.
+ * Reusing a nonce with AES-GCM destroys the construction's
+ * confidentiality and integrity guarantees. This function
+ * is the deterministic seam the spec's test vectors use;
+ * production minting calls {@link seal}, which draws a
+ * fresh random nonce every time.
+ */
+export declare function sealWithNonce(secret: string, remainder: string, nonce: Uint8Array, keyId?: string): string;
+/**
+ * Seal a remainder into a token segment (issue #255), with
+ * a fresh random 96-bit nonce. The token is the whole
+ * signature segment; pass `keyId` to stamp `<key-id>:`
+ * in front of it, so servers in a rotation window open it
+ * against the named key only.
+ */
+export declare function seal(secret: string, remainder: string, keyId?: string): string;
+/**
+ * Open a token segment, with or without a `<key-id>:`
+ * prefix, under one secret, returning the remainder it
+ * seals. The key ID is routing metadata and is not
+ * consulted: the question is whether this secret opens the
+ * token. Every failure (malformed body, wrong secret,
+ * tampered bytes, unknown version) throws the one error,
+ * `the token did not open under this secret`: openers must
+ * never learn which stage failed.
+ */
+export declare function unseal(secret: string, segment: string): string;
+/** Options for {@link buildSealedURL}. */
+export interface SealOptions {
+    /** Unix-seconds expiry, sealed inside the token as a leading `exp:` segment. */
+    expires?: number;
+    /** Key ID to stamp on the token segment (`<key-id>:s1.…`), for rotation. */
+    keyId?: string;
+    /**
+     * The cosmetic friendly name after the token. The server
+     * never parses, validates, or authenticates it; one
+     * filename-like segment is the dependable shape. Omit it
+     * and the URL ends at the token.
+     */
+    name?: string;
+}
+/**
+ * Assemble a sealed crabcrop URL:
+ * `{base}/[<key-id>:]s1.<token>/{friendly-name}` (issue
+ * #255). The remainder is assembled exactly as
+ * {@link buildURL} assembles it (expiry segment,
+ * operations, source) and then sealed whole, pre-expansion,
+ * so the sealed and plain forms of one render are one cache
+ * entry and one purge target on the server. A secret is
+ * required: there is no `unsafe` spelling of a token.
+ */
+export declare function buildSealedURL(base: string, secret: string, operations: string, source: string, options?: SealOptions): string;
 /**
  * Assemble a signed (or `unsafe`) crabcrop URL. `operations`
  * is the operation string verbatim (several `/`-separated

package/dist/index.js

@@ -2,7 +2,7 @@
  * Build and sign crabcrop URLs, per `spec/url-signing.md` in
  * the crabcrop repository. Standard library only.
  */
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 /**
  * Compute the signature segment for a remainder: the lowercase
  * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
@@ -76,6 +76,151 @@ export function signWithKeyId(secret, keyId, remainder) {
     }
     return `${keyId}:${sign(secret, remainder)}`;
 }
+/**
+ * The largest remainder {@link seal} will encrypt, in bytes
+ * (issue #255). A recipe longer than this belongs in a
+ * preset; the cap also bounds the token a server must
+ * decode.
+ */
+export const MAX_SEALED_REMAINDER = 2048;
+/** The AAD every sealed token is bound to. */
+const SEAL_AAD = Buffer.from("crabcrop/sealed/1", "utf8");
+/**
+ * The seal subkey: the raw bytes of the HMAC-SHA256 of the
+ * label `crabcrop/seal-key` under the secret, its own domain
+ * beside purge, purge-group, and upload, so there is no
+ * second secret to configure or rotate: each keyring entry
+ * yields its own seal subkey, and the rotation window for
+ * signatures is the rotation window for tokens.
+ */
+function sealKey(secret) {
+    return Buffer.from(sign(secret, "crabcrop/seal-key"), "hex");
+}
+/**
+ * Seal a remainder into a token segment with a
+ * caller-supplied nonce: `s1.<base64url(nonce ||
+ * ciphertext || tag)>`, AES-256-GCM under the derived seal
+ * subkey with the fixed associated data `crabcrop/sealed/1`.
+ *
+ * DANGER: a nonce must never repeat under one secret.
+ * Reusing a nonce with AES-GCM destroys the construction's
+ * confidentiality and integrity guarantees. This function
+ * is the deterministic seam the spec's test vectors use;
+ * production minting calls {@link seal}, which draws a
+ * fresh random nonce every time.
+ */
+export function sealWithNonce(secret, remainder, nonce, keyId) {
+    if (nonce.length !== 12) {
+        throw new Error(`sealed token nonce must be 12 bytes, got ${nonce.length}`);
+    }
+    if (Buffer.byteLength(remainder, "utf8") > MAX_SEALED_REMAINDER) {
+        throw new Error(`remainder is over the ${MAX_SEALED_REMAINDER}-byte sealing cap: a recipe that long belongs in a preset`);
+    }
+    const cipher = createCipheriv("aes-256-gcm", sealKey(secret), Buffer.from(nonce));
+    cipher.setAAD(SEAL_AAD);
+    const ciphertext = Buffer.concat([cipher.update(remainder, "utf8"), cipher.final()]);
+    const body = Buffer.concat([Buffer.from(nonce), ciphertext, cipher.getAuthTag()]);
+    const token = `s1.${body.toString("base64url")}`;
+    if (keyId === undefined) {
+        return token;
+    }
+    if (!isValidKeyId(keyId)) {
+        throw new Error(`invalid key ID ${JSON.stringify(keyId)}: 1 to 32 characters of [A-Za-z0-9_-]`);
+    }
+    return `${keyId}:${token}`;
+}
+/**
+ * Seal a remainder into a token segment (issue #255), with
+ * a fresh random 96-bit nonce. The token is the whole
+ * signature segment; pass `keyId` to stamp `<key-id>:`
+ * in front of it, so servers in a rotation window open it
+ * against the named key only.
+ */
+export function seal(secret, remainder, keyId) {
+    return sealWithNonce(secret, remainder, randomBytes(12), keyId);
+}
+/**
+ * Open a token segment, with or without a `<key-id>:`
+ * prefix, under one secret, returning the remainder it
+ * seals. The key ID is routing metadata and is not
+ * consulted: the question is whether this secret opens the
+ * token. Every failure (malformed body, wrong secret,
+ * tampered bytes, unknown version) throws the one error,
+ * `the token did not open under this secret`: openers must
+ * never learn which stage failed.
+ */
+export function unseal(secret, segment) {
+    const openFailed = () => new Error("the token did not open under this secret");
+    let token = segment;
+    const colon = segment.indexOf(":");
+    if (colon >= 0) {
+        if (!isValidKeyId(segment.slice(0, colon))) {
+            throw openFailed();
+        }
+        token = segment.slice(colon + 1);
+    }
+    if (!token.startsWith("s1.")) {
+        throw openFailed();
+    }
+    const body = token.slice(3);
+    // Node's base64 decoder is lenient (it skips characters
+    // outside the alphabet), so canonicity is checked by
+    // re-encoding: anything but the exact minted spelling
+    // fails here.
+    const raw = Buffer.from(body, "base64url");
+    if (raw.length < 12 + 16 || raw.toString("base64url") !== body) {
+        throw openFailed();
+    }
+    const decipher = createDecipheriv("aes-256-gcm", sealKey(secret), raw.subarray(0, 12));
+    decipher.setAAD(SEAL_AAD);
+    decipher.setAuthTag(raw.subarray(raw.length - 16));
+    let plain;
+    try {
+        plain = Buffer.concat([
+            decipher.update(raw.subarray(12, raw.length - 16)),
+            decipher.final(),
+        ]);
+    }
+    catch {
+        throw openFailed();
+    }
+    const text = plain.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(plain)) {
+        throw openFailed();
+    }
+    return text;
+}
+/**
+ * Assemble a sealed crabcrop URL:
+ * `{base}/[<key-id>:]s1.<token>/{friendly-name}` (issue
+ * #255). The remainder is assembled exactly as
+ * {@link buildURL} assembles it (expiry segment,
+ * operations, source) and then sealed whole, pre-expansion,
+ * so the sealed and plain forms of one render are one cache
+ * entry and one purge target on the server. A secret is
+ * required: there is no `unsafe` spelling of a token.
+ */
+export function buildSealedURL(base, secret, operations, source, options = {}) {
+    if (secret === null || secret === undefined) {
+        throw new Error("sealing requires a secret: there is no unsafe token");
+    }
+    if (options.expires !== undefined) {
+        assertExpires(options.expires);
+    }
+    assertUrlText(operations, "operations");
+    assertUrlText(source, "source");
+    const trimmedBase = base.replace(/\/+$/, "");
+    let remainder = "";
+    if (options.expires !== undefined) {
+        remainder += `exp:${options.expires}/`;
+    }
+    if (operations) {
+        remainder += `${operations}/`;
+    }
+    remainder += source;
+    const segment = seal(secret, remainder, options.keyId);
+    return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
+}
 /**
  * Fail loudly on inputs that can never produce a verifiable URL
  * (audit P-4, P-5): the remainder travels as a raw URL path, so

package/dist/operations.d.ts

@@ -171,8 +171,12 @@ export declare const filter: {
     blurClass(name: string): string;
     /** Pixelate every detected object of the named class. */
     pixelateClass(name: string): string;
+    /** Recolor every detected object of the named class to the given RRGGBB color. */
+    recolorClass(name: string, color: string): string;
     /** Blur the rectangle (x, y, w, h) in pixels. */
     blurRegion(x: number, y: number, w: number, h: number): string;
     /** Pixelate the rectangle (x, y, w, h) in pixels. */
     pixelateRegion(x: number, y: number, w: number, h: number): string;
+    /** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
+    removeRegion(x: number, y: number, w: number, h: number): string;
 };

package/dist/operations.js

@@ -480,6 +480,10 @@ export const filter = {
     pixelateClass(name) {
         return `pixelateclass(${className("pixelateclass name", name)})`;
     },
+    /** Recolor every detected object of the named class to the given RRGGBB color. */
+    recolorClass(name, color) {
+        return `recolorclass(${className("recolorclass name", name)},${hex6("recolorclass color", color)})`;
+    },
     /** Blur the rectangle (x, y, w, h) in pixels. */
     blurRegion(x, y, w, h) {
         return `blur_region(${region(x, y, w, h)})`;
@@ -488,6 +492,10 @@ export const filter = {
     pixelateRegion(x, y, w, h) {
         return `pixelate_region(${region(x, y, w, h)})`;
     },
+    /** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
+    removeRegion(x, y, w, h) {
+        return `remove_region(${region(x, y, w, h)})`;
+    },
 };
 function region(x, y, w, h) {
     intIn("region x", x, 0, MAX_DIMENSION);

package/package.json

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