# SDN-JS WASM Modules

This directory contains WebAssembly modules used by the SDN JavaScript library.

## Required WASM Files

The following WASM files should be placed in this directory:

### flatc-crypto.wasm

FlatBuffer encryption and signing module providing:
- AES-GCM encryption/decryption
- Ed25519 signing/verification
- Memory management functions

Build from the flatbuffers repository:
```bash
cd ../flatbuffers
emcc src/crypto.cpp -o ../sdn-js/wasm/flatc-crypto.wasm \
    -s EXPORTED_FUNCTIONS="['_encrypt_bytes', '_decrypt_bytes', '_ed25519_sign', '_ed25519_verify', '_malloc', '_free']" \
    -s EXPORTED_RUNTIME_METHODS="['HEAPU8']" \
    -O3
```

### edge-relays.wasm

Encrypted edge relay registry module (generated by build-edge-registry.ts):
```bash
npx ts-node scripts/build-edge-registry.ts /path/to/relays.json
```

### flatsql.wasm

FlatBuffer SQL virtual table module for browser-based SQLite:
```bash
cd ../flatbuffers-sqlite
emcc src/flatsql.cpp -o ../sdn-js/wasm/flatsql.wasm \
    -s EXPORTED_FUNCTIONS="['_create_virtual_table', '_query_flatbuffer', '_malloc', '_free']" \
    -O3
```

## Loading WASM Modules

The SDN library attempts to load WASM from multiple locations:
1. `./[module].wasm` - Same directory as the application
2. `/[module].wasm` - Root of the web server
3. `https://spacedatanetwork.org/cdn/[module].wasm` - CDN fallback

## CORS Requirements

When serving WASM files, ensure proper CORS headers:
```
Access-Control-Allow-Origin: *
Content-Type: application/wasm
```

## SRI Verification

Each WASM file has an accompanying `.sri` file containing its Subresource Integrity hash:
```html
<script src="sdn.js"
        integrity="sha384-xxxxx"
        crossorigin="anonymous"></script>
```

## Building All WASM Modules

Use the build script to compile all WASM modules:
```bash
npm run build:wasm
```

This requires Emscripten to be installed:
```bash
brew install emscripten  # macOS
apt install emscripten   # Ubuntu
```

### flatsql-wasi.wasm — PIN SPLIT RESOLVED (2026-08-06)

This copy is now **flatsql v1.4.3 (`c075dec`)**, matching the package pin, and it
moved in the SAME COMMIT as the Go host's `env` module — which is the only way it
was ever allowed to move.

**BREAKING FOR EMBEDDERS WHO BUILD THEIR OWN IMPORT OBJECT.** From v1.4.0 the
artifact registers FlatSQL's own `sqlite3_vfs` over seven REQUIRED imports on
module `env`:

```
i32 flatsql_io_open(ptr path, i32 pathLen, i32 flags)
i32 flatsql_io_read(i32 h, ptr dst, i32 len, f64 offset)
i32 flatsql_io_write(i32 h, ptr src, i32 len, f64 offset)
i32 flatsql_io_truncate(i32 h, f64 size)
i32 flatsql_io_sync(i32 h)
f64 flatsql_io_size(i32 h)
i32 flatsql_io_close(i32 h)
```

They are unconditional: a host that does not provide them **cannot instantiate
the module**. There is no degraded mode and no feature flag. Offsets cross as
`f64`, never `i64` — emscripten legalizes i64 at the JS boundary for the browser
target and not for `STANDALONE_WASM`, so an i64 would give the same import
different signatures in the two lanes.

`preloadFlatSQLWASI()` only returns BYTES; nothing in this repo instantiates
them. If you do, satisfy the seven imports — the flatsql package ships ready-made
backends at `flatsql/io` (`createMemoryBackend`, `createNodeFsBackend`,
`createChunkedStoreBackend`). The WASI surface itself is unchanged at six
functions: FlatSQL uses no WASI file descriptors, so **preopens are irrelevant to
its file I/O**.

Host side: the Go daemon embeds its own copy at
`sdn-server/internal/flatsqlrt/flatsql-wasi-noeh.wasm` (sha256 pin test) and
satisfies `env` in `sdn-server/internal/flatsqlrt/hostio.go` over real files
confined to the store directory.

The browser lane was never affected: it loads `flatsql/wasm`, whose emscripten
glue satisfies the seven imports itself (`sdn-js/src/flatsql-io-store.ts`
supplies the storage backend).