leakferret 0.1.14 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c62cebff3d1211eeca1d965e121374d702afce5ecd10f9780894a832149d94
-  data.tar.gz: 256fc704331ca3665340f2a91ed67536a08378e0d78d83ce07b945818123233d
+  metadata.gz: ef6c03214e9031af408f981d0da88fdc2d13a6bbb436162a172133cea932b87d
+  data.tar.gz: 51b3f462cab5b37de16c15c885650dfc8cec83fb9422b1b963cc9eb1de6de72b
 SHA512:
-  metadata.gz: faf71368d72c20cfe03dd6e33400e87d2ddae92a9fa299edf7f025fc935b5f1c89fadedaf0a05518c31bbde1094fdc41730fcd0d59ff73d3466d6e6c0f570921
-  data.tar.gz: c5b6e8eeed8d89a9f91cc0bb6c5f125b0cbc06e498347ce65035d1d7f36f1a40906efe151794a571974671e3a2e8e25975947aae42931893742b18b634a0daf0
+  metadata.gz: 0fefef7848e0fb314988b865daf8cfd542f29069473b330c9e20ddcbea3d26114dce8516f9db665574b132f1f1a103c76971e42876b51c12c26a529560c2bdfe
+  data.tar.gz: 434b508ffc8a671af5071db882e915681003cebd2746fd2055d48ac46e777fe29280ac9f371916e1ba6398eb412cd8cd61ff21ec157c1df56f6a549c39e17fcc

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to the `leakferret` gem are documented here. The gem version
+can move independently of the native binary version it targets.
+
+## [0.2.0] - 2026-06-04
+
+Minor bump (not patch): this removes the binary-download fallback, so a
+previously-supported install path is gone on platforms without a prebuilt gem
+(notably arm64-Windows). Breaking change under the 0.x convention.
+
+### Changed
+- Ship **precompiled platform gems** (x86_64-linux, x86_64-darwin, arm64-darwin,
+  x64-mingw-ucrt) with the native binary bundled inside the gem. A normal
+  `gem install` gets the binary through RubyGems itself: no download, no
+  network, no Rust toolchain. Audit it with `gem unpack leakferret`. Mirrors how
+  `nokogiri` and `sorbet-static` ship.
+- **Removed the binary-download flow entirely.** Dropped the install-time
+  `extconf.rb` pre-fetch and the runtime download + SHA256 logic. The gem now
+  has no fetch-and-run code to audit at all.
+- On a platform without a prebuilt binary (e.g. aarch64-linux, Alpine/musl), the
+  source gem still installs (so `bundle install` resolves) and raises a clear
+  message pointing to `cargo install leakferret-cli` or `LEAKFERRET_BIN`. It
+  never downloads.
+- Released gems now carry GitHub build provenance (SLSA attestation).
+
+### Removed
+- `ext/leakferret/extconf.rb` and the runtime binary downloader.
+
+Targets the leakferret `0.1.9` binary (unchanged).

data/README.md

@@ -16,14 +16,17 @@
 
 Ruby gem wrapper around the native [`leakferret`](https://github.com/leakferrethq/leakferret)
 binary. This gem ships no scanning logic of its own: it installs a tiny Ruby
-shim plus a small executable, and downloads the prebuilt, statically-linked
-binary (written in Rust) from GitHub Releases once per platform at install
-time. All the work — scan, classify, verify, rewrite — happens in that single
-binary.
-
-This is the same packaging pattern used by `ruff`, `biome`, and `esbuild`:
-distributing the toolchain to build a Rust engine on every machine is
-unfriendly, so we ship the compiled engine instead.
+shim plus the prebuilt, statically-linked engine (written in Rust). All the
+work — scan, classify, verify, rewrite — happens in that single binary.
+
+You get a **precompiled platform gem** with the binary bundled inside it, the
+same way `nokogiri` and `sorbet-static` ship their native code, for x86_64
+Linux (glibc), macOS (x86_64 and arm64), and x86_64 Windows. The binary travels
+through RubyGems with the gem — **no download, no network access, no Rust
+toolchain** — and you can audit exactly what you will run with
+`gem unpack leakferret`. The gem has **no fetch-and-run code at all**. On any
+other platform the source gem installs and points you at a one-line fix (build
+from source, or set `LEAKFERRET_BIN`); it never downloads a binary.
 
 ## What leakferret does
 
@@ -57,9 +60,19 @@ from your machine to the provider — leakferret has no servers.
 gem install leakferret
 ```
 
-The platform binary (`leakferret-{version}-{platform}.tar.gz` from GitHub
-Releases) is downloaded automatically on first use and cached under your home
-directory — no Rust toolchain required.
+RubyGems and Bundler select the right precompiled gem for your platform
+automatically, so the binary is already there after `gem install` — no
+first-run download. Inspect it before you trust it:
+
+```bash
+gem unpack leakferret        # the bundled binary is at lib/leakferret/bin/
+```
+
+Released gems carry GitHub build provenance (SLSA), so you can verify each gem
+was built from the tagged source in CI. On a platform without a prebuilt binary
+(e.g. aarch64-linux or Alpine/musl), the source gem still installs — so
+`bundle install` resolves — and tells you to build from source
+(`cargo install leakferret-cli`) or set `LEAKFERRET_BIN`. It never downloads.
 
 Add it to a `Gemfile` for project-local use:
 

data/lib/leakferret/binary.rb

@@ -7,45 +7,28 @@ require_relative 'platform'
 require_relative 'error'
 
 module Leakferret
-  # Resolves (and, if needed, downloads) the native `leakferret` binary.
+  # Resolves the native `leakferret` binary that ships inside the gem.
   #
-  # The binary is fetched into an absolute, user-writable cache directory
-  # rather than into the gem's own tree. RubyGems builds extensions in a
-  # throwaway temp dir, so anything written relative to the gem during
-  # `gem install` is discarded — the cache path sidesteps that entirely and
-  # also lets a plain `gem install` (no extension) work.
+  # Precompiled platform gems bundle the binary at lib/leakferret/bin/. There is
+  # deliberately no download path: the gem either carries the binary for your
+  # platform or it tells you how to provide one. Nothing here touches the
+  # network, so what you `gem unpack` is exactly what runs - the whole gem is
+  # auditable, with no fetch-and-execute code to vet.
   #
   # @api private
   module Binary
-    # A binary vendored inside the gem, if one was shipped (normally empty).
+    # Where a precompiled platform gem stages the native binary.
     BUNDLED_DIR = Pathname.new(__dir__).join('bin').freeze
 
-    # SHA256 of each release tarball, pinned to BINARY_VERSION. The download is
-    # verified against these before the archive is ever unpacked, so a tampered
-    # or corrupted release asset is rejected instead of being executed. Because
-    # the digests live in the gem source, auditing the published gem tells you
-    # exactly which binary bytes it will run. Regenerate on every binary bump
-    # from the release's `*.tar.gz.sha256` files.
-    CHECKSUMS = {
-      'aarch64-apple-darwin'     => '363b1da65bf34d2c89c37aa2e00eaa03d49c8595cc5b8bb752a344dacf21d7da',
-      'aarch64-pc-windows-msvc'  => 'b009e852af7eb73dc203e9cb343bec80a1727075d6a35be4ff9567191fd57ca9',
-      'x86_64-apple-darwin'      => '3af3d7f22a8d127053df123033b0b6777701310733d643406754423d6b1d3912',
-      'x86_64-pc-windows-msvc'   => '3f038f55cfded63ebc2f8c16c1edbdd1ddcd36ae43a872b91f5aaeed93438fc1',
-      'x86_64-unknown-linux-gnu' => 'ba28ac5ef5a44d47f162f3c424c1465da5bbd17fb7292f60d3bd3cf3b2d362a4'
-    }.freeze
-
     module_function
 
-    # Absolute path to the native binary, downloading it on first use if
-    # necessary. Resolution order:
-    #   1. LEAKFERRET_BIN          — explicit override
-    #   2. lib/leakferret/bin/     — a binary vendored in the gem
-    #   3. the per-version cache   — fetched on a prior run or at install
-    #   4. download into the cache now
+    # Absolute path to the native binary. Resolution order:
+    #   1. LEAKFERRET_BIN             - explicit override
+    #   2. lib/leakferret/bin/<name>  - bundled by the precompiled platform gem
     #
     # @return [String] absolute path to the executable
-    # @raise [BinaryNotFoundError] if the override is missing, or the binary is
-    #   absent and cannot be downloaded
+    # @raise [BinaryNotFoundError] if the override is missing, or no binary is
+    #   bundled for this platform
     def path
       override = ENV['LEAKFERRET_BIN']
       unless override.nil? || override.empty?
@@ -57,119 +40,50 @@ module Leakferret
       end
 
       bundled = BUNDLED_DIR.join(Platform.binary_name)
-      return bundled.to_s if bundled.file?
-
-      return cache_path.to_s if cache_path.file?
-
-      ensure!
-      raise BinaryNotFoundError, install_instructions(cache_path) unless cache_path.file?
-
-      cache_path.to_s
-    end
-
-    # User-writable cache directory, namespaced by the binary version so a
-    # gem upgrade fetches a fresh binary instead of reusing a stale one.
-    #
-    # @return [Pathname] the per-version cache directory
-    def cache_dir
-      base =
-        if Platform.windows?
-          ENV['LOCALAPPDATA'] || File.join(Dir.home, 'AppData', 'Local')
-        else
-          ENV['XDG_CACHE_HOME'] || File.join(Dir.home, '.cache')
-        end
-      Pathname.new(base).join('leakferret', BINARY_VERSION)
-    end
-
-    # @return [Pathname] the cached binary's full path for this platform
-    def cache_path
-      cache_dir.join(Platform.binary_name)
-    end
-
-    # @return [String] the GitHub release download URL for this platform's tarball
-    def download_url
-      'https://github.com/leakferrethq/leakferret/releases/download/' \
-        "v#{BINARY_VERSION}/leakferret-#{BINARY_VERSION}-#{Platform.triple}.tar.gz"
-    end
-
-    # Download, checksum-verify, and unpack the binary into the cache.
-    # Idempotent: a no-op when the binary is already cached. The SHA256 is
-    # checked against the pinned {CHECKSUMS} value before anything is written
-    # or marked executable, so a tampered or truncated asset is rejected.
-    #
-    # @return [String] absolute path to the cached binary
-    # @raise [BinaryNotFoundError] on an unknown platform, a checksum mismatch,
-    #   or a binary missing from the downloaded archive
-    def ensure!
-      dest = cache_path
-      return dest.to_s if dest.file?
-
-      require 'fileutils'
-      require 'open-uri'
-      require 'zlib'
-      require 'digest'
-      require 'stringio'
-      require 'rubygems/package'
-
-      expected = CHECKSUMS[Platform.triple]
-      if expected.nil?
-        raise BinaryNotFoundError,
-              "no pinned checksum for platform #{Platform.triple}; refusing to run an " \
-              'unverified binary. Build from source and set LEAKFERRET_BIN instead.'
-      end
-
-      FileUtils.mkdir_p(dest.dirname)
-
-      # Download the whole tarball, verify its SHA256 against the pinned value,
-      # and only then unpack. Nothing is written to the cache (let alone marked
-      # executable) until the bytes match, so a tampered or truncated release
-      # asset is rejected rather than run.
-      tarball = URI.open(download_url, &:read) # rubocop:disable Security/Open
-      actual = Digest::SHA256.hexdigest(tarball)
-      unless actual.casecmp?(expected)
-        raise BinaryNotFoundError,
-              "checksum mismatch for #{download_url}\n" \
-              "  expected #{expected}\n  got      #{actual}\n" \
-              'Refusing to install a binary that does not match the pinned hash.'
-      end
-
-      # Unpack in pure Ruby (no external `tar`, which on Windows mis-reads `C:\`
-      # as a remote host). The archive nests everything under
-      # leakferret-<version>-<triple>/, so match by basename.
-      found = false
-      Zlib::GzipReader.wrap(StringIO.new(tarball)) do |gz|
-        Gem::Package::TarReader.new(gz) do |tar|
-          tar.each do |entry|
-            next unless entry.file?
-            next unless File.basename(entry.full_name) == Platform.binary_name
-
-            File.binwrite(dest, entry.read)
-            found = true
+      if bundled.file?
+        # Make sure it is executable in case the mode did not survive packaging
+        # or install; the gem dir is usually writable, a read-only one is
+        # harmless to skip.
+        unless Platform.windows? || bundled.executable?
+          begin
+            bundled.chmod(0o755)
+          rescue StandardError
+            # best effort
           end
         end
+        return bundled.to_s
       end
-      raise BinaryNotFoundError, "binary not found inside #{download_url}" unless found
 
-      FileUtils.chmod(0o755, dest) unless Platform.windows?
-      dest.to_s
+      raise BinaryNotFoundError, no_binary_message
     end
 
-    # Human-readable fallback message shown when the binary is absent and the
-    # automatic download failed.
+    # Message shown when the source/fallback gem is installed on a platform with
+    # no precompiled binary. No automatic download is attempted - the user
+    # provides the binary, or builds it.
     #
-    # @param candidate [Pathname] the cache path the binary was expected at
-    # @return [String] multi-line manual-install instructions
-    def install_instructions(candidate)
+    # @return [String] multi-line build-from-source instructions
+    def no_binary_message
+      plat =
+        begin
+          Gem::Platform.local.to_s
+        rescue StandardError
+          RUBY_PLATFORM
+        end
+
       <<~MSG
-        leakferret native binary not found, and the automatic download failed.
+        No prebuilt leakferret binary ships for this platform (#{plat}).
 
-        Expected it at:
-          #{candidate}
+        leakferret publishes precompiled gems for x86_64 and arm64 macOS,
+        x86_64 Linux (glibc), and x86_64 Windows. On any other platform, provide
+        the binary yourself - either of these works:
 
-        Download the binary for your platform from:
-          https://github.com/leakferrethq/leakferret/releases
+          1. Build from source and point LEAKFERRET_BIN at it:
+               cargo install leakferret-cli
+               export LEAKFERRET_BIN="$(command -v leakferret)"
 
-        then either place it at the path above or point LEAKFERRET_BIN at it.
+          2. Download a release binary for your platform from
+               https://github.com/leakferrethq/leakferret/releases
+             and set LEAKFERRET_BIN to its absolute path.
       MSG
     end
   end

data/lib/leakferret/version.rb

@@ -3,11 +3,12 @@
 module Leakferret
   # The gem's own version (what `gem install leakferret` resolves).
   # @return [String]
-  VERSION = '0.1.14'
+  VERSION = '0.2.0'
 
-  # The native binary release this gem downloads and runs. Tracks the
-  # leakferret core release and can move independently of {VERSION}
-  # (e.g. a gem-only bugfix keeps the same binary).
+  # The native binary release this gem bundles and runs. The release workflow
+  # stages this version's binary into each precompiled platform gem. Tracks the
+  # leakferret core release and can move independently of {VERSION} (e.g. a
+  # gem-only bugfix keeps the same binary).
   # @return [String]
   BINARY_VERSION = '0.1.9'
 end

metadata

@@ -1,21 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: leakferret
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.2.0
 platform: ruby
 authors:
 - Maria Khan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies: []
 description: |
   Context-aware secret scanning for Ruby projects. A thin wrapper around the
   native leakferret binary (written in Rust): it finds hardcoded secrets,
   confirms which ones are actually live by calling the provider, and rewrites
-  them to read from environment variables instead. The platform binary is
-  downloaded automatically on first use, so no Rust toolchain is required.
+  them to read from environment variables instead.
+
+  Precompiled platform gems bundle the native binary inside the gem, so a
+  normal `gem install` ships the binary through RubyGems itself: no download,
+  no network access, and no Rust toolchain. You can audit exactly what you are
+  about to run with `gem unpack leakferret`. The gem never fetches and runs a
+  binary off the internet - there is no download code to vet. On a platform
+  without a prebuilt gem, the source gem tells you to build from source
+  (`cargo install leakferret-cli`) or point LEAKFERRET_BIN at a binary.
 
   The API exposes Leakferret.scan, Leakferret.verify, and Leakferret.rewrite
   (each returning Finding objects), plus a `leakferret` command-line tool.
@@ -23,15 +30,14 @@ email:
 - missusk@protonmail.com
 executables:
 - leakferret
-extensions:
-- ext/leakferret/extconf.rb
+extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - exe/leakferret
-- ext/leakferret/extconf.rb
 - lib/leakferret.rb
 - lib/leakferret/binary.rb
 - lib/leakferret/client.rb

data/ext/leakferret/extconf.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-# Best-effort install-time pre-fetch of the native binary into the
-# user-writable cache (see lib/leakferret/binary.rb). This is purely an
-# optimisation so the first invocation is instant — the binary is also
-# downloaded lazily on first use, so a failure here is harmless. Set
-# LEAKFERRET_SKIP_DOWNLOAD to skip the pre-fetch.
-#
-# We deliberately do NOT compile the Rust source: that would force every
-# user to have a Rust toolchain and wait for a long build. The
-# download-binary model matches ruff (Python), biome/esbuild (npm).
-
-require_relative '../../lib/leakferret/version'
-require_relative '../../lib/leakferret/platform'
-require_relative '../../lib/leakferret/error'
-require_relative '../../lib/leakferret/binary'
-
-# Emit an empty Makefile so rubygems considers the "extension" built.
-File.write('Makefile', "all:\n\t@true\ninstall:\n\t@true\nclean:\n\t@true\n")
-
-def log(msg)
-  warn "[leakferret/extconf] #{msg}"
-end
-
-if ENV['LEAKFERRET_SKIP_DOWNLOAD']
-  log 'LEAKFERRET_SKIP_DOWNLOAD set; binary will be downloaded on first use.'
-  exit 0
-end
-
-begin
-  path = Leakferret::Binary.ensure!
-  log "binary ready at #{path}"
-rescue StandardError => e
-  log "pre-fetch failed (#{e.class}: #{e.message}); it will download on first use."
-end
-
-# Always succeed: a failed pre-fetch must not fail the gem install.
-exit 0