stack/docs/tess/THREAT-MODEL.md

Tess Threat Model

Assets and Trust Boundaries

Assets: operator identity, tenant/project data, agent sessions, fleet control, approvals, credentials, memories, tool outputs, audit evidence, and provider transports.

Trust boundaries: Discord→plugin, CLI→gateway, plugin→gateway service identity, gateway→Pi/provider, Tess→Mos/fleet, Tess→Hermes, MCP→gateway, persistence, and tmux/Matrix transports.

Threat Matrix

ID	Severity	Threat	Required control	Required verification
TM-01	critical	Client invokes admin/system command without role	Server-side scope/role enforcement in executor; durable approval for privileged/destructive commands	Authenticated non-admin and forged-scope tests deny and audit
TM-02	critical	Cross-user/tenant list, attach, send, or terminate by guessed session ID	Owner/tenant binding on every session operation; admin override is explicit and audited	Cross-tenant matrix for REST, WS, CLI, Discord and provider methods
TM-03	high	MCP caller supplies another userId	Remove actor IDs from schemas; derive actor/tenant from authenticated context; per-tool scopes	Forged actor/tool calls deny; no victim data returned
TM-04	high	Discord ingress impersonates user/channel or bypasses gateway auth	Service-to-service identity, guild/channel/user allowlists, signed/correlated envelope, replay protection	Invalid service identity, unlisted IDs, replayed message IDs all deny
TM-05	high	Secrets/PII leak in chat, auth links, tool args, logs, memory, or DB	Redact before persistence/egress; DM/out-of-band auth flow; short-lived hashed token state; output classification	Seeded secret/PII canary absent from durable stores/logs/public channel
TM-06	high	Prompt/tool injection escalates from content to privileged action	Treat messages/files/tool output as untrusted data; structured proposals only; allowlisted tools; approval binds exact action digest	Injection corpus cannot invoke unapproved tools or alter authority
TM-07	high	Approval forged, replayed, or applied to modified action	One-time approval with actor, tenant, action digest, expiry, correlation and consumption record	Forged/replayed/expired/mutated approvals deny and audit
TM-08	medium	Restart causes message loss or duplicate side effects	Durable inbox/outbox/checkpoint; idempotency keys; transactional state transitions; bounded replay	Kill/restart at each state transition; exactly-once effect or safe dedupe
TM-09	medium	Session GC/retention crosses tenant/session scope	Session/user-scoped GC or separately authorized global retention job	GC one session; unrelated logs/memory remain unchanged
TM-10	high	tmux/Matrix transport target or identity spoofing	Exact target/socket binding, peer identity verification, Matrix whoami, authenticated transport metadata	Wrong socket/peer/room/identity refuses delivery/attach
TM-11	medium	Hermes adapter exposes unsupported or broader legacy powers	Capability negotiation, default deny, normalized scopes, adapter sandbox/timeouts	Unsupported and over-scoped operations fail closed
TM-12	medium	Tess competes with Mos or bypasses orchestration gates	Authority policy and correlated Mos handoff; no Tess worker-claim capability by default	Coding/decomposition intent produces handoff, not direct claim

Security Invariants

1. Authentication is not authorization; every command/tool/provider operation is authorized server-side.
2. Actor, tenant, roles, and channel bindings come only from authenticated gateway context.
3. No client-provided session ID grants ownership or attachment.
4. No privileged action executes without a matching, unexpired, one-time approval when policy requires it.
5. Redaction occurs before persistence and before channel egress.
6. Every externally caused operation is replay-safe and correlated.
7. Provider capability absence is a denial, not an invitation to shell around it.

Existing Findings That Block Tess

• Command executor lacks server-side enforcement for declared scopes.
• Session list/reuse/destroy surfaces are not owner-filtered consistently.
• MCP schemas accept caller-supplied user identity.
• Discord plugin lacks a complete authenticated service ingress and user/channel allowlists.
• Chat/tool persistence lacks mandatory redaction.
• Sessions/pending Discord output are in-memory and not restart-safe.
• Session GC currently performs globally scoped promotion.

These are tracked as M1 security prerequisites and must pass independent security review before Tess ingress is enabled.