@moxxy/e2e 0.27.0

package/dist/identity.js

@@ -0,0 +1,57 @@
+/**
+ * The agent's self-sovereign identity for proxy: a long-lived Ed25519 keypair.
+ *
+ * The public key alone determines two things, with no account system involved:
+ *   - the **fingerprint** carried out-of-band in the QR (`?fp=`), which the
+ *     phone pins and uses to authenticate the agent during the handshake;
+ *   - the **uuid** subdomain (`uuid = base32(sha256(pubkey))`), which the relay
+ *     re-derives after verifying a signature, so only the holder of the private
+ *     key can register/reclaim it (preimage-bound, like a WireGuard node key).
+ *
+ * Because the QR pins the fingerprint, the phone can independently recompute the
+ * expected uuid and reject any URL whose subdomain doesn't match — making the
+ * subdomain itself verifiable, not just trusted.
+ */
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { base32Encode, base64urlDecode, base64urlEncode } from './bytes.js';
+/** Number of base32 chars in the uuid label (16 × 5 = 80 bits of preimage strength). */
+export const UUID_LABEL_LENGTH = 16;
+/** Generate a fresh agent identity. */
+export function generateIdentity() {
+    const { secretKey, publicKey } = ed25519.keygen();
+    return { secretKey, publicKey };
+}
+/** Recover the public key from a stored secret key. */
+export function publicKeyFromSecret(secretKey) {
+    return ed25519.getPublicKey(secretKey);
+}
+/** The QR-carried fingerprint: base64url of the raw 32-byte public key. */
+export function fingerprint(publicKey) {
+    return base64urlEncode(publicKey);
+}
+/** Parse a fingerprint string back to the 32-byte public key (throws if malformed). */
+export function publicKeyFromFingerprint(fp) {
+    const key = base64urlDecode(fp);
+    if (key.length !== 32)
+        throw new Error(`bad fingerprint: expected 32 bytes, got ${key.length}`);
+    return key;
+}
+/** Derive the stable uuid subdomain label from a public key. */
+export function deriveUuid(publicKey) {
+    return base32Encode(sha256(publicKey)).slice(0, UUID_LABEL_LENGTH);
+}
+/** Sign a message with the identity's secret key (Ed25519). */
+export function sign(message, secretKey) {
+    return ed25519.sign(message, secretKey);
+}
+/** Verify an Ed25519 signature against a public key. */
+export function verify(signature, message, publicKey) {
+    try {
+        return ed25519.verify(signature, message, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE5E,wFAAwF;AACxF,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AASpC,uCAAuC;AACvC,MAAM,UAAU,gBAAgB;IAC9B,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,mBAAmB,CAAC,SAAqB;IACvD,OAAO,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,SAAqB;IAC/C,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,wBAAwB,CAAC,EAAU;IACjD,MAAM,GAAG,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;IAChC,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAChG,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,SAAqB;IAC9C,OAAO,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACrE,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,IAAI,CAAC,OAAmB,EAAE,SAAqB;IAC7D,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAC1C,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,MAAM,CACpB,SAAqB,EACrB,OAAmB,EACnB,SAAqB;IAErB,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@moxxy/e2e` — the end-to-end secure channel for the proxy tunnel.
+ *
+ * This `.` entry is **pure JS with no Node built-ins**, so it bundles under
+ * Metro/React Native. Key persistence (which needs the filesystem) lives in the
+ * separate `@moxxy/e2e/node` entry.
+ */
+export { generateIdentity, publicKeyFromSecret, fingerprint, publicKeyFromFingerprint, deriveUuid, sign, verify, UUID_LABEL_LENGTH, type Identity, } from './identity.js';
+export { startInitiator, respond, finishInitiator, CLIENT_HELLO_LEN, SERVER_HELLO_LEN, type SessionKeys, type InitiatorState, } from './handshake.js';
+export { FrameSealer, FrameOpener } from './frame.js';
+export { connectInitiator, connectResponder, type SecureChannel, type MessageTransport, } from './channel.js';
+export { base64urlEncode, base64urlDecode, base32Encode, constantTimeEqual, utf8, utf8Decode, } from './bytes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,wBAAwB,EACxB,UAAU,EACV,IAAI,EACJ,MAAM,EACN,iBAAiB,EACjB,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EACd,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,IAAI,EACJ,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@moxxy/e2e` — the end-to-end secure channel for the proxy tunnel.
+ *
+ * This `.` entry is **pure JS with no Node built-ins**, so it bundles under
+ * Metro/React Native. Key persistence (which needs the filesystem) lives in the
+ * separate `@moxxy/e2e/node` entry.
+ */
+export { generateIdentity, publicKeyFromSecret, fingerprint, publicKeyFromFingerprint, deriveUuid, sign, verify, UUID_LABEL_LENGTH, } from './identity.js';
+export { startInitiator, respond, finishInitiator, CLIENT_HELLO_LEN, SERVER_HELLO_LEN, } from './handshake.js';
+export { FrameSealer, FrameOpener } from './frame.js';
+export { connectInitiator, connectResponder, } from './channel.js';
+export { base64urlEncode, base64urlDecode, base32Encode, constantTimeEqual, utf8, utf8Decode, } from './bytes.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,wBAAwB,EACxB,UAAU,EACV,IAAI,EACJ,MAAM,EACN,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EACd,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,IAAI,EACJ,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,10 @@
+import { type Identity } from './identity.js';
+/** Default on-disk location of the agent's proxy identity secret key. */
+export declare function defaultIdentityPath(): string;
+/**
+ * Load the agent identity from disk, generating and persisting a fresh one on
+ * first run. The returned identity is stable across restarts, so the agent keeps
+ * the same uuid subdomain and the same pinned fingerprint.
+ */
+export declare function loadOrCreateIdentity(path?: string): Promise<Identity>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AASA,OAAO,EAAyC,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErF,yEAAyE;AACzE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBlG"}

package/dist/node.js

@@ -0,0 +1,45 @@
+/**
+ * Node-only identity persistence for `@moxxy/e2e`. Kept off the `.` export so the
+ * RN bundle never pulls `node:fs`. The secret key is stored once per install at
+ * `~/.moxxy/proxy-identity.key` (mode 0600, atomic write — same invariant the
+ * vault/sessions use), and the public key is derived from it on load.
+ */
+import { readFile } from 'node:fs/promises';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import { generateIdentity, publicKeyFromSecret } from './identity.js';
+/** Default on-disk location of the agent's proxy identity secret key. */
+export function defaultIdentityPath() {
+    return moxxyPath('proxy-identity.key');
+}
+/**
+ * Load the agent identity from disk, generating and persisting a fresh one on
+ * first run. The returned identity is stable across restarts, so the agent keeps
+ * the same uuid subdomain and the same pinned fingerprint.
+ */
+export async function loadOrCreateIdentity(path = defaultIdentityPath()) {
+    let hex = null;
+    try {
+        hex = (await readFile(path, 'utf8')).trim();
+    }
+    catch (err) {
+        // Missing file → first run (generate below). Anything else (e.g. EACCES) is real.
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    if (hex !== null) {
+        try {
+            const secretKey = hexToBytes(hex);
+            if (secretKey.length === 32) {
+                return { secretKey, publicKey: publicKeyFromSecret(secretKey) };
+            }
+        }
+        catch {
+            // Malformed contents → fall through and regenerate.
+        }
+    }
+    const identity = generateIdentity();
+    await writeFileAtomic(path, bytesToHex(identity.secretKey), { mode: 0o600 });
+    return identity;
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAiB,MAAM,eAAe,CAAC;AAErF,yEAAyE;AACzE,MAAM,UAAU,mBAAmB;IACjC,OAAO,SAAS,CAAC,oBAAoB,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAe,mBAAmB,EAAE;IAC7E,IAAI,GAAG,GAAkB,IAAI,CAAC;IAC9B,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kFAAkF;QAClF,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC;IAClE,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,SAAS,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;gBAC5B,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,MAAM,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7E,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@moxxy/e2e",
+  "version": "0.27.0",
+  "description": "End-to-end-encrypted secure channel for the proxy tunnel: a signed-ephemeral-ECDH handshake (Ed25519 identity pinned out-of-band via the QR fingerprint) + XChaCha20-Poly1305 framing, so a relay between agent and phone sees only ciphertext it cannot forge or read. Pure JS (@noble), no Node built-ins on the '.' export, so it bundles cleanly under Metro/React Native.",
+  "keywords": [
+    "moxxy",
+    "e2e",
+    "encryption",
+    "noble"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/e2e"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@moxxy/sdk": "0.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/bytes.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  base32Encode,
+  base64urlDecode,
+  base64urlEncode,
+  concatBytes,
+  constantTimeEqual,
+  readU64be,
+  u64be,
+  utf8,
+} from './bytes.js';
+
+describe('concatBytes', () => {
+  it('joins parts in order', () => {
+    expect([...concatBytes(new Uint8Array([1, 2]), new Uint8Array([3]))]).toEqual([1, 2, 3]);
+  });
+  it('handles empty input', () => {
+    expect(concatBytes().length).toBe(0);
+  });
+});
+
+describe('constantTimeEqual', () => {
+  it('is true for equal arrays', () => {
+    expect(constantTimeEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3]))).toBe(true);
+  });
+  it('is false for different contents or lengths', () => {
+    expect(constantTimeEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 4]))).toBe(false);
+    expect(constantTimeEqual(new Uint8Array([1, 2]), new Uint8Array([1, 2, 3]))).toBe(false);
+  });
+});
+
+describe('u64be / readU64be', () => {
+  it('round-trips small and large values', () => {
+    for (const n of [0, 1, 255, 256, 65535, 2 ** 32, 2 ** 32 + 7, Number.MAX_SAFE_INTEGER]) {
+      expect(readU64be(u64be(n))).toBe(n);
+    }
+  });
+  it('rejects out-of-range values', () => {
+    expect(() => u64be(-1)).toThrow();
+    expect(() => u64be(Number.MAX_SAFE_INTEGER + 1)).toThrow();
+  });
+});
+
+describe('base64url', () => {
+  it('matches a known vector', () => {
+    expect(base64urlEncode(utf8('foobar'))).toBe('Zm9vYmFy');
+  });
+  it('uses url-safe alphabet (- and _, no padding)', () => {
+    const encoded = base64urlEncode(new Uint8Array([251, 255, 191, 255]));
+    expect(encoded).not.toMatch(/[+/=]/);
+  });
+  it('round-trips arbitrary bytes of every length mod 3', () => {
+    for (let len = 0; len < 35; len++) {
+      const bytes = new Uint8Array(len).map((_, i) => (i * 37 + 11) & 0xff);
+      expect([...base64urlDecode(base64urlEncode(bytes))]).toEqual([...bytes]);
+    }
+  });
+  it('rejects invalid characters', () => {
+    expect(() => base64urlDecode('not valid!')).toThrow();
+  });
+});
+
+describe('base32Encode', () => {
+  it('matches a known lowercase vector', () => {
+    expect(base32Encode(utf8('foobar'))).toBe('mzxw6ytboi');
+  });
+  it('produces only DNS-label-safe chars', () => {
+    const out = base32Encode(new Uint8Array(40).map((_, i) => (i * 53) & 0xff));
+    expect(out).toMatch(/^[a-z2-7]+$/);
+  });
+});

package/src/bytes.ts

@@ -0,0 +1,146 @@
+/**
+ * Small, dependency-free byte helpers shared by the handshake/frame/identity
+ * modules. Encodings are hand-rolled (not `node:buffer`) so the `.` export stays
+ * RN-safe — React Native has no global `Buffer`.
+ */
+
+/** Concatenate byte arrays into one fresh `Uint8Array`. */
+export function concatBytes(...parts: readonly Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+
+/**
+ * Constant-time equality for two byte arrays. Returns false immediately on a
+ * length mismatch (lengths here are public — fixed-size keys), then XOR-folds
+ * every byte so the compare time doesn't depend on where the first difference
+ * is. Used for the pinned-fingerprint check, where a timing leak would let an
+ * attacker probe the expected key byte by byte.
+ */
+export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= (a[i] as number) ^ (b[i] as number);
+  return diff === 0;
+}
+
+/** UTF-8 encode without depending on `Buffer` (TextEncoder is in Node + RN). */
+export function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+/** UTF-8 decode (TextDecoder is in Node + modern RN/Hermes). */
+export function utf8Decode(b: Uint8Array): string {
+  return new TextDecoder().decode(b);
+}
+
+/**
+ * Big-endian 8-byte encoding of a non-negative JS number. Written as two 32-bit
+ * halves to avoid `BigInt`/`setBigUint64` (Hermes/older RN engines are spotty);
+ * safe for any sequence counter below `Number.MAX_SAFE_INTEGER`.
+ */
+export function u64be(n: number): Uint8Array {
+  if (!Number.isInteger(n) || n < 0 || n > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError(`u64be: out of range: ${n}`);
+  }
+  const out = new Uint8Array(8);
+  const hi = Math.floor(n / 0x1_0000_0000);
+  const lo = n >>> 0;
+  out[0] = (hi >>> 24) & 0xff;
+  out[1] = (hi >>> 16) & 0xff;
+  out[2] = (hi >>> 8) & 0xff;
+  out[3] = hi & 0xff;
+  out[4] = (lo >>> 24) & 0xff;
+  out[5] = (lo >>> 16) & 0xff;
+  out[6] = (lo >>> 8) & 0xff;
+  out[7] = lo & 0xff;
+  return out;
+}
+
+/** Decode a big-endian 8-byte counter back to a JS number. */
+export function readU64be(b: Uint8Array, off = 0): number {
+  const hi =
+    ((b[off] as number) << 24) |
+    ((b[off + 1] as number) << 16) |
+    ((b[off + 2] as number) << 8) |
+    (b[off + 3] as number);
+  const lo =
+    ((b[off + 4] as number) << 24) |
+    ((b[off + 5] as number) << 16) |
+    ((b[off + 6] as number) << 8) |
+    (b[off + 7] as number);
+  return (hi >>> 0) * 0x1_0000_0000 + (lo >>> 0);
+}
+
+// ---------------------------------------------------------------------------
+// base64url (RFC 4648 §5, no padding) — used to carry the 32-byte Ed25519
+// public-key fingerprint in the QR/connect URL.
+// ---------------------------------------------------------------------------
+
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+export function base64urlEncode(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] as number;
+    const b1 = i + 1 < bytes.length ? (bytes[i + 1] as number) : 0;
+    const b2 = i + 2 < bytes.length ? (bytes[i + 2] as number) : 0;
+    out += B64URL[b0 >> 2];
+    out += B64URL[((b0 & 0x03) << 4) | (b1 >> 4)];
+    if (i + 1 < bytes.length) out += B64URL[((b1 & 0x0f) << 2) | (b2 >> 6)];
+    if (i + 2 < bytes.length) out += B64URL[b2 & 0x3f];
+  }
+  return out;
+}
+
+export function base64urlDecode(s: string): Uint8Array {
+  const lut = new Int16Array(128).fill(-1);
+  for (let i = 0; i < B64URL.length; i++) lut[B64URL.charCodeAt(i)] = i;
+  const clean = s.trim();
+  const out: number[] = [];
+  let buf = 0;
+  let bits = 0;
+  for (const ch of clean) {
+    const code = ch.charCodeAt(0);
+    const v = code < 128 ? lut[code] : -1;
+    if (v === undefined || v < 0) throw new Error('base64urlDecode: invalid character');
+    buf = (buf << 6) | v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out.push((buf >> bits) & 0xff);
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+// ---------------------------------------------------------------------------
+// base32 (RFC 4648 §6, lowercase, no padding) — used for the uuid subdomain
+// label. Lowercase a-z + 2-7 is a valid DNS label, and the alphabet avoids the
+// visually ambiguous 0/1/8/9.
+// ---------------------------------------------------------------------------
+
+const B32 = 'abcdefghijklmnopqrstuvwxyz234567';
+
+export function base32Encode(bytes: Uint8Array): string {
+  let out = '';
+  let buf = 0;
+  let bits = 0;
+  for (const byte of bytes) {
+    buf = (buf << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += B32[(buf >> bits) & 0x1f];
+    }
+  }
+  if (bits > 0) out += B32[(buf << (5 - bits)) & 0x1f];
+  return out;
+}

package/src/channel.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+import { utf8 } from './bytes.js';
+import { connectInitiator, connectResponder, type MessageTransport } from './channel.js';
+import { generateIdentity } from './identity.js';
+
+/**
+ * A pair of in-memory transports modelling the relay link: a message sent on one
+ * end is delivered (async, ordered) to the other. An optional per-direction
+ * `mutate` hook lets a test play the tampering relay.
+ */
+function makePair(opts: {
+  mutateAtoB?: (d: Uint8Array) => Uint8Array | null;
+  mutateBtoA?: (d: Uint8Array) => Uint8Array | null;
+} = {}): [MessageTransport, MessageTransport] {
+  let aMsg: ((d: Uint8Array) => void) | null = null;
+  let bMsg: ((d: Uint8Array) => void) | null = null;
+  let aClose: (() => void) | null = null;
+  let bClose: (() => void) | null = null;
+  let open = true;
+
+  const deliver = (
+    to: () => ((d: Uint8Array) => void) | null,
+    mutate: ((d: Uint8Array) => Uint8Array | null) | undefined,
+    d: Uint8Array,
+  ): void => {
+    if (!open) return;
+    const out = mutate ? mutate(d) : d;
+    if (out === null) return; // dropped by the relay
+    queueMicrotask(() => to()?.(out));
+  };
+
+  const a: MessageTransport = {
+    send: (d) => deliver(() => bMsg, opts.mutateAtoB, d),
+    onMessage: (h) => {
+      aMsg = h;
+    },
+    onClose: (h) => {
+      aClose = h;
+    },
+    close: () => {
+      if (!open) return;
+      open = false;
+      queueMicrotask(() => {
+        aClose?.();
+        bClose?.();
+      });
+    },
+  };
+  const b: MessageTransport = {
+    send: (d) => deliver(() => aMsg, opts.mutateBtoA, d),
+    onMessage: (h) => {
+      bMsg = h;
+    },
+    onClose: (h) => {
+      bClose = h;
+    },
+    close: () => {
+      if (!open) return;
+      open = false;
+      queueMicrotask(() => {
+        aClose?.();
+        bClose?.();
+      });
+    },
+  };
+  return [a, b];
+}
+
+const collect = (ch: { onMessage: (cb: (p: Uint8Array) => void) => void }): string[] => {
+  const out: string[] = [];
+  ch.onMessage((p) => out.push(new TextDecoder().decode(p)));
+  return out;
+};
+
+describe('SecureChannel', () => {
+  it('establishes and exchanges messages both ways', async () => {
+    const agent = generateIdentity();
+    const [phoneT, agentT] = makePair();
+
+    const [phone, agentCh] = await Promise.all([
+      connectInitiator(phoneT, agent.publicKey),
+      connectResponder(agentT, agent),
+    ]);
+
+    const gotByAgent = collect(agentCh);
+    const gotByPhone = collect(phone);
+
+    phone.send(utf8('hello from phone'));
+    agentCh.send(utf8('hello from agent'));
+    await new Promise((r) => setTimeout(r, 5));
+
+    expect(gotByAgent).toEqual(['hello from phone']);
+    expect(gotByPhone).toEqual(['hello from agent']);
+  });
+
+  it('buffers messages received before a handler is registered', async () => {
+    const agent = generateIdentity();
+    const [phoneT, agentT] = makePair();
+    const [phone, agentCh] = await Promise.all([
+      connectInitiator(phoneT, agent.publicKey),
+      connectResponder(agentT, agent),
+    ]);
+
+    phone.send(utf8('early'));
+    await new Promise((r) => setTimeout(r, 5)); // arrives before onMessage set
+
+    const got = collect(agentCh); // registered late → should flush backlog
+    expect(got).toEqual(['early']);
+  });
+
+  it('rejects the handshake when the phone pins the wrong key (spoofing)', async () => {
+    const agent = generateIdentity();
+    const attacker = generateIdentity();
+    const [phoneT, agentT] = makePair();
+
+    // The agent responds with its real key, but the phone pins the attacker's.
+    void connectResponder(agentT, agent);
+    await expect(connectInitiator(phoneT, attacker.publicKey)).rejects.toThrow(/pinned fingerprint/);
+  });
+
+  it('closes the channel when the relay tampers with a frame', async () => {
+    const agent = generateIdentity();
+    let tamperArmed = false;
+    const [phoneT, agentT] = makePair({
+      mutateAtoB: (d) => {
+        // Leave the handshake (first message) intact; corrupt the first data frame.
+        if (!tamperArmed) {
+          tamperArmed = true;
+          return d;
+        }
+        const copy = d.slice();
+        copy[copy.length - 1] ^= 0x01;
+        return copy;
+      },
+    });
+
+    const [phone, agentCh] = await Promise.all([
+      connectInitiator(phoneT, agent.publicKey),
+      connectResponder(agentT, agent),
+    ]);
+
+    const got = collect(agentCh);
+    let closed = false;
+    agentCh.onClose(() => {
+      closed = true;
+    });
+
+    phone.send(utf8('tampered payload'));
+    await new Promise((r) => setTimeout(r, 5));
+
+    expect(got).toEqual([]); // never delivered
+    expect(closed).toBe(true); // channel torn down on tamper
+  });
+});