first commit
This commit is contained in:
commit
6d3ea3e2a6
43 files changed
+8204
No files matched your search
@@ -0,0 +1,224 @@
|
||||
// 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; }
|
||||
Reference in new issue
Block a user