feat: Sprint 3 — C FFI bindings, WASM compilation, Python example, SDK docs

- Create quicproquo-ffi crate with 7 extern "C" functions: connect,
  login, send, receive, disconnect, last_error, free_string
  (produces libquicproquo_ffi.so and .a)
- Feature-gate quicproquo-core for WASM: identity, hybrid_kem,
  safety_numbers, sealed_sender, app_message, padding, transcript
  all compile to wasm32-unknown-unknown
- Add Python ctypes example (examples/python/qpq_client.py) with
  QpqClient wrapper class and CLI
- Add SDK documentation: FFI reference, WASM guide, qpq-gen generators
- Update Dockerfile for quicproquo-ffi workspace member
This commit is contained in:
2026-03-03 23:47:40 +01:00
parent 9ab306d891
commit db46b72f58
16 changed files with 1402 additions and 80 deletions

View File

@@ -0,0 +1,70 @@
# WASM Integration
The `quicproquo-core` crate supports compilation to `wasm32-unknown-unknown`
when the `native` feature is disabled. This exposes the pure-crypto subset of
the library for use in browsers or other WASM runtimes.
## Building for WASM
```bash
rustup target add wasm32-unknown-unknown
cargo build -p quicproquo-core \
--target wasm32-unknown-unknown \
--no-default-features
```
The `--no-default-features` flag disables the `native` feature, which gates
MLS (openmls), OPAQUE, Cap'n Proto, and tokio -- all of which have dependencies
that do not compile to WASM.
## What is available in WASM mode
The following modules compile to WASM and are fully functional:
| Module | Description |
|-------------------|----------------------------------------------------|
| `identity` | Ed25519 identity keypair (generate, sign, verify) |
| `hybrid_kem` | X25519 + ML-KEM-768 hybrid key encapsulation |
| `safety_numbers` | Signal-style safety number computation |
| `sealed_sender` | Sender identity + Ed25519 signature envelope |
| `app_message` | Rich application message serialisation/parsing |
| `padding` | Message padding to hide plaintext lengths |
| `transcript` | Encrypted tamper-evident message transcript |
| `error` | `CoreError` type |
## What is NOT available in WASM mode
The following require the `native` feature and will not compile to WASM:
- `group` -- MLS group state machine (openmls)
- `keypackage` -- MLS KeyPackage generation
- `hybrid_crypto` -- hybrid HPKE provider for OpenMLS
- `keystore` -- OpenMLS key store with disk persistence
- `opaque_auth` -- OPAQUE cipher suite configuration
Networking (`quicproquo-client`, `quicproquo-server`) is not available in WASM.
## Random number generation
On `wasm32`, the `getrandom` crate is configured with the `js` feature to
use the browser's `crypto.getRandomValues()` API. This is set automatically
in `quicproquo-core/Cargo.toml`:
```toml
[target.'cfg(target_arch = "wasm32")'.dependencies]
getrandom = { version = "0.2", features = ["js"] }
```
This means the WASM build works in browser environments out of the box.
For non-browser WASM runtimes (WASI, etc.), you may need to adjust the
`getrandom` backend.
## Future plans
- **wasm-bindgen JS bindings**: Wrap the WASM-compatible modules with
`#[wasm_bindgen]` annotations to provide a native JavaScript/TypeScript API.
This would allow web frontends to perform client-side encryption without a
server round-trip.
- **wasm-pack integration**: Publish the WASM module as an npm package for
easy consumption in web projects.