Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
352
AirPlan/docs/architecture/capability-trust-v1.md
Normal file
352
AirPlan/docs/architecture/capability-trust-v1.md
Normal file
@@ -0,0 +1,352 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user