libsoliton/soliton_wasm

soliton-wasm

WebAssembly bindings for libsoliton — a pure-Rust post-quantum cryptographic library.

Install

Configure the registry once (per project or globally):

npm config set registry https://git.lo.sh/api/packages/lo/npm/

Then install:

bun add soliton-wasm
# or
npm install soliton-wasm
# or
pnpm add soliton-wasm

For Deno, configure in deno.json:

{
  "npmRegistry": "https://git.lo.sh/api/packages/lo/npm/"
}

import * as soliton from "npm:soliton-wasm";

Quick Start

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 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:

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 — full cryptographic specification
• CHEATSHEET.md — API quick reference
• Abstract.md — formal security model

License

AGPL-3.0-only