// Meow protocol v2. // // Conventions: // * all keys are raw 32-byte values (Ed25519 / X25519), never base64 inside protobuf; // * timestamps are unix seconds (uint64) unless suffixed with _ms; // * every top-level wire object carries a `version` so it can evolve without ambiguity. // // See rust/ARCHITECTURE.md for the cryptographic constructions referenced here. syntax = "proto3"; package meow.v2; // ───────────────────────────── Cards ───────────────────────────── // Self-signed description of a server, served at GET /v2/card. message ServerCard { uint32 version = 1; string name = 2; string description = 3; string url = 4; // canonical base URL (http[s]://host[:port]) bytes sign_key = 5; // Ed25519 public key bytes dh_key = 6; // X25519 public key, recipient of sealed requests uint64 issued_at = 7; bytes signature = 8; // Ed25519 over the card encoded with signature = empty } // Per-contact public material exchanged during an invitation. message ContactCard { uint32 version = 1; string name = 2; // nickname I want this contact to see bytes identity_key = 3; // Ed25519 bytes dh_key = 4; // X25519 static key for this relationship bytes mailbox = 5; // Ed25519 public key = mailbox where I read messages from you bytes ratchet_key = 6; // X25519 initial ratchet public key repeated ServerCard pull_servers = 7; // where I poll my mailbox } // ─────────────────────────── Invitation ────────────────────────── // Step 1 (initiator → invitee). Transported by file, QR code, server shortcode, BLE... message InvitationOffer { uint32 version = 1; bytes invitation_id = 2; // 16 random bytes string initiator_name = 3; bytes offer_dh_key = 4; // X25519 temporary key: the Answer is sealed to it bytes answer_mailbox = 5; // Ed25519 temporary key: mailbox where the Answer may be posted repeated ServerCard answer_servers = 6; string message = 7; uint64 expires_at = 8; } // Step 2 content (sealed to offer_dh_key). message InvitationAnswerBody { bytes invitation_id = 1; ContactCard invitee = 2; bytes signature = 3; // invitee.identity_key over transcript(offer, invitee) } // Step 3 content (sealed to invitee.dh_key). message InvitationConfirmBody { bytes invitation_id = 1; ContactCard initiator = 2; bytes ephemeral_key = 3; // X25519 public key used in the X3DH-like agreement bytes signature = 4; // initiator.identity_key over transcript(offer, invitee, initiator, ephemeral) RatchetMessage first_message = 5; // first Double Ratchet message (HandshakeAck): bootstraps the invitee's sending chain } // A sealed-box blob: ECIES X25519 + HKDF-SHA256 + XChaCha20-Poly1305. message Sealed { uint32 version = 1; bytes ephemeral_key = 2; bytes ciphertext = 3; // nonce (24) || aead ciphertext } // Invitation steps 2 and 3 as transported (file or mailbox). message InvitationMessage { uint32 version = 1; uint32 step = 2; // 2 = answer, 3 = confirm bytes invitation_id = 3; // clear, so the receiver can find the pending invitation Sealed sealed = 4; } // ─────────────────────────── Peer layer ────────────────────────── message RatchetHeader { bytes dh_key = 1; // X25519 current ratchet public key uint32 previous_count = 2; // PN uint32 message_number = 3; // N } // What sits in a mailbox. message PeerEnvelope { uint32 version = 1; oneof body { RatchetMessage ratchet = 2; InvitationMessage invitation = 3; // step 2 posted to the offer's answer mailbox } } message RatchetMessage { RatchetHeader header = 1; bytes ciphertext = 2; // nonce || aead(padded UserMessage) } // Plaintext of a RatchetMessage (after unpadding). message UserMessage { bytes id = 1; // 16 random bytes uint64 sent_at_ms = 2; oneof body { TextBody text = 10; FileBody file = 11; Receipt receipt = 12; HandshakeAck handshake_ack = 13; // invitation step 4 bytes app_data = 14; } bytes reply_to = 3; } message TextBody { string text = 1; } message FileBody { string filename = 1; uint64 size = 2; uint32 chunk = 3; uint32 chunks = 4; bytes data = 5; string mime = 6; } message Receipt { enum Kind { KIND_UNSPECIFIED = 0; DELIVERED = 1; READ = 2; } Kind kind = 1; repeated bytes message_ids = 2; } message HandshakeAck { bytes invitation_id = 1; } // ─────────────────────────── Client ↔ server ───────────────────── // Body of POST /v2/rpc. message SealedRequest { uint32 version = 1; bytes ephemeral_key = 2; bytes ciphertext = 3; // nonce || aead(Request), key = k_req } // Response body of POST /v2/rpc. message SealedResponse { uint32 version = 1; bytes ciphertext = 2; // nonce || aead(Response), key = k_resp } message Request { bytes request_id = 1; // 16 random bytes, anti-replay uint64 timestamp = 2; oneof body { Ping ping = 10; Post post = 11; Pull pull = 12; InvitationPublish inv_publish = 13; InvitationFetch inv_fetch = 14; } } message Response { bytes request_id = 1; oneof body { Error error = 10; Pong pong = 11; PostAck post_ack = 12; PullResult pull_result = 13; InvitationPublished inv_published = 14; InvitationFetched inv_fetched = 15; } } message Error { enum Code { CODE_UNSPECIFIED = 0; BAD_REQUEST = 1; UNAUTHORIZED = 2; NOT_FOUND = 3; TOO_LARGE = 4; RATE_LIMITED = 5; INTERNAL = 6; EXPIRED = 7; } Code code = 1; string message = 2; } message Ping {} message Pong { uint64 server_time = 1; } message Deposit { bytes mailbox = 1; // Ed25519 public key bytes payload = 2; // encoded PeerEnvelope } message Post { repeated Deposit deposits = 1; } message PostAck { uint32 accepted = 1; } message MailboxAuth { bytes mailbox = 1; uint64 timestamp = 2; bytes signature = 3; // see ARCHITECTURE.md §3.5 } message Pull { repeated MailboxAuth auths = 1; uint32 wait_seconds = 2; } message StoredMessage { bytes mailbox = 1; bytes payload = 2; uint64 received_at = 3; } message PullResult { repeated StoredMessage messages = 1; } message InvitationPublish { bytes payload = 1; // encoded InvitationOffer uint32 ttl_seconds = 2; uint32 shortcode_len = 3; string password = 4; } message InvitationPublished { string shortcode = 1; uint64 expires_at = 2; } message InvitationFetch { string shortcode = 1; string password = 2; } message InvitationFetched { bytes payload = 1; }