promptscrub 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6fe475bdcd3c44552076094d338cf41c2644ce834060969132295834b47f8425
+  data.tar.gz: ef23ed4be55822096547adff17507da18f8b48d47981bc2c53074abf1ded4631
+SHA512:
+  metadata.gz: 987376e104f603c3bb1c24e638e47591ec6b54642ff422ddf49c39f8ea5fc308b77a5a3edca9a779967f35bc22189951474ee47b2cf99c60740c2bd6b44508fa
+  data.tar.gz: 14621351db2f92ca5db1abb840452f6ead5307fa1e348ee30a50b4f3235dcce7100afccd7ea443f6164c4825c180f363b1c85035ba65274865bd8175cc22dde6

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-06-03
+
+### Added
+- `PromptScrub::Middleware` — Faraday middleware for request redaction + response rehydration
+- Built-in detectors: email, SSN, credit card (Luhn-validated), US phone number
+- `PromptScrub::Vault` — per-request thread-safe token↔value store
+- `PromptScrub::StreamRehydrator` — streaming helper with partial-token buffer
+- `PromptScrub.configure` block for global configuration
+- `Configuration#add_detector` — register custom regex detectors
+- `Configuration#disable_detector` — opt out of specific built-in detectors

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jibran Usman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# promptscrub
+
+[![Gem Version](https://badge.fury.io/rb/promptscrub.svg)](https://rubygems.org/gems/promptscrub)
+[![CI](https://github.com/jibranusman95/promptscrub/actions/workflows/ci.yml/badge.svg)](https://github.com/jibranusman95/promptscrub/actions/workflows/ci.yml)
+
+**Strip PII from LLM prompts. Rehydrate it in responses. Your users see real data. Your LLM provider never does.**
+
+Drop-in Faraday middleware for OpenAI, Anthropic, Gemini — and any LLM library built on Faraday (RubyLLM, langchainrb, llm.rb).
+
+```
+Your App                   PromptScrub                LLM API
+   │                           │                          │
+   │  "SSN is 123-45-6789"     │                          │
+   │──────────────────────────►│  redact                  │
+   │                           │  "SSN is <SSN_001>"      │
+   │                           │─────────────────────────►│
+   │                           │                          │ generate
+   │                           │◄─────────────────────────│
+   │                           │  "Your SSN <SSN_001>..."  │
+   │                           │  rehydrate               │
+   │  "Your SSN 123-45-6789..."│                          │
+   │◄──────────────────────────│                          │
+```
+
+No infra to deploy. No gateway to operate. Just middleware.
+
+## Installation
+
+```ruby
+gem "promptscrub"
+```
+
+## Quick start
+
+```ruby
+require "faraday"
+require "promptscrub"
+
+conn = Faraday.new("https://api.openai.com") do |f|
+  f.use PromptScrub::Middleware
+  f.request :json
+  f.response :json
+  f.adapter Faraday.default_adapter
+end
+
+# PII is stripped before the request leaves your app.
+# Tokens are rehydrated in the response. Transparent to your code.
+response = conn.post("/v1/chat/completions", {
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Summarize claim for SSN 234-56-7890, card 4532015112830366" }]
+})
+```
+
+### With RubyLLM
+
+```ruby
+RubyLLM.configure do |c|
+  c.faraday do |f|
+    f.use PromptScrub::Middleware
+  end
+end
+```
+
+## Built-in detectors
+
+| Type    | Detects                            | Token example   |
+|---------|------------------------------------|-----------------|
+| EMAIL   | `john.doe+tag@sub-domain.co.uk`    | `<EMAIL_001>`   |
+| SSN     | `123-45-6789` (invalid ranges excluded) | `<SSN_001>` |
+| CARD    | 13–19 digit numbers (Luhn-validated) | `<CARD_001>`  |
+| PHONE   | US numbers in all common formats   | `<PHONE_001>`   |
+
+Same value always maps to the same token within a request — so `alice@corp.com` appearing twice becomes `<EMAIL_001>` twice.
+
+## Configuration
+
+```ruby
+PromptScrub.configure do |config|
+  # Add a custom detector
+  config.add_detector(:zip, /\b\d{5}(-\d{4})?\b/)
+
+  # Opt out of a built-in
+  config.disable_detector(:phone)
+
+  # Redact only outbound (skip rehydration)
+  config.scrub_response = false
+end
+```
+
+## Streaming (SSE)
+
+For streaming responses where your app processes chunks directly, use `StreamRehydrator` to wrap your callback:
+
+```ruby
+vault      = PromptScrub::Vault.new
+redactor   = PromptScrub::Redactor.new(vault, PromptScrub.configuration.detectors)
+rehydrator = PromptScrub::StreamRehydrator.new(vault) do |clean_chunk|
+  print clean_chunk  # user sees real values
+end
+
+# Before streaming request:
+redacted_prompt = redactor.scrub(user_prompt)
+
+# For each SSE chunk received:
+rehydrator.call(raw_chunk)
+
+# After stream ends:
+rehydrator.flush
+```
+
+`StreamRehydrator` buffers partial tokens at chunk boundaries (e.g. `<EMAIL_` split across two chunks) and flushes them correctly when the token completes.
+
+## How it works
+
+1. **Redact** — on every outgoing request, `Redactor` scans the body string with all registered detectors and replaces matches with `<TYPE_NNN>` tokens. Each unique value gets a stable token stored in a per-request `Vault`.
+2. **Send** — the redacted body hits the LLM API. The model never sees real PII.
+3. **Rehydrate** — on the response, `Rehydrator` scans for token patterns and substitutes original values from the vault. Your application code receives the real data.
+
+The vault is in-memory and scoped to a single request — no persistence, no shared state between requests.
+
+## Security notes
+
+- Tokens are **not encrypted**. The vault lives in your process memory for the duration of a request.
+- Detection is regex-based. It will catch well-formed PII; obfuscated or unusual formats may slip through.
+- For high-assurance use cases (HIPAA, PCI-DSS), add custom detectors for your specific data patterns and review false-negative rates in your domain.
+- promptscrub is client-side middleware. It does not replace network-level controls or data governance policies.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/jibranusman95/promptscrub).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/promptscrub/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  class Configuration
+    attr_accessor :scrub_request, :scrub_response
+    attr_reader   :detectors
+
+    def initialize
+      @scrub_request  = true
+      @scrub_response = true
+      @detectors      = default_detectors
+    end
+
+    def add_detector(type_or_detector, pattern = nil)
+      detector = if type_or_detector.is_a?(Detector)
+                   type_or_detector
+                 else
+                   Detector.new(type_or_detector, pattern)
+                 end
+      @detectors << detector
+      self
+    end
+
+    def disable_detector(type)
+      @detectors.reject! { |d| d.type.casecmp(type.to_s).zero? }
+      self
+    end
+
+    private
+
+    def default_detectors
+      [
+        Detectors::Email.new,
+        Detectors::SSN.new,
+        Detectors::CreditCard.new,
+        Detectors::Phone.new
+      ]
+    end
+  end
+end

data/lib/promptscrub/detector.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  class Detector
+    attr_reader :type, :pattern
+
+    def initialize(type, pattern)
+      @type    = type.to_s.upcase
+      @pattern = pattern
+    end
+
+    def scan(text)
+      text.scan(pattern).map { |m| m.is_a?(Array) ? m.first : m }.uniq
+    end
+  end
+end

data/lib/promptscrub/detectors/credit_card.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  module Detectors
+    class CreditCard < Detector
+      PATTERN = /\b(?:\d[ -]?){13,18}\d\b/
+
+      def initialize
+        super('CARD', PATTERN)
+      end
+
+      def scan(text)
+        super.select { |n| luhn_valid?(n.gsub(/[ -]/, '')) }
+      end
+
+      private
+
+      def luhn_valid?(number)
+        return false unless number.match?(/\A\d{13,19}\z/)
+
+        digits = number.chars.map(&:to_i)
+        sum = digits.reverse.each_with_index.sum do |digit, i|
+          if i.odd?
+            doubled = digit * 2
+            doubled > 9 ? doubled - 9 : doubled
+          else
+            digit
+          end
+        end
+        (sum % 10).zero?
+      end
+    end
+  end
+end

data/lib/promptscrub/detectors/email.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  module Detectors
+    class Email < Detector
+      PATTERN = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/
+
+      def initialize
+        super('EMAIL', PATTERN)
+      end
+    end
+  end
+end

data/lib/promptscrub/detectors/phone.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  module Detectors
+    class Phone < Detector
+      PATTERN = /(?<!\d)(?:\+1[-.\s]?)?\(?[2-9]\d{2}\)?[-.\s]?\d{3}[-.\s]?\d{4}(?!\d)/
+
+      def initialize
+        super('PHONE', PATTERN)
+      end
+    end
+  end
+end

data/lib/promptscrub/detectors/ssn.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  module Detectors
+    class SSN < Detector
+      PATTERN = /\b(?!000|666|9\d{2})\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/
+
+      def initialize
+        super('SSN', PATTERN)
+      end
+    end
+  end
+end

data/lib/promptscrub/middleware.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PromptScrub
+  class Middleware < Faraday::Middleware
+    def initialize(app, config: PromptScrub.configuration)
+      super(app)
+      @config = config
+    end
+
+    def call(env)
+      vault      = Vault.new
+      redactor   = Redactor.new(vault, @config.detectors)
+      rehydrator = Rehydrator.new(vault)
+
+      env[:body] = scrub_body(env[:body], redactor) if @config.scrub_request
+
+      @app.call(env).on_complete do |response_env|
+        if @config.scrub_response && !vault.empty? && response_env[:body].is_a?(String)
+          response_env[:body] = rehydrator.rehydrate(response_env[:body])
+        end
+      end
+    end
+
+    private
+
+    def scrub_body(body, redactor)
+      return body if body.nil?
+
+      body_str = body.is_a?(String) ? body : JSON.generate(body)
+      redactor.scrub(body_str)
+    end
+  end
+end

data/lib/promptscrub/redactor.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  class Redactor
+    def initialize(vault, detectors)
+      @vault     = vault
+      @detectors = detectors
+    end
+
+    def scrub(text)
+      return text if text.nil? || text.empty?
+
+      result = text.dup
+      @detectors.each do |detector|
+        detector.scan(result).each do |match|
+          token  = @vault.tokenize(detector.type, match)
+          result = result.gsub(match, token)
+        end
+      end
+      result
+    end
+  end
+end

data/lib/promptscrub/rehydrator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  class Rehydrator
+    TOKEN_PATTERN = /<[A-Z]+_\d{3}>/
+
+    def initialize(vault)
+      @vault = vault
+    end
+
+    def rehydrate(text)
+      return text if text.nil? || text.empty?
+      return text if @vault.empty?
+
+      text.gsub(TOKEN_PATTERN) do |token|
+        @vault.rehydrate(token) || token
+      end
+    end
+  end
+end

data/lib/promptscrub/stream_rehydrator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  class StreamRehydrator
+    PARTIAL_TOKEN = /<[A-Z_\d]*\z/
+
+    def initialize(vault, &callback)
+      @vault    = vault
+      @callback = callback
+      @buffer   = ''
+    end
+
+    def call(chunk)
+      combined = @buffer + chunk
+      @buffer  = ''
+
+      if (match = combined.match(PARTIAL_TOKEN))
+        @buffer  = match[0]
+        combined = combined[0, match.begin(0)]
+      end
+
+      @callback.call(rehydrate(combined)) unless combined.empty?
+    end
+
+    def flush
+      result  = rehydrate(@buffer)
+      @buffer = ''
+      @callback.call(result) unless result.empty?
+    end
+
+    private
+
+    def rehydrate(text)
+      text.gsub(Rehydrator::TOKEN_PATTERN) do |token|
+        @vault.rehydrate(token) || token
+      end
+    end
+  end
+end

data/lib/promptscrub/vault.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  class Vault
+    def initialize
+      @store    = {}
+      @reverse  = {}
+      @counters = Hash.new(0)
+      @mutex    = Mutex.new
+    end
+
+    def tokenize(type, value)
+      @mutex.synchronize do
+        return @reverse[value] if @reverse.key?(value)
+
+        @counters[type] += 1
+        token = format('<%<type>s_%<num>03d>', type: type.upcase, num: @counters[type])
+        @store[token]   = value
+        @reverse[value] = token
+        token
+      end
+    end
+
+    def rehydrate(token)
+      @mutex.synchronize { @store[token] }
+    end
+
+    def empty?
+      @mutex.synchronize { @store.empty? }
+    end
+
+    def size
+      @mutex.synchronize { @store.size }
+    end
+  end
+end

data/lib/promptscrub/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PromptScrub
+  VERSION = '0.1.0'
+end

data/lib/promptscrub.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require_relative 'promptscrub/version'
+require_relative 'promptscrub/configuration'
+require_relative 'promptscrub/vault'
+require_relative 'promptscrub/detector'
+require_relative 'promptscrub/detectors/email'
+require_relative 'promptscrub/detectors/ssn'
+require_relative 'promptscrub/detectors/credit_card'
+require_relative 'promptscrub/detectors/phone'
+require_relative 'promptscrub/redactor'
+require_relative 'promptscrub/rehydrator'
+require_relative 'promptscrub/middleware'
+require_relative 'promptscrub/stream_rehydrator'
+
+module PromptScrub
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: promptscrub
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jibran Usman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  Drop-in Faraday middleware that detects and tokenizes PII (emails, SSNs, credit cards,
+  phone numbers, custom patterns) in outgoing LLM requests, then rehydrates tokens back
+  in responses. Works with OpenAI, Anthropic, Gemini, RubyLLM, langchainrb, and any
+  Faraday-based HTTP client. Includes StreamRehydrator for SSE streaming use cases.
+email:
+- jibran.usman@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/promptscrub.rb
+- lib/promptscrub/configuration.rb
+- lib/promptscrub/detector.rb
+- lib/promptscrub/detectors/credit_card.rb
+- lib/promptscrub/detectors/email.rb
+- lib/promptscrub/detectors/phone.rb
+- lib/promptscrub/detectors/ssn.rb
+- lib/promptscrub/middleware.rb
+- lib/promptscrub/redactor.rb
+- lib/promptscrub/rehydrator.rb
+- lib/promptscrub/stream_rehydrator.rb
+- lib/promptscrub/vault.rb
+- lib/promptscrub/version.rb
+homepage: https://github.com/jibranusman95/promptscrub
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jibranusman95/promptscrub
+  source_code_uri: https://github.com/jibranusman95/promptscrub
+  changelog_uri: https://github.com/jibranusman95/promptscrub/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Bidirectional PII redaction for LLM calls — strip sensitive data from prompts,
+  rehydrate in responses.
+test_files: []