@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 +91 -91
- package/README.md +522 -522
- package/dist/index.js.map +1 -1
- package/dist/plugin.js.map +1 -1
- package/package.json +4 -4
- package/src/cid.ts +200 -200
- package/src/crypto.ts +547 -547
- package/src/index.ts +58 -58
- package/src/plugin.ts +290 -290
- package/src/sd.ts +250 -250
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.
|