18af877ef0
All checks were successful
CI / lint (push) Successful in 1m35s
CI / test-python (push) Successful in 1m46s
CI / test-zig (push) Successful in 1m37s
CI / test-wasm (push) Successful in 1m52s
CI / test (push) Successful in 14m22s
CI / miri (push) Successful in 13m57s
CI / build (push) Successful in 1m6s
CI / fuzz-regression (push) Successful in 9m4s
CI / publish-python (push) Successful in 1m46s
CI / publish (push) Successful in 1m52s
CI / publish-wasm (push) Successful in 1m55s
Signed-off-by: Kamal Tufekcic <kamal@lo.sh>
122 lines
3.9 KiB
Markdown
122 lines
3.9 KiB
Markdown
# soliton-wasm
|
|
|
|
WebAssembly bindings for [libsoliton](https://git.lo.sh/lo/libsoliton) — a pure-Rust post-quantum cryptographic library.
|
|
|
|
## Install
|
|
|
|
Configure the registry once (per project or globally):
|
|
|
|
```bash
|
|
npm config set registry https://git.lo.sh/api/packages/lo/npm/
|
|
```
|
|
|
|
Then install:
|
|
|
|
```bash
|
|
bun add soliton-wasm
|
|
# or
|
|
npm install soliton-wasm
|
|
# or
|
|
pnpm add soliton-wasm
|
|
```
|
|
|
|
For Deno, configure in `deno.json`:
|
|
```json
|
|
{
|
|
"npmRegistry": "https://git.lo.sh/api/packages/lo/npm/"
|
|
}
|
|
```
|
|
```ts
|
|
import * as soliton from "npm:soliton-wasm";
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```js
|
|
import init, * as soliton from "soliton-wasm";
|
|
|
|
// Initialize the WASM module (required once).
|
|
await init();
|
|
|
|
// Identity
|
|
const alice = new soliton.Identity();
|
|
const sig = alice.sign(new TextEncoder().encode("hello"));
|
|
alice.verify(new TextEncoder().encode("hello"), sig);
|
|
const pk = alice.publicKey();
|
|
const fp = alice.fingerprint();
|
|
alice.free(); // zeroize secret key
|
|
|
|
// Primitives
|
|
const hash = soliton.sha3_256(data);
|
|
const tag = soliton.hmacSha3_256(key, data);
|
|
const okm = soliton.hkdfSha3_256(salt, ikm, info, 32);
|
|
|
|
// Auth (zero-knowledge)
|
|
const { ciphertext, token } = soliton.authChallenge(clientPk);
|
|
const proof = soliton.authRespond(clientSk, ciphertext);
|
|
const valid = soliton.authVerify(token, proof);
|
|
|
|
// KEX
|
|
const { publicKey: spkPub, secretKey: spkSk } = soliton.xwingKeygen();
|
|
const spkSig = soliton.kexSignPrekey(bobSk, spkPub);
|
|
const initiated = soliton.kexInitiate(
|
|
alicePk, aliceSk, bobPk, spkPub, 1, spkSig, "lo-crypto-v1",
|
|
);
|
|
|
|
// Ratchet
|
|
const { encryptedPayload, ratchetInitKey } = soliton.Ratchet.encryptFirstMessage(
|
|
chainKey, plaintext, aad,
|
|
);
|
|
const ratchet = soliton.Ratchet.initAlice(rootKey, rik, localFp, remoteFp, peerEk, ekSk);
|
|
const { header, ciphertext: ct } = ratchet.encrypt(plaintext);
|
|
ratchet.free();
|
|
|
|
// Streaming AEAD
|
|
const enc = new soliton.StreamEncryptor(key);
|
|
const hdr = enc.header();
|
|
const chunk = enc.encryptChunk(data, true); // is_last
|
|
enc.free();
|
|
|
|
// Storage
|
|
const ring = new soliton.StorageKeyRing(1, key);
|
|
const blob = ring.encryptBlob("channel", "segment", plaintext);
|
|
const decrypted = ring.decryptBlob("channel", "segment", blob);
|
|
ring.free();
|
|
|
|
// Verification phrase
|
|
const phrase = soliton.verificationPhrase(pkA, pkB);
|
|
```
|
|
|
|
## API
|
|
|
|
Full TypeScript types are included. All byte parameters accept `Uint8Array`. All byte returns are `Uint8Array`. Opaque types (`Identity`, `Ratchet`, `StorageKeyRing`, `StreamEncryptor`, `StreamDecryptor`, `CallKeys`) must be `free()`'d when no longer needed to zeroize secret material.
|
|
|
|
See [CHEATSHEET.md](https://git.lo.sh/lo/libsoliton/src/branch/master/CHEATSHEET.md) for the full API reference with sizes, error codes, and protocol details.
|
|
|
|
## CLI
|
|
|
|
The package includes a Node-based CLI for post-quantum operations without a Rust toolchain:
|
|
|
|
```bash
|
|
bunx soliton-wasm keygen # Generate identity keypair
|
|
bunx soliton-wasm fingerprint identity.pk # SHA3-256 fingerprint
|
|
bunx soliton-wasm sign identity.sk message.txt # Hybrid sign
|
|
bunx soliton-wasm verify identity.pk message.txt # Verify signature
|
|
bunx soliton-wasm xwing-keygen # X-Wing keypair (SPK/OPK)
|
|
bunx soliton-wasm phrase pk_a.bin pk_b.bin # Verification phrase
|
|
bunx soliton-wasm encrypt --key key.bin < in > out # Streaming AEAD encrypt
|
|
bunx soliton-wasm decrypt --key key.bin < in > out # Streaming AEAD decrypt
|
|
bunx soliton-wasm version
|
|
```
|
|
|
|
For better performance, use the native CLI: `cargo install soliton-cli` → `soliton keygen`.
|
|
|
|
## Documentation
|
|
|
|
- [Specification.md](https://git.lo.sh/lo/libsoliton/src/branch/master/Specification.md) — full cryptographic specification
|
|
- [CHEATSHEET.md](https://git.lo.sh/lo/libsoliton/src/branch/master/CHEATSHEET.md) — API quick reference
|
|
- [Abstract.md](https://git.lo.sh/lo/libsoliton/src/branch/master/Abstract.md) — formal security model
|
|
|
|
## License
|
|
|
|
[AGPL-3.0-only](https://git.lo.sh/lo/libsoliton/src/branch/master/LICENSE.md)
|