# node.capnp — Unified quicnprotochat node RPC interface.
#
# Combines Authentication and Delivery operations into a single service.
#
# ID generated with: capnp id
@0xd5ca5648a9cc1c28;

interface NodeService {
  # Upload a single-use KeyPackage for later retrieval by peers.
  # identityKey : Ed25519 public key bytes (32 bytes)
  # package     : TLS-encoded openmls KeyPackage
  # auth        : Auth context (versioned). For legacy clients, pass an empty
  #               struct or version=0.
  uploadKeyPackage @0 (identityKey :Data, package :Data, auth :Auth) -> (fingerprint :Data);

  # Fetch and atomically remove one KeyPackage for a given identity key.
  # Returns empty Data if none are stored.
  fetchKeyPackage  @1 (identityKey :Data, auth :Auth) -> (package :Data);

  # Enqueue an opaque payload for delivery to a recipient.
  # channelId : Optional channel identifier (empty for legacy). A 16-byte UUID
  #             is recommended for 1:1 channels.
  # version   : Schema/wire version. Must be 0 (legacy) or 1 (this spec).
  enqueue @2 (recipientKey :Data, payload :Data, channelId :Data, version :UInt16, auth :Auth) -> ();

  # Fetch and drain all queued payloads for the recipient.
  fetch @3 (recipientKey :Data, channelId :Data, version :UInt16, auth :Auth) -> (payloads :List(Data));

  # Long-poll: wait up to timeoutMs for new payloads, then drain queue.
  fetchWait @4 (recipientKey :Data, channelId :Data, version :UInt16, timeoutMs :UInt64, auth :Auth) -> (payloads :List(Data));

  # Health probe for readiness/liveness.
  health @5 () -> (status :Text);

  # Upload the hybrid (X25519 + ML-KEM-768) public key for sealed envelope encryption.
  uploadHybridKey @6 (identityKey :Data, hybridPublicKey :Data) -> ();

  # Fetch a peer's hybrid public key (for post-quantum envelope encryption).
  fetchHybridKey  @7 (identityKey :Data) -> (hybridPublicKey :Data);
}

struct Auth {
  version @0 :UInt16;   # 0 = legacy/none, 1 = token-based auth
  accessToken @1 :Data; # opaque bearer token issued at login
  deviceId @2 :Data;    # optional UUID bytes for auditing/rate limiting
}