@derec-alliance/react-native 0.0.2 → 0.0.3

package/ios/DeRecFFI.xcframework/ios-arm64_x86_64-simulator/Headers/derec_ffi.h

@@ -26,23 +26,48 @@
  */
 #define SHARE_ALGORITHM_REPLICA_SECRET 1
 
+/**
+ * Schema version stamped onto every channel record this build writes.
+ *
+ * Applications persist [`HelperChannel`] and [`ReplicaMember`] as opaque
+ * blobs whose shape the *library* owns, so a field change here is a
+ * migration the application cannot write without knowing a schema it does
+ * not define. The marker is what lets the library do that migration itself:
+ * a reader can tell a record apart by the shape it was written in rather
+ * than by guessing from which fields happen to be present.
+ *
+ * A record written before the marker existed deserializes as version 0 and
+ * is upgraded on read. A record claiming a version *newer* than this build
+ * understands is refused, because the alternative is silently dropping
+ * fields this build cannot see and writing the truncated result back.
+ *
+ * The value tracks the release that last changed the shape, not the release
+ * that is current: it moved to 3 when `transport` became `transports`, and
+ * stays there until the next shape change.
+ *
+ * Declared unconditionally, unlike the serde impls that stamp it: the SDK
+ * bridges mirror this number in their own encoders, and a constant they must
+ * agree with should not appear and disappear with a feature flag.
+ */
+#define CHANNEL_RECORD_SCHEMA_VERSION 3
+
 /**
  * Latest encoding major version, used for all new encodes. Bump only on a
  * breaking format change, adding the matching `vN` module and match arm.
  */
-#define LATEST 2
+#define LATEST 3
 
 /**
  * Minimum number of shares required to reconstruct the secret, absent an
- * explicit [`DeRecProtocolBuilder::with_threshold`] call. This is the sole
- * definition of the value — [`DeRecProtocolBuilder::new`] and the FFI
+ * explicit [`DeRecProtocolBuilder::with_threshold`](crate::protocol::DeRecProtocolBuilder::with_threshold) call. This is the sole
+ * definition of the value — [`DeRecProtocolBuilder::new`](crate::protocol::DeRecProtocolBuilder::new) and the FFI
  * config's serde default both read it rather than each hardcoding `3`.
  */
 #define DEFAULT_THRESHOLD 3
 
 /**
  * Number of recent share versions each helper retains, absent an explicit
- * [`DeRecProtocolBuilder::with_keep_versions_count`] call. Sole definition
+ * [`DeRecProtocolBuilder::with_keep_versions_count`](crate::protocol::DeRecProtocolBuilder::with_keep_versions_count) call. Sole definition
  * of the value; see [`DEFAULT_THRESHOLD`].
  */
 #define DEFAULT_KEEP_VERSIONS_COUNT 3
@@ -263,6 +288,26 @@
  */
 #define DEREC_CODE_TRANSPORT_INVALID 120
 
+/**
+ * No transport is shared with the peer — its offered endpoints and this
+ * application's served endpoints intersect to nothing. Always a local,
+ * terminal error: push-only delivery means an unreachable peer also
+ * cannot be told. `DEREC_CATEGORY_INVALID_INPUT`.
+ */
+#define DEREC_CODE_NO_USABLE_ENDPOINT 121
+
+/**
+ * Both plaintext opt-in flags were set explicitly and disagree: the
+ * deprecated `unsafe_http` says one thing and `unsafe_connection` the
+ * other. Raised at protocol construction rather than resolved by
+ * precedence, because the flag precedence would favour is the one being
+ * removed, and a configuration layer that emits every field
+ * unconditionally would otherwise let a defaulted value silently beat a
+ * deliberate one. Set only `unsafe_connection`.
+ * `DEREC_CATEGORY_INVALID_INPUT`.
+ */
+#define DEREC_CODE_CONFLICTING_PLAINTEXT_OPT_IN 122
+
 /**
  * Discriminants selecting which message [`derec_decode_message_json`] and
  * [`derec_encode_message_json`] operate on.
@@ -301,7 +346,7 @@
 /**
  * Not a standalone message on the wire, but it crosses this FFI on its own
  * as the `transport_protocol` argument of `create_contact_message` and the
- * `peer_transport_protocol` result of `produce_pair_response_message`.
+ * `peer_transports` result of `produce_pair_response_message`.
  */
 #define DEREC_MESSAGE_KIND_TRANSPORT_PROTOCOL 14
 
@@ -345,13 +390,13 @@
  * Replica catch-up. Takes no parameters: the group and this device's own
  * version are both read from the stores.
  */
-#define FLOW_KIND_SYNC_CHECK 7
+#define FLOW_KIND_REPLICA_DISCOVERY 7
 
 /**
  * Remove a member from the replica group. Params:
  * `{ "replica_id": "<decimal>", "memo": "<optional>" }`.
  */
-#define FLOW_KIND_REMOVE_REPLICA 8
+#define FLOW_KIND_UNPAIR_REPLICA 8
 
 /**
  * Opaque handle returned by [`derec_protocol_new`] and consumed by
@@ -552,7 +597,7 @@ typedef struct ExtractPairRequestResult {
 typedef struct ProducePairResponseMessageResult {
   struct DeRecError error;
   struct DeRecBuffer response_wire_bytes;
-  struct DeRecBuffer peer_transport_protocol;
+  struct DeRecBuffer peer_transports;
   struct DeRecBuffer shared_key;
   /**
    * Post-handshake rekey channel id the responder is committing to.
@@ -694,6 +739,17 @@ typedef struct DeRecProtocolNewResult {
  * [`crate::protocol::types::HelperChannel`] and
  * [`crate::protocol::types::ReplicaMember`] respectively.
  *
+ * Both listing callbacks receive a `filter` buffer holding a JSON-encoded
+ * [`crate::protocol::types::HelperFilter`] or
+ * [`crate::protocol::types::ReplicaFilter`] — an object with `ids`, `status`,
+ * `role` and `exclude`, where an empty array or a null `role` restricts
+ * nothing. A backend should apply it in its query rather than by listing
+ * everything and discarding rows; see
+ * [`crate::protocol::types::ChannelFilter`]. The library re-applies it to
+ * whatever comes back, so ignoring it is slow rather than wrong — but
+ * returning fewer rows than it selects is wrong, and undetectable. The buffer is owned
+ * by the caller and valid only for the duration of the call.
+ *
  * The order `list_replicas` returns is significant in exactly one situation —
  * it selects the successor when the group's source is removed. See
  * [`crate::protocol::DeRecChannelStore::replicas`] for the full contract.
@@ -717,8 +773,18 @@ typedef struct ChannelStoreCallbacks {
                     uint64_t channel_id,
                     uint64_t replica_id,
                     uint32_t *out_existed);
-  int32_t (*list_helpers)(void *user_data, uint64_t secret_id, uint8_t **out_ptr, size_t *out_len);
-  int32_t (*list_replicas)(void *user_data, uint64_t secret_id, uint8_t **out_ptr, size_t *out_len);
+  int32_t (*list_helpers)(void *user_data,
+                          uint64_t secret_id,
+                          const uint8_t *filter,
+                          size_t filter_len,
+                          uint8_t **out_ptr,
+                          size_t *out_len);
+  int32_t (*list_replicas)(void *user_data,
+                           uint64_t secret_id,
+                           const uint8_t *filter,
+                           size_t filter_len,
+                           uint8_t **out_ptr,
+                           size_t *out_len);
   int32_t (*link_channel)(void *user_data, uint64_t secret_id, uint64_t a, uint64_t b);
   int32_t (*linked_channels)(void *user_data,
                              uint64_t secret_id,
@@ -861,10 +927,24 @@ typedef struct StateStoreCallbacks {
  */
 typedef struct TransportCallbacks {
   void *user_data;
+  /**
+   * Deliver `bytes` to a peer reachable at any of `endpoints`.
+   *
+   * `endpoints` is a length-delimited sequence of encoded
+   * `TransportProtocol` messages — each entry preceded by its protobuf
+   * varint byte length, the same framing protobuf uses for a repeated
+   * embedded message field. They are the endpoints that peer advertised,
+   * in the order it offered them, already filtered to those the library
+   * will record.
+   *
+   * The library does not rank them. Which endpoint to dial, and whether
+   * to fall back to another when one is unreachable, is the
+   * implementation's choice. Return `0` once the message has reached any
+   * one of them; non-zero only when it reached none.
+   */
   int32_t (*send)(void *user_data,
-                  const uint8_t *uri_ptr,
-                  size_t uri_len,
-                  int32_t protocol,
+                  const uint8_t *endpoints_ptr,
+                  size_t endpoints_len,
                   const uint8_t *bytes,
                   size_t len);
 } TransportCallbacks;
@@ -1287,8 +1367,8 @@ struct DeRecMessageJsonResult derec_encode_message_json(int32_t kind,
  */
 struct CreateContactMessageResult create_contact_message(uint64_t channel_id,
                                                          int32_t contact_mode,
-                                                         const uint8_t *transport_protocol_ptr,
-                                                         size_t transport_protocol_len,
+                                                         const uint8_t *transport_protocols_ptr,
+                                                         size_t transport_protocols_len,
                                                          uint32_t has_nonce,
                                                          uint64_t nonce);
 
@@ -1362,8 +1442,8 @@ struct DecodeContactMessageResult decode_contact_message(const uint8_t *contact_
  * Non-null input pointers must point to the corresponding readable byte ranges.
  */
 struct ProducePairRequestMessageResult produce_pair_request_message(int32_t sender_kind,
-                                                                    const uint8_t *transport_protocol_ptr,
-                                                                    size_t transport_protocol_len,
+                                                                    const uint8_t *transport_protocols_ptr,
+                                                                    size_t transport_protocols_len,
                                                                     const uint8_t *contact_message_ptr,
                                                                     size_t contact_message_len,
                                                                     const uint8_t *communication_info_ptr,
@@ -1402,7 +1482,8 @@ struct ProducePairResponseMessageResult produce_pair_response_message(uint64_t c
                                                                       const uint8_t *communication_info_ptr,
                                                                       size_t communication_info_len,
                                                                       const uint8_t *parameter_range_ptr,
-                                                                      size_t parameter_range_len);
+                                                                      size_t parameter_range_len,
+                                                                      uint32_t unsafe_connection);
 
 /**
  * # Safety
@@ -1439,8 +1520,8 @@ struct ProcessPairResponseMessageResult process_pair_response_message(const uint
  *
  * Non-null input pointers must point to the corresponding readable byte ranges.
  */
-struct ProducePrePairRequestMessageResult produce_pre_pair_request_message(const uint8_t *transport_protocol_ptr,
-                                                                           size_t transport_protocol_len,
+struct ProducePrePairRequestMessageResult produce_pre_pair_request_message(const uint8_t *transport_protocols_ptr,
+                                                                           size_t transport_protocols_len,
                                                                            const uint8_t *contact_message_ptr,
                                                                            size_t contact_message_len);
 
@@ -1527,6 +1608,7 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   "secret_id": "12345678901234567890",
  *   "own_transport_uri": "https://example.com/derec",
  *   "own_transport_protocol": 1,
+ *   "own_transports": [{ "uri": "https://example.com/derec", "protocol": 0 }],
  *   "threshold": 3,
  *   "keep_versions_count": 2,
  *   "timeout_in_secs": 30,
@@ -1553,6 +1635,11 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   `derec_protocol_set_own_transport` must be called before pairing
  *   in that case.
  * - `own_transport_protocol`: [`derec_proto::Protocol`] discriminant.
+ * - `own_transports`: every endpoint this application serves, in
+ *   preference order — the order decides which of a peer's offered
+ *   endpoints is used. Optional; when non-empty it takes precedence over
+ *   `own_transport_uri` / `own_transport_protocol`, which stay fully
+ *   supported for callers that serve a single transport.
  * - `threshold` / `keep_versions_count`: optional; omitted means
  *   [`crate::protocol::DEFAULT_THRESHOLD`] /
  *   [`crate::protocol::DEFAULT_KEEP_VERSIONS_COUNT`].
@@ -1634,10 +1721,17 @@ struct DeRecError derec_protocol_set_communication_info(struct DeRecProtocolHand
                                                         size_t info_json_len);
 
 /**
- * Replace this node's local transport endpoint. See
- * [`crate::protocol::DeRecProtocol::set_own_transport`] for the
- * changeover discipline (keep the old endpoint up during the
- * transition).
+ * Replace this node's endpoint **for one protocol**, leaving the others
+ * alone. A node serves at most one endpoint per protocol, so the `(uri,
+ * protocol)` pair identifies the entry it replaces; an entry for a protocol
+ * not yet served is appended, and a replaced one keeps its position in the
+ * preference order. See
+ * [`crate::protocol::DeRecProtocol::set_own_transport`] for the changeover
+ * discipline (keep the old endpoint up during the transition).
+ *
+ * Superseded by [`derec_protocol_set_own_transports`], which takes the
+ * whole preference list and is the only way to change *which* protocols
+ * this node serves, or their order.
  *
  * # Safety
  *
@@ -1650,11 +1744,38 @@ struct DeRecError derec_protocol_set_communication_info(struct DeRecProtocolHand
  * from different threads are safe: the handle's internal mutex
  * serializes them.
  */
+__attribute__((deprecated("use derec_protocol_set_own_transports, which takes the whole preference list; removed at 0.0.5")))
 struct DeRecError derec_protocol_set_own_transport(struct DeRecProtocolHandle *handle,
                                                    const uint8_t *uri_ptr,
                                                    size_t uri_len,
                                                    int32_t protocol);
 
+/**
+ * Replace every endpoint this node advertises, in preference order.
+ *
+ * The runtime counterpart to the `own_transports` array accepted by
+ * [`super::derec_protocol_new`], and the way to change the whole set:
+ * `derec_protocol_set_own_transport` replaces only the entry for the
+ * protocol its URI names. A device serves at most one endpoint per
+ * protocol, so this list is a preference order over distinct protocols and
+ * two entries of the same protocol are rejected. Body is the same JSON
+ * shape that config array uses — `[{"uri": "...", "protocol": 0}, ...]`.
+ *
+ * Every entry is validated before any is stored, so a malformed URI
+ * leaves the previous set intact rather than half-applied.
+ *
+ * # Safety
+ *
+ * `handle` must be a valid pointer returned by
+ * [`super::derec_protocol_new`]. `json_ptr`/`json_len` must describe a
+ * readable byte range. Concurrent calls on the same handle from
+ * different threads are safe: the handle's internal mutex serializes
+ * them.
+ */
+struct DeRecError derec_protocol_set_own_transports(struct DeRecProtocolHandle *handle,
+                                                    const uint8_t *json_ptr,
+                                                    size_t json_len);
+
 /**
  * Remove `Pending` channels older than `older_than_secs`. See
  * [`crate::protocol::DeRecProtocol::remove_expired_channels`] for the

package/lib/primitives.d.ts

@@ -12,7 +12,7 @@ declare function decodeContact(wire: Uint8Array | ArrayBuffer): ContactMessage;
 export declare const primitives: {
     discovery: {
         request: {
-            produce(channel_id: bigint, shared_key: Uint8Array, reply_to?: TransportProtocol | null): ProduceResult;
+            produce(channel_id: bigint, shared_key: Uint8Array, reply_to?: TransportProtocol[]): ProduceResult;
             extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): {
                 request: GetSecretIdsVersionsRequestMessage;
             };
@@ -27,22 +27,22 @@ export declare const primitives: {
     };
     pairing: {
         request: {
-            create_contact(channel_id: bigint, contact_mode: ContactMode | number, transport_protocol: TransportProtocol): CreateContactResult;
+            create_contact(channel_id: bigint, contact_mode: ContactMode | number, transport_protocols: TransportProtocol[]): CreateContactResult;
             /** Proto-encodes a `ContactMessage`. Rejects a contact that violates the
              *  mode/field invariant rather than serializing it. */
             encode_contact: typeof encodeContact;
             /** Decodes proto `ContactMessage` bytes. Rejects a contact that violates
              *  the mode/field invariant rather than returning it. */
             decode_contact: typeof decodeContact;
-            produce(kind: SenderKind, transport_protocol: TransportProtocol, contact_message: ContactMessage, communication_info: CommunicationInfo | null, parameter_range: ParameterRange | null): PairingRequestProduceResult;
+            produce(kind: SenderKind, transport_protocols: TransportProtocol[], contact_message: ContactMessage, communication_info: CommunicationInfo | null, parameter_range: ParameterRange | null): PairingRequestProduceResult;
             extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): {
                 request: PairRequestMessage;
             };
-            produce_pre_pair(transport_protocol: TransportProtocol, contact_message: ContactMessage): ProducePrePairResult;
+            produce_pre_pair(own_transports: TransportProtocol[], contact_message: ContactMessage): ProducePrePairResult;
             extract_pre_pair(envelope_bytes: Uint8Array): PrePairRequestExtractResult;
         };
         response: {
-            produce(channel_id: bigint, request: PairRequestMessage, secret_key: Uint8Array, communication_info: CommunicationInfo | null, parameter_range: ParameterRange | null): PairingResponseProduceResult;
+            produce(channel_id: bigint, request: PairRequestMessage, secret_key: Uint8Array, communication_info: CommunicationInfo | null, parameter_range: ParameterRange | null, unsafe_connection?: boolean): PairingResponseProduceResult;
             extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): {
                 response: PairResponseMessage;
             };
@@ -54,7 +54,7 @@ export declare const primitives: {
     };
     recovery: {
         request: {
-            produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to?: TransportProtocol | null): ProduceResult;
+            produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to?: TransportProtocol[]): ProduceResult;
             extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): {
                 request: GetShareRequestMessage;
             };
@@ -70,7 +70,7 @@ export declare const primitives: {
     sharing: {
         request: {
             split(channels: bigint[], secret_id: bigint, version: number, secret_data: Uint8Array, threshold: number): SplitResult;
-            produce(channel_id: bigint, version: number, secret_id: bigint, committed_share: CommittedDeRecShare, keep_list: number[], description: string, shared_key: Uint8Array, reply_to?: TransportProtocol | null): ProduceResult;
+            produce(channel_id: bigint, version: number, secret_id: bigint, committed_share: CommittedDeRecShare, keep_list: number[], description: string, shared_key: Uint8Array, reply_to?: TransportProtocol[]): ProduceResult;
             extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): {
                 request: StoreShareRequestMessage;
             };
@@ -85,7 +85,7 @@ export declare const primitives: {
     };
     unpairing: {
         request: {
-            produce(channel_id: bigint, memo: string, shared_key: Uint8Array, reply_to?: TransportProtocol | null): ProduceResult;
+            produce(channel_id: bigint, memo: string, shared_key: Uint8Array, reply_to?: TransportProtocol[]): ProduceResult;
             extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): {
                 request: UnpairRequestMessage;
             };
@@ -109,7 +109,7 @@ export declare const primitives: {
     };
     verification: {
         request: {
-            produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to?: TransportProtocol | null): ProduceResult;
+            produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to?: TransportProtocol[]): ProduceResult;
             extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): {
                 request: VerifyShareRequestMessage;
             };

package/lib/primitives.js

@@ -28,11 +28,11 @@ function call(name, ...args) {
 function bytes(value) {
     return new Uint8Array(value);
 }
-/** `null` and `undefined` both mean "no override" for every optional
- *  `TransportProtocol` argument; the C ABI reads a zero-length buffer as
- *  absent. */
+/** An omitted or empty list means "no override" for every reply-to argument;
+ *  the C ABI reads a zero-length buffer as absent, and the responder then
+ *  routes to the endpoints already recorded for the channel. */
 function replyTo(value) {
-    return (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.TransportProtocol, value);
+    return value && value.length > 0 ? encodeTransportList(value) : new Uint8Array(0);
 }
 /**
  * `ContactMessage` keeps its own dedicated codec rather than going through
@@ -79,14 +79,64 @@ const discovery = {
         },
     },
 };
+/**
+ * Frames a preference-ordered endpoint list for the native seam: each entry
+ * preceded by its protobuf varint byte length. Order is preserved exactly.
+ */
+function encodeTransportList(transports) {
+    const entries = transports.map((t) => new Uint8Array((0, messages_1.encodeMessage)(messages_1.MessageKind.TransportProtocol, t)));
+    const out = [];
+    for (const entry of entries) {
+        let len = entry.length;
+        do {
+            let b = len & 0x7f;
+            len >>>= 7;
+            if (len !== 0)
+                b |= 0x80;
+            out.push(b);
+        } while (len !== 0);
+        out.push(...entry);
+    }
+    return new Uint8Array(out);
+}
+/**
+ * Reads the framing `encodeTransportList` writes. Order is the peer's and is
+ * preserved exactly — the library filters a peer's endpoints but never ranks
+ * them, so this order is the peer's own preference, not a recommendation.
+ */
+function decodeTransportList(framed) {
+    const buf = framed instanceof Uint8Array ? framed : new Uint8Array(framed);
+    const out = [];
+    let i = 0;
+    while (i < buf.length) {
+        let len = 0;
+        let shift = 0;
+        for (;;) {
+            if (i >= buf.length) {
+                throw new Error('truncated transport list: length prefix runs past the end');
+            }
+            const b = buf[i++];
+            len |= (b & 0x7f) << shift;
+            if ((b & 0x80) === 0)
+                break;
+            shift += 7;
+        }
+        if (i + len > buf.length) {
+            throw new Error('truncated transport list: entry runs past the end');
+        }
+        out.push((0, messages_1.decodeMessage)(messages_1.MessageKind.TransportProtocol, buf.subarray(i, i + len)));
+        i += len;
+    }
+    return out;
+}
 const pairing = {
     request: {
-        create_contact(channel_id, contact_mode, transport_protocol) {
+        create_contact(channel_id, contact_mode, transport_protocols) {
             // The C entry point also accepts a caller-supplied nonce behind a
             // presence flag. `@derec-alliance/nodejs` has no such parameter, so the
             // flag is 0 and the library generates one — the same behaviour, not a
             // default invented here.
-            const result = call('create_contact_message', channel_id, contact_mode, (0, messages_1.encodeMessage)(messages_1.MessageKind.TransportProtocol, transport_protocol), 0, 0n);
+            const result = call('create_contact_message', channel_id, contact_mode, encodeTransportList(transport_protocols), 0, 0n);
             return {
                 contact_message: decodeContact(result.contact_wire_bytes),
                 secret_key: bytes(result.secret_key_material),
@@ -98,8 +148,8 @@ const pairing = {
         /** Decodes proto `ContactMessage` bytes. Rejects a contact that violates
          *  the mode/field invariant rather than returning it. */
         decode_contact: decodeContact,
-        produce(kind, transport_protocol, contact_message, communication_info, parameter_range) {
-            const result = call('produce_pair_request_message', kind, (0, messages_1.encodeMessage)(messages_1.MessageKind.TransportProtocol, transport_protocol), encodeContact(contact_message), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.CommunicationInfo, communication_info), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range));
+        produce(kind, transport_protocols, contact_message, communication_info, parameter_range) {
+            const result = call('produce_pair_request_message', kind, encodeTransportList(transport_protocols), encodeContact(contact_message), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.CommunicationInfo, communication_info), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range));
             return {
                 envelope: bytes(result.request_wire_bytes),
                 initiator_contact_message: decodeContact(result.initiator_contact_message_wire_bytes),
@@ -112,8 +162,8 @@ const pairing = {
                 request: (0, messages_1.decodeMessage)(messages_1.MessageKind.PairRequest, result.request_proto_bytes),
             };
         },
-        produce_pre_pair(transport_protocol, contact_message) {
-            const envelope = call('produce_pre_pair_request_message', (0, messages_1.encodeMessage)(messages_1.MessageKind.TransportProtocol, transport_protocol), encodeContact(contact_message));
+        produce_pre_pair(own_transports, contact_message) {
+            const envelope = call('produce_pre_pair_request_message', encodeTransportList(own_transports), encodeContact(contact_message));
             return { envelope: bytes(envelope) };
         },
         extract_pre_pair(envelope_bytes) {
@@ -124,11 +174,11 @@ const pairing = {
         },
     },
     response: {
-        produce(channel_id, request, secret_key, communication_info, parameter_range) {
-            const result = call('produce_pair_response_message', channel_id, (0, messages_1.encodeMessage)(messages_1.MessageKind.PairRequest, request), secret_key, (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.CommunicationInfo, communication_info), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range));
+        produce(channel_id, request, secret_key, communication_info, parameter_range, unsafe_connection = false) {
+            const result = call('produce_pair_response_message', channel_id, (0, messages_1.encodeMessage)(messages_1.MessageKind.PairRequest, request), secret_key, (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.CommunicationInfo, communication_info), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range), unsafe_connection);
             return {
                 envelope: bytes(result.response_wire_bytes),
-                peer_transport_protocol: (0, messages_1.decodeMessage)(messages_1.MessageKind.TransportProtocol, result.peer_transport_protocol),
+                peer_transports: decodeTransportList(result.peer_transports),
                 shared_key: bytes(result.shared_key),
                 channel_id: result.channel_id,
             };

package/lib/protocol.d.ts

@@ -1,5 +1,5 @@
 import { FlowKind } from './types';
-import type { AutoAcceptPolicy, ChannelStore, ContactMessage, ContactMode, DeRecEvent, DiscoveryParams, PairingParams, ProtectSecretParams, RecoverSecretParams, RemoveReplicaParams, SecretStore, ShareStore, StateStore, SyncCheckParams, Timeouts, Transport, UnpairAck, UnpairParams, UpdateChannelInfoParams, UserSecretStore, VerifySharesParams } from './types';
+import type { AutoAcceptPolicy, ChannelStore, ContactMessage, ContactMode, DeRecEvent, DiscoveryParams, PairingParams, ParameterRange, ProtectSecretParams, RecoverSecretParams, UnpairReplicaParams, SecretStore, ShareStore, StateStore, ReplicaDiscoveryParams, Timeouts, Transport, UnpairAck, UnpairParams, UpdateChannelInfoParams, UserSecretStore, VerifySharesParams } from './types';
 /** Shape of the `__DeRec` host object as seen from this file: every member is
  *  a plain callable, since the JSI layer exposes host functions this way and
  *  TypeScript has no static knowledge of them (see `primitives.ts`'s `call`
@@ -11,7 +11,7 @@ type NativeHost = Record<string, (...args: any[]) => any>;
  * against does not carry this enum (it
  * only covers the Rust-internal serde enums listed under its `"enums"` key);
  * the transport `Protocol` enum lives in `protobufs/transportprotocol.proto`
- * instead, where only `HTTPS = 0` is currently defined.
+ * instead, where `HTTPS = 0` and `GRPC = 1` are defined.
  */
 export declare function protocolDiscriminant(protocol: string): number;
 /**
@@ -66,10 +66,37 @@ export declare class DeRecProtocolBuilder {
     withUserSecretStore(store: UserSecretStore): this;
     withStateStore(store: StateStore): this;
     withTransport(transport: Transport): this;
+    /**
+     * @deprecated Use {@link withOwnTransports}, which takes the whole
+     * preference list — `withOwnTransports([endpoint])` is the direct
+     * replacement. Removed at 0.0.5.
+     */
     withOwnTransport(endpoint: {
         uri: string;
         protocol: string;
     }): this;
+    /**
+     * Set every transport endpoint this application serves, in preference
+     * order. Written to the config's `own_transports` array, which takes
+     * precedence over `own_transport_uri` / `own_transport_protocol` on the
+     * Rust side when non-empty — see `ProtocolConfig` in
+     * `library/src/interop/ffi/protocol/handle/mod.rs`.
+     *
+     * The order given is forwarded verbatim: it is not sorted, deduplicated,
+     * or reordered here. It is this application's own preference and
+     * decides which of a peer's offered endpoints is used. Every listed
+     * transport must actually be served, because delivery is push-only —
+     * listing an endpoint this application does not serve makes pairing
+     * succeed and replies vanish.
+     *
+     * Supersedes {@link withOwnTransport} for applications serving more
+     * than one transport; the single-endpoint setter remains fully
+     * supported.
+     */
+    withOwnTransports(transports: {
+        uri: string;
+        protocol: string;
+    }[]): this;
     /** Default: 3. */
     withThreshold(threshold: number): this;
     /** Default: 3. */
@@ -82,8 +109,22 @@ export declare class DeRecProtocolBuilder {
      * `snake_case` keys one for one.
      */
     withTimeouts(timeouts: Timeouts): this;
-    /** Default: false. */
+    /**
+     * @deprecated Use {@link withUnsafeConnection}, which names both gated
+     * schemes. Removed at 0.0.5. Default: false.
+     */
     withUnsafeHttp(allow: boolean): this;
+    /**
+     * Accept plaintext `http://` and `grpc://` transport endpoints.
+     * **Development only.** Default: false. Supersedes
+     * {@link withUnsafeHttp}, which names only the HTTP scheme.
+     *
+     * Either flag alone is honored. Setting both to disagreeing values fails
+     * construction with the error code `CONFLICTING_PLAINTEXT_OPT_IN` rather
+     * than resolving silently, because precedence would hand the decision to
+     * the flag being removed.
+     */
+    withUnsafeConnection(allow: boolean): this;
     /**
      * Default: empty. `derec_protocol_new`'s own `communication_info` argument
      * is a pre-encoded `CommunicationInfo` protobuf message, and this SDK has
@@ -112,6 +153,17 @@ export declare class DeRecProtocolBuilder {
     withAutoAccept(policy: AutoAcceptPolicy): this;
     /** Default: unset. */
     withReplicaId(replicaId: bigint | number): this;
+    /**
+     * Declare the bounds this node advertises during pair negotiation.
+     *
+     * Embedded in outbound `PairRequest`/`PairResponse` envelopes and checked
+     * against the peer's range on inbound ones: a range that fails to
+     * intersect rejects the pairing. Every bound is optional and defaults to
+     * `0`, which the protocol reads as "no constraint on this dimension".
+     *
+     * Default: unset — no constraints advertised, every peer range accepted.
+     */
+    withParameterRange(range: Partial<ParameterRange>): this;
     build(): DeRecProtocol;
 }
 /**
@@ -153,8 +205,35 @@ export declare class DeRecProtocol {
      * surfaces a failure that would otherwise be swallowed.
      */
     setCommunicationInfo(info: Record<string, string>): Promise<void>;
-    /** Returns a `Promise` for the same reason {@link setCommunicationInfo} does. */
+    /**
+     * Replace this node's endpoint for one protocol, leaving the others
+     * alone. A node serves at most one endpoint per protocol, so the
+     * `(uri, protocol)` pair identifies the entry it replaces; an entry for a
+     * protocol not yet served is appended, and a replaced one keeps its
+     * position in the preference order.
+     *
+     * Returns a `Promise` for the same reason {@link setCommunicationInfo} does.
+     *
+     * @deprecated Use {@link setOwnTransports}, which takes the whole
+     * preference list and is the only way to change which protocols this node
+     * serves, or their order. Removed at 0.0.5.
+     */
     setOwnTransport(uri: string, protocol: string): Promise<void>;
+    /**
+     * Replaces every endpoint this node advertises, in preference order —
+     * the runtime counterpart to `withOwnTransports`, and the only way to
+     * change a multi-endpoint node's set ({@link setOwnTransport} collapses
+     * it to the one endpoint it is given).
+     *
+     * Every entry is validated before any is stored, so a malformed URI
+     * leaves the previous set intact. An empty array is rejected.
+     *
+     * Returns a `Promise` for the same reason {@link setCommunicationInfo} does.
+     */
+    setOwnTransports(transports: {
+        uri: string;
+        protocol: string;
+    }[]): Promise<void>;
     /**
      * Decodes the `contact_wire_bytes` `derec_protocol_create_contact`
      * produces into a typed `ContactMessage`, so an application can read the
@@ -170,8 +249,8 @@ export declare class DeRecProtocol {
     start(flowKind: FlowKind.RecoverSecret, params: RecoverSecretParams): Promise<DeRecEvent[]>;
     start(flowKind: FlowKind.Unpair, params: UnpairParams): Promise<DeRecEvent[]>;
     start(flowKind: FlowKind.UpdateChannelInfo, params: UpdateChannelInfoParams): Promise<DeRecEvent[]>;
-    start(flowKind: FlowKind.SyncCheck, params?: SyncCheckParams): Promise<DeRecEvent[]>;
-    start(flowKind: FlowKind.RemoveReplica, params: RemoveReplicaParams): Promise<DeRecEvent[]>;
+    start(flowKind: FlowKind.ReplicaDiscovery, params?: ReplicaDiscoveryParams): Promise<DeRecEvent[]>;
+    start(flowKind: FlowKind.UnpairReplica, params: UnpairReplicaParams): Promise<DeRecEvent[]>;
     process(message: Uint8Array): Promise<DeRecEvent[]>;
     tick(): Promise<DeRecEvent[]>;
     accept(actionBytes: Uint8Array): Promise<DeRecEvent[]>;