atproto-tailnet

Architecture

System overview

                     Internet
                        │
                ┌───────┴───────┐
                │     Caddy     │  TLS termination
                │  (ports 80,   │  Wildcard subdomains
                │   443)        │  Dynamic routing via admin API
                └───┬───────┬───┘
                    │       │
          ┌─────────┘       └──────────┐
          ▼                            ▼
  ┌───────────────┐          ┌─────────────────┐
  │  TypeScript   │          │  Rust           │
  │  Service      │          │  Coordinator    │
  │  (port 3000)  │◄────────►│  (port 9443)    │
  │               │  REST    │                 │
  │  Web UI, MCP  │  admin   │  Noise IK       │
  │  OAuth        │  API     │  Multi-tenant   │
  │  Orchestrator │          │  Per-tenant DERP│
  └───────┬───────┘          └────────┬────────┘
          │                           │
          └──────────┬────────────────┘
                     ▼
              ┌──────────────┐
              │  PostgreSQL  │  (service layer + coordinator)
              │  (port 5432) │  or SQLite (coordinator standalone)
              └──────────────┘

Components

TypeScript service

The application server uses Express 5 with Drizzle ORM. It does these tasks:

The service communicates with the coordinator through the admin REST API. The getControlClient(tenant) factory returns a CoordinatorApiClient or a HeadscaleApiClient. The choice depends on whether COORDINATOR_URL is set.

Rust coordinator

The coordinator is a purpose-built, multi-tenant WireGuard control plane. The workspace has 9 crates:

Crate Purpose
coord-core Shared types: TenantId, NodeId, ControlKey, MachineKey, error types, federation types
coord-noise Noise IK handshake (snow library) + encrypted transport with Tailscale-compatible big-endian nonces
coord-proto Tailscale control protocol messages: RegisterRequest/Response, MapRequest/Response
coord-acl ACL policy engine: per-tenant rules compiled to Tailscale FilterRule format
coord-store Storage backends: MemoryStore (dev), PgStore (PostgreSQL), SqliteStore (SQLite) with broadcast::Sender<PeerEvent>
coord-netmap Network map computation from store state, and the per-tenant DERP registry
coord-federation Federation protocol: session lifecycle, route engine, abuse controls, scoping, handshake state machine, auth, transport, discovery, inbound handlers. Storage: PgFederationStore, SqliteFederationStore, FederationMemoryStore
coord-api axum HTTP server: admin REST API, Noise handshake endpoint, health, federation message endpoints (only with COORD_FEDERATION_ENABLED=true)
coord-server Binary entrypoint: TOML and env configuration, persistent control key, admin key check

Protocol flow

Tailscale client                    Coordinator
      │                                  │
      ├── POST /ts2021 ────────────────►│  Noise IK handshake
      │◄─────── Noise session ──────────┤  (25519/ChaChaPoly/BLAKE2s)
      │                                  │
      │   ══ HTTP/2 over Noise ══        │
      │                                  │
      ├── POST /machine/register ──────►│  Pre-auth key validation
      │◄─────── RegisterResponse ───────┤  IP allocation (CGNAT)
      │                                  │
      ├── POST /machine/map ───────────►│  Subscribe to peer updates
      │◄─────── MapResponse (stream) ───┤  zstd-framed deltas
      │◄─────── PeersChanged ──────────┤  Every 60s keepalive
      │◄─────── PeersRemoved ──────────┤  On disconnect
      │                                  │

The streaming map connection uses HTTP/2 with PING-based keepalive (30s interval, 90s timeout). The coordinator uses this keepalive to detect disconnects.

Clients pin the Noise public key of the coordinator. The coordinator loads its control key from COORD_CONTROL_KEY_PATH. The Docker stack keeps the file on the coord_data volume.

Database

The TypeScript service needs PostgreSQL (Drizzle ORM, 30 tables). The coordinator supports three storage backends. You select the backend with store_backend in the TOML config or with the COORD_STORE_BACKEND env var:

The PostgreSQL and SQLite backends both run their own migrations at startup.

Caddy

Caddy is a reverse proxy with dynamic subdomain routing. The TypeScript service manages one Caddy route (@id: tailnet_tenants) through the admin API. The service rewrites the route each time it adds or removes a tenant. Caddy does these tasks:

The app sets TRUST_PROXY=1 behind Caddy. The service then reads the client IP address and the scheme from X-Forwarded-*. The secure session cookie needs this.

Multi-tenancy

The mesh network of each user is an isolated tenant. In coordinator mode:

Sub-collective hierarchy

Tenants can form a two-level parent/child hierarchy:

Organization (parent)
  ├── Team Alpha (child, posture: selective)
  ├── Team Beta (child, posture: closed)
  └── Team Gamma (child, posture: open)

Security model

Authentication layers

  1. AT Protocol OAuth: Users authenticate through their PDS. The system stores no passwords. Session cookies with sameSite: lax protect against CSRF.

  2. Instance operators: The DIDs in OPERATOR_DIDS. Only operators and designated tailnet creators can create tailnets. Only operators can use /api/operator/*. See ADR-0025.

  3. Role-based access: 17 granular permissions. You can combine them into custom roles. The originator identity is a hard flag. Nobody can downgrade it.

  4. Agent tokens: Bearer tokens with the prefix at_ for API access. The system stores them as SHA-256 hashes. Each token applies to one tenant and a subset of permissions. Expiry is mandatory. Agent tokens never get operator powers.

  5. MCP OAuth tokens: Bearer tokens with the prefix mcp_. They act as the user, and they work only through the /mcp tools. Operator tools need an opt-in scope at consent. The system stores only hashes.

  6. Coordinator admin auth: A constant-time bearer token comparison on all /api/* endpoints. The key must have at least 32 characters.

Network security

Data protection

Database schema

TypeScript service tables (30)

users, tenants, roles, memberships, oauth_states, oauth_sessions, invitations, device_approvals, device_locks, join_requests, auth_keys, notifications, service_devices, services, board_posts, agent_tokens, audit_logs, usage_snapshots, federation_links, collective_dids, broker_sessions, relay_nodes, credential_revocations, holder_binding_challenges, service_auth_jti_cache, instance_settings, tailnet_creators, mcp_oauth_clients, mcp_oauth_grants, mcp_oauth_tokens

Coordinator tables

coord_tenants, coord_nodes, coord_preauth_keys, coord_ipv4_counter (SQLite only), coord_federation_links, coord_broker_sessions, coord_collective_dids

When you use PostgreSQL, the TS service schema and the coordinator schema exist in the same database. A prefix prevents name collisions. When you use SQLite, the coordinator manages its own .db file independently.