leakferret 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 353c45016e727caee84d2f288e7c3c5cb9d2f0222f7e572ebb1fec054f46848d
-  data.tar.gz: a3d5593e00f2b3b2fcbe76b5035c627494a958bfa264cd809f05e428d39e1c8a
+  metadata.gz: e2273979e57b9e1e415bc9dc13be44e17382d0fb4dfde43b71e3e21d496f379b
+  data.tar.gz: 73bf40a88cdb03f4fa1d8cdb1ec852db6348d45439a88dad0a61501ff519977c
 SHA512:
-  metadata.gz: f2be117cdf827d36ce613506e948ec585aaebd59cabf15a06fd2ad6c6999e636c2fd021fbc7f7cf8efe093bbe48a1324f750ded8a74fd6387a42ddd7b2a77816
-  data.tar.gz: d17ec7a2a5e672af4eb9594ce10390a5e32b932ec4b63a1e811901979f8bf11b3dd83a527ab8bd1088b6af0e49bc280e97e8e28324bafcea0117170687ca62a1
+  metadata.gz: 60465cdf6da291268f439dfb9864e15a54460eb93b9b974b4071e38399cc2eed78b1b5a506dad18cd63a6ab069819841dcaca9bd6cc6f0a20388fc3b654cc8de
+  data.tar.gz: 3e2de8a23b90a1fae5e5bb01d312e6495a3274908eb8c18c9169edb8e24fbc4a2b1e493e45976e25e8082dc0418777d1e724022d1ef1065c8f38170555098781

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--readme README.md
+--title "leakferret (Ruby)"
+--no-private
+--charset utf-8
+lib/**/*.rb
+-
+LICENSE.txt

data/README.md

@@ -6,6 +6,9 @@
 
 > MCP-native secret scanner — verified findings, agent-applied rewrites.
 
+[![Gem Version](https://img.shields.io/gem/v/leakferret?logo=rubygems&logoColor=white)](https://rubygems.org/gems/leakferret)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/leakferrethq/leakferret/blob/master/LICENSE.txt)
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/leakferrethq/leakferret/master/brand/demo.gif" alt="leakferret finds, verifies, and rewrites a leaked secret" width="760">
 </p>

data/lib/leakferret/binary.rb

@@ -14,6 +14,8 @@ module Leakferret
   # 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.
+  #
+  # @api private
   module Binary
     # A binary vendored inside the gem, if one was shipped (normally empty).
     BUNDLED_DIR = Pathname.new(__dir__).join('bin').freeze
@@ -40,6 +42,10 @@ module Leakferret
     #   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
+    #
+    # @return [String] absolute path to the executable
+    # @raise [BinaryNotFoundError] if the override is missing, or the binary is
+    #   absent and cannot be downloaded
     def path
       override = ENV['LEAKFERRET_BIN']
       unless override.nil? || override.empty?
@@ -63,6 +69,8 @@ module Leakferret
 
     # 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?
@@ -73,17 +81,25 @@ module Leakferret
       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 and unpack the binary into the cache. Idempotent: a no-op when
-    # the binary is already cached. Returns the path; raises on failure.
+    # 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?
@@ -138,6 +154,11 @@ module Leakferret
       dest.to_s
     end
 
+    # Human-readable fallback message shown when the binary is absent and the
+    # automatic download failed.
+    #
+    # @param candidate [Pathname] the cache path the binary was expected at
+    # @return [String] multi-line manual-install instructions
     def install_instructions(candidate)
       <<~MSG
         leakferret native binary not found, and the automatic download failed.

data/lib/leakferret/client.rb

@@ -4,18 +4,47 @@ require 'json'
 require 'open3'
 
 module Leakferret
-  # Thin shell-out wrapper. Each public method invokes the binary with
-  # `--format json` and parses the resulting array.
+  # Thin shell-out wrapper around the native binary. Each public method invokes
+  # `leakferret <verb> --format json` and parses the resulting array. You
+  # normally call the module-level {Leakferret.scan}, {Leakferret.verify}, and
+  # {Leakferret.rewrite} helpers instead of constructing this directly.
   class Client
+    # Run a scan-only pass (regex pre-filter, offline).
+    #
+    # @param path [String] file or directory to scan
+    # @param exclude [Array<String>] glob(s) to skip
+    # @param only [Array<String>, String, nil] restrict the scan to these path(s)
+    # @param show_fixtures [Boolean] include catalog fixtures in the result
+    # @return [Array<Hash>] candidate finding hashes
+    # @raise [BinaryInvocationError] on an unexpected exit status
     def scan(path, exclude: [], only: nil, show_fixtures: false)
       run(['scan', path, '--format', 'json'] + format_flags(exclude:, only:, show_fixtures:))
     end
 
+    # Run scan + classify + provider verification.
+    #
+    # @param path [String] file or directory to scan
+    # @param mode [String] verify mode passed to `--verify-mode`
+    # @param timeout [Integer] per-verifier timeout in seconds
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @option opts [Boolean] :show_fixtures include catalog fixtures
+    # @return [Array<Hash>] findings with verification and verdict filled in
+    # @raise [BinaryInvocationError] on an unexpected exit status
     def verify(path, mode: 'best-effort', timeout: 10, **opts)
       run(['verify', path, '--format', 'json', '--verify-mode', mode,
            '--verifier-timeout-secs', timeout.to_s] + format_flags(**opts))
     end
 
+    # Run scan + classify + rewrite proposal.
+    #
+    # @param path [String] file or directory to scan
+    # @param apply [Boolean] write the rewrites in place when true
+    # @param backend [String] rewrite backend (e.g. `env`, `doppler`)
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @return [Array<Hash>] findings, each with a proposed replacement
+    # @raise [BinaryInvocationError] on an unexpected exit status
     def rewrite(path, apply: false, backend: 'env', **opts)
       args = ['rewrite', path, '--format', 'json', '--backend', backend]
       args << '--apply' if apply
@@ -24,6 +53,10 @@ module Leakferret
 
     private
 
+    # Build the shared `--exclude` / `--only` / `--show-fixtures` flag list.
+    #
+    # @return [Array<String>] CLI flags
+    # @api private
     def format_flags(exclude: [], only: nil, show_fixtures: false)
       flags = []
       Array(exclude).each { |g| flags.push('--exclude', g) }
@@ -32,6 +65,13 @@ module Leakferret
       flags
     end
 
+    # Invoke the binary and parse its JSON output. Exit codes 0 (clean) and 1
+    # (findings present) are both treated as success; any other status raises.
+    #
+    # @param args [Array<String>] argv passed to the binary
+    # @return [Array<Hash>] the parsed findings (empty array when output is blank)
+    # @raise [BinaryInvocationError] if the binary exits with a status other than 0 or 1
+    # @api private
     def run(args)
       out, err, status = Open3.capture3(Binary.path, *args)
       unless [0, 1].include?(status.exitstatus)

data/lib/leakferret/error.rb

@@ -1,11 +1,25 @@
 # frozen_string_literal: true
 
 module Leakferret
+  # Base class for every error this gem raises. Rescue this to catch them all.
   class Error < StandardError; end
+
+  # Raised when the native binary cannot be located or downloaded (no pinned
+  # checksum for the platform, a failed download, or a bad `LEAKFERRET_BIN`).
   class BinaryNotFoundError < Error; end
+
+  # Raised when the binary runs but exits with an unexpected status (anything
+  # other than 0 for a clean run or 1 for findings present).
   class BinaryInvocationError < Error
-    attr_reader :exit_status, :stderr
+    # @return [Integer] the binary's process exit status
+    attr_reader :exit_status
+
+    # @return [String] captured standard error from the failed invocation
+    attr_reader :stderr
 
+    # @param message [String] human-readable error message
+    # @param exit_status [Integer] the binary's exit status
+    # @param stderr [String] captured standard error
     def initialize(message, exit_status:, stderr:)
       super(message)
       @exit_status = exit_status

data/lib/leakferret/platform.rb

@@ -5,9 +5,18 @@ require 'rbconfig'
 require_relative 'error'
 
 module Leakferret
+  # Host detection for picking the right release asset. Maps the running
+  # Ruby's `RbConfig` host to a Rust target triple and binary name.
+  #
+  # @api private
   module Platform
     module_function
 
+    # The Rust target triple for the current host (e.g.
+    # `x86_64-unknown-linux-gnu`).
+    #
+    # @return [String] the target triple
+    # @raise [Error] on an unsupported CPU or OS, or aarch64-linux (no asset yet)
     def triple
       cpu = case RbConfig::CONFIG['host_cpu']
             when /x86_64|amd64|x64/ then 'x86_64'
@@ -29,10 +38,13 @@ module Leakferret
       end
     end
 
+    # Executable name for the current OS.
+    # @return [String] `"leakferret.exe"` on Windows, otherwise `"leakferret"`
     def binary_name
       windows? ? 'leakferret.exe' : 'leakferret'
     end
 
+    # @return [Integer, nil] truthy when the host OS is Windows
     def windows?
       RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
     end

data/lib/leakferret/version.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module Leakferret
-  # The gem's own version.
-  VERSION = '0.1.9'
+  # The gem's own version (what `gem install leakferret` resolves).
+  # @return [String]
+  VERSION = '0.1.10'
 
-  # The native binary release this gem downloads. Tracks the leakferret
-  # core release, which may move independently of the gem's own version
-  # (e.g. a gem-only bugfix).
+  # 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).
+  # @return [String]
   BINARY_VERSION = '0.1.6'
 end

data/lib/leakferret.rb

@@ -9,37 +9,91 @@ require 'leakferret/platform'
 require 'leakferret/binary'
 require 'leakferret/client'
 
-# Ruby wrapper around the native `leakferret` binary.
+# Ruby wrapper around the native `leakferret` secret scanner.
 #
-# The binary is downloaded once per platform at gem install time
-# (`ext/leakferret/extconf.rb`) into `lib/leakferret/bin/`. Subsequent
-# calls shell out to it and parse the JSON output.
+# leakferret finds hardcoded secrets, confirms which ones are actually live by
+# calling the provider, and rewrites them to read from environment variables.
+# This gem is a thin wrapper: the native binary (written in Rust) is downloaded
+# once per platform on first use and cached, then each call shells out to it
+# and parses the JSON it prints. The full secret value never leaves your
+# machine; every finding carries only a redacted `first4...last4` preview.
+#
+# The three top-level methods mirror the CLI verbs and each return an array of
+# finding hashes.
+#
+# @example Scan the working tree
+#   Leakferret.scan(".").each do |f|
+#     puts "#{f['path']}:#{f['line']} #{f['pattern']} [#{f['verdict']}]"
+#   end
+#
+# @example Fail a script on any live secret
+#   exit(1) unless Leakferret.verify(".", mode: "only-verified").empty?
+#
+# @see https://leakferret.com
+# @see https://github.com/leakferrethq/leakferret
 module Leakferret
   class << self
-    # Scan a directory; returns an array of finding hashes.
+    # Scan a path for candidate secrets. This is the regex pre-filter only (no
+    # classification, no verification): the fastest, fully offline pass.
+    #
+    # @param path [String] file or directory to scan, relative or absolute
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @option opts [Boolean] :show_fixtures (false) include catalog fixtures in the result
+    # @return [Array<Hash>] candidate findings, each with `path`, `line`,
+    #   `pattern`, `verdict`, and `match_redacted` keys
+    # @raise [BinaryInvocationError] if the binary exits with an unexpected status
+    # @example
+    #   Leakferret.scan("app/", exclude: ["**/*_test.rb"])
     def scan(path = '.', **opts)
       Client.new.scan(path, **opts)
     end
 
-    # Scan + verify + classify; returns findings with verification +
-    # verdict filled in.
+    # Scan, classify, and verify. Real findings are confirmed live with a
+    # harmless API call to the provider (AWS, GitHub, Stripe, and others), so
+    # this method makes outbound network requests.
+    #
+    # @param path [String] file or directory to scan
+    # @option opts [String] :mode ("best-effort") verify mode: `none`,
+    #   `best-effort`, `only-verified`, or `ever-verified`
+    # @option opts [Integer] :timeout (10) per-verifier timeout in seconds
+    # @option opts [Array<String>] :exclude glob(s) to skip
+    # @option opts [Array<String>, String] :only restrict the scan to these path(s)
+    # @return [Array<Hash>] findings with `verdict` and `verification` filled in
+    # @raise [BinaryInvocationError] if the binary exits with an unexpected status
+    # @example Only return secrets confirmed live
+    #   Leakferret.verify(".", mode: "only-verified")
     def verify(path = '.', **opts)
       Client.new.verify(path, **opts)
     end
 
-    # Scan + classify + propose rewrites for REAL findings. Use
-    # apply: true to write the rewrites in place.
+    # Scan, classify, and propose environment-variable rewrites for real
+    # findings. Pass `apply: true` to write the rewrites to disk in place.
+    #
+    # @param path [String] file or directory to scan
+    # @param apply [Boolean] when true, edit files in place; otherwise only
+    #   propose the replacements
+    # @option opts [String] :backend ("env") rewrite backend, e.g. `env`, `doppler`
+    # @return [Array<Hash>] findings, each with a `replacement` proposal attached
+    # @raise [BinaryInvocationError] if the binary exits with an unexpected status
+    # @example Apply rewrites and seed Doppler
+    #   Leakferret.rewrite(".", apply: true, backend: "doppler")
     def rewrite(path = '.', apply: false, **opts)
       Client.new.rewrite(path, apply: apply, **opts)
     end
 
-    # Path to the bundled binary. Useful for tooling integration.
+    # Absolute path to the native binary, downloading it on first use.
+    #
+    # @return [String] absolute filesystem path to the `leakferret` executable
+    # @raise [BinaryNotFoundError] if the binary is missing and cannot be fetched
     def binary_path
       Binary.path
     end
 
-    # Version reported by the bundled binary (Rust) — may differ from
-    # the gem version during pre-release.
+    # Version string reported by the bundled native binary. May differ from
+    # {VERSION} (the gem's own version) during pre-release; see {BINARY_VERSION}.
+    #
+    # @return [String] the binary's `--version` output, stripped
     def binary_version
       out, _err, _status = Open3.capture3(binary_path, '--version')
       out.strip

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: leakferret
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Maria Khan
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   Context-aware secret scanning for Ruby projects. A thin wrapper around the
@@ -27,6 +26,7 @@ extensions:
 - ext/leakferret/extconf.rb
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE.txt
 - README.md
 - exe/leakferret
@@ -44,8 +44,8 @@ metadata:
   homepage_uri: https://github.com/leakferrethq/leakferret-ruby
   source_code_uri: https://github.com/leakferrethq/leakferret-ruby
   changelog_uri: https://github.com/leakferrethq/leakferret-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/leakferret
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -60,8 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Context-aware secret detection (Ruby wrapper for the leakferret binary).
 test_files: []