This is the traceability matrix that maps every section of the design documents to its implementation status. It is a living document generated from the repository and updated on every push. Use it to see at a glance what is shipped, what is in progress, and what is still on paper.
Traceability matrix mapping each DESIGN.md section to current implementation status.
Legend:
✅ Done: Implemented (at least POC-level working code)
🔶 Partial: Some aspects implemented, gaps remain
⬜ Not started: No implementation yet
🔮 Future: Awan Saya scope or Phase 3+
📄 Doc-only: Informational section, no implementation required
Landing page with OS-detected download links; no login, session tokens, or machine list
§4.2
Data Flow: Client Connection
✅
tela: WS connect, WireGuard tunnel, auto-bind local listeners, reconnect
§4.2
Data Flow: Multiplexed Channels
🔮
One WS per session by design. DESIGN §6.2 fixes single-channel as the v1 shape; multiplexing is reserved for a hypothetical v2 (the relay frame reserves a session_id field for it)
§4.3
Component Interaction Model
🔶
Client→Hub and Agent→Hub paths work; Browser→Hub auth/session path not implemented
WSS via Cloudflare tunnel; internal plain WS; binary frames for WG datagrams, JSON for control
§6.2
Multiplexing (v1: single-channel)
🔮
Single-channel shipped as the v1 design (one WS = one session); DESIGN §6.2 reserves multiplexing for a hypothetical v2. A mux experiment landed and was reverted; the session_id field is held open for it
§6.3
Frame Format (7-byte relay header)
✅
7-byte big-endian header (magic + hop + flags + session_id) on every relayed binary message, internal/relay/frame.go; produced and consumed by all binaries. The earlier 12-byte draft was never built and is retired (DESIGN §6.3)
§6.4
Control Messages (v1)
✅
Frozen v1 set implemented: register/registered, connect, session-request/session-join/session-start/wg-pubkey/ready, udp-offer/peer-endpoint, session-end, error, mgmt-request/mgmt-response, keepalive. Envelope is controlMessage (agent) and signalingMsg (hub); receivers ignore unknown fields
§6.5
Tokens (v1)
✅
Static hex shared secrets, ACL-keyed, crypto/subtle compare, revoke-by-config-removal per DESIGN §6.5. The 0.16 cycle added lifecycle metadata (issuedAt/expiresAt/revokedAt in internal/hub/auth.go) plus admin revoke/expiry/rotate (internal/hub/admin_api.go, issue #24). Structured/signed tokens remain a deferred 1.x item, not a v1 requirement
§6.6
Backward Compatibility (1.x policy)
✅
protocolVersion negotiation shipped on register/connect (absent treated as 1), internal/hub/protocol_version_test.go. The 1.x compatibility contract (covered surfaces, additive-only rules, cross-version matrix) is specified in DESIGN §6.6
§6.7
Error Handling
🔶
Basic error logging; no structured error types or per-channel error handling
§6.8
WireGuard L3 Transport
✅
wireguard-go + gVisor netstack on both sides, ephemeral keypairs, zero-admin, hub is zero-knowledge relay
§6.8
UDP Relay Mode
✅
Hub UDP relay (port 41820), probe/ready handshake, asymmetric fallback (UDP↔WS bridging), auto-fallback on timeout, udpHost advertisement for proxy/tunnel setups
Agent is Go (telad), not C/C++. Static binary ✅, cross-compiled ✅
§7.3
Concurrency Model (libuv)
⬜
N/A. Go runtime, not libuv
§7.4
Configuration (telad.yaml)
✅
YAML config file with -config flag. Multi-machine, per-machine token override, rich metadata fields. System path: %ProgramData%\Tela\telad.yaml / /etc/tela/telad.yaml
§7.5
Logging
🔶
Console logging with [telad] prefix; no structured/rotated logs
§7.6
Updates
✅
Channel-based self-update via internal/channel. CLI: telad channel (show/set/show-manifest) and telad update (self-update). Mgmt actions: update, update-status, update-channel. Verifies SHA-256 against the channel manifest before swapping. See RELEASE-PROCESS.md.
Accepts agents/clients ✅, brokers sessions ✅, routes data ✅, token validation ✅ (with issue/expiry/revocation metadata), UDP relay ✅, /status API ✅, admin REST API ✅, metadata ✅ (stored and served via register message). No browser user auth
§8.2
Implementation (Go)
✅
telahubd: Go, gorilla/websocket, no Node.js, no MeshCentral
§8.3
Storage (SQLite / Postgres)
🔶
Auth config persisted to YAML (hot-reload); session/machine state is in-memory only
Note: DESIGN.md describes a "Helper" (Go binary, TCP bridge). The current implementation evolved beyond this: tela is the client binary that establishes a full WireGuard L3 tunnel and auto-binds local listeners. It subsumes the Helper role while adding encrypted tunneling.
Section
Title
Status
Notes
§10.1
Responsibilities
✅
WS connect ✅, WG tunnel ✅, TCP bind ✅, bidirectional pipe ✅, TCP_NODELAY ✅, reconnect ✅, token auth ✅, cert pinning ✅ (SHA-256 SPKI on the hub-bound WS and HTTPS dials, internal/certpin, TOFU, tela pin). Single session per connection (see §6.2)
§10.2
Non-Responsibilities
✅
Client stores nothing, needs no admin, doesn't install
§10.3
Distribution & Signing
🔶
Three release channels (dev/beta/stable) ✅ with channel manifests, SHA-256 verification, and tela channel + tela update CLI (plus matching subcommands on telad and telahubd). Custom channel names are also supported for self-hosted channel daemons. GitHub Releases for Windows/Linux/macOS amd64+arm64 ✅. NSIS Windows installer ✅. .deb/.rpm packages ✅. macOS .tar.gz ✅. No code signing yet (Authenticode for Windows, Developer ID for macOS) -- still on the 1.0 blocker list.
§10.4
Data Path
✅
client → tela → WireGuard → Hub → WireGuard → telad → service working, with optional UDP relay
Stable agentId and machineRegistrationId UUIDs shipped (persisted in telad.state, carried on register; see DESIGN-identity.md and §6.4.2). No Ed25519 keypair yet: agents are not cryptographically authenticated, only ACL-token authenticated
§12.2
Certificate Pinning
🔶
SHA-256 SPKI pinning shipped for the tela client (hub-bound WS + HTTPS) and the hub-to-hub bridge dial via internal/certpin, with TOFU on first connect and tela pin; pins stored per hub in credentials.yaml / hubs.yaml / telahubd.yaml. Agent-side (telad) and TelaVisor-portal pinning are deferred post-1.0 (ROADMAP-1.0, issue #23)
§12.3
Session Tokens
🔶
Named token identities with role-based ACL (owner/admin/user/viewer) ✅; auto-generated console-viewer token ✅; per-machine register/connect ACLs ✅; env-var bootstrap ✅; admin REST API ✅; hot-reload ✅. The 0.16 cycle added issuedAt/expiresAt/revokedAt metadata and admin revoke/expiry/rotate (issue #24). Still hex shared secrets, not signed or single-use JWTs
§12.4
Transport Security (TLS 1.3)
🔶
TLS via Cloudflare + Caddy (direct); internal hub↔agent is plain WS
§12.5
E2E Encryption
✅
WireGuard provides full E2E encryption (Curve25519 + ChaCha20-Poly1305). Hub is zero-knowledge relay
Named token identities with RBAC ✅; YAML-persisted auth config ✅; admin REST API ✅; tela admin CLI ✅; env-var bootstrap ✅. No bcrypt/cookies/TOTP (spec vision), but functional token-based auth is complete
Model A (direct) demonstrated via Cloudflare Tunnel + Caddy direct; Models B & C are Awan Saya scope
§18.2
Hub Registry
🔶
Tela now ships an in-tree portal implementing the hub registry/discovery contract (DESIGN-portal.md): internal/portal + file-backed internal/portal/store/file, the standalone cmd/telaportal daemon, and TelaVisor Portal mode. Awan Saya remains the multi-tenant Postgres reference. Persistent relay-connection registration (Model B) stays Awan Saya scope
Unit tests across certpin, channel, client, credstore, hub, portal. Protocol-level coverage in internal/hub: protocol_version_test.go, session_tokens_test.go, auth_test.go, admin_api_test.go, access_version_test.go, services_test.go. Not yet an exhaustive conformance corpus
§20.2
Integration Tests
🔶
internal/teststack runs a hub and agent in-process on localhost and drives registration/status assertions; bridged-session end-to-end tests live in stack_test.go. Pushing real bytes through a full client tunnel in-harness is not yet automated
§20.3
Regression Suite
🔶
The unit and integration tests run in CI (go test -race -count=1 ./...) on every push and PR, so they guard against regressions. No separately curated regression corpus beyond that
WireGuard L3 tunnel: E2E encrypted, zero-admin, zero-install on both sides (gVisor netstack)
UDP relay: Eliminates TCP-over-TCP; auto-fallback to WebSocket; asymmetric bridging; udpHost advertisement for proxy/tunnel deployments
Multi-port forwarding: telad advertises ports, tela auto-binds local listeners
Token auth with RBAC: Named identities (owner/admin/user), per-machine ACLs, env-var bootstrap for Docker, remote management via tela admin CLI and admin REST API, hot-reload (no restart needed)
Auto-reconnect: Both tela and telad reconnect on disconnect
Cross-platform client: Windows, Linux, macOS (Intel + ARM) binaries served from hub
Dual ingress: Cloudflare Tunnel + Caddy direct
Hub /status API: JSON endpoint for monitoring
Direct tunnel (P2P): STUN hole punching with automatic fallback cascade (direct → UDP relay → WebSocket)
CLI remote management: tela remote add configures a hub directory, tela remote remove removes it (tela login/tela logout kept as deprecated aliases)
Remote-based hub name resolution: Short hub names resolved via configured remotes' /api/hubs with local hubs.yaml fallback
File sharing: Native file transfer protocol (list, read, write, delete, mkdir, rename, move) with live change notifications, sandboxed per machine, accessible via tela files CLI and TelaVisor Files tab
Frozen v1 wire protocol: 7-byte relay frame header (internal/relay/frame.go), a fixed v1 control-message set, and protocolVersion negotiation (absent treated as 1), all specified authoritatively in DESIGN §6
Certificate pinning: SHA-256 SPKI pinning on the client's hub-bound WS and HTTPS dials and on the hub-to-hub bridge, via internal/certpin, with TOFU on first connect and tela pin
Session-token lifecycle: issuedAt/expiresAt/revokedAt metadata plus admin revoke, expiry, and rotation on top of the RBAC token model (issue #24)
Automated test suite: unit tests across certpin, channel, client, credstore, hub, and portal, plus the in-process internal/teststack hub+agent integration harness, all run under go test -race in CI
In-tree portal: internal/portal with a file-backed store, the standalone cmd/telaportal daemon, and TelaVisor Portal mode implement the hub registry/discovery contract without Awan Saya
Code signing (§10.3): no Authenticode (Windows) or Developer ID (macOS) signing yet; still on the 1.0 blocker list
Browser-based user auth (§13.1): token-based CLI/API auth is complete; the spec's bcrypt + cookies + TOTP browser flow is not built
Ed25519 agent identity (§12.1): stable agentId/machineRegistrationId UUIDs shipped, but agents still have no cryptographic keypair and are authenticated only by ACL token
Agent-side and TelaVisor cert pinning (§12.2): the client and hub-bridge dials pin; the telad agent dial and TelaVisor portal pinning are deferred post-1.0
Internal-hop transport security (§12.4, §6.1): TLS is terminated at the edge; the internal hub-to-agent hop is plain WS
End-to-end tunnel tests (§20.2): teststack covers registration and bridged sessions, but pushing real bytes through a client tunnel in-harness is not yet automated
Deliberately out of v1 scope (not gaps): channel multiplexing (§6.2), which is reserved for a hypothetical v2, and structured/signed session tokens (§6.5, issue #24), which are a planned 1.x enhancement rather than a v1 requirement.