samagotchi 0.108.0 → 0.110.0

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/tokens.css

@@ -3,10 +3,10 @@
   --glass-bg:color-mix(in srgb,var(--bg-panel) 70%,transparent);--glass-border:rgba(255,255,255,.08);--glass-highlight:rgba(255,255,255,.05);--glass-shadow:0 8px 30px rgba(0,0,0,.35);
   --diff-add-bg:rgba(63,185,80,.14);--diff-add-text:#aff5b4;--diff-del-bg:rgba(248,81,73,.14);--diff-del-text:#ffc1bc;
   --code-text:#c9d1d9;--code-keyword:#ff7b72;--code-string:#a5d6ff;--code-comment:#8b949e;--code-constant:#79c0ff;--code-func:#d2a8ff;--code-type:#ffa657;
-  --card-hover-border:rgba(255,255,255,.14);--on-solid:#fff;--on-warn:#fff;--text-hover:#fff;--badge-bg:rgba(255,255,255,.08);--badge-ring:rgba(255,255,255,.18);--shadow-strong:rgba(0,0,0,.5);--backdrop:rgba(0,0,0,.85);--toast-shadow:0 6px 24px rgba(0,0,0,.25);--ws-stale-opacity:.4;--ws-rule:var(--border-strong);--ws-muted:var(--text-3);--ws-faint:var(--text-muted);--ws-act-border:#444c56;--author-1:#79c0ff;--author-2:#d2a8ff;--author-3:#7ee787;--author-4:#ffa657;--author-5:#ff7b72;--author-6:#f2cc60;--author-owner:var(--text-3)}
+  --card-hover-border:rgba(255,255,255,.14);--on-solid:#fff;--on-warn:#fff;--text-hover:#fff;--badge-bg:rgba(255,255,255,.08);--badge-ring:rgba(255,255,255,.18);--shadow-strong:rgba(0,0,0,.5);--backdrop:rgba(0,0,0,.85);--toast-shadow:0 6px 24px rgba(0,0,0,.25);--ws-stale-opacity:.4;--ws-rule:var(--border-strong);--ws-muted:var(--text-3);--ws-faint:var(--text-muted);--ws-act-border:#444c56;--author-1:#79c0ff;--author-2:#d2a8ff;--author-3:#7ee787;--author-4:#ffa657;--author-5:#ff7b72;--author-6:#f2cc60;--author-owner:var(--text-3);--time-gap:var(--text-faint)}
 /* Light palette: follows the system setting. :not([data-theme="dark"]) leaves room for a later in-page toggle (data-theme on <html>); there is none yet. Each palette sets color-scheme, so native radios, inputs and scrollbars follow it. */
 @media (prefers-color-scheme:light){:root:not([data-theme="dark"]){color-scheme:light;--bg:#f5f6f8;--bg-panel:#ffffff;--bg-inset:#f1f3f6;--bg-raised:#e8ebf0;--bg-hover:#eceff4;--border:#dde1e7;--border-strong:#c3c9d2;--text:#1f2328;--text-bright:#0d1117;--text-2:#2f363d;--text-3:#475160;--text-muted:#57606a;--text-faint:#636c76;--accent:#0b5cd5;--accent-strong:#0550ae;--accent-bg:#e2ecfd;--accent-ring:rgba(11,92,213,.2);--primary:#1f6feb;--ok:#1a7f37;--ok-text:#116329;--ok-bg:#dafbe1;--warn:#9a6700;--warn-text:#7d4e00;--warn-bright:#875c00;--warn-bg:#fff6cc;--warn-border:#d4a72c;--danger:#cf222e;--danger-bg:#cf222e;--danger-text:#a40e26;--danger-bg-dim:#ffebe9;--think:#8250df;--think-text:#6639ba;--accent-border:#b8cef5;--pick-border:#0969da;
   --glass-border:rgba(31,35,40,.10);--glass-highlight:rgba(255,255,255,.7);--glass-shadow:0 8px 30px rgba(31,35,40,.10);
   --diff-add-bg:rgba(26,127,55,.12);--diff-add-text:#116329;--diff-del-bg:rgba(207,34,46,.10);--diff-del-text:#82071e;
   --code-text:#1f2328;--code-keyword:#cf222e;--code-string:#0a3069;--code-comment:#57606a;--code-constant:#0550ae;--code-func:#8250df;--code-type:#953800;
-  --card-hover-border:rgba(31,35,40,.18);--on-solid:#fff;--on-warn:#1f2328;--text-hover:#0d1117;--badge-bg:rgba(31,35,40,.06);--badge-ring:rgba(31,35,40,.15);--shadow-strong:rgba(31,35,40,.18);--backdrop:rgba(13,17,23,.85);--toast-shadow:0 6px 24px rgba(31,35,40,.14);--ws-stale-opacity:.55;--ws-rule:var(--border);--ws-muted:var(--text-muted);--ws-faint:var(--text-faint);--ws-act-border:var(--border-strong);--author-1:#0550ae;--author-2:#8250df;--author-3:#116329;--author-4:#953800;--author-5:#a40e26;--author-6:#7d4e00;--author-owner:var(--text-3)}}
+  --card-hover-border:rgba(31,35,40,.18);--on-solid:#fff;--on-warn:#1f2328;--text-hover:#0d1117;--badge-bg:rgba(31,35,40,.06);--badge-ring:rgba(31,35,40,.15);--shadow-strong:rgba(31,35,40,.18);--backdrop:rgba(13,17,23,.85);--toast-shadow:0 6px 24px rgba(31,35,40,.14);--ws-stale-opacity:.55;--ws-rule:var(--border);--ws-muted:var(--text-muted);--ws-faint:var(--text-faint);--ws-act-border:var(--border-strong);--author-1:#0550ae;--author-2:#8250df;--author-3:#116329;--author-4:#953800;--author-5:#a40e26;--author-6:#7d4e00;--author-owner:var(--text-3);--time-gap:var(--text-faint)}}

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

@@ -340,7 +340,9 @@ export function snapshotEvents({ current_turn: turn = null, queued = [], queued_
     const cutAfter = turn.cut_after != null ? { cut_after: turn.cut_after } : {};
     // A participant's turn names them (TurnAccumulator keeps author, author_name).
     const author = turn.author ? { author: turn.author, ...(turn.author_name ? { author_name: turn.author_name } : {}) } : {};
-    events.push(withImages({ type: "turn_started", prompt: turn.prompt, origin: turn.origin, continue: !!turn.continue, started_at, ...cutAfter, ...author }, turn.images));
+    // Its wall time (TurnAccumulator keeps turn_started's at): the gap divider before it.
+    const at = typeof turn.at === "string" ? { at: turn.at } : {};
+    events.push(withImages({ type: "turn_started", prompt: turn.prompt, origin: turn.origin, continue: !!turn.continue, started_at, ...at, ...cutAfter, ...author }, turn.images));
     let textIteration = null; // a text bubble is open for this iteration
     const closeText = () => {
       if (textIteration !== null) events.push({ type: "generation_completed" });

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

@@ -8,7 +8,7 @@ import { html, nothing, render } from "./vendor/lit-html.js";
 import { commandBlockTemplate, rowHover } from "./command_view.js";
 import { copySource } from "./copy.js";
 import { activityDiffTemplate } from "./diff_view.js";
-import { clip, steerSender } from "./format.js";
+import { clip, fullTime, steerSender } from "./format.js";
 import { rowTitleRef } from "./refs.js";
 import { readLinesTemplate } from "./read_view.js";
 import { handedOverId } from "./task_stop.js";
@@ -219,9 +219,15 @@ export function shellCommandMessage(content) {
 // A `!cmd`'s history bubble: the same markup the live page draws for a
 // command (app.js's drawCommandBubble): the line, the output in a
 // pre.command-output.
-export function commandBubbleTemplate({ line, text }) {
+export function commandBubbleTemplate({ line, text, at = null }) {
   const body = text ? html`<pre class="command-output">${text}</pre>` : nothing;
-  return html`<div class="bubble command"><div class="command-line">${line}</div>${body}</div>`;
+  return html`<div class="bubble command" title=${timeTitle(at)}><div class="command-line">${line}</div>${body}</div>`;
+}
+
+// A bubble's hover: when it happened (its message's `at`, MessageTime), in
+// full local time; no title when unknown.
+export function timeTitle(at) {
+  return fullTime(at) || nothing;
 }
 
 // A user message's body: runs of `>` lines become <blockquote>s, the rest
@@ -257,9 +263,10 @@ export function answerBubbleTemplate(message, { cls = "", at = null } = {}) {
   const klass = `bubble output${cls}${rendered ? " markdown" : ""}`;
   const answerAt = at ?? nothing;
   const source = rendered || user ? copySource(message) : nothing;
-  if (rendered) return html`<div class=${klass} data-answer-at=${answerAt} data-copy-source=${source} .innerHTML=${message.html}></div>`;
-  if (user) return html`<div class=${klass} data-answer-at=${answerAt} data-copy-source=${source}>${userBodyTemplate(message.content)}</div>`;
-  return html`<div class=${klass} data-answer-at=${answerAt} data-copy-source=${source} .textContent=${String(message?.content ?? "")}></div>`;
+  const title = timeTitle(message?.at);
+  if (rendered) return html`<div class=${klass} title=${title} data-answer-at=${answerAt} data-copy-source=${source} .innerHTML=${message.html}></div>`;
+  if (user) return html`<div class=${klass} title=${title} data-answer-at=${answerAt} data-copy-source=${source}>${userBodyTemplate(message.content)}</div>`;
+  return html`<div class=${klass} title=${title} data-answer-at=${answerAt} data-copy-source=${source} .textContent=${String(message?.content ?? "")}></div>`;
 }
 
 // A context note's bubble (background the user or another session pushed
@@ -267,7 +274,7 @@ export function answerBubbleTemplate(message, { cls = "", at = null } = {}) {
 // text.
 export function noteBubbleTemplate(note) {
   const from = note?.label ? `note from ${note.label}` : "note";
-  return html`<div class="bubble note"><div class="note-line">${from}</div><div class="note-text">${note?.content ?? ""}</div></div>`;
+  return html`<div class="bubble note" title=${timeTitle(note?.at)}><div class="note-line">${from}</div><div class="note-text">${note?.content ?? ""}</div></div>`;
 }
 
 // A plugin's steer (a nudge put into the running turn): one line that
@@ -295,7 +302,7 @@ export function userBubbleTemplate(message, { label = null, state = null, step =
   const from = author
     ? html`<span class="origin-label author-badge" title=${authorBadgeTitle(author.name)} data-unnamed=${author.unnamed ? "1" : nothing}>${authorBadgeText(author.name)}</span>`
     : label ? html`<span class="origin-label">${label}</span>` : nothing;
-  return html`<div class=${`bubble user${named ? ` ${named}` : ""}${author ? " by-participant" : ""}`} style=${author ? `--author-color:${author.color}` : nothing} data-author=${author?.author || nothing} data-user-state=${named || nothing} data-step=${step ? Number(step) : nothing} data-copy-source=${copySource({ ...message, role: "user" })} data-user-content=${key !== null ? key : nothing} data-own=${own ? "1" : nothing} data-enqueued-id=${enqueuedId || nothing} data-delivery=${delivery || nothing}>${from}<div class="user-message">${userBodyTemplate(message?.content)}${thumbs}</div>${stateBadgeTemplate(named, delivery)}</div>`;
+  return html`<div class=${`bubble user${named ? ` ${named}` : ""}${author ? " by-participant" : ""}`} title=${timeTitle(message?.at)} style=${author ? `--author-color:${author.color}` : nothing} data-author=${author?.author || nothing} data-user-state=${named || nothing} data-step=${step ? Number(step) : nothing} data-copy-source=${copySource({ ...message, role: "user" })} data-user-content=${key !== null ? key : nothing} data-own=${own ? "1" : nothing} data-enqueued-id=${enqueuedId || nothing} data-delivery=${delivery || nothing}>${from}<div class="user-message">${userBodyTemplate(message?.content)}${thumbs}</div>${stateBadgeTemplate(named, delivery)}</div>`;
 }
 
 // The notice of a turn that ended with no answer (the server's

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

@@ -42,6 +42,7 @@ import { createHold } from "./hold.js";
 import { linkedLine } from "./notice_links.js";
 import { taskCommand, taskStopButton } from "./task_stop.js";
 import { footprintTemplate, groupItems, stampHistory } from "./working_set_view.js";
+import { groupGaps, timeGapTemplate } from "./time_gaps.js";
 
 // ---- The templates: one step, its thinking, its label ----
 
@@ -847,7 +848,7 @@ function failedLineTemplate(record) {
 // web.working_set, never the turn view's): each block stamped with its
 // turn's ordinal and its rows with theirs (working_set_view.js), and the
 // turn's footprint line after it.
-export function turnHistoryNodes(items, timing, { thumbs, workingSet = false }) {
+export function turnHistoryNodes(items, timing, { thumbs, workingSet = false, now = Date.now() }) {
   const timingTemplate = (group) => {
     const record = group.record;
     // Numbered by its place in the turn records, as live (a failed turn
@@ -868,7 +869,7 @@ export function turnHistoryNodes(items, timing, { thumbs, workingSet = false })
   // as its command bubble, as live does — not as a user bubble.
   const userTemplate = (m, opts = {}) => {
     const shell = shellCommandMessage(m?.content);
-    if (shell) return commandBubbleTemplate(shell);
+    if (shell) return commandBubbleTemplate({ ...shell, at: m?.at });
     return userBubbleTemplate(m, { label: sourceLabel(m?.source), thumbs: thumbs(m.images), author: authorBadge(m?.author, m?.author_name), ...opts });
   };
   // The first text after a delegate report merged mid-turn, unless it is
@@ -886,7 +887,11 @@ export function turnHistoryNodes(items, timing, { thumbs, workingSet = false })
   const outlines = [];
   const blockTurns = [];
   let turnOrdinal = -1;
-  for (const group of turnGroups(items, timing)) {
+  const groups = turnGroups(items, timing);
+  // A quiet stretch before a group: its divider first (time_gaps.js).
+  const gaps = groupGaps(groups, items, now);
+  for (const [k, group] of groups.entries()) {
+    if (gaps[k]) parts.push(timeGapTemplate(gaps[k]));
     if (group.kind === "note") { parts.push(noteBubbleTemplate(items[group.i])); continue; }
     if (group.kind === "steer") { parts.push(steerTemplate(group.i, true)); continue; }
     if (group.kind === "answer") { parts.push(answerTemplate(group.answer, nothing)); continue; }

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

data/lib/samagotchi/web/running.rb

@@ -4,18 +4,23 @@ require "json"
 require "fileutils"
 require_relative "../atomic_file"
 require_relative "../session"
+require_relative "info_probe"
+require_relative "public_url"
 
 module Samagotchi
   module Web
     # Where this machine's chi web listens: $XDG_STATE_HOME/samagotchi/web.json
-    # ({pid, port}), written once its port is bound and removed when it
+    # ({pid, port}, and public_url when it runs with one: config's or
+    # --tunnel's), written once its port is bound and removed when it
     # stops (by that process only). A command that names chi web in what it
     # prints (chi share's link) reads the port here before config's
     # web.port, which a chi web started with --port or another config
     # doesn't follow. The file is a hint: a chi web killed hard leaves it,
-    # so a reader probes the port (InfoProbe) before trusting it.
+    # so a reader probes the port (InfoProbe) before trusting it. One slot:
+    # a second chi web on another port takes it over.
     module Running
       FILE = "web.json"
+      PROBE_TIMEOUT = 1.0
 
       module_function
 
@@ -24,9 +29,10 @@ module Samagotchi
       end
 
       # @return [String] +path+
-      def record(port:, path: self.path, pid: Process.pid)
+      # @param public_url [String, nil] the https origin it runs behind
+      def record(port:, path: self.path, pid: Process.pid, public_url: nil)
         FileUtils.mkdir_p(File.dirname(path))
-        AtomicFile.write(path, JSON.generate({ pid: pid, port: port }))
+        AtomicFile.write(path, JSON.generate({ pid: pid, port: port, public_url: public_url }.compact))
       end
 
       # Removes the file when this process wrote it (a second chi web's
@@ -41,6 +47,35 @@ module Samagotchi
         value.is_a?(Integer) && value.positive? ? value : nil
       end
 
+      # The public_url the running chi web recorded (a --tunnel's, which no
+      # config has), for a link that names it: only while the chi web that
+      # answers /api/info on the recorded port is the process that wrote the
+      # file (its pid), and only an https origin. A record left by a chi web
+      # killed hard, with a reused pid or another chi web (another state dir)
+      # on that port, is nil. The origin is this file's, never the probe's.
+      # @param probe [#call] (port) → InfoProbe's answer
+      # @return [PublicUrl, nil]
+      def live_public_url(path: self.path, probe: ->(port) { InfoProbe.call("127.0.0.1", port, timeout: PROBE_TIMEOUT) })
+        data = read(path) or return nil
+        pid, port, url = data.values_at("pid", "port", "public_url")
+        return nil unless pid.is_a?(Integer) && pid.positive? && port.is_a?(Integer) && port.positive? && url.is_a?(String)
+        return nil unless alive?(pid)
+
+        info = probe.call(port)
+        return nil unless info.is_a?(Hash) && info["pid"] == pid
+
+        PublicUrl.from_config(url: url)
+      rescue PublicUrl::Invalid
+        nil
+      end
+
+      def alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+
       def read(path)
         data = JSON.parse(File.read(path))
         data.is_a?(Hash) ? data : nil

data/lib/samagotchi/web/server.rb

@@ -9,10 +9,14 @@ require "webrick"
 require_relative "app"
 require_relative "info_probe"
 require_relative "lan"
+require_relative "link_codes"
+require_relative "proxy_gate"
+require_relative "public_url"
 require_relative "qr"
 require_relative "running"
 require_relative "session_hub"
 require_relative "token"
+require_relative "tunnel"
 require_relative "../config"
 require_relative "../project_scope"
 require_relative "../log"
@@ -58,24 +62,34 @@ module Samagotchi
       # How long `chi web` waits for a server already on its port to answer.
       PROBE_TIMEOUT = 0.3
 
+      # The raw header names next to Rack's env (ProxyGate's identity check):
+      # chi web is the only WEBrick server chi runs.
+      WEBrick::HTTPRequest.prepend(ProxyGate::RawHeaderNames) unless WEBrick::HTTPRequest < ProxyGate::RawHeaderNames
+
       # `chi web`: one server serves every project, the scope is in the page
       # URL. If a chi web already runs on the port, print (and with --open,
       # open) its page for +dir+ and leave it be; else start one.
       # @param scope ["project", "all"] "all": the plain page, every session
       # @param new_token [Boolean] replace the LAN access token first
       #   (--new-token): a running server takes the new one at once
+      # @param tunnel [String, nil] --tunnel's provider (Tunnel.for): this
+      #   run's public_url is the tunnel's, never config's, and the tunnel is
+      #   on while the server runs
       # @return [Integer] the exit status
       def self.launch(port: nil, host: nil, scope: "project", dir: Dir.pwd, open_browser: false, markdown: false,
                       view: Config::BY_KEY["web.view"].default, annotate_presets: Config::BY_KEY["web.annotate_presets"].default,
                       editor: Config::BY_KEY["web.editor"].default, new_token: false,
-                      working_set: Config::BY_KEY["web.working_set"].default)
+                      working_set: Config::BY_KEY["web.working_set"].default, tunnel: nil)
         rotate_token if new_token
+        public_url = public_url_setting unless tunnel
         setting = host_setting(host)
         lan = Lan.wanted?(setting) ? Lan.choose(setting) : nil
         host = resolve_host(setting)
         port = resolve_port(port)
         url = scope_url(host, port, dir: dir, scope: scope)
         found = probe(host, port)
+        raise Tunnel::AlreadyRunning, port if tunnel && found.is_a?(Hash)
+
         case found
         when Hash
           if lan && !found["lan"]
@@ -85,6 +99,8 @@ module Samagotchi
           end
           puts "chi web already runs on port #{port} (pid #{found["pid"]}): #{url}"
           puts running_lan_lines(found["lan"], port) if found["lan"]
+          running_public = public_url || Running.live_public_url(probe: ->(at) { probe(host, at) })
+          puts running_public_lines(running_public) if running_public
           puts lan_off_line(setting) if new_token && !found["lan"]
           open_url(url) if open_browser
           0
@@ -92,20 +108,30 @@ module Samagotchi
           warn in_use_message(port)
           1
         else
-          if new_token && !lan
+          if tunnel
+            provider = Tunnel.for(tunnel)
+            plan = provider.prepare(port: port, config_owner: Samagotchi::Config.get("web.proxy.owner"),
+                                    config_public_url: Samagotchi::Config.get("web.public_url"),
+                                    config_identity_header: Samagotchi::Config.get("web.proxy.identity_header"))
+            public_url = plan.public_url
+          end
+          if new_token && !lan && !public_url
             puts lan_off_line(setting)
             return 0
           end
           # The participants' grants: never served from a store others can read.
           Grants.check_permissions!(Grants.path)
-          if start(port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, view: view,
-                   annotate_presets: annotate_presets, editor: editor, lan: lan, working_set: working_set)
-            0
-          else
-            1
-          end
+          options = { port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, view: view,
+                      annotate_presets: annotate_presets, editor: editor, lan: lan, working_set: working_set,
+                      public_url: public_url }
+          started = if plan
+                      with_tunnel(provider, plan) { start(**options, public_notes: provider.start_lines(plan)) }
+                    else
+                      start(**options)
+                    end
+          started ? 0 : 1
         end
-      rescue Lan::Error, Grants::Insecure => e
+      rescue Lan::Error, Grants::Insecure, PublicUrl::Invalid, Tunnel::Refused => e
         warn "Error: #{e.message}"
         1
       rescue Interrupt
@@ -115,16 +141,52 @@ module Samagotchi
         CLI::Exit::INTERRUPTED
       end
 
+      # The tunnel on while the block runs (the server), off after it
+      # whatever ends it (Ctrl-C, SIGTERM, SIGHUP, a port taken), and only
+      # once #up succeeded: a refusal before it, or a failed #up, turns off
+      # nothing (a live tunnel of another chi web stays).
+      def self.with_tunnel(provider, plan)
+        provider.up(plan)
+        upped = true
+        yield
+      ensure
+        tunnel_down(provider, plan) if upped
+      end
+
+      # The tunnel's teardown, before any line (a hung-up terminal can't
+      # write): a failure is one warning line, never a crash or another exit
+      # status, and a second Ctrl-C during it only cuts it short.
+      def self.tunnel_down(provider, plan)
+        line = begin
+          provider.down_line(plan, provider.down(plan))
+        rescue Tunnel::Refused, SignalException => e
+          provider.down_warning(plan, e)
+        end
+        say(line) if line
+      end
+
+      # A line that may meet a terminal gone (SIGHUP): never an error.
+      def self.say(line)
+        puts line
+        $stdout.flush
+      rescue IOError, SystemCallError
+        nil
+      end
+
       # @param hub [SessionHub, nil] the session projection the page streams
       #   from; built over the app's state dir unless given
       # @param lan [Lan::Choice, nil] also listen on this LAN address, where
       #   every request but this machine's needs the access token
       # @param token_path [String] the LAN access token's file
+      # @param public_url [PublicUrl, nil] behind an auth proxy
+      #   (web.public_url, or --tunnel's): every request needs the access token
+      # @param public_notes [Array<String>] lines after the proxied link's
+      #   (the tunnel's)
       # @return [Boolean] false when the port was taken (said so on stderr)
       def self.start(port: nil, host: nil, url: nil, open_browser: false, state_dir: nil, manager: nil, markdown: false,
                      view: Config::BY_KEY["web.view"].default, annotate_presets: Config::BY_KEY["web.annotate_presets"].default, hub: nil, lan: nil,
                      editor: Config::BY_KEY["web.editor"].default, token_path: Token.path,
-                     working_set: Config::BY_KEY["web.working_set"].default)
+                     working_set: Config::BY_KEY["web.working_set"].default, public_url: nil, public_notes: [])
         config_restart_unsubscribe = ConfigFile.watch_restart_settings!(process: :web) do |message|
           Samagotchi::Log.warn(:config, "restart_required", echo: "Warning: config: #{message}")
         end
@@ -133,14 +195,18 @@ module Samagotchi
         url ||= "http://#{url_host(host)}:#{port}/"
 
         hub ||= SessionHub.new(state_dir: state_dir || Session.default_state_dir, manager: manager || SessionManager)
-        if lan
-          Token.load_or_create(token_path)
-          lan_option = { ip: lan.ip, token: Token::Source.new(token_path) }
-        end
+        Token.load_or_create(token_path) if lan || public_url
+        lan_option = { ip: lan.ip, token: Token::Source.new(token_path) } if lan
+        public_token = Token::Source.new(token_path) if public_url
         app = App.new(manager: manager, state_dir: state_dir, markdown: markdown, view: view,
-                      annotate_presets: annotate_presets, editor: editor, hub: hub, lan: lan_option, working_set: working_set)
+                      annotate_presets: annotate_presets, editor: editor, hub: hub, lan: lan_option, working_set: working_set,
+                      public_url: public_url, public_token: public_token)
         Samagotchi::Log.info(:web, "start", url: "http://#{host}:#{port}", version: Samagotchi::VERSION)
         Samagotchi::Log.info(:web, "lan", ip: lan.ip, interface: lan.interface) if lan
+        if public_url
+          Samagotchi::Log.info(:web, "public_url", origin: public_url.origin, identity_header: public_url.identity_label,
+                                                   owner: public_url.owner ? "set" : "none")
+        end
         # Subscribed before the first scan, which makes the first check.
         hub.subscribe(method(:on_hub_event))
         hub.start
@@ -148,15 +214,20 @@ module Samagotchi
         # the in-use line instead.
         running_path = Running.path(state_dir: state_dir)
         started = lambda do
-          record_running(running_path, port)
+          record_running(running_path, port, public_url)
           puts "Chi Web on #{url} (public: #{File.expand_path("public", __dir__)})"
           puts lan_lines(ip: lan.ip, port: port, token: Token.read(token_path), others: lan.others, public: lan.public) if lan
+          if public_url
+            puts public_lines(public_url, token: Token.read(token_path), codes: owner_codes(state_dir), notes: public_notes)
+          end
           puts "Press Ctrl-C to stop."
           $stdout.flush # a log file isn't line-buffered
           if open_browser
+            # With web.public_url the page opens through the proxy.
+            open_target = public_url ? public_url.link(owner_codes(state_dir).issue(kind: :owner, ttl: LinkCodes::OWNER_TTL)) : url
             Thread.new do
               sleep 0.8
-              open_url(url)
+              open_url(open_target)
             end
           end
         end
@@ -184,11 +255,11 @@ module Samagotchi
 
       class LanListenError < StandardError; end
 
-      # Where this chi web listens, for chi share's link (Web::Running); a
-      # write that fails leaves the server running and the readers on
-      # web.port.
-      def self.record_running(path, port)
-        Running.record(port: port, path: path)
+      # Where this chi web listens, and its public_url (config's or the
+      # tunnel's), for chi share's link (Web::Running); a write that fails
+      # leaves the server running and the readers on web.port and config.
+      def self.record_running(path, port, public_url = nil)
+        Running.record(port: port, path: path, public_url: public_url&.origin)
       rescue SystemCallError => e
         Samagotchi::Log.warn(:web, "running_record_failed", error: e.class.name)
       end
@@ -224,6 +295,51 @@ module Samagotchi
         raise LanListenError, e.message
       end
 
+      # web.public_url as Server runs it, nil when unset.
+      # @raise [PublicUrl::Invalid]
+      def self.public_url_setting
+        PublicUrl.from_config(url: Samagotchi::Config.get("web.public_url"),
+                              identity_header: Samagotchi::Config.get("web.proxy.identity_header"),
+                              owner: Samagotchi::Config.get("web.proxy.owner"))
+      end
+
+      # What web.public_url adds to the start lines: the proxied link (a
+      # one-time code in its fragment), who the owner is, +notes+ (the
+      # tunnel's) and, at a terminal, the link's QR code. On this machine the
+      # page opens through the proxy too; a direct request takes the token
+      # as Authorization: Bearer only (no cookie for 127.0.0.1, which every
+      # local port would get).
+      def self.public_lines(public_url, token:, codes: owner_codes, notes: [], qr: $stdout.tty?)
+        unless token
+          return ["Proxied: #{public_url.origin}/ (no access token: its file is gone; chi web --new-token makes one)",
+                  *notes]
+        end
+
+        who = if public_url.identity_header.nil? then "token only, no identity header"
+              elsif public_url.owner then "owner #{public_url.owner} by #{public_url.identity_header}, and the token"
+              else "nobody is the owner by identity: web.proxy.owner is unset"
+              end
+        link = public_url.link(codes.issue(kind: :owner, ttl: LinkCodes::OWNER_TTL))
+        lines = ["Proxied: #{link}   ← opens chi web as you once, within #{LinkCodes::OWNER_TTL / 60} minutes " \
+                 "(chi web again prints a new one)",
+                 "         (#{who}; on this machine the page opens through the proxy too)", *notes]
+        lines.concat(QR.lines(link)) if qr
+        lines
+      end
+
+      # The owner's one-time link codes, next to the grants.
+      def self.owner_codes(state_dir = nil) = LinkCodes.for_grants(Grants.path(state_dir: state_dir))
+
+      # A second chi web, when this machine's config has web.public_url (or
+      # the running chi web recorded one: Running.live_public_url): the link
+      # from there and the token file, never from what answered on the port.
+      def self.running_public_lines(public_url, token_path: Token.path, codes: owner_codes)
+        return ["Proxied: #{public_url.origin}/"] unless Token.read(token_path)
+
+        ["Proxied: #{public_url.link(codes.issue(kind: :owner, ttl: LinkCodes::OWNER_TTL))}   (once, within " \
+         "#{LinkCodes::OWNER_TTL / 60} minutes)"]
+      end
+
       def self.host_setting(host)
         (host || Samagotchi::Config.get("web.host")).to_s.strip
       end