Federation
Overview
Federation connects independently operated UnoLock nodes so that people can keep their own home service while exchanging private messages and working in Shared Spaces with Safes on other nodes. There is no central directory and no single operator that every node depends on.
Each node is a home service for the Safes created on it. Your browser talks only to your home node. The node finds other nodes, carries encrypted content between them, and enforces its own policy. Encryption and authority stay with the client: the node and the federation peers carry ciphertext and opaque routes, and never receive your plaintext or your private keys.
How nodes find each other
Nodes learn about one another through a distributed lookup network. It works without a central directory.
- Seeds introduce peers. A node starts from one or more bootstrap peers (seeds). Seeds are interchangeable introductions, not a central directory and not an allowlist of every destination.
- Discovery continues without the seed. While a node is operational and unlocked, it announces its onion service to peers, asks them for introductions, and probes introduced services before remembering them. After it has learned other reachable peers, lookup no longer needs the original seed to stay online.
- Peers are verified before they are kept. A node that pings yours is only a temporary candidate until your node successfully contacts it back over Tor. Unverified candidates expire after ten minutes and are not handed out to other peers or saved.
- Routing state is encrypted at rest. Learned peers are stored in the node's encrypted SQLite database.
Operators choose their own bootstrap peers. Saved bootstrap choices stay authoritative across restarts and upgrades; configuration updates do not add peers to an operator's list. See Configuration for where bootstrap peers are set.
A node needs at least one reachable introduction
A completely isolated node cannot discover anyone. It needs a reachable seed in the connected federation, or another service joining it. Learned peer hints expire after 30 minutes, so after a longer shutdown a node whose saved hints have expired needs at least one reachable configured seed again.
Tor between nodes, HTTPS for you
Federation uses two different connections:
| Connection | Transport |
|---|---|
| Your browser to your home node | HTTPS to the node's permanent hostname, for example https://node.example.com/ |
| Node to node | Tor v3 onion services |
Your browser connects to your home node over HTTPS. The node handles peer discovery and transport. A browser calls only its home service and the opaque transfer URLs that its home service returns.
Each node exposes a bounded onion API to other nodes, not its general Safe API. Every federation endpoint has explicit limits on request size, response size, timeouts and rate.
Tor is transport only. Application encryption, signatures, authentication and policy do not depend on Tor for their security, and Tor is never an authority for who may do what. See Tor and the Relay for how the node runs Tor and what Tor does and does not hide.
What federation carries
Federation transports two kinds of content between home services:
- Sealed one-to-one messages. The browser encrypts and signs a message before it leaves your device. See Receive Addresses and Messaging Across Nodes.
- Client-encrypted archives. Notes and files in Shared Spaces travel as encrypted bytes. See Shared Spaces Across Nodes.
Between nodes, only these may cross:
- sealed message envelopes;
- encrypted archive bytes;
- client-signed proofs;
- opaque routes and bounded control data.
These never cross to a federation peer:
- user-authored plaintext;
- contact names;
- private keys.
What federation never decrypts
The federation library and the nodes that run it do not decrypt your content.
- The browser signs a message header, then encrypts it. The node and the federation library cannot decrypt the message or verify that application signature.
- After decryption, the receiving client checks the signature before it trusts the sender's identity or acts on anything the message carries.
- Shared archive bytes stay encrypted in transit, in storage and in caches. A complete encrypted cache does not grant access.
Client-held authority and signing
The client, not the node, is the authority for confidentiality and sharing intent. The browser:
- encrypts content before it leaves your device;
- signs application messages and verifies message signatures after decryption;
- signs a fresh, short-lived proof for every remote archive operation;
- signs the exact node route authorized for each Receive Address.
A node cannot manufacture this authority. For remote archive operations, the receiving node verifies the client proof and then still applies its own Safe, archive, quota and resource policy. A proof authorizes only the single signed operation on one archive and lasts no more than five minutes. It is not an encryption key, a storage location, or a provider credential.
Storage and caches are never authorization authorities. When a remote node times out, has stale state, or cannot be reached over Tor, the operation fails closed. A Space whose authoritative refresh fails becomes stale and read-only rather than accepting changes.
What peers can observe
Participating services can observe timing, ciphertext size, pseudonymous address-hash activity, and the onion peer they contact. They must not log or return Receive Address strings, Safe IDs, Space names, contact names, plaintext metadata, signed transfer URLs, private keys, access proofs, or raw onion identities outside explicit operator configuration.
Discovery traffic carries service routes, not Receive Addresses or address hashes, and it creates no lookup-history records. Peers still see advertised service identities and can correlate address hashes in actual lookups. Tor transport and these metadata limits do not protect against every form of traffic analysis, malicious peers, Sybil attacks or network partitioning.
The public lookup network accepts bounded anonymous traffic. A remote party can temporarily use up its finite capacity and delay lookups or publication. That kind of interference ends at a failed or delayed lookup: it cannot disclose plaintext, substitute an accepted key, or redirect an accepted message.
Built to outlast any one company
Operators can build and run the AGPL node independently and configure their own bootstrap peers. Continued operation of the federation depends on participating operators and reachable peers, not on TechSologic remaining in business. This does not automatically recover data from a service that has shut down. See Operator Responsibilities and Support.
Full reference
FAQs
Is there a central server that all nodes depend on?
No. Nodes find each other through a distributed lookup network. Seeds only introduce a new node; once it has learned other reachable peers, lookup continues without the original seed.
Can other nodes read my messages or files?
No. Federation peers carry sealed envelopes, encrypted archive bytes, proofs and opaque routes. They do not receive user-authored plaintext, contact names or private keys, and the federation library does not decrypt or verify application-message signatures.
Do I need Tor in my browser?
No. Your browser connects to your home node over HTTPS. The node uses Tor onion services to talk to other nodes.
Can I choose which peers my node starts from?
Yes. Operators can configure their own bootstrap peers. Saved choices remain authoritative across restarts and upgrades. See Configuration.
What can a federation peer learn about me?
Peers can observe timing, ciphertext size, pseudonymous address-hash activity and which onion service they are talking to. They do not receive Receive Address strings, Safe IDs, Space names, contact names or plaintext metadata.