@optimystic/quereus-plugin-crypto 1.5.0 → 1.6.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/CHANGELOG.md CHANGED
@@ -1,91 +1,91 @@
1
- # Changelog
2
-
3
- ## 0.14.0 — BREAKING: `digest` API rework
4
-
5
- ### What changed
6
-
7
- The exported `digest()` function signature changed from:
8
-
9
- ```ts
10
- // OLD (≤ 0.13.x)
11
- digest(data: string | Uint8Array, algorithm?, inputEncoding?, outputEncoding?)
12
- ```
13
-
14
- to:
15
-
16
- ```ts
17
- // NEW (≥ 0.14.0)
18
- digest(fields: readonly DigestField[], algorithm?, encoding?)
19
- ```
20
-
21
- Key differences:
22
-
23
- | | Old | New |
24
- |---|---|---|
25
- | First argument | A single scalar value (`string` \| `Uint8Array`) | An **array** of values |
26
- | `inputEncoding` | 3rd positional arg | **Removed** (the new API frames values by type, no string-decoding step) |
27
- | Output encoding | 4th positional arg | 2nd `encoding` arg (shifted left by one) |
28
- | Algorithm | 2nd positional arg | 2nd `algorithm` arg (unchanged position) |
29
- | Result | Bare hash of the decoded bytes | **Framed** injective digest — `digest(['hello'])` ≠ `sha256("hello")` |
30
- | Algorithm + encoding | Per-call | **Bound at plugin load time** for the SQL function |
31
-
32
- ### Migration: JS/TypeScript callers
33
-
34
- ```ts
35
- // OLD
36
- const hashBytes = digest(payload, 'sha256', 'utf8', 'bytes') as Uint8Array;
37
- const payloadDigest = digest(payload, 'sha256', 'utf8', 'base64url') as string;
38
-
39
- // NEW — wrap the value in an array, drop inputEncoding
40
- const hashBytes = digest([payload], 'sha256', 'bytes') as Uint8Array;
41
- const payloadDigest = digest([payload], 'sha256', 'base64url') as string;
42
- ```
43
-
44
- > **The result value changes.** The new digest is *framed* (version byte + type tag +
45
- > length-prefixed payload per field), so `digest(['hello'])` is **not** the same bytes
46
- > as `sha256(utf8("hello"))`. If you need to match an externally-computed bare hash,
47
- > see the open question below.
48
-
49
- ### Migration: SQL callers
50
-
51
- The SQL `digest(field1, field2, ...)` function is **variadic over data fields** — every
52
- argument is a field to hash, not a config option — so the signature is unchanged from the
53
- SQL perspective.
54
-
55
- However, if you were passing extra positional arguments to mimic `algo`/`inputEncoding`/`outputEncoding`
56
- (e.g. `digest(data, 'sha256', 'utf8', 'bytes')`), those are now treated as **additional
57
- data fields** and hashed into the result silently rather than interpreted as config. There
58
- is **no error** on the SQL path for this; it just hashes more fields. Check any SQL call
59
- sites that pass more than pure data arguments.
60
-
61
- Algorithm and encoding are now set via the plugin config at load time (see the
62
- [Digest configuration](README.md#digest-configuration) section of the README).
63
-
64
- ### Why no compatibility shim?
65
-
66
- The old and new calling conventions cannot be cleanly disambiguated: the new first argument
67
- is always an array; the old's was always a scalar. Adding a scalar → old-API detection
68
- shim would silently re-enable the broken `inputEncoding` positional footgun and make the
69
- result value unpredictable. The clean break stays; instead, old-style JS calls now throw
70
- a clear, actionable error message naming this migration note.
71
-
72
- ### Error message for old-style calls
73
-
74
- If you pass a non-array as the first argument to `digest()` in JS/TypeScript, you will now
75
- see:
76
-
77
- ```
78
- digest(fields, algorithm?, encoding?): 'fields' must be an array of values.
79
- The digest API changed in v0.14: it is now variadic/injective over fields,
80
- the per-call inputEncoding was removed, and algorithm + output encoding are bound at plugin load time.
81
- Migrate digest(value, algo, inputEncoding, outputEncoding) → digest([value], algo, outputEncoding) —
82
- note the result is now a *framed* digest, not a bare hash of the bytes.
83
- ```
84
-
85
- ### Open question: bare hash helper
86
-
87
- The new `digest` has no function that returns a bare (un-framed) hash of a single value's
88
- bytes in a chosen encoding — what the old `digest(x, algo, inEnc, outEnc)` did. If you
89
- need bare-hash semantics (e.g. to match a hash stored before v0.14, or computed by an
90
- external system), there is currently no drop-in. File a separate issue/ticket if a
91
- `hash(data, algorithm, inputEncoding, outputEncoding)` helper is needed.
1
+ # Changelog
2
+
3
+ ## 0.14.0 — BREAKING: `digest` API rework
4
+
5
+ ### What changed
6
+
7
+ The exported `digest()` function signature changed from:
8
+
9
+ ```ts
10
+ // OLD (≤ 0.13.x)
11
+ digest(data: string | Uint8Array, algorithm?, inputEncoding?, outputEncoding?)
12
+ ```
13
+
14
+ to:
15
+
16
+ ```ts
17
+ // NEW (≥ 0.14.0)
18
+ digest(fields: readonly DigestField[], algorithm?, encoding?)
19
+ ```
20
+
21
+ Key differences:
22
+
23
+ | | Old | New |
24
+ |---|---|---|
25
+ | First argument | A single scalar value (`string` \| `Uint8Array`) | An **array** of values |
26
+ | `inputEncoding` | 3rd positional arg | **Removed** (the new API frames values by type, no string-decoding step) |
27
+ | Output encoding | 4th positional arg | 2nd `encoding` arg (shifted left by one) |
28
+ | Algorithm | 2nd positional arg | 2nd `algorithm` arg (unchanged position) |
29
+ | Result | Bare hash of the decoded bytes | **Framed** injective digest — `digest(['hello'])` ≠ `sha256("hello")` |
30
+ | Algorithm + encoding | Per-call | **Bound at plugin load time** for the SQL function |
31
+
32
+ ### Migration: JS/TypeScript callers
33
+
34
+ ```ts
35
+ // OLD
36
+ const hashBytes = digest(payload, 'sha256', 'utf8', 'bytes') as Uint8Array;
37
+ const payloadDigest = digest(payload, 'sha256', 'utf8', 'base64url') as string;
38
+
39
+ // NEW — wrap the value in an array, drop inputEncoding
40
+ const hashBytes = digest([payload], 'sha256', 'bytes') as Uint8Array;
41
+ const payloadDigest = digest([payload], 'sha256', 'base64url') as string;
42
+ ```
43
+
44
+ > **The result value changes.** The new digest is *framed* (version byte + type tag +
45
+ > length-prefixed payload per field), so `digest(['hello'])` is **not** the same bytes
46
+ > as `sha256(utf8("hello"))`. If you need to match an externally-computed bare hash,
47
+ > see the open question below.
48
+
49
+ ### Migration: SQL callers
50
+
51
+ The SQL `digest(field1, field2, ...)` function is **variadic over data fields** — every
52
+ argument is a field to hash, not a config option — so the signature is unchanged from the
53
+ SQL perspective.
54
+
55
+ However, if you were passing extra positional arguments to mimic `algo`/`inputEncoding`/`outputEncoding`
56
+ (e.g. `digest(data, 'sha256', 'utf8', 'bytes')`), those are now treated as **additional
57
+ data fields** and hashed into the result silently rather than interpreted as config. There
58
+ is **no error** on the SQL path for this; it just hashes more fields. Check any SQL call
59
+ sites that pass more than pure data arguments.
60
+
61
+ Algorithm and encoding are now set via the plugin config at load time (see the
62
+ [Digest configuration](README.md#digest-configuration) section of the README).
63
+
64
+ ### Why no compatibility shim?
65
+
66
+ The old and new calling conventions cannot be cleanly disambiguated: the new first argument
67
+ is always an array; the old's was always a scalar. Adding a scalar → old-API detection
68
+ shim would silently re-enable the broken `inputEncoding` positional footgun and make the
69
+ result value unpredictable. The clean break stays; instead, old-style JS calls now throw
70
+ a clear, actionable error message naming this migration note.
71
+
72
+ ### Error message for old-style calls
73
+
74
+ If you pass a non-array as the first argument to `digest()` in JS/TypeScript, you will now
75
+ see:
76
+
77
+ ```
78
+ digest(fields, algorithm?, encoding?): 'fields' must be an array of values.
79
+ The digest API changed in v0.14: it is now variadic/injective over fields,
80
+ the per-call inputEncoding was removed, and algorithm + output encoding are bound at plugin load time.
81
+ Migrate digest(value, algo, inputEncoding, outputEncoding) → digest([value], algo, outputEncoding) —
82
+ note the result is now a *framed* digest, not a bare hash of the bytes.
83
+ ```
84
+
85
+ ### Open question: bare hash helper
86
+
87
+ The new `digest` has no function that returns a bare (un-framed) hash of a single value's
88
+ bytes in a chosen encoding — what the old `digest(x, algo, inEnc, outEnc)` did. If you
89
+ need bare-hash semantics (e.g. to match a hash stored before v0.14, or computed by an
90
+ external system), there is currently no drop-in. File a separate issue/ticket if a
91
+ `hash(data, algorithm, inputEncoding, outputEncoding)` helper is needed.