theta-agent/DESIGN.md

theta-agent v2 — Simplified Architecture (LDAP-over-HTTPS)

Status: Draft for review · Supersedes: the WebRTC/SCTP spec (WebRTC dropped)

This document defines the v2 architecture for theta-agent. It replaces the earlier WebRTC/SCTP design with a strictly simpler model: one agent per node, one outbound WSS channel, and the agent provides local LDAP + secrets + IAM. The core problem it solves is the original ask — LDAP binds are painful across hostnames, networks, and TLS cert chains — by making the client stop speaking LDAP and instead do an HTTPS call to the SSO, where the directory is reachable.

---

1. Overview

APP (no agent)                          SSO
  HTTPS POST /ldap/bind ──────────────► [LDAP-over-HTTPS API] ──► OpenLDAP
  HTTPS POST /ldap/search ───────────►        ▲
                                              │ raw bytes
NODE (with theta-agent)                       │
  SSSD ──► /run/theta/ldap.sock ──► agent ──► WSS (ldap_tunnel) ─┘
  secrets: /etc/theta/templates/*.tpl ──► agent ──► HTTPS ──► OpenBao
  IAM: sudoers.d / authorized_keys ──► agent ◄── WSS ◄── IAM engine

Two ways to reach the directory, both simple:

• Apps (no agent): call the HTTPS LDAP API directly — one bind/search contract, no LDAP protocol.
• Nodes (with agent): the agent is a pure byte pump — it forwards raw LDAP bytes from a local socket to the SSO, which relays them into OpenLDAP. The agent never parses LDAP.

---

2. Transport

• Single transport: persistent outbound WebSocket (WSS) over TCP 443. No WebRTC, no SCTP, no UDP, no ICE, no fallback logic. The agent dials out; the SSO never needs an inbound port.
• Authentication: the existing token / join-key enrollment model carries over unchanged (see PROTOCOL.md §1.1). The agent presents its per-agent token; the SSO rejects anything it did not issue.
• Message framing: the existing WSMessage JSON envelope (type + payload) carries all traffic. Message types are extended for LDAP, secrets, and IAM (below). No binary framing, no stream multiplexing. The LDAP tunnel carries raw bytes as base64 in ldap_tunnel messages (see §4).

---

3. LDAP-over-HTTPS API (SSO side)

A small service (or routes in the existing proxy/sso) that performs the real LDAP operation against OpenLDAP, which is reachable from the SSO network. This is the pinepain/ldap-auth-proxy model: the client never speaks LDAP.

Endpoint	Request	Response
POST /api/v1/ldap/bind	{username, password}	200 {dn, attributes} or 401
POST /api/v1/ldap/search	{base_dn, scope, filter, attributes}	200 {entries: [...]}

• bind performs a real LDAP bind server-side and returns the bound DN and identity attributes.
• search runs a real LDAP search server-side and returns entries.
• Authorization: the API authorizes the caller (an app, or an agent acting for a node). OpenLDAP enforces the actual directory ACLs. This resolves the original spec's contradiction — we do not parse BER to enforce per-operation policy; the directory does.

3.1 Consumers

• Apps/services: call the API directly over HTTPS. No LDAP hostname, no LDAPS cert chain, no cross-network LDAP firewall rule.
• theta-agent: does not use this API. It tunnels raw LDAP bytes to the SSO's OpenLDAP over the WSS channel instead (see §4) — a byte pump, not a translation. The HTTPS API is for apps that have no agent on their network.

---

4. Agent local LDAP socket — a pure byte pump (for SSSD/PAM)

The agent provides a local LDAP endpoint so SSSD/PAM on the node can authenticate without direct LDAP connectivity. The agent does not speak LDAP at all. It is a dumb byte pump: whatever bytes land on the local socket are forwarded to the SSO, which relays them into its real OpenLDAP and pipes the response back.

SSSD ──► /run/theta/ldap.sock ──► agent ──► WSS (ldap_tunnel) ──► SSO ──► OpenLDAP
  ◄───────────────────────────────────────────────────────────────────────◄

• Socket: a Unix domain socket at /run/theta/ldap.sock, owned by root, mode 0660 (root + theta group). A unix socket is preferred over 127.0.0.1:389 because filesystem permissions restrict which local processes can connect — any process can reach a TCP port, only root/theta can reach the socket.
• Tunnel framing: each local connection gets a conn_id. Bytes are carried over the existing WSS channel as ldap_tunnel messages: {type:"ldap_tunnel", payload:{conn_id, data:<base64>, close:bool}}. The agent reads the socket and sends chunks up; the SSO relays them into OpenLDAP and sends OpenLDAP's response chunks back down; the agent writes them to the socket. close:true ends a connection.
• SSSD config: ldap_uri = ldapi://%2frun%2ftheta%2fldap.sock, StartTLS off (the transport to the SSO is already TLS/WSS; the local hop is plaintext on a root-owned socket).

4.1 Offline boot handling (validated)

If the agent cannot reach the SSO (WSS down), it cannot forward bytes, so it closes local socket connections. SSSD sees a connection failure and falls back to its local cache. This has been validated against real SSSD behavior: any user/group seen in the last N days can log in offline — a laptop user can log in on the road, and an admin can still reach a broken service host to fix it.

4.2 Open question — ldapi:// support

SSSD's ldap_uri accepts ldapi:// unix-socket URIs on modern versions, but this must be confirmed on the target SSSD build. If unsupported, fall back to 127.0.0.1:389 with a local firewall rule restricting the port to loopback.

---

5. Secrets engine

The agent renders OpenBao secrets to local files, reusing the existing @simpleworkjs/bao-conf patterns rather than inventing a parallel mechanism.

• Templates: /etc/theta/templates/*.tpl declare the secrets a service needs, e.g. DB_PASS="{{ bao "secret/data/nodes/node-42/db#password" }}".
• Flow: the agent requests the secret paths over the WSS channel → the SSO fetches from OpenBao (node-scoped to /secret/data/nodes/${NODE_ID}/*) → the agent renders the file atomically (write temp + rename) with mode 0600 → runs the configured post-render action (systemctl reload <svc>).
• Rotation: on a rotation/invalidation event pushed down the channel, the agent re-fetches, re-renders, and reloads.
• Note: OpenBao KV v2 secrets have no leases; "renewal" is a re-read on invalidation, not a lease renewal. (Dynamic secrets, if used, are a separate path.)

---

6. IAM engine

The SSO pushes node-scoped identity config down the WSS channel; the agent applies it locally.

• Sudo rules: write /etc/sudoers.d/theta-iam-<node_id>, run visudo -c, and atomically swap on success.
• SSH keys: sync user public keys via AuthorizedKeysCommand (the agent implements the command the SSH daemon calls per login) — not a non-standard /etc/ssh/authorized_keys.d/ directory.
• Access control: configure SSSD / /etc/security/access.conf for allowed login groups.
• Revocation: on account disable / group drop, flush local SSSD caches and drop active sessions for the affected user (mechanism TBD — loginctl vs pkill -u; high-risk, needs a defined trigger/event model).

6.1 Security — signed IAM payloads

Sudo rules and SSH keys grant root-equivalent access, so every IAM push is Ed25519-signed using the existing signature model (PROTOCOL.md §5). The agent verifies the signature against its pinned public_key before applying anything. Unsigned or invalid IAM payloads are rejected fail-closed.

---

7. Security model

• Fail-closed, capability-matrix philosophy carries over from v1: the agent only applies what its local config permits; the SSO cannot override local settings.
• Local socket auth: only root/theta can reach /run/theta/ldap.sock.
• Signed high-risk operations: IAM pushes (and any new high-risk command) require the Ed25519 signature.
• Node-scoped secrets: OpenBao access is restricted to the node's own path prefix.
• Blast radius: the agent runs as root; the unix socket + signature model + node-scoped secrets contain the damage if the agent is compromised.

---

8. What this drops from the original spec

• WebRTC / SCTP / DTLS / UDP / ICE — gone, WSS only.
• Three SCTP streams — replaced by one WSS channel with message types.
• The "node-scoped authorization" contradiction — resolved: the API authorizes the caller, OpenLDAP enforces ACLs.
• LDAP parsing in the agent — gone. The agent is a byte pump; it never parses LDAP. The SSO relays raw bytes into its real OpenLDAP.

---

9. Open questions / verification items

1. SSSD ldapi:// unix-socket support on the target build (§4.2).
2. Revocation mechanism — implemented as sss_cache -E + pkill -u <user> (§6). The event model (what triggers a push) is still to be wired into the SSO UI/engine.
3. AuthorizedKeysCommand — implemented: the agent installs /usr/local/bin/theta-authorized-keys which cats the user's key file (/etc/theta/authorized_keys/<user>). sshd must be configured with AuthorizedKeysCommand /usr/local/bin/theta-authorized-keys %u (§6).
4. Versioning/migration — is v2 a replacement for v1, or a parallel mode? The existing /api/agent/ws vs the new /api/v1/ldap/* paths need a story.
5. SSO relay target — the SSO relays tunnel bytes into its local OpenLDAP (slapd). The target address comes from conf.ldap.url; confirm it is a plaintext LDAP port reachable from the SSO process (§4).
6. Secrets node scope — the agent's node scope is its agent id (secret/data/nodes/<agent-id>/*). Confirm this matches how node secrets are provisioned in OpenBao (§5).