wire-mesh-core 3.0.1 → 3.2.0

package/dist/adapters/byte-stream-connection.cjs

@@ -0,0 +1,79 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_generated_protocol = require("../generated/protocol.cjs");
+let cbor2 = require("cbor2");
+//#region src/adapters/byte-stream-connection.ts
+const LENGTH_PREFIX_BYTES = 4;
+const BYTES_PER_KIBIBYTE = 1024;
+/** The largest frame body a peer may announce in a length prefix, matching the 100 MiB the `ws` package applies to one message on the same hub, so a WebSocket peer and a byte-stream peer are bounded alike. Without a bound a peer-controlled 4 GiB prefix makes the reader buffer until memory runs out. */
+const MAX_FRAME_BYTES = 100 * (BYTES_PER_KIBIBYTE * BYTES_PER_KIBIBYTE);
+/** A frame with an empty body, which carries nothing and is skipped by the reader. A QUIC stream is invisible to the peer until a byte crosses it, so the side that opens a stream writes one of these to make it visible before it has a real frame to send. */
+const STREAM_OPEN_MARKER = new Uint8Array(LENGTH_PREFIX_BYTES);
+/** The bytes that carry one frame on a byte stream: a 4-byte big-endian length, then the frame's CBOR body, the same framing the TCP adapter uses. */
+function encodeLengthPrefixedFrame(frame) {
+	const body = (0, cbor2.encode)(frame, cbor2.cdeEncodeOptions);
+	const message = new Uint8Array(LENGTH_PREFIX_BYTES + body.length);
+	new DataView(message.buffer).setUint32(0, body.length);
+	message.set(body, LENGTH_PREFIX_BYTES);
+	return message;
+}
+function concat(first, second) {
+	const joined = new Uint8Array(first.length + second.length);
+	joined.set(first);
+	joined.set(second, first.length);
+	return joined;
+}
+/**
+* Frames arriving on a byte stream, in order, until it ends. An empty body (STREAM_OPEN_MARKER) is skipped. A body that does not decode as CBOR, or a length prefix above MAX_FRAME_BYTES, rejects the iteration (a connection-level failure); a body that decodes but fails frame validation is dropped and the stream continues, since an unrecognised frame from a newer peer is what version negotiation exists to tolerate.
+*/
+async function* readFrames(reader) {
+	let buffered = /* @__PURE__ */ new Uint8Array(0);
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) return;
+			buffered = concat(buffered, chunk.value);
+			while (buffered.length >= LENGTH_PREFIX_BYTES) {
+				const bodyLength = new DataView(buffered.buffer, buffered.byteOffset).getUint32(0);
+				if (bodyLength > 104857600) throw new Error(`frame of ${String(bodyLength)} bytes exceeds the ${String(MAX_FRAME_BYTES)}-byte limit`);
+				if (buffered.length < LENGTH_PREFIX_BYTES + bodyLength) break;
+				if (bodyLength === 0) {
+					buffered = buffered.slice(LENGTH_PREFIX_BYTES);
+					continue;
+				}
+				const body = buffered.slice(LENGTH_PREFIX_BYTES, LENGTH_PREFIX_BYTES + bodyLength);
+				buffered = buffered.slice(LENGTH_PREFIX_BYTES + bodyLength);
+				const result = require_generated_protocol.frameSchema.safeParse((0, cbor2.decode)(body, cbor2.cdeDecodeOptions));
+				if (result.success) yield result.data;
+			}
+		}
+	} catch (error) {
+		await reader.cancel(error);
+		throw error;
+	}
+}
+/**
+* A Connection over an ordered, reliable byte stream, one frame per length-prefixed CBOR body. Pass `opened: true` on the side that opened the stream: it writes a STREAM_OPEN_MARKER first, so the peer sees the stream before the first real frame. Pass `opened: true` on the side that opened the stream, which writes a STREAM_OPEN_MARKER first so the peer sees the stream before the first real frame. `close` ends the writable side and cancels the readable side, so the peer sees the stream finish and this side's `receive()` ends.
+*/
+function connectionFromByteStream(stream, options = { opened: false }) {
+	const writer = stream.writable.getWriter();
+	const reader = stream.readable.getReader();
+	const frames = readFrames(reader);
+	const marked = options.opened ? writer.write(STREAM_OPEN_MARKER) : Promise.resolve();
+	marked.catch(() => void 0);
+	return {
+		send: async (frame) => {
+			await marked;
+			await writer.write(encodeLengthPrefixedFrame(frame));
+		},
+		receive: () => frames,
+		close: async () => {
+			await writer.close();
+			await reader.cancel();
+		}
+	};
+}
+//#endregion
+exports.MAX_FRAME_BYTES = MAX_FRAME_BYTES;
+exports.STREAM_OPEN_MARKER = STREAM_OPEN_MARKER;
+exports.connectionFromByteStream = connectionFromByteStream;
+exports.encodeLengthPrefixedFrame = encodeLengthPrefixedFrame;

package/dist/adapters/byte-stream-connection.d.cts

@@ -0,0 +1,21 @@
+import { N as Frame } from "../protocol-DCDae3z4.cjs";
+import { t as Connection } from "../transport-CfW7fsGK.cjs";
+//#region src/adapters/byte-stream-connection.d.ts
+/** The largest frame body a peer may announce in a length prefix, matching the 100 MiB the `ws` package applies to one message on the same hub, so a WebSocket peer and a byte-stream peer are bounded alike. Without a bound a peer-controlled 4 GiB prefix makes the reader buffer until memory runs out. */
+export declare const MAX_FRAME_BYTES: number;
+/** A frame with an empty body, which carries nothing and is skipped by the reader. A QUIC stream is invisible to the peer until a byte crosses it, so the side that opens a stream writes one of these to make it visible before it has a real frame to send. */
+export declare const STREAM_OPEN_MARKER: Uint8Array;
+/** The two halves of an ordered, reliable byte stream, as the Web Streams API models them: a WebTransport bidirectional stream is one, and so is any other stream a runtime exposes in that shape. */
+export interface ByteStream {
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+}
+/** The bytes that carry one frame on a byte stream: a 4-byte big-endian length, then the frame's CBOR body, the same framing the TCP adapter uses. */
+export declare function encodeLengthPrefixedFrame(frame: Frame): Uint8Array;
+/**
+ * A Connection over an ordered, reliable byte stream, one frame per length-prefixed CBOR body. Pass `opened: true` on the side that opened the stream: it writes a STREAM_OPEN_MARKER first, so the peer sees the stream before the first real frame. Pass `opened: true` on the side that opened the stream, which writes a STREAM_OPEN_MARKER first so the peer sees the stream before the first real frame. `close` ends the writable side and cancels the readable side, so the peer sees the stream finish and this side's `receive()` ends.
+ */
+export declare function connectionFromByteStream(stream: Readonly<ByteStream>, options?: Readonly<{
+  opened: boolean;
+}>): Connection;
+//#endregion

package/dist/adapters/byte-stream-connection.d.mts

@@ -0,0 +1,21 @@
+import { N as Frame } from "../protocol-DCDae3z4.mjs";
+import { t as Connection } from "../transport-iLBxIkRS.mjs";
+//#region src/adapters/byte-stream-connection.d.ts
+/** The largest frame body a peer may announce in a length prefix, matching the 100 MiB the `ws` package applies to one message on the same hub, so a WebSocket peer and a byte-stream peer are bounded alike. Without a bound a peer-controlled 4 GiB prefix makes the reader buffer until memory runs out. */
+export declare const MAX_FRAME_BYTES: number;
+/** A frame with an empty body, which carries nothing and is skipped by the reader. A QUIC stream is invisible to the peer until a byte crosses it, so the side that opens a stream writes one of these to make it visible before it has a real frame to send. */
+export declare const STREAM_OPEN_MARKER: Uint8Array;
+/** The two halves of an ordered, reliable byte stream, as the Web Streams API models them: a WebTransport bidirectional stream is one, and so is any other stream a runtime exposes in that shape. */
+export interface ByteStream {
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+}
+/** The bytes that carry one frame on a byte stream: a 4-byte big-endian length, then the frame's CBOR body, the same framing the TCP adapter uses. */
+export declare function encodeLengthPrefixedFrame(frame: Frame): Uint8Array;
+/**
+ * A Connection over an ordered, reliable byte stream, one frame per length-prefixed CBOR body. Pass `opened: true` on the side that opened the stream: it writes a STREAM_OPEN_MARKER first, so the peer sees the stream before the first real frame. Pass `opened: true` on the side that opened the stream, which writes a STREAM_OPEN_MARKER first so the peer sees the stream before the first real frame. `close` ends the writable side and cancels the readable side, so the peer sees the stream finish and this side's `receive()` ends.
+ */
+export declare function connectionFromByteStream(stream: Readonly<ByteStream>, options?: Readonly<{
+  opened: boolean;
+}>): Connection;
+//#endregion

package/dist/adapters/byte-stream-connection.mjs

@@ -0,0 +1,75 @@
+import { frameSchema } from "../generated/protocol.mjs";
+import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
+//#region src/adapters/byte-stream-connection.ts
+const LENGTH_PREFIX_BYTES = 4;
+const BYTES_PER_KIBIBYTE = 1024;
+/** The largest frame body a peer may announce in a length prefix, matching the 100 MiB the `ws` package applies to one message on the same hub, so a WebSocket peer and a byte-stream peer are bounded alike. Without a bound a peer-controlled 4 GiB prefix makes the reader buffer until memory runs out. */
+const MAX_FRAME_BYTES = 100 * (BYTES_PER_KIBIBYTE * BYTES_PER_KIBIBYTE);
+/** A frame with an empty body, which carries nothing and is skipped by the reader. A QUIC stream is invisible to the peer until a byte crosses it, so the side that opens a stream writes one of these to make it visible before it has a real frame to send. */
+const STREAM_OPEN_MARKER = new Uint8Array(LENGTH_PREFIX_BYTES);
+/** The bytes that carry one frame on a byte stream: a 4-byte big-endian length, then the frame's CBOR body, the same framing the TCP adapter uses. */
+function encodeLengthPrefixedFrame(frame) {
+	const body = encode(frame, cdeEncodeOptions);
+	const message = new Uint8Array(LENGTH_PREFIX_BYTES + body.length);
+	new DataView(message.buffer).setUint32(0, body.length);
+	message.set(body, LENGTH_PREFIX_BYTES);
+	return message;
+}
+function concat(first, second) {
+	const joined = new Uint8Array(first.length + second.length);
+	joined.set(first);
+	joined.set(second, first.length);
+	return joined;
+}
+/**
+* Frames arriving on a byte stream, in order, until it ends. An empty body (STREAM_OPEN_MARKER) is skipped. A body that does not decode as CBOR, or a length prefix above MAX_FRAME_BYTES, rejects the iteration (a connection-level failure); a body that decodes but fails frame validation is dropped and the stream continues, since an unrecognised frame from a newer peer is what version negotiation exists to tolerate.
+*/
+async function* readFrames(reader) {
+	let buffered = /* @__PURE__ */ new Uint8Array(0);
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) return;
+			buffered = concat(buffered, chunk.value);
+			while (buffered.length >= LENGTH_PREFIX_BYTES) {
+				const bodyLength = new DataView(buffered.buffer, buffered.byteOffset).getUint32(0);
+				if (bodyLength > 104857600) throw new Error(`frame of ${String(bodyLength)} bytes exceeds the ${String(MAX_FRAME_BYTES)}-byte limit`);
+				if (buffered.length < LENGTH_PREFIX_BYTES + bodyLength) break;
+				if (bodyLength === 0) {
+					buffered = buffered.slice(LENGTH_PREFIX_BYTES);
+					continue;
+				}
+				const body = buffered.slice(LENGTH_PREFIX_BYTES, LENGTH_PREFIX_BYTES + bodyLength);
+				buffered = buffered.slice(LENGTH_PREFIX_BYTES + bodyLength);
+				const result = frameSchema.safeParse(decode(body, cdeDecodeOptions));
+				if (result.success) yield result.data;
+			}
+		}
+	} catch (error) {
+		await reader.cancel(error);
+		throw error;
+	}
+}
+/**
+* A Connection over an ordered, reliable byte stream, one frame per length-prefixed CBOR body. Pass `opened: true` on the side that opened the stream: it writes a STREAM_OPEN_MARKER first, so the peer sees the stream before the first real frame. Pass `opened: true` on the side that opened the stream, which writes a STREAM_OPEN_MARKER first so the peer sees the stream before the first real frame. `close` ends the writable side and cancels the readable side, so the peer sees the stream finish and this side's `receive()` ends.
+*/
+function connectionFromByteStream(stream, options = { opened: false }) {
+	const writer = stream.writable.getWriter();
+	const reader = stream.readable.getReader();
+	const frames = readFrames(reader);
+	const marked = options.opened ? writer.write(STREAM_OPEN_MARKER) : Promise.resolve();
+	marked.catch(() => void 0);
+	return {
+		send: async (frame) => {
+			await marked;
+			await writer.write(encodeLengthPrefixedFrame(frame));
+		},
+		receive: () => frames,
+		close: async () => {
+			await writer.close();
+			await reader.cancel();
+		}
+	};
+}
+//#endregion
+export { MAX_FRAME_BYTES, STREAM_OPEN_MARKER, connectionFromByteStream, encodeLengthPrefixedFrame };

package/dist/adapters/memory-storage.d.cts

@@ -1,4 +1,4 @@
-import { KeyValueStorage } from "../ports/storage.cjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
 //#region src/adapters/memory-storage.d.ts
 /** An in-process KeyValueStorage backed by a Map -- for tests and single-process nodes; a real deployment substitutes a persistent adapter behind the same contract without touching anything that depends on the port. Not declared `async`: every operation is genuinely synchronous under the hood, so the contract's Promise return is satisfied directly via Promise.resolve() rather than an async function with no await in its body. */
 export declare function createMemoryStorage(): KeyValueStorage;

package/dist/adapters/memory-storage.d.mts

@@ -1,4 +1,4 @@
-import { KeyValueStorage } from "../ports/storage.mjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
 //#region src/adapters/memory-storage.d.ts
 /** An in-process KeyValueStorage backed by a Map -- for tests and single-process nodes; a real deployment substitutes a persistent adapter behind the same contract without touching anything that depends on the port. Not declared `async`: every operation is genuinely synchronous under the hood, so the contract's Promise return is satisfied directly via Promise.resolve() rather than an async function with no await in its body. */
 export declare function createMemoryStorage(): KeyValueStorage;

package/dist/adapters/node-fs-storage.d.cts

@@ -1,4 +1,4 @@
-import { KeyValueStorage } from "../ports/storage.cjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
 //#region src/adapters/node-fs-storage.d.ts
 export interface NodeFsStorageOptions {
   /** Directory to store entries under. Created on first write if it doesn't already exist. */

package/dist/adapters/node-fs-storage.d.mts

@@ -1,4 +1,4 @@
-import { KeyValueStorage } from "../ports/storage.mjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
 //#region src/adapters/node-fs-storage.d.ts
 export interface NodeFsStorageOptions {
   /** Directory to store entries under. Created on first write if it doesn't already exist. */

package/dist/domain/bulk.d.cts

@@ -1,6 +1,6 @@
 import { D as DeviceId, N as Frame, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-DCDae3z4.cjs";
-import { KeyValueStorage } from "../ports/storage.cjs";
 import { t as Connection } from "../transport-CfW7fsGK.cjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.cjs";
 //#region src/domain/bulk.d.ts
 /** The two capabilities matching the direction each manage-command actually flows (spec/bulk.cddl): the sender proves write authority to open a transfer, the receiver proves read authority to ask for one to continue. */

package/dist/domain/bulk.d.mts

@@ -1,6 +1,6 @@
 import { D as DeviceId, N as Frame, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-DCDae3z4.mjs";
-import { KeyValueStorage } from "../ports/storage.mjs";
 import { t as Connection } from "../transport-iLBxIkRS.mjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.mjs";
 //#region src/domain/bulk.d.ts
 /** The two capabilities matching the direction each manage-command actually flows (spec/bulk.cddl): the sender proves write authority to open a transfer, the receiver proves read authority to ask for one to continue. */

package/dist/domain/data-sync.d.cts

@@ -1,5 +1,5 @@
 import { D as DeviceId, E as DataRequestFrame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-DCDae3z4.cjs";
-import { KeyValueStorage } from "../ports/storage.cjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
 import { t as IdentityPort } from "../identity-DVCNuFLG.cjs";
 //#region src/domain/data-sync.d.ts
 export interface DataSyncOptions {

package/dist/domain/data-sync.d.mts

@@ -1,5 +1,5 @@
 import { D as DeviceId, E as DataRequestFrame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-DCDae3z4.mjs";
-import { KeyValueStorage } from "../ports/storage.mjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
 import { t as IdentityPort } from "../identity-DcaYgjXT.mjs";
 //#region src/domain/data-sync.d.ts
 export interface DataSyncOptions {

package/dist/domain/hub-mailbox.cjs

@@ -0,0 +1,81 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_device_id = require("./device-id.cjs");
+const require_domain_data_sync = require("./data-sync.cjs");
+//#region src/domain/hub-mailbox.ts
+/** The data frames a mailbox answers. */
+function isDataFrame(frame) {
+	return frame.type === "data-have" || frame.type === "data-request" || frame.type === "data-entries";
+}
+const LOG_COUNT_KEY = "mailbox/log-count";
+function logBytesKey(peer) {
+	return `mailbox/${require_domain_device_id.deviceIdToHex(peer)}/bytes`;
+}
+function encodeCount(value) {
+	return new TextEncoder().encode(String(value));
+}
+async function readCount(storage, key) {
+	const raw = await storage.get(key);
+	return raw === void 0 ? 0 : Number(new TextDecoder().decode(raw));
+}
+function sameDevice(a, b) {
+	return require_domain_device_id.deviceIdToHex(a) === require_domain_device_id.deviceIdToHex(b);
+}
+function createMailbox(options) {
+	const { storage, limits } = options;
+	async function handleHave(sender, frame, refuse) {
+		if (!sameDevice(sender, frame.peer)) {
+			refuse("not-the-owner");
+			return null;
+		}
+		if (await require_domain_data_sync.headSeqFor(storage, frame.peer) === 0) {
+			if (await readCount(storage, LOG_COUNT_KEY) >= limits.maxLogs) {
+				refuse("log-limit");
+				return null;
+			}
+		}
+		return require_domain_data_sync.handleDataHave(storage, frame);
+	}
+	async function handleEntries(sender, frame, refuse) {
+		if (!sameDevice(sender, frame.peer)) {
+			refuse("not-the-owner");
+			return null;
+		}
+		if (frame.entries.some((entry) => entry.length > limits.maxEntryBytes)) {
+			refuse("size-limit");
+			return null;
+		}
+		const held = await readCount(storage, logBytesKey(frame.peer));
+		const added = frame.entries.reduce((sum, entry) => sum + entry.length, 0);
+		if (held + added > limits.maxLogBytes) {
+			refuse("entry-limit");
+			return null;
+		}
+		const isNewLog = await require_domain_data_sync.headSeqFor(storage, frame.peer) === 0;
+		if (isNewLog && await readCount(storage, LOG_COUNT_KEY) >= limits.maxLogs) {
+			refuse("log-limit");
+			return null;
+		}
+		if (!(await require_domain_data_sync.handleDataEntries(storage, frame)).ok) {
+			refuse("gap");
+			return null;
+		}
+		await storage.set(logBytesKey(frame.peer), encodeCount(held + added));
+		if (isNewLog && frame.entries.length > 0) await storage.set(LOG_COUNT_KEY, encodeCount(await readCount(storage, LOG_COUNT_KEY) + 1));
+		return null;
+	}
+	return { async handle(sender, frame, onRefused) {
+		const refuse = (reason) => {
+			onRefused?.(reason);
+		};
+		if (sender === void 0) {
+			refuse("unregistered-sender");
+			return null;
+		}
+		if (frame.type === "data-have") return handleHave(sender, frame, refuse);
+		if (frame.type === "data-entries") return handleEntries(sender, frame, refuse);
+		return require_domain_data_sync.handleDataRequest(storage, frame, limits.readBatch);
+	} };
+}
+//#endregion
+exports.createMailbox = createMailbox;
+exports.isDataFrame = isDataFrame;

package/dist/domain/hub-mailbox.d.cts

@@ -0,0 +1,29 @@
+import { D as DeviceId, E as DataRequestFrame, N as Frame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-DCDae3z4.cjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
+//#region src/domain/hub-mailbox.d.ts
+export interface MailboxLimits {
+  /** How many devices' logs the mailbox will hold at once. */
+  readonly maxLogs: number;
+  /** How many bytes of entries one log may hold in total. */
+  readonly maxLogBytes: number;
+  /** How large one entry may be. */
+  readonly maxEntryBytes: number;
+  /** How many entries one reply carries at most; a longer log takes more rounds. */
+  readonly readBatch: number;
+}
+export interface MailboxOptions {
+  readonly storage: KeyValueStorage;
+  readonly limits: Readonly<MailboxLimits>;
+}
+/** Called for a data frame the mailbox refuses, so the host can report why; the sender is given no reply, since data-domain.cddl defines no error frame. */
+export type MailboxRefusalReason = "not-the-owner" | "unregistered-sender" | "log-limit" | "size-limit" | "entry-limit" | "gap";
+export interface Mailbox {
+  /**
+   * Handles one data frame from a connection. `sender` is the device the hub has verified that connection to be, or undefined when it has not gossiped one. Returns the frame to send back, or null for none. `onRefused` is told when the frame was refused and why.
+   */
+  handle: (sender: DeviceId | undefined, frame: Readonly<DataHaveFrame | DataRequestFrame | DataEntriesFrame>, onRefused?: (reason: MailboxRefusalReason) => void) => Promise<Frame | null>;
+}
+/** The data frames a mailbox answers. */
+export declare function isDataFrame(frame: Readonly<Frame>): frame is DataHaveFrame | DataRequestFrame | DataEntriesFrame;
+export declare function createMailbox(options: Readonly<MailboxOptions>): Mailbox;
+//#endregion

package/dist/domain/hub-mailbox.d.mts

@@ -0,0 +1,29 @@
+import { D as DeviceId, E as DataRequestFrame, N as Frame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-DCDae3z4.mjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
+//#region src/domain/hub-mailbox.d.ts
+export interface MailboxLimits {
+  /** How many devices' logs the mailbox will hold at once. */
+  readonly maxLogs: number;
+  /** How many bytes of entries one log may hold in total. */
+  readonly maxLogBytes: number;
+  /** How large one entry may be. */
+  readonly maxEntryBytes: number;
+  /** How many entries one reply carries at most; a longer log takes more rounds. */
+  readonly readBatch: number;
+}
+export interface MailboxOptions {
+  readonly storage: KeyValueStorage;
+  readonly limits: Readonly<MailboxLimits>;
+}
+/** Called for a data frame the mailbox refuses, so the host can report why; the sender is given no reply, since data-domain.cddl defines no error frame. */
+export type MailboxRefusalReason = "not-the-owner" | "unregistered-sender" | "log-limit" | "size-limit" | "entry-limit" | "gap";
+export interface Mailbox {
+  /**
+   * Handles one data frame from a connection. `sender` is the device the hub has verified that connection to be, or undefined when it has not gossiped one. Returns the frame to send back, or null for none. `onRefused` is told when the frame was refused and why.
+   */
+  handle: (sender: DeviceId | undefined, frame: Readonly<DataHaveFrame | DataRequestFrame | DataEntriesFrame>, onRefused?: (reason: MailboxRefusalReason) => void) => Promise<Frame | null>;
+}
+/** The data frames a mailbox answers. */
+export declare function isDataFrame(frame: Readonly<Frame>): frame is DataHaveFrame | DataRequestFrame | DataEntriesFrame;
+export declare function createMailbox(options: Readonly<MailboxOptions>): Mailbox;
+//#endregion

package/dist/domain/hub-mailbox.mjs

@@ -0,0 +1,79 @@
+import { deviceIdToHex } from "./device-id.mjs";
+import { handleDataEntries, handleDataHave, handleDataRequest, headSeqFor } from "./data-sync.mjs";
+//#region src/domain/hub-mailbox.ts
+/** The data frames a mailbox answers. */
+function isDataFrame(frame) {
+	return frame.type === "data-have" || frame.type === "data-request" || frame.type === "data-entries";
+}
+const LOG_COUNT_KEY = "mailbox/log-count";
+function logBytesKey(peer) {
+	return `mailbox/${deviceIdToHex(peer)}/bytes`;
+}
+function encodeCount(value) {
+	return new TextEncoder().encode(String(value));
+}
+async function readCount(storage, key) {
+	const raw = await storage.get(key);
+	return raw === void 0 ? 0 : Number(new TextDecoder().decode(raw));
+}
+function sameDevice(a, b) {
+	return deviceIdToHex(a) === deviceIdToHex(b);
+}
+function createMailbox(options) {
+	const { storage, limits } = options;
+	async function handleHave(sender, frame, refuse) {
+		if (!sameDevice(sender, frame.peer)) {
+			refuse("not-the-owner");
+			return null;
+		}
+		if (await headSeqFor(storage, frame.peer) === 0) {
+			if (await readCount(storage, LOG_COUNT_KEY) >= limits.maxLogs) {
+				refuse("log-limit");
+				return null;
+			}
+		}
+		return handleDataHave(storage, frame);
+	}
+	async function handleEntries(sender, frame, refuse) {
+		if (!sameDevice(sender, frame.peer)) {
+			refuse("not-the-owner");
+			return null;
+		}
+		if (frame.entries.some((entry) => entry.length > limits.maxEntryBytes)) {
+			refuse("size-limit");
+			return null;
+		}
+		const held = await readCount(storage, logBytesKey(frame.peer));
+		const added = frame.entries.reduce((sum, entry) => sum + entry.length, 0);
+		if (held + added > limits.maxLogBytes) {
+			refuse("entry-limit");
+			return null;
+		}
+		const isNewLog = await headSeqFor(storage, frame.peer) === 0;
+		if (isNewLog && await readCount(storage, LOG_COUNT_KEY) >= limits.maxLogs) {
+			refuse("log-limit");
+			return null;
+		}
+		if (!(await handleDataEntries(storage, frame)).ok) {
+			refuse("gap");
+			return null;
+		}
+		await storage.set(logBytesKey(frame.peer), encodeCount(held + added));
+		if (isNewLog && frame.entries.length > 0) await storage.set(LOG_COUNT_KEY, encodeCount(await readCount(storage, LOG_COUNT_KEY) + 1));
+		return null;
+	}
+	return { async handle(sender, frame, onRefused) {
+		const refuse = (reason) => {
+			onRefused?.(reason);
+		};
+		if (sender === void 0) {
+			refuse("unregistered-sender");
+			return null;
+		}
+		if (frame.type === "data-have") return handleHave(sender, frame, refuse);
+		if (frame.type === "data-entries") return handleEntries(sender, frame, refuse);
+		return handleDataRequest(storage, frame, limits.readBatch);
+	} };
+}
+//#endregion
+export { createMailbox, isDataFrame };

package/dist/domain/mesh-session.d.cts

@@ -1,7 +1,7 @@
 import { D as DeviceId, E as DataRequestFrame, N as Frame, T as DataHaveFrame, U as ManageError, V as ManageCommand, W as ManageOk, bt as RevocationEntry, et as PeerAdvert, f as CapabilityScope, lt as ProtocolVersion, nn as TopologyPeers, p as CapabilityToken, w as DataEntriesFrame } from "../protocol-DCDae3z4.cjs";
+import { r as Transport, t as Connection } from "../transport-CfW7fsGK.cjs";
 import { t as IdentityPort } from "../identity-DVCNuFLG.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
-import { r as Transport, t as Connection } from "../transport-CfW7fsGK.cjs";
 //#region src/domain/mesh-session.d.ts
 /** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
 export declare const HANDSHAKE_TIMEOUT_MS = 3000;

package/dist/domain/mesh-session.d.mts

@@ -1,7 +1,7 @@
 import { D as DeviceId, E as DataRequestFrame, N as Frame, T as DataHaveFrame, U as ManageError, V as ManageCommand, W as ManageOk, bt as RevocationEntry, et as PeerAdvert, f as CapabilityScope, lt as ProtocolVersion, nn as TopologyPeers, p as CapabilityToken, w as DataEntriesFrame } from "../protocol-DCDae3z4.mjs";
+import { r as Transport, t as Connection } from "../transport-iLBxIkRS.mjs";
 import { t as IdentityPort } from "../identity-DcaYgjXT.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
-import { r as Transport, t as Connection } from "../transport-iLBxIkRS.mjs";
 //#region src/domain/mesh-session.d.ts
 /** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
 export declare const HANDSHAKE_TIMEOUT_MS = 3000;

package/dist/domain/notice-board.d.cts

@@ -1,5 +1,5 @@
 import { D as DeviceId, Ot as RoomNotice, T as DataHaveFrame, kt as RoomNoticeClaims, p as CapabilityToken } from "../protocol-DCDae3z4.cjs";
-import { KeyValueStorage } from "../ports/storage.cjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
 import { t as IdentityPort } from "../identity-DVCNuFLG.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
 import { a as RevocationCheck } from "../tokens-DqFu7iMX.cjs";

package/dist/domain/notice-board.d.mts

@@ -1,5 +1,5 @@
 import { D as DeviceId, Ot as RoomNotice, T as DataHaveFrame, kt as RoomNoticeClaims, p as CapabilityToken } from "../protocol-DCDae3z4.mjs";
-import { KeyValueStorage } from "../ports/storage.mjs";
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
 import { t as IdentityPort } from "../identity-DcaYgjXT.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
 import { a as RevocationCheck } from "../tokens-CBiSYuzp.mjs";

package/dist/domain/pinned-address.cjs

@@ -0,0 +1,39 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/domain/pinned-address.ts
+const PIN_FRAGMENT = "#sha256=";
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+function hexToBytes(hex) {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < bytes.length; index++) bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+}
+/**
+* The address a node advertises for WebTransport: `https://host:port#sha256=<hex>`, the address and the hash of the certificate it serves. A client that pins the hash needs nothing else from the network to trust the node, so the pair travels together in one string, which `wire-candidate.address` already permits.
+*/
+function formatPinnedAddress(hostPort, sha256Hex) {
+	return `https://${hostPort}${PIN_FRAGMENT}${sha256Hex}`;
+}
+/**
+* Whether an address carries a certificate pin, and so is dialled over WebTransport rather than WebSocket.
+*/
+function isPinnedAddress(address) {
+	return address.startsWith("https://") && address.includes(PIN_FRAGMENT);
+}
+/**
+* Splits an address of the form `https://host:port#sha256=<hex>`.
+* @throws Error when the address is not `https://` or carries no valid 64-digit lowercase hex hash.
+*/
+function parsePinnedAddress(address) {
+	const url = new URL(address);
+	const hex = url.hash.startsWith(PIN_FRAGMENT) ? url.hash.slice(8) : "";
+	if (url.protocol !== "https:" || !SHA256_HEX_PATTERN.test(hex)) throw new Error(`expected "https://host:port${PIN_FRAGMENT}<64 hex digits>", got "${address}"`);
+	url.hash = "";
+	return {
+		url: url.toString(),
+		sha256: hexToBytes(hex)
+	};
+}
+//#endregion
+exports.formatPinnedAddress = formatPinnedAddress;
+exports.isPinnedAddress = isPinnedAddress;
+exports.parsePinnedAddress = parsePinnedAddress;

package/dist/domain/pinned-address.d.cts

@@ -0,0 +1,22 @@
+//#region src/domain/pinned-address.d.ts
+/** A WebTransport address and the SHA-256 hash of the certificate it is expected to serve. */
+export interface PinnedAddress {
+  /** `https://host:port/`, the URL to open. */
+  readonly url: string;
+  /** The certificate's SHA-256 hash, as bytes. */
+  readonly sha256: Uint8Array<ArrayBuffer>;
+}
+/**
+ * The address a node advertises for WebTransport: `https://host:port#sha256=<hex>`, the address and the hash of the certificate it serves. A client that pins the hash needs nothing else from the network to trust the node, so the pair travels together in one string, which `wire-candidate.address` already permits.
+ */
+export declare function formatPinnedAddress(hostPort: string, sha256Hex: string): string;
+/**
+ * Whether an address carries a certificate pin, and so is dialled over WebTransport rather than WebSocket.
+ */
+export declare function isPinnedAddress(address: string): boolean;
+/**
+ * Splits an address of the form `https://host:port#sha256=<hex>`.
+ * @throws Error when the address is not `https://` or carries no valid 64-digit lowercase hex hash.
+ */
+export declare function parsePinnedAddress(address: string): PinnedAddress;
+//#endregion

package/dist/domain/pinned-address.d.mts

@@ -0,0 +1,22 @@
+//#region src/domain/pinned-address.d.ts
+/** A WebTransport address and the SHA-256 hash of the certificate it is expected to serve. */
+export interface PinnedAddress {
+  /** `https://host:port/`, the URL to open. */
+  readonly url: string;
+  /** The certificate's SHA-256 hash, as bytes. */
+  readonly sha256: Uint8Array<ArrayBuffer>;
+}
+/**
+ * The address a node advertises for WebTransport: `https://host:port#sha256=<hex>`, the address and the hash of the certificate it serves. A client that pins the hash needs nothing else from the network to trust the node, so the pair travels together in one string, which `wire-candidate.address` already permits.
+ */
+export declare function formatPinnedAddress(hostPort: string, sha256Hex: string): string;
+/**
+ * Whether an address carries a certificate pin, and so is dialled over WebTransport rather than WebSocket.
+ */
+export declare function isPinnedAddress(address: string): boolean;
+/**
+ * Splits an address of the form `https://host:port#sha256=<hex>`.
+ * @throws Error when the address is not `https://` or carries no valid 64-digit lowercase hex hash.
+ */
+export declare function parsePinnedAddress(address: string): PinnedAddress;
+//#endregion

package/dist/domain/pinned-address.mjs

@@ -0,0 +1,36 @@
+//#region src/domain/pinned-address.ts
+const PIN_FRAGMENT = "#sha256=";
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+function hexToBytes(hex) {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < bytes.length; index++) bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+}
+/**
+* The address a node advertises for WebTransport: `https://host:port#sha256=<hex>`, the address and the hash of the certificate it serves. A client that pins the hash needs nothing else from the network to trust the node, so the pair travels together in one string, which `wire-candidate.address` already permits.
+*/
+function formatPinnedAddress(hostPort, sha256Hex) {
+	return `https://${hostPort}${PIN_FRAGMENT}${sha256Hex}`;
+}
+/**
+* Whether an address carries a certificate pin, and so is dialled over WebTransport rather than WebSocket.
+*/
+function isPinnedAddress(address) {
+	return address.startsWith("https://") && address.includes(PIN_FRAGMENT);
+}
+/**
+* Splits an address of the form `https://host:port#sha256=<hex>`.
+* @throws Error when the address is not `https://` or carries no valid 64-digit lowercase hex hash.
+*/
+function parsePinnedAddress(address) {
+	const url = new URL(address);
+	const hex = url.hash.startsWith(PIN_FRAGMENT) ? url.hash.slice(8) : "";
+	if (url.protocol !== "https:" || !SHA256_HEX_PATTERN.test(hex)) throw new Error(`expected "https://host:port${PIN_FRAGMENT}<64 hex digits>", got "${address}"`);
+	url.hash = "";
+	return {
+		url: url.toString(),
+		sha256: hexToBytes(hex)
+	};
+}
+//#endregion
+export { formatPinnedAddress, isPinnedAddress, parsePinnedAddress };

package/dist/domain/relay-hub.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_domain_peer_advert = require("./peer-advert.cjs");
 const require_domain_advert_extension_policy = require("./advert-extension-policy.cjs");
+const require_domain_hub_mailbox = require("./hub-mailbox.cjs");
 //#region src/domain/relay-hub.ts
 const HEX_RADIX = 16;
 const HEX_DIGITS_PER_BYTE = 2;
@@ -192,6 +193,19 @@ function createRelayHub(options) {
 			});
 			return;
 		}
+		if (options.mailbox !== void 0 && require_domain_hub_mailbox.isDataFrame(frame)) {
+			const sender = connectionDevice.get(connection);
+			const reply = await options.mailbox.handle(sender, frame, (reason) => {
+				options.onMailboxRefused?.({
+					device: sender,
+					reason
+				});
+			});
+			if (reply !== null) try {
+				await connection.send(reply);
+			} catch {}
+			return;
+		}
 		if (frame.type === "ping") {
 			try {
 				await connection.send({ type: "pong" });

package/dist/domain/relay-hub.d.cts

@@ -1,6 +1,7 @@
 import { D as DeviceId, N as Frame, et as PeerAdvert } from "../protocol-DCDae3z4.cjs";
 import { t as Connection } from "../transport-CfW7fsGK.cjs";
 import { AdvertExtensionPolicy } from "./advert-extension-policy.cjs";
+import { Mailbox, MailboxRefusalReason } from "./hub-mailbox.cjs";
 import { PeerAdvertVerifier } from "./peer-advert.cjs";
 //#region src/domain/relay-hub.d.ts
 /**
@@ -36,6 +37,15 @@ export interface RelayHubOptions {
   readonly extensionPolicy?: AdvertExtensionPolicy;
   /** Called with each advert refused by extensionPolicy, so the host can report it; the advert's sender is given no reply, since the transport spec defines none. */
   readonly onAdvertRefused?: (refusal: Readonly<AdvertRefusal>) => void;
+  /**
+   * The announcer role: a mailbox that holds other devices' `core/data` logs while they are offline (hub-mailbox.ts). Absent, data frames sent to this hub are ignored, as they always were.
+   */
+  readonly mailbox?: Mailbox;
+  /** Called with each data frame the mailbox refused and why, so the host can report it; the sender is given no reply. */
+  readonly onMailboxRefused?: (refusal: Readonly<{
+    device: DeviceId | undefined;
+    reason: MailboxRefusalReason;
+  }>) => void;
   /** Called whenever the value exportConnection returns for a connection changes: it gossiped an advert, gained or lost a pairing, or had one of its adverts taken over by another connection. A host whose own instance can be torn down while its connections stay open (the Cloudflare hub's hibernating Durable Object) reads the new value back with exportConnection, persists it against the connection, and hands it to a later instance through restoreConnections. */
   readonly onConnectionStateChanged?: (connection: Readonly<Connection>) => void;
 }

package/dist/domain/relay-hub.d.mts

@@ -1,6 +1,7 @@
 import { D as DeviceId, N as Frame, et as PeerAdvert } from "../protocol-DCDae3z4.mjs";
 import { t as Connection } from "../transport-iLBxIkRS.mjs";
 import { AdvertExtensionPolicy } from "./advert-extension-policy.mjs";
+import { Mailbox, MailboxRefusalReason } from "./hub-mailbox.mjs";
 import { PeerAdvertVerifier } from "./peer-advert.mjs";
 //#region src/domain/relay-hub.d.ts
 /**
@@ -36,6 +37,15 @@ export interface RelayHubOptions {
   readonly extensionPolicy?: AdvertExtensionPolicy;
   /** Called with each advert refused by extensionPolicy, so the host can report it; the advert's sender is given no reply, since the transport spec defines none. */
   readonly onAdvertRefused?: (refusal: Readonly<AdvertRefusal>) => void;
+  /**
+   * The announcer role: a mailbox that holds other devices' `core/data` logs while they are offline (hub-mailbox.ts). Absent, data frames sent to this hub are ignored, as they always were.
+   */
+  readonly mailbox?: Mailbox;
+  /** Called with each data frame the mailbox refused and why, so the host can report it; the sender is given no reply. */
+  readonly onMailboxRefused?: (refusal: Readonly<{
+    device: DeviceId | undefined;
+    reason: MailboxRefusalReason;
+  }>) => void;
   /** Called whenever the value exportConnection returns for a connection changes: it gossiped an advert, gained or lost a pairing, or had one of its adverts taken over by another connection. A host whose own instance can be torn down while its connections stay open (the Cloudflare hub's hibernating Durable Object) reads the new value back with exportConnection, persists it against the connection, and hands it to a later instance through restoreConnections. */
   readonly onConnectionStateChanged?: (connection: Readonly<Connection>) => void;
 }

package/dist/domain/relay-hub.mjs

@@ -1,5 +1,6 @@
 import { verifyPeerAdvert } from "./peer-advert.mjs";
 import { checkAdvertExtensions } from "./advert-extension-policy.mjs";
+import { isDataFrame } from "./hub-mailbox.mjs";
 //#region src/domain/relay-hub.ts
 const HEX_RADIX = 16;
 const HEX_DIGITS_PER_BYTE = 2;
@@ -191,6 +192,19 @@ function createRelayHub(options) {
 			});
 			return;
 		}
+		if (options.mailbox !== void 0 && isDataFrame(frame)) {
+			const sender = connectionDevice.get(connection);
+			const reply = await options.mailbox.handle(sender, frame, (reason) => {
+				options.onMailboxRefused?.({
+					device: sender,
+					reason
+				});
+			});
+			if (reply !== null) try {
+				await connection.send(reply);
+			} catch {}
+			return;
+		}
 		if (frame.type === "ping") {
 			try {
 				await connection.send({ type: "pong" });

package/dist/ports/storage.d.cts

@@ -1,9 +1,2 @@
-//#region src/ports/storage.d.ts
-export interface KeyValueStorage {
-  get: (key: string) => Promise<Uint8Array<ArrayBuffer> | undefined>;
-  set: (key: string, value: Uint8Array<ArrayBuffer>) => Promise<void>;
-  delete: (key: string) => Promise<void>;
-  /** Keys with the given prefix, in no particular order. */
-  keys: (prefix: string) => Promise<string[]>;
-}
-//#endregion
+import { t as KeyValueStorage } from "../storage-B403CRyu.cjs";
+export { KeyValueStorage };

package/dist/ports/storage.d.mts

@@ -1,9 +1,2 @@
-//#region src/ports/storage.d.ts
-export interface KeyValueStorage {
-  get: (key: string) => Promise<Uint8Array<ArrayBuffer> | undefined>;
-  set: (key: string, value: Uint8Array<ArrayBuffer>) => Promise<void>;
-  delete: (key: string) => Promise<void>;
-  /** Keys with the given prefix, in no particular order. */
-  keys: (prefix: string) => Promise<string[]>;
-}
-//#endregion
+import { t as KeyValueStorage } from "../storage-B403CRyu.mjs";
+export { KeyValueStorage };

package/dist/storage-B403CRyu.d.cts

@@ -0,0 +1,10 @@
+//#region src/ports/storage.d.ts
+interface KeyValueStorage {
+  get: (key: string) => Promise<Uint8Array<ArrayBuffer> | undefined>;
+  set: (key: string, value: Uint8Array<ArrayBuffer>) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  /** Keys with the given prefix, in no particular order. */
+  keys: (prefix: string) => Promise<string[]>;
+}
+//#endregion
+export { KeyValueStorage as t };

package/dist/storage-B403CRyu.d.mts

@@ -0,0 +1,10 @@
+//#region src/ports/storage.d.ts
+interface KeyValueStorage {
+  get: (key: string) => Promise<Uint8Array<ArrayBuffer> | undefined>;
+  set: (key: string, value: Uint8Array<ArrayBuffer>) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  /** Keys with the given prefix, in no particular order. */
+  keys: (prefix: string) => Promise<string[]>;
+}
+//#endregion
+export { KeyValueStorage as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "dependencies": {
     "cbor2": "2.3.0",
     "cddl.js": "1.0.1",
@@ -26,6 +26,10 @@
     "vitest": "5.0.0"
   },
   "exports": {
+    "./adapters/byte-stream-connection": {
+      "import": "./dist/adapters/byte-stream-connection.mjs",
+      "require": "./dist/adapters/byte-stream-connection.cjs"
+    },
     "./adapters/frame-codec": {
       "import": "./dist/adapters/frame-codec.mjs",
       "require": "./dist/adapters/frame-codec.cjs"
@@ -118,6 +122,10 @@
       "import": "./dist/domain/handshake.mjs",
       "require": "./dist/domain/handshake.cjs"
     },
+    "./domain/hub-mailbox": {
+      "import": "./dist/domain/hub-mailbox.mjs",
+      "require": "./dist/domain/hub-mailbox.cjs"
+    },
     "./domain/mesh-session": {
       "import": "./dist/domain/mesh-session.mjs",
       "require": "./dist/domain/mesh-session.cjs"
@@ -138,6 +146,10 @@
       "import": "./dist/domain/ping-round-trips.mjs",
       "require": "./dist/domain/ping-round-trips.cjs"
     },
+    "./domain/pinned-address": {
+      "import": "./dist/domain/pinned-address.mjs",
+      "require": "./dist/domain/pinned-address.cjs"
+    },
     "./domain/relay-hub": {
       "import": "./dist/domain/relay-hub.mjs",
       "require": "./dist/domain/relay-hub.cjs"