@derec-alliance/nodejs 0.0.2 → 0.0.4

package/proto/result.proto

@@ -0,0 +1,194 @@
+/*
+ * Copyright (c) DeRec Alliance and its Contributors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+package org.derecalliance.derec.protobuf;
+
+// Result represents the outcome of processing a DeRec protocol request.
+//
+// # Purpose
+//
+// This message is included in response messages to communicate:
+//
+// - whether a request was successfully processed
+// - the type of failure (if any)
+// - optional human-readable context for debugging or user display
+//
+// # Semantics
+//
+// A Result consists of:
+//
+// - a machine-readable `status` code
+// - an optional `memo` providing additional context
+//
+// The `status` field MUST be used by implementations to determine
+// protocol behavior. The `memo` field is informational only.
+//
+// # Usage
+//
+// - Every response message that can fail SHOULD include a Result
+// - Senders MUST inspect the `status` field to determine next steps
+// - The `memo` field MAY be displayed to users or logged for diagnostics
+//
+// # Security Considerations
+//
+// - The `memo` field SHOULD NOT include sensitive internal details
+// - Only high-level or user-safe information should be exposed
+//
+// # Idempotency
+//
+// The Result reflects the outcome of a specific request. Repeated identical
+// requests SHOULD produce consistent Result values unless system state changes.
+message DeRecResult {
+  // Status code indicating the outcome of the request.
+  StatusEnum status = 1;
+
+  // Optional human-readable description providing additional details.
+  //
+  // This field is intended for debugging, logging, or user display.
+  // It MUST NOT be relied upon for programmatic decision-making.
+  string memo = 2;
+}
+
+// StatusEnum defines the set of possible outcomes for processing
+// DeRec protocol requests.
+//
+// # Semantics
+//
+// These values are used across all response messages to provide a consistent
+// interpretation of success and failure conditions.
+//
+// Implementations MUST handle all known values and SHOULD safely ignore
+// unknown values for forward compatibility.
+enum StatusEnum {
+
+  // The request was successfully handled.
+  //
+  // No further action is required by the sender.
+  OK = 0;
+
+  // The request was partially fulfilled.
+  //
+  // The `memo` field SHOULD provide additional context explaining which
+  // parts succeeded and which did not.
+  PARTIAL = 1;
+
+  // The request failed for a generic or unspecified reason.
+  //
+  // The `memo` field MAY provide additional details.
+  FAIL = 2;
+
+  // The request failed because it would exceed the allowed storage limit
+  // for this sharer and secret ID.
+  //
+  // This typically applies to share storage operations.
+  SIZE_LIMIT_EXCEEDED = 3;
+
+  // The request was ignored because it exceeded the allowed frequency.
+  //
+  // This may be used for rate limiting to prevent abuse or excessive load.
+  TOO_FREQUENT = 4;
+
+  // The specified secret ID is not recognized by the Helper.
+  //
+  // This may occur during recovery or share retrieval.
+  UNKNOWN_SECRET_ID = 5;
+
+  // The specified share version does not exist for the given secret ID.
+  //
+  // This may occur if the version was never stored or has been deleted.
+  UNKNOWN_SHARE_VERSION = 6;
+
+  // The message could not be decrypted successfully.
+  //
+  // This indicates a failure in the cryptographic layer, such as:
+  //
+  // - incorrect key material
+  // - corrupted ciphertext
+  DECRYPTION_FAILED = 7;
+
+  // The message signature or authentication could not be verified.
+  //
+  // This indicates that the message integrity or authenticity check failed.
+  VERIFICATION_FAILED = 8;
+
+  // The message format is invalid.
+  //
+  // This includes errors such as:
+  //
+  // - protobuf parsing failures
+  // - missing required fields
+  // - structurally invalid messages
+  FORMAT_ERROR = 9;
+
+  // The request was rejected by the counter-party
+  //
+  // This might be used to indicate the user or system that received the
+  // requested rejected it.
+  REJECTED = 10;
+
+  // The pair handshake failed because the two parties' advertised
+  // `ParameterRange` values do not overlap on at least one field
+  // (e.g. local `minShareSize` exceeds peer `maxShareSize`).
+  //
+  // Sent on a `PairResponseMessage`; the `memo` field SHOULD describe
+  // the offending field and the two `(min, max)` pairs so the
+  // initiator can surface a useful diagnostic.
+  INCOMPATIBLE_PARAMETER_RANGE = 11;
+
+  // The announced transport protocol is one the recipient cannot serve.
+  //
+  // Returned only for a transport change on an **already-established**
+  // channel — an `UpdateChannelInfo` announcing a switch the recipient
+  // cannot follow. The recipient still holds the peer's previous working
+  // endpoint, which is what makes this refusal deliverable at all.
+  //
+  // It is deliberately **not** used during pairing. Delivery is push-only,
+  // so a party that cannot reach a peer also cannot deliver a rejection to
+  // it; pairing incompatibility surfaces locally to the application
+  // instead.
+  UNSUPPORTED_TRANSPORT_PROTOCOL = 12;
+
+  // A share already exists for this (secretId, version) with different
+  // content, so the write was refused.
+  //
+  // Exactly one writer owns a version. A recipient stores the first write
+  // it sees at a version; a later write carrying different bytes is
+  // rejected with this status rather than overwriting or coexisting. A
+  // byte-identical re-send is an idempotent retry and returns `OK`.
+  //
+  // Because a single writer always derives `version` as
+  // `latest_version + 1`, it can never rewrite a version with different
+  // content. Receiving this status therefore means a *second* writer
+  // published concurrently — typically the same user acting on two
+  // devices at once. Resolution is the application's responsibility: the
+  // round has failed and should be republished at a new version.
+  VERSION_CONFLICT = 13;
+
+  // A replica pairing named a `replicaId` that is already in use by another
+  // member of the group — including the recipient itself.
+  //
+  // Every member of a group must be uniquely identified: the roster is keyed
+  // by `replicaId`, and messages between members are attributed by it. Two
+  // members sharing an id would overwrite each other's roster row and make
+  // every acknowledgement ambiguous.
+  //
+  // `replicaId` is assigned by the application, so a collision is a
+  // configuration fault — most often the same identity reused on two devices,
+  // such as a cloned device image. Resolution is the application's: assign a
+  // distinct id and pair again. The protocol cannot pick one, because it
+  // cannot know which device is meant to keep the original.
+  //
+  // Reported before fingerprint verification: there is no point asking a user
+  // to confirm a pairing that cannot be completed.
+  REPLICA_ID_CONFLICT = 14;
+
+  // The Helper is requesting that the Owner terminate the relationship.
+  //
+  // The Owner SHOULD respond by sending an UnpairRequestMessage and
+  // ceasing further communication on the channel.
+  REQUEST_TO_CLOSE = 99;
+}

package/proto/secretidsversions.proto

@@ -0,0 +1,209 @@
+/*
+ * 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;
+
+// GetSecretIdsVersionsRequestMessage requests the list of all secrets and
+// corresponding share versions that a Helper stores for a given Owner.
+//
+// # Context
+//
+// This message is used during the recovery flow, after the Owner has
+// re-paired with a Helper (typically in recovery mode).
+//
+// Since the recovering Owner does not know which secrets or versions
+// the Helper holds, this message allows discovery of:
+//
+// - all secretIds associated with the Owner
+// - all share versions stored for each secret
+//
+// # Semantics
+//
+// The Helper responds with a GetSecretIdsVersionsResponseMessage containing:
+//
+// - one entry per secretId
+// - the list of versions stored for each secret
+//
+// # Authorization Rules
+//
+// The Helper MUST only fully process this request if it is received through
+// a communication channel that was established in recovery mode and has been
+// associated (via authentication) with the same Owner as previously stored
+// secrets.
+//
+// If this condition is not met, the Helper MAY:
+//
+// - return only partial information (e.g., for the current channel), or
+// - reject the request entirely
+//
+// # Authentication
+//
+// The Helper MUST authenticate the requester at the application level before
+// disclosing any information about stored secrets. Authentication is outside
+// the scope of the protocol and may include:
+//
+// - in-person verification
+// - KYC processes
+// - biometrics or credentials
+//
+// # Idempotency
+//
+// This request is idempotent. Repeated requests SHOULD return the same
+// information unless the underlying storage changes.
+message GetSecretIdsVersionsRequestMessage {
+  // 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 = 1;
+
+  // 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 = 2 [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 = 4;
+
+  // 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 = 3;
+}
+
+
+// GetSecretIdsVersionsResponseMessage returns the list of all secrets and
+// their corresponding share versions stored by the Helper for the Owner.
+//
+// # Semantics
+//
+// Each entry in `secretList` represents:
+//
+// - a `secretId` previously shared by the Owner
+// - the list of share versions currently stored for that secret
+//
+// This allows the recovering Owner to:
+//
+// - discover which secrets exist
+// - determine which versions to request via GetShareRequestMessage
+//
+// # Authorization and Privacy
+//
+// The Helper MUST ensure that:
+//
+// - the requester is authenticated as the same Owner
+// - the request originates from a recovery-mode channel
+//
+// Only under these conditions may the Helper return the full list of secrets.
+//
+// Otherwise, the Helper MUST:
+//
+// - return partial data (e.g., only for the current secretId), or
+// - return a failure result
+//
+// # Security Considerations
+//
+// - This message reveals metadata about stored secrets
+// - It MUST only be sent over an authenticated and encrypted channel
+// - Unauthorized disclosure could leak information about user activity
+//
+// # Idempotency
+//
+// For a given Helper state, repeated responses SHOULD return the same data.
+message GetSecretIdsVersionsResponseMessage {
+
+  // Result of processing the request.
+  //
+  // Indicates whether the request was successfully processed or rejected.
+  DeRecResult result = 1;
+
+  // List of secrets and their stored versions.
+  //
+  // Each entry corresponds to one secretId and the versions available
+  // for that secret.
+  repeated VersionList secretList = 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;
+
+  // 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 = 4;
+
+  // VersionList groups the share versions stored for a single secretId.
+  //
+  // # Semantics
+  //
+  // - `secretId` uniquely identifies a secret
+  // - `versions` lists all share versions currently stored for that secret,
+  //  each paired with a human-readable description
+  //
+  // The order of versions is not significant unless defined by the
+  // implementation.
+  message VersionList {
+    // Identifier of the secret.
+    uint64 secretId = 1;
+
+    // List of share versions stored for this secret.
+    //
+    // Each entry carries the numeric version identifier together with the
+    // human-readable description that was supplied by the Owner when the
+    // share was stored. Descriptions help the recovering Owner identify
+    // which secret corresponds to which identifier without relying on
+    // raw bytes alone.
+    repeated VersionEntry versions = 2;
+
+    // One stored version of a secret, paired with its human-readable label.
+    message VersionEntry {
+      // Numeric version identifier.
+      uint32 version = 1;
+
+      // Human-readable description supplied by the Owner at share-storage time.
+      //
+      // May be empty if no description was provided.
+      string versionDescription = 2;
+    }
+  }
+}

package/proto/storeshare.proto

@@ -0,0 +1,274 @@
+/*
+ * 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;
+
+// StoreShareRequestMessage instructs a Helper to store a share for a given
+// secret and manage the set of retained share versions.
+//
+// # Context
+//
+// This message is used in the sharing flow when:
+//
+// - a new secret is created
+// - an existing secret is updated
+// - the helper set or recovery threshold changes
+//
+// The Owner sends this message to each Helper to:
+//
+// - store (or replace) a specific share version
+// - update the set of versions that must be retained (keepList)
+//
+// # Semantics
+//
+// This message may carry two independent instructions:
+//
+// 1. Share storage/update:
+//    - If `share` is present, the Helper MUST store this share under the
+//      specified `version`
+//    - If the version already exists, the Helper MUST replace it
+//
+// 2. Retention policy update:
+//    - If `keepList` is present, it defines the complete set of versions
+//      that MUST be retained
+//    - Any stored version not in `keepList` SHOULD be deleted
+//
+// If `keepList` is absent:
+//
+// - The Helper MUST preserve the existing keepList
+// - The Helper MUST add the new `version` to the retained set
+//
+// # Consistency Requirements
+//
+// The Owner MUST ensure that for a given (secretId, version):
+//
+// - all Helpers receive identical share contents
+//
+// It is an error for different shares to be associated with the same
+// version and secretId.
+//
+// # Replay Protection
+//
+// To prevent replay attacks:
+//
+// - If `version` is less than the latest stored version,
+//  the Helper MUST ignore the `keepList` field
+//
+// This ensures that stale messages cannot cause deletion of newer shares.
+//
+// # Share Opacity
+//
+// The Helper MUST treat the `share` field as opaque data. It is not required
+// to understand or validate the share contents.
+//
+// # Idempotency
+//
+// This message is idempotent:
+//
+// - Re-sending the same (version, share) pair SHOULD result in the same state
+// - Re-applying the same keepList SHOULD not change state after the first time
+message StoreShareRequestMessage {
+
+  // Share bytes to be stored by the Helper.
+  //
+  // This is an opaque byte array produced by the share distribution
+  // algorithm. The Helper MUST store it without interpretation.
+  bytes share = 1;
+
+  // Identifier of the algorithm used to produce the share.
+  //
+  // This allows the Owner and Helper to coordinate on how the share
+  // should be interpreted during recovery.
+  //
+  // Algorithm 0 defines the share as a serialized `CommittedDeRecShare`
+  // protobuf message (see DeRec cryptography repository).
+  //
+  // Implementations SHOULD support algorithm 0 for interoperability.
+  int32 shareAlgorithm = 2;
+
+
+  // Identifier of the secret to which this share belongs.
+  //
+  // Used by the Helper to associate the share with the correct secret in the
+  // share store under the composite key (channel_id, secret_id, version).
+  uint64 secretId = 3;
+
+  // Version number of the share.
+  //
+  // Each resharing event increments this value.
+  uint32 version = 4;
+
+  // List of share versions that MUST be retained by the Helper.
+  //
+  // Any stored version not included in this list SHOULD be deleted.
+  //
+  // If absent, the Helper MUST:
+  //
+  // - retain the existing keepList
+  // - add the current `version` to the retained set
+  //
+  // This field MUST be ignored if `version` is older than the latest
+  // version already stored, to prevent replay attacks.
+  repeated uint32 keepList = 5;
+
+  // Optional human-readable description of this share version.
+  //
+  // This field is visible to the Helper and is not intended to carry
+  // sensitive information. It may be used for debugging, labeling, or
+  // user-facing display.
+  string versionDescription = 6;
+
+  // Timestamp indicating when this message was created.
+  //
+  // Used for observability, replay detection, and timeout handling.
+  google.protobuf.Timestamp timestamp = 7;
+
+  // Ephemeral transport endpoints at which the requester wants to receive
+  // the response to *this exchange*, in its own preference order,
+  // overriding the channel's stored peer endpoints for this round-trip
+  // only.
+  //
+  // # When to use
+  //
+  // Set when the requester's outbound endpoint does not match the endpoint
+  // the responder has on file for the channel — for example a replica
+  // talking to a helper that was paired with a sibling replica. The
+  // responder routes the response here but does NOT persist these
+  // endpoints; use `UpdateChannelInfoRequestMessage` for permanent changes.
+  //
+  // # Semantics
+  //
+  // - Absent (the default): the responder routes to the endpoints stored on
+  //  its `Channel` record for this `channelId`.
+  // - Present: the responder routes this exchange's response here, and
+  //  leaves the stored endpoints unchanged.
+  //
+  // 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** for the same reason it
+  // is on `transportProtocol`: it is one entry of a list and may be absent.
+  // Resolve it against `replyToTransports` instead.
+  optional TransportProtocol replyTo = 8 [deprecated = true];
+
+  // Every ephemeral endpoint the requester wants this exchange's response
+  // delivered to, in its own preference order.
+  //
+  // # Semantics
+  //
+  // - Empty, and `replyTo` absent: the responder routes to the endpoints
+  //  stored on its `Channel` record for this `channelId`.
+  // - Empty, `replyTo` present: that one endpoint, which is how every
+  //  implementation predating this field asks.
+  // - Non-empty: the responder routes the response to any one of these, in
+  //  the order given, and leaves the stored endpoints unchanged. Delivery
+  //  to any one is success.
+  //
+  // # Why this is a new field rather than a wider `replyTo`
+  //
+  // `replyTo` was singular through 0.0.2. Re-tagging it `repeated` would
+  // have been wire-compatible in the read direction only: protobuf merges a
+  // repeated submessage into a singular reader field-by-field, so a 0.0.2
+  // peer decoding a multi-entry list sees the **last** entry, while the
+  // first entry is what every other compatibility rule in this release
+  // designates as the legacy-readable one. One list cannot be ordered to
+  // satisfy both. A new tag lets the singular field keep meaning exactly
+  // what it did — the same shape `supportedTransports` (contact.proto tag 9)
+  // uses beside `transportProtocol` (tag 7).
+  repeated TransportProtocol replyToTransports = 10;
+
+  // Identity of the replica that authored this update.
+  //
+  // # Audience
+  //
+  // This field is for **replicas only**. Helpers know nothing about
+  // replicas and never receive it:
+  //
+  // - helper-bound (`SHARE_ALGORITHM_VSS`) — MUST be absent.
+  // - replica-bound (`SHARE_ALGORITHM_REPLICA_SECRET`) — MUST be present.
+  //
+  // The invariant is `replicaId.is_some() == (shareAlgorithm ==
+  // SHARE_ALGORITHM_REPLICA_SECRET)`, asserted on send and on receive; a
+  // violation is a protocol error, not a tolerated variation.
+  //
+  // # Why the receiver needs it
+  //
+  // Every member of a replica group shares one `channelId`, so the
+  // channel identifies the *group*, not the sender. The channel's
+  // counterparty says who established it, which after admission by a
+  // third member is not who wrote this message. Author attribution
+  // therefore comes from this field and never from the channel record.
+  //
+  // Applications use it to resolve which member published an update, and
+  // to route the response back to that member's endpoint.
+  //
+  // # Out of scope for the protocol
+  //
+  // The protocol does not authenticate the claim; anyone holding the
+  // group key may write any `replicaId`. It is an identifier, not an
+  // authenticator.
+  optional uint64 replicaId = 9;
+}
+
+// StoreShareResponseMessage is the response to a StoreShareRequestMessage.
+//
+// # Semantics
+//
+// This message indicates whether the Helper successfully:
+//
+// - stored or updated the requested share version
+// - applied the retention policy (keepList)
+//
+// # Idempotency
+//
+// Multiple identical requests SHOULD produce identical responses.
+message StoreShareResponseMessage {
+
+  // Result of processing the request.
+  //
+  // Indicates success or failure of the storage/update operation.
+  DeRecResult result = 1;
+
+  // Identifier of the secret to which this response refers.
+  //
+  // Echoed from the corresponding StoreShareRequestMessage so the Owner can
+  // correlate responses with the correct secret without inspecting the share
+  // bytes.
+  uint64 secretId = 2;
+
+  // Version number from the corresponding request.
+  //
+  // This allows the sender to correlate responses with requests.
+  uint32 version = 3;
+
+  // Timestamp indicating when this message was created.
+  //
+  // Used for observability, replay detection, and timeout handling.
+  google.protobuf.Timestamp timestamp = 4;
+
+  // Identity of the replica that produced this response.
+  //
+  // Present only when the corresponding request was replica-bound
+  // (`shareAlgorithm == SHARE_ALGORITHM_REPLICA_SECRET`); absent on
+  // helper responses, which carry no replica identity in either
+  // direction.
+  //
+  // # Why the requester needs it
+  //
+  // Every member of a replica group answers on the same `channelId`, and
+  // `secretId` and `version` are echoed identically by all of them. Two
+  // members responding to one publish are otherwise indistinguishable —
+  // the requester cannot tell whether both acknowledged or one
+  // acknowledged twice, and so cannot track a sharing round per member.
+  optional uint64 replicaId = 5;
+}