tina4ruby 3.13.97 → 3.13.99

data/lib/tina4/mcp.rb

@@ -590,7 +590,15 @@ module Tina4
   # share one fully-populated tool registry.
   def self._default_mcp_server
     @_default_mcp_server ||= begin
-      server = McpServer.new("/__dev/mcp", name: "Tina4 Dev Tools")
+      # VERSION-DEC-01 (feature 130): the built-in dev server's serverInfo
+      # must report the SAME version every other surface does (health,
+      # banner, dashboard), not the constructor's generic "1.0.0" default --
+      # found by direct verification against this live source, not assumed
+      # correct from the "Ruby is the reference" default. A user's OWN custom
+      # McpServer.new(path, name: ...) (no version: kwarg) is unaffected --
+      # that default stays "1.0.0" for app authors who have not set their own
+      # tool-server version.
+      server = McpServer.new("/__dev/mcp", name: "Tina4 Dev Tools", version: Tina4::VERSION)
       McpDevTools.register(server)
       server
     end

data/lib/tina4/messenger.rb

@@ -193,6 +193,22 @@ module Tina4
         )
       end
 
+      # TINA4_MAIL_REDIRECT_TO (MAIL-DEC-01): the REAL-SEND path only --
+      # capture already returned above, so this never touches the capture
+      # branch. When the list is non-empty, replace every recipient with the
+      # redirect list (so ONLY the dev list receives the mail, never the real
+      # recipients) and preserve the originals in a header. Subject/body/
+      # attachments are untouched; #send's return shape is unchanged. Read
+      # fresh per call, matching should_capture?'s own env-read style.
+      redirect_to = parse_mail_redirect_list(ENV["TINA4_MAIL_REDIRECT_TO"])
+      unless redirect_to.empty?
+        original_to = (normalize_recipients(to) + normalize_recipients(cc) + normalize_recipients(bcc)).join(", ")
+        to = redirect_to
+        cc = []
+        bcc = []
+        headers = (headers || {}).merge("X-Tina4-Original-To" => original_to)
+      end
+
       message_id = "<#{SecureRandom.uuid}@#{@host}>"
       raw = build_message(
         to: to, subject: subject, body: body, html: html, text: text,
@@ -476,6 +492,15 @@ module Tina4
       end
     end
 
+    # Parse TINA4_MAIL_REDIRECT_TO (MAIL-DEC-01): comma-separated addresses,
+    # each trimmed, blanks dropped. Empty/unset -> [] (redirect off, no
+    # behaviour change).
+    def parse_mail_redirect_list(raw)
+      return [] if raw.nil? || raw.empty?
+
+      raw.split(",").map(&:strip).reject(&:empty?)
+    end
+
     def format_address(address, name = nil)
       if name && !name.empty?
         "#{name} <#{address}>"

data/lib/tina4/middleware.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module Tina4
   class Middleware
     class << self
@@ -218,8 +220,8 @@ module Tina4
       # per-route "filter" middleware (a 2-arg callable returning false, see
       # Tina4::Route#run_middleware) must obey the SAME row as a before_* hook,
       # and the rule should exist exactly once.
-      def refuse(response)
-        forbid(response) if default_response?(response)
+      def refuse(request, response)
+        forbid(request, response) if default_response?(response)
         response
       end
 
@@ -263,7 +265,7 @@ module Tina4
         elsif result.is_a?(Array) && result.length == 2
           request, response = result
         elsif result == false
-          refuse(response)
+          refuse(request, response)
           return [true, request, response]
         end
 
@@ -294,16 +296,47 @@ module Tina4
         body.to_s.empty?
       end
 
-      # The canonical refusal, in the same shape as #middleware_500 so the two
-      # framework-generated error bodies match byte for byte across all four
-      # frameworks.
-      def forbid(response)
+      # The canonical refusal (ERR-DEC-01/ERR-DEC-02): routed through the SAME
+      # negotiated renderer 404/500 use, so a middleware refusal looks like
+      # every other error page - a user template if the app ships one, the
+      # framework's 403.twig otherwise, negotiated JSON for an API client -
+      # instead of the old bare/un-negotiated `{"error":"Forbidden","status":403}`.
+      def forbid(request, response)
+        request_id = Tina4::Log.get_request_id || ""
+        accept = request.respond_to?(:headers) ? (request.headers["accept"] || "") : ""
+
+        if Tina4::Template.wants_json?(accept)
+          set_response_json(response, error_json_body(request_id))
+          return response
+        end
+
+        path = request.respond_to?(:path) ? request.path.to_s : ""
+        html = begin
+          Tina4::Template.render_error(403, { "path" => CGI.escapeHTML(path), "request_id" => request_id })
+        rescue StandardError
+          nil
+        end
+
+        if html && response.respond_to?(:html)
+          response.html(html, 403)
+        else
+          set_response_json(response, error_json_body(request_id))
+        end
+        response
+      end
+
+      # The canonical JSON error envelope (ERR-DEC-02) - the SAME shape
+      # Python/PHP/Node build: {error: true, code, message, status, request_id}.
+      def error_json_body(request_id)
+        { error: true, code: "FORBIDDEN", message: "Forbidden", status: 403, request_id: request_id }
+      end
+
+      def set_response_json(response, body)
         if response.respond_to?(:json)
-          response.json({ error: "Forbidden", status: 403 }, 403)
+          response.json(body, 403)
         elsif response.respond_to?(:status_code=)
           response.status_code = 403
         end
-        response
       end
 
       # Copy a response's state onto the object the CALLER still holds.
@@ -567,111 +600,171 @@ module Tina4
 
   # CsrfMiddleware -- validates form tokens on state-changing requests.
   #
-  # Off by default -- only active when TINA4_CSRF=true in .env or when
-  # registered explicitly via Router.use(CsrfMiddleware).
+  # OFF by default: the middleware is NOT attached unless TINA4_CSRF is truthy
+  # (true/1/yes/on -- see .attach_from_env, called once at boot in
+  # Tina4.initialize!) OR it is registered explicitly via
+  # Router.use(CsrfMiddleware). Once attached, TINA4_CSRF=false (or 0/no) is the
+  # kill switch that disables enforcement again.
   #
-  # Behaviour:
-  #   - Skips GET, HEAD, OPTIONS requests.
-  #   - Skips routes marked .no_auth.
-  #   - Skips requests with a valid Authorization: Bearer header (API clients).
-  #   - Checks request.body["formToken"] then request.headers["X-Form-Token"].
-  #   - Rejects if token found in request.query["formToken"] (log warning, 403).
-  #   - Validates token with Auth.valid_token using SECRET env var.
-  #   - If token payload has session_id, verifies it matches request.session.session_id.
-  #   - Returns 403 with response.json({error: "CSRF_INVALID", message: ...}, 403) on failure.
+  # Behaviour (identical to the Python master's CsrfMiddleware.before_csrf):
+  #   - Skips GET, HEAD, OPTIONS (safe methods).
+  #   - Skips a public write route (.no_auth / auth: false -- auth_required
+  #     false). The matched Route is attached to the request before this
+  #     post-match middleware runs, so a genuinely public endpoint (login,
+  #     webhook) is not gated.
+  #   - Fails CLOSED: with TINA4_SECRET unset the signing secret resolves to
+  #     blank (there is NO built-in default), and a blank HMAC key is publicly
+  #     reproducible -- so no token can be trusted and every write is rejected
+  #     (403). This is the SEC-01 no-default-secret guarantee.
+  #   - Skips a request carrying a valid Authorization: Bearer token (API clients).
+  #   - Reads request.body["formToken"] then the X-Form-Token header.
+  #   - Rejects a token sent in the query string (403 + a logged warning) -- a
+  #     URL leaks through logs, referers and history.
+  #   - Validates the token with Auth.valid_token using the resolved secret, and
+  #     enforces that the token's "type" claim is "form" -- a non-form JWT in the
+  #     formToken slot is rejected even when its signature verifies.
+  #   - If the token carries a session_id, it must match the request session's id.
+  #   - Every rejection is HTTP 403 with the CSRF_INVALID envelope
+  #     ({error:true, code:"CSRF_INVALID", message:, status:403}) via
+  #     response.error -- byte-identical to Python/PHP/Node.
   class CsrfMiddleware
     class << self
       def before_csrf(request, response)
-        # Allow disabling CSRF via env var
-        csrf_env = ENV["TINA4_CSRF"].to_s.downcase
+        # 1. Kill switch -- TINA4_CSRF in {false,0,no} disables all CSRF checks,
+        #    even when the middleware is attached explicitly. Unset = enforced.
+        csrf_env = ENV["TINA4_CSRF"].to_s.strip.downcase
         return [request, response] if %w[false 0 no].include?(csrf_env)
 
-        # Skip safe HTTP methods
+        # 2. Safe HTTP methods never change state -- skip.
         method = (request.method || "GET").upcase
         return [request, response] if %w[GET HEAD OPTIONS].include?(method)
 
-        # Skip routes marked no_auth
-        handler = request.respond_to?(:handler) ? request.handler : nil
-        if handler
-          no_auth = if handler.is_a?(Hash)
-                      handler[:no_auth] || handler[:noAuth]
-                    elsif handler.respond_to?(:no_auth)
-                      handler.no_auth
-                    end
-          return [request, response] if no_auth
+        # 3. Public write routes (.no_auth / auth: false) skip CSRF -- a
+        #    genuinely public endpoint has no session to protect. The matched
+        #    Route is attached to the request before this post-match middleware
+        #    runs (DispatchPipeline#prepare_route_request); a public write route
+        #    has auth_required == false -- the SAME signal the auth gate reads.
+        #    (Reading request.handler, as this once did, was dead code: the live
+        #    request never carries a handler, so the no_auth skip never fired.)
+        route = request.respond_to?(:route) ? request.route : nil
+        if route.respond_to?(:auth_required) && route.auth_required == false
+          return [request, response]
+        end
+
+        # 4/5. Resolve the signing secret ONCE, fail-closed. TINA4_SECRET unset
+        #      resolves to blank (there is NO built-in default); a blank HMAC key
+        #      is publicly reproducible, so a token signed with it -- or with the
+        #      retired public 'tina4-default-secret' -- is a forgery. Reject every
+        #      write rather than validate against a guessable key. SEC-01.
+        secret = Tina4::Auth.hmac_secret
+        if secret.to_s.empty?
+          return [request, response.error(
+            "CSRF_INVALID",
+            "CSRF token cannot be validated: TINA4_SECRET is not set",
+            403
+          )]
         end
 
-        # Skip requests with valid Bearer token (API clients)
+        # 6. A valid Bearer JWT means an API client authenticating per request --
+        #    not subject to the cookie-replay attack CSRF defends against.
         headers = request.respond_to?(:headers) ? request.headers : {}
-        auth_header = headers["authorization"] || headers["Authorization"] || ""
+        auth_header = (headers["authorization"] || headers["Authorization"] || "").to_s
         if auth_header.start_with?("Bearer ")
-          bearer_token = auth_header[7..].strip
-          unless bearer_token.empty?
-            return [request, response] if Tina4::Auth.valid_token(bearer_token)
-          end
+          bearer_token = auth_header[7..].to_s.strip
+          return [request, response] if !bearer_token.empty? && Tina4::Auth.valid_token(bearer_token)
         end
 
-        # Reject if token is in query string (security risk)
-        query = if request.respond_to?(:params)
-                  request.params
-                elsif request.respond_to?(:query)
-                  request.query
-                else
-                  {}
-                end
-        query ||= {}
-
-        if query.is_a?(Hash) && query["formToken"] && !query["formToken"].to_s.empty?
+        # 7. A token in the query string leaks through logs/referers/history --
+        #    reject it. Read the QUERY STRING only, never request.params, which
+        #    merges the body (a legit body token would false-trip this check).
+        query = request.respond_to?(:query) ? request.query : {}
+        query = {} unless query.is_a?(Hash)
+        if !query["formToken"].to_s.empty?
           Tina4::Log.warning("[CSRF] Token found in query string — rejected for security")
-          response.json({ error: "CSRF_INVALID", message: "Form token must not be sent in the URL query string" }, 403)
-          return [request, response]
+          return [request, response.error(
+            "CSRF_INVALID",
+            "Form token must not be sent in the URL query string",
+            403
+          )]
         end
 
-        # Extract token: body first, then header
+        # 8. Extract the token: body first, then the X-Form-Token header.
         token = nil
         body = request.respond_to?(:body) ? request.body : nil
-        body ||= {}
         token = body["formToken"] if body.is_a?(Hash)
-
         if token.nil? || token.to_s.empty?
-          token = headers["X-Form-Token"] || headers["x-form-token"] || ""
+          token = headers["X-Form-Token"] || headers["x-form-token"]
         end
 
+        # 9. Missing token -- reject.
         if token.nil? || token.to_s.empty?
-          response.json({ error: "CSRF_INVALID", message: "Invalid or missing form token" }, 403)
-          return [request, response]
+          return [request, response.error("CSRF_INVALID", "Invalid or missing form token", 403)]
         end
 
-        # Validate the token
-        unless Tina4::Auth.valid_token(token.to_s)
-          response.json({ error: "CSRF_INVALID", message: "Invalid or missing form token" }, 403)
-          return [request, response]
+        # 10. Validate signature + expiry with the resolved secret. valid_token
+        #     returns the verified payload Hash (or nil) in 3.13.0+.
+        payload = Tina4::Auth.valid_token(token.to_s)
+        unless payload
+          return [request, response.error("CSRF_INVALID", "Invalid or missing form token", 403)]
         end
 
-        # Session binding — if token has session_id, verify it matches
-        payload = Tina4::Auth.get_payload(token.to_s) || {}
+        # 11. Enforce the form-token TYPE -- a valid signature is not enough. A
+        #     non-form JWT (e.g. an auth/session token) must never be accepted in
+        #     the formToken slot.
+        payload = {} unless payload.is_a?(Hash)
+        if payload["type"] != "form"
+          return [request, response.error("CSRF_INVALID", "Invalid or missing form token", 403)]
+        end
+
+        # 12. Session binding -- a token minted for one session cannot be replayed
+        #     against another. Read the request session's OWN id: Tina4::Session
+        #     exposes get_session_id (NOT session_id -- reading session_id then
+        #     session.get("session_id") looked up a DATA key, never the id, so
+        #     binding silently never fired against a real session). A plain Hash
+        #     session exposes "session_id".
         token_session_id = payload["session_id"]
         if token_session_id
-          current_session_id = nil
           session = request.respond_to?(:session) ? request.session : nil
-          if session
-            current_session_id = if session.respond_to?(:session_id)
-                                   session.session_id
-                                 elsif session.is_a?(Hash)
-                                   session["session_id"]
-                                 elsif session.respond_to?(:get)
-                                   session.get("session_id")
-                                 end
-          end
+          current_session_id =
+            if session.nil?
+              nil
+            elsif session.respond_to?(:session_id)
+              session.session_id
+            elsif session.respond_to?(:get_session_id)
+              session.get_session_id
+            elsif session.is_a?(Hash)
+              session["session_id"]
+            end
 
           if current_session_id && token_session_id != current_session_id
-            response.json({ error: "CSRF_INVALID", message: "Invalid or missing form token" }, 403)
-            return [request, response]
+            return [request, response.error("CSRF_INVALID", "Invalid or missing form token", 403)]
           end
         end
 
+        # 13. All checks passed.
         [request, response]
       end
+
+      # Auto-attach CsrfMiddleware when TINA4_CSRF is enabled in the environment.
+      #
+      # CSRF is OFF by default: with TINA4_CSRF unset the middleware is never
+      # attached, so a default app has no CSRF gate. A truthy value
+      # (true/1/yes/on, case-insensitive) attaches it globally so every
+      # state-changing route is gated -- the env flag is the switch, no code
+      # change needed. Idempotent (Middleware.use de-dupes). Returns true when the
+      # middleware is now attached. Mirrors the Python master's
+      # attach_csrf_from_env; the framework calls it once at boot
+      # (Tina4.initialize!). A false/0/no value still lets an explicit
+      # Router.use(CsrfMiddleware) opt-in be disabled at runtime by the kill
+      # switch in before_csrf.
+      def attach_from_env
+        value = ENV["TINA4_CSRF"].to_s.strip.downcase
+        if %w[true 1 yes on].include?(value)
+          Tina4::Middleware.use(Tina4::CsrfMiddleware)
+          return true
+        end
+        false
+      end
     end
   end
 
@@ -684,12 +777,32 @@ module Tina4
   #   TINA4_PERMISSIONS_POLICY  — Permissions-Policy (default: camera=(), microphone=(), geolocation=())
   class SecurityHeadersMiddleware
     class << self
+      # Register this middleware in the default chain (secure-by-default).
+      #
+      # Unlike CSRF (opt-in via TINA4_CSRF) this is UNCONDITIONAL: a default app
+      # ships the security headers with no opt-in -- the SECHDR-DEC-01 posture
+      # that closes the SECHDR-OFF-BY-DEFAULT gap (the middleware existed with good
+      # defaults but was never registered). Idempotent (Middleware.use de-dupes).
+      # The framework calls it once at boot (Tina4.initialize!). Returns true.
+      def attach
+        Tina4::Middleware.use(self)
+        true
+      end
+
       def before_security(request, response)
         response.headers["X-Frame-Options"] = ENV["TINA4_FRAME_OPTIONS"] || "SAMEORIGIN"
         response.headers["X-Content-Type-Options"] = "nosniff"
 
+        # HSTS is HTTPS-only (SECHDR-DEC-02): a downgrade-protection header on a
+        # plain-HTTP response is inert at best and ships a bad max-age on an
+        # unencrypted scheme at worst. Emit it ONLY when TINA4_HSTS is set AND the
+        # request is HTTPS -- Request.secure_scheme? honours x-forwarded-proto
+        # (first hop) then rack.url_scheme, the same source of truth the session
+        # cookie's Secure flag uses. Defensive env lookup keeps a non-Request from
+        # turning every response into a 500 now that this runs on every request.
         hsts = ENV["TINA4_HSTS"] || ""
-        unless hsts.empty?
+        env = request.respond_to?(:env) ? request.env : {}
+        if !hsts.empty? && Tina4::Request.secure_scheme?(env)
           response.headers["Strict-Transport-Security"] = "max-age=#{hsts}; includeSubDomains"
         end
 

data/lib/tina4/migration.rb

@@ -199,14 +199,23 @@ module Tina4
           end
           # migration_name is UNIQUE: a migration is "applied" iff a success row
           # exists, so a re-applied name must never duplicate a tracking row.
+          # Firebird's column-definition grammar requires DEFAULT to precede
+          # NOT NULL (<col> <type> [DEFAULT <value>] [NOT NULL]) -- unlike
+          # PostgreSQL/MySQL/SQLite/MSSQL, which accept either order. The
+          # previous "NOT NULL DEFAULT 1" order raised "Invalid token ...
+          # DEFAULT" (SQL error -104) on a real server; never caught before
+          # because no prior test constructed a real Migration against a real
+          # Firebird connection (MIG-FBMSSQL-MOCK, feature 15). Mirrors the
+          # Python reference (_create_v3_table's Firebird branch already uses
+          # this order).
           @db.execute(<<~SQL)
             CREATE TABLE #{TRACKING_TABLE} (
               id INTEGER NOT NULL PRIMARY KEY,
               migration_name VARCHAR(500) NOT NULL UNIQUE,
               description VARCHAR(500),
-              batch INTEGER NOT NULL DEFAULT 1,
+              batch INTEGER DEFAULT 1 NOT NULL,
               executed_at VARCHAR(50) NOT NULL,
-              passed INTEGER NOT NULL DEFAULT 1
+              passed INTEGER DEFAULT 1 NOT NULL
             )
           SQL
         else
@@ -320,10 +329,13 @@ module Tina4
       Tina4::Log.info("Running migration: #{name}")
       begin
         # Wrap each migration FILE in its own transaction so a multi-statement
-        # file that fails midway rolls back as a unit. Truly atomic only on
-        # engines with transactional DDL (PostgreSQL); MySQL/Firebird/SQLite
-        # auto-commit DDL, so earlier statements may persist there — keep one
-        # logical change per file.
+        # file that fails midway rolls back as a unit. Truly atomic on engines
+        # with transactional DDL (PostgreSQL, and SQLite -- autocommit is off
+        # inside start_transaction, proven by
+        # spec/migration_contract_spec.rb's "a multi-statement failure rolls
+        # back the DDL on SQLite too"). MySQL and Firebird auto-commit DDL, so
+        # earlier statements may persist there -- keep one logical change per
+        # file on those two engines.
         @db.start_transaction
         if file.end_with?(".rb")
           execute_ruby_migration(file, :up)
@@ -349,23 +361,35 @@ module Tina4
 
     def rollback_migration(name)
       Tina4::Log.info("Rolling back: #{name}")
+      # FAIL-SAFE (MIG-DEC-02, reuses the Python reference model): each
+      # rollback is its own transaction, and the ledger row is removed ONLY
+      # once the down artifact actually ran (or was confirmed a deliberate
+      # no-op empty file) -- never on a missing or failed down. A missing
+      # artifact now RAISES instead of Tina4::Log.warning-then-still-deleting,
+      # which was the exact MIG-ROLLBACK-DROPS-LEDGER bug: the schema stayed
+      # applied but the tracking row vanished, so it was silently forgotten.
+      @db.start_transaction
       begin
         file = File.join(@migrations_dir, name)
-        if name.end_with?(".rb") && File.exist?(file)
+        if name.end_with?(".rb")
+          raise "Cannot rollback #{name}: no .rb file found" unless File.exist?(file)
+
           execute_ruby_migration(file, :down)
         elsif name.end_with?(".sql")
-          down_file = File.join(@migrations_dir, name.sub(".sql", ".down.sql"))
-          if File.exist?(down_file)
-            execute_sql_file(down_file)
-          else
-            Tina4::Log.warning("No rollback file for: #{name}")
-          end
+          down_file = File.join(@migrations_dir, name.sub(/\.sql\z/, ".down.sql"))
+          raise "Cannot rollback #{name}: no .down.sql file found" unless File.exist?(down_file)
+
+          execute_sql_file(down_file)
+        else
+          raise "Cannot rollback #{name}: unrecognised migration file type"
         end
         _remove_migration_record(name)
+        @db.commit
         { name: name, status: "rolled_back" }
       rescue => e
+        @db.rollback rescue nil
         Tina4::Log.error("Rollback failed: #{name} - #{e.message}")
-        { name: name, status: "failed", error: e.message }
+        raise
       end
     end
 
@@ -593,9 +617,17 @@ module Tina4
 
     # Check if a column already exists in a Firebird table via RDB$RELATION_FIELDS.
     # Firebird stores unquoted identifiers in upper-case.
+    #
+    # The selected literal is ALIASED ("1 AS FOUND", not a bare "1"): #fetch_one
+    # applies limit: 1, and FirebirdDriver#apply_limit wraps the query in a
+    # derived table ("SELECT FIRST 1 SKIP 0 * FROM (<sql>)") -- Firebird REQUIRES
+    # every derived-table column to have a name, and a bare unaliased literal has
+    # none ("no column name specified for column number 1 in derived table",
+    # SQL error -104). Found on a REAL Firebird 5 (MIG-FBMSSQL-MOCK, feature 15)
+    # -- the old FakeDB-based spec never executed a real query here at all.
     def firebird_column_exists?(table, column)
       row = @db.fetch_one(
-        "SELECT 1 FROM RDB\$RELATION_FIELDS WHERE RDB\$RELATION_NAME = ? AND TRIM(RDB\$FIELD_NAME) = ?",
+        "SELECT 1 AS FOUND FROM RDB\$RELATION_FIELDS WHERE RDB\$RELATION_NAME = ? AND TRIM(RDB\$FIELD_NAME) = ?",
         [table.upcase, column.upcase]
       )
       !row.nil?