ADR-0004: Use Tenant-Level Encryption Keys

Date: 2026-06-06

Status: Accepted

Context

Eco Manager stores sensitive operational data such as passwords, API keys, PINs, private keys, and other values needed for BMS and remote operations work. A single global encryption key would create an unacceptable blast radius: compromise of one key could expose every tenant or customer.

The product should ensure that encrypted values belonging to one tenant, customer, organisation, or root entity cannot be decrypted by another tenant.

Decision

Eco Manager will use tenant/root-entity-level encryption boundaries. Encrypted Vault values and sensitive properties will reference the root entity that owns them and the tenant key version used to protect them.

The preferred model is envelope encryption:

Tenant Root Key / KEK
    wraps Data Encryption Keys / DEKs
        encrypt individual secret versions or sensitive property values

For Alpha, implementation may use a pragmatic local key provider suitable for development and controlled testing. The design must allow future migration to an external KMS, HSM, cloud KMS, or customer-managed-key model.

Consequences

Positive

• Smaller cryptographic blast radius.
• Clear tenant/customer encryption boundaries.
• Key rotation can be performed per tenant/root.
• The Vault can support stronger enterprise and customer-managed-key options later.

Trade-offs

• More key metadata must be stored and maintained.
• Secret reveal/copy operations must verify both authorization scope and key availability.
• Operational tooling is needed for key rotation, retirement, and recovery.