@fairfox/polly 0.69.0 → 0.71.0

package/dist/src/shared/lib/mesh-diagnostics.d.ts

@@ -0,0 +1,129 @@
+/**
+ * mesh-diagnostics — typed event stream for observable mesh failures and
+ * state transitions.
+ *
+ * The mesh network adapter's incoming path has seven branches that drop a
+ * message and return undefined: a malformed signed envelope, a revoked
+ * peer, an unknown peer, a bad signature, a malformed encrypted envelope,
+ * a missing document key, and a bad decryption. Each branch is correct —
+ * the adapter must not surface tampered or unidentifiable bytes to the
+ * Repo — but the drop is invisible to anything observing the application.
+ * The classic symptom is "the other peer typed something and nothing
+ * arrived" with no error anywhere.
+ *
+ * This module exposes a typed emit-and-subscribe stream that the adapter
+ * (and the pairing and revocation paths) write to. Tests subscribe to
+ * assert that exactly the expected diagnostics fired and no others;
+ * production code can attach an observability sink that turns the stream
+ * into telemetry or a user-visible diagnostic surface.
+ *
+ * The stream is module-level. Listeners are deduplicated by reference;
+ * subscribe returns an unsubscribe function. Listener exceptions are
+ * caught and dropped so a buggy observer cannot tear the network path.
+ */
+/** All diagnostic event kinds, discriminated by the `kind` field. */
+export type MeshDiagnostic = {
+    kind: "drop:malformed-signed-envelope";
+    reason?: string;
+} | {
+    kind: "drop:revoked-peer";
+    senderId: string;
+} | {
+    kind: "drop:unknown-peer";
+    senderId: string;
+} | {
+    kind: "drop:bad-signature";
+    senderId: string;
+    reason?: string;
+} | {
+    kind: "drop:malformed-encrypted-envelope";
+    senderId: string;
+    reason?: string;
+} | {
+    kind: "drop:missing-doc-key";
+    senderId: string;
+    documentId: string;
+} | {
+    kind: "drop:bad-decryption";
+    senderId: string;
+    documentId: string;
+    reason?: string;
+} | {
+    kind: "drop:unknown-control-type";
+    senderId: string;
+    tag: number;
+} | {
+    kind: "drop:empty-control-payload";
+    senderId: string;
+} | {
+    kind: "drop:control-handler-threw";
+    senderId: string;
+    tag: number;
+    reason: string;
+} | {
+    kind: "ctrl:revocation-received";
+    senderId: string;
+} | {
+    kind: "ctrl:revocation-summary-received";
+    senderId: string;
+} | {
+    kind: "revoke:duplicate";
+    revokedPeerId: string;
+    issuerId: string;
+} | {
+    kind: "revoke:rejected";
+    senderId: string;
+    reason: string;
+} | {
+    kind: "revoke:self-targeted";
+    issuerId: string;
+    reason?: string;
+    issuedAt: number;
+} | {
+    kind: "pair:invite-issued";
+    peerId: string;
+} | {
+    kind: "pair:invite-accepted";
+    peerId: string;
+    issuerId: string;
+} | {
+    kind: "revoke:issued";
+    revokedPeerId: string;
+    issuerId: string;
+} | {
+    kind: "revoke:applied";
+    revokedPeerId: string;
+};
+/** A diagnostic event with the wall-clock timestamp the emitter stamped. */
+export type MeshDiagnosticEvent = MeshDiagnostic & {
+    timestamp: number;
+};
+/** Callback shape for subscribers. */
+export type MeshDiagnosticListener = (event: MeshDiagnosticEvent) => void;
+/**
+ * Emit a diagnostic to every active subscriber. Synchronous. Listener
+ * exceptions are swallowed.
+ */
+export declare function emitMeshDiagnostic(diagnostic: MeshDiagnostic): void;
+/**
+ * Subscribe a listener. Returns an unsubscribe function. Idempotent on
+ * the same listener reference — subscribing the same function twice
+ * registers it once.
+ */
+export declare function subscribeToMeshDiagnostics(listener: MeshDiagnosticListener): () => void;
+/**
+ * Convenience for tests and trace recorders: subscribe, collect every
+ * event into an array, return the array and a stop function that
+ * unsubscribes. The returned array is the live capture buffer — reads
+ * see new events the moment they fire.
+ */
+export declare function recordMeshDiagnostics(): {
+    events: ReadonlyArray<MeshDiagnosticEvent>;
+    stop: () => void;
+};
+/**
+ * Test-only: drop every subscriber. Use in `afterEach` to guarantee
+ * isolation between tests when a stop function was missed. Not exported
+ * from the mesh subpath in production builds — tests reach in directly.
+ */
+export declare function clearMeshDiagnosticListeners(): void;

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,11 +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;
     /**
-     * Try to unwrap an incoming crypto-wrapped message. Returns the original
-     * Message on success, undefined on verification or decryption failure.
+     * 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 tryUnwrap;
+    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/console-allowlist.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fairfox/polly/test/e2e-mesh — canonical console-noise allowlist.
+ *
+ * Mesh runs emit a small number of benign console lines (Repo lifecycle,
+ * Automerge warmup, occasional sync diagnostics). E2e scripts watch the
+ * Puppeteer console stream and fail on anything unexpected; without an
+ * allowlist every run trips on the same benign noise.
+ *
+ * The allowlist is owned by polly because polly knows which lines its
+ * own code produces. Consumers extend it with their app-specific noise.
+ * Entries are tested as substrings against the rendered console message.
+ */
+/** Match a console line that contains the given substring. */
+export interface ConsolePattern {
+    /** Optional console level filter — "log" | "info" | "warn" | "error".
+     *  Undefined matches any level. */
+    level?: "log" | "info" | "warn" | "error";
+    /** Substring or RegExp the rendered console line must satisfy. */
+    match: string | RegExp;
+    /** Short reason — surfaces in failure messages when the allowlist
+     *  evolves and an entry should be removed. */
+    reason: string;
+}
+export declare const MESH_CONSOLE_ALLOWLIST: ReadonlyArray<ConsolePattern>;
+/**
+ * Return true when the console line matches any allowlist entry.
+ */
+export declare function isAllowedConsoleLine(line: {
+    level: string;
+    text: string;
+}, allowlist?: ReadonlyArray<ConsolePattern>): boolean;

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

@@ -0,0 +1,27 @@
+/**
+ * @fairfox/polly/test/e2e-mesh — end-to-end test kit for the mesh.
+ *
+ * Centralises the patterns every consumer's e2e scripts reinvent today:
+ * pairing-ceremony driving, convergence polling, console-noise filtering,
+ * screenshot-on-failure, and an embedded signalling relay. Fairfox and
+ * lingua import from this subpath rather than reimplementing.
+ *
+ * The kit is opinionated about the shape of the consumer it drives —
+ * pairing UI exposes stable `data-e2e-*` attributes, the bootstrap path
+ * goes through `createMeshClient`, the document state is observable via
+ * a polled DOM predicate. Consumers that follow the conventions get the
+ * full kit for free; those that diverge supply their own driver per
+ * primitive.
+ *
+ * Diagnostic obligation runs by default through {@link startDiagnosticRecorder}:
+ * unexpected silent drops on the diagnostic stream fail the script. A
+ * scenario that legitimately exercises a drop branch (e.g. revocation)
+ * passes the expected kinds to `assertNoSilentDrops({ allow: [...] })`.
+ */
+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, 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";
+export { type WithRelayOptions, type WithRelayResult, withRelay } from "./with-relay";