Secrets y configuración runtime

AWS Secrets Manager

Convención de naming: /zen/{env}/{categoria}/{recurso}. Todos los secrets viven en us-east-2 con kms_key_id = alias/zen-{env}-platform.

Conectores outbound

Secret name	Strategy	Schema
/zen/dev/connectors/whatsapp-meta-cloud/{phoneNumberId}	whatsapp-meta-cloud	{ accessToken, businessAccountId, phoneNumberId, appSecret }
/zen/dev/connectors/360dialog/{tenantId}	whatsapp-360dialog	{ apiKey }
/zen/dev/connectors/email-ses/{tenantId}	email-ses	{ fromAddress, configurationSet?, replyToAddresses? }
/zen/dev/connectors/sms-sns/{tenantId}	sms-sns	{ senderId?, smsType? } (defaults: senderId="Zerviz", smsType="Transactional")
/zen/dev/connectors/amazon-connect/{tenantId}	amazon-connect	{ instanceId, contactFlowId, queueId? }

Webhook secrets (inbound)

Secret name	Provider	Uso
/zen/dev/webhook-secrets/whatsapp-meta-cloud	Meta WABA	HMAC SHA256 sobre X-Hub-Signature-256
/zen/dev/webhook-secrets/whatsapp-360dialog	360dialog	HMAC SHA256 sobre X-Hub-Signature-256

Contact center

Secret name	Strategy
/zen/dev/connectors/five9-digital/{tenantId}	five9-digital
/zen/dev/connectors/amazon-connect/{tenantId}	amazon-connect

Cómo agregar un secret nuevo

1. Declarar en Terraform: agregar a infra/envs/dev/secrets.tf o el archivo del módulo correspondiente (p.ej. connectors_v11.tf):

resource "aws_secretsmanager_secret" "mi_secret" {
  name        = "/zen/${local.env}/connectors/mi-provider/example"
  description = "Credentials para Mi Provider"
  kms_key_id  = aws_kms_key.platform.arn

  lifecycle {
    ignore_changes = [secret_string]
  }
}

1. Permitir lectura desde el rol que lo consume (extra_iam_statements del módulo lambda-service):

extra_iam_statements = [
  {
    sid       = "ReadMiSecret"
    effect    = "Allow"
    actions   = ["secretsmanager:GetSecretValue"]
    resources = [aws_secretsmanager_secret.mi_secret.arn]
  }
]

1. Poblar el valor (manualmente, una sola vez):

aws secretsmanager put-secret-value \
  --region us-east-2 \
  --secret-id /zen/dev/connectors/mi-provider/example \
  --secret-string '{"apiKey":"..."}'

lifecycle.ignore_changes = [secret_string] evita que Terraform sobreescriba el valor en cada apply.

Variables de entorno por Lambda

Convención: nombres SCREAMING_SNAKE_CASE, prefijos por concepto:

Prefijo	Ejemplo	Significado
DDB_*	DDB_TENANTS_TABLE	Nombre de tabla DDB
S3_*	S3_FLOWS_BUCKET	Nombre de bucket S3
EVENT_BUS_NAME	zen-dev-domain-events	Bus EventBridge
*_SECRET_PREFIX	WEBHOOK_SECRET_PREFIX	Prefijo en Secrets Manager
POWERTOOLS_*	POWERTOOLS_SERVICE_NAME	AWS Lambda Powertools
ENV	dev	Ambiente

Ver infra/modules/lambda-service/main.tf para el bloque environment.variables por servicio.

Config runtime de SPAs

Cada SPA carga su config desde /config.js que se sube por separado al bucket S3 (no en el bundle build). Esto permite mismo bundle en dev/qa/prod.

• Admin SPA (apps/builder-spa): window.__ADMIN_CONFIG__ (ver developers/auth-cognito-pkce.md).
• Auth SPA (legacy-references/ze-login copia): window.__LOGIN_CONFIG__.
• Widget (apps/widget-spa): no usa /config.js — recibe config inline en Zengine.init({...}) (integrators/embed-widget.md).

¿Algún secreto en el código?

No. Ningún secret jamás se commitea. Para inyectar valores en tests:

• Unit tests: mocks via aws-sdk-client-mock o DI manual.
• Integration tests (LocalStack): AWS_ACCESS_KEY_ID=test literal (LocalStack ignora valor).
• Dev local: variables de entorno en shell, jamás .env committed.

Ver .gitignore y .checkov.yaml para reglas de scanning. git-secrets en pre-commit hook (TODO V1.1.x).