tina4ruby 3.13.138 → 3.13.139

data/lib/tina4/push.rb

@@ -11,6 +11,7 @@ require_relative "base64"
 require "json"
 require "net/http"
 require "uri"
+require_relative "ssrf"
 
 module Tina4
   class PushError < StandardError; end
@@ -40,7 +41,11 @@ module Tina4
       bytes.b.rjust(32, "\x00".b)
     end
 
-    def initialize(subject: nil, public_key: nil, private_key: nil, ttl: 60, urgency: nil)
+    def initialize(subject: nil, public_key: nil, private_key: nil, ttl: 60, urgency: nil, allow_hosts: nil)
+      # SSRF guard (ADR-0084): the push endpoint is refused when it resolves to a
+      # private/internal address unless TINA4_ALLOW_PRIVATE_REQUESTS is truthy or
+      # the host/CIDR is on this allow-list.
+      @allow_hosts = allow_hosts || []
       @subject = (subject || ENV.fetch("TINA4_VAPID_SUBJECT", "")).strip
       @public_key = (public_key || ENV.fetch("TINA4_VAPID_PUBLIC", "")).strip
       @private_key = (private_key || ENV.fetch("TINA4_VAPID_PRIVATE", "")).strip
@@ -88,6 +93,13 @@ module Tina4
     end
 
     def deliver(endpoint, uri, subject, public_key, private, public, body)
+      # SSRF guard (ADR-0084): refuse a private/internal push endpoint. Net::HTTP
+      # does not follow redirects, so guarding the endpoint is sufficient.
+      begin
+        Tina4::Ssrf.guard_url!(uri, @allow_hosts)
+      rescue Tina4::SsrfError => e
+        raise PushError, e.message
+      end
       request = Net::HTTP::Post.new(uri)
       request["Authorization"] = "vapid t=#{vapid_token(uri, subject, private, public)}, k=#{public_key}"
       request["Content-Encoding"] = "aes128gcm"

data/lib/tina4/queue_backends/kafka_backend.rb

@@ -267,6 +267,14 @@ module Tina4
         out
       end
 
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      def reject(job, reason = "")
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        dead_letter(job)
+        acknowledge(job)
+      end
+
       def failed(_topic, max_retries: 3)
         raise NotImplementedError,
               "The kafka queue backend cannot answer failed(): a job that failed " \

data/lib/tina4/queue_backends/lite_backend.rb

@@ -177,6 +177,18 @@ module Tina4
       # Aligns with retry_job(id) which had always unlinked the dead-letter
       # file — two spellings of the same intent that previously diverged.
       # Increments attempts, clears the error.
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      # Unlike fail(), which requeues until max_retries is spent, reject() moves
+      # a known-poison job straight to the dead-letter store. attempts is floored
+      # at max_retries so dead_letters (attempts >= limit) returns it and
+      # dead_letter_count agrees.
+      def reject(job, reason = "")
+        clear_reservation(job.topic, job.id)
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        move_to_dead_letter(job, reason)
+      end
+
       def retry(job, delay_seconds: 0)
         clear_reservation(job.topic, job.id)
         # Drop any dead-letter file for this id BEFORE the re-queue: if this

data/lib/tina4/queue_backends/mongo_backend.rb

@@ -284,6 +284,18 @@ module Tina4
       # the normal path. This method did not exist at all, and Queue#failed
       # silently returned [] for it — indistinguishable from "nothing has
       # failed" (ADR-0022 decision 7).
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      def reject(job, reason = "")
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        collection.find_one_and_update(
+          { _id: job.id },
+          { "$set" => { status: "dead", topic: "#{job.topic}.dead_letter",
+                        attempts: job.attempts, error: reason, reserved_at: nil } },
+          upsert: true
+        )
+      end
+
       def failed(topic, max_retries: 3)
         collection.find(
           topic: topic,

data/lib/tina4/queue_backends/rabbitmq_backend.rb

@@ -177,6 +177,14 @@ module Tina4
         end
       end
 
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      def reject(job, reason = "")
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        dead_letter(job)
+        complete(job)
+      end
+
       def failed(_topic, max_retries: 3)
         raise NotImplementedError,
               "The rabbitmq queue backend cannot answer failed(): a job that " \

data/lib/tina4/rack_app.rb

@@ -1189,68 +1189,46 @@ module Tina4
     def self.enforce_route_auth(env, route)
       return nil unless route.auth_required
 
-      token = nil
-      token_source = nil  # :header, :body, :session
-
-      # Priority 1: Authorization Bearer header
+      unauthorized = [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
+
+      # Token slots in priority order: Authorization Bearer header, then the
+      # body formToken (frond.js puts the auth token it received as a
+      # FreshToken there), then the session. The first slot holding a token
+      # decides, EXCEPT that a form token ("type" => "form") proves where a
+      # write came from, not who sent it: it is skipped and the next slot is
+      # tried (ADR-0079 s1). So a logged-in user posting a rendered form (form
+      # token in the body, auth token in the session) is still authenticated.
+      candidates = []
       auth_header = env["HTTP_AUTHORIZATION"] || ""
-      if auth_header =~ /\ABearer\s+(.+)\z/i
-        token = Regexp.last_match(1)
-        token_source = :header
-      end
+      candidates << [Regexp.last_match(1), :header] if auth_header =~ /\ABearer\s+(.+)\z/i
+      form_token = _extract_form_token(_read_rack_body(env), env)
+      candidates << [form_token, :body] if form_token && !form_token.empty?
 
-      # Priority 2: formToken from request body (for frond.js saveForm with {{ form_token() }})
-      if token.nil?
-        body_str = _read_rack_body(env)
-        form_token = _extract_form_token(body_str, env)
-        if form_token && !form_token.empty?
-          token = form_token
-          token_source = :body
-        end
+      verdict = candidates.each do |token, source|
+        outcome = _authenticate_token(env, token, source)
+        break outcome unless outcome == :skip
       end
+      return unauthorized if verdict == :denied
 
-      # Priority 3: Session token (for secured GET routes after login)
-      if token.nil?
+      unless env.key?("tina4.auth_payload")
         # Request path, so the same log-loud-then-degrade policy as
         # Request#session (ADR-0021): an unreachable session store must not turn
         # the auth gate into a 500. It degrades to an empty session, which means
         # no token, which means the ordinary 401 below - a SERVED request.
         session = Tina4::Session.new(env, degrade_on_backend_failure: true)
-        sso = session.get("_tina4_sso")
-        identity = sso.is_a?(Hash) ? sso["identity"] : nil
-        if identity.is_a?(Hash) && identity["issuer"] && identity["subject"]
+        # A provider-verified OIDC identity counts only while it is live
+        # (ADR-0079 s5).
+        identity = Tina4::Sso.live_session_identity(session.get("_tina4_sso"))
+        if identity
           env["tina4.auth_payload"] = identity
-          deny = rbac_forbidden(route, identity)
-          return deny if deny
-
-          return nil
-        end
-        session_token = session.get("token")
-        if session_token && !session_token.empty?
-          token = session_token
-          token_source = :session
-        end
-      end
-
-      # API_KEY bypass — routed through the timing-safe Tina4::Auth.validate_api_key
-      # (OpenSSL.fixed_length_secure_compare), matching tina4_python's _check_auth.
-      # It used to be a plain `token == api_key`, which returns as soon as two
-      # bytes differ — so response timing leaks the key prefix and the key can be
-      # recovered a character at a time. validate_api_key also covers the unset /
-      # blank / wrong-length cases the old guard spelled out by hand.
-      if Tina4::Auth.validate_api_key(token)
-        env["tina4.auth_payload"] = { "_auth" => "api_key" }
-      elsif token
-        unless Tina4::Auth.valid_token(token)
-          return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
+        else
+          session_token = session.get("token")
+          if session_token.is_a?(String) && !session_token.empty?
+            return unauthorized unless _authenticate_token(env, session_token, :session) == :accepted
+          end
         end
-        env["tina4.auth_payload"] = Tina4::Auth.get_payload(token)
-
-        # When body formToken validates, store a refreshed token for the FreshToken response header
-        env["tina4.fresh_token"] = Tina4::Auth.refresh_token(token) if token_source == :body
-      else
-        return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
       end
+      return unauthorized unless env.key?("tina4.auth_payload")
 
       # ── RBAC guards (Feature 138): authorization AFTER authentication ──
       # Auth has passed (401 ruled out above). If the route carries role/
@@ -1261,6 +1239,30 @@ module Tina4
       nil
     end
 
+    # Judge one token from one slot: :accepted (env["tina4.auth_payload"] set),
+    # :skip (a valid form token - not an identity, try the next slot) or
+    # :denied (anything else).
+    #
+    # API_KEY bypass - routed through the timing-safe Tina4::Auth.validate_api_key
+    # (OpenSSL.fixed_length_secure_compare), matching tina4_python's _check_auth.
+    # A plain `token == api_key` returns as soon as two bytes differ, so response
+    # timing would leak the key a character at a time.
+    def self._authenticate_token(env, token, source)
+      if Tina4::Auth.validate_api_key(token)
+        env["tina4.auth_payload"] = { "_auth" => "api_key" }
+        return :accepted
+      end
+      payload = Tina4::Auth.valid_token(token)
+      return :denied unless payload
+      return :skip unless Tina4::Auth.identity_payload?(payload)
+
+      env["tina4.auth_payload"] = payload
+      # When a body token authenticates, store a refreshed token for the
+      # FreshToken response header (identity tokens only).
+      env["tina4.fresh_token"] = Tina4::Auth.refresh_token(token) if source == :body
+      :accepted
+    end
+
     # Build a 403 Rack tuple when a route's RBAC guards are not satisfied by the
     # verified payload, else nil. AND across guard groups, OR within a group.
     # Roles read the `roles` claim (legacy singular `role` coerced); permissions

data/lib/tina4/realtime/s3_storage.rb

@@ -15,7 +15,15 @@ module Tina4
     class S3Storage < StorageBackend
       def initialize(endpoint: nil, key: nil, secret: nil, bucket: nil, region: nil)
         super()
-        require "aws-sdk-s3" # optional dependency, loaded lazily
+        begin
+          require "aws-sdk-s3" # optional dependency, loaded lazily
+        rescue LoadError
+          # Storage.select rescues this and falls back to local; its warning
+          # carries this message, so the remedy reaches the operator.
+          raise LoadError,
+                "The 'aws-sdk-s3' gem is required for S3Storage. Install it with: " \
+                "bundle add aws-sdk-s3 (or add gem \"aws-sdk-s3\" to your Gemfile)"
+        end
 
         @bucket = bucket || ENV["TINA4_STORAGE_BUCKET"]
         raise ArgumentError, "S3Storage requires TINA4_STORAGE_BUCKET" if @bucket.nil? || @bucket.empty?

data/lib/tina4/request.rb

@@ -292,6 +292,11 @@ module Tina4
     # still see the URL the client used. Matches Python/PHP/Node parity.
     def url
       scheme = self.class.secure_scheme?(env) ? "https" : "http"
+      # X-Forwarded-Host is honoured ONLY when the raw socket peer is a trusted
+      # proxy (TINA4_TRUSTED_PROXIES) — the same gate already applied to
+      # X-Forwarded-For. An untrusted client can otherwise forge the host and
+      # control the absolute request.url (password-reset links, cache keys,
+      # open-redirect base). Parity with Python/PHP/Node.
       forwarded_host = Tina4.trusted_proxy?(@remote_ip) ? env["HTTP_X_FORWARDED_HOST"] : nil
       host = forwarded_host || env["HTTP_HOST"] || env["SERVER_NAME"] || "localhost"
       port = env["SERVER_PORT"]

data/lib/tina4/session_handlers/database_handler.rb

@@ -217,25 +217,49 @@ module Tina4
       # spells "already exists" differently ("There is already an object named",
       # "already exists", SQLSTATE 42S01) and a string match would rot the first
       # time an engine reworded itself or ran under another locale.
+      #
+      # The re-check is RETRIED, a bounded number of times, because the loser
+      # can fail BEFORE the winner has committed. MEASURED on MySQL 8.4: CREATE
+      # TABLE IF NOT EXISTS takes a shared metadata lock on the name, checks,
+      # then upgrades it to exclusive, and two sessions upgrading at once is a
+      # metadata-lock deadlock. MySQL backs the victim off silently only when the
+      # session holds no other metadata lock; otherwise the victim gets 1213
+      # "Deadlock found" while the winner's table is still invisible, and one
+      # immediate re-check turned that lost race into a failed request (tina4-php
+      # CI run 35972320442). Same attempts and delays in all four frameworks.
+      CREATE_ATTEMPTS = 5
+      CREATE_RETRY_DELAY = 0.05
+
       def ensure_table
         return if @table_ready
 
         @table_ready = true
-        begin
-          db.execute(create_table_sql)
-        rescue StandardError
-          # A failed statement leaves PostgreSQL's transaction ABORTED, so
-          # without this the re-check would fail for the wrong reason and report
-          # a missing table that is right there. Best effort: an engine with no
-          # open transaction is entitled to object to being rolled back.
+        attempt = 1
+        until db.table_exists?(TABLE_NAME)
           begin
-            db.rollback
+            db.execute(create_table_sql)
+            return
           rescue StandardError
-            nil
+            # A failed statement leaves PostgreSQL's transaction ABORTED, so
+            # without this the re-check would fail for the wrong reason and
+            # report a missing table that is right there. Best effort: an engine
+            # with no open transaction is entitled to object to being rolled back.
+            begin
+              db.rollback
+            rescue StandardError
+              nil
+            end
+            # Somebody else created it - that is the race, and it is a success.
+            # Still absent after the last attempt is a real failure, re-raised
+            # untouched.
+            if attempt >= CREATE_ATTEMPTS
+              return if db.table_exists?(TABLE_NAME)
+
+              raise
+            end
+            sleep(CREATE_RETRY_DELAY * attempt)
+            attempt += 1
           end
-          # Somebody else created it - that is the race, and it is a success.
-          # Anything else is a real failure and is re-raised untouched.
-          raise unless db.table_exists?(TABLE_NAME)
         end
       end
     end

data/lib/tina4/sso.rb

@@ -22,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
@@ -221,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
@@ -251,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

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/version.rb

@@ -7,5 +7,5 @@
 
 
 module Tina4
-  VERSION = "3.13.138"
+  VERSION = "3.13.139"
 end