@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.
@@ -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: a purge
20
- * signature over the literal string `purge-group/<group>`,
21
- * which appears nowhere in the request URL. The helper
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. 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 { createHmac, 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 { createHmac, timingSafeEqual } from "node:crypto";
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,19 +35,21 @@ 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
- * The purge-group signature for a cache group: a purge
30
- * signature over the literal string `purge-group/<group>`,
31
- * which appears nowhere in the request URL. The helper
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 purgeSignature(secret, `purge-group/${group}`);
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 subkey = Buffer.from(sign(secret, "crabcrop/upload-key"), "hex");
49
- return createHmac("sha256", subkey).update(name, "utf8").digest("hex");
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 and whitespace, control, and
69
- * non-ASCII characters cannot be sent as-is; an expiry must be
70
- * 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.
71
238
  */
72
239
  function assertUrlText(text, what) {
73
240
  for (const c of text) {
74
241
  const code = c.codePointAt(0);
75
- if (c === "?" || c === "#" || code <= 0x20 || code === 0x7f || code > 0x7e) {
76
- 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}`);
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 > 16383) {
94
- 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}`);
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 = Buffer.from(signature.value, "utf8");
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
- const candidate = secret[signature.keyId];
179
- return candidate === undefined ? false : matches(candidate);
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..16383), 0 for
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 (positive). */
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
- format(format: ImageFormat): string;
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..16383. */
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
  };