tina4ruby 3.13.137 → 3.13.139

data/lib/tina4/sql_translator.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 "digest"
 require_relative "cache"
@@ -150,11 +156,98 @@ module Tina4
         [out, literals]
       end
 
+      # Rewrite every PLACEHOLDER `?` in +sql+ with the block's answer for its
+      # zero-based index, leaving every `?` that is not a placeholder alone
+      # (tina4-python #138). Skipped: string literals ('...' with '' escapes,
+      # Postgres E'...' with backslash escapes, $$...$$ and $tag$...$tag$),
+      # quoted identifiers ("..." and `...`, plus [...] when +brackets+ is true
+      # for SQL Server - never elsewhere, where arr[?] is a real placeholder)
+      # and comments (-- and /* */). A `%` is never special here.
+      #
+      # The two Ruby drivers that rewrite `?` both did a plain text rewrite:
+      # Postgres (? -> $n) turned SELECT 'why?', ? into 'why$1', $2; MSSQL
+      # (? -> escaped value, one sub at a time) also rewrote a `?` inside a
+      # value it had just spliced in.
+      def replace_placeholders(sql, brackets: false)
+        out = +""
+        index = 0
+        i = 0
+        n = sql.length
+        while i < n
+          span_end = placeholder_skip_span(sql, i, brackets)
+          if span_end
+            out << sql[i...span_end]
+            i = span_end
+          elsif sql[i] == "?"
+            out << yield(index).to_s
+            index += 1
+            i += 1
+          else
+            out << sql[i]
+            i += 1
+          end
+        end
+        out
+      end
+
       # Inverse of #mask_literals.
       def restore_literals(masked, literals)
         masked.gsub(/\x00(\d+)\x00/) { literals[::Regexp.last_match(1).to_i] }
       end
 
+      # When a literal, quoted identifier or comment STARTS at +i+, the index
+      # just past its end; otherwise nil. An unterminated span runs to the end.
+      def placeholder_skip_span(sql, i, brackets)
+        ch = sql[i]
+        nxt = sql[i + 1]
+        return sql.index("\n", i) || sql.length if ch == "-" && nxt == "-"
+        return (sql.index("*/", i + 2)&.+(2)) || sql.length if ch == "/" && nxt == "*"
+        return quoted_span_end(sql, i, "'", backslash: e_string?(sql, i)) if ch == "'"
+        return quoted_span_end(sql, i, ch) if ch == '"' || ch == "`"
+        return quoted_span_end(sql, i, "]") if brackets && ch == "["
+        return dollar_span_end(sql, i) if ch == "$"
+
+        nil
+      end
+
+      # The end of a span opened at +i+ and closed by +close+, where a doubled
+      # closer is an escaped one ('' "" `` ]]) and, for an E'...' string, a
+      # backslash escapes the next character.
+      def quoted_span_end(sql, i, close, backslash: false)
+        j = i + 1
+        n = sql.length
+        while j < n
+          if backslash && sql[j] == "\\"
+            j += 2
+          elsif sql[j] == close
+            return j + 1 unless sql[j + 1] == close
+
+            j += 2
+          else
+            j += 1
+          end
+        end
+        n
+      end
+
+      # A Postgres escape string: E'...' / e'...' where the E is its own token.
+      def e_string?(sql, i)
+        i.positive? && sql[i - 1].match?(/[eE]/) && (i < 2 || !sql[i - 2].match?(/[A-Za-z0-9_$]/))
+      end
+
+      # A Postgres dollar-quoted string ($$...$$ or $tag$...$tag$) starting at
+      # +i+, or nil. `$1` is a numbered parameter, not a tag (tags cannot start
+      # with a digit), and a `$` inside an identifier (a$b) opens nothing.
+      def dollar_span_end(sql, i)
+        return nil if i.positive? && sql[i - 1].match?(/[A-Za-z0-9_]/)
+
+        tag = sql[i..][/\A\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/]
+        return nil unless tag
+
+        close = sql.index(tag, i + tag.length)
+        close ? close + tag.length : sql.length
+      end
+
       # Convert || string concatenation to CONCAT() for MySQL/MSSQL. Rewrites ONLY
       # || operators joining expression operands OUTSIDE any string literal or
       # comment, and only the operand chain - never the whole statement.

data/lib/tina4/sqlite3_gem.rb

@@ -0,0 +1,27 @@
+# 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
+  # The sqlite3 gem is an APPLICATION dependency, not a framework one
+  # (ADR-0067): `tina4 init ruby` writes gem "sqlite3" into the project's
+  # Gemfile, and tina4ruby itself never declares it, exactly like pg, mysql2 and
+  # the other drivers. Everything that opens SQLite goes through here so a
+  # project without the gem gets one actionable message instead of a bare
+  # "cannot load such file -- sqlite3".
+  SQLITE3_MISSING_MESSAGE =
+    "The 'sqlite3' gem is required for SQLite connections. Add gem \"sqlite3\" " \
+    "to your Gemfile (tina4 init ruby does this for you), or install one of:\n" \
+    "    bundle add sqlite3     # if your project uses Bundler\n" \
+    "    gem install sqlite3    # bare driver"
+
+  def self.require_sqlite3!
+    require "sqlite3"
+  rescue LoadError
+    raise LoadError, SQLITE3_MISSING_MESSAGE
+  end
+end

data/lib/tina4/sso.rb

@@ -1,12 +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 "base64"
+
+require_relative "base64"
 require "digest"
 require "json"
 require "net/http"
 require "openssl"
 require "securerandom"
 require "uri"
+require_relative "parse_json"
 
 module Tina4
   class SsoError < StandardError; end
@@ -15,6 +22,30 @@ module Tina4
   class Sso
     PENDING_KEY = "_tina4_sso_pending"
     SESSION_KEY = "_tina4_sso"
+
+    # The stored SSO identity, only while it is live (ADR-0079 s5). +stored+ is
+    # the reserved _tina4_sso session value. The identity needs an issuer and a
+    # subject, and a numeric expires_at that is 0 (the provider gave no
+    # lifetime) or still in the future.
+    def self.live_session_identity(stored)
+      return nil unless stored.is_a?(Hash)
+
+      identity = stored["identity"]
+      return nil unless identity.is_a?(Hash) && identity["issuer"] && identity["subject"]
+
+      expires_at = stored.fetch("expires_at", 0)
+      return nil unless expires_at.is_a?(Integer) || expires_at.is_a?(Float)
+      return nil if expires_at.positive? && Time.now.to_i >= expires_at
+
+      identity
+    end
+
+    # When the provider's access token lapses; 0 when it gave no lifetime.
+    # Never "now", which is already in the past by the next request.
+    def self.expires_at(tokens)
+      lifetime = tokens.fetch("expires_in", 0).to_i
+      lifetime.positive? ? Time.now.to_i + lifetime : 0
+    end
     attr_reader :issuer, :client_id, :client_secret, :redirect_uri, :scopes,
                 :verify, :post_logout_redirect_uri, :claim_map
     @mounted = false
@@ -42,7 +73,7 @@ module Tina4
 
     def json_env(name, fallback)
       raw = ENV[name]
-      raw.nil? || raw.empty? ? fallback : JSON.parse(raw)
+      raw.nil? || raw.empty? ? fallback : Tina4.parse_json(raw)
     rescue JSON::ParserError => e
       raise SsoError, "#{name} must be valid JSON", cause: e
     end
@@ -83,7 +114,7 @@ module Tina4
       http.read_timeout = 10
       response = http.request(request)
       raise SsoError, "OIDC provider request failed" unless response.is_a?(Net::HTTPSuccess)
-      result = JSON.parse(response.body)
+      result = Tina4.parse_json(response.body)
       raise SsoError, "OIDC provider returned a non-object response" unless result.is_a?(Hash)
       result
     rescue JSON::ParserError, IOError, SystemCallError, Timeout::Error => e
@@ -119,7 +150,7 @@ module Tina4
       state = SecureRandom.urlsafe_base64(32)
       nonce = SecureRandom.urlsafe_base64(32)
       verifier = SecureRandom.urlsafe_base64(64)
-      challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+      challenge = Tina4::Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
       current.set(PENDING_KEY, {
                     "state" => state, "nonce" => nonce, "verifier" => verifier,
                     "return_to" => self.class.safe_return(return_to), "created_at" => Time.now.to_i
@@ -140,7 +171,7 @@ module Tina4
 
     def self.jwt_payload(token)
       part = token.split(".")[1].to_s
-      JSON.parse(Base64.urlsafe_decode64(part.ljust((part.length + 3) / 4 * 4, "=")))
+      Tina4.parse_json(Tina4::Base64.urlsafe_decode64(part.ljust((part.length + 3) / 4 * 4, "=")))
     rescue JSON::ParserError, ArgumentError
       raise SsoError, "provider returned an invalid ID token"
     end
@@ -178,9 +209,19 @@ module Tina4
       }
     end
 
+    # The provider's code and state arrive in the QUERY STRING. They used to be
+    # read from request.params, which carries ROUTE path params only
+    # (REQ-PARAM-POLLUTION), so the built-in /auth/callback never saw them and
+    # could not complete a sign-in. Parity with the Python master (sso.py reads
+    # request.query). A bare Session has no query - pass +query+ explicitly.
+    def self.query_of(request_or_session)
+      query = request_or_session.respond_to?(:query) ? request_or_session.query : nil
+      query.is_a?(Hash) ? query : {}
+    end
+
     def callback(request_or_session, query = nil)
       current = session(request_or_session)
-      values = query || request_or_session.params
+      values = query || self.class.query_of(request_or_session)
       pending = current&.get(PENDING_KEY)
       current&.delete(PENDING_KEY)
       unless pending.is_a?(Hash) && !values["code"].to_s.empty? && self.class.secure_equal(values["state"], pending["state"])
@@ -204,14 +245,13 @@ module Tina4
       current.set(SESSION_KEY, {
                     "version" => 1, "identity" => identity, "access_token" => tokens["access_token"],
                     "refresh_token" => tokens["refresh_token"], "id_token" => tokens["id_token"],
-                    "expires_at" => Time.now.to_i + tokens.fetch("expires_in", 0).to_i
+                    "expires_at" => self.class.expires_at(tokens)
                   })
       { "identity" => identity, "return_to" => self.class.safe_return(pending["return_to"]) }
     end
 
     def identity(request_or_session)
-      stored = session(request_or_session)&.get(SESSION_KEY)
-      value = stored.is_a?(Hash) ? stored["identity"] : nil
+      value = self.class.live_session_identity(session(request_or_session)&.get(SESSION_KEY))
       request_or_session.user = value if value && !request_or_session.is_a?(Tina4::Session)
       value
     end
@@ -234,7 +274,7 @@ module Tina4
         "identity" => value, "access_token" => tokens["access_token"],
         "refresh_token" => tokens["refresh_token"] || stored["refresh_token"],
         "id_token" => tokens["id_token"] || stored["id_token"],
-        "expires_at" => Time.now.to_i + tokens.fetch("expires_in", 0).to_i
+        "expires_at" => self.class.expires_at(tokens)
       ))
       value
     rescue StandardError
@@ -263,7 +303,7 @@ module Tina4
       end
       sso = from_issuer
       Tina4::Router.get("/auth/login") do |request, response|
-        response.redirect(sso.login(request, request.params["return_to"] || "/"))
+        response.redirect(sso.login(request, query_of(request)["return_to"] || "/"))
       end
       Tina4::Router.get("/auth/callback") do |request, response|
         begin
@@ -273,7 +313,7 @@ module Tina4
         end
       end
       Tina4::Router.post("/auth/logout") do |request, response|
-        response.redirect(sso.logout(request, request.params["return_to"] || "/"))
+        response.redirect(sso.logout(request, query_of(request)["return_to"] || "/"))
       end
       @mounted = true
       true

data/lib/tina4/ssrf.rb

@@ -0,0 +1,148 @@
+# 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 "ipaddr"
+require "resolv"
+require "socket"
+require "uri"
+
+module Tina4
+  # Raised when the SSRF guard refuses an outbound request.
+  class SsrfError < StandardError; end
+
+  # Outbound SSRF guard (ADR-0084).
+  #
+  # The Api client and Web Push refuse, by default, to connect to a private or
+  # internal address. Before each connection - the initial URL and every redirect
+  # hop the Api client follows - the host is resolved to its IP address(es) and
+  # the request is refused if any resolved address is loopback, private,
+  # link-local (including the cloud metadata address 169.254.169.254), unspecified
+  # or CGNAT. A non-http(s) scheme is refused.
+  #
+  # Off by default; TINA4_ALLOW_PRIVATE_REQUESTS (truthy) or an explicit allow-list
+  # of hosts / host:port / CIDRs opts out. Zero external dependencies - Ruby
+  # stdlib IPAddr + Resolv.
+  module Ssrf
+    ALLOW_PRIVATE_ENV = "TINA4_ALLOW_PRIVATE_REQUESTS"
+
+    # Truthiness identical to ADR-0070's set (trimmed, lower-cased).
+    TRUTHY = %w[1 true yes on].freeze
+
+    # The blocked address space, one definition shared with the contract fixture.
+    # 0.0.0.0/8 covers the unspecified address and the "this network" block.
+    BLOCKED = %w[
+      0.0.0.0/8 10.0.0.0/8 127.0.0.0/8 169.254.0.0/16
+      172.16.0.0/12 192.168.0.0/16 100.64.0.0/10
+      ::1/128 ::/128 fc00::/7 fe80::/10
+    ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+    module_function
+
+    # True when TINA4_ALLOW_PRIVATE_REQUESTS opts out of the guard.
+    def allow_private_requests?
+      TRUTHY.include?(ENV.fetch(ALLOW_PRIVATE_ENV, "").strip.downcase)
+    end
+
+    # Classify one IP string: true = private/internal, refuse it. An IPv4-mapped
+    # IPv6 address is classified by its embedded IPv4. An unparseable value is
+    # treated as blocked - the guard refuses what it cannot classify.
+    def blocked_address?(ip)
+      addr = IPAddr.new(ip.to_s.split("%").first)
+      addr = addr.native if addr.ipv6? && addr.ipv4_mapped?
+      BLOCKED.any? { |network| network.include?(addr) }
+    rescue IPAddr::Error
+      true
+    end
+
+    # Refuse +url+ when it targets a private/internal address. Raises SsrfError
+    # for a non-http(s) scheme, an unresolvable host, or any resolved address in
+    # the blocked space. allow_hosts is a list of hosts / host:port / CIDRs.
+    def guard_url!(url, allow_hosts = nil)
+      uri = url.is_a?(URI) ? url : URI.parse(url.to_s)
+      scheme = uri.scheme&.downcase
+      unless %w[http https].include?(scheme)
+        raise SsrfError, "Blocked request: URL scheme '#{scheme || '(none)'}' is not http or https"
+      end
+      host = uri.host.to_s
+      raise SsrfError, "Blocked request: URL has no host" if host.empty?
+
+      host = host.delete_prefix("[").delete_suffix("]")
+      port = uri.port || (scheme == "https" ? 443 : 80)
+
+      return if allow_private_requests?
+
+      resolved = resolve(host)
+      return if matches_allow_list?(host, port, resolved, allow_hosts)
+
+      resolved.each do |ip|
+        next unless blocked_address?(ip)
+
+        log_block(host, ip)
+        raise SsrfError,
+              "Blocked request to private/internal address #{ip} (host #{host}): " \
+              "set #{ALLOW_PRIVATE_ENV}=true to allow, or pass an allow-list."
+      end
+    end
+
+    # Resolve a host to its IP address(es). An IP literal resolves to itself.
+    def resolve(host)
+      begin
+        IPAddr.new(host)
+        return [host]
+      rescue IPAddr::Error
+        # not a literal - fall through to DNS
+      end
+      addresses = begin
+        Resolv.getaddresses(host)
+      rescue StandardError
+        []
+      end
+      if addresses.empty?
+        begin
+          addresses = [IPSocket.getaddress(host)]
+        rescue SocketError
+          addresses = []
+        end
+      end
+      raise SsrfError, "Blocked request to #{host}: cannot resolve host" if addresses.empty?
+
+      addresses
+    end
+
+    def matches_allow_list?(host, port, resolved, allow_hosts)
+      host_lower = host.downcase
+      Array(allow_hosts).each do |raw|
+        entry = raw.to_s.strip.downcase
+        next if entry.empty?
+        return true if entry == host_lower || entry == "#{host_lower}:#{port}"
+
+        next unless entry.include?("/")
+
+        begin
+          network = IPAddr.new(entry)
+        rescue IPAddr::Error
+          next
+        end
+        resolved.each do |ip|
+          begin
+            candidate = IPAddr.new(ip.to_s.split("%").first)
+          rescue IPAddr::Error
+            next
+          end
+          return true if network.include?(candidate)
+        end
+      end
+      false
+    end
+
+    def log_block(host, ip)
+      Tina4::Log.warning("SSRF guard blocked outbound request to #{host} (#{ip})") if defined?(Tina4::Log)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/tina4/swagger.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

data/lib/tina4/template.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
   module Template

data/lib/tina4/test.rb

@@ -1,8 +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/.
+
 
 # Tina4 — The Intelligent Native Application 4ramework
-# Copyright 2007 - current Tina4
-# License: MIT https://opensource.org/licenses/MIT
+# Copyright (c) 2026 Code Infinity
+# License: MPL-2.0 https://mozilla.org/MPL/2.0/
 
 module Tina4
   # Tina4 xUnit-style test base class — class-based test suites with HTTP

data/lib/tina4/test_client.rb

@@ -1,3 +1,9 @@
+# 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/.
+
 # Tina4 Test Client — Test routes without starting a server.
 #
 # Usage:
@@ -14,6 +20,7 @@
 #   response = client.get("/api/users/1", headers: { "Authorization" => "Bearer token123" })
 #
 require "stringio" # rack.input is a StringIO; require it here so a clean `require "tina4"` boot never NameErrors
+require_relative "parse_json"
 
 module Tina4
   class TestResponse
@@ -64,7 +71,7 @@ module Tina4
     # Parse body as JSON.
     def json
       return nil if @body.nil? || @body.empty?
-      JSON.parse(@body)
+      Tina4.parse_json(@body)
     rescue JSON::ParserError
       nil
     end

data/lib/tina4/testing.rb

@@ -1,6 +1,13 @@
 # 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 "stringio"
+require_relative "parse_json"
 
 module Tina4
   module Testing
@@ -281,7 +288,7 @@ module Tina4
       end
 
       def assert_json(response_body)
-        JSON.parse(response_body)
+        Tina4.parse_json(response_body)
       rescue JSON::ParserError => e
         raise TestFailure, "Invalid JSON: #{e.message}"
       end

data/lib/tina4/validator.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"
 

data/lib/tina4/version.rb

@@ -1,5 +1,11 @@
 # 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
-  VERSION = "3.13.137"
+  VERSION = "3.13.139"
 end