true the date

2025-11-30 19:23:21 +02:00
parent 71e9a56cfd
commit 0bef705bcc
14 changed files with 0 additions and 0 deletions
--- a/docs/product-advisories/28-Nov-2025
+++ b/docs/product-advisories/28-Nov-2025
@@ -0,0 +1,408 @@
+# 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*