scrubber_rb 0.1.0

data/README.md

@@ -0,0 +1,298 @@
+# scrubber_rb
+
+> Fast PII & secret redaction for Ruby — Rust-cored. Scrub logs, LLM prompts, and payloads before they leak.
+
+[![Gem Version](https://badge.fury.io/rb/scrubber_rb.svg)](https://rubygems.org/gems/scrubber_rb)
+[![CI](https://github.com/TheSoloHacker47/scrubber-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/TheSoloHacker47/scrubber-rb/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Your production logs contain emails. Your error tracker captures request params with credit
+cards in them. And now your app pipes user content straight into LLM APIs. `scrubber_rb`
+redacts sensitive data from any string in a single pass through a Rust engine — fast enough
+to sit in your logger, your Rack stack, and in front of every AI call.
+
+```ruby
+Scrubber.scrub("contact nik@example.com, card 4111 1111 1111 1111, key AKIAIOSFODNN7EXAMPLE")
+# => "contact [EMAIL], card [CREDIT_CARD], key [AWS_KEY]"
+```
+
+## Why this gem
+
+- **Fast.** Multi-pattern scanning runs in Rust (`regex` + `aho-corasick`) — one pass, no
+  backtracking, GVL released on large inputs. Measured **38x** a pure-Ruby implementation of
+  the identical detector set on a 100MB log corpus, and **83x** on a single log line
+  ([methodology below](#benchmarks), reproducible via `rake benchmark`).
+- **Accurate.** Checksums, not just shapes: credit cards must pass Luhn, Aadhaar must pass
+  Verhoeff, IBANs must pass mod-97. A random 16-digit number won't get redacted.
+- **Complete.** 18 detectors out of the box — emails, phones, cards, SSNs, IBANs, IPs, MACs,
+  JWTs, AWS keys, 19 provider-specific API key formats, private key blocks, `password=` pairs,
+  URL credentials — plus an opt-in India pack (Aadhaar, PAN, UPI) for DPDP Act compliance.
+- **ReDoS-immune.** Rust's regex engine is linear-time by design, so attacker-controlled log
+  content can't blow up your CPU with pathological backtracking.
+- **No toolchain needed.** Precompiled gems for Linux (x86_64/aarch64, glibc & musl) and
+  macOS (Intel & Apple Silicon). `gem install scrubber_rb` and you're done.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "scrubber_rb"
+```
+
+Requires Ruby >= 3.1. If no precompiled gem matches your platform, the source gem builds
+automatically (needs a Rust toolchain).
+
+## Usage
+
+### Basic
+
+```ruby
+Scrubber.scrub(text)     # default detectors, [LABEL] replacement
+Scrubber.detect(text)    # => [#<Scrubber::Match type=:email 11...26 preview="n**@e******.com">]
+Scrubber.match?(text)    # => true/false, without building the redacted string
+```
+
+### Reusable instance (the fast path)
+
+Compile once, scrub millions of times. Compiling ~45 patterns into one automaton is the
+expensive part; scanning is cheap.
+
+```ruby
+SCRUBBER = Scrubber.new(
+  detectors:   Scrubber::DEFAULTS + Scrubber::INDIA,
+  custom:      { employee_id: /\bEMP-\d{6}\b/ },
+  replacement: :hash                                  # deterministic tokens — logs stay correlatable
+)
+
+SCRUBBER.scrub("refund to nik@example.com")           # => "refund to [EMAIL:1efaf05b]"
+SCRUBBER.scrub("refund to nik@example.com")           # => same token — grep still works
+```
+
+Instances are frozen and hold no per-call state, so one instance is safe to share across every
+thread in the process. The module-level `Scrubber.scrub` memoizes one engine per distinct
+configuration, so it's fine too — the explicit instance just makes the lifetime obvious.
+
+### Replacement strategies
+
+| strategy | `nik@example.com` | `4111 1111 1111 1111` | `AKIA…EXAMPLE` |
+|---|---|---|---|
+| `:label` (default) | `[EMAIL]` | `[CREDIT_CARD]` | `[AWS_KEY]` |
+| `:mask` | `n**@e******.com` | `**** **** **** 1111` | `********************` |
+| `:hash` | `[EMAIL:1efaf05b]` | `[CREDIT_CARD:6a7e0e79]` | `[AWS_KEY:1a5d44a2]` |
+| `:remove` | *(deleted)* | *(deleted)* | *(deleted)* |
+
+`:mask` keeps the last four characters of *identifiers* so a human can still recognise the
+record, and reveals nothing at all for *secrets* — the last four characters of an API key are
+a leak, not a convenience.
+
+`:hash` is `sha256(salt + value)[0, 8]`. Same input, same token, across processes and days, so
+logs stay correlatable without holding the value. Pass `hash_salt:` to scope tokens per tenant
+or per environment.
+
+### Rails logs — one line
+
+```ruby
+# config/initializers/scrubber.rb
+Rails.logger.formatter = Scrubber::LogFormatter.new(Rails.logger.formatter)
+```
+
+Wrapping the *formatter* rather than the logger catches everything: your own
+`Rails.logger.info`, Active Record's SQL echo, Rack's request lines, and the exception messages
+your error middleware logs on the way out.
+
+### Rack middleware
+
+```ruby
+use Scrubber::Middleware
+```
+
+The middleware is deliberately **non-destructive**. It does not rewrite `QUERY_STRING`,
+`rack.input`, or `params` — redacting the request your application is about to act on would
+break every login form in the world, because the app needs the real password to check it.
+What leaks is not the request, it's the *record* of the request.
+
+So it publishes redacted copies for you to record, and cleans exceptions on the way out:
+
+```ruby
+env["scrubber.query_string"]  # "user=nik&password=[PASSWORD_PAIR]"
+env["scrubber.params"]        # { "user" => "nik", "password" => "[PASSWORD_PAIR]" }
+env["scrubber.instance"]      # the engine, for anything else you want to log
+```
+
+Any exception raised downstream is re-raised with a redacted message (same class, same
+backtrace), so an error tracker that has never heard of this gem still gets a clean payload.
+Turn that off with `use Scrubber::Middleware, scrub_exceptions: false`.
+
+### Before your LLM calls
+
+Stop shipping raw customer PII to third-party AI APIs:
+
+```ruby
+guard = Scrubber::LLMGuard.new           # defaults to :hash
+
+chat.ask(guard.call(user_message))
+```
+
+`LLMGuard` is a plain callable that preserves the shape of what you give it — a String, a
+message Array, or a message Hash — so it drops into RubyLLM, langchainrb, ruby-openai,
+anthropic-sdk-ruby, or a hand-rolled `Net::HTTP` call the same way:
+
+```ruby
+messages = [
+  { role: "system", content: "You are a support agent." },
+  { role: "user",   content: "my email is nik@example.com and my card is 4111 1111 1111 1111" }
+]
+
+client.chat(messages: guard.call(messages))
+# => user content becomes "my email is [EMAIL:1efaf05b] and my card is [CREDIT_CARD:6a7e0e79]"
+```
+
+Deterministic `:hash` tokens mean the model can still refer to "the same email" across a
+conversation without ever seeing it. `guard.findings(messages)` returns what *would* be
+redacted, if you want a "we blocked N leaks today" metric or a test that fails when a prompt
+builder regresses.
+
+> **On RubyLLM:** as of August 2026 RubyLLM has no public middleware or interceptor hook, so
+> this gem ships the wrapper pattern above rather than a plugin. Wrapping the argument at the
+> call site is one line and doesn't depend on RubyLLM internals staying put.
+
+### Big files
+
+```ruby
+Scrubber.scrub_file("production.log", "production.scrubbed.log")
+```
+
+Streams in 1MB chunks with an 8KB carry window, cutting at line boundaries so a match spanning
+a chunk boundary is never sliced in half (multi-line PEM blocks get an extra guard). Releases
+the GVL for inputs over 64KB, so your Puma threads keep serving.
+
+## Detectors
+
+| Default | Opt-in (India pack) |
+|---|---|
+| `email`, `phone`, `credit_card` (Luhn), `ssn`, `iban` (mod-97), `ip`, `ipv6`, `mac`, `jwt`, `aws_key`, `api_key`, `private_key`, `password_pair`, `url_credentials` | `phone_in`, `aadhaar` (Verhoeff), `pan`, `upi` |
+
+```ruby
+Scrubber.new(detectors: Scrubber::DEFAULTS + Scrubber::INDIA)
+Scrubber.new(detectors: %i[email credit_card])   # narrow it down for hot paths
+Scrubber::ALL                                    # everything
+```
+
+`:api_key` covers 19 provider-specific formats (GitHub, GitLab, Slack, Stripe, OpenAI,
+Anthropic, Google, SendGrid, Twilio, npm, PyPI, Shopify, Square, Mailgun, DigitalOcean,
+Telegram, AWS secret keys). All of them are structurally unambiguous vendor formats — there is
+no entropy heuristic, because those false-positive on git SHAs and UUIDs.
+
+Add your own with `custom: { name: /regexp/ }`. Ruby patterns are translated to Rust regex
+syntax; unsupported constructs (backreferences, lookaround, atomic groups, possessive
+quantifiers) raise `Scrubber::UnsupportedPatternError` at construction time, naming the
+construct. You will never get silent partial coverage.
+
+```ruby
+Scrubber.new(custom: { dupe: /(\w)\1/ })
+# => Scrubber::UnsupportedPatternError: custom detector "dupe" uses \1, which this engine
+#    cannot compile: backreferences require backtracking.
+```
+
+### Overlapping matches
+
+When two detectors cover the same span, the more specific one wins: `password=ghp_…` reports
+`[API_KEY]`, not `[PASSWORD_PAIR]`. Redaction is always the same either way; only the label
+differs. Scrubbing already-scrubbed text is a no-op, so nested middleware won't corrupt lines.
+
+## Benchmarks
+
+<!-- BENCHMARK:START -->
+<!-- generated by `rake benchmark`; do not edit by hand -->
+
+| implementation | throughput | relative |
+|---|---|---|
+| scrubber_rb (Rust core) | **50.4 MB/s** | 1.0x |
+| pure-Ruby reference (identical detectors) | 1.3 MB/s | 38.2x slower |
+
+100MB synthetic log corpus (seed 42), all 14 default detectors, single thread, ruby 3.3.0 on arm64-darwin24.
+Best of 2 passes. Reproduce with `rake benchmark`.
+<!-- BENCHMARK:END -->
+
+Per-line latency, which is what matters when this sits in your logger:
+
+| implementation | one log line | relative |
+|---|---|---|
+| scrubber_rb | **1.24 µs** | 1.0x |
+| pure-Ruby reference | 102.98 µs | 83x slower |
+
+A Rust scan costs about a microsecond per log line, which is why it is safe to put on the
+write path of every `Rails.logger` call.
+
+**Methodology**, because a benchmark you can't audit is marketing:
+
+- The baseline in `benchmark/pure_ruby_reference.rb` implements the **identical detector set**
+  — same patterns, same Luhn/Verhoeff/mod-97 checksums, same context validators, same
+  capture-group behaviour. It is written as good Ruby, not a strawman: one combined `Regexp`,
+  one `gsub` pass, no per-detector loop.
+- `spec/benchmark_reference_spec.rb` asserts the two implementations **redact identical spans**
+  on every fixture and on a slice of the corpus. If someone tightens a Rust detector and
+  forgets the reference, the suite fails before anyone reads this table.
+- The corpus is seeded synthetic production-shaped logs (`benchmark/corpus/generate.rb`), ~12%
+  of lines carrying something redactable. Raising that rate would flatter the Rust engine,
+  since pure Ruby is fastest on lines with no matches.
+- Throughput is the best of N single-threaded full passes. CI enforces a 5x regression floor
+  (`rake benchmark:gate`) rather than restating the headline number, because shared runners
+  are noisy.
+
+The difference is architectural, not micro-optimisation. Ruby's Onigmo is a backtracking
+engine with no `RegexSet` and no Aho-Corasick prefilter, so every rule in the alternation is
+live on every byte. The Rust core runs one Aho-Corasick pass over the literal anchors
+(`AKIA`, `-----BEGIN`, `ghp_`, `password`) to eliminate roughly two thirds of the rules before
+any regex runs, then one `RegexSet` pass for the rest.
+
+`logstop` solves a narrower problem (log filtering, pure Ruby, zero native code) and solves it
+well. If that's all you need, use it — it has no native extension to build. Run
+`rake benchmark:logstop` for a scope-matched comparison.
+
+## Security
+
+- **ReDoS.** Rust's `regex` crate is a finite-automata engine with no backtracking, so match
+  time is linear in input length regardless of the pattern. Attacker-controlled log content
+  cannot pin a CPU. Custom Ruby patterns are checked at construction and rejected if they
+  require backtracking, so you can't reintroduce the problem through the back door.
+- **Panics.** Every FFI entry point is wrapped in `catch_unwind`. A bug in the Rust core
+  becomes a `Scrubber::InternalError`, never a process abort.
+- **Invalid UTF-8.** Scanning steps over invalid byte sequences and passes them through
+  unchanged, so a corrupt log line is scrubbed where it can be and never raises.
+- **No network, no persistence, no telemetry.** It's a pure function library.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## What this gem does NOT do
+
+Deterministic patterns can't catch free-form PII — **names, home addresses, medical notes**.
+That's NER-model territory. We'd rather be honest about this than give you false confidence.
+
+If your threat model includes free-text PII, layer a model-based pass behind this gem's fast
+structural pass: [`top_secret`](https://github.com/thoughtbot/top_secret) and its
+[`ruby_llm-top_secret`](https://github.com/thoughtbot/ruby_llm-top_secret) integration cover
+that ground in Ruby, and Microsoft Presidio does in Python. Structural first (fast, exact),
+model second (slow, fuzzy) is the right order.
+
+## Compatibility
+
+Ruby 3.1–3.4 · Linux (x86_64, aarch64; glibc & musl) · macOS (Intel, Apple Silicon) ·
+Windows best-effort. CI runs the full matrix plus a weekly ruby-head canary.
+
+## Contributing
+
+```bash
+git clone https://github.com/TheSoloHacker47/scrubber-rb && cd scrubber-rb
+bin/setup                  # bundle install + rake compile
+bundle exec rake           # compile + spec
+bundle exec rake ci        # everything CI runs, in CI's order
+```
+
+New detector proposals are welcome — include public test vectors and a false-positive analysis
+in the PR. See [CONTRIBUTING.md](CONTRIBUTING.md), and [docs/RELEASING.md](docs/RELEASING.md)
+for how a release is cut.
+
+## License
+
+[MIT](LICENSE).

data/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 0.1.x | ✅ |
+
+Until 1.0, security fixes land on the latest minor release.
+
+## Reporting a vulnerability
+
+Please **do not open a public issue.**
+
+Use GitHub's private reporting:
+[Report a vulnerability](https://github.com/TheSoloHacker47/scrubber-rb/security/advisories/new)
+
+Or email **thesolohacker47@gmail.com**.
+
+Please include a minimal reproduction and the version you're on. You'll get an
+acknowledgement within 72 hours and an assessment within a week.
+
+## What counts as a vulnerability here
+
+This gem's job is to remove sensitive data from text. So:
+
+- **A false negative is a security bug.** If input containing a credential or PII in a
+  supported format comes back unredacted, that's a vulnerability, not a feature request —
+  especially if the input is attacker-controlled and shaped to evade a detector (unusual
+  encodings, separator tricks, boundary manipulation).
+- **A partial redaction is a security bug.** Output that leaves part of a secret visible.
+- **A ReDoS or unbounded-resource path is a vulnerability.** The Rust `regex` crate is
+  linear-time, so this should be impossible for built-in detectors; if you find input that
+  makes scanning superlinear, we want to know.
+- **A panic or crash across the FFI boundary is a vulnerability.** Every entry point is
+  wrapped in `catch_unwind` and should surface as `Scrubber::InternalError`. A process abort
+  means the wrapping failed.
+- **Memory unsafety** in the native extension — use-after-free, out-of-bounds read, a data
+  race in the shared `Engine`.
+
+## What does not count
+
+- **Free-form PII going unredacted.** Names, street addresses, and medical notes are an
+  explicit non-goal, stated in the README. Deterministic patterns cannot find them; that needs
+  an NER model. This isn't a bug, it's the documented scope.
+- **A false positive.** Over-redacting is annoying and we'll fix it, but it doesn't leak
+  anything. Open a normal issue.
+- **Data your configuration didn't ask for.** If `:aadhaar` isn't in your `detectors:` list,
+  Aadhaar numbers won't be redacted. Check your configuration before reporting.
+
+## When you report
+
+Please redact your own reproduction input before sending it. If the input is a real credential,
+rotate it first — a bug report is not a safe place for a live key.

data/ext/scrubber_rb/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "scrubber_rb"
+version = "0.1.0"
+edition = "2021"
+authors = ["Nikhil Nelson <thesolohacker47@gmail.com>"]
+license = "MIT"
+description = "Rust core for the scrubber_rb Ruby gem: fast PII and secret redaction"
+repository = "https://github.com/TheSoloHacker47/scrubber-rb"
+publish = false
+rust-version = "1.74"
+
+[lib]
+name = "scrubber_rb"
+# cdylib only. Nothing links against this crate as a library: the unit tests
+# live in `#[cfg(test)] mod tests` blocks, which `cargo test` compiles into its
+# own harness whatever the crate-type is.
+#
+# Keeping the list to exactly what is needed also keeps failures loud. With
+# "rlib" alongside it, a musl target that cannot build a cdylib silently
+# produced only the rlib and reported success, and the build failed several
+# steps later with a missing-file error that said nothing about the cause.
+crate-type = ["cdylib"]
+
+[features]
+# Link libruby into the built artifacts so `cargo test` can run the pure-Rust
+# unit tests from a plain executable. The shipped extension never enables this:
+# it is loaded *into* a Ruby process, which already has those symbols.
+link-ruby = ["rb-sys/link-ruby"]
+
+[dependencies]
+magnus = "0.7"
+rb-sys = "0.9"
+regex = "1.10"
+aho-corasick = "1.1"
+sha2 = "0.10"
+
+[build-dependencies]
+rb-sys-env = "0.1"
+
+[dev-dependencies]
+proptest = "1"

data/ext/scrubber_rb/build.rs

@@ -0,0 +1,6 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Exposes the `ruby_lt_3_2` / `ruby_gte_3_1` style cfgs and, more
+    // importantly, the link flags the extension needs on each platform.
+    let _ = rb_sys_env::activate()?;
+    Ok(())
+}

data/ext/scrubber_rb/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("scrubber_rb/scrubber_rb")

data/ext/scrubber_rb/src/detectors/checksum.rs

@@ -0,0 +1,222 @@
+//! Checksum validators.
+//!
+//! These are what separate `scrubber_rb` from a pile of regexes: a 16-digit
+//! number is only redacted as a credit card if it actually passes Luhn, and a
+//! 12-digit number is only an Aadhaar if it passes Verhoeff. Shapes lie;
+//! checksums do not.
+
+/// Luhn (mod-10) checksum, used by credit / debit card PANs.
+///
+/// Accepts an iterator of ASCII digit characters; non-digits must already be
+/// stripped by the caller.
+pub fn luhn(digits: &[u8]) -> bool {
+    if digits.len() < 12 {
+        return false;
+    }
+    let mut sum: u32 = 0;
+    // Double every second digit counting from the right.
+    for (i, d) in digits.iter().rev().enumerate() {
+        let mut v = u32::from(*d);
+        if i % 2 == 1 {
+            v *= 2;
+            if v > 9 {
+                v -= 9;
+            }
+        }
+        sum += v;
+    }
+    sum % 10 == 0
+}
+
+// Verhoeff tables. `D` is the dihedral group D5 multiplication table, `P` the
+// permutation table, `INV` the multiplicative inverse table.
+#[rustfmt::skip]
+const VERHOEFF_D: [[u8; 10]; 10] = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+    [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+    [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+    [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+    [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+    [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+    [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+];
+
+#[rustfmt::skip]
+const VERHOEFF_P: [[u8; 10]; 8] = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+    [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+    [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+    [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+    [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+    [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+];
+
+/// Verhoeff checksum, used by the Indian Aadhaar number.
+pub fn verhoeff(digits: &[u8]) -> bool {
+    let mut c: u8 = 0;
+    for (i, d) in digits.iter().rev().enumerate() {
+        if *d > 9 {
+            return false;
+        }
+        c = VERHOEFF_D[c as usize][VERHOEFF_P[i % 8][*d as usize] as usize];
+    }
+    c == 0
+}
+
+/// ISO 7064 mod-97-10, used by IBAN account numbers.
+///
+/// `s` is the raw IBAN with separators already stripped and letters uppercased.
+pub fn iban_mod97(s: &[u8]) -> bool {
+    if s.len() < 15 || s.len() > 34 {
+        return false;
+    }
+    // Move the first four characters to the end, then map A-Z to 10-35 and take
+    // the whole thing mod 97 incrementally (the number is far too big for u128).
+    let rotated = s[4..].iter().chain(s[..4].iter());
+    let mut rem: u32 = 0;
+    for ch in rotated {
+        let val = match ch {
+            b'0'..=b'9' => u32::from(ch - b'0'),
+            b'A'..=b'Z' => u32::from(ch - b'A') + 10,
+            _ => return false,
+        };
+        // Feed one or two decimal digits depending on the mapped value.
+        if val >= 10 {
+            rem = (rem * 100 + val) % 97;
+        } else {
+            rem = (rem * 10 + val) % 97;
+        }
+    }
+    rem == 1
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn d(s: &str) -> Vec<u8> {
+        s.bytes()
+            .filter(u8::is_ascii_digit)
+            .map(|b| b - b'0')
+            .collect()
+    }
+
+    #[test]
+    fn luhn_known_good_vectors() {
+        // Publicly published test card numbers.
+        for good in [
+            "4111111111111111", // Visa
+            "4012888888881881", // Visa
+            "5500005555555559", // Mastercard
+            "5105105105105100", // Mastercard
+            "378282246310005",  // Amex
+            "371449635398431",  // Amex
+            "6011111111111117", // Discover
+            "3530111333300000", // JCB
+        ] {
+            assert!(luhn(&d(good)), "{good} should pass Luhn");
+        }
+    }
+
+    #[test]
+    fn luhn_rejects_bad_check_digits() {
+        for bad in [
+            "4111111111111112",
+            "1234567890123456",
+            "0000000000000001",
+            "5500005555555558",
+        ] {
+            assert!(!luhn(&d(bad)), "{bad} should fail Luhn");
+        }
+    }
+
+    #[test]
+    fn luhn_rejects_short_input() {
+        assert!(!luhn(&d("12345678901")));
+    }
+
+    // Multiplicative inverse table for D5, used only to *generate* valid test
+    // vectors so the tests don't depend on hand-copied numbers.
+    const INV: [u8; 10] = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9];
+
+    fn with_check_digit(payload: &str) -> Vec<u8> {
+        let mut digits = d(payload);
+        let mut c: u8 = 0;
+        for (i, dg) in digits.iter().rev().enumerate() {
+            c = VERHOEFF_D[c as usize][VERHOEFF_P[(i + 1) % 8][*dg as usize] as usize];
+        }
+        digits.push(INV[c as usize]);
+        digits
+    }
+
+    #[test]
+    fn verhoeff_known_vectors() {
+        // Verhoeff's own published example: the check digit for 236 is 3.
+        assert!(verhoeff(&d("2363")));
+        assert!(!verhoeff(&d("2364")));
+    }
+
+    #[test]
+    fn verhoeff_accepts_generated_check_digits() {
+        for payload in ["23678901234", "99988877766", "20000000000", "61234567890"] {
+            let full = with_check_digit(payload);
+            assert_eq!(full.len(), 12);
+            assert!(verhoeff(&full), "{payload} + check digit should validate");
+        }
+    }
+
+    #[test]
+    fn verhoeff_rejects_transpositions_and_single_digit_errors() {
+        // Verhoeff catches all single-digit errors and all adjacent transpositions.
+        let base = with_check_digit("23678901234");
+        assert!(verhoeff(&base));
+        for i in 0..base.len() - 1 {
+            if base[i] == base[i + 1] {
+                continue;
+            }
+            let mut swapped = base.clone();
+            swapped.swap(i, i + 1);
+            assert!(!verhoeff(&swapped), "transposition at {i} should fail");
+        }
+        for i in 0..base.len() {
+            let mut bumped = base.clone();
+            bumped[i] = (bumped[i] + 1) % 10;
+            assert!(!verhoeff(&bumped), "single-digit error at {i} should fail");
+        }
+    }
+
+    #[test]
+    fn iban_known_vectors() {
+        for good in [
+            "GB82WEST12345698765432",
+            "DE89370400440532013000",
+            "FR1420041010050500013M02606",
+            "NL91ABNA0417164300",
+            "CH9300762011623852957",
+        ] {
+            assert!(iban_mod97(good.as_bytes()), "{good} should pass mod-97");
+        }
+    }
+
+    #[test]
+    fn iban_rejects_bad_checksums() {
+        for bad in [
+            "GB82WEST12345698765431",
+            "DE89370400440532013001",
+            "XX00NOTANIBANATALL0000",
+        ] {
+            assert!(!iban_mod97(bad.as_bytes()), "{bad} should fail mod-97");
+        }
+    }
+
+    #[test]
+    fn iban_rejects_out_of_range_lengths() {
+        assert!(!iban_mod97(b"GB82WEST"));
+        assert!(!iban_mod97(&[b'A'; 40]));
+    }
+}