How Kleo's network works

flowchart TB
    subgraph yours["Your machine"]
        kleo["Kleo<br/>desktop app"]
        node["plain-bitnames node<br/>wallet, keys, crypto<br/>JSON-RPC :6002"]
    end

    chain[("BitNames sidechain<br/>names, keys, commitments,<br/>payments")]
    peer["Someone else's Kleo<br/>+ their node"]

    subgraph infra["Infrastructure — replaceable, never trusted"]
        hub["kleo-hub<br/>profiles · mail · addresses · channels<br/>HTTP :7777"]
        relay["iroh relay<br/>hole punching, fallback path"]
    end

    kleo -->|"every key, every check"| node
    node <-->|"P2P, port 4002"| chain
    kleo -->|"signed uploads, signed requests"| hub
    kleo <-->|"QUIC, ALPN kleo/dm/1"| peer
    kleo -.->|"when no direct path exists"| relay
    relay -.-> peer
    hub -->|"checks signatures against its own node"| chain
    peer --> chain

sequenceDiagram
    autonumber
    participant K as Kleo
    participant N as Your node
    participant H as Hub / resolver
    participant S as The name's own server

    K->>N: bitname_data of blake3 of bob
    N-->>K: signing key, encryption key, commitment, address
    Note over K: With no commitment there is no profile to fetch — keys alone still verify signatures.

    K->>H: bitname_commit with bytes = commitment
    H-->>K: a JSON document
    K->>K: BLAKE3 of canonical JSON == commitment?
    alt matches
        K-->>K: Verified, source = resolver
    else no answer, or a different document
        K->>S: bitname_commit at the address published on-chain
        S-->>K: a JSON document
        K->>K: hash and compare again
        alt matches
            K-->>K: Verified, source = the name's own server
        else
            K-->>K: Unverified — shows nothing, and says every attempt it made
        end
    end

sequenceDiagram
    autonumber
    participant K as Kleo
    participant N as Your node
    participant C as Chain

    K->>N: is blake3 of alice already registered?
    N-->>K: no
    K->>N: reserve_bitname alice
    N->>C: reservation — commitment only, no plaintext
    Note over C: Block n
    K->>N: get_transaction_info
    N-->>K: confirmed
    K->>N: register_bitname alice with new signing and encryption keys
    N->>C: registration — reveals the name, publishes the keys
    Note over C: Block n+1
    K-->>K: alice is yours — and the plaintext name was never on-chain before it was

sequenceDiagram
    autonumber
    participant K as Kleo
    participant N as Your node
    participant H as Hub
    participant C as Chain

    K->>K: canonical JSON (RFC 8785), commitment = BLAKE3 of it
    K->>N: sign_arbitrary_msg over<br/>"kleo-resolver publish v1 / name / commitment"
    N-->>K: signature
    K->>H: kleo_publish [name, document, signature]
    H->>H: hash the document, check it against the signed statement
    H->>N: bitname_data — what key does this name publish?
    Note right of H: A hub checks with its own node, not the uploader's.
    H-->>K: stored, keyed by commitment
    K->>N: update_bitname — set commitment
    N->>C: BitNameUpdate
    Note over C: One block later the chain commits to it,<br/>and every reader can verify the document.

sequenceDiagram
    autonumber
    participant A as Alice's Kleo
    participant H as Hub (directory)
    participant B as Bob's Kleo

    B->>B: sign with the endpoint key:<br/>"kleo endpoint record v1 / endpoint / at / addresses / relay"
    B->>H: kleo_endpoint_put [record]
    H->>H: verify the signature against the endpoint id itself
    H->>H: refuse a record older than the one held (no replay)
    Note over H: Records expire after 24 h — a stale address is worse than none.

    A->>H: kleo_endpoint_get [bob's endpoint id]
    H-->>A: the signed record
    A->>A: check the signature again before using it
    Note over A: A hub that invents an address is simply ignored:<br/>the record wouldn't verify.
    A-->>B: dial those addresses directly

sequenceDiagram
    autonumber
    participant A as Alice's Kleo
    participant AN as Alice's node
    participant B as Bob's Kleo
    participant BN as Bob's node

    A->>AN: resolve bob — endpoints and hubs from his profile
    AN-->>A: chat.endpoints, chat.hubs
    A->>AN: encrypt to bob's key, signed as alice
    AN-->>A: armored message
    A->>B: QUIC (ALPN kleo/dm/1)<br/>4-byte length + JSON envelope
    B-->>A: "ok"
    Note over A,B: The envelope says from: alice.<br/>That is a claim, and nothing rests on it.
    B->>BN: decrypt, then verify the inner signature
    BN-->>B: signer = alice, key matches the chain
    B->>B: file it as alice — flagged if anything didn't line up

sequenceDiagram
    autonumber
    participant A as Alice's Kleo
    participant AN as Alice's node
    participant C as Chain
    participant B as Bob's Kleo

    B->>AN: publish chat.prekey in bob's profile
    Note over C: The prekey is inside the profile the chain commits to,<br/>so it is as authentic as the name itself.

    A->>AN: resolve bob — endpoints, hubs, prekey
    AN-->>A: prekey found
    A->>A: throwaway key, DH against the prekey, start the ratchet
    A->>AN: sign the message as alice (unchanged)
    A->>A: seal the signed armor under a one-message key
    A->>B: BITNAMES SEALED MESSAGE — ratchet key, counters, ciphertext
    Note over A,B: The BitName encryption key is not involved.<br/>Nothing here opens with it, now or later.

    B->>B: find which prekey it was sealed to, accept the session
    B->>B: open it — that message key is then discarded
    B->>AN: verify the signature inside, against the chain
    AN-->>B: signed by alice
    B->>A: reply — a new ratchet key, and a new chain in both directions

sequenceDiagram
    autonumber
    participant A as Alice's Kleo
    participant AN as Alice's node
    participant H as Hub (mailbox)
    participant HN as Hub's node
    participant B as Bob's Kleo
    participant BN as Bob's node

    A->>B: direct attempt
    B--xA: no answer — his machine is off
    A->>AN: sign "kleo mailbox deposit v1 / to / from / at / digest"
    A->>H: kleo_mailbox_deposit [to, from, armored, sent_at, at, signature, attachment]
    H->>HN: is alice's signature good, and is bob a registered name?
    HN-->>H: yes
    H-->>A: stored, id = BLAKE3 of the envelope
    Note over H: The hub holds ciphertext. It knows bob has mail,<br/>from alice, how big, and when. Not a word of it.

    B->>BN: sign "kleo mailbox fetch v1 / name / at"
    B->>H: kleo_mailbox_fetch [bob, at, signature]
    H->>HN: verify against bob's on-chain key, and refuse a stale timestamp
    HN-->>H: good
    H-->>B: everything waiting, oldest first
    B->>BN: decrypt and verify each one
    B->>H: kleo_mailbox_ack [bob, ids, at, signature]
    H-->>B: forgotten

sequenceDiagram
    autonumber
    participant A as Alice's Kleo
    participant AN as Alice's node
    participant C as Chain
    participant B as Bob's Kleo
    participant BN as Bob's node

    A->>AN: bitname_data of bob — paymail_fee_sats
    AN-->>A: 5000 sats
    A->>AN: list_utxos — which address holds bob's name?
    AN-->>A: the holder's address
    A->>AN: encrypt to bob, signed as alice
    AN-->>A: armored message
    A->>AN: create_transfer to that address,<br/>value at least the price, memo = hex of the armor
    AN->>C: transaction
    Note over C: Public forever: that a payment was made, and how much.<br/>Encrypted: every word of what it said.

    B->>BN: get_wallet_utxos
    BN-->>B: outputs, including one with a memo
    B->>BN: hex-decode the memo, decrypt, verify
    BN-->>B: from alice, verified, 5000 sats
    B->>B: file it, noted with what was paid

sequenceDiagram
    autonumber
    participant A as Author's Kleo
    participant AN as Author's node
    participant H as Hub (channels)
    participant HN as Hub's node
    participant R as Reader's Kleo
    participant RN as Reader's node

    A->>AN: resolve the channel — kind, authors, moderators, bans
    A->>AN: sign "kleo channel post v1 / channel / author / at" + text
    A->>H: kleo_channel_post [post]
    H->>HN: resolve the channel profile — does it allow this author?
    H->>HN: verify the signature against the author's on-chain key
    HN-->>H: both good
    H-->>A: stored

    R->>RN: resolve the channel (same profile, same rules)
    R->>H: kleo_channel_posts [channel, limit]
    H-->>R: posts, newest first
    loop every post
        R->>R: id matches its contents?
        R->>R: channel allows this author?
        R->>RN: signature good against the chain?
    end
    R-->>R: verified posts shown, anything else shown as unverified with the reason

sequenceDiagram
    autonumber
    participant O as Owner's Kleo
    participant ON as Owner's node
    participant C as Chain
    participant M as Member's Kleo
    participant H as Hub

    O->>O: generate a 32-byte group key
    loop each member
        O->>ON: encrypt_msg the key to that member's on-chain encryption key
        ON-->>O: sealed copy
    end
    O->>ON: publish the profile: members, sealed keys, epoch + 1
    ON->>C: commitment
    Note over C: The sealed copies are public. Only the member they were<br/>sealed to can open theirs.

    M->>M: read the channel profile, take its own sealed copy
    M->>ON: decrypt_msg with its own encryption key
    M->>M: group key
    M->>H: post — text encrypted under the group key, then signed
    Note over H: The hub stores ciphertext and cannot read a line.

    Note over O,M: Removing someone means a new key, sealed only to who is left,<br/>and epoch + 1 — they read nothing written afterwards.