@derec-alliance/react-native 0.0.5 → 0.0.7

package/README.md

@@ -98,7 +98,7 @@ const protocol = new DeRecProtocolBuilder(secretId) // bigint | number
   .withUserSecretStore(myUserSecretStore)
   .withStateStore(myStateStore)
   .withTransport(myTransport)
-  .withOwnTransport({ uri: 'https://owner.example.com', protocol: 'https' })
+  .withOwnTransports([{ uri: 'https://owner.example.com', protocol: 'https' }])
   .withThreshold(2)
   .build();
 
@@ -125,6 +125,27 @@ longer needed (safe to call more than once).
 
 ---
 
+## When `process()` fails
+
+`process()` settles expired deadlines (sharing-round and unpair timeouts)
+before it handles the message, and those are never reported again. So when
+the message then fails, the thrown `DeRecError` carries them: `events` holds
+every event produced before the failure, and `channel_id` names the channel
+the message came from (absent when the bytes were not a decodable envelope).
+Handle the events as you would a successful call's, then the error:
+
+```ts
+try {
+  handle(await protocol.process(bytes));
+} catch (error) {
+  const failure = error as DeRecError;
+  handle(failure.events ?? []);
+  report(failure.channel_id, failure);
+}
+```
+
+---
+
 ## Store interfaces
 
 The application layer owns all persistence; the library never writes to disk
@@ -134,6 +155,9 @@ declared in `src/types.ts`:
 - **`ChannelStore`** — pairing state: helper channels and replica-group
   membership, keyed by `(channelId, replicaId)`.
 - **`ShareStore`** — versioned VSS shares this device holds as a helper.
+  On an owner, `keepList` chooses which versions helpers keep; returning
+  `null` sends no keepList, so helpers keep every version; see
+  [the owner's keep list](https://github.com/derecalliance/lib-derec/tree/main/library#share-store-the-owners-keep-list).
 - **`SecretStore`** — small per-channel key material (shared keys, etc.),
   distinct from share bytes.
 - **`UserSecretStore`** — the most recent user-facing secret snapshot per
@@ -141,9 +165,14 @@ declared in `src/types.ts`:
 - **`StateStore`** — in-flight orchestrator bookkeeping (pending
   verifications, recoveries, unpairs, sharing rounds, replica discoveries) so a
   multi-round flow survives an app restart.
-- **`Transport`** — outbound delivery. `send(endpoint, message)` posts a
-  wire-format envelope to a peer; it is a mailbox, not a request/response
-  call, since not every peer (e.g. a phone behind NAT) can be dialed back.
+- **`Transport`** — outbound delivery.
+  `send(endpoints: ReadonlyArray<{ protocol: string; uri: string }>, message: Uint8Array): Promise<void>`
+  posts a wire-format envelope to a peer. `endpoints` is every address that
+  peer advertised, in its own order (`protocol` is `"https"` or `"grpc"`);
+  deliver once, to the first one that accepts it, and reject only when none
+  did. `sequentialFailover` and `singleEndpointTransport` implement that
+  choice for you. It is a mailbox, not a request/response call, since not
+  every peer (e.g. a phone behind NAT) can be dialed back.
 
 Every method is `async` and keyed by decimal-string ids — see the next
 section for why that differs from `DeRecProtocol`'s own methods. Full field-
@@ -215,17 +244,6 @@ after whatever is in flight.
 
 ## Known differences from `@derec-alliance/nodejs`
 
-**`setCommunicationInfo()`, `setOwnTransport()` and `setOwnTransports()` return a `Promise`.**
-`@derec-alliance/nodejs` declares both `void`. Here they must not run on the
-JavaScript thread: the underlying FFI setter takes the same handle lock a
-running flow holds across its store callbacks, and those callbacks block the
-worker until JavaScript settles them — so a synchronous setter would block
-the JavaScript thread on a lock only the JavaScript thread can release. The
-binding queues them onto the same serial worker every flow runs on instead.
-The nodejs SDK is WASM and single-threaded, so it cannot hit this. Code that
-ignores the return value — the way nodejs code calls these — is unaffected;
-awaiting them additionally lets a failure surface instead of vanishing.
-
 **The `DeRecErrorCategory` union differs from nodejs's.** This SDK's union
 omits `"wasm"`, which a C-ABI binding can never emit, and adds `"ok"`,
 `"ffi"` and `"state_store"`, which it can. A test pins the union to the crate's shared enum fixture so it stays in step

package/android/CMakeLists.txt

@@ -14,7 +14,7 @@ find_package(fbjni REQUIRED CONFIG)
 
 # Non-recursive on purpose: `cpp/tests/` holds the host-only test harness,
 # which must not be compiled into the device library.
-file(GLOB DEREC_CPP_SOURCES "${CMAKE_SOURCE_DIR}/../cpp/*.cpp")
+file(GLOB DEREC_CPP_SOURCES CONFIGURE_DEPENDS "${CMAKE_SOURCE_DIR}/../cpp/*.cpp")
 
 add_library(derec_jsi SHARED
   ${DEREC_CPP_SOURCES}

package/cpp/Convert.cpp

@@ -5,6 +5,7 @@
 
 #include <cstdlib>
 #include <cstring>
+#include <utility>
 
 namespace derec {
 
@@ -33,6 +34,23 @@ std::vector<uint8_t> takeBuffer(DeRecBuffer& buffer) {
   return out;
 }
 
+RestoreOutcome takeRestoreResult(DeRecProtocolRestoreResult& result) {
+  RestoreOutcome out{result.error, {}, {}};
+  try {
+    out.events = takeBuffer(result.events_json);
+    out.conflictingChannelIdsJson = takeBuffer(result.conflicting_channel_ids_json);
+  } catch (...) {
+    // `takeBuffer` clears a buffer only after releasing it, so whichever is
+    // still set here was never released.
+    derec_free_buffer(result.events_json.ptr, result.events_json.len);
+    derec_free_buffer(result.conflicting_channel_ids_json.ptr,
+                      result.conflicting_channel_ids_json.len);
+    derec_free_error(&result.error);
+    throw;
+  }
+  return out;
+}
+
 std::string takeString(char* owned) {
   if (owned == nullptr) {
     return {};
@@ -47,4 +65,111 @@ std::pair<std::string, std::string> errorName(int32_t category, int32_t code) {
           std::string(derec_error_code_name(code))};
 }
 
+
+// Minimal decoders for the wire's "bare JSON array/object of unsigned
+// integers" convention (`versions_json`, `channel_ids_json`, the `bytes`
+// field of a `ShareRecord` / `SecretValueRecord`). These are produced by
+// `serde_json`'s default compact, whitespace-free output over a fixed,
+// known shape, so a substring scan is sufficient and — critically — never
+// routes a `u64` through a JS `number`, which cannot represent every value
+// in that range exactly.
+
+namespace {
+
+/// Offset just past `"key":` in a flat, compact JSON object, or
+/// `std::string::npos` if `key` is absent.
+size_t fieldValueOffset(const std::string& json, const char* key) {
+  std::string needle = std::string("\"") + key + "\":";
+  size_t pos = json.find(needle);
+  return pos == std::string::npos ? std::string::npos : pos + needle.size();
+}
+
+uint64_t parseUnsignedAt(const std::string& json, size_t pos) {
+  uint64_t value = 0;
+  while (pos < json.size() && json[pos] >= '0' && json[pos] <= '9') {
+    value = value * 10 + static_cast<uint64_t>(json[pos] - '0');
+    ++pos;
+  }
+  return value;
+}
+
+std::vector<uint8_t> parseByteArrayAt(const std::string& json, size_t pos) {
+  std::vector<uint8_t> out;
+  while (pos < json.size() && json[pos] != '[') ++pos;
+  if (pos >= json.size()) return out;
+  ++pos;
+  while (pos < json.size() && json[pos] != ']') {
+    if (json[pos] < '0' || json[pos] > '9') {
+      ++pos;
+      continue;
+    }
+    uint64_t value = 0;
+    while (pos < json.size() && json[pos] >= '0' && json[pos] <= '9') {
+      value = value * 10 + static_cast<uint64_t>(json[pos] - '0');
+      ++pos;
+    }
+    out.push_back(static_cast<uint8_t>(value));
+  }
+  return out;
+}
+
+/// The string inside `"key":"..."` in a flat, compact JSON object, or empty
+/// if `key` is absent.
+std::optional<std::string> quotedFieldValue(const std::string& json, const char* key) {
+  size_t pos = fieldValueOffset(json, key);
+  if (pos == std::string::npos || pos >= json.size() || json[pos] != '"') return std::nullopt;
+  size_t end = json.find('"', pos + 1);
+  if (end == std::string::npos) return std::nullopt;
+  return json.substr(pos + 1, end - pos - 1);
+}
+
+}  // namespace
+
+/// Parse a bare `[n, n, ...]` array of unsigned decimal integers.
+std::vector<uint64_t> parseUnsignedJsonArray(const uint8_t* ptr, size_t len) {
+  std::vector<uint64_t> out;
+  size_t i = 0;
+  while (i < len && ptr[i] != '[') ++i;
+  if (i >= len) return out;
+  ++i;
+  while (i < len && ptr[i] != ']') {
+    if (ptr[i] < '0' || ptr[i] > '9') {
+      ++i;
+      continue;
+    }
+    uint64_t value = 0;
+    while (i < len && ptr[i] >= '0' && ptr[i] <= '9') {
+      value = value * 10 + static_cast<uint64_t>(ptr[i] - '0');
+      ++i;
+    }
+    out.push_back(value);
+  }
+  return out;
+}
+
+/// `{"kind":<n>,"bytes":[<n>,...]}` — the wire shape `SecretStore.save`
+/// receives; `kind` is already carried as a separate FFI argument so only
+/// `bytes` needs to be read back out.
+std::vector<uint8_t> decodeSecretValueBytes(const uint8_t* ptr, size_t len) {
+  std::string json(reinterpret_cast<const char*>(ptr), len);
+  size_t pos = fieldValueOffset(json, "bytes");
+  if (pos == std::string::npos) return {};
+  return parseByteArrayAt(json, pos);
+}
+
+std::optional<DecodedShare> decodeShareRecord(const uint8_t* ptr, size_t len) {
+  std::string json(reinterpret_cast<const char*>(ptr), len);
+  std::optional<std::string> secretId = quotedFieldValue(json, "secret_id");
+  size_t versionPos = fieldValueOffset(json, "version");
+  size_t bytesPos = fieldValueOffset(json, "bytes");
+  if (!secretId || versionPos == std::string::npos || bytesPos == std::string::npos) {
+    return std::nullopt;
+  }
+  DecodedShare out;
+  out.secretId = std::move(*secretId);
+  out.version = static_cast<uint32_t>(parseUnsignedAt(json, versionPos));
+  out.bytes = parseByteArrayAt(json, bytesPos);
+  return out;
+}
+
 }  // namespace derec

package/cpp/Convert.h

@@ -5,6 +5,7 @@
 
 #include <cstddef>
 #include <cstdint>
+#include <optional>
 #include <string>
 #include <utility>
 #include <vector>
@@ -32,7 +33,41 @@ std::vector<uint8_t> takeBuffer(DeRecBuffer& buffer);
 /// Copy a Rust-owned C string and release it via `derec_free_string`.
 std::string takeString(char* owned);
 
+/// Every owned part of a `DeRecProtocolRestoreResult`, copied out with both
+/// buffers already released. `error`'s strings stay owned: they are released
+/// by `throwDeRecError`, as for every other result.
+struct RestoreOutcome {
+  DeRecError error;
+  std::vector<uint8_t> events;
+  std::vector<uint8_t> conflictingChannelIdsJson;
+};
+
+/// Releases both buffers of `result` on every path, including a failed copy.
+RestoreOutcome takeRestoreResult(DeRecProtocolRestoreResult& result);
+
 /// Resolve the `(category, code)` name pair from the crate's accessors.
 std::pair<std::string, std::string> errorName(int32_t category, int32_t code);
 
+// Decoders for the payloads Rust hands the store callbacks.
+// They hold no `jsi` state, so the standalone test harness exercises them
+// against the real crate.
+
+/// Parse a bare `[n, n, ...]` array of unsigned decimal integers.
+std::vector<uint64_t> parseUnsignedJsonArray(const uint8_t* ptr, size_t len);
+
+/// The `bytes` field of a `{"kind":<n>,"bytes":[<n>,...]}` `SecretValueRecord`.
+std::vector<uint8_t> decodeSecretValueBytes(const uint8_t* ptr, size_t len);
+
+/// A `ShareRecord` as `ShareStore.save` receives it. `secretId` is the
+/// record's own `secret_id`, kept as the decimal string Rust wrote.
+struct DecodedShare {
+  std::string secretId;
+  uint32_t version;
+  std::vector<uint8_t> bytes;
+};
+
+/// Decode `{"secret_id":"...","version":<n>,"bytes":[<n>,...]}`. Empty when
+/// any of the three fields is absent.
+std::optional<DecodedShare> decodeShareRecord(const uint8_t* ptr, size_t len);
+
 }  // namespace derec

package/cpp/DeRecInstaller.cpp

@@ -157,18 +157,6 @@ void install(jsi::Runtime& rt, std::shared_ptr<Invoker> invoker) {
 
   auto host = jsi::Object(rt);
 
-  host.setProperty(
-      rt, "version",
-      jsi::Function::createFromHostFunction(
-          rt, jsi::PropNameID::forAscii(rt, "version"), 0,
-          [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value*, size_t)
-              -> jsi::Value {
-            DeRecProtocolVersion version = derec_protocol_version();
-            std::string text = std::to_string(version.major) + "." +
-                               std::to_string(version.minor);
-            return jsi::String::createFromUtf8(rt, text);
-          }));
-
   installPrimitives(rt, host);
 
   host.setProperty(

package/cpp/Primitives.cpp

@@ -14,6 +14,19 @@ using namespace facebook;
 namespace derec {
 
 void throwDeRecError(jsi::Runtime& rt, const DeRecError& error) {
+  throwDeRecError(rt, error, {});
+}
+
+void throwDeRecError(jsi::Runtime& rt,
+                     const DeRecError& error,
+                     const std::vector<uint8_t>& conflictingChannelIdsJson) {
+  throwDeRecError(rt, error, conflictingChannelIdsJson, {});
+}
+
+void throwDeRecError(jsi::Runtime& rt,
+                     const DeRecError& error,
+                     const std::vector<uint8_t>& conflictingChannelIdsJson,
+                     const ProcessFailureDetails& process) {
   auto names = errorName(error.category, error.code);
   // `message` and `peer_memo` are Rust-owned strings; copy before releasing.
   std::string message =
@@ -42,6 +55,20 @@ void throwDeRecError(jsi::Runtime& rt, const DeRecError& error) {
     payload.setProperty(rt, "expected", jsi::Value(static_cast<int>(expected)));
     payload.setProperty(rt, "got", jsi::Value(static_cast<int>(got)));
   }
+  if (!conflictingChannelIdsJson.empty()) {
+    payload.setProperty(rt, "channel_ids",
+                        jsi::Value::createFromJsonUtf8(rt, conflictingChannelIdsJson.data(),
+                                                       conflictingChannelIdsJson.size()));
+  }
+  if (process.hasChannelId) {
+    payload.setProperty(rt, "channel_id",
+                        jsi::String::createFromUtf8(rt, std::to_string(process.channelId)));
+  }
+  if (!process.eventsJson.empty()) {
+    payload.setProperty(rt, "events",
+                        jsi::Value::createFromJsonUtf8(rt, process.eventsJson.data(),
+                                                       process.eventsJson.size()));
+  }
   throw jsi::JSError(rt, jsi::Value(rt, payload));
 }
 
@@ -74,6 +101,22 @@ jsi::Value toArrayBuffer(jsi::Runtime& rt, const uint8_t* bytes, size_t len) {
   return jsi::Value(rt, result);
 }
 
+/// Build a genuine `Uint8Array` (not a bare `ArrayBuffer`) — every store
+/// interface types its byte payloads as `Uint8Array`, and application code
+/// is entitled to index or slice it directly.
+jsi::Value toUint8ArrayVal(jsi::Runtime& rt, const uint8_t* bytes, size_t len) {
+  jsi::Uint8Array arr(rt, len);
+  if (len > 0 && bytes != nullptr) {
+    jsi::ArrayBuffer buffer = arr.buffer(rt);
+    std::memcpy(buffer.data(rt), bytes, len);
+  }
+  return jsi::Value(rt, std::move(arr));
+}
+
+jsi::Value toUint8ArrayVal(jsi::Runtime& rt, const std::vector<uint8_t>& bytes) {
+  return toUint8ArrayVal(rt, bytes.data(), bytes.size());
+}
+
 uint64_t asU64(jsi::Runtime& rt, const jsi::Value& value) {
   if (value.isBigInt()) {
     return value.asBigInt(rt).asUint64(rt);
@@ -262,6 +305,28 @@ jsi::Value readTraceId(jsi::Runtime& rt,
   return jsi::Value(rt, jsi::BigInt::fromUint64(rt, result.trace_id));
 }
 
+/// `version() -> { major: number, minor: number }` — the protocol version the
+/// core writes into every envelope it produces.
+jsi::Value protocolVersion(jsi::Runtime& rt,
+                           const jsi::Value&,
+                           const jsi::Value*,
+                           size_t) {
+  DeRecProtocolVersion version = derec_protocol_version();
+  auto payload = jsi::Object(rt);
+  payload.setProperty(rt, "major", jsi::Value(static_cast<double>(version.major)));
+  payload.setProperty(rt, "minor", jsi::Value(static_cast<double>(version.minor)));
+  return jsi::Value(rt, payload);
+}
+
+/// `generate_replica_id() -> bigint` — a fresh replica identity from the
+/// core, never `0`. The application persists it once per device.
+jsi::Value generateReplicaId(jsi::Runtime& rt,
+                             const jsi::Value&,
+                             const jsi::Value*,
+                             size_t) {
+  return jsi::Value(rt, jsi::BigInt::fromUint64(rt, derec_generate_replica_id()));
+}
+
 /// `create_contact_message(channelId: bigint, contactMode: number,
 ///   transportProtocols: ArrayBuffer, hasNonce: number, nonce: bigint)
 ///   -> { contact_wire_bytes, secret_key_material }`
@@ -291,21 +356,6 @@ jsi::Value createContactMessage(jsi::Runtime& rt,
   return jsi::Value(rt, payload);
 }
 
-/// `validate_contact_message(contactMessage: ArrayBuffer) -> undefined`
-jsi::Value validateContactMessage(jsi::Runtime& rt,
-                                  const jsi::Value&,
-                                  const jsi::Value* args,
-                                  size_t count) {
-  requireArgs(rt, "validate_contact_message", count, 1);
-  ByteView contactMessage = asBytes(rt, args[0]);
-  DeRecError error =
-      validate_contact_message(contactMessage.ptr, contactMessage.len);
-  if (error.code != 0) {
-    throwDeRecError(rt, error);
-  }
-  return jsi::Value::undefined();
-}
-
 /// `encode_contact_message(contactJson: ArrayBuffer) -> ArrayBuffer`
 jsi::Value encodeContactMessage(jsi::Runtime& rt,
                                 const jsi::Value&,
@@ -338,6 +388,20 @@ jsi::Value decodeContactMessage(jsi::Runtime& rt,
   return toArrayBuffer(rt, bytes.data(), bytes.size());
 }
 
+/// `transport_protocol_discriminant(name: string) -> number`
+///
+/// The `derec_proto::Protocol` discriminant the crate assigns to `name`, or
+/// `-1` when it names none; forwarded unchanged for Rust to validate.
+jsi::Value transportProtocolDiscriminant(jsi::Runtime& rt,
+                                         const jsi::Value&,
+                                         const jsi::Value* args,
+                                         size_t count) {
+  requireArgs(rt, "transport_protocol_discriminant", count, 1);
+  std::string name = args[0].asString(rt).utf8(rt);
+  return jsi::Value(static_cast<int>(derec_transport_protocol_discriminant(
+      reinterpret_cast<const uint8_t*>(name.data()), name.size())));
+}
+
 /// `decode_message_json(kind: number, protoBytes: ArrayBuffer) -> ArrayBuffer`
 ///
 /// Turns the opaque `*_proto_bytes` an `extract_*` call returns into the JSON
@@ -415,17 +479,19 @@ jsi::Value producePairRequestMessage(jsi::Runtime& rt,
   return jsi::Value(rt, payload);
 }
 
-/// `extract_pair_request(request: ArrayBuffer, secretKeyMaterial: ArrayBuffer)
-///   -> { channel_id, request_proto_bytes }`
+/// `extract_pair_request(request: ArrayBuffer, secretKeyMaterial: ArrayBuffer,
+///   parameterRange: ArrayBuffer|null) -> { channel_id, request_proto_bytes }`
 jsi::Value extractPairRequest(jsi::Runtime& rt,
                               const jsi::Value&,
                               const jsi::Value* args,
                               size_t count) {
-  requireArgs(rt, "extract_pair_request", count, 2);
+  requireArgs(rt, "extract_pair_request", count, 3);
   ByteView request = asBytes(rt, args[0]);
   ByteView secretKeyMaterial = asBytes(rt, args[1]);
+  ByteView parameterRange = asBytes(rt, args[2]);
   ExtractPairRequestResult result = extract_pair_request(
-      request.ptr, request.len, secretKeyMaterial.ptr, secretKeyMaterial.len);
+      request.ptr, request.len, secretKeyMaterial.ptr, secretKeyMaterial.len,
+      parameterRange.ptr, parameterRange.len);
   if (result.error.code != 0) {
     throwDeRecError(rt, result.error);
   }
@@ -506,19 +572,21 @@ jsi::Value extractPairResponse(jsi::Runtime& rt,
 }
 
 /// `process_pair_response_message(contactMessage: ArrayBuffer, responseProto:
-///   ArrayBuffer, secretKeyMaterial: ArrayBuffer) -> { shared_key,
-///   channel_id }`
+///   ArrayBuffer, secretKeyMaterial: ArrayBuffer, parameterRange:
+///   ArrayBuffer|null) -> { shared_key, channel_id }`
 jsi::Value processPairResponseMessage(jsi::Runtime& rt,
                                       const jsi::Value&,
                                       const jsi::Value* args,
                                       size_t count) {
-  requireArgs(rt, "process_pair_response_message", count, 3);
+  requireArgs(rt, "process_pair_response_message", count, 4);
   ByteView contactMessage = asBytes(rt, args[0]);
   ByteView responseProto = asBytes(rt, args[1]);
   ByteView secretKeyMaterial = asBytes(rt, args[2]);
+  ByteView parameterRange = asBytes(rt, args[3]);
   ProcessPairResponseMessageResult result = process_pair_response_message(
       contactMessage.ptr, contactMessage.len, responseProto.ptr,
-      responseProto.len, secretKeyMaterial.ptr, secretKeyMaterial.len);
+      responseProto.len, secretKeyMaterial.ptr, secretKeyMaterial.len,
+      parameterRange.ptr, parameterRange.len);
   if (result.error.code != 0) {
     throwDeRecError(rt, result.error);
   }
@@ -645,6 +713,79 @@ jsi::Value processPrePairResponseMessage(jsi::Runtime& rt,
   return jsi::Value(rt, payload);
 }
 
+/// `produce_pre_pair_no_keys_response_message(channelId: bigint,
+///   requestProto: ArrayBuffer) -> { envelope_wire_bytes,
+///   secret_key_material }`
+jsi::Value producePrePairNoKeysResponseMessage(jsi::Runtime& rt,
+                                               const jsi::Value&,
+                                               const jsi::Value* args,
+                                               size_t count) {
+  requireArgs(rt, "produce_pre_pair_no_keys_response_message", count, 2);
+  uint64_t channelId = asU64(rt, args[0]);
+  ByteView requestProto = asBytes(rt, args[1]);
+  ProducePrePairNoKeysResponseMessageResult result =
+      produce_pre_pair_no_keys_response_message(channelId, requestProto.ptr,
+                                                requestProto.len);
+  if (result.error.code != 0) {
+    throwDeRecError(rt, result.error);
+  }
+  std::vector<uint8_t> envelope = takeBuffer(result.envelope_wire_bytes);
+  std::vector<uint8_t> secretKeyMaterial = takeBuffer(result.secret_key_material);
+  auto payload = jsi::Object(rt);
+  payload.setProperty(rt, "envelope_wire_bytes",
+                      toArrayBuffer(rt, envelope.data(), envelope.size()));
+  payload.setProperty(
+      rt, "secret_key_material",
+      toArrayBuffer(rt, secretKeyMaterial.data(), secretKeyMaterial.size()));
+  return jsi::Value(rt, payload);
+}
+
+/// `process_pre_pair_no_keys_response_message(contactMessage: ArrayBuffer,
+///   responseProto: ArrayBuffer) -> { mlkem_encapsulation_key,
+///   ecies_public_key, nonce }`
+jsi::Value processPrePairNoKeysResponseMessage(jsi::Runtime& rt,
+                                               const jsi::Value&,
+                                               const jsi::Value* args,
+                                               size_t count) {
+  requireArgs(rt, "process_pre_pair_no_keys_response_message", count, 2);
+  ByteView contactMessage = asBytes(rt, args[0]);
+  ByteView responseProto = asBytes(rt, args[1]);
+  ProcessPrePairResponseMessageResult result =
+      process_pre_pair_no_keys_response_message(contactMessage.ptr,
+                                                contactMessage.len,
+                                                responseProto.ptr,
+                                                responseProto.len);
+  if (result.error.code != 0) {
+    throwDeRecError(rt, result.error);
+  }
+  std::vector<uint8_t> mlkemKey = takeBuffer(result.mlkem_encapsulation_key);
+  std::vector<uint8_t> eciesKey = takeBuffer(result.ecies_public_key);
+  auto payload = jsi::Object(rt);
+  payload.setProperty(rt, "mlkem_encapsulation_key",
+                      toArrayBuffer(rt, mlkemKey.data(), mlkemKey.size()));
+  payload.setProperty(rt, "ecies_public_key",
+                      toArrayBuffer(rt, eciesKey.data(), eciesKey.size()));
+  payload.setProperty(rt, "nonce",
+                      jsi::Value(rt, jsi::BigInt::fromUint64(rt, result.nonce)));
+  return jsi::Value(rt, payload);
+}
+
+/// `pairing_fingerprint(sharedKey: ArrayBuffer) -> string`
+jsi::Value pairingFingerprint(jsi::Runtime& rt,
+                              const jsi::Value&,
+                              const jsi::Value* args,
+                              size_t count) {
+  requireArgs(rt, "pairing_fingerprint", count, 1);
+  ByteView sharedKey = asBytes(rt, args[0]);
+  PairingFingerprintResult result =
+      pairing_fingerprint(sharedKey.ptr, sharedKey.len);
+  if (result.error.code != 0) {
+    throwDeRecError(rt, result.error);
+  }
+  std::string fingerprint = takeString(result.fingerprint);
+  return jsi::String::createFromUtf8(rt, fingerprint);
+}
+
 /// `produce_get_share_request_message(channelId: bigint, secretId: bigint,
 ///   version: number, sharedKey: ArrayBuffer, replyTo: ArrayBuffer|null)
 ///   -> ArrayBuffer`
@@ -1134,6 +1275,8 @@ void bind(jsi::Runtime& rt,
 }  // namespace
 
 void installPrimitives(jsi::Runtime& rt, jsi::Object& host) {
+  bind(rt, host, "version", 0, protocolVersion);
+  bind(rt, host, "generate_replica_id", 0, generateReplicaId);
   bind(rt, host, "produce_get_secret_ids_versions_request_message", 3,
        produceGetSecretIdsVersionsRequestMessage);
   bind(rt, host, "extract_get_secret_ids_versions_request", 2,
@@ -1147,16 +1290,17 @@ void installPrimitives(jsi::Runtime& rt, jsi::Object& host) {
   bind(rt, host, "apply_trace_id_to_envelope", 2, applyTraceId);
   bind(rt, host, "read_trace_id_from_envelope", 1, readTraceId);
   bind(rt, host, "create_contact_message", 5, createContactMessage);
-  bind(rt, host, "validate_contact_message", 1, validateContactMessage);
   bind(rt, host, "encode_contact_message", 1, encodeContactMessage);
   bind(rt, host, "decode_contact_message", 1, decodeContactMessage);
+  bind(rt, host, "transport_protocol_discriminant", 1,
+       transportProtocolDiscriminant);
   bind(rt, host, "decode_message_json", 2, decodeMessageJson);
   bind(rt, host, "encode_message_json", 2, encodeMessageJson);
   bind(rt, host, "produce_pair_request_message", 5, producePairRequestMessage);
-  bind(rt, host, "extract_pair_request", 2, extractPairRequest);
+  bind(rt, host, "extract_pair_request", 3, extractPairRequest);
   bind(rt, host, "produce_pair_response_message", 7, producePairResponseMessage);
   bind(rt, host, "extract_pair_response", 2, extractPairResponse);
-  bind(rt, host, "process_pair_response_message", 3, processPairResponseMessage);
+  bind(rt, host, "process_pair_response_message", 4, processPairResponseMessage);
   bind(rt, host, "produce_pre_pair_request_message", 2,
        producePrePairRequestMessage);
   bind(rt, host, "extract_pre_pair_request", 1, extractPrePairRequest);
@@ -1165,6 +1309,11 @@ void installPrimitives(jsi::Runtime& rt, jsi::Object& host) {
   bind(rt, host, "extract_pre_pair_response", 1, extractPrePairResponse);
   bind(rt, host, "process_pre_pair_response_message", 2,
        processPrePairResponseMessage);
+  bind(rt, host, "produce_pre_pair_no_keys_response_message", 2,
+       producePrePairNoKeysResponseMessage);
+  bind(rt, host, "process_pre_pair_no_keys_response_message", 2,
+       processPrePairNoKeysResponseMessage);
+  bind(rt, host, "pairing_fingerprint", 1, pairingFingerprint);
   bind(rt, host, "produce_get_share_request_message", 5,
        produceGetShareRequestMessage);
   bind(rt, host, "extract_get_share_request", 2, extractGetShareRequest);

package/cpp/Primitives.h

@@ -5,6 +5,9 @@
 
 #include <jsi/jsi.h>
 
+#include <cstdint>
+#include <vector>
+
 extern "C" {
 #include "derec_ffi.h"
 }
@@ -16,6 +19,29 @@ namespace derec {
 /// application error handling ports between the JavaScript SDKs unchanged.
 [[noreturn]] void throwDeRecError(facebook::jsi::Runtime& rt, const DeRecError& error);
 
+/// As above, additionally attaching `channel_ids` — the JSON array of
+/// decimal-string ids in `conflictingChannelIdsJson`, verbatim — when that
+/// buffer is non-empty. Only `restore` produces one.
+[[noreturn]] void throwDeRecError(facebook::jsi::Runtime& rt,
+                                  const DeRecError& error,
+                                  const std::vector<uint8_t>& conflictingChannelIdsJson);
+
+/// What a failed `derec_protocol_process` adds to its error: the events it
+/// produced before failing, and the channel the failing message came from.
+struct ProcessFailureDetails {
+  std::vector<uint8_t> eventsJson;
+  bool hasChannelId = false;
+  uint64_t channelId = 0;
+};
+
+/// As above, additionally attaching `channel_id` (a decimal string) when
+/// `process.hasChannelId` is set, and `events` (the JSON array verbatim)
+/// when `process.eventsJson` is non-empty. Only `process` produces these.
+[[noreturn]] void throwDeRecError(facebook::jsi::Runtime& rt,
+                                  const DeRecError& error,
+                                  const std::vector<uint8_t>& conflictingChannelIdsJson,
+                                  const ProcessFailureDetails& process);
+
 /// Read an `ArrayBuffer` or typed-array argument as a byte range.
 /// Returns `{nullptr, 0}` for `null`/`undefined`.
 struct ByteView {
@@ -30,6 +56,13 @@ facebook::jsi::Value toArrayBuffer(facebook::jsi::Runtime& rt,
                                     size_t len);
 
 /// Read a `bigint` or `number` argument as a `uint64_t`.
+/// A genuine `Uint8Array` holding a copy of `bytes`.
+facebook::jsi::Value toUint8ArrayVal(facebook::jsi::Runtime& rt,
+                                     const uint8_t* bytes,
+                                     size_t len);
+facebook::jsi::Value toUint8ArrayVal(facebook::jsi::Runtime& rt,
+                                     const std::vector<uint8_t>& bytes);
+
 uint64_t asU64(facebook::jsi::Runtime& rt, const facebook::jsi::Value& value);
 
 /// Install every stateless FFI primitive as a host function on `host`, named