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:

CAPABILITY.md or capability.json

V1 canonical JSON shape:

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
}

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

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:

<capability-id>.<tool-name>

Built-in tools reserve short namespaces:

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

4. Dependency Declaration

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

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

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:

resources/capabilities/

Global user-installed:

~/.air/capabilities/

Project-local:

<project>/.air/shared/capabilities/

Cached downloads:

~/.air/cache/plugins/

Project-local capability config:

<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:

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:

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:

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

Project lockfile candidate:

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

12. Built-in MVP Capabilities

Built-in capabilities are part of runtime packages:

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:

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:

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