Component Communication

Which component communicates with what?

flowchart TD
    subgraph A[Attestant]
        B[/<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/attestant">Reach Attestant</a>/]
    end

    subgraph C[Local Peer]
        E{{<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/node#peer-node">Reachable Peer Node</a>}}
        D[<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/reachable-app">Reachable Application</a>]
        F([<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/secrets">Reachable Secrets</a>])
        F -.->|encrypts/decrypts & signs/verifies messages for| D
        E -.->|provides long-term storage for| D
    end

    subgraph G[Remote Peer]
        H{{<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/node#peer-node">Reachable Peer Node</a>}}
    end

    subgraph Reaching Party
        I[<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/reaching-app">Reaching Application</a>]
        J([<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/reaching-app/src-wasm">Reaching Link</a>])
        J -.->|encrypts/decrypts & signs/verifies messages for| I
    end

    K{{<a href="https://codeberg.org/reachable-systems/reach/src/branch/main/node#server-node">Reachable Server Node</a>}}

    K -->|hosts| I

    A -->|signs verifying keys of| C
    A -->|signs verifying keys of| G
    A -->|provides prerequisites to| K

    I ==>|collects messages from| K
    E ==>|collects messages from| K
    H ==>|collects messages from| K
    B ==>|uploads signed verifying keys to| K
    E <==>|opportunistically syncs with| H

All local connections use WebSocket based binary protocols via Unix domain sockets.

How does the Reachable Application communicate with its Secrets and Node services?

sequenceDiagram
    participant rs as Reachable Secrets
    participant rc as Reachable Application
    participant rn as Reachable Node
    participant rrn as Remote Reachable Node

    rc->>rn: Init
    note over rn,rrn: only valid for Server Nodes
    rn->>rrn: Init
    rrn->>rn: Reach
    note over rrn,rn: from Server Node
    rn->>rc: Reach
    note over rc: caches ReachablePublicKeys for eventual replies
    rc->>rs: (asks to decrypt) EnvelopeIdHints, (passes our own) ReachablePublicKeys
    rs-->>rs: attempts to decrypt EnvelopeIdHints
    note over rs: ReachablePublicKeys are ordered, so this is sped up<br>by only attempting with the delta of unused keys since<br>the most recent successful decryption and the<br>ReachablePublicKeys we received
    rs->>rc: (successfully decrypted) HintedEnvelopeIds
    note over rs: for every HintedEnvelopeId, saves a the relationship<br>between the asymmetric secret key that and the EnvelopeId
    rc->>rn: EnvelopeId
    note over rn,rrn: Peers are queried before Server
    rn->>rrn: EnvelopeId
    rrn->>rn: Envelope
    note over rn: stores Envelope along with EnvelopeId
    rn->>rc: Envelope
    rc->>rs: Envelope
    note over rs: queries saved asymmetric secret key that was able to<br>recover the HintedEnvelopeId for this Envelope<br>as it is the same key that decrypts it
    rs-->>rs: decrypts MessageVaultLink::MessageVaultId
    alt Reaching user Envelope contains MessageVaultLink::SealedLink
        rs-->>rs: decrypts SealedMessageVaultId (with SharedSecretKeys)
    end
    note over rs: saves the relationship between MessageVaultId and the<br>recovered symmetric secret key
    rs->>rc: MessageVaultId
    rc->>rn: MessageVaultId
    note over rn,rrn: Peers are queried before Server
    rn->>rrn: MessageVaultId
    rrn->>rn: MessageVault
    note over rn: stores MessageVault along with MessageVaultId
    rn->>rc: MessageVault
    rc->>rs: MessageVault
    note over rs: queries saved symmetric secret key that was able to<br>recover the MessageVaultLink linking to this MessageVault<br>as it is the same key that decrypts it
    rs->>rc: Message
    note over rc: displays contents

How does the Reachable Application reply to messages?

Additional context:

1. Reachable Secrets generates, signs, and saves all secret keys as well as their relationship to EnvelopeIds and MessageVaultIds, also encrypts
2. Reachable Application does not save messages by itself. It displays decrypted contents but does not save it at any point. It is merely the UI for interaction with other components.
3. Reachable Node locally saves encrypted Envelopes (queryable by EnvelopeIds) and MessageVaults (queryable by MessageVaultId) to decrypt on demand and sharing with other remote peers.

sequenceDiagram
    participant rs as Reachable Secrets
    participant rc as Reachable Application
    participant rn as Reachable Node
    participant rrn as Remote Reachable Node

    rc-->>rc: starts Message reply in existing thread
    rc->>rn: StartReply with MessageVaultId (of initial contact)
    rn->>rrn: Init
    rrn->>rn: Reach
    rn->>rc: ReplyInfo with MessageVault (of initial contact) + ReachablePublicKeys
    rc->>rs: Message Content + MessageVault + ReachablePublicKeys
    rs->>rc: MessageVaultSeed
    rc->>rn: MessageVaultSeed
    rn->>rrn: MessageVaultSeed
    rrn->>rn: SealedMessageVaultId
    rn->>rc: SealedMessageVaultId
    rc->>rs: SealedMessageVaultId
    rs->>rc: MessageVaultId + EnvelopeSeed
    rc->>rn: MessageVaultId + EnvelopeSeed
    note over rn: Uses MessageVaultSeed and MessageVaultId to save<br>MessageVault (to share with peers)
    rn->>rrn: EnvelopeSeed
    rrn->>rn: SealedEnvelopeId
    rn->>rc: SealedEnvelopeId
    rc->>rs: SealedEnvelopeId
    rs->>rc: EnvelopeId
    rc->>rn: EnvelopeId
    note over rn: uses EnvelopeSeed and EnvelopeId to save<br>Envelope (to share with peers)