# federation.capnp — Server-to-server federation RPC interface.
#
# Enables multiple quicproquo servers to relay messages across instances
# via mutual TLS over QUIC. Each method carries a FederationAuth struct whose
# `origin` field is validated against the mTLS certificate's SAN.
#
# ID generated with: capnp id
@0xb7e3f4a1c9d82056;

interface FederationService {
  # Relay an enqueued payload to a recipient on this server.
  relayEnqueue @0 (
    recipientKey :Data,
    payload      :Data,
    channelId    :Data,
    version      :UInt16,
    auth         :FederationAuth
  ) -> (seq :UInt64);

  # Relay a batch enqueue to multiple recipients on this server.
  relayBatchEnqueue @1 (
    recipientKeys :List(Data),
    payload       :Data,
    channelId     :Data,
    version       :UInt16,
    auth          :FederationAuth
  ) -> (seqs :List(UInt64));

  # Fetch a KeyPackage for an identity hosted on this server.
  proxyFetchKeyPackage @2 (
    identityKey :Data,
    auth        :FederationAuth
  ) -> (package :Data);

  # Fetch a hybrid public key for an identity hosted on this server.
  proxyFetchHybridKey @3 (
    identityKey :Data,
    auth        :FederationAuth
  ) -> (hybridPublicKey :Data);

  # Resolve a username to identity key on this server.
  proxyResolveUser @4 (
    username :Text,
    auth     :FederationAuth
  ) -> (identityKey :Data);

  # Health / readiness probe for the federation link.
  federationHealth @5 () -> (status :Text, serverDomain :Text);
}

struct FederationAuth {
  # Origin domain of the requesting server. Validated against mTLS cert SAN.
  origin @0 :Text;
}