@derec-alliance/react-native 0.0.7 → 0.0.9

package/lib/errors.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) 2026 DeRec Alliance. All rights reserved.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEREC_ERROR_CATEGORIES = void 0;
+exports.DEREC_ERROR_CODES = exports.DEREC_ERROR_CATEGORIES = void 0;
 /**
  * Every category name `derec_error_category_name` can return, and no others.
  *
@@ -33,3 +33,65 @@ exports.DEREC_ERROR_CATEGORIES = [
     "invariant",
     "state_store",
 ];
+/**
+ * Every code `derec_error_code_name` can return, and no others.
+ *
+ * Held to the shared enum fixture by a test, like {@link DEREC_ERROR_CATEGORIES}.
+ * Unlike the WASM bindings, this SDK raises no marshalling-level codes of its
+ * own before a value reaches the library, so this list is exactly the Rust
+ * `Code` table in `library/src/interop/error_codes.rs`.
+ */
+exports.DEREC_ERROR_CODES = [
+    "ok",
+    "non_ok_status",
+    "version_mismatch",
+    "invariant",
+    "invalid_input",
+    "protobuf_decode",
+    "protobuf_encode",
+    "protocol_violation",
+    "store_error",
+    "builder_error",
+    "missing_shared_key",
+    "role_mismatch",
+    "replica_id_not_configured",
+    "channel_already_paired",
+    "already_restored",
+    "restore_conflict",
+    "replica_id_conflict",
+    "encryption",
+    "keygen",
+    "finish_pairing_initiator",
+    "finish_pairing_responder",
+    "empty_transport_uri",
+    "invalid_contact_message",
+    "invalid_pair_request_message",
+    "invalid_pair_response_message",
+    "prepair_hash_mismatch",
+    "missing_replica_id",
+    "unexpected_replica_id",
+    "incompatible_parameter_range",
+    "empty_channels",
+    "duplicate_channel_id",
+    "invalid_threshold",
+    "empty_secret_data",
+    "vss_share_failed",
+    "invalid_weight",
+    "too_many_subshares",
+    "empty_responses",
+    "empty_committed_derec_share",
+    "decode_committed_derec_share",
+    "decode_derec_share",
+    "secret_id_mismatch",
+    "reconstruction_failed",
+    "malformed_recovered_secret",
+    "ffi_null_ptr",
+    "ffi_bad_length",
+    "ffi_bad_utf8",
+    "ffi_bad_proto",
+    "ffi_invalid_enum",
+    "ffi_bad_shared_key",
+    "ffi_nul_in_string",
+    "transport_invalid",
+    "no_usable_endpoint",
+];

package/lib/primitives.d.ts

@@ -1,4 +1,4 @@
-import type { CommittedDeRecShare, CommunicationInfo, ContactMessage, ContactMode, CreateContactResult, DiscoveryProcessResult, GetSecretIdsVersionsRequestMessage, GetSecretIdsVersionsResponseMessage, GetShareRequestMessage, GetShareResponseMessage, PairRequestMessage, PairResponseMessage, PairingProcessResult, PairingRequestProduceResult, PairingResponseProduceResult, ParameterRange, PrePairRequestExtractResult, PrePairRequestMessage, PrePairResponseExtractResult, PrePairResponseMessage, ProcessPrePairResult, ProducePrePairNoKeysResult, ProducePrePairResult, ProduceResult, RecoverResult, SecretVersionEntry, SenderKind, SharingResponseProduceResult, SplitResult, StoreShareRequestMessage, StoreShareResponseMessage, TransportProtocol, UnpairRequestMessage, UnpairResponseMessage, UnpairingProcessResult, VerifyShareRequestMessage, VerifyShareResponseMessage } from './types';
+import type { CommittedDeRecShare, CommunicationInfo, ContactMessage, ContactMode, CreateContactResult, DiscoveryProcessResult, GetSecretIdsVersionsRequestMessage, GetSecretIdsVersionsResponseMessage, GetShareRequestMessage, GetShareResponseMessage, PairRequestMessage, PairResponseMessage, PairingProcessResult, PairingRequestProduceResult, PairingResponseProduceResult, ParameterRange, PrePairRequestExtractResult, PrePairRequestMessage, PrePairResponseExtractResult, PrePairResponseMessage, ProcessPrePairResult, ProducePrePairNoKeysResult, ProducePrePairResult, ProduceResult, RecoverResult, SecretVersionEntry, SenderKind, SharingResponseProduceResult, SplitResult, StoreShareRequestMessage, StoreShareResponseMessage, TransportProtocol, UnpairRequestMessage, UnpairResponseMessage, UnpairingProcessResult, VerifyShareRequestMessage, VerifyShareResponseMessage, WeightedChannel } from './types';
 export declare const primitives: {
     discovery: {
         request: {
@@ -67,7 +67,7 @@ export declare const primitives: {
     };
     sharing: {
         request: {
-            split(channels: bigint[], secret_id: bigint, version: number, secret_data: Uint8Array, threshold: number): SplitResult;
+            split(channels: WeightedChannel[], secret_id: bigint, version: number, secret_data: Uint8Array, threshold: number): SplitResult;
             produce(channel_id: bigint, version: number, secret_id: bigint, committed_share: CommittedDeRecShare, keep_list: number[], description: string, shared_key: Uint8Array, reply_to?: TransportProtocol[]): ProduceResult;
             extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): {
                 request: StoreShareRequestMessage;

package/lib/primitives.js

@@ -270,7 +270,9 @@ const recovery = {
 const sharing = {
     request: {
         split(channels, secret_id, version, secret_data, threshold) {
-            const packed = call('protect_secret', secret_id, secret_data, channels, threshold, version);
+            const ids = channels.map(([channelId]) => BigInt(channelId));
+            const weights = channels.map(([, weight]) => weight);
+            const packed = call('protect_secret', secret_id, secret_data, ids, weights, threshold, version);
             const shares = new Map();
             for (const entry of (0, binary_1.decodeCommittedShareEntries)(packed)) {
                 shares.set(entry.channelId, (0, messages_1.decodeMessage)(messages_1.MessageKind.CommittedDeRecShare, entry.shareProto));

package/lib/protocol.d.ts

@@ -1,5 +1,5 @@
 import { FlowKind } 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';
+import type { AutoAcceptPolicy, ChannelStore, ContactMessage, ContactMode, DeRecEvent, DeRecProtocolConfig, Endpoint, DiscoveryParams, PairingParams, ParameterRange, ProtectSecretParams, RecoverSecretParams, UnpairReplicaParams, SecretStore, ShareStore, StateStore, StatusEnum, ReplicaDiscoveryParams, Timeouts, Transport, UnpairAck, UnpairParams, UpdateChannelInfoParams, UserSecretStore, VerifySharesParams, StoresInit } 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`
@@ -20,9 +20,12 @@ export declare function buildProtectSecretParams(params: ProtectSecretParams): R
  * `SecretWire`'s own shape: `channel_id`/`replica_id` are the decimal `u64`
  * strings the `SecretRecovered` event already carries, forwarded verbatim;
  * `communication_info` is omitted per-entry (not sent as `{}`) whenever a
- * helper or replica member has none, matching the Go SDK's `omitempty` and
- * the shared golden fixture byte-for-byte; `replicas` is omitted entirely
- * when the recovered secret has no replica group.
+ * helper or replica member has none — `undefined`, `null`, or an empty map
+ * are all treated the same — matching the Go SDK's `omitempty` and the
+ * shared golden fixture byte-for-byte; `weight` is forwarded as given
+ * whenever a helper carries one; `replicas` is omitted entirely when the
+ * recovered secret has no replica group, and `threshold` when the roster
+ * records none.
  *
  * Exported so it can be golden-tested against the shared wire fixture
  * without a native module.
@@ -55,6 +58,13 @@ export declare class DeRecProtocolBuilder {
     withSecretStore(store: SecretStore): this;
     withUserSecretStore(store: UserSecretStore): this;
     withStateStore(store: StateStore): this;
+    /**
+     * Set every store in one call. Forwards to {@link withChannelStore},
+     * {@link withShareStore}, {@link withSecretStore},
+     * {@link withUserSecretStore} and {@link withStateStore} in turn, so
+     * calling one of them again afterwards replaces just that store.
+     */
+    withStores(stores: StoresInit): this;
     withTransport(transport: Transport): this;
     /**
      * Set every transport endpoint this application serves, in preference
@@ -72,7 +82,22 @@ export declare class DeRecProtocolBuilder {
      * since a node with no endpoint cannot be reached by any peer.
      */
     withOwnTransports(transports: Endpoint[]): this;
-    /** Default: 3. */
+    /**
+     * The starting threshold: the minimum number of subshares required to
+     * reconstruct the secret, for a secret with no threshold stored. Every
+     * publish stores the threshold it used (`UserSecrets.threshold`), the
+     * roster carries it, and `restore` and replica hydration put it back. A
+     * round splits at `ProtectSecretParams.threshold`, otherwise at the stored
+     * threshold, and only otherwise at this value, so changing it later does
+     * not change a stored threshold.
+     *
+     * A Helper holds one subshare unless `ProtectSecretParams.weights` has
+     * given it a weight, so with no weights the threshold is a number of
+     * Helpers, as before. Every weight must be below the round's threshold, so
+     * no single Helper can recover alone. When this value applies and is
+     * lowered to or below a stored weight, every publish fails with
+     * `invalid_weight` until `ProtectSecret` assigns valid weights. Default: 3.
+     */
     withThreshold(threshold: number): this;
     /**
      * Every field is optional; not calling this at all leaves all four at the
@@ -92,7 +117,12 @@ export declare class DeRecProtocolBuilder {
      * map is part of the protocol from construction.
      */
     withCommunicationInfo(info: Record<string, string>): this;
-    /** Default: false. */
+    /**
+     * Who answers an inbound request whose handling failed. `true`: the
+     * library sends the response itself. `false`: nothing is sent, and the
+     * `RequestFailed` event carries a token to pass to `reject`. Default:
+     * false.
+     */
     withAutoRespondOnFailure(enabled: boolean): this;
     /** Default: "required". */
     withUnpairAck(ack: UnpairAck): this;
@@ -117,8 +147,53 @@ export declare class DeRecProtocolBuilder {
      * applies its default.
      *
      * Default: unset — no constraints advertised, every peer range accepted.
+     *
+     * Share size is enforced by the helper; frequency limits are enforced by
+     * the app's share store (refuse from `save`/`recordVerification`); the
+     * deletion and deactivation timeouts are checked at pairing only.
      */
     withParameterRange(range: Partial<ParameterRange>): this;
+    /**
+     * Cap the total number of subshares one sharing round may split the
+     * secret into — the sum of every helper's weight. Crosses to the library
+     * as a decimal string. Default: unset, no cap.
+     *
+     * Checked only by `start(ProtectSecret)`, including the publishes the
+     * library starts itself: a round over the cap fails with
+     * `too_many_subshares` before anything is sent. Recovery applies no cap.
+     * Recovering costs time that grows quadratically with the total number of
+     * subshares, so the cap bounds what a later recovery must do. A cap below
+     * the threshold makes `build()` throw.
+     */
+    withMaxSubshares(max: bigint | number): this;
+    /**
+     * Layer a {@link DeRecProtocolConfig} onto the builder: a field the config
+     * sets (present and not `null`) replaces what the builder currently
+     * holds, a field it leaves unset is untouched, and `timeouts` merges per
+     * field against the builder's current timeouts rather than resetting the
+     * other three. Every other nested object replaces as a whole. Apply a
+     * general config, then a per-user one, then any individual `with*` call —
+     * the last write wins per field, same as two `withConfig` calls in a row.
+     *
+     * Every key is assigned verbatim into the same `snake_case` config JSON
+     * `build()` sends to `protocol_new`, whatever it is spelled as: nothing
+     * here validates, defaults, or recognizes field names. Rust does both —
+     * `deny_unknown_fields` is what turns a misspelled key into an error.
+     *
+     * `secret_id` is not a config field — it is the constructor argument —
+     * and `build()` always sends the constructor's value last, so a config
+     * (e.g. loaded from a per-user record) can never redirect which secret
+     * this instance manages even if it carries a `secret_id` key.
+     *
+     * A config parsed from JSON can carry an own `__proto__` key. Assigning
+     * it through plain bracket notation would hit the accessor
+     * `Object.prototype` defines for that name and replace this builder's
+     * config object's prototype instead of setting a field on it — the value
+     * would then vanish from the JSON payload instead of reaching Rust to be
+     * rejected as an unknown key. `Object.defineProperty` makes it a genuine
+     * own property, the same as every other key here.
+     */
+    withConfig(config: DeRecProtocolConfig): this;
     build(): DeRecProtocol;
 }
 /**
@@ -186,6 +261,17 @@ export declare class DeRecProtocol {
     start(flowKind: FlowKind.UnpairReplica, params: UnpairReplicaParams): Promise<DeRecEvent[]>;
     process(message: Uint8Array): Promise<DeRecEvent[]>;
     tick(): Promise<DeRecEvent[]>;
+    /**
+     * Accept a pending action from an `ActionRequired` event, returning the
+     * events it produces.
+     *
+     * When the action completes a pairing, the publish that follows reuses the
+     * stored helper weights. If one is no longer valid under the round's
+     * threshold, that publish fails with `invalid_weight` before anything is
+     * sent and this throws: the pairing has completed and its response was
+     * sent, but the `PairingCompleted` event is not returned. Call `start`
+     * with `ProtectSecret` and valid weights to publish.
+     */
     accept(actionBytes: Uint8Array): Promise<DeRecEvent[]>;
     reject(actionBytes: Uint8Array, status: StatusEnum, memo: string): Promise<void>;
     getFingerprint(channelId: bigint | number): Promise<string>;
@@ -198,6 +284,13 @@ export declare class DeRecProtocol {
      * 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.
+     *
+     * On a promotion the current snapshot is published to the promoted peer,
+     * reusing the stored helper weights. If one is no longer valid under the
+     * current threshold, that publish fails with `invalid_weight` before
+     * anything is sent and this throws. The promotion stands: calling this
+     * again resolves `true` and publishes nothing, so call `start` with
+     * `ProtectSecret` and valid weights to reach the promoted peer.
      */
     verifyFingerprint(channelId: bigint | number, fingerprint: string): Promise<boolean>;
     removeExpiredChannels(olderThanSecs: number): Promise<string[]>;
@@ -211,6 +304,9 @@ export declare class DeRecProtocol {
      * reported as a `PeerNotRestored` event in the returned array and the rest
      * of the roster is restored.
      *
+     * A helper's or member's `communication_info` may be absent or `null`;
+     * both mean the same thing — no entries.
+     *
      * Rejects with a `DeRecError`; among its codes:
      *
      * | code               | meaning                                                     |

package/lib/protocol.js

@@ -78,19 +78,32 @@ function buildProtectSecretParams(params) {
     if (params.description !== undefined) {
         out.description = params.description;
     }
+    if (params.weights != null && params.weights.size > 0) {
+        const weights = {};
+        for (const [id, weight] of params.weights) {
+            weights[id.toString()] = weight;
+        }
+        out.weights = weights;
+    }
+    if (params.threshold != null) {
+        out.threshold = params.threshold;
+    }
     return out;
 }
 function communicationInfoOrOmit(info) {
-    return info !== undefined && Object.keys(info).length > 0 ? info : undefined;
+    return info != null && Object.keys(info).length > 0 ? info : undefined;
 }
 /**
  * `RestoreParamsJson` (`library/src/interop/ffi/protocol/handle/flow.rs`). Mirrors
  * `SecretWire`'s own shape: `channel_id`/`replica_id` are the decimal `u64`
  * strings the `SecretRecovered` event already carries, forwarded verbatim;
  * `communication_info` is omitted per-entry (not sent as `{}`) whenever a
- * helper or replica member has none, matching the Go SDK's `omitempty` and
- * the shared golden fixture byte-for-byte; `replicas` is omitted entirely
- * when the recovered secret has no replica group.
+ * helper or replica member has none — `undefined`, `null`, or an empty map
+ * are all treated the same — matching the Go SDK's `omitempty` and the
+ * shared golden fixture byte-for-byte; `weight` is forwarded as given
+ * whenever a helper carries one; `replicas` is omitted entirely when the
+ * recovered secret has no replica group, and `threshold` when the roster
+ * records none.
  *
  * Exported so it can be golden-tested against the shared wire fixture
  * without a native module.
@@ -107,6 +120,9 @@ function buildRestoreParams(recoveredSecret, version) {
             if (info !== undefined) {
                 out.communication_info = info;
             }
+            if (helper.weight !== undefined) {
+                out.weight = helper.weight;
+            }
             return out;
         }),
         secrets: recoveredSecret.secrets.map((secret) => ({
@@ -133,6 +149,9 @@ function buildRestoreParams(recoveredSecret, version) {
             shared_key: Array.from(recoveredSecret.replicas.shared_key),
         };
     }
+    if (recoveredSecret.threshold != null) {
+        recovered.threshold = recoveredSecret.threshold;
+    }
     return { version, recovered_secret: recovered };
 }
 /**
@@ -267,6 +286,19 @@ class DeRecProtocolBuilder {
         this.stores.stateStore = store;
         return this;
     }
+    /**
+     * Set every store in one call. Forwards to {@link withChannelStore},
+     * {@link withShareStore}, {@link withSecretStore},
+     * {@link withUserSecretStore} and {@link withStateStore} in turn, so
+     * calling one of them again afterwards replaces just that store.
+     */
+    withStores(stores) {
+        return this.withChannelStore(stores.channelStore)
+            .withShareStore(stores.shareStore)
+            .withSecretStore(stores.secretStore)
+            .withUserSecretStore(stores.userSecretStore)
+            .withStateStore(stores.stateStore);
+    }
     withTransport(transport) {
         this.stores.transport = transport;
         return this;
@@ -290,7 +322,22 @@ class DeRecProtocolBuilder {
         this.config.own_transports = transports.map(({ uri, protocol }) => ({ uri, protocol }));
         return this;
     }
-    /** Default: 3. */
+    /**
+     * The starting threshold: the minimum number of subshares required to
+     * reconstruct the secret, for a secret with no threshold stored. Every
+     * publish stores the threshold it used (`UserSecrets.threshold`), the
+     * roster carries it, and `restore` and replica hydration put it back. A
+     * round splits at `ProtectSecretParams.threshold`, otherwise at the stored
+     * threshold, and only otherwise at this value, so changing it later does
+     * not change a stored threshold.
+     *
+     * A Helper holds one subshare unless `ProtectSecretParams.weights` has
+     * given it a weight, so with no weights the threshold is a number of
+     * Helpers, as before. Every weight must be below the round's threshold, so
+     * no single Helper can recover alone. When this value applies and is
+     * lowered to or below a stored weight, every publish fails with
+     * `invalid_weight` until `ProtectSecret` assigns valid weights. Default: 3.
+     */
     withThreshold(threshold) {
         this.config.threshold = threshold;
         return this;
@@ -322,7 +369,12 @@ class DeRecProtocolBuilder {
         this.config.communication_info = info;
         return this;
     }
-    /** Default: false. */
+    /**
+     * Who answers an inbound request whose handling failed. `true`: the
+     * library sends the response itself. `false`: nothing is sent, and the
+     * `RequestFailed` event carries a token to pass to `reject`. Default:
+     * false.
+     */
     withAutoRespondOnFailure(enabled) {
         this.config.auto_respond_on_failure = enabled;
         return this;
@@ -371,6 +423,10 @@ class DeRecProtocolBuilder {
      * applies its default.
      *
      * Default: unset — no constraints advertised, every peer range accepted.
+     *
+     * Share size is enforced by the helper; frequency limits are enforced by
+     * the app's share store (refuse from `save`/`recordVerification`); the
+     * deletion and deactivation timeouts are checked at pairing only.
      */
     withParameterRange(range) {
         this.config.parameter_range = {
@@ -387,11 +443,85 @@ class DeRecProtocolBuilder {
         };
         return this;
     }
+    /**
+     * Cap the total number of subshares one sharing round may split the
+     * secret into — the sum of every helper's weight. Crosses to the library
+     * as a decimal string. Default: unset, no cap.
+     *
+     * Checked only by `start(ProtectSecret)`, including the publishes the
+     * library starts itself: a round over the cap fails with
+     * `too_many_subshares` before anything is sent. Recovery applies no cap.
+     * Recovering costs time that grows quadratically with the total number of
+     * subshares, so the cap bounds what a later recovery must do. A cap below
+     * the threshold makes `build()` throw.
+     */
+    withMaxSubshares(max) {
+        this.config.max_subshares = BigInt(max).toString();
+        return this;
+    }
+    /**
+     * Layer a {@link DeRecProtocolConfig} onto the builder: a field the config
+     * sets (present and not `null`) replaces what the builder currently
+     * holds, a field it leaves unset is untouched, and `timeouts` merges per
+     * field against the builder's current timeouts rather than resetting the
+     * other three. Every other nested object replaces as a whole. Apply a
+     * general config, then a per-user one, then any individual `with*` call —
+     * the last write wins per field, same as two `withConfig` calls in a row.
+     *
+     * Every key is assigned verbatim into the same `snake_case` config JSON
+     * `build()` sends to `protocol_new`, whatever it is spelled as: nothing
+     * here validates, defaults, or recognizes field names. Rust does both —
+     * `deny_unknown_fields` is what turns a misspelled key into an error.
+     *
+     * `secret_id` is not a config field — it is the constructor argument —
+     * and `build()` always sends the constructor's value last, so a config
+     * (e.g. loaded from a per-user record) can never redirect which secret
+     * this instance manages even if it carries a `secret_id` key.
+     *
+     * A config parsed from JSON can carry an own `__proto__` key. Assigning
+     * it through plain bracket notation would hit the accessor
+     * `Object.prototype` defines for that name and replace this builder's
+     * config object's prototype instead of setting a field on it — the value
+     * would then vanish from the JSON payload instead of reaching Rust to be
+     * rejected as an unknown key. `Object.defineProperty` makes it a genuine
+     * own property, the same as every other key here.
+     */
+    withConfig(config) {
+        for (const [key, value] of Object.entries(config)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (key === 'timeouts') {
+                const held = this.config.timeouts ?? {};
+                const merged = { ...held };
+                for (const [timeoutKey, timeoutValue] of Object.entries(value)) {
+                    if (timeoutValue !== undefined && timeoutValue !== null) {
+                        merged[timeoutKey] = timeoutValue;
+                    }
+                }
+                this.config.timeouts = merged;
+                continue;
+            }
+            if (key === '__proto__') {
+                Object.defineProperty(this.config, key, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+                continue;
+            }
+            this.config[key] = value;
+        }
+        return this;
+    }
     build() {
         const config = {
-            secret_id: this.secretIdValue.toString(),
             replica_id: null,
             ...this.config,
+            // Last, so a config's own `secret_id` key (it is not a config field;
+            // see `withConfig`) can never override the constructor's.
+            secret_id: this.secretIdValue.toString(),
         };
         const host = (0, native_1.getNative)().protocol_new(JSON.stringify(config), new Uint8Array(0), this.stores);
         return DeRecProtocol.fromHost(host);
@@ -490,6 +620,17 @@ class DeRecProtocol {
         const buffer = (await this.host.tick());
         return decodeEvents(buffer);
     }
+    /**
+     * Accept a pending action from an `ActionRequired` event, returning the
+     * events it produces.
+     *
+     * When the action completes a pairing, the publish that follows reuses the
+     * stored helper weights. If one is no longer valid under the round's
+     * threshold, that publish fails with `invalid_weight` before anything is
+     * sent and this throws: the pairing has completed and its response was
+     * sent, but the `PairingCompleted` event is not returned. Call `start`
+     * with `ProtectSecret` and valid weights to publish.
+     */
     async accept(actionBytes) {
         const buffer = (await this.host.accept(actionBytes));
         return decodeEvents(buffer);
@@ -509,6 +650,13 @@ class DeRecProtocol {
      * 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.
+     *
+     * On a promotion the current snapshot is published to the promoted peer,
+     * reusing the stored helper weights. If one is no longer valid under the
+     * current threshold, that publish fails with `invalid_weight` before
+     * anything is sent and this throws. The promotion stands: calling this
+     * again resolves `true` and publishes nothing, so call `start` with
+     * `ProtectSecret` and valid weights to reach the promoted peer.
      */
     async verifyFingerprint(channelId, fingerprint) {
         return (await this.host.verifyFingerprint(toBigInt(channelId), fingerprint));
@@ -527,6 +675,9 @@ class DeRecProtocol {
      * reported as a `PeerNotRestored` event in the returned array and the rest
      * of the roster is restored.
      *
+     * A helper's or member's `communication_info` may be absent or `null`;
+     * both mean the same thing — no entries.
+     *
      * Rejects with a `DeRecError`; among its codes:
      *
      * | code               | meaning                                                     |