@crabcrop/url 0.9.11 → 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 +35 -7
- package/dist/bytes.d.ts +21 -0
- package/dist/bytes.js +86 -0
- package/dist/crypto/aes-gcm.d.ts +21 -0
- package/dist/crypto/aes-gcm.js +248 -0
- package/dist/crypto/node.d.ts +11 -0
- package/dist/crypto/node.js +41 -0
- package/dist/crypto/portable.d.ts +14 -0
- package/dist/crypto/portable.js +60 -0
- package/dist/crypto/sha256.d.ts +14 -0
- package/dist/crypto/sha256.js +131 -0
- package/dist/explain.d.ts +55 -7
- package/dist/explain.js +116 -65
- package/dist/index.d.ts +2 -1
- package/dist/index.js +60 -50
- package/dist/limits.d.ts +9 -0
- package/dist/limits.js +9 -0
- package/dist/operations.d.ts +8 -20
- package/dist/operations.js +133 -71
- package/package.json +11 -3
package/dist/index.js
CHANGED
|
@@ -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 { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEq
|
|
|
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,8 +35,7 @@ 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
41
|
* The purge-group signature for a cache group: HMAC-SHA256
|
|
@@ -37,8 +49,7 @@ export function purgeSignature(secret, target) {
|
|
|
37
49
|
* `POST /purge-group/<signature>/<group>`.
|
|
38
50
|
*/
|
|
39
51
|
export function purgeGroupSignature(secret, group) {
|
|
40
|
-
|
|
41
|
-
return createHmac("sha256", subkey).update(group, "utf8").digest("hex");
|
|
52
|
+
return toHex(hmacSha256(subkey(secret, "crabcrop/purge-group-key"), group));
|
|
42
53
|
}
|
|
43
54
|
/**
|
|
44
55
|
* The upload signature for an object name: HMAC-SHA256 of
|
|
@@ -58,9 +69,8 @@ export function purgeGroupSignature(secret, group) {
|
|
|
58
69
|
* a token replays until the secret rotates.
|
|
59
70
|
*/
|
|
60
71
|
export function uploadSignature(secret, name, expires) {
|
|
61
|
-
const subkey = Buffer.from(sign(secret, "crabcrop/upload-key"), "hex");
|
|
62
72
|
const signed = expires === undefined ? name : `exp:${expires}/${name}`;
|
|
63
|
-
return
|
|
73
|
+
return toHex(hmacSha256(subkey(secret, "crabcrop/upload-key"), signed));
|
|
64
74
|
}
|
|
65
75
|
/** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
|
|
66
76
|
export function isValidKeyId(id) {
|
|
@@ -84,7 +94,7 @@ export function signWithKeyId(secret, keyId, remainder) {
|
|
|
84
94
|
*/
|
|
85
95
|
export const MAX_SEALED_REMAINDER = 2048;
|
|
86
96
|
/** The AAD every sealed token is bound to. */
|
|
87
|
-
const SEAL_AAD =
|
|
97
|
+
const SEAL_AAD = utf8("crabcrop/sealed/1");
|
|
88
98
|
/**
|
|
89
99
|
* The seal subkey: the raw bytes of the HMAC-SHA256 of the
|
|
90
100
|
* label `crabcrop/seal-key` under the secret, its own domain
|
|
@@ -94,7 +104,7 @@ const SEAL_AAD = Buffer.from("crabcrop/sealed/1", "utf8");
|
|
|
94
104
|
* signatures is the rotation window for tokens.
|
|
95
105
|
*/
|
|
96
106
|
function sealKey(secret) {
|
|
97
|
-
return
|
|
107
|
+
return subkey(secret, "crabcrop/seal-key");
|
|
98
108
|
}
|
|
99
109
|
/**
|
|
100
110
|
* Seal a remainder into a token segment with a
|
|
@@ -113,14 +123,15 @@ export function sealWithNonce(secret, remainder, nonce, keyId) {
|
|
|
113
123
|
if (nonce.length !== 12) {
|
|
114
124
|
throw new Error(`sealed token nonce must be 12 bytes, got ${nonce.length}`);
|
|
115
125
|
}
|
|
116
|
-
|
|
126
|
+
const plaintext = utf8(remainder);
|
|
127
|
+
if (plaintext.length > MAX_SEALED_REMAINDER) {
|
|
117
128
|
throw new Error(`remainder is over the ${MAX_SEALED_REMAINDER}-byte sealing cap: a recipe that long belongs in a preset`);
|
|
118
129
|
}
|
|
119
|
-
const
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
const token = `s1.${body
|
|
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)}`;
|
|
124
135
|
if (keyId === undefined) {
|
|
125
136
|
return token;
|
|
126
137
|
}
|
|
@@ -163,29 +174,17 @@ export function unseal(secret, segment) {
|
|
|
163
174
|
throw openFailed();
|
|
164
175
|
}
|
|
165
176
|
const body = token.slice(3);
|
|
166
|
-
//
|
|
167
|
-
//
|
|
168
|
-
//
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
if (raw.length < 12 + 16 || raw.toString("base64url") !== body) {
|
|
172
|
-
throw openFailed();
|
|
173
|
-
}
|
|
174
|
-
const decipher = createDecipheriv("aes-256-gcm", sealKey(secret), raw.subarray(0, 12));
|
|
175
|
-
decipher.setAAD(SEAL_AAD);
|
|
176
|
-
decipher.setAuthTag(raw.subarray(raw.length - 16));
|
|
177
|
-
let plain;
|
|
178
|
-
try {
|
|
179
|
-
plain = Buffer.concat([
|
|
180
|
-
decipher.update(raw.subarray(12, raw.length - 16)),
|
|
181
|
-
decipher.final(),
|
|
182
|
-
]);
|
|
183
|
-
}
|
|
184
|
-
catch {
|
|
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) {
|
|
185
182
|
throw openFailed();
|
|
186
183
|
}
|
|
187
|
-
const
|
|
188
|
-
|
|
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) {
|
|
189
188
|
throw openFailed();
|
|
190
189
|
}
|
|
191
190
|
return text;
|
|
@@ -221,18 +220,31 @@ export function buildSealedURL(base, secret, operations, source, options = {}) {
|
|
|
221
220
|
const segment = seal(secret, remainder, options.keyId);
|
|
222
221
|
return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
|
|
223
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 = "\"<>\\^`{|}";
|
|
224
231
|
/**
|
|
225
232
|
* Fail loudly on inputs that can never produce a verifiable URL
|
|
226
233
|
* (audit P-4, P-5): the remainder travels as a raw URL path, so
|
|
227
|
-
* `?`/`#` would truncate it
|
|
228
|
-
*
|
|
229
|
-
*
|
|
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.
|
|
230
238
|
*/
|
|
231
239
|
function assertUrlText(text, what) {
|
|
232
240
|
for (const c of text) {
|
|
233
241
|
const code = c.codePointAt(0);
|
|
234
|
-
|
|
235
|
-
|
|
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}`);
|
|
236
248
|
}
|
|
237
249
|
}
|
|
238
250
|
}
|
|
@@ -249,8 +261,8 @@ function assertExpires(expires) {
|
|
|
249
261
|
* flip), so it throws here, at build time.
|
|
250
262
|
*/
|
|
251
263
|
function assertWidth(width) {
|
|
252
|
-
if (!Number.isSafeInteger(width) || width < 1 || width >
|
|
253
|
-
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}`);
|
|
254
266
|
}
|
|
255
267
|
}
|
|
256
268
|
/**
|
|
@@ -305,6 +317,7 @@ export function buildSrcSet(base, secret, source, widths, options = {}) {
|
|
|
305
317
|
}
|
|
306
318
|
export { explainUrl } from "./explain.js";
|
|
307
319
|
export { FILTER_DESCRIPTIONS } from "./explain.js";
|
|
320
|
+
export { MAX_DIMENSION } from "./limits.js";
|
|
308
321
|
export { filter, joinOps, ops } from "./operations.js";
|
|
309
322
|
import { explainUrl } from "./explain.js";
|
|
310
323
|
/**
|
|
@@ -325,11 +338,8 @@ export function verifyUrlSignature(secret, input) {
|
|
|
325
338
|
}
|
|
326
339
|
// Constant-time, like the Rust and Python verifiers: a
|
|
327
340
|
// plain === leaks how much of the tag was right.
|
|
328
|
-
const given =
|
|
329
|
-
const matches = (candidate) =>
|
|
330
|
-
const expected = Buffer.from(sign(candidate, remainder), "utf8");
|
|
331
|
-
return expected.length === given.length && timingSafeEqual(expected, given);
|
|
332
|
-
};
|
|
341
|
+
const given = utf8(signature.value);
|
|
342
|
+
const matches = (candidate) => timingSafeEqual(utf8(sign(candidate, remainder)), given);
|
|
333
343
|
if (typeof secret === "string") {
|
|
334
344
|
return matches(secret);
|
|
335
345
|
}
|
package/dist/limits.d.ts
ADDED
|
@@ -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;
|
package/dist/limits.js
ADDED
|
@@ -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;
|
package/dist/operations.d.ts
CHANGED
|
@@ -1,16 +1,3 @@
|
|
|
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";
|
|
16
3
|
/** Formats a per-format quality entry can name (the video formats take no quality). */
|
|
@@ -69,8 +56,8 @@ export interface StudioOptions {
|
|
|
69
56
|
pad?: number;
|
|
70
57
|
}
|
|
71
58
|
/**
|
|
72
|
-
* One side of a size: a pixel count (1..
|
|
73
|
-
* 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
|
|
74
61
|
* `"orig"` for the source's own dimension.
|
|
75
62
|
*/
|
|
76
63
|
export type Dimension = number | "orig";
|
|
@@ -94,10 +81,11 @@ export declare const ops: {
|
|
|
94
81
|
* Needs a detection model configured on the server; when
|
|
95
82
|
* none of the classes is detected the render falls back
|
|
96
83
|
* to the plain center crop of the same size. Duplicate
|
|
97
|
-
* classes (case-insensitive
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
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`.
|
|
101
89
|
*/
|
|
102
90
|
cropObjects(width: number, height: number, classes: string[], scale?: number): string;
|
|
103
91
|
/** `crop-rect:10x20:110x220` (left x top : right x bottom). */
|
|
@@ -254,7 +242,7 @@ export declare const filter: {
|
|
|
254
242
|
mask(shape: MaskShape): string;
|
|
255
243
|
duotone(shadow: string, highlight: string): string;
|
|
256
244
|
monochrome(color: string): string;
|
|
257
|
-
/** Mosaic block size in pixels: 1..
|
|
245
|
+
/** Mosaic block size in pixels: 1..{@link MAX_DIMENSION}. */
|
|
258
246
|
pixelate(blockSize: number): string;
|
|
259
247
|
flip(axis: "h" | "v"): string;
|
|
260
248
|
/** Overlay a watermark image at (x, y), opacity 0..100. */
|