samagotchi 0.108.0 → 0.109.0

data/lib/samagotchi/web/participants_admin.rb

@@ -57,10 +57,10 @@ module Samagotchi
 
         issued = Participants.invite(@grants, session_id: id, name: body["name"], kind: (body["kind"] || "human").to_s,
                                               ttl: ttl, cap: cap, state_dir: default_state_dir)
-        link = participant_link(req, id, issued.token)
+        link = participant_link(req, id, issued.token, expires_at: issued.grant.expires_at)
         warning = ReviewStart.share_warning(Session.load(id, state_dir: default_state_dir))
         json_response(201, { participant: issued.grant.public_h(@grants.now), token: issued.token,
-                             link: link, lan: !@lan.nil?, qr_svg: QR.svg(link), warning: warning })
+                             link: link, lan: !@lan.nil? || !@public_url.nil?, qr_svg: QR.svg(link), warning: warning })
       rescue Grants::Invalid => e
         error_response(400, "invalid_participant", e.message)
       end
@@ -115,10 +115,17 @@ module Samagotchi
         error_response(400, "invalid_participant", e.message)
       end
 
-      # The link a participant opens: this chi web's LAN address when it has
-      # one (the owner may be asking on loopback), else the Host asked; the
-      # token traded for the cookie, the session in the fragment.
-      def participant_link(req, id, token)
+      # The link a participant opens: web.public_url's with a one-time code
+      # for the token in the fragment (LinkCodes, until the grant expires;
+      # the page trades it, POST /api/token); else this chi web's LAN address
+      # when it has one (the owner may be asking on loopback), else the Host
+      # asked; the token traded for the cookie, the session in the fragment.
+      def participant_link(req, id, token, expires_at: nil)
+        if @public_url
+          ttl = expires_at ? [Time.iso8601(expires_at) - @grants.now, 1].max : LinkCodes::OWNER_TTL
+          return @public_url.link(@link_codes.issue(kind: :grant, token: token, ttl: ttl), "s=#{id}")
+        end
+
         host = req.get_header("HTTP_HOST").to_s
         port = host[/:(\d+)\z/, 1] || req.port.to_s
         name = @lan ? @lan[:ip] : host.sub(/:\d*\z/, "")

data/lib/samagotchi/web/proxy_gate.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "link_codes"
+require_relative "principal"
+require_relative "public_url"
+require_relative "../log"
+require_relative "../proxy_trace"
+
+module Samagotchi
+  module Web
+    # chi web behind an auth proxy (web.public_url), mixed into App. With a
+    # PublicUrl every request needs a token (this machine's too: a proxy
+    # with no trace and a rewritten Host looks local). A request is
+    # *proxied* when it carries a proxy trace (ProxyTrace: X-Forwarded-*,
+    # Forwarded, X-Real-IP, a known identity header…), the configured
+    # identity header, or the public Host. A proxied request:
+    # - is the owner with the owner token, and, when web.proxy.identity_header
+    #   is set, only if that header is one clean value equal to
+    #   web.proxy.owner (D-a: identity AND token);
+    # - is a participant with a live grant's token (a grant bound to an
+    #   identity only for that identity, and only proxied);
+    # - else nil: the gate's 401, its reason in the detail (only the
+    #   requester's own identity) and the log.
+    # The identity header is refused when repeated, with a comma, empty, or
+    # sent under two names or with an underscore: WEBrick folds
+    # X_Forwarded_Email into the same Rack key as X-Forwarded-Email, the
+    # last one winning, so the gate reads the raw names (RawHeaderNames,
+    # installed by Server). See docs/configuration.md "Behind an auth proxy".
+    module ProxyGate
+      # The header names a request came with, as WEBrick read them
+      # (lower-cased, "_" kept), in the Rack env. Prepended to
+      # WEBrick::HTTPRequest by Server.
+      module RawHeaderNames
+        def meta_vars
+          super.merge(RAW_NAMES_ENV => header.keys)
+        end
+      end
+
+      RAW_NAMES_ENV = "samagotchi.raw_header_names"
+      # Why the gate refused a proxied request, for the 401's detail.
+      REFUSED_ENV = "samagotchi.proxy_refused"
+      # The token cookie on a proxied (https) request: Secure, Path=/, no
+      # Domain (other host names under the domain, a pod's other ports, don't
+      # get it). Cookies aren't port-scoped: a server on the same host name
+      # and another port does.
+      SECURE_COOKIE = "__Host-chi_token"
+
+      private
+
+      def init_proxy_gate(public_url, token)
+        @public_url = public_url
+        @public_token = token
+        @link_codes = LinkCodes.for_grants(@grants.path)
+        @proxy_hint_mutex = Mutex.new
+        @proxy_hint_logged = false
+      end
+
+      def proxied?(req)
+        return false unless @public_url
+
+        env = req.env
+        return true if @public_url.host?(env["HTTP_HOST"])
+        return true if @public_url.identity_env && env.key?(@public_url.identity_env)
+
+        names = env[RAW_NAMES_ENV] || env.keys.filter_map { |key| ProxyTrace.env_name(key) }
+        names.any? { |name| ProxyTrace.header?(name) }
+      end
+
+      # [:ok, email] | [:none, nil] | [:bad, reason]: the configured identity
+      # header of a proxied request; :none without one configured.
+      def proxy_identity(req)
+        env_key = @public_url.identity_env
+        return [:none, nil] unless env_key
+
+        raw = req.env[RAW_NAMES_ENV]
+        return [:bad, "the server gave no raw header names to check the identity header against"] unless raw
+
+        names = raw.select { |name| PublicUrl.env_key(name) == env_key }.uniq
+        return [:bad, "identity header sent under #{names.size} names (#{names.join(", ")})"] if names.size > 1
+        return [:bad, "identity header sent with an underscore (#{names.first})"] if names.first&.include?("_")
+
+        value = req.env[env_key]
+        return [:none, nil] if value.nil?
+        return [:bad, "identity header not among the raw header names"] if names.empty?
+
+        value = value.strip
+        return [:bad, "identity header empty"] if value.empty?
+        return [:bad, "identity header repeated or with a comma"] if value.include?(",")
+
+        [:ok, value.downcase]
+      end
+
+      # The principal of a proxied request, or nil (the reason in the env).
+      def proxied_principal(req, given)
+        state, identity = proxy_identity(req)
+        return proxy_refuse(req, identity) if state == :bad
+
+        notice_identity_headers(req) if state == :none
+        shown = identity || "(none)"
+        if owner_token?(given)
+          return Principal::OWNER if @public_url.identity_env.nil?
+          return Principal::OWNER if @public_url.owner && identity == @public_url.owner
+
+          return proxy_refuse(req, "owner token with identity #{shown}#{identity_hint(req)}")
+        end
+        grant_tokens = given.select { |value| Grants.token?(value) }
+        return proxy_refuse(req, "no token (identity #{shown})") if grant_tokens.empty?
+
+        participant_principal(req, grant_tokens, identity: identity, proxied: true)
+      end
+
+      # chi's own probe of a chi web behind a proxy (InfoProbe: a second chi
+      # web, chi share, chi update) sends no token: GET /api/info from this
+      # machine, not through the proxy, with no token at all, gets the
+      # fields it checks (nothing secret), so no probe ever hands the token
+      # to whatever listens on the port.
+      def probe_info?(req)
+        return false unless @public_url && req.get? && req.path_info == "/api/info"
+        return false unless App::LOOPBACK_PEERS.include?(req.get_header("REMOTE_ADDR").to_s) && !proxied?(req)
+
+        req.get_header("HTTP_AUTHORIZATION").nil? && req.get_header("HTTP_COOKIE").nil?
+      end
+
+      def probe_info
+        json_response(200, { app: "chi-web", version: Samagotchi::VERSION, pid: Process.pid, features: App::INFO_FEATURES,
+                             lan: @lan && @lan[:ip] })
+      end
+
+      def proxy_refuse(req, reason)
+        req.env[REFUSED_ENV] = reason
+        nil
+      end
+
+      # The known identity headers (ProxyTrace::IDENTITY_HEADERS) a proxied
+      # request carries other than the configured one.
+      def other_identity_headers(req)
+        ProxyTrace::IDENTITY_HEADERS.select do |name|
+          key = PublicUrl.env_key(name)
+          key != @public_url.identity_env && req.env.key?(key)
+        end
+      end
+
+      def identity_hint(req)
+        return "" if @public_url.identity_env.nil? || req.env.key?(@public_url.identity_env)
+
+        others = other_identity_headers(req)
+        others.empty? ? "" : "; the proxy sends #{others.join(", ")}, not #{@public_url.identity_header}"
+      end
+
+      # Once per start: a proxied request without the configured identity
+      # header (or with none configured) but with a header a known setup
+      # puts the identity in. A wrong header locks the owner out, and one the
+      # proxy doesn't replace is a client-chosen string: the line says which.
+      def notice_identity_headers(req)
+        return if @proxy_hint_logged
+
+        others = other_identity_headers(req)
+        return if others.empty?
+        return unless @proxy_hint_mutex.synchronize { !@proxy_hint_logged && (@proxy_hint_logged = true) }
+
+        if @public_url.identity_env
+          Log.warn(:web, "proxy_identity_header", configured: @public_url.identity_header, sent: others.join(","),
+                                                  echo: "Warning: chi web: the proxy sends #{others.join(", ")}, not " \
+                                                        "web.proxy.identity_header #{@public_url.identity_header}")
+        else
+          Log.info(:web, "proxy_identity_header", configured: "none", sent: others.join(","),
+                                                  echo: "chi web: the proxy sends #{others.join(", ")}; with " \
+                                                        "web.proxy.identity_header and web.proxy.owner it is checked " \
+                                                        "next to the token (only a header the proxy replaces)")
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/web/public/app.js

@@ -24,7 +24,10 @@ import {
   addContext,
   renderText,
   getWorkingSet,
+  onAuthLost,
 } from "./data.js";
+import { authProbe, createAuthLost } from "./auth_lost.js";
+import { REPLACE_SESSION_TEXT, fragmentCode, tradeFragmentCode } from "./token_fragment.js";
 import { createContextChips } from "./context_chips.js";
 import { createLlmContextControl } from "./llm_context_chip.js";
 import { createParticipantsControl } from "./participants_panel.js";
@@ -96,6 +99,16 @@ import { createSessionActions } from "./session_actions.js";
 import { createRename } from "./session_rename.js";
 import { createSendTurn } from "./send_turn.js";
 
+// A link's #code= (behind an auth proxy): traded for the cookie before
+// anything else runs; the page reloads without it.
+// This page has a session already: the trade would replace it (a link
+// someone sent to swap this browser's session for theirs), so ask first.
+if (fragmentCode(globalThis.location?.hash)
+    && await tradeFragmentCode({ ask: () => globalThis.confirm(REPLACE_SESSION_TEXT) })) await new Promise(() => {});
+// Signed out (the proxy's session or chi's token): a banner, or one reload.
+const authLost = createAuthLost();
+onAuthLost(authLost);
+
 const $ = (s) => document.querySelector(s);
 const topStripEl = $("#topStrip");
 const allListEl = $("#allList");
@@ -449,9 +462,20 @@ function openSessionEvents() {
       eventsControl = null;
       refresh();
     },
+    // The browser gave up after frames: signed out (the proxy's sign-in
+    // page answered the reconnect), or chi web went away for a while.
+    onClosed: () => {
+      eventsControl = null;
+      authProbe().then((state) => {
+        if (state === "lost") authLost("events");
+        else setTimeout(openSessionEvents, EVENTS_REOPEN_MS);
+      });
+    },
   });
 }
 
+const EVENTS_REOPEN_MS = 3000;
+
 // Which chi serves this page now and which is the newest installed (the
 // events snapshot, and `chi` frames when that changes). A toast says when
 // chi web was upgraded while this tab stayed open (offering the reload,

data/lib/samagotchi/web/public/auth_lost.js

@@ -0,0 +1,76 @@
+// Signed out: the auth proxy's session (Okta…) or chi's token is gone. An
+// /api answer says so in one of these ways: a 401 (chi's unauthorized, or
+// the proxy's own 401 {} for Accept: application/json), a fetch that was
+// redirected or came back as HTML (a sign-in page), or, from the probe,
+// a redirect fetch can't follow (real IdPs send no CORS: a TypeError, so
+// the probe asks with redirect: "manual"). The page then says so in a
+// banner with Reload, and reloads by itself at most once a minute (the
+// proxy's sign-in brings the user back), never when it can't keep the time.
+
+export const AUTH_RELOAD_KEY = "chi.authReloadAt";
+export const AUTH_RELOAD_MS = 60_000;
+
+// Whether a fetch Response says the sign-in is gone.
+export function lostAnswer(res) {
+  if (!res) return false;
+  if (res.status === 401 || res.redirected || res.type === "opaqueredirect") return true;
+  const type = res.headers?.get?.("content-type") || "";
+  return type.includes("text/html");
+}
+
+// "lost" | "ok" | "down" (chi web unreachable: no banner, the page's own
+// retries go on).
+export async function authProbe(fetchImpl = globalThis.fetch) {
+  try {
+    const res = await fetchImpl("/api/info", {
+      credentials: "same-origin", redirect: "manual", headers: { Accept: "application/json" },
+    });
+    return lostAnswer(res) ? "lost" : "ok";
+  } catch (_) {
+    return "down";
+  }
+}
+
+export const AUTH_LOST_TEXT = "Signed out (the proxy's sign-in or chi's token ended).";
+
+// The page's authLost(reason): once, a banner (doc) and, unless one ran in
+// the last minute, a reload. storage: sessionStorage (may be missing or throw).
+export function createAuthLost({
+  doc = globalThis.document, storage = () => globalThis.sessionStorage, reload = () => globalThis.location.reload(),
+  now = () => Date.now(), log = (reason) => console.warn("chi: signed out", reason),
+} = {}) {
+  let shown = false;
+  return function authLost(reason) {
+    if (shown) return;
+    shown = true;
+    log(reason);
+    // The reload only when its stamp can be kept: without storage (a
+    // private window) a page that keeps losing its sign-in would reload
+    // forever, so it gets the banner.
+    let due = false;
+    try {
+      due = now() - (Number(storage().getItem(AUTH_RELOAD_KEY)) || 0) >= AUTH_RELOAD_MS;
+      if (due) storage().setItem(AUTH_RELOAD_KEY, String(now()));
+    } catch (_) {
+      due = false;
+    }
+    if (due) {
+      reload();
+      return;
+    }
+    const bar = doc.createElement("div");
+    bar.id = "authLost";
+    bar.setAttribute("role", "alert");
+    bar.style.cssText = "position:fixed;top:0;left:0;right:0;z-index:10000;padding:8px 16px;font-size:14px;"
+      + "color:var(--warn-text);background:var(--warn-bg);border-bottom:1px solid var(--warn-border);"
+      + "display:flex;gap:12px;align-items:center;justify-content:center";
+    const text = doc.createElement("span");
+    text.textContent = AUTH_LOST_TEXT;
+    const button = doc.createElement("button");
+    button.type = "button";
+    button.textContent = "Reload";
+    button.addEventListener("click", () => reload());
+    bar.append(text, button);
+    doc.body.append(bar);
+  };
+}

data/lib/samagotchi/web/public/data.js

@@ -1,9 +1,27 @@
+import { authProbe, lostAnswer } from "./auth_lost.js";
+
+// What the page does when an answer says the sign-in is gone (auth_lost.js;
+// app.js sets it). A no-op until then.
+let authLostHandler = () => {};
+export function onAuthLost(handler) {
+  authLostHandler = typeof handler === "function" ? handler : () => {};
+}
+
+// Accept: application/json: an auth proxy whose session ended answers 401
+// {} (oauth2-proxy) rather than a redirect to its sign-in. A fetch that
+// fails outright asks authProbe whether that was a sign-in redirect.
 export function api(path, opts = {}) {
   const { fetchImpl = globalThis.fetch } = opts;
   return fetchImpl(path, {
-    headers: { "Content-Type": "application/json", ...(opts.headers || {}) },
     ...opts,
+    headers: { "Content-Type": "application/json", Accept: "application/json", ...(opts.headers || {}) },
+  }).catch((error) => {
+    if (error instanceof TypeError) {
+      authProbe(fetchImpl).then((state) => { if (state === "lost") authLostHandler(`fetch ${path}`); }, () => {});
+    }
+    throw error;
   }).then(async (r) => {
+    if (lostAnswer(r)) authLostHandler(`${r.status} ${path}`);
     const j = await r.json().catch(() => ({}));
     if (!r.ok) {
       // The server's words as they are: what the page shows the user. The
@@ -279,10 +297,12 @@ export function openStream(id, fromSeq, handlers = {}, opts = {}) {
 // only when the browser gave up before the first frame (a chi web without
 // a hub answers 503, a bad ?dir 400): the caller falls back to fetching.
 // Later errors are left to EventSource's own reconnect, and a reconnect
-// always starts with a fresh snapshot.
+// always starts with a fresh snapshot, unless the browser gave up for good
+// (readyState CLOSED: an auth proxy answered the reconnect with its sign-in
+// page): onClosed then, and the caller probes and opens it again.
 // @return {{close(): void}}
 export function openEvents(handlers = {}, opts = {}) {
-  const { EventSourceImpl = globalThis.EventSource, dir, onError } = opts;
+  const { EventSourceImpl = globalThis.EventSource, dir, onError, onClosed } = opts;
   const url = dir ? `/api/events?dir=${encodeURIComponent(dir)}` : "/api/events";
   const es = new EventSourceImpl(url);
   let frameReceived = false;
@@ -290,10 +310,14 @@ export function openEvents(handlers = {}, opts = {}) {
   let live = true;
   es.onerror = () => {
     // readyState 2 (CLOSED): the browser won't retry on its own.
-    if (frameReceived || !live || es.readyState !== 2) return;
+    if (!live || es.readyState !== 2) return;
     live = false;
     try { es.close(); } catch (_) {}
-    if (typeof onError === "function") onError();
+    if (!frameReceived) {
+      if (typeof onError === "function") onError();
+    } else if (typeof onClosed === "function") {
+      onClosed();
+    }
   };
   return {
     close() {

data/lib/samagotchi/web/public/participant.js

@@ -9,6 +9,16 @@ import {
   authorColor, participantAuthor, authorLabel, toolLine, toolsSummary, refusalText, dequeueText, endedText, streamURL, reloads, endsLiveTurn, liveFrom, applyLive,
   liveText, withToolSteps, pickSubject, subjectBody, subjectsKey, narrowView, retryDelay, retries,
 } from "./participant_model.js";
+import { createAuthLost, lostAnswer } from "./auth_lost.js";
+import { REPLACE_SESSION_TEXT, fragmentCode, tradeFragmentCode } from "./token_fragment.js";
+
+// A link's #code= opened in a browser that already has a cookie: traded
+// first, the page reloads without it.
+// This page has a session already: the trade would replace it (a link
+// someone sent to swap this browser's session for theirs), so ask first.
+if (fragmentCode(globalThis.location?.hash)
+    && await tradeFragmentCode({ ask: () => globalThis.confirm(REPLACE_SESSION_TEXT) })) await new Promise(() => {});
+const authLost = createAuthLost();
 
 const $ = (id) => document.getElementById(id);
 const body = document.body.dataset;
@@ -47,17 +57,21 @@ function el(tag, cls, text) {
 }
 
 // A request's answer; a network failure is status 0 (the page says it
-// can't reach the session), never a throw.
+// can't reach the session), never a throw. A 401 with chi's words is the
+// link ending (revoked, expired); one without (an auth proxy's own 401 {}),
+// a redirect or an HTML answer is the sign-in ending (auth_lost.js).
 async function api(path, options = {}) {
   let res;
   try {
-    res = await fetch(path, { credentials: "same-origin", ...options });
+    res = await fetch(path, { credentials: "same-origin", ...options,
+                              headers: { Accept: "application/json", ...(options.headers || {}) } });
   } catch {
     return { status: 0, ok: false, body: null };
   }
   let json = null;
   try { json = await res.json(); } catch { json = null; }
-  if (res.status === 401) showEnded(json);
+  if (lostAnswer(res) && !(res.status === 401 && json?.error)) authLost(`${res.status} ${path}`);
+  else if (res.status === 401) showEnded(json);
   return { status: res.status, ok: res.ok, body: json };
 }
 

data/lib/samagotchi/web/public/token_fragment.js

@@ -0,0 +1,57 @@
+// A link's one-time code in its fragment (https://<public url>/#code=…&s=ID,
+// what chi web makes behind an auth proxy: never a token, since a fragment
+// outlives the sign-in redirects and stays in the browser's history). The
+// page posts it to POST /api/token, which uses it up and sets the cookie,
+// then loads itself again without it. The 401 page runs it (chi web serves
+// this file without the token); the owner's and participant's pages do on
+// load, asking first, since the trade replaces the browser's session. Plain
+// module, no imports.
+
+// {code, rest}: the fragment's code and what else it says ("s=ID"), or
+// null without one.
+export function fragmentCode(hash) {
+  const params = new URLSearchParams(String(hash || "").replace(/^#/, ""));
+  const code = params.get("code");
+  if (!code) return null;
+  params.delete("code");
+  return { code, rest: params.toString() };
+}
+
+export const REPLACE_SESSION_TEXT = "This link signs this browser in as its holder, in place of the session it has now. Open it?";
+
+// Trades the fragment's code, if there is one: the URL loses it at once
+// (history.replaceState), the page reloads once the cookie is set. ask():
+// whether to go ahead (a page that already has a session); declined, the
+// code is dropped unused. Resolves true when it reloads, false when there
+// was nothing to trade, it was declined, or the code was refused
+// (onRefused gets the server's words).
+export async function tradeFragmentCode({
+  loc = globalThis.location, hist = globalThis.history, fetchImpl = globalThis.fetch, onRefused = () => {},
+  ask = () => true,
+} = {}) {
+  const found = fragmentCode(loc?.hash);
+  if (!found) return false;
+  try {
+    hist.replaceState(null, "", `${loc.pathname}${loc.search}${found.rest ? `#${found.rest}` : ""}`);
+  } catch (_) {}
+  if (!ask()) return false;
+  let res;
+  try {
+    res = await fetchImpl("/api/token", {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ code: found.code }),
+    });
+  } catch (_) {
+    onRefused("chi web can't be reached: reload to try again.");
+    return false;
+  }
+  if (res.ok) {
+    loc.reload();
+    return true;
+  }
+  const body = await res.json().catch(() => ({}));
+  onRefused(body.detail || `That link was refused (HTTP ${res.status}): it works once, and an owner's link for 10 minutes.`);
+  return false;
+}

data/lib/samagotchi/web/public_url.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../redacted_inspect"
+
+module Samagotchi
+  module Web
+    # chi web behind an auth proxy (web.public_url, docs/configuration.md
+    # "Behind an auth proxy"): the https origin people open, the request
+    # header the proxy puts the signed-in user's email in (nil: none is
+    # trusted, the chi token alone decides) and the owner's email. Set, it
+    # turns on proxied mode (Web::ProxyGate): every request needs a token.
+    PublicUrl = Data.define(:origin, :host, :identity_header, :owner) do
+      # The Rack env key of the identity header (HTTP_X_FORWARDED_EMAIL),
+      # nil without one.
+      def identity_env = identity_header && PublicUrl.env_key(identity_header)
+
+      # Whether a Host header names the public host: any case, a trailing
+      # dot, and an explicit :443 for a 443 origin are the same host.
+      def host?(header)
+        name, port = header.to_s.downcase.match(/\A(.*?)(?::(\d+))?\z/).captures
+        name = name.delete_suffix(".")
+        port = nil if port == "443"
+        host == (port ? "#{name}:#{port}" : name)
+      end
+
+      # The header's name as people write it, or "none".
+      def identity_label = identity_header || "none"
+
+      # https://host[:port]/#code=CODE[&FRAGMENT]: a link with a one-time
+      # code (LinkCodes) in its fragment, never a token: a fragment outlives
+      # the sign-in redirects and stays in the browser's history.
+      def link(code, fragment = nil) = "#{origin}/##{["code=#{code}", fragment].compact.join("&")}"
+    end
+
+    class PublicUrl
+      class Invalid < StandardError; end
+
+      # An HTTP header name (RFC 9110 token characters chi accepts).
+      HEADER_NAME = /\A[A-Za-z0-9][A-Za-z0-9-]*\z/
+
+      # @return [PublicUrl, nil] nil when +url+ is unset
+      # @raise [Invalid] a url that isn't an https origin, a bad header name,
+      #   or an owner without an identity header to check it against
+      def self.from_config(url:, identity_header: nil, owner: nil)
+        text = url.to_s.strip
+        return nil if text.empty?
+
+        origin, host = parse_origin(text)
+        header = identity_header.to_s.strip
+        header = nil if header.empty? || header.casecmp?("none")
+        if header && !HEADER_NAME.match?(header)
+          raise Invalid, "web.proxy.identity_header must be a header name (letters, digits and -), not #{header}"
+        end
+
+        owner = owner.to_s.strip.downcase
+        owner = nil if owner.empty?
+        if owner && header.nil?
+          raise Invalid, "web.proxy.owner needs web.proxy.identity_header (the header the proxy puts #{owner} in); " \
+                         "without one only the chi token decides, so leave owner unset"
+        end
+
+        new(origin: origin, host: host, identity_header: header, owner: owner)
+      end
+
+      def self.parse_origin(text)
+        uri = URI.parse(text)
+        bare = uri.path.to_s.empty? || uri.path == "/"
+        unless uri.scheme&.downcase == "https" && uri.host && !uri.host.empty? && bare && uri.query.nil? &&
+               uri.fragment.nil? && uri.userinfo.nil?
+          raise Invalid, invalid_url(text)
+        end
+
+        name = uri.host.downcase
+        host = uri.port == 443 ? name : "#{name}:#{uri.port}"
+        ["https://#{host}", host]
+      rescue URI::InvalidURIError
+        raise Invalid, invalid_url(text)
+      end
+
+      def self.invalid_url(text) = "web.public_url must be an https origin (https://host or https://host:port), not #{text}"
+
+      # The Rack env key WEBrick makes of a header name.
+      def self.env_key(name) = "HTTP_#{name.upcase.tr("-", "_")}"
+    end
+  end
+end