##
## COMMON DATA TYPES
##

# 32-byte BLAKE3 hash
type Blake3Digest32 data[32]

# Hash digest
type Digest union { Blake3Digest32 }

# ChaCha20 key
type ChaCha20Key data[32]

# Symmetric key
type SymKey union { ChaCha20Key }

# Curve25519 public key
type Curve25519PubKey data[32]

# Curve25519 private key
type Curve25519PrivKey data[32]

# Public key
type PubKey union { Curve25519PubKey }

# Private key
type PrivKey union { Curve25519PrivKey }

# Ed25519 signature
type Ed25519Sig data[64]

# Cryptographic signature
type Sig union { Ed25519Sig }

# Timestamp: absolute time in minutes since 2022-02-22 22:22 UTC
type Timestamp u32

# Relative time in seconds
type Seconds u8

# Relative time in minutes
type Minutes u8

# Relative time in hours
type Hours u8

# Relative time in days
type Days u8

# Relative time (e.g. delay from current time)
type RelTime union {
  | Seconds | Minutes | Hours | Days
}

##
## STORAGE OBJECTS
##

# Block ID
#
# BLAKE3 hash over the serialized Block with encrypted content.
type BlockId Digest

# Block reference
type BlockRef struct {
  # Block ID
  id: BlockId

  # Key for decrypting the Block
  key: SymKey
}

# ID of the root block of a Merkle tree
type ObjectId BlockId

# Object reference
type ObjectRef BlockRef

# Internal node of a Merkle tree
type InternalNode list<SymKey>

# Data chunk at a leaf of a Merkle tree
type DataChunk data

# Content of a Block
type BlockContentV0 union {
  # Internal node with references to children
  | InternalNode

  # Leaf node with encrypted data chunk
  | DataChunk
}

# List of Object dependencies stored in an Object
type DepList union {
  list<ObjectId>
}

# Dependencies of an Object,
# referenced from the root Block
type ObjectDeps union {
  # List of Object IDs
  | list<ObjectId>

  # Reference to an Object that contains a DepList
  | ObjectRef
}

# Immutable block with encrypted content
#
# Object content is chunked and stored as blocks in a Merkle tree.
# A Block is a Merkle tree node.
type BlockV0 struct {
  # BlockIds for child nodes in the Merkle tree
  children: list<BlockId>

  # Other objects this object depends on (e.g. Commit deps & acks)
  # only set for the root Block
  deps: ObjectDeps

  # Expiry time of this block and all of its children
  # when the block should be deleted by all replicas
  expiry: optional<Timestamp>

  # Encrypted BlockContentV0
  #
  # Encrypted using convergent encryption with ChaCha20:
  # - convergence_key: BLAKE3 derive_key ("LoFiRe Data BLAKE3 key",
  #                                       repo_pubkey + repo_secret)
  # - key: BLAKE3 keyed hash (convergence_key, plain_block)
  # - nonce: 0
  content: data # BlockContentV0
}
type Block union { BlockV0 }

# Repository definition
#
# Published in root branch, where:
# - branch_pubkey: repo_pubkey
# - branch_secret: BLAKE3 derive_key ("LoFiRe Root Branch secret",
#                                     repo_pubkey + repo_secret)
type RepositoryV0 struct {
  # Repo public key ID
  id: PubKey

  # List of branches
  branches: list<ObjectRef>

  # Whether or not to allow external requests
  allowExtRequests: bool

  # App-specific metadata
  metadata: data
}
type Repository union { RepositoryV0 }

# Add a branch to the repository
type AddBranchV0 ObjectRef
type AddBranch union { AddBranchV0 }

# Remove a branch from the repository
type RemoveBranchV0 ObjectRef
type RemoveBranch union { RemoveBranchV0 }

# Commit block types
type CommitType enum {
  REPOSITORY ADD_BRANCH REMOVE_BRANCH
  BRANCH ADD_MEMBERS END_OF_BRANCH
  TRANSACTION SNAPSHOT COMMIT_ACK
}

# Member of a branch
type MemberV0 struct {
  # Member public key ID
  id: PubKey

  # Commit types the member is allowed to publish in the branch
  commitTypes: list<CommitType>

  # App-specific metadata
  # (role, permissions, cryptographic material, etc)
  metadata: data
}
type Member union { MemberV0 }

# Branch definition
#
# First commit in a branch, signed by branch key
# In case of a fork, the commit deps indicate the previous branch heads.
type BranchV0 struct {
  # Branch public key ID
  id: PubKey

  # Pub/sub topic for publishing events
  topic: PubKey

  # Branch secret key
  secret: SymKey

  # Members with permissions
  members: list<Member>

  # Number of acks required for a commit to be valid
  quorum: map<CommitType><u32>

  # Delay to send explicit acks, if not enough implicit acks arrived by then
  ackDelay: RelTime

  # Tags for organizing branches within the repository
  tags: list<data>

  # App-specific metadata (validation rules, etc)
  metadata: data
}
type Branch union { BranchV0 }

# Add members to an existing branch
#
# If a member already exists, it overwrites the previous definition,
# in that case this can only be used for adding new permissions,
# not to remove existing ones.
# The quorum and ackDelay can be changed as well.
type AddMembersV0 struct {
  # Members to add, with permissions
  members: list<Member>

  # New quorum
  quorum: optional<map<CommitType><u32>>

  # New ackDelay
  ackDelay: optional<RelTime>
}
type AddMembers union { AddMembersV0 }

type PlainOrEncryptedObjectRef union {
  | ObjectRef
  | data       # Encrypted ObjectRef
}

# End of branch
#
# No more commits accepted afterwards, only acks of this commit.
# May reference a fork where the branch continues
# with possibly different members, permissions, validation rules.
type EndOfBranchV0 struct {
  # (Encrypted) reference to forked branch (optional)
  fork: optional<PlainOrEncryptedObjectRef>

  # Expiry time when all commits in the branch should be deleted
  expiry: Timestamp
}
type EndOfBranch union { EndOfBranchV0 }

# Transaction with CRDT operations
type TransactionV0 data
type Transaction union { TransactionV0 }

# Snapshot of a Branch
#
# Contains a data structure computed from the commits at the specified head.
type SnapshotV0 struct {
  # Branch heads the snapshot was made from
  heads: list<ObjectId>

  # Snapshot data structure
  content: data
}
type Snapshot union { SnapshotV0 }

# Acknowledgement of another Commit
type Ack union {
  void
}

# Commit body, corresponds to CommitType
type CommitBody union {
  | Repository | AddBranch | RemoveBranch
  | Branch | AddMembers | EndOfBranch
  | Transaction | Snapshot | Ack
}

# Content of CommitV0
type CommitContentV0 struct {
  # Commit author
  author: PubKey

  # Author's commit sequence number in this branch
  seq: u32

  # Branch the commit belongs to
  branch: ObjectRef

  # Direct dependencies of this commit
  deps: list<ObjectRef>

  # Not directly dependent heads to acknowledge
  acks: list<ObjectRef>

  # Files the commit references
  refs: list<ObjectRef>

  # App-specific metadata (commit message, creation time, etc)
  metadata: data

  # Block with a CommitBody inside
  body: ObjectRef

  # Expiry time of the body block
  expiry: optional<Timestamp>
}

# Commit Object
#
# Signed by branch key, or a member key authorized to publish this commit type.
type CommitV0 struct {
  content: CommitContentV0

  # Signature over the content by the author
   sig: Sig
}
type Commit union { CommitV0 }

# File Object
type FileV0 struct {
  contentType: data
  metadata: data
  content: data
}
type File union { FileV0 }

# Immutable object content stored in encrypted blocks of a Merkle tree
type ObjectContent union {
  | Commit | CommitBody | File | DepList
}

##
## COMMON DATA TYPES FOR MESSAGES
##

# Peer ID
type PeerId PubKey

# Overlay ID
#
# - for public overlays that need to be discovered by public key:
#   BLAKE3 hash over the repository public key
# - for private overlays:
#   BLAKE3 keyed hash over the repository public key
#   - key: BLAKE3 derive_key ("LoFiRe OverlayId BLAKE3 key", repo_secret)
type OverlayId Digest

# Overlay session ID
#
# Used as a component for key derivation.
# Each peer generates it randomly when (re)joining the overlay network.
type SessionId u64

# Topic ID
type TopicId PubKey

# Result code
type Result enum { OK ERROR }

# IP address
type IPv4 data[4]
type IPv6 data[16]
type IP union { IPv4 | IPv6 }

type IPTransportProtocol enum { TLS QUIC }

type IPTransportAddr struct {
  ip: IP
  port: u16
  protocol: IPTransportProtocol
}

# Network address
type NetAddr union { IPTransportAddr }

# Bloom filter (variable size)
type BloomFilter struct {
  # Number of hash functions
  k: u8

  # Filter
  f: data
}

# Bloom filter (128 B)
# (m=1024; k=7; p=0.01; n=107)
type BloomFilter128 data[128]

# Bloom filter (1 KiB)
# (m=8192; k=7; p=0.01; n=855)
type BloomFilter1K data[1024]

##
## OVERLAY MESSAGES
##

# Overlay connection request
#
# Sent to an existing overlay member to initiate a session.
type OverlayConnect union {
  void
}

# Overlay disconnection request
#
# Sent to a connected overlay member to terminate a session.
type OverlayDisconnect union {
  void
}

# Content of TopicAdvertV0
type TopicAdvertContentV0 struct {
  # Topic public key
  topic: PubKey

  # Peer public key
  peer: PeerId
}

# Topic advertisement by a publisher
#
# Flooded to all peers in overlay.
# Creates subscription routing table entries.
type TopicAdvertV0 struct {
  content: TopicAdvertContentV0

  # Signature over content by topic key
  sig: Sig
}
type TopicAdvert union { TopicAdvertV0 }

# Topic subscription request by a peer
#
# Forwarded towards all publishers along subscription routing table entries
# that are created by TopicAdverts.
# Creates event routing table entries along the path.
type SubReqV0 struct {
  # Random ID generated by the subscriber
  id: u64

  # Topic public key
  topic: PubKey
}
type SubReq union { SubReqV0 }

# Topic subscription acknowledgement by a publisher
#
# Sent to all subscribers in an Event.
type SubAckV0 struct {
  # SubReq ID to acknowledge
  id: u64
}
type SubAck union { SubAckV0 }

# Topic unsubscription request by a subscriber
#
# A broker unsubscribes from upstream brokers
# when it has no more subscribers left.
type UnsubReqV0 struct {
  # Topic public key
  topic: PubKey
}
type UnsubReq union { UnsubReqV0 }

# Topic unsubscription acknowledgement
# Sent to the requestor in response to an UnsubReq
type UnsubAckV0 struct {
  # Topic public key
  topic: PubKey
}
type UnsubAck union { UnsubAckV0 }

# Branch change notification
#
# Contains a chunk of a newly added Commit or File referenced by a commit.
type ChangeV0 struct {
  # Block with encrypted content
  content: Block

  # Encrypted key for the Commit object in content
  # Only set for the root block of the object
  # The key is encrypted using ChaCha20:
  # - key: BLAKE3 derive_key ("LoFiRe Change Object ChaCha20 key",
  #                           repo_pubkey + repo_secret +
  #                           branch_pubkey + branch_secret + publisher_pubkey)
  # - nonce: commit_seq
  key: optional<data[32]> # SymKey
}
type Change union { ChangeV0 }

# Body of EventContentV0
type EventBodyV0 union {
  | SubAck | Change
}

# Content of EventV0
type EventContentV0 struct {
  # Pub/sub topic
  topic: PubKey

  # Publisher pubkey encrypted with ChaCha20:
  # - key: BLAKE3 derive_key ("LoFiRe Event Publisher ChaCha20 key",
  #                           repo_pubkey + repo_secret +
  #                           branch_pubkey + branch_secret)
  publisher: data[32] # PubKey

  # Commit sequence number of publisher
  seq: u32

  # Event body
  body: EventBodyV0
}

# Pub/sub event published in a topic
#
# Forwarded along event routing table entries.
type EventV0 struct {
  content: EventContentV0

  # Signature over content by topic key
  sig: Sig
}
type Event union { EventV0 }

# Block search in a pub/sub topic
#
# Sent along the reverse path of a pub/sub topic
# from a subscriber to all publishers
type BlockSearchTopicV0 struct {
  # Topic to forward the request in
  topic: PubKey

  # List of BlockIds to request
  ids: list<BlockId>

  # Whether or not to include all children recursively in the response
  includeChildren: bool

  # List of Peer IDs the request traversed so far
  path: list<PeerId>
}
type BlockSearchTopic union { BlockSearchTopicV0 }

# Block search along a random walk
type BlockSearchRandomV0 struct {
  # List of BlockIds to request
  ids: list<BlockId>

  # Whether or not to include all children recursively in the response
  includeChildren: bool

  # Number of random nodes to forward the request to at each step
  fanout: u8

  # List of Peer IDs the request traversed so far
  path: list<PeerId>
}
type BlockSearchRandom union { BlockSearchRandomV0 }

# Response to a BlockSearch* request
#
# Follows request path with possible shortcuts.
type BlockResultV0 struct {
  # Response path
  path: list<PeerId>

  # Resulting Block(s)
  payload: list<Block>
}
type BlockResult union { BlockResultV0 }

# Request latest events corresponding to the branch heads in a pub/sub topic.
#
# In response an Event is sent for each commit chunk that belong to branch heads
# that are not present in the requestor's known heads.
type BranchHeadsReqV0 struct {
  # Topic public key of the branch
  topic: PubKey

  # Known heads
  knownHeads: list<ObjectId>
}
type BranchHeadsReq union { BranchHeadsReqV0 }

# Branch synchronization request
#
# In response a stream of Blocks of the requested Objects are sent
# that are not present in the requestor's known heads and commits
type BranchSyncReqV0 struct {
  # Heads to request, including all their dependencies
  heads: list<ObjectId>

  # Fully synchronized until these commits
  knownHeads: list<ObjectId>

  # Known commit IDs since knownHeads
  knownCommits: BloomFilter
}
type BranchSyncReq union { BranchSyncReqV0 }

# Events the requestor needs
type NeedEventsV0 struct {
  # Publisher ID
  publisher: Digest

  # First sequence number to request
  from: u32

  # Last sequence number to request
  to: u32
}

# Events the responder has
type HaveEventsV0 struct {
  # Publisher ID
  publisher: Digest

  # First sequence number to send
  from: u32

  # Last sequence number to send
  to: u32
}

# Request missed events for a pub/sub topic
# for the specified range of publisher sequence numbers.
#
# In response an EventResp then a stream of Events are sent.
type EventReqV0 struct {
  # Topic public key
  topic: PubKey

  # Events needed by the requestor
  need: list<NeedEventsV0>
}
type EventReq union { EventReqV0 }

# Response to an EventReq
type EventRespV0 struct {
  # Events the responder has
  have: list<HaveEventsV0>
}
type EventResp union { EventRespV0 }

# Content of OverlayRequestV0
type OverlayRequestContentV0 union {
  | EventReq
  | BranchHeadsReq
  | BranchSyncReq
}

# Request sent to an overlay
type OverlayRequestV0 struct {
  # Request ID
  id: u64

  # Request content
  content: OverlayRequestContentV0
}
type OverlayRequest union { OverlayRequestV0 }

# Content of OverlayResponse
type OverlayResponseContentV0 union {
  | Block
  | EventResp
  | Event
}

# Response to an OverlayRequest
type OverlayResponseV0 struct {
  # Request ID
  id: u64

  # Result
  result: u16

  # Response content
  content: optional<OverlayResponseContentV0>
}
type OverlayResponse union { OverlayResponseV0 }

# Content of PeerAdvertV0
type PeerAdvertContentV0 struct {
  # Peer ID
  peer: PeerId

  # Topic subscriptions
  subs: BloomFilter128

  # Network addresses
  address: list<NetAddr>

  # Version number
  version: u32

  # App-specific metadata (profile, cryptographic material, etc)
  metadata: data
}

# Peer advertisement
#
# Sent periodically across the overlay along random walks.
type PeerAdvertV0 struct {
  # Peer advertisement content
  content: PeerAdvertContentV0

  # Signature over content by peer's private key
  sig: Sig

  # Time-to-live, decremented at each hop
  ttl: u8
}
type PeerAdvert union { PeerAdvertV0 }

# Content of OverlayMessageContentPaddedV0
type OverlayMessageContentV0 union {
  | OverlayConnect | OverlayDisconnect
  | PeerAdvert | TopicAdvert
  | SubReq | SubAck
  | UnsubReq | UnsubAck
  | Event
  | BlockSearchTopic | BlockSearchRandom | BlockResult
  | OverlayRequest | OverlayResponse
}

# Padded content of OverlayMessageV0
type OverlayMessageContentPaddedV0 struct {
  content: OverlayMessageContentV0

  # Optional padding
  padding: data
}

# Overlay message
type OverlayMessageV0 struct {
  # Overlay ID
  overlay: OverlayId

  # Session ID
  session: SessionId

  # Padded content encrypted with ChaCha20
  #
  # - overlay_secret: BLAKE3 derive_key ("LoFiRe Overlay BLAKE3 key",
  #                                      repo_pubkey + repo_secret)
  # - key: BLAKE3 derive_key ("LoFiRe OverlayMessage ChaCha20 key",
  #                           overlay_secret + session_id)
  # - nonce: per-session message sequence number of sending peer
  content: data # OverlayMessageContentPaddedV0

  # BLAKE3 MAC
  # BLAKE3 keyed hash over the encrypted content
  # - key: BLAKE3 derive_key ("LoFiRe OverlayMessage BLAKE3 key",
  #                            overlay_secret + session_id)
  mac: Digest
}
type OverlayMessage union { OverlayMessageV0 }

##
## BROKER MESSAGES
##

# Content of AddUserV0
type AddUserContentV0 struct {
  # User pub key
  user: PubKey
}

# Add user account
type AddUserV0 struct {
  content: AddUserContentV0

  # Signature by admin key
  sig: Sig
}
type AddUser union { AddUserV0 }

# Content of DelUserV0
type DelUserContentV0 struct {
  # User pub key
  user: PubKey
}

# Delete user account
type DelUserV0 struct {
  content: DelUserContentV0

  # Signature by admin key
  sig: Sig
}
type DelUser union { DelUserV0 }

# Content of AddClientV0
type AddClientContentV0 struct {
  # Client pub key
  client: PubKey
}

# Add a client
type AddClientV0 struct {
  content: AddClientContentV0

  # Signature by user key
  sig: Sig
}
type AddClient union { AddClientV0 }

# Content of DelClientV0
type DelClientContentV0 struct {
  # Client pub key
  client: PubKey
}

# Remove a client
type DelClientV0 struct  {
  content: DelClientContentV0

  # Signature by user key
  sig: Sig
}
type DelClient union { DelClientV0 }

# Content of BrokerRequest
type BrokerRequestContentV0 union {
  | AddUser | DelUser
  | AddClient | DelClient
}

# Broker request
type BrokerRequestV0 struct {
  # Request ID
  id: u64

  # Request content
  content: BrokerRequestContentV0
}
type BrokerRequest union { BrokerRequestV0 }


# Response to an BrokerRequest
type BrokerResponseV0 struct {
  # Request ID
  id: u64

  # Result (including but not limited to Result)
  result: u16
}
type BrokerResponse union { BrokerResponseV0 }

# Request to join an overlay
type OverlayJoinV0 struct {
  # Overlay secret
  secret: SymKey

  # Public key for the repository the overlay belongs to.
  # Mandatory for local brokers.
  repoPubKey: optional<PubKey>

  # Peers to connect to
  peers: list<PeerAdvert>
}
type OverlayJoin union { OverlayJoinV0 }

# Request to leave an overlay
type OverlayLeave union {
  void
}

# Overlay status request
type OverlayStatusReq union {
  void
}

# Overlay status response
type OverlayStatusRespV0 struct {
  # Whether or not the broker has joined the overlay
  joined: bool

  # List of peers currently connected in the overlay
  peers: list<PeerAdvert>
}
type OverlayStatusResp union { OverlayStatusRespV0 }

# Request a block by ID
type BlockGetV0 struct {
  # Block ID to request
  id: BlockId

  # Whether or not to include all children recursively
  includeChildren: bool

  # Topic the block is referenced from
  topic: optional<PubKey>
}
type BlockGet union { BlockGetV0 }

# Request to store a block
type BlockPut union { Block }

# Request to pin an object
#
# Brokers maintain an LRU cache of objects,
# where old, unused objects might get deleted to free up space for new ones.
# Pinned objects are retained, regardless of last access.
# Note that expiry is still observed in case of pinned objects.
# To make an object survive its expiry,
# it needs to be copied with a different expiry time.
type ObjectPinV0 struct {
  id: ObjectId
}
type ObjectPin union { ObjectPinV0 }

# Request to unpin an object
type ObjectUnpinV0 struct {
  id: ObjectId
}
type ObjectUnpin union { ObjectUnpinV0 }

# Request to copy an object with a different expiry time
type ObjectCopyV0 struct {
  # Object ID to copy
  id: ObjectId

  # New expiry time
  expiry: optional<Timestamp>
}
type ObjectCopy union { ObjectCopyV0 }

# Request to delete an object
type ObjectDelV0 struct {
  id: ObjectId
}
type ObjectDel union { ObjectDelV0 }

# Request subscription to a topic
type TopicSubV0 struct {
  # Topic to subscribe
  topic: PubKey

  # Publishers need to include a signed TopicAdvert for the PeerId of the broker
  advert: optional<TopicAdvertV0>
}
type TopicSub union { TopicSubV0 }

# Request unsubscription from a topic
type TopicUnsubV0 struct {
  # Topic to unsubscribe
  topic: PubKey
}
type TopicUnsub union { TopicUnsubV0 }

# Connect to an already subscribed topic, and start receiving its Events
type TopicConnectV0 struct {
  # Topic to connect
  topic: PubKey
}
type TopicConnect union { TopicConnectV0 }

# Disconnect from a topic and stop receiving its Events
type TopicDisconnectV0 struct {
  # Topic to disconnect
  topic: PubKey
}
type TopicDisconnect union { TopicDisconnectV0 }

# Content of BrokerOverlayRequest
type BrokerOverlayRequestContentV0 union {
  | OverlayStatusReq | OverlayJoin | OverlayLeave
  | TopicSub | TopicUnsub
  | TopicConnect | TopicDisconnect
  | Event
  | BlockGet | BlockPut
  | ObjectPin | ObjectUnpin
  | ObjectCopy | ObjectDel
  | BranchHeadsReq | BranchSyncReq
}

# Broker overlay request
type BrokerOverlayRequestV0 struct {
  # Request ID
  id: u64

  # Request content
  content: BrokerOverlayRequestContentV0
}
type BrokerOverlayRequest union { BrokerOverlayRequestV0 }

# Content of BrokerOverlayResponseV0
type BrokerOverlayResponseContentV0 union {
  | Block
  | ObjectId
  | OverlayStatusResp
}

# Response to an BrokerOverlayRequest
type BrokerOverlayResponseV0 struct {
  # Request ID
  id: u64

  # Result (including but not limited to Result)
  result: u16
  content: optional<BrokerOverlayResponseContentV0>
}
type BrokerOverlayResponse union { BrokerOverlayResponseV0 }

# Content of BrokerOverlayMessageV0
type BrokerOverlayMessageContentV0 union {
  | BrokerOverlayRequest | BrokerOverlayResponse
  | Event
}

# Message for an overlay
type BrokerOverlayMessageV0 struct {
  overlay: OverlayId
  content: BrokerOverlayMessageContentV0
}
type BrokerOverlayMessage union { BrokerOverlayMessageV0 }

# Content of BrokerMessage
type BrokerMessageContentV0 union {
  | BrokerRequest | BrokerResponse
  | BrokerOverlayMessage
}

# Broker message
type BrokerMessageV0 struct {
  content: BrokerMessageContentV0

  # Optional padding
  padding: data
}
type BrokerMessage union { BrokerMessageV0 }

##
## EXTERNAL REQUESTS
##

# Request object(s) by ID from a repository by non-members
#
# The request is sent by a non-member to an overlay member node,
# which has a replica of the repository.
#
# The response includes all blocks of the requested objects,
# and optionally all object dependencies recursively.
type ExtObjectGetV0 struct {
  # Repository to request the objects from
  repo: PubKey

  # List of Object IDs to request, including their children
  ids: list<ObjectId>

  # Whether or not to include object dependencies
  includeDeps: bool

  # Expiry time after which the link becomes invalid
  expiry: optional<Timestamp>
}
type ExtObjectGet union { ExtObjectGetV0 }

# Branch heads request
type ExtBranchHeadsReq BranchHeadsReq

# Branch synchronization request
type ExtBranchSyncReq BranchSyncReq

# Content of ExtRequestV0
type ExtRequestContentV0 union {
  | ExtObjectGet
  | ExtBranchHeadsReq
  | ExtBranchSyncReq
}

# External request authenticated by a MAC
type ExtRequestV0 struct {
  # Request ID
  id: u64

  # Request content
  content: ExtRequestContentV0

  # BLAKE3 MAC over content
  # BLAKE3 keyed hash:
  # - key: BLAKE3 derive_key ("LoFiRe ExtRequest BLAKE3 key",
  #                           repo_pubkey + repo_secret)      # FIXME
  mac: Digest
}
type ExtRequest union { ExtRequestV0 }

# Content of ExtResponseV0
type ExtResponseContentV0 union {
  | Block
  | EventResp
  | Event
}

# Response to an ExtRequest
type ExtResponseV0 struct {
  # Request ID
  id: u64

  # Result code
  result: u16

  # Response content
  content: optional<ExtResponseContentV0>
}
type ExtResponse union { ExtResponseV0 }

##
## AUTHENTICATION MESSAGES
##

type ClientHelloV0 void
type ClientHello union { ClientHelloV0 }

# Initiate connection - choose broker or ext protocol
# First message sent by the client
type StartProtocol union { ClientHello | ExtRequest }

# Server hello sent upon a client connection
type ServerHelloV0 struct {
  # Nonce for ClientAuth
  nonce: data
}
type ServerHello union { ServerHelloV0 }

# Client authentication
type ClientAuthV0 struct {
  # Authentication data
  content: struct {
    # User pub key
    user: PubKey

    # Client pub key
    client: PubKey

    # Nonce from ServerHello
    nonce: data
  }

  # Signature by client key
  sig: Sig
}
type ClientAuth union { ClientAuthV0 }

# Authentication result
type AuthResultV0 struct {
  # Authentication result (Ok/Error)
  result: u16

  # Authentication token for HTTP
  token: optional<data>
}
type AuthResult union { AuthResultV0 }

##
## DIRECT MESSAGES
##

# Link/invitation to the repository
type RepoLinkV0 struct {
  # Repository public key ID
  id: PubKey

  # Repository secret
  secret: SymKey

  # Peers to connect to
  peers: list<PeerAdvert>
}
type RepoLink union { RepoLinkV0 }

# Owned repository with private key
type RepoKeysV0 struct {
  # Repository private key
  key: PrivKey

  # Repository secret
  secret: SymKey

  # Peers to connect to
  peers: list<PeerAdvert>
}
type RepoKeys union { RepoKeysV0 }

# Link to object(s) or to a branch from a repository
# that can be shared to non-members
type ObjectLinkV0 struct {
  # Request to send to an overlay peer
  req: ExtRequest

  # Keys for the root blocks of the requested objects
  keys: list<ObjectRef>
}
type ObjectLink union { ObjectLinkV0 }

##
## BROKER STORAGE
##

# A topic this node subscribed to in an overlay
type TopicV0 struct {
  # Topic public key ID
  id: PubKey

  # Signed TopicAdvert for publishers
  advert: optional<TopicAdvertV0>

  # Set of branch heads
  heads: list<ObjectId>

  # Number of local users that subscribed to the topic
  users: u32
}
type Topic union { TopicV0 }

# An overlay this node joined
type OverlayV0 struct {
  # Overlay ID
  id: OverlayId

  # Overlay secret
  secret: SymKey

  # Known peers with connected flag
  peers: list<PeerAdvert>

  # Topics this node subscribed to in the overlay
  topics: list<TopicId>

  # Number of local users that joined the overlay
  users: u32

  # Last access by any user
  lastAccess: Timestamp
}
type Overlay union { OverlayV0 }

# User accounts
#
# Stored as user_pubkey -> Account
type AccountV0 struct {
  # Authorized client pub keys
  clients: list<PubKey>

  # Admins can add/remove user accounts
  admin: bool

  # Overlays joined
  overlays: list<OverlayId>
}
type Account union { AccountV0 }