repo/services/multistreaming/SECURITY.md

SECURITY.md — multistreaming

This document describes the security model of the self-hosted multistreaming service, its threat model, and — explicitly and honestly — the limits of what it can protect. Read it before exposing the service to anything but a trusted network.

---

1. What this service does

multistreaming ingests RTMP feeds (typically one per person from OBS) and restreams them to one or more streaming platforms (Twitch, YouTube, Kick, or a custom RTMP endpoint). Two programming modes exist:

• Passthrough — each live feed is remuxed (-c copy) to its destination accounts without re-encoding.
• Scenes & composition — multiple live feeds are composed (grid or picture-in-picture, plus text/image overlays) and re-encoded into a single program pushed to destination accounts, with per-output audio routing.

To push to a platform, the service must present that platform's stream key. Stream keys are the highest-value secret in the system.

---

2. Threat model

Assets

Asset	Sensitivity
Platform stream keys (Twitch/YouTube/Kick/custom)	Highest — compromise = account takeover of that channel
Vault master passphrase / vault key (VK)	Highest — decrypts all keys in a vault
Account metadata, room topology, scene definitions	Low–moderate
Composed/relayed video	As sensitive as the stream content itself

Actors

Actor	Assumption
Homelab operator / host root	Fully trusted. Can read any memory/disk on the machine.
Service account (the container)	Trusted with plaintext keys at push time only.
Vault owner	Holds the master passphrase; controls their own accounts.
Room owner	Full control of a room's production; sees own keys only.
Room editor	Edits feeds/outputs/scenes; never sees anyone's keys.
Room streamer	Manages their own accounts + grants their own keys; read-only on production.
Streaming platform	External; receives the pushed stream.
Network observer (LAN/internet)	Assumed able to observe traffic unless TLS/VPN is used.

Trust zones

1. Browser — holds the vault key (VK) only while a vault is unlocked, in memory; encrypts/decrypts keys client-side.
2. Panel server (the container, the "center machine") — persists only ciphertext; holds plaintext keys transiently in memory during a stream.
3. Ingest path — RTMP from OBS to the container on port 1935.

---

3. Zero-knowledge vault

The server never stores a plaintext stream key. Account secrets are stored as secretCiphertext ({iv, data}, AES-GCM) encrypted under a random 256-bit vault key (VK) that only the user's browser holds after unlock.

Key hierarchy (src/vault.js):

master passphrase ──PBKDF2-HMAC-SHA256 (600k)──▶ KEK ──wraps──▶ VK ──encrypts──▶ account secrets

• salt — random 16 bytes, stored server-side.
• serverWrapped — the VK wrapped by the KEK under AAD multistreaming:vault:v1. Stored server-side; useless without the master passphrase.
• deviceWrapped — the VK wrapped by a non-extractable browser device key under AAD fingerprint|sessionId. Enables silent unlock and is session-bound: a different session id or browser fingerprint fails AES-GCM authentication.
• Each account secret is encrypted under the VK with AAD acct:<accountId>, so a ciphertext cannot be replayed against a different account id.

Consequences:

• A database/disk leak of config.json yields only PBKDF2-wrapped blobs and per-account ciphertexts — nothing decryptable without the passphrase or the device key.
• There is no password recovery. Losing the passphrase and the device wrapping means the keys are unrecoverable (by design).

---

4. Capability grants (keys in memory)

The zero-knowledge property cannot extend all the way to the push: some machine must present the plaintext key to the platform at push time. That machine is the multistreaming container.

To minimize exposure, the service uses short-lived, in-memory capability grants (src/grants.js):

• A streamer clicks Start streaming; their browser decrypts the selected keys client-side and sends them to the server over the panel connection.
• The server stores them only in memory: accountId → { key, grantedBy, expiresAt }, never on disk.
• Lifetime is GRANT_TTL_MS (default 6 hours). Expired grants are dropped on access.
• Grants are revoked when the streamer clicks Stop streaming, when the account is deleted, or on expiry.
• FFmpeg resolves the destination URL from the live grant at spawn time; the URL (which contains the key) is redacted in all logs (redactUrl).

---

5. Authentication & authorization

• Sessions (src/auth.js): HMAC-SHA256-signed tokens (base64url({sid, uid, iat}).signature) in an HttpOnly; SameSite=Lax cookie, 12-hour lifetime. SESSION_SECRET should be set to a stable random value; if unset it is generated per boot (sessions do not survive restarts).
• Local auth (dev only): scrypt password hashing, constant-time comparison.
• OIDC (recommended, Authelia): authorization-code + PKCE (S256), with the verifier held server-side (10-minute state). Identity is mapped to a local user record by sub/username. OIDC is for authentication only — it never touches vault key material.

Per-room roles

Capability	owner	editor	streamer
Manage feeds, outputs, scenes, scene outputs, images	✅	✅	—
Activate/deactivate scenes	✅	✅	—
View room production	✅	✅	✅
Manage own accounts + grant own keys	✅	✅	✅
See another user's secretCiphertext	—	—	—

Non-members receive 404 (never 403) on room-scoped reads, and insufficient roles receive 403. maskAccount strips secretCiphertext from every account unless the viewer is its owner, so editors and streamers never see others' keys.

---

6. Single-use invites

POST /api/rooms/:roomId/invites (owner only) mints an invite with a 256-bit random token, a role of editor or streamer (never owner), and a 7-day expiry. Accepting an invite consumes it (deletes the record) and creates the membership. Invites are:

• single-use (consumed on accept),
• expiring (pruned at load and on lookup),
• role-limited (cannot mint an owner),
• unguessable (256-bit token).

---

7. The inherent trust boundary (be explicit)

If you compromise the host (or the multistreaming container while a stream is running), you can read every key that is currently granted. That is not a bug; it is the fundamental limit of any restreaming service — the machine that pushes must hold the key at push time.

The mitigations are scope and time, not prevention:

1. Keys are held only in memory, only for granted accounts, and only for GRANT_TTL_MS.
2. Revocation is one click ("Stop streaming") or automatic on expiry.
3. Keys are never written to disk, never logged, and never sent to editors, streamers, or other room members.

If the host is untrusted, do not run this service on it.

---

8. Scene & composition security

• FFmpeg argument injection is prevented by: spawning via an argument array (no shell) and escaping overlay text for FFmpeg's filtergraph parser (escapeDrawtext: control chars stripped, \ and ' escaped) plus drawtext=...:expansion=none, a 256-character cap, and NUL stripping.
• Image overlays accept only decoded payloads ≤ 1 MiB whose magic bytes are PNG/JPEG/WebP; files are stored under dataDir/uploads with server-generated UUID filenames (never client-supplied paths), and the path is single-quote escaped before reaching the movie filter.
• Log redaction applies to composed outputs exactly as to passthrough: destination URLs (which embed keys) are replaced before logging.

---

9. Residual risks & known limits

1. Center-machine memory — see §7. Root/host access during a stream reads live keys.
2. No CSP / XSS hardening — the panel does not currently ship a strict Content-Security-Policy. A browser XSS could read a decrypted key while the vault is unlocked. Run the panel behind a TLS reverse proxy and keep dependencies updated.
3. Plaintext RTMP ingest — the ingest path (port 1935) is unencrypted and bypasses the HTTP proxy by design. Keep it on a trusted LAN/VPN; do not expose 1935 to the internet.
4. Panel TLS — the container serves HTTP on 8080; TLS termination is expected at a reverse proxy (nginx-proxy-manager).
5. Local auth mode — AUTH_MODE=local is intended for development; OIDC is the recommended production mode.
6. No audit log — grant/activate/invite events are not persisted for audit.
7. Composition re-encode — scene mode decodes and re-encodes feeds on the server; this does not weaken key handling but is a CPU cost and a single point of processing.

---

10. Operational checklist

• Set a stable, high-entropy SESSION_SECRET.
• Use AUTH_MODE=oidc behind Authelia with PKCE and matching OIDC_REDIRECT_URI.
• Terminate TLS at the reverse proxy; expose only the panel there, not 1935.
• Keep RTMP ingest on a private network.
• Leave GRANT_TTL_MS as short as operationally comfortable.
• Back up dataDir (it holds the only copy of wrapped keys; there is no recovery without the passphrase).