@crabcrop/mcp 0.1.0 → 0.10.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 +12 -5
- package/dist/index.js +83 -34
- package/node_modules/@crabcrop/url/README.md +51 -7
- package/node_modules/@crabcrop/url/dist/bytes.d.ts +21 -0
- package/node_modules/@crabcrop/url/dist/bytes.js +86 -0
- package/node_modules/@crabcrop/url/dist/crypto/aes-gcm.d.ts +21 -0
- package/node_modules/@crabcrop/url/dist/crypto/aes-gcm.js +248 -0
- package/node_modules/@crabcrop/url/dist/crypto/node.d.ts +11 -0
- package/node_modules/@crabcrop/url/dist/crypto/node.js +41 -0
- package/node_modules/@crabcrop/url/dist/crypto/portable.d.ts +14 -0
- package/node_modules/@crabcrop/url/dist/crypto/portable.js +60 -0
- package/node_modules/@crabcrop/url/dist/crypto/sha256.d.ts +14 -0
- package/node_modules/@crabcrop/url/dist/crypto/sha256.js +131 -0
- package/node_modules/@crabcrop/url/dist/explain.d.ts +56 -8
- package/node_modules/@crabcrop/url/dist/explain.js +497 -50
- package/node_modules/@crabcrop/url/dist/index.d.ts +83 -5
- package/node_modules/@crabcrop/url/dist/index.js +201 -26
- package/node_modules/@crabcrop/url/dist/limits.d.ts +9 -0
- package/node_modules/@crabcrop/url/dist/limits.js +9 -0
- package/node_modules/@crabcrop/url/dist/operations.d.ts +114 -19
- package/node_modules/@crabcrop/url/dist/operations.js +343 -50
- package/node_modules/@crabcrop/url/package.json +12 -4
- package/package.json +1 -1
- package/server.json +1 -1
|
@@ -16,9 +16,12 @@ export declare function sign(secret: string, remainder: string): string;
|
|
|
16
16
|
*/
|
|
17
17
|
export declare function purgeSignature(secret: string, target: string): string;
|
|
18
18
|
/**
|
|
19
|
-
* The purge-group signature for a cache group:
|
|
20
|
-
*
|
|
21
|
-
*
|
|
19
|
+
* The purge-group signature for a cache group: HMAC-SHA256
|
|
20
|
+
* of the group name under a subkey derived from the secret
|
|
21
|
+
* (the raw HMAC of the secret over the label
|
|
22
|
+
* `crabcrop/purge-group-key`), its own domain beside the
|
|
23
|
+
* purge subkey, so a per-target purge signature can never
|
|
24
|
+
* be transplanted to the purge-group endpoint. The helper
|
|
22
25
|
* exists so nobody has to know the signed string. This is
|
|
23
26
|
* the signature segment for
|
|
24
27
|
* `POST /purge-group/<signature>/<group>`.
|
|
@@ -31,8 +34,17 @@ export declare function purgeGroupSignature(secret: string, group: string): stri
|
|
|
31
34
|
* so neither an image signature nor a purge signature can
|
|
32
35
|
* ever be replayed as an upload signature. This is the
|
|
33
36
|
* signature segment for `PUT /upload/<signature>/<name>`.
|
|
37
|
+
*
|
|
38
|
+
* With `expires` (unix seconds), the signature covers
|
|
39
|
+
* `exp:<expires>/<name>` instead, and the request path is
|
|
40
|
+
* `PUT /upload/<signature>/exp:<expires>/<name>`: the
|
|
41
|
+
* expiry sits inside the signed string, so it can neither
|
|
42
|
+
* be stripped nor extended, and the server refuses the
|
|
43
|
+
* upload once that second is reached. Delegated upload
|
|
44
|
+
* tokens should always use the expiring form; without it
|
|
45
|
+
* a token replays until the secret rotates.
|
|
34
46
|
*/
|
|
35
|
-
export declare function uploadSignature(secret: string, name: string): string;
|
|
47
|
+
export declare function uploadSignature(secret: string, name: string, expires?: number): string;
|
|
36
48
|
export interface BuildOptions {
|
|
37
49
|
/** Unix-seconds expiry, emitted as a leading `exp:` segment. */
|
|
38
50
|
expires?: number;
|
|
@@ -51,6 +63,71 @@ export declare function isValidKeyId(id: string): boolean;
|
|
|
51
63
|
* followed by the hex tag `sign` computes.
|
|
52
64
|
*/
|
|
53
65
|
export declare function signWithKeyId(secret: string, keyId: string, remainder: string): string;
|
|
66
|
+
/**
|
|
67
|
+
* The largest remainder {@link seal} will encrypt, in bytes
|
|
68
|
+
* (issue #255). A recipe longer than this belongs in a
|
|
69
|
+
* preset; the cap also bounds the token a server must
|
|
70
|
+
* decode.
|
|
71
|
+
*/
|
|
72
|
+
export declare const MAX_SEALED_REMAINDER = 2048;
|
|
73
|
+
/**
|
|
74
|
+
* Seal a remainder into a token segment with a
|
|
75
|
+
* caller-supplied nonce: `s1.<base64url(nonce ||
|
|
76
|
+
* ciphertext || tag)>`, AES-256-GCM under the derived seal
|
|
77
|
+
* subkey with the fixed associated data `crabcrop/sealed/1`.
|
|
78
|
+
*
|
|
79
|
+
* DANGER: a nonce must never repeat under one secret.
|
|
80
|
+
* Reusing a nonce with AES-GCM destroys the construction's
|
|
81
|
+
* confidentiality and integrity guarantees. This function
|
|
82
|
+
* is the deterministic seam the spec's test vectors use;
|
|
83
|
+
* production minting calls {@link seal}, which draws a
|
|
84
|
+
* fresh random nonce every time.
|
|
85
|
+
*/
|
|
86
|
+
export declare function sealWithNonce(secret: string, remainder: string, nonce: Uint8Array, keyId?: string): string;
|
|
87
|
+
/**
|
|
88
|
+
* Seal a remainder into a token segment (issue #255), with
|
|
89
|
+
* a fresh random 96-bit nonce. The token is the whole
|
|
90
|
+
* signature segment; pass `keyId` to stamp `<key-id>:`
|
|
91
|
+
* in front of it, so servers in a rotation window open it
|
|
92
|
+
* against the named key only.
|
|
93
|
+
*/
|
|
94
|
+
export declare function seal(secret: string, remainder: string, keyId?: string): string;
|
|
95
|
+
/**
|
|
96
|
+
* Open a token segment, with or without a `<key-id>:`
|
|
97
|
+
* prefix, under one secret, returning the remainder it
|
|
98
|
+
* seals. The key ID is routing metadata and is not
|
|
99
|
+
* consulted: the question is whether this secret opens the
|
|
100
|
+
* token. Every failure (malformed body, wrong secret,
|
|
101
|
+
* tampered bytes, unknown version) throws the one error,
|
|
102
|
+
* `the token did not open under this secret`: openers must
|
|
103
|
+
* never learn which stage failed.
|
|
104
|
+
*/
|
|
105
|
+
export declare function unseal(secret: string, segment: string): string;
|
|
106
|
+
/** Options for {@link buildSealedURL}. */
|
|
107
|
+
export interface SealOptions {
|
|
108
|
+
/** Unix-seconds expiry, sealed inside the token as a leading `exp:` segment. */
|
|
109
|
+
expires?: number;
|
|
110
|
+
/** Key ID to stamp on the token segment (`<key-id>:s1.…`), for rotation. */
|
|
111
|
+
keyId?: string;
|
|
112
|
+
/**
|
|
113
|
+
* The cosmetic friendly name after the token. The server
|
|
114
|
+
* never parses, validates, or authenticates it; one
|
|
115
|
+
* filename-like segment is the dependable shape. Omit it
|
|
116
|
+
* and the URL ends at the token.
|
|
117
|
+
*/
|
|
118
|
+
name?: string;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Assemble a sealed crabcrop URL:
|
|
122
|
+
* `{base}/[<key-id>:]s1.<token>/{friendly-name}` (issue
|
|
123
|
+
* #255). The remainder is assembled exactly as
|
|
124
|
+
* {@link buildURL} assembles it (expiry segment,
|
|
125
|
+
* operations, source) and then sealed whole, pre-expansion,
|
|
126
|
+
* so the sealed and plain forms of one render are one cache
|
|
127
|
+
* entry and one purge target on the server. A secret is
|
|
128
|
+
* required: there is no `unsafe` spelling of a token.
|
|
129
|
+
*/
|
|
130
|
+
export declare function buildSealedURL(base: string, secret: string, operations: string, source: string, options?: SealOptions): string;
|
|
54
131
|
/**
|
|
55
132
|
* Assemble a signed (or `unsafe`) crabcrop URL. `operations`
|
|
56
133
|
* is the operation string verbatim (several `/`-separated
|
|
@@ -68,8 +145,9 @@ export declare function buildSrcSet(base: string, secret: string | null, source:
|
|
|
68
145
|
export { explainUrl } from "./explain.ts";
|
|
69
146
|
export { FILTER_DESCRIPTIONS } from "./explain.ts";
|
|
70
147
|
export type { ExplainedSegment, Explanation, SegmentKind, SignatureKind } from "./explain.ts";
|
|
148
|
+
export { MAX_DIMENSION } from "./limits.ts";
|
|
71
149
|
export { filter, joinOps, ops } from "./operations.ts";
|
|
72
|
-
export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, } from "./operations.ts";
|
|
150
|
+
export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, FormatOptions, ImageFormat, MaskShape, PerFormatQualityFormat, StudioMode, StudioOptions, StudioShadow, } from "./operations.ts";
|
|
73
151
|
/**
|
|
74
152
|
* Verify a URL's signature locally. Returns true or false, or
|
|
75
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.
|
|
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 {
|
|
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 { createHmac, timingSafeEqual } from "node:crypto";
|
|
|
10
15
|
* exactly as it will appear.
|
|
11
16
|
*/
|
|
12
17
|
export function sign(secret, remainder) {
|
|
13
|
-
return
|
|
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,19 +35,21 @@ export function sign(secret, remainder) {
|
|
|
22
35
|
* `POST /purge/<signature>/<path>`.
|
|
23
36
|
*/
|
|
24
37
|
export function purgeSignature(secret, target) {
|
|
25
|
-
|
|
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
|
-
* The purge-group signature for a cache group:
|
|
30
|
-
*
|
|
31
|
-
*
|
|
41
|
+
* The purge-group signature for a cache group: HMAC-SHA256
|
|
42
|
+
* of the group name under a subkey derived from the secret
|
|
43
|
+
* (the raw HMAC of the secret over the label
|
|
44
|
+
* `crabcrop/purge-group-key`), its own domain beside the
|
|
45
|
+
* purge subkey, so a per-target purge signature can never
|
|
46
|
+
* be transplanted to the purge-group endpoint. The helper
|
|
32
47
|
* exists so nobody has to know the signed string. This is
|
|
33
48
|
* the signature segment for
|
|
34
49
|
* `POST /purge-group/<signature>/<group>`.
|
|
35
50
|
*/
|
|
36
51
|
export function purgeGroupSignature(secret, group) {
|
|
37
|
-
return
|
|
52
|
+
return toHex(hmacSha256(subkey(secret, "crabcrop/purge-group-key"), group));
|
|
38
53
|
}
|
|
39
54
|
/**
|
|
40
55
|
* The upload signature for an object name: HMAC-SHA256 of
|
|
@@ -43,10 +58,19 @@ export function purgeGroupSignature(secret, group) {
|
|
|
43
58
|
* so neither an image signature nor a purge signature can
|
|
44
59
|
* ever be replayed as an upload signature. This is the
|
|
45
60
|
* signature segment for `PUT /upload/<signature>/<name>`.
|
|
61
|
+
*
|
|
62
|
+
* With `expires` (unix seconds), the signature covers
|
|
63
|
+
* `exp:<expires>/<name>` instead, and the request path is
|
|
64
|
+
* `PUT /upload/<signature>/exp:<expires>/<name>`: the
|
|
65
|
+
* expiry sits inside the signed string, so it can neither
|
|
66
|
+
* be stripped nor extended, and the server refuses the
|
|
67
|
+
* upload once that second is reached. Delegated upload
|
|
68
|
+
* tokens should always use the expiring form; without it
|
|
69
|
+
* a token replays until the secret rotates.
|
|
46
70
|
*/
|
|
47
|
-
export function uploadSignature(secret, name) {
|
|
48
|
-
const
|
|
49
|
-
return
|
|
71
|
+
export function uploadSignature(secret, name, expires) {
|
|
72
|
+
const signed = expires === undefined ? name : `exp:${expires}/${name}`;
|
|
73
|
+
return toHex(hmacSha256(subkey(secret, "crabcrop/upload-key"), signed));
|
|
50
74
|
}
|
|
51
75
|
/** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
|
|
52
76
|
export function isValidKeyId(id) {
|
|
@@ -62,18 +86,165 @@ export function signWithKeyId(secret, keyId, remainder) {
|
|
|
62
86
|
}
|
|
63
87
|
return `${keyId}:${sign(secret, remainder)}`;
|
|
64
88
|
}
|
|
89
|
+
/**
|
|
90
|
+
* The largest remainder {@link seal} will encrypt, in bytes
|
|
91
|
+
* (issue #255). A recipe longer than this belongs in a
|
|
92
|
+
* preset; the cap also bounds the token a server must
|
|
93
|
+
* decode.
|
|
94
|
+
*/
|
|
95
|
+
export const MAX_SEALED_REMAINDER = 2048;
|
|
96
|
+
/** The AAD every sealed token is bound to. */
|
|
97
|
+
const SEAL_AAD = utf8("crabcrop/sealed/1");
|
|
98
|
+
/**
|
|
99
|
+
* The seal subkey: the raw bytes of the HMAC-SHA256 of the
|
|
100
|
+
* label `crabcrop/seal-key` under the secret, its own domain
|
|
101
|
+
* beside purge, purge-group, and upload, so there is no
|
|
102
|
+
* second secret to configure or rotate: each keyring entry
|
|
103
|
+
* yields its own seal subkey, and the rotation window for
|
|
104
|
+
* signatures is the rotation window for tokens.
|
|
105
|
+
*/
|
|
106
|
+
function sealKey(secret) {
|
|
107
|
+
return subkey(secret, "crabcrop/seal-key");
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Seal a remainder into a token segment with a
|
|
111
|
+
* caller-supplied nonce: `s1.<base64url(nonce ||
|
|
112
|
+
* ciphertext || tag)>`, AES-256-GCM under the derived seal
|
|
113
|
+
* subkey with the fixed associated data `crabcrop/sealed/1`.
|
|
114
|
+
*
|
|
115
|
+
* DANGER: a nonce must never repeat under one secret.
|
|
116
|
+
* Reusing a nonce with AES-GCM destroys the construction's
|
|
117
|
+
* confidentiality and integrity guarantees. This function
|
|
118
|
+
* is the deterministic seam the spec's test vectors use;
|
|
119
|
+
* production minting calls {@link seal}, which draws a
|
|
120
|
+
* fresh random nonce every time.
|
|
121
|
+
*/
|
|
122
|
+
export function sealWithNonce(secret, remainder, nonce, keyId) {
|
|
123
|
+
if (nonce.length !== 12) {
|
|
124
|
+
throw new Error(`sealed token nonce must be 12 bytes, got ${nonce.length}`);
|
|
125
|
+
}
|
|
126
|
+
const plaintext = utf8(remainder);
|
|
127
|
+
if (plaintext.length > MAX_SEALED_REMAINDER) {
|
|
128
|
+
throw new Error(`remainder is over the ${MAX_SEALED_REMAINDER}-byte sealing cap: a recipe that long belongs in a preset`);
|
|
129
|
+
}
|
|
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)}`;
|
|
135
|
+
if (keyId === undefined) {
|
|
136
|
+
return token;
|
|
137
|
+
}
|
|
138
|
+
if (!isValidKeyId(keyId)) {
|
|
139
|
+
throw new Error(`invalid key ID ${JSON.stringify(keyId)}: 1 to 32 characters of [A-Za-z0-9_-]`);
|
|
140
|
+
}
|
|
141
|
+
return `${keyId}:${token}`;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* Seal a remainder into a token segment (issue #255), with
|
|
145
|
+
* a fresh random 96-bit nonce. The token is the whole
|
|
146
|
+
* signature segment; pass `keyId` to stamp `<key-id>:`
|
|
147
|
+
* in front of it, so servers in a rotation window open it
|
|
148
|
+
* against the named key only.
|
|
149
|
+
*/
|
|
150
|
+
export function seal(secret, remainder, keyId) {
|
|
151
|
+
return sealWithNonce(secret, remainder, randomBytes(12), keyId);
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Open a token segment, with or without a `<key-id>:`
|
|
155
|
+
* prefix, under one secret, returning the remainder it
|
|
156
|
+
* seals. The key ID is routing metadata and is not
|
|
157
|
+
* consulted: the question is whether this secret opens the
|
|
158
|
+
* token. Every failure (malformed body, wrong secret,
|
|
159
|
+
* tampered bytes, unknown version) throws the one error,
|
|
160
|
+
* `the token did not open under this secret`: openers must
|
|
161
|
+
* never learn which stage failed.
|
|
162
|
+
*/
|
|
163
|
+
export function unseal(secret, segment) {
|
|
164
|
+
const openFailed = () => new Error("the token did not open under this secret");
|
|
165
|
+
let token = segment;
|
|
166
|
+
const colon = segment.indexOf(":");
|
|
167
|
+
if (colon >= 0) {
|
|
168
|
+
if (!isValidKeyId(segment.slice(0, colon))) {
|
|
169
|
+
throw openFailed();
|
|
170
|
+
}
|
|
171
|
+
token = segment.slice(colon + 1);
|
|
172
|
+
}
|
|
173
|
+
if (!token.startsWith("s1.")) {
|
|
174
|
+
throw openFailed();
|
|
175
|
+
}
|
|
176
|
+
const body = token.slice(3);
|
|
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) {
|
|
182
|
+
throw openFailed();
|
|
183
|
+
}
|
|
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) {
|
|
188
|
+
throw openFailed();
|
|
189
|
+
}
|
|
190
|
+
return text;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Assemble a sealed crabcrop URL:
|
|
194
|
+
* `{base}/[<key-id>:]s1.<token>/{friendly-name}` (issue
|
|
195
|
+
* #255). The remainder is assembled exactly as
|
|
196
|
+
* {@link buildURL} assembles it (expiry segment,
|
|
197
|
+
* operations, source) and then sealed whole, pre-expansion,
|
|
198
|
+
* so the sealed and plain forms of one render are one cache
|
|
199
|
+
* entry and one purge target on the server. A secret is
|
|
200
|
+
* required: there is no `unsafe` spelling of a token.
|
|
201
|
+
*/
|
|
202
|
+
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
|
+
if (options.expires !== undefined) {
|
|
207
|
+
assertExpires(options.expires);
|
|
208
|
+
}
|
|
209
|
+
assertUrlText(operations, "operations");
|
|
210
|
+
assertUrlText(source, "source");
|
|
211
|
+
const trimmedBase = base.replace(/\/+$/, "");
|
|
212
|
+
let remainder = "";
|
|
213
|
+
if (options.expires !== undefined) {
|
|
214
|
+
remainder += `exp:${options.expires}/`;
|
|
215
|
+
}
|
|
216
|
+
if (operations) {
|
|
217
|
+
remainder += `${operations}/`;
|
|
218
|
+
}
|
|
219
|
+
remainder += source;
|
|
220
|
+
const segment = seal(secret, remainder, options.keyId);
|
|
221
|
+
return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
|
|
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 = "\"<>\\^`{|}";
|
|
65
231
|
/**
|
|
66
232
|
* Fail loudly on inputs that can never produce a verifiable URL
|
|
67
233
|
* (audit P-4, P-5): the remainder travels as a raw URL path, so
|
|
68
|
-
* `?`/`#` would truncate it
|
|
69
|
-
*
|
|
70
|
-
*
|
|
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.
|
|
71
238
|
*/
|
|
72
239
|
function assertUrlText(text, what) {
|
|
73
240
|
for (const c of text) {
|
|
74
241
|
const code = c.codePointAt(0);
|
|
75
|
-
|
|
76
|
-
|
|
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}`);
|
|
77
248
|
}
|
|
78
249
|
}
|
|
79
250
|
}
|
|
@@ -90,8 +261,8 @@ function assertExpires(expires) {
|
|
|
90
261
|
* flip), so it throws here, at build time.
|
|
91
262
|
*/
|
|
92
263
|
function assertWidth(width) {
|
|
93
|
-
if (!Number.isSafeInteger(width) || width < 1 || width >
|
|
94
|
-
throw new Error(`srcset width must be a positive integer no larger than
|
|
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}`);
|
|
95
266
|
}
|
|
96
267
|
}
|
|
97
268
|
/**
|
|
@@ -146,6 +317,7 @@ export function buildSrcSet(base, secret, source, widths, options = {}) {
|
|
|
146
317
|
}
|
|
147
318
|
export { explainUrl } from "./explain.js";
|
|
148
319
|
export { FILTER_DESCRIPTIONS } from "./explain.js";
|
|
320
|
+
export { MAX_DIMENSION } from "./limits.js";
|
|
149
321
|
export { filter, joinOps, ops } from "./operations.js";
|
|
150
322
|
import { explainUrl } from "./explain.js";
|
|
151
323
|
/**
|
|
@@ -166,17 +338,20 @@ export function verifyUrlSignature(secret, input) {
|
|
|
166
338
|
}
|
|
167
339
|
// Constant-time, like the Rust and Python verifiers: a
|
|
168
340
|
// plain === leaks how much of the tag was right.
|
|
169
|
-
const given =
|
|
170
|
-
const matches = (candidate) =>
|
|
171
|
-
const expected = Buffer.from(sign(candidate, remainder), "utf8");
|
|
172
|
-
return expected.length === given.length && timingSafeEqual(expected, given);
|
|
173
|
-
};
|
|
341
|
+
const given = utf8(signature.value);
|
|
342
|
+
const matches = (candidate) => timingSafeEqual(utf8(sign(candidate, remainder)), given);
|
|
174
343
|
if (typeof secret === "string") {
|
|
175
344
|
return matches(secret);
|
|
176
345
|
}
|
|
177
346
|
if (signature.keyId !== undefined) {
|
|
178
|
-
|
|
179
|
-
|
|
347
|
+
// Own properties only: key IDs are attacker-shaped text
|
|
348
|
+
// (`constructor`, `toString`, `__proto__` are all legal
|
|
349
|
+
// IDs), and an inherited lookup would hand a non-string
|
|
350
|
+
// to the HMAC and throw instead of answering false.
|
|
351
|
+
const candidate = Object.hasOwn(secret, signature.keyId)
|
|
352
|
+
? secret[signature.keyId]
|
|
353
|
+
: undefined;
|
|
354
|
+
return typeof candidate === "string" ? matches(candidate) : false;
|
|
180
355
|
}
|
|
181
356
|
return Object.values(secret).some(matches);
|
|
182
357
|
}
|
|
@@ -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,18 +1,20 @@
|
|
|
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";
|
|
3
|
+
/** Formats a per-format quality entry can name (the video formats take no quality). */
|
|
4
|
+
export type PerFormatQualityFormat = "jpeg" | "png" | "webp" | "jxl" | "avif" | "gif";
|
|
5
|
+
/** Per-format encoder options for the `format(...)` filter (issue #319). */
|
|
6
|
+
export interface FormatOptions {
|
|
7
|
+
/** JPEG: progressive (multi-scan) encoding. */
|
|
8
|
+
progressive?: boolean;
|
|
9
|
+
/** JPEG: chroma subsampling, 444, 422, or 420. */
|
|
10
|
+
subsampling?: 444 | 422 | 420;
|
|
11
|
+
/** PNG: Adam7 interlacing. */
|
|
12
|
+
interlace?: boolean;
|
|
13
|
+
/** WebP: libwebp compression method, 0..6. */
|
|
14
|
+
method?: number;
|
|
15
|
+
/** WebP: smart subsampling strength, 0..100. */
|
|
16
|
+
sns?: number;
|
|
17
|
+
}
|
|
16
18
|
/** Crop alignments; `center` is the bare `crop:WxH` spelling. */
|
|
17
19
|
export type CropAlign = "center" | "smart" | "face" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
|
|
18
20
|
/** Text-overlay anchor points. */
|
|
@@ -23,9 +25,39 @@ export type BlendMode = "normal" | "multiply" | "screen" | "overlay";
|
|
|
23
25
|
export type MaskShape = "circle" | "ellipse";
|
|
24
26
|
/** Channels the `curve(...)` filter remaps. */
|
|
25
27
|
export type CurveChannel = "rgb" | "r" | "g" | "b";
|
|
28
|
+
/** Modes the `studio(...)` filter runs. */
|
|
29
|
+
export type StudioMode = "product" | "scene";
|
|
30
|
+
/** Contact shadow strengths for `studio(product, ...)`. */
|
|
31
|
+
export type StudioShadow = "soft" | "strong" | "none";
|
|
32
|
+
/**
|
|
33
|
+
* Named arguments for the `studio(...)` filter. `bg` and
|
|
34
|
+
* `shadow` are product arguments only: the server rejects
|
|
35
|
+
* them under `scene`, so the builder throws for them there.
|
|
36
|
+
*/
|
|
37
|
+
export interface StudioOptions {
|
|
38
|
+
/**
|
|
39
|
+
* The product backdrop: `"white"`, `"brand"` (the
|
|
40
|
+
* operator brand color, white when none is configured),
|
|
41
|
+
* `"none"` (the subject keeps its transparency and no
|
|
42
|
+
* shadow is synthesized), or a RRGGBB hex color. Unset
|
|
43
|
+
* means the unnamed default: the brand color when one
|
|
44
|
+
* is configured, else white. Naming `"white"` is not
|
|
45
|
+
* the default: the two can resolve differently, so they
|
|
46
|
+
* spell differently.
|
|
47
|
+
*/
|
|
48
|
+
bg?: string;
|
|
49
|
+
/** Contact shadow strength; the default is `"soft"`. */
|
|
50
|
+
shadow?: StudioShadow;
|
|
51
|
+
/**
|
|
52
|
+
* Pad margin in percent, 0..40; the default is 10.
|
|
53
|
+
* Under `scene` it is the margin the reframed subject
|
|
54
|
+
* keeps.
|
|
55
|
+
*/
|
|
56
|
+
pad?: number;
|
|
57
|
+
}
|
|
26
58
|
/**
|
|
27
|
-
* One side of a size: a pixel count (1..
|
|
28
|
-
* 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
|
|
29
61
|
* `"orig"` for the source's own dimension.
|
|
30
62
|
*/
|
|
31
63
|
export type Dimension = number | "orig";
|
|
@@ -41,10 +73,27 @@ export declare const ops: {
|
|
|
41
73
|
fitIn(width: Dimension, height: Dimension, adaptive?: boolean): string;
|
|
42
74
|
/** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
|
|
43
75
|
crop(width: number, height: number, align?: CropAlign): string;
|
|
76
|
+
/**
|
|
77
|
+
* `crop:300x200:objects(person,car):1.5`; crops to the
|
|
78
|
+
* union of every detection of the named classes, the
|
|
79
|
+
* union box scaled about its center by `scale` (1 is the
|
|
80
|
+
* tight box; the crop stays centered on the union).
|
|
81
|
+
* Needs a detection model configured on the server; when
|
|
82
|
+
* none of the classes is detected the render falls back
|
|
83
|
+
* to the plain center crop of the same size. Duplicate
|
|
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`.
|
|
89
|
+
*/
|
|
90
|
+
cropObjects(width: number, height: number, classes: string[], scale?: number): string;
|
|
44
91
|
/** `crop-rect:10x20:110x220` (left x top : right x bottom). */
|
|
45
92
|
cropRect(left: number, top: number, right: number, bottom: number): string;
|
|
46
93
|
/** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
|
|
47
94
|
focal(left: number, top: number, right: number, bottom: number): string;
|
|
95
|
+
/** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
|
|
96
|
+
focalPoint(x: number, y: number, zoom?: number): string;
|
|
48
97
|
/** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
|
|
49
98
|
pad(width: number, height: number, fill?: "blur" | string): string;
|
|
50
99
|
/** `preset:thumb`; expands server-side. */
|
|
@@ -77,12 +126,13 @@ export declare const filter: {
|
|
|
77
126
|
invert(): string;
|
|
78
127
|
noUpscale(): string;
|
|
79
128
|
equalize(): string;
|
|
129
|
+
enhance(): string;
|
|
80
130
|
removeBg(): string;
|
|
81
131
|
keepProfile(): string;
|
|
82
132
|
sepia(): string;
|
|
83
133
|
blurFaces(): string;
|
|
84
134
|
pixelateFaces(): string;
|
|
85
|
-
/** Gaussian blur by sigma
|
|
135
|
+
/** Gaussian blur by sigma: positive, at most the server's 512 cap. */
|
|
86
136
|
blur(sigma: number): string;
|
|
87
137
|
/** Unsharp-mask strength (positive). */
|
|
88
138
|
sharpen(amount: number): string;
|
|
@@ -90,6 +140,14 @@ export declare const filter: {
|
|
|
90
140
|
brighten(amount: number): string;
|
|
91
141
|
/** Percent contrast: -100..100 (0 unchanged, -100 flat). */
|
|
92
142
|
contrast(percent: number): string;
|
|
143
|
+
/** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
|
|
144
|
+
gamma(value: number): string;
|
|
145
|
+
/** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
|
|
146
|
+
exposure(stops: number): string;
|
|
147
|
+
/** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
|
|
148
|
+
highlightsShadows(highlights: number, shadows: number): string;
|
|
149
|
+
/** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
|
|
150
|
+
vibrance(percent: number): string;
|
|
93
151
|
/** Rotate the hue by integer degrees. */
|
|
94
152
|
hueRotate(degrees: number): string;
|
|
95
153
|
/** Saturation factor: 0..255 (0 grayscale, 1 identity). */
|
|
@@ -131,13 +189,46 @@ export declare const filter: {
|
|
|
131
189
|
rotate(angle: number): string;
|
|
132
190
|
/** Trim uniform borders; tolerance 0..255, default 10. */
|
|
133
191
|
trim(tolerance?: number): string;
|
|
192
|
+
/** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
|
|
193
|
+
trimSides(tolerance: number, left: number, top: number, right: number, bottom: number): string;
|
|
134
194
|
/** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
|
|
135
195
|
quality(value: number | "auto"): string;
|
|
136
|
-
|
|
196
|
+
/**
|
|
197
|
+
* Per-format quality in one URL: a map of format to value
|
|
198
|
+
* (1..100 or "auto"), plus an optional fallback for
|
|
199
|
+
* formats with no entry. Resolved by the server after
|
|
200
|
+
* format negotiation; entries spell in canonical
|
|
201
|
+
* (format-name) order with the fallback first.
|
|
202
|
+
*/
|
|
203
|
+
qualityPerFormat(entries: Partial<Record<PerFormatQualityFormat, number | "auto">>, fallback?: number | "auto"): string;
|
|
204
|
+
/** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
|
|
205
|
+
palette(colors: number): string;
|
|
206
|
+
/**
|
|
207
|
+
* Output format, with its encoder options (issue #319):
|
|
208
|
+
* `progressive` and `subsampling` (444, 422, or 420) for
|
|
209
|
+
* JPEG, `interlace` for PNG, `method` (0..6) and `sns`
|
|
210
|
+
* (smart subsampling, 0..100) for WebP. An option its
|
|
211
|
+
* format cannot honour throws here, like the server's 400.
|
|
212
|
+
*/
|
|
213
|
+
format(format: ImageFormat, options?: FormatOptions): string;
|
|
137
214
|
/** The background color other operations pad with (RRGGBB). */
|
|
138
215
|
fill(color: string): string;
|
|
139
216
|
/** How much a face crop expands around the face: 0..3. */
|
|
140
217
|
facePad(amount: number): string;
|
|
218
|
+
/**
|
|
219
|
+
* Studio mode: `studio(product)` composites the subject
|
|
220
|
+
* the server's segmentation model finds onto a backdrop
|
|
221
|
+
* with a synthesized contact shadow, scaled and centered
|
|
222
|
+
* to the pad margin; `studio(scene)` keeps the
|
|
223
|
+
* photograph's scene, reframing it on the detected
|
|
224
|
+
* subject and correcting light and color. See
|
|
225
|
+
* {@link StudioOptions} for the named arguments.
|
|
226
|
+
* Arguments spelled at their defaults (shadow `soft`,
|
|
227
|
+
* pad 10) are omitted, matching the server's canonical
|
|
228
|
+
* spelling, so `studio("product", { pad: 10 })` and
|
|
229
|
+
* `studio("product")` are the same string.
|
|
230
|
+
*/
|
|
231
|
+
studio(mode: StudioMode, options?: StudioOptions): string;
|
|
141
232
|
/** AI upscale by the given factor. */
|
|
142
233
|
upscale(factor: 2 | 4): string;
|
|
143
234
|
/** Device pixel ratio the sizes are multiplied by. */
|
|
@@ -146,12 +237,12 @@ export declare const filter: {
|
|
|
146
237
|
maxBytes(bytes: number): string;
|
|
147
238
|
/** Round the corners: one radius for all, or [tl, tr, br, bl]. */
|
|
148
239
|
radius(value: number | [number, number, number, number]): string;
|
|
149
|
-
/** Paint an opaque border inside the frame (RRGGBB). */
|
|
240
|
+
/** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
|
|
150
241
|
border(width: number, color: string): string;
|
|
151
242
|
mask(shape: MaskShape): string;
|
|
152
243
|
duotone(shadow: string, highlight: string): string;
|
|
153
244
|
monochrome(color: string): string;
|
|
154
|
-
/** Mosaic block size in pixels: 1..
|
|
245
|
+
/** Mosaic block size in pixels: 1..{@link MAX_DIMENSION}. */
|
|
155
246
|
pixelate(blockSize: number): string;
|
|
156
247
|
flip(axis: "h" | "v"): string;
|
|
157
248
|
/** Overlay a watermark image at (x, y), opacity 0..100. */
|
|
@@ -171,8 +262,12 @@ export declare const filter: {
|
|
|
171
262
|
blurClass(name: string): string;
|
|
172
263
|
/** Pixelate every detected object of the named class. */
|
|
173
264
|
pixelateClass(name: string): string;
|
|
265
|
+
/** Recolor every detected object of the named class to the given RRGGBB color. */
|
|
266
|
+
recolorClass(name: string, color: string): string;
|
|
174
267
|
/** Blur the rectangle (x, y, w, h) in pixels. */
|
|
175
268
|
blurRegion(x: number, y: number, w: number, h: number): string;
|
|
176
269
|
/** Pixelate the rectangle (x, y, w, h) in pixels. */
|
|
177
270
|
pixelateRegion(x: number, y: number, w: number, h: number): string;
|
|
271
|
+
/** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
|
|
272
|
+
removeRegion(x: number, y: number, w: number, h: number): string;
|
|
178
273
|
};
|