AirCoding/AirPlan/docs/architecture/security-model-v1.md

# AirCoding Security Model V1

Date: 2026-05-27
Status: Canonical security model for V1.0.0 Alpha skeleton

This document defines AirCoding's MVP security boundaries for local coding-agent operation.

## 1. Security Goals

AirCoding should:

1. Protect user code, credentials, system-sensitive files, and git history.
2. Allow productive local development, including C++ build directories and `sudo` when appropriate.
3. Make risky actions visible and confirmable.
4. Keep local evidence useful for debugging without automatic upload.
5. Prevent tool/provider/plugin boundaries from bypassing permissions.
6. Preserve recoverability through backups, artifacts, and event history.

## 2. Trust Boundaries

```text
User
  → Main Agent/UI
  → Runtime services
  → ToolRegistry/PermissionEngine
  → OS/filesystem/shell/network/provider
```

Boundary rules:

1. User instructions are intent, not permission bypass.
2. LLM output is untrusted until validated by runtime/tool schemas and PermissionEngine.
3. Tool inputs are validated before execution.
4. Provider responses cannot directly modify files or run commands.
5. Plugins/capabilities use the same ToolRegistry and PermissionEngine path as built-ins.
6. Session DB/artifacts are local state, not remote telemetry.

## 3. Permission Profiles

```ts
type PermissionProfile =
  | "low"
  | "normal"
  | "high"
  | "developer"
```

Profile behavior:

| Profile | Behavior |
|---|---|
| `low` | ask for writes/exec/network beyond read-only inspection |
| `normal` | allow project-local work; ask for project-outside/system-sensitive/credentials |
| `high` | announce-then-run many allowlisted actions; still ask for credentials/system-sensitive/migrations/destructive shared actions |
| `developer` | for AirCoding developers; may emit full encrypted diagnostics; still cannot bypass credential/policy rules |

## 4. Path Security

Path categories:

```ts
type PathRiskCategory =
  | "project"
  | "project_air_shared"
  | "project_air_local"
  | "project_build"
  | "project_git"
  | "project_outside_user"
  | "system_sensitive"
  | "credential_store"
  | "unknown"
```

Rules:

1. Resolve symlinks with realpath before deciding risk.
2. Project directory reads are allowed by default.
3. Project directory writes are allowed by default except protected paths.
4. `.git/` is write-protected by default.
5. Build directories are unrestricted project paths because C++ workflows need them.
6. Project-outside non-system writes require backup then allow/ask depending profile.
7. System-sensitive and credential-store paths require explicit confirmation or are blocked.
8. Unknown paths are treated conservatively.

System-sensitive examples:

```text
/etc
/usr
/bin
/sbin
/boot
/dev
/proc
/sys
system service directories
package manager global state
```

Credential-store examples:

```text
~/.ssh
~/.gnupg
password manager stores
cloud credential directories
.env files when classified as secret-bearing
API key config files
```

## 5. Command Security

Command risk categories:

```ts
type CommandRisk =
  | "read_only"
  | "project_write"
  | "build_or_test"
  | "network"
  | "dependency_install"
  | "destructive"
  | "system_sensitive"
  | "credential_access"
  | "privilege_escalation"
  | "unknown"
```

Rules:

1. `sudo` alone is not automatically forbidden.
2. `sudo` touching system-sensitive paths still requires explicit confirmation.
3. Destructive commands are never run silently unless narrowly allowlisted and recoverable.
4. Interactive commands are not supported in MVP except through dedicated tools.
5. Commands must have cwd and timeout.
6. stdout/stderr are captured as artifacts when needed for evidence.
7. Shell execution is non-interactive and does not inherit secrets except allowlisted environment variables.

Destructive examples:

```text
rm -rf
reset --hard
clean -fd
force push
dropping databases
overwriting user files outside scoped paths
killing unrelated processes
```

## 6. Network Security

Network categories:

```text
provider API calls
dependency downloads
project-requested network behavior
analysis/debug network capture
unknown outbound network
```

Rules:

1. Provider API calls use configured providers only.
2. Dependency downloads are managed through Doctor/setup and permission policy.
3. Generated/project code network access must match user request or be approved.
4. Network capture may require elevated permissions and explicit reason.
5. No automatic upload of doctor bundles, debug knowledge, artifacts, screenshots, logs, pcaps, or source code.

## 7. Credential Handling

Credential rules:

1. Secrets are referenced by `auth_ref`, never copied into session DB/events/artifacts.
2. Tools must declare whether input/output may contain secrets.
3. Provider adapters redact auth headers and API keys from logs.
4. Doctor checks existence/shape of credentials without printing values.
5. Credential access always requires explicit confirmation unless already granted by a scoped secure config reference.
6. LLM-visible context must not include secrets unless the user explicitly requests and the policy allows it.

## 8. Provider and Prompt Injection Security

External content includes:

```text
web pages
dependency logs
compiler output
repo files
tool output
provider responses
MCP/plugin output
```

Rules:

1. External content is data, not instruction.
2. Tool results cannot override runtime policy or project rules.
3. Prompt injection suspicion is surfaced to the user/developer log when relevant.
4. ContextAssembler separates instruction layers from evidence/tool output layers.
5. Provider output must pass tool schema validation before tool execution.

## 9. Plugin and Capability Security

Capabilities declare:

```text
tools provided
dependencies
permissions requested
network access
artifact types
config schema
trust level
```

Rules:

1. Capability install/enable is a permissioned action.
2. Capability tools are not privileged above built-ins.
3. Capability dependencies are detected/installed by Doctor, not by arbitrary plugin scripts.
4. Unknown plugin events cannot be durable unless registered or namespaced and approved.
5. Capability updates require the same package/source trust policy as install.

## 10. Logs, Artifacts, and Export

Local logs:

```text
~/.air/logs/air.log
~/.air/logs/air.developer.log
```

Rules:

1. `air.log` is user-readable and contains startup failures, exceptions, and environment configuration issues.
2. `air.developer.log` is full debug/performance log encrypted with development-team public key.
3. Logs retain seven days by default.
4. Session artifacts are project-local and not automatically redacted.
5. Export/share/upload requires explicit user action.
6. Debug Knowledge sharing requires redaction, preview, and authorization.
7. Doctor bundles may include full diagnostics and are encrypted for development-team channel.

## 11. Backup and Recovery

Project-outside writes:

```text
backup to <project>/.air/local/backups/ before write
```

Migration:

```text
always ask user
backup .air first
rollback on failure
```

Workspace merges preserve conflict artifacts and do not discard user work silently.

## 12. Refusal and Block Conditions

AirCoding refuses or blocks:

```text
malware, credential theft, stealth, evasion, destructive abuse
unauthorized access or exploitation
mass targeting or DoS
supply-chain compromise
unapproved credential access
unapproved destructive shared-state actions
policy-bypassing requests
```

Defensive security, authorized testing, CTF, and educational work are allowed when authorization context is clear.

## 13. PermissionEngine API

```ts
interface PermissionRequestContext {
  session_id: string
  task_id?: string
  agent_id?: string
  tool_name?: string
  command?: string
  paths?: string[]
  network?: boolean
  requested_action: string
  reason: string
}

type PermissionAction = "allow" | "deny" | "ask_user" | "block" | "refuse" | "announce_then_run"
type PermissionGrantScope = "none" | "once" | "session" | "project" | "global"

interface PermissionDecision {
  action: PermissionAction
  grant_scope: PermissionGrantScope
  risk_level: "low" | "medium" | "high" | "critical"
  reason: string
  required_confirmation?: boolean
  backup_required?: boolean
  evidence_refs?: string[]
}
```

Permission decisions are recorded with `permission.decision.recorded` when durable.

## 14. V1.0.0 Alpha Cut Line

V1.0.0 Alpha skeleton must implement:

1. Realpath-based path classifier.
2. Command risk analyzer.
3. Permission profiles.
4. Explicit credential/system-sensitive confirmation gates.
5. Project-outside backup-before-write path.
6. ToolRegistry permission enforcement.
7. Provider secret redaction.
8. Export/share no-auto-upload rule.
9. Security refusal/block handling.
10. Permission decision events.

Post-MVP:

```text
sandboxed command runner
seccomp/container profiles
plugin signature verification
secret scanner integration
advanced prompt-injection classifier
policy-as-code engine
```