docs: add comprehensive security threat model and architecture documentation

1 files changed, 68 insertions, 0 deletions

diff --git a/SECURITY.md b/SECURITY.md
index 537834e4d..cd7e4525b 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,3 +1,71 @@
+# Security
+
+## Threat Model
+
+### Overview
+
+OpenCode is an AI-powered coding assistant that runs locally on your machine. It provides an agent system with access to powerful tools including shell execution, file operations, and web access.
+
+### No Sandbox
+
+OpenCode does **not** sandbox the agent. The permission system exists as a UX feature to help users stay aware of what actions the agent is taking - it prompts for confirmation before executing commands, writing files, etc. However, it is not designed to provide security isolation.
+
+If you need true isolation, run OpenCode inside a Docker container or VM.
+
+### Out of Scope
+
+| Category                        | Rationale                                                               |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| **Server access when opted-in** | If you enable server mode, API access is expected behavior              |
+| **Sandbox escapes**             | The permission system is not a sandbox (see above)                      |
+| **LLM provider data handling**  | Data sent to your configured LLM provider is governed by their policies |
+| **MCP server behavior**         | External MCP servers you configure are outside our trust boundary       |
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         User's Machine                          │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │                    OpenCode Process                       │  │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │  │
+│  │  │   Agent     │  │ Permission  │  │    Storage      │   │  │
+│  │  │  (LLM +     │  │   System    │  │ (~/.local/share │   │  │
+│  │  │   Tools)    │  │             │  │   /opencode)    │   │  │
+│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │  │
+│  │         │                                                 │  │
+│  │         ▼                                                 │  │
+│  │  ┌─────────────────────────────────────────────────────┐ │  │
+│  │  │              Project Directory (cwd)                │ │  │
+│  │  └─────────────────────────────────────────────────────┘ │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                              │                                   │
+│           ┌──────────────────┼──────────────────┐               │
+│           ▼                  ▼                  ▼               │
+│    ┌────────────┐    ┌─────────────┐    ┌─────────────┐        │
+│    │ External   │    │    LLM      │    │    MCP      │        │
+│    │ Filesystem │    │  Providers  │    │  Servers    │        │
+│    └────────────┘    └─────────────┘    └─────────────┘        │
+└─────────────────────────────────────────────────────────────────┘
+
+Optional (user must opt-in):
+┌─────────────────────────────────────────────────────────────────┐
+│                      HTTP Server Mode                           │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  Server (localhost:port)                                │   │
+│  │  - REST API endpoints                                   │   │
+│  │  - WebSocket PTY                                        │   │
+│  │  - SSE event stream                                     │   │
+│  └─────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Server Mode
+
+Server mode is opt-in only. When enabled, set `OPENCODE_SERVER_PASSWORD` to require HTTP Basic Auth. Without this, the server runs unauthenticated (with a warning).
+
+---
+
 # Reporting Security Issues
 
 We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.