Saltar a contenido

ADR-0010 · Secretos y KMS: Secrets Manager + CMK por tenant + rotación automática

  • Status: Accepted
  • Date: 2026-04-30
  • Deciders: Cristian Fernández (Zerviz Group)
  • Related: ADR-0002 (tenancy), ADR-0005 (auth), CLAUDE.md rule (Secrets Manager only).

Context

CLAUDE.md exige Secrets Manager exclusivo. El legacy viola la regla con env vars en claro (R-01, archivado pero recordatorio). Ambiente nuevo arranca limpio.

Decision

Naming convention

/ze/{env}/{scope}/{name}
  • scope = platform para secretos transversales (admin tokens internos, OIDC IdP secrets, OpenAI key compartida en dev).
  • scope = tenant/{tenant_id} para secretos per-tenant (CMK alias, conector secrets).
  • scope = connector/{tenant_id}/{connector_id} para credenciales específicas de un conector.
  • scope = webhook-secrets/{provider} para secret rotativo de Lambda Authorizer (ADR-0005).

Ejemplos: - /ze/prod/tenant/IPLACEX-demo/cmk-alias → alias/ze-prod-tenant-iplacex-demo. - /ze/prod/connector/iplacex-demo/whatsapp-meta-cloud → access token Meta del tenant. - /ze/prod/webhook-secrets/meta → secret HMAC para validar firma + nonce.

Rotación

  • Secrets de proveedor (Meta, 360, Five9, OpenAI): rotación manual por owner (no hay rotación automática del lado del proveedor para todos). Recordatorio cada 90 días vía EventBridge Scheduler → SNS owner.
  • Webhook authorizer secrets: rotación automática cada 30 días vía Lambda rotator (Secrets Manager native rotation). Lambda rotator publica SecretRotated event para invalidar caches.
  • DB credentials (RDS): rotación automática cada 30 días con Secrets Manager rotación nativa para Postgres. Strategy: single user (no multi-user, simplifica).
  • JWT signing keys (Cognito): managed por Cognito (no acción nuestra).

Access control

  • IAM policy granular: cada Lambda lee sólo los secretos de su scope.
  • Tier lógico: Lambda lee /ze/{env}/connector/{tenant_id}/* filtrando por tenant_id desde JWT/event (no por wildcard).
  • Tier físico: secretos viven en la cuenta del tenant; cross-account access prohibido.

KMS

  • CMK por tenant: alias/ze-{env}-tenant-<id>. Rotación anual automática (KMS native).
  • CMK plataforma: alias/ze-{env}-platform. Para secretos scope=platform y datos de control plane.
  • CMK observability: alias/ze-{env}-observability para CloudWatch Logs encryption + Firehose audit.
  • Key policy estricta: principal = roles de servicios específicos; deny kms:ScheduleKeyDeletion salvo break-glass role.

Cache + invalidación

  • packages/secrets-resolver wrapper:
  • Cache in-memory por handler (TTL 5 min).
  • Listener EventBridge SecretRotated invalida cache.
  • SDK v3 client con XRay subsegment.

Auditoría

  • CloudTrail data events activos en secretsmanager:GetSecretValue y kms:Decrypt.
  • Retención 7 años (S3 Object Lock compliance) → cumple ISO + Ley 19.628 forward.

Consequences

Positive

  • Cero secretos en env vars; cero secretos en código.
  • Rotación automática reduce ventana de exposición.
  • Per-tenant CMK habilita "BYOK ready" futuro (cliente puede traer su propia CMK).

Negative

  • GetSecretValue agrega latencia (mitigado con cache).
  • Rotación automática rompe Lambdas si no implementan invalidación. packages/secrets-resolver lo resuelve.

Alternatives considered

  • SSM Parameter Store: OK para feature flags y CB state, pero no para secretos sensibles (sin rotación nativa).
  • HashiCorp Vault: rechazado, agrega ops sin justificación clara vs Secrets Manager.

Tenant-isolation impact

  • IAM con condition secretsmanager:VersionStage=AWSCURRENT + path /ze/{env}/connector/${aws:PrincipalTag/tenant_id}/*.
  • Tier físico: aislamiento por cuenta.

Blast radius

  • Secret comprometido ⇒ rotación + revocación inmediata. Window ≤ 5 min con cache invalidation.

Cost note

  • Secrets Manager: USD 0.40 por secreto/mes + USD 0.05 por 10k API calls. Estimado prod < USD 50/mes.
  • KMS CMK: USD 1/mes/key + USD 0.03 por 10k requests. CMK por tenant ⇒ escala con N tenants. Tier físico paga sus propios CMK.

ISO 27001 controls touched

  • A.10.1.1, A.10.1.2 (criptografía + key management).
  • A.9.2.4 (gestión de información secreta de autenticación).
  • A.12.4.3 (logs de admin/operator) — CloudTrail data events.
  • A.18.1.5 (regulación de controles criptográficos).

Sources

  • CLAUDE.md (Secrets Manager only).
  • docs/discovery/00-phase1-prerequisites.md Anexo A-02 (CMK per tenant).
  • ADRs 0002, 0005, 0007.