tina4ruby 3.13.98 → 3.13.99

data/lib/tina4/drivers/mongodb_driver.rb

@@ -70,9 +70,11 @@ module Tina4
           @last_insert_id = result.inserted_id.to_s
           result
         when :update
-          collection.update_many(parsed[:filter] || {}, { "$set" => parsed[:updates] })
+          # parse_update guarantees a scoped filter (or it raised) — no || {} fallback.
+          collection.update_many(parsed[:filter], { "$set" => parsed[:updates] })
         when :delete
-          collection.delete_many(parsed[:filter] || {})
+          # parse_delete guarantees a scoped filter (or it raised) — no || {} fallback.
+          collection.delete_many(parsed[:filter])
         when :create_collection
           begin
             @db.command(create: parsed[:collection].to_s)
@@ -91,6 +93,49 @@ module Tina4
         @last_insert_id
       end
 
+      # Atomic, monotonic, concurrency-safe next id — feature 16. A
+      # findOneAndUpdate($inc) on the tina4_sequences collection, keyed by _id
+      # (its built-in unique index makes concurrent first-use upserts race-safe:
+      # two callers can never create two counters for one table). Seeds from
+      # MAX(pk_column) the FIRST time only ($setOnInsert). Raises on an
+      # impossible empty result rather than returning a fixed id that could
+      # collide with an existing row.
+      def get_next_id(table, pk_column = "id")
+        sequences = @db["tina4_sequences"]
+        seq_name = "#{table}.#{pk_column}"
+
+        if sequences.find("_id" => seq_name).first.nil?
+          seed = 0
+          begin
+            max_doc = @db[table.to_s].find.sort(pk_column => -1).limit(1).first
+            seed = max_doc[pk_column].to_i if max_doc && max_doc[pk_column]
+          rescue StandardError
+            # Collection may not exist yet — seed 0.
+          end
+          begin
+            sequences.update_one(
+              { "_id" => seq_name },
+              { "$setOnInsert" => { "current_value" => seed } },
+              upsert: true
+            )
+          rescue StandardError
+            # Race — another caller seeded first; the atomic $inc below still holds.
+          end
+        end
+
+        doc = sequences.find_one_and_update(
+          { "_id" => seq_name },
+          { "$inc" => { "current_value" => 1 } },
+          return_document: :after,
+          upsert: true
+        )
+        if doc.nil? || doc["current_value"].nil?
+          raise "get_next_id: MongoDB counter '#{seq_name}' produced no value"
+        end
+
+        doc["current_value"].to_i
+      end
+
       def placeholder
         "?"
       end
@@ -126,6 +171,11 @@ module Tina4
         # no-op
       end
 
+      # ADR-0044 required adapter capability.
+      def get_database_type
+        'mongodb'
+      end
+
       def tables
         @db.collection_names.reject { |n| n.start_with?("system.") }
       end
@@ -351,6 +401,17 @@ module Tina4
       def parse_condition(clause)
         clause = clause.strip.gsub(/^\(+/, "").gsub(/\)+$/, "").strip
 
+        # Explicit 1=1 tautology -- the WHERE clause truncate() passes -- means
+        # MATCH-ALL: translate it to an empty {} filter so truncate() empties the
+        # collection, exactly as PHP already does. Without this, "1 = 1" fell
+        # through to the "=" comparison below and parsed as { "1" => 1 }, which
+        # matches NOTHING, so a truncate() silently deleted 0 documents while the
+        # caller believed the collection was emptied. This does NOT weaken the
+        # fail-closed guard: 1=1 is an EXPLICIT tautology, distinct from an
+        # unparseable WHERE (the raise at the end of this method still fires) and
+        # from a blank/absent WHERE (which require_where_for_write still rejects).
+        return {} if clause.match?(/\A1\s*=\s*1\z/)
+
         # IS NULL / IS NOT NULL
         if (m = clause.match(/^(\w+)\s+IS\s+NOT\s+NULL$/i))
           return { m[1] => { "$ne" => nil } }
@@ -398,8 +459,33 @@ module Tina4
           end
         end
 
-        # Fallback — return as a raw string comment (best-effort)
-        {}
+        # Fail closed. An unrecognised condition must NEVER degrade to an empty
+        # (match-all) filter: on a DELETE/UPDATE that empty filter reaches
+        # delete_many({})/update_many({}) and wipes or rewrites the WHOLE
+        # collection. Raise so the caller sees the unsupported SQL instead of
+        # silently losing data.
+        raise ArgumentError,
+              "Unsupported MongoDB WHERE condition: #{clause.inspect}. The MongoDB " \
+              "SQL provider fails closed rather than matching every document. " \
+              "Supported: = != <> > >= < <= LIKE, NOT LIKE, IN, NOT IN, " \
+              "IS [NOT] NULL, AND, OR."
+      end
+
+      # Fail closed: a DELETE/UPDATE must carry a WHERE clause.
+      #
+      # A missing or blank WHERE translates to an empty MongoDB filter, which
+      # matches EVERY document, so delete_many({})/update_many({}) would wipe or
+      # rewrite the whole collection. Refuse it. The explicit whole-collection
+      # spelling is truncate() (it passes WHERE 1 = 1); the native driver via
+      # #connection is the escape hatch for anything the SQL subset cannot
+      # express. Shared by both write paths so the guard cannot drift.
+      def require_where_for_write(where_str, operation, collection)
+        return unless where_str.nil? || where_str.strip.empty?
+
+        raise ArgumentError,
+              "Refusing to #{operation} every document in '#{collection}': the " \
+              "statement has no WHERE clause, which would affect the whole " \
+              "collection. Add a WHERE, or use truncate() to clear it explicitly."
       end
 
       def parse_value(str)
@@ -474,10 +560,7 @@ module Tina4
 
         m = sql.match(/UPDATE\s+(\w+)\s+SET\s+(.+?)(?:\s+WHERE\s+(.+))?$/im)
         unless m
-          result[:collection] = :unknown
-          result[:updates] = {}
-          result[:filter] = {}
-          return result
+          raise ArgumentError, "MongodbDriver: cannot parse UPDATE statement: #{sql}"
         end
 
         result[:collection] = m[1].to_sym
@@ -497,9 +580,10 @@ module Tina4
         end
         result[:updates] = updates
 
-        # Parse WHERE
+        # Parse WHERE — refuse a filterless UPDATE (would rewrite the whole collection).
         where_str = m[3]&.strip
-        result[:filter] = where_str && !where_str.empty? ? parse_where(where_str) : {}
+        require_where_for_write(where_str, "UPDATE", result[:collection])
+        result[:filter] = parse_where(where_str)
 
         result
       end
@@ -533,14 +617,14 @@ module Tina4
 
         m = sql.match(/DELETE\s+FROM\s+(\w+)(?:\s+WHERE\s+(.+))?$/im)
         unless m
-          result[:collection] = :unknown
-          result[:filter] = {}
-          return result
+          raise ArgumentError, "MongodbDriver: cannot parse DELETE statement: #{sql}"
         end
 
         result[:collection] = m[1].to_sym
+        # Refuse a filterless DELETE (would empty the whole collection).
         where_str = m[2]&.strip
-        result[:filter] = where_str && !where_str.empty? ? parse_where(where_str) : {}
+        require_where_for_write(where_str, "DELETE", result[:collection])
+        result[:filter] = parse_where(where_str)
 
         result
       end

data/lib/tina4/drivers/mssql_driver.rb

@@ -153,6 +153,11 @@ module Tina4
         !rows.empty?
       end
 
+      # ADR-0044 required adapter capability.
+      def get_database_type
+        'mssql'
+      end
+
       def tables
         rows = execute_query("SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE'")
         rows.map { |r| r[:TABLE_NAME] || r[:table_name] }
@@ -224,14 +229,46 @@ module Tina4
             elsif param.is_a?(Time) || param.is_a?(DateTime)
               "'#{(param.respond_to?(:iso8601) ? param.iso8601 : param.to_s).gsub("'", "''")}'"
             elsif param.is_a?(String)
-              "'#{param.gsub("'", "''")}'"
-            else
+              interpolate_string(param)
+            elsif param.is_a?(Integer)
+              param.to_s
+            elsif param.is_a?(Float)
+              # A finite Float is a valid numeric literal; NaN/Infinity are not
+              # representable in T-SQL and would stringify to a bareword.
+              raise ArgumentError, "MssqlDriver cannot bind a non-finite Float (#{param})" unless param.finite?
+
+              param.to_s
+            elsif param.is_a?(Numeric)
+              # BigDecimal / Rational -> a plain decimal literal.
               param.to_s
+            else
+              # MSSQL-INTERP-RUBY: the old `else param.to_s` emitted a BAREWORD for
+              # any unrecognised type (a Symbol became `WHERE x = active`, invalid
+              # or unintended SQL - a breakage / injection vector). Refuse it loudly
+              # instead of splicing an arbitrary object's #to_s into the statement.
+              raise ArgumentError,
+                    "MssqlDriver cannot safely bind a #{param.class} parameter to MSSQL " \
+                    "(#{param.inspect}); pass nil, true/false, a Time, a String " \
+                    "(text, or ASCII-8BIT bytes), or a Numeric - never a bareword"
             end
           result = result.sub("?", escaped)
         end
         result
       end
+
+      # Bind a String parameter. ASCII-8BIT (binary) bytes become a T-SQL
+      # varbinary literal `0x...`, NOT a quoted string: FreeTDS (tiny_tds) cannot
+      # carry raw binary through a quoted literal - a NUL byte breaks the TDS
+      # stream / truncates the value - whereas a `0x` literal round-trips
+      # byte-for-byte (MEASURED against real SQL Server). A text String keeps the
+      # quote-doubled literal (correct T-SQL escaping).
+      def interpolate_string(param)
+        if param.encoding == Encoding::BINARY
+          param.empty? ? "0x" : "0x#{param.unpack1('H*')}"
+        else
+          "'#{param.gsub("'", "''")}'"
+        end
+      end
     end
   end
 end

data/lib/tina4/drivers/mysql_driver.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "schema_split"
+require_relative "../sql_translator"
 
 module Tina4
   module Drivers
@@ -64,7 +65,19 @@ module Tina4
         @connection&.close
       end
 
+      # Apply the MySQL dialect rewrites the translator owns: +||+ -> CONCAT and
+      # ILIKE -> LOWER() LIKE LOWER() (both literal-safe). MySQL reads a bare +||+
+      # as logical OR and has no ILIKE, so portable canonical SQL must be rewritten
+      # before it reaches the driver. A statement with neither token short-circuits
+      # unchanged, so ordinary queries are untouched. (SQLTRANS-DEC-02: this is the
+      # wiring that makes the previously-dead concat/ilike helpers live in Ruby.)
+      def translate_dialect(sql)
+        sql = Tina4::SQLTranslator.concat_pipes_to_func(sql)
+        Tina4::SQLTranslator.ilike_to_like(sql)
+      end
+
       def execute_query(sql, params = [])
+        sql = translate_dialect(sql)
         if params.empty?
           results = @connection.query(sql, symbolize_keys: true)
         else
@@ -75,6 +88,7 @@ module Tina4
       end
 
       def execute(sql, params = [])
+        sql = translate_dialect(sql)
         stmt = nil
         result =
           if params.empty?
@@ -117,10 +131,14 @@ module Tina4
 
         if sql.to_s.lstrip[0, 6].casecmp?("INSERT")
           first_id = @connection.last_id
-          rows = @affected_rows.to_i
+          # MySQL reports the FIRST id of a multi-row INSERT; normalise to the
+          # LAST via the shared SQLTranslator helper (the one place that knows the
+          # first id and the row count) instead of the inline arithmetic
+          # (MYSQL-BATCH-ID-DUP). Guarded on a positive id so a non-auto-increment
+          # insert keeps whatever the driver reported.
           @last_insert_id =
             if first_id.to_i.positive?
-              first_id.to_i + [rows, 1].max - 1
+              Tina4::SQLTranslator.batch_last_id(first_id, @affected_rows.to_i, "mysql")
             else
               first_id
             end
@@ -179,13 +197,23 @@ module Tina4
         !rows.empty?
       end
 
+      # ADR-0044 required adapter capability.
+      def get_database_type
+        'mysql'
+      end
+
       def tables
         rows = execute_query("SHOW TABLES")
         rows.map { |r| r.values.first }
       end
 
       def columns(table_name)
-        rows = execute_query("DESCRIBE #{table_name}")
+        # DESCRIBE takes an IDENTIFIER, not a bind parameter, so the table name is
+        # made injection-safe by STRICT backtick-quoting (escaping embedded
+        # backticks) rather than interpolated raw (MYSQL-DESCRIBE-UNPARAM): a
+        # crafted/odd name becomes ONE escaped identifier - a clean "unknown
+        # table", never runnable SQL - and an odd-but-valid name introspects.
+        rows = execute_query("DESCRIBE #{quote_mysql_identifier(table_name)}")
         rows.map do |r|
           {
             name: r[:Field],
@@ -196,6 +224,18 @@ module Tina4
           }
         end
       end
+
+      private
+
+      # Strict backtick-quote a (possibly schema-qualified) identifier, ESCAPING
+      # embedded backticks, for use where a bind parameter is not accepted
+      # (DESCRIBE). A crafted/odd name becomes ONE escaped identifier - a clean
+      # "unknown table", never runnable SQL (MYSQL-DESCRIBE-UNPARAM).
+      def quote_mysql_identifier(name)
+        schema, table = split_schema(name.to_s)
+        q = ->(part) { "`#{part.to_s.gsub('`', '``')}`" }
+        schema.nil? ? q.call(table) : "#{q.call(schema)}.#{q.call(table)}"
+      end
     end
   end
 end

data/lib/tina4/drivers/odbc_driver.rb

@@ -70,7 +70,15 @@ module Tina4
           dsn_string = "#{dsn_string};PWD=#{password}"
         end
 
-        @connection = ODBC::Database.new(dsn_string)
+        # ODBC::Database.new(string) routes to SQLConnect, which takes a DSN NAME
+        # (data source), NOT a connection string - so a DRIVER={...} / DSN=...
+        # string (exactly what Tina4's odbc:/// URL produces) raised "Invalid
+        # string or buffer length" against a real driver. SQLDriverConnect is the
+        # call that parses a connection string; reach it via #drvconnect on an
+        # unconnected handle. MEASURED against a real psqlodbc source: this adapter
+        # could never connect with a connection string until now.
+        @connection = ODBC::Database.new
+        @connection.drvconnect(dsn_string)
         @in_transaction = false
         self
       end
@@ -177,6 +185,11 @@ module Tina4
       end
 
       # List all user tables via ODBC metadata.
+      # ADR-0044 required adapter capability.
+      def get_database_type
+        'odbc'
+      end
+
       def tables
         stmt = @connection.tables
         rows = []
@@ -194,6 +207,7 @@ module Tina4
 
       # Return column metadata for a table via ODBC metadata.
       def columns(table_name)
+        pk = primary_key_columns(table_name)
         stmt = @connection.columns(table_name.to_s)
         result = []
         while (row = stmt.fetch_hash)
@@ -206,7 +220,10 @@ module Tina4
             type: type.to_s,
             nullable: nullable_val.to_i == 1,
             default: default,
-            primary_key: false  # ODBC metadata does not reliably expose PK flag here
+            # Real PK, from the ODBC catalog (SQLPrimaryKeys) - not the old
+            # `false` stub. The write-guard reads primary_key, so without this a
+            # PK-keyed update(table, data) on ODBC could not introspect the key.
+            primary_key: pk.include?(name.to_s.downcase)
           }
         end
         stmt.drop
@@ -216,6 +233,23 @@ module Tina4
         raise e
       end
 
+      # The table's primary-key columns from the ODBC catalog (SQLPrimaryKeys),
+      # down-cased for case-insensitive matching. Empty on any target that does
+      # not report them - the write-guard then requires an explicit filter.
+      def primary_key_columns(table_name)
+        stmt = @connection.primary_keys(table_name.to_s)
+        cols = []
+        while (row = stmt.fetch_hash)
+          col = row["COLUMN_NAME"] || row[:COLUMN_NAME]
+          cols << col.to_s.downcase if col
+        end
+        stmt.drop
+        cols
+      rescue StandardError
+        stmt&.drop rescue nil
+        []
+      end
+
       private
 
       # (No symbolize_keys here: execute_query already hydrates by zipping a

data/lib/tina4/drivers/postgres_driver.rb

@@ -218,6 +218,11 @@ module Tina4
         !rows.empty? && !rows[0][:oid].nil?
       end
 
+      # ADR-0044 required adapter capability.
+      def get_database_type
+        "postgres"
+      end
+
       def tables
         # v3.13.14 (#48): list every user schema; public tables stay bare,
         # others are returned schema-qualified.

data/lib/tina4/drivers/sqlite_driver.rb

@@ -183,6 +183,7 @@ module Tina4
         pragma = schema && identifier?(schema) && identifier?(tbl) ? "#{schema}.table_info(#{tbl})" : "table_info(#{table_name})"
         rows = execute_query("PRAGMA #{pragma}")
         rows.map do |r|
+          pk = r[:pk].to_i
           {
             name: r[:name],
             type: r[:type],
@@ -191,11 +192,20 @@ module Tina4
             # PRAGMA table_info reports `pk` as the 1-BASED POSITION within the
             # primary key, not a boolean: a composite key gives pk=1, pk=2, ...
             # Testing `== 1` reported only the first column of a composite key.
-            primary_key: r[:pk].to_i.positive?
+            primary_key: pk.positive?,
+            # ADR-0044 amendment (Feature 5 Decision 7): null for a non-key
+            # column; for a composite key this IS the declared PRIMARY KEY
+            # (...) order, not table-column order.
+            primary_key_position: pk.positive? ? pk : nil
           }
         end
       end
 
+      # ADR-0044 required adapter capability.
+      def get_database_type
+        "sqlite"
+      end
+
       private
 
       # A safe-to-interpolate SQL identifier (no quoting/escaping needed).

data/lib/tina4/env.rb

@@ -89,7 +89,7 @@ module Tina4
       "TINA4_SWAGGER_VERSION" => "1.0.0",
       "TINA4_LOCALE" => "en",
       "TINA4_DEBUG" => "true",
-      "TINA4_LOG_LEVEL" => "[TINA4_LOG_ALL]"
+      "TINA4_LOG_LEVEL" => "ALL"
     }.freeze
 
     # The ONE env truthiness table. Every env boolean in every Tina4 framework

data/lib/tina4/error_overlay.rb

@@ -11,8 +11,14 @@
 #     Tina4::ErrorOverlay.render_error_overlay(e, request: env)
 #   end
 #
-# Only activate when TINA4_DEBUG is true.
-# In production, call Tina4::ErrorOverlay.render_production_error instead.
+# Only activate when TINA4_DEBUG is true. The production 500 is NOT rendered here —
+# the dispatch renders the generic errors/500 page with an empty error_message
+# (CWE-209), so the exception detail stays in the server log only, never in the body.
+#
+# Sensitive request fields (Authorization / Cookie / Set-Cookie headers and
+# password-like body/param keys) are redacted even in the dev overlay, the frame count
+# is capped, and the caller wraps this render in a rescue, so a broken overlay or a
+# recursive stack still yields a bounded, safe 500.
 
 module Tina4
   module ErrorOverlay
@@ -32,6 +38,18 @@ module Tina4
 
     CONTEXT_LINES = 7
 
+    # OVERLAY-DEC-03: cap the rendered frames so a deep/recursive stack yields a
+    # bounded page, not one source-file read per frame.
+    MAX_FRAMES = 50
+
+    # OVERLAY-DEC-02: request fields whose KEY matches this are masked in the dev
+    # overlay (Authorization/Cookie/Set-Cookie headers via authorization|cookie —
+    # Rack spells them HTTP_AUTHORIZATION / HTTP_COOKIE; password/token/secret/api_key
+    # body/param keys via the rest). Over-matching a benign field is the SAFE direction
+    # in a dev tool — over-masking leaks nothing; under-masking leaks a secret.
+    SENSITIVE_KEY_RE = /password|passwd|secret|token|authorization|cookie|key/i
+    REDACTED = "[redacted]"
+
     class << self
       # Render a rich HTML error overlay.
       #
@@ -50,25 +68,36 @@ module Tina4
         # what actually raised the error.
         captured_at = Time.now.to_f
 
-        # ── Stack trace ──
+        # ── Stack trace (OVERLAY-DEC-03: capped) ──
+        # A recursive stack of thousands of frames would otherwise do one source-file
+        # read per frame and emit an unbounded page; render only the innermost
+        # MAX_FRAMES and note the rest.
         frames_html = +""
         backtrace = exception.backtrace || []
-        backtrace.each do |line|
+        backtrace.first(MAX_FRAMES).each do |line|
           file, lineno, method = parse_backtrace_line(line)
           frames_html << format_frame(file, lineno, method, captured_at: captured_at)
         end
+        hidden = backtrace.length - [backtrace.length, MAX_FRAMES].min
+        if hidden.positive?
+          frames_html << "<div style=\"color:#{SUBTEXT};padding:8px 0;font-size:13px;\">" \
+            "&#8230; #{hidden} more stack frames hidden (truncated at #{MAX_FRAMES})</div>"
+        end
 
-        # ── Request info ──
+        # ── Request info (OVERLAY-DEC-02: sensitive fields redacted) ──
         request_pairs = []
         if request.is_a?(Hash)
           request.each do |k, v|
             key = k.to_s
             if v.is_a?(Hash)
-              v.each { |hk, hv| request_pairs << ["#{key}.#{hk}", hv.to_s] }
+              v.each do |hk, hv|
+                pair_key = "#{key}.#{hk}"
+                request_pairs << [pair_key, redact(pair_key, hv.to_s)]
+              end
             elsif key.start_with?("HTTP_") || %w[REQUEST_METHOD REQUEST_URI SERVER_PROTOCOL
               REMOTE_ADDR SERVER_PORT QUERY_STRING CONTENT_TYPE CONTENT_LENGTH
               method url path].include?(key)
-              request_pairs << [key, v.to_s]
+              request_pairs << [key, redact(key, v.to_s)]
             end
           end
         end
@@ -120,48 +149,6 @@ module Tina4
         HTML
       end
 
-      # Render a safe, generic error page for production.
-      def render_production_error(status_code: 500, message: "Internal Server Error", path: "")
-        # Determine color based on status code
-        code_color = case status_code
-                     when 403 then "#f59e0b"
-                     when 404 then "#3b82f6"
-                     else "#ef4444"
-                     end
-
-        <<~HTML
-          <!DOCTYPE html>
-          <html lang="en">
-          <head>
-          <meta charset="utf-8">
-          <meta name="viewport" content="width=device-width, initial-scale=1">
-          <title>#{status_code} — #{esc(message)}</title>
-          <style>
-          * { box-sizing: border-box; margin: 0; padding: 0; }
-          body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
-          .error-card { background: #1e293b; border: 1px solid #334155; border-radius: 1rem; padding: 3rem; text-align: center; max-width: 520px; width: 90%; }
-          .error-code { font-size: 8rem; font-weight: 900; color: #{code_color}; opacity: 0.6; line-height: 1; margin-bottom: 0.5rem; }
-          .error-title { font-size: 1.5rem; font-weight: 700; margin-bottom: 0.75rem; }
-          .error-msg { color: #94a3b8; font-size: 1rem; margin-bottom: 1.5rem; line-height: 1.5; }
-          .error-path { font-family: 'SF Mono', monospace; background: #0f172a; color: #{code_color}; padding: 0.5rem 1rem; border-radius: 0.5rem; font-size: 0.85rem; word-break: break-all; margin-bottom: 1.5rem; display: inline-block; }
-          .error-home { display: inline-block; padding: 0.6rem 2rem; background: #3b82f6; color: #fff; text-decoration: none; border-radius: 0.5rem; font-size: 0.9rem; font-weight: 600; }
-          .error-home:hover { opacity: 0.9; }
-          .logo { font-size: 1.5rem; margin-bottom: 1rem; opacity: 0.5; }
-          </style>
-          </head>
-          <body>
-          <div class="error-card">
-              <div class="error-code">#{status_code}</div>
-              <div class="error-title">#{esc(message)}</div>
-              <div class="error-msg">Something went wrong while processing your request.</div>
-              #{path.to_s.empty? ? '' : "<div class=\"error-path\">#{esc(path)}</div><br>"}
-              <a href="/" class="error-home">Go Home</a>
-          </div>
-          </body>
-          </html>
-        HTML
-      end
-
       # Return true if TINA4_DEBUG is enabled.
       def is_debug_mode
         Tina4::Env.is_truthy(ENV.fetch("TINA4_DEBUG", ""))
@@ -169,6 +156,13 @@ module Tina4
 
       private
 
+      # Mask a sensitive request value (OVERLAY-DEC-02). Returns "[redacted]" when
+      # +key+ names a secret field (an Authorization/Cookie/Set-Cookie header or a
+      # password/token/secret/key-like body/param key), otherwise the value unchanged.
+      def redact(key, value)
+        key.to_s.match?(SENSITIVE_KEY_RE) ? REDACTED : value
+      end
+
       def esc(text)
         text.to_s
             .gsub("&", "&amp;")