@derec-alliance/react-native 0.0.5 → 0.0.7

package/cpp/derec_ffi.h

@@ -65,13 +65,6 @@
  */
 #define DEFAULT_THRESHOLD 3
 
-/**
- * Number of recent share versions each helper retains, absent an explicit
- * [`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
-
 /**
  * Maximum accepted transport URI length, in bytes.
  *
@@ -296,18 +289,6 @@
  */
 #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.
@@ -678,6 +659,20 @@ typedef struct ExtractPrePairResponseResult {
   struct DeRecBuffer response_proto_bytes;
 } ExtractPrePairResponseResult;
 
+typedef struct ProducePrePairNoKeysResponseMessageResult {
+  struct DeRecError error;
+  /**
+   * Serialized outer plaintext `DeRecMessage` envelope carrying a
+   * `PrePairResponseMessage` with freshly generated public keys.
+   */
+  struct DeRecBuffer envelope_wire_bytes;
+  /**
+   * The secret key material generated for this pairing. The caller MUST
+   * persist it: the `PairRequestMessage` that follows is encrypted to it.
+   */
+  struct DeRecBuffer secret_key_material;
+} ProducePrePairNoKeysResponseMessageResult;
+
 /**
  * On success the two key buffers hold the validated public keys republished
  * by the contact creator. On failure (status non-Ok, hash mismatch, etc.)
@@ -693,6 +688,15 @@ typedef struct ProcessPrePairResponseMessageResult {
   uint64_t nonce;
 } ProcessPrePairResponseMessageResult;
 
+typedef struct PairingFingerprintResult {
+  struct DeRecError error;
+  /**
+   * NUL-terminated UTF-8 fingerprint. Free with
+   * [`crate::interop::ffi::common::derec_free_string`]. Null on failure.
+   */
+  char *fingerprint;
+} PairingFingerprintResult;
+
 /**
  * Result type for [`derec_protocol_new`].
  */
@@ -796,6 +800,12 @@ typedef struct ChannelStoreCallbacks {
 
 /**
  * Caller-supplied callbacks for secret persistence.
+ *
+ * `load_many` receives the requested channel ids as a JSON array of
+ * numbers and returns a JSON array with exactly one entry per requested id,
+ * in the same order: the same `{kind, bytes}` record `load` returns, or
+ * `null` when nothing of `kind` is stored for that channel. Whether a
+ * missing entry is an error is decided by the library, not the callback.
  */
 typedef struct SecretStoreCallbacks {
   void *user_data;
@@ -805,6 +815,13 @@ typedef struct SecretStoreCallbacks {
                   uint32_t kind,
                   uint8_t **out_ptr,
                   size_t *out_len);
+  int32_t (*load_many)(void *user_data,
+                       uint64_t secret_id,
+                       const uint8_t *channel_ids_json_ptr,
+                       size_t channel_ids_json_len,
+                       uint32_t kind,
+                       uint8_t **out_ptr,
+                       size_t *out_len);
   int32_t (*save)(void *user_data,
                   uint64_t secret_id,
                   uint64_t channel_id,
@@ -820,6 +837,11 @@ typedef struct SecretStoreCallbacks {
  * arrays (`channel_ids[]`, `versions[]`) cross the FFI as JSON
  * strings, matching the `Vec<u8>` ↔ JSON-array convention used for
  * every other wire-format buffer in this module.
+ *
+ * `keep_list` returns the JSON encoding of the application's answer:
+ * `null` for no list (the owner sends an empty `keepList` and helpers keep
+ * every version) or an array of version numbers. An empty buffer or return code `1` also
+ * means `null`.
  */
 typedef struct ShareStoreCallbacks {
   void *user_data;
@@ -854,6 +876,16 @@ typedef struct ShareStoreCallbacks {
                   const uint8_t *share_json_ptr,
                   size_t share_json_len);
   int32_t (*remove_channel)(void *user_data, uint64_t secret_id, uint64_t channel_id);
+  int32_t (*remove_versions)(void *user_data,
+                             uint64_t secret_id,
+                             uint64_t channel_id,
+                             const uint8_t *versions_json_ptr,
+                             size_t versions_json_len);
+  int32_t (*keep_list)(void *user_data,
+                       uint64_t secret_id,
+                       uint32_t version,
+                       uint8_t **out_ptr,
+                       size_t *out_len);
   void (*free_buffer)(void *user_data, uint8_t *ptr, size_t len);
 } ShareStoreCallbacks;
 
@@ -977,6 +1009,51 @@ typedef struct DeRecProtocolEventsResult {
   struct DeRecBuffer events_json;
 } DeRecProtocolEventsResult;
 
+/**
+ * Result of [`derec_protocol_process`].
+ *
+ * A failed call still carries the events produced before the failure in
+ * `events_json`, and names the channel the failing message came from.
+ */
+typedef struct DeRecProtocolProcessResult {
+  struct DeRecError error;
+  /**
+   * UTF-8 JSON array of events, as on [`DeRecProtocolEventsResult`].
+   * Filled on success and on failure.
+   */
+  struct DeRecBuffer events_json;
+  /**
+   * Whether `channel_id` is set. False on success and when the bytes
+   * were not a decodable envelope.
+   */
+  bool has_channel_id;
+  /**
+   * The channel the failing message came from.
+   */
+  uint64_t channel_id;
+} DeRecProtocolProcessResult;
+
+/**
+ * Result of [`derec_protocol_restore`].
+ *
+ * A restore refused because channels already exist at the recovered ids
+ * reports which ones in `conflicting_channel_ids_json`, so the application
+ * can clear exactly those and retry.
+ */
+typedef struct DeRecProtocolRestoreResult {
+  struct DeRecError error;
+  /**
+   * UTF-8 JSON array of events, as on [`DeRecProtocolEventsResult`].
+   */
+  struct DeRecBuffer events_json;
+  /**
+   * UTF-8 JSON array of decimal-string channel ids. Non-empty only when
+   * `error.code` is `DEREC_CODE_RESTORE_CONFLICT`. Caller releases via
+   * [`crate::interop::ffi::derec_free_buffer`].
+   */
+  struct DeRecBuffer conflicting_channel_ids_json;
+} DeRecProtocolRestoreResult;
+
 /**
  * Result type for fingerprint accessors.
  */
@@ -1372,34 +1449,9 @@ struct CreateContactMessageResult create_contact_message(uint64_t channel_id,
                                                          uint32_t has_nonce,
                                                          uint64_t nonce);
 
-/**
- * Structurally validate a proto-encoded `ContactMessage`. Returns a
- * successful [`DeRecError`] iff the contact's `(contact_mode, inline keys,
- * binding hash)` tuple satisfies the per-mode invariants enforced by the
- * pairing primitives. Intended for bindings to call at their parse
- * boundary (e.g. `FromProtoBytes`) so that the decoded value handed to
- * application code is guaranteed well-formed.
- *
- * Failure codes:
- * - [`DEREC_CODE_FFI_BAD_PROTO`] if the bytes do not decode as a
- *   `ContactMessage`.
- * - The library's `InvalidContactMessage` error code on any structural
- *   violation (unknown `contact_mode`, mode/field mismatch, wrong
- *   binding-hash length).
- *
- * # Safety
- *
- * `contact_message_ptr` must point to a readable range of
- * `contact_message_len` bytes (or be null with `len == 0`).
- */
-struct DeRecError validate_contact_message(const uint8_t *contact_message_ptr,
-                                           size_t contact_message_len);
-
 /**
  * Encodes a JSON [`ContactMessageDto`] to `ContactMessage` proto wire bytes.
- * Structurally validates the input first so a locally-constructed contact
- * that violates the mode/field invariant is rejected at the boundary rather
- * than silently serialized.
+ * See [`crate::primitives::pairing::request::encode_contact`].
  *
  * The JSON shape is [`ContactMessageDto`]'s serde representation with one
  * adjustment applied at this seam: `channel_id` and `nonce` are decimal
@@ -1419,9 +1471,7 @@ struct EncodeContactMessageResult encode_contact_message(const uint8_t *contact_
 /**
  * Decodes proto-encoded `ContactMessage` wire bytes into the JSON
  * [`ContactMessageDto`] shape described on [`encode_contact_message`].
- * Structurally validates the decoded value before returning it to
- * application code so consumers can trust the mode/field invariants
- * documented on the wire format.
+ * See [`crate::primitives::pairing::request::decode_contact`].
  *
  * # Safety
  *
@@ -1452,6 +1502,10 @@ struct ProducePairRequestMessageResult produce_pair_request_message(int32_t send
                                                                     size_t parameter_range_len);
 
 /**
+ * `parameter_range_ptr` may be null / zero-length to declare no parameter
+ * range; otherwise it must be serialized [`derec_proto::ParameterRange`]
+ * proto bytes. See [`crate::primitives::pairing::request::extract`].
+ *
  * # Safety
  *
  * Non-null input pointers must point to the corresponding readable byte ranges.
@@ -1459,7 +1513,9 @@ struct ProducePairRequestMessageResult produce_pair_request_message(int32_t send
 struct ExtractPairRequestResult extract_pair_request(const uint8_t *request_ptr,
                                                      size_t request_len,
                                                      const uint8_t *secret_key_material_ptr,
-                                                     size_t secret_key_material_len);
+                                                     size_t secret_key_material_len,
+                                                     const uint8_t *parameter_range_ptr,
+                                                     size_t parameter_range_len);
 
 /**
  * `request_proto_ptr` / `request_proto_len` must be the `request_proto_bytes`
@@ -1499,6 +1555,10 @@ struct ExtractPairResponseResult extract_pair_response(const uint8_t *response_p
  * `response_proto_ptr` / `response_proto_len` must be the
  * `response_proto_bytes` returned by [`extract_pair_response`].
  *
+ * `parameter_range_ptr` may be null / zero-length to declare no parameter
+ * range; otherwise it must be serialized [`derec_proto::ParameterRange`]
+ * proto bytes. See [`crate::primitives::pairing::response::process`].
+ *
  * # Safety
  *
  * Non-null input pointers must point to the corresponding readable byte ranges.
@@ -1508,7 +1568,9 @@ struct ProcessPairResponseMessageResult process_pair_response_message(const uint
                                                                       const uint8_t *response_proto_ptr,
                                                                       size_t response_proto_len,
                                                                       const uint8_t *secret_key_material_ptr,
-                                                                      size_t secret_key_material_len);
+                                                                      size_t secret_key_material_len,
+                                                                      const uint8_t *parameter_range_ptr,
+                                                                      size_t parameter_range_len);
 
 /**
  * Builds a plaintext `PrePairRequestMessage` envelope. Used by the scanner
@@ -1563,6 +1625,55 @@ struct ProducePrePairResponseMessageResult produce_pre_pair_response_message(uin
 struct ExtractPrePairResponseResult extract_pre_pair_response(const uint8_t *envelope_ptr,
                                                               size_t envelope_len);
 
+/**
+ * Contact-creator side of a `NO_KEYS` pairing: generates key material and
+ * answers the `PrePairRequestMessage` with its public half.
+ *
+ * The caller MUST first match the request's `nonce` against the contact it
+ * issued — the only thing that authenticates a `NO_KEYS` request — and MUST
+ * keep the resulting channel unusable until both sides confirm
+ * [`pairing_fingerprint`] out of band.
+ *
+ * `request_proto_ptr` / `request_proto_len` must be the `request_proto_bytes`
+ * returned by [`extract_pre_pair_request`].
+ *
+ * # Safety
+ *
+ * Non-null input pointers must point to the corresponding readable byte ranges.
+ */
+struct ProducePrePairNoKeysResponseMessageResult produce_pre_pair_no_keys_response_message(uint64_t channel_id,
+                                                                                           const uint8_t *request_proto_ptr,
+                                                                                           size_t request_proto_len);
+
+/**
+ * Scanner side of a `NO_KEYS` pairing: accepts the contact creator's public
+ * keys. There is no binding hash to check them against, so the channel this
+ * leads to MUST stay unusable until both sides confirm
+ * [`pairing_fingerprint`] out of band.
+ *
+ * `response_proto_ptr` / `response_proto_len` must be the
+ * `response_proto_bytes` returned by [`extract_pre_pair_response`].
+ *
+ * # Safety
+ *
+ * Non-null input pointers must point to the corresponding readable byte ranges.
+ */
+struct ProcessPrePairResponseMessageResult process_pre_pair_no_keys_response_message(const uint8_t *contact_message_ptr,
+                                                                                     size_t contact_message_len,
+                                                                                     const uint8_t *response_proto_ptr,
+                                                                                     size_t response_proto_len);
+
+/**
+ * The human-readable fingerprint of a pairing's shared key. See
+ * [`crate::primitives::pairing::fingerprint`].
+ *
+ * # Safety
+ *
+ * `shared_key_ptr` must point to `shared_key_len` readable bytes.
+ */
+struct PairingFingerprintResult pairing_fingerprint(const uint8_t *shared_key_ptr,
+                                                    size_t shared_key_len);
+
 /**
  * Scanner-side: validates a decoded `PrePairResponseMessage` against the
  * original `ContactMessage`'s SHA-384 binding hash. On success returns the
@@ -1588,30 +1699,24 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  * arguments in a single call — e.g. Go via `purego` (no cgo), which
  * panics with "too many stack arguments" past a handful of
  * parameters. Scalar configuration is bundled into a single JSON
- * buffer; `communication_info` stays a separate proto-encoded
- * `CommunicationInfo` buffer; the 6 store/transport callback structs
+ * buffer; `communication_info` travels either in that JSON or as a
+ * separate proto-encoded `CommunicationInfo` buffer; the 6 store/transport callback structs
  * are still passed as individual pointers, since purego marshals
  * pointer-sized arguments natively.
  *
- * `config_json` must deserialize to the following shape — all field
- * names `snake_case`. `secret_id`, `own_transport_uri` and
- * `own_transport_protocol` are the only genuinely required fields;
- * `threshold`, `keep_versions_count`, `auto_respond_on_failure`,
- * `unpair_ack`, `auto_reply_to` and `auto_accept` may each be omitted, in
- * which case the value matches
+ * `config_json` must deserialize to [`ProtocolConfig`] — all field names
+ * `snake_case`. `secret_id` is the only required field. Every other field
+ * may be omitted, in which case the value matches
  * [`crate::protocol::DeRecProtocolBuilder::new`]'s own default for that
- * setting — see [`ProtocolConfig`]'s field-level `#[serde(default)]`
- * attributes, which read the same constants the builder does:
+ * setting: [`ProtocolConfig`]'s field-level `#[serde(default)]` attributes
+ * read the same constants the builder does. A field that is present is
+ * used as given, including `0`, and validated by the builder.
  *
  * ```json
  * {
  *   "secret_id": "12345678901234567890",
- *   "own_transport_uri": "https://example.com/derec",
- *   "own_transport_protocol": 1,
- *   "own_transports": [{ "uri": "https://example.com/derec", "protocol": 0 }],
+ *   "own_transports": [{ "uri": "https://example.com/derec", "protocol": "https" }],
  *   "threshold": 3,
- *   "keep_versions_count": 2,
- *   "timeout_in_secs": 30,
  *   "auto_respond_on_failure": false,
  *   "unpair_ack": 0,
  *   "auto_reply_to": false,
@@ -1625,36 +1730,62 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *     "unpair": false,
  *     "update_channel_info": false
  *   },
- *   "remove_expired_channels": { "enabled": true, "timeout_in_secs": 300 },
- *   "replica_id": null
+ *   "timeouts": {
+ *     "inbound_message_secs": 300,
+ *     "sharing_round_secs": 60,
+ *     "unpair_ack_secs": 60,
+ *     "expired_channels": { "enabled": true, "timeout_in_secs": 300 }
+ *   },
+ *   "unsafe_connection": false,
+ *   "replica_id": null,
+ *   "parameter_range": {
+ *     "min_share_size": 0,
+ *     "max_share_size": 0,
+ *     "min_time_between_verifications": 0,
+ *     "max_time_between_verifications": 0,
+ *     "min_time_between_share_updates": 0,
+ *     "max_time_between_share_updates": 0,
+ *     "min_unresponsive_deletion_timeout": 0,
+ *     "max_unresponsive_deletion_timeout": 0,
+ *     "min_unresponsive_deactivation_timeout": 0,
+ *     "max_unresponsive_deactivation_timeout": 0
+ *   }
  * }
  * ```
  *
  * - `secret_id`: decimal-string `u64`.
- * - `own_transport_uri`: may be `""` for the deferred-config path;
- *   `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`].
- * - `unpair_ack`: `0` = Required, `1` = NotRequired; optional, omitted
- *   means `0`.
- * - `auto_respond_on_failure` / `auto_reply_to`: optional, omitted means
- *   `false`.
- * - `auto_accept`: one boolean per flow; the whole object is optional,
- *   omitted means every flow `false`.
- * - `remove_expired_channels`: automatic removal of expired `Pending`
- *   channels. Optional — omitted means `{ "enabled": true,
- *   "timeout_in_secs": 300 }`. Both fields are always sent; when
- *   `enabled` is `false` the timeout is ignored by the library.
+ *   endpoints is used. `protocol` is its name (`"https"`, `"grpc"`) or
+ *   its `derec_proto::Protocol` discriminant (`0`, `1`). Each entry is validated, and
+ *   two entries of the same protocol are rejected. Required: an absent or
+ *   empty list is refused, since a node with no endpoint cannot be reached
+ *   by any peer.
+ * - `threshold`: omitted means [`crate::protocol::DEFAULT_THRESHOLD`]. A
+ *   `threshold` below `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
+ * - `unpair_ack`: `0` / `"required"` = Required, `1` / `"not_required"` =
+ *   NotRequired; omitted means Required.
+ *   Any other value is rejected with `DEREC_CODE_FFI_INVALID_ENUM`.
+ * - `auto_respond_on_failure` / `auto_reply_to`: omitted means `false`.
+ * - `timeouts`: the four waiting periods, in whole seconds. Each field is
+ *   optional and omitted means the [`crate::protocol::types::Timeouts`]
+ *   default. `expired_channels` is the automatic removal of `Pending`
+ *   channels; both of its fields are always sent, and when `enabled` is
+ *   `false` the timeout is ignored by the library.
+ * - `unsafe_connection`: accept plaintext `http://` and `grpc://`
+ *   endpoints. Development only; omitted means `false`.
  * - `replica_id`: decimal-string `u64`, or absent/`null` for "no
  *   replica id".
+ * - `auto_accept`: each flow is individually optional; an omitted flow
+ *   takes [`crate::protocol::AutoAcceptPolicy::default()`]'s value.
+ * - `parameter_range`: the bounds advertised during pair negotiation,
+ *   mirroring [`derec_proto::ParameterRange`]. Optional object; every bound
+ *   is optional, omitted means `0` ("no constraint"), and each may be a JSON
+ *   number or a decimal string.
+ * - `communication_info`: optional flat JSON object of string keys to
+ *   string values. Mutually exclusive with a non-empty
+ *   `communication_info_ptr` buffer; omitted with an empty buffer means
+ *   no entries.
  *
  * # Safety
  *
@@ -1720,46 +1851,15 @@ struct DeRecError derec_protocol_set_communication_info(struct DeRecProtocolHand
                                                         const uint8_t *info_json_ptr,
                                                         size_t info_json_len);
 
-/**
- * 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
- *
- * `handle` must be a valid pointer returned by
- * [`super::derec_protocol_new`]. `uri_ptr`/`uri_len` must describe a
- * readable byte range. The `(uri, protocol)` pair is validated via
- * [`super::validate_transport`] before it is stored — see that
- * function's docs for the structural rules (length cap, scheme
- * match, enum discriminant). Concurrent calls on the same handle
- * 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
+ * [`super::derec_protocol_new`]. 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}, ...]`.
+ * shape that config array uses — `[{"uri": "...", "protocol": "https"}, ...]`,
+ * with `protocol` as its name or its `derec_proto::Protocol` discriminant.
  *
  * Every entry is validated before any is stored, so a malformed URI
  * leaves the previous set intact rather than half-applied.
@@ -1809,7 +1909,8 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
 
 /**
  * Process an inbound `DeRecMessage` envelope. See
- * [`crate::protocol::DeRecProtocol::process`].
+ * [`crate::protocol::DeRecProtocol::process`]. On failure the result still
+ * carries the events produced before it and the failing channel.
  *
  * # Safety
  *
@@ -1817,9 +1918,9 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
  * [`super::derec_protocol_new`]. `message_ptr`/`message_len` must
  * describe a readable byte range.
  */
-struct DeRecProtocolEventsResult derec_protocol_process(struct DeRecProtocolHandle *handle,
-                                                        const uint8_t *message_ptr,
-                                                        size_t message_len);
+struct DeRecProtocolProcessResult derec_protocol_process(struct DeRecProtocolHandle *handle,
+                                                         const uint8_t *message_ptr,
+                                                         size_t message_len);
 
 /**
  * Advance time-driven state without an inbound message. See
@@ -1883,13 +1984,15 @@ struct DeRecError derec_protocol_reject(struct DeRecProtocolHandle *handle,
  * {
  *   "version": 7,
  *   "recovered_secret": {
- *     "helpers": [{ "channel_id": "11", "transport_uri": "...",
+ *     "helpers": [{ "channel_id": "11",
+ *                   "transports": [{ "uri": "https://helper.example", "protocol": "https" }],
  *                   "shared_key": [..32 bytes..],
  *                   "communication_info": {} }],
  *     "secrets": [{ "id": [..], "name": "...", "data": [..] }],
  *     "replicas": {
  *       "channel_id": "21",
- *       "members": [{ "replica_id": "51966", "transport_uri": "...",
+ *       "members": [{ "replica_id": "51966",
+ *                     "transports": [{ "uri": "https://replica.example", "protocol": "https" }],
  *                     "role": "Source", "communication_info": {} }],
  *       "shared_key": [..32 bytes..]
  *     }
@@ -1898,8 +2001,14 @@ struct DeRecError derec_protocol_reject(struct DeRecProtocolHandle *handle,
  * ```
  *
  * Field names mirror `SecretWire` in `protocol/events/wire.rs` — the
- * same shape `SecretRecovered` carries. `channel_id` and `replica_id`
- * are decimal `u64` strings (empty / absent means zero).
+ * same shape `SecretRecovered` carries, so the `secret` of that event can
+ * be passed back unchanged. `channel_id` and `replica_id` are required
+ * decimal `u64` strings; an absent, empty, or malformed id is rejected.
+ * `transports` is every endpoint the peer advertised, in its preference
+ * order; `protocol` is its name, `"https"` or `"grpc"`. An absent or
+ * `null` `transports` reads as an empty list, and a helper or member with
+ * no endpoint gets no channel: restore skips it and reports it as a
+ * `PeerNotRestored` event. `role` is `"Source"` or `"Destination"`.
  *
  * `replicas` is an **object**, not an array, and is omitted entirely when
  * the `secret_id` has no replica group. Every member of the group shares
@@ -1907,15 +2016,23 @@ struct DeRecError derec_protocol_reject(struct DeRecProtocolHandle *handle,
  * repeated per member; a member is identified by `replica_id` alone, and
  * the group's source is the member whose `role` is `"Source"`.
  *
+ * On success the result carries the events the restore produced, as
+ * [`DeRecProtocolEventsResult`] does — one `PeerNotRestored` per skipped
+ * helper or member among them. When channels already exist at ids
+ * restore is about to write, `error.code` is
+ * `DEREC_CODE_RESTORE_CONFLICT` and `conflicting_channel_ids_json` lists
+ * exactly those ids; nothing is written, so the application can clear
+ * them and retry.
+ *
  * # Safety
  *
  * `handle` must be a valid pointer returned by
  * [`super::derec_protocol_new`]. `params_json_ptr`/`params_json_len`
  * must describe a readable byte range.
  */
-struct DeRecProtocolEventsResult derec_protocol_restore(struct DeRecProtocolHandle *handle,
-                                                        const uint8_t *params_json_ptr,
-                                                        size_t params_json_len);
+struct DeRecProtocolRestoreResult derec_protocol_restore(struct DeRecProtocolHandle *handle,
+                                                         const uint8_t *params_json_ptr,
+                                                         size_t params_json_len);
 
 /**
  * Derive the human-readable fingerprint for a paired channel. See
@@ -1985,6 +2102,48 @@ struct DeRecProtocolCreateContactResult derec_protocol_create_contact(struct DeR
                                                                       uint32_t has_nonce,
                                                                       uint64_t nonce);
 
+/**
+ * Decode the `endpoints` buffer a [`TransportCallbacks::send`] call
+ * receives into a UTF-8 JSON array of `{"protocol": "...", "uri": "..."}`
+ * objects, order preserved. `protocol` is the name
+ * [`crate::interop::ffi::protocol_names::derec_transport_protocol_name`] gives the
+ * discriminant, the same endpoint shape the WASM SDKs hand to their
+ * transport's `send`. An entry with an unknown protocol discriminant, or a
+ * malformed buffer, is an error rather than a guessed name.
+ *
+ * Release `bytes` with [`crate::interop::ffi::common::derec_free_buffer`].
+ *
+ * # Safety
+ *
+ * `endpoints_ptr` must be valid for reads of `endpoints_len` bytes when
+ * `endpoints_len` is non-zero.
+ */
+struct DeRecMessageJsonResult derec_transport_endpoints_json(const uint8_t *endpoints_ptr,
+                                                             size_t endpoints_len);
+
+/**
+ * Static NUL-terminated name (`"https"` or `"grpc"`) for a
+ * `derec_proto::Protocol` discriminant.
+ *
+ * Returns NULL for a discriminant outside the defined protocols. The
+ * returned pointer has static lifetime and must **not** be freed.
+ */
+const char *derec_transport_protocol_name(int32_t protocol);
+
+/**
+ * `derec_proto::Protocol` discriminant for a protocol name, compared
+ * case-insensitively.
+ *
+ * Returns `-1` when the name is not valid UTF-8 or names no defined
+ * protocol.
+ *
+ * # Safety
+ *
+ * `name_ptr`/`name_len` must describe a readable byte range, or `name_len`
+ * must be zero.
+ */
+int32_t derec_transport_protocol_discriminant(const uint8_t *name_ptr, size_t name_len);
+
 struct DeRecProtocolVersion derec_protocol_version(void);
 
 /**
@@ -2053,6 +2212,13 @@ struct RecoverFromShareResponsesResult recover_from_share_responses(const uint8_
                                                                     uint64_t secret_id,
                                                                     uint32_t version);
 
+/**
+ * A fresh replica identity. See [`crate::generate_replica_id`]: the caller
+ * persists it once per device and passes the same value on every protocol
+ * init. Never `0`.
+ */
+uint64_t derec_generate_replica_id(void);
+
 /**
  * # Safety
  *