leviathan-crypto 1.2.0 → 1.3.1
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/CLAUDE.md +19 -17
- package/README.md +130 -65
- package/SECURITY.md +2 -1
- package/dist/chacha20/index.js +1 -1
- package/dist/chacha20/pool.js +1 -1
- package/dist/{chacha.wasm → chacha20.wasm} +0 -0
- package/dist/docs/architecture.md +25 -25
- package/dist/docs/argon2id.md +6 -6
- package/dist/docs/chacha20.md +11 -7
- package/dist/docs/chacha20_pool.md +9 -6
- package/dist/docs/fortuna.md +7 -7
- package/dist/docs/init.md +4 -4
- package/dist/docs/loader.md +5 -5
- package/dist/docs/serpent.md +49 -13
- package/dist/docs/sha2.md +13 -8
- package/dist/docs/sha3.md +8 -5
- package/dist/docs/types.md +8 -8
- package/dist/docs/utils.md +29 -8
- package/dist/docs/wasm.md +8 -7
- package/dist/embedded/{chacha.d.ts → chacha20.d.ts} +1 -1
- package/dist/embedded/{chacha.js → chacha20.js} +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/init.js +1 -1
- package/dist/serpent/index.d.ts +0 -1
- package/dist/serpent/index.js +0 -2
- package/dist/serpent/stream-sealer.d.ts +18 -2
- package/dist/serpent/stream-sealer.js +122 -4
- package/package.json +1 -1
- package/dist/serpent/stream-encoder.d.ts +0 -20
- package/dist/serpent/stream-encoder.js +0 -167
package/CLAUDE.md
CHANGED
|
@@ -87,16 +87,12 @@ await serpentInit()
|
|
|
87
87
|
|
|
88
88
|
| Classes | `init()` call |
|
|
89
89
|
|---------|--------------|
|
|
90
|
-
| `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `
|
|
90
|
+
| `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc` | `init(['serpent', 'sha2'])` |
|
|
91
91
|
| `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool` | `init(['chacha20'])` |
|
|
92
92
|
| `SHA256`, `SHA384`, `SHA512`, `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512`, `HKDF_SHA256`, `HKDF_SHA512` | `init(['sha2'])` |
|
|
93
93
|
| `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` | `init(['sha3'])` |
|
|
94
94
|
| `Fortuna` | `init(['serpent', 'sha2'])` |
|
|
95
95
|
|
|
96
|
-
`Argon2id` is a separate subpath: `import { Argon2id } from 'leviathan-crypto/argon2id'`
|
|
97
|
-
It does **not** require `init()` — it uses its own WASM loader.
|
|
98
|
-
`'argon2id'` is **not** a valid module string for `init()`.
|
|
99
|
-
|
|
100
96
|
---
|
|
101
97
|
|
|
102
98
|
## Recommended patterns
|
|
@@ -138,23 +134,24 @@ const ptLast = opener.open(last)
|
|
|
138
134
|
|
|
139
135
|
### Length-prefixed streaming (for files and buffered transports)
|
|
140
136
|
|
|
141
|
-
`
|
|
142
|
-
`u32be` length-prefixed framing
|
|
137
|
+
Pass `{ framed: true }` to `SerpentStreamSealer`/`SerpentStreamOpener` for self-delimiting
|
|
138
|
+
`u32be` length-prefixed framing. Use when chunks will be concatenated into a flat byte
|
|
139
|
+
stream. Omit when the transport frames messages itself (WebSocket, IPC).
|
|
143
140
|
|
|
144
141
|
```typescript
|
|
145
|
-
import { init,
|
|
142
|
+
import { init, SerpentStreamSealer, SerpentStreamOpener, randomBytes } from 'leviathan-crypto'
|
|
146
143
|
|
|
147
144
|
await init(['serpent', 'sha2'])
|
|
148
145
|
|
|
149
|
-
const key
|
|
150
|
-
const
|
|
151
|
-
const header
|
|
146
|
+
const key = randomBytes(64)
|
|
147
|
+
const sealer = new SerpentStreamSealer(key, 65536, { framed: true })
|
|
148
|
+
const header = sealer.header()
|
|
152
149
|
|
|
153
|
-
const frame0
|
|
154
|
-
const last
|
|
150
|
+
const frame0 = sealer.seal(data0) // u32be(len) || sealed chunk
|
|
151
|
+
const last = sealer.final(tail)
|
|
155
152
|
|
|
156
|
-
const
|
|
157
|
-
const chunks
|
|
153
|
+
const opener = new SerpentStreamOpener(key, header, { framed: true })
|
|
154
|
+
const chunks = opener.feed(frame0) // Uint8Array[] — throws on auth failure
|
|
158
155
|
```
|
|
159
156
|
|
|
160
157
|
### XChaCha20-Poly1305
|
|
@@ -236,7 +233,7 @@ cipher.decrypt(key, iv, ciphertext) // correct
|
|
|
236
233
|
## Utilities (no `init()` required)
|
|
237
234
|
|
|
238
235
|
```typescript
|
|
239
|
-
import { hexToBytes, bytesToHex, randomBytes, constantTimeEqual, wipe } from 'leviathan-crypto'
|
|
236
|
+
import { hexToBytes, bytesToHex, randomBytes, constantTimeEqual, wipe, hasSIMD } from 'leviathan-crypto'
|
|
240
237
|
|
|
241
238
|
// available immediately — no await init() needed
|
|
242
239
|
const key = randomBytes(32)
|
|
@@ -246,6 +243,11 @@ const safe = constantTimeEqual(a, b) // constant-time equality — never use =
|
|
|
246
243
|
wipe(key) // zero a Uint8Array in place
|
|
247
244
|
```
|
|
248
245
|
|
|
246
|
+
`hasSIMD()` returns `true` if the runtime supports WebAssembly SIMD. It is used
|
|
247
|
+
internally — you do not need to call it. SIMD acceleration is fully transparent:
|
|
248
|
+
`SerpentCtr.encryptChunk`, `SerpentCbc.decrypt`, and `ChaCha20.encryptChunk` all
|
|
249
|
+
auto-dispatch to the faster 4-wide SIMD path when available, with no API change.
|
|
250
|
+
|
|
249
251
|
---
|
|
250
252
|
|
|
251
253
|
## Full documentation
|
|
@@ -254,7 +256,7 @@ The complete API reference ships in `docs/` alongside this file:
|
|
|
254
256
|
|
|
255
257
|
| File | Contents |
|
|
256
258
|
|------|----------|
|
|
257
|
-
| `docs/serpent.md` | `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `
|
|
259
|
+
| `docs/serpent.md` | `SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc` |
|
|
258
260
|
| `docs/chacha20.md` | `ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool` |
|
|
259
261
|
| `docs/sha2.md` | `SHA256`, `SHA384`, `SHA512`, `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512`, `HKDF_SHA256`, `HKDF_SHA512` |
|
|
260
262
|
| `docs/sha3.md` | `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256` |
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
[](https://github.com/xero/leviathan-crypto/releases/latest) [](https://www.npmjs.com/package/leviathan-crypto) [](https://github.com/xero/leviathan-crypto/actions/workflows/test-suite.yml) [](https://github.com/xero/leviathan-crypto/wiki)
|
|
2
2
|
|
|
3
|
-
   [](https://github.com/xero/
|
|
3
|
+
    [](https://github.com/xero/leviathan-crypto/blob/main/LICENSE)
|
|
4
4
|
|
|
5
5
|
<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="Leviathan logo" width="400" >
|
|
6
6
|
|
|
@@ -8,26 +8,62 @@
|
|
|
8
8
|
|
|
9
9
|
> Web cryptography built on Serpent-256 paranoia and XChaCha20-Poly1305 elegance.
|
|
10
10
|
|
|
11
|
-
**Serpent-256 is the cipher for those who distrust consensus.** In 2001, when
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
11
|
+
**Serpent-256 is the cipher for those who distrust consensus.** In 2001, when
|
|
12
|
+
NIST selected AES, Serpent actually received more first-place security votes
|
|
13
|
+
from the evaluation committee. However, it lost because the competition also
|
|
14
|
+
considered performance on hardware embedded systems, which are no longer
|
|
15
|
+
representative of the environments for which we develop software. Serpent's
|
|
16
|
+
designers made no compromises: thirty-two rounds, S-boxes implemented using
|
|
17
|
+
pure Boolean logic gates without table lookups, and every bit processed for
|
|
18
|
+
each block. You use Serpent not because a committee recommended it, but because
|
|
19
|
+
you trust the cryptanalysis. The current best attack on the full
|
|
20
|
+
thirty-two-round Serpent-256 achieves 2²⁵⁵·¹⁹ — less than one bit below the
|
|
21
|
+
brute-force ceiling, and strictly impractical. This includes our own
|
|
22
|
+
independent research, which improved upon the published result. See
|
|
23
|
+
[`serpent_audit.md`](https://github.com/xero/leviathan-crypto/wiki/serpent_audit).
|
|
24
|
+
|
|
25
|
+
**XChaCha20-Poly1305 is the cipher for those who appreciate design that has
|
|
26
|
+
nothing to hide.** Daniel Bernstein built ChaCha20 as a twenty-round ARX
|
|
27
|
+
construction: add, rotate, and XOR, in a precise choreography that simply
|
|
28
|
+
doesn't have the attack surface that table-based ciphers do. It has no S-boxes,
|
|
29
|
+
no cache-timing leakage, and requires no hardware acceleration to be fast.
|
|
30
|
+
Poly1305 adds a final layer of security: a one-time authenticator with an
|
|
31
|
+
unconditional forgery bound, mathematically guaranteed regardless of attacker
|
|
32
|
+
compute power. XChaCha20-Poly1305 is the construction you reach for when you
|
|
33
|
+
want an AEAD whose security proof you can actually read without a PhD. See
|
|
34
|
+
[`chacha_audit.md`](https://github.com/xero/leviathan-crypto/wiki/chacha_audit).
|
|
35
|
+
|
|
36
|
+
The tension between these two approaches constitutes the library's core
|
|
37
|
+
identity. Serpent embodies defiance, ChaCha embodies elegance, yet both arrive
|
|
38
|
+
at the same place: constant-time, side-channel resistant implementations,
|
|
39
|
+
independently audited against their specifications. They represent two design
|
|
40
|
+
philosophies that do not agree on anything, except the answer.
|
|
41
|
+
|
|
42
|
+
**WebAssembly provides a correctness layer.** Each primitive compiles into its
|
|
43
|
+
own isolated binary, executing outside the JavaScript JIT. This prevents
|
|
44
|
+
speculative optimization from affecting key material and ensures that
|
|
45
|
+
data-dependent timing vulnerabilities do not cross the boundary.
|
|
46
|
+
|
|
47
|
+
**TypeScript acts as the ergonomics layer.** Fully typed classes, explicit
|
|
48
|
+
`init()` gates, input validation, and authenticated compositions ensure
|
|
49
|
+
primitives are connected correctly.
|
|
20
50
|
|
|
21
51
|
---
|
|
22
52
|
|
|
23
53
|
#### **Zero Dependencies.**
|
|
24
|
-
|
|
54
|
+
|
|
55
|
+
With no npm dependency graph to audit, the supply chain attack surface is
|
|
56
|
+
eliminated.
|
|
25
57
|
|
|
26
58
|
#### **Tree-shakeable.**
|
|
27
|
-
|
|
59
|
+
|
|
60
|
+
Import only the cipher(s) you intend to use. Subpath exports allow bundlers to
|
|
61
|
+
exclude everything else.
|
|
28
62
|
|
|
29
63
|
#### **Side-effect Free.**
|
|
30
|
-
|
|
64
|
+
|
|
65
|
+
Nothing runs upon import. Initialization via `init()` is explicit and
|
|
66
|
+
asynchronous.
|
|
31
67
|
|
|
32
68
|
|
|
33
69
|
## Installation
|
|
@@ -40,7 +76,10 @@ npm install leviathan-crypto
|
|
|
40
76
|
```
|
|
41
77
|
|
|
42
78
|
> [!NOTE]
|
|
43
|
-
> The Serpent and ChaCha20 modules require a runtime with WebAssembly SIMD
|
|
79
|
+
> The Serpent and ChaCha20 modules require a runtime with WebAssembly SIMD
|
|
80
|
+
> support. [This has been a feature of all major browsers and runtimes since
|
|
81
|
+
> 2021](https://caniuse.com/wasm-simd). All other primitives (SHA-2, SHA-3,
|
|
82
|
+
> Poly1305) run on any WASM-capable runtime.
|
|
44
83
|
|
|
45
84
|
---
|
|
46
85
|
|
|
@@ -48,15 +87,30 @@ npm install leviathan-crypto
|
|
|
48
87
|
|
|
49
88
|
**`lvthn-web`** [ [demo](https://leviathan.3xi.club/web) · [source](https://github.com/xero/leviathan-demos/tree/main/lvthn-web) · [readme](https://github.com/xero/leviathan-demos/blob/main/lvthn-web/README.md) ]
|
|
50
89
|
|
|
51
|
-
A browser encryption tool in a single, self-contained HTML file. Encrypt text
|
|
90
|
+
A browser encryption tool in a single, self-contained HTML file. Encrypt text
|
|
91
|
+
or files using Serpent-256-CBC and Argon2id key derivation, then share the
|
|
92
|
+
armored output. No server, installation, or network connection required after
|
|
93
|
+
initial load. The code is written to be read. The Encrypt-then-MAC
|
|
94
|
+
construction, HMAC input (header with HMAC field zeroed + ciphertext), and
|
|
95
|
+
Argon2id parameters are all intentional examples worth reading.
|
|
52
96
|
|
|
53
97
|
**`lvthn-chat`** [ [demo](https://leviathan.3xi.club/chat) · [source](https://github.com/xero/leviathan-demos/tree/main/lvthn-chat) · [readme](https://github.com/xero/leviathan-demos/blob/main/lvthn-chat/README.md) ]
|
|
54
98
|
|
|
55
|
-
End-to-end encrypted chat featuring two-party messaging over X25519 key
|
|
99
|
+
End-to-end encrypted chat featuring two-party messaging over X25519 key
|
|
100
|
+
exchange and XChaCha20-Poly1305 message encryption. The relay server functions
|
|
101
|
+
as a dumb WebSocket pipe that never sees plaintext. Each message incorporates
|
|
102
|
+
sequence numbers, which allows the system to detect and reject replayed
|
|
103
|
+
messages from an attacker. The demo deconstructs the protocol step by step,
|
|
104
|
+
with visual feedback for both injection and replays.
|
|
56
105
|
|
|
57
106
|
**`lvthn-cli`** [ [npm](https://www.npmjs.com/package/lvthn) · [source](https://github.com/xero/leviathan-demos/tree/main/lvthn-cli) · [readme](https://github.com/xero/leviathan-demos/blob/main/lvthn-cli/README.md) ]
|
|
58
107
|
|
|
59
|
-
File encryption CLI. Supports both Serpent-256 and XChaCha20-Poly1305,
|
|
108
|
+
File encryption CLI. Supports both Serpent-256 and XChaCha20-Poly1305,
|
|
109
|
+
selectable via the `--cipher` flag. A single keyfile is compatible with both
|
|
110
|
+
ciphers; the header byte determines decryption automatically. Encryption and
|
|
111
|
+
decryption distribute 64KB chunks across a worker pool sized to
|
|
112
|
+
hardwareConcurrency. Each worker owns an isolated WASM instance with no shared
|
|
113
|
+
memory between workers.
|
|
60
114
|
|
|
61
115
|
```sh
|
|
62
116
|
bun i -g lvthn # or npm slow mode
|
|
@@ -69,27 +123,33 @@ cat secret.txt | lvthn encrypt -k my.key --armor > secret.enc
|
|
|
69
123
|
|
|
70
124
|
## Primitives
|
|
71
125
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
|
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
126
|
+
| Class | Module | Auth | Notes |
|
|
127
|
+
| ----------------------------------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
128
|
+
| **Authenticated encryption** | | | |
|
|
129
|
+
| `SerpentSeal` | `serpent`, `sha2` | **Yes** | Serpent-CBC + HMAC-SHA256. Recommended default for most use cases. 64-byte key. |
|
|
130
|
+
| `SerpentStream`, `SerpentStreamPool` | `serpent`, `sha2` | **Yes** | Chunked one-shot AEAD for large payloads. Pool variant parallelises across workers. 32-byte key. |
|
|
131
|
+
| `SerpentStreamSealer`, `SerpentStreamOpener` | `serpent`, `sha2` | **Yes** | Incremental streaming AEAD: seal/open one chunk at a time. Pass `{ framed: true }` for self-delimiting `u32be` length-prefix framing. 64-byte key. |
|
|
132
|
+
| `XChaCha20Poly1305` | `chacha20` | **Yes** | XChaCha20-Poly1305 AEAD. Recommended when you want a simpler API or a 192-bit nonce safe for random generation. 32-byte key. |
|
|
133
|
+
| `XChaCha20Poly1305Pool` | `chacha20` | **Yes** | Worker-pool wrapper for `XChaCha20Poly1305`. Parallelises encryption across isolated WASM instances. |
|
|
134
|
+
| `ChaCha20Poly1305` | `chacha20` | **Yes** | ChaCha20-Poly1305 AEAD — RFC 8439. 12-byte nonce; prefer `XChaCha20Poly1305` unless you need RFC 8439 exact compliance. |
|
|
135
|
+
| **Unauthenticated primitives** _pair with HMAC or use AEAD_ | | | |
|
|
136
|
+
| `Serpent` | `serpent` | **No** | Serpent-256 ECB block cipher. Single-block encrypt/decrypt. |
|
|
137
|
+
| `SerpentCtr` | `serpent` | **No** | Serpent-256 CTR mode stream cipher. Requires `{ dangerUnauthenticated: true }`. |
|
|
138
|
+
| `SerpentCbc` | `serpent` | **No** | Serpent-256 CBC mode with PKCS7 padding. Requires `{ dangerUnauthenticated: true }`. |
|
|
139
|
+
| `ChaCha20` | `chacha20` | **No** | ChaCha20 stream cipher — RFC 8439. Unauthenticated; use `XChaCha20Poly1305` unless you need raw keystream. |
|
|
140
|
+
| `Poly1305` | `chacha20` | **No** | Poly1305 one-time MAC — RFC 8439. Use via the AEAD classes unless you have a specific reason not to. |
|
|
141
|
+
| **Hashing and key derivation** | | | |
|
|
142
|
+
| `SHA256`, `SHA384`, `SHA512` | `sha2` | — | SHA-2 family — FIPS 180-4. |
|
|
143
|
+
| `HMAC_SHA256`, `HMAC_SHA384`, `HMAC_SHA512` | `sha2` | — | HMAC construction over SHA-2 — RFC 2104. |
|
|
144
|
+
| `HKDF_SHA256`, `HKDF_SHA512` | `sha2` | — | Extract-and-expand key derivation over HMAC — RFC 5869. |
|
|
145
|
+
| `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512` | `sha3` | — | SHA-3 family — FIPS 202. Keccak-based, structurally independent of SHA-2. |
|
|
146
|
+
| `SHAKE128`, `SHAKE256` | `sha3` | — | Extendable output functions (XOF) — FIPS 202. Variable-length output; useful for key derivation and stream generation. |
|
|
147
|
+
| **CSPRNG** | | | |
|
|
148
|
+
| `Fortuna` | `serpent`, `sha2` | — | Fortuna CSPRNG (Ferguson & Schneier). 32 entropy pools, forward secrecy. Use `Fortuna.create()`. |
|
|
86
149
|
|
|
87
150
|
> [!IMPORTANT]
|
|
88
151
|
> All cryptographic computation runs in WASM (AssemblyScript), isolated outside the JavaScript JIT. The TypeScript layer provides the public API with input validation, type safety, and developer ergonomics.
|
|
89
152
|
|
|
90
|
-
> [!WARNING]
|
|
91
|
-
> `SerpentCtr` and `SerpentCbc` are **unauthenticated** cipher modes. They provide confidentiality but not integrity or authenticity. An attacker can modify ciphertext without detection. For authenticated Serpent encryption use `SerpentSeal` or `SerpentStreamSealer`. When using CBC/CTR directly, pair with `HMAC_SHA256` using the Encrypt-then-MAC pattern.
|
|
92
|
-
|
|
93
153
|
---
|
|
94
154
|
|
|
95
155
|
## Quick Start
|
|
@@ -135,7 +195,8 @@ const decrypted = chacha.decrypt(key, nonce, ciphertext)
|
|
|
135
195
|
chacha.dispose()
|
|
136
196
|
```
|
|
137
197
|
|
|
138
|
-
For more examples, including streaming, chunking, hashing, and key derivation,
|
|
198
|
+
For more examples, including streaming, chunking, hashing, and key derivation,
|
|
199
|
+
see the [examples page](https://github.com/xero/leviathan-crypto/wiki/examples).
|
|
139
200
|
|
|
140
201
|
---
|
|
141
202
|
|
|
@@ -154,7 +215,8 @@ await init(['serpent'], 'manual', { wasmBinary: { serpent: myBuffer } })
|
|
|
154
215
|
|
|
155
216
|
### Tree-shaking with subpath imports
|
|
156
217
|
|
|
157
|
-
Each cipher ships as its own subpath export. A bundler with tree-shaking
|
|
218
|
+
Each cipher ships as its own subpath export. A bundler with tree-shaking
|
|
219
|
+
support and `"sideEffects": false` will exclude every module you don't import:
|
|
158
220
|
|
|
159
221
|
```typescript
|
|
160
222
|
// Only serpent.wasm ends up in your bundle
|
|
@@ -186,37 +248,38 @@ await chacha20Init()
|
|
|
186
248
|
|
|
187
249
|
### API Surface
|
|
188
250
|
|
|
189
|
-
| Module
|
|
190
|
-
|
|
|
191
|
-
| serpent
|
|
192
|
-
| asm_serpent
|
|
193
|
-
| chacha20
|
|
194
|
-
| asm_chacha
|
|
195
|
-
| sha2
|
|
196
|
-
| asm_sha2
|
|
197
|
-
| sha3
|
|
198
|
-
| asm_sha3
|
|
199
|
-
| fortuna
|
|
200
|
-
| init
|
|
201
|
-
| utils
|
|
202
|
-
| types
|
|
251
|
+
| Module | MD/Wiki | Description |
|
|
252
|
+
| ----------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
253
|
+
| serpent | [▼](./docs/serpent.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/serpent) | Serpent-256 TypeScript API (`SerpentSeal`, `SerpentStream`, `SerpentStreamPool`, `SerpentStreamSealer`, `SerpentStreamOpener`, `Serpent`, `SerpentCtr`, `SerpentCbc`) |
|
|
254
|
+
| asm_serpent | [▼](./docs/asm_serpent.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_serpent) | Serpent-256 WASM implementation (bitslice S-boxes, key schedule, CTR/CBC) |
|
|
255
|
+
| chacha20 | [▼](./docs/chacha20.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/chacha20) | ChaCha20/Poly1305 TypeScript API (`ChaCha20`, `Poly1305`, `ChaCha20Poly1305`, `XChaCha20Poly1305`, `XChaCha20Poly1305Pool`) |
|
|
256
|
+
| asm_chacha | [▼](./docs/asm_chacha.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_chacha) | ChaCha20/Poly1305 WASM implementation (quarter-round, HChaCha20) |
|
|
257
|
+
| sha2 | [▼](./docs/sha2.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/sha2) | SHA-2 TypeScript API (`SHA256`, `SHA512`, `SHA384`, `HMAC_SHA256`, `HMAC_SHA512`, `HMAC_SHA384`) |
|
|
258
|
+
| asm_sha2 | [▼](./docs/asm_sha2.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_sha2) | SHA-2 WASM implementation (compression functions, HMAC) |
|
|
259
|
+
| sha3 | [▼](./docs/sha3.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/sha3) | SHA-3 TypeScript API (`SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256`) |
|
|
260
|
+
| asm_sha3 | [▼](./docs/asm_sha3.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/asm_sha3) | SHA-3 WASM implementation (Keccak-f[1600], sponge construction) |
|
|
261
|
+
| fortuna | [▼](./docs/fortuna.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/fortuna) | Fortuna CSPRNG (forward secrecy, 32 entropy pools) |
|
|
262
|
+
| init | [▼](./docs/init.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/init) | `init()` API and WASM loading modes |
|
|
263
|
+
| utils | [▼](./docs/utils.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils) | Encoding helpers, `constantTimeEqual`, `wipe`, `randomBytes` |
|
|
264
|
+
| types | [▼](./docs/types.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/types) | TypeScript interfaces (`Hash`, `KeyedHash`, `Blockcipher`, `Streamcipher`, `AEAD`) |
|
|
203
265
|
|
|
204
266
|
### Utilities
|
|
205
267
|
|
|
206
268
|
These helpers are available immediately on import with no `init()` required.
|
|
207
269
|
|
|
208
|
-
| Function | MD/Wiki | Description
|
|
209
|
-
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
210
|
-
| `hexToBytes(hex)` | [▼](./docs/utils.md#hextobytes) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#hextobytes) | Hex string to `Uint8Array` (accepts uppercase, `0x` prefix)
|
|
211
|
-
| `bytesToHex(bytes)` | [▼](./docs/utils.md#bytestohex) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#bytestohex) | `Uint8Array` to lowercase hex string
|
|
212
|
-
| `utf8ToBytes(str)` | [▼](./docs/utils.md#utf8tobytes) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#utf8tobytes) | UTF-8 string to `Uint8Array`
|
|
213
|
-
| `bytesToUtf8(bytes)` | [▼](./docs/utils.md#bytestoutf8) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#bytestoutf8) | `Uint8Array` to UTF-8 string
|
|
214
|
-
| `base64ToBytes(b64)` | [▼](./docs/utils.md#base64tobytes) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#base64tobytes) | Base64/base64url string to `Uint8Array` (undefined on invalid)
|
|
215
|
-
| `bytesToBase64(bytes, url?)` | [▼](./docs/utils.md#bytestobase64) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#bytestobase64) | `Uint8Array` to base64 string (url=true for base64url)
|
|
216
|
-
| `constantTimeEqual(a, b)` | [▼](./docs/utils.md#constanttimeequal) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) | Constant-time byte comparison (XOR-accumulate)
|
|
217
|
-
| `wipe(data)` | [▼](./docs/utils.md#wipe) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#wipe) | Zero a typed array in place
|
|
218
|
-
| `xor(a, b)` | [▼](./docs/utils.md#xor) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#xor) | XOR two equal-length `Uint8Array`s
|
|
219
|
-
| `concat(a, b)` | [▼](./docs/utils.md#concat) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#concat) | Concatenate two `Uint8Array`s
|
|
270
|
+
| Function | MD/Wiki | Description |
|
|
271
|
+
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
272
|
+
| `hexToBytes(hex)` | [▼](./docs/utils.md#hextobytes) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#hextobytes) | Hex string to `Uint8Array` (accepts uppercase, `0x` prefix) |
|
|
273
|
+
| `bytesToHex(bytes)` | [▼](./docs/utils.md#bytestohex) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#bytestohex) | `Uint8Array` to lowercase hex string |
|
|
274
|
+
| `utf8ToBytes(str)` | [▼](./docs/utils.md#utf8tobytes) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#utf8tobytes) | UTF-8 string to `Uint8Array` |
|
|
275
|
+
| `bytesToUtf8(bytes)` | [▼](./docs/utils.md#bytestoutf8) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#bytestoutf8) | `Uint8Array` to UTF-8 string |
|
|
276
|
+
| `base64ToBytes(b64)` | [▼](./docs/utils.md#base64tobytes) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#base64tobytes) | Base64/base64url string to `Uint8Array` (undefined on invalid) |
|
|
277
|
+
| `bytesToBase64(bytes, url?)` | [▼](./docs/utils.md#bytestobase64) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#bytestobase64) | `Uint8Array` to base64 string (url=true for base64url) |
|
|
278
|
+
| `constantTimeEqual(a, b)` | [▼](./docs/utils.md#constanttimeequal) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal) | Constant-time byte comparison (XOR-accumulate) |
|
|
279
|
+
| `wipe(data)` | [▼](./docs/utils.md#wipe) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#wipe) | Zero a typed array in place |
|
|
280
|
+
| `xor(a, b)` | [▼](./docs/utils.md#xor) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#xor) | XOR two equal-length `Uint8Array`s |
|
|
281
|
+
| `concat(a, b)` | [▼](./docs/utils.md#concat) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#concat) | Concatenate two `Uint8Array`s |
|
|
282
|
+
| `hasSIMD()` | [▼](./docs/utils.md#hassimd) · [¶](https://github.com/xero/leviathan-crypto/wiki/utils#hassimd) | Detects WebAssembly SIMD support. Cached after first call. Used internally for CTR/CBC/ChaCha20 dispatch. |
|
|
220
283
|
|
|
221
284
|
### Algorithm correctness and verifications
|
|
222
285
|
|
|
@@ -230,13 +293,14 @@ These helpers are available immediately on import with no `init()` required.
|
|
|
230
293
|
| hkdf_audit | [▼](./docs/hkdf_audit.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/hkdf_audit) | HKDF extract-then-expand, info field domain separation, SerpentStream key derivation |
|
|
231
294
|
|
|
232
295
|
>[!NOTE]
|
|
233
|
-
> Additional documentation available in [./docs](./docs/README.md) and on the
|
|
296
|
+
> Additional documentation available in [./docs](./docs/README.md) and on the
|
|
297
|
+
> [project wiki](https://github.com/xero/leviathan-crypto/wiki/).
|
|
234
298
|
|
|
235
299
|
---
|
|
236
300
|
|
|
237
301
|
## License
|
|
238
302
|
|
|
239
|
-
leviathan is
|
|
303
|
+
leviathan-crypto is released under the [MIT license](./LICENSE).
|
|
240
304
|
|
|
241
305
|
```
|
|
242
306
|
▄▄▄▄▄▄▄▄▄▄
|
|
@@ -260,3 +324,4 @@ leviathan is written under the [MIT license](http://www.opensource.org/licenses/
|
|
|
260
324
|
▀██████▀ ▀████▄▄▄████▀
|
|
261
325
|
▀█████▀
|
|
262
326
|
```
|
|
327
|
+
|
package/SECURITY.md
CHANGED
package/dist/chacha20/index.js
CHANGED
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
import { getInstance, initModule } from '../init.js';
|
|
27
27
|
import { aeadEncrypt, aeadDecrypt, xcEncrypt, xcDecrypt } from './ops.js';
|
|
28
28
|
import { hasSIMD } from '../utils.js';
|
|
29
|
-
const _embedded = () => import('../embedded/
|
|
29
|
+
const _embedded = () => import('../embedded/chacha20.js').then(m => m.WASM_BASE64);
|
|
30
30
|
export async function chacha20Init(mode = 'embedded', opts) {
|
|
31
31
|
return initModule('chacha20', _embedded, mode, opts);
|
|
32
32
|
}
|
package/dist/chacha20/pool.js
CHANGED
|
@@ -20,7 +20,7 @@ let _wasmModule;
|
|
|
20
20
|
async function getWasmModule() {
|
|
21
21
|
if (_wasmModule)
|
|
22
22
|
return _wasmModule;
|
|
23
|
-
const { WASM_BASE64 } = await import('../embedded/
|
|
23
|
+
const { WASM_BASE64 } = await import('../embedded/chacha20.js');
|
|
24
24
|
const bytes = base64ToBytes(WASM_BASE64);
|
|
25
25
|
_wasmModule = await WebAssembly.compile(bytes.buffer);
|
|
26
26
|
return _wasmModule;
|
|
Binary file
|
|
@@ -65,8 +65,8 @@ leviathan-crypto/
|
|
|
65
65
|
│ │ │ ├── cbc.ts ← CBC mode
|
|
66
66
|
│ │ │ ├── ctr.ts ← CTR mode
|
|
67
67
|
│ │ │ └── buffers.ts ← static buffer layout + offset getters
|
|
68
|
-
│ │ ├──
|
|
69
|
-
│ │ │ ├── index.ts ← asc entry point →
|
|
68
|
+
│ │ ├── chacha20/
|
|
69
|
+
│ │ │ ├── index.ts ← asc entry point → chacha20.wasm
|
|
70
70
|
│ │ │ ├── chacha20.ts
|
|
71
71
|
│ │ │ ├── poly1305.ts
|
|
72
72
|
│ │ │ ├── wipe.ts
|
|
@@ -90,7 +90,7 @@ leviathan-crypto/
|
|
|
90
90
|
│ ├── fortuna.ts ← Fortuna CSPRNG (requires serpent + sha2)
|
|
91
91
|
│ ├── embedded/ ← generated base64 files (gitignored, build artifact)
|
|
92
92
|
│ │ ├── serpent.ts
|
|
93
|
-
│ │ ├──
|
|
93
|
+
│ │ ├── chacha20.ts
|
|
94
94
|
│ │ ├── sha2.ts
|
|
95
95
|
│ │ └── sha3.ts
|
|
96
96
|
│ ├── serpent/
|
|
@@ -162,7 +162,7 @@ independent, separate linear memories, separate buffer layouts, no shared state.
|
|
|
162
162
|
| Module | Binary | Primitives |
|
|
163
163
|
|--------|--------|------------|
|
|
164
164
|
| `serpent` | `serpent.wasm` | Serpent-256 block cipher: ECB, CTR mode, CBC mode |
|
|
165
|
-
| `chacha20` | `
|
|
165
|
+
| `chacha20` | `chacha20.wasm` | ChaCha20, Poly1305, ChaCha20-Poly1305 AEAD, XChaCha20-Poly1305 AEAD |
|
|
166
166
|
| `sha2` | `sha2.wasm` | SHA-256, SHA-384, SHA-512, HMAC-SHA256, HMAC-SHA384, HMAC-SHA512 |
|
|
167
167
|
| `sha3` | `sha3.wasm` | SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256 |
|
|
168
168
|
|
|
@@ -188,11 +188,11 @@ parallel AEAD), and `SerpentStreamSealer` / `SerpentStreamOpener` (incremental
|
|
|
188
188
|
streaming AEAD). All Tier 2 classes use HKDF-SHA256 for per-chunk key derivation
|
|
189
189
|
and require both `serpent` and `sha2` to be initialized.
|
|
190
190
|
|
|
191
|
-
**`
|
|
191
|
+
**`chacha20.wasm`**
|
|
192
192
|
ChaCha20 stream cipher (RFC 8439). Poly1305 MAC (RFC 8439 §2.5). ChaCha20-Poly1305
|
|
193
193
|
AEAD (RFC 8439 §2.8). XChaCha20-Poly1305 AEAD (draft-irtf-cfrg-xchacha).
|
|
194
194
|
HChaCha20 subkey derivation.
|
|
195
|
-
Source: `src/asm/
|
|
195
|
+
Source: `src/asm/chacha20/`
|
|
196
196
|
|
|
197
197
|
The chacha20 TypeScript module also includes `pool.ts` (`XChaCha20Poly1305Pool`)
|
|
198
198
|
and `pool.worker.ts`. The worker file compiles to `dist/chacha20/pool.worker.js`
|
|
@@ -255,7 +255,7 @@ await init(['serpent', 'sha3'])
|
|
|
255
255
|
**`'streaming'` (performance path)**
|
|
256
256
|
Uses `WebAssembly.instantiateStreaming()` for maximum load performance. The
|
|
257
257
|
browser compiles the WASM binary while still downloading it. `wasmUrl` is a
|
|
258
|
-
base URL, the loader appends the filename (`serpent.wasm`, `
|
|
258
|
+
base URL, the loader appends the filename (`serpent.wasm`, `chacha20.wasm`, etc.).
|
|
259
259
|
Requires the `.wasm` files to be served with `Content-Type: application/wasm`.
|
|
260
260
|
|
|
261
261
|
```typescript
|
|
@@ -395,7 +395,7 @@ index.ts
|
|
|
395
395
|
re-exports: buffers + serpent + serpent_unrolled + cbc + ctr
|
|
396
396
|
```
|
|
397
397
|
|
|
398
|
-
**ChaCha (`src/asm/
|
|
398
|
+
**ChaCha (`src/asm/chacha20/`)**
|
|
399
399
|
|
|
400
400
|
```
|
|
401
401
|
buffers.ts
|
|
@@ -464,7 +464,7 @@ index.ts
|
|
|
464
464
|
| | | | | isInitialized()
|
|
465
465
|
v v v v v
|
|
466
466
|
embedded/ embedded/ embedded/ embedded/
|
|
467
|
-
serpent.ts
|
|
467
|
+
serpent.ts chacha20.ts sha2.ts sha3.ts
|
|
468
468
|
(each module owns its own embedded thunk, no cross-module imports)
|
|
469
469
|
```
|
|
470
470
|
|
|
@@ -490,7 +490,7 @@ The loader calls the thunk, decodes base64, and instantiates the WASM binary.
|
|
|
490
490
|
| `serpent/stream.ts` | `serpent/index.ts`, `sha2/index.ts`, `utils.ts` | `SerpentCtr`, `HMAC_SHA256`, `HKDF_SHA256`, `constantTimeEqual`, `concat` |
|
|
491
491
|
| `serpent/stream-pool.ts` | `serpent/stream.ts` | `sealChunk`, `openChunk`, `chunkInfo` |
|
|
492
492
|
| `serpent/stream-sealer.ts` | `serpent/index.ts`, `sha2/index.ts`, `utils.ts` | `SerpentCbc`, `HMAC_SHA256`, `HKDF_SHA256`, `concat`, `constantTimeEqual`, `wipe` |
|
|
493
|
-
| `chacha20/index.ts` | `init.ts`, `utils.ts`, `chacha20/types.ts`, `embedded/
|
|
493
|
+
| `chacha20/index.ts` | `init.ts`, `utils.ts`, `chacha20/types.ts`, `embedded/chacha20.ts` | `getInstance`, `initModule`, `Mode`, `InitOpts`, `constantTimeEqual`, `ChaChaExports`, `WASM_BASE64` |
|
|
494
494
|
| `sha2/index.ts` | `init.ts`, `embedded/sha2.ts` | `getInstance`, `initModule`, `Mode`, `InitOpts`, `WASM_BASE64` |
|
|
495
495
|
| `sha3/index.ts` | `init.ts`, `embedded/sha3.ts` | `getInstance`, `initModule`, `Mode`, `InitOpts`, `WASM_BASE64` |
|
|
496
496
|
| `fortuna.ts` | `init.ts`, `serpent/index.ts`, `sha2/index.ts`, `utils.ts` | `isInitialized`, `Serpent`, `SHA256`, `wipe`/`concat`/`utf8ToBytes` |
|
|
@@ -520,7 +520,7 @@ TypeScript, they call Tier 1 classes rather than WASM functions directly.
|
|
|
520
520
|
| `SerpentStreamSealer` | `SerpentCbc` + `HMAC_SHA256` + `HKDF_SHA256` |
|
|
521
521
|
| `SerpentStreamOpener` | `SerpentCbc` + `HMAC_SHA256` + `HKDF_SHA256` |
|
|
522
522
|
|
|
523
|
-
**chacha20/index.ts → asm/
|
|
523
|
+
**chacha20/index.ts → asm/chacha20/**
|
|
524
524
|
|
|
525
525
|
| TS Class | WASM functions called |
|
|
526
526
|
|----------|---------------------|
|
|
@@ -654,7 +654,7 @@ Source: `src/asm/serpent/buffers.ts`
|
|
|
654
654
|
|
|
655
655
|
### ChaCha20 module — 3 pages (192 KB)
|
|
656
656
|
|
|
657
|
-
Source: `src/asm/
|
|
657
|
+
Source: `src/asm/chacha20/buffers.ts`
|
|
658
658
|
|
|
659
659
|
| Offset | Size | Name |
|
|
660
660
|
|--------|------|------|
|
|
@@ -782,16 +782,16 @@ They are the immutable truth, and must never be modified to make tests pass.
|
|
|
782
782
|
|
|
783
783
|
> ## Cross-References
|
|
784
784
|
>
|
|
785
|
-
> - [
|
|
786
|
-
> - [test-suite
|
|
787
|
-
> - [init
|
|
788
|
-
> - [loader
|
|
789
|
-
> - [wasm
|
|
790
|
-
> - [types
|
|
791
|
-
> - [utils
|
|
792
|
-
> - [serpent
|
|
793
|
-
> - [chacha20
|
|
794
|
-
> - [sha2
|
|
795
|
-
> - [sha3
|
|
796
|
-
> - [fortuna
|
|
797
|
-
> - [argon2id
|
|
785
|
+
> - [index](./README.md) — Project Documentation index
|
|
786
|
+
> - [test-suite](./test-suite.md) — testing methodology, vector corpus, and gate discipline
|
|
787
|
+
> - [init](./init.md) — `init()` API, three loading modes, and idempotent behavior
|
|
788
|
+
> - [loader](./loader.md) — internal WASM binary loading strategies (embedded, streaming, manual)
|
|
789
|
+
> - [wasm](./wasm.md) — WebAssembly primer: modules, instances, memory, and the init gate
|
|
790
|
+
> - [types](./types.md) — public TypeScript interfaces (`Hash`, `KeyedHash`, `Blockcipher`, `Streamcipher`, `AEAD`)
|
|
791
|
+
> - [utils](./utils.md) — encoding helpers, `constantTimeEqual`, `wipe`, `randomBytes`
|
|
792
|
+
> - [serpent](./serpent.md) — Serpent-256 TypeScript API (SerpentSeal, SerpentStream, raw modes)
|
|
793
|
+
> - [chacha20](./chacha20.md) — ChaCha20/Poly1305 TypeScript API and XChaCha20-Poly1305 AEAD
|
|
794
|
+
> - [sha2](./sha2.md) — SHA-2 hashes, HMAC, and HKDF TypeScript API
|
|
795
|
+
> - [sha3](./sha3.md) — SHA-3 hashes and SHAKE XOFs TypeScript API
|
|
796
|
+
> - [fortuna](./fortuna.md) — Fortuna CSPRNG with forward secrecy and entropy pooling
|
|
797
|
+
> - [argon2id](./argon2id.md) — Argon2id password hashing and key derivation
|
package/dist/docs/argon2id.md
CHANGED
|
@@ -282,9 +282,9 @@ xc2.dispose();
|
|
|
282
282
|
|
|
283
283
|
> ## Cross-References
|
|
284
284
|
>
|
|
285
|
-
> - [
|
|
286
|
-
> - [sha2
|
|
287
|
-
> - [serpent
|
|
288
|
-
> - [chacha20
|
|
289
|
-
> - [utils
|
|
290
|
-
> - [architecture
|
|
285
|
+
> - [index](./README.md) — Project Documentation index
|
|
286
|
+
> - [sha2](./sha2.md) — HKDF-SHA256 for key expansion from Argon2id root keys
|
|
287
|
+
> - [serpent](./serpent.md) — SerpentSeal: Serpent-256 authenticated encryption (pairs with Argon2id-derived keys)
|
|
288
|
+
> - [chacha20](./chacha20.md) — XChaCha20Poly1305: ChaCha20 authenticated encryption (pairs with Argon2id-derived keys)
|
|
289
|
+
> - [utils](./utils.md) — `randomBytes` for generating salts, `constantTimeEqual` for hash verification
|
|
290
|
+
> - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
|