224 lines
7.2 KiB
Protocol Buffer
224 lines
7.2 KiB
Protocol Buffer
// 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; }
|