@derec-alliance/nodejs 0.0.4 → 0.0.6

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[]>;
 }
 
@@ -242,6 +231,17 @@ export interface Share {
   bytes: Uint8Array;
 }
 
+/**
+ * Share-record persistence.
+ *
+ * Rows are keyed by `(secretId, channelId, version)` where `secretId` is
+ * the partition passed to every method. `Share.secretId` is a different
+ * value: it names the secret the bytes belong to, which on a helper is
+ * the owner's id and routinely differs from the partition this device
+ * stores under. Key on the argument and carry `share.secretId` alongside
+ * as data — keying on it instead puts rows where no `load` looks, since
+ * every read filters on the partition.
+ */
 export interface ShareStore {
   load(secretId: string, channelId: string, versions: number[]): Promise<Share[]>;
   loadMany(
@@ -265,6 +265,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;
 }
 
 /**
@@ -308,6 +312,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.
  *
@@ -353,7 +369,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>;
 }
@@ -373,10 +389,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.
@@ -421,7 +452,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
@@ -463,20 +494,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;
@@ -486,8 +530,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[];
 }
 
@@ -535,20 +578,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[];
 }
 
 /**
@@ -607,18 +641,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.
    *
@@ -643,7 +693,7 @@ export type DeRecEvent =
       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
@@ -696,9 +746,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;
@@ -718,9 +768,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;
         };
@@ -729,12 +779,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,
@@ -752,22 +802,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;
@@ -785,9 +841,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;
         };
@@ -810,15 +866,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;
@@ -836,9 +893,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;
         };
@@ -848,6 +905,56 @@ 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.
+   *
+   *  `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. */
   | {
@@ -856,7 +963,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
@@ -873,7 +980,7 @@ export type DeRecEvent =
   | {
       type: "ChannelInfoUpdateRejected";
       channel_id: string;
-      status: number;
+      status: StatusEnum;
       memo: string;
     }
   /** Emitted by `process()` in place of `ActionRequired` when the
@@ -885,6 +992,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)`. */
@@ -953,8 +1092,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
@@ -982,10 +1121,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.
@@ -1000,32 +1152,22 @@ 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. */
+  /** Number of recent versions each helper must retain. Default: 3. */
   withKeepVersionsCount(count: number): DeRecProtocolBuilder;
   /**
    * Configure how long the protocol waits on each thing that can keep it
@@ -1044,8 +1186,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`,
@@ -1061,33 +1203,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;
   /**
@@ -1102,7 +1231,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;
   /**
@@ -1125,10 +1255,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;
 
@@ -1141,8 +1294,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.
@@ -1186,29 +1339,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
@@ -1217,7 +1352,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[]>;
 
@@ -1231,14 +1366,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
@@ -1263,23 +1398,32 @@ 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:
+   * 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"],
@@ -1386,6 +1530,14 @@ 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";
+
 export type PendingActionKind =
   | "Pairing"
   | "PrePair"
@@ -1416,17 +1568,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[];
 }
 
@@ -1448,21 +1592,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 {
@@ -1648,6 +1783,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;
@@ -1700,6 +1844,7 @@ export type DeRecErrorCategory =
   | "secret_store"
   | "channel_store"
   | "share_store"
+  | "state_store"
   | "input"
   | "protobuf"
   | "invariant"
@@ -1713,6 +1858,10 @@ 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 `restore` `CONFLICT`: the pre-existing channels at canonical ids. */
+  channel_ids?: string[];
 }
 
 export declare const primitives: {
@@ -1747,16 +1896,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,
@@ -1766,7 +1931,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
@@ -1778,8 +1953,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[],
@@ -1794,6 +1967,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.
        */
@@ -1807,10 +1984,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;
 
       /**
@@ -1838,7 +2023,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: {