# Authentication and Authorization Architecture

**Version:** 1.0
**Date:** 2025-11-29
**Status:** Canonical

This advisory defines the product rationale, token model, scope taxonomy, and implementation strategy for the Authority module, consolidating authentication and authorization patterns across all Stella Ops services.

---

## 1. Executive Summary

Authority is the **on-premises OIDC/OAuth2 issuing service** that provides secure identity for all Stella Ops operations. Key capabilities:

- **Short-Lived Tokens (OpTok)** - 2-5 minute TTL operational tokens
- **Sender Constraints** - DPoP or mTLS binding prevents token theft
- **Fine-Grained Scopes** - 65+ scopes with role bundles
- **Multi-Tenant Isolation** - Tenant claims enforced throughout
- **Delegated Service Accounts** - Automation without credential exposure
- **Sovereign Crypto Support** - Configurable signing algorithms per profile

---

## 2. Market Drivers

### 2.1 Target Segments

| Segment | Authentication Requirements | Use Case |
|---------|---------------------------|----------|
| **Enterprise** | SSO/SAML integration, MFA | Corporate security policies |
| **Government** | CAC/PIV, FIPS validation | Federal compliance |
| **Financial Services** | Strong auth, audit trails | SOC 2, PCI-DSS |
| **Healthcare** | HIPAA access controls | PHI protection |

### 2.2 Competitive Positioning

Most vulnerability scanning tools rely on basic API keys. Stella Ops differentiates with:
- **Zero-trust token model** with sender constraints
- **Fine-grained RBAC** with 65+ scopes
- **Cryptographic binding** (DPoP/mTLS) prevents token theft
- **Deterministic revocation bundles** for offline verification
- **Plugin extensibility** for custom identity providers

---

## 3. Token Model

### 3.1 Three-Token System

| Token | Lifetime | Purpose | Binding |
|-------|----------|---------|---------|
| **License Token (LT)** | Long-lived | Cloud licensing enrollment | Installation |
| **Proof-of-Entitlement (PoE)** | Medium | License validation | Installation key |
| **Operational Token (OpTok)** | 2-5 min | Runtime authentication | DPoP/mTLS |

### 3.2 Operational Token Structure

**Registered Claims:**

```json
{
  "iss": "https://authority.example.com",
  "sub": "client-id-or-user-id",
  "aud": "signer|scanner|attestor|concelier|...",
  "exp": 1732881600,
  "iat": 1732881300,
  "nbf": 1732881270,
  "jti": "uuid",
  "scope": "scanner.scan scanner.export signer.sign"
}
```

**Sender Constraint Claims:**

```json
{
  "cnf": {
    "jkt": "base64url(SHA-256(JWK))",     // DPoP binding
    "x5t#S256": "base64url(SHA-256(cert))" // mTLS binding
  }
}
```

**Tenant & Context Claims:**

```json
{
  "tid": "tenant-id",
  "inst": "installation-id",
  "roles": ["svc.scanner", "svc.signer"],
  "plan": "enterprise"
}
```

### 3.3 Sender Constraints

**DPoP (Demonstration of Proof-of-Possession):**

1. Client generates ephemeral JWK keypair
2. Client sends DPoP proof header with `htm`, `htu`, `iat`, `jti`
3. Authority validates and stamps token with `cnf.jkt`
4. Resource servers verify same key on each request
5. Nonce challenges available for high-value audiences

**mTLS (Mutual TLS):**

1. Client presents certificate at TLS handshake
2. Authority validates and binds to `cnf.x5t#S256`
3. Resource servers verify same cert on each request
4. Required for high-value audiences (signer, attestor)

---

## 4. Scope Taxonomy

### 4.1 Scope Categories (65+ scopes)

**Ingestion Scopes (tenant-required):**
- `advisory:ingest` - Concelier advisory ingestion
- `vex:ingest` - Excititor VEX ingestion
- `signals:write` - Reachability signal ingestion

**Verification Scopes (require `aoc:verify` pairing):**
- `advisory:read` - Advisory queries
- `vex:read` - VEX queries
- `signals:read` - Signal queries

**Service Scopes:**

| Service | Scopes |
|---------|--------|
| **Signer** | `signer.sign` (mTLS enforced) |
| **Scanner** | `scanner.scan`, `scanner.export`, `scanner.read` |
| **Attestor** | `attestor.write` |
| **Policy Studio** | `policy:author`, `policy:review`, `policy:approve`, `policy:operate`, `policy:publish`, `policy:promote`, `policy:audit`, `policy:simulate` |
| **Vuln Explorer** | `vuln:view`, `vuln:investigate`, `vuln:operate`, `vuln:audit` |
| **Orchestrator** | `orch:read`, `orch:operate`, `orch:quota`, `orch:backfill` |
| **Export Center** | `export.viewer`, `export.operator`, `export.admin` |
| **Task Packs** | `packs.read`, `packs.write`, `packs.run`, `packs.approve` |
| **Evidence** | `evidence:create`, `evidence:read`, `evidence:hold` |
| **Timeline** | `timeline:read`, `timeline:write` |

**Special Scopes:**
- `obs:incident` - Incident mode activation (fresh auth required)
- `tenant:admin` - Cross-tenant operations

### 4.2 Role Bundles

Authority provides 40+ predefined roles that bundle related scopes:

| Role | Scopes | Requirements |
|------|--------|--------------|
| `role/concelier-ingest` | `advisory:ingest`, `advisory:read` | Tenant claim |
| `role/signals-uploader` | `signals:write`, `signals:read`, `aoc:verify` | Tenant claim |
| `role/policy-engine` | `effective:write`, `findings:read` | `serviceIdentity: policy-engine` |
| `role/policy-author` | `policy:author`, `policy:read`, `policy:simulate`, `findings:read` | - |
| `role/policy-approver` | `policy:approve`, `policy:review`, `policy:read`, `policy:simulate`, `findings:read` | - |
| `role/orch-operator` | `orch:read`, `orch:operate` | - |
| `role/export-admin` | `export.viewer`, `export.operator`, `export.admin` | - |

---

## 5. Multi-Tenant Isolation

### 5.1 Tenant Claim Enforcement

**Token Issuance:**
- Authority normalizes tenant: `trim().ToLowerInvariant()`
- Tokens include `tid` (tenant ID) and `inst` (installation ID)
- Cross-tenant isolation enforced at issuance

**Propagation:**
- API Gateway forwards `tid` as `X-Stella-Tenant` header
- Downstream services reject requests without header
- All data stamped with tenant identifier

**Scope Enforcement:**
- Ingestion scopes require tenant claim
- `aoc:verify` pairing required for verification scopes
- Cross-tenant replay rejected

### 5.2 Cross-Tenant Operations

For platform operators with `tenant:admin`:
- Switch tenants via `/authority/tenant/switch`
- CLI `--tenant <id>` override
- Delegated token exchange for automation
- Full audit trail of tenant switches

---

## 6. Advanced Token Features

### 6.1 Delegated Service Accounts

```yaml
delegation:
  quotas:
    maxActiveTokens: 50
  serviceAccounts:
    - accountId: "svc-observer"
      tenant: "tenant-default"
      displayName: "Observability Exporter"
      allowedScopes: ["jobs:read", "findings:read"]
      authorizedClients: ["export-center-worker"]
```

**Token Shape:**
- Includes `stellaops:service_account` claim
- `act` claim describes caller hierarchy
- Quota enforcement per tenant/account

### 6.2 Fresh Auth Window (5 Minutes)

Required for high-privilege operations:
- Policy publish/promote
- Pack approvals
- Incident mode activation
- Operator actions

**Token must include:**
- `auth_time` within 5 minutes of request
- Interactive authentication (password/device-code)

### 6.3 ABAC Attributes (Vuln Explorer)

Tokens can carry attribute-based filters:
- `stellaops:vuln_env` - Environment filter
- `stellaops:vuln_owner` - Team/owner filter
- `stellaops:vuln_business_tier` - Criticality tier

---

## 7. Implementation Strategy

### 7.1 Phase 1: Core Token Infrastructure (Complete)

- [x] DPoP validation on all `/token` grants
- [x] mTLS binding for refresh grants
- [x] Sealed-mode CI gating
- [x] Pack signing policies and RBAC
- [x] LDAP plugin with claims enricher

### 7.2 Phase 2: Sovereign Crypto (In Progress)

- [ ] Crypto provider registry wiring (AUTH-CRYPTO-90-001)
- [ ] GOST signing support
- [ ] FIPS validation
- [ ] Post-quantum preparation

### 7.3 Phase 3: Advanced Features (Planned)

- [ ] DSSE predicate types for SBOM/Graph/VEX (AUTH-REACH-401-005)
- [ ] PostgreSQL storage migration
- [ ] Enhanced delegation quotas

---

## 8. API Surface

### 8.1 Token Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/token` | POST | Token issuance (all grant types) |
| `/introspect` | POST | Token introspection |
| `/revoke` | POST | Token/refresh revocation |
| `/.well-known/openid-configuration` | GET | OIDC discovery |
| `/jwks` | GET | JSON Web Key Set |

### 8.2 Supported Grant Types

- **Client Credentials** - Service-to-service (mTLS or private_key_jwt)
- **Device Code** - CLI on headless agents
- **Authorization Code + PKCE** - Browser UI login
- **Refresh Token** - With DPoP/mTLS re-validation

### 8.3 Admin APIs

All under `/admin` (mTLS + `authority.admin` scope):

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/admin/clients` | POST | Create/update client |
| `/admin/audiences` | POST | Register audience URIs |
| `/admin/roles` | POST | Define role→scope mappings |
| `/admin/tenants` | POST | Create tenant entries |
| `/admin/keys/rotate` | POST | Rotate signing key |

---

## 9. Revocation & JWKS

### 9.1 Revocation Bundles

Deterministic bundles for offline verification:

```
revocation-bundle.json
├── revokedTokens[]      # List of revoked jti values
├── revokedClients[]     # Revoked client IDs
├── generatedAt          # UTC timestamp
├── validUntil           # Expiry for offline cache
└── signature            # Detached JWS (RFC 7797)
```

### 9.2 JWKS Management

- At least 2 active keys during rotation
- Old keys retained for max TTL + 5 minutes
- Key status: `active`, `retired`, `revoked`

### 9.3 CLI Verification

```bash
# Export revocation bundle
stella auth revoke export --output revocation.json

# Verify bundle signature
stella auth revoke verify --bundle revocation.json --key pubkey.pem
```

---

## 10. Security Considerations

### 10.1 Threat Model Coverage

| Threat | Mitigation |
|--------|------------|
| Token theft | DPoP/mTLS sender constraints |
| Replay attacks | DPoP nonce challenges, short TTL |
| Token injection | Audience validation |
| Privilege escalation | Scope enforcement, role bundles |
| Cross-tenant access | Tenant claim isolation |

### 10.2 Operational Security

- Bootstrap API key protection
- Key rotation before expiration
- Rate limiting on `/token` endpoint
- Audit logging for all token operations

---

## 11. Observability

### 11.1 Metrics

- `authority_token_issued_total{grant_type,audience}`
- `authority_token_rejected_total{reason}`
- `authority_dpop_nonce_miss_total`
- `authority_mtls_mismatch_total`

### 11.2 Audit Events

- `authority.token.issued` - Token issuance
- `authority.token.rejected` - Rejection with reason
- `authority.tenant.switch` - Cross-tenant operation
- `authority.key.rotated` - Key rotation
- `authority.plugin.*.password_verification` - Plugin events

---

## 12. Related Documentation

| Resource | Location |
|----------|----------|
| Authority architecture | `docs/modules/authority/architecture.md` |
| Authority overview | `docs/11_AUTHORITY.md` |
| Scope reference | `docs/security/authority-scopes.md` |
| DPoP/mTLS rollout | `docs/security/dpop-mtls-rollout.md` |
| Threat model | `docs/security/authority-threat-model.md` |
| Revocation bundles | `docs/security/revocation-bundle.md` |
| Key rotation | `docs/modules/authority/operations/key-rotation.md` |
| Plugin guide | `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` |

---

## 13. Sprint Mapping

- **Historical:** SPRINT_100_identity_signing.md (CLOSED)
- **Documentation:** SPRINT_314_docs_modules_authority.md
- **PostgreSQL:** SPRINT_3401_0001_0001_postgres_authority.md
- **Crypto:** SPRINT_0514_0001_0001_sovereign_crypto_enablement.md

**Key Task IDs:**
- `AUTH-DPOP-11-001` - DPoP validation (DONE)
- `AUTH-MTLS-11-002` - mTLS binding (DONE)
- `AUTH-AIRGAP-57-001` - Sealed-mode CI gating (DONE)
- `AUTH-CRYPTO-90-001` - Sovereign crypto wiring (IN PROGRESS)
- `AUTH-REACH-401-005` - DSSE predicates (TODO)

---

## 14. Success Metrics

| Metric | Target |
|--------|--------|
| Token issuance latency | < 50ms p99 |
| DPoP validation rate | 100% on `/token` |
| Sender constraint coverage | 100% for high-value audiences |
| Key rotation downtime | Zero |
| Revocation bundle freshness | < 5 minutes |

---

*Last updated: 2025-11-29*