tina4ruby 3.13.137 → 3.13.138

data/lib/tina4/messenger.rb

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-begin
-  require "net/smtp"
-rescue LoadError
-  # net-smtp gem needed on Ruby >= 4.0: gem install net-smtp
-end
-begin
-  require "net/imap"
-rescue LoadError
-  # net-imap gem needed on Ruby >= 4.0: gem install net-imap
-end
-require "base64"
+
+require_relative "base64"
+require_relative "smtp_client"
+require_relative "imap_client"
 require "securerandom"
 require "time"
 require "socket"
@@ -37,17 +35,14 @@ module Tina4
   # "we talked fine and the mailbox is empty". These must fail loud — LOG and
   # RAISE — never be silently swallowed into an empty result. Mirrors the
   # Python master's _IMAP_CONNECTION_ERRORS tuple.
-  #
-  # Built lazily so a missing net/imap gem (LoadError above) doesn't break
-  # loading this file.
   IMAP_CONNECTION_ERRORS = [
     SocketError,            # DNS / host resolution failures
-    IOError,                # closed/broken stream, EOF mid-conversation
+    IOError,                # closed/broken stream, EOF, MailSocket::TimeoutError
     SystemCallError,        # Errno::ECONNREFUSED / ECONNRESET / ETIMEDOUT etc.
-    Timeout::Error,         # connect/read timeout (Net::OpenTimeout descends from this)
+    Timeout::Error,         # kept for callers that wrap Messenger in Timeout.timeout
+    Messenger::ImapClient::Error, # NO / BAD / BYE from the server (was Net::IMAP::Error)
     MessengerError          # our own protocol-failure signal (re-raised as-is)
   ].tap do |errors|
-    errors << Net::IMAP::Error if defined?(Net::IMAP::Error)
     errors << OpenSSL::SSL::SSLError if defined?(OpenSSL::SSL::SSLError)
   end.freeze
 
@@ -124,7 +119,7 @@ module Tina4
       # SMTP encryption: constructor > .env > backward-compat use_tls > default "tls"
       env_encryption = encryption  || ENV["TINA4_MAIL_ENCRYPTION"]
       if env_encryption
-        @encryption = env_encryption.downcase
+        @encryption = normalize_encryption(env_encryption, "mail")
       elsif !use_tls.nil?
         @encryption = use_tls ? "tls" : "none"
       else
@@ -138,7 +133,7 @@ module Tina4
       # IMAP encryption: dedicated env var TINA4_MAIL_IMAP_ENCRYPTION (tls/starttls/none).
       # Defaults to "tls" — IMAPS over implicit TLS on port 993 is the safe industry norm.
       env_imap_enc = imap_encryption || ENV["TINA4_MAIL_IMAP_ENCRYPTION"]
-      @imap_encryption = (env_imap_enc && !env_imap_enc.to_s.empty?) ? env_imap_enc.to_s.downcase : "tls"
+      @imap_encryption = env_imap_enc.nil? ? "tls" : normalize_encryption(env_imap_enc, "IMAP")
       @imap_use_tls    = %w[tls starttls ssl].include?(@imap_encryption)
 
       # IMAP credentials, independent of SMTP. Dedicated
@@ -150,11 +145,18 @@ module Tina4
       @imap_password = imap_password || ENV["TINA4_MAIL_IMAP_PASSWORD"] || @password
     end
 
-    # Send email using Ruby's Net::SMTP
-    # Returns { success: true/false, message: "...", id: "..." }
+    def normalize_encryption(value, label)
+      normalized = value.to_s.strip.downcase
+      unless %w[ssl tls starttls none].include?(normalized)
+        raise ArgumentError, "Unknown #{label} encryption '#{value}'. Valid values: ssl, tls, starttls, none."
+      end
+      normalized
+    end
+    private :normalize_encryption
+
     # The local mailbox, present only once this messenger has captured something
     # (or eagerly, when create_messenger knows it will).
-    attr_accessor :dev_mailbox
+    attr_writer :dev_mailbox
 
     # Should send capture locally instead of talking to SMTP?
     #
@@ -221,11 +223,8 @@ module Tina4
                        normalize_recipients(cc) +
                        normalize_recipients(bcc)
 
-      smtp = Net::SMTP.new(@host, @port)
-      smtp.enable_starttls if @use_tls
-
-      smtp.start(@host, @username, @password, auth_method) do |conn|
-        conn.send_message(raw, @from_address, all_recipients)
+      smtp_session do |smtp|
+        smtp.send_message(raw, @from_address, all_recipients)
       end
 
       Tina4::Log.info("Email sent to #{Array(to).join(', ')}: #{subject}")
@@ -256,11 +255,7 @@ module Tina4
     # Test SMTP connection
     # Returns { success: true/false, message: "..." }
     def test_connection
-      smtp = Net::SMTP.new(@host, @port)
-      smtp.enable_starttls if @use_tls
-      smtp.start(@host, @username, @password, auth_method) do |_conn|
-        # connection succeeded
-      end
+      smtp_session { |_smtp| } # connect, TLS, AUTH, QUIT
       { success: true, message: "SMTP connection successful" }
     rescue => e
       { success: false, message: e.message }
@@ -403,8 +398,7 @@ module Tina4
     def folders
       imap = imap_open("folders")
       begin
-        boxes = imap.list("", "*")
-        (boxes || []).map(&:name)
+        imap.list("", "*")
       rescue *IMAP_CONNECTION_ERRORS => e
         raise imap_fail("folders", e)
       ensure
@@ -477,6 +471,25 @@ module Tina4
 
     # ── SMTP helpers ─────────────────────────────────────────────────────
 
+    # One SMTP session on Tina4::Messenger::SmtpClient:
+    #   implicit TLS  port 465 (as in Python, PHP and Node) or encryption "ssl"
+    #   STARTTLS      encryption "tls" / "starttls"; REQUIRED, so a server that
+    #                 does not offer it fails the send instead of getting the
+    #                 message and the credentials in clear
+    #   plain         "none"
+    # AUTH only when both credentials are set.
+    def smtp_session(&block)
+      authenticate = !auth_method.nil?
+      SmtpClient.start(
+        host: @host, port: @port,
+        tls: @port == SmtpClient::IMPLICIT_TLS_PORT || @encryption == "ssl",
+        starttls: @use_tls,
+        username: authenticate ? @username : nil,
+        password: authenticate ? @password : nil,
+        &block
+      )
+    end
+
     def auth_method
       return :plain if @username && @password
 
@@ -541,19 +554,19 @@ module Tina4
           parts << "Content-Type: text/plain; charset=UTF-8"
           parts << "Content-Transfer-Encoding: base64"
           parts << ""
-          parts << Base64.encode64(text)
+          parts << Tina4::Base64.encode64(text)
           parts << "--#{alt_boundary}"
           parts << "Content-Type: text/html; charset=UTF-8"
           parts << "Content-Transfer-Encoding: base64"
           parts << ""
-          parts << Base64.encode64(body)
+          parts << Tina4::Base64.encode64(body)
           parts << "--#{alt_boundary}--"
         else
           content_type = html ? "text/html" : "text/plain"
           parts << "Content-Type: #{content_type}; charset=UTF-8"
           parts << "Content-Transfer-Encoding: base64"
           parts << ""
-          parts << Base64.encode64(body)
+          parts << Tina4::Base64.encode64(body)
         end
 
         # Attachment parts
@@ -570,19 +583,19 @@ module Tina4
         parts << "Content-Type: text/plain; charset=UTF-8"
         parts << "Content-Transfer-Encoding: base64"
         parts << ""
-        parts << Base64.encode64(text)
+        parts << Tina4::Base64.encode64(text)
         parts << "--#{alt_boundary}"
         parts << "Content-Type: text/html; charset=UTF-8"
         parts << "Content-Transfer-Encoding: base64"
         parts << ""
-        parts << Base64.encode64(body)
+        parts << Tina4::Base64.encode64(body)
         parts << "--#{alt_boundary}--"
       else
         content_type = html ? "text/html" : "text/plain"
         parts << "Content-Type: #{content_type}; charset=UTF-8"
         parts << "Content-Transfer-Encoding: base64"
         parts << ""
-        parts << Base64.encode64(body)
+        parts << Tina4::Base64.encode64(body)
       end
 
       parts.join("\r\n")
@@ -602,7 +615,7 @@ module Tina4
         return []
       end
 
-      encoded = content.is_a?(String) && !content.ascii_only? ? Base64.encode64(content) : Base64.encode64(content.to_s)
+      encoded = content.is_a?(String) && !content.ascii_only? ? Tina4::Base64.encode64(content) : Tina4::Base64.encode64(content.to_s)
 
       lines << "Content-Type: #{mime}; name=\"#{filename}\""
       lines << "Content-Disposition: attachment; filename=\"#{filename}\""
@@ -616,7 +629,7 @@ module Tina4
       if value.ascii_only?
         value
       else
-        "=?UTF-8?B?#{Base64.strict_encode64(value)}?="
+        "=?UTF-8?B?#{Tina4::Base64.strict_encode64(value)}?="
       end
     end
 
@@ -653,13 +666,31 @@ module Tina4
     # failure this FAILS LOUD — logs and raises MessengerConnectionError —
     # rather than swallowing the error into an empty result.
     def imap_open(method)
-      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
-      imap.login(@imap_username, @imap_password)
-      imap
+      imap_login
     rescue *IMAP_CONNECTION_ERRORS => e
       raise imap_fail(method, e)
     end
 
+    # Connect with the configured transport and log in. "tls"/"ssl" is implicit
+    # TLS (IMAPS), "starttls" is a plain connect upgraded with STARTTLS before
+    # the credentials are sent (it used to open implicit TLS instead, so a
+    # STARTTLS-only server on 143 could not be reached), anything else is plain.
+    # LOGIN only when both credentials are set, as in the Python master.
+    def imap_login
+      imap = ImapClient.new(
+        @imap_host, port: @imap_port,
+        tls: %w[tls ssl].include?(@imap_encryption),
+        starttls: @imap_encryption == "starttls"
+      )
+      begin
+        imap.login(@imap_username, @imap_password) if @imap_username && @imap_password
+      rescue StandardError
+        imap_cleanup(imap)
+        raise
+      end
+      imap
+    end
+
     # Best-effort teardown of an IMAP connection. Never raises.
     def imap_cleanup(imap)
       return if imap.nil?
@@ -694,12 +725,12 @@ module Tina4
     # test_imap_connection). Read methods use imap_open + ensure directly so
     # they can fail loud.
     def imap_connect(&block)
-      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
-      imap.login(@imap_username, @imap_password)
-      result = block.call(imap)
-      imap.logout
-      imap.disconnect
-      result
+      imap = imap_login
+      begin
+        block.call(imap)
+      ensure
+        imap_cleanup(imap)
+      end
     end
 
     # An inbox() item — EXACTLY these seven keys (decisions doc G4):
@@ -828,7 +859,7 @@ module Tina4
         line = raw_line.chomp
         if current_key && line =~ /\A[ \t]/
           headers[current_key] = "#{headers[current_key]} #{line.strip}"
-        elsif (m = line.match(/\A([\w!\#$%&'*+\-.^_`|~]+):[ \t]?(.*)\z/))
+        elsif (m = line.match(/\A([\w!\#$%&'*+\-.^`|~]+):[ \t]?(.*)\z/))
           current_key = m[1]
           headers[current_key] = m[2]
         end
@@ -846,7 +877,7 @@ module Tina4
 
         decoded = case encoding
                   when "B"
-                    Base64.decode64(encoded)
+                    Tina4::Base64.decode64(encoded)
                   when "Q"
                     encoded.gsub("_", " ").gsub(/=([0-9A-Fa-f]{2})/) { [$1].pack("H2") }
                   else
@@ -892,7 +923,7 @@ module Tina4
       headers = header_body[0]
 
       if headers =~ /Content-Transfer-Encoding:\s*base64/i
-        Base64.decode64(body).force_encoding("UTF-8")
+        Tina4::Base64.decode64(body).force_encoding("UTF-8")
       elsif headers =~ /Content-Transfer-Encoding:\s*quoted-printable/i
         body.gsub(/=\r?\n/, "").gsub(/=([0-9A-Fa-f]{2})/) { [$1].pack("H2") }
       else
@@ -921,7 +952,7 @@ module Tina4
       body = header_body[1].sub(/\r?\n\z/, "")
 
       if headers =~ /Content-Transfer-Encoding:\s*base64/i
-        Base64.decode64(body)
+        Tina4::Base64.decode64(body)
       elsif headers =~ /Content-Transfer-Encoding:\s*quoted-printable/i
         body.gsub(/=\r?\n/, "").gsub(/=([0-9A-Fa-f]{2})/) { [$1].pack("H2") }.b
       else

data/lib/tina4/metrics.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require 'json'
 require 'open3'

data/lib/tina4/middleware.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-require "cgi"
+
+require "cgi/escape"
 
 module Tina4
   class Middleware
@@ -789,9 +795,24 @@ module Tina4
         true
       end
 
+      # The canonical security header set (SECHDR-DEC-01) without HSTS, as
+      # [name, value] pairs, with the env overrides applied. The built-in
+      # server puts exactly this on its own transport rejections (ADR-0068),
+      # which are written before the request's scheme is known.
+      def canonical_headers
+        [
+          ["X-Frame-Options", ENV["TINA4_FRAME_OPTIONS"] || "SAMEORIGIN"],
+          ["X-Content-Type-Options", "nosniff"],
+          ["Content-Security-Policy", ENV["TINA4_CSP"] || "default-src 'self'"],
+          ["Referrer-Policy", ENV["TINA4_REFERRER_POLICY"] || "strict-origin-when-cross-origin"],
+          ["X-XSS-Protection", "0"],
+          ["Permissions-Policy", ENV["TINA4_PERMISSIONS_POLICY"] || "camera=(), microphone=(), geolocation=()"]
+        ]
+      end
+
       def before_security(request, response)
-        response.headers["X-Frame-Options"] = ENV["TINA4_FRAME_OPTIONS"] || "SAMEORIGIN"
-        response.headers["X-Content-Type-Options"] = "nosniff"
+        warn_csp_default_once if ENV["TINA4_CSP"].nil?
+        canonical_headers.each { |name, value| response.headers[name] = value }
 
         # HSTS is HTTPS-only (SECHDR-DEC-02): a downgrade-protection header on a
         # plain-HTTP response is inert at best and ships a bad max-age on an
@@ -806,12 +827,6 @@ module Tina4
           response.headers["Strict-Transport-Security"] = "max-age=#{hsts}; includeSubDomains"
         end
 
-        warn_csp_default_once if ENV["TINA4_CSP"].nil?
-        response.headers["Content-Security-Policy"] = ENV["TINA4_CSP"] || "default-src 'self'"
-        response.headers["Referrer-Policy"] = ENV["TINA4_REFERRER_POLICY"] || "strict-origin-when-cross-origin"
-        response.headers["X-XSS-Protection"] = "0"
-        response.headers["Permissions-Policy"] = ENV["TINA4_PERMISSIONS_POLICY"] || "camera=(), microphone=(), geolocation=()"
-
         [request, response]
       end
 

data/lib/tina4/migration.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "fileutils"
 
 module Tina4

data/lib/tina4/model_collection.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # A list of ORM models that ALSO carries the total rows matching the query.

data/lib/tina4/mqtt.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "socket"
 require "securerandom"
 require_relative "mqtt_message"
+require_relative "database_url"
 
 module Tina4
   # Any MQTT protocol / connection failure.
@@ -166,7 +173,7 @@ module Tina4
       scheme = raw[%r{\A([A-Za-z][A-Za-z0-9+.-]*)://}, 1]&.downcase
       unless scheme.nil? || %w[mqtt tcp mqtts].include?(scheme)
         raise ArgumentError,
-              "unsupported MQTT url scheme #{scheme.inspect} in #{raw.inspect} — " \
+              "unsupported MQTT url scheme #{scheme.inspect} in #{Tina4::DatabaseUrl.redact(raw).inspect} — " \
               "this client speaks mqtt://, tcp:// or mqtts:// (TLS). " \
               "WebSocket transports are not implemented."
       end
@@ -185,7 +192,7 @@ module Tina4
       end
 
       match = rest.match(%r{\A(?<host>\[[^\]]+\]|[^:/]+)(?::(?<port>\d+))?(?:/.*)?\z})
-      raise ArgumentError, "malformed MQTT url #{raw.inspect} — expected mqtt://host:port" unless match
+      raise ArgumentError, "malformed MQTT url #{Tina4::DatabaseUrl.redact(raw).inspect} — expected mqtt://host:port" unless match
 
       {
         host: match[:host].delete_prefix("[").delete_suffix("]"),

data/lib/tina4/mqtt_message.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # One MQTT 3.1.1 application message as delivered by the broker.

data/lib/tina4/orm.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
+require_relative "parse_json"
 
 module Tina4
   # Convert a snake_case name to camelCase.
@@ -139,7 +146,8 @@ module Tina4
         @soft_delete_field = val
       end
 
-      # Field mapping: { 'db_column' => 'ruby_attribute' }
+      # Field mapping: { 'ruby_attribute' => 'db_column' } (get_db_column,
+      # to_db_hash and from_hash all read it in this direction).
       def field_mapping
         @field_mapping || {}
       end
@@ -310,13 +318,13 @@ module Tina4
             # REL-SOFTDELETE-TRAVERSAL: a soft-deleted child must not surface
             # through eager traversal (parity with lazy + the finders).
             soft = klass.soft_delete ? " AND (#{klass.soft_delete_field} IS NULL OR #{klass.soft_delete_field} = 0)" : ""
-            order_col = klass.primary_key_field || :id
+            order_col = klass.get_db_column(klass.primary_key_field || :id)
             # REL-EAGER-UNBOUNDED: chunk the parent PKs so the IN list stays
             # bounded, and page each chunk so no relation is truncated.
             related_records = []
             pk_values.each_slice(EAGER_IN_CHUNK) do |chunk|
               placeholders = chunk.map { "?" }.join(",")
-              sql = "SELECT * FROM #{klass.table_name} WHERE #{fk} IN (#{placeholders})#{soft} ORDER BY #{order_col}"
+              sql = "SELECT * FROM #{klass.table_name} WHERE #{klass.get_db_column(fk)} IN (#{placeholders})#{soft} ORDER BY #{order_col}"
               offset = 0
               loop do
                 batch = klass.db.fetch(sql, chunk, limit: EAGER_PAGE_SIZE, offset: offset).to_a
@@ -331,8 +339,9 @@ module Tina4
 
             # Group by FK
             grouped = {}
+            fk_attribute = klass.attribute_for(fk)
             related_records.each do |record|
-              fk_val = record.__send__(fk.to_sym) if record.respond_to?(fk.to_sym)
+              fk_val = record.__send__(fk_attribute) if record.respond_to?(fk_attribute)
               (grouped[fk_val] ||= []) << record
             end
 
@@ -347,7 +356,7 @@ module Tina4
             end
 
           when :belongs_to
-            fk = rel[:foreign_key] || "#{rel_name}_id"
+            fk = attribute_for(rel[:foreign_key] || "#{rel_name}_id")
             fk_values = instances.map { |inst|
               inst.respond_to?(fk.to_sym) ? inst.__send__(fk.to_sym) : nil
             }.compact.uniq
@@ -360,7 +369,7 @@ module Tina4
             related_records = []
             fk_values.each_slice(EAGER_IN_CHUNK) do |chunk|
               placeholders = chunk.map { "?" }.join(",")
-              sql = "SELECT * FROM #{klass.table_name} WHERE #{related_pk} IN (#{placeholders})#{soft}"
+              sql = "SELECT * FROM #{klass.table_name} WHERE #{klass.get_db_column(related_pk)} IN (#{placeholders})#{soft}"
               # One row per distinct PK, so limit == chunk size (default 100 would truncate a full chunk).
               related_records.concat(klass.db.fetch(sql, chunk, limit: chunk.length).to_a.map { |row| klass.from_hash(row) })
             end
@@ -771,7 +780,7 @@ module Tina4
           fdef = field_definitions[attr_name.to_sym]
           if fdef && fdef[:type] == :json && value.is_a?(String)
             begin
-              value = JSON.parse(value)
+              value = Tina4.parse_json(value)
             rescue JSON::ParserError
               # leave the raw string in place
             end
@@ -791,7 +800,7 @@ module Tina4
       # spec/orm_spec.rb:78 verifies public access. find_by_filter stays
       # public for the same reason; both are part of the documented API.
       def find_by_id(id)
-        pk = primary_key_field || :id
+        pk = get_db_column(primary_key_field || :id)
         sql = "SELECT * FROM #{table_name} WHERE #{pk} = ?"
         if soft_delete
           sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
@@ -829,6 +838,46 @@ module Tina4
         col.to_sym
       end
 
+      # tina4: ADR-0069 - the ONE resolver for caller-supplied field names that
+      # become SQL identifiers (AutoCrud filter/sort/write body, find(hash)). A
+      # key resolves only when it is a DECLARED field's attribute name or that
+      # field's mapped DB column, and the declared attribute is returned.
+      # Anything else returns nil, so the caller rejects or drops it before any
+      # SQL is built.
+      def resolve_field(key) # -> Symbol or nil
+        wanted = key.to_s
+        field_definitions.each_key do |attribute|
+          # the model's own attribute -> column mapping
+          return attribute if wanted == attribute.to_s || wanted == get_db_column(attribute).to_s
+        end
+        nil
+      end
+
+      # A primary-key value that arrived as text (a URL {id}, a GraphQL ID),
+      # ready to bind. An integer key accepts only an integer string and answers
+      # nil otherwise, so "3x" can never address row 3; any other key type (a
+      # string natural key) is returned unchanged rather than coerced.
+      def coerce_primary_key(raw) # -> value or nil
+        pk = primary_key_field || :id
+        return raw unless field_definitions.dig(pk.to_sym, :type) == :integer
+        return raw if raw.is_a?(Integer)
+
+        raw.to_s.match?(/\A-?\d+\z/) ? raw.to_s.to_i : nil
+      end
+
+      # The DB column of the declared field +key+ resolves to (see resolve_field).
+      def resolve_field_column(key) # -> String or nil
+        attribute = resolve_field(key)
+        attribute && get_db_column(attribute).to_s
+      end
+
+      # The attribute that holds +name+, whether +name+ is the attribute itself
+      # or the DB column it maps to (the reverse of get_db_column). Relationship
+      # foreign keys accept either spelling.
+      def attribute_for(name) # -> Symbol
+        resolve_field(name) || name.to_sym
+      end
+
       private
 
       def auto_discover_db
@@ -838,7 +887,13 @@ module Tina4
       end
 
       def find_by_filter(filter, limit: 100, offset: nil, order_by: nil)
-        where_parts = filter.keys.map { |k| "#{k} = ?" }
+        # ADR-0069: every key must resolve to a declared field's column.
+        where_parts = filter.keys.map do |key|
+          column = resolve_field_column(key)
+          raise ArgumentError, "Unknown filter field '#{key}' for model #{name.to_s.split('::').last}" unless column
+
+          "#{column} = ?"
+        end
         sql = "SELECT * FROM #{table_name} WHERE #{where_parts.join(' AND ')}"
         if soft_delete
           sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
@@ -891,7 +946,7 @@ module Tina4
       @assigned_fields = []
       # Accept a JSON object string (parity with Python/PHP/Node):
       #   Widget.new('{"id":1,"name":"alpha"}')
-      attributes = JSON.parse(attributes) if attributes.is_a?(String)
+      attributes = Tina4.parse_json(attributes) if attributes.is_a?(String)
       # A single model is one record — reject an Array with a clear message.
       if attributes.is_a?(Array)
         raise ArgumentError,
@@ -973,9 +1028,10 @@ module Tina4
     # Addressing a row by one column of a composite key matches every row
     # sharing that value. Feature 4 removed that from the raw write path; this
     # is the same rule for the ORM above it.
+    # { db_column => value } for every key column: it addresses the row in SQL.
     def pk_filter
       self.class.primary_key_fields.each_with_object({}) do |name, acc|
-        acc[name] = __send__(name) if respond_to?(name)
+        acc[self.class.get_db_column(name)] = __send__(name) if respond_to?(name)
       end
     end
 
@@ -1500,7 +1556,7 @@ module Tina4
       pk_value = __send__(pk)
       return nil unless pk_value
 
-      where = "#{fk} = ?"
+      where = "#{klass.get_db_column(fk)} = ?"
       # REL-SOFTDELETE-TRAVERSAL: exclude a soft-deleted related row.
       if klass.soft_delete
         where += " AND (#{klass.soft_delete_field} IS NULL OR #{klass.soft_delete_field} = 0)"
@@ -1520,13 +1576,13 @@ module Tina4
       pk_value = __send__(pk)
       return [] unless pk_value
 
-      where = "#{fk} = ?"
+      where = "#{klass.get_db_column(fk)} = ?"
       # REL-SOFTDELETE-TRAVERSAL: a soft-deleted child must not surface through
       # parent.children, consistent with the finders' default exclusion.
       if klass.soft_delete
         where += " AND (#{klass.soft_delete_field} IS NULL OR #{klass.soft_delete_field} = 0)"
       end
-      order_col = klass.primary_key_field || :id
+      order_col = klass.get_db_column(klass.primary_key_field || :id)
       sql = "SELECT * FROM #{klass.table_name} WHERE #{where} ORDER BY #{order_col}"
       # REL-EAGER-UNBOUNDED: page through ALL children rather than silently capping
       # at the default fetch limit (was 100), so the tail is never lost.
@@ -1547,8 +1603,8 @@ module Tina4
       return nil unless rel
 
       klass = Object.const_get(rel[:class_name])
-      fk = rel[:foreign_key] || "#{name}_id"
-      fk_value = __send__(fk.to_sym) if respond_to?(fk.to_sym)
+      fk = self.class.attribute_for(rel[:foreign_key] || "#{name}_id")
+      fk_value = __send__(fk) if respond_to?(fk)
       return nil unless fk_value
 
       @relationship_cache[name] = klass.find(fk_value)

data/lib/tina4/parse_json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+
+require "json"
+
+module Tina4
+  # JSON.parse for JSON that arrives from outside the process (request bodies,
+  # tokens, API responses, queue payloads), with the duplicate-key rule pinned:
+  # the LAST occurrence of a repeated key wins.
+  #
+  # That is what Python's json.loads, PHP's json_decode and JavaScript's
+  # JSON.parse do, and what the json gem did until 3.0, which raises on a
+  # duplicate key by default. tina4ruby does not pin the json gem (it is a
+  # default gem), so without this the same request would parse in an app that
+  # resolved json 2.x and fail in one that resolved 3.x. The option is ignored
+  # by json versions that predate it, which already take the last key.
+  def self.parse_json(text, **options)
+    JSON.parse(text, allow_duplicate_key: true, **options)
+  end
+end