@derec-alliance/react-native 0.0.2 → 0.0.4

package/lib/types.d.ts

@@ -10,6 +10,99 @@ export interface SecretStore {
     save(secretId: string, channelId: string, kind: 0 | 1 | 2, value: Uint8Array): Promise<void>;
     remove(secretId: string, channelId: string, kind: 0 | 1 | 2): Promise<void>;
 }
+/**
+ * A channel's lifecycle status, as the Rust variant name the core emits.
+ */
+export type ChannelStatusName = "Pending" | "Paired" | "Unpairing";
+/**
+ * A peer's role on a helper channel, as the Rust variant name.
+ */
+export type SenderKindName = "Owner" | "Helper" | "ReplicaSource" | "ReplicaDestination";
+/**
+ * A member's role within a replica group, as the Rust variant name.
+ */
+export type ReplicaRoleName = "Source" | "Destination";
+/**
+ * Narrows a listing from {@link ChannelStore}.
+ *
+ * Every field is a restriction, and every field's empty value means "do not
+ * restrict on this" — a filter of all-empties selects everything.
+ * Restrictions combine with AND, and `exclude` is applied last, overriding
+ * `ids`.
+ *
+ * **Returning everything under the `secretId` and ignoring the filter is
+ * correct**, and the implementation to write unless there is a measured reason
+ * not to. The library re-applies the filter to whatever you return and drops
+ * what it excludes, so a superset is trimmed before anything acts on it.
+ *
+ * Pushing the filter into your query — a `WHERE` clause, a key-condition
+ * expression — is an optimization you opt into. It saves transferring rows the
+ * caller discards, which costs bandwidth everywhere and real money on a metered
+ * backing that bills by bytes read. Verify one against
+ * `library/tests/fixtures/channel_filter.json`.
+ *
+ * The asymmetry is what makes pushdown worth verifying: the re-check can drop
+ * rows but cannot recover one that was never returned, so selecting too *few*
+ * is undetectable at runtime — no exception, no event, just a share that was
+ * never published. That matters most here, because TypeScript accepts a
+ * function of fewer parameters where more are declared: a store written before
+ * this parameter existed still satisfies the interface and compiles clean under
+ * `--strict`, so the type system cannot see the gap either.
+ *
+ * Ids are decimal strings, like every other `u64` on this bridge.
+ */
+export interface ChannelFilter<Role> {
+    /** Restrict to these ids. Empty selects every record. */
+    ids: string[];
+    /** Restrict to these statuses. Empty selects any status. */
+    status: ChannelStatusName[];
+    /** Restrict to this role. `null` selects any role. */
+    role: Role | null;
+    /** Omit these ids, applied after `ids`. Empty omits nothing. */
+    exclude: string[];
+}
+/**
+ * Whether a channel or member with these attributes survives `filter`.
+ *
+ * Every empty field means "do not restrict", `exclude` is applied after `ids`,
+ * and the restrictions combine with AND — the same contract the core states on
+ * `ChannelFilter`. A store whose backing cannot express the filter as a query
+ * can list and call this; that is correct but transfers the rows the filter
+ * exists to leave behind.
+ *
+ * `id` is a decimal string, as ids are everywhere on this bridge. `role` is the
+ * peer's `SenderKind` name for `listHelpers` and the member's `ReplicaRole`
+ * name for `listReplicas`.
+ */
+export declare function channelFilterMatches(filter: HelperFilter | ReplicaFilter | null | undefined, id: string, status: ChannelStatusName, role: SenderKindName | ReplicaRoleName): boolean;
+/**
+ * The endpoints a peer-supplied message advertises, in the peer's own order.
+ *
+ * Yields `supported_transports` when it is non-empty, and otherwise the
+ * singular `transport_protocol` — which is how every implementation predating
+ * the offer list advertises, and the reason this is a function rather than a
+ * field read. Reading `transport_protocol` directly is a bug: its meaning
+ * narrowed to "one entry of a list, and possibly absent", so a peer that has
+ * moved past it looks unreachable to a reader that was correct before 0.0.3.
+ *
+ * Reports what was advertised, not what is acceptable — nothing here is
+ * validated, and the protocol still applies its own transport policy to
+ * whatever it records.
+ */
+export declare function advertisedEndpoints(message: {
+    transport_protocol?: TransportProtocol;
+    supported_transports?: TransportProtocol[];
+} | null | undefined): TransportProtocol[];
+/**
+ * Narrows `listHelpers`. Ids are the channel's `channel_id` and the role is
+ * the **peer's** `peer_role`.
+ */
+export type HelperFilter = ChannelFilter<SenderKindName>;
+/**
+ * Narrows `listReplicas`. Ids are the member's `replica_id` and the role is
+ * the member's `role`.
+ */
+export type ReplicaFilter = ChannelFilter<ReplicaRoleName>;
 /**
  * Channel-record persistence.
  *
@@ -30,7 +123,7 @@ export interface SecretStore {
  *
  * `listHelpers` and `listReplicas` are **not** arrays of that union — they
  * return a JSON array of the **inner** records with the tag stripped:
- * `[{ channel_id, transport, ... }, ...]`, `HelperChannel` for the first and
+ * `[{ schema_version, channel_id, transports, ... }, ...]`, `HelperChannel` for the first and
  * `ReplicaMember` for the second. Wrapping each element back in
  * `{ "Helper": ... }` will not decode.
  *
@@ -50,8 +143,16 @@ export interface ChannelStore {
     load(secretId: string, channelId: string, replicaId: string): Promise<Uint8Array | null | undefined>;
     save(secretId: string, channelId: string, replicaId: string, bytes: Uint8Array): Promise<void>;
     remove(secretId: string, channelId: string, replicaId: string): Promise<boolean>;
-    /** JSON array of the helper channels stored under `secretId`. */
-    listHelpers(secretId: string): Promise<Uint8Array | null | undefined>;
+    /**
+     * JSON array of the helper channels stored under `secretId` that `filter`
+     * selects.
+     *
+     * Apply the filter in your query rather than listing everything and
+     * discarding rows; see {@link ChannelFilter}. The library re-applies it to
+     * whatever you return, so ignoring it is slow rather than wrong — but
+     * returning fewer rows than it selects is wrong, and undetectable.
+     */
+    listHelpers(secretId: string, filter: HelperFilter): Promise<Uint8Array | null | undefined>;
     /**
      * JSON array of the replica-group members stored under `secretId`,
      * including this device's own row.
@@ -70,7 +171,7 @@ export interface ChannelStore {
      * insertion order after arbitrary edits are both effectively arbitrary.
      * Order explicitly to make succession predictable.
      */
-    listReplicas(secretId: string): Promise<Uint8Array | null | undefined>;
+    listReplicas(secretId: string, filter: ReplicaFilter): Promise<Uint8Array | null | undefined>;
     linkChannel(secretId: string, channelId: string, linkedChannelId: string): Promise<void>;
     linkedChannels(secretId: string, channelId: string): Promise<string[]>;
 }
@@ -114,7 +215,7 @@ export interface UserSecretStore {
  * returns the exact blob it received, `remove` drops the row, and
  * `loadAll` returns every blob whose `kind` matches the requested
  * category (`0` = PendingVerification, `1` = PendingRecovery,
- * `2` = PendingUnpair, `3` = SharingRound, `4` = PendingSyncCheck).
+ * `2` = PendingUnpair, `3` = SharingRound, `4` = PendingReplicaDiscovery).
  *
  * Rows are keyed by `(secretId, StateKey)` — the `keyJson` buffer is
  * a JSON object `{ kind, channel_id?, version? }` matching the `kind`
@@ -152,11 +253,80 @@ export interface StateStore {
  * DeRec over request/response transports" in the Rust SDK README.
  */
 export interface Transport {
-    send(endpoint: {
+    /**
+     * Delivers `message` to a peer reachable at any of `endpoints`.
+     *
+     * `endpoints` are the addresses that peer advertised, in the order it
+     * offered them, already filtered to those the library will record. The
+     * library does not rank them: which to dial, and whether to fall back when
+     * one is unreachable, is this implementation's choice. Never empty.
+     *
+     * Delivery to any one endpoint is success. Reject only when the message
+     * reached none of them.
+     *
+     * **Deliver once.** Every entry addresses the same peer, so sending to all
+     * of them delivers one authenticated message several times. Stop at the
+     * first success. The protocol's handlers are idempotent, so a duplicate
+     * does not corrupt state, but it is still a duplicate to anything counting
+     * messages, and a peer entitled to treat re-delivery as a replay will.
+     *
+     * **Prefer an adapter to writing this by hand.** Choosing which endpoint to
+     * dial is yours and stays here; the bookkeeping around it is the same
+     * everywhere and is already written and tested. Write a {@link SendOne} and
+     * wrap it in {@link sequentialFailover}. Taking `endpoints[0]` type-checks,
+     * passes every test, and silently gives up the failover the list exists to
+     * provide — if that is genuinely wanted, say so with
+     * {@link singleEndpointTransport} rather than by indexing.
+     */
+    send(endpoints: ReadonlyArray<{
         protocol: string;
         uri: string;
-    }, message: Uint8Array): Promise<void>;
+    }>, message: Uint8Array): Promise<void>;
 }
+/**
+ * Delivers one message to one endpoint.
+ *
+ * The narrow half of a transport: everything genuinely about dialing, and
+ * nothing about which endpoint to dial. Pass one of these to
+ * {@link sequentialFailover} or {@link singleEndpointTransport} to get a
+ * {@link Transport}.
+ *
+ * Rejecting means the endpoint did not receive the message. The rejection
+ * reason need not distinguish "unreachable" from "rejected":
+ * {@link sequentialFailover} treats both as a reason to try the next endpoint,
+ * which is the safe reading. Trying an endpoint that would have refused costs
+ * a round trip; skipping one that would have worked costs the delivery.
+ */
+export type SendOne = (endpoint: {
+    protocol: string;
+    uri: string;
+}, message: Uint8Array) => Promise<void>;
+/**
+ * Builds a {@link Transport} that tries each endpoint in the order the peer
+ * offered it and stops at the first success.
+ *
+ * An error is thrown only when every endpoint failed. The message is delivered
+ * at most once.
+ *
+ * This is the right default. A peer advertising several endpoints is saying it
+ * can be reached at any of them, and the reason 0.0.3 records the whole list is
+ * so one being down does not end the conversation.
+ */
+export declare function sequentialFailover(dialer: SendOne): Transport;
+/**
+ * Builds a {@link Transport} that uses the first endpoint only.
+ *
+ * Reproduces the pre-0.0.3 behaviour exactly, for an application that genuinely
+ * serves one endpoint or has a reason not to fail over.
+ *
+ * It exists so that choosing it is visible. `endpoints[0]` written inline looks
+ * like an implementation detail and reads as finished; naming this records that
+ * failover was considered and declined, which is a claim a reviewer can
+ * disagree with. If the peers this application talks to advertise more than one
+ * endpoint, prefer {@link sequentialFailover} — every endpoint after the first
+ * is reachability being thrown away.
+ */
+export declare function singleEndpointTransport(dialer: SendOne): Transport;
 export declare enum SenderKind {
     Owner = 0,
     Helper = 1,
@@ -205,18 +375,25 @@ export declare enum FlowKind {
     /** Ask the replica group whether this device is behind, and catch up if it
      *  is. Replica-only, and takes no parameters — the group and this device's
      *  own version both come from the stores. */
-    SyncCheck = 7,
+    ReplicaDiscovery = 7,
     /** Remove a member from the replica group. Replica-only. Naming this device
      *  is a voluntary departure; naming another is an eviction. Params:
      *  `{ replica_id: string; memo?: string }` — `replica_id` is a decimal
      *  string so ids above 2^53 survive JS number handling. */
-    RemoveReplica = 8
+    UnpairReplica = 8
 }
 export type UnpairAck = "required" | "not_required";
 export interface ContactMessage {
     channel_id: bigint;
     /** `ContactMode` numeric value (0 = INLINE_KEYS, 1 = HASHED_KEYS, 2 = NO_KEYS). */
     contact_mode: number;
+    /**
+     * @deprecated Reading this field directly is incorrect: its meaning narrowed
+     * to "one entry of a list, and possibly absent", so a peer advertising only
+     * `supported_transports` looks unreachable to a reader that was correct
+     * before 0.0.3. Call {@link advertisedEndpoints}, which resolves both
+     * spellings. Removed at 0.0.5.
+     */
     transport_protocol?: TransportProtocol;
     nonce: bigint;
     /** Present only when `contact_mode === ContactMode.InlineKeys`. */
@@ -226,6 +403,10 @@ export interface ContactMessage {
     /** Present only when `contact_mode === ContactMode.HashedKeys`. SHA-384 digest (48 bytes). */
     contact_binding_hash?: Uint8Array;
     timestamp?: Timestamp;
+    /** Every transport endpoint the creator of this contact can be reached
+     *  on, in its own preference order. Empty means "only
+     *  `transport_protocol` is offered". */
+    supported_transports: TransportProtocol[];
 }
 export interface UserSecret {
     id: Uint8Array;
@@ -263,11 +444,23 @@ export interface UpdateChannelInfoParams {
     /** New communication-info map. `null`/absent leaves the peer's stored
      *  map untouched; pass an empty object to clear it. */
     communication_info?: Record<string, string>;
-    /** New transport endpoint. Absent leaves it untouched. */
+    /**
+     * New transport endpoint. Absent leaves it untouched.
+     *
+     * @deprecated Use `own_transports`, which carries every endpoint this node
+     * now serves; its first entry also fills this field for peers predating the
+     * list. Removed at 0.0.5.
+     */
     transport_protocol?: {
         uri: string;
         protocol: number;
     };
+    /**
+     * Every endpoint this node now serves, in its own preference order.
+     * Omitted leaves the target(s)' stored set untouched. Takes precedence
+     * over `transport_protocol`, whose first entry it also fills.
+     */
+    own_transports?: TransportProtocol[];
 }
 /**
  * How long the protocol waits on each thing that can keep it waiting. Every
@@ -297,10 +490,10 @@ export interface Timeouts {
         timeout_in_secs: number;
     };
 }
-/** `SyncCheck` takes no parameters: the group and this device's own version
+/** `ReplicaDiscovery` takes no parameters: the group and this device's own version
  *  are both read from the stores. The argument may be omitted entirely. */
-export type SyncCheckParams = Record<string, never>;
-export interface RemoveReplicaParams {
+export type ReplicaDiscoveryParams = Record<string, never>;
+export interface UnpairReplicaParams {
     /** The member to remove, as a **decimal** `u64` string — the same form
      *  `ReplicaPaired.peer_replica_id` hands back. A value naming no current
      *  member is rejected; it is not silently ignored. */
@@ -319,7 +512,7 @@ export type DeRecEvent = {
     type: "ActionRequired";
     channel_id: string;
     action: Uint8Array;
-    action_kind: string;
+    action_kind: PendingActionKind;
     peer_communication_info?: Record<string, string>;
     sender_kind?: SenderKind;
     version?: number;
@@ -406,7 +599,7 @@ export type DeRecEvent = {
 /** A replica catch-up finished. `fetched_from` is absent when this device
  *  was already current, in which case no hydration event follows. */
  | {
-    type: "SyncCheckComplete";
+    type: "ReplicaDiscoveryComplete";
     local_version: number;
     group_version: number;
     fetched_from?: string;
@@ -455,7 +648,11 @@ export type DeRecEvent = {
     secret: {
         helpers: Array<{
             channel_id: string;
-            transport_uri: string;
+            /** Every endpoint this peer advertised, in the order it offered them. */
+            transports: Array<{
+                uri: string;
+                protocol: number;
+            }>;
             shared_key: Uint8Array;
             communication_info: Record<string, string>;
         }>;
@@ -476,7 +673,11 @@ export type DeRecEvent = {
              *  originated, which is why no separate owner field is needed. */
             members: Array<{
                 replica_id: string;
-                transport_uri: string;
+                /** Every endpoint this peer advertised, in the order it offered them. */
+                transports: Array<{
+                    uri: string;
+                    protocol: number;
+                }>;
                 role: "Source" | "Destination";
                 communication_info: Record<string, string>;
             }>;
@@ -504,7 +705,7 @@ export type DeRecEvent = {
 /** Fires alongside `PairingCompleted` on replica-mode pair handshakes.
  *  `peer_replica_id` is the peer's `u64` as a **decimal** string,
  *  matching the wire `derec.replica_id` representation and every other
- *  id across this boundary. Pass it back verbatim — `RemoveReplica`
+ *  id across this boundary. Pass it back verbatim — `UnpairReplica`
  *  expects the same decimal form. The local side's role
  *  (`ReplicaSource` vs `ReplicaDestination`) is on the persisted
  *  channel record — replica pairings are unidirectional, so there is
@@ -529,7 +730,11 @@ export type DeRecEvent = {
     secret: {
         helpers: Array<{
             channel_id: string;
-            transport_uri: string;
+            /** Every endpoint this peer advertised, in the order it offered them. */
+            transports: Array<{
+                uri: string;
+                protocol: number;
+            }>;
             shared_key: Uint8Array;
             communication_info: Record<string, string>;
         }>;
@@ -548,7 +753,11 @@ export type DeRecEvent = {
              *  originated, which is why no separate owner field is needed. */
             members: Array<{
                 replica_id: string;
-                transport_uri: string;
+                /** Every endpoint this peer advertised, in the order it offered them. */
+                transports: Array<{
+                    uri: string;
+                    protocol: number;
+                }>;
                 role: "Source" | "Destination";
                 communication_info: Record<string, string>;
             }>;
@@ -578,7 +787,11 @@ export type DeRecEvent = {
     secret: {
         helpers: Array<{
             channel_id: string;
-            transport_uri: string;
+            /** Every endpoint this peer advertised, in the order it offered them. */
+            transports: Array<{
+                uri: string;
+                protocol: number;
+            }>;
             shared_key: Uint8Array;
             communication_info: Record<string, string>;
         }>;
@@ -597,7 +810,11 @@ export type DeRecEvent = {
              *  originated, which is why no separate owner field is needed. */
             members: Array<{
                 replica_id: string;
-                transport_uri: string;
+                /** Every endpoint this peer advertised, in the order it offered them. */
+                transports: Array<{
+                    uri: string;
+                    protocol: number;
+                }>;
                 role: "Source" | "Destination";
                 communication_info: Record<string, string>;
             }>;
@@ -647,7 +864,7 @@ export type DeRecEvent = {
  | {
     type: "AutoAccepted";
     channel_id: string;
-    action_kind: string;
+    action_kind: PendingActionKind;
 } | {
     type: "NoOp";
 }
@@ -658,12 +875,14 @@ export type DeRecEvent = {
     type: "PairingStarted";
     channel_id: string;
     kind: SenderKind;
+    trace_id: string;
 }
 /** A discovery request was dispatched to `channel_id`. Emitted per
  *  targeted helper by `start(Discovery)`. */
  | {
     type: "DiscoveryStarted";
     channel_id: string;
+    trace_id: string;
 }
 /** A discovery request could not be dispatched to `channel_id`. Other
  *  targeted channels are unaffected. */
@@ -678,6 +897,7 @@ export type DeRecEvent = {
     type: "ProtectSecretStarted";
     channel_id: string;
     version: number;
+    trace_id: string;
 }
 /** A share-storage request could not be dispatched to `channel_id`. */
  | {
@@ -691,6 +911,7 @@ export type DeRecEvent = {
     type: "VerifySharesStarted";
     channel_id: string;
     version: number;
+    trace_id: string;
 }
 /** A verify-share challenge could not be dispatched to `channel_id`. */
  | {
@@ -704,6 +925,7 @@ export type DeRecEvent = {
     type: "RecoverSecretStarted";
     channel_id: string;
     version: number;
+    trace_id: string;
 }
 /** A recovery share request could not be dispatched to `channel_id`. */
  | {
@@ -722,11 +944,13 @@ export type DeRecEvent = {
 } | {
     type: "UnpairStarted";
     channel_id: string;
+    trace_id: string;
 }
 /** An update-channel-info request was dispatched to `channel_id`. */
  | {
     type: "UpdateChannelInfoStarted";
     channel_id: string;
+    trace_id: string;
 }
 /** An update-channel-info request could not be dispatched to
  *  `channel_id`. */
@@ -787,7 +1011,12 @@ export interface GetSecretIdsVersionsRequestMessage {
     timestamp?: Timestamp;
     /** Ephemeral endpoint where the requester wants the response routed.
      *  Absent means "use the channel's stored peer endpoint". */
-    reply_to?: TransportProtocol;
+    /**
+     * Every endpoint the requester can be answered on for this exchange, in
+     * its own preference order. Omitted means route to the endpoints already
+     * recorded for the channel.
+     */
+    reply_to?: TransportProtocol[];
     /** Replica-group member that sent this; see `replicaId` semantics. */
     replica_id?: bigint;
 }
@@ -826,6 +1055,13 @@ export interface CommunicationInfoKeyValue {
 export interface CommunicationInfo {
     communication_info_entries: CommunicationInfoKeyValue[];
 }
+/**
+ * The label vocabulary for `ActionRequired.action_kind` and
+ * `AutoAccepted.action_kind` — one value per pending-action kind the
+ * protocol can raise. Matches the Rust `PendingActionKind` discriminants
+ * one-for-one.
+ */
+export type PendingActionKind = "Pairing" | "PrePair" | "StoreShare" | "VerifyShare" | "Discovery" | "GetShare" | "Unpair" | "UpdateChannelInfo";
 export interface ParameterRange {
     min_share_size: bigint;
     max_share_size: bigint;
@@ -845,8 +1081,18 @@ export interface PairRequestMessage {
     nonce: bigint;
     communication_info?: CommunicationInfo;
     parameter_range?: ParameterRange;
+    /**
+     * @deprecated Reading this field directly is incorrect: its meaning narrowed
+     * to "one entry of a list, and possibly absent", so a peer advertising only
+     * `supported_transports` looks unreachable to a reader that was correct
+     * before 0.0.3. Call {@link advertisedEndpoints}, which resolves both
+     * spellings. Removed at 0.0.5.
+     */
     transport_protocol?: TransportProtocol;
     timestamp?: Timestamp;
+    /** Every transport endpoint the initiator can be reached on, in its own
+     *  preference order. Empty means "only `transport_protocol` is offered". */
+    supported_transports: TransportProtocol[];
 }
 export interface PairResponseMessage {
     result?: DeRecResult;
@@ -865,8 +1111,21 @@ export interface PairResponseMessage {
 }
 export interface PrePairRequestMessage {
     nonce: bigint;
+    /**
+     * @deprecated Reading this field directly is incorrect: its meaning narrowed
+     * to "one entry of a list, and possibly absent", so a peer advertising only
+     * `supported_transports` looks unreachable to a reader that was correct
+     * before 0.0.3. Call {@link advertisedEndpoints}, which resolves both
+     * spellings. Removed at 0.0.5.
+     */
     transport_protocol?: TransportProtocol;
     timestamp?: Timestamp;
+    /**
+     * Every endpoint the sender can be reached on for the PrePair reply, in
+     * its own preference order. At least one of this and `transport_protocol`
+     * must be present.
+     */
+    supported_transports?: TransportProtocol[];
 }
 export interface PrePairResponseMessage {
     result?: DeRecResult;
@@ -882,7 +1141,12 @@ export interface GetShareRequestMessage {
     version: number;
     timestamp?: Timestamp;
     /** Ephemeral response endpoint; see `replyTo` semantics. */
-    reply_to?: TransportProtocol;
+    /**
+     * Every endpoint the requester can be answered on for this exchange, in
+     * its own preference order. Omitted means route to the endpoints already
+     * recorded for the channel.
+     */
+    reply_to?: TransportProtocol[];
     /** Replica-group member that sent this; see `replicaId` semantics. */
     replica_id?: bigint;
 }
@@ -917,7 +1181,12 @@ export interface StoreShareRequestMessage {
     timestamp?: Timestamp;
     secret_id: bigint;
     /** Ephemeral response endpoint; see `replyTo` semantics. */
-    reply_to?: TransportProtocol;
+    /**
+     * Every endpoint the requester can be answered on for this exchange, in
+     * its own preference order. Omitted means route to the endpoints already
+     * recorded for the channel.
+     */
+    reply_to?: TransportProtocol[];
     /** Replica-group member that sent this; see `replicaId` semantics. */
     replica_id?: bigint;
 }
@@ -933,7 +1202,12 @@ export interface UnpairRequestMessage {
     memo: string;
     timestamp?: Timestamp;
     /** Ephemeral response endpoint; see `replyTo` semantics. */
-    reply_to?: TransportProtocol;
+    /**
+     * Every endpoint the requester can be answered on for this exchange, in
+     * its own preference order. Omitted means route to the endpoints already
+     * recorded for the channel.
+     */
+    reply_to?: TransportProtocol[];
     /** Replica-group member that sent this; see `replicaId` semantics. */
     replica_id?: bigint;
 }
@@ -947,7 +1221,12 @@ export interface VerifyShareRequestMessage {
     nonce: bigint;
     timestamp?: Timestamp;
     /** Ephemeral response endpoint; see `replyTo` semantics. */
-    reply_to?: TransportProtocol;
+    /**
+     * Every endpoint the requester can be answered on for this exchange, in
+     * its own preference order. Omitted means route to the endpoints already
+     * recorded for the channel.
+     */
+    reply_to?: TransportProtocol[];
 }
 export interface VerifyShareResponseMessage {
     result?: DeRecResult;
@@ -974,7 +1253,12 @@ export interface PairingRequestProduceResult extends ProduceResult {
     secret_key: Uint8Array;
 }
 export interface PairingResponseProduceResult extends ProduceResult {
-    peer_transport_protocol: TransportProtocol;
+    /**
+     * Every endpoint the requester advertised, in the order it offered them,
+     * filtered to those the library will record. Never empty. Choosing which
+     * to dial, and failing over when one is unreachable, is the application's.
+     */
+    peer_transports: TransportProtocol[];
     shared_key: Uint8Array;
     /**
      * Post-handshake rekey channel id the responder is committing to.