@did-btcr2/method 0.28.0 → 0.32.0

package/src/core/aggregation/transport/http/sse-stream.ts

@@ -0,0 +1,121 @@
+/**
+ * Parsed Server-Sent Events record.
+ *
+ * Events without a `data` field are never yielded (per the SSE spec — only a
+ * blank line that follows at least one `data:` line dispatches an event).
+ */
+export interface SseEvent {
+  /** Optional event name (from `event:` field). Defaults to "message" if omitted. */
+  event?: string;
+  /** Accumulated data payload (multiple `data:` lines joined with `\n`). */
+  data: string;
+  /** Last-Event-ID value for reconnect resumption. */
+  id?: string;
+  /** Retry delay hint in milliseconds. */
+  retry?: number;
+}
+
+/**
+ * Parse an SSE stream into an async iterable of {@link SseEvent} records.
+ *
+ * The parser follows the HTML Living Standard ({@link https://html.spec.whatwg.org/multipage/server-sent-events.html})
+ * closely enough for our needs: LF and CRLF line terminators, multi-line
+ * `data` fields, `event` / `id` / `retry` fields, and `:`-prefixed comments.
+ * CR-only line terminators are not supported (every mainstream SSE
+ * implementation emits LF or CRLF).
+ *
+ * Pure, runtime-agnostic — works anywhere `ReadableStream<Uint8Array>` and
+ * `TextDecoder` exist (browsers and Node 22+).
+ *
+ * The caller owns stream lifecycle: cancellation should be effected via an
+ * `AbortController` on the producing `fetch`, which propagates as a read
+ * error and cleanly unwinds this generator's `finally`.
+ */
+export async function* parseSseStream(
+  readable: ReadableStream<Uint8Array>,
+): AsyncGenerator<SseEvent, void, void> {
+  const decoder = new TextDecoder('utf-8');
+  const reader  = readable.getReader();
+
+  let buffer  = '';
+  let pending: { event?: string; data?: string; id?: string; retry?: number } = {};
+
+  const dispatchPending = (): SseEvent | null => {
+    if(pending.data === undefined) {
+      pending = {};
+      return null;
+    }
+    const ev: SseEvent = { data: pending.data };
+    if(pending.event !== undefined) ev.event = pending.event;
+    if(pending.id    !== undefined) ev.id    = pending.id;
+    if(pending.retry !== undefined) ev.retry = pending.retry;
+    pending = {};
+    return ev;
+  };
+
+  const processLine = (line: string): void => {
+    if(line.startsWith(':')) return; // comment
+
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let   value = colon === -1 ? '' : line.slice(colon + 1);
+    if(value.startsWith(' ')) value = value.slice(1);
+
+    switch(field) {
+      case 'data':
+        pending.data = pending.data === undefined ? value : `${pending.data}\n${value}`;
+        break;
+      case 'event':
+        pending.event = value;
+        break;
+      case 'id':
+        // Per spec: ignore ids containing NUL.
+        if(!value.includes('\0')) pending.id = value;
+        break;
+      case 'retry': {
+        const n = Number(value);
+        if(Number.isInteger(n) && n >= 0) pending.retry = n;
+        break;
+      }
+      // Other fields (including unknown names) are ignored per the spec.
+    }
+  };
+
+  try {
+    for(;;) {
+      const { value, done } = await reader.read();
+      if(done) {
+        // Flush any bytes the decoder is still holding.
+        buffer += decoder.decode();
+        if(buffer.length > 0) {
+          const line = buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer;
+          if(line.length > 0) processLine(line);
+          buffer = '';
+        }
+        const tail = dispatchPending();
+        if(tail) yield tail;
+        return;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Drain as many complete lines as are available.
+      let lineEnd = buffer.indexOf('\n');
+      while(lineEnd !== -1) {
+        let line = buffer.slice(0, lineEnd);
+        if(line.endsWith('\r')) line = line.slice(0, -1);
+        buffer = buffer.slice(lineEnd + 1);
+
+        if(line.length === 0) {
+          const ev = dispatchPending();
+          if(ev) yield ev;
+        } else {
+          processLine(line);
+        }
+        lineEnd = buffer.indexOf('\n');
+      }
+    }
+  } finally {
+    try { reader.releaseLock(); } catch { /* already released */ }
+  }
+}

package/src/core/aggregation/transport/http/sse-writer.ts

@@ -0,0 +1,23 @@
+/**
+ * Format an SSE event frame. Pairs with {@link parseSseStream}.
+ *
+ * Multi-line `data` is split across multiple `data:` lines per the SSE spec —
+ * each embedded `\n` becomes its own line, and the parser rejoins them.
+ *
+ * The returned string includes a trailing blank line (the dispatch marker).
+ */
+export function formatSseEvent(event: string, data: string, id?: string): string {
+  const lines: string[] = [];
+  if(id !== undefined) lines.push(`id: ${id}`);
+  lines.push(`event: ${event}`);
+  for(const part of data.split('\n')) lines.push(`data: ${part}`);
+  lines.push('');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** SSE comment frame (server keepalive). Lines starting with `:` are ignored by compliant parsers. */
+export function formatSseComment(comment: string): string {
+  const safe = comment.replace(/\n/g, ' ');
+  return `: ${safe}\n\n`;
+}

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

@@ -3,3 +3,4 @@ export * from './error.js';
 export * from './factory.js';
 export * from './nostr.js';
 export * from './didcomm.js';
+export * from './http/index.js';

package/src/core/aggregation/transport/nostr.ts

@@ -2,9 +2,12 @@ import type { Did } from '@did-btcr2/common';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import type { SubCloser } from 'nostr-tools/abstract-pool';
 import type { Event, EventTemplate} from 'nostr-tools';
 import { finalizeEvent, nip44 } from 'nostr-tools';
 import { SimplePool } from 'nostr-tools/pool';
+import type { Logger } from '../logger.js';
+import { CONSOLE_LOGGER } from '../logger.js';
 import type { BaseMessage } from '../messages/base.js';
 import { COHORT_ADVERT } from '../messages/constants.js';
 import { isAggregationMessageType, isKeygenMessageType, isSignMessageType, isUpdateMessageType } from '../messages/guards.js';
@@ -24,12 +27,32 @@ export const DEFAULT_NOSTR_RELAYS = [
 
 export interface NostrTransportConfig {
   relays?: string[];
+  /**
+   * Optional logger for transport-level diagnostics (publish/subscribe events,
+   * relay rejections, parse failures). Defaults to {@link CONSOLE_LOGGER}.
+   */
+  logger?: Logger;
+  /**
+   * How far back (in milliseconds) to set the `since` filter on the broadcast
+   * (COHORT_ADVERT) subscription. Some public relays do NOT replay historical
+   * events to late subscribers when the filter has no `since`, so the advert
+   * gets lost if the subscription lands after the publish. A short lookback
+   * window nudges those relays into delivering recent adverts. Set to 0 to
+   * disable the filter entirely (unbounded history). Defaults to
+   * {@link DEFAULT_BROADCAST_LOOKBACK_MS} (5 minutes).
+   */
+  broadcastLookbackMs?: number;
 }
 
+/** Default `since` lookback for broadcast (COHORT_ADVERT) subscriptions: 5 minutes. */
+export const DEFAULT_BROADCAST_LOOKBACK_MS = 5 * 60 * 1000;
+
 /** Internal registration for a single actor sharing this transport. */
 interface ActorEntry {
   keys: SchnorrKeyPair;
   handlers: Map<string, MessageHandler>;
+  /** Relay-pool subscriptions opened for this actor. Closed on unregisterActor(). */
+  subscriptions: SubCloser[];
 }
 
 /**
@@ -56,9 +79,13 @@ export class NostrTransport implements Transport {
   #actors: Map<string, ActorEntry> = new Map();
   #peerRegistry: Map<string, Uint8Array> = new Map();
   #started = false;
+  #logger: Logger;
+  #broadcastLookbackMs: number;
 
   constructor(config?: NostrTransportConfig) {
     this.#relays = config?.relays ?? DEFAULT_NOSTR_RELAYS;
+    this.#logger = config?.logger ?? CONSOLE_LOGGER;
+    this.#broadcastLookbackMs = config?.broadcastLookbackMs ?? DEFAULT_BROADCAST_LOOKBACK_MS;
   }
 
   /**
@@ -70,11 +97,12 @@ export class NostrTransport implements Transport {
    * @example
    * const transport = new NostrTransport();
    * const keys = SchnorrKeyPair.generate();
-   * transport.registerActor('did:btcr2:...', keys);
+   * const did = DidBtcr2.create(keys.publicKey.compressed, { idType: 'KEY', network: 'mutinynet' });
+   * transport.registerActor(did, keys);
    * transport.start();
    */
-  public registerActor(did: string, keys: SchnorrKeyPair): void {
-    const entry: ActorEntry = { keys, handlers: new Map() };
+  registerActor(did: string, keys: SchnorrKeyPair): void {
+    const entry: ActorEntry = { keys, handlers: new Map(), subscriptions: [] };
     this.#actors.set(did, entry);
 
     // If already started, create a directed subscription for this actor
@@ -83,11 +111,57 @@ export class NostrTransport implements Transport {
     }
   }
 
-  public getActorPk(did: string): Uint8Array | undefined {
+  /**
+   * Detach an actor: drop its handlers, close its relay subscriptions, and remove its keys + peer
+   * mapping. Idempotent.
+   * @param {string} did - The DID of the actor to unregister.
+   * @returns {void}
+   * @throws {TransportAdapterError} If the transport is not started or if the pool is unavailable.
+   * @example
+   * transport.unregisterActor(did);
+   */
+  unregisterActor(did: string): void {
+    const entry = this.#actors.get(did);
+    if(!entry) return;
+    for(const sub of entry.subscriptions) {
+      try { sub.close(); } catch(err) { this.#logger.debug(`Error closing subscription for ${did}:`, err); }
+    }
+    entry.subscriptions.length = 0;
+    entry.handlers.clear();
+    this.#actors.delete(did);
+    this.#peerRegistry.delete(did);
+  }
+
+  /**
+   * Remove a single (actor, messageType) handler. Idempotent.
+   * @param {string} actorDid - The DID of the actor.
+   * @param {string} messageType - The type of message to unregister the handler for.
+   * @returns {void}
+   * @example
+   * transport.unregisterMessageHandler(actorDid, messageType);
+   */
+  unregisterMessageHandler(actorDid: string, messageType: string): void {
+    const actor = this.#actors.get(actorDid);
+    if(!actor) return;
+    actor.handlers.delete(messageType);
+  }
+
+  /**
+   * Gets the public key for a registered actor by their DID.
+   * @param {string} did - The DID of the registered actor to get the public key for.
+   * @returns {Uint8Array | undefined} The compressed public key bytes for the actor's DID, or
+   * undefined if the DID is not registered.
+   */
+  getActorPk(did: string): Uint8Array | undefined {
     return this.#actors.get(did)?.keys.publicKey.compressed;
   }
 
-  public registerPeer(did: string, communicationPk: Uint8Array): void {
+  /**
+   * Registers a peer's communication public key for encrypted messages.
+   * @param {string} did - The DID of the peer to register.
+   * @param {Uint8Array} communicationPk - The compressed secp256k1 public key bytes for the peer.
+   */
+  registerPeer(did: string, communicationPk: Uint8Array): void {
     try {
       new CompressedSecp256k1PublicKey(communicationPk);
     } catch {
@@ -99,11 +173,27 @@ export class NostrTransport implements Transport {
     this.#peerRegistry.set(did, communicationPk);
   }
 
-  public getPeerPk(did: string): Uint8Array | undefined {
+  /**
+   * Gets the registered communication public key for a peer by their DID.
+   * @param {string} did - The DID of the peer to get the communication public key for.
+   * @returns {Uint8Array | undefined} The compressed secp256k1 public key bytes for the peer, or
+   * undefined if the peer is not registered.
+   */
+  getPeerPk(did: string): Uint8Array | undefined {
     return this.#peerRegistry.get(did);
   }
 
-  public registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
+  /**
+   * Registers a message handler function for a specific actor and message type. The handler will be called
+   * when a message of the specified type is received for the actor's DID. The transport must have been
+   * started for handlers to be invoked. If the transport is already started, the handler will be registered
+   * immediately; otherwise, it will be registered when the transport starts and the actor's subscription is created.
+   * @param {string} actorDid - The DID of the actor to register the message handler for.
+   * @param {string} messageType - The type of message to handle.
+   * @param {MessageHandler} handler - The function to handle incoming messages of the specified type.
+   * @throws {TransportAdapterError} If the actor DID is not registered or if the handler is invalid.
+   */
+  registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
     const actor = this.#actors.get(actorDid);
     if(!actor) {
       throw new TransportAdapterError(
@@ -114,16 +204,41 @@ export class NostrTransport implements Transport {
     actor.handlers.set(messageType, handler);
   }
 
-  public start(): NostrTransport {
+  /**
+   * Starts the transport by connecting to the configured Nostr relays and setting up subscriptions
+   * for all registered actors. This method must be called after registering actors via registerActor()
+   * and before sending or receiving messages. The transport will subscribe to broadcast events (kind 1)
+   * for cohort adverts and directed events (kinds 1 and 1059) for each registered actor based on their
+   * public keys. Incoming events are processed and dispatched to the appropriate handlers based on
+   * message type. If the transport is already started, this method has no effect.
+   * @returns {NostrTransport}
+   */
+  start(): NostrTransport {
     if(this.#started) return this;
     this.#started = true;
 
     this.pool = new SimplePool();
-    const since = Math.floor(Date.now() / 1000);
 
-    // Broadcast subscription: kind 1 COHORT_ADVERT events (all actors receive these)
-    this.pool.subscribeMany(this.#relays, { kinds: [1], '#t': [COHORT_ADVERT], since }, {
-      onclose : (reasons: string[]) => console.debug('Nostr broadcast subscription closed', reasons),
+    // Broadcast subscription: kind 1 COHORT_ADVERT events (all actors receive
+    // these). Duplicate adverts are idempotent: AggregationParticipant stores
+    // discovered cohorts in a Map keyed by cohortId.
+    //
+    // The `since` filter is a workaround for relays that don't backfill
+    // historical events to late subscribers (observed on nos.lol and
+    // relay.snort.social). Without it, an advert published before a
+    // participant's subscription lands is lost on those relays. The default
+    // 5-minute window is generous enough to cover network + subscription
+    // setup delays while still excluding ancient traffic. Set
+    // broadcastLookbackMs to 0 to disable.
+    const broadcastFilter: { kinds: number[]; '#t': string[]; since?: number } = {
+      kinds : [1],
+      '#t'  : [COHORT_ADVERT],
+    };
+    if(this.#broadcastLookbackMs > 0) {
+      broadcastFilter.since = Math.floor((Date.now() - this.#broadcastLookbackMs) / 1000);
+    }
+    this.pool.subscribeMany(this.#relays, broadcastFilter, {
+      onclose : (reasons: string[]) => this.#logger.debug('Nostr broadcast subscription closed', reasons),
       onevent : this.#handleBroadcastEvent.bind(this),
     });
 
@@ -132,11 +247,23 @@ export class NostrTransport implements Transport {
       this.#subscribeDirected(did, entry);
     }
 
-    console.info(`NostrTransport started, listening on ${this.#relays.length} relay(s)`);
+    this.#logger.info(`NostrTransport started, listening on ${this.#relays.length} relay(s)`);
     return this;
   }
 
-  public async sendMessage(message: BaseMessage, sender: Did, to?: Did): Promise<void> {
+  /**
+   * Sends a message by publishing a Nostr event to the configured relays. The message is serialized
+   * as JSON and included in the event content.
+   * @param {BaseMessage} message - The aggregation message to send. Must include a valid `type` property.
+   * @param {Did} sender - The DID of the registered actor sending the message. Must have been
+   * registered via registerActor().
+   * @param {Did} [to] - Optional recipient DID for directed messages. Required for encrypted message
+   * types. If provided, must have been registered via registerPeer().
+   * @returns {Promise<void>} Resolves when the message has been published to the relays. Note that
+   * publication is best-effort: the method will resolve as long as at least one relay accepts the
+   * event, even if others reject it.
+   */
+  async sendMessage(message: BaseMessage, sender: Did, to?: Did): Promise<void> {
     const type = message.type;
 
     if(!type) {
@@ -178,7 +305,7 @@ export class NostrTransport implements Transport {
         tags,
         content    : JSON.stringify(message, NostrTransport.#jsonReplacer),
       } as EventTemplate, senderKeys.secretKey.bytes);
-      console.debug(`Publishing kind 1 [${type}]`);
+      this.#logger.debug(`Publishing kind 1 [${type}]`);
       await this.#publishToRelays(event);
       return;
     }
@@ -211,31 +338,91 @@ export class NostrTransport implements Transport {
         tags,
         content,
       } as EventTemplate, senderKeys.secretKey.bytes);
-      console.debug(`Publishing kind 1059 [${type}]`);
+      this.#logger.debug(`Publishing kind 1059 [${type}]`);
       await this.#publishToRelays(event);
       return;
     }
 
-    console.warn(`Unsupported message type: ${type}`);
+    this.#logger.warn(`Unsupported message type: ${type}`);
   }
 
+  /**
+   * Publish the message once immediately and then re-publish on an interval
+   * until the returned stop function is invoked.
+   *
+   * Useful for broadcast messages (COHORT_ADVERT) on relays that don't
+   * backfill historical events to late subscribers: republishing gives late
+   * joiners a window to discover the message without requiring protocol
+   * changes. Relay rate-limit / publish failures inside the interval are
+   * caught and logged rather than propagated — the caller should stop the
+   * repeater once the protocol condition is satisfied.
+   */
+  publishRepeating(message: BaseMessage, sender: Did, intervalMs: number, recipient?: Did): () => void {
+    let stopped = false;
+    // Fire the first publish eagerly; any error surfaces as a rejected
+    // promise that we swallow to avoid unhandled rejections — the caller can
+    // observe delivery via receive-side handlers.
+    void this.sendMessage(message, sender, recipient).catch((err) => {
+      this.#logger.debug('publishRepeating first send failed:', err);
+    });
+    const timer = setInterval(() => {
+      if(stopped) return;
+      void this.sendMessage(message, sender, recipient).catch((err) => {
+        this.#logger.debug('publishRepeating retry failed:', err);
+      });
+    }, intervalMs);
+    return () => {
+      if(stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    };
+  }
+
+  /**
+   * Creates a directed subscription for the given actor, filtering for messages that match the
+   * actor's public key. Messages received on this subscription are dispatched to the actor's
+   * registered handlers based on message type.
+   * @param {string} did - The DID of the actor to create the subscription for.
+   * @param {ActorEntry} entry - The actor's registration entry containing keys and handlers.
+   * @returns {void}
+   * @throws {TransportAdapterError} If the transport is not started or if the pool is unavailable.
+   */
   #subscribeDirected(did: string, entry: ActorEntry): void {
     if(!this.pool) return;
 
     const pkHex = bytesToHex(entry.keys.publicKey.x);
-    const since = Math.floor(Date.now() / 1000);
 
-    this.pool.subscribeMany(this.#relays, { kinds: [1, 1059], '#p': [pkHex], since }, {
-      onclose : (reasons: string[]) => console.debug(`Nostr directed subscription closed for ${did}`, reasons),
+    // No `since` filter: directed messages must be retrievable on reconnect /
+    // crash-recovery. Out-of-phase messages are silently dropped by the state
+    // machines (AggregationService, AggregationParticipant), so replayed stale
+    // messages are harmless.
+    const sub = this.pool.subscribeMany(this.#relays, { kinds: [1, 1059], '#p': [pkHex] }, {
+      onclose : (reasons: string[]) => this.#logger.debug(`Nostr directed subscription closed for ${did}`, reasons),
       onevent : this.#makeActorEventHandler(did),
     });
+    entry.subscriptions.push(sub);
   }
 
+  /**
+   * Creates an event handler function for a specific actor that processes incoming events, decrypts
+   * if necessary, and dispatches messages to the actor's registered handlers based on message type.
+   * @param {string} actorDid - The DID of the actor to create the event handler for.
+   * @returns {(event: Event) => Promise<void>} An asynchronous event handler function that
+   * processes incoming events for the specified actor.
+   */
   #makeActorEventHandler(actorDid: string): (event: Event) => Promise<void> {
     return async (event: Event) => {
       const actor = this.#actors.get(actorDid);
       if(!actor) return;
 
+      // Relay self-echo: sendMessage() adds the sender's own pubkey to the
+      // event's `p` tags (so recipients can reply). The directed subscription
+      // filter `{'#p': [actor_pk]}` therefore matches every event this actor
+      // publishes. Skip — we don't need to process our own outgoing events,
+      // and attempting to NIP-44-decrypt them fails with "invalid MAC" because
+      // the content was encrypted for the recipient, not self.
+      if(event.pubkey === bytesToHex(actor.keys.publicKey.x)) return;
+
       let message: Record<string, unknown>;
 
       try {
@@ -252,7 +439,7 @@ export class NostrTransport implements Transport {
           return;
         }
       } catch(err) {
-        console.debug(`Failed to parse event ${event.id} for ${actorDid}:`, err);
+        this.#logger.debug(`Failed to parse event ${event.id} for ${actorDid}:`, err);
         return;
       }
 
@@ -260,6 +447,16 @@ export class NostrTransport implements Transport {
     };
   }
 
+  /**
+   * Handles incoming broadcast events (kind 1) by parsing the event content, validating it as an
+   * aggregation message, and dispatching it to all registered actors that have handlers for the
+   * message type. This is used for COHORT_ADVERT messages that need to be received by all actors
+   * regardless of DID.
+   * @param {Event} event - The Nostr event to handle, expected to be a kind 1 broadcast containing
+   * a COHORT_ADVERT message. The event content is parsed and dispatched to all registered actors
+   * that have handlers for the
+   * @returns
+   */
   async #handleBroadcastEvent(event: Event): Promise<void> {
     if(event.kind !== 1) return;
 
@@ -267,7 +464,7 @@ export class NostrTransport implements Transport {
     try {
       message = JSON.parse(event.content, NostrTransport.#jsonReviver);
     } catch(err) {
-      console.debug(`Failed to parse broadcast event ${event.id}:`, err);
+      this.#logger.debug(`Failed to parse broadcast event ${event.id}:`, err);
       return;
     }
 
@@ -285,6 +482,18 @@ export class NostrTransport implements Transport {
     }
   }
 
+  /**
+   * Dispatches a parsed message to the appropriate handler of a registered actor based on message type.
+   * The message is expected to have already been parsed from the Nostr event content and validated as
+   * an aggregation message. If the message has a body, its properties are merged into the top-level
+   * message object for easier handler access. The message is then dispatched to the handler registered
+   * for its type, if one exists.
+   * @param {Record<string, unknown>} message - The message object parsed from a Nostr event, expected to
+   * @param {ActorEntry} actor - The registered actor entry containing keys and handlers to dispatch the message to.
+   * @returns {void}
+   * @throws {TransportAdapterError} If the message type is unsupported or if no handler is registered
+   * for the message type.
+   */
   #dispatchMessage(message: Record<string, unknown>, actor: ActorEntry): void {
     if(message.body && typeof message.body === 'object') {
       message = { ...message, ...(message.body as Record<string, unknown>) };
@@ -297,6 +506,16 @@ export class NostrTransport implements Transport {
     if(handler) handler(message);
   }
 
+  /**
+   * Publishes a Nostr event to the configured relays and handles the results. The method waits for all
+   * relay promises to settle and checks how many accepted or rejected the event. If all relays reject the event,
+   * an error is thrown. Otherwise, the method completes successfully even if some relays rejected the event,
+   * as long as at least one relay accepted it. Relay rejections are logged for debugging purposes.
+   * @param {Event} event - The Nostr event to publish to the configured relays. The event should already
+   * @returns {Promise<void>} A promise that resolves if the event was accepted by at least one relay, or rejects
+   * with a TransportAdapterError if all relays rejected the event.
+   * @throws {TransportAdapterError} If the pool is not initialized or if all relays reject the event.
+   */
   async #publishToRelays(event: Event): Promise<void> {
     const relayPromises = this.pool?.publish(this.#relays, event);
     if(!relayPromises?.length) return;
@@ -306,7 +525,7 @@ export class NostrTransport implements Transport {
     const rejected = results.filter(r => r.status === 'rejected');
 
     for(const r of rejected) {
-      console.debug(`Relay rejected event ${event.id}: ${(r as PromiseRejectedResult).reason}`);
+      this.#logger.debug(`Relay rejected event ${event.id}: ${(r as PromiseRejectedResult).reason}`);
     }
 
     if(accepted === 0) {
@@ -317,6 +536,18 @@ export class NostrTransport implements Transport {
     }
   }
 
+  /**
+   * Custom JSON replacer to handle serialization of Uint8Array values as hex strings in message
+   * content. This allows messages containing binary data (e.g. public keys, signatures) to be correctly
+   * serialized to JSON for Nostr event content. The replacer checks if a value is a Uint8Array and, if so,
+   * converts it to a hex string wrapped in an object with a __bytes property. The corresponding reviver
+   * can then convert this back to a Uint8Array when parsing the message content from the event.
+   * @param {string} _key - The key of the property being processed.
+   * @param {unknown} value - The value to check if the message type is valid.
+   * @returns {unknown} The transformed value for JSON serialization. If the value is a Uint8Array,
+   * it returns an object with a __bytes property containing the hex string. Otherwise, it returns
+   * the value unchanged.
+   */
   static #jsonReplacer(_key: string, value: unknown): unknown {
     if(value instanceof Uint8Array) {
       return { __bytes: bytesToHex(value) };
@@ -324,6 +555,18 @@ export class NostrTransport implements Transport {
     return value;
   }
 
+  /**
+   * Custom JSON reviver to handle deserialization of hex strings back into Uint8Array values in message
+   * content. This complements the custom replacer used during serialization, allowing messages that contain
+   * binary data (e.g. public keys, signatures) to be correctly reconstructed when parsing JSON from
+   * Nostr event content. The reviver checks if a value is an object with a __bytes property and,
+   * if so, converts the hex string back into a Uint8Array. Otherwise, it returns the value unchanged.
+   * @param {string} _key - The key of the property being processed.
+   * @param {unknown} value - The value to check if it is an object containing a __bytes property for
+   * hex string conversion.
+   * @returns {unknown} The transformed value for JSON deserialization. If the value is an object
+   * with a __bytes property, it returns a Uint8Array. Otherwise, it returns the value unchanged.
+   */
   static #jsonReviver(_key: string, value: unknown): unknown {
     if(value && typeof value === 'object' && '__bytes' in (value as Record<string, unknown>)) {
       return hexToBytes((value as { __bytes: string }).__bytes);

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

@@ -5,7 +5,7 @@ export type SyncMessageHandler = (msg: any) => void;
 export type AsyncMessageHandler = (msg: any) => Promise<void>;
 export type MessageHandler = SyncMessageHandler | AsyncMessageHandler;
 
-export type TransportType = 'nostr' | 'didcomm';
+export type TransportType = 'nostr' | 'didcomm' | 'http';
 
 /**
  * Multi-actor message transport.
@@ -41,6 +41,39 @@ export interface Transport {
   /** Register a message handler scoped to a specific actor. */
   registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
 
+  /** Remove a previously-registered handler. No-op if not registered. */
+  unregisterMessageHandler(actorDid: string, messageType: string): void;
+
+  /**
+   * Detach an actor: unregister all its handlers, drop its keys, and close any
+   * transport-level subscriptions created for it. No-op if the actor is not
+   * registered.
+   */
+  unregisterActor(did: string): void;
+
   /** Send a message. The transport looks up sender to resolve signing keys. */
   sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void>;
+
+  /**
+   * Publish the message once immediately and then repeat it on a fixed
+   * interval. Returns a stop function the caller MUST invoke when the repeat
+   * is no longer needed (e.g. once the protocol state that required the
+   * message is satisfied).
+   *
+   * Useful for broadcasts on transports that don't reliably backfill
+   * historical events to late subscribers (many Nostr relays) — republishing
+   * gives late joiners a window in which to discover the message. The first
+   * publish is synchronous-ish (fired before the method returns).
+   *
+   * Callers specify `recipient` only for directed messages; for broadcasts
+   * it is omitted.
+   *
+   * @returns A stop function. Idempotent — safe to call more than once.
+   */
+  publishRepeating(
+    message: BaseMessage,
+    sender: string,
+    intervalMs: number,
+    recipient?: string,
+  ): () => void;
 }