@derec-alliance/react-native 0.0.5 → 0.0.6

package/lib/primitives.js

@@ -35,19 +35,16 @@ function replyTo(value) {
     return value && value.length > 0 ? encodeTransportList(value) : new Uint8Array(0);
 }
 /**
- * `ContactMessage` keeps its own dedicated codec rather than going through
- * the generic message codec: `encode_contact_message` /
- * `decode_contact_message` also enforce the mode/field invariant — an
- * `InlineKeys` contact must carry keys, a `HashedKeys` one must carry only
- * the commitment — so a malformed contact is rejected here rather than
- * travelling.
+ * Every contact crossing the native seam goes through the core's contact
+ * codec, which also refuses a contact that violates the invariants of its
+ * contact mode. Delegates to `pairing.request.encode_contact` /
+ * `decode_contact`, defined below.
  */
 function encodeContact(contact_message) {
-    return bytes(call('encode_contact_message', (0, codec_1.jsonToBytes)((0, messages_1.plainMessage)(contact_message))));
+    return pairing.request.encode_contact(contact_message);
 }
 function decodeContact(wire) {
-    const json = call('decode_contact_message', wire);
-    return (0, messages_1.reviveMessage)((0, codec_1.jsonFromBytes)(json));
+    return pairing.request.decode_contact(wire);
 }
 const discovery = {
     request: {
@@ -131,23 +128,31 @@ function decodeTransportList(framed) {
 }
 const pairing = {
     request: {
-        create_contact(channel_id, contact_mode, transport_protocols) {
-            // The C entry point also accepts a caller-supplied nonce behind a
-            // presence flag. `@derec-alliance/nodejs` has no such parameter, so the
-            // flag is 0 and the library generates one — the same behaviour, not a
-            // default invented here.
-            const result = call('create_contact_message', channel_id, contact_mode, encodeTransportList(transport_protocols), 0, 0n);
+        /** Creates an out-of-band `ContactMessage`. `nonce` omitted or `null`
+         *  lets the library draw a random one; `ContactMode.NoKeys` requires the
+         *  caller to supply it. */
+        create_contact(channel_id, contact_mode, transport_protocols, nonce) {
+            // The C entry point carries `Option<u64>` as a presence flag plus a
+            // value; an absent nonce clears the flag and the library draws one.
+            const result = call('create_contact_message', channel_id, contact_mode, encodeTransportList(transport_protocols), nonce == null ? 0 : 1, nonce ?? 0n);
             return {
                 contact_message: decodeContact(result.contact_wire_bytes),
                 secret_key: bytes(result.secret_key_material),
             };
         },
-        /** Proto-encodes a `ContactMessage`. Rejects a contact that violates the
-         *  mode/field invariant rather than serializing it. */
-        encode_contact: encodeContact,
-        /** Decodes proto `ContactMessage` bytes. Rejects a contact that violates
-         *  the mode/field invariant rather than returning it. */
-        decode_contact: decodeContact,
+        /** Serializes a `ContactMessage` to the bytes delivered out of band.
+         *  Refuses a contact that violates the invariants of its contact mode or
+         *  advertises no endpoint. */
+        encode_contact(contact_message) {
+            return bytes(call('encode_contact_message', (0, codec_1.jsonToBytes)((0, messages_1.plainMessage)(contact_message))));
+        },
+        /** Parses out-of-band contact bytes back into a `ContactMessage`.
+         *  Refuses bytes that are not a contact, or a contact that violates the
+         *  invariants of its contact mode. */
+        decode_contact(bytes) {
+            const json = call('decode_contact_message', bytes);
+            return (0, messages_1.reviveMessage)((0, codec_1.jsonFromBytes)(json));
+        },
         produce(kind, transport_protocols, contact_message, communication_info, parameter_range) {
             const result = call('produce_pair_request_message', kind, encodeTransportList(transport_protocols), encodeContact(contact_message), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.CommunicationInfo, communication_info), (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range));
             return {
@@ -156,8 +161,8 @@ const pairing = {
                 secret_key: bytes(result.secret_key_material),
             };
         },
-        extract(envelope_bytes, secret_key) {
-            const result = call('extract_pair_request', envelope_bytes, secret_key);
+        extract(envelope_bytes, secret_key, parameter_range) {
+            const result = call('extract_pair_request', envelope_bytes, secret_key, (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range));
             return {
                 request: (0, messages_1.decodeMessage)(messages_1.MessageKind.PairRequest, result.request_proto_bytes),
             };
@@ -189,8 +194,8 @@ const pairing = {
                 response: (0, messages_1.decodeMessage)(messages_1.MessageKind.PairResponse, result.response_proto_bytes),
             };
         },
-        process(contact_message, response, secret_key) {
-            const result = call('process_pair_response_message', encodeContact(contact_message), (0, messages_1.encodeMessage)(messages_1.MessageKind.PairResponse, response), secret_key);
+        process(contact_message, response, secret_key, parameter_range) {
+            const result = call('process_pair_response_message', encodeContact(contact_message), (0, messages_1.encodeMessage)(messages_1.MessageKind.PairResponse, response), secret_key, (0, messages_1.encodeOptionalMessage)(messages_1.MessageKind.ParameterRange, parameter_range));
             return { shared_key: bytes(result.shared_key), channel_id: result.channel_id };
         },
         produce_pre_pair(channel_id, request, secret_key) {
@@ -211,6 +216,24 @@ const pairing = {
                 nonce: result.nonce,
             };
         },
+        produce_pre_pair_no_keys(channel_id, request) {
+            const result = call('produce_pre_pair_no_keys_response_message', channel_id, (0, messages_1.encodeMessage)(messages_1.MessageKind.PrePairRequest, request));
+            return {
+                envelope: bytes(result.envelope_wire_bytes),
+                secret_key_material: bytes(result.secret_key_material),
+            };
+        },
+        process_pre_pair_no_keys(contact_message, response) {
+            const result = call('process_pre_pair_no_keys_response_message', encodeContact(contact_message), (0, messages_1.encodeMessage)(messages_1.MessageKind.PrePairResponse, response));
+            return {
+                mlkem_encapsulation_key: bytes(result.mlkem_encapsulation_key),
+                ecies_public_key: bytes(result.ecies_public_key),
+                nonce: result.nonce,
+            };
+        },
+    },
+    fingerprint(shared_key) {
+        return call('pairing_fingerprint', shared_key);
     },
 };
 const recovery = {

package/lib/protocol.d.ts

@@ -1,19 +1,10 @@
 import { FlowKind } from './types';
-import type { AutoAcceptPolicy, ChannelStore, ContactMessage, ContactMode, DeRecEvent, DiscoveryParams, PairingParams, ParameterRange, ProtectSecretParams, RecoverSecretParams, UnpairReplicaParams, SecretStore, ShareStore, StateStore, ReplicaDiscoveryParams, Timeouts, Transport, UnpairAck, UnpairParams, UpdateChannelInfoParams, UserSecretStore, VerifySharesParams } from './types';
+import type { AutoAcceptPolicy, ChannelStore, ContactMessage, ContactMode, DeRecEvent, Endpoint, DiscoveryParams, PairingParams, ParameterRange, ProtectSecretParams, RecoverSecretParams, UnpairReplicaParams, SecretStore, ShareStore, StateStore, StatusEnum, ReplicaDiscoveryParams, Timeouts, Transport, UnpairAck, UnpairParams, UpdateChannelInfoParams, UserSecretStore, VerifySharesParams } from './types';
 /** Shape of the `__DeRec` host object as seen from this file: every member is
  *  a plain callable, since the JSI layer exposes host functions this way and
  *  TypeScript has no static knowledge of them (see `primitives.ts`'s `call`
  *  helper, which uses the same escape hatch). */
 type NativeHost = Record<string, (...args: any[]) => any>;
-/**
- * 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.
- */
-export declare function protocolDiscriminant(protocol: string): number;
 /**
  * `ProtectSecretParamsJson` (`library/src/interop/ffi/protocol/flow.rs`): every
  * `UserSecret.id`/`.data` byte array travels as a bare JSON array of decimal
@@ -58,7 +49,6 @@ export declare class DeRecProtocolBuilder {
     private readonly secretIdValue;
     private config;
     private stores;
-    private communicationInfo;
     constructor(secretId: bigint | number);
     withChannelStore(store: ChannelStore): this;
     withShareStore(store: ShareStore): this;
@@ -66,21 +56,10 @@ export declare class DeRecProtocolBuilder {
     withUserSecretStore(store: UserSecretStore): this;
     withStateStore(store: StateStore): this;
     withTransport(transport: Transport): this;
-    /**
-     * @deprecated Use {@link withOwnTransports}, which takes the whole
-     * preference list — `withOwnTransports([endpoint])` is the direct
-     * replacement. Removed at 0.0.5.
-     */
-    withOwnTransport(endpoint: {
-        uri: string;
-        protocol: string;
-    }): this;
     /**
      * Set every transport endpoint this application serves, in preference
-     * order. Written to the config's `own_transports` array, which takes
-     * precedence over `own_transport_uri` / `own_transport_protocol` on the
-     * Rust side when non-empty — see `ProtocolConfig` in
-     * `library/src/interop/ffi/protocol/handle/mod.rs`.
+     * 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
@@ -89,14 +68,10 @@ export declare 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: {
-        uri: string;
-        protocol: string;
-    }[]): this;
+    withOwnTransports(transports: Endpoint[]): this;
     /** Default: 3. */
     withThreshold(threshold: number): this;
     /** Default: 3. */
@@ -109,38 +84,14 @@ export declare class DeRecProtocolBuilder {
      * `snake_case` keys one for one.
      */
     withTimeouts(timeouts: Timeouts): this;
-    /**
-     * @deprecated Use {@link withUnsafeConnection}, which names both gated
-     * schemes. Removed at 0.0.5. Default: false.
-     */
-    withUnsafeHttp(allow: boolean): this;
     /**
      * Accept plaintext `http://` and `grpc://` transport endpoints.
-     * **Development only.** Default: false. Supersedes
-     * {@link withUnsafeHttp}, which names only the HTTP scheme.
-     *
-     * Either flag alone is honored. Setting both to disagreeing values fails
-     * construction with the error code `CONFLICTING_PLAINTEXT_OPT_IN` rather
-     * than resolving silently, because precedence would hand the decision to
-     * the flag being removed.
+     * **Development only.** Default: false.
      */
     withUnsafeConnection(allow: boolean): this;
     /**
-     * Default: empty. `derec_protocol_new`'s own `communication_info` argument
-     * is a pre-encoded `CommunicationInfo` protobuf message, and this SDK has
-     * 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: Record<string, string>): this;
     /** Default: false. */
@@ -149,7 +100,10 @@ export declare class DeRecProtocolBuilder {
     withUnpairAck(ack: UnpairAck): this;
     /** Default: false. */
     withAutoReplyTo(enabled: boolean): 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: AutoAcceptPolicy): this;
     /** Default: unset. */
     withReplicaId(replicaId: bigint | number): this;
@@ -160,6 +114,9 @@ export declare 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.
      */
@@ -169,9 +126,8 @@ export declare class 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.
@@ -191,53 +147,32 @@ export declare class DeRecProtocol {
     static fromHost(host: NativeHost): DeRecProtocol;
     secretId(): bigint;
     /**
-     * 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: Record<string, string>): Promise<void>;
-    /**
-     * Replace this node's endpoint for one protocol, leaving the others
-     * alone. A node serves at most one endpoint per protocol, so the
-     * `(uri, protocol)` pair identifies the entry it replaces; an entry for a
-     * protocol not yet served is appended, and a replaced one keeps its
-     * position in the preference order.
-     *
-     * Returns a `Promise` for the same reason {@link setCommunicationInfo} does.
-     *
-     * @deprecated Use {@link setOwnTransports}, which takes the whole
-     * preference list and is the only way to change which protocols this node
-     * serves, or their order. Removed at 0.0.5.
-     */
-    setOwnTransport(uri: string, protocol: string): Promise<void>;
     /**
      * Replaces every endpoint this node advertises, in preference order —
-     * the runtime counterpart to `withOwnTransports`, and the only way to
-     * change a multi-endpoint node's set ({@link setOwnTransport} collapses
-     * it to the one endpoint it is given).
+     * 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: {
-        uri: string;
-        protocol: string;
-    }[]): Promise<void>;
+    setOwnTransports(transports: Endpoint[]): Promise<void>;
     /**
      * 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.
      */
@@ -254,14 +189,31 @@ export declare class DeRecProtocol {
     process(message: Uint8Array): Promise<DeRecEvent[]>;
     tick(): Promise<DeRecEvent[]>;
     accept(actionBytes: Uint8Array): Promise<DeRecEvent[]>;
-    reject(actionBytes: Uint8Array, status: number, memo: string): Promise<void>;
+    reject(actionBytes: Uint8Array, status: StatusEnum, memo: string): Promise<void>;
     getFingerprint(channelId: bigint | number): Promise<string>;
     verifyFingerprint(channelId: bigint | number, fingerprint: string): Promise<boolean>;
     removeExpiredChannels(olderThanSecs: number): Promise<string[]>;
+    /**
+     * Rebuild this protocol's `secret_id` namespace from a recovered `Secret`.
+     * Pass the `secret` carried by the `SecretRecovered` event verbatim.
+     * 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.     |
+     */
     restore(recoveredSecret: Extract<DeRecEvent, {
         type: 'SecretRecovered';
     }>['secret'], version: number): Promise<DeRecEvent[]>;
     /** Release the native handle. Safe to call more than once. */
     free(): void;
+    /** Same as {@link DeRecProtocol.free}, for `using`. */
+    [Symbol.dispose](): void;
 }
 export {};