@did-btcr2/aggregation 0.1.0

package/dist/types/transport/in-memory.d.ts

@@ -0,0 +1,64 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+/**
+ * In-process message bus connecting one or more {@link InMemoryTransport}
+ * instances. Routes broadcasts to every registered actor and directed messages
+ * to the actor that owns the recipient DID, with no relay, server, or network.
+ *
+ * Each delivery does a JSON round-trip (Uint8Array preserved as `__bytes` hex)
+ * so handlers receive an isolated, serialization-faithful copy, exactly as a
+ * real transport would. The message `body` is merged to the top level to match
+ * the shape the {@link NostrTransport} dispatch produces.
+ *
+ * @class InMemoryBus
+ */
+export declare class InMemoryBus {
+    #private;
+    /** Attach a transport to this bus. Called by the transport's constructor. */
+    register(transport: InMemoryTransport): void;
+    /** Detach a transport from this bus. */
+    unregister(transport: InMemoryTransport): void;
+    /**
+     * Deliver a message. With no `recipient` the message is broadcast to every
+     * actor on the bus; otherwise it is routed to the single transport that owns
+     * the recipient DID.
+     */
+    deliver(message: BaseMessage, _sender: string, recipient?: string): Promise<void>;
+}
+/**
+ * In-process {@link Transport} that routes aggregation messages through an
+ * {@link InMemoryBus} instead of a relay or HTTP server. Supports multiple
+ * actors per instance, so a single transport can host both a service and its
+ * participants (e.g. a cohort-of-one via {@link AggregationRunner.solo}).
+ *
+ * Encryption is a no-op (in-process, same trust domain); `registerPeer` /
+ * `getPeerPk` keep a registry so the contract matches the wire transports.
+ *
+ * @class InMemoryTransport
+ * @implements {Transport}
+ */
+export declare class InMemoryTransport implements Transport {
+    #private;
+    name: string;
+    readonly bus: InMemoryBus;
+    /** @param bus Shared bus. Pass the same bus to connect multiple transports. */
+    constructor(bus?: InMemoryBus);
+    start(): void;
+    registerActor(did: string, keys: SchnorrKeyPair): void;
+    getActorPk(did: string): Uint8Array | undefined;
+    /** True if `did` is registered on this transport. Used by the bus for routing. */
+    hasActor(did: string): boolean;
+    registerPeer(did: string, communicationPk: Uint8Array): void;
+    getPeerPk(did: string): Uint8Array | undefined;
+    registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void;
+    unregisterMessageHandler(actorDid: string, messageType: string): void;
+    unregisterActor(did: string): void;
+    sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void>;
+    publishRepeating(message: BaseMessage, sender: string, intervalMs: number, recipient?: string): () => void;
+    /** Deliver a broadcast message to every actor on this transport that handles `type`. */
+    dispatchBroadcast(type: string, message: unknown): Promise<void>;
+    /** Deliver a directed message to the recipient actor's handler for `type`. */
+    dispatchDirected(recipientDid: string, type: string, message: unknown): Promise<void>;
+}
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/types/transport/in-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../../src/transport/in-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAShE;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;;IAGtB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAI5C,wCAAwC;IACxC,UAAU,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAI9C;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA0BxF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,YAAW,SAAS;;IACjD,IAAI,EAAE,MAAM,CAAe;IAC3B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAK1B,+EAA+E;gBACnE,GAAG,GAAE,WAA+B;IAKhD,KAAK,IAAI,IAAI;IAIb,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAOtD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI9B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI;IAI5D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAK5F,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAKrE,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQ5B,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1F,gBAAgB,CACd,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,IAAI;IAcb,wFAAwF;IAClF,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtE,8EAA8E;IACxE,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAI5F"}

package/dist/types/transport/index.d.ts

@@ -0,0 +1,8 @@
+export * from './transport.js';
+export * from './error.js';
+export * from './factory.js';
+export * from './in-memory.js';
+export * from './nostr.js';
+export * from './didcomm.js';
+export * from './http/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/transport/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transport/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}

package/dist/types/transport/nostr.d.ts

@@ -0,0 +1,153 @@
+import type { Did } from '@did-btcr2/common';
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { SimplePool } from 'nostr-tools/pool';
+import type { Logger } from '../logger.js';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+/**
+ * Default Nostr relay URLs.
+ * @constant {Array<string>} DEFAULT_NOSTR_RELAYS
+ */
+export declare const DEFAULT_NOSTR_RELAYS: string[];
+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 declare const DEFAULT_BROADCAST_LOOKBACK_MS: number;
+/**
+ * Nostr Transport for did:btcr2 aggregation messages.
+ *
+ * A single NostrTransport manages one relay pool and supports multiple
+ * registered actors. Each actor registers its own DID and keys via
+ * {@link registerActor}; the transport resolves the correct identity when
+ * sending or receiving.
+ *
+ * Message routing:
+ * - Keygen messages (COHORT_ADVERT, COHORT_OPT_IN, COHORT_OPT_IN_ACCEPT, COHORT_READY) to kind 1 (plaintext)
+ * - Update messages (SUBMIT_UPDATE, DISTRIBUTE_AGGREGATED_DATA, VALIDATION_ACK) to kind 1059 (NIP-44 encrypted)
+ * - Sign messages to kind 1059 (NIP-44 encrypted)
+ *
+ * @class NostrTransport
+ * @implements {Transport}
+ */
+export declare class NostrTransport implements Transport {
+    #private;
+    name: string;
+    pool?: SimplePool;
+    constructor(config?: NostrTransportConfig);
+    /**
+     * Registers an actor (DID + keys) to send/receive messages with.
+     * Must be called before start() to ensure subscriptions are created for the actor.
+     * @param {string} did - The DID of the actor.
+     * @param {SchnorrKeyPair} keys - The Schnorr key pair for the actor.
+     * @throws {TransportAdapterError} If the actor is already registered or if the transport has already started.
+     * @example
+     * const transport = new NostrTransport();
+     * const keys = SchnorrKeyPair.generate();
+     * const did = DidBtcr2.create(keys.publicKey.compressed, { idType: 'KEY', network: 'mutinynet' });
+     * transport.registerActor(did, keys);
+     * transport.start();
+     */
+    registerActor(did: string, keys: SchnorrKeyPair): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    sendMessage(message: BaseMessage, sender: Did, to?: Did): Promise<void>;
+    /**
+     * 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;
+}
+//# sourceMappingURL=nostr.d.ts.map

package/dist/types/transport/nostr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nostr.d.ts","sourceRoot":"","sources":["../../../src/transport/nostr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,uFAAuF;AACvF,eAAO,MAAM,6BAA6B,QAAgB,CAAC;AAU3D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,SAAS;;IAC9C,IAAI,EAAE,MAAM,CAAW;IAEvB,IAAI,CAAC,EAAE,UAAU,CAAC;gBAQN,MAAM,CAAC,EAAE,oBAAoB;IAMzC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAUtD;;;;;;;;OAQG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAYlC;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAMrE;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI;IAY5D;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9C;;;;;;;;;OASG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAW5F;;;;;;;;OAQG;IACH,KAAK,IAAI,cAAc;IAsCvB;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAmF7E;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,GAAG,MAAM,IAAI;CAwNrG"}

package/dist/types/transport/transport.d.ts

@@ -0,0 +1,62 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { BaseMessage } from '../messages/base.js';
+export type SyncMessageHandler = (msg: any) => void;
+export type AsyncMessageHandler = (msg: any) => Promise<void>;
+export type MessageHandler = SyncMessageHandler | AsyncMessageHandler;
+export type TransportType = 'nostr' | 'didcomm' | 'http';
+/**
+ * Multi-actor message transport.
+ *
+ * A single transport instance manages one connection (relay pool, channel, etc.)
+ * shared by all registered actors. Each actor registers its own DID and keys;
+ * the transport resolves the correct identity when sending or receiving messages.
+ *
+ * The transport is a pure passthrough: it knows nothing about the aggregation
+ * protocol. It only signs/encrypts outgoing messages with the sender's keys and
+ * dispatches incoming messages to the correct actor's registered handler.
+ *
+ * @interface Transport
+ */
+export interface Transport {
+    name: string;
+    /** Start the underlying transport (idempotent, only starts once). */
+    start(): void;
+    /** Register an actor (service or participant) with this transport. */
+    registerActor(did: string, keys: SchnorrKeyPair): void;
+    /** Return a registered actor's compressed communication public key. */
+    getActorPk(did: string): Uint8Array | undefined;
+    /** Store a remote peer's communication public key for encrypted routing. */
+    registerPeer(did: string, communicationPk: Uint8Array): void;
+    /** Retrieve a remote peer's communication public key. */
+    getPeerPk(did: string): Uint8Array | undefined;
+    /** 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;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/types/transport/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEtE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,qEAAqE;IACrE,KAAK,IAAI,IAAI,CAAC;IAEd,sEAAsE;IACtE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEvD,uEAAuE;IACvE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEhD,4EAA4E;IAC5E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAE/C,6DAA6D;IAC7D,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7F,uEAAuE;IACvE,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtE;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CACd,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,IAAI,CAAC;CACf"}

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@did-btcr2/aggregation",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Multi-party coordination for did:btcr2 aggregate beacons: sans-I/O AggregationService and AggregationParticipant state machines, MuSig2 (BIP-327) signing sessions, cohort conditions, and pluggable transports (Nostr, HTTP, in-memory).",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "browser": "./dist/browser.mjs",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./browser": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/browser.mjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "dist/types/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MPL-2.0",
+  "contributors": [
+    {
+      "name": "dcdpr",
+      "url": "https://github.com/dcdpr"
+    },
+    {
+      "name": "jintekc",
+      "url": "https://github.com/jintekc",
+      "email": "github@jintek.consulting"
+    }
+  ],
+  "homepage": "https://github.com/dcdpr/did-btcr2-js/tree/main/packages/aggregation",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:dcdpr/did-btcr2-js.git",
+    "directory": "packages/aggregation"
+  },
+  "bugs": "https://github.com/dcdpr/did-btcr2-js/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "did",
+    "dids",
+    "decentralized identity",
+    "decentralized identifiers",
+    "did method",
+    "did:btcr2",
+    "bitcoin",
+    "aggregate beacon",
+    "aggregation",
+    "musig2",
+    "bip327",
+    "nostr",
+    "cohort"
+  ],
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@scure/btc-signer": "^1.8.1",
+    "nostr-tools": "^2.23.3",
+    "@did-btcr2/smt": "^0.3.0",
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/bitcoin": "^0.7.0",
+    "@did-btcr2/cryptosuite": "^8.0.0",
+    "@did-btcr2/common": "^9.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@types/chai": "^5.0.1",
+    "@types/chai-as-promised": "^8.0.1",
+    "@types/eslint": "^9.6.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.13.4",
+    "@typescript-eslint/eslint-plugin": "^8.24.1",
+    "@typescript-eslint/parser": "^8.24.1",
+    "c8": "^10.1.3",
+    "chai": "^5.2.0",
+    "chai-as-promised": "^8.0.1",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.20.1",
+    "eslint-plugin-mocha": "^10.5.0",
+    "globals": "^15.15.0",
+    "mocha": "^11.1.0",
+    "mocha-junit-reporter": "^2.2.1",
+    "node-stdlib-browser": "^1.3.1",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.1",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist coverage tests/compiled",
+    "clean:build": "rimraf dist",
+    "clean:tests": "rimraf coverage tests/compiled",
+    "wipe": "rimraf node_modules pnpm-lock.json",
+    "reinstall": "pnpm install --force",
+    "build": "pnpm clean:build && pnpm build:esm && pnpm build:cjs && pnpm build:browser",
+    "build:esm": "rimraf dist/esm dist/types && pnpm tsc -p tsconfig.json",
+    "build:cjs": "tsup && echo '{\"type\": \"commonjs\"}' > ./dist/cjs/package.json",
+    "build:browser": "rimraf dist/browser.mjs dist/browser.js && node build/bundles.js",
+    "build:tests": "pnpm clean:tests && pnpm tsc -p tests/tsconfig.json",
+    "build:all": "pnpm build && pnpm build:tests",
+    "release": "pnpm build && pnpm pack && mv *.tgz ../../release/aggregation",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "pnpm c8 mocha",
+    "build:test": "pnpm build && pnpm build:tests && pnpm c8 mocha",
+    "build:lint:test": "pnpm build && pnpm build:tests && pnpm lint:fix",
+    "prepublish": "pnpm build"
+  }
+}

package/src/beacon-strategy.ts

@@ -0,0 +1,142 @@
+import { canonicalize } from '@did-btcr2/common';
+import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SerializedSMTProof } from '@did-btcr2/smt';
+import { base64UrlToHash, blockHash, didToIndex, hashToBase64Url, verifySerializedProof } from '@did-btcr2/smt';
+import type { AggregationCohort } from './cohort.js';
+import type { BaseBody } from './messages/base.js';
+
+/** Validation result returned to the participant for a distribute-data message. */
+export interface BeaconValidationResult {
+  matches: boolean;
+  casAnnouncement?: Record<string, string>;
+  smtProof?: SerializedSMTProof;
+}
+
+/** Per-participant body attached to DISTRIBUTE_AGGREGATED_DATA by the service. */
+export interface BeaconDistributePayload {
+  casAnnouncement?: Record<string, string>;
+  smtProof?: Record<string, unknown>;
+}
+
+/**
+ * Pluggable strategy for beacon-type-specific aggregation, distribution, and
+ * participant-side validation. Lets new beacon types be added without
+ * modifying the service or participant state machines: register a new strategy
+ * via {@link registerBeaconStrategy}.
+ */
+export interface AggregateBeaconStrategy {
+  /** String constant used as `beaconType` on CohortConfig / BaseMessage bodies. */
+  readonly type: string;
+
+  /**
+   * Service: build the aggregated data on the cohort after all updates are
+   * collected. Implementation should mutate the cohort (set signalBytes,
+   * casAnnouncement, smtProofs, etc.).
+   */
+  buildAggregatedData(cohort: AggregationCohort): void;
+
+  /**
+   * Service: produce the body fields to attach to DISTRIBUTE_AGGREGATED_DATA
+   * for a specific participant. Called once per cohort member.
+   */
+  getDistributePayload(cohort: AggregationCohort, participantDid: string): BeaconDistributePayload;
+
+  /**
+   * Participant: verify the aggregated data they received reflects their own
+   * slot. A submitter (`included: true`) checks its update is included; a
+   * decliner (`included: false`, cooperative non-inclusion) checks its
+   * non-inclusion slot instead (absence from the CAS map, or an SMT
+   * non-inclusion proof). `submittedUpdate`/`expectedHash` are present only for a
+   * submitter. Pure function: returns matches + sidecar fields for the caller.
+   */
+  validateParticipantView(params: {
+    participantDid: string;
+    included: boolean;
+    submittedUpdate?: SignedBTCR2Update;
+    expectedHash?: string;
+    body: BaseBody;
+  }): BeaconValidationResult;
+}
+
+const CAS_STRATEGY: AggregateBeaconStrategy = {
+  type : 'CASBeacon',
+
+  buildAggregatedData(cohort) {
+    cohort.buildCASAnnouncement();
+  },
+
+  getDistributePayload(cohort) {
+    return { casAnnouncement: cohort.casAnnouncement };
+  },
+
+  validateParticipantView({ participantDid, included, expectedHash, body }) {
+    const casAnnouncement = body.casAnnouncement;
+    if(!casAnnouncement) return { matches: false };
+    if(!included) {
+      // Cooperative non-inclusion: the decliner must be ABSENT from the map.
+      return { matches: !(participantDid in casAnnouncement), casAnnouncement };
+    }
+    return {
+      matches : casAnnouncement[participantDid] === expectedHash,
+      casAnnouncement,
+    };
+  },
+};
+
+const SMT_STRATEGY: AggregateBeaconStrategy = {
+  type : 'SMTBeacon',
+
+  buildAggregatedData(cohort) {
+    cohort.buildSMTTree();
+  },
+
+  getDistributePayload(cohort, participantDid) {
+    const proof = cohort.smtProofs?.get(participantDid);
+    return { smtProof: proof as unknown as Record<string, unknown> | undefined };
+  },
+
+  validateParticipantView({ participantDid, included, submittedUpdate, body }) {
+    const smtProof = body.smtProof as unknown as SerializedSMTProof | undefined;
+    const index = didToIndex(participantDid);
+
+    if(!included) {
+      // Cooperative non-inclusion: the proof has a nonce but no updateId by
+      // construction. The leaf is SHA-256(SHA-256(nonce)); do NOT run the
+      // inclusion-only updateId guard (a missing updateId is correct here).
+      if(!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+      const candidateHash = blockHash(blockHash(base64UrlToHash(smtProof.nonce)));
+      return { matches: verifySerializedProof(smtProof, index, candidateHash), smtProof };
+    }
+
+    if(!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
+    // Verify updateId matches the canonicalized update hash. Proof hash fields
+    // are base64url (no padding) per the SMT Proof spec.
+    const canonicalBytes = new TextEncoder().encode(canonicalize(submittedUpdate as unknown as Record<string, unknown>));
+    const expectedUpdateId = hashToBase64Url(blockHash(canonicalBytes));
+    if(smtProof.updateId !== expectedUpdateId) {
+      return { matches: false, smtProof };
+    }
+    // Verify Merkle inclusion. The leaf is SHA-256(SHA-256(nonce) || SHA-256(update)).
+    const candidateHash = blockHash(blockHash(base64UrlToHash(smtProof.nonce)), base64UrlToHash(smtProof.updateId));
+    return {
+      matches : verifySerializedProof(smtProof, index, candidateHash),
+      smtProof,
+    };
+  },
+};
+
+/** Registered strategies keyed by `beaconType` string. */
+const STRATEGIES: Map<string, AggregateBeaconStrategy> = new Map([
+  [CAS_STRATEGY.type, CAS_STRATEGY],
+  [SMT_STRATEGY.type, SMT_STRATEGY],
+]);
+
+/** Register a custom beacon strategy. Overwrites any existing entry with the same type. */
+export function registerBeaconStrategy(strategy: AggregateBeaconStrategy): void {
+  STRATEGIES.set(strategy.type, strategy);
+}
+
+/** Look up a registered beacon strategy by type, or undefined if not registered. */
+export function getBeaconStrategy(type: string): AggregateBeaconStrategy | undefined {
+  return STRATEGIES.get(type);
+}