gem-guardian 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b22c1d6bd9bad2286db3b0bf061e14df64e544a7ec050b5c3ba883dc5dbaf9
-  data.tar.gz: 98768de703f861207c355cdf9299428d9b70caeab628b8861e643ed8d38fa6ab
+  metadata.gz: 9d95cfd5ad19142df2c6c18d606f7c4badf96c11e1e7acc8fa048a5c8cd5d7ad
+  data.tar.gz: 31efbe8a66d14abe2abf8a73c34a080f4b9ca56a45e9e83ffd16194292ae5d61
 SHA512:
-  metadata.gz: e167265b43bfb4311f73df8390579c9707034dfab202cd694fb0a43e3a0a75c68431217e7068de518bd75b14cb71ee1a08cffa0ccbe59e8dff869d35db958fb4
-  data.tar.gz: 419cf82e3c70e1e34fd29e37e277899a96355b410a0b54dfb9830daebb8d5e3818f4016d835408802fad6ab588d37c97bab3836cff62c5455d28780476620c1b
+  metadata.gz: f010bbbfefcd4748b5695d20ddfc13b7e86fb5ad0501a0eecb8682638b8eee00c12950a7cc86600e315ffb371262fd48900cf6f70749a7e34d92e719e1f75953
+  data.tar.gz: 979b1cfd1e3ba1e692b03736361f345c5209bfbf2cb6978cb6b8c6a9ce48d009b7ce7e5fc3ef19016ab953fb9383b2059bcc26b4079bbd18cb5bc6c59b7c0d81

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## [0.4.1] - 2026-06-21
+
+- Add curated RBS signatures for the public API.
+- Restore `rbs:validate` to the default quality checks, load project signatures explicitly, and package them with the gem.
+
 ## [0.4.0]
 
 - Add `.gem-guardian.yml` project configuration for publisher checksum providers.

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 gem "minitest", "~> 6.0"
 gem "pry", "~> 0.16.0"
 gem "rake", "~> 13.4"
+gem "rbs", "~> 3.9"
 gem "rubocop", "~> 1.87"
 gem "rubocop-minitest", "~> 0.39.1"
 gem "rubocop-rake", "~> 0.7.1"

data/Rakefile

@@ -19,6 +19,13 @@ end
 
 YARD::Rake::YardocTask.new(:yard)
 
+namespace :rbs do
+  desc "Validate RBS signatures"
+  task :validate do
+    sh "bundle exec rbs -I sig validate"
+  end
+end
+
 namespace :yard do
   desc "Validate YARD documentation coverage"
   task :validate do
@@ -40,4 +47,4 @@ namespace :yard do
   end
 end
 
-task default: %i[test rubocop yard:validate]
+task default: %i[test rubocop rbs:validate yard:validate]

data/gem-guardian.gemspec

@@ -27,12 +27,12 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(__dir__) do
     tracked_files = `git ls-files -z`.split("\x0")
-    source_files = Dir["lib/**/*", "exe/*", "README.md", "LICENSE.txt", "CHANGELOG.md"]
+    source_files = Dir["lib/**/*", "sig/**/*", "exe/*", "README.md", "LICENSE.txt", "CHANGELOG.md"]
     (tracked_files + source_files).uniq.reject do |f|
       f.match(%r{\A(?:test|spec|features)/})
     end
   rescue StandardError
-    Dir["lib/**/*", "exe/*", "README.md", "LICENSE.txt", "CHANGELOG.md"]
+    Dir["lib/**/*", "sig/**/*", "exe/*", "README.md", "LICENSE.txt", "CHANGELOG.md"]
   end
 
   spec.bindir = "exe"

data/lib/gem/guardian/version.rb

@@ -3,6 +3,6 @@
 module Gem
   module Guardian
     # gem-guardian version.
-    VERSION = "0.4.0"
+    VERSION = "0.4.1"
   end
 end

data/sig/gem/guardian/checksum_provider.rbs

@@ -0,0 +1,57 @@
+module Gem
+  module Guardian
+    module ChecksumProvider
+      interface _Provider
+        def checksum_for: (Dependency dependency, client: RubygemsClient) -> Result?
+      end
+
+      class Result < Data
+        attr_reader sha256: String
+        attr_reader source: Symbol
+        attr_reader provider: String
+        attr_reader verification_uri: String?
+
+        def self.new: (String sha256, Symbol source, String provider, String? verification_uri) -> instance
+                    | (sha256: String, source: Symbol, provider: String, verification_uri: String?) -> instance
+
+        def to_h: () -> Hash[Symbol, String | Symbol | nil]
+      end
+
+      class RubyGemsApi
+        include _Provider
+      end
+
+      class CompactIndex
+        include _Provider
+      end
+
+      class SourceScoped
+        include _Provider
+
+        def initialize: (source: String, provider: _Provider) -> void
+      end
+
+      class Url
+        include _Provider
+
+        SHA256_PATTERN: Regexp
+        OPEN_TIMEOUT: Integer
+        READ_TIMEOUT: Integer
+
+        def initialize: (template: String, ?http: untyped, ?provider_name: String) -> void
+      end
+    end
+
+    class Configuration
+      DEFAULT_PATH: String
+
+      attr_reader path: String?
+      attr_reader checksum_providers: Array[ChecksumProvider::_Provider]
+
+      def self.load: (?path: String?, ?cwd: String) -> Configuration
+
+      def initialize: (?path: String?, ?checksum_providers: Array[ChecksumProvider::_Provider]) -> void
+      def checksum_providers?: () -> bool
+    end
+  end
+end

data/sig/gem/guardian/cli.rbs

@@ -0,0 +1,33 @@
+module Gem
+  module Guardian
+    class CLI
+      class LockfileDataView < Data
+        attr_reader dependencies: Array[Dependency]
+        attr_reader checksums: checksum_map
+        attr_reader checksums_section_present: bool
+
+        def self.new: (Array[Dependency] dependencies, checksum_map checksums, bool checksums_section_present) -> instance
+                    | (dependencies: Array[Dependency], checksums: checksum_map, checksums_section_present: bool) -> instance
+
+        def checksum_for: (Dependency dependency, ?String algorithm) -> String?
+        def sha256_checksums: () -> Hash[Dependency, String]
+        def missing_checksum_dependencies: () -> Array[Dependency]
+        def checksums_present?: () -> bool
+      end
+
+      def self.start: (Array[String] argv) -> Integer
+
+      def initialize: (
+        Array[String] argv,
+        ?stdout: untyped,
+        ?stderr: untyped,
+        ?verifier_class: untyped,
+        ?lockfile_parser_class: untyped,
+        ?provenance_verifier_class: untyped,
+        ?report_builder_class: untyped
+      ) -> void
+
+      def run: () -> Integer
+    end
+  end
+end

data/sig/gem/guardian/clients.rbs

@@ -0,0 +1,80 @@
+module Gem
+  module Guardian
+    class GitHubClient
+      DEFAULT_HOST: String
+
+      def initialize: (?host: String, ?http: untyped) -> void
+      def release: (String repository, String tag) -> Hash[String, untyped]?
+      def tag_verification: (String repository, String tag) -> Hash[String, untyped]?
+    end
+
+    class RubygemsClient
+      class TrustedPublishingProvenance < Data
+        attr_reader trusted_publishing: bool
+        attr_reader repository: String?
+        attr_reader ref: String?
+        attr_reader workflow: String?
+        attr_reader issuer: String?
+        attr_reader subject: String?
+        attr_reader sha256: String?
+        attr_reader attestation_url: String?
+
+        def self.new: (
+          bool trusted_publishing,
+          String? repository,
+          String? ref,
+          String? workflow,
+          String? issuer,
+          String? subject,
+          String? sha256,
+          String? attestation_url
+        ) -> instance
+        | (
+          trusted_publishing: bool,
+          repository: String?,
+          ref: String?,
+          workflow: String?,
+          issuer: String?,
+          subject: String?,
+          sha256: String?,
+          attestation_url: String?
+        ) -> instance
+      end
+
+      SOURCE_COMMIT_PATTERN: Regexp
+      BUILD_FILE_PATTERN: Regexp
+      LOG_ENTRY_PATTERN: Regexp
+      SHA256_PATTERN: Regexp
+      WORKFLOW_PATTERN: Regexp
+      DEFAULT_HOST: String
+      MAX_REDIRECTS: Integer
+      OPEN_TIMEOUT: Integer
+      READ_TIMEOUT: Integer
+
+      def self.default_checksum_providers: () -> Array[ChecksumProvider::_Provider]
+
+      def initialize: (
+        ?host: String,
+        ?http: untyped,
+        ?credentials: untyped,
+        ?spec_fetcher: untyped,
+        ?sources: untyped,
+        ?checksum_providers: Array[ChecksumProvider::_Provider]?
+      ) -> void
+
+      def resolve_dependency: (Dependency dependency) -> Dependency
+      def expected_sha256: (Dependency dependency) -> String
+      def registry_checksum: (Dependency dependency) -> ChecksumProvider::Result?
+      def sanitize_uri: (untyped uri) -> String
+      def rubygems_api_checksum: (Dependency dependency) -> ChecksumProvider::Result?
+      def compact_index_registry_checksum: (Dependency dependency) -> ChecksumProvider::Result?
+      def trusted_publishing_provenance: (Dependency dependency) -> TrustedPublishingProvenance?
+      def download_gem: (Dependency dependency, String destination) -> String
+    end
+
+    class ArtifactStore
+      def initialize: (client: RubygemsClient, ?cache_dir: String) -> void
+      def path_for: (Dependency dependency) -> String
+    end
+  end
+end

data/sig/gem/guardian/core.rbs

@@ -0,0 +1,39 @@
+module Gem
+  module Guardian
+    VERSION: String
+
+    class Error < StandardError
+    end
+
+    class ChecksumNotFound < Error
+    end
+
+    class ArtifactFetchError < Error
+    end
+
+    class LockfileError < Error
+    end
+
+    class Dependency < Data
+      attr_reader name: String
+      attr_reader version: String
+      attr_reader platform: String?
+      attr_reader source: String?
+
+      def self.new: (name: String, version: String, platform: String?, ?source: String?) -> instance
+
+      def initialize: (name: String, version: String, platform: String?, ?source: String?) -> void
+      def gem_filename: () -> String
+    end
+
+    module Checksum
+      def self.sha256_file: (String path) -> String
+    end
+
+    module Progress
+      def self.update: (untyped message, ?io: untyped, ?force: bool) -> void
+      def self.finish: (?untyped message, ?io: untyped, ?force: bool) -> void
+      def self.enabled?: (?untyped io, ?force: bool) -> bool
+    end
+  end
+end

data/sig/gem/guardian/lockfile.rbs

@@ -0,0 +1,30 @@
+module Gem
+  module Guardian
+    type checksum_map = Hash[Dependency, Hash[String, String]]
+
+    class LockfileParser
+      GEM_LINE: Regexp
+      REMOTE_LINE: Regexp
+      CHECKSUM_LINE: Regexp
+
+      class LockfileData < Data
+        attr_reader dependencies: Array[Dependency]
+        attr_reader checksums: checksum_map
+        attr_reader checksums_section_present: bool
+
+        def self.new: (Array[Dependency] dependencies, checksum_map checksums, bool checksums_section_present) -> instance
+                    | (dependencies: Array[Dependency], checksums: checksum_map, checksums_section_present: bool) -> instance
+
+        def checksum_for: (Dependency dependency, ?String algorithm) -> String?
+        def sha256_checksums: () -> Hash[Dependency, String]
+        def missing_checksum_dependencies: () -> Array[Dependency]
+        def checksums_present?: () -> bool
+      end
+
+      def initialize: (?String path) -> void
+      def parse: () -> LockfileData
+      def dependencies: () -> Array[Dependency]
+      def checksums: () -> checksum_map
+    end
+  end
+end

data/sig/gem/guardian/registry.rbs

@@ -0,0 +1,51 @@
+module Gem
+  module Guardian
+    class Registry
+      class Entry < Data
+        attr_reader name: String
+        attr_reader version: String
+        attr_reader platform: String
+        attr_reader source: String
+
+        def self.new: (name: String, version: String, platform: String, source: String) -> instance
+                    | (String name, String version, String platform, String source) -> instance
+
+        def dependency: () -> Dependency
+      end
+
+      def initialize: (?sources: untyped, ?spec_fetcher: untyped) -> void
+      def each_latest_spec: (?limit: Integer?) { (Entry) -> void } -> untyped
+                          | (?limit: Integer?) -> Enumerator[Entry, untyped]
+      def latest_specs: (?limit: Integer?) -> Array[Entry]
+    end
+
+    class RegistryAudit
+      class EntryResult < Data
+        attr_reader entry: Registry::Entry
+        attr_reader provenance: ProvenanceResult
+
+        def self.new: (entry: Registry::Entry, provenance: ProvenanceResult) -> instance
+                    | (Registry::Entry entry, ProvenanceResult provenance) -> instance
+
+        def dependency: () -> Dependency
+      end
+
+      class Result < Data
+        attr_reader results: Array[EntryResult]
+
+        def self.new: (Array[EntryResult] results) -> instance
+                    | (results: Array[EntryResult]) -> instance
+
+        def counts: () -> Hash[provenance_status, Integer]
+        def verified: () -> Array[EntryResult]
+        def unsupported: () -> Array[EntryResult]
+        def errors: () -> Array[EntryResult]
+        def mismatches: () -> Array[EntryResult]
+        def total: () -> Integer
+      end
+
+      def initialize: (?registry: Registry, ?provenance_verifier: ProvenanceVerifier) -> void
+      def run: (?limit: Integer?) -> Result
+    end
+  end
+end

data/sig/gem/guardian/reporting.rbs

@@ -0,0 +1,32 @@
+module Gem
+  module Guardian
+    class ReportBuilder
+      def initialize: (version: String) -> void
+
+      def build: (
+        Enumerable[VerificationResult] results,
+        lockfile_data: LockfileParser::LockfileData | CLI::LockfileDataView | nil,
+        ?provenance_results: Array[ProvenanceResult],
+        ?lockfile_path: String?
+      ) -> Hash[Symbol, untyped]
+    end
+
+    class ResultPrinter
+      USAGE: String
+
+      def initialize: (stdout: untyped) -> void
+      def print_results: (Enumerable[VerificationResult] results, lockfile_mode: bool) -> void
+      def print_result: (VerificationResult result, lockfile_mode: bool) -> void
+      def print_ok_result: (VerificationResult result, String label, bool lockfile_mode) -> void
+      def print_mismatch_result: (VerificationResult result, String label) -> void
+      def print_error_result: (VerificationResult result, String label) -> void
+      def print_lockfile_coverage: (LockfileParser::LockfileData | CLI::LockfileDataView lockfile_data) -> void
+      def print_provenance_results: (Enumerable[ProvenanceResult] results) -> void
+      def print_provenance_result: (ProvenanceResult result) -> void
+      def print_verified_provenance_result: (ProvenanceResult result, String label) -> void
+      def print_mismatched_provenance_result: (ProvenanceResult result, String label) -> void
+      def print_unsupported_provenance_result: (ProvenanceResult result, String label) -> void
+      def usage: () -> void
+    end
+  end
+end

data/sig/gem/guardian/verification.rbs

@@ -0,0 +1,125 @@
+module Gem
+  module Guardian
+    type verification_status = :ok | :mismatch | :error
+    type checksum_source = :lockfile | :registry | :artifact
+    type provenance_status = :verified | :unsupported | :mismatch | :error
+
+    class VerificationResult < Data
+      attr_reader dependency: Dependency
+      attr_reader expected_sha256: String?
+      attr_reader actual_sha256: String?
+      attr_reader artifact_path: String?
+      attr_reader status: verification_status
+      attr_reader error: Exception?
+      attr_reader checksum_source: checksum_source?
+      attr_reader registry_sha256: String?
+      attr_reader registry_checksum_provider: String?
+      attr_reader registry_checksum_uri: String?
+
+      def self.new: (
+        dependency: Dependency,
+        expected_sha256: String?,
+        actual_sha256: String?,
+        artifact_path: String?,
+        status: verification_status,
+        error: Exception?,
+        checksum_source: checksum_source?,
+        registry_sha256: String?,
+        registry_checksum_provider: String?,
+        registry_checksum_uri: String?
+      ) -> instance
+
+      def ok?: () -> bool
+    end
+
+    class Verifier
+      def initialize: (
+        ?client: RubygemsClient,
+        ?artifact_store: ArtifactStore?,
+        ?expected_checksums: Hash[Dependency, String]
+      ) -> void
+
+      def verify: (Dependency dependency) -> VerificationResult
+      def verify_all: (Enumerable[Dependency] dependencies) -> Array[VerificationResult]
+    end
+
+    class GitHubReleaseResult < Data
+      attr_reader dependency: Dependency
+      attr_reader status: provenance_status
+      attr_reader repository: String?
+      attr_reader tag: String?
+      attr_reader checksum_assets: Array[String]
+      attr_reader signature_assets: Array[String]
+      attr_reader signed_tag: bool?
+      attr_reader signed_tag_reason: String?
+      attr_reader release_attestation: bool?
+      attr_reader release_url: String?
+      attr_reader error: Exception?
+
+      def self.new: (
+        dependency: Dependency,
+        status: provenance_status,
+        repository: String?,
+        tag: String?,
+        checksum_assets: Array[String],
+        signature_assets: Array[String],
+        signed_tag: bool?,
+        signed_tag_reason: String?,
+        release_attestation: bool?,
+        release_url: String?,
+        error: Exception?
+      ) -> instance
+
+      def verified?: () -> bool
+    end
+
+    class GitHubReleaseVerifier
+      def initialize: (?client: GitHubClient) -> void
+      def verify: (RubygemsClient::TrustedPublishingProvenance provenance) -> GitHubReleaseResult
+    end
+
+    class ProvenanceResult < Data
+      attr_reader dependency: Dependency
+      attr_reader status: provenance_status
+      attr_reader trusted_publishing: bool?
+      attr_reader repository: String?
+      attr_reader ref: String?
+      attr_reader workflow: String?
+      attr_reader issuer: String?
+      attr_reader subject: String?
+      attr_reader expected_sha256: String?
+      attr_reader actual_sha256: String?
+      attr_reader error: Exception?
+      attr_reader attestation_url: String?
+      attr_reader github_release: GitHubReleaseResult?
+
+      def self.new: (
+        dependency: Dependency,
+        status: provenance_status,
+        trusted_publishing: bool?,
+        repository: String?,
+        ref: String?,
+        workflow: String?,
+        issuer: String?,
+        subject: String?,
+        expected_sha256: String?,
+        actual_sha256: String?,
+        error: Exception?,
+        attestation_url: String?,
+        github_release: GitHubReleaseResult?
+      ) -> instance
+
+      def verified?: () -> bool
+    end
+
+    class ProvenanceVerifier
+      def initialize: (
+        ?client: RubygemsClient,
+        ?github_release_verifier: GitHubReleaseVerifier
+      ) -> void
+
+      def verify: (Dependency dependency, ?artifact_sha256: String?) -> ProvenanceResult
+      def verify_all: (Enumerable[VerificationResult] results) -> Array[ProvenanceResult]
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-guardian
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Kenneth Demanawa
@@ -59,6 +59,14 @@ files:
 - lib/gem/guardian/version.rb
 - mise.toml
 - script/registry_provenance_audit.rb
+- sig/gem/guardian/checksum_provider.rbs
+- sig/gem/guardian/cli.rbs
+- sig/gem/guardian/clients.rbs
+- sig/gem/guardian/core.rbs
+- sig/gem/guardian/lockfile.rbs
+- sig/gem/guardian/registry.rbs
+- sig/gem/guardian/reporting.rbs
+- sig/gem/guardian/verification.rbs
 homepage: https://kanutocd.github.io/gem-guardian
 licenses:
 - MIT