@derec-alliance/nodejs 0.0.3 → 0.0.5

package/proto/transportprotocol.proto

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+package org.derecalliance.derec.protobuf;
+
+/// Enumeration of supported transport protocols.
+///
+/// Additional values MAY be introduced in future versions of the protocol.
+enum Protocol {
+  /// HTTPS-based transport.
+  ///
+  /// Messages are delivered via HTTP(S) requests, typically using a
+  /// request/response pattern where the Owner acts as client and the
+  /// Helper acts as server.
+  ///
+  /// This is the default transport.
+  HTTPS = 0;
+
+  /// gRPC-based transport.
+  ///
+  /// Messages are delivered as unary `DeRecTransport.Send` calls carrying a
+  /// `DeRecMessage` directly. Delivery is push-only: the call returns
+  /// `google.protobuf.Empty`, and every response is a fresh `Send` to the
+  /// peer's own endpoint, so both parties must run a reachable server.
+  ///
+  /// URI forms:
+  ///
+  /// - `grpcs://host:port` — gRPC over TLS
+  /// - `grpc://host:port` — plaintext, development only
+  GRPC = 1;
+}
+
+/// TransportProtocol defines how a DeRec participant (Owner or Helper)
+/// can be reached over the network.
+///
+/// This message encapsulates the transport-layer endpoint and the protocol
+/// required to deliver DeRec messages to that endpoint. It is typically
+/// exchanged during pairing (via ContactMessage) so that both parties know
+/// how to establish communication channels.
+///
+/// A TransportProtocol does not itself provide security guarantees.
+/// All DeRec protocol messages MUST still be signed and encrypted at the
+/// application layer, regardless of the underlying transport.
+///
+/// # Semantics
+///
+/// - The `uri` identifies the remote endpoint (e.g., HTTPS URL, message queue).
+/// - The `protocol` specifies how the URI should be interpreted and how
+///   messages must be transmitted.
+/// - The combination of (`protocol`, `uri`) MUST be sufficient for the sender
+///   to deliver a DeRec message to the receiver.
+///
+/// # Usage
+///
+/// - Included in ContactMessage during pairing to advertise reachable endpoints.
+/// - May be stored by peers as part of the communication channel state.
+/// - Used by the sender to select the correct transport mechanism when
+///   delivering protocol messages.
+///
+/// # Extensibility
+///
+/// The Protocol enum is expected to grow as new transport mechanisms are
+/// supported (e.g., message queues, peer-to-peer transports). Implementations
+/// MUST ignore unknown enum values unless explicitly required otherwise.
+///
+/// # Reliability
+///
+/// Transport protocols may be:
+/// - request/response (e.g., HTTPS)
+/// - store-and-forward (e.g., message queues)
+///
+/// Implementations MUST handle retries and idempotency at the protocol layer,
+/// independent of transport guarantees.
+message TransportProtocol {
+  /// URI endpoint used to contact the peer.
+  ///
+  /// The format of this field depends on the selected `protocol`.
+  /// Examples:
+  ///
+  /// - HTTPS: "https://example.com/derec" or "http://example.com/derec"
+  /// - gRPC: "grpcs://example.com:443" or "grpc://example.com:50051"
+  /// - Future protocols MAY define other URI schemes.
+  ///
+  /// The URI MUST be sufficient to route messages to the intended recipient.
+  string uri = 1;
+
+  /// Transport protocol associated with the URI.
+  ///
+  /// This determines:
+  /// - how the `uri` should be interpreted
+  /// - how messages are serialized and delivered
+  /// - what communication pattern is expected (e.g., synchronous vs async)
+  ///
+  /// Implementations MUST support all mandatory protocol types defined here.
+  Protocol protocol = 2;
+}

package/proto/unpair.proto

@@ -0,0 +1,140 @@
+/*
+ * 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;
+
+// UnpairRequestMessage requests termination of the DeRec relationship
+// between two parties (Owner and Helper).
+//
+// # Context
+//
+// This message is used when:
+//
+// - the Owner no longer wants a Helper to store shares
+// - the Helper chooses to stop acting as a Helper
+// - the relationship must be terminated due to policy, failure, or user action
+//
+// # Semantics
+//
+// Upon receiving this message, the recipient MUST:
+//
+// - stop acting as a Helper for the corresponding channel
+// - cease all protocol interactions for that channel
+//
+// The recipient SHOULD:
+//
+// - delete all stored shares and related state for the Owner
+//
+// However, deletion MAY be subject to:
+//
+// - regulatory requirements
+// - contractual obligations
+// - service-specific retention policies
+//
+// # Effects on Protocol State
+//
+// After a successful unpair:
+//
+// - the channel is considered permanently closed
+// - the Owner MUST NOT rely on this Helper for recovery
+// - the Owner SHOULD reshare secrets with remaining Helpers if necessary
+//
+// # Idempotency
+//
+// This message is idempotent. Repeated unpair requests SHOULD result in
+// the same final state.
+message UnpairRequestMessage {
+
+  // Optional human-readable explanation for the unpairing.
+  //
+  // This field is intended for logging, debugging, or user display.
+  // It MUST NOT be relied upon for protocol behavior.
+  string memo = 1;
+
+  // Timestamp indicating when this message was created.
+  //
+  // This value is expressed in UTC and can be used for:
+  //
+  // - observability and logging
+  // - replay detection (in combination with sequence numbers)
+  // - timeout handling
+  google.protobuf.Timestamp timestamp = 2;
+
+  // Ephemeral transport endpoint at which the requester wants to receive
+  // the response to *this exchange*, overriding the channel's stored peer
+  // endpoint for this round-trip only.
+  //
+  // See `StoreShareRequestMessage.replyTo` for full semantics.
+  //
+  // Superseded by `replyToTransports`, which carries every endpoint rather
+  // than one. Kept, and still populated with the list's first entry, so
+  // implementations predating that field still receive a reply.
+  // **Scheduled for removal in v0.0.5.** Reading this field directly is now
+  // incorrect — resolve it against `replyToTransports`.
+  optional TransportProtocol replyTo = 3 [deprecated = true];
+
+  // Every ephemeral endpoint the requester wants this exchange's response
+  // delivered to, in its own preference order.
+  //
+  // See `StoreShareRequestMessage.replyToTransports` for full semantics,
+  // including why this is a new tag rather than a widened `replyTo`.
+  repeated TransportProtocol replyToTransports = 5;
+
+  // Identity of the replica-group member that initiated this unpair.
+  //
+  // A replica-originated unpair MUST carry it; an owner-originated one MUST
+  // NOT. Its presence is what tells the receiver which path the message
+  // belongs to, exactly as on `StoreShareRequestMessage`. Asserted on send
+  // and on receive; a violation is a protocol error.
+  //
+  // Removing a replica is not the same operation as unpairing a helper. A
+  // helper channel serves exactly one peer, so unpairing deletes it. Every
+  // member of a replica group shares one channel, so deleting it would sever
+  // the whole group — replica removal edits a member row instead, and this
+  // field says which row.
+  optional uint64 replicaId = 4;
+}
+
+// UnpairResponseMessage is the response to an UnpairRequestMessage.
+//
+// # Semantics
+//
+// This message indicates whether the recipient successfully processed
+// the unpair request.
+//
+// On success:
+//
+// - the relationship is considered terminated
+// - the recipient has ceased participation in the protocol for this channel
+//
+// On failure:
+//
+// - the relationship state is undefined and SHOULD be handled by the
+//  application (e.g., retry or escalate)
+//
+// # Idempotency
+//
+// Multiple identical unpair requests SHOULD produce consistent responses.
+message UnpairResponseMessage {
+  // Result of processing the unpair request.
+  //
+  // Indicates whether the unpair operation was successfully completed.
+  DeRecResult result = 1;
+
+  // Timestamp indicating when this message was created.
+  //
+  // This value is expressed in UTC and can be used for:
+  //
+  // - observability and logging
+  // - replay detection (in combination with sequence numbers)
+  // - timeout handling
+  google.protobuf.Timestamp timestamp = 2;
+}

package/proto/updatechannelinfo.proto

@@ -0,0 +1,129 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+import "communicationinfo.proto";
+import "result.proto";
+import "transportprotocol.proto";
+
+package org.derecalliance.derec.protobuf;
+
+// UpdateChannelInfoRequestMessage notifies the peer that the sender's
+// communication metadata and/or transport endpoint have changed.
+//
+// # Context
+//
+// Both `communication_info` and `transport_protocol` are exchanged at pairing
+// time only. This message lets either party (Owner or Helper) propagate
+// post-pairing changes without re-pairing.
+//
+// # Semantics
+//
+// Both fields are optional and independent:
+//
+// - `communication_info` absent (no `CommunicationInfo` set) means "do not
+//  modify the communication info stored for the sender." Presence — even
+//  with an empty `communication_info_entries` list — means "replace the
+//  stored map with the supplied one." Updates, additions, and deletions
+//  are all expressed by the difference between the receiver's current map
+//  and the supplied one.
+// - `transport_protocol` absent means "do not modify the transport endpoint
+//  stored for the sender." Presence means "the sender's transport endpoint
+//  is now this value." The receiver MUST route subsequent messages on this
+//  channel to the new endpoint, including the
+//  UpdateChannelInfoResponseMessage for this request.
+//
+// # Endpoint changeover
+//
+// When `transport_protocol` is updated, the receiver sends its response to
+// the new endpoint. The sender's application is therefore responsible for
+// ensuring the new endpoint is reachable BEFORE this request is issued, and
+// for keeping the old endpoint operational long enough for in-flight
+// messages from other peers (and any concurrent operations) to drain.
+message UpdateChannelInfoRequestMessage {
+
+  // Updated communication info for the sender, or absent to leave unchanged.
+  //
+  // Presence (even with an empty entries list) replaces the receiver's
+  // stored map for this channel. Absence leaves it untouched.
+  optional CommunicationInfo communicationInfo = 1;
+
+  // Updated transport endpoint for the sender, or absent to leave unchanged.
+  //
+  // Presence updates both the URI and protocol enum. The receiver routes
+  // the response to this new endpoint.
+  //
+  // 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 announces only
+  // `supportedTransports`. A reader that was correct before this release is
+  // a bug now — it records the wrong address, or none, for a peer that
+  // announced a perfectly good one. 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 learn the new address.
+  //
+  // **Scheduled for removal in v0.0.5.**
+  optional TransportProtocol transportProtocol = 2 [deprecated = true];
+
+  // Every transport endpoint the sender can now be reached on, in its own
+  // preference order, replacing the receiver's stored set for this channel.
+  //
+  // # Semantics
+  //
+  // - Empty, and `transportProtocol` absent: the sender's endpoints are
+  //  left unchanged. An update that changes only `communicationInfo` says
+  //  nothing about transports.
+  // - Non-empty: replaces the stored set outright. Unlike a request's
+  //  `replyTo`, this **is** persisted — it is how a peer announces it has
+  //  moved.
+  //
+  // # Compatibility
+  //
+  // Empty with `transportProtocol` present means "only that one endpoint 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 learn the new address.
+  repeated TransportProtocol supportedTransports = 4;
+
+  // 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;
+}
+
+// UpdateChannelInfoResponseMessage is the response to an
+// UpdateChannelInfoRequestMessage.
+//
+// # Semantics
+//
+// On success (`result.status == OK`):
+//
+// - the receiver has persisted the supplied updates
+// - subsequent messages from the receiver MUST use the new endpoint, if
+//  `transport_protocol` was updated
+//
+// On failure:
+//
+// - the receiver's stored state is unchanged
+// - the sender SHOULD inspect `result.memo` for diagnostic context
+message UpdateChannelInfoResponseMessage {
+
+  // Result of processing the update.
+  DeRecResult result = 1;
+
+  // Timestamp indicating when this message was created.
+  google.protobuf.Timestamp timestamp = 2;
+}

package/proto/verify.proto

@@ -0,0 +1,170 @@
+/*
+ * 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;
+
+
+// VerifyShareRequestMessage initiates a verification challenge from the Owner
+// to a Helper to confirm that the Helper still retains a specific share.
+//
+// # Context
+//
+// This message is part of the verification flow, which allows the Owner to:
+//
+// - periodically check Helper liveness
+// - detect data loss or corruption of stored shares
+// - identify Helpers that are no longer reliable for recovery
+//
+// # Semantics
+//
+// The Owner challenges the Helper by providing:
+//
+// - a `version` identifying the share to verify
+// - a fresh `nonce` to ensure the response is unique and not replayable
+//
+// The Helper MUST compute a cryptographic hash over:
+//
+//  committedDeRecShare || nonce
+//
+// and return the result in a VerifyShareResponseMessage.
+//
+// # Security Properties
+//
+// - The nonce ensures freshness and prevents replay attacks
+// - The hash proves possession of the exact share bytes
+// - The Helper cannot produce a valid response without holding the share
+//
+// # Idempotency
+//
+// Each request is uniquely identified by the nonce. Reusing a nonce SHOULD
+// be avoided, as it weakens replay protection guarantees.
+message VerifyShareRequestMessage {
+  // Secret id being challenged.
+  //
+  // This identifies which stored share for a secret the Helper must use to compute
+  // the verification proof.
+  uint64 secretId = 1;
+
+  // Share version being challenged.
+  //
+  // This identifies which stored share version the Helper must use to compute
+  // the verification proof.
+  uint32 version = 2;
+
+  // Random challenge nonce generated by the Owner.
+  //
+  // This value MUST be unpredictable and unique per request to ensure
+  // freshness and prevent replay of previous responses.
+  uint64 nonce = 3;
+
+  // Timestamp indicating when this message was created.
+  //
+  // This value is expressed in UTC and can be used for:
+  //
+  // - observability and logging
+  // - replay detection (in combination with sequence numbers)
+  // - timeout handling
+  google.protobuf.Timestamp timestamp = 4;
+
+  // Ephemeral transport endpoint at which the requester wants to receive
+  // the response to *this exchange*, overriding the channel's stored peer
+  // endpoint for this round-trip only.
+  //
+  // See `StoreShareRequestMessage.replyTo` for full semantics.
+  //
+  // Superseded by `replyToTransports`, which carries every endpoint rather
+  // than one. Kept, and still populated with the list's first entry, so
+  // implementations predating that field still receive a reply.
+  // **Scheduled for removal in v0.0.5.** Reading this field directly is now
+  // incorrect — resolve it against `replyToTransports`.
+  optional TransportProtocol replyTo = 5 [deprecated = true];
+
+  // Every ephemeral endpoint the requester wants this exchange's response
+  // delivered to, in its own preference order.
+  //
+  // See `StoreShareRequestMessage.replyToTransports` for full semantics,
+  // including why this is a new tag rather than a widened `replyTo`.
+  repeated TransportProtocol replyToTransports = 6;
+}
+
+// VerifyShareResponseMessage contains the result of a verification challenge
+// and, on success, provides a proof of share possession.
+//
+// # Semantics
+//
+// In response to a VerifyShareRequestMessage, the Helper:
+//
+// - retrieves the requested share version
+// - computes the hash over (committedDeRecShare || nonce)
+// - returns the result along with the echoed version and nonce
+//
+// The Owner verifies the response by recomputing the expected hash and
+// comparing it with the received value.
+//
+// # Failure Handling
+//
+// If the verification fails (e.g., incorrect hash or error result), the Owner:
+//
+// - MAY retry the verification
+// - MAY resend the correct share to the Helper
+// - MAY mark the Helper as unreliable after repeated failures
+//
+// # Security Considerations
+//
+// - The hash MUST be computed using SHA-384 as defined by the protocol
+// - The nonce MUST match the request to ensure the response is not replayed
+// - The response MUST be sent over an authenticated and encrypted channel
+//
+// # Idempotency
+//
+// Responses are tied to a specific (version, nonce) pair. Replaying a response
+// with a stale nonce SHOULD be rejected by the Owner.
+message VerifyShareResponseMessage {
+  // Result of processing the verification request.
+  //
+  // Indicates whether the Helper successfully computed the proof or
+  // encountered an error (e.g., share not found).
+  DeRecResult result = 1;
+
+  // Secret id this response refers to.
+  //
+  // MUST match the version provided in the request.
+  uint64 secretId = 2;
+
+  // Share version this response refers to.
+  //
+  // MUST match the version provided in the request.
+  uint32 version = 3;
+
+  // Challenge nonce echoed from the request.
+  //
+  // MUST exactly match the nonce provided in the request.
+  uint64 nonce = 4;
+
+  // Verification proof.
+  //
+  // This is the SHA-384 hash of:
+  //
+  //  committedDeRecShare || nonce
+  //
+  // where `committedDeRecShare` is the exact byte sequence originally
+  // stored by the Helper.
+  bytes hash = 5;
+
+  // Timestamp indicating when this message was created.
+  //
+  // This value is expressed in UTC and can be used for:
+  //
+  // - observability and logging
+  // - replay detection (in combination with sequence numbers)
+  // - timeout handling
+  google.protobuf.Timestamp timestamp = 6;
+}