# OpenFang Security Architecture

This document provides a comprehensive technical reference for every security system in the OpenFang Agent Operating System. All struct names, function signatures, constant values, and algorithm descriptions are drawn directly from the source code.

---

## Table of Contents

01. -[Security Overview](/content/docs/security#1-security-overview/index.html)
02. -[Capability-Based Security](/content/docs/security#2-capability-based-security/index.html)
03. -[WASM Dual Metering](/content/docs/security#3-wasm-dual-metering/index.html)
04. -[Merkle Hash Chain Audit Trail](/content/docs/security#4-merkle-hash-chain-audit-trail/index.html)
05. -[Information Flow Taint Tracking](/content/docs/security#5-information-flow-taint-tracking/index.html)
06. -[Ed25519 Manifest Signing](/content/docs/security#6-ed25519-manifest-signing/index.html)
07. -[SSRF Protection](/content/docs/security#7-ssrf-protection/index.html)
08. -[Secret Zeroization](/content/docs/security#8-secret-zeroization/index.html)
09. -[OFP Mutual Authentication](/content/docs/security#9-ofp-mutual-authentication/index.html)
10. -[Security Headers](/content/docs/security#10-security-headers/index.html)
11. -[GCRA Rate Limiter](/content/docs/security#11-gcra-rate-limiter/index.html)
12. -[Path Traversal Prevention](/content/docs/security#12-path-traversal-prevention/index.html)
13. -[Subprocess Sandbox](/content/docs/security#13-subprocess-sandbox/index.html)
14. -[Prompt Injection Scanner](/content/docs/security#14-prompt-injection-scanner/index.html)
15. -[Loop Guard](/content/docs/security#15-loop-guard/index.html)
16. -[Session Repair](/content/docs/security#16-session-repair/index.html)
17. -[Health Endpoint Redaction](/content/docs/security#17-health-endpoint-redaction/index.html)
18. -[Security Configuration](/content/docs/security#18-security-configuration/index.html)
19. -[Security Dependencies](/content/docs/security#19-security-dependencies/index.html)

---

## 1. Security Overview

OpenFang implements **defense-in-depth** security. No single mechanism is trusted to be the sole protector; instead, 16 independent systems form overlapping layers so that a failure in any one layer is caught by others.

| # | System | Crate | Protects Against |
| --- | --- | --- | --- |
| 1 | Capability-Based Security | `openfang-types` | Unauthorized actions by agents |
| 2 | WASM Dual Metering | `openfang-runtime` | Infinite loops, CPU DoS |
| 3 | Merkle Audit Trail | `openfang-runtime` | Tampered audit logs |
| 4 | Taint Tracking | `openfang-types` | Prompt injection, data exfiltration |
| 5 | Ed25519 Manifest Signing | `openfang-types` | Supply chain attacks |
| 6 | SSRF Protection | `openfang-runtime` | Server-Side Request Forgery |
| 7 | Secret Zeroization | `openfang-runtime`, `openfang-channels` | Memory forensics, key leakage |
| 8 | OFP Mutual Auth | `openfang-wire` | Unauthorized peer connections |
| 9 | Security Headers | `openfang-api` | XSS, clickjacking, MIME sniffing |
| 10 | GCRA Rate Limiter | `openfang-api` | API abuse, denial of service |
| 11 | Path Traversal Prevention | `openfang-runtime` | Directory traversal attacks |
| 12 | Subprocess Sandbox | `openfang-runtime` | Secret leakage via child processes |
| 13 | Prompt Injection Scanner | `openfang-skills` | Malicious skill prompts |
| 14 | Loop Guard | `openfang-runtime` | Stuck agent tool loops |
| 15 | Session Repair | `openfang-runtime` | Corrupted LLM conversation history |
| 16 | Health Endpoint Redaction | `openfang-api` | Information leakage |

---

## 2. Capability-Based Security

OpenFang uses capability-based security. An agent can only perform actions it has been explicitly granted permission to do. Capabilities are immutable after agent creation and are enforced at the kernel level.

### 2.1 Capability Variants

The `Capability` enum defines every permission type:

```rust
pub enum Capability {
    // Filesystem
    FileRead(String),       // Glob pattern, e.g. "/data/*"
    FileWrite(String),

// Network
    NetConnect(String),     // Host:port pattern, e.g. "*.openai.com:443"
    NetListen(u16),

// Tools
    ToolInvoke(String),     // Specific tool ID
    ToolAll,                // All tools (dangerous)

// LLM
    LlmQuery(String),
    LlmMaxTokens(u64),

// Agent interaction
    AgentSpawn,
    AgentMessage(String),
    AgentKill(String),

// Memory
    MemoryRead(String),
    MemoryWrite(String),

// Shell
    ShellExec(String),
    EnvRead(String),

// OFP Wire Protocol
    OfpDiscover,
    OfpConnect(String),
    OfpAdvertise,

// Economic
    EconSpend(f64),
    EconEarn,
    EconTransfer(String),
}
```

### 2.2 Pattern Matching

The `capability_matches(granted, required)` function implements glob-style matching:

- **Exact match:** `