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

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

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:

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:

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

Credential-store examples:

~/.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:

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:

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

6. Network Security

Network categories:

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:

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:

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:

~/.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:

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

Migration:

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:

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

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:

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