@derec-alliance/nodejs 0.0.3 → 0.0.5

package/proto/pair.proto

@@ -0,0 +1,284 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+import "communicationinfo.proto";
+import "parameterrange.proto";
+import "result.proto";
+import "transportprotocol.proto";
+
+package org.derecalliance.derec.protobuf;
+
+// SenderKind identifies the logical role of the sender in the pairing flow.
+//
+// The role determines how the receiver interprets the message and what
+// role each party takes in the resulting channel. Pairs are formed by
+// matching complementary kinds: Owner↔Helper, ReplicaSource↔ReplicaDestination.
+enum SenderKind {
+  // Sender is an Owner.
+  //
+  // Used for all Owner-initiated pairings, whether establishing a new
+  // relationship or re-pairing during recovery. There is no protocol-level
+  // distinction between the two cases.
+  OWNER = 0;
+
+  // Sender is acting as a Helper.
+  //
+  // Helpers may initiate pairing in some application flows, though the
+  // Owner typically acts as the initiator.
+  HELPER = 1;
+
+  // Sender is the Source side of a replica pair — the device that owns
+  // the secrets and pushes them to a destination for backup. The matching
+  // peer kind is REPLICA_DESTINATION.
+  //
+  // Replica pairing follows the same cryptographic handshake as Helper
+  // pairing but adds a mandatory fingerprint-verify step before the
+  // channel transitions out of `Pending`. After verification, the Source
+  // calls ProtectSecret targeting the Destination channel; the library
+  // sends a `ReplicaSecretPayload` (full secret + share map) to the
+  // Destination via a normal channel-mode `StoreShareRequest`.
+  REPLICA_SOURCE = 3;
+
+  // Sender is the Destination side of a replica pair — the device that
+  // receives and stores full secret copies from a Source for backup or
+  // recovery purposes. The matching peer kind is REPLICA_SOURCE.
+  //
+  // The Destination never initiates ProtectSecret on this channel; it
+  // only receives `ReplicaSecretPayload` messages and surfaces them to
+  // the application via the `ReplicaSecretReceived` event.
+  REPLICA_DESTINATION = 4;
+}
+
+// PairRequestMessage is the first message in the pairing protocol,
+// sent from the initiator to the responder after receiving a ContactMessage.
+//
+// # Preconditions
+//
+// Before sending this message:
+//
+// - The initiator MUST have received a valid ContactMessage from the responder
+// - The initiator MUST use the responder's public encryption material from
+//  the ContactMessage to construct this request
+//
+// # Purpose
+//
+// This message establishes:
+//
+// - the initiator's identity and role (Owner/Helper, recovery mode or not)
+// - fresh cryptographic material for the responder to use in subsequent messages
+// - agreement negotiation inputs (parameter ranges)
+// - binding between the out-of-band contact exchange and this pairing attempt
+// - transport information for future communication
+//
+// # Security Properties
+//
+// - The nonce binds this request to the ContactMessage exchange
+// - The ciphertext and public keys bootstrap a secure communication channel
+// - The message is encrypted and authenticated at the DeRecMessage layer
+//
+// # Outcome
+//
+// Upon successful processing, the responder replies with PairResponseMessage.
+// After this exchange:
+//
+// - both parties know each other's public keys
+// - a secure communication channel is established for subsequent protocol flows
+message PairRequestMessage {
+
+  // The role of the sender of this message.
+  //
+  // This informs the responder whether the initiator is:
+  //
+  // - an Owner (normal or recovery mode), or
+  // - a Helper
+  //
+  // Recovery mode has special semantics for how Helpers associate this
+  // pairing with existing stored secrets.
+  SenderKind senderKind = 1;
+
+  // ML-KEM-768 ciphertext.
+  //
+  // This ciphertext is generated using the responder's ML-KEM public key
+  // obtained from the ContactMessage. It is used to establish shared
+  // cryptographic material for securing subsequent communication.
+  bytes mlkemCiphertext = 2;
+
+  // Serialized ECIES public key of the sender.
+  //
+  // This key is provided to the responder so that future messages can be
+  // encrypted toward the initiator.
+  bytes eciesPublicKey = 3;
+
+  // Sender's application-level identifying information.
+  //
+  // This field is intended for user-facing identification and may include
+  // data such as name, phone number, or account identifiers.
+  //
+  // It is not used directly by the protocol for security decisions.
+  CommunicationInfo communicationInfo = 5;
+
+  // Nonce binding this request to the ContactMessage exchange.
+  //
+  // This value MUST match the nonce provided in the ContactMessage.
+  // It allows the responder to verify that the pairing request corresponds
+  // to the same out-of-band interaction, preventing mismatched or spoofed
+  // pairing attempts.
+  uint64 nonce = 6;
+
+  // Parameter range supported by the sender.
+  //
+  // This defines the acceptable configuration space (e.g., thresholds,
+  // limits) that the sender is willing to operate under.
+  //
+  // The responder combines this with its own parameter range to determine
+  // whether pairing is possible and which parameters to use.
+  ParameterRange parameterRange = 7;
+
+  // Transport information for reaching the initiator.
+  //
+  // This specifies:
+  //
+  // - the endpoint where the initiator can receive messages
+  // - the protocol required to deliver those messages
+  //
+  // After pairing, the responder uses this information to send responses
+  // and all subsequent protocol messages to the initiator.
+  // Deprecated: superseded by `supportedTransports`, which carries every
+  // endpoint rather than one.
+  //
+  // **Reading this field directly is now incorrect.** Its meaning narrowed
+  // from "the endpoint" to "one entry of a list, and possibly absent": an
+  // initiator that has moved past this field advertises only
+  // `supportedTransports`. A reader that was correct before this release is
+  // a bug now — it rejects, or fails to reach, a peer that is offering it a
+  // perfectly good endpoint. Resolve both spellings instead of reading
+  // either: `advertised_endpoints()` (Rust and TypeScript),
+  // `AdvertisedEndpoints()` (Go), `AdvertisedEndpoints()` (.NET).
+  //
+  // Senders still populate it: a sender that sets `supportedTransports`
+  // MUST also set this to a single best-compatibility choice, so
+  // implementations predating the list still pair.
+  //
+  // **Scheduled for removal in v0.0.5.**
+  TransportProtocol transportProtocol = 8 [deprecated = true];
+
+  // Timestamp indicating when this message was created.
+  //
+  // Used for observability and may assist in replay detection or timeout
+  // handling, depending on the implementation.
+  google.protobuf.Timestamp timestamp = 9;
+
+  // Every transport endpoint the initiator can be reached on, in the
+  // initiator's own preference order.
+  //
+  // Same semantics as `ContactMessage.supportedTransports`: the responder
+  // selects by its own preference, and absent means "only
+  // `transportProtocol` is offered".
+  repeated TransportProtocol supportedTransports = 10;
+}
+
+// PairResponseMessage is the response to a PairRequestMessage.
+//
+// # Purpose
+//
+// This message completes the pairing handshake. It informs the initiator:
+//
+// - whether the pairing was accepted or rejected
+// - the responder's role and identity information
+// - the responder's supported parameter range
+//
+// # Differences from PairRequestMessage
+//
+// - Does not include encryption public keys, as those were already exchanged
+//  via ContactMessage and PairRequestMessage
+// - Includes a Result field indicating success or failure
+//
+// # Semantics
+//
+// - If `result` indicates success, a secure channel is considered established
+// - If `result` indicates failure, the pairing MUST be treated as unsuccessful
+//  and no further protocol messages should be exchanged on this channel
+//
+// The nonce MUST match the value provided in the request, ensuring that the
+// response corresponds to the same pairing session.
+message PairResponseMessage {
+
+  // Result of processing the pairing request.
+  //
+  // Indicates whether the pairing was successful or failed.
+  // Failure may occur due to:
+  //
+  // - incompatible parameter ranges
+  // - failed authentication at the application layer
+  // - invalid or malformed request data
+  DeRecResult result = 1;
+
+  // Application-level identifying information of the responder.
+  //
+  // Intended for user-facing identification and display purposes.
+  CommunicationInfo communicationInfo = 4;
+
+  // Nonce identifying the pairing session.
+  //
+  // This value MUST exactly match the nonce received in the
+  // PairRequestMessage. A mismatch indicates an invalid or unrelated
+  // pairing attempt and SHOULD result in rejection.
+  uint64 nonce = 5;
+
+  // Parameter range supported by the responder.
+  //
+  // The initiator combines this with its own parameter range to determine
+  // the final agreed configuration for the channel.
+  ParameterRange parameterRange = 6;
+
+  // Timestamp indicating when this message was created.
+  //
+  // Used for observability and may assist in replay detection or timeout
+  // handling, depending on the implementation.
+  google.protobuf.Timestamp timestamp = 7;
+
+  // Derived channel identifier the two parties switch to immediately after
+  // the pairing handshake completes. This message is the only place this
+  // value travels on the wire, and it travels encrypted (inside the pairing
+  // envelope), so a passive observer who only sees the pre-rekey traffic
+  // cannot link the now-paired session to its long-running successor.
+  //
+  // # Derivation
+  //
+  // The responder computes:
+  //
+  // ```text
+  // channelId = u64::from_be_bytes(
+  //     SHA-384(
+  //         u64_be(originalChannelId) || sharedKeyBytes
+  //     )[0..8]
+  // )
+  // ```
+  //
+  // where `originalChannelId` is the channelId from the contact / pairing
+  // envelopes and `sharedKeyBytes` is the freshly-derived pairing shared
+  // key.
+  //
+  // # Validation
+  //
+  // The requester MUST recompute the same hash with its own derivation of
+  // the shared key and reject the response (closing the would-be channel)
+  // if the value here does not match. A non-matching value indicates either
+  // a key-derivation mismatch (the channel would be unusable anyway) or
+  // tampering by a peer that somehow forged a valid envelope but cannot
+  // produce the SHA-384 preimage.
+  //
+  // # Effect
+  //
+  // Both parties atomically rekey their local channel record from
+  // `originalChannelId` to this value once the handshake is accepted. All
+  // subsequent envelopes on this channel — including the
+  // UpdateChannelInfo handover for the long-term transport — route on the
+  // new id.
+  uint64 channelId = 8;
+}

package/proto/parameterrange.proto

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+package org.derecalliance.derec.protobuf;
+
+message ParameterRange {
+
+  // Minimum and maximum number of bytes the party is willing to store
+  // at any given time.
+  int64 minShareSize = 1;
+  int64 maxShareSize = 2;
+
+  // Minimum and maximum interval between verification requests that
+  // will be accepted.
+  int64 minTimeBetweenVerifications = 3;
+  int64 maxTimeBetweenVerifications = 4;
+
+  // Minimum and maximum interval between accepting new share updates.
+  int64 minTimeBetweenShareUpdates = 5;
+  int64 maxTimeBetweenShareUpdates = 6;
+
+  // Minimum and maximum timeout period (in seconds) after which the
+  // other party is considered unresponsive and the pairing may be
+  // removed along with all associated data.
+  int64 minUnresponsiveDeletionTimeout = 7;
+  int64 maxUnresponsiveDeletionTimeout = 8;
+
+  // Minimum and maximum timeout period (in seconds) after which the
+  // other party is considered inactive.
+  int64 minUnresponsiveDeactivationTimeout = 9;
+  int64 maxUnresponsiveDeactivationTimeout = 10;
+}

package/proto/prepair.proto

@@ -0,0 +1,177 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+import "result.proto";
+import "transportprotocol.proto";
+
+package org.derecalliance.derec.protobuf;
+
+// PrePairRequestMessage is sent by the recipient of a ContactMessage whose
+// `contactMode == CONTACT_MODE_HASHED_KEYS`. It asks the contact creator for
+// the actual ML-KEM and ECIES public keys that the contact's
+// `contactBindingHash` commits to.
+//
+// # When this is sent
+//
+// `CONTACT_MODE_HASHED_KEYS` contacts carry only a hash of the public keys
+// so they fit in size-constrained out-of-band channels (e.g. QR codes,
+// short URLs). The recipient must obtain the actual keys before it can
+// construct the first encrypted `PairRequestMessage`.
+//
+// # Security
+//
+// This message is plaintext — no shared key has been established yet. The
+// scanner-side integrity check happens after the `PrePairResponseMessage`
+// arrives, by recomputing the hash and matching it against the original
+// `contactBindingHash`. An attacker who intercepts the transport cannot
+// substitute different keys without producing a hash collision.
+//
+// # Envelope
+//
+// The message is wrapped in a `DeRecMessage` envelope just like every
+// other protocol message. The envelope's `channelId` carries the routing
+// key; the envelope's `message` field carries the serialized
+// `PrePairRequestMessage` bytes unencrypted (because no symmetric key
+// exists yet).
+//
+// # Security: transport endpoint is observable
+//
+// Because the envelope is plaintext, the `transportProtocol` field in both
+// `PrePairRequestMessage` and `PrePairResponseMessage` is visible to any
+// passive observer on the network path. The same applies to the
+// `transportProtocol` carried in the `HASHED_KEYS`-mode `ContactMessage`
+// itself if its out-of-band channel can be observed.
+//
+// The protocol relies on this contract from the application to preserve
+// the security guarantees of `HASHED_KEYS` mode:
+//
+// - The `transportProtocol` used during pairing (the one advertised in the
+//  `ContactMessage` and echoed in `PrePairRequestMessage`) MUST be
+//  ephemeral and short-lived — bound to the pairing attempt, not to the
+//  long-term identity of either peer.
+// - Once pairing completes, the application MUST swap to a long-term
+//  endpoint via an `UpdateChannelInfoRequestMessage`. The ephemeral
+//  pairing endpoint is retired after the changeover (see the endpoint-
+//  changeover discipline on `UpdateChannelInfoRequestMessage`).
+//
+// `INLINE_KEYS`-mode contacts do not have this constraint because the
+// `PairRequestMessage` is asymmetrically encrypted; only the
+// `ContactMessage` itself crosses an unencrypted channel, which is by
+// definition the trusted out-of-band one.
+message PrePairRequestMessage {
+
+  // The same `nonce` the original `ContactMessage` advertised. Bound to
+  // the contact session; mismatches indicate a stale or spoofed request
+  // and the receiver MUST refuse to serve the keys.
+  uint64 nonce = 1;
+
+  // Transport endpoint at which the sender expects to receive the
+  // `PrePairResponseMessage`.
+  //
+  // Deprecated: superseded by `supportedTransports`, which carries every
+  // endpoint rather than one.
+  //
+  // **Reading this field directly is now incorrect.** Its meaning narrowed
+  // from "the endpoint" to "one entry of a list, and possibly absent": a
+  // sender that has moved past this field advertises only
+  // `supportedTransports`. A reader that was correct before this release is
+  // a bug now — it rejects, or fails to reply to, a peer that is offering it
+  // a perfectly good endpoint. Resolve both spellings instead of reading
+  // either: `advertised_endpoints()` (Rust and TypeScript),
+  // `AdvertisedEndpoints()` (Go), `AdvertisedEndpoints()` (.NET).
+  //
+  // Senders still populate it: a sender that sets `supportedTransports`
+  // MUST also set this to a single best-compatibility choice, so
+  // implementations predating the list still receive a reply.
+  //
+  // **Scheduled for removal in v0.0.5.**
+  TransportProtocol transportProtocol = 2 [deprecated = true];
+
+  // Timestamp indicating when this message was created.
+  //
+  // This value is expressed in UTC and is used for envelope-vs-body
+  // timestamp validation, replay detection, and observability.
+  google.protobuf.Timestamp timestamp = 3;
+
+  // Every transport endpoint the sender of this PrePair request can be
+  // reached on for the `PrePairResponseMessage`.
+  //
+  // Each entry is a complete endpoint: a URI plus the protocol that says
+  // how to interpret it. The list is written in the sender's own
+  // preference order.
+  //
+  // # Selection is the recipient's
+  //
+  // A recipient picks whichever entry suits it, ordered by its **own**
+  // preference rather than the sender's. The order here expresses
+  // availability, not a ranking the recipient must honor.
+  //
+  // # Compatibility
+  //
+  // Absent means "only `transportProtocol` is offered", which is how every
+  // implementation predating this field behaves. A sender populating this
+  // list MUST also set `transportProtocol` to a single best-compatibility
+  // choice so those implementations still reply.
+  //
+  // At least one of the two MUST be present: a request naming no endpoint
+  // gives the recipient nowhere to send the response.
+  //
+  // # Security
+  //
+  // PrePair traffic is plaintext — no shared key exists yet — so these
+  // endpoints are visible to a passive observer, exactly as
+  // `transportProtocol` already was. The recipient's transport policy still
+  // refuses plaintext entries unless plaintext has been opted into.
+  repeated TransportProtocol supportedTransports = 4;
+}
+
+// PrePairResponseMessage is the contact creator's reply to a
+// `PrePairRequestMessage`. On success it carries the real public keys; on
+// failure it carries only a non-`Ok` `DeRecResult`.
+//
+// # Validation by the receiver
+//
+// The recipient (the original scanner of the `ContactMessage`) MUST:
+//
+// - Confirm `result.status == OK`. On non-`Ok`, surface a typed error to
+//  the application and do not proceed.
+// - Recompute
+//
+//  ```text
+//  SHA-384(mlkemEncapsulationKey || eciesPublicKey
+//           || u64_be(nonce) || u64_be(channelId))
+//  ```
+//
+//  and verify it matches the original `ContactMessage.contactBindingHash`.
+// - Only on a match, proceed to construct and send a normal
+//  `PairRequestMessage`.
+//
+// # Envelope
+//
+// Plaintext-in-`DeRecMessage`-envelope, same as `PrePairRequestMessage`.
+message PrePairResponseMessage {
+
+  // Result of processing the `PrePairRequestMessage`. On `OK`, the two
+  // key fields below are present. On any non-`Ok` status, the key fields
+  // MUST be absent.
+  DeRecResult result = 1;
+
+  // Serialized ML-KEM-768 encapsulation key. Present only when
+  // `result.status == OK`.
+  optional bytes mlkemEncapsulationKey = 2;
+
+  // Serialized ECIES public key. Present only when
+  // `result.status == OK`.
+  optional bytes eciesPublicKey = 3;
+
+  // Echoed from the request for session correlation.
+  uint64 nonce = 4;
+
+  // Timestamp indicating when this message was created.
+  google.protobuf.Timestamp timestamp = 5;
+}