feat: M5 Prekey Server + M7 Wire Format

M5: Shade Prekey Server (Hono)
- REST API: register, fetch bundle, replenish, count, delete
- MemoryPrekeyStore for testing/embedded use
- Standalone Docker deployment (Dockerfile + standalone.ts)
- One-time prekey consumption on bundle fetch

M7: Compact binary wire format
- Version-tagged envelopes (PreKeyMessage, RatchetMessage)
- Length-prefixed byte arrays, big-endian integers
- Significantly smaller than JSON (no base64 bloat)
- Roundtrip encode/decode for all message types

100 tests, 0 failures across M1-M5+M7.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/shade-proto/src/index.ts

@@ -0,0 +1 @@
+export { encodeEnvelope, decodeEnvelope, encodePreKeyMessage, encodeRatchetMessage } from './wire.js';

packages/shade-proto/src/wire.ts

@@ -0,0 +1,172 @@
+/**
+ * Shade Wire Format — compact binary encoding for protocol messages.
+ *
+ * Format: [version:1][type:1][payload...]
+ *
+ * Types:
+ *   0x01 = PreKeyMessage
+ *   0x02 = RatchetMessage
+ *
+ * All multi-byte integers are big-endian.
+ * All byte arrays are length-prefixed (2-byte length + data).
+ */
+
+import type { PreKeyMessage, RatchetMessage, ShadeEnvelope } from '@shade/core';
+
+const VERSION = 0x01;
+
+const TYPE_PREKEY = 0x01;
+const TYPE_RATCHET = 0x02;
+
+// ─── Encode ──────────────────────────────────────────────────
+
+export function encodeEnvelope(envelope: ShadeEnvelope): Uint8Array {
+  if (envelope.type === 'prekey') {
+    return encodePreKeyMessage(envelope.content as PreKeyMessage);
+  }
+  return encodeRatchetMessage(envelope.content as RatchetMessage);
+}
+
+export function encodePreKeyMessage(msg: PreKeyMessage): Uint8Array {
+  const ratchetBytes = encodeRatchetMessageInner(msg.message);
+  const parts: Uint8Array[] = [];
+
+  // Header
+  parts.push(new Uint8Array([VERSION, TYPE_PREKEY]));
+
+  // registrationId (4 bytes)
+  parts.push(uint32(msg.registrationId));
+
+  // preKeyId (4 bytes, 0xFFFFFFFF = none)
+  parts.push(uint32(msg.preKeyId ?? 0xFFFFFFFF));
+
+  // signedPreKeyId (4 bytes)
+  parts.push(uint32(msg.signedPreKeyId));
+
+  // ephemeralKey (length-prefixed)
+  parts.push(lpBytes(msg.ephemeralKey));
+
+  // identityDHKey (length-prefixed)
+  parts.push(lpBytes(msg.identityDHKey));
+
+  // embedded ratchet message (length-prefixed)
+  parts.push(lpBytes(ratchetBytes));
+
+  return concat(parts);
+}
+
+export function encodeRatchetMessage(msg: RatchetMessage): Uint8Array {
+  const parts: Uint8Array[] = [];
+  parts.push(new Uint8Array([VERSION, TYPE_RATCHET]));
+  parts.push(encodeRatchetMessageInner(msg));
+  return concat(parts);
+}
+
+function encodeRatchetMessageInner(msg: RatchetMessage): Uint8Array {
+  const parts: Uint8Array[] = [];
+  parts.push(lpBytes(msg.dhPublicKey));
+  parts.push(uint32(msg.previousCounter));
+  parts.push(uint32(msg.counter));
+  parts.push(lpBytes(msg.ciphertext));
+  parts.push(lpBytes(msg.nonce));
+  return concat(parts);
+}
+
+// ─── Decode ──────────────────────────────────────────────────
+
+export function decodeEnvelope(data: Uint8Array): ShadeEnvelope {
+  if (data.length < 2) throw new Error('Too short');
+  const version = data[0];
+  if (version !== VERSION) throw new Error(`Unknown version: ${version}`);
+
+  const type = data[1];
+  const payload = data.slice(2);
+
+  if (type === TYPE_PREKEY) {
+    const msg = decodePreKeyMessageInner(payload);
+    return { type: 'prekey', content: msg, timestamp: 0, senderAddress: '' };
+  }
+  if (type === TYPE_RATCHET) {
+    const msg = decodeRatchetMessageInner(payload, 0).value;
+    return { type: 'ratchet', content: msg, timestamp: 0, senderAddress: '' };
+  }
+  throw new Error(`Unknown type: ${type}`);
+}
+
+function decodePreKeyMessageInner(data: Uint8Array): PreKeyMessage {
+  let offset = 0;
+
+  const registrationId = readUint32(data, offset); offset += 4;
+  const preKeyIdRaw = readUint32(data, offset); offset += 4;
+  const preKeyId = preKeyIdRaw === 0xFFFFFFFF ? undefined : preKeyIdRaw;
+  const signedPreKeyId = readUint32(data, offset); offset += 4;
+
+  const ephemeral = readLP(data, offset); offset = ephemeral.end;
+  const identityDH = readLP(data, offset); offset = identityDH.end;
+  const ratchetData = readLP(data, offset); offset = ratchetData.end;
+
+  const ratchet = decodeRatchetMessageInner(ratchetData.value, 0);
+
+  return {
+    registrationId,
+    preKeyId,
+    signedPreKeyId,
+    ephemeralKey: ephemeral.value,
+    identityDHKey: identityDH.value,
+    message: ratchet.value,
+  };
+}
+
+function decodeRatchetMessageInner(data: Uint8Array, offset: number): { value: RatchetMessage; end: number } {
+  const dhPub = readLP(data, offset); offset = dhPub.end;
+  const prevCounter = readUint32(data, offset); offset += 4;
+  const counter = readUint32(data, offset); offset += 4;
+  const ciphertext = readLP(data, offset); offset = ciphertext.end;
+  const nonce = readLP(data, offset); offset = nonce.end;
+
+  return {
+    value: {
+      dhPublicKey: dhPub.value,
+      previousCounter: prevCounter,
+      counter,
+      ciphertext: ciphertext.value,
+      nonce: nonce.value,
+    },
+    end: offset,
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function uint32(n: number): Uint8Array {
+  const buf = new Uint8Array(4);
+  new DataView(buf.buffer).setUint32(0, n, false);
+  return buf;
+}
+
+function lpBytes(data: Uint8Array): Uint8Array {
+  const len = new Uint8Array(2);
+  new DataView(len.buffer).setUint16(0, data.length, false);
+  return concat([len, data]);
+}
+
+function readUint32(data: Uint8Array, offset: number): number {
+  return new DataView(data.buffer, data.byteOffset + offset).getUint32(0, false);
+}
+
+function readLP(data: Uint8Array, offset: number): { value: Uint8Array; end: number } {
+  const len = new DataView(data.buffer, data.byteOffset + offset).getUint16(0, false);
+  const value = data.slice(offset + 2, offset + 2 + len);
+  return { value, end: offset + 2 + len };
+}
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    result.set(p, offset);
+    offset += p.length;
+  }
+  return result;
+}

packages/shade-proto/tests/wire.test.ts

@@ -0,0 +1,185 @@
+import { describe, test, expect } from 'bun:test';
+import { encodeEnvelope, decodeEnvelope, encodePreKeyMessage, encodeRatchetMessage } from '../src/index.js';
+import type { PreKeyMessage, RatchetMessage, ShadeEnvelope } from '@shade/core';
+
+function randBytes(n: number): Uint8Array {
+  const buf = new Uint8Array(n);
+  crypto.getRandomValues(buf);
+  return buf;
+}
+
+function makeRatchetMessage(): RatchetMessage {
+  return {
+    dhPublicKey: randBytes(32),
+    previousCounter: 42,
+    counter: 7,
+    ciphertext: randBytes(64),
+    nonce: randBytes(12),
+  };
+}
+
+function makePreKeyMessage(): PreKeyMessage {
+  return {
+    registrationId: 12345,
+    preKeyId: 100,
+    signedPreKeyId: 1,
+    ephemeralKey: randBytes(32),
+    identityDHKey: randBytes(32),
+    message: makeRatchetMessage(),
+  };
+}
+
+describe('Wire Format', () => {
+  // ─── RatchetMessage ────────────────────────────────────────
+
+  describe('RatchetMessage', () => {
+    test('encode/decode roundtrip', () => {
+      const msg = makeRatchetMessage();
+      const envelope: ShadeEnvelope = {
+        type: 'ratchet',
+        content: msg,
+        timestamp: Date.now(),
+        senderAddress: 'alice',
+      };
+
+      const encoded = encodeEnvelope(envelope);
+      const decoded = decodeEnvelope(encoded);
+
+      expect(decoded.type).toBe('ratchet');
+      const rm = decoded.content as RatchetMessage;
+      expect(rm.dhPublicKey).toEqual(msg.dhPublicKey);
+      expect(rm.previousCounter).toBe(42);
+      expect(rm.counter).toBe(7);
+      expect(rm.ciphertext).toEqual(msg.ciphertext);
+      expect(rm.nonce).toEqual(msg.nonce);
+    });
+
+    test('compact size (smaller than JSON)', () => {
+      const msg = makeRatchetMessage();
+      const envelope: ShadeEnvelope = {
+        type: 'ratchet',
+        content: msg,
+        timestamp: 0,
+        senderAddress: '',
+      };
+
+      const binary = encodeEnvelope(envelope);
+      const json = new TextEncoder().encode(JSON.stringify(envelope));
+
+      // Binary should be significantly smaller
+      expect(binary.length).toBeLessThan(json.length);
+    });
+  });
+
+  // ─── PreKeyMessage ─────────────────────────────────────────
+
+  describe('PreKeyMessage', () => {
+    test('encode/decode roundtrip with preKeyId', () => {
+      const msg = makePreKeyMessage();
+      const envelope: ShadeEnvelope = {
+        type: 'prekey',
+        content: msg,
+        timestamp: Date.now(),
+        senderAddress: 'alice',
+      };
+
+      const encoded = encodeEnvelope(envelope);
+      const decoded = decodeEnvelope(encoded);
+
+      expect(decoded.type).toBe('prekey');
+      const pm = decoded.content as PreKeyMessage;
+      expect(pm.registrationId).toBe(12345);
+      expect(pm.preKeyId).toBe(100);
+      expect(pm.signedPreKeyId).toBe(1);
+      expect(pm.ephemeralKey).toEqual(msg.ephemeralKey);
+      expect(pm.identityDHKey).toEqual(msg.identityDHKey);
+
+      // Nested ratchet message
+      expect(pm.message.dhPublicKey).toEqual(msg.message.dhPublicKey);
+      expect(pm.message.counter).toBe(msg.message.counter);
+      expect(pm.message.ciphertext).toEqual(msg.message.ciphertext);
+      expect(pm.message.nonce).toEqual(msg.message.nonce);
+    });
+
+    test('encode/decode roundtrip without preKeyId', () => {
+      const msg = makePreKeyMessage();
+      msg.preKeyId = undefined;
+
+      const envelope: ShadeEnvelope = {
+        type: 'prekey',
+        content: msg,
+        timestamp: 0,
+        senderAddress: '',
+      };
+
+      const encoded = encodeEnvelope(envelope);
+      const decoded = decodeEnvelope(encoded);
+
+      const pm = decoded.content as PreKeyMessage;
+      expect(pm.preKeyId).toBeUndefined();
+    });
+  });
+
+  // ─── Edge Cases ────────────────────────────────────────────
+
+  describe('edge cases', () => {
+    test('empty ciphertext', () => {
+      const msg: RatchetMessage = {
+        dhPublicKey: randBytes(32),
+        previousCounter: 0,
+        counter: 0,
+        ciphertext: new Uint8Array(0),
+        nonce: randBytes(12),
+      };
+
+      const encoded = encodeRatchetMessage(msg);
+      const decoded = decodeEnvelope(encoded);
+      expect((decoded.content as RatchetMessage).ciphertext.length).toBe(0);
+    });
+
+    test('large ciphertext (10KB)', () => {
+      const msg: RatchetMessage = {
+        dhPublicKey: randBytes(32),
+        previousCounter: 0,
+        counter: 0,
+        ciphertext: randBytes(10240),
+        nonce: randBytes(12),
+      };
+
+      const encoded = encodeRatchetMessage(msg);
+      const decoded = decodeEnvelope(encoded);
+      expect((decoded.content as RatchetMessage).ciphertext).toEqual(msg.ciphertext);
+    });
+
+    test('max counter values', () => {
+      const msg: RatchetMessage = {
+        dhPublicKey: randBytes(32),
+        previousCounter: 0xFFFFFFFF - 1,
+        counter: 0xFFFFFFFF - 1,
+        ciphertext: randBytes(16),
+        nonce: randBytes(12),
+      };
+
+      const encoded = encodeRatchetMessage(msg);
+      const decoded = decodeEnvelope(encoded);
+      const rm = decoded.content as RatchetMessage;
+      expect(rm.previousCounter).toBe(0xFFFFFFFF - 1);
+      expect(rm.counter).toBe(0xFFFFFFFF - 1);
+    });
+
+    test('rejects unknown version', () => {
+      const data = new Uint8Array([0xFF, 0x01]);
+      expect(() => decodeEnvelope(data)).toThrow('Unknown version');
+    });
+
+    test('rejects unknown type', () => {
+      const data = new Uint8Array([0x01, 0xFF]);
+      expect(() => decodeEnvelope(data)).toThrow('Unknown type');
+    });
+
+    test('rejects too-short data', () => {
+      expect(() => decodeEnvelope(new Uint8Array([0x01]))).toThrow('Too short');
+      expect(() => decodeEnvelope(new Uint8Array([]))).toThrow('Too short');
+    });
+  });
+});

packages/shade-proto/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}