Skip to content

Last reviewed: 2026-07-28 Accepted decision: - ../../decisions/accepted/0030-sensitive-company-data-key-recovery-and-backup-protection.md - ../../decisions/accepted/0031-company-scoped-postgresql-backup-and-atomic-restore.md

Contract: Backup security

Purpose

This contract defines minimum security behavior for BooksPlus backups and restores.

Contract

Backups must preserve recoverability without creating uncontrolled exposure of company data.

Rules

  • Backup creation must be auditable.
  • Backup export must require authorization.
  • Backup validation must require authorization.
  • Backup restore must require authorization.
  • Backup restore must create an audit event.
  • Backups must be encrypted or otherwise protected.
  • Restore procedures must be documented and periodically testable.
  • A supported backup is one versioned authenticated encrypted container covering a consistent PostgreSQL snapshot, managed evidence artifacts, company key envelope, and exact manifest.
  • The backup key is random and wrapped by customer-held recovery material that is not stored inside the backup.
  • Backup creation must not leave plaintext database dumps or evidence artifacts in ordinary temporary storage.
  • Restore validates format, manifest, schema compatibility, key envelope, and every component before replacing current company state.
  • Failed validation leaves current company state unchanged.
  • Backup and restore use the versioned Company Backup Snapshot contract.
  • Whole-database replacement is not a supported company restore.
  • Restore preserves the backup company UUID, changes no other company, and never remaps, clones, or merges company identity.
  • Capture uses one repeatable-read snapshot across relational state, managed evidence, and the company key envelope.
  • Restore validates the complete logical snapshot in isolation before one atomic company-replacement transaction.
  • The recovery secret must authenticate both the backup container and the captured company key envelope before mutation.
  • Company-scoped audit events merge append-only; current audit evidence is not rolled back with replaceable company state.
  • The initial supported restore requires exact application-schema and snapshot-catalog versions.
  • When sales-tax persistence is implemented, a supported company backup must include the complete company-owned sales-tax control aggregate and Finance remittance matches defined by the Sales Tax Accounting and Remittance Contract. Tax-provider credentials, bank credentials, payment credentials, and authentication material remain excluded from ordinary control rows and audit payloads.

Protected actions:

  • backup.create
  • backup.export
  • backup.validate
  • backup.restore

Creation, export, validation, and restore emit value-free audit events. Restore requires a reason and step-up confirmation. Backup audit evidence must not contain recovery material, plaintext components, encrypted component bytes, authentication values, or component digests.

Acceptance criteria

  • An authorized user can create a backup.
  • Unauthorized users cannot export or restore backups.
  • Backup export creates an audit event.
  • Backup restore creates an audit event.
  • Backup files are protected from casual inspection.
  • A complete restore recovers database records and managed evidence together.
  • A successful restore changes only the selected company.
  • A missing or conflicting shared definition blocks restore before mutation.
  • A restored missing actor cannot receive access without a later protected rebind and enable action.
  • Captured actor-role assignments require explicit protected review and are never activated merely because a backup was restored.
  • Audit events created after the backup remain present after restore.
  • A backup without the recovery secret cannot expose usable company data.
  • Support bundles do not contain backup recovery material or sensitive artifact plaintext.