Skip to main content
Proposed (STA-822). It implements 0188 decision 2 for AWS and the crypto-shredding of 0212.

​
Context

KeyProvider had only a memory driver, so the audit service opened subject keys from its own row and nothing served a tenant’s data keys from KMS. Erasing one person’s audit payloads needs a key per person that can be destroyed without touching the tenant’s other data.

​
Decision

  1. Wrapped keys per tenant. A tenant’s data keys are generated by KMS (GenerateDataKeyWithoutPlaintext, AES-256) and stored wrapped beside the tenant, oldest first (wrapTenantKey). AwsKmsKeyProviderDriver unwraps each once, keeps it in memory for the instance’s life, and serves the last as current. Managed or bring your own: the KMS key is the environment’s managed key or the tenant’s own key ARN granted to the runtime role. No credential is configured; the host passes the SDK’s KMS client, and @stackra/contracts takes no SDK dependency.
  2. Bound to the tenant. The encryption context is { "stackra:tenant", "stackra:key" }, so a wrapped key copied to another tenant or renamed fails to unwrap; the context holds ids only, since CloudTrail logs it. Deleting a tenant’s wrapped keys crypto-shreds its data.
  3. A key per subject. SubjectKeyProviderDriver derives a subject’s key with HKDF-SHA-256 from the tenant’s key, the subject’s own random salt (16 bytes or more, stored beside the subject) and the subject id. The derived key keeps the tenant key’s id, so rotation carries through. Destroying the salt makes that subject’s sealed fields unreadable while everyone else’s stay readable.

​
Consequences

  • Services seal per-tenant with AesGcmFieldCipherDriver over the KMS driver, and per-person data over the subject driver; the audit service drops its own key derivation.
  • Other clouds get their own drivers of the same port when a deployment needs them.

​
Enforcement

packages/foundation/contracts/src/core/drivers/__tests__/aws-kms-key-provider.driver.test.ts and packages/foundation/contracts/src/core/drivers/__tests__/subject-key-provider.driver.test.ts.

​
Supersedes and sources

Supersedes: none. Sources: OS services/audit/SPEC.md gap 3; STA-822.