@derec-alliance/nodejs 0.0.3 → 0.0.4

package/proto/derecmessage.proto

@@ -0,0 +1,213 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+import "pair.proto";
+import "unpair.proto";
+import "storeshare.proto";
+import "verify.proto";
+import "getshare.proto";
+import "secretidsversions.proto";
+import "updatechannelinfo.proto";
+import "prepair.proto";
+import "error.proto";
+
+package org.derecalliance.derec.protobuf;
+
+// DeRecMessage is the top-level protocol envelope for all DeRec messages,
+// except ContactMessage which is exchanged out-of-band during pairing.
+//
+// This message represents the unit of communication between an Owner and a
+// Helper once a secure channel has been established. Every protocol exchange
+// (pairing, sharing, verification, recovery, etc.) is carried inside this
+// envelope.
+//
+// # Security Model
+//
+// The DeRecMessage envelope itself is not responsible for confidentiality or
+// authenticity. Instead:
+//
+// - The `message` field contains encrypted bytes representing the inner message
+// - Encryption is applied at the payload level prior to transport
+//
+// Implementations MUST ensure that:
+//
+// - The inner message is encrypted using the agreed channel keys
+// - The envelope metadata is treated as untrusted until the payload is verified
+//
+// # Semantics
+//
+// A DeRecMessage provides:
+//
+// - protocol versioning information for compatibility handling
+// - ordering guarantees via a monotonically increasing sequence number
+// - channel identification for routing and key selection
+// - a timestamp for replay protection and observability
+// - an encrypted payload containing exactly one protocol message
+//
+// The envelope is transport-agnostic and can be delivered over any supported
+// transport (e.g., HTTPS, message queues), as defined by TransportProtocol.
+//
+// # Ordering and Idempotency
+//
+// Communication follows a request/response pattern:
+//
+// - The Owner sends a request message
+// - The Helper replies with a corresponding response
+//
+// The `sequence` field is used to:
+//
+// - enforce message ordering
+// - detect duplicates or out-of-order delivery
+// - support replay protection
+//
+// Implementations SHOULD treat messages as idempotent and be resilient to
+// retries and duplicate deliveries.
+//
+// # Key Rotation
+//
+// The sequence number may also be used as a trigger for automatic key rotation.
+// When a configured threshold is reached, implementations MAY initiate a key
+// rotation flow to maintain forward secrecy.
+//
+// # Versioning
+//
+// The protocolVersionMajor and protocolVersionMinor fields allow peers to:
+//
+// - detect incompatible protocol versions
+// - apply backward-compatible parsing logic when possible
+//
+// Implementations MUST define behavior for handling version mismatches.
+//
+// # Payload Encoding
+//
+// The `message` field contains encrypted raw bytes. When decrypted, these bytes
+// MUST deserialize into a MessageBody, which contains exactly one concrete
+// protocol message.
+//
+// The oneof structure ensures that each DeRecMessage carries a single logical
+// operation.
+message DeRecMessage {
+  // DeRec protocol major version.
+  //
+  // Incremented for breaking changes that are not backward compatible.
+  uint32 protocolVersionMajor = 1;
+
+  // DeRec protocol minor version.
+  //
+  // Incremented for backward-compatible changes such as adding new fields
+  // or message types.
+  uint32 protocolVersionMinor = 2;
+
+  // Monotonically increasing message sequence number.
+  //
+  // This value increments by 1 for each message sent on a given channel.
+  // It is used to:
+  //
+  // - enforce ordering
+  // - detect duplicates or missing messages
+  // - support replay protection
+  //
+  // Implementations MAY also use this value to trigger automatic key rotation
+  // once a predefined threshold is reached.
+  uint32 sequence = 3;
+
+  // Channel identifier associated with this communication session.
+  //
+  // This value uniquely identifies the logical channel between an Owner and
+  // a Helper for a given secret. It is established during pairing and used
+  // thereafter to:
+  //
+  // - route messages to the correct channel state
+  // - select the appropriate cryptographic keys
+  //
+  // This MUST match the channelId exchanged during the ContactMessage phase.
+  uint64 channelId = 4;
+
+  // Timestamp indicating when the sender created this message.
+  //
+  // This value is expressed in UTC and can be used for:
+  //
+  // - replay detection
+  // - timeout handling
+  // - logging and observability
+  //
+  // Implementations SHOULD NOT rely solely on this value for security-critical
+  // decisions without additional protections.
+  google.protobuf.Timestamp timestamp = 5;
+
+  // Encrypted message payload.
+  //
+  // This field contains the encrypted bytes of a serialized MessageBody.
+  // The encryption scheme and key material are defined by the pairing process
+  // and subsequent key management flows.
+  //
+  // Upon decryption, this field MUST deserialize into a valid MessageBody
+  // containing exactly one protocol message.
+  bytes message = 6;
+
+  // Application-supplied correlation token, echoed verbatim by the
+  // responder on the matching response envelope.
+  //
+  // # Purpose
+  //
+  // Lets the side that originated a request match the eventual response to
+  // the in-flight request that produced it, even when:
+  //
+  // - multiple requests are outstanding on the same channel,
+  // - responses arrive out of order with respect to send order,
+  // - the responder takes arbitrary time to reply.
+  //
+  // # Semantics
+  //
+  // - On a request envelope: the requester sets this to any value it can
+  //  use to correlate the response back to the originating call site. A
+  //  random `uint64` is a typical choice; collisions are unlikely at any
+  //  realistic concurrency level.
+  // - On a response envelope: the responder MUST copy the request's
+  //  `traceId` verbatim. The library does this automatically in every
+  //  response producer.
+  // - Zero (the protobuf default when unset) is treated as "no correlation
+  //  requested." Responders still echo the zero on the response envelope;
+  //  requesters that do not care about correlation simply ignore the
+  //  field.
+  //
+  // # Privacy
+  //
+  // This field is plaintext on the wire (the envelope is not encrypted).
+  // The token itself is opaque, so it carries no information about either
+  // peer's identity or intent — it is purely a correlation handle. Passive
+  // observers could already correlate request/response pairs by channelId
+  // and timing; `traceId` does not add to that exposure.
+  uint64 traceId = 7;
+
+  // MessageBody defines all possible DeRec protocol messages that can be
+  // transported inside the DeRecMessage envelope.
+  //
+  // Exactly one of the fields MUST be set when constructing a message.
+  message MessageBody {
+    oneof body {
+      PairRequestMessage pairRequestMessage = 1;
+      PairResponseMessage pairResponseMessage = 2;
+      UnpairRequestMessage unpairRequestMessage = 3;
+      UnpairResponseMessage unpairResponseMessage = 4;
+      StoreShareRequestMessage storeShareRequestMessage = 5;
+      StoreShareResponseMessage storeShareResponseMessage = 6;
+      VerifyShareRequestMessage verifyShareRequestMessage = 7;
+      VerifyShareResponseMessage verifyShareResponseMessage = 8;
+      GetSecretIdsVersionsRequestMessage getSecretIdsVersionsRequestMessage = 9;
+      GetSecretIdsVersionsResponseMessage getSecretIdsVersionsResponseMessage = 10;
+      GetShareRequestMessage getShareRequestMessage = 11;
+      GetShareResponseMessage getShareResponseMessage = 12;
+      ErrorResponseMessage errorResponseMessage = 13;
+      UpdateChannelInfoRequestMessage updateChannelInfoRequestMessage = 14;
+      UpdateChannelInfoResponseMessage updateChannelInfoResponseMessage = 15;
+      PrePairRequestMessage prePairRequestMessage = 16;
+      PrePairResponseMessage prePairResponseMessage = 17;
+    }
+  }
+}

package/proto/derecsecret.proto

@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+import "result.proto";
+import "parameterrange.proto";
+import "google/protobuf/timestamp.proto";
+
+package org.derecalliance.derec.protobuf;
+
+
+// HelperSpecificInfo captures per-helper metadata associated with a secret.
+//
+// # Purpose
+//
+// This message binds a specific Helper to:
+//
+// - its identity (via a hash of its public encryption key)
+// - the parameters agreed during pairing with the Owner
+//
+// This information allows the Owner to:
+//
+// - track which Helpers are associated with a given secret
+// - reconstruct the correct configuration during recovery
+// - verify that Helpers are operating under the expected parameters
+//
+// # Semantics
+//
+// Each entry represents one Helper participating in the secret sharing
+// scheme. The collection of these entries defines the Helper set for
+// a given version of the secret.
+//
+// # Identity Binding
+//
+// The `helper` field is a SHA-384 hash of the Helper's public encryption
+// key. This provides a stable identifier without exposing the key itself.
+//
+// Implementations MUST ensure that:
+//
+// - the hash corresponds to the exact public key used during pairing
+// - the mapping between Helper identity and key is preserved
+//
+// # Parameter Agreement
+//
+// The `helperParams` field records the parameter range agreed between
+// the Owner and the Helper during pairing. This ensures that:
+//
+// - the share distribution is consistent with negotiated constraints
+// - recovery can validate expected parameters
+message HelperSpecificInfo {
+
+  // SHA-384 hash of the Helper's public encryption key.
+  //
+  // This uniquely identifies the Helper within the context of the secret
+  // without exposing the raw key material.
+  bytes helper = 1;
+
+  // Parameters agreed upon between the Helper and the Owner.
+  //
+  // These parameters originate from the intersection of both parties'
+  // supported ranges during pairing.
+  ParameterRange helperParams = 2;
+}
+
+
+// DeRecSecret represents the canonical structure of the secret material
+// that is encrypted and distributed across Helpers.
+//
+// # Context
+//
+// Before distribution:
+//
+// - the Owner constructs a DeRecSecret
+// - the `secretData` is encrypted (e.g., via AES-GCM)
+// - the encryption key is split using a secret sharing scheme (e.g., Shamir)
+//
+// The resulting shares are then distributed to Helpers.
+//
+// This message defines the structure used by "share algorithm 0".
+//
+// # Semantics
+//
+// A DeRecSecret contains:
+//
+// - the raw secret payload
+// - metadata describing the sharing configuration
+// - the set of Helpers and their associated parameters
+//
+// This metadata is critical for:
+//
+// - reconstructing the secret during recovery
+// - validating the integrity and configuration of shares
+//
+// # Thresholds
+//
+// Two thresholds are defined:
+//
+// 1. Recovery threshold:
+//    - Minimum number of Helpers required to reconstruct the secret
+//
+// 2. Confirmation threshold:
+//    - Minimum number of Helpers that must acknowledge receipt of a new
+//      share version before older versions can be safely deleted
+//
+// # Security Considerations
+//
+// - The entire DeRecSecret MUST be encrypted before distribution
+// - Helpers MUST NOT have access to the plaintext secretData
+// - Metadata should not leak sensitive information beyond what is required
+//
+// # Versioning
+//
+// Each share distribution version implicitly corresponds to a snapshot
+// of this structure. Changes to:
+//
+// - secretData
+// - helper set
+// - thresholds
+//
+// result in a new version being generated and distributed.
+message DeRecSecret {
+
+  // Arbitrary secret payload.
+  //
+  // This may include cryptographic keys, credentials, documents, or any
+  // serialized data the Owner wishes to protect. When produced by the DeRec
+  // library, these bytes are the recoverable secret: a 1-byte version prefix
+  // followed by a versioned payload (v1 = gzip-compressed (RFC 1952) JSON,
+  // base64 (RFC 4648 §4) byte fields, u64 as decimal strings). Other payloads
+  // MAY use a different encoding; secretData is opaque to the protocol.
+  bytes secretData = 1;
+
+  // Timestamp indicating when this secret (or this version of it) was created.
+  //
+  // Used for auditing, version tracking, and observability.
+  google.protobuf.Timestamp creationTime = 2;
+
+  // Minimum number of Helpers required to reconstruct the secret.
+  //
+  // This corresponds to the threshold parameter of the underlying
+  // secret sharing scheme.
+  int64 helperThresholdForRecovery = 3;
+
+  // Minimum number of Helpers that must confirm receipt of a share
+  // before older versions can be deleted.
+  //
+  // This ensures that sufficient redundancy exists before removing
+  // previous share versions.
+  int64 helperThresholdForConfirmingShareReceipt = 4;
+
+  // List of Helpers participating in this secret.
+  //
+  // Each entry defines:
+  //
+  // - the identity of the Helper
+  // - the parameters agreed with that Helper
+  //
+  // The size of this list defines the total number of shares generated.
+  repeated HelperSpecificInfo helpers = 5;
+}

package/proto/derectransport.proto

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+package org.derecalliance.derec.protobuf;
+
+import "derecmessage.proto";
+import "google/protobuf/empty.proto";
+
+/// Delivery service for DeRec messages over gRPC.
+///
+/// Mirrors the request/response-free delivery model the protocol already
+/// uses: a sender hands one envelope to one endpoint and learns only whether
+/// delivery succeeded.
+///
+/// # Push-only
+///
+/// `Send` returns `google.protobuf.Empty`. There is no inline reply. A
+/// responder answers by opening a new `Send` to the requester's own
+/// endpoint, which means **both parties must run a reachable server**.
+/// Responses are correlated by the envelope's `traceId`, not by the call.
+///
+/// # Security
+///
+/// This service provides no security guarantees of its own. Every
+/// `DeRecMessage` carries its payload signed and encrypted at the
+/// application layer, and remains valid regardless of transport.
+service DeRecTransport {
+  /// Deliver one DeRec envelope to this endpoint.
+  ///
+  /// Returns once the receiver has accepted the envelope for processing.
+  /// Acceptance is not a protocol-level acknowledgement: a protocol
+  /// response, if any, arrives as a separate `Send` call.
+  rpc Send(DeRecMessage) returns (google.protobuf.Empty);
+}

package/proto/error.proto

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+import "result.proto";
+
+package org.derecalliance.derec.protobuf;
+
+// ErrorResponseMessage is a generic error response sent when a protocol
+// message cannot be processed successfully.
+//
+// # Context
+//
+// This message may be returned in response to any DeRecMessage when the
+// receiver encounters an error during processing.
+//
+// Typical scenarios include:
+//
+// - malformed or invalid message payloads
+// - unsupported or unknown message types
+// - protocol violations (e.g., invalid sequence, nonce mismatch)
+// - authorization or validation failures
+//
+// # Semantics
+//
+// This message indicates that:
+//
+// - the original request was not successfully processed
+// - no state change should be assumed by the sender
+//
+// The sender SHOULD:
+//
+// - inspect the `result` field to determine the cause of the failure
+// - decide whether to retry, abort, or escalate based on the error
+//
+// # Usage Guidelines
+//
+// - This message is intended as a fallback when no more specific response
+//  type is applicable
+// - Protocol-specific errors SHOULD use their corresponding response
+//  messages when available
+//
+// # Security Considerations
+//
+// - Error responses SHOULD avoid leaking sensitive internal details
+// - Only high-level error information should be exposed via `result`
+//
+// # Idempotency
+//
+// Error responses are idempotent and may be returned multiple times
+// for repeated invalid requests.
+message ErrorResponseMessage {
+  // Result describing the error encountered while processing the request.
+  //
+  // This field encodes the error type and any associated status information.
+  DeRecResult result = 1;
+}

package/proto/getshare.proto

@@ -0,0 +1,194 @@
+/*
+ * 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;
+
+// GetShareRequestMessage requests a previously stored share from a Helper.
+//
+// # Context
+//
+// This message is used during the recovery flow, after pairing has been
+// established (typically in recovery mode). Once a Helper has indicated
+// which secret IDs and versions it holds, the Owner sends this request
+// to retrieve specific shares.
+//
+// # Semantics
+//
+// The request identifies a share by:
+//
+// - `secretId`: the identifier of the protected secret
+// - `version`: the version of the share distribution
+//
+// The Helper is expected to locate the corresponding share and return it
+// in a GetShareResponseMessage.
+//
+// # Authorization Rules
+//
+// The Helper MUST only process this request if it is received through a
+// valid communication channel that is authorized to access the requested
+// share. Specifically:
+//
+// - the request MUST originate from the same secretId channel, OR
+// - the request MUST originate from a channel established in recovery mode
+//  and associated with the same user
+//
+// Otherwise, the Helper MUST reject the request.
+//
+// # Idempotency
+//
+// This request is idempotent. Repeated requests for the same (secretId,
+// version) pair SHOULD return the same result.
+message GetShareRequestMessage {
+
+  // Numeric identifier of the secret for which the share is requested.
+  //
+  // Generated by the Owner when the secret is created. It uniquely
+  // identifies the secret within the context of the Owner and its Helpers.
+  uint64 secretId = 1;
+
+  // Version of the share being requested.
+  //
+  // Each time a secret is reshared (e.g., due to updates or changes in
+  // helper set), a new version is created. This field specifies which
+  // version of the share should be returned.
+  uint32 version = 2;
+
+  // 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 = 3;
+
+  // 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 = 4 [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;
+
+  // Identity of the replica-group member this message concerns.
+  //
+  // Present **only** on the replica path, where a member drives catch-up
+  // against another member. Absent on the owner ↔ helper path, which is
+  // unchanged.
+  //
+  // Every member of a group is addressed on one shared `channel_id`, so the
+  // channel cannot name the peer — this field does. Its presence is also what
+  // tells the receiver which path a message belongs to.
+  optional uint64 replicaId = 5;
+}
+
+// GetShareResponseMessage returns a share previously stored by the Helper.
+//
+// # Semantics
+//
+// This message is sent in response to a GetShareRequestMessage. It either:
+//
+// - returns the requested share (on success), or
+// - indicates failure via the `result` field
+//
+// # Authorization Enforcement
+//
+// The Helper MUST ensure that the request satisfies the authorization rules
+// described in GetShareRequestMessage before returning any share data.
+//
+// # Share Contents
+//
+// The returned share is an opaque byte sequence that typically includes:
+//
+// - the Shamir share (x, y)
+// - the encrypted secret payload (or a reference to it)
+// - the commitment (e.g., Merkle root)
+// - the opening proof for verification
+//
+// The exact structure is defined by the share algorithm indicated in
+// `shareAlgorithm`.
+//
+// # Security Considerations
+//
+// - The share MUST only be returned over an authenticated and encrypted
+//  DeRec channel
+// - Incorrect or malicious shares may be detected by the Owner during
+//  recovery using commitment verification
+//
+// # Idempotency
+//
+// For a given (secretId, version), repeated responses SHOULD return
+// the same share data.
+message GetShareResponseMessage {
+
+  // Result of processing the request.
+  //
+  // Indicates whether the share was successfully retrieved or if an error
+  // occurred (e.g., unauthorized request, unknown secretId, or missing version).
+  DeRecResult result = 1;
+
+  // The committed DeRec share.
+  //
+  // This is an opaque byte array containing the share data as produced by
+  // the share distribution algorithm. Its internal structure depends on
+  // `shareAlgorithm`.
+  bytes committedDeRecShare = 2;
+
+  // Identifier of the share algorithm used to produce the share.
+  //
+  // This allows the recipient to interpret and process the share correctly
+  // during verification and reconstruction.
+  int32 shareAlgorithm = 3;
+
+  // Timestamp indicating when this message was created.
+  //
+  // This value is expressed in UTC and can be used for observability,
+  // replay detection, and timeout handling.
+  google.protobuf.Timestamp timestamp = 4;
+
+  // Identifier of the secret to which this response refers.
+  //
+  // Echoed from the corresponding GetShareRequestMessage so the Owner can
+  // correlate responses with the correct pending recovery without inspecting
+  // the share bytes. Required when the Owner has multiple recoveries in
+  // progress concurrently, or to defend against stale responses from a
+  // previously-abandoned recovery attempt.
+  uint64 secretId = 5;
+
+  // Version of the share being returned.
+  //
+  // Echoed from the corresponding GetShareRequestMessage for the same
+  // correlation reasons as `secretId`.
+  uint32 version = 6;
+
+  // Identity of the replica-group member this message concerns.
+  //
+  // Present **only** on the replica path, where a member drives catch-up
+  // against another member. Absent on the owner ↔ helper path, which is
+  // unchanged.
+  //
+  // Every member of a group is addressed on one shared `channel_id`, so the
+  // channel cannot name the peer — this field does. Its presence is also what
+  // tells the receiver which path a message belongs to.
+  optional uint64 replicaId = 7;
+}