tosijs-ui 1.16.25 → 1.16.26

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.16.26
+
+### Tunnel
+
+- **Global keys: one link opens every workspace, and survives restarts.** The preview host can
+  hold two machine-wide keys: `PREVIEW_EDIT_TOKEN` (new, optional) opens every workspace for
+  editing, and `PREVIEW_TOKEN` (the static previews' invite secret) opens them read-only.
+  Put them in `/etc/caddy/preview.env` on the box (re-run `tosijs-caddy-install`) and in
+  `~/local-secrets/tosijs-preview.env` on each machine running a dev server. Visit the box's
+  root once with `?t=<key>`: Caddy sets a cookie across the preview domain (24 hours for the
+  edit key), and the root page lists every workspace that is up and whether you can edit or
+  only view it. Opening one starts a session there on the first page load, and after a
+  dev-server restart a reload is all it takes. Keys must be at least 24 letters, digits, `-` or
+  `_`, because the box compares them with no rate limit; the installer refuses a short edit
+  key, and a dev server ignores one and says so. A workspace can refuse them with
+  `tunnel.globalKeys: false`, or with `'view'` let either key browse and neither edit; any other
+  value refuses both and says so. The eight-letter `--link` codes are unchanged.
+- **The view key is your preview invite.** Everyone you have given a static-preview link can,
+  by default, also read every workspace that accepts the view key while it is up, even with
+  `requireToken`. Set `tunnel.globalKeys: false` on a project that should stay yours, or rotate
+  the invite secret.
+- **Rotating a key** means editing both files, re-running the installer and restarting the dev
+  servers: a session a key already opened lasts up to 24 hours and is not re-checked against
+  the key until its server restarts.
+- **`tosijs-tunnel` refreshes the box's root page** when it registers a workspace, so a newly
+  tunnelled project appears in the list straight away. The box's root page escapes project
+  names, which it inserted into the page as they were.
+- The edit key opens a `globalKeys: 'view'` workspace read-only, as the view key does.
+
+### Security
+
+- **Source and data writes over the tunnel must come from the workspace's own origin**
+  (affected: 1.9.0 to 1.16.25). They relied on the session cookie's `SameSite=Lax`, but every
+  host under the preview domain is the same *site*, so a page on another project's preview (its
+  live examples included) could POST to your workspace with your session attached. The haltija
+  bridge's component and socket over the tunnel check the same (affected: 1.12.2 to 1.16.25).
+- **A read-only session can no longer attach the haltija agent bridge** (affected: 1.15.0 to
+  1.16.25, with `haltijaDev: 'tunnel'`). A share link's session passed the bridge's gate, which
+  asked only whether the session was valid.
+- **A redirect after redeeming a link stays on the workspace.** A link at a path starting `//`
+  redirected to another host.
+
 ## 1.16.25
 
 ### Dev server

package/bin/caddy-install.ts

@@ -24,9 +24,11 @@ Three deliberate properties:
   anything else through Caddy, that is destructive — so the dry run prints a diff against
   the live file and you get to look at it before `--go`.
 
-  THE SECRET NEVER LEAVES THE BOX. Substitution happens remotely, reading
-  `/etc/caddy/preview.env`. `PREVIEW_TOKEN` is never transmitted, never appears in argv on
-  this machine, and is redacted out of the diff before it is printed.
+  THIS COMMAND NEVER CARRIES THE SECRETS. Substitution happens remotely, reading
+  `/etc/caddy/preview.env`. `PREVIEW_TOKEN` and `PREVIEW_EDIT_TOKEN` are never transmitted by
+  it, never appear in argv on this machine, and are redacted out of the diff before it is
+  printed. (Global keys are a separate choice: to use them, you copy the same values into
+  ~/local-secrets on the machines that run dev servers.)
 
   VALIDATE BEFORE SWAP. `caddy fmt` then `caddy validate` run against a scratch file; the
   live config is replaced by an atomic `mv` only once it is known to parse. A rejected
@@ -121,14 +123,28 @@ set -a; . /etc/caddy/preview.env; set +a
 : "\${ACME_EMAIL:?set ACME_EMAIL in /etc/caddy/preview.env}"
 : "\${PREVIEW_DOMAIN:?set PREVIEW_DOMAIN in /etc/caddy/preview.env}"
 
+# The global EDIT key is optional. Unset, the template still needs a value, so it gets one
+# nobody knows and the edit cookie opens nothing. Set, it is compared by Caddy with no rate
+# limit in front, so it must be long, and the cookie match needs a plain alphabet.
+if [ -z "\${PREVIEW_EDIT_TOKEN:-}" ]; then
+  PREVIEW_EDIT_TOKEN="unset-$(od -An -tx1 -N24 /dev/urandom | tr -d ' \\n')"
+elif ! printf '%s' "$PREVIEW_EDIT_TOKEN" | grep -qE '^[A-Za-z0-9_-]{24,}$'; then
+  echo "PREVIEW_EDIT_TOKEN must be at least 24 letters, digits, - or _ — refusing to install." >&2
+  exit 1
+elif [ "$PREVIEW_EDIT_TOKEN" = "$PREVIEW_TOKEN" ]; then
+  echo "PREVIEW_EDIT_TOKEN equals PREVIEW_TOKEN, so every preview link could edit — refusing to install." >&2
+  exit 1
+fi
+
 sed -e "s|__PREVIEW_TOKEN__|$PREVIEW_TOKEN|g" \\
+    -e "s|__PREVIEW_EDIT_TOKEN__|$PREVIEW_EDIT_TOKEN|g" \\
     -e "s|{{ACME_EMAIL}}|$ACME_EMAIL|g" \\
     -e "s|{{PREVIEW_DOMAIN}}|$PREVIEW_DOMAIN|g" \\
     /etc/caddy/Caddyfile.tpl > /etc/caddy/Caddyfile.new
 
-if grep -qE '\\{\\{|__PREVIEW_TOKEN__' /etc/caddy/Caddyfile.new; then
+if grep -qE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new; then
   echo "Unsubstituted placeholders remain — refusing to install:" >&2
-  grep -nE '\\{\\{|__PREVIEW_TOKEN__' /etc/caddy/Caddyfile.new >&2
+  grep -nE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new >&2
   rm -f /etc/caddy/Caddyfile.new
   exit 1
 fi
@@ -150,7 +166,8 @@ else
   echo "--- would change /etc/caddy/Caddyfile (token redacted) ---"
   if [ -f /etc/caddy/Caddyfile ]; then
     diff -u /etc/caddy/Caddyfile /etc/caddy/Caddyfile.new \\
-      | sed "s|$PREVIEW_TOKEN|***REDACTED***|g" || true
+      | sed -e "s|$PREVIEW_TOKEN|***REDACTED***|g" \\
+            -e "s|$PREVIEW_EDIT_TOKEN|***REDACTED***|g" || true
   else
     echo "(no existing /etc/caddy/Caddyfile — this would create it)"
   fi

package/bin/deploy-preview.ts

@@ -31,6 +31,7 @@ import { existsSync } from 'fs'
 import {
   previewRootFor,
   registerCaddyFragment,
+  refreshHostIndex,
   resolvePreviewHost,
   parseArgv,
 } from './resolve-site-config.ts'
@@ -205,51 +206,10 @@ async function registerSite(): Promise<boolean> {
   return ok
 }
 
-/** Refresh the host's index so this deploy shows up immediately. */
-async function refreshIndex(): Promise<void> {
-  const remote = `/tmp/tosi-build-index-${process.pid}.sh`
-  /*
-  Resolve the script against THIS PACKAGE, not the adopter's cwd.
-
-  `deploy/` is in `files`, so the asset ships at node_modules/tosijs-ui/deploy/ — only
-  the resolution was wrong, which meant every adopter's scp failed, the failure was
-  swallowed by a bare `return`, and the deploy still printed "✅ Deployed". Exactly the
-  #37 class of bug, one cycle later: a package asset located relative to whoever called us.
-  */
-  const script = `${import.meta.dir}/../deploy/build-index.sh`
-  const put = await $`scp -q ${script} ${`${host}:${remote}`}`.nothrow().quiet()
-  if (put.exitCode !== 0) {
-    // Loudly: the deploy itself succeeded, so this must not read as total failure —
-    // but a silently stale index is how you conclude a deploy did not land.
-    console.warn(
-      `⚠️  Could not refresh the host index (scp of ${script} failed).\n` +
-        `   The deploy landed; the listing at the root will be stale until the next one.\n` +
-        `   ${put.stderr.toString().trim().slice(0, 200)}`
-    )
-    return
-  }
-  const run = await $`ssh ${host} bash ${remote}`.nothrow().quiet()
-  await $`ssh ${host} rm -f ${remote}`.nothrow().quiet()
-  // build-index.sh is `set -euo pipefail`; a non-root user on a root-owned tree dies at
-  // mkdir. Discarding this exit code meant the deploy printed ✅ over a failed index.
-  if (run.exitCode !== 0) {
-    console.warn(
-      `⚠️  the host index was not refreshed (exit ${run.exitCode}). The deploy landed;\n` +
-        `   the listing at the root will be stale until the next successful one.\n` +
-        `   ${(run.stderr.toString() || run.stdout.toString())
-          .trim()
-          .slice(0, 200)}`
-    )
-    return
-  }
-  const out = run.stdout.toString().trim()
-  if (out) console.log(`   ${out}`)
-}
-
 let routed = true
 if (go) {
   routed = await registerSite()
-  await refreshIndex()
+  await refreshHostIndex(host!)
 }
 
 /*

package/bin/resolve-site-config.ts

@@ -19,7 +19,8 @@ silently picking up a parent directory's config would mean publishing the wrong
 and "it found something" is not the same as "it found yours".
 */
 
-import { existsSync, readFileSync } from 'fs'
+import { $ } from 'bun'
+import { existsSync } from 'fs'
 import * as path from 'path'
 
 export interface PreviewConfig {
@@ -151,47 +152,11 @@ export {
 } from '../dist/doc-system/site/site-config.js'
 
 /*
-Where the preview host comes from — ONE implementation, and a fallback that works for
-things that are not a human at an interactive prompt.
-
-`PREVIEW_HOST` lives in `~/local-secrets/tosijs-preview.env`: mode 700, a sibling of the
-repos rather than inside one, so it is structurally impossible to commit. That is a stronger
-guarantee than a rule saying "don't commit the host", which this project wrote, believed, and
-then violated in its own `tosijs-site.config.ts` for months.
-
-The fallback exists because the previous advice — "export it from your shell profile" — is
-present for a human and ABSENT for every tool: non-interactive shells inherit no interactive
-profile, so an agent or a CI step sees nothing and reports a missing credential rather than a
-missing `export`. Reading the file directly makes the resolution order true for both.
-
-Parses only `KEY=value` / `export KEY=value`, strips one layer of quotes, ignores the rest.
-Not a shell — a credentials file that needs evaluating is a credentials file that can run
-code.
+`readLocalSecret` lives in the package (`src/doc-system/site/local-secrets.ts`) because the dev
+server reads the global tunnel keys from the same file; it is re-exported here for the bins.
 */
-export function readLocalSecret(
-  name: string,
-  file = path.join(
-    process.env.HOME ?? '',
-    'local-secrets',
-    'tosijs-preview.env'
-  )
-): string | undefined {
-  if (!process.env.HOME || !existsSync(file)) return undefined
-  let text: string
-  try {
-    text = readFileSync(file, 'utf8')
-  } catch {
-    return undefined
-  }
-  for (const line of text.split('\n')) {
-    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(
-      line
-    )
-    if (!m || m[1] !== name) continue
-    return m[2].trim().replace(/^(['"])(.*)\1$/, '$2')
-  }
-  return undefined
-}
+export { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
+import { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
 
 /**
  * `--host=` > `PREVIEW_HOST` > `PREVIEW_SSH` (legacy) > **site config** > `~/local-secrets`.
@@ -434,3 +399,47 @@ export function parseArgv(argv: string[], spec: ArgvSpec): Argv {
     rest: argv.filter((a) => !a.startsWith('--')),
   }
 }
+
+/**
+ * Refresh the host's index so a deploy, or a newly registered tunnel, shows up immediately.
+ * Shared by `tosijs-deploy` and `tosijs-tunnel`.
+ */
+export async function refreshHostIndex(host: string): Promise<void> {
+  const remote = `/tmp/tosi-build-index-${process.pid}.sh`
+  /*
+  Resolve the script against THIS PACKAGE, not the adopter's cwd.
+
+  `deploy/` is in `files`, so the asset ships at node_modules/tosijs-ui/deploy/ — only
+  the resolution was wrong, which meant every adopter's scp failed, the failure was
+  swallowed by a bare `return`, and the deploy still printed "✅ Deployed". Exactly the
+  #37 class of bug, one cycle later: a package asset located relative to whoever called us.
+  */
+  const script = `${import.meta.dir}/../deploy/build-index.sh`
+  const put = await $`scp -q ${script} ${`${host}:${remote}`}`.nothrow().quiet()
+  if (put.exitCode !== 0) {
+    // Loudly: the deploy or tunnel itself succeeded, so this must not read as total
+    // failure — but a silently stale index is how you conclude it did not land.
+    console.warn(
+      `⚠️  Could not refresh the host index (scp of ${script} failed).\n` +
+        `   The listing at the root will be stale until the next refresh.\n` +
+        `   ${put.stderr.toString().trim().slice(0, 200)}`
+    )
+    return
+  }
+  const run = await $`ssh ${host} bash ${remote}`.nothrow().quiet()
+  await $`ssh ${host} rm -f ${remote}`.nothrow().quiet()
+  // build-index.sh is `set -euo pipefail`; a non-root user on a root-owned tree dies at
+  // mkdir. Discarding this exit code meant the deploy printed ✅ over a failed index.
+  if (run.exitCode !== 0) {
+    console.warn(
+      `⚠️  the host index was not refreshed (exit ${run.exitCode}). The listing at\n` +
+        `   the root will be stale until the next successful refresh.\n` +
+        `   ${(run.stderr.toString() || run.stdout.toString())
+          .trim()
+          .slice(0, 200)}`
+    )
+    return
+  }
+  const out = run.stdout.toString().trim()
+  if (out) console.log(`   ${out}`)
+}

package/bin/tunnel.ts

@@ -34,6 +34,7 @@ import { $ } from 'bun'
 import {
   previewRootFor,
   registerCaddyFragment,
+  refreshHostIndex,
   resolveDevPort,
   resolvePreviewHost,
   resolveSiteConfig,
@@ -418,6 +419,8 @@ if (publicUrl) {
       describe: `${hostname} → this workspace`,
       body: fragment,
     })
+    // The root's list of live workspaces is read from these fragments.
+    if (routed) await refreshHostIndex(host!)
   }
 }
 

package/deploy/Caddyfile

@@ -2,8 +2,10 @@
 #
 #   {{ACME_EMAIL}}      your Let's Encrypt account email
 #   {{PREVIEW_DOMAIN}}  the domain your preview hosts live under (e.g. dev.example.com)
-#   __PREVIEW_TOKEN__   the shared invite secret, substituted at install time from
-#                       /etc/caddy/preview.env — NEVER commit a real value here
+#   __PREVIEW_TOKEN__   the shared invite secret (the global VIEW key), substituted at
+#                       install time from /etc/caddy/preview.env — NEVER commit a real value
+#   __PREVIEW_EDIT_TOKEN__  the global EDIT key, from the same file; optional (unset, the
+#                       installer fills in a value nobody knows)
 #
 # Installing this file with the placeholders intact gives you a preview host whose entire
 # invite gate is a literal string published in a public repo and in every npm tarball, and
@@ -64,7 +66,28 @@
 		redir * / 302
 	}
 
-	@unauthed not header_regexp Cookie "tosi_preview=__PREVIEW_TOKEN__"
+	# THE GLOBAL EDIT KEY: `?t=<edit key>` on any preview host sets `tosi_edit` across the
+	# whole preview domain for 24 hours. Every tunnelled workspace that holds the same key
+	# (PREVIEW_EDIT_TOKEN in ~/local-secrets/tosijs-preview.env on the machine running it)
+	# trades it for an editing session on the first page load, so the root's list opens them
+	# all, across dev-server restarts. It also opens these static previews. The view key above
+	# opens workspaces read-only the same way. See `globalKeys` in doc-site-system.md.
+	#
+	# The cookie is the key itself: Caddy can compare a fixed value and cannot sign one. A
+	# leaked edit cookie is write access to every workspace that accepts the key until it is
+	# rotated (edit preview.env here and on each machine, re-run the installer).
+	@editlink query t=__PREVIEW_EDIT_TOKEN__
+	handle @editlink {
+		header Set-Cookie "tosi_edit=__PREVIEW_EDIT_TOKEN__; Domain=.{{PREVIEW_DOMAIN}}; Path=/; Max-Age=86400; HttpOnly; Secure; SameSite=Lax"
+		header Referrer-Policy "no-referrer"
+		header Cache-Control "no-store"
+		redir * / 302
+	}
+
+	@unauthed {
+		not header_regexp Cookie "tosi_preview=__PREVIEW_TOKEN__"
+		not header_regexp Cookie "tosi_edit=__PREVIEW_EDIT_TOKEN__"
+	}
 	handle @unauthed {
 		header Content-Type "text/html; charset=utf-8"
 		header Cache-Control "no-store"

package/deploy/build-index.sh

@@ -21,6 +21,9 @@
 set -euo pipefail
 
 ROOT=/srv/preview
+
+# Names come from config and file names; nothing reaches the page unescaped.
+html() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g' -e 's/"/\&quot;/g'; }
 OUT="$ROOT/_index"
 mkdir -p "$OUT"
 
@@ -39,6 +42,7 @@ for dir in "$ROOT"/*/; do
 	gen=$(sed -n 's/.*"generator": *"\([^"]*\)".*/\1/p' "$vj" | head -1)
 	site=$(sed -n 's/.*"site": *"\([^"]*\)".*/\1/p' "$vj" | head -1)
 	[ -n "$site" ] || site="$name"
+	site=$(html "$site")
 
 	# The hostname comes from the project's OWN Caddy fragment — the same file the
 	# router reads — so this listing cannot disagree with what actually serves. An
@@ -71,6 +75,24 @@ for dir in "$ROOT"/*/; do
 	</li>"
 done
 
+# Tunnelled workspaces: every registered `-tunnel` fragment. Whether one is UP, and what
+# the reader may do there, changes by the minute, so the page asks each one when it loads
+# (see the script below); this only lists where to ask.
+live=""
+for frag in "$ROOT"/_sites/*-tunnel.caddy; do
+	[ -f "$frag" ] || continue
+	name="$(html "$(basename "$frag" -tunnel.caddy)")"
+	host=$(sed -n 's/^\([A-Za-z0-9.-]*\) *{.*/\1/p' "$frag" | head -1)
+	[ -n "$host" ] || continue
+	live="$live
+	<li data-workspace=\"$host\" hidden>
+		<a href=\"https://$host/\">
+			<span class=\"name\">$name</span>
+			<span class=\"meta\"><span class=\"access\"></span><code>$host</code></span>
+		</a>
+	</li>"
+done
+
 # The REAL tosiPlatform icon, lifted verbatim from src/icons/data/tosiPlatform.ts.
 # (The first version of this file hand-drew a rough approximation — a blue box with a
 # stroke in it — which is exactly the sort of thing nobody notices in review and
@@ -108,6 +130,9 @@ cat > "$OUT/index.html" <<HTML
 	code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; }
 	.gen { display:block; color:var(--dim); font-size:.75rem; margin-top:.3rem; }
 	.empty { color:var(--dim); }
+	h2 { font-size:1rem; margin:2rem 0 .75rem; font-weight:600; }
+	.access { font-weight:600; }
+	.access.edit { color:#2a8a3e; }
 	footer { color:var(--dim); font-size:.8rem; margin-top:2.5rem; }
 </style>
 <main>
@@ -116,6 +141,8 @@ cat > "$OUT/index.html" <<HTML
 	$(if [ "$count" -eq 0 ]; then echo '<p class="empty">Nothing deployed yet.</p>'; else echo "<ul>$rows
 	</ul>"; fi)
 	$(if [ -n "$unlinked" ]; then echo "<p class=\"empty\">Deployed but not routed:$unlinked</p>"; fi)
+	$(if [ -n "$live" ]; then echo "<section id=\"live\" hidden><h2>Live workspaces</h2><ul>$live
+	</ul></section>"; fi)
 	<footer>Previews only — not production. Each entry updates when that project deploys (<code>bun run deploy --go</code>), not when it builds.</footer>
 </main>
 <script>
@@ -133,6 +160,24 @@ cat > "$OUT/index.html" <<HTML
 		t.textContent = rel
 		t.title = d.toLocaleString()
 	}
+
+	// Ask each tunnelled workspace whether it is up and what this reader may do there. Only
+	// this origin may read the answer, and it reflects the key cookie this page set; a
+	// workspace that is down (or older than this probe) shows nothing. Opening one trades the
+	// key for a session there, so these are plain links.
+	for (const li of document.querySelectorAll('[data-workspace]')) {
+		fetch('https://' + li.dataset.workspace + '/__alive', { credentials: 'include' })
+			.then((r) => (r.ok && r.status === 200 ? r.json() : null))
+			.then((info) => {
+				if (!info || !info.access) return
+				const label = li.querySelector('.access')
+				label.textContent = info.access === 'edit' ? 'edit' : 'view'
+				label.classList.add(info.access)
+				li.hidden = false
+				document.getElementById('live').hidden = false
+			})
+			.catch(() => {})
+	}
 </script>
 HTML
 

package/dist/doc-system/site/dev-auth.d.ts

@@ -156,6 +156,8 @@ export declare function resolveShareTtlMs(tunnel?: {
  * the set before the lookup. Widening reuse must not widen lifetime.
  */
 export declare function redeemLink(state: AuthState, token: string, now: number, policy?: LinkPolicy): string | null;
+/** Mint a session token directly: what a redeemed link or a global key turns into. */
+export declare function issueSession(state: AuthState, now: number, ttlMs: number, readOnly: boolean): string;
 export declare const REDEEM_MIN_MS = 100;
 /** Consecutive failures after which the slot widens. A human never reaches this. */
 export declare const SLOW_AFTER_FAILURES = 10;
@@ -268,6 +270,14 @@ export declare function sessionCookie(token: string, maxAgeMs?: number): string;
  * defeat the entire design.
  */
 export declare function urlWithoutToken(rawUrl: string, param: string): string;
+/**
+ * A request's path, query and hash, for a `Location` that cannot leave this origin.
+ *
+ * A path is not always same-origin as a Location: `GET //evil.example/x` has the pathname
+ * `//evil.example/x`, which a browser reads as a protocol-relative URL to another host. Runs of
+ * leading slashes collapse to one.
+ */
+export declare function sameOriginPath(rawUrl: string): string;
 export declare function isSameOriginRequest(request: {
     url?: string;
     headers: {
@@ -361,6 +371,82 @@ export declare function sessionMayWrite(state: AuthState, token: string | null |
  * runs — but that is a property of the CALL ORDER, so keep the two together at every call site.
  */
 export declare function cookieMayWrite(state: AuthState, cookieValue: string | undefined | null): boolean;
+/** Caddy's cookie for the view key; the static previews' invite gate already sets it. */
+export declare const GLOBAL_VIEW_COOKIE = "tosi_preview";
+/** Caddy's cookie for the edit key. */
+export declare const GLOBAL_EDIT_COOKIE = "tosi_edit";
+/** Shorter keys are refused: Caddy compares them with no rate limit in front. */
+export declare const GLOBAL_KEY_MIN_LENGTH = 24;
+/**
+ * A session minted from a global key lasts a day, or until this dev server stops (sessions
+ * live in memory). The key is NOT re-checked while the session lives, so rotating a key ends
+ * the sessions it already opened only when each workspace restarts.
+ */
+export declare const GLOBAL_KEY_SESSION_TTL_MS: number;
+/**
+ * The most live sessions one server holds; past it the oldest goes. Only a key holder can mint
+ * one per page load, so this bounds a browser stuck reloading, not an attacker.
+ */
+export declare const MAX_SESSIONS = 1000;
+export interface GlobalKeys {
+    edit?: string;
+    view?: string;
+    /**
+     * What the edit key grants here: `'edit'`, or `'view'` on a workspace that refuses edit
+     * (`globalKeys: 'view'`). The edit key always opens at least what the view key does, as it
+     * does on the box.
+     */
+    editGrants?: 'edit' | 'view';
+}
+/**
+ * The keys this workspace accepts, from `tunnel.globalKeys` and the two secrets.
+ *
+ * `false` accepts neither; `'view'` lets either key browse and neither edit, so this workspace
+ * can be opened from the box's list and never edited through it. A key that is too short or has
+ * characters Caddy's cookie match cannot hold is not used, and `problems` says why, so the server
+ * can say so at launch rather than leave a key that silently opens nothing. So does a setting
+ * that is none of these, which accepts neither key: a misspelt `'off'` must not mean "both".
+ */
+export declare function resolveGlobalKeys(setting: unknown, secrets: {
+    PREVIEW_TOKEN?: string;
+    PREVIEW_EDIT_TOKEN?: string;
+}): {
+    keys: GlobalKeys;
+    problems: string[];
+};
+/** What the global-key cookies on a request grant: the edit key wins over the view key. */
+export declare function globalKeyAccess(cookieHeader: string | null | undefined, keys: GlobalKeys): 'edit' | 'view' | null;
+/** Is this a browser loading a page (not a fetch, a script or a socket)? */
+export declare function isNavigation(request: {
+    method: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}): boolean;
+/**
+ * Should this request trade a global key for a session, and of which kind?
+ *
+ * Only over the tunnel, only on a page load, and only when it would add something: no valid
+ * session yet, or a read-only one when the edit key is held.
+ */
+export declare function globalKeyExchange(request: {
+    method: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}, opts: {
+    viaTunnel: boolean;
+    auth: AuthState;
+    keys: GlobalKeys;
+    now: number;
+}): 'edit' | 'view' | null;
+/**
+ * The origin allowed to read this workspace's liveness answer: the box's own list.
+ *
+ * Only an https origin whose host is a parent domain of this host, so `dev.example.com` may ask
+ * `ui.edit.dev.example.com` and nothing else may.
+ */
+export declare function liveProbeOrigin(origin: string | null, host: string | null): string | null;
 /**
  * Who may attach the haltija dev channel — i.e. let an agent DRIVE this page.
  *
@@ -377,6 +463,29 @@ export declare function mayDriveWithAgent(opts: {
     viaTunnel: boolean;
     peer?: string | null;
     hasValidSession: boolean;
+    /** a read-only session (a share link, the view key) may look, never drive */
+    sessionMayWrite?: boolean;
+}): boolean;
+/**
+ * The whole haltija-bridge gate for one request, as the dev server applies it.
+ *
+ * `mayDriveWithAgent` on the request's session (a read-only one may not drive), and, for the
+ * component and the socket (`sameOriginRequired`), a same-origin request over the tunnel: a
+ * sibling host under the preview domain is the same SITE, so its pages carry the cookie. The
+ * page load that injects the loader is a navigation, often from the box's list, so it is not
+ * held to same-origin.
+ */
+export declare function haltijaBridgeAdmission(request: {
+    url?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}, opts: {
+    viaTunnel: boolean;
+    peer?: string | null;
+    auth: AuthState;
+    now: number;
+    sameOriginRequired: boolean;
 }): boolean;
 /**
  * THE loopback test. dev-server re-exports this as `isLoopbackAddress`; it used to