leviathan-crypto 1.1.0 → 1.3.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/CLAUDE.md +19 -17
- package/README.md +153 -82
- package/SECURITY.md +100 -55
- package/dist/chacha.wasm +0 -0
- package/dist/chacha20/index.js +3 -1
- package/dist/chacha20/types.d.ts +2 -0
- package/dist/docs/architecture.md +4 -2
- package/dist/docs/serpent.md +38 -4
- package/dist/docs/utils.md +21 -0
- package/dist/embedded/chacha.d.ts +1 -1
- package/dist/embedded/chacha.js +1 -1
- package/dist/embedded/serpent.d.ts +1 -1
- package/dist/embedded/serpent.js +1 -1
- package/dist/embedded/sha2.d.ts +1 -1
- package/dist/embedded/sha2.js +1 -1
- package/dist/embedded/sha3.d.ts +1 -1
- package/dist/embedded/sha3.js +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/serpent/index.d.ts +0 -1
- package/dist/serpent/index.js +5 -4
- package/dist/serpent/stream-sealer.d.ts +18 -2
- package/dist/serpent/stream-sealer.js +122 -4
- package/dist/serpent.wasm +0 -0
- package/dist/sha2.wasm +0 -0
- package/dist/sha3.wasm +0 -0
- package/dist/utils.d.ts +5 -0
- package/dist/utils.js +25 -0
- 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
1
|
[](https://github.com/xero/leviathan-crypto/releases/latest) [](https://github.com/xero/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/text0wnz/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,28 +8,63 @@
|
|
|
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
|
-
Nothing runs upon import. Initialization via `init()` is explicit and asynchronous.
|
|
31
64
|
|
|
32
|
-
|
|
65
|
+
Nothing runs upon import. Initialization via `init()` is explicit and
|
|
66
|
+
asynchronous.
|
|
67
|
+
|
|
33
68
|
|
|
34
69
|
## Installation
|
|
35
70
|
|
|
@@ -40,21 +75,42 @@ bun i leviathan-crypto
|
|
|
40
75
|
npm install leviathan-crypto
|
|
41
76
|
```
|
|
42
77
|
|
|
78
|
+
> [!NOTE]
|
|
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. All other primitives (SHA-2, SHA-3, Poly1305) run on any WASM-capable
|
|
82
|
+
> runtime.
|
|
83
|
+
|
|
43
84
|
---
|
|
44
85
|
|
|
45
86
|
## Demos
|
|
46
87
|
|
|
47
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) ]
|
|
48
89
|
|
|
49
|
-
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.
|
|
50
96
|
|
|
51
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) ]
|
|
52
98
|
|
|
53
|
-
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.
|
|
54
105
|
|
|
55
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) ]
|
|
56
107
|
|
|
57
|
-
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.
|
|
58
114
|
|
|
59
115
|
```sh
|
|
60
116
|
bun i -g lvthn # or npm slow mode
|
|
@@ -67,27 +123,33 @@ cat secret.txt | lvthn encrypt -k my.key --armor > secret.enc
|
|
|
67
123
|
|
|
68
124
|
## Primitives
|
|
69
125
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
|
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
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()`. |
|
|
84
149
|
|
|
85
150
|
> [!IMPORTANT]
|
|
86
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.
|
|
87
152
|
|
|
88
|
-
> [!WARNING]
|
|
89
|
-
> `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.
|
|
90
|
-
|
|
91
153
|
---
|
|
92
154
|
|
|
93
155
|
## Quick Start
|
|
@@ -133,7 +195,8 @@ const decrypted = chacha.decrypt(key, nonce, ciphertext)
|
|
|
133
195
|
chacha.dispose()
|
|
134
196
|
```
|
|
135
197
|
|
|
136
|
-
For more examples
|
|
198
|
+
For more examples, including streaming, chunking, hashing, and key derivation,
|
|
199
|
+
see the [examples page](https://github.com/xero/leviathan-crypto/wiki/examples).
|
|
137
200
|
|
|
138
201
|
---
|
|
139
202
|
|
|
@@ -152,7 +215,8 @@ await init(['serpent'], 'manual', { wasmBinary: { serpent: myBuffer } })
|
|
|
152
215
|
|
|
153
216
|
### Tree-shaking with subpath imports
|
|
154
217
|
|
|
155
|
-
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:
|
|
156
220
|
|
|
157
221
|
```typescript
|
|
158
222
|
// Only serpent.wasm ends up in your bundle
|
|
@@ -174,63 +238,69 @@ await chacha20Init()
|
|
|
174
238
|
|
|
175
239
|
---
|
|
176
240
|
|
|
177
|
-
##
|
|
178
|
-
|
|
179
|
-
These helpers are available immediately on import with no `init()` required.
|
|
180
|
-
|
|
181
|
-
| Function | Description |
|
|
182
|
-
| -------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
183
|
-
| [`hexToBytes(hex)`](./docs/utils.md#hextobytes) | Hex string to `Uint8Array` (accepts uppercase, `0x` prefix) |
|
|
184
|
-
| [`bytesToHex(bytes)`](./docs/utils.md#bytestohex) | `Uint8Array` to lowercase hex string |
|
|
185
|
-
| [`utf8ToBytes(str)`](./docs/utils.md#utf8tobytes) | UTF-8 string to `Uint8Array` |
|
|
186
|
-
| [`bytesToUtf8(bytes)`](./docs/utils.md#bytestoutf8) | `Uint8Array` to UTF-8 string |
|
|
187
|
-
| [`base64ToBytes(b64)`](./docs/utils.md#base64tobytes) | Base64/base64url string to `Uint8Array` (undefined on invalid) |
|
|
188
|
-
| [`bytesToBase64(bytes, url?)`](./docs/utils.md#bytestobase64) | `Uint8Array` to base64 string (url=true for base64url) |
|
|
189
|
-
| [`constantTimeEqual(a, b)`](./docs/utils.md#constanttimeequal) | Constant-time byte comparison (XOR-accumulate) |
|
|
190
|
-
| [`wipe(data)`](./docs/utils.md#wipe) | Zero a typed array in place |
|
|
191
|
-
| [`xor(a, b)`](./docs/utils.md#xor) | XOR two equal-length `Uint8Array`s |
|
|
192
|
-
| [`concat(a, b)`](./docs/utils.md#concat) | Concatenate two `Uint8Array`s |
|
|
193
|
-
| [`randomBytes(n)`](./docs/utils.md#randombytes) | Cryptographically secure random bytes via Web Crypto |
|
|
241
|
+
## Documentation
|
|
194
242
|
|
|
195
|
-
|
|
243
|
+
| Document | MD/Wiki | Description |
|
|
244
|
+
| ------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
245
|
+
| architecture | [▼](./docs/architecture.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/architecture) | Architecture overview, build pipeline, module relationships |
|
|
246
|
+
| test-suite | [▼](./docs/test-suite.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/test-suite) | Test suite structure, vector corpus, gate discipline |
|
|
247
|
+
| security | [▼](./SECURITY.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/security_policy) | Project security policy covering posture, disclosure, and scopes |
|
|
248
|
+
|
|
249
|
+
### API Surface
|
|
250
|
+
|
|
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`) |
|
|
265
|
+
|
|
266
|
+
### Utilities
|
|
196
267
|
|
|
197
|
-
|
|
268
|
+
These helpers are available immediately on import with no `init()` required.
|
|
198
269
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
| [
|
|
204
|
-
| [
|
|
205
|
-
| [
|
|
206
|
-
| [
|
|
207
|
-
| [
|
|
208
|
-
| [
|
|
209
|
-
| [
|
|
210
|
-
| [
|
|
211
|
-
| [
|
|
212
|
-
| [init.md](./docs/init.md) | `init()` API and WASM loading modes |
|
|
213
|
-
| [utils.md](./docs/utils.md) | Encoding helpers, `constantTimeEqual`, `wipe`, `randomBytes` |
|
|
214
|
-
| [types.md](./docs/types.md) | TypeScript interfaces (`Hash`, `KeyedHash`, `Blockcipher`, `Streamcipher`, `AEAD`) |
|
|
215
|
-
| [architecture.md](./docs/architecture.md) | Architecture overview, build pipeline, module relationships |
|
|
216
|
-
| [test-suite.md](./docs/test-suite.md) | Test suite structure, vector corpus, gate discipline |
|
|
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. |
|
|
217
283
|
|
|
218
284
|
### Algorithm correctness and verifications
|
|
219
285
|
|
|
220
|
-
| Primitive
|
|
221
|
-
|
|
|
222
|
-
| [
|
|
223
|
-
| [
|
|
224
|
-
| [
|
|
225
|
-
| [
|
|
226
|
-
| [
|
|
227
|
-
| [
|
|
286
|
+
| Primitive | MD/Wiki | Description |
|
|
287
|
+
| ------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
288
|
+
| serpent_audit | [▼](./docs/serpent_audit.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/serpent_audit) | Correctness verification, side-channel analysis, cryptanalytic paper review |
|
|
289
|
+
| chacha_audit | [▼](./docs/chacha_audit.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/chacha_audit) | XChaCha20-Poly1305 correctness, Poly1305 field arithmetic, HChaCha20 nonce extension |
|
|
290
|
+
| sha2_audit | [▼](./docs/sha2_audit.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/sha2_audit) | SHA-256/512/384 correctness, HMAC and HKDF composition, constant verification |
|
|
291
|
+
| sha3_audit | [▼](./docs/sha3_audit.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/sha3_audit) | Keccak permutation correctness, θ/ρ/π/χ/ι step verification, round constant derivation |
|
|
292
|
+
| hmac_audit | [▼](./docs/hmac_audit.md) · [¶](https://github.com/xero/leviathan-crypto/wiki/hmac_audit) | HMAC-SHA256/512/384 construction, key processing, RFC 4231 vector coverage |
|
|
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 |
|
|
294
|
+
|
|
295
|
+
>[!NOTE]
|
|
296
|
+
> Additional documentation available in [./docs](./docs/README.md) and on the
|
|
297
|
+
> [project wiki](https://github.com/xero/leviathan-crypto/wiki/).
|
|
228
298
|
|
|
229
299
|
---
|
|
230
300
|
|
|
231
301
|
## License
|
|
232
302
|
|
|
233
|
-
leviathan is
|
|
303
|
+
leviathan-crypto is released under the [MIT license](./LICENSE).
|
|
234
304
|
|
|
235
305
|
```
|
|
236
306
|
▄▄▄▄▄▄▄▄▄▄
|
|
@@ -254,3 +324,4 @@ leviathan is written under the [MIT license](http://www.opensource.org/licenses/
|
|
|
254
324
|
▀██████▀ ▀████▄▄▄████▀
|
|
255
325
|
▀█████▀
|
|
256
326
|
```
|
|
327
|
+
|