Skip to main content

Diagrams

Security in diagrams

Who can see what, where the trust boundaries are, and what each kind of attacker can and cannot do, drawn one picture at a time.

These drawings follow the threat model in the whitepaper and in docs/security/THREAT_MODEL.md. Green is what holds, red is what an attacker gets.

Boundaries

Where plaintext lives

Your devicekeys and plaintextYour networkTLSOur serversaccounts, fallback messagesXMTP nodesciphertext, size, timingAztecproofs
Trust boundaries. Plaintext and keys exist only on your device; everything past your network sees ciphertext, proofs, or the account data named here.
Mermaid source
Mermaid
flowchart LR
  Dev[Your device<br/>keys and plaintext]:::ok
  Net[Your network<br/>TLS]:::muted
  Srv[Our servers<br/>accounts, fallback messages]:::dashed
  X[XMTP nodes<br/>ciphertext, size, timing]:::muted
  Az[Aztec<br/>proofs]:::muted
  Dev --> Net
  Net --> Srv
  Net --> X
  Net --> Az

What each party sees

YouWho you talk toXMTP nodesSize, timing,conversation of a messageOur serversAccounts, contacts,who is onlineAztec networkThe fee payerof a transactionContentAmount and recipientof a private paymentknowsseeseeseesnotnotnot
Metadata. Content stays private everywhere; each party still sees something, and this is what.
Mermaid source
Mermaid
flowchart LR
  You[You] -->|knows| Who[Who you talk to]
  X[XMTP nodes] -->|see| Meta[Size, timing,<br/>conversation of a message]
  Srv[Our servers] -->|see| Acc[Accounts, contacts,<br/>who is online]
  Az[Aztec network] -->|sees| Fee[The fee payer<br/>of a transaction]
  Meta -.->|not| Content[Content]:::ok
  Acc -.->|not| Content
  Fee -.->|not| Amt[Amount and recipient<br/>of a private payment]:::ok

Attackers

Our servers, compromised

Full control ofour serversRead fallback messages,community posts, contactsSee who is online,deny serviceRead direct messagessent over XMTPSign as you ormove your fundscancancannotcannot
Someone who takes over our servers.
Mermaid source
Mermaid
flowchart LR
  Adv[Full control of<br/>our servers]:::danger
  Adv -->|can| C1[Read fallback messages,<br/>community posts, contacts]
  Adv -->|can| C2[See who is online,<br/>deny service]
  Adv -.->|cannot| N1[Read direct messages<br/>sent over XMTP]:::ok
  Adv -.->|cannot| N2[Sign as you or<br/>move your funds]:::ok

Nodes and networks

An XMTP node operatorSee ciphertext, its size andtiming,and its conversationRead itAn observer on your networkSee which services you use,and whenRead anything sentover TLScancannotcancannot
Someone who runs a node, or watches your network.
Mermaid source
Mermaid
flowchart LR
  Op[An XMTP node operator]:::danger -->|can| S1[See ciphertext, its size and timing,<br/>and its conversation]
  Op -.->|cannot| R1[Read it]:::ok
  Obs[An observer on your network]:::danger -->|can| S2[See which services you use,<br/>and when]
  Obs -.->|cannot| R2[Read anything sent<br/>over TLS]:::ok

Devices and QR codes

Someone with yourunlocked deviceOpen Ledger Chat,read browser storageSign in elsewherewithout the walletSomeone who tricks youinto scanning their codeAsk to be linked: the phonenames the computer and asks youGet the wallet or anysignature you do not approvecancannotcancannot
Someone with your device in hand, or a phishing QR code.
Mermaid source
Mermaid
flowchart LR
  Dev[Someone with your<br/>unlocked device]:::danger -->|can| O[Open Ledger Chat,<br/>read browser storage]
  Dev -.->|cannot| S[Sign in elsewhere<br/>without the wallet]:::ok
  QR[Someone who tricks you<br/>into scanning their code]:::danger -->|can| Ask[Ask to be linked: the phone<br/>names the computer and asks you]
  QR -.->|cannot| W[Get the wallet or any<br/>signature you do not approve]:::ok

Malware

Malware on your deviceEverything you can seeNo design that is only softwarecan prevent thissees
Malware is outside what any messenger can stop. Keeping the system updated, locking the device and running few browser extensions reduce the risk.
Mermaid source
Mermaid
flowchart LR
  Mal[Malware on your device]:::danger -->|sees| All[Everything you can see]
  All -.-> Note[No design that is only software<br/>can prevent this]:::muted

Keys and secrets

What your wallet signs

WalletXMTP installation keysPrivate account secretSession cookieHttpOnly, seven daysStay in this browserOur server verifies it,scripts cannot read itsignatureEIP-712 signatureEIP-4361 signature
One wallet, three different signatures, three different things. None of the keys leaves the browser.
Mermaid source
Mermaid
flowchart LR
  W[Wallet] -->|signature| Inst[XMTP installation keys]
  W -->|EIP-712 signature| Az[Private account secret]
  W -->|EIP-4361 signature| Sess[Session cookie<br/>HttpOnly, seven days]
  Inst --> Dev[(Stay in this browser)]:::ok
  Az --> Dev
  Sess --> Srv[Our server verifies it,<br/>scripts cannot read it]:::ok

Ciphers by purpose

Channel key, 256 bitsSealed requests betweencomputer and phoneECDH P-256 andHKDF-SHA256File key per fileHKDF-SHA256Encrypted piecesMLS epoch keysMessagesDTLS-SRTP keysCall mediaAES-256-GCMAES-256-GCM
The encryption in use, by what it protects.
Mermaid source
Mermaid
flowchart LR
  Ch[Channel key, 256 bits] -->|AES-256-GCM| Req[Sealed requests between<br/>computer and phone]
  ECDH[ECDH P-256 and HKDF-SHA256] --> Ch
  File[File key per file<br/>HKDF-SHA256] -->|AES-256-GCM| Pieces[Encrypted pieces]
  MLS[MLS epoch keys] --> Msgs[Messages]
  DTLS[DTLS-SRTP keys] --> Media[Call media]

Process

Guards on every change

CommitSecret scan ofstaged files, pre-commitForbidden securitypatternsSecurity testsHuman reviewMain branch
Checks every change passes on its way in.
Mermaid source
Mermaid
flowchart TB
  Commit[Commit] --> Sec[Secret scan of<br/>staged files, pre-commit]
  Sec --> Pat[Forbidden security<br/>patterns]
  Pat --> Tests[Security tests]
  Tests --> Rev[Human review]
  Rev --> Main[Main branch]

Reporting a vulnerability

Someone finds a problemWe acknowledge itWe assess and fixWe publish the fixPublish before a fixGitHub security advisoryplease do not
Reporting a vulnerability. The commitments and timings are on the trust page.
Mermaid source
Mermaid
flowchart LR
  R[Someone finds a problem] -->|GitHub security advisory| Ack[We acknowledge it]
  Ack --> Ass[We assess and fix]
  Ass --> Pub[We publish the fix]
  R -.->|please do not| Pubf[Publish before a fix]:::muted

What is still open

TodaySeal fallback messageson the clientCommunities as MLS groupsExternal audit andpenetration testSelf-hosted signallingLedger RelayPrivate fee payer on AztecPost-quantum key exchangewhen MLS supports it
Open problems, as listed in the whitepaper. None of these is done yet.
Mermaid source
Mermaid
flowchart LR
  Now[Today] --> P1[Seal fallback messages<br/>on the client]
  Now --> P2[Communities as MLS groups]
  Now --> P3[External audit and<br/>penetration test]
  Now --> P4[Self-hosted signalling<br/>Ledger Relay]:::dashed
  Now --> P5[Private fee payer on Aztec]
  Now --> P6[Post-quantum key exchange<br/>when MLS supports it]