initial commit

Signed-off-by: Kamal Tufekcic <kamal@lo.sh>

soliton_wasm/README.md

@@ -0,0 +1,122 @@
+# 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/main/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/main/Specification.md) — full cryptographic specification
+- [CHEATSHEET.md](https://git.lo.sh/lo/libsoliton/src/branch/main/CHEATSHEET.md) — API quick reference
+- [Abstract.md](https://git.lo.sh/lo/libsoliton/src/branch/main/Abstract.md) — formal security model
+
+## License
+
+[AGPL-3.0-only](https://git.lo.sh/lo/libsoliton/src/branch/main/LICENSE.md)