@derec-alliance/nodejs 0.0.5 → 0.0.7

package/index.d.ts

@@ -9,15 +9,15 @@ export interface SecretStore {
   ): Promise<Uint8Array | null | undefined>;
   /**
    * Load secrets of the same `kind` for several channels in one call,
-   * scoped to `secretId`. Must return an array with one entry per input
-   * id, in the same order, using `null` (or `undefined`) for channels
-   * with no stored secret of `kind`.
+   * scoped to `secretId`. Must return an array with exactly one entry per
+   * input id, in the same order, using `null` (or `undefined`) for channels
+   * with no stored secret of `kind`. Whether a missing entry is an error is
+   * decided by the library.
    */
   loadMany(
     secretId: string,
     channelIds: string[],
     kind: 0 | 1 | 2,
-    missingPolicy: "skip" | "fail",
   ): Promise<Array<Uint8Array | null | undefined>>;
   save(
     secretId: string,
@@ -123,22 +123,15 @@ export declare function channelFilterMatches(
 /**
  * The endpoints a peer-supplied message advertises, in the peer's own order.
  *
- * Yields `supported_transports` when it is non-empty, and otherwise the
- * singular `transport_protocol` — which is how every implementation predating
- * the offer list advertises, and the reason this is a function rather than a
- * field read. Reading `transport_protocol` directly is a bug: its meaning
- * narrowed to "one entry of a list, and possibly absent", so a peer that has
- * moved past it looks unreachable to a reader that was correct before 0.0.3.
- *
  * Reports what was advertised, not what is acceptable — nothing here is
  * validated, and the protocol still applies its own transport policy to
  * whatever it records.
  */
 export declare function advertisedEndpoints(
   message:
-    | Pick<ContactMessage, "transport_protocol" | "supported_transports">
-    | Pick<PairRequestMessage, "transport_protocol" | "supported_transports">
-    | Pick<PrePairRequestMessage, "transport_protocol" | "supported_transports">
+    | Pick<ContactMessage, "supported_transports">
+    | Pick<PairRequestMessage, "supported_transports">
+    | Pick<PrePairRequestMessage, "supported_transports">
     | null
     | undefined,
 ): TransportProtocol[];
@@ -228,11 +221,7 @@ export interface ChannelStore {
     secretId: string,
     filter: ReplicaFilter,
   ): Promise<Uint8Array | null | undefined>;
-  linkChannel(
-    secretId: string,
-    channelId: string,
-    linkedChannelId: string,
-  ): Promise<void>;
+  linkChannel(secretId: string, a: string, b: string): Promise<void>;
   linkedChannels(secretId: string, channelId: string): Promise<string[]>;
 }
 
@@ -264,6 +253,35 @@ export interface ShareStore {
   save(secretId: string, channelId: string, share: Share): Promise<void>;
   latestVersion(secretId: string): Promise<number | null>;
   removeChannel(secretId: string, channelId: string): Promise<void>;
+  /**
+   * Drop the shares stored under `(secretId, channelId)` at each of
+   * `versions`. Idempotent: a version that is not stored is skipped, and
+   * an empty array is a no-op.
+   *
+   * A helper calls this to apply `StoreShareRequestMessage.keepList`, the
+   * complete set of versions the owner wants retained: every stored
+   * version outside it is removed once the incoming share is persisted.
+   * Shares under other channels or partitions must be left untouched.
+   */
+  removeVersions(secretId: string, channelId: string, versions: number[]): Promise<void>;
+  /**
+   * Owner only: the versions every helper keeps after the owner distributes
+   * `version`. Asked once per sharing round, before anything is sent,
+   * including the rounds the library starts itself; the answer becomes
+   * `keepList` for every helper.
+   *
+   * Return `null` or `undefined` to send no `keepList` (it goes out empty):
+   * helpers then keep every version they hold. An app that wants to cap how
+   * many versions helpers retain returns that cap here. A returned list is
+   * used as is, plus `version`, which the library always adds. Helpers
+   * delete every version that is not listed, so list every version that
+   * could still become the latest: those that committed (for example, whose
+   * `SharingComplete` reported `threshold_met`) and those whose round is
+   * still open. Leave out only versions whose round failed or that the user
+   * rolled back; a list that leaves out too much can make the secret
+   * unrecoverable.
+   */
+  keepList(secretId: string, version: number): Promise<number[] | null | undefined>;
 }
 
 export interface UserSecretEntry {
@@ -276,6 +294,10 @@ export interface UserSecrets {
   version: number;
   secrets: UserSecretEntry[];
   description?: string;
+  /** Decimal `replica_id` of the member that published `version`. Absent
+   *  when none is recorded. Store and return it unchanged: replica members
+   *  compare it to detect a conflicting copy of the same version. */
+  author_replica_id?: string;
 }
 
 /**
@@ -319,6 +341,18 @@ export interface StateStore {
   loadAll(secretId: string, kind: 0 | 1 | 2 | 3 | 4): Promise<Uint8Array[]>;
 }
 
+/** A transport protocol, by name. */
+export type TransportProtocolName = "https" | "grpc";
+
+/**
+ * One endpoint a node serves or a peer advertised, as every app-facing call
+ * and event carries it.
+ */
+export interface Endpoint {
+  uri: string;
+  protocol: TransportProtocolName;
+}
+
 /**
  * Outbound message delivery.
  *
@@ -364,7 +398,7 @@ export interface Transport {
    * with {@link singleEndpointTransport} rather than by indexing.
    */
   send(
-    endpoints: ReadonlyArray<{ protocol: string; uri: string }>,
+    endpoints: ReadonlyArray<Endpoint>,
     message: Uint8Array,
   ): Promise<void>;
 }
@@ -384,10 +418,25 @@ export interface Transport {
  * a round trip; skipping one that would have worked costs the delivery.
  */
 export type SendOne = (
-  endpoint: { protocol: string; uri: string },
+  endpoint: Endpoint,
   message: Uint8Array,
 ) => Promise<void>;
 
+/**
+ * The DeRec protocol version this build speaks — the `protocolVersionMajor` /
+ * `protocolVersionMinor` it writes into every envelope it produces. Not the
+ * package version.
+ */
+export declare function protocol_version(): { major: number; minor: number };
+
+/**
+ * A fresh replica identity, generated by the core — never `0`. Persist it
+ * once per device and pass the same value to `withReplicaId` on every
+ * protocol init: a device whose id changes cannot be re-identified by its
+ * group.
+ */
+export declare function generate_replica_id(): bigint;
+
 /**
  * Builds a {@link Transport} that tries each endpoint in the order the peer
  * offered it and stops at the first success.
@@ -432,7 +481,7 @@ export enum SenderKind {
  *   the scanner must fetch the actual keys over the wire via the `PrePair`
  *   round-trip and verify them against the commitment before pairing.
  * - `NoKeys`: no key material and no commitment. The contact carries only
- *   `channel_id`, `nonce`, and `transport_protocol` — small enough to be
+ *   `channel_id`, `nonce`, and `supported_transports` — small enough to be
  *   hand-typed or dictated. Keys are generated on the fly by the contact
  *   creator when the `PrePairRequest` arrives; the scanner accepts them
  *   without cryptographic verification. Trust rests entirely on the OOB
@@ -474,20 +523,33 @@ export enum FlowKind {
   UnpairReplica = 8,
 }
 
+/** Result status carried in every protocol response (`result.proto`). Passed
+ *  to `reject()` to say why an inbound request was refused. */
+export enum StatusEnum {
+  Ok = 0,
+  Partial = 1,
+  Fail = 2,
+  SizeLimitExceeded = 3,
+  TooFrequent = 4,
+  UnknownSecretId = 5,
+  UnknownShareVersion = 6,
+  DecryptionFailed = 7,
+  VerificationFailed = 8,
+  FormatError = 9,
+  Rejected = 10,
+  IncompatibleParameterRange = 11,
+  UnsupportedTransportProtocol = 12,
+  VersionConflict = 13,
+  ReplicaIdConflict = 14,
+  RequestToClose = 99,
+}
+
 export type UnpairAck = "required" | "not_required";
 
 export interface ContactMessage {
   channel_id: bigint;
   /** `ContactMode` numeric value (0 = INLINE_KEYS, 1 = HASHED_KEYS, 2 = NO_KEYS). */
   contact_mode: number;
-  /**
-   * @deprecated Reading this field directly is incorrect: its meaning narrowed
-   * to "one entry of a list, and possibly absent", so a peer advertising only
-   * `supported_transports` looks unreachable to a reader that was correct
-   * before 0.0.3. Call {@link advertisedEndpoints}, which resolves both
-   * spellings. Removed at 0.0.5.
-   */
-  transport_protocol?: TransportProtocol;
   nonce: bigint;
   /** Present only when `contact_mode === ContactMode.InlineKeys`. */
   mlkem_encapsulation_key?: Uint8Array;
@@ -497,8 +559,7 @@ export interface ContactMessage {
   contact_binding_hash?: Uint8Array;
   timestamp?: Timestamp;
   /** Every transport endpoint the creator of this contact can be reached
-   *  on, in its own preference order. Empty means "only
-   *  `transport_protocol` is offered". */
+   *  on, in its own preference order. */
   supported_transports: TransportProtocol[];
 }
 
@@ -546,20 +607,11 @@ export interface UpdateChannelInfoParams {
    *  map untouched; pass an empty object to clear it. */
   communication_info?: Record<string, string>;
 
-  /**
-   * New transport endpoint. Absent leaves it untouched.
-   *
-   * @deprecated Use `own_transports`, which carries every endpoint this node
-   * now serves; its first entry also fills this field for peers predating the
-   * list. Removed at 0.0.5.
-   */
-  transport_protocol?: { uri: string; protocol: number };
   /**
    * Every endpoint this node now serves, in its own preference order.
-   * Omitted leaves the target(s)' stored set untouched. Takes precedence
-   * over `transport_protocol`, whose first entry it also fills.
+   * Omitted leaves the target(s)' stored set untouched.
    */
-  own_transports?: TransportProtocol[];
+  own_transports?: Endpoint[];
 }
 
 /**
@@ -592,6 +644,15 @@ export interface Timeouts {
  *  are both read from the stores. The argument may be omitted entirely. */
 export type ReplicaDiscoveryParams = Record<string, never>;
 
+/** Any member may remove any member, the source included: a lost or stolen
+ *  source must be removable by the devices that remain, and the library
+ *  checks no role. Ask the user before starting this flow, above all when it
+ *  names the source. Removing the source promotes the first remaining member
+ *  in the order the channel store's `listReplicas` returns. The removed
+ *  member is not asked and gets no event when told to leave: when a roster
+ *  excluding it arrives it drops its whole `secret_id` partition and emits
+ *  `SelfRemovedFromGroup`. The secret survives on the remaining members and
+ *  the helpers. */
 export interface UnpairReplicaParams {
   /** The member to remove, as a **decimal** `u64` string — the same form
    *  `ReplicaPaired.peer_replica_id` hands back. A value naming no current
@@ -618,18 +679,34 @@ export type DeRecEvent =
       action: Uint8Array;
 
       action_kind: PendingActionKind;
+      /** Correlation token of the inbound request, decimal-encoded. */
+      trace_id: string;
+      /** Pairing only. */
       peer_communication_info?: Record<string, string>;
-
+      /** `sender_kind` of the inbound pair request (Pairing only). */
       sender_kind?: SenderKind;
-
+      /** Share version (StoreShare / VerifyShare / GetShare). */
       version?: number;
+      /** Description of the secret version (StoreShare only). */
       share_description?: string;
-
+      /** Secret identifier, decimal-encoded (StoreShare / VerifyShare /
+       *  GetShare). On GetShare, with `version`, names the requested share. */
       share_secret_id?: string;
+      /** Length in bytes of the share the helper would store (StoreShare
+       *  only) — what a size or quota decision is made on. */
+      share_size?: number;
+      /** The peer's memo (Unpair only). */
+      unpair_memo?: string;
+      /** Communication info the peer replaces its stored map with
+       *  (UpdateChannelInfo only). Absent: unchanged. Empty: cleared. */
+      updated_communication_info?: Record<string, string>;
+      /** Endpoints the peer is moving to (UpdateChannelInfo only). Absent:
+       *  unchanged. */
+      updated_transports?: Endpoint[];
     }
   | { type: "ShareStored"; channel_id: string; version: number }
   | { type: "ShareConfirmed"; channel_id: string; version: number }
-  | { type: "ShareRejected"; channel_id: string; version: number; status: number; memo: string }
+  | { type: "ShareRejected"; channel_id: string; version: number; status: StatusEnum; memo: string }
   /** A publishing round finished — every targeted helper confirmed,
    *  rejected, or timed out.
    *
@@ -647,14 +724,17 @@ export type DeRecEvent =
   | { type: "SharingComplete"; version: number; confirmed_count: number; failed_count: number; threshold_met: boolean }
   /** A group member refused a secret sync. Keyed by `replica_id`, not
    *  `channel_id`: every member answers on the one group channel. A
-   *  `VERSION_CONFLICT` status means the round must be resolved and
-   *  republished at a new version. */
+   *  `VERSION_CONFLICT` status means another member holds a different copy
+   *  of this version: do not publish from this device again until the
+   *  conflict is resolved. Run `start(FlowKind.ReplicaDiscovery)` to receive
+   *  the group's copy as `ReplicaVersionConflict`, merge, and publish the
+   *  result once with `start(FlowKind.ProtectSecret)`. */
   | {
       type: "ReplicaSyncRejected";
       replica_id: string;
       secret_id: string;
       version: number;
-      status: number;
+      status: StatusEnum;
       memo: string;
     }
   /** A secret sync could not be delivered to a member at all — distinct from
@@ -671,7 +751,8 @@ export type DeRecEvent =
   /** This device left the group and dropped its whole `secret_id` partition —
    *  group channel, helper channels, shares, secrets and the snapshot. Fires
    *  only once it was told to leave *and* has since seen a roster excluding
-   *  it; absence alone never destroys a copy of the secret. */
+   *  it; absence alone never destroys a copy of the secret. The teardown is
+   *  automatic: this device is not asked first and gets no earlier event. */
   | { type: "SelfRemovedFromGroup"; version: number }
   /** A replica catch-up finished. `fetched_from` is absent when this device
    *  was already current, in which case no hydration event follows. */
@@ -687,6 +768,10 @@ export type DeRecEvent =
    *  library keeps no durable per-member sync state. */
   | { type: "ReplicaSyncComplete"; version: number; synced: string[]; behind: string[] }
   | { type: "ShareVerified"; channel_id: string; version: number }
+  /** A helper refused a verification challenge: its response carried a
+   *  non-OK `status` instead of a proof. The challenge is spent; a new
+   *  `VerifyShares` round challenges the helper again. */
+  | { type: "ShareVerifyRejected"; channel_id: string; version: number; status: StatusEnum; memo: string }
   | {
       type: "SecretsDiscovered";
       channel_id: string;
@@ -695,6 +780,22 @@ export type DeRecEvent =
     }
   | { type: "RecoveryShareReceived"; channel_id: string; shares_received: number }
   | { type: "RecoveryShareError"; channel_id: string; shares_received: number; error: string }
+  /** A helper refused a recovery share request: its response carried a
+   *  non-OK `status` (e.g. `UNKNOWN_SHARE_VERSION`) instead of a share. The
+   *  refusal is not collected — it does not count towards `shares_received`
+   *  and the recovery stays open for the other helpers' shares — but it does
+   *  answer that helper's `RecoverSecretStarted`. */
+  | { type: "RecoveryShareRefused"; channel_id: string; version: number; status: StatusEnum; memo: string }
+  /** A helper answered with a share that cannot be part of the secret;
+   *  `reason` says how it failed. `Malformed` and `InvalidProof` are judged
+   *  on arrival; `Inconsistent` (valid on its own but disagreeing with the
+   *  shares the secret was rebuilt from) is reported alongside
+   *  `SecretRecovered`, once per helper. The share is set aside — it does
+   *  not count towards `shares_received` and never blocks the recovery. An
+   *  honest helper never sends one, so the app may treat it as a sign of a
+   *  damaged or compromised helper, e.g. offer to unpair it. It also
+   *  answers that helper's `RecoverSecretStarted`. */
+  | { type: "RecoveryShareCorrupted"; channel_id: string; version: number; reason: CorruptionReason }
   /** Recovery completed — the typed `Secret` snapshot the owner
    *  originally protected. Mirrors `ReplicaSecretReceived.secret`:
    *  `secrets` is the user-facing `Vec<UserSecret>` the application
@@ -707,9 +808,9 @@ export type DeRecEvent =
         helpers: Array<{
           channel_id: string;
           /** Every endpoint this peer advertised, in the order it offered them. */
-          transports: Array<{ uri: string; protocol: number }>;
+          transports: Endpoint[];
           shared_key: Uint8Array;
-          communication_info: Record<string, string>;
+          communication_info?: Record<string, string>;
         }>;
         secrets: Array<{
           id: Uint8Array;
@@ -729,9 +830,9 @@ export type DeRecEvent =
           members: Array<{
             replica_id: string;
             /** Every endpoint this peer advertised, in the order it offered them. */
-            transports: Array<{ uri: string; protocol: number }>;
+            transports: Endpoint[];
             role: "Source" | "Destination";
-            communication_info: Record<string, string>;
+            communication_info?: Record<string, string>;
           }>;
           shared_key: Uint8Array;
         };
@@ -740,12 +841,12 @@ export type DeRecEvent =
 
   | { type: "Unpaired"; channel_id: string }
 
-  | { type: "UnpairRejected"; channel_id: string; status: number; memo: string }
+  | { type: "UnpairRejected"; channel_id: string; status: StatusEnum; memo: string }
 
   /** Contact creator answered the scanner's `PrePairRequest` with a
    *  non-Ok status (HashedKeys flow). Distinct from a cryptographic
    *  hash mismatch, which surfaces as a thrown error from `process()`. */
-  | { type: "PrePairRejected"; channel_id: string; status: number; memo: string }
+  | { type: "PrePairRejected"; channel_id: string; status: StatusEnum; memo: string }
 
   /** Fires alongside `PairingCompleted` on replica-mode pair handshakes.
    *  `peer_replica_id` is the peer's `u64` as a **decimal** string,
@@ -763,22 +864,28 @@ export type DeRecEvent =
   /** A `ReplicaSource` peer pushed a secret sync on a
    *  `ReplicaDestination` channel. The library decoded the
    *  `ReplicaSecretPayload`; the app installs `secret.secrets` and
-   *  optionally uses `shares` for recovery. `from_replica_id` and the
-   *  `replica_id` fields inside `secret` are `u64` as **decimal**
-   *  strings. */
+   *  optionally uses `shares` for recovery. `from_replica_id`,
+   *  `author_replica_id` and the `replica_id` fields inside `secret` are
+   *  `u64` as **decimal** strings.
+   *
+   *  `from_replica_id` is the member this copy came from: the publisher on
+   *  a push, the serving member on a catch-up. `author_replica_id` is the
+   *  member that published `version`, or `null` when the serving member's
+   *  snapshot records none. */
   | {
       type: "ReplicaSecretReceived";
       channel_id: string;
       from_replica_id: string;
+      author_replica_id: string | null;
       secret_id: string;
       version: number;
       secret: {
         helpers: Array<{
           channel_id: string;
           /** Every endpoint this peer advertised, in the order it offered them. */
-          transports: Array<{ uri: string; protocol: number }>;
+          transports: Endpoint[];
           shared_key: Uint8Array;
-          communication_info: Record<string, string>;
+          communication_info?: Record<string, string>;
         }>;
         secrets: Array<{
           id: Uint8Array;
@@ -796,9 +903,9 @@ export type DeRecEvent =
           members: Array<{
             replica_id: string;
             /** Every endpoint this peer advertised, in the order it offered them. */
-            transports: Array<{ uri: string; protocol: number }>;
+            transports: Endpoint[];
             role: "Source" | "Destination";
-            communication_info: Record<string, string>;
+            communication_info?: Record<string, string>;
           }>;
           shared_key: Uint8Array;
         };
@@ -821,15 +928,16 @@ export type DeRecEvent =
       type: "ReplicaSecretInstalled";
       channel_id: string;
       from_replica_id: string;
+      author_replica_id: string | null;
       secret_id: string;
       version: number;
       secret: {
         helpers: Array<{
           channel_id: string;
           /** Every endpoint this peer advertised, in the order it offered them. */
-          transports: Array<{ uri: string; protocol: number }>;
+          transports: Endpoint[];
           shared_key: Uint8Array;
-          communication_info: Record<string, string>;
+          communication_info?: Record<string, string>;
         }>;
         secrets: Array<{
           id: Uint8Array;
@@ -847,9 +955,9 @@ export type DeRecEvent =
           members: Array<{
             replica_id: string;
             /** Every endpoint this peer advertised, in the order it offered them. */
-            transports: Array<{ uri: string; protocol: number }>;
+            transports: Endpoint[];
             role: "Source" | "Destination";
-            communication_info: Record<string, string>;
+            communication_info?: Record<string, string>;
           }>;
           shared_key: Uint8Array;
         };
@@ -859,6 +967,59 @@ export type DeRecEvent =
         committed_share: Uint8Array;
       }>;
     }
+  /** A member offered a different copy of the version this device holds.
+   *  Nothing was written: this device keeps its own copy and refuses the
+   *  incoming one with `VERSION_CONFLICT`, so the publisher sees
+   *  `ReplicaSyncRejected`. Both copies are complete states — the held one
+   *  is in the local stores, the incoming one is `secret`. Resolve by
+   *  publishing the chosen state with `start(FlowKind.ProtectSecret)`; the
+   *  next version supersedes both on every member and helper. Until then,
+   *  do not publish from this device: any further `ProtectSecret` is a
+   *  higher version that every other member applies over its own copy,
+   *  losing the change it never merged.
+   *
+   *  `held_author_replica_id` / `incoming_author_replica_id` are the
+   *  decimal `replica_id` of each copy's publisher, or `null` when that
+   *  copy records none. */
+  | {
+      type: "ReplicaVersionConflict";
+      channel_id: string;
+      from_replica_id: string;
+      secret_id: string;
+      version: number;
+      held_author_replica_id: string | null;
+      incoming_author_replica_id: string | null;
+      secret: {
+        helpers: Array<{
+          channel_id: string;
+          /** Every endpoint this peer advertised, in the order it offered them. */
+          transports: Endpoint[];
+          shared_key: Uint8Array;
+          communication_info?: Record<string, string>;
+        }>;
+        secrets: Array<{
+          id: Uint8Array;
+          name: string;
+          data: Uint8Array;
+        }>;
+        /** The same shape as `SecretRecovered.secret.replicas`. */
+        replicas?: {
+          /** The one channel every member is addressed on. */
+          channel_id: string;
+          /** Every member of the group, including the writer. Exactly one
+           *  carries `role: "Source"` — that member is where the secret
+           *  originated, which is why no separate owner field is needed. */
+          members: Array<{
+            replica_id: string;
+            /** Every endpoint this peer advertised, in the order it offered them. */
+            transports: Endpoint[];
+            role: "Source" | "Destination";
+            communication_info?: Record<string, string>;
+          }>;
+          shared_key: Uint8Array;
+        };
+      };
+    }
   /** Peer's ack of a secret sync we sent. `status` is the `StatusEnum`
    *  integer (0 = Ok), `memo` is the peer's explanation. */
   | {
@@ -867,7 +1028,7 @@ export type DeRecEvent =
       from_replica_id: string;
       secret_id: string;
       version: number;
-      status: number;
+      status: StatusEnum;
       memo: string;
     }
   /** A peer announced an updated `communication_info` map and/or
@@ -884,7 +1045,7 @@ export type DeRecEvent =
   | {
       type: "ChannelInfoUpdateRejected";
       channel_id: string;
-      status: number;
+      status: StatusEnum;
       memo: string;
     }
   /** Emitted by `process()` in place of `ActionRequired` when the
@@ -896,6 +1057,38 @@ export type DeRecEvent =
    *  (`"Pairing"`, `"StoreShare"`, …). */
   | { type: "AutoAccepted"; channel_id: string; action_kind: PendingActionKind }
   | { type: "NoOp" }
+  /** An inbound message was dropped untouched: no store was written and
+   *  nothing was sent back. `reason` says why.
+   *
+   *  `"PendingVerification"` means the peer sent something before this
+   *  device confirmed the channel's fingerprint — typically a replica source
+   *  pushing its first copy while this destination still shows the code.
+   *  Confirming does not replay it: after `verifyFingerprint` succeeds, a
+   *  replica destination calls `start(FlowKind.ReplicaDiscovery)` to pull
+   *  the copy itself. `"Expired"` means the message was older than the
+   *  inbound timeout. `trace_id` matches the peer's `*Started` event for
+   *  the same round (`"0"` when the sender set none). */
+  | {
+      type: "MessageIgnored";
+      channel_id: string;
+      reason: IgnoreReason;
+      trace_id: string;
+    }
+  /** Returned by `restore`: a roster entry got no channel, so this device
+   *  cannot reach that peer. Every other entry and the user-secret snapshot
+   *  were restored; `reason` says why this one was not. `"NoTransports"`
+   *  means the recovered roster names no endpoint for it.
+   *
+   *  For a helper, `channel_id` is its channel and `replica_id` is absent.
+   *  For a replica group member, `channel_id` is the group's channel and
+   *  `replica_id` names the member. The peer itself is untouched — a helper
+   *  still holds its share — and pairing with it again makes it reachable. */
+  | {
+      type: "PeerNotRestored";
+      channel_id: string;
+      replica_id?: string;
+      reason: NotRestoredReason;
+    }
   /** A pairing handshake was dispatched successfully. `kind` is the
    *  local party's role — same value the subsequent `PairingCompleted`
    *  will carry. Emitted by `start(Pairing)`. */
@@ -964,8 +1157,8 @@ export type DeRecEvent =
  *   inbound shares. The protocol enforces no size, quota or rate limit
  *   of its own, and `maxShareSize` is checked for range overlap at
  *   pairing time only, never against an actual share. While this is
- *   `false`, `ActionRequired` carries the decoded request, so the
- *   application can inspect the share and call `reject()` with
+ *   `false`, `ActionRequired` carries `share_size`, so the application
+ *   can compare it to its quota and call `reject()` with
  *   `StatusEnum.SizeLimitExceeded`. Setting it `true` removes that
  *   opportunity entirely: every share from every paired Owner is stored
  *   unconditionally, at whatever size it arrives. Keep off in any
@@ -993,10 +1186,23 @@ export interface AutoAcceptPolicy {
  * between them without reaching for reference docs.
  *
  * Required setters: `withChannelStore`, `withShareStore`,
- * `withSecretStore`, `withTransport`, and either `withOwnTransport` or
- * `withOwnTransports`. Calling `build()` without all five throws.
+ * `withSecretStore`, `withUserSecretStore`, `withStateStore`,
+ * `withTransport`, and `withOwnTransports`. Calling `build()` without all
+ * seven throws.
+ *
+ * An optional setter that is never called leaves the library's default in
+ * force.
  */
 export declare class DeRecProtocolBuilder {
+  /**
+   * Release the builder's memory in the library. `build()` already releases
+   * it; call this only for a builder that is discarded unbuilt. Safe to call
+   * more than once.
+   */
+  free(): void;
+  /** Same as {@link DeRecProtocolBuilder.free}, for `using`. */
+  [Symbol.dispose](): void;
+
   /**
    * Construct a builder bound to a specific secret. `secretId`
    * identifies the single secret this protocol instance manages.
@@ -1011,33 +1217,21 @@ export declare class DeRecProtocolBuilder {
   withUserSecretStore(store: UserSecretStore): DeRecProtocolBuilder;
   withStateStore(store: StateStore): DeRecProtocolBuilder;
   withTransport(transport: Transport): DeRecProtocolBuilder;
-  /**
-   * @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 }): DeRecProtocolBuilder;
   /**
    * Set every transport endpoint this application serves, in preference
    * order. `protocol` is `"https"` or `"grpc"` (case-insensitive) per
-   * entry, same as {@link withOwnTransport}.
+   * entry.
    *
    * The order is this application's own preference and decides which of
    * a peer's offered endpoints is used; it is not sorted, deduplicated,
    * or reordered. Every listed transport must actually be served,
    * because delivery is push-only — listing an endpoint this application
    * does not serve makes pairing succeed and replies vanish.
-   *
-   * Supersedes {@link withOwnTransport} for applications serving more
-   * than one transport; the single-endpoint setter remains fully
-   * supported.
    */
-  withOwnTransports(transports: { uri: string; protocol: string }[]): DeRecProtocolBuilder;
+  withOwnTransports(transports: Endpoint[]): DeRecProtocolBuilder;
 
-  /** Default: 3. */
+  /** Minimum number of shares required to reconstruct the secret. Default: 3. */
   withThreshold(threshold: number): DeRecProtocolBuilder;
-  /** Default: 3. */
-  withKeepVersionsCount(count: number): DeRecProtocolBuilder;
   /**
    * Configure how long the protocol waits on each thing that can keep it
    * waiting. Every field is optional and **absent means "keep the library
@@ -1055,8 +1249,8 @@ export declare class DeRecProtocolBuilder {
   withTimeouts(timeouts: Timeouts): DeRecProtocolBuilder;
 
   /**
-   * Accept plaintext `http://` transport endpoints. **Development only.**
-   * Default: `false`.
+   * Accept plaintext `http://` and `grpc://` transport endpoints.
+   * **Development only.** Default: `false`.
    *
    * With `false`, plaintext is accepted in exactly one situation: an endpoint
    * this device configured for **itself** that names loopback (`localhost`,
@@ -1072,33 +1266,20 @@ export declare class DeRecProtocolBuilder {
    * delivery is your `Transport`. Nothing here stops an application sending
    * plaintext — it governs which endpoints the protocol will record,
    * propagate to peers, and reply to.
-   *
-   * @deprecated Use {@link withUnsafeConnection}, which names both gated
-   * schemes. Removed at 0.0.5.
-   */
-  withUnsafeHttp(allow: boolean): DeRecProtocolBuilder;
-  /**
-   * Accept plaintext `http://` and `grpc://` transport endpoints.
-   * **Development only.** Default: `false`. Supersedes
-   * {@link withUnsafeHttp}, which names only the HTTP scheme.
-   *
-   * Either flag alone is honored. Setting both to disagreeing values fails
-   * construction with the error code `CONFLICTING_PLAINTEXT_OPT_IN` rather
-   * than resolving silently, because precedence would hand the decision to
-   * the flag being removed.
    */
   withUnsafeConnection(allow: boolean): DeRecProtocolBuilder;
   /** Default: empty. */
   withCommunicationInfo(info: Record<string, string>): DeRecProtocolBuilder;
   /** Default: false. */
   withAutoRespondOnFailure(enabled: boolean): DeRecProtocolBuilder;
-  /** Default: "required". */
+  /** Exactly `"required"` or `"not_required"`; any other string throws
+   *  `invalid_unpair_ack`. Default: `"required"`. */
   withUnpairAck(ack: UnpairAck): DeRecProtocolBuilder;
   /**
    * When `true`, every outbound channel-mode request stamps
-   * `request.replyTo = ownTransport` so the responder routes its reply
-   * back here even if the channel's stored peer endpoint points
-   * elsewhere. Default: false.
+   * `request.reply_to` with this node's own transports so the responder
+   * routes its reply back here even if the channel's stored peer endpoint
+   * points elsewhere. Default: false.
    */
   withAutoReplyTo(enabled: boolean): DeRecProtocolBuilder;
   /**
@@ -1113,7 +1294,8 @@ export declare class DeRecProtocolBuilder {
   /**
    * Stable per-device replica id. Required to participate in any
    * `ReplicaSource` / `ReplicaDestination` pairing. The id must be
-   * stable across restarts. Default: unset.
+   * stable across restarts: mint it once with {@link generate_replica_id}
+   * and persist it. Default: unset.
    */
   withReplicaId(id: bigint | number): DeRecProtocolBuilder;
   /**
@@ -1136,10 +1318,33 @@ export declare class DeRecProtocolBuilder {
   build(): DeRecProtocol;
 }
 
+/**
+ * Every method that touches protocol state returns a `Promise` and runs under
+ * one lock per instance, so overlapping calls on the same instance — a `tick`
+ * timer firing while `process` handles an inbound message — queue and run one
+ * at a time, in the order they were made. Distinct instances do not share the
+ * lock: two instances bound to the same `secretId` and the same stores must
+ * still be serialized by the caller.
+ *
+ * A store or transport callback must not await a call on the instance that
+ * invoked it: that call queues behind the one waiting on the callback, and
+ * neither settles. Calling `free()` while a call is in flight throws.
+ */
 export declare class DeRecProtocol {
   /** Use {@link DeRecProtocolBuilder} to construct instances. */
   private constructor();
 
+  /**
+   * Release this protocol's memory in the library, and its references to the
+   * stores and transport. The library's memory is not reclaimed by the
+   * JavaScript garbage collector in time to rely on, so call this when done.
+   * Safe to call more than once; any other method called afterwards throws,
+   * as does calling this while a call is in flight.
+   */
+  free(): void;
+  /** Same as {@link DeRecProtocol.free}, for `using`. */
+  [Symbol.dispose](): void;
+
   /** The secret identifier this protocol instance is bound to. */
   secretId(): bigint;
 
@@ -1152,8 +1357,8 @@ export declare class DeRecProtocol {
    *                     directly in the contact. `ContactMode.HashedKeys`
    *                     embeds only a SHA-384 binding hash (keys are
    *                     fetched later via the `PrePair` round-trip).
-   *                     `HashedKeys` requires `ownTransportUri` to be
-   *                     ephemeral.
+   *                     `HashedKeys` requires the advertised own
+   *                     transports to be ephemeral.
    */
   /**
    * Single entry point for all three `ContactMode` variants.
@@ -1197,29 +1402,11 @@ export declare class DeRecProtocol {
    * contact peers — follow up with
    * <c>start(FlowKind.UpdateChannelInfo, ...)</c> to propagate.
    */
-  setCommunicationInfo(info: Record<string, string>): 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.
-   *
-   * IMPORTANT: keep the old endpoint operational during the changeover
-   * (see the Rust docs on the matching setter for the discipline).
-   *
-   * @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): void;
+  setCommunicationInfo(info: Record<string, string>): Promise<void>;
 
   /**
    * Replace every endpoint this node advertises, in preference order —
-   * the runtime counterpart to <c>withOwnTransports</c>, and the way to
-   * change the whole set (<c>setOwnTransport</c> replaces only the entry
-   * for the protocol its URI names).
+   * the runtime counterpart to `withOwnTransports`.
    *
    * A node serves at most one endpoint per protocol, so this list is a
    * preference order over distinct protocols. Two entries of the same
@@ -1228,7 +1415,7 @@ export declare class DeRecProtocol {
    * Every entry is validated before any is stored, so a malformed URI
    * leaves the previous set intact. An empty array is rejected.
    */
-  setOwnTransports(transports: { uri: string; protocol: string }[]): void;
+  setOwnTransports(transports: Endpoint[]): Promise<void>;
 
   process(message: Uint8Array): Promise<DeRecEvent[]>;
 
@@ -1242,14 +1429,14 @@ export declare class DeRecProtocol {
    * shorter than the configured timeout.
    *
    * Safe to call at any time; with nothing in flight it resolves to an empty
-   * array. It mutates the same round state an inbound response does, so it
-   * must be serialized against `process` for the same `secretId`.
+   * array. Overlapping calls with `process` on the same instance queue
+   * rather than collide.
    */
   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>;
 
   /**
    * Derive the human-readable fingerprint for a paired channel. Both sides
@@ -1264,6 +1451,11 @@ export declare class DeRecProtocol {
    * 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.
    */
   verifyFingerprint(channelId: bigint | number, fingerprint: string): Promise<boolean>;
   /**
@@ -1274,23 +1466,36 @@ export declare class DeRecProtocol {
    * threshold given even when that policy is disabled. The age comparison
    * is strict, so a channel created within the current second survives
    * even `0`.
+   *
+   * `olderThanSecs` is a `u64`: a `bigint`, a non-negative safe-integer
+   * `number`, or a decimal string. Anything else throws `decode_error`.
    */
-  removeExpiredChannels(olderThanSecs: number): Promise<string[]>;
+  removeExpiredChannels(olderThanSecs: bigint | number | string): Promise<string[]>;
 
   /**
    * Rebuild this protocol's `secret_id` namespace from a recovered
    * `Secret`. Mirrors the Rust `DeRecProtocol::restore` — pass the
    * typed `secret` carried by the `SecretRecovered` event verbatim.
    *
-   * Errors surface as structured objects with a `code` field:
+   * 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.
+   *
+   * Errors surface as a `DeRecError` (`category`, `code`, `message`):
    *
    * | code               | meaning                                                          |
    * |--------------------|------------------------------------------------------------------|
-   * | `ALREADY_RESTORED` | A user-secret snapshot already exists for this `secret_id`.      |
-   * | `CONFLICT`         | Channels live at canonical helper / replica ids. The error       |
+   * | `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.          |
-   * | `INVARIANT`        | The recovered `Secret` is internally inconsistent.               |
-   * | `STORAGE`          | A store I/O call failed mid-restore.                             |
+   * | `invariant`        | The recovered `Secret` is internally inconsistent.               |
+   * | `invalid_recovered_secret` | `recoveredSecret` is malformed — e.g. a missing or       |
+   * |                    | non-decimal `channel_id` / `replica_id`.                         |
+   * | `store_error`      | A store call failed mid-restore; `category` names the store.     |
    */
   restore(
     recoveredSecret: Extract<DeRecEvent, { type: "SecretRecovered" }>["secret"],
@@ -1397,6 +1602,22 @@ export interface CommunicationInfo {
  * protocol can raise. Matches the Rust `PendingActionKind` discriminants
  * one-for-one.
  */
+/** Why a `MessageIgnored` event dropped a message. Matches the Rust
+ *  `IgnoreReason` discriminants one-for-one. */
+export type IgnoreReason = "PendingVerification" | "Expired";
+
+/** Why a `PeerNotRestored` event left a roster entry without a channel.
+ *  Matches the Rust `NotRestoredReason` discriminants one-for-one. */
+export type NotRestoredReason = "NoTransports";
+
+/** Why a `RecoveryShareCorrupted` event set a helper's share aside.
+ *  Matches the Rust `CorruptionReason` discriminants one-for-one:
+ *  `Malformed` — no decodable share for the requested secret and version;
+ *  `InvalidProof` — the share fails its own Merkle proof;
+ *  `Inconsistent` — valid on its own, but its commitment root or ciphertext
+ *  disagrees with the shares the secret was rebuilt from. */
+export type CorruptionReason = "Malformed" | "InvalidProof" | "Inconsistent";
+
 export type PendingActionKind =
   | "Pairing"
   | "PrePair"
@@ -1427,17 +1648,9 @@ export interface PairRequestMessage {
   nonce: bigint;
   communication_info?: CommunicationInfo;
   parameter_range?: ParameterRange;
-  /**
-   * @deprecated Reading this field directly is incorrect: its meaning narrowed
-   * to "one entry of a list, and possibly absent", so a peer advertising only
-   * `supported_transports` looks unreachable to a reader that was correct
-   * before 0.0.3. Call {@link advertisedEndpoints}, which resolves both
-   * spellings. Removed at 0.0.5.
-   */
-  transport_protocol?: TransportProtocol;
   timestamp?: Timestamp;
   /** Every transport endpoint the initiator can be reached on, in its own
-   *  preference order. Empty means "only `transport_protocol` is offered". */
+   *  preference order. */
   supported_transports: TransportProtocol[];
 }
 
@@ -1459,21 +1672,12 @@ export interface PairResponseMessage {
 
 export interface PrePairRequestMessage {
   nonce: bigint;
-  /**
-   * @deprecated Reading this field directly is incorrect: its meaning narrowed
-   * to "one entry of a list, and possibly absent", so a peer advertising only
-   * `supported_transports` looks unreachable to a reader that was correct
-   * before 0.0.3. Call {@link advertisedEndpoints}, which resolves both
-   * spellings. Removed at 0.0.5.
-   */
-  transport_protocol?: TransportProtocol;
   timestamp?: Timestamp;
   /**
    * Every endpoint the sender can be reached on for the PrePair reply, in
-   * its own preference order. At least one of this and `transport_protocol`
-   * must be present.
+   * its own preference order.
    */
-  supported_transports?: TransportProtocol[];
+  supported_transports: TransportProtocol[];
 }
 
 export interface PrePairResponseMessage {
@@ -1659,6 +1863,15 @@ export interface ProducePrePairResult {
   envelope: Uint8Array;
 }
 
+export interface ProducePrePairNoKeysResult {
+
+  envelope: Uint8Array;
+
+  /** Secret key material generated for this pairing. The caller MUST persist
+   * it: the `PairRequest` that follows is encrypted to it. */
+  secret_key_material: Uint8Array;
+}
+
 export interface PrePairRequestExtractResult {
 
   request: PrePairRequestMessage;
@@ -1711,6 +1924,7 @@ export type DeRecErrorCategory =
   | "secret_store"
   | "channel_store"
   | "share_store"
+  | "state_store"
   | "input"
   | "protobuf"
   | "invariant"
@@ -1724,6 +1938,16 @@ export interface DeRecError {
   memo?: string;
   expected?: number;
   got?: number;
+  /** The channel the failing inbound message arrived on, when `process()` could tell. */
+  channel_id?: string;
+  /**
+   * On a failed `process()`: the events it produced before failing, such as
+   * sharing-round and unpair timeouts. They are not reported again, so
+   * handle them as you would a successful call's events.
+   */
+  events?: DeRecEvent[];
+  /** On a `restore` `CONFLICT`: the pre-existing channels at canonical ids. */
+  channel_ids?: string[];
 }
 
 export declare const primitives: {
@@ -1758,16 +1982,32 @@ export declare const primitives: {
        *                      commitment and the scanner must complete a
        *                      `PrePair` round-trip first.
        * @param transport_protocols  Every endpoint this initiator serves, in
-       *                             preference order. The first also fills the
-       *                             legacy singular field. For `HashedKeys`
-       *                             mode they MUST be ephemeral.
+       *                             preference order. For `HashedKeys` mode
+       *                             they MUST be ephemeral.
+       * @param nonce  Correlation nonce embedded in the contact. Omitted or
+       *               `null`, the library draws a random `u64` — the right
+       *               choice for `InlineKeys` / `HashedKeys`, where the nonce
+       *               is a security parameter. Required for `ContactMode.NoKeys`,
+       *               where the caller typically picks a short human-typable
+       *               value for manual entry. Must fit in a `u64`.
        */
       create_contact(
         channel_id: bigint,
         contact_mode: ContactMode | number,
         transport_protocols: TransportProtocol[],
+        nonce?: bigint | number | null,
       ): CreateContactResult;
+      /**
+       * Serializes a `ContactMessage` to the bytes delivered out of band.
+       * Throws on a contact that violates the invariants of its contact mode
+       * or advertises no endpoint.
+       */
       encode_contact(contact_message: ContactMessage): Uint8Array;
+      /**
+       * Parses out-of-band contact bytes back into a `ContactMessage`. Throws
+       * on bytes that are not a contact, or a contact that violates the
+       * invariants of its contact mode.
+       */
       decode_contact(bytes: Uint8Array): ContactMessage;
       produce(
         kind: SenderKind,
@@ -1777,7 +2017,17 @@ export declare const primitives: {
         parameter_range: ParameterRange | null,
       ): PairingRequestProduceResult;
 
-      extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): { request: PairRequestMessage };
+      /**
+       * @param parameter_range  The range this side accepts, or `null` for
+       *                         none. A request advertising a range that does
+       *                         not overlap it is refused with
+       *                         `incompatible_parameter_range`.
+       */
+      extract(
+        envelope_bytes: Uint8Array,
+        secret_key: Uint8Array,
+        parameter_range: ParameterRange | null,
+      ): { request: PairRequestMessage };
 
       /**
        * Scanner-side: build a plaintext `PrePairRequest` envelope when the
@@ -1789,8 +2039,6 @@ export declare const primitives: {
       /**
        * @param own_transports  Every endpoint this scanner serves for the
        *                        PrePair reply, in its own preference order.
-       *                        The first entry also fills the deprecated
-       *                        singular field for peers predating the list.
        */
       produce_pre_pair(
         own_transports: TransportProtocol[],
@@ -1805,6 +2053,10 @@ export declare const primitives: {
     };
     response: {
       /**
+       * @param parameter_range    The range this side accepts and advertises,
+       *                           or `null` for none. A request advertising a
+       *                           range that does not overlap it is refused
+       *                           with `incompatible_parameter_range`.
        * @param unsafe_connection  Accept plaintext peer endpoints
        *                           (`http://`, `grpc://`). Development only.
        */
@@ -1818,10 +2070,18 @@ export declare const primitives: {
       ): PairingResponseProduceResult;
 
       extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): { response: PairResponseMessage };
+      /**
+       * @param parameter_range  The range this side accepts, or `null` for
+       *                         none. A response advertising a range that
+       *                         does not overlap it is refused with
+       *                         `incompatible_parameter_range` before any key
+       *                         is derived.
+       */
       process(
         contact_message: ContactMessage,
         response: PairResponseMessage,
         secret_key: Uint8Array,
+        parameter_range: ParameterRange | null,
       ): PairingProcessResult;
 
       /**
@@ -1849,7 +2109,41 @@ export declare const primitives: {
         contact_message: ContactMessage,
         response: PrePairResponseMessage,
       ): ProcessPrePairResult;
+
+      /**
+       * Contact-creator side of a `NoKeys` pairing: generate key material and
+       * answer the `PrePairRequest` with its public half.
+       *
+       * The caller MUST first match the request's `nonce` against the contact
+       * it issued — the only thing that authenticates a `NoKeys` request — and
+       * MUST persist `secret_key_material`. The resulting channel MUST stay
+       * unusable until both sides confirm `pairing.fingerprint` out of band.
+       */
+      produce_pre_pair_no_keys(
+        channel_id: bigint,
+        request: PrePairRequestMessage,
+      ): ProducePrePairNoKeysResult;
+
+      /**
+       * Scanner side of a `NoKeys` pairing: accept the contact creator's
+       * public keys. There is no binding hash to check them against, so the
+       * resulting channel MUST stay unusable until both sides confirm
+       * `pairing.fingerprint` out of band. Throws on a non-`Ok` status, a
+       * missing key or a `nonce` mismatch.
+       */
+      process_pre_pair_no_keys(
+        contact_message: ContactMessage,
+        response: PrePairResponseMessage,
+      ): ProcessPrePairResult;
     };
+
+    /**
+     * The human-readable fingerprint of a pairing's 32-byte shared key. Both
+     * ends derive the same value; comparing it out of band confirms the
+     * pairing. A `NoKeys` pairing MUST be confirmed this way before use.
+     * Throws on a key that is not 32 bytes.
+     */
+    fingerprint(shared_key: Uint8Array): string;
   };
   recovery: {
     request: {