@moxxy/e2e 0.27.0

package/src/channel.ts

@@ -0,0 +1,124 @@
+/**
+ * `SecureChannel` ties the handshake + framing to a concrete message transport
+ * (a WebSocket, or anything that delivers discrete binary messages in order).
+ *
+ * It runs the two-message handshake first, then transparently seals everything
+ * the caller `send()`s and opens everything that arrives, emitting plaintext via
+ * `onMessage`. Both ends use the same channel object; only the constructor
+ * (`connectInitiator` for the phone, `connectResponder` for the agent shim)
+ * differs. The returned promise resolves once the channel is encrypted and
+ * ready — any handshake failure (length, pin mismatch, bad signature, early
+ * close) rejects it, and the caller must abort the connection.
+ */
+import { FrameOpener, FrameSealer } from './frame.js';
+import {
+  finishInitiator,
+  respond,
+  startInitiator,
+  type SessionKeys,
+} from './handshake.js';
+import type { Identity } from './identity.js';
+
+/** A minimal duplex transport of discrete, ordered binary messages. */
+export interface MessageTransport {
+  /** Send one binary message. */
+  send(data: Uint8Array): void;
+  /** Register the (single) handler for inbound binary messages. */
+  onMessage(handler: (data: Uint8Array) => void): void;
+  /** Register the (single) handler for transport close. */
+  onClose(handler: () => void): void;
+  /** Close the underlying transport. */
+  close(): void;
+}
+
+export interface SecureChannel {
+  /** Encrypt and send one plaintext message. */
+  send(plaintext: Uint8Array): void;
+  /** Register the handler for decrypted inbound messages. Buffered until set. */
+  onMessage(handler: (plaintext: Uint8Array) => void): void;
+  /** Register a close handler (fires on transport close or fatal frame error). */
+  onClose(handler: () => void): void;
+  /** Tear down the channel and the underlying transport. */
+  close(): void;
+}
+
+function makeChannel(transport: MessageTransport, keys: SessionKeys): SecureChannel {
+  const sealer = new FrameSealer(keys.sendKey);
+  const opener = new FrameOpener(keys.recvKey);
+  let onMsg: ((pt: Uint8Array) => void) | null = null;
+  let onClose: (() => void) | null = null;
+  const backlog: Uint8Array[] = [];
+  let closed = false;
+
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    transport.close();
+    onClose?.();
+  };
+
+  transport.onMessage((data) => {
+    let pt: Uint8Array;
+    try {
+      pt = opener.open(data);
+    } catch {
+      // A frame that fails to open is a tampering/replay attempt on the wire —
+      // tear the whole channel down rather than skipping the message.
+      close();
+      return;
+    }
+    if (onMsg) onMsg(pt);
+    else backlog.push(pt);
+  });
+  transport.onClose(() => {
+    if (closed) return;
+    closed = true;
+    onClose?.();
+  });
+
+  return {
+    send: (plaintext) => transport.send(sealer.seal(plaintext)),
+    onMessage: (handler) => {
+      onMsg = handler;
+      while (backlog.length > 0) handler(backlog.shift() as Uint8Array);
+    },
+    onClose: (handler) => {
+      onClose = handler;
+    },
+    close,
+  };
+}
+
+/**
+ * Wait for exactly the next inbound transport message (the handshake reply),
+ * rejecting if the transport closes first. Used only during the handshake.
+ */
+function nextMessage(transport: MessageTransport): Promise<Uint8Array> {
+  return new Promise((resolve, reject) => {
+    transport.onMessage((data) => resolve(data));
+    transport.onClose(() => reject(new Error('proxy-e2e: transport closed during handshake')));
+  });
+}
+
+/** Phone side: pin the agent's public key (from the QR `fp`) and connect. */
+export async function connectInitiator(
+  transport: MessageTransport,
+  pinnedPublicKey: Uint8Array,
+): Promise<SecureChannel> {
+  const { clientHello, state } = startInitiator();
+  const reply = nextMessage(transport);
+  transport.send(clientHello);
+  const keys = finishInitiator(await reply, state, pinnedPublicKey);
+  return makeChannel(transport, keys);
+}
+
+/** Agent side: respond with a signed ServerHello and connect. */
+export async function connectResponder(
+  transport: MessageTransport,
+  identity: Identity,
+): Promise<SecureChannel> {
+  const clientHello = await nextMessage(transport);
+  const { serverHello, keys } = respond(clientHello, identity);
+  transport.send(serverHello);
+  return makeChannel(transport, keys);
+}

package/src/frame.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { utf8 } from './bytes.js';
+import { FrameOpener, FrameSealer } from './frame.js';
+
+const key = (): Uint8Array => sha256(utf8('test-key'));
+
+describe('frame', () => {
+  it('seals and opens a round trip', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(key());
+    const msg = utf8('hello world');
+    expect([...opener.open(sealer.seal(msg))]).toEqual([...msg]);
+  });
+
+  it('preserves ordering across many frames', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(key());
+    for (let i = 0; i < 50; i++) {
+      const m = utf8(`msg-${i}`);
+      expect([...opener.open(sealer.seal(m))]).toEqual([...m]);
+    }
+  });
+
+  it('rejects a tampered ciphertext', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(key());
+    const frame = sealer.seal(utf8('secret'));
+    frame[frame.length - 1] ^= 0x01;
+    expect(() => opener.open(frame)).toThrow();
+  });
+
+  it('rejects a tampered sequence number', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(key());
+    const frame = sealer.seal(utf8('secret'));
+    frame[0] ^= 0x01; // mutate the seq header (bound as AAD)
+    expect(() => opener.open(frame)).toThrow();
+  });
+
+  it('rejects a replayed frame', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(key());
+    const frame = sealer.seal(utf8('once'));
+    opener.open(frame);
+    expect(() => opener.open(frame)).toThrow(/replayed|out-of-order/);
+  });
+
+  it('rejects reordered frames', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(key());
+    const f0 = sealer.seal(utf8('zero'));
+    const f1 = sealer.seal(utf8('one'));
+    opener.open(f1); // accept seq 1 first
+    expect(() => opener.open(f0)).toThrow(/out-of-order/); // seq 0 now stale
+  });
+
+  it('rejects a frame opened with the wrong key', () => {
+    const sealer = new FrameSealer(key());
+    const opener = new FrameOpener(sha256(utf8('other-key')));
+    expect(() => opener.open(sealer.seal(utf8('secret')))).toThrow();
+  });
+});

package/src/frame.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-message AEAD framing for the post-handshake channel.
+ *
+ * Each frame: seq(8 BE) ‖ nonce(24) ‖ XChaCha20-Poly1305(key, nonce, aad=seq).
+ *
+ * The sequence number is bound as AAD and enforced strictly increasing by the
+ * receiver, so the relay (the adversary on the wire) cannot replay, reorder, or
+ * drop-and-resend a frame without the open failing. XChaCha's 192-bit random
+ * nonce means we never have to synchronise a nonce counter across the wire.
+ *
+ * A sealer/opener pair is one-directional; a SecureChannel keeps one of each,
+ * keyed by the directional keys from the handshake.
+ */
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { concatBytes, readU64be, u64be } from './bytes.js';
+
+const SEQ = 8;
+const NONCE = 24;
+const HEADER = SEQ + NONCE; // 32
+
+/** Seals outgoing plaintext into authenticated frames with a monotonic counter. */
+export class FrameSealer {
+  private seq = 0;
+  constructor(private readonly key: Uint8Array) {}
+
+  seal(plaintext: Uint8Array): Uint8Array {
+    const seqBytes = u64be(this.seq);
+    const nonce = randomBytes(NONCE);
+    const ct = xchacha20poly1305(this.key, nonce, seqBytes).encrypt(plaintext);
+    this.seq += 1;
+    return concatBytes(seqBytes, nonce, ct);
+  }
+}
+
+/** Opens incoming frames, rejecting any whose sequence is not strictly increasing. */
+export class FrameOpener {
+  /** Highest sequence accepted so far; -1 means "nothing yet". */
+  private lastSeq = -1;
+  constructor(private readonly key: Uint8Array) {}
+
+  open(frame: Uint8Array): Uint8Array {
+    if (frame.length < HEADER) throw new Error('proxy-e2e: frame too short');
+    const seqBytes = frame.slice(0, SEQ);
+    const seq = readU64be(seqBytes);
+    if (seq <= this.lastSeq) {
+      throw new Error(`proxy-e2e: out-of-order/replayed frame (seq ${seq} <= ${this.lastSeq})`);
+    }
+    const nonce = frame.slice(SEQ, HEADER);
+    const ct = frame.slice(HEADER);
+    // Throws if the tag (over ciphertext + seq AAD) doesn't verify.
+    const pt = xchacha20poly1305(this.key, nonce, seqBytes).decrypt(ct);
+    this.lastSeq = seq;
+    return pt;
+  }
+}

package/src/handshake.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { generateIdentity } from './identity.js';
+import {
+  CLIENT_HELLO_LEN,
+  finishInitiator,
+  respond,
+  SERVER_HELLO_LEN,
+  startInitiator,
+} from './handshake.js';
+
+describe('handshake', () => {
+  it('agrees on matching directional keys', () => {
+    const agent = generateIdentity();
+    const { clientHello, state } = startInitiator();
+    expect(clientHello.length).toBe(CLIENT_HELLO_LEN);
+
+    const { serverHello, keys: rKeys } = respond(clientHello, agent);
+    expect(serverHello.length).toBe(SERVER_HELLO_LEN);
+
+    const iKeys = finishInitiator(serverHello, state, agent.publicKey);
+
+    // Initiator's send is responder's recv, and vice versa.
+    expect([...iKeys.sendKey]).toEqual([...rKeys.recvKey]);
+    expect([...iKeys.recvKey]).toEqual([...rKeys.sendKey]);
+    // The two directions use different keys.
+    expect([...iKeys.sendKey]).not.toEqual([...iKeys.recvKey]);
+  });
+
+  it('rejects a server identity that does not match the pin (spoofing)', () => {
+    const agent = generateIdentity();
+    const attacker = generateIdentity();
+    const { clientHello, state } = startInitiator();
+    const { serverHello } = respond(clientHello, attacker);
+
+    expect(() => finishInitiator(serverHello, state, agent.publicKey)).toThrow(/pinned fingerprint/);
+  });
+
+  it('rejects a tampered ServerHello signature', () => {
+    const agent = generateIdentity();
+    const { clientHello, state } = startInitiator();
+    const { serverHello } = respond(clientHello, agent);
+
+    // Flip a bit inside the signature region (last 64 bytes).
+    const tampered = serverHello.slice();
+    tampered[tampered.length - 1] ^= 0x01;
+
+    expect(() => finishInitiator(tampered, state, agent.publicKey)).toThrow();
+  });
+
+  it('rejects malformed lengths', () => {
+    const agent = generateIdentity();
+    expect(() => respond(new Uint8Array(10), agent)).toThrow(/ClientHello/);
+    const { state } = startInitiator();
+    expect(() => finishInitiator(new Uint8Array(10), state, agent.publicKey)).toThrow(/ServerHello/);
+  });
+});

package/src/handshake.ts

@@ -0,0 +1,136 @@
+/**
+ * The proxy E2E handshake: an authenticated, forward-secret key agreement run
+ * as the first two messages inside the tunnel, before any session traffic.
+ *
+ * Shape (station-to-station-lite / signed ephemeral ECDH):
+ *   initiator (phone) ──ClientHello──▶ responder (agent)
+ *     ClientHello = ephI_pub(32) ‖ nC(16)
+ *   responder ──ServerHello──▶ initiator
+ *     ServerHello = ephR_pub(32) ‖ nS(16) ‖ idPub(32) ‖ sig(64)
+ *     sig = Ed25519.sign(transcript, idSecret)
+ *     transcript = LABEL ‖ ephI_pub ‖ ephR_pub ‖ nC ‖ nS
+ *
+ * The initiator pins `idPub` against the QR fingerprint (constant-time) and
+ * verifies `sig` over the transcript — so a relay (or anyone without the private
+ * key) cannot impersonate the agent. Both sides derive the session keys from the
+ * X25519 shared secret via HKDF; the ephemeral keys give forward secrecy. Keys
+ * are split per direction to prevent reflection.
+ *
+ * The phone is NOT authenticated by key here — it authenticates with the bearer
+ * token at the app layer (unchanged), which now travels encrypted inside this
+ * channel.
+ */
+import { x25519 } from '@noble/curves/ed25519.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { concatBytes, constantTimeEqual, utf8 } from './bytes.js';
+import { sign, verify } from './identity.js';
+
+const LABEL = utf8('moxxy/proxy-e2e/v1');
+const HS_NONCE = 16;
+const X_PUB = 32;
+const ID_PUB = 32;
+const SIG = 64;
+
+export const CLIENT_HELLO_LEN = X_PUB + HS_NONCE; // 48
+export const SERVER_HELLO_LEN = X_PUB + HS_NONCE + ID_PUB + SIG; // 144
+
+/** Directional session keys, named from the owner's point of view. */
+export interface SessionKeys {
+  /** Key for frames this side SENDS. */
+  readonly sendKey: Uint8Array;
+  /** Key for frames this side RECEIVES. */
+  readonly recvKey: Uint8Array;
+}
+
+/** Opaque initiator state carried between {@link startInitiator} and {@link finishInitiator}. */
+export interface InitiatorState {
+  readonly ephSecret: Uint8Array;
+  readonly ephPublic: Uint8Array;
+  readonly clientNonce: Uint8Array;
+}
+
+function transcript(
+  ephIPub: Uint8Array,
+  ephRPub: Uint8Array,
+  nC: Uint8Array,
+  nS: Uint8Array,
+): Uint8Array {
+  return concatBytes(LABEL, ephIPub, ephRPub, nC, nS);
+}
+
+function deriveKeys(shared: Uint8Array, nC: Uint8Array, nS: Uint8Array): { i2r: Uint8Array; r2i: Uint8Array } {
+  const okm = hkdf(sha256, shared, concatBytes(nC, nS), LABEL, 64);
+  return { i2r: okm.slice(0, 32), r2i: okm.slice(32, 64) };
+}
+
+/** Initiator (phone) step 1: produce the ClientHello and the state to finish later. */
+export function startInitiator(): { clientHello: Uint8Array; state: InitiatorState } {
+  const { secretKey: ephSecret, publicKey: ephPublic } = x25519.keygen();
+  const clientNonce = randomBytes(HS_NONCE);
+  return {
+    clientHello: concatBytes(ephPublic, clientNonce),
+    state: { ephSecret, ephPublic, clientNonce },
+  };
+}
+
+/**
+ * Responder (agent) step: consume the ClientHello, produce the signed
+ * ServerHello, and derive the session keys. Throws on a malformed ClientHello.
+ */
+export function respond(
+  clientHello: Uint8Array,
+  identity: { secretKey: Uint8Array; publicKey: Uint8Array },
+): { serverHello: Uint8Array; keys: SessionKeys } {
+  if (clientHello.length !== CLIENT_HELLO_LEN) {
+    throw new Error(`proxy-e2e: bad ClientHello length ${clientHello.length}`);
+  }
+  const ephIPub = clientHello.slice(0, X_PUB);
+  const nC = clientHello.slice(X_PUB, X_PUB + HS_NONCE);
+
+  const { secretKey: ephSecret, publicKey: ephRPub } = x25519.keygen();
+  const nS = randomBytes(HS_NONCE);
+  const sig = sign(transcript(ephIPub, ephRPub, nC, nS), identity.secretKey);
+
+  const shared = x25519.getSharedSecret(ephSecret, ephIPub);
+  const { i2r, r2i } = deriveKeys(shared, nC, nS);
+
+  return {
+    serverHello: concatBytes(ephRPub, nS, identity.publicKey, sig),
+    keys: { sendKey: r2i, recvKey: i2r },
+  };
+}
+
+/**
+ * Initiator (phone) step 2: consume the ServerHello, verify the agent's pinned
+ * identity + signature, and derive the session keys. Throws on length mismatch,
+ * a fingerprint that doesn't match the pin, or an invalid signature — every
+ * failure means "this is not the agent the QR named", so the caller must abort.
+ */
+export function finishInitiator(
+  serverHello: Uint8Array,
+  state: InitiatorState,
+  pinnedPublicKey: Uint8Array,
+): SessionKeys {
+  if (serverHello.length !== SERVER_HELLO_LEN) {
+    throw new Error(`proxy-e2e: bad ServerHello length ${serverHello.length}`);
+  }
+  let off = 0;
+  const ephRPub = serverHello.slice(off, (off += X_PUB));
+  const nS = serverHello.slice(off, (off += HS_NONCE));
+  const idPub = serverHello.slice(off, (off += ID_PUB));
+  const sig = serverHello.slice(off, (off += SIG));
+
+  if (!constantTimeEqual(idPub, pinnedPublicKey)) {
+    throw new Error('proxy-e2e: identity key does not match pinned fingerprint (possible spoofing)');
+  }
+  const t = transcript(state.ephPublic, ephRPub, state.clientNonce, nS);
+  if (!verify(sig, t, idPub)) {
+    throw new Error('proxy-e2e: handshake signature invalid (possible spoofing)');
+  }
+
+  const shared = x25519.getSharedSecret(state.ephSecret, ephRPub);
+  const { i2r, r2i } = deriveKeys(shared, state.clientNonce, nS);
+  return { sendKey: i2r, recvKey: r2i };
+}

package/src/identity.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import {
+  deriveUuid,
+  fingerprint,
+  generateIdentity,
+  publicKeyFromFingerprint,
+  publicKeyFromSecret,
+  sign,
+  UUID_LABEL_LENGTH,
+  verify,
+} from './identity.js';
+
+describe('identity', () => {
+  it('generates a 32-byte keypair whose public key derives from the secret', () => {
+    const id = generateIdentity();
+    expect(id.secretKey.length).toBe(32);
+    expect(id.publicKey.length).toBe(32);
+    expect([...publicKeyFromSecret(id.secretKey)]).toEqual([...id.publicKey]);
+  });
+
+  it('round-trips the fingerprint to the public key', () => {
+    const id = generateIdentity();
+    expect([...publicKeyFromFingerprint(fingerprint(id.publicKey))]).toEqual([...id.publicKey]);
+  });
+
+  it('rejects a malformed fingerprint', () => {
+    expect(() => publicKeyFromFingerprint('AAAA')).toThrow();
+  });
+
+  it('derives a stable, DNS-safe, fixed-length uuid from the public key', () => {
+    const id = generateIdentity();
+    const uuid = deriveUuid(id.publicKey);
+    expect(uuid).toBe(deriveUuid(id.publicKey)); // deterministic
+    expect(uuid.length).toBe(UUID_LABEL_LENGTH);
+    expect(uuid).toMatch(/^[a-z2-7]+$/);
+  });
+
+  it('gives distinct uuids for distinct keys', () => {
+    expect(deriveUuid(generateIdentity().publicKey)).not.toBe(
+      deriveUuid(generateIdentity().publicKey),
+    );
+  });
+
+  it('signs and verifies, and rejects tampered messages/keys', () => {
+    const id = generateIdentity();
+    const msg = new Uint8Array([1, 2, 3, 4, 5]);
+    const sig = sign(msg, id.secretKey);
+    expect(verify(sig, msg, id.publicKey)).toBe(true);
+
+    const tampered = new Uint8Array([1, 2, 3, 4, 6]);
+    expect(verify(sig, tampered, id.publicKey)).toBe(false);
+    expect(verify(sig, msg, generateIdentity().publicKey)).toBe(false);
+  });
+});

package/src/identity.ts

@@ -0,0 +1,73 @@
+/**
+ * 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;
+
+export interface Identity {
+  /** Ed25519 secret key (32 bytes). Never leaves the agent. */
+  readonly secretKey: Uint8Array;
+  /** Ed25519 public key (32 bytes). The identity. */
+  readonly publicKey: Uint8Array;
+}
+
+/** Generate a fresh agent identity. */
+export function generateIdentity(): Identity {
+  const { secretKey, publicKey } = ed25519.keygen();
+  return { secretKey, publicKey };
+}
+
+/** Recover the public key from a stored secret key. */
+export function publicKeyFromSecret(secretKey: Uint8Array): Uint8Array {
+  return ed25519.getPublicKey(secretKey);
+}
+
+/** The QR-carried fingerprint: base64url of the raw 32-byte public key. */
+export function fingerprint(publicKey: Uint8Array): string {
+  return base64urlEncode(publicKey);
+}
+
+/** Parse a fingerprint string back to the 32-byte public key (throws if malformed). */
+export function publicKeyFromFingerprint(fp: string): Uint8Array {
+  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: Uint8Array): string {
+  return base32Encode(sha256(publicKey)).slice(0, UUID_LABEL_LENGTH);
+}
+
+/** Sign a message with the identity's secret key (Ed25519). */
+export function sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array {
+  return ed25519.sign(message, secretKey);
+}
+
+/** Verify an Ed25519 signature against a public key. */
+export function verify(
+  signature: Uint8Array,
+  message: Uint8Array,
+  publicKey: Uint8Array,
+): boolean {
+  try {
+    return ed25519.verify(signature, message, publicKey);
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * `@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';

package/src/node.test.ts

@@ -0,0 +1,38 @@
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { loadOrCreateIdentity } from './node.js';
+
+describe('loadOrCreateIdentity', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'proxy-id-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('creates a fresh identity, persists it 0600, and reloads the same one', async () => {
+    const path = join(dir, 'proxy-identity.key');
+    const first = await loadOrCreateIdentity(path);
+    expect(first.secretKey.length).toBe(32);
+
+    const mode = (await stat(path)).mode & 0o777;
+    expect(mode).toBe(0o600);
+
+    const second = await loadOrCreateIdentity(path);
+    expect([...second.secretKey]).toEqual([...first.secretKey]);
+    expect([...second.publicKey]).toEqual([...first.publicKey]);
+  });
+
+  it('regenerates if the stored key is malformed', async () => {
+    const path = join(dir, 'proxy-identity.key');
+    await loadOrCreateIdentity(path);
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(path, 'garbage', 'utf8');
+    const regenerated = await loadOrCreateIdentity(path);
+    expect(regenerated.secretKey.length).toBe(32);
+    expect((await readFile(path, 'utf8')).trim()).not.toBe('garbage');
+  });
+});