Skip to content

feat: Checksum verification gates for production migration applies #34

@Lazialize

Description

@Lazialize

Problem

The current checksum verification only detects mismatches in strata status and does not act as a gate (blocking mechanism) during strata apply. There is a risk of applying tampered migration files in production. Additionally, there is no mechanism to guarantee migration integrity across different environments.

Proposed Solution

Make checksum verification mandatory before migration application, blocking execution on mismatch.

Features

  1. Pre-apply checksum verification

    • When strata apply runs, compare the .meta.yaml checksum with the actual hash of up.sql / down.sql files for unapplied migrations
    • Block on mismatch (explicitly skippable with --skip-checksum-verify)
  2. Checksum lock file

    • Generate migrations/.checksum-lock.yaml containing checksums for all migrations
    • In CI/CD, run strata check --verify-checksums to verify consistency with the lock file
  3. Cross-environment integrity check

    • Add --verify flag to strata status to compare DB-recorded checksums with local files

Implementation Plan

  1. Checksum verification service (src/db/src/services/checksum_verifier.rs — new)

    pub struct ChecksumVerifier;
    
    impl ChecksumVerifier {
        /// Compute SHA-256 checksum of a file
        pub fn compute_checksum(path: &Path) -> Result<String>;
        
        /// Compare .meta.yaml checksum with actual file checksum
        pub fn verify_migration(migration_dir: &Path) -> Result<ChecksumVerifyResult>;
        
        /// Verify all migrations
        pub fn verify_all(migrations_dir: &Path) -> Result<Vec<ChecksumVerifyResult>>;
    }
  2. Changes to apply command (src/cli/src/cli/commands/apply.rs)

    • Call ChecksumVerifier::verify_all() before application
    • Display errors and block on mismatch
  3. Lock file generation (during strata generate)

    • Automatically update .checksum-lock.yaml when generating migrations
  4. Extend check command (src/cli/src/cli/commands/check.rs)

    • Add --verify-checksums flag for checksum verification

Files Affected

  • src/db/src/services/checksum_verifier.rs (new)
  • src/cli/src/cli/commands/apply.rs — Add verification gate
  • src/cli/src/cli/commands/generate.rs — Lock file generation
  • src/cli/src/cli/commands/check.rs — Add verification flag

Alternatives Considered

  • Git hooks: Verify checksums in pre-commit hooks. This creates a Git dependency, so built-in verification is more appropriate
  • DB-side verification only: Comparing DB-recorded checksums with files cannot detect tampering of unapplied migrations

Additional Context

  • Corresponds to "Add checksum verification gates for production applies" in ROADMAP.md
  • The existing sha2 crate enables SHA-256 computation
  • The existing .meta.yaml already has a checksum field

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions