@crabcrop/mcp 0.10.1 → 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 +1 -1
- package/dist/index.js +1 -1
- package/node_modules/@crabcrop/url/README.md +4 -1
- package/node_modules/@crabcrop/url/dist/index.d.ts +30 -7
- package/node_modules/@crabcrop/url/dist/index.js +57 -12
- package/node_modules/@crabcrop/url/package.json +1 -1
- package/package.json +1 -1
- package/server.json +1 -1
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.
|
|
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
|
|
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
|
|
14
|
-
* signature
|
|
15
|
-
*
|
|
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
|
|
35
|
-
*
|
|
36
|
-
*
|
|
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
|
|
23
|
-
*
|
|
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
|
|
34
|
-
* signature
|
|
35
|
-
*
|
|
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
|
|
59
|
-
*
|
|
60
|
-
*
|
|
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);
|
package/package.json
CHANGED
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.
|
|
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"}
|