@theermite/morphic-wasm-core 2.0.0-alpha.0

package/README.md

@@ -0,0 +1,76 @@
+# @theermite/morphic-wasm-core
+
+Rust → WebAssembly critical paths for the Morphic Adaptation Engine.
+
+**Status**: B-018 (live). NaCl box primitives shipped.
+CDC ref: F-017 (Tri-layer Rust→WASM critical).
+
+## What it provides
+
+NaCl-compatible authenticated encryption (Curve25519 + XSalsa20 + Poly1305)
+via the audited [`crypto_box`](https://crates.io/crates/crypto_box) crate
+(RustCrypto, pure Rust). Output is byte-identical to `tweetnacl.box`, so
+ciphertexts produced by either side are interchangeable.
+
+Exported API (TypeScript via `wasm-bindgen`):
+
+| Function | Returns | Purpose |
+|----------|---------|---------|
+| `wasmGenerateKeypair()` | `WasmKeyPair` (publicKey + secretKey) | Curve25519 key pair via OsRng (Web Crypto in browser) |
+| `wasmGenerateNonce()` | `Uint8Array` (24 bytes) | Random XSalsa20 nonce |
+| `wasmRandomBytes(len)` | `Uint8Array` | CSPRNG bytes |
+| `wasmEncryptBox(plaintext, recipientPk, senderSk, nonce)` | `Uint8Array` | Authenticated ciphertext (plaintext + 16-byte Poly1305 tag) |
+| `wasmDecryptBox(ciphertext, nonce, senderPk, recipientSk)` | `Uint8Array` | Plaintext, or throws `JsError` on auth failure |
+
+## Build
+
+```bash
+pnpm --filter @theermite/morphic-wasm-core build           # target web
+pnpm --filter @theermite/morphic-wasm-core build:bundler   # target bundler (Vite/webpack)
+```
+
+Output lands in `pkg/` (ESM + `.d.ts` + raw `.wasm`, ~58 KB). The bundle
+is loaded **lazily** by `packages/engine/src/wasm-bridge.ts` so projects
+that don't need WASM crypto pay 0 KB.
+
+## Tests
+
+```bash
+pnpm --filter @theermite/morphic-wasm-core test            # native cargo tests
+```
+
+Runs 9 tests, including 4 property-based tests × 1024 cases (= 4096
+encrypt/decrypt round-trips) covering:
+
+- Round-trip identity (`decrypt(encrypt(m)) == m`)
+- Bit-flip tamper detection (Poly1305 catches every alteration)
+- Wrong-nonce rejection
+- Wrong-key rejection (with a positive sanity check inside)
+
+Plus 5 deterministic fixtures (key/nonce lengths, tag overhead, empty
+plaintext, truncated ciphertext).
+
+## Why Rust → WASM (vs staying on tweetnacl-js)
+
+- **Maintenance**: `tweetnacl-js` is unmaintained since 2020. `crypto_box`
+  is part of the actively-maintained RustCrypto ecosystem.
+- **Audit surface**: pure-Rust, no JS legacy. Smaller dependency tree.
+- **Performance**: WASM crypto ~2-5× faster than JS for sustained workloads
+  (large message batches, many keypairs).
+- **Determinism**: same binary across Node, Deno, browsers — no engine
+  variance on a critical path.
+
+## Defensive assertions (PET §5)
+
+| Function | Assertions |
+|----------|-----------|
+| `wasm_encrypt_box` / `wasm_decrypt_box` | key lengths = 32 bytes; nonce length = 24 bytes |
+| `wasm_decrypt_box` | authentication failures surface as `Err` (no silent corruption) |
+| `wasm_generate_keypair` | uses `OsRng` (browser Web Crypto via `getrandom` js feature) |
+
+Length checks pulled into a single `validate_box_inputs` helper to keep
+the audit trail concentrated.
+
+## License
+
+AGPL-3.0-or-later (matches the rest of the Morphic Engine).

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@theermite/morphic-wasm-core",
+  "version": "2.0.0-alpha.0",
+  "description": "Shinkofa Morphic Adaptation — Rust→WASM critical paths (NaCl box, B-018)",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "./pkg/morphic_wasm_core.js",
+  "types": "./pkg/morphic_wasm_core.d.ts",
+  "files": [
+    "pkg/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "wasm-pack build --target web --release && rm -f pkg/.gitignore",
+    "build:bundler": "wasm-pack build --target bundler --release && rm -f pkg/.gitignore",
+    "test": "cargo test --release",
+    "test:proptest": "cargo test --release --test proptest_roundtrip",
+    "clean": "rm -rf pkg target"
+  }
+}

package/pkg/README.md

@@ -0,0 +1,76 @@
+# @morphic/wasm-core
+
+Rust → WebAssembly critical paths for the Morphic Adaptation Engine.
+
+**Status**: B-018 (live). NaCl box primitives shipped.
+CDC ref: F-017 (Tri-layer Rust→WASM critical).
+
+## What it provides
+
+NaCl-compatible authenticated encryption (Curve25519 + XSalsa20 + Poly1305)
+via the audited [`crypto_box`](https://crates.io/crates/crypto_box) crate
+(RustCrypto, pure Rust). Output is byte-identical to `tweetnacl.box`, so
+ciphertexts produced by either side are interchangeable.
+
+Exported API (TypeScript via `wasm-bindgen`):
+
+| Function | Returns | Purpose |
+|----------|---------|---------|
+| `wasmGenerateKeypair()` | `WasmKeyPair` (publicKey + secretKey) | Curve25519 key pair via OsRng (Web Crypto in browser) |
+| `wasmGenerateNonce()` | `Uint8Array` (24 bytes) | Random XSalsa20 nonce |
+| `wasmRandomBytes(len)` | `Uint8Array` | CSPRNG bytes |
+| `wasmEncryptBox(plaintext, recipientPk, senderSk, nonce)` | `Uint8Array` | Authenticated ciphertext (plaintext + 16-byte Poly1305 tag) |
+| `wasmDecryptBox(ciphertext, nonce, senderPk, recipientSk)` | `Uint8Array` | Plaintext, or throws `JsError` on auth failure |
+
+## Build
+
+```bash
+pnpm --filter @morphic/wasm-core build           # target web
+pnpm --filter @morphic/wasm-core build:bundler   # target bundler (Vite/webpack)
+```
+
+Output lands in `pkg/` (ESM + `.d.ts` + raw `.wasm`, ~58 KB). The bundle
+is loaded **lazily** by `packages/engine/src/wasm-bridge.ts` so projects
+that don't need WASM crypto pay 0 KB.
+
+## Tests
+
+```bash
+pnpm --filter @morphic/wasm-core test            # native cargo tests
+```
+
+Runs 9 tests, including 4 property-based tests × 1024 cases (= 4096
+encrypt/decrypt round-trips) covering:
+
+- Round-trip identity (`decrypt(encrypt(m)) == m`)
+- Bit-flip tamper detection (Poly1305 catches every alteration)
+- Wrong-nonce rejection
+- Wrong-key rejection (with a positive sanity check inside)
+
+Plus 5 deterministic fixtures (key/nonce lengths, tag overhead, empty
+plaintext, truncated ciphertext).
+
+## Why Rust → WASM (vs staying on tweetnacl-js)
+
+- **Maintenance**: `tweetnacl-js` is unmaintained since 2020. `crypto_box`
+  is part of the actively-maintained RustCrypto ecosystem.
+- **Audit surface**: pure-Rust, no JS legacy. Smaller dependency tree.
+- **Performance**: WASM crypto ~2-5× faster than JS for sustained workloads
+  (large message batches, many keypairs).
+- **Determinism**: same binary across Node, Deno, browsers — no engine
+  variance on a critical path.
+
+## Defensive assertions (PET §5)
+
+| Function | Assertions |
+|----------|-----------|
+| `wasm_encrypt_box` / `wasm_decrypt_box` | key lengths = 32 bytes; nonce length = 24 bytes |
+| `wasm_decrypt_box` | authentication failures surface as `Err` (no silent corruption) |
+| `wasm_generate_keypair` | uses `OsRng` (browser Web Crypto via `getrandom` js feature) |
+
+Length checks pulled into a single `validate_box_inputs` helper to keep
+the audit trail concentrated.
+
+## License
+
+AGPL-3.0-or-later (matches the rest of the Morphic Engine).

package/pkg/morphic_wasm_core.d.ts

@@ -0,0 +1,98 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Result type for a generated key pair, exposed to JS as a struct with
+ * `publicKey` and `secretKey` getters returning Uint8Array.
+ */
+export class WasmKeyPair {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+}
+
+/**
+ * Decrypt `ciphertext` using NaCl box.open.
+ *
+ * Inputs:
+ *   - ciphertext: bytes produced by `wasm_encrypt_box` (or any NaCl-compatible
+ *     box implementation, including tweetnacl-js)
+ *   - nonce: 24 bytes used at encryption time
+ *   - sender_pk: 32 bytes (peer's public key)
+ *   - recipient_sk: 32 bytes (our secret key)
+ *
+ * Returns the plaintext, or Err on any authentication failure (wrong key,
+ * tampered ciphertext, wrong nonce, truncated input).
+ */
+export function wasmDecryptBox(ciphertext: Uint8Array, nonce: Uint8Array, sender_pk: Uint8Array, recipient_sk: Uint8Array): Uint8Array;
+
+/**
+ * Encrypt `plaintext` using NaCl box (Curve25519 + XSalsa20Poly1305).
+ *
+ * Inputs:
+ *   - plaintext: arbitrary bytes
+ *   - recipient_pk: 32 bytes (Curve25519 public key)
+ *   - sender_sk: 32 bytes (Curve25519 secret key)
+ *   - nonce: 24 bytes (must be unique per (sender, recipient) pair)
+ *
+ * Output: ciphertext bytes (includes 16-byte Poly1305 tag).
+ */
+export function wasmEncryptBox(plaintext: Uint8Array, recipient_pk: Uint8Array, sender_sk: Uint8Array, nonce: Uint8Array): Uint8Array;
+
+/**
+ * Generate a Curve25519 key pair using the system CSPRNG
+ * (Web Crypto API in browser via `getrandom` js feature).
+ */
+export function wasmGenerateKeypair(): WasmKeyPair;
+
+/**
+ * Sample a fresh nonce using the construction's recommended generator.
+ */
+export function wasmGenerateNonce(): Uint8Array;
+
+/**
+ * Generate `len` random bytes using the system CSPRNG.
+ */
+export function wasmRandomBytes(len: number): Uint8Array;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmkeypair_free: (a: number, b: number) => void;
+    readonly wasmDecryptBox: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly wasmEncryptBox: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly wasmGenerateKeypair: () => number;
+    readonly wasmGenerateNonce: (a: number) => void;
+    readonly wasmRandomBytes: (a: number, b: number) => void;
+    readonly wasmkeypair_publicKey: (a: number, b: number) => void;
+    readonly wasmkeypair_secretKey: (a: number, b: number) => void;
+    readonly __wbindgen_export: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;