quicproquo/schemas/node.capnp

# node.capnp — Unified quicproquo 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 (version=1, non-empty accessToken required).
  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 default). A 16-byte UUID
  #               is recommended for 1:1 channels.
  # version      : Schema/wire version. Must be 1.
  # Returns the monotonically increasing per-inbox sequence number assigned to this message,
  # plus a cryptographic delivery proof (96 bytes: 32-byte SHA-256 preimage || 64-byte Ed25519
  # signature). Old clients that do not read deliveryProof are unaffected (Cap'n Proto optional).
  enqueue @2 (recipientKey :Data, payload :Data, channelId :Data, version :UInt16, auth :Auth) -> (seq :UInt64, deliveryProof :Data);

  # Fetch and drain all queued payloads for the recipient.
  # limit: max number of messages to return (0 = fetch all).
  # Returns envelopes with per-inbox sequence numbers for ordered MLS processing.
  fetch @3 (recipientKey :Data, channelId :Data, version :UInt16, auth :Auth, limit :UInt32) -> (payloads :List(Envelope));

  # Long-poll: wait up to timeoutMs for new payloads, then drain queue.
  # limit: max number of messages to return (0 = fetch all).
  # Returns envelopes with per-inbox sequence numbers for ordered MLS processing.
  fetchWait @4 (recipientKey :Data, channelId :Data, version :UInt16, timeoutMs :UInt64, auth :Auth, limit :UInt32) -> (payloads :List(Envelope));

  # 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, auth :Auth) -> ();

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

  # ── OPAQUE password-authenticated registration ──────────────────────────

  # Start OPAQUE registration: client sends blinded password element.
  opaqueRegisterStart  @8 (username :Text, request :Data) -> (response :Data);

  # Finish OPAQUE registration: client uploads sealed credential envelope.
  opaqueRegisterFinish @9 (username :Text, upload :Data, identityKey :Data)  -> (success :Bool);

  # ── OPAQUE password-authenticated login ─────────────────────────────────

  # Start OPAQUE login: client sends credential request.
  opaqueLoginStart  @10 (username :Text, request :Data)     -> (response :Data);

  # Finish OPAQUE login: client sends credential finalization, receives session token.
  opaqueLoginFinish @11 (username :Text, finalization :Data, identityKey :Data) -> (sessionToken :Data);

  # ── P2P endpoint discovery ────────────────────────────────────────────────

  # Publish this node's iroh endpoint address for P2P connectivity.
  # nodeAddr is the serialized iroh NodeAddr (JSON or custom encoding).
  publishEndpoint @12 (identityKey :Data, nodeAddr :Data, auth :Auth) -> ();

  # Resolve a peer's iroh endpoint for direct P2P connection.
  resolveEndpoint @13 (identityKey :Data, auth :Auth) -> (nodeAddr :Data);

  # Peek at queued payloads without removing them (non-destructive read).
  # Returns envelopes sorted by seq. Use `ack` to remove processed messages.
  peek @14 (recipientKey :Data, channelId :Data, version :UInt16, auth :Auth, limit :UInt32) -> (payloads :List(Envelope));

  # Acknowledge (remove) all messages up to and including the given sequence number.
  ack @15 (recipientKey :Data, channelId :Data, version :UInt16, seqUpTo :UInt64, auth :Auth) -> ();

  # Fetch multiple peers' hybrid public keys in a single round-trip.
  fetchHybridKeys @16 (identityKeys :List(Data), auth :Auth) -> (keys :List(Data));

  # Enqueue the same payload to multiple recipients in a single round-trip.
  batchEnqueue @17 (recipientKeys :List(Data), payload :Data, channelId :Data, version :UInt16, auth :Auth) -> (seqs :List(UInt64));

  # Create a 1:1 channel between the caller and the given peer. Returns a 16-byte channelId (UUID).
  # Both members can enqueue/fetch for this channel; recipientKey must be the other member.
  # wasNew is true iff this call created the channel; false if it already existed.
  # The caller who receives wasNew=true is the MLS group initiator and must send the Welcome.
  # The caller who receives wasNew=false must wait for the peer's Welcome via the background poller.
  createChannel @18 (peerKey :Data, auth :Auth) -> (channelId :Data, wasNew :Bool);

  # Resolve a username to its Ed25519 identity key (32 bytes).
  # Returns empty Data if the username is not registered.
  # inclusionProof : bincode-serialised InclusionProof from quicproquo-kt, proving the
  #   (username, identityKey) binding is in the server's append-only Merkle log.
  #   Empty when the log entry is not yet available (e.g. legacy server or new registration
  #   that has not been committed to the log). Clients should verify when non-empty.
  resolveUser @19 (username :Text, auth :Auth) -> (identityKey :Data, inclusionProof :Data);

  # Reverse lookup: resolve an Ed25519 identity key to the registered username.
  # Returns empty Text if the identity key is not associated with any user.
  resolveIdentity @20 (identityKey :Data, auth :Auth) -> (username :Text);

  # Upload a blob chunk. The server reassembles chunks and verifies SHA-256 on completion.
  # blobHash  : expected SHA-256 hash (32 bytes) of the complete blob.
  # chunk     : raw bytes for this segment.
  # offset    : byte offset within the blob where this chunk starts.
  # totalSize : total size of the complete blob in bytes.
  # mimeType  : MIME type of the blob (e.g. "image/png").
  # Returns blobId = blobHash once the blob is fully uploaded and verified.
  uploadBlob @21 (auth :Auth, blobHash :Data, chunk :Data, offset :UInt64, totalSize :UInt64, mimeType :Text) -> (blobId :Data);

  # Download a blob chunk. Returns up to `length` bytes starting at `offset`.
  # blobId    : the blob identifier (SHA-256 hash returned by uploadBlob).
  # offset    : byte offset within the blob to start reading from.
  # length    : maximum number of bytes to return (capped at 256 KB).
  # Returns the requested chunk, the total blob size, and its MIME type.
  downloadBlob @22 (auth :Auth, blobId :Data, offset :UInt64, length :UInt32) -> (chunk :Data, totalSize :UInt64, mimeType :Text);
}

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

# A delivery envelope pairing a per-inbox sequence number with an opaque payload.
# Clients sort by `seq` before processing to guarantee MLS commit ordering.
struct Envelope {
  seq  @0 :UInt64; # monotonically increasing per-inbox counter (assigned by server)
  data @1 :Data;   # opaque payload (hybrid-encrypted MLS message)
}