Add integrity verification command

- Introduced `git pkgs integrity` command to show and verify lockfile integrity hashes.
- Added `--drift` flag to detect packages with different hashes for the same version.
- Updated `ecosystems-bibliothecary` to ~> 15.3 and `purl` to >= 1.7.1
- Enhanced `dependency_snapshots` table to store integrity hashes (schema v4).
- Updated documentation to include integrity verification details.
- Modified various components to support integrity tracking and reporting.
- Added tests for integrity command and lockfile integrity extraction.

Author: andrew

CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+- `git pkgs integrity` command to show and verify lockfile integrity hashes
+- `--drift` flag to detect packages with different hashes for the same version
+- Registry integrity comparison via ecosyste.ms API
+- Store integrity hashes from lockfiles in dependency_snapshots table (schema v4, run `git pkgs upgrade`)
+- Update ecosystems-bibliothecary to ~> 15.3 (integrity extraction from lockfiles)
+- Update purl to >= 1.7.1 (ecosyste.ms API URL support)
+
 ## [0.8.0] - 2026-01-14
 
 - `git pkgs outdated` command to find dependencies with newer versions available in registries

Gemfile.lock

@@ -8,8 +8,8 @@ PATH
   remote: .
   specs:
     git-pkgs (0.8.0)
-      ecosystems-bibliothecary (~> 15.2)
-      purl (~> 1.7)
+      ecosystems-bibliothecary (~> 15.3)
+      purl (~> 1.7, >= 1.7.1)
       rugged (~> 1.0)
       sarif-ruby
       sequel (>= 5.0)
@@ -29,7 +29,7 @@ GEM
     csv (3.3.5)
     date (3.5.1)
     docile (1.4.1)
-    ecosystems-bibliothecary (15.2.0)
+    ecosystems-bibliothecary (15.3.0)
       bundler
       csv
       json (~> 2.8)
@@ -58,16 +58,16 @@ GEM
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.7.0)
+    prism (1.8.0)
     psych (5.3.1)
       date
       stringio
     public_suffix (7.0.2)
-    purl (1.7.0)
+    purl (1.7.1)
       addressable (~> 2.8)
     racc (1.8.1)
     rake (13.3.1)
-    rdoc (7.0.3)
+    rdoc (7.1.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -98,7 +98,7 @@ GEM
     stringio (3.2.0)
     tomlrb (2.0.4)
     tsort (0.2.0)
-    vers (1.0.2)
+    vers (1.0.3)
     webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -136,7 +136,7 @@ CHECKSUMS
   csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  ecosystems-bibliothecary (15.2.0) sha256=bef81a0175f8bdf1d61938d5d5d32e226ec4ff44a54d5d5d34faea663ed67a24
+  ecosystems-bibliothecary (15.3.0) sha256=dc3c8caa3218bf833beba9e3eb8cbeb35987f771532ff0eab87fbcdfb30ce4eb
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   git-pkgs (0.8.0)
   hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
@@ -150,13 +150,13 @@ CHECKSUMS
   ox (2.14.23) sha256=4a9aedb4d6c78c5ebac1d7287dc7cc6808e14a8831d7adb727438f6a1b461b66
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
-  prism (1.7.0) sha256=10062f734bf7985c8424c44fac382ac04a58124ea3d220ec3ba9fe4f2da65103
+  prism (1.8.0) sha256=84453a16ef5530ea62c5f03ec16b52a459575ad4e7b9c2b360fd8ce2c39c1254
   psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
   public_suffix (7.0.2) sha256=9114090c8e4e7135c1fd0e7acfea33afaab38101884320c65aaa0ffb8e26a857
-  purl (1.7.0) sha256=e25a6b951975e94104a17d8d40e8529fa882a5a63717c68af2390e9b8d0ac3f2
+  purl (1.7.1) sha256=459aecf3e0e2199bdfafa2885731b39af7c081dcd1d63d7ec036aab732e56ed3
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
-  rdoc (7.0.3) sha256=dfe3d0981d19b7bba71d9dbaeb57c9f4e3a7a4103162148a559c4fc687ea81f9
+  rdoc (7.1.0) sha256=494899df0706c178596ca6e1d50f1b7eb285a9b2aae715be5abd742734f17363
   regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
@@ -180,7 +180,7 @@ CHECKSUMS
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   tomlrb (2.0.4) sha256=262f77947ac3ac9b3366a0a5940ecd238300c553e2e14f22009e2afcd2181b99
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
-  vers (1.0.2) sha256=0ea9a63acbe1f197268c7da93f0708a4fc99bd88d86aa49dccf5b1b8d4c68de5
+  vers (1.0.3) sha256=d1ef5b0f146a23515ab94b0a6d7ad7338494f90af358857da83a7d8a9921bc89
   webmock (3.26.1) sha256=4f696fb57c90a827c20aadb2d4f9058bbff10f7f043bd0d4c3f58791143b1cd7
 
 BUNDLED WITH

README.md

@@ -322,6 +322,19 @@ Output formats: `text` (default), `json`, and `sarif`. SARIF integrates with Git
 
 Vulnerability data is cached locally and refreshed automatically when stale (>24h). Use `git pkgs vulns sync --refresh` to force an update. See [docs/vulns.md](docs/vulns.md) for full documentation.
 
+### Integrity verification
+
+Show SHA256 hashes from lockfiles. Modern lockfiles include checksums that verify package contents haven't been tampered with.
+
+```bash
+git pkgs integrity              # show hashes for current dependencies
+git pkgs integrity --drift      # detect same version with different hashes
+git pkgs integrity -f json      # JSON output
+git pkgs integrity --stateless  # no database needed
+```
+
+The `--drift` flag scans your history for packages where the same version has different integrity hashes, which could indicate a supply chain issue.
+
 ### Diff between commits
 
 ```bash

docs/internals.md

@@ -19,7 +19,7 @@ The schema has ten tables. Six handle dependency tracking:
 - `branch_commits` is a join table preserving commit order within each branch
 - `manifests` stores file paths with their ecosystem (npm, rubygems, etc.) and kind (manifest vs lockfile)
 - `dependency_changes` records every add, modify, or remove event
-- `dependency_snapshots` stores full dependency state at intervals
+- `dependency_snapshots` stores full dependency state at intervals, including lockfile integrity hashes
 
 Four more support vulnerability scanning and package enrichment:
 
@@ -227,6 +227,25 @@ The `licenses` command checks licenses against configured policies:
 
 The command exits with code 1 when violations are found, making it suitable for CI pipelines.
 
+## Integrity Verification
+
+The `integrity` command shows SHA256 hashes from lockfiles. Modern lockfiles include checksums: Gemfile.lock has a CHECKSUMS section, package-lock.json has integrity fields. These hashes verify that the exact package content matches what was originally resolved.
+
+The `dependency_snapshots` table stores integrity alongside other dependency data. During `init` and `update`, bibliothecary extracts the integrity field from parsed lockfiles and git-pkgs stores it with each snapshot.
+
+The `--drift` flag does two things:
+
+1. **Internal drift** - detects when the same package@version has different integrity hashes across your history. This shouldn't happen under normal circumstances and could indicate:
+   - A dependency was republished with different content (rare but possible on some registries)
+   - A supply chain attack replaced a package
+   - Lockfile corruption or manual editing
+
+2. **Registry mismatch** - compares lockfile hashes against the registry's published integrity via the ecosyste.ms API. A mismatch here is more serious: either your lockfile has been tampered with, or the registry itself has different content than what you resolved.
+
+Internal drift queries the database for unique (purl, integrity) pairs and flags purls with multiple different values. Registry comparison fetches each version's integrity from ecosyste.ms (using the purl gem's `ecosystems_version_api_url` method) and compares against the lockfile value.
+
+Unlike the `outdated` and `licenses` commands which are entirely extrinsic, integrity verification is primarily intrinsic (lockfile hashes come from your git history) with optional extrinsic comparison when using `--drift`.
+
 ## Models
 
 Sequel models live in [`lib/git/pkgs/models/`](../lib/git/pkgs/models/). They're straightforward except for a few convenience methods:

git-pkgs.gemspec

@@ -34,8 +34,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rugged", "~> 1.0"
   spec.add_dependency "sequel", ">= 5.0"
   spec.add_dependency "sqlite3", ">= 2.0"
-  spec.add_dependency "ecosystems-bibliothecary", "~> 15.2"
+  spec.add_dependency "ecosystems-bibliothecary", "~> 15.3"
   spec.add_dependency "vers", "~> 1.0"
-  spec.add_dependency "purl", "~> 1.7"
+  spec.add_dependency "purl", "~> 1.7", ">= 1.7.1"
   spec.add_dependency "sarif-ruby"
 end

lib/git/pkgs.rb

@@ -49,12 +49,14 @@
 require_relative "pkgs/commands/vulns"
 require_relative "pkgs/commands/outdated"
 require_relative "pkgs/commands/licenses"
+require_relative "pkgs/commands/integrity"
 
 module Git
   module Pkgs
     class Error < StandardError; end
     class NotInitializedError < Error; end
     class NotInGitRepoError < Error; end
+    class SchemaVersionError < Error; end
 
     class << self
       attr_accessor :quiet, :git_dir, :work_tree, :db_path, :batch_size, :snapshot_interval, :threads

lib/git/pkgs/analyzer.rb

@@ -141,7 +141,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
               purl: generate_purl(result[:platform], dep[:name]),
               change_type: "added",
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
 
             key = [manifest_path, dep[:name]]
@@ -150,7 +151,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
               kind: result[:kind],
               purl: generate_purl(result[:platform], dep[:name]),
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
           end
         end
@@ -179,7 +181,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
               purl: generate_purl(after_result[:platform], name),
               change_type: "added",
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
 
             key = [manifest_path, name]
@@ -188,7 +191,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
               kind: after_result[:kind],
               purl: generate_purl(after_result[:platform], name),
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
           end
 
@@ -202,7 +206,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
               purl: generate_purl(before_result[:platform], name),
               change_type: "removed",
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
 
             key = [manifest_path, name]
@@ -223,7 +228,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
                 change_type: "modified",
                 requirement: after_dep[:requirement],
                 previous_requirement: before_dep[:requirement],
-                dependency_type: after_dep[:type]
+                dependency_type: after_dep[:type],
+                integrity: after_dep[:integrity]
               }
 
               key = [manifest_path, name]
@@ -232,7 +238,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
                 kind: after_result[:kind],
                 purl: generate_purl(after_result[:platform], name),
                 requirement: after_dep[:requirement],
-                dependency_type: after_dep[:type]
+                dependency_type: after_dep[:type],
+                integrity: after_dep[:integrity]
               }
             end
           end
@@ -252,7 +259,8 @@ def analyze_commit(rugged_commit, previous_snapshot = {})
               purl: generate_purl(result[:platform], dep[:name]),
               change_type: "removed",
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
 
             key = [manifest_path, dep[:name]]
@@ -329,7 +337,8 @@ def dependencies_at_commit(rugged_commit)
               kind: result[:kind],
               purl: generate_purl(result[:platform], dep[:name]),
               requirement: dep[:requirement],
-              dependency_type: dep[:type]
+              dependency_type: dep[:type],
+              integrity: dep[:integrity]
             }
           end
         end

lib/git/pkgs/cli.rb

@@ -35,7 +35,8 @@ class CLI
           "stats" => "Show dependency statistics",
           "stale" => "Show dependencies that haven't been updated",
           "outdated" => "Show packages with newer versions available",
-          "licenses" => "Show licenses for dependencies"
+          "licenses" => "Show licenses for dependencies",
+          "integrity" => "Show and verify lockfile integrity hashes"
         },
         "Security" => {
           "vulns" => "Scan for known vulnerabilities"

lib/git/pkgs/commands/branch.rb

@@ -191,6 +191,7 @@ def bulk_process_commits(commits, branch, analyzer, total, repo)
                     ecosystem: s[:ecosystem],
                     requirement: s[:requirement],
                     dependency_type: s[:dependency_type],
+                    integrity: s[:integrity],
                     created_at: now,
                     updated_at: now
                   }
@@ -266,7 +267,8 @@ def bulk_process_commits(commits, branch, analyzer, total, repo)
                     name: name,
                     ecosystem: dep_info[:ecosystem],
                     requirement: dep_info[:requirement],
-                    dependency_type: dep_info[:dependency_type]
+                    dependency_type: dep_info[:dependency_type],
+                    integrity: dep_info[:integrity]
                   }
                 end
                 snapshots_stored += snapshot.size
@@ -286,7 +288,8 @@ def bulk_process_commits(commits, branch, analyzer, total, repo)
                   name: name,
                   ecosystem: dep_info[:ecosystem],
                   requirement: dep_info[:requirement],
-                  dependency_type: dep_info[:dependency_type]
+                  dependency_type: dep_info[:dependency_type],
+                  integrity: dep_info[:integrity]
                 }
               end
               snapshots_stored += snapshot.size

lib/git/pkgs/commands/init.rb

@@ -125,6 +125,7 @@ def bulk_process_commits(commits, branch, analyzer, total)
                     purl: s[:purl],
                     requirement: s[:requirement],
                     dependency_type: s[:dependency_type],
+                    integrity: s[:integrity],
                     created_at: now,
                     updated_at: now
                   }
@@ -207,7 +208,8 @@ def bulk_process_commits(commits, branch, analyzer, total)
                     ecosystem: dep_info[:ecosystem],
                     purl: dep_info[:purl],
                     requirement: dep_info[:requirement],
-                    dependency_type: dep_info[:dependency_type]
+                    dependency_type: dep_info[:dependency_type],
+                    integrity: dep_info[:integrity]
                   }
                 end
                 snapshots_stored += snapshot.size
@@ -228,7 +230,8 @@ def bulk_process_commits(commits, branch, analyzer, total)
                   ecosystem: dep_info[:ecosystem],
                   purl: dep_info[:purl],
                   requirement: dep_info[:requirement],
-                  dependency_type: dep_info[:dependency_type]
+                  dependency_type: dep_info[:dependency_type],
+                  integrity: dep_info[:integrity]
                 }
               end
               snapshots_stored += snapshot.size