@derec-alliance/react-native 0.0.2 → 0.0.4

package/lib/types.js

@@ -3,6 +3,113 @@
 // Copyright (c) 2026 DeRec Alliance. All rights reserved.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowKind = exports.ContactMode = exports.SenderKind = void 0;
+exports.channelFilterMatches = channelFilterMatches;
+exports.advertisedEndpoints = advertisedEndpoints;
+exports.sequentialFailover = sequentialFailover;
+exports.singleEndpointTransport = singleEndpointTransport;
+/**
+ * Whether a channel or member with these attributes survives `filter`.
+ *
+ * Every empty field means "do not restrict", `exclude` is applied after `ids`,
+ * and the restrictions combine with AND — the same contract the core states on
+ * `ChannelFilter`. A store whose backing cannot express the filter as a query
+ * can list and call this; that is correct but transfers the rows the filter
+ * exists to leave behind.
+ *
+ * `id` is a decimal string, as ids are everywhere on this bridge. `role` is the
+ * peer's `SenderKind` name for `listHelpers` and the member's `ReplicaRole`
+ * name for `listReplicas`.
+ */
+function channelFilterMatches(filter, id, status, role) {
+    if (!filter)
+        return true;
+    const ids = filter.ids ?? [];
+    const statuses = filter.status ?? [];
+    const exclude = filter.exclude ?? [];
+    if (ids.length > 0 && !ids.includes(id))
+        return false;
+    if (statuses.length > 0 && !statuses.includes(status))
+        return false;
+    if (filter.role != null && filter.role !== role)
+        return false;
+    return !exclude.includes(id);
+}
+/**
+ * The endpoints a peer-supplied message advertises, in the peer's own order.
+ *
+ * Yields `supported_transports` when it is non-empty, and otherwise the
+ * singular `transport_protocol` — which is how every implementation predating
+ * the offer list advertises, and the reason this is a function rather than a
+ * field read. Reading `transport_protocol` directly is a bug: its meaning
+ * narrowed to "one entry of a list, and possibly absent", so a peer that has
+ * moved past it looks unreachable to a reader that was correct before 0.0.3.
+ *
+ * Reports what was advertised, not what is acceptable — nothing here is
+ * validated, and the protocol still applies its own transport policy to
+ * whatever it records.
+ */
+function advertisedEndpoints(message) {
+    if (!message)
+        return [];
+    const offers = message.supported_transports ?? [];
+    if (offers.length > 0)
+        return offers;
+    return message.transport_protocol ? [message.transport_protocol] : [];
+}
+/**
+ * Builds a {@link Transport} that tries each endpoint in the order the peer
+ * offered it and stops at the first success.
+ *
+ * An error is thrown only when every endpoint failed. The message is delivered
+ * at most once.
+ *
+ * This is the right default. A peer advertising several endpoints is saying it
+ * can be reached at any of them, and the reason 0.0.3 records the whole list is
+ * so one being down does not end the conversation.
+ */
+function sequentialFailover(dialer) {
+    return {
+        async send(endpoints, message) {
+            let last;
+            for (const endpoint of endpoints) {
+                try {
+                    await dialer(endpoint, message);
+                    return;
+                }
+                catch (e) {
+                    last = e;
+                }
+            }
+            // `endpoints` is never empty — the library refuses to record a peer
+            // whose endpoints were all filtered away — so reaching here means at
+            // least one attempt was made and `last` is populated.
+            throw last ?? new Error('send was called with no endpoints');
+        },
+    };
+}
+/**
+ * Builds a {@link Transport} that uses the first endpoint only.
+ *
+ * Reproduces the pre-0.0.3 behaviour exactly, for an application that genuinely
+ * serves one endpoint or has a reason not to fail over.
+ *
+ * It exists so that choosing it is visible. `endpoints[0]` written inline looks
+ * like an implementation detail and reads as finished; naming this records that
+ * failover was considered and declined, which is a claim a reviewer can
+ * disagree with. If the peers this application talks to advertise more than one
+ * endpoint, prefer {@link sequentialFailover} — every endpoint after the first
+ * is reachability being thrown away.
+ */
+function singleEndpointTransport(dialer) {
+    return {
+        async send(endpoints, message) {
+            if (endpoints.length === 0) {
+                throw new Error('send was called with no endpoints');
+            }
+            await dialer(endpoints[0], message);
+        },
+    };
+}
 var SenderKind;
 (function (SenderKind) {
     SenderKind[SenderKind["Owner"] = 0] = "Owner";
@@ -54,10 +161,10 @@ var FlowKind;
     /** Ask the replica group whether this device is behind, and catch up if it
      *  is. Replica-only, and takes no parameters — the group and this device's
      *  own version both come from the stores. */
-    FlowKind[FlowKind["SyncCheck"] = 7] = "SyncCheck";
+    FlowKind[FlowKind["ReplicaDiscovery"] = 7] = "ReplicaDiscovery";
     /** Remove a member from the replica group. Replica-only. Naming this device
      *  is a voluntary departure; naming another is an eviction. Params:
      *  `{ replica_id: string; memo?: string }` — `replica_id` is a decimal
      *  string so ids above 2^53 survive JS number handling. */
-    FlowKind[FlowKind["RemoveReplica"] = 8] = "RemoveReplica";
+    FlowKind[FlowKind["UnpairReplica"] = 8] = "UnpairReplica";
 })(FlowKind || (exports.FlowKind = FlowKind = {}));

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@derec-alliance/react-native",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "React Native bindings for derec-library, the Rust SDK for the DeRec protocol.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/derecalliance/lib-derec"
   },
+  "homepage": "https://derec.org",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [

package/src/primitives.ts

@@ -86,11 +86,11 @@ function bytes(value: unknown): Uint8Array {
   return new Uint8Array(value as ArrayBuffer);
 }
 
-/** `null` and `undefined` both mean "no override" for every optional
- *  `TransportProtocol` argument; the C ABI reads a zero-length buffer as
- *  absent. */
-function replyTo(value: TransportProtocol | null | undefined): Uint8Array {
-  return encodeOptionalMessage(MessageKind.TransportProtocol, value);
+/** 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: TransportProtocol[] | undefined): Uint8Array {
+  return value && value.length > 0 ? encodeTransportList(value) : new Uint8Array(0);
 }
 
 /**
@@ -117,7 +117,7 @@ const discovery = {
     produce(
       channel_id: bigint,
       shared_key: Uint8Array,
-      reply_to?: TransportProtocol | null,
+      reply_to?: TransportProtocol[],
     ): ProduceResult {
       const envelope = call(
         'produce_get_secret_ids_versions_request_message',
@@ -188,12 +188,69 @@ 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: TransportProtocol[]): Uint8Array {
+  const entries = transports.map((t) =>
+    new Uint8Array(encodeMessage(MessageKind.TransportProtocol, t)),
+  );
+  const out: number[] = [];
+  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: Uint8Array | ArrayBuffer): TransportProtocol[] {
+  const buf = framed instanceof Uint8Array ? framed : new Uint8Array(framed);
+  const out: TransportProtocol[] = [];
+  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(
+      decodeMessage<TransportProtocol>(
+        MessageKind.TransportProtocol,
+        buf.subarray(i, i + len),
+      ),
+    );
+    i += len;
+  }
+  return out;
+}
+
 const pairing = {
   request: {
     create_contact(
       channel_id: bigint,
       contact_mode: ContactMode | number,
-      transport_protocol: TransportProtocol,
+      transport_protocols: TransportProtocol[],
     ): CreateContactResult {
       // The C entry point also accepts a caller-supplied nonce behind a
       // presence flag. `@derec-alliance/nodejs` has no such parameter, so the
@@ -203,7 +260,7 @@ const pairing = {
         'create_contact_message',
         channel_id,
         contact_mode,
-        encodeMessage(MessageKind.TransportProtocol, transport_protocol),
+        encodeTransportList(transport_protocols),
         0,
         0n,
       ) as { contact_wire_bytes: ArrayBuffer; secret_key_material: ArrayBuffer };
@@ -223,7 +280,7 @@ const pairing = {
 
     produce(
       kind: SenderKind,
-      transport_protocol: TransportProtocol,
+      transport_protocols: TransportProtocol[],
       contact_message: ContactMessage,
       communication_info: CommunicationInfo | null,
       parameter_range: ParameterRange | null,
@@ -231,7 +288,7 @@ const pairing = {
       const result = call(
         'produce_pair_request_message',
         kind,
-        encodeMessage(MessageKind.TransportProtocol, transport_protocol),
+        encodeTransportList(transport_protocols),
         encodeContact(contact_message),
         encodeOptionalMessage(MessageKind.CommunicationInfo, communication_info),
         encodeOptionalMessage(MessageKind.ParameterRange, parameter_range),
@@ -262,12 +319,12 @@ const pairing = {
     },
 
     produce_pre_pair(
-      transport_protocol: TransportProtocol,
+      own_transports: TransportProtocol[],
       contact_message: ContactMessage,
     ): ProducePrePairResult {
       const envelope = call(
         'produce_pre_pair_request_message',
-        encodeMessage(MessageKind.TransportProtocol, transport_protocol),
+        encodeTransportList(own_transports),
         encodeContact(contact_message),
       );
       return { envelope: bytes(envelope) };
@@ -293,6 +350,7 @@ const pairing = {
       secret_key: Uint8Array,
       communication_info: CommunicationInfo | null,
       parameter_range: ParameterRange | null,
+      unsafe_connection = false,
     ): PairingResponseProduceResult {
       const result = call(
         'produce_pair_response_message',
@@ -301,18 +359,16 @@ const pairing = {
         secret_key,
         encodeOptionalMessage(MessageKind.CommunicationInfo, communication_info),
         encodeOptionalMessage(MessageKind.ParameterRange, parameter_range),
+        unsafe_connection,
       ) as {
         response_wire_bytes: ArrayBuffer;
-        peer_transport_protocol: ArrayBuffer;
+        peer_transports: ArrayBuffer;
         shared_key: ArrayBuffer;
         channel_id: bigint;
       };
       return {
         envelope: bytes(result.response_wire_bytes),
-        peer_transport_protocol: decodeMessage<TransportProtocol>(
-          MessageKind.TransportProtocol,
-          result.peer_transport_protocol,
-        ),
+        peer_transports: decodeTransportList(result.peer_transports),
         shared_key: bytes(result.shared_key),
         channel_id: result.channel_id,
       };
@@ -402,7 +458,7 @@ const recovery = {
       secret_id: bigint,
       version: number,
       shared_key: Uint8Array,
-      reply_to?: TransportProtocol | null,
+      reply_to?: TransportProtocol[],
     ): ProduceResult {
       const envelope = call(
         'produce_get_share_request_message',
@@ -505,7 +561,7 @@ const sharing = {
       keep_list: number[],
       description: string,
       shared_key: Uint8Array,
-      reply_to?: TransportProtocol | null,
+      reply_to?: TransportProtocol[],
     ): ProduceResult {
       const envelope = call(
         'produce_store_share_request_message',
@@ -596,7 +652,7 @@ const unpairing = {
       channel_id: bigint,
       memo: string,
       shared_key: Uint8Array,
-      reply_to?: TransportProtocol | null,
+      reply_to?: TransportProtocol[],
     ): ProduceResult {
       const envelope = call(
         'produce_unpair_request_message',
@@ -668,7 +724,7 @@ const verification = {
       secret_id: bigint,
       version: number,
       shared_key: Uint8Array,
-      reply_to?: TransportProtocol | null,
+      reply_to?: TransportProtocol[],
     ): ProduceResult {
       const envelope = call(
         'produce_verify_share_request_message',

package/src/protocol.ts

@@ -13,13 +13,14 @@ import type {
   DeRecEvent,
   DiscoveryParams,
   PairingParams,
+  ParameterRange,
   ProtectSecretParams,
   RecoverSecretParams,
-  RemoveReplicaParams,
+  UnpairReplicaParams,
   SecretStore,
   ShareStore,
   StateStore,
-  SyncCheckParams,
+  ReplicaDiscoveryParams,
   Target,
   Timeouts,
   Transport,
@@ -86,12 +87,14 @@ function decodeEvents(buffer: ArrayBuffer): DeRecEvent[] {
  * 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 function protocolDiscriminant(protocol: string): number {
   switch (protocol.toLowerCase()) {
     case 'https':
       return 0;
+    case 'grpc':
+      return 1;
     default:
       throw new Error(`DeRec: unknown transport protocol "${protocol}"`);
   }
@@ -156,7 +159,7 @@ export function buildRestoreParams(
     helpers: recoveredSecret.helpers.map((helper) => {
       const out: Record<string, unknown> = {
         channel_id: helper.channel_id,
-        transport_uri: helper.transport_uri,
+        transports: helper.transports,
         shared_key: Array.from(helper.shared_key),
       };
       const info = communicationInfoOrOmit(helper.communication_info);
@@ -177,7 +180,7 @@ export function buildRestoreParams(
       members: recoveredSecret.replicas.members.map((member) => {
         const out: Record<string, unknown> = {
           replica_id: member.replica_id,
-          transport_uri: member.transport_uri,
+          transports: member.transports,
           role: member.role,
         };
         const info = communicationInfoOrOmit(member.communication_info);
@@ -258,17 +261,22 @@ function buildStartParams(flowKind: FlowKind, params: unknown): Uint8Array {
       if (p.communication_info !== undefined) {
         out.communication_info = p.communication_info;
       }
-      if (p.transport_protocol !== undefined) {
+      if (p.own_transports !== undefined && p.own_transports.length > 0) {
+        out.own_transports = p.own_transports;
+        // The first entry also fills the deprecated singular field so a peer
+        // predating `supported_transports` still learns the new address.
+        out.transport_protocol = p.own_transports[0];
+      } else if (p.transport_protocol !== undefined) {
         out.transport_protocol = p.transport_protocol;
       }
       return jsonToBytes(out);
     }
-    case FlowKind.SyncCheck:
+    case FlowKind.ReplicaDiscovery:
       // No parameters: the group and this device's own version both come
       // from the stores.
       return jsonToBytes({});
-    case FlowKind.RemoveReplica: {
-      const p = params as RemoveReplicaParams;
+    case FlowKind.UnpairReplica: {
+      const p = params as UnpairReplicaParams;
       const out: Record<string, unknown> = { replica_id: p.replica_id };
       if (p.memo !== undefined) {
         out.memo = p.memo;
@@ -341,12 +349,43 @@ export class DeRecProtocolBuilder {
     return 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 {
     this.config.own_transport_uri = endpoint.uri;
     this.config.own_transport_protocol = protocolDiscriminant(endpoint.protocol);
     return 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 {
+    this.config.own_transports = transports.map((t) => ({
+      uri: t.uri,
+      protocol: protocolDiscriminant(t.protocol),
+    }));
+    return this;
+  }
+
   /** Default: 3. */
   withThreshold(threshold: number): this {
     this.config.threshold = threshold;
@@ -371,12 +410,30 @@ export class DeRecProtocolBuilder {
     return this;
   }
 
-  /** Default: false. */
+  /**
+   * @deprecated Use {@link withUnsafeConnection}, which names both gated
+   * schemes. Removed at 0.0.5. Default: false.
+   */
   withUnsafeHttp(allow: boolean): this {
     this.config.unsafe_http = allow;
     return 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 {
+    this.config.unsafe_connection = allow;
+    return this;
+  }
+
   /**
    * Default: empty. `derec_protocol_new`'s own `communication_info` argument
    * is a pre-encoded `CommunicationInfo` protobuf message, and this SDK has
@@ -444,6 +501,41 @@ export class DeRecProtocolBuilder {
     return 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 {
+    const n = (v: bigint | undefined) => Number(v ?? 0n);
+    this.config.parameter_range = {
+      min_share_size: n(range.min_share_size),
+      max_share_size: n(range.max_share_size),
+      min_time_between_verifications: n(range.min_time_between_verifications),
+      max_time_between_verifications: n(range.max_time_between_verifications),
+      min_time_between_share_updates: n(range.min_time_between_share_updates),
+      max_time_between_share_updates: n(range.max_time_between_share_updates),
+      min_unresponsive_deletion_timeout: n(
+        range.min_unresponsive_deletion_timeout,
+      ),
+      max_unresponsive_deletion_timeout: n(
+        range.max_unresponsive_deletion_timeout,
+      ),
+      min_unresponsive_deactivation_timeout: n(
+        range.min_unresponsive_deactivation_timeout,
+      ),
+      max_unresponsive_deactivation_timeout: n(
+        range.max_unresponsive_deactivation_timeout,
+      ),
+    };
+    return this;
+  }
+
   build(): DeRecProtocol {
     const config = {
       secret_id: this.secretIdValue.toString(),
@@ -526,7 +618,19 @@ export class DeRecProtocol {
     return this.host.setCommunicationInfo(jsonToBytes(info)) as 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> {
     return this.host.setOwnTransport(
       uri,
@@ -534,6 +638,27 @@ export class DeRecProtocol {
     ) as 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> {
+    const wire = transports.map(({ uri, protocol }) => ({
+      uri,
+      protocol: protocolDiscriminant(protocol),
+    }));
+    return this.host.setOwnTransports(jsonToBytes(wire)) as Promise<void>;
+  }
+
   /**
    * Decodes the `contact_wire_bytes` `derec_protocol_create_contact`
    * produces into a typed `ContactMessage`, so an application can read the
@@ -565,8 +690,8 @@ export 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[]>;
   async start(flowKind: FlowKind, params?: unknown): Promise<DeRecEvent[]> {
     const paramsBytes = buildStartParams(flowKind, params);
     const buffer = (await this.host.start(flowKind, paramsBytes)) as ArrayBuffer;