Skip to content

ADR 0030: Sensitive Company Data, Key Recovery, and Backup Protection

Context

BooksPlus must retain full taxpayer identifiers and sensitive W-9 evidence for information-return filing. Ordinary PostgreSQL access control, an application configuration secret, or an operating-system disk-encryption assumption does not satisfy ADRs 0013, 0025, and 0027. The launch design also needs customer- controlled recovery and a backup that does not expose the rest of the company database or managed evidence artifacts.

Decision

BooksPlus uses application-layer envelope encryption for sensitive fields and managed sensitive artifacts.

Each company has a random 256-bit company key-encryption key. Each protected payload has its own random 256-bit data-encryption key. AES-256-GCM encrypts both payloads and wrapped keys with a fresh 96-bit nonce and authenticated context containing company id, owning object identity, payload purpose, and envelope version. Ciphertext, nonce, authentication tag, wrapped data key, key version, and algorithm identity are stored; plaintext and unwrapped keys are not.

The company key is stored only as an authenticated envelope wrapped by a separate random 256-bit recovery secret. BooksPlus derives the recovery wrapping key with PBKDF2-HMAC-SHA-256, a fresh minimum 128-bit salt, 200,000 iterations, and a 256-bit result. The high-entropy recovery secret is encoded for display with unpadded Base64url. The recovery secret:

  • is shown to an authorized customer once at company-protection setup;
  • is not stored in PostgreSQL, managed evidence storage, logs, audit events, telemetry, support bundles, or backups;
  • may be cached only by an accepted operating-system credential-store adapter;
  • may otherwise be supplied by the authorized user when the company is unlocked; and
  • has no insecure plaintext-file fallback.

The unwrapped company key exists only in process memory for the shortest practical unlocked session. Key material is cleared on lock and best-effort zeroed after use. Loss of both the recovery secret and every authorized credential-store copy makes protected data unrecoverable; BooksPlus must make that consequence explicit before setup.

Company-protection initialization and recovery-secret unlock are distinct protected actions. Both require a reason and step-up confirmation and emit value-free audit events. Automatic session lock and key clearing do not require authorization.

Protected taxpayer identifiers

Full taxpayer identifiers are stored only as encrypted payload envelopes separate from ordinary payee and payer profile snapshots. The ordinary profile retains only identifier type, permitted masked display, validation state, key version, and protected-payload identity.

Maintenance, full-value viewing, and sensitive export remain distinct protected actions. A successful or failed full-value view emits an audit event without the value, masked value, ciphertext, key material, or evidence contents. Ordinary queries never decrypt the value.

Full-value viewing and sensitive export require a reason and step-up confirmation. Maintenance uses its distinct protected action and ordinary company-scoped authorization; a later credential-store convenience must not bypass either action.

Sensitive Source Document artifacts

Source Documents continue to own W-9 and classification evidence identity. Sensitive artifact bytes live in a BooksPlus-managed evidence store under an opaque generated storage identity, never a user-supplied filename or path. PostgreSQL retains company-scoped artifact metadata, owning Source Document, content type, byte length, cryptographic integrity values, envelope identity, and supersession history.

Artifact bytes are encrypted before durable storage. Reads verify company, Source Document, authorization, authenticated context, and ciphertext integrity before returning plaintext. Support bundles and routine exports omit sensitive artifacts. Replacement creates a new Source Document or artifact identity and preserves the prior ciphertext; it does not overwrite it.

Backup and restore

A supported backup is one versioned authenticated encrypted container that coordinates:

  • a consistent PostgreSQL snapshot;
  • managed evidence artifacts;
  • the company key envelope and envelope metadata;
  • a manifest of exact component identities, lengths, and cryptographic digests; and
  • backup format and application-schema versions.

The whole container is encrypted with a fresh random backup key wrapped by the customer recovery secret. The recovery secret is not inside the container. Backup creation, export, validation, and restore use protected actions and value-free audit events. Restore validates the container, manifest, schema compatibility, key envelope, and every component before replacing company state. A failed validation leaves current company state unchanged.

Implementations must not leave plaintext database dumps, evidence artifacts, taxpayer identifiers, or backup payloads in ordinary temporary storage.

Validation and failure behavior

  • No API accepts a caller-supplied nonce, tag, wrapped key, algorithm, or authenticated context for a new protected payload.
  • Envelope identity and authenticated context are immutable.
  • Exact replay returns the existing protected record; changed plaintext under the same logical write identity is a conflict.
  • Decryption failure returns a generic protected-data integrity error and never exposes which byte, key, or taxpayer-identifier part differed.
  • Cross-company key, envelope, profile, Source Document, artifact, backup, and restore references are rejected.
  • Masked support totals remain available without decrypting full TINs.
  • Filing approval and sensitive export require the necessary protected values to be present and decryptable.

Key rotation

Envelope records carry key version. A company-key rotation rewraps protected data keys under a new company key without changing payload ciphertext or business identity. Rotation is atomic and audited. Retirement of an old key is allowed only after all active envelopes and retained backup policy are reconciled. Automated rotation scheduling is deferred.

Consequences

  • Full TIN and W-9 retention can proceed without placing plaintext in ordinary profile snapshots, database columns, logs, or managed files.
  • Customer recovery control does not depend on a vendor-held secret.
  • The backup container can protect otherwise ordinary company records as well as already encrypted sensitive payloads.
  • Platform credential stores are convenience adapters, not the only recovery path or a substitute for customer-held recovery material.
  • Backup orchestration and platform credential-store adapters remain separate infrastructure concerns behind stable security contracts.
  • 0013-encrypted-company-data.md
  • 0014-append-only-security-audit-events.md
  • 0025-contractor-classification-and-information-return-filing.md
  • 0027-managed-local-postgresql-launch-deployment.md
  • 0031-company-scoped-postgresql-backup-and-atomic-restore.md
  • ../../contracts/contractor-and-information-return-filing.contract.md
  • ../../contracts/source-document.contract.md
  • ../../contracts/security/company-data-encryption-contract.md
  • ../../contracts/security/backup-security-contract.md