@derec-alliance/react-native 0.0.5 → 0.0.7

package/lib/protocol.js

@@ -3,7 +3,6 @@
 // Copyright (c) 2026 DeRec Alliance. All rights reserved.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeRecProtocol = exports.DeRecProtocolBuilder = void 0;
-exports.protocolDiscriminant = protocolDiscriminant;
 exports.buildProtectSecretParams = buildProtectSecretParams;
 exports.buildRestoreParams = buildRestoreParams;
 const codec_1 = require("./codec");
@@ -50,24 +49,6 @@ function reviveEventBytes(value) {
 function decodeEvents(buffer) {
     return reviveEventBytes((0, codec_1.jsonFromBytes)(buffer));
 }
-/**
- * Maps a transport protocol name to the `derec_proto::Protocol` discriminant.
- * The shared enum fixture every other numeric mapping in this SDK is checked
- * 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 `HTTPS = 0` and `GRPC = 1` are defined.
- */
-function protocolDiscriminant(protocol) {
-    switch (protocol.toLowerCase()) {
-        case 'https':
-            return 0;
-        case 'grpc':
-            return 1;
-        default:
-            throw new Error(`DeRec: unknown transport protocol "${protocol}"`);
-    }
-}
 function encodeTarget(target) {
     if (target === null) {
         return null;
@@ -219,14 +200,8 @@ function buildStartParams(flowKind, params) {
             if (p.communication_info !== undefined) {
                 out.communication_info = p.communication_info;
             }
-            if (p.own_transports !== undefined && p.own_transports.length > 0) {
+            if (p.own_transports !== undefined) {
                 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 (0, codec_1.jsonToBytes)(out);
         }
@@ -259,9 +234,9 @@ function toBigInt(id) {
  *
  * Every value the caller supplies is forwarded verbatim — defaults, clamping
  * and the meaning of a disabled cleanup policy are library decisions.
- * `threshold`, `keep_versions_count`, `auto_respond_on_failure`,
- * `unpair_ack`, `auto_reply_to` and `auto_accept` are omitted entirely from
- * the emitted config unless their setter was called: `ProtocolConfig` has a
+ * `threshold`, `auto_respond_on_failure`, `unpair_ack`, `auto_reply_to`
+ * and `auto_accept` are omitted entirely from the emitted config unless
+ * their setter was called: `ProtocolConfig` has a
  * `#[serde(default = "...")]` on each of them, reading the same constants
  * `DeRecProtocolBuilder::new` uses, so an absent key resolves to the
  * library's own default rather than one frozen into this shim.
@@ -296,22 +271,10 @@ class DeRecProtocolBuilder {
         this.stores.transport = transport;
         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) {
-        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`.
+     * order. Written to the config's `own_transports` array — 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
@@ -320,15 +283,11 @@ class DeRecProtocolBuilder {
      * 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.
+     * Required: `build()` with no own transport is refused by the library,
+     * since a node with no endpoint cannot be reached by any peer.
      */
     withOwnTransports(transports) {
-        this.config.own_transports = transports.map((t) => ({
-            uri: t.uri,
-            protocol: protocolDiscriminant(t.protocol),
-        }));
+        this.config.own_transports = transports.map(({ uri, protocol }) => ({ uri, protocol }));
         return this;
     }
     /** Default: 3. */
@@ -336,11 +295,6 @@ class DeRecProtocolBuilder {
         this.config.threshold = threshold;
         return this;
     }
-    /** Default: 3. */
-    withKeepVersionsCount(count) {
-        this.config.keep_versions_count = count;
-        return this;
-    }
     /**
      * Every field is optional; not calling this at all leaves all four at the
      * library's defaults — `timeouts` is genuinely absent from the JSON in
@@ -352,47 +306,20 @@ class DeRecProtocolBuilder {
         this.config.timeouts = { ...timeouts };
         return this;
     }
-    /**
-     * @deprecated Use {@link withUnsafeConnection}, which names both gated
-     * schemes. Removed at 0.0.5. Default: false.
-     */
-    withUnsafeHttp(allow) {
-        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.
+     * **Development only.** Default: false.
      */
     withUnsafeConnection(allow) {
         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
-     * no encoder for that message — the C ABI exposes one only for
-     * `ContactMessage`. Hand-rolling one here would be SDK-side protocol logic
-     * with no test coverage — exactly what this codebase's "Rust decides, the
-     * SDK only marshals" rule forbids. Instead,
-     * `build()` constructs the protocol with an empty `communication_info`
-     * (a legitimate, always-accepted value — see `decode_communication_info`
-     * in `library/src/interop/ffi/protocol/handle/mod.rs`, which treats a zero-length
-     * buffer as "no entries") and then calls the already-bound
-     * {@link DeRecProtocol.setCommunicationInfo}, which takes the same map as
-     * plain JSON (`derec_protocol_set_communication_info` in
-     * `library/src/interop/ffi/protocol/handle/config.rs`). That setter is queued on
-     * the protocol's serial worker before `build()` returns, so it is ordered
-     * ahead of every call the caller can subsequently make.
+     * Default: empty. Written to the config's `communication_info` key, so the
+     * map is part of the protocol from construction.
      */
     withCommunicationInfo(info) {
-        this.communicationInfo = info;
+        this.config.communication_info = info;
         return this;
     }
     /** Default: false. */
@@ -402,15 +329,7 @@ class DeRecProtocolBuilder {
     }
     /** Default: "required". */
     withUnpairAck(ack) {
-        if (ack === 'required') {
-            this.config.unpair_ack = 0;
-        }
-        else if (ack === 'not_required') {
-            this.config.unpair_ack = 1;
-        }
-        else {
-            throw new Error(`DeRec: unknown unpair ack "${ack}"`);
-        }
+        this.config.unpair_ack = ack;
         return this;
     }
     /** Default: false. */
@@ -418,17 +337,20 @@ class DeRecProtocolBuilder {
         this.config.auto_reply_to = enabled;
         return this;
     }
-    /** Default: empty policy (every flow off). */
+    /**
+     * Default: empty policy (every flow off). A flow left out of `policy` is
+     * left out of the config, and the library applies its own default to it.
+     */
     withAutoAccept(policy) {
         this.config.auto_accept = {
-            pairing: policy.pairing ?? false,
-            pre_pair: policy.prePair ?? false,
-            store_share: policy.storeShare ?? false,
-            verify_share: policy.verifyShare ?? false,
-            discovery: policy.discovery ?? false,
-            get_share: policy.getShare ?? false,
-            unpair: policy.unpair ?? false,
-            update_channel_info: policy.updateChannelInfo ?? false,
+            pairing: policy.pairing,
+            pre_pair: policy.prePair,
+            store_share: policy.storeShare,
+            verify_share: policy.verifyShare,
+            discovery: policy.discovery,
+            get_share: policy.getShare,
+            unpair: policy.unpair,
+            update_channel_info: policy.updateChannelInfo,
         };
         return this;
     }
@@ -444,22 +366,24 @@ class DeRecProtocolBuilder {
      * 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".
+     * Bounds cross to the library as decimal strings, so the full `i64` range
+     * survives; a bound left out is left out of the config, and the library
+     * applies its default.
      *
      * Default: unset — no constraints advertised, every peer range accepted.
      */
     withParameterRange(range) {
-        const n = (v) => 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),
+            min_share_size: range.min_share_size?.toString(),
+            max_share_size: range.max_share_size?.toString(),
+            min_time_between_verifications: range.min_time_between_verifications?.toString(),
+            max_time_between_verifications: range.max_time_between_verifications?.toString(),
+            min_time_between_share_updates: range.min_time_between_share_updates?.toString(),
+            max_time_between_share_updates: range.max_time_between_share_updates?.toString(),
+            min_unresponsive_deletion_timeout: range.min_unresponsive_deletion_timeout?.toString(),
+            max_unresponsive_deletion_timeout: range.max_unresponsive_deletion_timeout?.toString(),
+            min_unresponsive_deactivation_timeout: range.min_unresponsive_deactivation_timeout?.toString(),
+            max_unresponsive_deactivation_timeout: range.max_unresponsive_deactivation_timeout?.toString(),
         };
         return this;
     }
@@ -467,34 +391,18 @@ class DeRecProtocolBuilder {
         const config = {
             secret_id: this.secretIdValue.toString(),
             replica_id: null,
-            own_transport_uri: '',
-            own_transport_protocol: 0,
             ...this.config,
         };
         const host = (0, native_1.getNative)().protocol_new(JSON.stringify(config), new Uint8Array(0), this.stores);
-        const protocol = DeRecProtocol.fromHost(host);
-        if (this.communicationInfo !== undefined) {
-            // `setCommunicationInfo` is asynchronous, but `build()` stays
-            // synchronous: the guarantee callers need is not that the map has been
-            // applied by the time `build()` returns, it is that no flow can run
-            // before it. Posting it here puts it on the protocol's serial worker
-            // queue ahead of anything the caller has had the chance to start, so
-            // every subsequent call observes it. Left unhandled deliberately — a
-            // failure reaches the runtime's unhandled-rejection reporting rather
-            // than being silently discarded, and `build()` has no synchronous
-            // channel to raise it on.
-            void protocol.setCommunicationInfo(this.communicationInfo);
-        }
-        return protocol;
+        return DeRecProtocol.fromHost(host);
     }
 }
 exports.DeRecProtocolBuilder = DeRecProtocolBuilder;
 /**
  * Thin wrapper around the `ProtocolHost` JSI host object, mirroring
  * `@derec-alliance/nodejs`'s `DeRecProtocol` — same methods, and the same
- * sync/async split except for `setCommunicationInfo` and `setOwnTransport`,
- * which return a `Promise` here (see their own doc comments for why);
- * `secretId` is synchronous and everything else returns a `Promise`. Every method encodes its
+ * sync/async split: `secretId` is synchronous and everything else returns a
+ * `Promise`. Every method encodes its
  * arguments into the wire shape the host function expects and decodes its
  * result back into the typed value declared here; no protocol decision is
  * made in this class.
@@ -519,60 +427,37 @@ class DeRecProtocol {
         return this.host.secretId();
     }
     /**
-     * Returns a `Promise`, where `@derec-alliance/nodejs` declares this
-     * `void`. The native setter takes the same handle mutex a running flow
-     * holds across its store callbacks, so calling it on the JavaScript thread
-     * would block that thread until the flow released the mutex — which it
-     * cannot do while it is waiting on the JavaScript thread. The binding
-     * therefore queues the setter onto the same serial worker every flow runs
-     * on, which orders it after any call already in flight. The nodejs SDK is
-     * WASM and single-threaded, so it has no such hazard.
+     * Replaces this node's local communication info.
      *
-     * Callers that ignore the result behave exactly as before, so this stays
-     * source-compatible with nodejs-shaped code; awaiting it additionally
-     * surfaces a failure that would otherwise be swallowed.
+     * The native setter takes the same handle mutex a running flow holds
+     * across its store callbacks, so calling it on the JavaScript thread would
+     * block that thread until the flow released the mutex — which it cannot do
+     * while it is waiting on the JavaScript thread. The binding therefore
+     * queues the setter onto the same serial worker every flow runs on, which
+     * orders it after any call already in flight. Awaiting the returned
+     * `Promise` surfaces a failure that would otherwise be swallowed.
      */
     setCommunicationInfo(info) {
         return this.host.setCommunicationInfo((0, codec_1.jsonToBytes)(info));
     }
-    /**
-     * 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, protocol) {
-        return this.host.setOwnTransport(uri, protocolDiscriminant(protocol));
-    }
     /**
      * 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).
+     * the runtime counterpart to `withOwnTransports`.
      *
      * 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.
+     * Queued onto the serial worker for the same reason as
+     * {@link setCommunicationInfo}.
      */
     setOwnTransports(transports) {
-        const wire = transports.map(({ uri, protocol }) => ({
-            uri,
-            protocol: protocolDiscriminant(protocol),
-        }));
+        const wire = transports.map(({ uri, protocol }) => ({ uri, protocol }));
         return this.host.setOwnTransports((0, codec_1.jsonToBytes)(wire));
     }
     /**
      * Decodes the `contact_wire_bytes` `derec_protocol_create_contact`
      * produces into a typed `ContactMessage`, so an application can read the
-     * contact's `nonce`, `transport_protocol` and mode without a protobuf
+     * contact's `nonce`, `supported_transports` and mode without a protobuf
      * codec of its own. Feed the returned object straight back into
      * `start(FlowKind.Pairing, { contact })`, which re-encodes it.
      */
@@ -588,7 +473,17 @@ class DeRecProtocol {
         return decodeEvents(buffer);
     }
     async process(message) {
-        const buffer = (await this.host.process(message));
+        let buffer;
+        try {
+            buffer = (await this.host.process(message));
+        }
+        catch (error) {
+            const failure = error;
+            if (Array.isArray(failure.events)) {
+                failure.events = reviveEventBytes(failure.events);
+            }
+            throw error;
+        }
         return decodeEvents(buffer);
     }
     async tick() {
@@ -605,6 +500,16 @@ class DeRecProtocol {
     async getFingerprint(channelId) {
         return (await this.host.getFingerprint(toBigInt(channelId)));
     }
+    /**
+     * Verify `fingerprint` against the channel's locally-derived one. On
+     * match, the channel transitions from `Pending` to `Paired`. Returns
+     * `true` on confirmation, `false` on mismatch.
+     *
+     * On a replica destination, confirming is also the decision to adopt the
+     * group's vault: the source's publish is then installed as it arrives,
+     * with no further prompt. Ask the user before calling this; to decline,
+     * never confirm.
+     */
     async verifyFingerprint(channelId, fingerprint) {
         return (await this.host.verifyFingerprint(toBigInt(channelId), fingerprint));
     }
@@ -612,6 +517,24 @@ class DeRecProtocol {
         const buffer = (await this.host.removeExpiredChannels(olderThanSecs));
         return (0, codec_1.jsonFromBytes)(buffer);
     }
+    /**
+     * Rebuild this protocol's `secret_id` namespace from a recovered `Secret`.
+     * Pass the `secret` carried by the `SecretRecovered` event verbatim.
+     * Recovery and restore are separate steps on purpose: `SecretRecovered`
+     * writes nothing. Show the user what was recovered, or ask them, before
+     * calling `restore`, which commits it to this device.
+     * A helper or member whose `transports` is empty gets no channel: it is
+     * reported as a `PeerNotRestored` event in the returned array and the rest
+     * of the roster is restored.
+     *
+     * Rejects with a `DeRecError`; among its codes:
+     *
+     * | code               | meaning                                                     |
+     * |--------------------|-------------------------------------------------------------|
+     * | `already_restored` | A user-secret snapshot already exists for this `secret_id`. |
+     * | `restore_conflict` | Channels live at ids restore is about to write. The error   |
+     * |                    | carries `channel_ids: string[]` listing the collisions.     |
+     */
     async restore(recoveredSecret, version) {
         const params = buildRestoreParams(recoveredSecret, version);
         const buffer = (await this.host.restore((0, codec_1.jsonToBytes)(params)));
@@ -621,5 +544,9 @@ class DeRecProtocol {
     free() {
         this.host.free();
     }
+    /** Same as {@link DeRecProtocol.free}, for `using`. */
+    [Symbol.dispose]() {
+        this.free();
+    }
 }
 exports.DeRecProtocol = DeRecProtocol;