FIN Central

ADR-001: AWS Secrets Manager — `/fin/central/*` subtree convention

2 min read

ADR-001: AWS Secrets Manager — /fin/central/* subtree convention

Status: accepted (2026-05-15) Date decided: 2026-05-15 Decided by: Rob Garcia, with Claude Code session 01

Context

Phase 1 §2 of the demarcation runbook required organizing AWS Secrets Manager secrets for the new FIN Central infrastructure. The runbook called for /fin/central/* and /fin/tenant/nathel/* subtree conventions but didn’t prescribe specific naming for the leaf keys.

Initial provisioning (early in the 2026-05-15 session) used flat naming:

fin/central_prod_neon_pooled
fin/central_prod_neon_unpooled
fin/central_staging_neon_pooled
fin/central_staging_neon_unpooled

This was inconsistent with the existing fin/nathel/fin-agentic/EMAIL_WEBHOOK_SIGNING_SECRET secret which already used the slash-subtree pattern.

Decision

Adopt the slash-subtree convention for all FIN secrets:

/fin/central/<env>/<key>      # Central infrastructure (env = prod | staging)
/fin/tenant/<tenant_id>/<key> # Tenant-scoped secrets
/fin/<top-level-key>          # Cross-cutting (e.g., neon_console API key)

Migrated 4 Central secrets to subtree form:

Old (flat)New (subtree)
fin/central_prod_neon_pooled/fin/central/prod/neon-pooled
fin/central_prod_neon_unpooled/fin/central/prod/neon-unpooled
fin/central_staging_neon_pooled/fin/central/staging/neon-pooled
fin/central_staging_neon_unpooled/fin/central/staging/neon-unpooled

Plus added /fin/central/prod/fin-app-password for the Hyperdrive credential.

Old flat-named secrets are scheduled for 30-day recovery deletion (reversible).

Consequences

Positive

  • AWS console grouping — secrets visually grouped by /fin/central/* prefix
  • IAM policy targeting — can grant secretsmanager:GetSecretValue on arn:...:secret:fin/central/* (single resource glob covers all Central secrets)
  • Symmetric with existing Nathel pattern — /fin/nathel/* already in use
  • Discoverable — aws secretsmanager list-secrets --filters Key=name,Values=fin/central lists all Central secrets in one call

Negative

  • One-time migration cost — required updating references in the operator handoff doc + AWS SM secret references in shell snippets

Neutral

  • AWS SM doesn’t support rename — migration was create-new + 30-day-recovery-delete-old. Old names recoverable until 2026-06-14 if needed.

Implementation

Done 2026-05-15. Verified all 4 new secrets exist via:

aws secretsmanager list-secrets --filters Key=name,Values=fin/central \
  --query 'SecretList[].Name' --output text

Graph View