# Security and Trust

**Status:** Approved target-state baseline  
**First realization:** I0; privileged dogfood gate before I1  
**Practice:** R2 threat modeling.

## Target State

AWP treats agent code, repository code, CI jobs and external provider input as untrusted relative to the control plane. Authorization is capability-based and attributable to `Principal = Human | Agent | System`.

```text
Public client
   ↓ auth/session
Gateway
   ↓ authenticated internal caller + Principal context
Control plane
   ↓ scoped capability / CredentialReference projection
Execution workload / provider
```

The control plane is the final authority. The gateway, agent runtime, CI runner, browser and provider webhooks are never trusted merely because they are internal-looking.

## Invariants From Day 1

- secrets remain behind `SecretStore`; product state stores `CredentialReference` only;
- agents/runners do not receive reusable Git publication, merge or production credentials;
- lower scopes may narrow but never broaden security/capability ceilings;
- every privileged operation rechecks authorization against current Principal, policy, connection binding and target state;
- provider/webhook identity and signatures are verified before observations enter reconciliation;
- untrusted/fork CI jobs receive no protected secrets;
- normal AgentRuns execute in isolated K3s workspaces, not the workstation;
- namespace, ServiceAccount, NetworkPolicy and resource limits express execution trust tiers;
- privileged/host access is an explicit exceptional execution profile, never the default;
- audit records high-risk/denied actions without recording secret material.

## Principal and Capability Model

A `Principal` has stable AWP identity and resolved roles/capabilities. Capabilities are action/resource scoped, for example:

```text
project.read
plan.modify
factory.start
changeset.publish
review.submit
merge.execute
connection.bind
deployment.promote
cluster.machine.enroll
```

Policy evaluates capabilities plus context. Roles are convenience groupings, not the sole authorization model.

## Credentials and Connections

```text
Connection
  -> CredentialReference
      -> SecretStore secret/version

ProjectConnectionBinding
  -> allowed capabilities/resources

Plan/Task/Run
  -> may narrow binding
  -X-> may not silently broaden it
```

Execution receives short-lived/attempt-scoped credentials whenever possible. Secret values do not appear in domain events, audit payloads, logs, Plan/Task records or UI state.

## Trusted Publication

AgentRuns produce `ChangeSet`; trusted control-plane publication verifies:

- expected repository/base revision;
- changed-tree/patch fidelity;
- allowed ref/repository;
- attempt/task provenance;
- required verification/review state;
- current merge/publish policy.

A publication credential is held by the trusted provider adapter/control plane, not mounted into the coding workspace.

## Execution Isolation

Baseline controls:

```text
isolated namespace/workload identity
non-root where possible
read-only service credentials unless needed
network egress policy by execution profile
resource limits
no host filesystem/socket access by default
dedicated PVC/object checkpointing
gVisor RuntimeClass where compatible
separate trusted runner profiles for privileged build mechanics
```

## Threat Model

Before privileged I1 dogfood, maintain an explicit threat model covering:

- browser/gateway -> control trust;
- provider/model credentials;
- GitHub publication authority;
- K3s execution and untrusted agent code;
- workspace/WIP/checkpoint storage;
- agent -> publisher boundary;
- review -> merge authority;
- provider/webhook event trust;
- CI runner trust tiers;
- object-store/log data exposure.

Prefer OWASP conventions and Threat Dragon where it reduces custom work.

## Security State and Failure

Authentication, permission, resource-selection, reauth/revocation and provider outage are distinct states. Connections can be `connected`, `needs-resource-selection`, `needs-permission`, `needs-reauth`, `revoked`, `degraded/error`.

Security failures fail closed for privileged actions. Read-only degradation may remain available where safe.

## Increment Realization

| Increment | Security realization |
|---|---|
| I0 | Principal/capability skeleton, SecretStore/CredentialReference, execution isolation, architecture checks, threat model. |
| I1 | live agent/reviewer/publication/merge separation. |
| I2 | connection onboarding and Planning security/trust triggers. |
| I3 | generic autonomy/Approval/Policy product UX. |
| I5/I6 | CI/deployment privilege tiers and protected promotion. |
| I7 | machine-enrollment trust and cluster admin. |
| I9 | multi-user/org/tenant isolation, enterprise audit/retention. |

## Current Implementation State

Security requirements are target authority; existing broad Overdeck workstation access is explicitly non-precedent.

## Deferred Realization

SPIFFE/SPIRE, OpenBao/ESO, vCluster, Cilium and advanced policy controllers are trigger-only options, not baseline requirements.

## Temporary Dogfood Behavior

Single-owner dogfood may have simpler identity UX, but the control plane still models a Principal and capability checks so I9 multi-user support does not require replacing authorization semantics.

## Decisions / ADRs

Changes to publication authority, execution isolation or secret ownership require explicit Decision and threat-model update.