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.

Closed Prerequisite Findings

The original M1 findings below are closed by landed controls and retained for audit traceability.

Former finding	Closed evidence
Command scope/role enforcement	apps/gateway/src/commands/command-authorization.service.ts and its authorization tests enforce the server-side approval boundary.
Cross-owner session access	Gateway session ownership tests cover server-derived owner and tenant scope.
Caller-controlled MCP identity	MCP tools derive actor and tenant from authenticated gateway context.
Missing Discord ingress allowlists	apps/gateway/src/plugin/plugin.module.ts requires the guild, channel, and user allowlist environment values; apps/gateway/src/plugin/discord-ingress.security.spec.ts exercises denial and configured ingress.
Missing redaction before persistence/egress	Gateway and log redaction coverage verifies sensitive content is classified before durable storage or channel delivery.
In-memory-only restart safety	packages/agent/src/durable-session.test.ts reconstructs durable identity, inbox/outbox, checkpoints, and handoffs after simulated restart.
Globally scoped session GC	apps/gateway/src/gc/session-gc.service.spec.ts verifies session-only collection and the absence of automatic global collection entry points.

These controls remain subject to the runtime's independent review and release qualification gates.