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.