Consume octi-desktop's published wire-format fixtures

Migrates fixture-lock.json from v1 single-source to v2 multi-source and adds octi-desktop as a second pinned producer. Per-module desktop-{meta,clipboard,files}.test.ts files parse each payloadJson through the production deserializer and assert field-by-field against octi-desktop's canonical inputs. Desktop's wire shape differs in a few places — SharedFile.blobKey is a plain UUID (not sha256:<hex>), MetaInfo.deviceBootedAt is a real ISO Instant for the full vector — and the tests pin those values.

sync-ref-resolver.ts and tools/sync-fixtures.ts rewritten for multi-source: parseLockJson accepts both v1 flat and v2 nested shapes (migration-window safety net) and validates internally so callers never see an unvalidated lock. Cache layout migrated to .cache/interop-fixtures/<owner>/<repo>/<sha>/. fetchBytes streams via res.body.getReader() with per-chunk cap so a hostile or mis-pinned upstream can't burn arbitrary memory before we notice; deterministic failures (4xx, size cap) skip retries. Manifest byteLength is now validated against actual bytes on both cold-fetch and warm-cache paths.

Pairs with octi-desktop#56 (the producer) and octi#319 (the other consumer, both merged).

Author: d4rken

.claude/rules/testing.md

@@ -47,13 +47,18 @@ test that pins the format:
 - `crypto/payload.test.ts`, `crypto/streaming-aead.test.ts`, `crypto/tink-keyset.test.ts`
   — wire bytes vs Tink/Android fixtures fetched from
   [`d4rken-org/octi`](https://github.com/d4rken-org/octi) at the commit SHA pinned
-  in `fixture-lock.json`. The cache lives at `.cache/interop-fixtures/<sha>/`
-  (gitignored). `tools/sync-fixtures.ts` is wired as vitest `globalSetup`, so
-  any `pnpm test` invocation refreshes the cache before tests run; explicit
+  in `fixture-lock.json`. `tools/sync-fixtures.ts` is wired as vitest `globalSetup`,
+  so any `pnpm test` invocation refreshes the cache before tests run; explicit
   `pnpm fixtures:sync` does the same thing manually. Loader + materialization
   helpers live at [`src/__interop__/fixture-loader.ts`](../../src/__interop__/fixture-loader.ts).
   Regenerate fixtures upstream in app-main and bump the lockfile here — never
   edit cached files.
+- `__interop__/desktop-{meta,clipboard,files}.test.ts` — same idea pointing at
+  the second source. Fetched from
+  [`d4rken-org/octi-desktop`](https://github.com/d4rken-org/octi-desktop) at the
+  SHA pinned in `fixture-lock.json#sources["d4rken-org/octi-desktop"]`. Pins the
+  per-module wire shape octi-desktop emits (`SharedFile.blobKey` is a plain UUID
+  here, not `sha256:<hex>` like web/android).
 - `modules/<name>.test.ts` — backward-compat JSON for each module.
 - `linking/linking-data.test.ts` — gzip + base64 link payload.
 - `__interop__/published-self-check.test.ts` — pins what octi-web publishes
@@ -63,6 +68,26 @@ test that pins the format:
   files are byte-equal to fresh output. Regenerate via `pnpm fixtures:generate`
   after touching `serializeXxxInfo` or the canonical inputs in the generator.
 
+### Multi-source `fixture-lock.json`
+
+Schema v2 — one entry per upstream producer. Cache laid out as
+`.cache/interop-fixtures/<owner>/<repo>/<sha>/` (gitignored). The parser also
+accepts the legacy v1 flat shape so a hand-edit revert during the migration
+window still parses.
+
+```json
+{
+  "schemaVersion": 2,
+  "sources": {
+    "d4rken-org/octi":         { "ref": "<sha40>", "manifest_sha256": "<sha256>" },
+    "d4rken-org/octi-desktop": { "ref": "<sha40>", "manifest_sha256": "<sha256>" }
+  }
+}
+```
+
+To bump one source, change its `ref` and recompute `manifest_sha256` via
+`sha256sum` on the manifest at that SHA. The other source stays anchored.
+
 When changing wire format intentionally, update the fixture in a dedicated
 commit so the diff is reviewable in isolation.
 

fixture-lock.json

@@ -1,5 +1,13 @@
 {
-  "source": "d4rken-org/octi",
-  "ref": "f7e1089b5ba80590a65b6107e9b050f2caf1881a",
-  "manifest_sha256": "cfa0325bcd00f056b034b9c3795e59b33c3a2a8eb27d248aa767b46093fe666d"
+  "schemaVersion": 2,
+  "sources": {
+    "d4rken-org/octi": {
+      "ref": "f7e1089b5ba80590a65b6107e9b050f2caf1881a",
+      "manifest_sha256": "cfa0325bcd00f056b034b9c3795e59b33c3a2a8eb27d248aa767b46093fe666d"
+    },
+    "d4rken-org/octi-desktop": {
+      "ref": "1e00e71fc60841fda80d7db4f630aa99b1112c9d",
+      "manifest_sha256": "ce2fd860ff124599bfc61a94f824c17c521cf79d744f06bc3551e284e6a37fe4"
+    }
+  }
 }

src/__interop__/desktop-clipboard.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Verify octi-web's ClipboardInfo decoder can consume what octi-desktop publishes.
+ *
+ * Pin: type enum + base64-encoded data. Uint8Array equality holds across the encode
+ * boundary (desktop emits base64; web's deserializer base64-decodes back to bytes).
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  type InteropPublishedModuleFixture,
+  type InteropPublishedVector,
+  loadInteropJson,
+  verifyVectorIntegrity,
+} from "./fixture-loader";
+import { CLIPBOARD_MODULE_ID, deserializeClipboardInfo } from "../modules/clipboard";
+
+const SOURCE = "d4rken-org/octi-desktop";
+const FIXTURE_FILE = "octi-desktop-clipboard.json";
+
+const fixture = loadInteropJson<InteropPublishedModuleFixture>(FIXTURE_FILE, SOURCE);
+
+function vector(name: string): InteropPublishedVector {
+  const v = fixture.vectors.find((x) => x.name === name);
+  if (!v) throw new Error(`vector '${name}' missing in ${fixture.module}`);
+  verifyVectorIntegrity(v);
+  return v;
+}
+
+function decode(v: InteropPublishedVector) {
+  return deserializeClipboardInfo(new TextEncoder().encode(v.payloadJson));
+}
+
+describe("desktop clipboard interop", () => {
+  it("fixture schema sanity", () => {
+    expect(fixture.schemaVersion).toBe(1);
+    expect(fixture.module).toBe(CLIPBOARD_MODULE_ID);
+    expect(fixture.producer).toBe(SOURCE);
+    expect(fixture.vectors.map((v) => v.name)).toEqual([
+      "EMPTY",
+      "SIMPLE_TEXT_short",
+      "SIMPLE_TEXT_unicode",
+    ]);
+  });
+
+  it("'EMPTY' vector decodes to empty data", () => {
+    const info = decode(vector("EMPTY"));
+    expect(info.type).toBe("EMPTY");
+    expect(info.data.byteLength).toBe(0);
+  });
+
+  it("'SIMPLE_TEXT_short' vector decodes ASCII payload", () => {
+    const info = decode(vector("SIMPLE_TEXT_short"));
+    expect(info.type).toBe("SIMPLE_TEXT");
+    expect(info.data).toEqual(new TextEncoder().encode("hello from desktop"));
+  });
+
+  it("'SIMPLE_TEXT_unicode' vector decodes multi-codepoint payload", () => {
+    const info = decode(vector("SIMPLE_TEXT_unicode"));
+    expect(info.type).toBe("SIMPLE_TEXT");
+    expect(info.data).toEqual(new TextEncoder().encode("café 👋 你好 — العربية"));
+  });
+});

src/__interop__/desktop-files.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Verify octi-web's FileShareInfo decoder can consume what octi-desktop publishes.
+ *
+ * Wire-shape differences vs web's own fixtures: desktop emits plain UUID strings for
+ * `SharedFile.blobKey` (via `UUID.randomUUID().toString()`) rather than the
+ * `sha256:<hex>` form web/android use. The connector IDs are desktop-flavoured
+ * (`kserver-prod...77777777-...`). Long size handling: same 8e9-byte `files-large`
+ * vector as web's own producer, exceeds Int.MAX_VALUE — JS Number handles it exactly
+ * through 2^53.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  type InteropPublishedModuleFixture,
+  type InteropPublishedVector,
+  loadInteropJson,
+  verifyVectorIntegrity,
+} from "./fixture-loader";
+import { deserializeFileShareInfo, FILES_MODULE_ID } from "../modules/files";
+
+const SOURCE = "d4rken-org/octi-desktop";
+const FIXTURE_FILE = "octi-desktop-files.json";
+
+const PROD_CONNECTOR =
+  "kserver-prod.kserver.octi.darken.eu-77777777-8888-9999-aaaa-bbbbbbbbbbbb";
+const BETA_CONNECTOR =
+  "kserver-beta.kserver.octi.darken.eu-cccccccc-1111-2222-3333-444444444444";
+
+const fixture = loadInteropJson<InteropPublishedModuleFixture>(FIXTURE_FILE, SOURCE);
+
+function vector(name: string): InteropPublishedVector {
+  const v = fixture.vectors.find((x) => x.name === name);
+  if (!v) throw new Error(`vector '${name}' missing in ${fixture.module}`);
+  verifyVectorIntegrity(v);
+  return v;
+}
+
+function decode(v: InteropPublishedVector) {
+  return deserializeFileShareInfo(new TextEncoder().encode(v.payloadJson));
+}
+
+describe("desktop files interop", () => {
+  it("fixture schema sanity", () => {
+    expect(fixture.schemaVersion).toBe(1);
+    expect(fixture.module).toBe(FILES_MODULE_ID);
+    expect(fixture.producer).toBe(SOURCE);
+    expect(fixture.vectors.map((v) => v.name)).toEqual([
+      "empty",
+      "single-file",
+      "with-multiple-files",
+      "with-delete-requests",
+      "multi-connector",
+      "files-large",
+    ]);
+  });
+
+  it("'empty' vector decodes to empty lists", () => {
+    const info = decode(vector("empty"));
+    expect(info.files).toEqual([]);
+    expect(info.deleteRequests).toEqual([]);
+  });
+
+  it("'single-file' vector decodes one SharedFile with UUID blobKey", () => {
+    const info = decode(vector("single-file"));
+    expect(info.files.length).toBe(1);
+    expect(info.deleteRequests).toEqual([]);
+
+    const f = info.files[0];
+    expect(f.name).toBe("notes.txt");
+    expect(f.mimeType).toBe("text/plain");
+    expect(f.size).toBe(1234);
+    expect(f.blobKey).toBe("00000000-0000-0000-0000-000000000001");
+    expect(f.checksum).toBe("11".repeat(32));
+    expect(f.sharedAt).toBe("2026-05-01T12:00:00Z");
+    expect(f.expiresAt).toBe("2026-05-31T12:00:00Z");
+    expect(f.availableOn).toEqual([PROD_CONNECTOR]);
+    expect(f.connectorRefs).toEqual({ [PROD_CONNECTOR]: "blob-id-aaaa" });
+  });
+
+  it("'with-multiple-files' vector decodes both entries field-by-field", () => {
+    const info = decode(vector("with-multiple-files"));
+    expect(info.files.length).toBe(2);
+    expect(info.deleteRequests).toEqual([]);
+
+    const alpha = info.files[0];
+    expect(alpha.name).toBe("alpha.bin");
+    expect(alpha.mimeType).toBe("application/octet-stream");
+    expect(alpha.size).toBe(256);
+    expect(alpha.blobKey).toBe("00000000-0000-0000-0000-000000000002");
+    expect(alpha.checksum).toBe("22".repeat(32));
+    expect(alpha.sharedAt).toBe("2026-05-01T12:00:00Z");
+    expect(alpha.expiresAt).toBe("2026-05-31T12:00:00Z");
+    expect(alpha.availableOn).toEqual([PROD_CONNECTOR]);
+    expect(alpha.connectorRefs).toEqual({ [PROD_CONNECTOR]: "blob-id-bbbb" });
+
+    const beta = info.files[1];
+    expect(beta.name).toBe("beta.pdf");
+    expect(beta.mimeType).toBe("application/pdf");
+    expect(beta.size).toBe(4096);
+    expect(beta.blobKey).toBe("00000000-0000-0000-0000-000000000003");
+    expect(beta.checksum).toBe("33".repeat(32));
+    expect(beta.sharedAt).toBe("2026-05-01T13:00:00Z");
+    expect(beta.expiresAt).toBe("2026-05-31T13:00:00Z");
+    expect(beta.availableOn).toEqual([PROD_CONNECTOR]);
+    expect(beta.connectorRefs).toEqual({ [PROD_CONNECTOR]: "blob-id-cccc" });
+  });
+
+  it("'with-delete-requests' vector decodes the deleteRequests branch field-by-field", () => {
+    const info = decode(vector("with-delete-requests"));
+    expect(info.files.length).toBe(1);
+    expect(info.deleteRequests.length).toBe(1);
+
+    const f = info.files[0];
+    expect(f.name).toBe("shared.txt");
+    expect(f.mimeType).toBe("text/plain");
+    expect(f.size).toBe(100);
+    expect(f.blobKey).toBe("00000000-0000-0000-0000-000000000004");
+    expect(f.checksum).toBe("44".repeat(32));
+    expect(f.sharedAt).toBe("2026-05-01T12:00:00Z");
+    expect(f.expiresAt).toBe("2026-05-31T12:00:00Z");
+    expect(f.availableOn).toEqual([PROD_CONNECTOR]);
+    expect(f.connectorRefs).toEqual({ [PROD_CONNECTOR]: "blob-id-dddd" });
+
+    const req = info.deleteRequests[0];
+    expect(req.targetDeviceId).toBe("99999999-8888-7777-6666-555555555555");
+    expect(req.blobKey).toBe("00000000-0000-0000-0000-000000000005");
+    expect(req.requestedAt).toBe("2026-05-10T00:00:00Z");
+    expect(req.retainUntil).toBe("2026-05-17T00:00:00Z");
+  });
+
+  it("'multi-connector' vector decodes both connectorRefs entries field-by-field", () => {
+    const info = decode(vector("multi-connector"));
+    expect(info.files.length).toBe(1);
+    expect(info.deleteRequests).toEqual([]);
+
+    const f = info.files[0];
+    expect(f.name).toBe("shared-across.bin");
+    expect(f.mimeType).toBe("application/octet-stream");
+    expect(f.size).toBe(512);
+    expect(f.blobKey).toBe("00000000-0000-0000-0000-000000000007");
+    expect(f.checksum).toBe("77".repeat(32));
+    expect(f.sharedAt).toBe("2026-05-01T12:00:00Z");
+    expect(f.expiresAt).toBe("2026-05-31T12:00:00Z");
+    expect(new Set(f.availableOn)).toEqual(new Set([PROD_CONNECTOR, BETA_CONNECTOR]));
+    expect(f.connectorRefs).toEqual({
+      [PROD_CONNECTOR]: "blob-id-prod-7777",
+      [BETA_CONNECTOR]: "blob-id-beta-7777",
+    });
+  });
+
+  it("'files-large' vector decodes size larger than Int.MAX_VALUE", () => {
+    // Pins large-number handling on the JS consumer. JS Number is double-precision so
+    // 8e9 is exactly representable; the test still asserts equality to catch a
+    // hypothetical type-erasure-to-string regression.
+    const info = decode(vector("files-large"));
+    expect(info.files.length).toBe(1);
+    expect(info.deleteRequests).toEqual([]);
+
+    const f = info.files[0];
+    expect(f.name).toBe("big.iso");
+    expect(f.mimeType).toBe("application/octet-stream");
+    expect(f.size).toBe(8_000_000_000);
+    expect(f.size).toBeGreaterThan(2 ** 31 - 1);
+    expect(f.blobKey).toBe("00000000-0000-0000-0000-000000000006");
+    expect(f.checksum).toBe("66".repeat(32));
+    expect(f.sharedAt).toBe("2026-05-01T12:00:00Z");
+    expect(f.expiresAt).toBe("2026-05-31T12:00:00Z");
+    expect(f.availableOn).toEqual([PROD_CONNECTOR]);
+    expect(f.connectorRefs).toEqual({ [PROD_CONNECTOR]: "blob-id-eeee" });
+  });
+});