# 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)