data_redactor 0.5.0 → 0.7.0

data/lib/data_redactor.rb

@@ -1,7 +1,42 @@
+require "set"
 require_relative "data_redactor/version"
 require_relative "data_redactor/data_redactor" # loads the compiled .so
 
+# High-performance regex-based redactor for sensitive data.
+#
+# DataRedactor scans text for sensitive patterns (API keys, IBANs, national
+# IDs, emails, phone numbers, etc.) and replaces matches with a configurable
+# placeholder. The matching is done by a C extension backed by POSIX
+# +regex.h+, so it is fast enough to run inline on large payloads.
+#
+# @example Basic redaction
+#   DataRedactor.redact("key is AKIAIOSFODNN7EXAMPLE")
+#   # => "key is [REDACTED]"
+#
+# @example Filter by tag or pattern name
+#   DataRedactor.redact(text, only: :credentials)
+#   DataRedactor.redact(text, except: [:contact, :network])
+#   DataRedactor.redact(text, only: :contact, except: ["email"])
+#   DataRedactor.redact(text, only: ["aws_access_key_id"])
+#
+# @example Custom placeholder
+#   DataRedactor.redact(text, placeholder: "***")
+#   DataRedactor.redact(text, placeholder: :tagged) # => "[REDACTED:CONTACT]"
+#   DataRedactor.redact(text, placeholder: :hash)   # => "[CONTACT_a3f9]"
+#
+# @example Audit / dry-run
+#   DataRedactor.scan(text)
+#   # => { redacted: "...", matches: [{tag:, name:, value:, start:, length:}, ...] }
+#
+# @example Custom pattern
+#   DataRedactor.add_pattern(name: "employee_id", regex: "EMP-[0-9]{6}")
 module DataRedactor
+  # Map of tag symbol to the integer bit used by the C layer.
+  #
+  # The keys of this hash are the canonical list of supported tags; pass any
+  # of them to {redact} or {scan} via +only:+ / +except:+.
+  #
+  # @return [Hash{Symbol => Integer}] frozen tag-to-bit map
   TAGS = {
     credentials: TAG_CREDENTIALS,
     financial:   TAG_FINANCIAL,
@@ -14,70 +49,148 @@ module DataRedactor
     custom:      TAG_CUSTOM
   }.freeze
 
+  # Raised when a tag symbol passed to +only:+ / +except:+ / +tag:+ is not in {TAGS}.
   class UnknownTagError     < ArgumentError; end
+
+  # Raised when a String passed via +only:+ / +except:+ does not match any
+  # registered pattern name. See {pattern_names}.
+  class UnknownPatternError < ArgumentError; end
+
+  # Raised by {add_pattern} when the supplied regex is not valid POSIX ERE,
+  # uses Ruby-only syntax (+\d+, +\s+, lookaround, non-greedy, etc.), or
+  # contains capture groups while +boundary: true+ is requested.
   class InvalidPatternError < ArgumentError; end
 
+  # @api private
   # Capture groups break boundary-wrapper group index assumptions ([1],[2],[3] shift).
   CAPTURE_GROUP_RE = /(?<!\\)\((?!\?:)/.freeze
 
+  # @api private
   # Ruby regex syntax that has no POSIX ERE equivalent.
   RUBY_ONLY_SYNTAX_RE = /\\[dDwWsShHbB]|\(\?[<!=]|\(\?<[a-zA-Z]|\(\?[imx]|[*+?]\?/.freeze
 
+  # Default placeholder used when +placeholder:+ is not given to {redact}.
   PLACEHOLDER_DEFAULT = "[REDACTED]"
 
   module_function
 
+  # List of supported tag symbols.
+  #
+  # @return [Array<Symbol>] every key from {TAGS}
   def tags
     TAGS.keys
   end
 
-  def redact(text, only: nil, except: nil, placeholder: PLACEHOLDER_DEFAULT)
-    raise ArgumentError, "pass only: or except:, not both" if only && except
-
-    mask =
-      if only
-        bits_for(only)
-      elsif except
-        TAG_ALL & ~bits_for(except)
-      else
-        TAG_ALL
-      end
+  # List of every pattern name the redactor knows about.
+  #
+  # Includes the {BUILTIN_PATTERN_NAMES} plus any names registered via
+  # {add_pattern}. Useful for discovering what String values +only:+ /
+  # +except:+ accept, and for filtering / debugging.
+  #
+  # @return [Array<String>] built-in names first (in execution order),
+  #   then custom names in registration order.
+  def pattern_names
+    BUILTIN_PATTERN_NAMES + _custom_patterns.map { |h| h[:name] }
+  end
 
+  # Redact every match of the configured patterns in +text+.
+  #
+  # +only:+ and +except:+ both accept a single value or an Array, mixing:
+  # - **Symbols** — tag names from {TAGS} (e.g. +:contact+, +:credentials+).
+  # - **Strings** — specific pattern names from {pattern_names} (e.g. +"email"+).
+  #
+  # They can be combined: +only: :contact, except: ["email"]+ means
+  # "redact every contact pattern except email." Symbols give you tag-level
+  # control; Strings give you per-pattern precision.
+  #
+  # **Precedence:** a pattern is redacted iff
+  # +(only is nil OR pattern matches only:)+ AND +(pattern does not match except:)+.
+  # +except:+ always wins over +only:+ when they overlap — e.g.
+  # +only: :contact, except: :contact+ produces an empty redaction (no-op),
+  # and +only: ["email"], except: ["email"]+ likewise skips email entirely.
+  #
+  # @param text [String] input string. Returned unchanged if no patterns match.
+  # @param only [Symbol, String, Array, nil] include only the given tag(s)
+  #   and/or pattern name(s).
+  # @param except [Symbol, String, Array, nil] exclude the given tag(s)
+  #   and/or pattern name(s). May be combined with +only:+.
+  # @param placeholder [String, :tagged, :hash] replacement strategy.
+  #   A String is used verbatim. +:tagged+ produces +[REDACTED:TAGNAME]+.
+  #   +:hash+ produces a deterministic +[TAGNAME_xxxx]+ token (4-hex djb2)
+  #   so the same input value always maps to the same token.
+  # @return [String] a new string with every match replaced.
+  # @raise [ArgumentError] if +placeholder:+ is not a String/:tagged/:hash.
+  # @raise [UnknownTagError] if any Symbol in +only:+/+except:+ is not in {TAGS}.
+  # @raise [UnknownPatternError] if any String in +only:+/+except:+ is not in {pattern_names}.
+  #
+  # @example
+  #   DataRedactor.redact("token sk_live_abc123", only: :credentials)
+  #   DataRedactor.redact(text, only: [:contact, "aws_access_key_id"])
+  #   DataRedactor.redact(text, only: :contact, except: ["email"])
+  def redact(text, only: nil, except: nil, placeholder: PLACEHOLDER_DEFAULT)
+    enable_bits = build_enable_bits(only, except)
     ph_mode, ph_str = resolve_placeholder(placeholder)
-    _redact(text, mask, ph_mode, ph_str)
+    _redact(text, ph_mode, ph_str, enable_bits)
   end
 
-  # Scan text without necessarily redacting it.
+  # Scan +text+ and return both the redacted string and per-match metadata.
+  #
+  # Useful for auditing, false-positive tuning, and compliance pipelines.
+  # +:start+ and +:length+ are byte offsets into the *original* string, so
+  # +text.byteslice(m[:start], m[:length]) == m[:value]+.
   #
-  # Returns { redacted: String, matches: [{tag:, name:, value:, start:, length:}, ...] }
-  # The :tag value is a Symbol matching one of DataRedactor.tags.
-  # :start and :length are byte offsets into the original string.
+  # @param text [String] input string.
+  # @param only [Symbol, String, Array, nil] same semantics as {redact}.
+  # @param except [Symbol, String, Array, nil] same semantics as {redact}.
+  # @return [Hash{Symbol => Object}] +{ redacted: String, matches:
+  #   Array<Hash> }+. Each match hash has +:tag+ (Symbol), +:name+ (String),
+  #   +:value+ (String), +:start+ (Integer byte offset), +:length+ (Integer).
+  # @raise [UnknownTagError] if any Symbol in +only:+/+except:+ is not in {TAGS}.
+  # @raise [UnknownPatternError] if any String in +only:+/+except:+ is not in {pattern_names}.
+  #
+  # @example
+  #   DataRedactor.scan("user@example.com")
+  #   # => { redacted: "[REDACTED]",
+  #   #      matches: [{tag: :contact, name: "email",
+  #   #                 value: "user@example.com", start: 0, length: 16}] }
   def scan(text, only: nil, except: nil)
-    raise ArgumentError, "pass only: or except:, not both" if only && except
-
-    mask =
-      if only
-        bits_for(only)
-      elsif except
-        TAG_ALL & ~bits_for(except)
-      else
-        TAG_ALL
-      end
-
-    result = _scan(text, mask)
+    enable_bits = build_enable_bits(only, except)
+    result = _scan(text, enable_bits)
     # Normalise: convert tag string from C (uppercase) back to the Symbol used in TAGS
-    result[:matches].each do |m|
-      m[:tag] = m[:tag].to_s.downcase.to_sym
-    end
+    result[:matches].each { |m| m[:tag] = m[:tag].to_s.downcase.to_sym }
     result
   end
 
-  # Add (or replace) a custom redaction pattern.
+  # Register a custom redaction pattern.
   #
-  # name:     unique identifier string
-  # regex:    String (POSIX ERE) or Regexp; Ruby-only syntax raises InvalidPatternError
-  # tag:      one of the TAGS keys (default :custom), or any built-in tag
-  # boundary: wrap with word-boundary guards; incompatible with capture groups
+  # Patterns must be valid POSIX ERE. Ruby-only syntax (+\d+, +\s+, +\w+,
+  # +\b+, lookaround, non-greedy quantifiers, named groups) is rejected
+  # at registration time, never at redaction time.
+  #
+  # If a pattern with the same +name+ is already registered, it is replaced
+  # (the old compiled +regex_t+ is freed).
+  #
+  # @param name [String] unique identifier for this pattern. Used by {remove_pattern}.
+  # @param regex [String, Regexp] POSIX ERE source. A Regexp is accepted
+  #   for convenience but only its +.source+ is used; flags are ignored.
+  # @param tag [Symbol] one of {TAGS} keys. Defaults to +:custom+.
+  # @param boundary [Boolean] when true, the pattern is wrapped with
+  #   +(^|[^0-9A-Za-z])(...)([^0-9A-Za-z]|$)+ so it only matches when not
+  #   embedded in a longer alphanumeric token. Incompatible with patterns
+  #   that contain capture groups.
+  # @return [Boolean] +true+ on success.
+  # @raise [ArgumentError] if +name+ is not a non-empty String, or +regex+
+  #   is neither a String nor a Regexp.
+  # @raise [InvalidPatternError] if the pattern uses Ruby-only syntax,
+  #   contains capture groups while +boundary: true+, or fails +regcomp+.
+  # @raise [UnknownTagError] if +tag+ is not in {TAGS}.
+  #
+  # @example
+  #   DataRedactor.add_pattern(name: "employee_id", regex: "EMP-[0-9]{6}")
+  #   DataRedactor.add_pattern(name: "internal_key",
+  #                            regex: /INT-[A-Z]{3}/,
+  #                            tag: :credentials,
+  #                            boundary: true)
   def add_pattern(name:, regex:, tag: :custom, boundary: false)
     raise ArgumentError, "name must be a non-empty String" \
       unless name.is_a?(String) && !name.empty?
@@ -105,10 +218,20 @@ module DataRedactor
     _add_pattern(name, source, tag_bit, boundary ? 1 : 0)
   end
 
+  # Remove a previously registered custom pattern.
+  #
+  # @param name [String, Symbol] the +name+ used in {add_pattern}.
+  # @return [Boolean] +true+ if a pattern was removed, +false+ if no
+  #   pattern with that name was registered.
   def remove_pattern(name)
     _remove_pattern(name.to_s)
   end
 
+  # List every currently registered custom pattern.
+  #
+  # @return [Array<Hash{Symbol => Object}>] one hash per pattern with keys
+  #   +:name+ (String), +:source+ (String — the POSIX ERE source),
+  #   +:tag+ (Symbol), +:boundary+ (Boolean).
   def custom_patterns
     _custom_patterns.map do |h|
       { name: h[:name], source: h[:source], tag: TAGS.key(h[:tag_bit]) || :custom,
@@ -116,22 +239,101 @@ module DataRedactor
     end
   end
 
+  # Remove every registered custom pattern.
+  #
+  # Mostly useful in test suites that need a clean slate between examples.
+  #
+  # @return [nil]
   def clear_custom_patterns!
     _clear_custom_patterns
   end
 
-  def bits_for(tag_list)
-    Array(tag_list).inject(0) do |acc, tag|
-      bit = TAGS[tag] or raise UnknownTagError,
-        "unknown tag #{tag.inspect}; valid tags: #{TAGS.keys.inspect}"
-      acc | bit
+  # @api private
+  # Split a mixed Symbol/String filter list into +(tag_bitmask, name_set)+.
+  #
+  # @param entries [nil, Symbol, String, Array]
+  # @return [Array(Integer, Set<String>)] tag bits OR-ed together; set of
+  #   pattern-name Strings.
+  # @raise [UnknownTagError] for unknown Symbols.
+  # @raise [UnknownPatternError] for unknown Strings.
+  def split_filter(entries)
+    bits = 0
+    names = Set.new
+    return [bits, names] if entries.nil?
+    Array(entries).each do |e|
+      case e
+      when Symbol
+        bit = TAGS[e] or raise UnknownTagError,
+          "unknown tag #{e.inspect}; valid tags: #{TAGS.keys.inspect}"
+        bits |= bit
+      when String
+        unless pattern_names.include?(e)
+          raise UnknownPatternError,
+            "unknown pattern name #{e.inspect}; see DataRedactor.pattern_names"
+        end
+        names << e
+      else
+        raise ArgumentError,
+          "only:/except: entries must be a Symbol (tag) or String (pattern name), got #{e.inspect}"
+      end
+    end
+    [bits, names]
+  end
+
+  # @api private
+  # Build the per-pattern enable bit-list passed to the C layer.
+  #
+  # The list has one Integer (0 or 1) per pattern in execution order:
+  # built-ins first (NUM_PATTERNS entries), then currently registered custom
+  # patterns in registration order. C iterates by index and skips zeros.
+  #
+  # Semantics of +only:+ / +except:+ — both accept a mix of Symbols (tags)
+  # and Strings (pattern names):
+  #   enabled(p) iff
+  #     (only is nil OR p.tag ∈ only_tags OR p.name ∈ only_names)
+  #     AND p.tag ∉ except_tags AND p.name ∉ except_names
+  #
+  # @return [Array<Integer>] same length as built-ins + customs.
+  def build_enable_bits(only, except)
+    only_bits,   only_names   = split_filter(only)
+    except_bits, except_names = split_filter(except)
+    only_present = !only.nil?
+
+    bits = Array.new(BUILTIN_PATTERN_NAMES.length + _custom_patterns.length, 0)
+
+    BUILTIN_PATTERN_NAMES.each_with_index do |name, i|
+      tag_bit = BUILTIN_PATTERN_TAG_BITS[i]
+      bits[i] = 1 if pattern_enabled?(name, tag_bit, only_present,
+                                      only_bits, only_names,
+                                      except_bits, except_names)
     end
+
+    _custom_patterns.each_with_index do |h, i|
+      bits[BUILTIN_PATTERN_NAMES.length + i] = 1 if pattern_enabled?(
+        h[:name], h[:tag_bit], only_present,
+        only_bits, only_names, except_bits, except_names)
+    end
+
+    bits
   end
 
-  # Returns [ph_mode_int, ph_str] for the C layer.
-  #   placeholder: "***"      -> plain string
-  #   placeholder: :tagged    -> "[REDACTED:TAGNAME]"
-  #   placeholder: :hash      -> "[TAGNAME_xxxx]"
+  # @api private
+  def pattern_enabled?(name, tag_bit, only_present, only_bits, only_names,
+                       except_bits, except_names)
+    return false if (tag_bit & except_bits) != 0
+    return false if except_names.include?(name)
+    return true  unless only_present
+    return true  if (tag_bit & only_bits) != 0
+    only_names.include?(name)
+  end
+
+  # @api private
+  # Translate the user-facing +placeholder:+ value into the +(mode_int, str)+
+  # pair the C layer expects.
+  #
+  # @param placeholder [String, :tagged, :hash]
+  # @return [Array(Integer, String)]
+  # @raise [ArgumentError] if +placeholder+ is none of the accepted values.
   def resolve_placeholder(placeholder)
     case placeholder
     when :tagged then [PH_MODE_TAGGED, ""]

data/readme.md

@@ -1,5 +1,9 @@
 # DataRedactor
 
+[![Gem Version](https://badge.fury.io/rb/data_redactor.svg)](https://rubygems.org/gems/data_redactor)
+[![CI](https://github.com/danielefrisanco/data_redactor/actions/workflows/ci.yml/badge.svg)](https://github.com/danielefrisanco/data_redactor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 A Ruby gem with a C extension for high-performance regex-based redaction of sensitive data from strings.
 
 ## What it does
@@ -16,25 +20,34 @@ DataRedactor.redact(text)
 # => "User CF is [REDACTED] and key is [REDACTED]"
 ```
 
-### Filtering by tag
+### Filtering by tag or pattern name
 
-Every pattern belongs to one tag. Use `only:` to redact a subset, or `except:` to skip one.
+`only:` and `except:` both accept a single value or an Array, mixing **Symbols** (tag names) and **Strings** (specific pattern names).
 
 ```ruby
 DataRedactor.tags
-# => [:credentials, :financial, :tax_id, :national_id, :contact, :network, :travel, :other]
+# => [:credentials, :financial, :tax_id, :national_id, :contact, :network, :travel, :other, :custom]
+
+DataRedactor.pattern_names
+# => ["aws_s3_presigned_url", "aws_access_key_id", "email", "phone_e164", "ipv4", ...]
 
-# Only redact API keys / tokens / private keys
+# Tag-level filtering
 DataRedactor.redact(text, only: [:credentials])
+DataRedactor.redact(text, except: :contact)
 
-# Redact everything except contact info (emails, phone numbers)
-DataRedactor.redact(text, except: [:contact])
+# Single specific pattern
+DataRedactor.redact(text, only: ["aws_access_key_id"])
 
-# Single symbol works too
-DataRedactor.redact(text, only: :financial)
+# Mix — every credentials pattern PLUS aws_access_key_id (even if it lived in another tag)
+DataRedactor.redact(text, only: [:credentials, "aws_access_key_id"])
+
+# Combine — every contact pattern EXCEPT email
+DataRedactor.redact(text, only: :contact, except: ["email"])
 ```
 
-Passing an unknown tag raises `DataRedactor::UnknownTagError`. Passing both `only:` and `except:` raises `ArgumentError`.
+**Precedence:** a pattern is redacted iff `(only is nil OR matches only:)` AND `(does not match except:)`. `except:` always wins when the two overlap, so `only: :contact, except: :contact` produces a no-op (everything is excluded).
+
+**Errors:** an unknown tag Symbol raises `DataRedactor::UnknownTagError`; an unknown pattern name String raises `DataRedactor::UnknownPatternError`.
 
 ### Configurable placeholder
 
@@ -84,9 +97,10 @@ result = DataRedactor.scan("User AKIAIOSFODNN7EXAMPLE logged in from 192.168.1.1
 m = result[:matches].first
 original_text.byteslice(m[:start], m[:length])  # => "AKIAIOSFODNN7EXAMPLE"
 
-# Accepts the same tag filters as redact
+# Accepts the same filters as redact (tags + specific pattern names)
 DataRedactor.scan(text, only: :credentials)
 DataRedactor.scan(text, except: :network)
+DataRedactor.scan(text, only: :contact, except: ["email"])
 ```
 
 ### Custom patterns
@@ -114,21 +128,81 @@ DataRedactor.clear_custom_patterns!               # mostly for test suites
 
 **`boundary: true`** — wraps the pattern with `(^|[^0-9A-Za-z])(PATTERN)([^0-9A-Za-z]|$)` so it only fires when the token is not embedded in a longer alphanumeric string. Incompatible with patterns that contain capture groups.
 
-## Detected patterns (49 total)
+## Integrations
+
+Optional adapters for Logger, Rails, and Rack. None are loaded automatically — `require` only what you use, and the gem adds zero runtime dependencies in the gemspec.
+
+### Logger formatter
+
+Drop-in `Logger::Formatter` replacement that scrubs every emitted line:
+
+```ruby
+require "data_redactor/integrations/logger"
+
+logger = Logger.new($stdout)
+logger.formatter = DataRedactor::Integrations::Logger.new
+logger.info("Auth failed for alice@example.com")
+# => I, [...] -- : Auth failed for [REDACTED]
+```
+
+Wraps an inner formatter (defaults to `Logger::Formatter`), so it composes with structured loggers. Forwards `only:`, `except:`, `placeholder:` to `DataRedactor.redact`. Exception messages and arbitrary objects are scrubbed too — the wrapped object is passed unchanged to the inner formatter so the exception cause chain is preserved; only the rendered string is redacted.
+
+### Rails `filter_parameters` adapter
+
+```ruby
+# config/initializers/filter_parameter_logging.rb
+require "data_redactor/integrations/rails"
+
+Rails.application.config.filter_parameters += [
+  DataRedactor::Integrations::Rails.filter
+]
+```
+
+Returns a `(key, value)` proc compatible with Rails' parameter filter. String values are mutated in place via `String#replace` so Rails sees the redacted value. Non-strings are left alone. Accepts the same `only:`/`except:`/`placeholder:` kwargs.
+
+### Rack middleware
+
+```ruby
+# config.ru
+require "data_redactor/integrations/rack"
+
+use DataRedactor::Integrations::Rack, scrub: [:body, :headers]
+run MyApp
+```
+
+`scrub:` selects which surfaces to redact (default `[:body, :headers]`):
+
+- **`:body`** — buffers the response body, runs `DataRedactor.redact` over it, returns it as a single chunk. Drops the `Content-Length` header so the server recomputes (the redacted body may differ in byte length).
+- **`:headers`** — scrubs sensitive **response** headers (`Set-Cookie`, `Authorization`, `X-Api-Key`, `X-Auth-Token`, `X-Access-Token`) in place, and sensitive **request** headers (`HTTP_AUTHORIZATION`, `HTTP_PROXY_AUTHORIZATION`, `HTTP_COOKIE`, `HTTP_X_API_KEY`, `HTTP_X_AUTH_TOKEN`, `HTTP_X_ACCESS_TOKEN`) in the env hash so any downstream middleware that logs them sees redacted values.
+
+Pass an empty subset (e.g. `scrub: [:headers]`) to opt out of body wrapping. Forwards `only:`/`except:`/`placeholder:` to `DataRedactor.redact`. Unknown surfaces raise `ArgumentError` at boot.
+
+> **Body wrapping is buffering.** The middleware reads the entire response body into memory before scanning. For streaming endpoints (SSE, large file downloads, Rack::Hijack) use `scrub: [:headers]` and rely on the Logger formatter for application logs instead.
+
+## Detected patterns (85 total)
+
+The table below is a representative sample. Use `DataRedactor.pattern_names` for the canonical, machine-readable list — it stays in sync with the C extension automatically.
 
 ### Cloud & API secrets
 
 | # | Pattern | Example |
 |---|---|---|
-| 0 | AWS Access Key ID | `AKIAIOSFODNN7EXAMPLE` |
-| 1 | AWS Secret Access Key | 40-character base64 string |
-| 5 | Google API Key | `AIzaSyXXXX...` |
-| 6 | GitHub Personal Access Token | `github_pat_XXXX...` |
-| 7 | Slack Webhook URL | `https://hooks.slack.com/services/T.../B.../...` |
-| 8 | Stripe Secret Key | `sk_live_XXXX...` |
-| 9 | PEM Private Key header | `-----BEGIN RSA PRIVATE KEY-----` |
-| 13 | Scaleway Access Key | `SCW12345ABCDE6789FGHIJ` |
-| 14 | UUID v4 / Scaleway Secret Key | `550e8400-e29b-41d4-a716-446655440000` |
+| — | AWS Access Key ID | `AKIAIOSFODNN7EXAMPLE` |
+| — | AWS Secret Access Key | 40-character base64 string |
+| — | Google API Key | `AIzaSyXXXX...` |
+| — | GitHub Personal Access Token | `github_pat_XXXX...` |
+| — | GitHub Classic PAT / OAuth | `ghp_XXXX...` / `gho_XXXX...` |
+| — | Slack Webhook URL | `https://hooks.slack.com/services/T.../B.../...` |
+| — | Stripe Secret Key | `sk_live_XXXX...` |
+| — | Anthropic API Key | `sk-ant-api03-XXXX...` |
+| — | OpenAI Project API Key | `sk-proj-XXXX...` |
+| — | GitLab Personal Access Token | `glpat-XXXX...` |
+| — | DigitalOcean PAT | `dop_v1_XXXX...` |
+| — | Databricks API Token | `dapiXXXX...` |
+| — | Sentry DSN | `https://KEY@oNNN.ingest.sentry.io/PID` |
+| — | PEM Private Key header | `-----BEGIN RSA PRIVATE KEY-----` |
+| — | Scaleway Access Key | `SCW12345ABCDE6789FGHIJ` |
+| — | UUID v4 / Scaleway Secret Key | `550e8400-e29b-41d4-a716-446655440000` |
 
 ### Travel documents
 
@@ -205,10 +279,16 @@ redactor/
 │       └── version.rb
 ├── ext/
 │   └── data_redactor/
-│       ├── extconf.rb         # Checks for C headers, generates Makefile
-│       └── data_redactor.c       # C extension: regex compilation + redaction
+│       ├── extconf.rb            # Checks for C headers, generates Makefile (globs *.c)
+│       ├── data_redactor.c       # Entry point: Init_data_redactor only
+│       ├── patterns.{c,h}        # Built-in pattern table + compiled regex_t array
+│       ├── placeholder.{c,h}     # write_placeholder, djb2 hash, tag_name_for_bit
+│       ├── redact.{c,h}          # _redact + replace_all_matches + wrap_boundary
+│       ├── scan.{c,h}            # _scan + byte-offset replacement-log macros
+│       ├── custom_patterns.{c,h} # Dynamic registry: add/remove/clear/list
+│       └── tags.h                # TAG_* bit constants
 └── spec/
-    └── data_redactor_spec.rb     # RSpec tests (61 examples, one per pattern)
+    └── data_redactor_spec.rb     # RSpec tests — at least one example per pattern, plus filter / placeholder / custom-pattern coverage
 ```
 
 ## Requirements
@@ -245,7 +325,7 @@ bundle exec rake
 
 ## How it works
 
-1. At load time, `Init_data_redactor` compiles all 49 regex patterns once using `regcomp` (POSIX ERE) and stores them as static `regex_t` structs. Patterns marked as boundary-wrapped are expanded with `wrap_boundary()` before compilation.
+1. At load time, `Init_data_redactor` compiles all 85 regex patterns once using `regcomp` (POSIX ERE) and stores them as static `regex_t` structs. Patterns marked as boundary-wrapped are expanded with `wrap_boundary()` before compilation.
 2. `DataRedactor.redact(text)` receives a Ruby `String`, converts it to a C `char*` via `StringValueCStr`, and runs each compiled pattern in sequence on a working buffer.
 3. For each pattern, `replace_all_matches` iterates using `regexec`, copies non-matching segments to a fresh output buffer, and inserts `[REDACTED]` in place of each match. For boundary-wrapped patterns, `regexec` is called with `nmatch=4` and sub-match groups `[1]`/`[3]` identify the boundary characters so they are preserved verbatim.
 4. The output buffer is grown with `realloc` as needed. After all patterns are applied the result is returned as a Ruby `String` via `rb_str_new_cstr`. All intermediate `malloc`/`strdup` allocations are explicitly `free`d.
@@ -254,6 +334,12 @@ bundle exec rake
 
 All C-side buffers are heap-allocated with `malloc`/`strdup` and freed before the function returns. The only Ruby-managed allocation is the final return value from `rb_str_new_cstr`. No Ruby objects are created mid-processing, so GC cannot collect anything out from under the C code.
 
+## Thread safety
+
+`DataRedactor.redact` and `DataRedactor.scan` are safe to call concurrently from multiple threads. Built-in patterns are compiled into a static `regex_t` array at load time and never mutated afterward, and each call allocates its own working buffers. POSIX `regexec` is documented as thread-safe.
+
+`DataRedactor.add_pattern`, `remove_pattern`, and `clear_custom_patterns!` mutate a shared dynamic array and are **not** thread-safe. Register custom patterns once at boot — before spawning worker threads or forking — and they will be visible (read-only) to every subsequent `redact`/`scan` call.
+
 ## Versioning
 
 This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). Until `1.0.0`, minor versions may introduce breaking changes; from `1.0.0` onward, breaking changes will only land in major versions. See [CHANGELOG.md](CHANGELOG.md) for the release history.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_redactor
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Daniele Frisanco
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-02 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -38,10 +38,39 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: A Ruby gem with a C extension for high-performance scanning and redaction
-  of 79 sensitive patterns — API keys, tokens, credentials, IBANs, national IDs, emails,
-  phone numbers, and PII from 15+ countries. Designed to sanitize text before sending
-  to LLMs, logging systems, or any public/third-party API.
+  of 85 sensitive patterns — API keys, tokens, credentials, IBANs, national IDs, emails,
+  phone numbers, and PII from 15+ countries. Optional Logger formatter, Rails filter_parameters
+  adapter, and Rack middleware. Designed to sanitize text before sending to LLMs,
+  logging systems, or any public/third-party API.
 email:
 - daniele.frisanco@gmail.com
 executables: []
@@ -51,9 +80,23 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
+- ext/data_redactor/custom_patterns.c
+- ext/data_redactor/custom_patterns.h
 - ext/data_redactor/data_redactor.c
 - ext/data_redactor/extconf.rb
+- ext/data_redactor/patterns.c
+- ext/data_redactor/patterns.h
+- ext/data_redactor/placeholder.c
+- ext/data_redactor/placeholder.h
+- ext/data_redactor/redact.c
+- ext/data_redactor/redact.h
+- ext/data_redactor/scan.c
+- ext/data_redactor/scan.h
+- ext/data_redactor/tags.h
 - lib/data_redactor.rb
+- lib/data_redactor/integrations/logger.rb
+- lib/data_redactor/integrations/rack.rb
+- lib/data_redactor/integrations/rails.rb
 - lib/data_redactor/version.rb
 - readme.md
 homepage: https://github.com/danielefrisanco/data_redactor