Security Model

Tubo's security model is built on transport isolation, secret-backed namespace discovery, stable service identity, and capability-based access. Understanding what each layer provides — and does not provide — is essential for safe deployment.

Layer 1 — Transport isolation (PSK)

When a swarm key is configured, libp2p rejects any peer that cannot prove knowledge of the PSK during the pnet handshake. This happens before any libp2p protocol negotiation.

Provides:

• Network-level isolation — an outsider can't even see which peers are in the swarm.
• Defence against relay-assisted attacks from outside the swarm.

Does not provide:

• Per-service access control. Any peer in the swarm can dial any other peer.
• Anonymity or traffic analysis resistance.

Layer 2 — Namespace discovery and publish authorisation

In discovery-enabled collaborative namespaces, overlay reachability alone is not enough to see services. Peers also need the correct namespace discovery entry. Every service has a stable service ID derived from an Ed25519 owner key, and before a service can publish into a namespace it must hold a PublishLease signed by the cluster authority.

Discovery subscribers validate:

1. The GossipSub topic matches the expected Discovery V3 topic derived from the namespace discovery entry.
2. The announcement signature is valid against the service owner key.
3. The ServiceClaim is signed by a trusted cluster authority.
4. The nonce has not been seen before (bounded replay window).
5. The TTL is within the claim's expiry.

A compromised or rogue peer that has swarm transport access but lacks valid namespace discovery state or a valid authority-signed publication chain will have its announcements silently dropped.

Layer 3 — Connect authorisation (leases + PoP)

Connecting to a service requires a ConnectAccessLease bound to the client's local keypair. On every stream open, the client presents a signed proof-of-possession (PoP) that binds: scope, service ID, access lease hash, nonce, and timestamp.

The service validates:

• PoP signature matches the client keypair in the lease.
• Scope and service ID match the connected service.
• Nonce has not been replayed (rolling window).
• Timestamp is within the allowed skew.
• Access lease is not expired or revoked.

Trust roots

There are two trust roots:

• Public trust root — the public Tubo bundle is verified on install. The public authority key is pinned locally; tokens cannot redefine it, and the public bundle does not carry namespace discovery entries.
• Private trust root — for private clusters, the authority keypair is created by tubo create cluster/<name> and stored locally. Cluster invites use TOFU (trust on first use) for introducing a private authority.

What Tubo does NOT guarantee

• Anonymity: relay nodes see IP addresses and connection timing.
• Content confidentiality from relay: while relay does not decrypt stream content, it can correlate connections by timing.
• Protection against a compromised relay: a relay under attacker control can drop traffic or perform denial-of-service. It cannot decrypt traffic, forge valid signed leases, or act as a namespace discovery authority by default.
• Perfect immediate revocation of old discovery state: namespace discovery rotation uses a current/previous grace model. Peers that still hold a non-expired previous entry may continue to discover publications during the grace window.
• Forward secrecy of old tokens: revocation is not retroactive for already-established sessions. New streams after revocation are blocked.
• OS-level isolation: Tubo does not sandbox origin services. If the origin process is compromised, the attacker can serve arbitrary responses.

Cryptographic primitives

Reporting vulnerabilities

Please report security issues via GitHub private vulnerability reporting or directly to the maintainers. Do not open public issues for security bugs.