AirCoding/AirPlan/docs/architecture/capability-trust-v1.md

# AirCoding Capability Trust Model V1

Date: 2026-05-27
Status: Canonical capability/plugin trust model for V1.0.0 Alpha skeleton

This document defines how AirCoding trusts, installs, enables, validates, and runs capabilities and plugins.

Capabilities are tool bundles with dependencies, triggers, evidence types, and configuration schema. They extend ToolRegistry but do not bypass runtime security.

## 1. Goals

Capability trust must:

1. Allow built-in and future third-party capabilities.
2. Keep dependency installation under Doctor/setup policy.
3. Prevent plugins from bypassing PermissionEngine.
4. Make capability source and permissions visible.
5. Support project-local reproducibility.
6. Keep MVP simple while leaving a path to signed plugins later.

## 2. Capability Manifest

Manifest path:

```text
CAPABILITY.md or capability.json
```

V1 canonical JSON shape:

```ts
interface CapabilityManifestV1 {
  schema_version: 1
  capability_id: string
  display_name: string
  version: string
  description: string
  publisher?: string
  source: CapabilitySource
  trust_level: CapabilityTrustLevel
  tools: CapabilityToolDeclaration[]
  dependencies?: CapabilityDependency[]
  permissions: CapabilityPermissionDeclaration
  events?: {
    produced?: string[]
    consumed?: string[]
  }
  artifact_types?: string[]
  config_schema?: unknown
  entrypoint?: CapabilityEntrypoint
}
```

```ts
type CapabilitySource =
  | { kind: "built_in" }
  | { kind: "local_path"; path: string }
  | { kind: "git"; url: string; ref?: string }
  | { kind: "registry"; registry_id: string; package: string; version: string }

type CapabilityTrustLevel =
  | "built_in"
  | "project_local"
  | "user_installed"
  | "verified_publisher"
  | "untrusted"
```

## 3. Tool Declaration

```ts
interface CapabilityToolDeclaration {
  name: string
  version: number
  category: ToolCategory
  description: string
  input_schema: unknown
  output_schema: unknown
  streaming?: boolean
  permissions: {
    read_paths?: boolean
    write_paths?: boolean
    execute?: boolean
    network?: boolean
    system_sensitive?: boolean
    credentials?: boolean
  }
}
```

Tool names must be namespaced unless built-in:

```text
<capability-id>.<tool-name>
```

Built-in tools reserve short namespaces:

```text
fs.*
shell.*
git.*
project.*
cpp.*
debug.*
gui.*
network.*
artifact.*
context.*
permission.*
doctor.*
```

## 4. Dependency Declaration

```ts
interface CapabilityDependency {
  dependency_id: string
  kind: "system_package" | "binary" | "language_package" | "service" | "model" | "provider" | "display_backend"
  required: boolean
  detector: string
  installer?: {
    strategy: "doctor_allowlisted" | "manual" | "unsupported"
    commands?: string[]
    package_names?: string[]
  }
  permission_notes?: string
}
```

Rules:

1. Capability manifests declare dependencies; they do not install directly.
2. Doctor detects and installs/fixes dependencies according to permission profile.
3. Credentials/system-sensitive dependencies always require explicit confirmation.
4. Install commands must be visible in Doctor plan.

## 5. Permission Declaration

```ts
interface CapabilityPermissionDeclaration {
  read_project?: boolean
  write_project?: boolean
  execute_commands?: boolean
  network?: boolean
  system_sensitive?: boolean
  credentials?: boolean
  project_outside_write?: boolean
  generated_artifacts?: string[]
  notes?: string[]
}
```

Permission declarations are maximum requested permissions, not grants. Runtime PermissionEngine still evaluates every tool call.

## 6. Trust Levels

| Trust level | Meaning | Enable behavior |
|---|---|---|
| `built_in` | shipped with AirCoding release | enabled by default if required |
| `project_local` | stored in project and reviewed by user/team | ask on first enable |
| `user_installed` | installed by user into global AirCoding config | ask on install/enable |
| `verified_publisher` | future signed/verified source | ask with higher confidence |
| `untrusted` | unknown source or modified package | disabled until explicit user approval |

Trust level affects prompts and defaults; it does not bypass PermissionEngine.

## 7. Capability Lifecycle

```text
discovered
  → validated
  → doctor_checked
  → enabled
  → registered
  → active
  → disabled | failed | updated
```

### `discovered`

Runtime finds capability manifests in configured locations.

### `validated`

Manifest schema, tool schemas, namespacing, and declared permissions are validated.

### `doctor_checked`

Doctor checks dependencies and reports missing/incompatible items.

### `enabled`

User/project policy enables the capability.

### `registered`

Tools are added to ToolRegistry with permission metadata.

### `active`

Tools may be invoked through normal ToolRegistry path.

## 8. Capability Locations

Built-in:

```text
resources/capabilities/
```

Global user-installed:

```text
~/.air/capabilities/
```

Project-local:

```text
<project>/.air/shared/capabilities/
```

Cached downloads:

```text
~/.air/cache/plugins/
```

Project-local capability config:

```text
<project>/.air/shared/capabilities.yaml
```

## 9. Runtime Isolation

MVP isolation:

1. Capability tools run as normal runtime tools or child processes under ToolRegistry control.
2. Every filesystem/shell/network action goes through PermissionEngine.
3. Capability code cannot write EventStore directly; it emits tool results/events through runtime APIs.
4. Capability-generated artifacts use ArtifactStore.
5. Capability config is schema-validated.
6. Capability logs go through runtime logging with redaction rules.

Post-MVP may add process/container sandboxing.

## 10. Event Namespace Rules

Built-in event types are defined in `event-registry-v1.md`.

Capability custom events must be namespaced:

```text
capability.<capability-id>.<event-name>
```

Rules:

1. Custom capability events are ephemeral by default.
2. Durable custom events require registration and schema approval.
3. Capability events must not spoof built-in event names.
4. EventStore rejects unknown durable events unless development-mode config explicitly allows them.

## 11. Update and Integrity Rules

MVP:

```text
record source kind/path/ref/version
record manifest hash
ask before updating user-installed or project-local capability
Doctor rechecks dependencies after update
```

Post-MVP:

```text
signature verification
publisher trust store
lockfile with hashes
reproducible capability bundle format
```

Project lockfile candidate:

```text
<project>/.air/shared/capability-lock.json
```

## 12. Built-in MVP Capabilities

Built-in capabilities are part of runtime packages:

```text
core-filesystem
core-shell
core-git
core-project
core-artifacts
core-context
core-permission
core-doctor
toolchain-cpp
debug-basic
gui-evidence-basic
network-evidence-basic
ui-design-assets-basic
```

Only the tools in `tool-registry-v1.md` are required for MVP implementation. Other capability names may exist as placeholders if their tools are not registered yet.

## 13. Refusal and Disable Conditions

Disable/block a capability when:

```text
manifest invalid
tool schema invalid
requested permissions exceed user/project policy
source is untrusted and not approved
dependency install requires disallowed action
capability attempts to bypass ToolRegistry/PermissionEngine
capability emits spoofed built-in events
capability output contains malicious prompt-injection instructions targeting runtime policy
```

## 14. V1.0.0 Alpha Cut Line

V1.0.0 Alpha skeleton must implement:

1. Capability manifest schema.
2. Built-in capability registration.
3. Namespaced tool validation.
4. Dependency declaration and Doctor check path.
5. Enable/disable config.
6. Permission declaration display.
7. ToolRegistry enforcement for capability tools.
8. Manifest hash/source recording.
9. Rejection of unknown durable capability events.

Post-MVP:

```text
signed capability packages
registry publishing
containerized capability execution
capability lockfile enforcement
capability review UI
automatic vulnerability checks
```