@derec-alliance/nodejs 0.0.5 → 0.0.7

package/README.md

@@ -126,7 +126,7 @@ const request = primitives.pairing.request.produce(
 
 // Step 3: Initiator extracts the request and produces the response.
 const { request: pairRequest } =
-  primitives.pairing.request.extract(request.envelope, contact.secret_key);
+  primitives.pairing.request.extract(request.envelope, contact.secret_key, null);
 const produced = primitives.pairing.response.produce(
   channelId,
   pairRequest,
@@ -141,6 +141,7 @@ const processed = primitives.pairing.response.process(
   request.initiator_contact_message,
   pairResponse,
   request.secret_key,
+  null,
 );
 
 // Both sides hold the same shared key and rekeyed channel id.
@@ -227,7 +228,7 @@ The orchestrator handles the whole chain automatically:
   `ActionRequired` event with `action_kind: "PrePair"`. Call
   `protocol.accept(action)` to publish the keys (the library builds the
   response and routes it), or `protocol.reject(action, status, memo)` to
-  refuse.
+  refuse — `status` is a `StatusEnum` value such as `StatusEnum.Rejected`.
 - **Scanner** — `protocol.start(FlowKind.Pairing, { kind, contact })` kicks
   off the plaintext PrePair leg. `start()` returns a `DeRecEvent[]`
   containing one `PairingStarted { channel_id, kind }` event that
@@ -316,12 +317,22 @@ const recovered = primitives.recovery.response.recover(
 // `recovered` is a Uint8Array carrying the reconstructed secret payload.
 ```
 
-When driving the protocol layer instead of the primitives, the recovering
-device receives a `SecretRecovered` event carrying the typed `secret`. Pass it
+When driving the protocol layer instead of the primitives, a helper that
+answers with a share that cannot be part of the secret is reported as a
+`RecoveryShareCorrupted` event (`reason`: `"Malformed"`, `"InvalidProof"` or
+`"Inconsistent"`); the share is set aside and never blocks the recovery from
+the others. An honest helper never sends one, so treat it as a sign of a
+damaged or compromised helper — for example, offer to unpair it.
+
+The recovering device receives a `SecretRecovered` event carrying the typed
+`secret`. Pass it
 to `protocol.restore(secret, version)` on a fresh `DeRecProtocol` instance to
 commit canonical helper / replica state and wipe the throwaway recovery-mode
 channels — at that point the device resumes normal operation as if the secret
 had been protected here originally.
+A helper or member with no endpoint in the recovered roster gets no channel;
+`restore` returns a `PeerNotRestored` event for it (`reason: "NoTransports"`)
+and restores the rest.
 
 ```ts
 const events = await protocol.process(responseBytes);
@@ -332,8 +343,10 @@ for (const ev of events) {
 }
 ```
 
-Errors surface as objects with a `code` field — `ALREADY_RESTORED`,
-`CONFLICT` (with `channel_ids`), `INVARIANT`, or `STORAGE`.
+Errors surface as a `DeRecError` with a `category` and `code` —
+`already_restored`, `restore_conflict` (with `channel_ids`), `invariant`,
+`invalid_recovered_secret` (a malformed `secret`), or `store_error` (a store call failed; `category`
+names the store).
 
 > **Secret format:** the recoverable secret (the bytes helpers store and
 > recovery reconstructs) is `[version byte] · payload` — v1's payload is
@@ -380,6 +393,12 @@ console.log("Valid:", isValid);
 - No protobuf types are exposed
 - No cryptographic operations occur in JavaScript
 - Rust is the single source of truth
+- Every `DeRecProtocol` method that touches protocol state returns a
+  `Promise`, including the `set*` setters. Overlapping calls on one
+  instance — a `tick()` timer firing while `process()` handles a message —
+  queue and run in the order they were made; they never collide. A store
+  or transport callback must not await a call on the instance that
+  invoked it, since that call waits behind the callback's own caller.
 
 ---
 
@@ -392,14 +411,18 @@ side runs as `SenderKind.ReplicaSource` (owns the secret), the other as
 with a stable `replicaId`:
 
 ```ts
-const owner = new DeRecProtocol(
-  channelStore, shareStore, secretStore, transport,
-  "https://owner.example.com", "https",
-  /* threshold */ 2, /* keepVersionsCount */ 3,
-  { name: "Owner" },
-  null, null, null, null,
-  /* replicaId */ 0xAAAA_AAAA_AAAA_AAAAn,
-);
+const owner = new DeRecProtocolBuilder(secretId)
+  .withChannelStore(channelStore)
+  .withShareStore(shareStore)
+  .withSecretStore(secretStore)
+  .withUserSecretStore(userSecretStore)
+  .withStateStore(stateStore)
+  .withTransport(transport)
+  .withOwnTransports([{ uri: "https://owner.example.com", protocol: "https" }])
+  .withThreshold(2)
+  .withCommunicationInfo({ name: "Owner" })
+  .withReplicaId(0xAAAA_AAAA_AAAA_AAAAn)
+  .build();
 ```
 
 A typical Source↔Destination handshake:
@@ -452,6 +475,27 @@ End-to-end coverage lives in the repository's tests — see
 
 ---
 
+## When `process()` fails
+
+`process()` settles expired deadlines (sharing-round and unpair timeouts)
+before it handles the message, and those are never reported again. So when
+the message then fails, the thrown `DeRecError` carries them: `events` holds
+every event produced before the failure, and `channel_id` names the channel
+the message came from (absent when the bytes were not a decodable envelope).
+Handle the events as you would a successful call's, then the error:
+
+```ts
+try {
+  handle(await protocol.process(bytes));
+} catch (error) {
+  const failure = error as DeRecError;
+  handle(failure.events ?? []);
+  report(failure.channel_id, failure);
+}
+```
+
+---
+
 ## Correlation and routing
 
 Two cross-cutting metadata fields appear on every channel-mode exchange:
@@ -461,13 +505,13 @@ Two cross-cutting metadata fields appear on every channel-mode exchange:
   end-to-end (random token on every outbound request, echo on every
   response). Primitive-only callers can manipulate it directly via
   `envelope.apply_trace_id(bytes, traceId)` and `envelope.read_trace_id(bytes)`.
-- **`replyTo`** — optional `TransportProtocol` on request bodies, telling
-  the responder to route this exchange's response to an alternate endpoint.
+- **`replyTo`** — optional `TransportProtocol` list on request bodies, telling
+  the responder to route this exchange's response to alternate endpoints.
   Set it per call (every `primitives.*.request.produce` takes a trailing
   `reply_to` arg) or protocol-wide with the `autoReplyTo` constructor flag
-  on `DeRecProtocol` (stamps `replyTo = ownTransport` on every outbound
-  request). Excludes pairing and `UpdateChannelInfo`, which already carry
-  their own `transportProtocol` field.
+  on `DeRecProtocol` (stamps this node's own transports into `replyTo` on
+  every outbound request). Excludes pairing and `UpdateChannelInfo`, which
+  already carry their own `supportedTransports` field.
 
 The motivating case for `replyTo` is replicas: when Replica A sends a
 request on a channel the helper paired with sibling Replica B, the
@@ -554,13 +598,16 @@ that you can retire as soon as the PrePair leg completes.
 
 The recommended pattern is: pair on the ephemeral URI, then — as soon
 as the pairing completes on the contact creator side — call
-`setOwnTransports` with the permanent endpoint (`setOwnTransport` is
-deprecated and removed at 0.0.5) and start an
+`setOwnTransports` with the permanent endpoint and start an
 `UpdateChannelInfo` flow against the peer to announce the swap. Once
 the peer acknowledges, retire the ephemeral URI. This keeps the
 plaintext PrePair window tight while letting subsequent traffic ride
 on the long-lived endpoint.
 
+`UpdateChannelInfo` reaches helper channels only. A replica member that
+changes its endpoint or `communication_info` publishes a new version first,
+then updates its helpers; see [On a replica member](https://github.com/derecalliance/lib-derec/tree/main/library#on-a-replica-member).
+
 ### Replica fingerprint verification is mandatory
 
 Replica channels are created with `status: "Pending"` and remain there
@@ -571,6 +618,15 @@ target is still `Pending`. Treat verification as a required step in
 the pairing UX — a scanner that auto-pairs without it accepts a
 MITM-vulnerable replica.
 
+Until a device confirms, it ignores everything the peer sends on that
+channel: `process` changes no store, sends nothing back, and returns
+`{ type: "MessageIgnored", channel_id, reason: "PendingVerification",
+trace_id }`. This matters most for a replica destination. The source's own
+confirmation publishes the vault immediately, so that copy usually arrives
+before the destination's user has confirmed. Confirming does not replay it:
+once the destination's `verifyFingerprint` resolves `true`, call
+`start(FlowKind.ReplicaDiscovery)` to pull the copy from the source.
+
 ### The `derec.*` namespace in `communicationInfo` is library-owned
 
 `communicationInfo` is otherwise an opaque app-defined map, but every

package/derec_library.d.ts

@@ -9,11 +9,12 @@
  * 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.
  *
- * All optional setters carry the defaults documented on the Rust
- * builder.
+ * An optional setter that is never called leaves the Rust builder's default
+ * in force: the value is forwarded only when the application supplied one.
  */
 export class DeRecProtocolBuilder {
     free(): void;
@@ -43,7 +44,7 @@ export class DeRecProtocolBuilder {
      */
     withAutoAccept(policy: any): DeRecProtocolBuilder;
     /**
-     * Whether outbound requests stamp `replyTo = ownTransport`.
+     * Whether outbound requests carry this node's own transports as their reply-to list.
      * Default: false.
      */
     withAutoReplyTo(enabled: boolean): DeRecProtocolBuilder;
@@ -57,34 +58,17 @@ export class DeRecProtocolBuilder {
      * `info` shape: `Record<string, string>`. Default: empty.
      */
     withCommunicationInfo(info: any): DeRecProtocolBuilder;
-    /**
-     * Number of recent versions each helper must retain. Default: 3.
-     */
-    withKeepVersionsCount(count: number): DeRecProtocolBuilder;
-    /**
-     * `endpoint` shape: `{ uri: string, protocol: string }`.
-     * `protocol` is `"https"` or `"grpc"` (case-insensitive).
-     *
-     * @deprecated Use `withOwnTransports`, which takes the whole preference
-     * list — `withOwnTransports([endpoint])` is the direct replacement.
-     * Removed at 0.0.5.
-     */
-    withOwnTransport(endpoint: any): DeRecProtocolBuilder;
     /**
      * Every transport endpoint this application serves, in preference
      * order. `transports` is an array of `{ uri: string, protocol: string
      * }` objects, `protocol` being `"https"` or `"grpc"`
-     * (case-insensitive), same shape as [`Self::with_own_transport`].
+     * (case-insensitive).
      *
      * The order is the application's own preference and decides which of
      * a peer's offered endpoints is used. 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 [`Self::with_own_transport`] for applications serving
-     * more than one transport; the single-endpoint setter remains fully
-     * supported.
      */
     withOwnTransports(transports: any[]): DeRecProtocolBuilder;
     /**
@@ -108,7 +92,7 @@ export class DeRecProtocolBuilder {
     withStateStore(store: any): DeRecProtocolBuilder;
     /**
      * Minimum number of shares required to reconstruct the secret.
-     * Default: 3.
+     * Default: [`crate::protocol::DEFAULT_THRESHOLD`].
      */
     withThreshold(threshold: number): DeRecProtocolBuilder;
     /**
@@ -133,18 +117,13 @@ export class DeRecProtocolBuilder {
     withTimeouts(timeouts: any): DeRecProtocolBuilder;
     withTransport(transport: any): DeRecProtocolBuilder;
     /**
-     * `ack` is `"required"` (default) or `"not_required"`.
+     * `ack` is exactly `"required"` (default) or `"not_required"`, naming
+     * [`UnpairAck::Required`] and [`UnpairAck::NotRequired`].
      */
     withUnpairAck(ack: string): DeRecProtocolBuilder;
     /**
      * Accept plaintext transport endpoints — `http://` and `grpc://`.
-     * **Development only.** Default `false`. See `withUnsafeHttp` for the
-     * conflict rule when both are set.
-     */
-    withUnsafeConnection(allow: boolean): DeRecProtocolBuilder;
-    /**
-     * Accept plaintext `http://` transport endpoints. **Development only.**
-     * Default `false`.
+     * **Development only.** Default `false`.
      *
      * With it `false`, plaintext is accepted only for an endpoint this
      * device configured for *itself* that names loopback (`localhost`,
@@ -152,11 +131,8 @@ export class DeRecProtocolBuilder {
      * With it `true`, plaintext is accepted for any host on any path,
      * including endpoints a peer supplies. That is what makes the LAN case
      * work (a phone against a laptop), and why the name is blunt.
-     *
-     * Superseded by `withUnsafeConnection`; still honored, and wins on
-     * conflict. Removed at 0.0.5.
      */
-    withUnsafeHttp(allow: boolean): DeRecProtocolBuilder;
+    withUnsafeConnection(allow: boolean): DeRecProtocolBuilder;
     withUserSecretStore(store: any): DeRecProtocolBuilder;
 }
 
@@ -164,31 +140,46 @@ export class DeRecProtocolBuilder {
  * Higher-level DeRec protocol orchestrator for TypeScript/JavaScript consumers.
  *
  * Wraps [`crate::protocol::DeRecProtocol`] with JS-side store
- * and transport adapters so that a TypeScript application can drive all five
- * protocol flows without routing raw bytes manually.
+ * and transport adapters so that a TypeScript application can drive every
+ * protocol flow without routing raw bytes manually. Built with
+ * [`DeRecProtocolBuilderWasm`] (`DeRecProtocolBuilder` in JS).
  *
  * # Stores
  *
- * Pass four JS objects that implement the interfaces documented on each
- * parameter.  All store methods must return `Promise`s — synchronous
- * implementations can wrap their result with `Promise.resolve(...)`.
+ * The five stores and the transport are JS objects implementing the
+ * `ChannelStore`, `ShareStore`, `SecretStore`, `UserSecretStore`,
+ * `StateStore` and `Transport` interfaces in `index.d.ts`. All their methods
+ * must return `Promise`s — synchronous implementations can wrap their result
+ * with `Promise.resolve(...)`.
  *
- * # Events
+ * # Concurrency
  *
- * [`process`](DeRecProtocolWasm::process) returns an `Array` of plain JS
- * objects, each with a `type` discriminant field:
+ * Every method that touches protocol state is `async` 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 `secret_id` and
+ * the same stores must still be serialized by the caller.
  *
- * | `type`             | Additional fields                                      |
- * |--------------------|--------------------------------------------------------|
- * | `PairingCompleted`  | `channel_id: string`, `pairing_channel_id: string`, `kind: number` |
- * | `ShareStored`      | `channel_id: string`, `version: number`                |
- * | `ShareConfirmed`   | `channel_id: string`, `version: number`                |
- * | `ShareVerified`    | `channel_id: string`, `version: number`                |
- * | `SecretsDiscovered`| `channel_id: string`, `secrets: SecretVersionEntry[]`  |
- * | `SecretRecovered`  | `secret: { helpers, secrets, replicas }` (same nested shape as `ReplicaSecretReceived.secret`) |
- * | `NoOp`             | _(none)_                                               |
+ * 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.
  *
- * `SecretVersionEntry = { secret_id: bigint, versions: { version: number, description: string }[] }`
+ * Methods take `&self` for this reason: wasm-bindgen holds the borrow of
+ * the instance for an async call's whole lifetime, so under `&mut self` an
+ * overlapping call fails that borrow outside its promise and never
+ * settles.
+ *
+ * # Events
+ *
+ * [`process`](DeRecProtocolWasm::process), [`start`](DeRecProtocolWasm::start),
+ * [`accept`](DeRecProtocolWasm::accept), [`tick`](DeRecProtocolWasm::tick)
+ * and [`restore`](DeRecProtocolWasm::restore) return an `Array` of plain JS
+ * objects, one per [`crate::protocol::DeRecEvent`], each tagged by a `type`
+ * field naming the variant. Every `u64` identifier (`channel_id`,
+ * `secret_id`, `replica_id`, `trace_id`) is a decimal string. The full set of
+ * shapes is the `DeRecEvent` union in `index.d.ts`.
  */
 export class DeRecProtocolWasm {
     private constructor();
@@ -261,46 +252,36 @@ export class DeRecProtocolWasm {
      * # Returns
      *
      * An `Array` of removed channel ids as decimal strings.
+     *
+     * `older_than_secs` is a `u64`: a `bigint`, a non-negative safe-integer
+     * `number`, or a decimal string.
      */
-    removeExpiredChannels(older_than_secs: number): Promise<any>;
+    removeExpiredChannels(older_than_secs: any): Promise<any>;
     /**
      * Rebuild this protocol's `secret_id` namespace from a recovered
      * `Secret`. Mirrors [`crate::protocol::DeRecProtocol::restore`] —
      * see that method for the full contract.
      *
      * `recoveredSecret` is the typed `Secret` object carried by the
-     * `SecretRecovered` event; pass it verbatim.
+     * `SecretRecovered` event; pass it verbatim. A helper or member whose
+     * `transports` is empty, `null` or absent 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 structured JS errors with a `code` field:
+     * 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(recovered_secret: any, version: number): Promise<any>;
     /**
-     * Generate an out-of-band contact message (QR code payload, deep link, …).
-     *
-     * Returns a plain JS `ContactMessage` object. The `channel_id` field identifies
-     * the pairing session and will match the `channel_id` in the eventual
-     * `PairingCompleted` event — read it directly from the returned object.
-     *
-     * The caller is responsible for serializing the contact for out-of-band
-     * delivery (QR code, deep link, etc.). The peer passes the deserialized object
-     * to [`start`](Self::start) with `FlowKind::Pairing`.
-     *
-     * # Arguments
-     *
-     * * `channel_id` — Optional `BigInt` channel identifier. Pass `null` or
-     *   `undefined` to have the library generate a random one.
-     * * `contact_mode` — `0` for `InlineKeys` (keys embedded directly), `1`
-     *   for `HashedKeys` (contact carries only a SHA-384 binding hash; the
-     *   scanner fetches keys via a `PrePair` round-trip). `HashedKeys`
-     *   requires the protocol's `own_transport` to be ephemeral.
      * The secret identifier this protocol instance is bound to.
      */
     secretId(): bigint;
@@ -308,32 +289,13 @@ export class DeRecProtocolWasm {
      * Replace this node's local communication info. Does not contact peers —
      * follow up with a `start(UpdateChannelInfo, ...)` to propagate.
      */
-    setCommunicationInfo(info: any): 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.
-     *
-     * @deprecated Use `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.
-     *
-     * See `setCommunicationInfo` for the matching update-propagation
-     * flow, and `setOwnTransports` to keep more than one endpoint.
-     * IMPORTANT: keep the old endpoint operational during the changeover —
-     * see the Rust docs on `set_own_transport` for the discipline.
-     */
-    setOwnTransport(uri: string, protocol: string): void;
+    setCommunicationInfo(info: any): Promise<void>;
     /**
      * Replace every endpoint this node advertises, in preference order.
      *
      * `transports` is an array of `{ uri: string, protocol: string }`
-     * objects, same shape as `withOwnTransports`. The runtime counterpart
-     * to that builder setter, and the way to change the whole set:
-     * `setOwnTransport` replaces only the entry for the protocol its URI
-     * names. A node serves at most one endpoint per protocol, so this list
+     * objects, same shape as `withOwnTransports`, and is its runtime
+     * counterpart. A node serves at most one endpoint per protocol, so this list
      * is a preference order over distinct protocols and two entries of the
      * same protocol are rejected.
      *
@@ -342,18 +304,17 @@ export class DeRecProtocolWasm {
      * operational during the changeover — see the Rust docs on
      * `set_own_transports` for the discipline.
      */
-    setOwnTransports(transports: any[]): void;
+    setOwnTransports(transports: any[]): Promise<void>;
     /**
      * Unified entry point for initiating any protocol flow.
      *
      * # Arguments
      *
-     * * `flow_kind` — Flow discriminant:
-     *   - `0` = Pairing (params: `{ kind: number, contact: ContactMessage, name?: string }`)
-     *   - `1` = Discovery (params: `{ target: BigInt | BigInt[] | null }`)
-     *   - `2` = ProtectSecret (params: `{ secrets: UserSecret[], description?: string }`)
-     *   - `3` = VerifyShares (params: `{ version: number, target: BigInt | BigInt[] | null }`)
-     *   - `4` = RecoverSecret (params: `{ secretId: Uint8Array, version: number }`)
+     * * `flow_kind` — `FlowKind` discriminant: `0` Pairing, `1` Discovery,
+     *   `2` ProtectSecret, `3` VerifyShares, `4` RecoverSecret, `5` Unpair,
+     *   `6` UpdateChannelInfo, `7` ReplicaDiscovery, `8` UnpairReplica.
+     * * `params` — the flow's parameters, declared per kind in `index.d.ts`
+     *   as `PairingParams`, `DiscoveryParams`, … `UnpairReplicaParams`.
      *
      * # Returns
      *
@@ -411,30 +372,33 @@ export function envelope_apply_trace_id(envelope_bytes: Uint8Array, trace_id: bi
 export function envelope_read_trace_id(envelope_bytes: Uint8Array): bigint;
 
 /**
- * Structurally validate a JS-side [`ContactMessage`]. Throws on any
- * mode/field inconsistency (unknown `contact_mode`, mode/field mismatch,
- * wrong binding-hash length).
+ * A fresh replica identity. See [`crate::generate_replica_id`]: the caller
+ * persists it once per device and passes the same value on every protocol
+ * init. Never `0`.
  */
-export function pairing_contact_message_validate(contact_message: any): void;
+export function generate_replica_id(): bigint;
+
+/**
+ * The human-readable fingerprint of a pairing's shared key. Both ends derive
+ * the same value; comparing it out of band confirms the pairing.
+ */
+export function pairing_fingerprint(shared_key: Uint8Array): string;
 
 export function pairing_request_create_contact(channel_id: bigint, contact_mode: number, transport_protocols: any, nonce: any): any;
 
 /**
- * Decodes a proto-encoded [`ContactMessage`]. Structurally validates the
- * decoded value before returning it to application code so consumers can
- * trust the mode/field invariants documented on the wire format.
+ * Decodes proto `ContactMessage` wire bytes. See
+ * [`crate::primitives::pairing::request::decode_contact`].
  */
 export function pairing_request_decode_contact(bytes: Uint8Array): any;
 
 /**
- * Encodes a [`ContactMessage`] to proto wire bytes. Structurally validates
- * the input first so a locally-constructed contact that violates the
- * mode/field invariant is rejected at the boundary rather than silently
- * serialized.
+ * Encodes a [`ContactMessage`] to proto wire bytes. See
+ * [`crate::primitives::pairing::request::encode_contact`].
  */
 export function pairing_request_encode_contact(contact_message: any): Uint8Array;
 
-export function pairing_request_extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): any;
+export function pairing_request_extract(envelope_bytes: Uint8Array, secret_key: Uint8Array, parameter_range: any): any;
 
 /**
  * Initiator-side: decode an inbound plaintext `PrePairRequest` envelope.
@@ -456,7 +420,7 @@ export function pairing_response_extract(envelope_bytes: Uint8Array, secret_key:
  */
 export function pairing_response_extract_pre_pair(envelope_bytes: Uint8Array): any;
 
-export function pairing_response_process(contact_message: any, response: any, secret_key: Uint8Array): any;
+export function pairing_response_process(contact_message: any, response: any, secret_key: Uint8Array, parameter_range: any): any;
 
 /**
  * Scanner-side: validate the `PrePairResponse` against the contact's
@@ -464,6 +428,14 @@ export function pairing_response_process(contact_message: any, response: any, se
  */
 export function pairing_response_process_pre_pair(contact_message: any, response: any): any;
 
+/**
+ * Scanner side of a `NO_KEYS` pairing: accept the contact creator's public
+ * keys. There is no binding hash to check them against, so the channel this
+ * leads to MUST stay unusable until both sides confirm `pairing_fingerprint`
+ * out of band.
+ */
+export function pairing_response_process_pre_pair_no_keys(contact_message: any, response: any): any;
+
 export function pairing_response_produce(channel_id: bigint, request: any, secret_key: Uint8Array, communication_info: any, parameter_range: any, unsafe_connection: boolean): any;
 
 /**
@@ -471,6 +443,23 @@ export function pairing_response_produce(channel_id: bigint, request: any, secre
  */
 export function pairing_response_produce_pre_pair(channel_id: bigint, request: any, secret_key: Uint8Array): any;
 
+/**
+ * Contact-creator side of a `NO_KEYS` 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, and MUST keep the resulting channel unusable until both sides
+ * confirm `pairing_fingerprint` out of band.
+ */
+export function pairing_response_produce_pre_pair_no_keys(channel_id: bigint, request: any): any;
+
+/**
+ * The DeRec protocol version this build speaks — the `protocolVersionMajor`
+ * / `protocolVersionMinor` it writes into every envelope it produces —
+ * as `{ major, minor }`.
+ */
+export function protocol_version(): any;
+
 export function recovery_request_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
 
 export function recovery_request_produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to: any): any;