Security → Architecture

Security architecture

TunnelCrib has four components. Only two of them ever see Service traffic; the Central Server only ever sees control-plane and signaling messages.

ComponentRoleSees Service traffic?
TunnelCrib ClientRequests a Tunnel, opens a local listener, forwards Service traffic to the Agent.Yes (it is one endpoint of the Tunnel)
Central ServerAuthenticates Devices, enforces organization isolation, allocates sessions, relays signaling messages.No — signaling only
TunnelCrib AgentAdvertises approved Services, serves the requested Service over the established transport.Yes (it is the other endpoint)
TunnelCrib Relay (tunnelcrib-bridge)Optional data-plane hop, used only when a Direct Tunnel cannot be established.See What the Relay can see

Direct Tunnel first, Relay only on failure

Every Tunnel attempt tries a direct Client–Agent path before ever involving a Relay, using three fallback tiers:

TierMechanismFalls back when
0UDP + KCP, STUN-assisted NAT traversalSTUN unreachable, no peer candidate, or punch timeout
1TCP simultaneous-open punch (SO_REUSEPORT)Tier 0 fails within the shared punch budget
2TunnelCrib Relay (tunnelcrib-bridge), hosted or a Private RelayTier 1 also fails within the total punch budget (10s)

Whichever tier wins, SSH is the only authentication and encryption layer. UDP and TCP punching only establish the underlying byte stream; the SSH handshake, host-key pinning, and public-key authentication are identical in every tier.

Registration and authorization sequence

  1. TunnelCrib Client and TunnelCrib Agent each register with the Central Server (hostname, uuid, and, for Agents, advertised protocols).
  2. The Central Server validates each Device against the organization's registry by organization, UUID, and Device type.
  3. The Central Server issues a nonce challenge to both peers.
  4. Client and Agent sign the nonce with their per-Device identity key (see Device identity).
  5. The Central Server verifies the signature against the registered public key. Connections failing this check are rejected.
  6. When a Client requests a Tunnel, the Central Server checks the requested protocol against the Agent's advertised list and organization boundary before signaling either peer.

Independently of the registration handshake, every Direct Tunnel's SSH layer separately pins a per-session Client public key and, after first use, the Agent's host key — so a Direct Tunnel cannot be impersonated even if the transport-level address exchange were spoofed.

Trust boundary summary: the Central Server brokers who may request what; it never terminates or forwards Service traffic. The Client and Agent are the only parties that see Service bytes on a Direct Tunnel. On a Relay-mediated Tunnel, see what the Relay can see.