tina4ruby 3.13.94 → 3.13.97

data/README.md

@@ -58,7 +58,7 @@ db = Tina4::Database.new("sqlite://app.db")
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
 | **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
-| **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
+| **Auth & Security** (5) | JWT (HS256/HS384/HS512 standard, RS256 opt-in, both stdlib OpenSSL, no gem), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
 | **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |

data/lib/tina4/auth.rb

@@ -33,6 +33,28 @@ module Tina4
       "HS512" => OpenSSL::Digest::SHA512
     }.freeze
 
+    # RS256 (RSA-SHA256) is the OPT-IN asymmetric algorithm, and Ruby needs NO gem
+    # for it: OpenSSL is a stdlib DEFAULT GEM, so OpenSSL::PKey::RSA#sign/#verify
+    # emit and check exactly the RFC 7515 signature the other frameworks do
+    # (measured: a token minted here verifies under PHP openssl_verify AND Node
+    # crypto.createVerify, and a tampered payload goes INVALID in both). The `jwt`
+    # gem was declared only to wrap the base64url envelope this file already
+    # builds for HMAC, so it was dropped.
+    #
+    # The contract requires a LOUD, ACTIONABLE failure wherever RS256 is
+    # unavailable. In Ruby that branch is UNREACHABLE in practice: the
+    # `require "openssl"` at the top of this file is what supplies OpenSSL::HMAC
+    # for the HMAC path too, so an interpreter lacking it cannot load Tina4 at
+    # all. The message therefore names the real remedy and deliberately does NOT
+    # suggest installing a library — there is none to install.
+    RS256_UNAVAILABLE_MESSAGE =
+      "RS256 is unavailable: this Ruby has no OpenSSL::PKey::RSA. OpenSSL is a " \
+      "Ruby stdlib DEFAULT GEM, so this interpreter was built without the openssl " \
+      "extension — rebuild Ruby with OpenSSL support, or use a build that ships " \
+      "it. Do NOT install a JWT gem: Tina4 signs and verifies RS256 with stdlib " \
+      "OpenSSL and needs no third-party library. Tina4's standard algorithms are " \
+      "HS256/HS384/HS512, which are stdlib OpenSSL too."
+
     # Seconds of clock skew tolerated on the "nbf" (not-before) claim. Without
     # this a token minted on one host and validated on another a second behind is
     # rejected for no real reason; RFC 7519 explicitly allows "a small leeway".
@@ -155,75 +177,114 @@ module Tina4
         OpenSSL::HMAC.digest(HMAC_ALGORITHMS.fetch(algorithm).new, secret.to_s, signing_input)
       end
 
-      # Build a JWT with Ruby's OpenSSL::HMAC (no gem needed). The algorithm is the
-      # explicit argument, else TINA4_JWT_ALGORITHM, else HS256 — and the header
-      # advertises exactly the algorithm that signed.
-      def hmac_encode(claims, secret, algorithm: nil)
-        alg = resolve_algorithm(algorithm)
-        header = { "alg" => alg, "typ" => "JWT" }
+      # Write the base64url header.payload.signature envelope. The signature bytes
+      # come from the block, so the HMAC and RS256 paths share ONE envelope writer
+      # — and one place where "alg" is stamped from whatever actually signed.
+      def encode_envelope(algorithm, claims)
         segments = [
-          base64url_encode(JSON.generate(header)),
+          base64url_encode(JSON.generate({ "alg" => algorithm, "typ" => "JWT" })),
           base64url_encode(JSON.generate(claims))
         ]
-        signing_input = segments.join(".")
-        segments << base64url_encode(hmac_signature(alg, secret, signing_input))
+        segments << base64url_encode(yield(segments.join(".")))
         segments.join(".")
       end
 
-      # Decode and verify an HMAC-signed JWT. Returns the payload hash or nil.
+      # Read the envelope, PIN the header alg, check the signature via the block,
+      # then apply the RFC 7519 claim rules. Returns the payload hash or nil.
       #
       # The algorithm is PINNED to our configured one rather than trusted from the
       # token: a header asking to be verified as anything else — "none", a
-      # different HMAC, or an RSA alg we do not implement here — is rejected before
-      # any signature work.
-      def hmac_decode(token, secret, algorithm: nil)
-        # Resolved OUTSIDE the rescue below: an unsupported algorithm is a
-        # configuration error that must surface, not become a nil "invalid token".
-        alg = resolve_algorithm(algorithm)
+      # different HMAC, or RS256 while we are configured for HMAC — is rejected
+      # before any signature work. Making RS256 opt-in must NOT open algorithm
+      # substitution, so both paths share this one pin.
+      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 yield("#{parts[0]}.#{parts[1]}", base64url_decode(parts[2]))
 
-        begin
-          parts = token.split(".")
-          return nil unless parts.length == 3
+        payload = JSON.parse(base64url_decode(parts[1]))
+        now = Time.now.to_i
 
-          header_json = base64url_decode(parts[0])
-          header = JSON.parse(header_json)
-          return nil unless header["alg"] == alg
+        # RFC 7519 s4.1.4: "The processing of the 'exp' claim requires that the
+        # current date/time MUST be before the expiration date/time". now == exp
+        # is therefore ALREADY expired, so the test is >=.
+        #
+        # key? — NOT a truthiness test on the value. A PRESENT but malformed exp
+        # must never read as "no constraint": `payload["exp"] && ...` skipped the
+        # check entirely for exp: null / exp: false, turning a broken token into
+        # one that never expires.
+        if payload.key?("exp")
+          exp = numeric_date(payload["exp"])
+          return nil if exp.nil? || now >= exp
+        end
 
-          # Verify signature
-          signing_input = "#{parts[0]}.#{parts[1]}"
-          expected_sig = hmac_signature(alg, secret, signing_input)
-          actual_sig = base64url_decode(parts[2])
+        # "nbf" (not-before): a post-dated token is not valid yet. Tolerate
+        # JWT_LEEWAY_SECONDS of clock skew so a token minted on a host a second
+        # ahead is not rejected for nothing. Same malformed-is-rejected rule as
+        # exp; NO nbf key at all stays unconstrained (non-breaking).
+        if payload.key?("nbf")
+          nbf = numeric_date(payload["nbf"])
+          return nil if nbf.nil? || now + JWT_LEEWAY_SECONDS < nbf
+        end
 
+        payload
+      rescue ArgumentError, JSON::ParserError, OpenSSL::OpenSSLError
+        nil
+      end
+
+      # Build a JWT with Ruby's OpenSSL::HMAC (no gem needed). The algorithm is the
+      # explicit argument, else TINA4_JWT_ALGORITHM, else HS256 — and the header
+      # advertises exactly the algorithm that signed.
+      def hmac_encode(claims, secret, algorithm: nil)
+        alg = resolve_algorithm(algorithm)
+        encode_envelope(alg, claims) { |input| hmac_signature(alg, secret, input) }
+      end
+
+      # Decode and verify an HMAC-signed JWT. Returns the payload hash or nil.
+      def hmac_decode(token, secret, algorithm: nil)
+        # Resolved OUTSIDE decode_envelope's rescue: an unsupported algorithm is a
+        # configuration error that must surface, not become a nil "invalid token".
+        alg = resolve_algorithm(algorithm)
+
+        decode_envelope(token, alg) do |input, signature|
+          expected = hmac_signature(alg, secret, input)
           # Constant-time comparison to prevent timing attacks. Lengths must match
-          # first — fixed_length_secure_compare raises on a length mismatch, which
+          # first — fixed_length_secure_compare RAISES on a length mismatch, which
           # a forged signature of the wrong digest size would trigger.
-          return nil unless expected_sig.bytesize == actual_sig.bytesize
-          return nil unless OpenSSL.fixed_length_secure_compare(expected_sig, actual_sig)
+          expected.bytesize == signature.bytesize &&
+            OpenSSL.fixed_length_secure_compare(expected, signature)
+        end
+      end
 
-          payload = JSON.parse(base64url_decode(parts[1]))
+      # ── RS256: opt-in, stdlib OpenSSL, zero gems ─────────────────
 
-          # Check expiry
-          now = Time.now.to_i
-          return nil if payload["exp"] && now >= payload["exp"]
+      # Does this runtime provide RSA natively? Ruby ships OpenSSL as a stdlib
+      # DEFAULT GEM, so this is true on every normal build — there is nothing to
+      # install and nothing to opt into at the library level.
+      def rs256_available?
+        defined?(OpenSSL::PKey::RSA) ? true : false
+      end
 
-          # "nbf" (not-before): a post-dated token is not valid yet. Tolerate
-          # JWT_LEEWAY_SECONDS of clock skew so a token minted on a host a second
-          # ahead is not rejected for nothing.
-          return nil if payload["nbf"] && now + JWT_LEEWAY_SECONDS < payload["nbf"]
+      # RSA-SHA256, with a FRESH digest instance per call so nothing about the
+      # digest state is shared between calls or threads (same rule as HMAC).
+      def rs256_encode(claims)
+        require_rs256!
+        encode_envelope("RS256", claims) { |input| private_key.sign(OpenSSL::Digest::SHA256.new, input) }
+      end
 
-          payload
-        rescue ArgumentError, JSON::ParserError, OpenSSL::HMACError
-          nil
-        end
+      def rs256_decode(token)
+        require_rs256!
+        decode_envelope(token, "RS256") { |input, sig| public_key.verify(OpenSSL::Digest::SHA256.new, sig, input) }
       end
 
-      # ── Token API (auto-selects HS256 or RS256) ─────────────────
+      # ── Token API (HMAC by default; RS256 when RSA keys are present) ──
 
       # Mint a signed JWT.
       #
       # `algorithm:` selects the HMAC algorithm (else TINA4_JWT_ALGORITHM, else
       # HS256); an unsupported one raises ArgumentError rather than quietly
-      # downgrading. It applies to the HMAC path only — the legacy RS256 path
+      # downgrading. It applies to the HMAC path only — the opt-in RS256 path
       # (RSA keys present in .keys/) is unaffected.
       #
       # BREAKING (deliberate): no "nbf" claim is stamped. It duplicated "iat",
@@ -244,17 +305,15 @@ module Tina4
           hmac_encode(claims, hmac_secret, algorithm: algorithm)
         else
           ensure_keys
-          require "jwt"
-          JWT.encode(claims, private_key, "RS256")
+          rs256_encode(claims)
         end
       end
 
-
       # Verify a JWT signature + expiry.
       #
       # 3.13.0: return type changed from `Boolean` to `Hash | nil`. The
       # decoded payload is returned on success, nil on failure. Matches
-      # firebase/jwt-ruby and Python's Auth.valid_token in 3.13.0.
+      # Python's Auth.valid_token in 3.13.0.
       #
       # Legacy `if Tina4::Auth.valid_token(t)` patterns keep working
       # because a non-empty Hash is truthy and nil is falsy.
@@ -263,32 +322,17 @@ module Tina4
           hmac_decode(token, hmac_secret) # returns Hash payload or nil
         else
           ensure_keys
-          require "jwt"
-          decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
-          decoded[0] # firebase/jwt-ruby returns [payload, header]
+          rs256_decode(token)
         end
-      rescue JWT::ExpiredSignature, JWT::DecodeError
-        nil
       end
 
+      # BREAKING (deliberate): the RS256 branch used to surface the jwt gem's own
+      # wording ("Signature has expired", or a raw decode message). Both paths now
+      # report the single HMAC-path wording, so the detail shape no longer depends
+      # on which algorithm signed.
       def valid_token_detail(token)
-        if use_hmac?
-          payload = hmac_decode(token, hmac_secret)
-          if payload
-            { valid: true, payload: payload }
-          else
-            { valid: false, error: "Invalid or expired token" }
-          end
-        else
-          ensure_keys
-          require "jwt"
-          decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
-          { valid: true, payload: decoded[0] }
-        end
-      rescue JWT::ExpiredSignature
-        { valid: false, error: "Token expired" }
-      rescue JWT::DecodeError => e
-        { valid: false, error: e.message }
+        payload = valid_token(token)
+        payload ? { valid: true, payload: payload } : { valid: false, error: "Invalid or expired token" }
       end
 
       def hash_password(password, salt = nil, iterations = 260000)
@@ -349,23 +393,31 @@ module Tina4
 
         token = Regexp.last_match(1)
 
+        # The JWT is checked FIRST, then the API key — the order Python, PHP and
+        # Node all use. Ruby checked the API key first, so the same request could
+        # authenticate differently depending on the framework.
+        #
+        # A custom secret and/or algorithm validates against those directly rather
+        # 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)
+                  end
+        return payload if payload
+
         # API_KEY bypass — timing-safe comparison via validate_api_key
         # (OpenSSL.fixed_length_secure_compare). Parity with Python's
         # authenticate_request (validate_api_key), PHP (hash_equals) and
         # Node (timingSafeEqual). Never use a plain `==` here — that leaks the
         # key length/prefix through comparison timing.
-        if validate_api_key(token)
-          return { "api_key" => true }
-        end
-
-        # If a custom secret and/or algorithm is provided, validate against those
-        # directly rather than this process's env-resolved defaults.
-        if secret || algorithm
-          payload = hmac_decode(token, secret || hmac_secret, algorithm: algorithm)
-          return payload ? payload : nil
-        end
+        #
+        # "_auth" is the cross-framework key for a non-JWT auth result; PHP and
+        # Node already used it, Python used "auth_type" and Ruby "api_key", so the
+        # same successful auth read three different ways.
+        return { "_auth" => "api_key" } if validate_api_key(token)
 
-        valid_token(token) ? get_payload(token) : nil
+        nil
       end
 
       def validate_api_key(provided, expected: nil)
@@ -392,22 +444,24 @@ 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)
+            return true
+          end
+
           # API_KEY bypass — timing-safe comparison via validate_api_key
           # (OpenSSL.fixed_length_secure_compare). Parity with Python's
           # authenticate_request (validate_api_key), PHP (hash_equals) and
           # Node (timingSafeEqual). Never use a plain `==` here — that leaks the
           # key length/prefix through comparison timing.
           if validate_api_key(token)
-            env["tina4.auth"] = { "api_key" => true }
+            env["tina4.auth"] = { "_auth" => "api_key" }
             return true
           end
 
-          if valid_token(token)
-            env["tina4.auth"] = get_payload(token)
-            true
-          else
-            false
-          end
+          false
         end
       end
 
@@ -431,6 +485,31 @@ module Tina4
 
       private
 
+      # The loud, actionable RS256 gate. NotImplementedError is deliberate: it is
+      # Ruby's "not available on this platform" error AND it is NOT a
+      # StandardError, so a caller's blanket `rescue => e` cannot swallow it into
+      # a mysterious false. Unreachable on any Ruby that can load this file.
+      def require_rs256!
+        raise NotImplementedError, RS256_UNAVAILABLE_MESSAGE unless rs256_available?
+      end
+
+      # Coerce an RFC 7519 NumericDate claim to integer seconds, else nil.
+      #
+      # RFC 7519 s2 defines exp/nbf/iat as a NumericDate — a JSON numeric value.
+      # A claim that is PRESENT but not a number is malformed, and a malformed
+      # constraint must never read as "no constraint": treating a non-numeric exp
+      # as absent turns a broken token into one that never expires. Every
+      # non-numeric JSON type (null, true/false, String, Array, Hash) returns nil
+      # so the caller rejects the token. Mirrors the Python master's
+      # _numeric_date; Ruby needs no bool special-case because TrueClass is not
+      # an Integer (in Python bool IS an int subclass, so exp: true would compare
+      # as 1970).
+      def numeric_date(value)
+        return nil unless value.is_a?(Integer) || value.is_a?(Float)
+
+        value.to_i
+      end
+
       # ── Dev-secret bootstrap helpers (parity with Python master) ──
 
       # Dev when the framework debug flag is truthy (TINA4_DEBUG).

data/lib/tina4/auto_crud.rb

@@ -105,22 +105,30 @@ module Tina4
               total = model_class.count
             else
               where_clause = filter_conditions.join(" AND ")
-              records = model_class.where(where_clause, filter_values)
-              total = records.length
-              # Apply manual pagination for filtered results
-              records = records.slice(offset, limit) || []
+              # Fetch THIS page in SQL (limit + offset) and take the total from a
+              # COUNT(*) over the same filter — never rows-returned, never an
+              # in-memory re-slice by the absolute offset (ADR-0043 root causes 2
+              # and 3, which returned zero rows for a valid page).
+              records = model_class.where(where_clause, filter_values,
+                                          limit: limit, offset: offset, order_by: order_by)
+              total = model_class.count(where_clause, filter_values)
             end
 
-            res.json({
-              data: records.map { |r| r.to_h },
-              total: total,
-              limit: limit,
-              offset: offset
-            })
+            # Build the envelope through the ONE canonical derivation — the same
+            # DatabaseResult#to_paginate ADR-0043 fixed — so the REST list endpoint
+            # can never drift from it again. Exactly seven snake_case keys:
+            # records, total, page, per_page, total_pages, limit, offset. `records`
+            # is this page verbatim, `total` the true COUNT, and page/per_page/
+            # total_pages/limit/offset are all derived from the query that ran.
+            page_result = Tina4::DatabaseResult.new(
+              records.map { |r| r.to_h }, count: total, limit: limit, offset: offset
+            )
+            res.json(page_result.to_paginate)
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
-        }, swagger_meta: { summary: "List all #{pretty_name}", tags: [table.to_s] })
+        }, swagger_meta: { summary: "List all #{pretty_name}", tags: [table.to_s],
+                           model: model_class, model_list: true })
 
         # GET /api/{table}/{id} -- get single record
         Tina4::Router.add("GET", "#{prefix}/#{table}/{id}", proc { |req, res|
@@ -135,7 +143,8 @@ module Tina4
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
-        }, swagger_meta: { summary: "Get #{pretty_name} by ID", tags: [table.to_s] })
+        }, swagger_meta: { summary: "Get #{pretty_name} by ID", tags: [table.to_s],
+                           model: model_class })
 
         # POST /api/{table} -- create record
         post_route = Tina4::Router.add("POST", "#{prefix}/#{table}", proc { |req, res|
@@ -153,16 +162,11 @@ module Tina4
         }, swagger_meta: {
           summary: "Create #{pretty_name}",
           tags: [table.to_s],
-          request_body: {
-            "description" => "#{pretty_name} data",
-            "required" => true,
-            "content" => {
-              "application/json" => {
-                "schema" => { "type" => "object" },
-                "example" => example_body
-              }
-            }
-          }
+          # Reference the model's components.schemas entry ($ref, keyed by the
+          # model CLASS name) instead of a bare {type:object}; the generated
+          # example stays as a sample body. See decisions doc S2.
+          model: model_class,
+          example: example_body
         })
 
         # Secure-by-default: only opt out of the write gate when public: true.
@@ -194,16 +198,9 @@ module Tina4
         }, swagger_meta: {
           summary: "Update #{pretty_name}",
           tags: [table.to_s],
-          request_body: {
-            "description" => "#{pretty_name} data",
-            "required" => true,
-            "content" => {
-              "application/json" => {
-                "schema" => { "type" => "object" },
-                "example" => example_body
-              }
-            }
-          }
+          # $ref the model schema instead of {type:object} (see decisions S2).
+          model: model_class,
+          example: example_body
         })
 
         # Secure-by-default: only opt out of the write gate when public: true.

data/lib/tina4/cache_backends/base_backend.rb

@@ -45,6 +45,25 @@ module Tina4
         raise NotImplementedError
       end
 
+      # Evict expired entries and return HOW MANY were evicted.
+      #
+      # The base answer is 0, and it is an honest one: redis, valkey, memcached
+      # and mongodb expire entries SERVER-SIDE, so by the time a sweep runs
+      # there is nothing left for this process to reclaim. Backends that hold
+      # entries locally - memory, file, database - override this with a real
+      # count.
+      #
+      # It lives on the BASE so sweep is answerable on every provider. It used
+      # to exist only on the file backend, so sweep raised NoMethodError on the
+      # other six and every caller grew a respond_to?(:sweep) guard - and a
+      # guard cannot tell "not supported" from "evicted nothing", which are
+      # opposite readings for whoever is watching the number.
+      #
+      # @return [Integer] number of entries evicted, never negative
+      def sweep
+        0
+      end
+
       # Whether this backend is actually usable (driver present + service
       # reachable). Local backends are always available; network/driver backends
       # override this so the factory can fall back to the file backend.

data/lib/tina4/cache_backends/database_backend.rb

@@ -102,6 +102,35 @@ module Tina4
         "database"
       end
 
+      # Evict expired rows and return how many were deleted.
+      #
+      # A SQL table expires NOTHING by itself. Unlike redis/valkey/memcached/
+      # mongodb, which reclaim server-side, an expired row here sits in
+      # tina4_cache until something removes it - and the only thing that did was
+      # get(), which deletes a single row when someone happens to re-read that
+      # exact key. A key never read again was never reclaimed, so the table grew
+      # without bound while sweep, the one API whose job is reclaiming it,
+      # returned 0 and did nothing.
+      #
+      # expires_at > 0 is the guard that matters: this backend stores 0 for "no
+      # expiry" (get() uses the same guard), so a sweep comparing only
+      # expires_at < now would delete every permanent entry on its first run.
+      #
+      # COUNT then DELETE, against one captured timestamp, so the number
+      # returned is exactly the number of rows the DELETE removes on every
+      # engine - affected-row counts are best-effort outside SQLite.
+      def sweep
+        now = Time.now.to_f
+        row = @db.fetch_one(
+          "SELECT COUNT(*) AS c FROM tina4_cache WHERE expires_at > 0 AND expires_at < ?", [now]
+        )
+        expired = row ? (row["c"] || row[:c]).to_i : 0
+        return 0 if expired.zero?
+
+        @db.execute("DELETE FROM tina4_cache WHERE expires_at > 0 AND expires_at < ?", [now])
+        expired
+      end
+
       private
 
       def env_nonempty(key)