# Security Architecture Overview

## Security Principles

| Principle | Implementation |
|-----------|----------------|
| **Defense in depth** | Multiple layers: network, auth, authz, audit |
| **Least privilege** | Role-based access; minimal permissions |
| **Zero trust** | All requests authenticated; mTLS for agents |
| **Secrets hygiene** | Secrets in vault; never in DB; ephemeral injection |
| **Audit everything** | All mutations logged; evidence trail |
| **Immutable evidence** | Evidence packets append-only; cryptographically signed |

## Authentication Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                    AUTHENTICATION ARCHITECTURE                              │
│                                                                             │
│  Human Users                            Service/Agent                       │
│  ┌──────────┐                          ┌──────────┐                        │
│  │ Browser  │                          │ Agent    │                        │
│  └────┬─────┘                          └────┬─────┘                        │
│       │                                     │                               │
│       │ OAuth 2.0                           │ mTLS + JWT                    │
│       │ Authorization Code                  │                               │
│       ▼                                     ▼                               │
│  ┌──────────────────────────────────────────────────────────────────┐      │
│  │                         AUTHORITY MODULE                          │      │
│  │                                                                   │      │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │      │
│  │  │ OAuth 2.0   │  │   mTLS      │  │ API Key     │              │      │
│  │  │ Provider    │  │ Validator   │  │ Validator   │              │      │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │      │
│  │                                                                   │      │
│  │  ┌─────────────────────────────────────────────────────────────┐ │      │
│  │  │                    TOKEN ISSUER                              │ │      │
│  │  │  - Short-lived JWT (15 min)                                 │ │      │
│  │  │  - Contains: user_id, tenant_id, roles, permissions         │ │      │
│  │  │  - Signed with RS256                                        │ │      │
│  │  └─────────────────────────────────────────────────────────────┘ │      │
│  └──────────────────────────────────────────────────────────────────┘      │
│       │                                                                     │
│       ▼                                                                     │
│  ┌──────────────────────────────────────────────────────────────────┐      │
│  │                         API GATEWAY                               │      │
│  │                                                                   │      │
│  │  - Validate JWT signature                                        │      │
│  │  - Check token expiration                                        │      │
│  │  - Extract tenant context                                        │      │
│  │  - Enforce rate limits                                           │      │
│  └──────────────────────────────────────────────────────────────────┘      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Authorization Model

### Permission Structure

```typescript
interface Permission {
  resource: ResourceType;
  action: ActionType;
  scope?: ScopeType;
  conditions?: Condition[];
}

type ResourceType =
  | "environment"
  | "release"
  | "promotion"
  | "target"
  | "agent"
  | "workflow"
  | "plugin"
  | "integration"
  | "evidence";

type ActionType =
  | "create"
  | "read"
  | "update"
  | "delete"
  | "execute"
  | "approve"
  | "deploy"
  | "rollback";

type ScopeType =
  | "*"                              // All resources
  | { environmentId: UUID }          // Specific environment
  | { labels: Record<string, string> };  // Label-based
```

### Role Definitions

| Role | Permissions |
|------|-------------|
| `admin` | All permissions on all resources |
| `release-manager` | Full access to releases, promotions; read environments/targets |
| `deployer` | Read releases; create/read promotions; read targets |
| `approver` | Read/approve promotions |
| `viewer` | Read-only access to all resources |

### Environment-Scoped Roles

Roles can be scoped to specific environments:

```typescript
// Example: Production deployer can only deploy to production
const prodDeployer = {
  role: "deployer",
  scope: { environmentId: "prod-environment-uuid" }
};
```

## Policy Enforcement Points

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                    POLICY ENFORCEMENT POINTS                                │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         API LAYER (PEP 1)                            │   │
│  │  - Authenticate request                                             │   │
│  │  - Check resource-level permissions                                  │   │
│  │  - Enforce tenant isolation                                          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      SERVICE LAYER (PEP 2)                           │   │
│  │  - Check business-level permissions                                  │   │
│  │  - Validate separation of duties                                     │   │
│  │  - Enforce approval policies                                         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    DECISION ENGINE (PEP 3)                           │   │
│  │  - Evaluate security gates                                          │   │
│  │  - Evaluate custom OPA policies                                     │   │
│  │  - Produce signed decision records                                  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     DATA LAYER (PEP 4)                               │   │
│  │  - Row-level security (tenant_id)                                   │   │
│  │  - Append-only enforcement (evidence)                               │   │
│  │  - Encryption at rest                                               │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Agent Security Model

See [Agent Security](agent-security.md) for detailed agent security architecture.

Key features:
- mTLS authentication with CA-signed certificates
- One-time registration tokens
- Short-lived JWT for task execution
- Encrypted task payloads
- Scoped credentials per task

## Secrets Management

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                    SECRETS FLOW (NEVER STORED IN DB)                        │
│                                                                             │
│  ┌──────────────┐        ┌──────────────┐        ┌──────────────┐          │
│  │    VAULT     │        │  STELLA CORE │        │    AGENT     │          │
│  │  (Source)    │        │  (Broker)    │        │  (Consumer)  │          │
│  └──────┬───────┘        └──────┬───────┘        └──────┬───────┘          │
│         │                       │                       │                   │
│         │                       │ Task requires secret  │                   │
│         │                       │                       │                   │
│         │ Fetch with service   │                       │                   │
│         │ account token        │                       │                   │
│         │◄───────────────────────                       │                   │
│         │                       │                       │                   │
│         │ Return secret        │                       │                   │
│         │ (wrapped, short TTL) │                       │                   │
│         │───────────────────────►                       │                   │
│         │                       │                       │                   │
│         │                       │ Embed in task payload │                   │
│         │                       │ (encrypted)          │                   │
│         │                       │───────────────────────►                   │
│         │                       │                       │                   │
│         │                       │                       │ Decrypt           │
│         │                       │                       │ Use for task      │
│         │                       │                       │ Discard           │
│                                                                             │
│  Rules:                                                                     │
│  - Secrets NEVER stored in Stella database                                 │
│  - Only Vault references stored                                            │
│  - Secrets fetched at execution time only                                  │
│  - Secrets not logged (masked in logs)                                     │
│  - Secrets not persisted in agent memory beyond task scope                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Threat Model

| Threat | Attack Vector | Mitigation |
|--------|---------------|------------|
| **Credential theft** | Database breach | Secrets never in DB; only vault refs |
| **Token replay** | Stolen JWT | Short-lived tokens (15 min); refresh tokens rotated |
| **Agent impersonation** | Fake agent | mTLS with CA-signed certs; registration token one-time |
| **Digest tampering** | Modified image | Digest verification at pull time; mismatch = failure |
| **Evidence tampering** | Modified audit records | Append-only table; cryptographic signing |
| **Privilege escalation** | Compromised account | Role-based access; SoD enforcement; audit logs |
| **Supply chain attack** | Malicious plugin | Plugin sandbox; capability declarations; review process |
| **Lateral movement** | Compromised target | Short-lived task credentials; scoped permissions |
| **Data exfiltration** | Log/artifact theft | Encryption at rest; network segmentation |
| **Denial of service** | Resource exhaustion | Rate limiting; resource quotas; circuit breakers |

## Audit Trail

### Audit Event Structure

```typescript
interface AuditEvent {
  id: UUID;
  timestamp: DateTime;
  tenantId: UUID;

  // Actor
  actorType: "user" | "agent" | "system" | "plugin";
  actorId: UUID;
  actorName: string;
  actorIp?: string;

  // Action
  action: string;              // "promotion.approved", "deployment.started"
  resource: string;            // "promotion"
  resourceId: UUID;

  // Context
  environmentId?: UUID;
  releaseId?: UUID;
  promotionId?: UUID;

  // Details
  before?: object;             // State before (for updates)
  after?: object;              // State after
  metadata?: object;           // Additional context

  // Integrity
  previousEventHash: string;   // Hash chain for tamper detection
  eventHash: string;
}
```

### Audited Operations

| Category | Operations |
|----------|------------|
| **Authentication** | Login, logout, token refresh, failed attempts |
| **Authorization** | Permission denied events |
| **Environments** | Create, update, delete, freeze window changes |
| **Releases** | Create, deprecate, archive |
| **Promotions** | Request, approve, reject, cancel |
| **Deployments** | Start, complete, fail, rollback |
| **Targets** | Register, update, delete, health changes |
| **Agents** | Register, heartbeat gaps, capability changes |
| **Integrations** | Create, update, delete, test |
| **Plugins** | Enable, disable, config changes |
| **Evidence** | Create (never update/delete) |

## References

- [Authentication & Authorization](auth.md)
- [Agent Security](agent-security.md)
- [Threat Model](threat-model.md)
- [Audit Trail](audit-trail.md)