134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# ChronoSeal WASM Build Guide
|
|
|
|
ChronoSeal uses a Rust-based WASM runtime to power browser-side attestation logic, signing, hash chaining, VM execution, and mutation commitment preview.
|
|
|
|
## Why WASM
|
|
|
|
The WASM runtime provides a deterministic, sandboxed environment for the following tasks:
|
|
|
|
* generate Ed25519 keypairs in-browser
|
|
* sign canonical heartbeat payloads
|
|
* execute randomized VM opcode programs
|
|
* compute Blake3 hash chain progression
|
|
* preview and commit synthetic gene mutations
|
|
|
|
This enables server/client parity and prevents the private key from leaving the browser runtime.
|
|
|
|
## Build Requirements
|
|
|
|
Install the Rust WASM target and `wasm-pack`:
|
|
|
|
```bash
|
|
rustup target add wasm32-unknown-unknown
|
|
cargo install wasm-pack
|
|
```
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
wasm-pack --version
|
|
```
|
|
|
|
## Build the WASM Module
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
wasm-pack build wasm --target web --release
|
|
rm -rf frontend/pkg
|
|
mv wasm/pkg frontend/pkg
|
|
```
|
|
|
|
`--target web` produces an ES module compatible with the existing frontend JavaScript.
|
|
|
|
`--release` enables optimizations for runtime performance and size.
|
|
|
|
## Output
|
|
|
|
After a successful build, `frontend/pkg/` contains:
|
|
|
|
* `antibot_wasm.js`
|
|
* `antibot_wasm_bg.wasm`
|
|
* `antibot_wasm_bg.js`
|
|
* `antibot_wasm.d.ts`
|
|
* `antibot_wasm_bg.d.ts`
|
|
* `package.json`
|
|
|
|
The frontend expects the WASM package under `frontend/pkg/`.
|
|
|
|
## Runtime Exports
|
|
|
|
The WASM module exports the following functions:
|
|
|
|
* `generate_keypair()` — generate a new Ed25519 keypair and return public key hex
|
|
* `get_public_key()` — return the current public key hex
|
|
* `sign_message(msg)` — sign a UTF-8 payload and return the hex signature
|
|
* `compute_next_hash(prev, ts, entropy, stack, salt)` — compute the next Blake3 chain hash
|
|
* `run_program(b64)` — execute a base64 VM program and return stack state
|
|
* `init_gene_state(gene_size)` — initialise the synthetic gene buffer
|
|
* `preview_gene_commitment(order_b64)` — preview the next gene commitment from a mutation order
|
|
* `commit_gene_preview()` — commit the previewed mutation after successful heartbeat
|
|
* `discard_gene_preview()` — discard the previewed mutation after rejection or error
|
|
* `current_gene_commitment()` — return the current committed gene commitment
|
|
|
|
## Browser Integration
|
|
|
|
The frontend imports the generated module like this:
|
|
|
|
```js
|
|
import init, {
|
|
generate_keypair,
|
|
sign_message,
|
|
compute_next_hash,
|
|
run_program,
|
|
init_gene_state,
|
|
preview_gene_commitment,
|
|
commit_gene_preview,
|
|
discard_gene_preview,
|
|
current_gene_commitment
|
|
} from './pkg/antibot_wasm.js';
|
|
```
|
|
|
|
`await init()` must be called before invoking any other exported function.
|
|
|
|
## Deployment Note
|
|
|
|
The `.wasm` binary must be served with the correct MIME type:
|
|
|
|
```
|
|
Content-Type: application/wasm
|
|
```
|
|
|
|
The built-in Axum static file handler already sets the appropriate MIME type for `.wasm` files.
|
|
|
|
## Build Script
|
|
|
|
Use the convenience script:
|
|
|
|
```bash
|
|
bash scripts/build.sh
|
|
```
|
|
|
|
This builds the WASM package, moves it into `frontend/pkg/`, and builds the server binary.
|
|
|
|
## Recommended Development Flow
|
|
|
|
* For WASM-only changes:
|
|
|
|
```bash
|
|
wasm-pack build wasm --target web
|
|
rm -rf frontend/pkg
|
|
mv wasm/pkg frontend/pkg
|
|
```
|
|
|
|
* For server-only changes:
|
|
|
|
```bash
|
|
cargo build -p server
|
|
```
|
|
|
|
## Notes
|
|
|
|
Generated files in `wasm/pkg/` and `frontend/pkg/` are not tracked in source control.
|
|
They are build artifacts and should be regenerated as part of the release workflow.
|