first commit

This commit is contained in:
yves committed 2026-11-20 21:47:33 +01:00
commit 6d3ea3e2a6
43 files changed
+8204

No files matched your search

+224
View File
@@ -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; }