pad sync frames to size buckets before encryption so the relay cannot read vault size or operation type off traffic shape (v4.1.9)

@@ -0,0 +1,61 @@1+import { describe, expect, it } from "vitest";2+import {3+  padSyncFrame,4+  syncFrameBucket,5+  unpadSyncFrame,6+} from "./sync-padding";7+8+describe("sync frame padding (E7)", () => {9+  it("round-trips payloads of every shape, including empty", () => {10+    for (const size of [0, 1, 5, 251, 252, 253, 1000, 70_000]) {11+      const payload = Uint8Array.from({ length: size }, (_, i) => (i * 31) & 0xff);12+      expect(Array.from(unpadSyncFrame(padSyncFrame(payload)))).toEqual(13+        Array.from(payload),14+      );15+    }16+  });17+18+  it("collapses every small control frame to one indistinguishable size", () => {19+    // The point of the exercise: a relay must not be able to tell a HELLO from20+    // a REQUEST from a DONE by looking at the frame it is forwarding.21+    const hello = new TextEncoder().encode('{"type":"SYNC_HELLO","vaultId":"' + "a".repeat(64) + '"}');22+    const done = new TextEncoder().encode('{"type":"SYNC_DONE"}');23+    expect(padSyncFrame(hello).length).toBe(padSyncFrame(done).length);24+    expect(padSyncFrame(done).length).toBe(256);25+  });26+27+  it("pins the bucket ladder — cross-platform KAT, must match peach-android", () => {28+    const cases: Array<[number, number]> = [29+      [0, 256],30+      [252, 256],31+      [253, 512],32+      [1024, 2048],33+      [65_532, 65_536],34+      [65_533, 131_072],35+      [200_000, 262_144],36+    ];37+    for (const [payload, expected] of cases) {38+      expect(syncFrameBucket(4 + payload)).toBe(expected);39+      expect(padSyncFrame(new Uint8Array(payload)).length).toBe(expected);40+    }41+  });42+43+  it("keeps large-frame overhead bounded rather than doubling", () => {44+    // Doubling a 12 MiB frame would exceed the 24 MiB transport cap for no45+    // extra privacy, so buckets go linear above 64 KiB.46+    const twelveMiB = 12 * 1024 * 1024;47+    const padded = syncFrameBucket(twelveMiB);48+    expect(padded).toBeGreaterThanOrEqual(twelveMiB);49+    expect(padded - twelveMiB).toBeLessThan(64 * 1024);50+  });51+52+  it("rejects a frame whose declared length exceeds what it carries", () => {53+    const forged = new Uint8Array(256);54+    new DataView(forged.buffer).setUint32(0, 9999, false);55+    expect(() => unpadSyncFrame(forged)).toThrow(/more payload than it carries/);56+  });57+58+  it("rejects a frame shorter than its length header", () => {59+    expect(() => unpadSyncFrame(new Uint8Array(3))).toThrow(/length header/);60+  });61+});

@@ -0,0 +1,63 @@1+// E7: frame padding at the relay boundary.2+//3+// A relay forwards only Noise ciphertext it cannot read, so the one thing it4+// can still learn is traffic SHAPE — frame sizes and timing. Sizes alone5+// distinguish a SYNC_HELLO from a SYNC_ENTRIES carrying a whole vault, and6+// track how a vault grows over time. Padding to size buckets removes that7+// resolution.8+//9+// Wire format of a padded plaintext, BEFORE Noise encryption:10+//11+//     [4-byte big-endian payload length][payload][zero padding to bucket size]12+//13+// The length header is what makes unpadding unambiguous, so the padding may be14+// any bytes; zeros are used because they compress and cost nothing.15+//16+// COORDINATED WIRE CHANGE — peach-android's SyncPadding must bucket17+// identically. A mismatch is loud, not silent: the receiver reads a length18+// that does not fit its frame and rejects it.19+20+const HEADER_BYTES = 4;21+/** Below this, every frame looks the same — covers HELLO/REQUEST/DONE and any22+ *  other small control frame. */23+const MIN_BUCKET = 256;24+/** Above this, buckets grow linearly instead of doubling: doubling a 12 MiB25+ *  frame would blow past the 24 MiB cap for no extra privacy. */26+const LINEAR_BUCKET_STEP = 64 * 1024;27+28+/**29+ * Round a total frame size up to the next bucket: powers of two while small,30+ * then multiples of LINEAR_BUCKET_STEP. Exported for the cross-platform KAT.31+ */32+export function syncFrameBucket(totalBytes: number): number {33+  if (totalBytes <= MIN_BUCKET) return MIN_BUCKET;34+  if (totalBytes <= LINEAR_BUCKET_STEP) {35+    let bucket = MIN_BUCKET;36+    while (bucket < totalBytes) bucket *= 2;37+    return bucket;38+  }39+  return Math.ceil(totalBytes / LINEAR_BUCKET_STEP) * LINEAR_BUCKET_STEP;40+}41+42+export function padSyncFrame(payload: Uint8Array): Uint8Array {43+  const bucket = syncFrameBucket(HEADER_BYTES + payload.length);44+  const out = new Uint8Array(bucket);45+  new DataView(out.buffer).setUint32(0, payload.length, false);46+  out.set(payload, HEADER_BYTES);47+  return out;48+}49+50+export function unpadSyncFrame(padded: Uint8Array): Uint8Array {51+  if (padded.length < HEADER_BYTES) {52+    throw new Error("padded sync frame is shorter than its length header");53+  }54+  const length = new DataView(55+    padded.buffer,56+    padded.byteOffset,57+    padded.byteLength,58+  ).getUint32(0, false);59+  if (length > padded.length - HEADER_BYTES) {60+    throw new Error("padded sync frame declares more payload than it carries");61+  }62+  return padded.slice(HEADER_BYTES, HEADER_BYTES + length);63+}