railwatch-server 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcacb047d9cf5bb22240714ce151df68c886a9e9ded531bf0937b487c3d11983
-  data.tar.gz: c5b475ace2a3fcceffa5f7a1d029e14923bae9bc6e17045f3c7e876ee027b631
+  metadata.gz: 044ca51326a9a973769258885495639465aa0d8127c4c8248f761d484324c3db
+  data.tar.gz: 5cdddf3a5fb4bdca4f4711ce347e578c26b6f9dc0d4f84836a0e4d124b9459e5
 SHA512:
-  metadata.gz: a255c06462451b89c159853645fd715d0029db8388e4b581908fd53095a264b7161cdc7332c45082badc50297ae823d12985c0e55bb4e6661da5785e383abe62
-  data.tar.gz: 8ac3ddbf0926b87ee811cf4ffbb1018d6e6c34cc37f53ebbd94549ad1f7efa47342a4bcc27aa8cc6d4a4b29fa2601266da07bfc903901e986223a86f83dc6eb7
+  metadata.gz: d3ce595cd4b47ffec3e8c61581d70e5c68808644d81868efcf865ac8908dbc7b13d02914be28f62ccbfe9e9177423c7cf19e3ad0bf7eb94ee77d7b3bd03d7ba6
+  data.tar.gz: e1d58c1d34eb13b433e3a83418cb6171f8822d7be3bd729050173158ff5b5a8c832fa331aec536d9a2628da8c71255c0014a01be53bbd9e0f7caa66f206e899b

data/README.md

@@ -91,6 +91,7 @@ whether the server is up, and where the agent reports.
 | `RAILWATCH_SERVER_PROXY_CONNECT_TIMEOUT` | `2` | seconds to connect to the server on loopback; past it, 503 |
 | `RAILWATCH_SERVER_PROXY_FIRST_BYTE_TIMEOUT` | `25` | seconds for the server to start answering a dashboard request; past it, 504 with a message. Under 30 s on purpose: Thruster (its write timeout) and kamal-proxy drop a response that hasn't started after 30 s, and the visitor gets an empty reply instead |
 | `RAILWATCH_SERVER_PROXY_IDLE_TIMEOUT` | `60` | seconds a response that has started may go without a byte moving; past it the connection is closed |
+| `RAILWATCH_SERVER_AGENT_ACCESS` | on in development for this machine only, off elsewhere | whether `<mount>/mcp` and `<mount>/api/` (an AI agent's requests) are signed for the visitor like the dashboard, so the agent needs no token. See [AI agents](#ai-agents) |
 | `RAILWATCH_SERVER_NICE` | `10` | how far below the app's CPU priority the server runs (0-19; 0: the same). A busy dashboard can keep every core busy; measured in a 2-CPU container under 30 dashboard clients at the app's priority, the app's `/up` p50 went from 2 to 15 ms. Not under a CPU quota (`docker --cpus`, Kubernetes CPU limits): the kernel throttles the container's processes together whatever their priority, and in that 2-CPU container under `--cpus 2` nice 10 measured no better than nice 0 (`/up` p99 190-580 ms at either); on 2 dedicated cores (`--cpuset-cpus`) it took `/up` p99 from 207-363 ms to 18-22 ms. In a quota-limited container give it real cores (a cpuset, or a VM) or keep dashboard use light |
 
 **Environments.** One environment per data dir, named after `Rails.env`:
@@ -143,6 +144,54 @@ end
 Without it, the HTTP Basic user name (or "Operator") is an admin. Users are
 created in the server on first sight. Nobody signs in to the server itself.
 
+## AI agents
+
+The server's MCP endpoint and JSON API are under the mount too
+(`/railwatch/mcp`, `/railwatch/api/v1`). The bundled railwatch-rs takes the
+proxy's signed user on them, so an agent on the same machine needs no token
+in development:
+
+```sh
+claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp
+```
+
+(or `bin/rails generate railwatch:agents` from the railwatch gem, which
+writes `.mcp.json` and the instructions). The proxy signs those requests
+for the visitor exactly as it signs dashboard pages, and the server takes
+the signed header as that user on MCP and the API: every read tool, and the
+issue writes (`update_issue`, `add_comment`), attributed to the user and
+"agent".
+
+**What that opens, and to whom.** By default (`agent_access` unset) only
+when all of these hold:
+
+- `Rails.env.development?` (the server's environment, `config.environment`);
+- the request comes from this machine (`request.local?`: `127.0.0.1` or
+  `::1`). A dev server bound to `0.0.0.0` still refuses the LAN;
+- its `Host` is `localhost`, `127.0.0.1` or `::1`. A web page whose own name
+  was rebound to `127.0.0.1` (DNS rebinding) arrives under that name, not
+  these, and gets no signature;
+- the dashboard's gate passes, as for any page (open in development unless
+  you configured HTTP Basic or a base controller).
+
+The server also refuses a signed MCP or API request the browser marks as
+coming from another site (`Origin` that is not the `Host`, or
+`Sec-Fetch-Site: cross-site`), so a page you visit can't call them through
+your browser. What is left: anything that can send a request to
+`localhost:3000` from your machine (another local user, a local process)
+can read the development app's telemetry and comment on its issues. That is
+already true of the dashboard at `/railwatch` in development, and of the
+dev app itself.
+
+Everywhere else agent requests are forwarded without the visitor and the
+server answers 401 until the agent sends a token (`Authorization: Bearer
+rwp_...` from Settings -> Profile), which the proxy passes through
+unchanged; a token always wins over the signature, in development too.
+`config.agent_access = true` (or `RAILWATCH_SERVER_AGENT_ACCESS=1`) signs
+agent requests for whoever passes the gate in any environment: only behind
+a gate that authenticates people (`base_controller_class` with your login),
+since the agent then acts as them. `false` turns it off in development too.
+
 ## How it works
 
 ```

data/app/controllers/railwatch/server/proxy_controller.rb

@@ -103,6 +103,8 @@ module Railwatch
         Purpose Sec-Purpose Sec-Fetch-Site Sec-Fetch-Mode Sec-Fetch-Dest If-None-Match If-Modified-Since
       ].freeze
       HOP_BY_HOP = %w[connection keep-alive transfer-encoding content-length te trailer upgrade proxy-connection].freeze
+      # Host names that only reach this machine (agent_access?).
+      LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
 
       skip_forgery_protection if respond_to?(:skip_forgery_protection)
       before_action :authenticate_by_http_basic
@@ -147,9 +149,15 @@ module Railwatch
 
       private
 
+      # An agent's Bearer token takes the one Authorization header Basic would
+      # need, so a request to MCP or the API with one is left to the server,
+      # which checks the token (401 without a valid one) as a standalone
+      # railwatch-rs does. The app's own before_actions (base_controller_class)
+      # still run.
       def authenticate_by_http_basic
         config = Railwatch.config
         return unless config.http_basic_auth_enabled
+        return if agent_bearer
         return if config.http_basic_auth_ok?(request)
 
         request_http_basic_authentication("Railwatch")
@@ -172,6 +180,32 @@ module Railwatch
         ProxyAuth.sign(secret, email: v[:email], name: v[:name], role: v[:role])
       end
 
+      # The server's MCP endpoint and JSON API: what an AI agent calls.
+      def agent_request?
+        mount = Railwatch::Server.config.normalized_mount_path
+        rest = mount == "/" ? request.path : request.path.delete_prefix(mount)
+        rest == "/mcp" || rest.start_with?("/api/")
+      end
+
+      # Whether an agent request is signed for the visitor (config.agent_access).
+      # By default only in development, and only for a request from this
+      # machine (request.local?: a dev server bound to 0.0.0.0 still refuses
+      # the LAN) to a local host name (a page on another site that rebinds
+      # its own name to 127.0.0.1 arrives with that name as Host).
+      def agent_access?
+        setting = Railwatch::Server.config.agent_access
+        return setting unless setting.nil?
+
+        Railwatch::Server.config.environment == "development" && request.local? && LOCAL_HOSTS.include?(request.host)
+      end
+
+      # An agent's own token, which the server checks: sent on as it came,
+      # and the visitor is not signed (the server would ignore them anyway).
+      def agent_bearer
+        value = request.authorization.to_s
+        value if agent_request? && value.start_with?("Bearer ")
+      end
+
       def upstream_headers(secret)
         headers = FORWARDED_HEADERS.each_with_object({}) do |name, h|
           value = request.headers[name]
@@ -188,7 +222,13 @@ module Railwatch
         # and only that: the server (RAILWATCH_TRUST_PROXY) keys its per-IP
         # limits on the last address here.
         headers["X-Forwarded-For"] = request.remote_ip
-        headers[ProxyAuth::HEADER] = signed_header(secret)
+        # An agent request without access goes on unsigned: the server's 401
+        # tells the agent to send a token.
+        if (bearer = agent_bearer)
+          headers["Authorization"] = bearer
+        elsif !agent_request? || agent_access?
+          headers[ProxyAuth::HEADER] = signed_header(secret)
+        end
         headers
       end
 

data/lib/railwatch/server/configuration.rb

@@ -16,7 +16,8 @@ module Railwatch
     class Configuration
       attr_accessor :enabled, :port, :data_dir, :mount_path, :binary, :url, :stop_timeout, :setup_timeout, :user, :wire_agent,
                     :max_live_connections, :max_proxied_requests, :proxy_connect_timeout, :proxy_first_byte_timeout,
-                    :proxy_idle_timeout, :nice, :smtp, :mail_from, :backup, :google, :retention, :alert_delivery, :server_env
+                    :proxy_idle_timeout, :nice, :smtp, :mail_from, :backup, :google, :retention, :alert_delivery, :server_env,
+                    :agent_access
 
       def initialize
         # nil: on, except under Rails.env.test (a test run on a machine with
@@ -48,6 +49,13 @@ module Railwatch
         # Who the dashboard's visitor is, as the server should see them:
         # ->(controller) { { email:, name:, role: "admin" | "member" } }.
         @user = nil
+        # Whether <mount>/mcp and <mount>/api/ (what an AI agent calls) are
+        # signed for the visitor like the dashboard, so the agent needs no
+        # token. nil: only in development, for a request from this machine
+        # to a local host name (ProxyController#agent_access?). true: for
+        # every request that passes the gate, in any environment. false:
+        # never; an agent sends a token (Authorization: Bearer rwp_...).
+        @agent_access = env_bool("RAILWATCH_SERVER_AGENT_ACCESS", nil)
         # Point the railwatch agent at the bundled server when the app has not
         # configured one (no RAILWATCH_TOKEN). Off: the app wires it itself.
         @wire_agent = env_bool("RAILWATCH_SERVER_WIRE_AGENT", true)

data/lib/railwatch/server/version.rb

@@ -2,9 +2,9 @@
 
 module Railwatch
   module Server
-    VERSION = "0.1.3"
+    VERSION = "0.1.4"
     # The published railwatch-rs commit the bundled binaries are built from
     # (README, "The server side"); the Corresponding Source under AGPL-3.0.
-    RAILWATCH_RS = "d465705aa111c0f264315d2f640a364513015fd7"
+    RAILWATCH_RS = "36cd8771f1a6da2cf1b94052f7b2052a8a1ea630"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch-server
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Rebulk
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement