WOPR implements a three-layer security model for session isolation and access control. This protects against malicious P2P peers, compromised plugins, and unauthorized cross-session access.

┌─────────────────────────────────────────────────────────────┐
│                    WOPR Security Model                       │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Trust Levels (WHO)                                │
│  - owner, trusted, semi-trusted, untrusted                  │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Capabilities (WHAT)                               │
│  - inject, inject.tools, inject.network, session.spawn, ... │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Sandbox (WHERE)                                   │
│  - Docker isolation with network/filesystem restrictions    │
└─────────────────────────────────────────────────────────────┘

# Via CLI
wopr security status

# Via A2A tool in a session
# Use security_whoami tool to see your trust level and capabilities

# Grant trusted access with specific capabilities
wopr p2p grant <peer-pubkey> --profile trusted --sessions "code,research"

# Grant semi-trusted access (no tools by default)
wopr p2p grant <peer-pubkey> --profile semi-trusted --sessions "public-api"

{
  "security": {
    "gateways": {
      "sessions": ["p2p-gateway"],
      "rules": {
        "p2p-gateway": {
          "allowForwardTo": ["code-executor", "research"],
          "allowActions": ["query", "summarize"],
          "rateLimit": { "perMinute": 10 }
        }
      }
    }
  }
}

Trust levels determine the baseline permissions for an injection source.

owner > trusted > semi-trusted > untrusted

Higher trust levels inherit all permissions of lower levels. A trusted source can do everything a semi-trusted source can, plus more.

1. CLI/Daemon: Always owner
2. P2P Peers: Based on access grant configuration
3. Plugins: Based on plugin manifest
4. API: Based on API key configuration
5. Discovery: Always untrusted (requires explicit grant to elevate)

Capabilities provide fine-grained control over what actions a source can perform.

Pre-configured capability sets for common use cases:

const CAPABILITY_PROFILES = {
  owner: ["*"],  // All capabilities
  trusted: ["inject", "inject.tools", "session.spawn", "a2a.call"],
  "semi-trusted": ["inject", "inject.tools"],
  untrusted: ["inject"],  // Message only, no tools
  readonly: ["inject"],   // Alias for untrusted
  gateway: ["inject", "inject.tools", "cross.inject", "a2a.call"],
};

// In code
import { hasCapability } from "./security/types.js";

if (hasCapability(["inject", "inject.tools"], "inject.network")) {
  // Has network capability
}

// Via A2A tool
// Use security_check tool: { "capability": "inject.network" }

For untrusted sources, WOPR can execute sessions in isolated Docker containers.

{
  "security": {
    "trustLevels": {
      "untrusted": {
        "sandbox": {
          "enabled": true,
          "network": "none",
          "readOnly": true,
          "memory": "512m",
          "cpus": "0.5"
        }
      }
    }
  }
}

1. Trust level has sandbox.enabled: true
2. Session explicitly requires sandbox
3. Source type is untrusted P2P discovery

See SANDBOX.md for detailed sandbox configuration.

Untrusted sources cannot directly inject into privileged sessions. They must go through a gateway session.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  P2P Peer       │────▶│  Gateway        │────▶│  Privileged     │
│  (untrusted)    │     │  (semi-trusted) │     │  (owner/trusted)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
     inject              validates & forwards     executes

1. Receive - Accept injections from untrusted sources
2. Validate - Check against policy (allowed actions, rate limits)
3. Transform - Sanitize/restructure requests
4. Forward - Inject into appropriate privileged session
5. Respond - Return results to original requester

• Choke point: All untrusted traffic goes through one place
• Policy enforcement: Gateway enforces rules before forwarding
• Audit trail: All escalations logged at gateway
• No direct access: Untrusted never touches privileged sessions

See GATEWAY.md for detailed gateway configuration.

Sessions have access to security introspection tools:

Returns the caller's security context.

// Response
{
  "trustLevel": "trusted",
  "capabilities": ["inject", "inject.tools", "session.spawn"],
  "sandbox": { "enabled": false },
  "source": {
    "type": "p2p",
    "identity": { "publicKey": "MCow..." }
  }
}

Check if a specific action is allowed before attempting it.

// Request
{ "capability": "inject.network" }

// Response
{
  "allowed": false,
  "reason": "Capability inject.network not granted for trust level 'trusted'"
}

Note: P2P security features require the wopr-plugin-p2p plugin.

The P2P plugin includes several security measures:

Discovered peers are NOT automatically granted access:

// Default behavior (secure)
{
  accept: false,
  sessions: [],
  reason: "Discovery auto-accept disabled. Use p2p_grant to authorize."
}

Reduced from 7 days to 24 hours for security:

gracePeriodMs: 24 * 3600000  // 24 hours

Protection against memory exhaustion attacks:

Messages exceeding these limits are rejected before processing.

Per-peer rate limits for different operations:

Security can operate in different modes during migration:

{
  "security": {
    "enforcement": "warn"
  }
}

Start with warn to identify issues, then switch to enforce.

See SECURITY_CONFIG.md for complete configuration options.

{
  "security": {
    "enforcement": "enforce",
    "defaults": {
      "tools": { "deny": ["config.write", "inject.exec"] }
    },
    "trustLevels": {
      "untrusted": {
        "sandbox": { "enabled": true, "network": "none" },
        "tools": { "deny": ["*"] }
      }
    },
    "p2p": {
      "discoveryTrust": "untrusted",
      "autoAccept": false
    }
  }
}

See SECURITY_API.md for programmatic security management.

• THREAT_MODEL.md - Cryptographic security and threat analysis
• GATEWAY.md - Gateway session configuration
• SANDBOX.md - Docker sandbox details
• SECURITY_CONFIG.md - Configuration reference
• SECURITY_API.md - API reference