@crabcrop/mcp 0.13.0 → 0.14.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.
@@ -1,21 +1,4 @@
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
+ export { isReservedRemainder, RESERVED_SEGMENT } from "./limits.ts";
19
2
  /**
20
3
  * Compute the signature segment for a remainder: the lowercase
21
4
  * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
@@ -34,8 +17,24 @@ export declare function sign(secret: string, remainder: string): string;
34
17
  * signature: no signer signs a label (see
35
18
  * {@link RESERVED_SEGMENT}). This is the signature segment
36
19
  * for `POST /purge/<signature>/<path>`.
20
+ *
21
+ * With `expires` (unix seconds), the signature covers
22
+ * `exp:<expires>/<path>` instead, and the request path is
23
+ * `POST /purge/<signature>/exp:<expires>/<path>`: the
24
+ * expiry sits inside the signed string, so it can neither
25
+ * be stripped nor extended, and the server refuses the
26
+ * purge once that second is reached. Without it the
27
+ * signature authorizes the purge until the secret rotates.
28
+ * An expiry that is not a non-negative integer throws.
29
+ *
30
+ * The server reads a leading `exp:` segment of the path as
31
+ * the purge's own expiry, so a target that opens with an
32
+ * image URL's `exp:` is refused from that second on. An
33
+ * image's `exp:` is not part of its cache key:
34
+ * drop it from the target and the purge evicts the same
35
+ * entries.
37
36
  */
38
- export declare function purgeSignature(secret: string, target: string): string;
37
+ export declare function purgeSignature(secret: string, target: string, expires?: number): string;
39
38
  /**
40
39
  * The purge-group signature for a cache group: HMAC-SHA256
41
40
  * of the group name under a subkey derived from the secret
@@ -46,8 +45,14 @@ export declare function purgeSignature(secret: string, target: string): string;
46
45
  * exists so nobody has to know the signed string. This is
47
46
  * the signature segment for
48
47
  * `POST /purge-group/<signature>/<group>`.
48
+ *
49
+ * With `expires` (unix seconds), the signature covers
50
+ * `exp:<expires>/<group>`, the request path is
51
+ * `POST /purge-group/<signature>/exp:<expires>/<group>`, and
52
+ * the server refuses the purge once that second is
53
+ * reached, as for {@link purgeSignature}.
49
54
  */
50
- export declare function purgeGroupSignature(secret: string, group: string): string;
55
+ export declare function purgeGroupSignature(secret: string, group: string, expires?: number): string;
51
56
  /**
52
57
  * The upload signature for an object name: HMAC-SHA256 of
53
58
  * the name under a subkey derived from the secret (the raw
@@ -7,27 +7,10 @@
7
7
  */
8
8
  import { aes256GcmOpen, aes256GcmSeal, hmacSha256, randomBytes, timingSafeEqual, } from "#crypto";
9
9
  import { fromBase64Url, toBase64Url, toHex, utf8, utf8Strict } from "./bytes.js";
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
- }
10
+ import { isReservedRemainder, MAX_DIMENSION, RESERVED_SEGMENT } from "./limits.js";
11
+ // Declared beside MAX_DIMENSION, where the explainer reads them
12
+ // too (issue #712).
13
+ export { isReservedRemainder, RESERVED_SEGMENT } from "./limits.js";
31
14
  function assertNotReserved(remainder) {
32
15
  if (isReservedRemainder(remainder)) {
33
16
  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`);
@@ -54,6 +37,18 @@ export function sign(secret, remainder) {
54
37
  function subkey(secret, label) {
55
38
  return hmacSha256(secret, label);
56
39
  }
40
+ /**
41
+ * The signed string of a purge or purge-group signature:
42
+ * the target, or `exp:<expires>/` and the target. It is also
43
+ * what follows the signature segment in the request path.
44
+ */
45
+ function purgeSignedString(target, expires) {
46
+ if (expires === undefined) {
47
+ return target;
48
+ }
49
+ assertExpires(expires);
50
+ return `exp:${expires}/${target}`;
51
+ }
57
52
  /**
58
53
  * The purge signature for a target path (the request
59
54
  * remainder without its signature): HMAC-SHA256 of the
@@ -63,9 +58,26 @@ function subkey(secret, label) {
63
58
  * signature: no signer signs a label (see
64
59
  * {@link RESERVED_SEGMENT}). This is the signature segment
65
60
  * for `POST /purge/<signature>/<path>`.
61
+ *
62
+ * With `expires` (unix seconds), the signature covers
63
+ * `exp:<expires>/<path>` instead, and the request path is
64
+ * `POST /purge/<signature>/exp:<expires>/<path>`: the
65
+ * expiry sits inside the signed string, so it can neither
66
+ * be stripped nor extended, and the server refuses the
67
+ * purge once that second is reached. Without it the
68
+ * signature authorizes the purge until the secret rotates.
69
+ * An expiry that is not a non-negative integer throws.
70
+ *
71
+ * The server reads a leading `exp:` segment of the path as
72
+ * the purge's own expiry, so a target that opens with an
73
+ * image URL's `exp:` is refused from that second on. An
74
+ * image's `exp:` is not part of its cache key:
75
+ * drop it from the target and the purge evicts the same
76
+ * entries.
66
77
  */
67
- export function purgeSignature(secret, target) {
68
- return toHex(hmacSha256(subkey(secret, "crabcrop/purge-key"), target));
78
+ export function purgeSignature(secret, target, expires) {
79
+ const signed = purgeSignedString(target, expires);
80
+ return toHex(hmacSha256(subkey(secret, "crabcrop/purge-key"), signed));
69
81
  }
70
82
  /**
71
83
  * The purge-group signature for a cache group: HMAC-SHA256
@@ -77,9 +89,16 @@ export function purgeSignature(secret, target) {
77
89
  * exists so nobody has to know the signed string. This is
78
90
  * the signature segment for
79
91
  * `POST /purge-group/<signature>/<group>`.
92
+ *
93
+ * With `expires` (unix seconds), the signature covers
94
+ * `exp:<expires>/<group>`, the request path is
95
+ * `POST /purge-group/<signature>/exp:<expires>/<group>`, and
96
+ * the server refuses the purge once that second is
97
+ * reached, as for {@link purgeSignature}.
80
98
  */
81
- export function purgeGroupSignature(secret, group) {
82
- return toHex(hmacSha256(subkey(secret, "crabcrop/purge-group-key"), group));
99
+ export function purgeGroupSignature(secret, group, expires) {
100
+ const signed = purgeSignedString(group, expires);
101
+ return toHex(hmacSha256(subkey(secret, "crabcrop/purge-group-key"), signed));
83
102
  }
84
103
  /**
85
104
  * The upload signature for an object name: HMAC-SHA256 of
@@ -7,3 +7,22 @@
7
7
  * integrations all check against this one constant.
8
8
  */
9
9
  export declare const MAX_DIMENSION = 16383;
10
+ /**
11
+ * The first remainder segment reserved for key derivation.
12
+ * Every derived subkey (purge, purge-group, upload, seal, and
13
+ * the server's cache entry key) is the HMAC of a label such as
14
+ * `crabcrop/purge-key` under the secret, which is the image
15
+ * signature of that label. No image URL may begin with this
16
+ * segment (the server refuses one with `400 reserved_segment`),
17
+ * and `sign` and every builder refuse a remainder that does,
18
+ * so no image signature is ever a subkey. The explainer reports
19
+ * such a remainder as the server answers it.
20
+ */
21
+ export declare 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 declare function isReservedRemainder(remainder: string): boolean;
@@ -7,3 +7,24 @@
7
7
  * integrations all check against this one constant.
8
8
  */
9
9
  export const MAX_DIMENSION = 16383;
10
+ /**
11
+ * The first remainder segment reserved for key derivation.
12
+ * Every derived subkey (purge, purge-group, upload, seal, and
13
+ * the server's cache entry key) is the HMAC of a label such as
14
+ * `crabcrop/purge-key` under the secret, which is the image
15
+ * signature of that label. No image URL may begin with this
16
+ * segment (the server refuses one with `400 reserved_segment`),
17
+ * and `sign` and every builder refuse a remainder that does,
18
+ * so no image signature is ever a subkey. The explainer reports
19
+ * such a remainder as the server answers it.
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
+ }
@@ -29,7 +29,7 @@
29
29
  "test": "node --test && node --conditions=browser --test"
30
30
  },
31
31
  "type": "module",
32
- "version": "0.13.0",
32
+ "version": "0.14.0",
33
33
  "devDependencies": {
34
34
  "@types/node": "^26.6.5",
35
35
  "typescript": "^7.0.2"
package/package.json CHANGED
@@ -15,10 +15,10 @@
15
15
  "test": "node --test --test-concurrency=1 test/*.test.mjs"
16
16
  },
17
17
  "type": "module",
18
- "version": "0.13.0",
18
+ "version": "0.14.0",
19
19
  "devDependencies": {
20
20
  "@types/node": "^26.6.5",
21
- "typescript": "^5.9.3"
21
+ "typescript": "^7.0.2"
22
22
  },
23
23
  "main": "./dist/index.js",
24
24
  "bundleDependencies": [
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.13.0"}],"repository":{"source":"github","url":"https://github.com/dayvson/crabcrop"},"version":"0.13.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.14.0"}],"repository":{"source":"github","url":"https://github.com/dayvson/crabcrop"},"version":"0.14.0"}