Skip to main content

Documentation Index

Fetch the complete documentation index at: https://woku.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

Todas las credenciales sensibles de Woku (cadenas de conexión a base de datos, claves JWT, API keys de terceros, tokens de Stytch SSO, etc.) se almacenan en AWS SSM Parameter Store como SecureString y se inyectan al container en producción al momento de arrancar.

​
Modelo

  • Almacenamiento: AWS SSM Parameter Store, región us-east-1, bajo el prefijo /shared/prod/secrets/. Tipo SecureString (cifrado con KMS, llave alias/aws/ssm).
  • Inyección: AWS Copilot lee cada parámetro y lo entrega al container como variable de entorno (process.env) al iniciar la tarea ECS. Sucede automáticamente vía el bloque secrets: del manifest de la aplicación.
  • Permisos: el rol de ejecución de la tarea ECS tiene una policy acotada a ssm:GetParameters + kms:Decrypt solo sobre el prefijo /shared/prod/secrets/*. No puede leer otros parámetros de la cuenta.

​
Auditabilidad

  • Cada lectura de un parámetro queda en AWS CloudTrail.
  • Cada cambio (PutParameter, DeleteParameter) queda en CloudTrail también, con identidad IAM del autor.
  • KMS registra las operaciones Decrypt por separado en CloudTrail (data events si están habilitados).

​
¿Por qué no AWS Secrets Manager?

SSM Parameter Store SecureString ofrece el mismo cifrado KMS que Secrets Manager y la misma garantía de aislamiento. La diferencia principal es la rotación automática integrada (RDS / DocumentDB / Lambda), que actualmente no necesitamos. La elección de SSM nos ahorra el costo per-secret de Secrets Manager (~$0.40/mes c/u) manteniendo las garantías de cifrado y auditoría.

​
Lo que NO se hace

  • ❌ Nunca commiteamos secrets al repositorio. Hay un .dockerignore que excluye .env y .env.* de la imagen Docker; los archivos locales jamás llegan a producción.
  • ❌ Nunca pasamos secrets como argumentos en CI/CLI inline. Quedan en el shell history y en logs de CI. Se exportan al entorno antes de ejecutar el comando que los necesita.
  • ❌ Nunca se ponen secrets en variables: del manifest (esa sección está en texto plano dentro del CloudFormation stack).

​
Entornos

EntornoOrigen de secrets
ProducciónSSM Parameter Store, leído por Copilot al arrancar el container. Esta es la fuente de verdad.
Local devArchivo .env en woku-server/ (cada desarrollador tiene el suyo).
Estado actual: algunas instalaciones locales tienen valores de producción mezclados con sandbox dentro de su .env. El objetivo es que el .env local contenga solo valores de dev/sandbox (Mongo local, Stytch sandbox project, Paddle sandbox, etc.) y que cualquier conexión a recursos productivos pase exclusivamente por SSM al levantar el container en AWS.
Si necesitas un secret nuevo en producción, sigue el procedimiento.

​
Agregar un secret nuevo

  1. Subir el valor a SSM. Exporta el valor en tu shell y usa el helper que vive en el repo: 
    export MI_SECRET_NUEVO="..."
./scripts/upload-secrets-to-ssm.sh
    El script sube cada variable que esté exportada a /shared/prod/secrets/<NOMBRE> como SecureString. Skipea silenciosamente las que no estén seteadas.
  2. Referenciarlo desde el manifest en copilot/woku-server/manifest.yml: 
    secrets:
  MI_SECRET_NUEVO: /shared/prod/secrets/MI_SECRET_NUEVO
  3. Deploy. Próximo copilot deploy levanta el container con la variable disponible en process.env.MI_SECRET_NUEVO.

​
Rotar un secret

Para credenciales sin rotación automática (todo lo que tenemos hoy):
  1. Genera el nuevo valor en el proveedor (ej: nuevo STYTCH_SECRET en el dashboard de Stytch).
  2. aws ssm put-parameter --overwrite --type SecureString ... (el helper script ya lo hace).
  3. Force-redeploy del servicio para que tome el valor nuevo: copilot svc deploy --name woku-server.
  4. Revoca el valor anterior en el proveedor.
El container no detecta cambios en SSM en vivo. Los valores se leen una sola vez al arrancar. Por eso siempre hay que redeployar después de rotar.

​
Reportar un leak

Si descubres un secret expuesto (en un repo público, en logs, en un PR, en un screenshot), envía el detalle a team@woku.app. El proceso de respuesta:
  1. Rotación inmediata del valor comprometido.
  2. Investigación de uso del valor anterior en CloudTrail.
  3. Notificación al cliente si la rotación afecta sus integraciones.
El SLA por defecto es 4 horas hábiles, o lo que pacte tu contrato Corporate si exige un tiempo menor.