@crabcrop/url 0.10.1 → 0.12.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 +8 -2
- package/dist/explain.d.ts +27 -0
- package/dist/explain.js +95 -6
- package/dist/index.d.ts +32 -8
- package/dist/index.js +59 -13
- package/dist/operations.d.ts +2 -0
- package/dist/operations.js +8 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -33,11 +33,15 @@ const srcset = buildSrcSet(
|
|
|
33
33
|
[400, 800, 1200],
|
|
34
34
|
);
|
|
35
35
|
|
|
36
|
-
// The
|
|
36
|
+
// The signature for a remainder, if you assemble URLs yourself. It
|
|
37
|
+
// throws for a remainder that begins with the reserved segment
|
|
38
|
+
// "crabcrop" (isReservedRemainder), as every builder does: the derived
|
|
39
|
+
// subkeys are signatures of labels under that segment.
|
|
37
40
|
const signature = sign("your-secret", "300x200/https://example.com/photo.jpg");
|
|
38
41
|
|
|
39
42
|
// Verify a signed URL's signature locally, in constant time
|
|
40
|
-
// (unsigned or malformed URLs return null
|
|
43
|
+
// (unsigned or malformed URLs return null, and so do URLs longer
|
|
44
|
+
// than 64 KiB).
|
|
41
45
|
const ok = verifyUrlSignature("your-secret", url);
|
|
42
46
|
|
|
43
47
|
// Purge signatures for the server's /purge and /purge-group endpoints
|
|
@@ -69,6 +73,8 @@ const remainder = unseal("your-secret", seal("your-secret", "300x200/https://exa
|
|
|
69
73
|
|
|
70
74
|
Pass `null` as the secret to produce the literal `unsafe` signature segment, for servers running with `CRABCROP_ALLOW_UNSAFE` or in presets-only mode.
|
|
71
75
|
|
|
76
|
+
`explainUrl(url)` parses a URL back into its signature, its explained segments and its source, and lists every error. It reads at most 64 KiB (65,536 bytes of UTF-8), which bounds the time one call takes. A longer input gets a single error and no signature, so `verifyUrlSignature` returns null for it.
|
|
77
|
+
|
|
72
78
|
The builders throw on operations or a source that can never verify: `?`, `#`, whitespace, control and non-ASCII characters, and `"` `<` `>` `\` `^` `` ` `` `{` `|` `}`, which a browser rewrites before an `<img src>` or `fetch()` request leaves the page (`\` becomes `/`, the rest are percent-encoded). Percent-encode those in the source first (`x{y}.jpg` as `x%7By%7D.jpg`); the error names the encoding. The full rules are in [`spec/url-signing.md`](../../spec/url-signing.md#building-urls).
|
|
73
79
|
|
|
74
80
|
## Typed operations
|
package/dist/explain.d.ts
CHANGED
|
@@ -27,6 +27,16 @@ export declare const FILTER_DESCRIPTIONS: Record<string, string>;
|
|
|
27
27
|
export declare const CROP_ALIGNS: readonly ["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"];
|
|
28
28
|
/** Text overlay anchors (url.rs Anchor::parse). */
|
|
29
29
|
export declare const TEXT_ANCHORS: readonly ["top-left", "top-center", "top-right", "center-left", "center", "center-right", "bottom-left", "bottom-center", "bottom-right"];
|
|
30
|
+
/** The most characters a `text` label may hold (url.rs MAX_TEXT_GLYPHS, issue #606). */
|
|
31
|
+
export declare const MAX_TEXT_GLYPHS = 1000;
|
|
32
|
+
/** The most a `text` label's character count times its size may come to (url.rs MAX_TEXT_EXTENT). */
|
|
33
|
+
export declare const MAX_TEXT_EXTENT = 100000;
|
|
34
|
+
/**
|
|
35
|
+
* Whether a decoded `text` label at `size` is within the
|
|
36
|
+
* server's caps. Characters are Unicode code points, as the
|
|
37
|
+
* server counts them, not bytes or UTF-16 code units.
|
|
38
|
+
*/
|
|
39
|
+
export declare function textLabelFits(label: string, size: number): boolean;
|
|
30
40
|
/** Output formats `format(...)` names; `jpg` is an input alias of `jpeg`. */
|
|
31
41
|
export declare const IMAGE_FORMATS: readonly ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
|
|
32
42
|
/**
|
|
@@ -63,6 +73,19 @@ export declare function isOneOf<T extends string | number>(list: readonly T[], v
|
|
|
63
73
|
* MAX_OBJECTS_CLASSES).
|
|
64
74
|
*/
|
|
65
75
|
export declare const MAX_OBJECTS_CLASSES = 32;
|
|
76
|
+
/**
|
|
77
|
+
* Trim like the server's Rust `str::trim`: exactly the
|
|
78
|
+
* Unicode White_Space set, from both ends. JavaScript's
|
|
79
|
+
* `String.prototype.trim` disagrees on two characters:
|
|
80
|
+
* it also strips U+FEFF, which the server keeps (so a
|
|
81
|
+
* class name wrapped in it is no class name), and it
|
|
82
|
+
* keeps U+0085, which the server strips (issue #537).
|
|
83
|
+
* Every place this package mirrors a server-side trim
|
|
84
|
+
* uses this instead of the built-in. It walks in from
|
|
85
|
+
* each end, so it takes time linear in the input, however
|
|
86
|
+
* long a run of white space is.
|
|
87
|
+
*/
|
|
88
|
+
export declare function trimLikeServer(text: string): string;
|
|
66
89
|
/**
|
|
67
90
|
* A detection class name as the server's parse_class_name
|
|
68
91
|
* takes it, already trimmed: 1 to 64 UTF-8 bytes (bytes, not
|
|
@@ -86,5 +109,9 @@ export declare function classFoldKey(name: string): string;
|
|
|
86
109
|
*
|
|
87
110
|
* Returns { signature, segments, source, remainder, errors }
|
|
88
111
|
* where segments carry { raw, kind, title, detail?, error? }.
|
|
112
|
+
*
|
|
113
|
+
* Input longer than MAX_EXPLAIN_BYTES is not read: the answer
|
|
114
|
+
* is one error and no signature, so verifyUrlSignature returns
|
|
115
|
+
* null for it.
|
|
89
116
|
*/
|
|
90
117
|
export declare function explainUrl(input: string, nowSeconds?: number): Explanation;
|
package/dist/explain.js
CHANGED
|
@@ -128,6 +128,24 @@ export const TEXT_ANCHORS = [
|
|
|
128
128
|
"bottom-center",
|
|
129
129
|
"bottom-right",
|
|
130
130
|
];
|
|
131
|
+
/** The most characters a `text` label may hold (url.rs MAX_TEXT_GLYPHS, issue #606). */
|
|
132
|
+
export const MAX_TEXT_GLYPHS = 1000;
|
|
133
|
+
/** The most a `text` label's character count times its size may come to (url.rs MAX_TEXT_EXTENT). */
|
|
134
|
+
export const MAX_TEXT_EXTENT = 100000;
|
|
135
|
+
/**
|
|
136
|
+
* Whether a decoded `text` label at `size` is within the
|
|
137
|
+
* server's caps. Characters are Unicode code points, as the
|
|
138
|
+
* server counts them, not bytes or UTF-16 code units.
|
|
139
|
+
*/
|
|
140
|
+
export function textLabelFits(label, size) {
|
|
141
|
+
let glyphs = 0;
|
|
142
|
+
for (const _ of label) {
|
|
143
|
+
glyphs += 1;
|
|
144
|
+
if (glyphs > MAX_TEXT_GLYPHS)
|
|
145
|
+
return false;
|
|
146
|
+
}
|
|
147
|
+
return glyphs * size <= MAX_TEXT_EXTENT;
|
|
148
|
+
}
|
|
131
149
|
/** Output formats `format(...)` names; `jpg` is an input alias of `jpeg`. */
|
|
132
150
|
export const IMAGE_FORMATS = ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
|
|
133
151
|
/**
|
|
@@ -166,6 +184,46 @@ export function isOneOf(list, value) {
|
|
|
166
184
|
* MAX_OBJECTS_CLASSES).
|
|
167
185
|
*/
|
|
168
186
|
export const MAX_OBJECTS_CLASSES = 32;
|
|
187
|
+
/**
|
|
188
|
+
* Whether a UTF-16 code unit is in the Unicode White_Space
|
|
189
|
+
* set, the set Rust's `str::trim` strips. Every member is in
|
|
190
|
+
* the Basic Multilingual Plane, so one code unit is one
|
|
191
|
+
* character here, and a surrogate is never white space.
|
|
192
|
+
*/
|
|
193
|
+
function isServerWhiteSpace(unit) {
|
|
194
|
+
return ((unit >= 0x0009 && unit <= 0x000d) ||
|
|
195
|
+
unit === 0x0020 ||
|
|
196
|
+
unit === 0x0085 ||
|
|
197
|
+
unit === 0x00a0 ||
|
|
198
|
+
unit === 0x1680 ||
|
|
199
|
+
(unit >= 0x2000 && unit <= 0x200a) ||
|
|
200
|
+
unit === 0x2028 ||
|
|
201
|
+
unit === 0x2029 ||
|
|
202
|
+
unit === 0x202f ||
|
|
203
|
+
unit === 0x205f ||
|
|
204
|
+
unit === 0x3000);
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* Trim like the server's Rust `str::trim`: exactly the
|
|
208
|
+
* Unicode White_Space set, from both ends. JavaScript's
|
|
209
|
+
* `String.prototype.trim` disagrees on two characters:
|
|
210
|
+
* it also strips U+FEFF, which the server keeps (so a
|
|
211
|
+
* class name wrapped in it is no class name), and it
|
|
212
|
+
* keeps U+0085, which the server strips (issue #537).
|
|
213
|
+
* Every place this package mirrors a server-side trim
|
|
214
|
+
* uses this instead of the built-in. It walks in from
|
|
215
|
+
* each end, so it takes time linear in the input, however
|
|
216
|
+
* long a run of white space is.
|
|
217
|
+
*/
|
|
218
|
+
export function trimLikeServer(text) {
|
|
219
|
+
let start = 0;
|
|
220
|
+
let end = text.length;
|
|
221
|
+
while (start < end && isServerWhiteSpace(text.charCodeAt(start)))
|
|
222
|
+
start++;
|
|
223
|
+
while (end > start && isServerWhiteSpace(text.charCodeAt(end - 1)))
|
|
224
|
+
end--;
|
|
225
|
+
return text.slice(start, end);
|
|
226
|
+
}
|
|
169
227
|
/**
|
|
170
228
|
* A detection class name as the server's parse_class_name
|
|
171
229
|
* takes it, already trimmed: 1 to 64 UTF-8 bytes (bytes, not
|
|
@@ -206,7 +264,12 @@ function isIntIn(s, min, max) {
|
|
|
206
264
|
// unsigned parsers accept '+' too), then digits.
|
|
207
265
|
return /^[+-]?\d+$/.test(s) && BigInt(s) >= BigInt(min) && BigInt(s) <= BigInt(max);
|
|
208
266
|
}
|
|
209
|
-
|
|
267
|
+
// The fraction digits can only follow a literal dot, so a run
|
|
268
|
+
// of digits has one way to match and a long run costs linear
|
|
269
|
+
// time. The older `\d+\.?\d*` could split one run at any point
|
|
270
|
+
// and took quadratic time when the match failed (issue #594).
|
|
271
|
+
// Both accept the same strings.
|
|
272
|
+
const RUST_FLOAT = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
|
|
210
273
|
function isFloat(s) {
|
|
211
274
|
// Rust's f32::from_str syntax (AP-23): plain decimal with
|
|
212
275
|
// an optional exponent; no hex, no surrounding whitespace,
|
|
@@ -535,7 +598,7 @@ function validateFilter(name, args) {
|
|
|
535
598
|
if (args === null)
|
|
536
599
|
return bad;
|
|
537
600
|
const decoded = percentDecodable(args);
|
|
538
|
-
return decoded !== null && isClassName(decoded
|
|
601
|
+
return decoded !== null && isClassName(trimLikeServer(decoded)) ? null : bad;
|
|
539
602
|
}
|
|
540
603
|
case "recolorclass": {
|
|
541
604
|
if (args === null)
|
|
@@ -546,7 +609,7 @@ function validateFilter(name, args) {
|
|
|
546
609
|
if (!/^[0-9a-fA-F]{6}$/.test(args.slice(cut + 1)))
|
|
547
610
|
return bad;
|
|
548
611
|
const decoded = percentDecodable(args.slice(0, cut));
|
|
549
|
-
return decoded !== null && isClassName(decoded
|
|
612
|
+
return decoded !== null && isClassName(trimLikeServer(decoded)) ? null : bad;
|
|
550
613
|
}
|
|
551
614
|
case "blur_region":
|
|
552
615
|
case "pixelate_region":
|
|
@@ -582,7 +645,8 @@ function validateFilter(name, args) {
|
|
|
582
645
|
/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(color) &&
|
|
583
646
|
isIntIn(size, 1, 1000) &&
|
|
584
647
|
text !== null &&
|
|
585
|
-
text !== ""
|
|
648
|
+
text !== "" &&
|
|
649
|
+
textLabelFits(text, Number(size))
|
|
586
650
|
? null
|
|
587
651
|
: bad;
|
|
588
652
|
}
|
|
@@ -692,7 +756,7 @@ function parseObjectsAlign(align) {
|
|
|
692
756
|
const decoded = percentDecodable(part);
|
|
693
757
|
if (decoded === null)
|
|
694
758
|
return null;
|
|
695
|
-
const name = decoded
|
|
759
|
+
const name = trimLikeServer(decoded);
|
|
696
760
|
if (!isClassName(name))
|
|
697
761
|
return null;
|
|
698
762
|
const key = classFoldKey(name);
|
|
@@ -971,6 +1035,18 @@ function isSizeShaped(seg) {
|
|
|
971
1035
|
};
|
|
972
1036
|
return spelling(left) || spelling(right);
|
|
973
1037
|
}
|
|
1038
|
+
/**
|
|
1039
|
+
* The most input explainUrl reads, in UTF-8 bytes: 64 KiB. It
|
|
1040
|
+
* bounds the work one call does, and it sits above the URL
|
|
1041
|
+
* limits of common CDNs and proxies.
|
|
1042
|
+
*/
|
|
1043
|
+
const MAX_EXPLAIN_BYTES = 64 * 1024;
|
|
1044
|
+
function utf8Length(text) {
|
|
1045
|
+
// UTF-8 never takes fewer bytes than UTF-16 code units, so
|
|
1046
|
+
// the caller checks .length first and this only runs on
|
|
1047
|
+
// input of at most MAX_EXPLAIN_BYTES code units.
|
|
1048
|
+
return new TextEncoder().encode(text).length;
|
|
1049
|
+
}
|
|
974
1050
|
/**
|
|
975
1051
|
* Parse a crabcrop URL (or bare path) back into its pieces,
|
|
976
1052
|
* explaining each segment. Mirrors the server's dispatch:
|
|
@@ -979,14 +1055,27 @@ function isSizeShaped(seg) {
|
|
|
979
1055
|
*
|
|
980
1056
|
* Returns { signature, segments, source, remainder, errors }
|
|
981
1057
|
* where segments carry { raw, kind, title, detail?, error? }.
|
|
1058
|
+
*
|
|
1059
|
+
* Input longer than MAX_EXPLAIN_BYTES is not read: the answer
|
|
1060
|
+
* is one error and no signature, so verifyUrlSignature returns
|
|
1061
|
+
* null for it.
|
|
982
1062
|
*/
|
|
983
1063
|
export function explainUrl(input, nowSeconds = Math.floor(Date.now() / 1000)) {
|
|
1064
|
+
if (input.length > MAX_EXPLAIN_BYTES || utf8Length(input) > MAX_EXPLAIN_BYTES) {
|
|
1065
|
+
return {
|
|
1066
|
+
signature: null,
|
|
1067
|
+
segments: [],
|
|
1068
|
+
source: "",
|
|
1069
|
+
remainder: "",
|
|
1070
|
+
errors: [`the URL is longer than 64 KiB (${MAX_EXPLAIN_BYTES} bytes): the explainer does not read it`],
|
|
1071
|
+
};
|
|
1072
|
+
}
|
|
984
1073
|
// Extract the path by string surgery, never via the URL
|
|
985
1074
|
// parser: WHATWG parsing resolves dot segments (.. and
|
|
986
1075
|
// %2e%2e) that the server treats as literal path bytes
|
|
987
1076
|
// (audit P-3). A query or fragment is not part of the
|
|
988
1077
|
// signed path, on either side.
|
|
989
|
-
let path = input
|
|
1078
|
+
let path = trimLikeServer(input);
|
|
990
1079
|
const scheme = path.indexOf("://");
|
|
991
1080
|
if (scheme > 0 && /^[a-zA-Z][a-zA-Z0-9+.-]*$/.test(path.slice(0, scheme))) {
|
|
992
1081
|
const afterAuthority = path.slice(scheme + 3);
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The first remainder segment reserved for key derivation.
|
|
3
|
+
* Every derived subkey (purge, purge-group, upload, seal, and
|
|
4
|
+
* the server's cache entry key) is the HMAC of a label such as
|
|
5
|
+
* `crabcrop/purge-key` under the secret, which is the image
|
|
6
|
+
* signature of that label. No image URL may begin with this
|
|
7
|
+
* segment (the server refuses one with `400 reserved_segment`),
|
|
8
|
+
* and {@link sign} and every builder refuse a remainder that
|
|
9
|
+
* does, so no image signature is ever a subkey.
|
|
10
|
+
*/
|
|
11
|
+
export declare const RESERVED_SEGMENT = "crabcrop";
|
|
12
|
+
/**
|
|
13
|
+
* Whether `remainder` begins with {@link RESERVED_SEGMENT}: it
|
|
14
|
+
* is that segment alone or starts with `crabcrop/`. The test is
|
|
15
|
+
* on the text as written, as the HMAC is: `exp:1/crabcrop/x`
|
|
16
|
+
* and `CRABCROP/x` are not reserved.
|
|
17
|
+
*/
|
|
18
|
+
export declare function isReservedRemainder(remainder: string): boolean;
|
|
1
19
|
/**
|
|
2
20
|
* Compute the signature segment for a remainder: the lowercase
|
|
3
21
|
* hex HMAC-SHA256 of `remainder` under `secret`. The remainder
|
|
4
22
|
* is everything after the signature segment in the URL,
|
|
5
|
-
* exactly as it will appear.
|
|
23
|
+
* exactly as it will appear. A remainder that begins with
|
|
24
|
+
* {@link RESERVED_SEGMENT} throws: its signature could be a
|
|
25
|
+
* derived subkey.
|
|
6
26
|
*/
|
|
7
27
|
export declare function sign(secret: string, remainder: string): string;
|
|
8
28
|
/**
|
|
@@ -10,9 +30,10 @@ export declare function sign(secret: string, remainder: string): string;
|
|
|
10
30
|
* remainder without its signature): HMAC-SHA256 of the
|
|
11
31
|
* path under a subkey derived from the secret (the raw
|
|
12
32
|
* HMAC of the secret over the label `crabcrop/purge-key`),
|
|
13
|
-
* so an image signature
|
|
14
|
-
* signature
|
|
15
|
-
*
|
|
33
|
+
* so an image signature does not verify as a purge
|
|
34
|
+
* signature: no signer signs a label (see
|
|
35
|
+
* {@link RESERVED_SEGMENT}). This is the signature segment
|
|
36
|
+
* for `POST /purge/<signature>/<path>`.
|
|
16
37
|
*/
|
|
17
38
|
export declare function purgeSignature(secret: string, target: string): string;
|
|
18
39
|
/**
|
|
@@ -31,9 +52,11 @@ export declare function purgeGroupSignature(secret: string, group: string): stri
|
|
|
31
52
|
* The upload signature for an object name: HMAC-SHA256 of
|
|
32
53
|
* the name under a subkey derived from the secret (the raw
|
|
33
54
|
* HMAC of the secret over the label `crabcrop/upload-key`),
|
|
34
|
-
* so neither an image signature nor a purge signature
|
|
35
|
-
*
|
|
36
|
-
*
|
|
55
|
+
* so neither an image signature nor a purge signature
|
|
56
|
+
* verifies as an upload signature: a purge signature is
|
|
57
|
+
* under another subkey, and no signer signs a label (see
|
|
58
|
+
* {@link RESERVED_SEGMENT}). This is the signature segment
|
|
59
|
+
* for `PUT /upload/<signature>/<name>`.
|
|
37
60
|
*
|
|
38
61
|
* With `expires` (unix seconds), the signature covers
|
|
39
62
|
* `exp:<expires>/<name>` instead, and the request path is
|
|
@@ -150,7 +173,8 @@ export { filter, joinOps, ops } from "./operations.ts";
|
|
|
150
173
|
export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, FormatOptions, ImageFormat, MaskShape, PerFormatQualityFormat, StudioMode, StudioOptions, StudioShadow, } from "./operations.ts";
|
|
151
174
|
/**
|
|
152
175
|
* Verify a URL's signature locally. Returns true or false, or
|
|
153
|
-
* null when the URL is unsigned or malformed
|
|
176
|
+
* null when the URL is unsigned or malformed, or longer than
|
|
177
|
+
* the 64 KiB the explainer reads.
|
|
154
178
|
*
|
|
155
179
|
* With a single secret string, the key ID (when the URL
|
|
156
180
|
* carries one) is ignored: the question is whether this
|
package/dist/index.js
CHANGED
|
@@ -8,19 +8,48 @@
|
|
|
8
8
|
import { aes256GcmOpen, aes256GcmSeal, hmacSha256, randomBytes, timingSafeEqual, } from "#crypto";
|
|
9
9
|
import { fromBase64Url, toBase64Url, toHex, utf8, utf8Strict } from "./bytes.js";
|
|
10
10
|
import { MAX_DIMENSION } from "./limits.js";
|
|
11
|
+
/**
|
|
12
|
+
* The first remainder segment reserved for key derivation.
|
|
13
|
+
* Every derived subkey (purge, purge-group, upload, seal, and
|
|
14
|
+
* the server's cache entry key) is the HMAC of a label such as
|
|
15
|
+
* `crabcrop/purge-key` under the secret, which is the image
|
|
16
|
+
* signature of that label. No image URL may begin with this
|
|
17
|
+
* segment (the server refuses one with `400 reserved_segment`),
|
|
18
|
+
* and {@link sign} and every builder refuse a remainder that
|
|
19
|
+
* does, so no image signature is ever a subkey.
|
|
20
|
+
*/
|
|
21
|
+
export const RESERVED_SEGMENT = "crabcrop";
|
|
22
|
+
/**
|
|
23
|
+
* Whether `remainder` begins with {@link RESERVED_SEGMENT}: it
|
|
24
|
+
* is that segment alone or starts with `crabcrop/`. The test is
|
|
25
|
+
* on the text as written, as the HMAC is: `exp:1/crabcrop/x`
|
|
26
|
+
* and `CRABCROP/x` are not reserved.
|
|
27
|
+
*/
|
|
28
|
+
export function isReservedRemainder(remainder) {
|
|
29
|
+
return remainder === RESERVED_SEGMENT || remainder.startsWith(`${RESERVED_SEGMENT}/`);
|
|
30
|
+
}
|
|
31
|
+
function assertNotReserved(remainder) {
|
|
32
|
+
if (isReservedRemainder(remainder)) {
|
|
33
|
+
throw new Error(`remainder begins with the reserved segment "${RESERVED_SEGMENT}": it is kept for key derivation, and no image URL may begin with it`);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
11
36
|
/**
|
|
12
37
|
* Compute the signature segment for a remainder: the lowercase
|
|
13
38
|
* hex HMAC-SHA256 of `remainder` under `secret`. The remainder
|
|
14
39
|
* is everything after the signature segment in the URL,
|
|
15
|
-
* exactly as it will appear.
|
|
40
|
+
* exactly as it will appear. A remainder that begins with
|
|
41
|
+
* {@link RESERVED_SEGMENT} throws: its signature could be a
|
|
42
|
+
* derived subkey.
|
|
16
43
|
*/
|
|
17
44
|
export function sign(secret, remainder) {
|
|
45
|
+
assertNotReserved(remainder);
|
|
18
46
|
return toHex(hmacSha256(secret, remainder));
|
|
19
47
|
}
|
|
20
48
|
/**
|
|
21
49
|
* A subkey derived from the secret: the raw HMAC-SHA256 of
|
|
22
|
-
* `label` under it
|
|
23
|
-
*
|
|
50
|
+
* `label` under it, one per signing domain. Every label begins
|
|
51
|
+
* with {@link RESERVED_SEGMENT}, which is why {@link sign}
|
|
52
|
+
* refuses to compute the same value as a signature.
|
|
24
53
|
*/
|
|
25
54
|
function subkey(secret, label) {
|
|
26
55
|
return hmacSha256(secret, label);
|
|
@@ -30,9 +59,10 @@ function subkey(secret, label) {
|
|
|
30
59
|
* remainder without its signature): HMAC-SHA256 of the
|
|
31
60
|
* path under a subkey derived from the secret (the raw
|
|
32
61
|
* HMAC of the secret over the label `crabcrop/purge-key`),
|
|
33
|
-
* so an image signature
|
|
34
|
-
* signature
|
|
35
|
-
*
|
|
62
|
+
* so an image signature does not verify as a purge
|
|
63
|
+
* signature: no signer signs a label (see
|
|
64
|
+
* {@link RESERVED_SEGMENT}). This is the signature segment
|
|
65
|
+
* for `POST /purge/<signature>/<path>`.
|
|
36
66
|
*/
|
|
37
67
|
export function purgeSignature(secret, target) {
|
|
38
68
|
return toHex(hmacSha256(subkey(secret, "crabcrop/purge-key"), target));
|
|
@@ -55,9 +85,11 @@ export function purgeGroupSignature(secret, group) {
|
|
|
55
85
|
* The upload signature for an object name: HMAC-SHA256 of
|
|
56
86
|
* the name under a subkey derived from the secret (the raw
|
|
57
87
|
* HMAC of the secret over the label `crabcrop/upload-key`),
|
|
58
|
-
* so neither an image signature nor a purge signature
|
|
59
|
-
*
|
|
60
|
-
*
|
|
88
|
+
* so neither an image signature nor a purge signature
|
|
89
|
+
* verifies as an upload signature: a purge signature is
|
|
90
|
+
* under another subkey, and no signer signs a label (see
|
|
91
|
+
* {@link RESERVED_SEGMENT}). This is the signature segment
|
|
92
|
+
* for `PUT /upload/<signature>/<name>`.
|
|
61
93
|
*
|
|
62
94
|
* With `expires` (unix seconds), the signature covers
|
|
63
95
|
* `exp:<expires>/<name>` instead, and the request path is
|
|
@@ -200,9 +232,6 @@ export function unseal(secret, segment) {
|
|
|
200
232
|
* required: there is no `unsafe` spelling of a token.
|
|
201
233
|
*/
|
|
202
234
|
export function buildSealedURL(base, secret, operations, source, options = {}) {
|
|
203
|
-
if (secret === null || secret === undefined) {
|
|
204
|
-
throw new Error("sealing requires a secret: there is no unsafe token");
|
|
205
|
-
}
|
|
206
235
|
if (options.expires !== undefined) {
|
|
207
236
|
assertExpires(options.expires);
|
|
208
237
|
}
|
|
@@ -217,6 +246,13 @@ export function buildSealedURL(base, secret, operations, source, options = {}) {
|
|
|
217
246
|
remainder += `${operations}/`;
|
|
218
247
|
}
|
|
219
248
|
remainder += source;
|
|
249
|
+
assertNotReserved(remainder);
|
|
250
|
+
// The inputs are checked before the secret, as in the Rust
|
|
251
|
+
// and Python builders, so a refused input gets the same
|
|
252
|
+
// error with or without a secret.
|
|
253
|
+
if (secret === null || secret === undefined) {
|
|
254
|
+
throw new Error("sealing requires a secret: there is no unsafe token");
|
|
255
|
+
}
|
|
220
256
|
const segment = seal(secret, remainder, options.keyId);
|
|
221
257
|
return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
|
|
222
258
|
}
|
|
@@ -287,6 +323,9 @@ export function buildURL(base, secret, operations, source, options = {}) {
|
|
|
287
323
|
remainder += `${operations}/`;
|
|
288
324
|
}
|
|
289
325
|
remainder += source;
|
|
326
|
+
// Refused with or without a secret: the server refuses the
|
|
327
|
+
// URL whatever its signature.
|
|
328
|
+
assertNotReserved(remainder);
|
|
290
329
|
let signature;
|
|
291
330
|
if (secret === null) {
|
|
292
331
|
if (options.keyId !== undefined) {
|
|
@@ -322,7 +361,8 @@ export { filter, joinOps, ops } from "./operations.js";
|
|
|
322
361
|
import { explainUrl } from "./explain.js";
|
|
323
362
|
/**
|
|
324
363
|
* Verify a URL's signature locally. Returns true or false, or
|
|
325
|
-
* null when the URL is unsigned or malformed
|
|
364
|
+
* null when the URL is unsigned or malformed, or longer than
|
|
365
|
+
* the 64 KiB the explainer reads.
|
|
326
366
|
*
|
|
327
367
|
* With a single secret string, the key ID (when the URL
|
|
328
368
|
* carries one) is ignored: the question is whether this
|
|
@@ -336,6 +376,12 @@ export function verifyUrlSignature(secret, input) {
|
|
|
336
376
|
if (!signature || signature.kind !== "hmac") {
|
|
337
377
|
return null;
|
|
338
378
|
}
|
|
379
|
+
// No signature over a reserved remainder is ever valid: the
|
|
380
|
+
// server refuses it whatever the signature, and this check
|
|
381
|
+
// must not confirm a derived subkey either.
|
|
382
|
+
if (isReservedRemainder(remainder)) {
|
|
383
|
+
return false;
|
|
384
|
+
}
|
|
339
385
|
// Constant-time, like the Rust and Python verifiers: a
|
|
340
386
|
// plain === leaks how much of the tag was right.
|
|
341
387
|
const given = utf8(signature.value);
|
package/dist/operations.d.ts
CHANGED
|
@@ -256,6 +256,8 @@ export declare const filter: {
|
|
|
256
256
|
/**
|
|
257
257
|
* Draw a text overlay. Color is RRGGBB or RRGGBBAA; the
|
|
258
258
|
* canonical spelling is always eight lowercase hex digits.
|
|
259
|
+
* The label holds at most 1000 characters, and characters
|
|
260
|
+
* times size is at most 100000 (the server's caps).
|
|
259
261
|
*/
|
|
260
262
|
text(content: string, size: number, color: string, anchor: Anchor): string;
|
|
261
263
|
/** Blur every detected object of the named class. */
|
package/dist/operations.js
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
* still written on each side: the builders check numbers, the
|
|
17
17
|
* explainer checks their spellings.
|
|
18
18
|
*/
|
|
19
|
-
import { BLEND_MODES, classFoldKey, CROP_ALIGNS, CURVE_CHANNELS, DPR_FACTORS, FLIP_AXES, IMAGE_FORMATS, isClassName, isOneOf, JPEG_SUBSAMPLINGS, MASK_SHAPES, MAX_OBJECTS_CLASSES, QUALITY_FORMATS, STUDIO_BACKDROPS, STUDIO_MODES, STUDIO_SHADOWS, TEXT_ANCHORS, UPSCALE_FACTORS, } from "./explain.js";
|
|
19
|
+
import { BLEND_MODES, classFoldKey, CROP_ALIGNS, CURVE_CHANNELS, DPR_FACTORS, FLIP_AXES, IMAGE_FORMATS, isClassName, isOneOf, JPEG_SUBSAMPLINGS, MASK_SHAPES, MAX_OBJECTS_CLASSES, MAX_TEXT_EXTENT, MAX_TEXT_GLYPHS, QUALITY_FORMATS, STUDIO_BACKDROPS, STUDIO_MODES, STUDIO_SHADOWS, TEXT_ANCHORS, textLabelFits, trimLikeServer, UPSCALE_FACTORS, } from "./explain.js";
|
|
20
20
|
import { MAX_DIMENSION } from "./limits.js";
|
|
21
21
|
function fail(what, value, rule) {
|
|
22
22
|
throw new Error(`${what} must be ${rule}, got ${JSON.stringify(value)}`);
|
|
@@ -173,7 +173,7 @@ function encodeArg(text) {
|
|
|
173
173
|
return encodeURIComponent(text).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
|
|
174
174
|
}
|
|
175
175
|
function className(what, name) {
|
|
176
|
-
const trimmed = name
|
|
176
|
+
const trimmed = trimLikeServer(name);
|
|
177
177
|
if (!isClassName(trimmed)) {
|
|
178
178
|
fail(what, name, "1 to 64 UTF-8 bytes of letters, digits, space, `_`, `.`, `-`, `/`");
|
|
179
179
|
}
|
|
@@ -236,7 +236,7 @@ export const ops = {
|
|
|
236
236
|
const names = [];
|
|
237
237
|
for (const name of classes) {
|
|
238
238
|
const encoded = className("crop objects class", name);
|
|
239
|
-
const key = classFoldKey(name
|
|
239
|
+
const key = classFoldKey(trimLikeServer(name));
|
|
240
240
|
if (!seen.has(key)) {
|
|
241
241
|
if (names.length === MAX_OBJECTS_CLASSES) {
|
|
242
242
|
fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
|
|
@@ -740,6 +740,8 @@ export const filter = {
|
|
|
740
740
|
/**
|
|
741
741
|
* Draw a text overlay. Color is RRGGBB or RRGGBBAA; the
|
|
742
742
|
* canonical spelling is always eight lowercase hex digits.
|
|
743
|
+
* The label holds at most 1000 characters, and characters
|
|
744
|
+
* times size is at most 100000 (the server's caps).
|
|
743
745
|
*/
|
|
744
746
|
text(content, size, color, anchor) {
|
|
745
747
|
if (!isOneOf(TEXT_ANCHORS, anchor)) {
|
|
@@ -748,6 +750,9 @@ export const filter = {
|
|
|
748
750
|
if (content === "")
|
|
749
751
|
fail("text", content, "a non-empty label");
|
|
750
752
|
intIn("text size", size, 1, 1000);
|
|
753
|
+
if (!textLabelFits(content, size)) {
|
|
754
|
+
fail("text", content, `at most ${MAX_TEXT_GLYPHS} characters, and characters times size at most ${MAX_TEXT_EXTENT}`);
|
|
755
|
+
}
|
|
751
756
|
return `text(${encodeArg(content)},${size},${hex6or8("text color", color)},${anchor})`;
|
|
752
757
|
},
|
|
753
758
|
/** Blur every detected object of the named class. */
|