@derec-alliance/react-native 0.0.4 → 0.0.6

package/src/errors.ts

@@ -42,4 +42,11 @@ export interface DeRecError {
   memo?: string;
   expected?: number;
   got?: number;
+  /**
+   * Present only when `code` is `"restore_conflict"`: the channels already
+   * living at the recovered canonical ids, as decimal strings — the same
+   * field `@derec-alliance/nodejs` carries on its restore conflict error.
+   * Clear exactly these and retry `restore`.
+   */
+  channel_ids?: string[];
 }

package/src/native.ts

@@ -6,7 +6,8 @@
  * surface passes `ArrayBuffer`s that TurboModule specs cannot express.
  */
 export interface DeRecNative {
-  version(): string;
+  version(): { major: number; minor: number };
+  generate_replica_id(): bigint;
 }
 
 /**

package/src/primitives.ts

@@ -55,6 +55,7 @@ import type {
   PrePairResponseExtractResult,
   PrePairResponseMessage,
   ProcessPrePairResult,
+  ProducePrePairNoKeysResult,
   ProducePrePairResult,
   ProduceResult,
   RecoverResult,
@@ -94,22 +95,17 @@ function replyTo(value: TransportProtocol[] | undefined): Uint8Array {
 }
 
 /**
- * `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: ContactMessage): Uint8Array {
-  return bytes(
-    call('encode_contact_message', jsonToBytes(plainMessage(contact_message))),
-  );
+  return pairing.request.encode_contact(contact_message);
 }
 
 function decodeContact(wire: Uint8Array | ArrayBuffer): ContactMessage {
-  const json = call('decode_contact_message', wire) as ArrayBuffer;
-  return reviveMessage(jsonFromBytes(json)) as ContactMessage;
+  return pairing.request.decode_contact(wire);
 }
 
 const discovery = {
@@ -247,22 +243,24 @@ function decodeTransportList(framed: Uint8Array | ArrayBuffer): TransportProtoco
 
 const pairing = {
   request: {
+    /** 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: bigint,
       contact_mode: ContactMode | number,
       transport_protocols: TransportProtocol[],
+      nonce?: bigint | number | null,
     ): CreateContactResult {
-      // 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.
+      // 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),
-        0,
-        0n,
+        nonce == null ? 0 : 1,
+        nonce ?? 0n,
       ) as { contact_wire_bytes: ArrayBuffer; secret_key_material: ArrayBuffer };
       return {
         contact_message: decodeContact(result.contact_wire_bytes),
@@ -270,13 +268,22 @@ const pairing = {
       };
     },
 
-    /** Proto-encodes a `ContactMessage`. Rejects a contact that violates the
-     *  mode/field invariant rather than serializing it. */
-    encode_contact: encodeContact,
+    /** 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: ContactMessage): Uint8Array {
+      return bytes(
+        call('encode_contact_message', jsonToBytes(plainMessage(contact_message))),
+      );
+    },
 
-    /** Decodes proto `ContactMessage` bytes. Rejects a contact that violates
-     *  the mode/field invariant rather than returning it. */
-    decode_contact: decodeContact,
+    /** 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: Uint8Array | ArrayBuffer): ContactMessage {
+      const json = call('decode_contact_message', bytes) as ArrayBuffer;
+      return reviveMessage(jsonFromBytes(json)) as ContactMessage;
+    },
 
     produce(
       kind: SenderKind,
@@ -306,8 +313,17 @@ const pairing = {
       };
     },
 
-    extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): { request: PairRequestMessage } {
-      const result = call('extract_pair_request', envelope_bytes, secret_key) as {
+    extract(
+      envelope_bytes: Uint8Array,
+      secret_key: Uint8Array,
+      parameter_range: ParameterRange | null,
+    ): { request: PairRequestMessage } {
+      const result = call(
+        'extract_pair_request',
+        envelope_bytes,
+        secret_key,
+        encodeOptionalMessage(MessageKind.ParameterRange, parameter_range),
+      ) as {
         request_proto_bytes: ArrayBuffer;
       };
       return {
@@ -393,12 +409,14 @@ const pairing = {
       contact_message: ContactMessage,
       response: PairResponseMessage,
       secret_key: Uint8Array,
+      parameter_range: ParameterRange | null,
     ): PairingProcessResult {
       const result = call(
         'process_pair_response_message',
         encodeContact(contact_message),
         encodeMessage(MessageKind.PairResponse, response),
         secret_key,
+        encodeOptionalMessage(MessageKind.ParameterRange, parameter_range),
       ) as { shared_key: ArrayBuffer; channel_id: bigint };
       return { shared_key: bytes(result.shared_key), channel_id: result.channel_id };
     },
@@ -448,6 +466,45 @@ const pairing = {
         nonce: result.nonce,
       };
     },
+
+    produce_pre_pair_no_keys(
+      channel_id: bigint,
+      request: PrePairRequestMessage,
+    ): ProducePrePairNoKeysResult {
+      const result = call(
+        'produce_pre_pair_no_keys_response_message',
+        channel_id,
+        encodeMessage(MessageKind.PrePairRequest, request),
+      ) as { envelope_wire_bytes: ArrayBuffer; secret_key_material: ArrayBuffer };
+      return {
+        envelope: bytes(result.envelope_wire_bytes),
+        secret_key_material: bytes(result.secret_key_material),
+      };
+    },
+
+    process_pre_pair_no_keys(
+      contact_message: ContactMessage,
+      response: PrePairResponseMessage,
+    ): ProcessPrePairResult {
+      const result = call(
+        'process_pre_pair_no_keys_response_message',
+        encodeContact(contact_message),
+        encodeMessage(MessageKind.PrePairResponse, response),
+      ) as {
+        mlkem_encapsulation_key: ArrayBuffer;
+        ecies_public_key: ArrayBuffer;
+        nonce: bigint;
+      };
+      return {
+        mlkem_encapsulation_key: bytes(result.mlkem_encapsulation_key),
+        ecies_public_key: bytes(result.ecies_public_key),
+        nonce: result.nonce,
+      };
+    },
+  },
+
+  fingerprint(shared_key: Uint8Array): string {
+    return call('pairing_fingerprint', shared_key) as string;
   },
 };
 

package/src/protocol.ts

@@ -11,6 +11,7 @@ import type {
   ContactMessage,
   ContactMode,
   DeRecEvent,
+  Endpoint,
   DiscoveryParams,
   PairingParams,
   ParameterRange,
@@ -20,6 +21,7 @@ import type {
   SecretStore,
   ShareStore,
   StateStore,
+  StatusEnum,
   ReplicaDiscoveryParams,
   Target,
   Timeouts,
@@ -81,25 +83,6 @@ function decodeEvents(buffer: ArrayBuffer): DeRecEvent[] {
   return reviveEventBytes(jsonFromBytes(buffer)) as DeRecEvent[];
 }
 
-/**
- * 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 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}"`);
-  }
-}
-
 function encodeTarget(target: Target): unknown {
   if (target === null) {
     return null;
@@ -261,13 +244,8 @@ function buildStartParams(flowKind: FlowKind, params: unknown): Uint8Array {
       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 jsonToBytes(out);
     }
@@ -313,7 +291,6 @@ export class DeRecProtocolBuilder {
   private readonly secretIdValue: bigint;
   private config: Record<string, unknown> = {};
   private stores: Record<string, unknown> = {};
-  private communicationInfo: Record<string, string> | undefined;
 
   constructor(secretId: bigint | number) {
     this.secretIdValue = BigInt(secretId);
@@ -349,23 +326,10 @@ 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`.
+   * 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
@@ -374,15 +338,11 @@ export 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 {
-    this.config.own_transports = transports.map((t) => ({
-      uri: t.uri,
-      protocol: protocolDiscriminant(t.protocol),
-    }));
+  withOwnTransports(transports: Endpoint[]): this {
+    this.config.own_transports = transports.map(({ uri, protocol }) => ({ uri, protocol }));
     return this;
   }
 
@@ -410,24 +370,9 @@ export class DeRecProtocolBuilder {
     return this;
   }
 
-  /**
-   * @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.
+   * **Development only.** Default: false.
    */
   withUnsafeConnection(allow: boolean): this {
     this.config.unsafe_connection = allow;
@@ -435,24 +380,11 @@ export class DeRecProtocolBuilder {
   }
 
   /**
-   * 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 {
-    this.communicationInfo = info;
+    this.config.communication_info = info;
     return this;
   }
 
@@ -464,13 +396,7 @@ export class DeRecProtocolBuilder {
 
   /** Default: "required". */
   withUnpairAck(ack: UnpairAck): this {
-    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 as string}"`);
-    }
+    this.config.unpair_ack = ack;
     return this;
   }
 
@@ -480,17 +406,20 @@ export class DeRecProtocolBuilder {
     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: AutoAcceptPolicy): this {
     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;
   }
@@ -508,30 +437,26 @@ export 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: 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,
-      ),
+      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;
   }
@@ -540,8 +465,6 @@ export class DeRecProtocolBuilder {
     const config = {
       secret_id: this.secretIdValue.toString(),
       replica_id: null,
-      own_transport_uri: '',
-      own_transport_protocol: 0,
       ...this.config,
     };
     const host = (getNative() as unknown as NativeHost).protocol_new(
@@ -549,29 +472,15 @@ export class DeRecProtocolBuilder {
       new Uint8Array(0),
       this.stores,
     ) as NativeHost;
-    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);
   }
 }
 
 /**
  * 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.
@@ -601,68 +510,39 @@ export class DeRecProtocol {
   }
 
   /**
-   * 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> {
     return this.host.setCommunicationInfo(jsonToBytes(info)) as 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> {
-    return this.host.setOwnTransport(
-      uri,
-      protocolDiscriminant(protocol),
-    ) 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).
+   * 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> {
-    const wire = transports.map(({ uri, protocol }) => ({
-      uri,
-      protocol: protocolDiscriminant(protocol),
-    }));
+  setOwnTransports(transports: Endpoint[]): Promise<void> {
+    const wire = transports.map(({ uri, protocol }) => ({ uri, 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
-   * 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.
    */
@@ -713,7 +593,7 @@ export class DeRecProtocol {
     return decodeEvents(buffer);
   }
 
-  async reject(actionBytes: Uint8Array, status: number, memo: string): Promise<void> {
+  async reject(actionBytes: Uint8Array, status: StatusEnum, memo: string): Promise<void> {
     await this.host.reject(actionBytes, status, memo);
   }
 
@@ -730,6 +610,21 @@ export class DeRecProtocol {
     return jsonFromBytes(buffer) as 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.     |
+   */
   async restore(
     recoveredSecret: Extract<DeRecEvent, { type: 'SecretRecovered' }>['secret'],
     version: number,
@@ -743,4 +638,9 @@ export class DeRecProtocol {
   free(): void {
     this.host.free();
   }
+
+  /** Same as {@link DeRecProtocol.free}, for `using`. */
+  [Symbol.dispose](): void {
+    this.free();
+  }
 }