@crabcrop/mcp 0.9.11 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,15 @@
1
1
  /**
2
2
  * Parse a crabcrop URL (or bare path) back into its pieces and
3
3
  * explain each segment, mirroring the server's grammar. This is
4
- * the canonical implementation: the playground keeps a plain-JS
5
- * copy for its no-build static page, and both are pinned to the
6
- * same verdict corpus (audit PL-10, P-3).
4
+ * the one JavaScript implementation of the grammar (issue #482):
5
+ * the typed builders in operations.ts validate with the checks
6
+ * exported here, and the playground serves this module's build
7
+ * (playground/sdk/, refreshed by scripts/sync_playground_sdk.py,
8
+ * whose --check fails on drift or on a second copy). Every
9
+ * surface is pinned to the same verdict corpora (audit PL-10,
10
+ * P-3).
7
11
  */
12
+ import { MAX_DIMENSION } from "./limits.js";
8
13
  export const FILTER_DESCRIPTIONS = {
9
14
  grayscale: "convert to grayscale",
10
15
  invert: "invert the colors",
@@ -58,7 +63,6 @@ export const FILTER_DESCRIPTIONS = {
58
63
  pixelate_region: "pixelate the rectangle (x,y,w,h) in pixels at this point in the chain (redaction)",
59
64
  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)",
60
65
  };
61
- const MAX_DIMENSION = 16383;
62
66
  function parseDimension(part) {
63
67
  let flip = false;
64
68
  let digits = part;
@@ -105,6 +109,84 @@ function sizeBlurb(seg) {
105
109
  ].filter(Boolean);
106
110
  return `resize to ${describe(size.w, "width")} by ${describe(size.h, "height")}${flips.length ? ` (${flips.join(", ")})` : ""}`;
107
111
  }
112
+ // The grammar's closed sets, declared once for the explainer
113
+ // and the typed builders (issue #482). Each is `as const` so
114
+ // test/grammar-sets.test.ts can check it against the union
115
+ // type operations.ts gives callers: a value added to one side
116
+ // only fails the type check.
117
+ /** Crop alignments (url.rs parse_align); `center` is the bare `crop:WxH`. */
118
+ export const CROP_ALIGNS = ["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"];
119
+ /** Text overlay anchors (url.rs Anchor::parse). */
120
+ export const TEXT_ANCHORS = [
121
+ "top-left",
122
+ "top-center",
123
+ "top-right",
124
+ "center-left",
125
+ "center",
126
+ "center-right",
127
+ "bottom-left",
128
+ "bottom-center",
129
+ "bottom-right",
130
+ ];
131
+ /** Output formats `format(...)` names; `jpg` is an input alias of `jpeg`. */
132
+ export const IMAGE_FORMATS = ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
133
+ /**
134
+ * Formats a per-format `quality(...)` entry names, in
135
+ * canonical (name) order: the still formats, since a video
136
+ * format's quality is not the server's to set. `jpg` is
137
+ * accepted as the input alias of `jpeg`.
138
+ */
139
+ export const QUALITY_FORMATS = ["avif", "gif", "jpeg", "jxl", "png", "webp"];
140
+ /** JPEG chroma subsamplings `format(jpeg,subsampling:...)` takes. */
141
+ export const JPEG_SUBSAMPLINGS = [444, 422, 420];
142
+ /** Overlay blend modes. */
143
+ export const BLEND_MODES = ["normal", "multiply", "screen", "overlay"];
144
+ /** Channels `curve(...)` remaps. */
145
+ export const CURVE_CHANNELS = ["rgb", "r", "g", "b"];
146
+ /** Modes `studio(...)` runs. */
147
+ export const STUDIO_MODES = ["product", "scene"];
148
+ /** Named backdrops for `studio(product,bg:...)`; any RRGGBB color also works. */
149
+ export const STUDIO_BACKDROPS = ["white", "brand", "none"];
150
+ /** Contact shadow strengths for `studio(product, ...)`. */
151
+ export const STUDIO_SHADOWS = ["soft", "strong", "none"];
152
+ /** Factors `upscale(...)` takes. */
153
+ export const UPSCALE_FACTORS = [2, 4];
154
+ /** Device pixel ratios `dpr(...)` takes. */
155
+ export const DPR_FACTORS = [1, 1.5, 2, 3];
156
+ /** Shapes `mask(...)` cuts. */
157
+ export const MASK_SHAPES = ["circle", "ellipse"];
158
+ /** Axes `flip(...)` mirrors across. */
159
+ export const FLIP_AXES = ["h", "v"];
160
+ /** Whether `value` is a member of the closed set `list`. */
161
+ export function isOneOf(list, value) {
162
+ return list.includes(value);
163
+ }
164
+ /**
165
+ * The objects crop's cap on distinct class names (url.rs
166
+ * MAX_OBJECTS_CLASSES).
167
+ */
168
+ export const MAX_OBJECTS_CLASSES = 32;
169
+ /**
170
+ * A detection class name as the server's parse_class_name
171
+ * takes it, already trimmed: 1 to 64 UTF-8 bytes (bytes, not
172
+ * UTF-16 code units, as on the server) of letters, digits,
173
+ * space, `_`, `.`, `-`, `/`.
174
+ */
175
+ export function isClassName(name) {
176
+ return (name.length >= 1 &&
177
+ new TextEncoder().encode(name).length <= 64 &&
178
+ /^[\p{L}\p{N} _.\-/]+$/u.test(name));
179
+ }
180
+ /**
181
+ * The key a class name folds to when the objects crop drops
182
+ * repeats. The server compares names with
183
+ * `eq_ignore_ascii_case` (url.rs parse_crop_align), so only
184
+ * A to Z fold: `E` and `e` are one class, `É` and `é` are two
185
+ * (issue #482).
186
+ */
187
+ export function classFoldKey(name) {
188
+ return name.replace(/[A-Z]/g, (c) => c.toLowerCase());
189
+ }
108
190
  const NO_ARG_FILTERS = new Set([
109
191
  "grayscale",
110
192
  "invert",
@@ -117,18 +199,8 @@ const NO_ARG_FILTERS = new Set([
117
199
  "blurfaces",
118
200
  "pixelatefaces",
119
201
  ]);
120
- const FORMAT_NAMES = new Set(["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"]);
121
- const ANCHOR_NAMES = new Set([
122
- "top-left",
123
- "top-center",
124
- "top-right",
125
- "center-left",
126
- "center",
127
- "center-right",
128
- "bottom-left",
129
- "bottom-center",
130
- "bottom-right",
131
- ]);
202
+ const FORMAT_NAMES = new Set(IMAGE_FORMATS);
203
+ const ANCHOR_NAMES = new Set(TEXT_ANCHORS);
132
204
  function isIntIn(s, min, max) {
133
205
  // Rust's integer from_str syntax: an optional sign (the
134
206
  // unsigned parsers accept '+' too), then digits.
@@ -246,9 +318,9 @@ function validateFilter(name, args) {
246
318
  else {
247
319
  const name = part.slice(0, colon);
248
320
  const value = part.slice(colon + 1);
249
- if (!FORMAT_NAMES.has(name) || name === "mp4" || name === "webm")
250
- return bad;
251
321
  const canonical = name === "jpg" ? "jpeg" : name;
322
+ if (!isOneOf(QUALITY_FORMATS, canonical))
323
+ return bad;
252
324
  if (seen.has(canonical))
253
325
  return bad;
254
326
  seen.add(canonical);
@@ -278,7 +350,7 @@ function validateFilter(name, args) {
278
350
  if (name === "jpeg" || name === "jpg") {
279
351
  if (option === "progressive")
280
352
  continue;
281
- if (/^subsampling:(444|422|420)$/.test(option))
353
+ if (JPEG_SUBSAMPLINGS.some((s) => option === `subsampling:${s}`))
282
354
  continue;
283
355
  return bad;
284
356
  }
@@ -308,7 +380,7 @@ function validateFilter(name, args) {
308
380
  if (args === null)
309
381
  return bad;
310
382
  const parts = args.split(",");
311
- if (!["rgb", "r", "g", "b"].includes(parts[0]))
383
+ if (!isOneOf(CURVE_CHANNELS, parts[0]))
312
384
  return bad;
313
385
  const coords = parts.slice(1);
314
386
  if (coords.length < 4 || coords.length > 32 || coords.length % 2 !== 0)
@@ -339,7 +411,7 @@ function validateFilter(name, args) {
339
411
  ? null
340
412
  : bad;
341
413
  case "upscale":
342
- return args !== null && /^[+-]?\d+$/.test(args) && (Number(args) === 2 || Number(args) === 4)
414
+ return args !== null && /^[+-]?\d+$/.test(args) && isOneOf(UPSCALE_FACTORS, Number(args))
343
415
  ? null
344
416
  : bad;
345
417
  case "studio": {
@@ -354,7 +426,7 @@ function validateFilter(name, args) {
354
426
  return bad;
355
427
  const parts = args.split(",");
356
428
  const mode = parts[0];
357
- if (mode !== "product" && mode !== "scene")
429
+ if (!isOneOf(STUDIO_MODES, mode))
358
430
  return bad;
359
431
  const seen = new Set();
360
432
  for (const part of parts.slice(1)) {
@@ -374,15 +446,11 @@ function validateFilter(name, args) {
374
446
  return bad;
375
447
  }
376
448
  else if (mode === "product" && key === "bg") {
377
- if (value !== "white" &&
378
- value !== "brand" &&
379
- value !== "none" &&
380
- !/^[0-9a-fA-F]{6}$/.test(value)) {
449
+ if (!isOneOf(STUDIO_BACKDROPS, value) && !/^[0-9a-fA-F]{6}$/.test(value))
381
450
  return bad;
382
- }
383
451
  }
384
452
  else if (mode === "product" && key === "shadow") {
385
- if (value !== "none" && value !== "soft" && value !== "strong")
453
+ if (!isOneOf(STUDIO_SHADOWS, value))
386
454
  return bad;
387
455
  }
388
456
  else {
@@ -392,7 +460,7 @@ function validateFilter(name, args) {
392
460
  return null;
393
461
  }
394
462
  case "dpr":
395
- return args !== null && isFloat(args) && [1, 1.5, 2, 3].includes(Number(args))
463
+ return args !== null && isFloat(args) && isOneOf(DPR_FACTORS, Number(args))
396
464
  ? null
397
465
  : bad;
398
466
  case "rotate":
@@ -406,7 +474,7 @@ function validateFilter(name, args) {
406
474
  return bad;
407
475
  const parts = args.split(",");
408
476
  return (parts.length === 1 || parts.length === 4) &&
409
- parts.every((p) => isIntIn(p, 0, 16383))
477
+ parts.every((p) => isIntIn(p, 0, MAX_DIMENSION))
410
478
  ? null
411
479
  : bad;
412
480
  }
@@ -415,13 +483,13 @@ function validateFilter(name, args) {
415
483
  return bad;
416
484
  const parts = args.split(",");
417
485
  return parts.length === 2 &&
418
- isIntIn(parts[0], 0, 16383) &&
486
+ isIntIn(parts[0], 0, MAX_DIMENSION) &&
419
487
  /^[0-9a-fA-F]{6}$/.test(parts[1])
420
488
  ? null
421
489
  : bad;
422
490
  }
423
491
  case "mask":
424
- return args === "circle" || args === "ellipse" ? null : bad;
492
+ return isOneOf(MASK_SHAPES, args) ? null : bad;
425
493
  case "duotone": {
426
494
  if (args === null)
427
495
  return bad;
@@ -431,9 +499,9 @@ function validateFilter(name, args) {
431
499
  case "monochrome":
432
500
  return args !== null && /^[0-9a-fA-F]{6}$/.test(args) ? null : bad;
433
501
  case "pixelate":
434
- return args !== null && isIntIn(args, 1, 16383) ? null : bad;
502
+ return args !== null && isIntIn(args, 1, MAX_DIMENSION) ? null : bad;
435
503
  case "flip":
436
- return args === "h" || args === "v" ? null : bad;
504
+ return isOneOf(FLIP_AXES, args) ? null : bad;
437
505
  case "overlay": {
438
506
  if (args === null)
439
507
  return bad;
@@ -451,7 +519,7 @@ function validateFilter(name, args) {
451
519
  rest = fields.slice(0, -1);
452
520
  }
453
521
  const blend = rest[rest.length - 1];
454
- if (!["normal", "multiply", "screen", "overlay"].includes(blend))
522
+ if (!isOneOf(BLEND_MODES, blend))
455
523
  return bad;
456
524
  if (!isIntIn(rest[rest.length - 2], 0, 100))
457
525
  return bad;
@@ -467,14 +535,7 @@ function validateFilter(name, args) {
467
535
  if (args === null)
468
536
  return bad;
469
537
  const decoded = percentDecodable(args);
470
- if (decoded === null)
471
- return bad;
472
- const name = decoded.trim();
473
- return name.length >= 1 &&
474
- new TextEncoder().encode(name).length <= 64 &&
475
- /^[\p{L}\p{N} _.\-/]+$/u.test(name)
476
- ? null
477
- : bad;
538
+ return decoded !== null && isClassName(decoded.trim()) ? null : bad;
478
539
  }
479
540
  case "recolorclass": {
480
541
  if (args === null)
@@ -485,14 +546,7 @@ function validateFilter(name, args) {
485
546
  if (!/^[0-9a-fA-F]{6}$/.test(args.slice(cut + 1)))
486
547
  return bad;
487
548
  const decoded = percentDecodable(args.slice(0, cut));
488
- if (decoded === null)
489
- return bad;
490
- const name = decoded.trim();
491
- return name.length >= 1 &&
492
- new TextEncoder().encode(name).length <= 64 &&
493
- /^[\p{L}\p{N} _.\-/]+$/u.test(name)
494
- ? null
495
- : bad;
549
+ return decoded !== null && isClassName(decoded.trim()) ? null : bad;
496
550
  }
497
551
  case "blur_region":
498
552
  case "pixelate_region":
@@ -501,7 +555,7 @@ function validateFilter(name, args) {
501
555
  return bad;
502
556
  const parts = args.split(",");
503
557
  return parts.length === 4 &&
504
- parts.every((p) => isIntIn(p, 0, 16383)) &&
558
+ parts.every((p) => isIntIn(p, 0, MAX_DIMENSION)) &&
505
559
  Number(parts[2]) >= 1 &&
506
560
  Number(parts[3]) >= 1
507
561
  ? null
@@ -599,17 +653,17 @@ function explainFilters(rest) {
599
653
  }
600
654
  return { detail: blurbs.join("; ") };
601
655
  }
602
- const ALIGN_NAMES = new Set(["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"]);
656
+ const ALIGN_NAMES = new Set(CROP_ALIGNS);
603
657
  const U64_MAX = 18446744073709551615n;
604
658
  /**
605
659
  * The objects crop alignment (url.rs parse_objects, ported):
606
660
  * `objects(<class>[,<class>...])[:<scale>]`. Returns the
607
- * decoded class names (duplicates folded, first spelling
608
- * kept, as the server's canonical form folds them) and the
609
- * scale, or null when the server would reject the form.
610
- * The 32-class cap counts distinct names, as the server's
611
- * does: repeats are free, and a 33rd distinct name rejects
612
- * the form (issue #408).
661
+ * decoded class names (duplicates folded ASCII-only, first
662
+ * spelling kept, as the server's canonical form folds them)
663
+ * and the scale, or null when the server would reject the
664
+ * form. The 32-class cap counts distinct names, as the
665
+ * server's does: repeats are free, and a 33rd distinct name
666
+ * rejects the form (issue #408).
613
667
  */
614
668
  function parseObjectsAlign(align) {
615
669
  if (!align.startsWith("objects("))
@@ -639,14 +693,11 @@ function parseObjectsAlign(align) {
639
693
  if (decoded === null)
640
694
  return null;
641
695
  const name = decoded.trim();
642
- if (name.length < 1 ||
643
- new TextEncoder().encode(name).length > 64 ||
644
- !/^[\p{L}\p{N} _.\-/]+$/u.test(name)) {
696
+ if (!isClassName(name))
645
697
  return null;
646
- }
647
- const key = name.toLowerCase();
698
+ const key = classFoldKey(name);
648
699
  if (!seen.has(key)) {
649
- if (classes.length === 32)
700
+ if (classes.length === MAX_OBJECTS_CLASSES)
650
701
  return null;
651
702
  seen.add(key);
652
703
  classes.push(name);
@@ -145,8 +145,9 @@ export declare function buildSrcSet(base: string, secret: string | null, source:
145
145
  export { explainUrl } from "./explain.ts";
146
146
  export { FILTER_DESCRIPTIONS } from "./explain.ts";
147
147
  export type { ExplainedSegment, Explanation, SegmentKind, SignatureKind } from "./explain.ts";
148
+ export { MAX_DIMENSION } from "./limits.ts";
148
149
  export { filter, joinOps, ops } from "./operations.ts";
149
- export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, StudioMode, StudioOptions, StudioShadow, } from "./operations.ts";
150
+ export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, FormatOptions, ImageFormat, MaskShape, PerFormatQualityFormat, StudioMode, StudioOptions, StudioShadow, } from "./operations.ts";
150
151
  /**
151
152
  * Verify a URL's signature locally. Returns true or false, or
152
153
  * null when the URL is unsigned or malformed.
@@ -1,8 +1,13 @@
1
1
  /**
2
2
  * Build and sign crabcrop URLs, per `spec/url-signing.md` in
3
- * the crabcrop repository. Standard library only.
3
+ * the crabcrop repository. No dependencies: `#crypto` resolves
4
+ * to `node:crypto` on Node and to a plain TypeScript backend
5
+ * in browser bundles (see package.json `imports`), and this
6
+ * module uses no Node globals, so it bundles for either.
4
7
  */
5
- import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
8
+ import { aes256GcmOpen, aes256GcmSeal, hmacSha256, randomBytes, timingSafeEqual, } from "#crypto";
9
+ import { fromBase64Url, toBase64Url, toHex, utf8, utf8Strict } from "./bytes.js";
10
+ import { MAX_DIMENSION } from "./limits.js";
6
11
  /**
7
12
  * Compute the signature segment for a remainder: the lowercase
8
13
  * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
@@ -10,7 +15,15 @@ import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEq
10
15
  * exactly as it will appear.
11
16
  */
12
17
  export function sign(secret, remainder) {
13
- return createHmac("sha256", secret).update(remainder, "utf8").digest("hex");
18
+ return toHex(hmacSha256(secret, remainder));
19
+ }
20
+ /**
21
+ * A subkey derived from the secret: the raw HMAC-SHA256 of
22
+ * `label` under it (the bytes whose hex is `sign(secret,
23
+ * label)`), one per signing domain.
24
+ */
25
+ function subkey(secret, label) {
26
+ return hmacSha256(secret, label);
14
27
  }
15
28
  /**
16
29
  * The purge signature for a target path (the request
@@ -22,8 +35,7 @@ export function sign(secret, remainder) {
22
35
  * `POST /purge/<signature>/<path>`.
23
36
  */
24
37
  export function purgeSignature(secret, target) {
25
- const subkey = Buffer.from(sign(secret, "crabcrop/purge-key"), "hex");
26
- return createHmac("sha256", subkey).update(target, "utf8").digest("hex");
38
+ return toHex(hmacSha256(subkey(secret, "crabcrop/purge-key"), target));
27
39
  }
28
40
  /**
29
41
  * The purge-group signature for a cache group: HMAC-SHA256
@@ -37,8 +49,7 @@ export function purgeSignature(secret, target) {
37
49
  * `POST /purge-group/<signature>/<group>`.
38
50
  */
39
51
  export function purgeGroupSignature(secret, group) {
40
- const subkey = Buffer.from(sign(secret, "crabcrop/purge-group-key"), "hex");
41
- return createHmac("sha256", subkey).update(group, "utf8").digest("hex");
52
+ return toHex(hmacSha256(subkey(secret, "crabcrop/purge-group-key"), group));
42
53
  }
43
54
  /**
44
55
  * The upload signature for an object name: HMAC-SHA256 of
@@ -58,9 +69,8 @@ export function purgeGroupSignature(secret, group) {
58
69
  * a token replays until the secret rotates.
59
70
  */
60
71
  export function uploadSignature(secret, name, expires) {
61
- const subkey = Buffer.from(sign(secret, "crabcrop/upload-key"), "hex");
62
72
  const signed = expires === undefined ? name : `exp:${expires}/${name}`;
63
- return createHmac("sha256", subkey).update(signed, "utf8").digest("hex");
73
+ return toHex(hmacSha256(subkey(secret, "crabcrop/upload-key"), signed));
64
74
  }
65
75
  /** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
66
76
  export function isValidKeyId(id) {
@@ -84,7 +94,7 @@ export function signWithKeyId(secret, keyId, remainder) {
84
94
  */
85
95
  export const MAX_SEALED_REMAINDER = 2048;
86
96
  /** The AAD every sealed token is bound to. */
87
- const SEAL_AAD = Buffer.from("crabcrop/sealed/1", "utf8");
97
+ const SEAL_AAD = utf8("crabcrop/sealed/1");
88
98
  /**
89
99
  * The seal subkey: the raw bytes of the HMAC-SHA256 of the
90
100
  * label `crabcrop/seal-key` under the secret, its own domain
@@ -94,7 +104,7 @@ const SEAL_AAD = Buffer.from("crabcrop/sealed/1", "utf8");
94
104
  * signatures is the rotation window for tokens.
95
105
  */
96
106
  function sealKey(secret) {
97
- return Buffer.from(sign(secret, "crabcrop/seal-key"), "hex");
107
+ return subkey(secret, "crabcrop/seal-key");
98
108
  }
99
109
  /**
100
110
  * Seal a remainder into a token segment with a
@@ -113,14 +123,15 @@ export function sealWithNonce(secret, remainder, nonce, keyId) {
113
123
  if (nonce.length !== 12) {
114
124
  throw new Error(`sealed token nonce must be 12 bytes, got ${nonce.length}`);
115
125
  }
116
- if (Buffer.byteLength(remainder, "utf8") > MAX_SEALED_REMAINDER) {
126
+ const plaintext = utf8(remainder);
127
+ if (plaintext.length > MAX_SEALED_REMAINDER) {
117
128
  throw new Error(`remainder is over the ${MAX_SEALED_REMAINDER}-byte sealing cap: a recipe that long belongs in a preset`);
118
129
  }
119
- const cipher = createCipheriv("aes-256-gcm", sealKey(secret), Buffer.from(nonce));
120
- cipher.setAAD(SEAL_AAD);
121
- const ciphertext = Buffer.concat([cipher.update(remainder, "utf8"), cipher.final()]);
122
- const body = Buffer.concat([Buffer.from(nonce), ciphertext, cipher.getAuthTag()]);
123
- const token = `s1.${body.toString("base64url")}`;
130
+ const sealed = aes256GcmSeal(sealKey(secret), nonce, SEAL_AAD, plaintext);
131
+ const body = new Uint8Array(nonce.length + sealed.length);
132
+ body.set(nonce);
133
+ body.set(sealed, nonce.length);
134
+ const token = `s1.${toBase64Url(body)}`;
124
135
  if (keyId === undefined) {
125
136
  return token;
126
137
  }
@@ -163,29 +174,17 @@ export function unseal(secret, segment) {
163
174
  throw openFailed();
164
175
  }
165
176
  const body = token.slice(3);
166
- // Node's base64 decoder is lenient (it skips characters
167
- // outside the alphabet), so canonicity is checked by
168
- // re-encoding: anything but the exact minted spelling
169
- // fails here.
170
- const raw = Buffer.from(body, "base64url");
171
- if (raw.length < 12 + 16 || raw.toString("base64url") !== body) {
172
- throw openFailed();
173
- }
174
- const decipher = createDecipheriv("aes-256-gcm", sealKey(secret), raw.subarray(0, 12));
175
- decipher.setAAD(SEAL_AAD);
176
- decipher.setAuthTag(raw.subarray(raw.length - 16));
177
- let plain;
178
- try {
179
- plain = Buffer.concat([
180
- decipher.update(raw.subarray(12, raw.length - 16)),
181
- decipher.final(),
182
- ]);
183
- }
184
- catch {
177
+ // Canonicity is checked by re-encoding: anything but the
178
+ // exact minted spelling (padding, stray characters, nonzero
179
+ // trailing bits) fails here.
180
+ const raw = fromBase64Url(body);
181
+ if (raw === null || raw.length < 12 + 16 || toBase64Url(raw) !== body) {
185
182
  throw openFailed();
186
183
  }
187
- const text = plain.toString("utf8");
188
- if (!Buffer.from(text, "utf8").equals(plain)) {
184
+ const plain = aes256GcmOpen(sealKey(secret), raw.subarray(0, 12), SEAL_AAD, raw.subarray(12));
185
+ // The plaintext must be valid UTF-8: a remainder is text.
186
+ const text = plain === null ? null : utf8Strict(plain);
187
+ if (text === null) {
189
188
  throw openFailed();
190
189
  }
191
190
  return text;
@@ -221,18 +220,31 @@ export function buildSealedURL(base, secret, operations, source, options = {}) {
221
220
  const segment = seal(secret, remainder, options.keyId);
222
221
  return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
223
222
  }
223
+ /**
224
+ * Characters a browser rewrites in a URL path (issue #472): an
225
+ * `<img src>` or `fetch()` URL is parsed by WHATWG rules, which
226
+ * turn `\` into `/` and percent-encode the rest (Chrome encodes
227
+ * `^` and `|` too). The server verifies the raw path, so a URL
228
+ * signed over one of them answers 403 from a page.
229
+ */
230
+ const BROWSER_REWRITTEN = "\"<>\\^`{|}";
224
231
  /**
225
232
  * Fail loudly on inputs that can never produce a verifiable URL
226
233
  * (audit P-4, P-5): the remainder travels as a raw URL path, so
227
- * `?`/`#` would truncate it and whitespace, control, and
228
- * non-ASCII characters cannot be sent as-is; an expiry must be
229
- * a non-negative integer the server's u64 parser accepts.
234
+ * `?`/`#` would truncate it, whitespace, control, and non-ASCII
235
+ * characters cannot be sent as-is, and a browser rewrites the
236
+ * {@link BROWSER_REWRITTEN} set; an expiry must be a
237
+ * non-negative integer the server's u64 parser accepts.
230
238
  */
231
239
  function assertUrlText(text, what) {
232
240
  for (const c of text) {
233
241
  const code = c.codePointAt(0);
234
- if (c === "?" || c === "#" || code <= 0x20 || code === 0x7f || code > 0x7e) {
235
- throw new Error(`${what} contains a character that cannot appear in a crabcrop URL: ${JSON.stringify(c)}`);
242
+ const rewritten = BROWSER_REWRITTEN.includes(c);
243
+ if (c === "?" || c === "#" || code <= 0x20 || code === 0x7f || code > 0x7e || rewritten) {
244
+ const hint = rewritten
245
+ ? ` (browsers rewrite it; percent-encode it as %${code.toString(16).toUpperCase()})`
246
+ : "";
247
+ throw new Error(`${what} contains a character that cannot appear in a crabcrop URL: ${JSON.stringify(c)}${hint}`);
236
248
  }
237
249
  }
238
250
  }
@@ -249,8 +261,8 @@ function assertExpires(expires) {
249
261
  * flip), so it throws here, at build time.
250
262
  */
251
263
  function assertWidth(width) {
252
- if (!Number.isSafeInteger(width) || width < 1 || width > 16383) {
253
- throw new Error(`srcset width must be a positive integer no larger than 16383, got ${width}`);
264
+ if (!Number.isSafeInteger(width) || width < 1 || width > MAX_DIMENSION) {
265
+ throw new Error(`srcset width must be a positive integer no larger than ${MAX_DIMENSION}, got ${width}`);
254
266
  }
255
267
  }
256
268
  /**
@@ -305,6 +317,7 @@ export function buildSrcSet(base, secret, source, widths, options = {}) {
305
317
  }
306
318
  export { explainUrl } from "./explain.js";
307
319
  export { FILTER_DESCRIPTIONS } from "./explain.js";
320
+ export { MAX_DIMENSION } from "./limits.js";
308
321
  export { filter, joinOps, ops } from "./operations.js";
309
322
  import { explainUrl } from "./explain.js";
310
323
  /**
@@ -325,11 +338,8 @@ export function verifyUrlSignature(secret, input) {
325
338
  }
326
339
  // Constant-time, like the Rust and Python verifiers: a
327
340
  // plain === leaks how much of the tag was right.
328
- const given = Buffer.from(signature.value, "utf8");
329
- const matches = (candidate) => {
330
- const expected = Buffer.from(sign(candidate, remainder), "utf8");
331
- return expected.length === given.length && timingSafeEqual(expected, given);
332
- };
341
+ const given = utf8(signature.value);
342
+ const matches = (candidate) => timingSafeEqual(utf8(sign(candidate, remainder)), given);
333
343
  if (typeof secret === "string") {
334
344
  return matches(secret);
335
345
  }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The server's per-axis pixel cap (`MAX_DIMENSION` in the
3
+ * server's `url.rs`): the largest value a size side, a crop
4
+ * or pad box, a region, a border, a radius, or a pixelate
5
+ * block can name. A larger value is a parse error on the
6
+ * server, so the builders, the explainer, and the framework
7
+ * integrations all check against this one constant.
8
+ */
9
+ export declare const MAX_DIMENSION = 16383;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The server's per-axis pixel cap (`MAX_DIMENSION` in the
3
+ * server's `url.rs`): the largest value a size side, a crop
4
+ * or pad box, a region, a border, a radius, or a pixelate
5
+ * block can name. A larger value is a parse error on the
6
+ * server, so the builders, the explainer, and the framework
7
+ * integrations all check against this one constant.
8
+ */
9
+ export const MAX_DIMENSION = 16383;
@@ -1,16 +1,3 @@
1
- /**
2
- * Typed builders for crabcrop operation strings (AP-24).
3
- *
4
- * `buildURL` takes operations verbatim, by design: the string
5
- * is the spec. This module is the optional typed surface over
6
- * it: each call validates its arguments against the server's
7
- * grammar (the same bounds the explainer enforces) and returns
8
- * the operation segment in its canonical spelling, so a typed
9
- * pipeline and the equivalent hand-written string produce
10
- * byte-identical URLs. Validation throws at build time, like
11
- * `buildSrcSet` does for widths: a value the server would 400
12
- * never gets signed.
13
- */
14
1
  /** Output formats the `format(...)` filter accepts. */
15
2
  export type ImageFormat = "jpeg" | "jpg" | "png" | "webp" | "jxl" | "avif" | "gif" | "mp4" | "webm";
16
3
  /** Formats a per-format quality entry can name (the video formats take no quality). */
@@ -69,8 +56,8 @@ export interface StudioOptions {
69
56
  pad?: number;
70
57
  }
71
58
  /**
72
- * One side of a size: a pixel count (1..16383), 0 for
73
- * proportional, a negative count to flip that axis, or
59
+ * One side of a size: a pixel count (1..{@link MAX_DIMENSION}),
60
+ * 0 for proportional, a negative count to flip that axis, or
74
61
  * `"orig"` for the source's own dimension.
75
62
  */
76
63
  export type Dimension = number | "orig";
@@ -94,10 +81,11 @@ export declare const ops: {
94
81
  * Needs a detection model configured on the server; when
95
82
  * none of the classes is detected the render falls back
96
83
  * to the plain center crop of the same size. Duplicate
97
- * classes (case-insensitive) are spelled once, as the
98
- * server's canonical form spells them; at most 32
99
- * distinct classes, and a 33rd throws, since the server
100
- * rejects it with `invalid_crop`.
84
+ * classes (ASCII case-insensitive, as the server compares
85
+ * them: `E` repeats `e`, `É` does not repeat `é`) are
86
+ * spelled once, as the server's canonical form spells
87
+ * them; at most 32 distinct classes, and a 33rd throws,
88
+ * since the server rejects it with `invalid_crop`.
101
89
  */
102
90
  cropObjects(width: number, height: number, classes: string[], scale?: number): string;
103
91
  /** `crop-rect:10x20:110x220` (left x top : right x bottom). */
@@ -254,7 +242,7 @@ export declare const filter: {
254
242
  mask(shape: MaskShape): string;
255
243
  duotone(shadow: string, highlight: string): string;
256
244
  monochrome(color: string): string;
257
- /** Mosaic block size in pixels: 1..16383. */
245
+ /** Mosaic block size in pixels: 1..{@link MAX_DIMENSION}. */
258
246
  pixelate(blockSize: number): string;
259
247
  flip(axis: "h" | "v"): string;
260
248
  /** Overlay a watermark image at (x, y), opacity 0..100. */