@crabcrop/mcp 0.10.0 → 0.11.0

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.
package/README.md CHANGED
@@ -6,7 +6,7 @@ A first-party MCP (Model Context Protocol) server for crabcrop, so coding agents
6
6
 
7
7
  | Tool | What it does |
8
8
  |---|---|
9
- | `sign_url` | Build and sign a URL from an operation string and a source (optional expiry). |
9
+ | `sign_url` | Build and sign a URL from an operation string and a source (optional expiry). Like every builder, it refuses a remainder that begins with the reserved segment `crabcrop`. |
10
10
  | `explain_url` | Parse a URL back into its signature kind, explained segments, and source; malformed segments are flagged. |
11
11
  | `fetch_meta` | Fetch the server's meta JSON for a URL (dimensions, format, bytes, quality, placeholders on request). The server needs meta mode on (`CRABCROP_META_MODE=1`); it is off by default, and the tool then reports the server's `403 meta_disabled`. Only fetches URLs on the configured `CRABCROP_BASE` origin, never follows redirects, and caps the response at 256 KiB. |
12
12
  | `purge_result` | Evict a cached result by its URL remainder; a preset URL works as-is (the server expands it before matching). Only POSTs to `/purge/` under the configured `CRABCROP_BASE` (a per-call `base` must equal it) and refuses paths with dot segments. |
package/dist/index.js CHANGED
@@ -19,7 +19,7 @@
19
19
  * Run: node src/index.ts (Node >= 22.18, for type stripping)
20
20
  */
21
21
  import { buildURL, explainUrl, purgeSignature } from "@crabcrop/url";
22
- const SERVER = { name: "crabcrop", version: "0.10.0" };
22
+ const SERVER = { name: "crabcrop", version: "0.11.0" };
23
23
  const PROTOCOL = "2024-11-05";
24
24
  const envBase = process.env.CRABCROP_BASE ?? "";
25
25
  const envSecret = process.env.CRABCROP_SECRET ?? null;
@@ -33,7 +33,10 @@ const srcset = buildSrcSet(
33
33
  [400, 800, 1200],
34
34
  );
35
35
 
36
- // The raw signature for a remainder, if you assemble URLs yourself.
36
+ // The signature for a remainder, if you assemble URLs yourself. It
37
+ // throws for a remainder that begins with the reserved segment
38
+ // "crabcrop" (isReservedRemainder), as every builder does: the derived
39
+ // subkeys are signatures of labels under that segment.
37
40
  const signature = sign("your-secret", "300x200/https://example.com/photo.jpg");
38
41
 
39
42
  // Verify a signed URL's signature locally, in constant time
@@ -1,8 +1,28 @@
1
+ /**
2
+ * The first remainder segment reserved for key derivation.
3
+ * Every derived subkey (purge, purge-group, upload, seal, and
4
+ * the server's cache entry key) is the HMAC of a label such as
5
+ * `crabcrop/purge-key` under the secret, which is the image
6
+ * signature of that label. No image URL may begin with this
7
+ * segment (the server refuses one with `400 reserved_segment`),
8
+ * and {@link sign} and every builder refuse a remainder that
9
+ * does, so no image signature is ever a subkey.
10
+ */
11
+ export declare const RESERVED_SEGMENT = "crabcrop";
12
+ /**
13
+ * Whether `remainder` begins with {@link RESERVED_SEGMENT}: it
14
+ * is that segment alone or starts with `crabcrop/`. The test is
15
+ * on the text as written, as the HMAC is: `exp:1/crabcrop/x`
16
+ * and `CRABCROP/x` are not reserved.
17
+ */
18
+ export declare function isReservedRemainder(remainder: string): boolean;
1
19
  /**
2
20
  * Compute the signature segment for a remainder: the lowercase
3
21
  * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
4
22
  * is everything after the signature segment in the URL,
5
- * exactly as it will appear.
23
+ * exactly as it will appear. A remainder that begins with
24
+ * {@link RESERVED_SEGMENT} throws: its signature could be a
25
+ * derived subkey.
6
26
  */
7
27
  export declare function sign(secret: string, remainder: string): string;
8
28
  /**
@@ -10,9 +30,10 @@ export declare function sign(secret: string, remainder: string): string;
10
30
  * remainder without its signature): HMAC-SHA256 of the
11
31
  * path under a subkey derived from the secret (the raw
12
32
  * HMAC of the secret over the label `crabcrop/purge-key`),
13
- * so an image signature can never be replayed as a purge
14
- * signature. This is the signature segment for
15
- * `POST /purge/<signature>/<path>`.
33
+ * so an image signature does not verify as a purge
34
+ * signature: no signer signs a label (see
35
+ * {@link RESERVED_SEGMENT}). This is the signature segment
36
+ * for `POST /purge/<signature>/<path>`.
16
37
  */
17
38
  export declare function purgeSignature(secret: string, target: string): string;
18
39
  /**
@@ -31,9 +52,11 @@ export declare function purgeGroupSignature(secret: string, group: string): stri
31
52
  * The upload signature for an object name: HMAC-SHA256 of
32
53
  * the name under a subkey derived from the secret (the raw
33
54
  * HMAC of the secret over the label `crabcrop/upload-key`),
34
- * so neither an image signature nor a purge signature can
35
- * ever be replayed as an upload signature. This is the
36
- * signature segment for `PUT /upload/<signature>/<name>`.
55
+ * so neither an image signature nor a purge signature
56
+ * verifies as an upload signature: a purge signature is
57
+ * under another subkey, and no signer signs a label (see
58
+ * {@link RESERVED_SEGMENT}). This is the signature segment
59
+ * for `PUT /upload/<signature>/<name>`.
37
60
  *
38
61
  * With `expires` (unix seconds), the signature covers
39
62
  * `exp:<expires>/<name>` instead, and the request path is
@@ -8,19 +8,48 @@
8
8
  import { aes256GcmOpen, aes256GcmSeal, hmacSha256, randomBytes, timingSafeEqual, } from "#crypto";
9
9
  import { fromBase64Url, toBase64Url, toHex, utf8, utf8Strict } from "./bytes.js";
10
10
  import { MAX_DIMENSION } from "./limits.js";
11
+ /**
12
+ * The first remainder segment reserved for key derivation.
13
+ * Every derived subkey (purge, purge-group, upload, seal, and
14
+ * the server's cache entry key) is the HMAC of a label such as
15
+ * `crabcrop/purge-key` under the secret, which is the image
16
+ * signature of that label. No image URL may begin with this
17
+ * segment (the server refuses one with `400 reserved_segment`),
18
+ * and {@link sign} and every builder refuse a remainder that
19
+ * does, so no image signature is ever a subkey.
20
+ */
21
+ export const RESERVED_SEGMENT = "crabcrop";
22
+ /**
23
+ * Whether `remainder` begins with {@link RESERVED_SEGMENT}: it
24
+ * is that segment alone or starts with `crabcrop/`. The test is
25
+ * on the text as written, as the HMAC is: `exp:1/crabcrop/x`
26
+ * and `CRABCROP/x` are not reserved.
27
+ */
28
+ export function isReservedRemainder(remainder) {
29
+ return remainder === RESERVED_SEGMENT || remainder.startsWith(`${RESERVED_SEGMENT}/`);
30
+ }
31
+ function assertNotReserved(remainder) {
32
+ if (isReservedRemainder(remainder)) {
33
+ throw new Error(`remainder begins with the reserved segment "${RESERVED_SEGMENT}": it is kept for key derivation, and no image URL may begin with it`);
34
+ }
35
+ }
11
36
  /**
12
37
  * Compute the signature segment for a remainder: the lowercase
13
38
  * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
14
39
  * is everything after the signature segment in the URL,
15
- * exactly as it will appear.
40
+ * exactly as it will appear. A remainder that begins with
41
+ * {@link RESERVED_SEGMENT} throws: its signature could be a
42
+ * derived subkey.
16
43
  */
17
44
  export function sign(secret, remainder) {
45
+ assertNotReserved(remainder);
18
46
  return toHex(hmacSha256(secret, remainder));
19
47
  }
20
48
  /**
21
49
  * 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.
50
+ * `label` under it, one per signing domain. Every label begins
51
+ * with {@link RESERVED_SEGMENT}, which is why {@link sign}
52
+ * refuses to compute the same value as a signature.
24
53
  */
25
54
  function subkey(secret, label) {
26
55
  return hmacSha256(secret, label);
@@ -30,9 +59,10 @@ function subkey(secret, label) {
30
59
  * remainder without its signature): HMAC-SHA256 of the
31
60
  * path under a subkey derived from the secret (the raw
32
61
  * HMAC of the secret over the label `crabcrop/purge-key`),
33
- * so an image signature can never be replayed as a purge
34
- * signature. This is the signature segment for
35
- * `POST /purge/<signature>/<path>`.
62
+ * so an image signature does not verify as a purge
63
+ * signature: no signer signs a label (see
64
+ * {@link RESERVED_SEGMENT}). This is the signature segment
65
+ * for `POST /purge/<signature>/<path>`.
36
66
  */
37
67
  export function purgeSignature(secret, target) {
38
68
  return toHex(hmacSha256(subkey(secret, "crabcrop/purge-key"), target));
@@ -55,9 +85,11 @@ export function purgeGroupSignature(secret, group) {
55
85
  * The upload signature for an object name: HMAC-SHA256 of
56
86
  * the name under a subkey derived from the secret (the raw
57
87
  * HMAC of the secret over the label `crabcrop/upload-key`),
58
- * so neither an image signature nor a purge signature can
59
- * ever be replayed as an upload signature. This is the
60
- * signature segment for `PUT /upload/<signature>/<name>`.
88
+ * so neither an image signature nor a purge signature
89
+ * verifies as an upload signature: a purge signature is
90
+ * under another subkey, and no signer signs a label (see
91
+ * {@link RESERVED_SEGMENT}). This is the signature segment
92
+ * for `PUT /upload/<signature>/<name>`.
61
93
  *
62
94
  * With `expires` (unix seconds), the signature covers
63
95
  * `exp:<expires>/<name>` instead, and the request path is
@@ -200,9 +232,6 @@ export function unseal(secret, segment) {
200
232
  * required: there is no `unsafe` spelling of a token.
201
233
  */
202
234
  export function buildSealedURL(base, secret, operations, source, options = {}) {
203
- if (secret === null || secret === undefined) {
204
- throw new Error("sealing requires a secret: there is no unsafe token");
205
- }
206
235
  if (options.expires !== undefined) {
207
236
  assertExpires(options.expires);
208
237
  }
@@ -217,6 +246,13 @@ export function buildSealedURL(base, secret, operations, source, options = {}) {
217
246
  remainder += `${operations}/`;
218
247
  }
219
248
  remainder += source;
249
+ assertNotReserved(remainder);
250
+ // The inputs are checked before the secret, as in the Rust
251
+ // and Python builders, so a refused input gets the same
252
+ // error with or without a secret.
253
+ if (secret === null || secret === undefined) {
254
+ throw new Error("sealing requires a secret: there is no unsafe token");
255
+ }
220
256
  const segment = seal(secret, remainder, options.keyId);
221
257
  return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
222
258
  }
@@ -287,6 +323,9 @@ export function buildURL(base, secret, operations, source, options = {}) {
287
323
  remainder += `${operations}/`;
288
324
  }
289
325
  remainder += source;
326
+ // Refused with or without a secret: the server refuses the
327
+ // URL whatever its signature.
328
+ assertNotReserved(remainder);
290
329
  let signature;
291
330
  if (secret === null) {
292
331
  if (options.keyId !== undefined) {
@@ -336,6 +375,12 @@ export function verifyUrlSignature(secret, input) {
336
375
  if (!signature || signature.kind !== "hmac") {
337
376
  return null;
338
377
  }
378
+ // No signature over a reserved remainder is ever valid: the
379
+ // server refuses it whatever the signature, and this check
380
+ // must not confirm a derived subkey either.
381
+ if (isReservedRemainder(remainder)) {
382
+ return false;
383
+ }
339
384
  // Constant-time, like the Rust and Python verifiers: a
340
385
  // plain === leaks how much of the tag was right.
341
386
  const given = utf8(signature.value);
@@ -29,7 +29,7 @@
29
29
  "test": "node --test && node --conditions=browser --test"
30
30
  },
31
31
  "type": "module",
32
- "version": "0.10.0",
32
+ "version": "0.11.0",
33
33
  "devDependencies": {
34
34
  "@types/node": "^26.6.5",
35
35
  "typescript": "^7.0.2"
package/package.json CHANGED
@@ -15,7 +15,7 @@
15
15
  "test": "node --test test/*.test.mjs"
16
16
  },
17
17
  "type": "module",
18
- "version": "0.10.0",
18
+ "version": "0.11.0",
19
19
  "devDependencies": {
20
20
  "@types/node": "^26.6.5",
21
21
  "typescript": "^5.9.3"
package/server.json CHANGED
@@ -1 +1 @@
1
- {"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Sign and explain crabcrop image URLs, fetch processed-image metadata, and purge cached results.","name":"io.github.crabcrop/crabcrop","packages":[{"environmentVariables":[{"description":"Base URL of the crabcrop server the tools act on (for example https://images.example.com).","format":"string","isRequired":false,"isSecret":false,"name":"CRABCROP_BASE"},{"description":"The server's signing secret, used by sign_url and purge_result. Keep it in the environment, not in tool arguments.","format":"string","isRequired":false,"isSecret":true,"name":"CRABCROP_SECRET"}],"identifier":"@crabcrop/mcp","registryBaseUrl":"https://registry.npmjs.org","registryType":"npm","runTimeHint":"npx","transport":{"type":"stdio"},"version":"0.10.0"}],"repository":{"source":"github","url":"https://github.com/dayvson/crabcrop"},"version":"0.10.0"}
1
+ {"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Sign and explain crabcrop image URLs, fetch processed-image metadata, and purge cached results.","name":"io.github.crabcrop/crabcrop","packages":[{"environmentVariables":[{"description":"Base URL of the crabcrop server the tools act on (for example https://images.example.com).","format":"string","isRequired":false,"isSecret":false,"name":"CRABCROP_BASE"},{"description":"The server's signing secret, used by sign_url and purge_result. Keep it in the environment, not in tool arguments.","format":"string","isRequired":false,"isSecret":true,"name":"CRABCROP_SECRET"}],"identifier":"@crabcrop/mcp","registryBaseUrl":"https://registry.npmjs.org","registryType":"npm","runTimeHint":"npx","transport":{"type":"stdio"},"version":"0.11.0"}],"repository":{"source":"github","url":"https://github.com/dayvson/crabcrop"},"version":"0.11.0"}