@did-btcr2/method 0.28.0 → 0.32.0

package/src/core/aggregation/transport/http/client.ts

@@ -0,0 +1,409 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
+
+import { Identifier } from '../../../identifier.js';
+import type { Logger } from '../../logger.js';
+import { CONSOLE_LOGGER } from '../../logger.js';
+import type { BaseMessage } from '../../messages/base.js';
+import type { MessageHandler, Transport } from '../transport.js';
+import { reviveFromWire, signEnvelope, verifyEnvelope } from './envelope.js';
+import { HttpTransportError } from './errors.js';
+import {
+  DEFAULT_CLOCK_SKEW_SEC,
+  HTTP_ROUTE,
+  SSE_EVENT,
+  type SignedEnvelope,
+} from './protocol.js';
+import { buildRequestAuth } from './request-auth.js';
+import { parseSseStream } from './sse-stream.js';
+
+export interface HttpClientTransportConfig {
+  /** Base URL of the aggregation service (e.g. `https://aggregator.example.com/`). */
+  baseUrl: string | URL;
+  /** Custom `fetch` implementation (tests, Workers, React Native). Defaults to `globalThis.fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Diagnostic logger. Defaults to {@link CONSOLE_LOGGER}. */
+  logger?: Logger;
+  /** Reconnect backoff (ms) given attempt count (0-based). */
+  reconnectBackoff?: (attempt: number) => number;
+  /** Envelope / request-auth clock-skew tolerance in seconds. */
+  clockSkewSec?: number;
+}
+
+/** Default exponential backoff: 1s, 2s, 4s, ..., capped at 30s, 20% jitter. */
+export function defaultReconnectBackoff(attempt: number): number {
+  const base   = Math.min(1000 * 2 ** attempt, 30_000);
+  const jitter = base * 0.2 * Math.random();
+  return Math.floor(base + jitter);
+}
+
+interface ActorEntry {
+  keys: SchnorrKeyPair;
+  handlers: Map<string, MessageHandler>;
+  inboxAbort?: AbortController;
+}
+
+/**
+ * HTTP transport client. Implements the transport-agnostic {@link Transport}
+ * interface; the wire is fetch-based SSE for incoming events and fetch-based
+ * POST for outgoing messages. All runtime I/O goes through `fetchImpl` so
+ * tests can substitute a mock without touching the network.
+ */
+export class HttpClientTransport implements Transport {
+  readonly name = 'http';
+
+  readonly #baseUrl:      URL;
+  readonly #fetch:        typeof fetch;
+  readonly #logger:       Logger;
+  readonly #backoff:      (attempt: number) => number;
+  readonly #clockSkewSec: number;
+
+  readonly #actors: Map<string, ActorEntry>   = new Map();
+  readonly #peers:  Map<string, Uint8Array>   = new Map();
+
+  #started = false;
+  #broadcastAbort?: AbortController;
+
+  constructor(config: HttpClientTransportConfig) {
+    const base = typeof config.baseUrl === 'string' ? new URL(config.baseUrl) : new URL(config.baseUrl.href);
+    if(!base.pathname.endsWith('/')) base.pathname += '/';
+    this.#baseUrl      = base;
+    this.#logger       = config.logger ?? CONSOLE_LOGGER;
+    this.#backoff      = config.reconnectBackoff ?? defaultReconnectBackoff;
+    this.#clockSkewSec = config.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+
+    const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    if(typeof fetchImpl !== 'function') {
+      throw new HttpTransportError(
+        'No fetch implementation available. Pass config.fetchImpl explicitly.',
+        'NO_FETCH_IMPL',
+      );
+    }
+    this.#fetch = fetchImpl;
+  }
+
+  start(): void {
+    if(this.#started) return;
+    this.#started = true;
+
+    this.#broadcastAbort = new AbortController();
+    this.#runBroadcastLoop(this.#broadcastAbort.signal);
+
+    for(const [did, entry] of this.#actors) {
+      this.#openInbox(did, entry);
+    }
+  }
+
+  /**
+   * Tear down all SSE subscriptions and stop reconnect loops. Not part of the
+   * {@link Transport} interface, but needed in tests and whenever a client
+   * wants to cleanly disconnect without unregistering every actor.
+   *
+   * Idempotent. Actors remain registered (re-call {@link start} to resume).
+   */
+  stop(): void {
+    this.#broadcastAbort?.abort();
+    this.#broadcastAbort = undefined;
+    for(const entry of this.#actors.values()) {
+      entry.inboxAbort?.abort();
+      entry.inboxAbort = undefined;
+    }
+    this.#started = false;
+  }
+
+  registerActor(did: string, keys: SchnorrKeyPair): void {
+    const existing = this.#actors.get(did);
+    if(existing?.inboxAbort) existing.inboxAbort.abort();
+
+    const entry: ActorEntry = { keys, handlers: new Map() };
+    this.#actors.set(did, entry);
+    if(this.#started) this.#openInbox(did, entry);
+  }
+
+  unregisterActor(did: string): void {
+    const entry = this.#actors.get(did);
+    if(!entry) return;
+    entry.inboxAbort?.abort();
+    this.#actors.delete(did);
+    this.#peers.delete(did);
+  }
+
+  getActorPk(did: string): Uint8Array | undefined {
+    return this.#actors.get(did)?.keys.publicKey.compressed;
+  }
+
+  registerPeer(did: string, communicationPk: Uint8Array): void {
+    try {
+      new CompressedSecp256k1PublicKey(communicationPk);
+    } catch {
+      throw new HttpTransportError(
+        `Invalid communication public key for peer ${did}: expected a 33-byte compressed secp256k1 key.`,
+        'INVALID_PEER_KEY',
+        { did, keyLength: communicationPk.length },
+      );
+    }
+    this.#peers.set(did, communicationPk);
+  }
+
+  getPeerPk(did: string): Uint8Array | undefined {
+    return this.#peers.get(did);
+  }
+
+  registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
+    const actor = this.#actors.get(actorDid);
+    if(!actor) {
+      throw new HttpTransportError(
+        `Cannot register handler: actor ${actorDid} not registered. Call registerActor() first.`,
+        'UNKNOWN_ACTOR',
+        { did: actorDid },
+      );
+    }
+    actor.handlers.set(messageType, handler);
+  }
+
+  unregisterMessageHandler(actorDid: string, messageType: string): void {
+    this.#actors.get(actorDid)?.handlers.delete(messageType);
+  }
+
+  async sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void> {
+    const actor = this.#actors.get(sender);
+    if(!actor) {
+      throw new HttpTransportError(
+        `Unknown sender: ${sender}. Call registerActor() before sending messages.`,
+        'UNKNOWN_SENDER',
+        { did: sender },
+      );
+    }
+
+    const envelope = signEnvelope(
+      message,
+      { did: sender, keys: actor.keys },
+      { to: recipient },
+    );
+
+    const url = this.#route(HTTP_ROUTE.MESSAGES);
+    const res = await this.#fetch(url, {
+      method  : 'POST',
+      headers : { 'content-type': 'application/json' },
+      body    : JSON.stringify(envelope),
+    });
+
+    if(!res.ok) {
+      const body = await safeText(res);
+      throw new HttpTransportError(
+        `sendMessage failed: HTTP ${res.status}`,
+        'SEND_MESSAGE_HTTP',
+        { status: res.status, body: body.slice(0, 256), messageType: message.type },
+      );
+    }
+  }
+
+  publishRepeating(
+    message:   BaseMessage,
+    sender:    string,
+    intervalMs: number,
+    recipient?: string,
+  ): () => void {
+    let stopped = false;
+    const attempt = (): void => {
+      if(stopped) return;
+      this.sendMessage(message, sender, recipient).catch((err) => {
+        this.#logger.debug('publishRepeating send failed:', err);
+      });
+    };
+    attempt();
+    const timer = setInterval(attempt, intervalMs);
+    return (): void => {
+      if(stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    };
+  }
+
+  #route(template: string): URL {
+    // Strip the leading slash so `new URL(rel, base)` is resolved against the
+    // base's pathname instead of replacing it.
+    return new URL(template.replace(/^\//, ''), this.#baseUrl);
+  }
+
+  #openInbox(did: string, entry: ActorEntry): void {
+    const abort = new AbortController();
+    entry.inboxAbort = abort;
+    this.#runInboxLoop(did, entry, abort.signal);
+  }
+
+  async #runBroadcastLoop(signal: AbortSignal): Promise<void> {
+    const url = this.#route(HTTP_ROUTE.ADVERTS);
+    let attempt = 0;
+    while(!signal.aborted) {
+      try {
+        const res = await this.#fetch(url, {
+          method  : 'GET',
+          headers : { accept: 'text/event-stream' },
+          signal,
+        });
+        if(!res.ok || !res.body) {
+          this.#logger.warn(`Broadcast subscribe failed: HTTP ${res.status}`);
+          await sleep(this.#backoff(attempt++), signal);
+          continue;
+        }
+        attempt = 0;
+        for await (const ev of parseSseStream(res.body)) {
+          if(signal.aborted) return;
+          if(ev.event !== SSE_EVENT.ADVERT) continue;
+          this.#dispatchBroadcast(ev.data);
+        }
+      } catch(err) {
+        if(signal.aborted) return;
+        this.#logger.debug('Broadcast loop error:', err);
+        try {
+          await sleep(this.#backoff(attempt++), signal);
+        } catch {
+          return; // sleep was aborted
+        }
+      }
+    }
+  }
+
+  async #runInboxLoop(did: string, entry: ActorEntry, signal: AbortSignal): Promise<void> {
+    const url = this.#route(HTTP_ROUTE.ACTOR_INBOX.replace('{did}', encodeURIComponent(did)));
+    let attempt = 0;
+    while(!signal.aborted) {
+      try {
+        const auth = buildRequestAuth(did, entry.keys, url.pathname);
+        const res = await this.#fetch(url, {
+          method  : 'GET',
+          headers : { accept: 'text/event-stream', authorization: auth },
+          signal,
+        });
+        if(!res.ok || !res.body) {
+          this.#logger.warn(`Inbox subscribe failed for ${did}: HTTP ${res.status}`);
+          await sleep(this.#backoff(attempt++), signal);
+          continue;
+        }
+        attempt = 0;
+        for await (const ev of parseSseStream(res.body)) {
+          if(signal.aborted) return;
+          if(ev.event !== SSE_EVENT.MESSAGE) continue;
+          await this.#dispatchInbox(ev.data, did, entry);
+        }
+      } catch(err) {
+        if(signal.aborted) return;
+        this.#logger.debug(`Inbox loop error for ${did}:`, err);
+        try {
+          await sleep(this.#backoff(attempt++), signal);
+        } catch {
+          return;
+        }
+      }
+    }
+  }
+
+  #dispatchBroadcast(dataJson: string): void {
+    const envelope = parseEnvelope(dataJson, this.#logger);
+    if(!envelope) return;
+
+    const senderPk = this.#resolveSenderPk(envelope.from);
+    if(!senderPk) {
+      this.#logger.debug(`Broadcast from unresolvable DID: ${envelope.from}`);
+      return;
+    }
+    try {
+      verifyEnvelope(envelope, senderPk, { clockSkewSec: this.#clockSkewSec });
+    } catch(err) {
+      this.#logger.debug('Broadcast envelope verification failed:', err);
+      return;
+    }
+
+    const revived = reviveFromWire(envelope.message) as Record<string, unknown>;
+    const flat = flattenMessage(revived);
+    const messageType = typeof flat.type === 'string' ? flat.type : undefined;
+    if(!messageType) return;
+
+    for(const actor of this.#actors.values()) {
+      const handler = actor.handlers.get(messageType);
+      if(handler) void Promise.resolve(handler(flat));
+    }
+  }
+
+  async #dispatchInbox(dataJson: string, actorDid: string, entry: ActorEntry): Promise<void> {
+    const envelope = parseEnvelope(dataJson, this.#logger);
+    if(!envelope) return;
+
+    const senderPk = this.#resolveSenderPk(envelope.from);
+    if(!senderPk) {
+      this.#logger.debug(`Inbox message from unresolvable DID: ${envelope.from}`);
+      return;
+    }
+    try {
+      verifyEnvelope(envelope, senderPk, {
+        clockSkewSec : this.#clockSkewSec,
+        expectedTo   : actorDid,
+      });
+    } catch(err) {
+      this.#logger.debug(`Inbox envelope verification failed for ${actorDid}:`, err);
+      return;
+    }
+
+    const revived = reviveFromWire(envelope.message) as Record<string, unknown>;
+    const flat = flattenMessage(revived);
+    const messageType = typeof flat.type === 'string' ? flat.type : undefined;
+    if(!messageType) return;
+
+    const handler = entry.handlers.get(messageType);
+    if(handler) await handler(flat);
+  }
+
+  #resolveSenderPk(did: string): CompressedSecp256k1PublicKey | undefined {
+    const peerBytes = this.#peers.get(did);
+    if(peerBytes) {
+      try { return new CompressedSecp256k1PublicKey(peerBytes); }
+      catch { /* fall through to DID decode */ }
+    }
+    try {
+      const components = Identifier.decode(did);
+      if(components.idType === 'KEY') {
+        return new CompressedSecp256k1PublicKey(components.genesisBytes);
+      }
+    } catch {
+      // Not a decodable did:btcr2 KEY identifier.
+    }
+    return undefined;
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if(ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(new Error('aborted'));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if(signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+async function safeText(res: Response): Promise<string> {
+  try { return await res.text(); }
+  catch { return ''; }
+}
+
+function parseEnvelope(dataJson: string, logger: Logger): SignedEnvelope | undefined {
+  try { return JSON.parse(dataJson) as SignedEnvelope; }
+  catch(err) {
+    logger.debug('SSE event: failed to parse envelope JSON:', err);
+    return undefined;
+  }
+}
+
+function flattenMessage(msg: Record<string, unknown>): Record<string, unknown> {
+  if(msg.body && typeof msg.body === 'object') {
+    return { ...msg, ...(msg.body as Record<string, unknown>) };
+  }
+  return msg;
+}

package/src/core/aggregation/transport/http/envelope.ts

@@ -0,0 +1,204 @@
+import { canonicalHashBytes } from '@did-btcr2/common';
+import type { CompressedSecp256k1PublicKey, SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
+
+import type { BaseMessage } from '../../messages/base.js';
+import { HttpTransportError } from './errors.js';
+import {
+  DEFAULT_CLOCK_SKEW_SEC,
+  DEFAULT_NONCE_LEN_BYTES,
+  HTTP_ENVELOPE_VERSION,
+  type SignedEnvelope,
+} from './protocol.js';
+
+/** Any shape acceptable as an envelope payload. `BaseMessage` instances are
+ *  `toJSON`-normalized before signing so class vs. POJO callers produce the
+ *  same canonical form. */
+export type EnvelopeMessage = BaseMessage | Record<string, unknown>;
+
+export interface SignEnvelopeOptions {
+  /** Recipient DID. Omit for broadcasts. */
+  to?: string;
+  /** Override the random nonce (tests). */
+  nonce?: string;
+  /** Override the unix-seconds timestamp (tests). */
+  timestamp?: number;
+}
+
+export interface VerifyEnvelopeOptions {
+  /** Reject if `envelope.from` doesn't match. */
+  expectedFrom?: string;
+  /** Reject if `envelope.to` doesn't match. Pass `undefined` to require a broadcast. */
+  expectedTo?: string;
+  /** Clock-skew tolerance (seconds). Defaults to {@link DEFAULT_CLOCK_SKEW_SEC}. */
+  clockSkewSec?: number;
+  /** Clock override (tests). Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+/**
+ * Build a {@link SignedEnvelope} around `message`.
+ *
+ * Pure function — no I/O beyond `randomBytes` for nonce generation (which
+ * uses the platform's cryptographic RNG: `crypto.getRandomValues` in browsers,
+ * `node:crypto` in Node). Deterministic when both `nonce` and `timestamp` are
+ * supplied via {@link SignEnvelopeOptions}.
+ */
+export function signEnvelope(
+  message: EnvelopeMessage,
+  sender:  { did: string; keys: SchnorrKeyPair },
+  opts:    SignEnvelopeOptions = {},
+): SignedEnvelope {
+  const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1000);
+  const nonce     = opts.nonce ?? bytesToHex(randomBytes(DEFAULT_NONCE_LEN_BYTES));
+  const messageJson = normalizeForWire(normalizeMessage(message)) as Record<string, unknown>;
+
+  const unsigned: Omit<SignedEnvelope, 'sig'> = {
+    v         : HTTP_ENVELOPE_VERSION,
+    from      : sender.did,
+    ...(opts.to !== undefined ? { to: opts.to } : {}),
+    timestamp,
+    nonce,
+    message   : messageJson,
+  };
+
+  const digest = canonicalHashBytes(unsigned);
+  const sig    = sender.keys.secretKey.sign(digest, { scheme: 'schnorr' });
+
+  return { ...unsigned, sig: bytesToHex(sig) };
+}
+
+/**
+ * Verify a {@link SignedEnvelope} against the sender's compressed secp256k1
+ * communication public key. Throws {@link HttpTransportError} on any failure;
+ * returns normally on success.
+ *
+ * Does NOT check nonce uniqueness — replay protection is the caller's
+ * responsibility (the server-side transport maintains an LRU cache).
+ */
+export function verifyEnvelope(
+  envelope: SignedEnvelope,
+  senderPk: CompressedSecp256k1PublicKey,
+  opts:     VerifyEnvelopeOptions = {},
+): void {
+  if(envelope.v !== HTTP_ENVELOPE_VERSION) {
+    throw new HttpTransportError(
+      `Unsupported envelope version: ${envelope.v}`,
+      'ENVELOPE_VERSION_MISMATCH',
+      { version: envelope.v, expected: HTTP_ENVELOPE_VERSION },
+    );
+  }
+
+  if(opts.expectedFrom !== undefined && envelope.from !== opts.expectedFrom) {
+    throw new HttpTransportError(
+      `Envelope from mismatch: expected ${opts.expectedFrom}, got ${envelope.from}`,
+      'ENVELOPE_FROM_MISMATCH',
+      { expected: opts.expectedFrom, got: envelope.from },
+    );
+  }
+
+  if('expectedTo' in opts && envelope.to !== opts.expectedTo) {
+    throw new HttpTransportError(
+      `Envelope to mismatch: expected ${opts.expectedTo ?? '<broadcast>'}, got ${envelope.to ?? '<broadcast>'}`,
+      'ENVELOPE_TO_MISMATCH',
+      { expected: opts.expectedTo, got: envelope.to },
+    );
+  }
+
+  const skewSec = opts.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+  const nowMs   = opts.now ? opts.now() : Date.now();
+  const nowSec  = Math.floor(nowMs / 1000);
+  const diff    = Math.abs(nowSec - envelope.timestamp);
+  if(diff > skewSec) {
+    throw new HttpTransportError(
+      `Envelope timestamp out of skew: ${diff}s > ${skewSec}s`,
+      'ENVELOPE_TIMESTAMP_SKEW',
+      { diff, skewSec, timestamp: envelope.timestamp, now: nowSec },
+    );
+  }
+
+  let sigBytes: Uint8Array;
+  try {
+    sigBytes = hexToBytes(envelope.sig);
+  } catch {
+    throw new HttpTransportError(
+      'Envelope signature is not valid hex',
+      'ENVELOPE_SIG_HEX',
+    );
+  }
+  if(sigBytes.length !== 64) {
+    throw new HttpTransportError(
+      `Invalid signature length: ${sigBytes.length} (expected 64)`,
+      'ENVELOPE_SIG_LENGTH',
+      { length: sigBytes.length },
+    );
+  }
+
+  const { sig: _sig, ...unsigned } = envelope;
+  const digest = canonicalHashBytes(unsigned);
+
+  const ok = senderPk.verify(sigBytes, digest, { scheme: 'schnorr' });
+  if(!ok) {
+    throw new HttpTransportError(
+      'Envelope signature verification failed',
+      'ENVELOPE_SIG_INVALID',
+    );
+  }
+}
+
+function normalizeMessage(message: EnvelopeMessage): Record<string, unknown> {
+  const maybeToJSON = (message as { toJSON?: () => unknown }).toJSON;
+  if(typeof maybeToJSON === 'function') {
+    return maybeToJSON.call(message) as Record<string, unknown>;
+  }
+  return message as Record<string, unknown>;
+}
+
+/**
+ * Recursively replace `Uint8Array` values with `{ __bytes: hex }` sentinel
+ * objects so they survive JSON canonicalization / HTTP body serialization.
+ * Pairs with {@link reviveFromWire}.
+ *
+ * Without this, `JSON.stringify` serializes a `Uint8Array` as an index-keyed
+ * object (`{"0":1,"1":2,...}`), which `canonicalize` then re-parses into a
+ * plain object — the receiver cannot reconstruct the original bytes even
+ * though the signature still verifies.
+ */
+export function normalizeForWire(value: unknown): unknown {
+  if(value instanceof Uint8Array) {
+    return { __bytes: bytesToHex(value) };
+  }
+  if(Array.isArray(value)) {
+    return value.map((v) => normalizeForWire(v));
+  }
+  if(value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for(const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = normalizeForWire(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Recursively convert `{ __bytes: hex }` sentinels back into `Uint8Array`
+ * values. Call on `envelope.message` *after* successful verification and
+ * before handing the payload to a runner's handler.
+ */
+export function reviveFromWire(value: unknown): unknown {
+  if(value && typeof value === 'object' && !Array.isArray(value)) {
+    const rec = value as Record<string, unknown>;
+    const keys = Object.keys(rec);
+    if(keys.length === 1 && keys[0] === '__bytes' && typeof rec.__bytes === 'string') {
+      return hexToBytes(rec.__bytes);
+    }
+    const out: Record<string, unknown> = {};
+    for(const [k, v] of Object.entries(rec)) out[k] = reviveFromWire(v);
+    return out;
+  }
+  if(Array.isArray(value)) {
+    return value.map((v) => reviveFromWire(v));
+  }
+  return value;
+}

package/src/core/aggregation/transport/http/errors.ts

@@ -0,0 +1,11 @@
+import { TransportAdapterError } from '../error.js';
+
+/**
+ * Errors raised by the HTTP transport adapter. Extends {@link TransportAdapterError}
+ * so callers can catch HTTP-specific failures narrowly or transport failures broadly.
+ */
+export class HttpTransportError extends TransportAdapterError {
+  constructor(message: string, type: string = 'HttpTransportError', data?: Record<string, any>) {
+    super(message, type, { adapter: 'http', ...(data ?? {}) });
+  }
+}

package/src/core/aggregation/transport/http/inbox-buffer.ts

@@ -0,0 +1,53 @@
+export interface StoredEvent {
+  /** Monotonic ID assigned at append time. Stable across the buffer's lifetime. */
+  id: string;
+  /** SSE event name. */
+  event: string;
+  /** SSE data payload (typically a JSON-stringified {@link SignedEnvelope}). */
+  data: string;
+}
+
+/**
+ * Fixed-capacity FIFO ring buffer of SSE events for a single actor's inbox.
+ *
+ * When a subscriber (re)connects with a `Last-Event-ID` header, the server
+ * uses {@link since} to replay everything that arrived while the subscriber
+ * was disconnected. Events older than the replay window (evicted from the
+ * ring) are unrecoverable — callers should choose `capacity` based on
+ * expected message rate × acceptable reconnect window.
+ */
+export class InboxBuffer {
+  readonly #capacity: number;
+  readonly #entries: StoredEvent[] = [];
+  #nextId = 1;
+
+  constructor(capacity = 100) {
+    if(capacity < 1) throw new Error(`InboxBuffer capacity must be >= 1; got ${capacity}`);
+    this.#capacity = capacity;
+  }
+
+  /** Append an event. Returns the stored record (including its assigned id). */
+  append(event: string, data: string): StoredEvent {
+    const stored: StoredEvent = { id: String(this.#nextId++), event, data };
+    this.#entries.push(stored);
+    if(this.#entries.length > this.#capacity) this.#entries.shift();
+    return stored;
+  }
+
+  /**
+   * Return stored events with id strictly greater than `lastEventId`. If
+   * `lastEventId` is unset or unparseable, returns everything currently
+   * retained.
+   */
+  since(lastEventId?: string): StoredEvent[] {
+    if(!lastEventId) return this.#entries.slice();
+    const boundary = Number(lastEventId);
+    if(!Number.isFinite(boundary)) return this.#entries.slice();
+    return this.#entries.filter((e) => Number(e.id) > boundary);
+  }
+
+  /** Currently retained event count. */
+  size(): number {
+    return this.#entries.length;
+  }
+}

package/src/core/aggregation/transport/http/index.ts

@@ -0,0 +1,11 @@
+export * from './errors.js';
+export * from './protocol.js';
+export * from './envelope.js';
+export * from './sse-stream.js';
+export * from './sse-writer.js';
+export * from './request-auth.js';
+export * from './nonce-cache.js';
+export * from './rate-limiter.js';
+export * from './inbox-buffer.js';
+export * from './client.js';
+export * from './server.js';