sitegoose 0.3.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f88d90ea071f9dde430e079a88e42a22dabd4f0faeaa4a662da5c94eb8cd942c
+  data.tar.gz: 1033458a91be1a78a2464a9439d2d021eaedce386b0cfb7eb7662db4927a3e50
+SHA512:
+  metadata.gz: e20cd12422c5830f3a710340198b634c2c192e9d26a830879fa756ebd1901a95c28054ab5d74d73812a80b7243653078592ddd59d9df02048760039b6e9f543b
+  data.tar.gz: 5190a6b466bdf730a41265537aa1fdf01090aaeb77966d0bf720532ec12db816ebcb15b9ee96561e0a1f45c4d5f9d83256a1adf049f05873f94e57118896c635

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 steviec87
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,342 @@
+# sitegoose (Ruby)
+
+One package for your Ruby server, run from your analytics dashboard: a
+**firewall**, **error monitoring** and **server analytics** (payments,
+sign-ups, leads). Rails, Sinatra and any Rack app, with Sidekiq jobs. Only
+the standard library and `rack`; Ruby 3.0 or later.
+
+```ruby
+# Gemfile
+gem "sitegoose"
+```
+
+## Rails
+
+Nothing to add to the middleware stack: the gem's Railtie puts it first.
+
+```ruby
+# config/initializers/sitegoose.rb
+SiteGoose.configure(
+  site_id: "YOUR_SITE_ID",
+  secret: ENV["ANALYTICS_SITE_SECRET"],   # site settings; keep it on the server
+  endpoint: "https://YOUR_COLLECTOR_URL",
+  # trust_proxy: 1,             # behind Nginx or a load balancer
+  # trust_proxy: "cloudflare",  # every request through Cloudflare
+)
+```
+
+Or keep it in the credentials (`bin/rails credentials:edit`), under
+`sitegoose:` with the same keys, or in `config.sitegoose`.
+The environment works too: `ANALYTICS_SITE_ID`, `ANALYTICS_SITE_SECRET`,
+`ANALYTICS_ENDPOINT`, `ANALYTICS_SERVER_NAME`, `ANALYTICS_TRUST_PROXY`.
+Lowest first: the environment, credentials, `config.sitegoose`,
+`configure`.
+
+Then, on their own:
+
+- Request errors, with the route pattern (`/orders/:id`), including the ones
+  Rails turns into its 500 page.
+- `Rails.error.handle`, `.record` and `.report`: the errors your code handles.
+- Devise (Warden) failed logins count towards bot protection, and logins and
+  logouts go to the audit log.
+- The controller action, mail and queued job before an error are its
+  breadcrumbs.
+
+In your code: `SiteGoose.track(...)`, or `SiteGoose.platform`.
+
+## Sinatra and other Rack apps
+
+```ruby
+use SiteGoose::Middleware,
+    site_id: "YOUR_SITE_ID", secret: ENV["ANALYTICS_SITE_SECRET"], endpoint: "https://YOUR_COLLECTOR_URL"
+```
+
+Put it first; added twice (by hand next to the Railtie, or by an engine),
+the second copy passes requests straight on. Sinatra's route patterns (`/users/:id`) and its error pages are
+read on their own; set `set :raise_errors, false` (production's default) or
+`set :show_exceptions, false` as usual. Hanami, Roda and plain Rack work the
+same way. A full example is in `examples/sinatra/`.
+
+## Sidekiq
+
+```ruby
+# config/initializers/sidekiq.rb
+require "sitegoose/sidekiq"
+SiteGoose::Sidekiq.install
+```
+
+Every job then runs as a [job](#error-monitoring) named after its class (the
+ActiveJob class under ActiveJob): its errors carry the route
+`/(job) ChargeJob`, and each run is timed (Server speed → Jobs).
+
+- A failure that will be retried is timed as failed but not sent: the error
+  is sent when the last attempt fails, or when Sidekiq gives the job up (the
+  Dead set, `:kill`).
+- `Sidekiq::Shutdown` (a job stopped mid-run, to run again) is neither timed
+  nor sent.
+- What's waiting is sent when Sidekiq shuts down.
+- Don't also wrap a job in `platform.job`: it would be timed twice.
+
+## Puma, Unicorn and Passenger
+
+The platform is made on the first request, so a master that only forks
+workers starts nothing. Its background threads start again in each worker
+after a fork (Puma clustered mode, `preload_app!`, Unicorn, Passenger), a
+fork waits for a send in flight, and what the parent had waiting is the
+parent's to send. Nothing to configure. On Ruby 3.0, which has no fork hook,
+a worker notices it was forked at its first request or job instead, and a
+fork doesn't wait for a send in flight.
+
+## Modules
+
+| Module | What it does | Default |
+|---|---|---|
+| `firewall` | Blocks addresses, known criminal networks, shared blocks and floods (Security → Firewall) | on |
+| `firewall`'s attack patterns | Rules that match the *request* (its path, query string and user agent), not just the address, so an attack is turned away before your code runs. They come with the firewall's rules and are managed on the Security page (Firewall → Attack patterns). Nothing to configure (protocol: `sdk/protocols/firewall.md`). Patterns need Ruby 3.2+, which can stop a match that runs long; on 3.0 and 3.1 a rule's pattern is skipped (its other parts still match) and a warning says so once | with the firewall |
+| `proxy` | Serves the tracker and takes visits under your own domain, so ad blockers can't hide those visitors | on |
+| `errors` | Sends your server's errors to the Errors report | on |
+| `analytics` | `track`, `identify` and `lead` from your server | on |
+| `audit` | `platform.audit("user.role_changed", actor: ..., target: ..., request: ...)`; Devise logins and logouts on their own | on |
+| `flags` | `platform.enabled?("new-checkout", user: user.id)`: features on or off from the dashboard | on |
+| `maintenance` | A "back soon" page while maintenance mode is on in the dashboard | on |
+| `headers` | Adds the security headers you pick on the Security page; your own headers win | on |
+| `forms` | Checks forms before you accept them: `platform.check_form(request)` | on |
+| `performance` | Response times and errors of every route (Health → Server speed): Rails and Sinatra route patterns. With it, the database queries each route runs (below) | on |
+| `crawlers` | Which search engines and AI bots fetch your pages (Health → Crawlers), counted by the middleware | on |
+| `resources` | This machine's CPU, load, memory, disks and network, once a minute (Health → Server resources). Linux | on |
+| `inventory` | The installed gems and Ruby version, once a day, so the Security check can flag known security holes (`{host: ...}`: the server's name) | on |
+| `posture` | How the server is set up, once a day, for the Security check: Rails' environment, `consider_all_requests_local`, `secret_key_base`, `config.hosts`, `force_ssl` and session cookie settings (when it's a Rails app), whether the app runs as root, code anyone on the machine can write, and files in the folders you serve to the web that shouldn't be public (a dump, a `.env`, a `.bak`). Reads only, and sends no file's contents. `{roots: ["public", {dir: "uploads", prefix: "files"}]}` (default: Rails' `public/`), `{checks: -> { [...] }}` for checks of your own (protocol: `sdk/protocols/posture.md`) | on |
+
+Each takes `true`, `false` or its options as a hash:
+
+```ruby
+SiteGoose.configure(site_id: ..., secret: ..., endpoint: ...,
+                            firewall: { mode: "monitor", cache_file: "tmp/firewall-rules.json" },
+                            errors: { capture_uncaught: false },
+                            analytics: false)
+```
+
+`enabled: false` turns the whole package off (every request passes).
+
+**Switch modules off in the dashboard** (Security → Server package) without a
+deploy: the package checks about once a minute. Modules are independent: one
+failing to start, or the collector being down, never stops the others, and
+never slows your requests; a failure of the package itself passes the request
+to your app.
+
+## Database queries
+
+Server speed → Queries: per route and per query, how many ran, how many
+failed, and how long they took, so a slow route shows which query made it
+slow. Every value is replaced by `?` before anything is counted
+(`WHERE email = ?`), and bound parameters are never read
+(protocol: `sdk/protocols/queries.md`).
+
+- **Active Record** (Rails, or on its own): automatic, from its
+  `sql.active_record` notification. Schema and cached queries are left out.
+- **Sequel**: one line, after `Sequel.connect`:
+
+  ```ruby
+  DB = Sequel.connect(ENV["DATABASE_URL"])
+  SiteGoose.watch_database(DB)
+  ```
+
+- **MongoDB** (the `mongo` gem, Mongoid): automatic, through the driver's
+  command monitoring.
+
+A query counts under the request (or Sidekiq or `platform.job` run) it ran
+in, with the same method and route Server speed shows; one outside them,
+like a console or a thread of your own, counts as `JOB (background)`. A
+query is counted once: one run by Sequel on Active Record's connection is
+Sequel's. It rides on `performance`: switched off there, nothing is
+recorded; `queries: false` keeps Server speed without the queries:
+
+```ruby
+SiteGoose.configure(site_id: ..., secret: ..., endpoint: ..., queries: false)
+```
+
+## Firewall
+
+Rules, monitor or block mode and reports are in the dashboard (Security →
+Firewall). New sites start in monitor mode.
+
+Options: `mode` (`"monitor"` or `"block"`, overrides the dashboard),
+`cache_file` (keep rules between restarts), `trust_proxy`, `counter`.
+
+**The visitor's address:** behind a proxy, every request comes from the proxy
+unless you set `trust_proxy`: `1` for one proxy or load balancer, `2` for
+Cloudflare in front of a load balancer, `"cloudflare"` when every request
+comes through Cloudflare (`CF-Connecting-IP` is believed only from
+Cloudflare's own addresses: anyone who reaches your server directly can send
+it). The package reads the connection's address itself, not Rails'
+`request.remote_ip`, so set it here even if Rails already trusts the proxy.
+
+**Who is counted:** an IPv4 address, or an IPv6 address's /64 (one machine
+usually holds the whole /64); `::ffff:a.b.c.d` is the IPv4 address. Files a
+page load asks for by the dozen (`/assets/`, `/packs/`, `.css`, `.js`, images,
+fonts) don't count against the rate limit. A forwarded address that isn't one
+(`unknown`, a name) means the connection's address is checked instead, and a
+port on it (`1.2.3.4:5678`, `[2001:db8::1]:443`) is dropped.
+
+**Rate limit with several workers:** each worker counts on its own, so the
+limit is per worker. For one count, pass a shared counter:
+
+```ruby
+counter = lambda do |key, ttl|
+  hits = REDIS.incr(key)
+  REDIS.expire(key, ttl) if hits == 1
+  hits
+end
+
+SiteGoose.configure(..., firewall: { counter: counter })
+```
+
+**Bot protection:** Devise's failed logins are counted on their own;
+elsewhere call `platform.login_failed(request)` when a login fails. Past the
+site's limit the address is banned here straight away and on your other
+servers within a minute or two. Floods (over the rate limit) are banned the
+same way.
+
+**Probes.** Requests for files no visitor ever asks for (`/.env`, `/.git/…`,
+backups: the list comes with the rules) are rule `probe`; in block mode the
+address is also banned on this server, and the collector bans it on the
+site's other servers.
+
+**Browser check** (paid plans, switched on in the dashboard). A visitor's
+first page of the day is a short "checking your browser" page that sets a
+cookie with JavaScript and reloads; after that the site answers as usual for
+about a day. Only a `GET` or `HEAD` that asks for a web page is checked:
+forms, webhooks, payment callbacks, API calls (`Accept: application/json`),
+the paths you exclude, your allowed addresses, search engines and the AI
+crawlers that bring visits never see it. It stops cheap floods (scripts that
+don't run JavaScript) and nothing more: the pass is bound to the visitor's
+address and the day. The cookie, `__sg_pass`, holds a signed day and nothing
+about the visitor; it is strictly necessary and needs no consent. Checked
+requests show on the Security page as rule `challenge`.
+
+## Error monitoring
+
+Request errors are sent by the middleware, and the exception that ends the
+program (a crash in a script or rake task) at exit. Errors you catch:
+
+```ruby
+begin
+  charge_card(order)
+rescue PaymentError => e
+  SiteGoose.capture_exception(e, status: 502)
+  raise
+end
+```
+
+In Rails, `Rails.error.handle { ... }` and `Rails.error.report(e)` do the
+same. Exceptions your code only logs: `errors: { capture_logging: true }`
+sends an exception logged at ERROR or above (`logger.error(e)`); it is still
+logged. Rails' logger is hooked on its own; elsewhere
+`platform.capture_logger(logger)`. An exception is sent once however many of
+these see it, and one sent inside a request keeps that request's route. A
+batch the collector couldn't take is tried once more a few seconds later.
+
+What still can't be sent waits in a file in the temp folder and is sent when
+it can be, after a restart too; each error keeps the time it happened.
+
+An error in a request or job also shows the steps before it. Add them with
+`SiteGoose.add_breadcrumb("Order saved")`; a step added outside a
+request or job is dropped. Outgoing HTTP calls aren't recorded on their own
+(Ruby has no public hook for them); in Rails the controller, mailer and job
+notifications are.
+
+Background jobs other than Sidekiq's:
+
+```ruby
+SiteGoose.job("send-receipts") { send_receipts }
+```
+
+Their errors carry the job's name as the route, a job that raises is sent
+(status 500) and raised on, and each run is timed (Server speed → Jobs).
+
+**Several apps on one site** (a Rails app, a Sidekiq process, a Node service
+next to it): install the package in each, with the same `site_id`, `secret`
+and `endpoint`, and a `server_name` of its own. Errors, Server speed,
+Crawlers and Security → Updates then tell the apps apart, and Health → All
+systems lists each with a light: the package checks in about once a minute
+(`sdk/protocols/checkin.md`). A service only your other apps call takes
+`firewall: false, proxy: false, maintenance: false`; on a machine shared by
+several apps, keep `resources` on in only one of them.
+
+Options: `server_name`, `root` (backtrace paths relative to it; default
+`Rails.root` or the working directory), `release` (default
+`ANALYTICS_RELEASE`), `capture_uncaught`, `capture_logging`, `spool_dir`
+(where unsent errors wait; `false` for none), `before_send` (a lambda taking
+the event and the error: return the event, changed or not, as a Hash, or
+`nil` to drop it; anything else, or a raise, drops it with a warning).
+Messages are cut at 2,000 characters, and the file of unsent errors stops at
+1 MB.
+
+## Server analytics
+
+For what only your server knows for sure. Not pageviews: the tracker counts those.
+
+```ruby
+platform = SiteGoose.platform
+session = platform.session_id(request)  # the visit, from the X-Analytics-Session header
+
+platform.track("purchase", { "numeric_value" => "49.90", "currency" => "EUR", "event_uid" => "order-#{order.id}" }, session_id: session)
+platform.identify(user.id, session_id: session)
+platform.lead({ "email" => "ana@example.com", "name" => "Ana", "status" => "qualified" })
+```
+
+`track` sends in the background; `identify` and `lead` wait for the answer
+(up to 5 seconds).
+
+**Link to the visit:** send the tracker's session ID with your site's requests:
+
+```js
+fetch("/api/orders", { headers: { "x-analytics-session": window.analyticsSession?.getId() || "" }, ... });
+```
+
+## Ad blockers
+
+This package already runs on your own domain, so it serves the tracker and
+takes the visits itself. Use the two addresses it gives you in your layout:
+
+```erb
+<% proxy = SiteGoose.platform&.proxy %>
+<script async src="<%= proxy&.script_url %>" data-siteid="..." data-domain="example.com"
+        data-collect="<%= proxy&.collect_url %>"></script>
+```
+
+- The path comes from your secret, so it isn't in the page and isn't a name
+  any blocker lists. Pick your own with `proxy: { prefix: "..." }`.
+- Tracker files are fetched once and then held in memory; if we can't be
+  reached, the copy already held is served rather than nothing, and a file
+  that couldn't be fetched isn't asked for again for 30 seconds.
+- These run on your app's request threads, so they wait at most 1 second to
+  connect and 2 to answer, and after three failures in a row the collector
+  is left alone for 30 seconds (beacons get a 502 straight away; the
+  tracker counts them as lost). A collector that stops answering can't use
+  up Puma's threads.
+- The visitor's address goes on as `X-Forwarded-For` and cookies never leave
+  your server.
+- Beacons are answered before the rate limit, the browser check, the
+  crawler count and the timing, so your own analytics traffic doesn't
+  appear as pages of your site. A denied or banned address gets a 403 here
+  too.
+- Switch it off with `proxy: false`, or in the dashboard (Site settings →
+  Server). Then load the tracker from us as before.
+
+## Shutting down
+
+What's waiting is sent at exit on its own, within 5 seconds in all (a
+container's or PM2's grace period is longer): no send starts after that,
+none is retried, and errors that weren't sent wait in their file for the
+next start. Sidekiq's shutdown flush has the same deadline.
+`SiteGoose.flush` sends it
+now (a short-lived script, a serverless function before returning);
+`platform.close` also stops the background threads.
+
+## Tests
+
+```bash
+bundle install
+ruby -Ilib -Itest -e 'Dir["test/*_test.rb"].each { |f| require_relative f }'
+```

data/lib/sitegoose/analytics.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Analytics module: what only the server sees for sure (payments, sign-ups,
+# plan changes), next to the browser tracker's visits. Not pageviews: the
+# tracker counts those, and counting them here too would count them twice.
+#
+# - track(): events, batched to POST /events/server-events in the background.
+#   Each gets an event_uid, so a retried batch can be told apart from new events.
+# - identify(): links the browser's visit to your user ID (/events/identify).
+# - lead(): adds or updates a lead (/events/lead).
+# identify() and lead() wait for the answer (up to 5 seconds).
+
+require "securerandom"
+
+module SiteGoose
+  class Analytics
+    BATCH = 100
+    QUEUE_MAX = 1000
+    FLUSH_EVERY = 2
+    RETRY_EVERY = 15
+
+    attr_reader :queue
+
+    def initialize(core, **_)
+      @core = core
+      @queue = []
+      @lock = Mutex.new
+      @job = core.valid? ? Periodic.new(FLUSH_EVERY) { flush ? FLUSH_EVERY : RETRY_EVERY } : nil
+      Forking.register(self)
+    end
+
+    def after_fork_in_child
+      @lock = Mutex.new
+      @queue = []
+    end
+
+    # name: the event's name; fields: value, numeric_value, currency, url,
+    # event_label, variant, id, timestamp, event_uid, transaction_id, coupon
+    # (expresscollect/docs/server-events.md). Returns the event_uid, or ""
+    # when not queued.
+    def track(name, fields = nil, session_id = "")
+      return "" unless name.is_a?(String) && !name.empty? && @core.on?("analytics")
+
+      fields = (fields || {}).each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      event = { "timestamp" => SiteGoose.iso_now, "session_id" => session_id.to_s }
+      event.merge!(fields)
+      event["event_name"] = name[0, 100]
+      event["event_uid"] = fields["event_uid"].to_s.empty? ? SecureRandom.uuid : fields["event_uid"].to_s
+      event["numeric_value"] = event["numeric_value"].to_s if event["numeric_value"].is_a?(Numeric)
+      full = @lock.synchronize do
+        if @queue.size >= QUEUE_MAX
+          @core.log("analytics", "queue full, event dropped")
+          return ""
+        end
+        @queue << event
+        @queue.size >= BATCH
+      end
+      @job&.run_now if full
+      event["event_uid"]
+    end
+
+    # Sends what's waiting; false when some of it must be tried again.
+    def flush
+      waiting = @lock.synchronize do
+        taken = @queue
+        @queue = []
+        taken
+      end
+      ok = true
+      waiting.each_slice(BATCH) do |batch|
+        res = @core.request("analytics", "/events/server-events", body: { "events" => batch })
+        if res.nil? || res.status == 429 || res.status >= 500
+          ok = false
+          @lock.synchronize { @queue = (batch + @queue).first(QUEUE_MAX) }
+        elsif !res.ok?
+          @core.log("analytics", "events refused:", res.body.to_s[0, 300])
+        end
+      end
+      ok
+    end
+
+    # Links the visit to your user ID. true when stored.
+    def identify(user_id, session_id = "")
+      return false if user_id.to_s.empty? || session_id.to_s.empty? || !@core.on?("analytics")
+
+      res = @core.request("analytics", "/events/identify", body: { "user_id" => user_id.to_s, "session_id" => session_id.to_s })
+      res ? res.ok? : false
+    end
+
+    # fields: email or phone, and name, status, tags, note, deal fields...
+    # Returns {"status", "lead_id"}, or nil.
+    def lead(fields, session_id = "")
+      return nil unless @core.on?("analytics")
+
+      body = { "session_id" => session_id.to_s }
+      (fields || {}).each { |k, v| body[k.to_s] = v }
+      res = @core.request("analytics", "/events/lead", body: body)
+      return nil if res.nil?
+
+      unless res.ok?
+        @core.log("analytics", "lead refused:", res.body.to_s[0, 300])
+        return nil
+      end
+      res.json
+    end
+
+    def close
+      @job&.stop
+      Forking.unregister(self)
+      flush
+    end
+  end
+end

data/lib/sitegoose/challenge.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+# The browser check (rule `challenge`, sdk/protocols/firewall.md under "Flood
+# protection"): a GET or HEAD that asks for a page, from an address with no
+# valid pass, gets a small page instead of the site. Its script sets the pass
+# cookie and reloads, which a script that doesn't run JavaScript never does.
+#
+# The pass is <day>.<first 32 hex digits of HMAC-SHA256(key, "<day>|<who>")>,
+# key = HMAC-SHA256 of "sg-challenge-v1" keyed with the site secret, so any of
+# the site's servers accepts a pass another one handed out. It counts for its
+# own day and the next. sdk/protocols/challenge-cases.json holds the cases
+# every client runs; backend/scripts/challenge-cases.mjs is the reference.
+
+require "openssl"
+require "securerandom"
+require "ipaddr"
+require "json"
+
+module SiteGoose
+  module Challenge
+    COOKIE = "__sg_pass"
+    MAX_AGE = 86_400
+    LABEL = "sg-challenge-v1"
+    PASS = /\A(\d{1,10})\.([0-9a-f]{32})\z/.freeze
+
+    module_function
+
+    # The key every pass is signed with, from the site secret.
+    def pass_key(secret)
+      OpenSSL::HMAC.digest("SHA256", secret.to_s, LABEL)
+    end
+
+    # What a pass is bound to: the IPv4 address (an IPv4-mapped IPv6 address
+    # as IPv4), or an IPv6 address's /64 as four groups of four lower-case hex
+    # digits. "*" for the agent's nginx (a package never accepts it); nil for
+    # anything that isn't an address.
+    def who(ip)
+      text = ip.to_s.strip
+      return "*" if text == "*"
+
+      key = IP.key(text)
+      return nil if key.nil?
+
+      if key >> 32 == 0xFFFF
+        v4 = key & 0xFFFFFFFF
+        return [24, 16, 8, 0].map { |shift| (v4 >> shift) & 0xFF }.join(".")
+      end
+      format("%032x", key).scan(/.{4}/).first(4).join(":")
+    end
+
+    # Whole days since 1970-01-01 UTC.
+    def day_of(now = nil)
+      ((now || Time.now.to_f).to_f / 86_400).floor
+    end
+
+    def sign(key, day, bound)
+      OpenSSL::HMAC.hexdigest("SHA256", key, "#{day}|#{bound}")[0, 32]
+    end
+
+    # Today's pass for this address, or "" when it isn't one.
+    def make_pass(key, ip, now = nil)
+      bound = who(ip)
+      return "" if bound.nil?
+
+      day = day_of(now)
+      "#{day}.#{sign(key, day, bound)}"
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      if OpenSSL.respond_to?(:fixed_length_secure_compare)
+        OpenSSL.fixed_length_secure_compare(a, b)
+      else
+        diff = 0
+        a.bytes.zip(b.bytes) { |x, y| diff |= x ^ y }
+        diff.zero?
+      end
+    end
+
+    # True when value is this address's pass for today or yesterday.
+    def valid?(key, ip, value, now = nil)
+      match = PASS.match(value.to_s)
+      bound = who(ip)
+      return false if match.nil? || bound.nil? || bound == "*"
+
+      day = match[1].to_i
+      today = day_of(now)
+      return false unless day == today || day == today - 1
+
+      secure_compare(match[2], sign(key, day, bound))
+    end
+
+    # Every value the Cookie header carries under name (a browser can send
+    # two, from different paths); at most four, like the Node client. Two
+    # Cookie headers arrive joined by ", " (Puma), so that separates cookies
+    # too: our values ("<day>.<hex>", the preview code) never hold one, and a
+    # piece of someone else's value split off this way names no cookie of ours.
+    def cookie_values(cookie_header, name = COOKIE)
+      found = []
+      cookie_header.to_s.split(/;|, /).each do |part|
+        k, sep, value = part.strip.partition("=")
+        next if sep.empty? || k.strip != name
+
+        found << value.strip.delete_prefix('"').delete_suffix('"')
+        break if found.size == 4
+      end
+      found
+    end
+
+    def pass?(key, ip, cookie_header, now = nil)
+      cookie_values(cookie_header).any? { |value| valid?(key, ip, value, now) }
+    end
+
+    # The rules' skip prefixes, lower-cased.
+    def compile_skip(entries)
+      Array(entries).select { |p| p.is_a?(String) && !p.empty? }.map(&:downcase).first(200)
+    end
+
+    # Conditions 1 to 3: a GET or HEAD, whose Accept asks for text/html, for a
+    # path (lower-cased, no query string) under none of skip.
+    def asks_for_page?(method, target, accept, skip)
+      return false unless %w[GET HEAD].include?(method.to_s.upcase)
+      return false unless accept.to_s.downcase.include?("text/html")
+
+      path = target.to_s.split("?", 2)[0].to_s.split("#", 2)[0].to_s.downcase
+      skip.none? { |prefix| path.start_with?(prefix) }
+    end
+
+    PAGE = <<~HTML
+      <!doctype html>
+      <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+      <meta name="robots" content="noindex"><title>Just a moment</title>
+      <style nonce="%<nonce>s">body{font:16px/1.5 system-ui,sans-serif;margin:0;display:flex;min-height:100vh;align-items:center;justify-content:center;color:#222;background:#fafafa}main{max-width:28rem;padding:2rem;text-align:center}</style>
+      </head><body><main><p id="m">Checking your browser before you continue&hellip;</p>
+      <noscript><p>Please turn on JavaScript to continue to this site.</p></noscript></main>
+      <script nonce="%<nonce>s">%<script>s</script>
+      </body></html>
+    HTML
+
+    # The page's script: sets the pass and reloads, but only when reading the
+    # cookie back shows it was set (with cookies off it says so instead of
+    # reloading forever), and at most three times a minute, counted in
+    # sessionStorage (an address that changes on every request would otherwise
+    # never get a pass that holds and reload for ever), or in a __sg_tries
+    # cookie lasting a minute where storage is blocked or full. Secure only
+    # when the browser is on https: it knows, where the server behind a proxy
+    # can only be told. The same script as the Node, PHP and Python clients'.
+    def script(value)
+      "(function(){var n=#{COOKIE.to_json},v=#{value.to_json},m=document.getElementById(\"m\")," \
+        "s=location.protocol===\"https:\";" \
+        "document.cookie=n+\"=\"+v+\"; Max-Age=#{MAX_AGE}; Path=/; SameSite=Lax\"+(s?\"; Secure\":\"\");" \
+        "if((\" \"+document.cookie+\";\").indexOf(\" \"+n+\"=\"+v+\";\")<0){m.textContent=\"Please allow cookies for this site, then reload the page.\";return;}" \
+        "var k=\"__sg_tries\",r=0,t;" \
+        "try{t=JSON.parse(sessionStorage.getItem(k)||\"[]\").filter(function(x){return Date.now()-x<60000;});r=t.length;if(r<3){t.push(Date.now());sessionStorage.setItem(k,JSON.stringify(t));}}" \
+        "catch(e){t=/(?:^|; )__sg_tries=([0-9]+)/.exec(document.cookie);r=t?+t[1]:0;if(r<3)document.cookie=k+\"=\"+(r+1)+\"; Max-Age=60; Path=/; SameSite=Lax\"+(s?\"; Secure\":\"\");}" \
+        "if(r>=3){m.textContent=\"This page couldn't be opened because your connection's address keeps changing. Please try again in a minute.\";return;}" \
+        "location.reload();})();"
+    end
+
+    # [503, headers, body] for the check page: its own Content-Security-Policy
+    # with a fresh nonce for its one script, and no body for a HEAD.
+    def page(key, ip, method, now = nil)
+      nonce = SecureRandom.urlsafe_base64(18)
+      headers = {
+        "content-type" => "text/html; charset=utf-8",
+        "cache-control" => "no-store",
+        "x-robots-tag" => "noindex",
+        "content-security-policy" => "default-src 'none'; script-src 'nonce-#{nonce}'; style-src 'nonce-#{nonce}'; " \
+                                     "base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+      }
+      return [503, headers, ""] if method.to_s.upcase == "HEAD"
+
+      [503, headers, format(PAGE, nonce: nonce, script: script(make_pass(key, ip, now)))]
+    end
+  end
+end