@fairfox/polly 0.70.0 → 0.71.0

package/dist/src/shared/lib/mesh-network-adapter.d.ts

@@ -45,6 +45,41 @@ import { type SigningKeyPair } from "./signing";
  * encryption mode. See the file-level comment for the per-document key
  * follow-up. */
 export declare const DEFAULT_MESH_KEY_ID = "polly-mesh-default";
+/**
+ * Control-message type tags. Every mesh message carries a single tag
+ * byte at the front of its plaintext payload, after decryption and
+ * signature verification. The tag discriminates the inner contents so
+ * future control flows (RFC-043 revocation propagation, future RFCs)
+ * can share the same encrypted-signed envelope without re-versioning.
+ *
+ * 0x00 is the default Automerge sync-message channel that polly has
+ * carried since the first cut. 0x01 and 0x02 are reserved for the
+ * revocation flow designed in RFC-043; the adapter recognises them at
+ * receive time but does not yet act on the payload — that lands in
+ * the second RFC-043 PR. Tags 0x03 and above are unassigned; a
+ * receiver that sees one emits `drop:unknown-control-type` and the
+ * message is dropped.
+ *
+ * Wire format break: polly 0.70 and earlier do not prepend the tag
+ * and do not strip it on receive. Mixing 0.70 and 0.71-plus peers on
+ * the same mesh produces garbage on both sides. The break is
+ * acknowledged in RFC-043 and required for the protocol-level
+ * revocation feature; the alternative (a separate WebRTC data
+ * channel) doubles transport complexity.
+ */
+export declare const MESH_CONTROL_TYPE: {
+    /** Automerge sync message — the default channel. */
+    readonly Sync: 0;
+    /** A signed RevocationRecord (RFC-043). Receive-side dispatch is
+     *  wired in this PR; the apply-and-persist behaviour lands in the
+     *  next RFC-043 PR. */
+    readonly Revocation: 1;
+    /** A revocation-set summary exchanged on every new peer connection
+     *  to gossip revocations to peers that were offline at issue-time
+     *  (RFC-043). Same staging as Revocation. */
+    readonly RevocationSummary: 2;
+};
+export type MeshControlType = (typeof MESH_CONTROL_TYPE)[keyof typeof MESH_CONTROL_TYPE];
 /**
  * A mesh keyring holds the local peer's signing identity, the public keys
  * of every peer the local node will accept messages from, the symmetric
@@ -106,6 +141,22 @@ export interface MeshNetworkAdapterOptions {
      * messages. Defaults to true (encrypt + sign, the full $meshState
      * posture). */
     encryptionEnabled?: boolean;
+    /**
+     * Optional handler for non-Sync control messages (RFC-043). Called
+     * after signature verification and decryption with the type tag,
+     * the body bytes that followed the tag, and the verified senderId.
+     * The handler owns the apply-and-persist behaviour for whichever
+     * control flow the tag belongs to; the adapter routes only.
+     *
+     * The handler is called *after* the corresponding `ctrl:*-received`
+     * diagnostic fires, so subscribers observing the low-level signal
+     * see the event before the handler mutates any application state.
+     * Handler exceptions are swallowed by the adapter — a buggy handler
+     * cannot tear the network path — but a diagnostic
+     * `drop:control-handler-threw` is emitted so the failure is
+     * observable.
+     */
+    onControlMessage?: (tag: number, body: Uint8Array, senderId: string) => void;
 }
 /**
  * NetworkAdapter that wraps another adapter with Polly's mesh-transport
@@ -121,6 +172,7 @@ export declare class MeshNetworkAdapter extends NetworkAdapter {
     readonly base: NetworkAdapter;
     readonly keyringSource: () => MeshKeyring;
     readonly encryptionEnabled: boolean;
+    readonly onControlMessage: ((tag: number, body: Uint8Array, senderId: string) => void) | undefined;
     /** Read-only view of the current keyring. Each access calls
      * {@link MeshNetworkAdapterOptions.keyringSource}, so the value
      * reflects whatever mutations or swaps the caller has applied since
@@ -137,7 +189,46 @@ export declare class MeshNetworkAdapter extends NetworkAdapter {
      * Wrap an outgoing Automerge message in an encrypt-then-sign envelope.
      * The wrapped payload is returned as a Message with the original sender
      * and target ids and the crypto blob in the `data` field.
+     *
+     * The serialised Automerge message is prefixed with a one-byte
+     * control-type tag (RFC-043). For outgoing Automerge sync this is
+     * always {@link MESH_CONTROL_TYPE.Sync} (0x00); the tag exists so
+     * future control flows (revocation propagation, revocation-set
+     * summaries) can share the same encrypted-signed envelope without
+     * re-versioning the wire format.
      */
     private wrap;
     private tryUnwrap;
+    /**
+     * Dispatch a verified-and-decrypted plaintext payload based on its
+     * one-byte control-type tag (RFC-043). For {@link MESH_CONTROL_TYPE.Sync}
+     * the remainder is the serialised Automerge message and is returned
+     * to the caller. For revocation tags the dispatch emits a
+     * `ctrl:*-received` diagnostic and drops the payload at this layer
+     * pending the next RFC-043 PR. Unknown tags emit
+     * `drop:unknown-control-type` and drop.
+     */
+    private dispatchTaggedPayload;
+    private invokeControlHandler;
+    /**
+     * Send a control message (RFC-043) to a list of connected peers.
+     * The body is wrapped in the same encrypt-sign envelope Automerge
+     * sync uses; the type tag goes in front so receivers route it to
+     * {@link MeshNetworkAdapterOptions.onControlMessage}.
+     *
+     * The base adapter does not surface its connected-peer set on the
+     * NetworkAdapter interface, so the caller passes the targets
+     * explicitly. The MeshClient layer maintains that list from the
+     * `peer-candidate` / `peer-disconnected` events.
+     */
+    sendControlMessage(tag: MeshControlType, body: Uint8Array, targetPeerIds: ReadonlyArray<PeerId>): void;
 }
+/**
+ * Prepend a one-byte control-type tag to a payload. The tag goes
+ * inside the encrypted-signed envelope (or directly inside the signed
+ * envelope in sign-only mode), so it is both confidential (encrypted
+ * when encryption is enabled) and authenticated (covered by the
+ * signature). Exposed so future RFC-043 issue helpers can build
+ * tagged payloads without rebuilding this primitive.
+ */
+export declare function prependControlTag(tag: MeshControlType, body: Uint8Array): Uint8Array;

package/dist/src/shared/lib/revocation-summary.d.ts

@@ -0,0 +1,54 @@
+/**
+ * revocation-summary — RFC-043 wire format for the revocation-set
+ * summary exchanged on every new peer connection.
+ *
+ * On a fresh data channel both peers send the other a summary of
+ * every revocation they currently hold. After exchange each side
+ * computes which entries in its own set are missing from the
+ * remote's summary, and pushes those entries as full encoded
+ * revocation blobs (tag 0x01). The summary itself is informative,
+ * not authoritative — only the signed blob can mutate a keyring.
+ *
+ * Wire format: UTF-8 JSON. A summary is a sorted JSON array of
+ * entries, each carrying the fields needed to detect set-difference
+ * without leaking the blob's signature. Sorting is canonical so two
+ * peers comparing summaries agree on order even when their stores
+ * were populated in different sequences.
+ *
+ *   [
+ *     { "r": "<revokedPeerId>", "i": "<issuerPeerId>", "t": <issuedAt> },
+ *     ...
+ *   ]
+ *
+ * Short field names keep the wire compact for keyrings with many
+ * revocations. Long-form parsing isn't a goal — the format is
+ * internal to the mesh protocol.
+ */
+/** A single entry in a revocation-set summary. */
+export interface RevocationSummaryEntry {
+    /** Peer id the revocation targets. */
+    revokedPeerId: string;
+    /** Peer id that issued the revocation. */
+    issuerPeerId: string;
+    /** Unix milliseconds at issue time, from the underlying RevocationRecord. */
+    issuedAt: number;
+}
+/**
+ * Encode a list of revocation entries to the canonical wire
+ * representation. Entries are sorted by `revokedPeerId` then
+ * `issuerPeerId` then `issuedAt` to make the comparison
+ * order-independent.
+ */
+export declare function encodeRevocationSummary(entries: ReadonlyArray<RevocationSummaryEntry>): Uint8Array;
+/**
+ * Inverse of {@link encodeRevocationSummary}. Throws on malformed
+ * input — the caller is expected to drop the summary and emit a
+ * diagnostic when this happens, not retry.
+ */
+export declare function decodeRevocationSummary(bytes: Uint8Array): RevocationSummaryEntry[];
+/**
+ * Stable key for a summary entry. Two entries with the same key
+ * represent the same logical revocation. Used by the
+ * peer-candidate gossip path to compute set differences.
+ */
+export declare function summaryEntryKey(entry: RevocationSummaryEntry): string;

package/dist/tools/test/src/e2e-mesh/index.d.ts

@@ -20,7 +20,7 @@
  */
 export { type ConsolePattern, isAllowedConsoleLine, MESH_CONSOLE_ALLOWLIST, } from "./console-allowlist";
 export { knownPeersFor, type PrebakedKeyringPair, type PrebakedKeyringSet, type PrebakedPeer, prebakeKeyringPair, prebakeKeyringSet, } from "./keys";
-export { type CapturedConsoleLine, type LaunchedPeer, type LaunchPeerOptions, launchPeer, } from "./launch-peer";
+export { type CapturedConsoleLine, type LaunchedPeer, type LaunchPeerOptions, type LaunchSecondTabOptions, launchPeer, launchSecondTab, } from "./launch-peer";
 export { type DiagnosticRecorder, MeshAssertionError, type MeshAssertionFailure, startDiagnosticRecorder, } from "./mesh-assertions";
 export { type ServeConsumerOptions, type ServeConsumerResult, serveConsumer, } from "./serve-consumer";
 export { type ConvergencePredicate, type PeerSnapshot, type WaitForConvergenceOptions, waitForConvergence, waitForMeshConnected, } from "./wait-for-convergence";

package/dist/tools/test/src/e2e-mesh/index.js

@@ -806,6 +806,7 @@ ${summary}
   return {
     peerId,
     page,
+    browser,
     console: consoleLines,
     pageErrors,
     assertNoUnexpectedConsole,
@@ -827,6 +828,98 @@ ${summary}
     }
   };
 }
+async function launchSecondTab(parent, options) {
+  const {
+    consumerUrl,
+    consoleAllowlist = MESH_CONSOLE_ALLOWLIST,
+    readyTimeoutMs = 15000
+  } = options;
+  const page = await parent.browser.newPage();
+  const consoleLines = [];
+  const pageErrors = [];
+  page.on("console", (msg) => {
+    const level = msg.type();
+    const text = msg.text();
+    const allowed = isAllowedConsoleLine({ level, text }, consoleAllowlist);
+    consoleLines.push({ level, text, allowed });
+  });
+  page.on("pageerror", (err) => {
+    pageErrors.push(err instanceof Error ? err.message : String(err));
+  });
+  await page.goto(consumerUrl, { waitUntil: "domcontentloaded" });
+  const deadline = Date.now() + readyTimeoutMs;
+  let ready = false;
+  let lastStatus = "";
+  while (Date.now() < deadline) {
+    lastStatus = await page.evaluate(() => document.querySelector("[data-e2e='status']")?.textContent ?? "");
+    if (lastStatus === "ready") {
+      ready = true;
+      break;
+    }
+    if (lastStatus.startsWith("error") || lastStatus.startsWith("bootstrap-failed")) {
+      await page.close();
+      throw new Error(`launchSecondTab(${parent.peerId}): consumer reported "${lastStatus}"`);
+    }
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  if (!ready) {
+    await page.close();
+    throw new Error(`launchSecondTab(${parent.peerId}): consumer did not reach "ready" within ${readyTimeoutMs}ms (last status: "${lastStatus}")`);
+  }
+  function assertNoUnexpectedConsole() {
+    const bad = consoleLines.filter((line) => !line.allowed && (line.level === "error" || line.level === "warn" || line.level === "warning"));
+    if (bad.length > 0) {
+      const summary = bad.map((l) => `  [${l.level}] ${l.text}`).join(`
+`);
+      throw new Error(`launchSecondTab(${parent.peerId}): unexpected console output:
+${summary}`);
+    }
+    if (pageErrors.length > 0) {
+      throw new Error(`launchSecondTab(${parent.peerId}): page errors:
+${pageErrors.map((e) => `  ${e}`).join(`
+`)}`);
+    }
+  }
+  async function collectDiagnostics() {
+    return page.evaluate(() => {
+      const w = window;
+      return w.__pollyE2eDiagnostics ? [...w.__pollyE2eDiagnostics] : [];
+    });
+  }
+  async function assertNoSilentDrops(allow = []) {
+    const allowed = new Set(allow);
+    const events = await collectDiagnostics();
+    const unexpected = events.filter((event) => event.kind.startsWith("drop:") && !allowed.has(event.kind));
+    if (unexpected.length === 0)
+      return;
+    const summary = unexpected.map((event) => {
+      const { kind, timestamp: _ts, ...rest } = event;
+      return `  ${kind} ${JSON.stringify(rest)}`;
+    }).join(`
+`);
+    throw new MeshAssertionError(`launchSecondTab(${parent.peerId}): unexpected silent-drop diagnostics fired during the e2e run.
+${summary}`, unexpected);
+  }
+  let closed = false;
+  return {
+    peerId: parent.peerId,
+    page,
+    browser: parent.browser,
+    console: consoleLines,
+    pageErrors,
+    assertNoUnexpectedConsole,
+    collectDiagnostics,
+    assertNoSilentDrops,
+    close: async () => {
+      if (closed)
+        return;
+      closed = true;
+      try {
+        await page.close();
+      } catch {}
+    }
+  };
+}
 // tools/test/src/e2e-mesh/serve-consumer.ts
 var {readFileSync} = (() => ({}));
 var __dirname = "/Users/AJT/projects/polly/packages/polly/tools/test/src/e2e-mesh";
@@ -1079,6 +1172,7 @@ export {
   serveConsumer,
   prebakeKeyringSet,
   prebakeKeyringPair,
+  launchSecondTab,
   launchPeer,
   knownPeersFor,
   isAllowedConsoleLine,
@@ -1086,4 +1180,4 @@ export {
   MESH_CONSOLE_ALLOWLIST
 };
 
-//# debugId=7F448F738B995B3064756E2164756E21
+//# debugId=2D797840A9246AEE64756E2164756E21