# ADR 0006: Security and Key Management Baseline

- Status: Accepted
- Date: 2026-03-11
- Owners: Security Team, Architecture Group
- Related:
  - `docs/adr/0001-app-boundaries.md`
  - `docs/adr/0005-api-error-and-idempotency-response-contract.md`
  - `docs/non-functional-slo.md`
  - `docs/phase-tracker.md`

## Context
The wallet platform handles sensitive identity and financial operations. Security controls must be consistent across apps mode domains and enforceable before major money movement features are exposed.

This ADR defines the minimum security baseline for authentication, token lifecycle, secrets management, key rotation, encryption, and audit controls.

## Decision
Adopt a default-deny, short-lived credential, and externalized secret-management model.

Core decisions:
1. Access tokens are short-lived and signed with rotating asymmetric keys.
2. Refresh tokens are opaque, revocable, and rotated on use.
3. Secrets are never stored in source control or static config files.
4. Cryptographic keys are managed externally (Vault/HSM integration boundary).
5. Sensitive data is encrypted at rest and protected in transit.

## Authentication and Session Baseline
Requirements:
- OAuth2/JWT-compatible access tokens with strict claim validation.
- Access token TTL: 5-15 minutes (environment policy).
- Refresh token TTL: environment policy, revocation-capable.
- Refresh token rotation required (one-time-use semantics).
- Device/session binding where applicable.
- OTP/MFA required for high-risk operations.

Required claims validation:
- `iss`, `aud`, `sub`, `exp`, `iat`, `jti`
- optional domain claims: `tenant_id`, `roles`, `scopes`

## Signing Keys and Rotation
Key policy:
- Use asymmetric signing (`RS256` or stronger organization-approved equivalent).
- Keys identified by `kid` and published via internal JWKS endpoint for verifiers.
- Rotation cadence:
  - scheduled rotation at fixed policy interval
  - emergency rotation procedure for key compromise
- Minimum overlap window during rotation to allow token validation continuity.

Operational rules:
1. New keys introduced before old keys are retired.
2. Old signing keys disabled only after overlap window.
3. Key lifecycle events audited.

## Secrets Management Baseline
Rules:
- All production secrets sourced from secret manager (Azure Vault/HashiCorp Vault equivalent).
- No plaintext secrets in repository, release artifacts, or logs.
- Principle of least privilege for secret access per OTP app.
- Runtime fetch and refresh where supported; startup fail-fast if critical secrets unavailable.

Scope examples:
- DB credentials
- JWT signing keys references
- external provider credentials
- encryption keys

## Data Protection Baseline
In transit:
- TLS 1.2+ for all external and internal service communications where applicable.
- Mutual TLS for sensitive internal integrations as policy requires.

At rest:
- Encrypt PII and sensitive fields using approved crypto primitives.
- Apply field-level encryption for high-sensitivity data.
- Store only minimum required PII.

Redaction:
- Structured logs must redact tokens, secrets, and sensitive payload fields.

## Authorization Baseline
- RBAC required for admin and internal operations.
- Scope-based authorization for API endpoints.
- Explicit permission checks in command handlers for privileged actions.

## Abuse and Edge Security Controls
- Rate limiting and burst controls at gateway and app edge.
- Login and OTP anti-bruteforce controls.
- Account/device lockout policy with risk-based challenge escalation.
- IP/device anomaly hooks integrated with `wallet_risk`.

## Audit and Compliance Controls
Mandatory audit events:
- auth success/failure
- token issued/refreshed/revoked
- key rotation and secret access failures
- privileged action attempts

Audit event requirements:
- `request_id`, `correlation_id`, actor, action, target, outcome, timestamp.
- immutable audit stream and retention policy compliance.

## Incident and Compromise Handling
Must define and test:
1. key compromise emergency rotation playbook
2. refresh token revocation blast strategy
3. credential leak response and secret rollover runbook
4. forensic log capture and timeline reconstruction

## Test and Verification Requirements
1. Token validation tests for valid/invalid/expired/not-before/audience mismatch.
2. Refresh token rotation tests including replay rejection.
3. Secret injection tests for all environments.
4. Redaction tests ensuring no secret leakage in logs.
5. Pen-test/security test gate prior to production.

## Consequences
Positive:
- Strong baseline for regulated wallet workloads.
- Reduced credential abuse and key compromise blast radius.
- Better audit readiness for compliance reviews.

Trade-offs:
- Additional operational complexity around rotation and secret lifecycle.
- More strict rollout requirements for auth-dependent services.

## Acceptance Criteria
1. Access and refresh token lifecycle controls implemented and tested.
2. Key rotation mechanism (scheduled + emergency) documented and exercised in non-prod.
3. Secret manager integration active for all critical secrets.
4. Required security audit events emitted and queryable.
5. Phase 2 security gate passes with evidence.