# Security Model

AIP separates semantic authorization from transport authentication and
connector-specific authenticity checks. This prevents a legacy profile or
product connector from implicitly becoming a universal trust root.

## Trust Domains

A trust domain owns principals, capabilities, resources, channels, and policy.
`Principal` metadata is a claim, not authentication. A native edge must replace
or validate that claim against a server-owned identity established by a trusted
signer binding, bearer/mTLS identity, workload identity, or authenticated
transport mapping. Connectors preserve source-local identities through
`ExternalRef` values without treating those identities as native AIP principals
unless a gateway policy maps them.

## Authentication

Authentication is profile-specific:

- signed native envelopes are accepted only when their `did:key` has an
  explicit principal binding and `Envelope.from` matches that binding;
- HTTP deployments can use bearer tokens, API keys, mTLS, or reverse-proxy
  identity, but the authenticated edge must inject the resulting principal;
- webhooks use HMAC signatures, delivery ids, and timestamp skew checks;
- NATS deployments inherit NATS account, subject, and credential controls;
- SSE and WebSocket sessions inherit the HTTP upgrade authentication decision.

The authentication result is trusted runtime context. Authorization remains a
separate capability-scoped decision in `aip-auth`; user-controlled payload
metadata cannot create or replace that context.

## Trusted Identity Resolution

The standalone daemon denies governed action execution until the deployment
installs a trusted identity directory with `--trusted-identity-file` or
`AIPD_TRUSTED_IDENTITY_FILE`. Each JSON binding identifies the
transport-authenticated `principal_id` and a non-zero monotonic `revision` and
may include verified tenant membership, an opaque credential handle, sanitized
identity mapping, and RFC 3339 expiration. Revoked, expired, duplicate, and
zero-revision bindings are rejected at startup.

The directory must be a regular file smaller than 1 MiB and must not be group-
or world-writable. It contains identity and credential references, never bearer
tokens or connector secrets. Deployments should mount it read-only from their
identity-policy control plane.

`CredentialPolicy.required` is authoritative. When it is `false`, a connector
may use a deployment-owned secret without requiring a caller-bound credential
handle. If an optional handle is supplied, its issuer, scopes, tenant, and
expiration are still validated. When `required` is `true`, a missing handle is
always denied before connector dispatch.

## Authorization

Capabilities are invoked through explicit policy checks. The runtime evaluates
principal kind, scopes, risk, and human-approval requirements before dispatching
an action handler. Product connectors should not hide authorization decisions in
their own outbound code.

## Replay Protection

Signed native messages are claimed in a durable replay registry until the
configured replay window expires. External deliveries carry profile delivery
ids or native idempotency keys. Runtime reservations, leases, and fencing prevent
concurrent execution, while connectors must declare whether the downstream
operation itself supports safe retry. A local idempotency record cannot provide
exactly-once semantics for a downstream API that has no idempotency facility.
Webhook profiles enforce timestamp skew before accepting a payload.

## Payload Redaction

Connectors may preserve raw payloads for debugging or audit only when policy
allows it. Logs, traces, and cross-domain events should carry normalized fields,
ids, and redacted snippets rather than full product payloads or secrets.

## Cryptography

`aip-crypto` owns canonical JSON, Ed25519 signatures, DID-key conversion,
receipt hashes, hash chains, X25519 key agreement, HKDF-SHA256, and
AES-256-GCM session encryption primitives. The runtime and connectors consume
these primitives but do not redefine them.

## Escalation Security

Human escalation is a first-class protocol state. High-risk or policy-blocked
capabilities should return an escalation event or `RequiresHuman` action result
instead of bypassing policy. Escalation decisions must identify the resolving
principal and be stored as audit events where policy requires.

## Key Rotation

Manifests can advertise supported signing keys, DID identifiers, and transport
security metadata. Operators rotate keys by adding a second explicit trusted
DID-to-principal binding, accepting both keys during a bounded overlap window,
then removing the old binding once no active session or callback depends on it.
Publishing a DID in a manifest does not by itself make that DID trusted.