tina4ruby 3.13.137 → 3.13.139

data/lib/tina4/api.rb

@@ -1,11 +1,19 @@
 # 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 "net/http"
 require "openssl"
 require "uri"
 require "json"
-require "base64"
+require_relative "base64"
 require "securerandom"
+require_relative "parse_json"
+require_relative "ssrf"
 
 module Tina4
   # Statuses that warrant an automatic retry when max_retries > 0: rate-limit
@@ -101,7 +109,7 @@ module Tina4
     def initialize(base_url, headers: {}, timeout: 30,
                    bearer_token: nil, username: nil, password: nil,
                    verify_ssl: nil, max_retries: 0, retry_backoff: 0.5,
-                   transport: nil, cookies: false)
+                   transport: nil, cookies: false, allow_hosts: nil)
       if !transport.nil? && !transport.respond_to?(:call)
         raise ArgumentError, "transport must respond to #call(method, url, headers, body, timeout)"
       end
@@ -123,6 +131,8 @@ module Tina4
       @transport = transport
       @cookies_enabled = cookies ? true : false
       @cookies = {}
+      # SSRF guard (ADR-0084): explicit allow-list of hosts / host:port / CIDRs.
+      @allow_hosts = allow_hosts || []
 
       # Bearer wins over basic-auth when both passed
       if bearer_token
@@ -258,6 +268,7 @@ module Tina4
       headers = @headers.dup
       cookie = cookie_header
       headers["Cookie"] = cookie if @cookies_enabled && cookie
+      headers = origin_headers(uri, headers)
 
       return download_via_transport(uri, headers, dest_path) if @transport
 
@@ -277,7 +288,7 @@ module Tina4
     end
 
     def set_basic_auth(username, password)
-      @headers["Authorization"] = "Basic #{Base64.strict_encode64("#{username}:#{password}")}"
+      @headers["Authorization"] = "Basic #{Tina4::Base64.strict_encode64("#{username}:#{password}")}"
       self
     end
 
@@ -447,10 +458,21 @@ module Tina4
                       when "HEAD"   then Net::HTTP::Head
                       else raise ArgumentError, "unsupported stream method: #{method}"
                       end
+      # SSRF guard (ADR-0084): refuse a private/internal target before connect.
+      begin
+        Tina4::Ssrf.guard_url!(uri, @allow_hosts)
+      rescue Tina4::SsrfError => e
+        raise APIStreamError.new(e.message)
+      end
+
       request = request_class.new(uri)
       apply_headers(request, headers || {})
       cookie = cookie_header
       request["Cookie"] = cookie if @cookies_enabled && cookie
+      unless same_origin?(uri, URI.parse(@base_url))
+        request.delete("Authorization")
+        request.delete("Cookie")
+      end
       if body
         request.body = body.is_a?(String) ? body : JSON.generate(body)
         request["Content-Type"] = content_type if content_type
@@ -458,12 +480,22 @@ module Tina4
         request["Content-Type"] = content_type
       end
 
+      # ADR-0060: connect_timeout (else TINA4_API_CONNECT_TIMEOUT, else 10s)
+      # bounds establishment and raises Net::OpenTimeout; timeout (else
+      # TINA4_API_TIMEOUT, else the client timeout) bounds the WHOLE stream and
+      # raises APIStreamTimeoutError. Both are Timeout::Error. `timeout` used to
+      # be only Net::HTTP's per-read idle timeout, so a server that kept
+      # dripping data streamed forever.
+      connect_bound = connect_timeout || stream_env_seconds("TINA4_API_CONNECT_TIMEOUT", 10.0)
+      total_bound = timeout || stream_env_seconds("TINA4_API_TIMEOUT", @timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + total_bound
+
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
       http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
-      http.open_timeout = connect_timeout || @timeout
-      http.read_timeout = timeout || @timeout
-      http.write_timeout = (timeout || @timeout) if http.respond_to?(:write_timeout=)
+      http.open_timeout = [connect_bound, total_bound].min
+      http.read_timeout = total_bound
+      http.write_timeout = total_bound if http.respond_to?(:write_timeout=)
 
       http.start do |conn|
         conn.request(request) do |response|
@@ -473,9 +505,26 @@ module Tina4
             raise APIStreamError.new("stream returned HTTP #{status}", status)
           end
           store_cookies(response.get_fields("Set-Cookie"))
-          response.read_body { |chunk| yield chunk }
+          response.read_body do |chunk|
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise APIStreamTimeoutError, "stream exceeded its total timeout of #{total_bound}s" unless remaining.positive?
+
+            # The next read may wait only for what is left of the deadline.
+            # tina4: bounded per read, so a server dripping single bytes inside
+            # one chunk header can overrun by one read at most.
+            conn.read_timeout = remaining
+            yield chunk
+          end
         end
       end
+    rescue Net::ReadTimeout, Net::WriteTimeout
+      raise APIStreamTimeoutError, "stream exceeded its total timeout of #{total_bound}s"
+    end
+
+    # A positive number of seconds from an env var; anything else falls back.
+    def stream_env_seconds(name, fallback)
+      seconds = Float(ENV[name].to_s.strip, exception: false)
+      seconds&.positive? ? seconds : fallback
     end
 
     def build_uri(path, params = {})
@@ -488,6 +537,10 @@ module Tina4
       uri
     end
 
+    def origin_headers(uri, headers)
+      same_origin?(uri, URI.parse(@base_url)) ? headers : strip_cross_origin(headers)
+    end
+
     def apply_headers(request, extra_headers)
       @headers.merge(extra_headers).each do |key, value|
         request[key] = value
@@ -523,6 +576,7 @@ module Tina4
       request.each_header { |key, value| headers[key] = value }
       cookie = cookie_header
       headers["cookie"] = cookie if @cookies_enabled && cookie
+      headers = origin_headers(uri, headers)
       body = request.body
 
       if @transport
@@ -552,6 +606,12 @@ module Tina4
       current_body = body
 
       loop do
+        # SSRF guard (ADR-0084): re-validated per hop, so a redirect to a
+        # private/internal address is refused even when the initial URL was
+        # public. Raises SsrfError; attempt_request/download turn it into a
+        # status-0 error response.
+        Tina4::Ssrf.guard_url!(current_uri, @allow_hosts)
+
         http = Net::HTTP.new(current_uri.host, current_uri.port)
         http.use_ssl = current_uri.scheme == "https"
         # Only disable verification when EXPLICITLY false — nil/true keep the
@@ -803,6 +863,12 @@ module Tina4
     end
   end
 
+  # A stream_* call ran past its total timeout (timeout:, else
+  # TINA4_API_TIMEOUT). A Timeout::Error, as Python's ApiTimeoutError is a
+  # TimeoutError, and deliberately NOT an APIStreamError: callers such as
+  # AiClient treat APIStreamError as an HTTP status failure.
+  class APIStreamTimeoutError < Timeout::Error; end
+
   class APIResponse
     attr_reader :status, :body, :headers, :error, :path
 
@@ -821,7 +887,7 @@ module Tina4
     end
 
     def json
-      @json ||= JSON.parse(@body)
+      @json ||= Tina4.parse_json(@body)
     rescue JSON::ParserError, TypeError
       {}
     end

data/lib/tina4/auth.rb

@@ -1,9 +1,17 @@
 # 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 "openssl"
-require "base64"
+require_relative "base64"
 require "json"
 require "fileutils"
 require "securerandom"
+require_relative "parse_json"
+require_relative "secret_file"
 
 module Tina4
   module Auth
@@ -60,13 +68,72 @@ module Tina4
     # rejected for no real reason; RFC 7519 explicitly allows "a small leeway".
     JWT_LEEWAY_SECONDS = 60
 
+    # Token purposes that are never an identity (ADR-0079 s1). Frond's
+    # form_token signs a JWT with the same TINA4_SECRET as an auth token, marked
+    # "type" => "form". A form token proves where a write came from, never who
+    # the caller is, so every identity gate refuses these purposes. valid_token
+    # itself stays purpose-neutral: CsrfMiddleware needs it for form tokens.
+    NON_IDENTITY_TOKEN_TYPES = %w[form].freeze
+
+    # Minimum HMAC key length in bytes (ADR-0079 s2): the HS256 output size,
+    # RFC 7518 s3.2. A blank key is the shortest case - anyone can reproduce an
+    # HMAC made with it.
+    MIN_SECRET_BYTES = 32
+
+    # The HMAC signing key is blank or shorter than MIN_SECRET_BYTES. An
+    # ArgumentError, Ruby's equivalent of Python's ValueError.
+    class InsecureSecretError < ArgumentError; end
+
     class << self
+      # Explicitly provision an RS256 key pair in <root_dir>/.keys (opt-in). The
+      # framework never calls this on its own: a blank TINA4_SECRET used to mint
+      # a key pair implicitly at boot (ADR-0079 s2).
       def setup(root_dir = Dir.pwd)
         @keys_dir = File.join(root_dir, KEYS_DIR)
         FileUtils.mkdir_p(@keys_dir)
         ensure_keys
       end
 
+      # Point RS256 at <root_dir>/.keys WITHOUT creating anything. Boot uses
+      # this, so an operator-provisioned key pair there keeps working.
+      def keys_root=(root_dir)
+        @keys_dir = File.join(root_dir, KEYS_DIR)
+        @private_key = nil
+        @public_key = nil
+      end
+
+      # True when a VERIFIED payload may stand for a caller's identity. A payload
+      # whose "type" is a reserved non-identity purpose (a Frond form token) is
+      # refused; application payloads are otherwise untouched.
+      def identity_payload?(payload)
+        payload.is_a?(Hash) && !NON_IDENTITY_TOKEN_TYPES.include?(payload["type"])
+      end
+
+      # The actionable error for a weak HMAC key, or nil when the key is usable.
+      def insecure_secret_message(secret)
+        length = secret.to_s.bytesize
+        return nil if length >= MIN_SECRET_BYTES
+
+        what = length.zero? ? "is not set" : "is #{length} bytes"
+        "Auth: TINA4_SECRET #{what}; an HMAC JWT secret must be at least " \
+          "#{MIN_SECRET_BYTES} bytes. Generate one with `openssl rand -hex 32` and set " \
+          "TINA4_SECRET in your environment or .env."
+      end
+
+      # Refuse to boot with a secret that makes tokens forgeable (ADR-0079 s2).
+      # Outside dev a blank TINA4_SECRET is refused; in any mode a set-but-short
+      # one is refused. An operator-provisioned RS256 key pair in .keys/ stands
+      # in for the secret. Raises InsecureSecretError with the actionable message.
+      def require_boot_secret!
+        return if rsa_keys_present?
+
+        secret = ENV["TINA4_SECRET"].to_s
+        return if secret.empty? && dev?
+
+        message = insecure_secret_message(secret)
+        raise InsecureSecretError, message if message
+      end
+
       # Boot-time bootstrap (run once after env load, before auth is used).
       #
       # Mirrors the Python master's tina4_python.auth.ensure_dev_secret:
@@ -100,12 +167,10 @@ module Tina4
           local_path = File.join(root_dir, ".env.local")
           # If the file exists and does not end in a newline, prepend one so the
           # new key lands on its own line rather than gluing onto the last value.
-          prefix = ""
-          if File.exist?(local_path)
-            content = File.read(local_path)
-            prefix = "\n" if !content.empty? && !content.end_with?("\n")
+          SecretFile.update(local_path) do |content|
+            prefix = !content.empty? && !content.end_with?("\n") ? "\n" : ""
+            content + "#{prefix}TINA4_SECRET=#{new_secret}\n"
           end
-          File.open(local_path, "a") { |f| f.write("#{prefix}TINA4_SECRET=#{new_secret}\n") }
           log_info("Auth: generated a development secret, saved to .env.local (gitignored)")
         rescue StandardError => e
           # Keep the in-memory secret for this run; just warn. Never crash boot.
@@ -117,15 +182,17 @@ module Tina4
 
       # ── HS256 helpers (stdlib only, no gem) ──────────────────────
 
-      # Returns true when SECRET env var is set and no RSA keys exist in .keys/
+      # HMAC with TINA4_SECRET unless an RS256 key pair has been provisioned in
+      # .keys/ (kept for existing deployments). A blank secret no longer falls
+      # back to an implicitly generated key pair: it is refused (ADR-0079 s2).
       def use_hmac?
-        secret = ENV["TINA4_SECRET"]
-        return false if secret.nil? || secret.empty?
+        !rsa_keys_present?
+      end
 
-        # If RSA keys already exist on disk, prefer RS256 for backward compat
+      def rsa_keys_present?
         @keys_dir ||= File.join(Dir.pwd, KEYS_DIR)
-        !(File.exist?(File.join(@keys_dir, "private.pem")) &&
-          File.exist?(File.join(@keys_dir, "public.pem")))
+        File.exist?(File.join(@keys_dir, "private.pem")) &&
+          File.exist?(File.join(@keys_dir, "public.pem"))
       end
 
       # Lazy per-call secret resolver. When the secret is blank, emit the
@@ -139,7 +206,7 @@ module Tina4
 
       # Base64url-encode without padding (JWT spec)
       def base64url_encode(data)
-        Base64.urlsafe_encode64(data, padding: false)
+        Tina4::Base64.urlsafe_encode64(data, padding: false)
       end
 
       # Base64url-decode (handles missing padding)
@@ -147,7 +214,7 @@ module Tina4
         # Add back padding
         remainder = str.length % 4
         str += "=" * ((4 - remainder) % 4) if remainder != 0
-        Base64.urlsafe_decode64(str)
+        Tina4::Base64.urlsafe_decode64(str)
       end
 
       # Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else
@@ -174,6 +241,9 @@ module Tina4
       # HMAC the signing input with the digest the algorithm actually names, so the
       # header's "alg" can never disagree with the bytes we produced.
       def hmac_signature(algorithm, secret, signing_input)
+        weak = insecure_secret_message(secret)
+        raise InsecureSecretError, weak if weak
+
         OpenSSL::HMAC.digest(HMAC_ALGORITHMS.fetch(algorithm).new, secret.to_s, signing_input)
       end
 
@@ -200,10 +270,10 @@ module Tina4
       def decode_envelope(token, algorithm)
         parts = token.to_s.split(".")
         return nil unless parts.length == 3
-        return nil unless JSON.parse(base64url_decode(parts[0]))["alg"] == algorithm
+        return nil unless Tina4.parse_json(base64url_decode(parts[0]))["alg"] == algorithm
         return nil unless yield("#{parts[0]}.#{parts[1]}", base64url_decode(parts[2]))
 
-        payload = JSON.parse(base64url_decode(parts[1]))
+        payload = Tina4.parse_json(base64url_decode(parts[1]))
         now = Time.now.to_i
 
         # RFC 7519 s4.1.4: "The processing of the 'exp' claim requires that the
@@ -247,6 +317,15 @@ module Tina4
         # configuration error that must surface, not become a nil "invalid token".
         alg = resolve_algorithm(algorithm)
 
+        # A blank or short key verifies tokens anyone can mint, so the token is
+        # REJECTED (fail closed with a 401, never a 500) and the operator is
+        # told why. ADR-0079 s2.
+        weak = insecure_secret_message(secret)
+        if weak
+          log_warning(weak)
+          return nil
+        end
+
         decode_envelope(token, alg) do |input, signature|
           expected = hmac_signature(alg, secret, input)
           # Constant-time comparison to prevent timing attacks. Lengths must match
@@ -304,7 +383,6 @@ module Tina4
         elsif use_hmac?
           hmac_encode(claims, hmac_secret, algorithm: algorithm)
         else
-          ensure_keys
           rs256_encode(claims)
         end
       end
@@ -321,7 +399,6 @@ module Tina4
         if use_hmac?
           hmac_decode(token, hmac_secret) # returns Hash payload or nil
         else
-          ensure_keys
           rs256_decode(token)
         end
       end
@@ -361,7 +438,7 @@ module Tina4
         return nil unless parts.length == 3
 
         payload_json = base64url_decode(parts[1])
-        JSON.parse(payload_json)
+        Tina4.parse_json(payload_json)
       rescue ArgumentError, JSON::ParserError
         nil
       end
@@ -401,10 +478,11 @@ module Tina4
         # than this process's env-resolved defaults.
         payload = if secret || algorithm
                     hmac_decode(token, secret || hmac_secret, algorithm: algorithm)
-                  elsif valid_token(token)
-                    get_payload(token)
+                  else
+                    valid_token(token)
                   end
-        return payload if payload
+        # A form token is not an identity (ADR-0079 s1).
+        return identity_payload?(payload) ? payload : nil if payload
 
         # API_KEY bypass — timing-safe comparison via validate_api_key
         # (OpenSSL.fixed_length_secure_compare). Parity with Python's
@@ -445,9 +523,13 @@ module Tina4
           token = Regexp.last_match(1)
 
           # JWT first, then the API key — same order and same payload shape as
-          # authenticate_request above (and as Python/PHP/Node).
-          if valid_token(token)
-            env["tina4.auth"] = get_payload(token)
+          # authenticate_request above (and as Python/PHP/Node). A form token is
+          # not an identity (ADR-0079 s1).
+          payload = valid_token(token)
+          if payload
+            return false unless identity_payload?(payload)
+
+            env["tina4.auth"] = payload
             return true
           end
 
@@ -564,7 +646,7 @@ module Tina4
       def generate_keys
         Tina4::Log.info("Generating RSA key pair for JWT authentication")
         key = OpenSSL::PKey::RSA.generate(2048)
-        File.write(private_key_path, key.to_pem)
+        SecretFile.update(private_key_path) { key.to_pem }
         File.write(public_key_path, key.public_key.to_pem)
         @private_key = nil
         @public_key = nil

data/lib/tina4/auto_crud.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"
 
 module Tina4
@@ -105,17 +111,46 @@ module Tina4
             page     = [page, 1].max
             limit    = per_page
             offset   = req.query["offset"] ? req.query["offset"].to_i : (page - 1) * per_page
-            order_by = parse_sort(req.query["sort"])
 
-            # Filter support: ?filter[field]=value
+            # Filter support: ?filter[field]=value. ADR-0069: ANY bracket key is
+            # captured and must resolve to a declared field (attribute or its
+            # mapped column); an unknown key is a 400 before any SQL runs.
+            #
+            # The query parser keeps bracketed keys flat, so a list or map shows
+            # up as "sort[...]" or "filter[name][...]": a 400, never ignored.
+            if req.query.keys.any? { |key| key.start_with?("sort[") }
+              next res.error("INVALID_QUERY_PARAMETER",
+                             "Query parameter 'sort' must be a single comma-separated string", 400)
+            end
+
             filter_conditions = []
             filter_values = []
+            unknown_filter_field = nil
+            nested_filter_field = nil
             req.query.each do |key, value|
-              if key =~ /\Afilter\[(\w+)\]\z/
-                filter_conditions << "#{$1} = ?"
-                filter_values << value
+              next unless key =~ /\Afilter\[(.*)\]\z/m
+
+              filter_key = Regexp.last_match(1)
+              if filter_key.include?("][")
+                nested_filter_field = filter_key.split("][", 2).first
+                break
               end
+              column = model_class.resolve_field_column(filter_key)
+              unless column
+                unknown_filter_field = filter_key
+                break
+              end
+              filter_conditions << "#{column} = ?"
+              filter_values << value
+            end
+            if nested_filter_field
+              next res.error("INVALID_QUERY_PARAMETER",
+                             "Filter value for '#{nested_filter_field}' must be a single value", 400)
             end
+            next res.error("UNKNOWN_FIELD", "Unknown filter field '#{unknown_filter_field}'", 400) if unknown_filter_field
+
+            order_by, unknown_sort_field = parse_sort(model_class, req.query["sort"])
+            next res.error("UNKNOWN_FIELD", "Unknown sort field '#{unknown_sort_field}'", 400) if unknown_sort_field
 
             if filter_conditions.empty?
               records = model_class.all(limit: limit, offset: offset, order_by: order_by)
@@ -150,8 +185,7 @@ module Tina4
         # GET /api/{table}/{id} -- get single record
         Tina4::Router.add("GET", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             if record
               res.json({ data: record.to_h })
             else
@@ -200,8 +234,7 @@ module Tina4
         # PUT /api/{table}/{id} -- update record
         put_route = Tina4::Router.add("PUT", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -236,8 +269,7 @@ module Tina4
         # DELETE /api/{table}/{id} -- delete record
         delete_route = Tina4::Router.add("DELETE", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -314,27 +346,51 @@ module Tina4
         auto_increment = single_pk && defs[single_pk.to_sym] && defs[single_pk.to_sym][:auto_increment]
         strip_pk = is_create ? !(single_pk && !auto_increment) : true
 
+        # ADR-0069: a body key is written only when it resolves to a DECLARED
+        # field, by attribute name or its mapped column - the SAME resolver the
+        # list route's filter/sort use. Anything else is dropped (writes drop,
+        # reads 400).
         data.each_with_object({}) do |(key, value), allowed|
-          key_s = key.to_s
-          next unless defs.key?(key_s.to_sym)
-          next if key_s == "is_deleted"
-          next if strip_pk && pk_fields.include?(key_s)
+          attribute = model_class.resolve_field(key)
+          next unless attribute
 
-          allowed[key] = value
+          attribute_name = attribute.to_s
+          next if attribute_name == "is_deleted"
+          next if strip_pk && pk_fields.include?(attribute_name)
+
+          allowed[attribute_name] = value
         end
       end
 
-      # Parse sort parameter: "-name,created_at" => "name DESC, created_at ASC"
-      def parse_sort(sort_str)
-        return nil if sort_str.nil? || sort_str.empty?
-        sort_str.split(",").map do |field|
-          field = field.strip
-          if field.start_with?("-")
-            "#{field[1..-1]} DESC"
-          else
-            "#{field} ASC"
-          end
-        end.join(", ")
+      # The row a URL {id} addresses, or nil. The id is bound, never
+      # interpolated; ORM.coerce_primary_key keeps a string natural key as-is
+      # and answers nil for a non-integer id on an integer key (-> 404).
+      def find_addressed_record(model_class, raw_id)
+        id = model_class.coerce_primary_key(raw_id)
+        id.nil? ? nil : model_class.find_by_id(id)
+      end
+
+      # Parse the sort parameter: "-name,created_at" => "name DESC, created_at ASC".
+      #
+      # ADR-0069: each part (empty parts skipped, a leading "-" means DESC) must
+      # resolve to a declared field; the ORDER BY is built ONLY from resolved
+      # columns plus ASC/DESC. Returns [order_by_or_nil, unknown_field_or_nil].
+      def parse_sort(model_class, sort_str)
+        return [nil, nil] if sort_str.nil? || sort_str.empty?
+
+        parts = []
+        sort_str.split(",").each do |part|
+          part = part.strip
+          next if part.empty?
+
+          descending = part.start_with?("-")
+          field = descending ? part[1..].strip : part
+          column = model_class.resolve_field_column(field)
+          return [nil, field] unless column
+
+          parts << "#{column} #{descending ? 'DESC' : 'ASC'}"
+        end
+        [parts.empty? ? nil : parts.join(", "), nil]
       end
     end
   end

data/lib/tina4/background.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
   # Periodic background task registry.
@@ -9,7 +15,7 @@ module Tina4
   #
   # Ruby has no asyncio event loop, so each task runs in its own dedicated OS
   # thread, started at registration time. Because the thread runs regardless of
-  # which web server (Puma/WEBrick) is in front, a Ruby background task is never
+  # which web server (the built-in server or Puma) is in front, a Ruby background task is never
   # a silent no-op under production — the thread IS the runtime (contrast the
   # Python ASGI / PHP-FPM silent-no-op the other frameworks had to fix). The GIL
   # keeps it cooperative-enough for the periodic work this is meant for (queue

data/lib/tina4/base64.rb

@@ -0,0 +1,59 @@
+# 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
+  # Base64 on core Array#pack / String#unpack1, so Tina4 needs no base64 gem.
+  #
+  # The base64 gem stopped being a default gem in Ruby 3.4, and a bundled gem an
+  # app does not declare is not on the load path under Bundler. The gem is itself
+  # a thin wrapper over pack("m"), so this module keeps its method names and its
+  # exact semantics (same bytes out, same ArgumentError on bad strict input) and
+  # the call sites read the same with a Tina4:: prefix.
+  module Base64
+    module_function
+
+    # RFC 2045 (MIME): a newline after every 60 encoded characters and at the end.
+    def encode64(binary)
+      [binary].pack("m")
+    end
+
+    # Lenient decode: characters outside the alphabet are skipped, never raised on.
+    def decode64(string)
+      string.unpack1("m")
+    end
+
+    # RFC 4648: no line feeds.
+    def strict_encode64(binary)
+      [binary].pack("m0")
+    end
+
+    # Raises ArgumentError on anything that is not canonical, padded base64.
+    def strict_decode64(string)
+      string.unpack1("m0")
+    end
+
+    # RFC 4648 URL-safe alphabet ("-" and "_"), padding optional.
+    def urlsafe_encode64(binary, padding: true)
+      encoded = strict_encode64(binary)
+      encoded.chomp!("==") or encoded.chomp!("=") unless padding
+      encoded.tr!("+/", "-_")
+      encoded
+    end
+
+    # Accepts padded or unpadded input; raises ArgumentError on invalid input.
+    def urlsafe_decode64(string)
+      if !string.end_with?("=") && string.length % 4 != 0
+        string = string.ljust((string.length + 3) & ~3, "=")
+        string.tr!("-_", "+/")
+      else
+        string = string.tr("-_", "+/")
+      end
+      strict_decode64(string)
+    end
+  end
+end