Secrets Architecture & Storage

NordStern enforces a strict rule: secrets must never be stored in plaintext in the database or hardcoded in configuration files.

Reference vs. Value Storage Model

Secrets are split into:

• References (Stored in DB): The database stores pointers or ARN paths (Amazon Resource Names). For example, a database row might specify:

  {
    "payout_provider": "cashfree",
    "payout_credentials_ref": "nordstern/testnet/anchor/mizupay/payout_keys"
  }

• Values (Stored in Vault): The actual sensitive API keys and signing credentials live inside an external vault.

┌──────────────┐
│ Platform DB  │ ──► Reads Secret Reference (ARN)
└──────────────┘
       │
       ▼
┌──────────────┐
│ Business Srv │ ──► Requests Value from SecretStore
└──────────────┘
       │
       ▼
┌──────────────┐
│ Secret Vault │ ──► Returns Value to memory only (never written to disk)
└──────────────┘

At runtime, when the Business Server needs to perform an operation (like triggering a payout), it queries the SecretStore client to fetch the value from the vault directly into volatile memory.

Dev vs. Production Parity

• Development (LocalStack): In development, LocalStack replicates AWS Secrets Manager locally on port 4566.
• Production (AWS Secrets Manager): In production, the environment variable SECRETS_ENDPOINT is omitted. The SDK automatically resolves to the real AWS Secrets Manager endpoint, resolving permissions using AWS IAM Role Service Accounts (IRSA) on the EKS cluster.

Encryption of Stellar Keys

The Stellar issuer, distribution, and signing seeds (S...) are handled directly by the Control Plane.

• Seeds are encrypted with AES-256-GCM using a master key (MASTER_KEK) before being saved to Postgres.
• This provides double-envelope security: database encryption protects the keys, and vault storage protects the API credentials.

Traceability Links

• AWS secrets manager client: platform/api/src/lib/secrets/secretsManager.ts
• Secret store interfaces: platform/api/src/lib/secrets/index.ts
• Keys encryptor: anchor-service/control-plane/src/vault.ts