tina4ruby 3.13.39 → 3.13.40

data/lib/tina4/env.rb

@@ -62,8 +62,13 @@ module Tina4
     end
     lines.concat([
                    "",
-                   "Run `tina4 env --migrate` to rewrite your .env automatically,",
-                   "or rename manually. See https://tina4.com/release/3.12.0",
+                   "Note: these may come from a .env file loaded by dotenv, not just",
+                   "the runtime environment - check your image / build context (a .env",
+                   "baked into a Docker image is loaded at startup) as well as k8s/CI env.",
+                   "",
+                   "FIX: run `tina4 env --migrate` to rewrite your .env automatically",
+                   "(it renames every legacy name to its TINA4_ form in place).",
+                   "Or rename manually. See https://tina4.com/release/3.12.0",
                    "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                    sep, ""
                  ])

data/lib/tina4/mcp.rb

@@ -131,38 +131,71 @@ module Tina4
     schema
   end
 
-  # Check if the server is running on localhost.
+  # Informational only — whether the CONFIGURED host looks local.
+  #
+  # NOT the security gate. This reads TINA4_HOST_NAME (the configured bind
+  # address), which on a 0.0.0.0 bind looks "local" while still accepting
+  # remote clients. Trust decisions use {request_allowed?} with the RAW
+  # socket peer instead. Kept for diagnostics / back-compat.
   def self.is_localhost?
     host = ENV.fetch("TINA4_HOST_NAME", "localhost:7145").split(":").first
     ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].include?(host)
   end
 
-  # Resolve whether the built-in MCP dev server should be active.
+  # Whether an address is a loopback (in-process / same-host) peer.
+  #
+  # Operates on the RAW socket peer, never X-Forwarded-For. Empty means an
+  # in-process / synthetic request (no socket) and is trusted. The `::ffff:`
+  # IPv4-mapped prefix is stripped. NOTE: 0.0.0.0 is a BIND address, never a
+  # client address, so it is deliberately NOT loopback.
   #
-  # Resolution order (highest priority first):
-  #   1. TINA4_MCP set explicitly → use that (truthy/falsey). Honoured on ANY
-  #      host. An explicit `true` is how a sysadmin opts a remote /
-  #      debug-disabled deployment in (e.g. for a remote AI assistant); an
-  #      explicit `false` force-disables it everywhere.
-  #   2. TINA4_DEBUG=true → implicit on for dev, but LOCALHOST-ONLY unless
-  #      TINA4_MCP_REMOTE=true. The MCP dev tools expose powerful operations
-  #      (DB query, file read/WRITE, route listing), so they never auto-expose
-  #      on a non-localhost host without an explicit opt-in.
+  # Python master parity: tina4_python.mcp.is_loopback.
+  def self.is_loopback?(ip)
+    return true if ip.nil? || ip.to_s.empty?
+
+    addr = ip.to_s.strip.downcase
+    addr = addr[7..] if addr.start_with?("::ffff:")
+    addr == "::1" || addr == "localhost" || addr.start_with?("127.")
+  end
+
+  # Capability gate — whether the MCP subsystem may run at all.
+  #
+  # Pure capability, host-INDEPENDENT (Python master parity):
+  #   1. TINA4_MCP set explicitly → use it (sysadmin override, any host).
+  #   2. Else TINA4_DEBUG truthy → MCP is a capability of this deployment.
   #   3. Otherwise off.
   #
-  # Mirrors the Python master (tina4_python/mcp/__init__.py is_enabled). Before
-  # v3.13.39 is_localhost? was dead code and TINA4_MCP_REMOTE was never read, so
-  # the documented localhost guard was not actually enforced — a non-localhost
-  # TINA4_DEBUG=true deployment auto-exposed the dev tools. This wires it.
+  # This NO LONGER consults the host. A debug box bound to 0.0.0.0 still "has"
+  # the capability, but {request_allowed?} is what decides whether a given
+  # CALLER may use it — loopback always, remote only with an explicit opt-in
+  # plus a valid token. Splitting capability from per-request authorisation
+  # closes the hole where a 0.0.0.0 bind auto-exposed DB/file tools to remote
+  # unauthenticated callers (pre-3.13.40 is_localhost? treated 0.0.0.0 local).
   def self.mcp_enabled?
     explicit = ENV["TINA4_MCP"]
     if explicit && !explicit.empty?
       return truthy?(explicit)
     end
-    return false unless truthy?(ENV["TINA4_DEBUG"])
 
-    # Dev auto-enable: localhost only, unless explicitly opted into remote.
-    is_localhost? || truthy?(ENV["TINA4_MCP_REMOTE"])
+    truthy?(ENV["TINA4_DEBUG"])
+  end
+
+  # Per-request authorisation — whether THIS caller may use MCP.
+  #
+  # @param remote_ip [String] raw socket peer (env["REMOTE_ADDR"]), never XFF.
+  # @param has_valid_token [Boolean] true when the request carried a token
+  #   matching TINA4_MCP_TOKEN.
+  #
+  # Rules (Python master parity, tina4_python.mcp.is_request_allowed):
+  #   - Capability off ({mcp_enabled?} false) → deny.
+  #   - Loopback peer → allow.
+  #   - Remote peer → only when TINA4_MCP_REMOTE is truthy AND a valid token
+  #     was presented. No configured token ⇒ remote can never pass.
+  def self.request_allowed?(remote_ip, has_valid_token: false)
+    return false unless mcp_enabled?
+    return true if is_loopback?(remote_ip)
+
+    truthy?(ENV["TINA4_MCP_REMOTE"]) && has_valid_token
   end
 
   # Case-insensitive truthiness for env values: true/1/yes/on.
@@ -593,9 +626,27 @@ module Tina4
         err = looks_like_prose.call(rel_path)
         raise ArgumentError, "Invalid path #{rel_path.inspect}: #{err}" if err
         resolved = File.expand_path(rel_path, project_root)
-        unless resolved.start_with?(project_root)
+        # Compare against root + separator, not a bare prefix: a plain
+        # start_with?(project_root) would also accept a sibling like
+        # "<root>-evil". expand_path already resolves ".." so a climb-out
+        # lands outside root and is rejected here.
+        root_prefix = "#{project_root.chomp(File::SEPARATOR)}#{File::SEPARATOR}"
+        unless resolved == project_root || resolved.start_with?(root_prefix)
           raise ArgumentError, "Path escapes project directory: #{rel_path}"
         end
+        # Belt-and-braces against symlink escapes: if the path already exists,
+        # canonicalise it and re-check containment. A symlink inside the tree
+        # pointing outside would otherwise slip past the textual check. New
+        # paths (parent not created yet) have no realpath and rely on the
+        # expand_path containment above.
+        if File.exist?(resolved)
+          real = File.realpath(resolved)
+          real_root = File.realpath(project_root)
+          real_prefix = "#{real_root.chomp(File::SEPARATOR)}#{File::SEPARATOR}"
+          unless real == real_root || real.start_with?(real_prefix)
+            raise ArgumentError, "Path escapes project directory: #{rel_path}"
+          end
+        end
         resolved
       end
 
@@ -663,7 +714,22 @@ module Tina4
         db = Tina4.database
         return { "error" => "No database connection" } if db.nil?
         param_list = params.is_a?(String) ? JSON.parse(params) : params
-        result = db.fetch(sql, param_list)
+        param_list = [] unless param_list.is_a?(Array)
+        # Defense-in-depth: this tool is read-only. Strip comments, reject
+        # multiple statements, and require a leading SELECT/WITH so it can
+        # never mutate data even if reached (database_execute is the write
+        # surface, gated separately). Mirrors the Python master.
+        cleaned = sql.to_s.gsub(/--[^\r\n]*/, " ").gsub(%r{/\*.*?\*/}m, " ")
+        cleaned = cleaned.strip.sub(/[;\s]+\z/, "")
+        return { "error" => "database_query rejects multiple statements" } if cleaned.include?(";")
+        unless cleaned =~ /\A(select|with)\b/i
+          return { "error" => "database_query is read-only (SELECT/WITH only)" }
+        end
+        begin
+          result = db.fetch(cleaned, param_list)
+        rescue => e
+          return { "error" => (db.get_error rescue nil) || e.message }
+        end
         { "records" => result.to_a, "count" => result.count }
       }, "Execute a read-only SQL query (SELECT)")
 
@@ -692,6 +758,12 @@ module Tina4
       server.register_tool("database_columns", lambda { |table:|
         db = Tina4.database
         return { "error" => "No database connection" } if db.nil?
+        # Constrain the table name to a safe identifier (optionally
+        # schema-qualified) — defense-in-depth so it can never be abused for
+        # injection even if an adapter interpolates it. Parity with Python/PHP.
+        unless table.to_s =~ /\A[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?\z/
+          return { "error" => "Invalid table name" }
+        end
         db.columns(table)
       }, "Get column definitions for a table")
 

data/lib/tina4/rack_app.rb

@@ -454,17 +454,26 @@ module Tina4
     end
 
     def serve_swagger_ui
+      # Honour the documented production on/off switch (TINA4_SWAGGER_ENABLED,
+      # else TINA4_DEBUG) — before v3.13.40 this was never checked and /swagger
+      # (the full API surface) was served unconditionally in production.
+      return [404, { "content-type" => "text/plain" }, ["Not Found"]] unless Tina4::Swagger.enabled?
+
+      # The UI assets load from a CDN by default (keeps the framework
+      # zero-dependency — no vendored ~1.4MB swagger-ui-dist). Air-gapped
+      # deployments point TINA4_SWAGGER_UI_CDN at a self-hosted mirror.
+      cdn = (ENV["TINA4_SWAGGER_UI_CDN"] || "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5").sub(%r{/+\z}, "")
       html = <<~HTML
         <!DOCTYPE html>
         <html lang="en">
         <head>
           <meta charset="UTF-8">
           <title>API Documentation</title>
-          <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+          <link rel="stylesheet" href="#{cdn}/swagger-ui.css">
         </head>
         <body>
           <div id="swagger-ui"></div>
-          <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+          <script src="#{cdn}/swagger-ui-bundle.js"></script>
           <script>
             SwaggerUIBundle({ url: '/swagger/openapi.json', dom_id: '#swagger-ui' });
           </script>
@@ -475,8 +484,11 @@ module Tina4
     end
 
     def serve_openapi_json
-      @openapi_json ||= JSON.generate(Tina4::Swagger.generate)
-      [200, { "content-type" => "application/json; charset=utf-8" }, [@openapi_json]]
+      return [404, { "content-type" => "application/json; charset=utf-8" }, ['{"error":"Not Found"}']] unless Tina4::Swagger.enabled?
+
+      # Regenerate per request — DevReload adds routes in-process (same PID), so
+      # a memoized spec would go stale until restart. Swagger.generate is cheap.
+      [200, { "content-type" => "application/json; charset=utf-8" }, [JSON.generate(Tina4::Swagger.generate)]]
     end
 
     def handle_403(path = "")

data/lib/tina4/swagger.rb

@@ -7,14 +7,28 @@ module Tina4
       def generate(routes = [])
         spec = base_spec
         route_list = routes.empty? ? Tina4::Router.routes : routes
+        # Accumulators shared across routes: ORM models referenced
+        # (-> components.schemas), tags used (-> top-level tags[]), seen
+        # operationIds (de-dup — OpenAPI requires them unique).
+        ctx = { models: {}, used_tags: [], seen_ids: [] }
         route_list.each do |route|
-          add_route_to_spec(spec, route)
+          add_route_to_spec(spec, route, ctx)
         end
+
+        unless ctx[:models].empty?
+          spec["components"]["schemas"] = {}
+          ctx[:models].each do |name, klass|
+            spec["components"]["schemas"][name] = model_schema(klass)
+          end
+        end
+        spec["tags"] = ctx[:used_tags].map { |t| { "name" => t } } unless ctx[:used_tags].empty?
+
         spec
       end
 
-      # TINA4_SWAGGER_ENABLED — defaults to TINA4_DEBUG. When false, callers
-      # can choose to skip mounting /swagger entirely in production.
+      # TINA4_SWAGGER_ENABLED — defaults to TINA4_DEBUG. Wired into RackApp's
+      # /swagger serving (v3.13.40), so it genuinely gates whether the docs are
+      # served — it was dead code before.
       def enabled?
         explicit = ENV["TINA4_SWAGGER_ENABLED"]
         if explicit && !explicit.empty?
@@ -51,9 +65,7 @@ module Tina4
         {
           "openapi" => "3.0.3",
           "info" => info,
-          "servers" => [
-            { "url" => "/" }
-          ],
+          "servers" => servers,
           "paths" => {},
           "components" => {
             "securitySchemes" => {
@@ -67,48 +79,125 @@ module Tina4
         }
       end
 
-      def add_route_to_spec(spec, route)
-        path = convert_path(route.path)
+      # servers[] — TINA4_SWAGGER_SERVERS (comma-separated) for a multi-server
+      # list, else SWAGGER_DEV_URL, else the relative "/" default.
+      def servers
+        raw = ENV.fetch("TINA4_SWAGGER_SERVERS", "")
+        urls = raw.split(",").map(&:strip).reject(&:empty?)
+        return urls.map { |u| { "url" => u } } unless urls.empty?
+
+        dev = ENV["SWAGGER_DEV_URL"]
+        return [{ "url" => dev }] if dev && !dev.empty?
+
+        [{ "url" => "/" }]
+      end
+
+      # Valid OpenAPI path-item methods. Anything else (e.g. "any", a WebSocket
+      # "ws") is not a valid key and would make the document spec-invalid.
+      HTTP_METHODS = %w[get post put patch delete head options trace].freeze
+
+      def add_route_to_spec(spec, route, ctx)
         method = route.method.downcase
-        return if method == "any"
+        return unless HTTP_METHODS.include?(method)
+
+        path = convert_path(route.path)
+        meta = route.swagger_meta || {}
+
+        # ORM model -> components.schemas + $ref
+        ref = nil
+        if (model = meta[:model])
+          klass = model.is_a?(String) ? resolve_model(model) : model
+          if klass
+            name = klass.name.split("::").last
+            ctx[:models][name] ||= klass
+            ref = "#/components/schemas/#{name}"
+          end
+        end
+
+        tags = meta[:tags] || [extract_tag(route.path)]
+        tags.each { |t| ctx[:used_tags] << t unless ctx[:used_tags].include?(t) }
 
         spec["paths"][path] ||= {}
         operation = {
-          "summary" => route.swagger_meta[:summary] || "#{method.upcase} #{route.path}",
-          "description" => route.swagger_meta[:description] || "",
-          "tags" => route.swagger_meta[:tags] || [extract_tag(route.path)],
+          "operationId" => unique_operation_id(method, path, ctx[:seen_ids]),
+          "summary" => meta[:summary] || "#{method.upcase} #{route.path}",
+          "description" => meta[:description] || "",
+          "tags" => tags,
           "parameters" => build_parameters(route),
-          "responses" => route.swagger_meta[:responses] || default_responses
+          "responses" => meta[:responses] || model_or_default_responses(ref, meta[:model_list])
         }
 
+        operation["deprecated"] = true if meta[:deprecated]
+
         if route.auth_handler
           operation["security"] = [{ "bearerAuth" => [] }]
         end
 
-        if %w[post put patch].include?(method) && route.swagger_meta[:request_body]
-          operation["requestBody"] = route.swagger_meta[:request_body]
-        elsif %w[post put patch].include?(method)
-          operation["requestBody"] = default_request_body
+        if %w[post put patch].include?(method)
+          operation["requestBody"] = build_request_body(method, meta, ref)
         end
 
         spec["paths"][path][method] = operation
       end
 
+      def build_request_body(_method, meta, ref)
+        return meta[:request_body] if meta[:request_body]
+
+        schema = ref ? { "$ref" => ref } : { "type" => "object" }
+        content = { "schema" => schema }
+        content["example"] = meta[:example] if meta[:example]
+        { "content" => { "application/json" => content } }
+      end
+
+      def model_or_default_responses(ref, model_list)
+        return default_responses unless ref
+
+        schema = model_list ? { "type" => "array", "items" => { "$ref" => ref } } : { "$ref" => ref }
+        {
+          "200" => {
+            "description" => "Successful response",
+            "content" => { "application/json" => { "schema" => schema } }
+          }
+        }
+      end
+
       def convert_path(path)
-        # Convert {id:int} to {id}
-        path.gsub(/\{(\w+)(?::\w+)?\}/, '{\1}')
+        # {id:int} -> {id}
+        p = path.gsub(/\{(\w+)(?::\w+)?\}/, '{\1}')
+        # splat *path -> {path}; bare /* -> /{wildcard} (a literal '*' segment
+        # or an orphaned splat param is invalid OpenAPI templating)
+        p = p.gsub(/\*(\w+)/, '{\1}')
+        p.gsub(%r{(?<=/)\*(?=/|$)}, "{wildcard}")
       end
 
       def extract_tag(path)
         parts = path.split("/").reject(&:empty?)
-        parts.first || "default"
+        first = parts.first
+        return "default" if first.nil? || first.start_with?("{", "*")
+
+        first
+      end
+
+      def unique_operation_id(method, path, seen)
+        base = method + path.gsub(%r{[/{}*]}) { |c| c == "*" ? "wildcard" : "_" }
+        base = base.gsub(/_+/, "_").chomp("_")
+        oid = base
+        n = 2
+        while seen.include?(oid)
+          oid = "#{base}_#{n}"
+          n += 1
+        end
+        seen << oid
+        oid
       end
 
       def build_parameters(route)
         params = []
         route.param_names.each do |param|
+          name = param[:name].to_s
+          name = "wildcard" if name == "*"
           params << {
-            "name" => param[:name].to_s,
+            "name" => name,
             "in" => "path",
             "required" => true,
             "schema" => param_schema(param[:type])
@@ -118,16 +207,71 @@ module Tina4
       end
 
       def param_schema(type)
-        case type
+        case type.to_s
         when "int", "integer"
           { "type" => "integer" }
         when "float", "number"
           { "type" => "number" }
+        when "uuid"
+          { "type" => "string", "format" => "uuid" }
+        when "slug"
+          { "type" => "string", "pattern" => "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        when "alpha"
+          { "type" => "string", "pattern" => "^[A-Za-z]+$" }
+        when "alnum"
+          { "type" => "string", "pattern" => "^[A-Za-z0-9]+$" }
+        else
+          { "type" => "string" }
+        end
+      end
+
+      # Build a components.schemas object from an ORM model's field definitions.
+      def model_schema(model_class)
+        props = {}
+        required = []
+        defs = model_class.respond_to?(:field_definitions) ? model_class.field_definitions : {}
+        defs.each do |name, opts|
+          props[name.to_s] = field_schema(opts)
+          required << name.to_s if opts[:nullable] == false
+        end
+        schema = { "type" => "object", "properties" => props.empty? ? {} : props }
+        schema["required"] = required unless required.empty?
+        schema
+      end
+
+      def field_schema(opts)
+        schema = map_field_type(opts[:type])
+        schema["readOnly"] = true if opts[:primary_key] && opts[:auto_increment]
+        schema
+      end
+
+      def map_field_type(type)
+        case type.to_s
+        when "integer"
+          { "type" => "integer" }
+        when "float", "decimal", "numeric"
+          { "type" => "number" }
+        when "boolean"
+          { "type" => "boolean" }
+        when "datetime", "date", "timestamp"
+          { "type" => "string", "format" => "date-time" }
+        when "blob"
+          { "type" => "string", "format" => "byte" }
         else
           { "type" => "string" }
         end
       end
 
+      def resolve_model(name)
+        Object.const_get(name)
+      rescue NameError
+        begin
+          Tina4.const_get(name)
+        rescue NameError
+          nil
+        end
+      end
+
       def default_responses
         {
           "200" => { "description" => "Successful response" },
@@ -137,16 +281,6 @@ module Tina4
           "500" => { "description" => "Internal server error" }
         }
       end
-
-      def default_request_body
-        {
-          "content" => {
-            "application/json" => {
-              "schema" => { "type" => "object" }
-            }
-          }
-        }
-      end
     end
   end
 end

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.39"
+  VERSION = "3.13.40"
 end

data/lib/tina4.rb

@@ -50,6 +50,7 @@ require_relative "tina4/error_overlay"
 require_relative "tina4/test_client"
 require_relative "tina4/test"
 require_relative "tina4/docs"
+require_relative "tina4/docstore"
 require_relative "tina4/mcp"
 
 module Tina4

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.39
+  version: 3.13.40
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -278,6 +278,7 @@ files:
 - lib/tina4/dev_admin.rb
 - lib/tina4/dev_mailbox.rb
 - lib/tina4/docs.rb
+- lib/tina4/docstore.rb
 - lib/tina4/drivers/firebird_driver.rb
 - lib/tina4/drivers/mongodb_driver.rb
 - lib/tina4/drivers/mssql_driver.rb