End-to-end lifecycle

From strangers to delivered messages: invite, pairing, profile exchange, send, and fetch — the complete Yakr session story.

Master flow

flowchart TB
  Start([Two users want to chat]) --> Invite[1. Alice creates invite URL]
  Invite --> Accept[2. Bob accepts invite]
  Accept --> Safety[3. Verify safety code OOB]
  Safety --> Pair[4. X25519 pairing handshake]
  Pair --> Master[5. Derive master secret + ratchet]
  Master --> Profile[6. Exchange delivery profiles]
  Profile --> Send[7. Alice sends encrypted message]
  Send --> Store[8. Relay stores opaque blob]
  Store --> Fetch[9. Bob fetches and decrypts]
  Fetch --> Done([Conversation established])

Steps 1–3: invite & verification

Alice generates a signed CBOR invite bundle and shares it as a URL or QR code. Bob decodes it, verifies the Ed25519 signature, and compares the safety code with Alice over a trusted channel.

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>Alice: create_invite() + sign CBOR
  Alice->>Bob: yakr://invite/... (QR, link)
  Bob->>Bob: verify Ed25519 signature
  Bob->>Bob: compute safety code
  Note over Alice,Bob: Both display safety digits
  Alice->>Bob: confirm codes match (voice/SMS)

CLI — AlicePhase 4

yakr invite create --port 8090
# → yakr://invite/qWhwcm90b2NvbG... (truncated)
# → Safety code: 4510 2126 16

Steps 4–6: pairing & profiles

An X25519 (or hybrid PQ) handshake establishes a master secret and double ratchet. Both sides exchange signed delivery profiles listing relay descriptors, TLS pins, and mailbox routes.

Steps 7–9: send & fetch

Alice encrypts an inner JSON message, wraps it in an outer blob with a mailbox tag, and POSTs to a paired relay. Bob polls outbound, fetches by tag, decrypts locally, and may send a delivery receipt.