tosijs-ui 1.16.27 → 1.16.28

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.16.28
+
+### Tunnel
+
+- **`tosijs-tunnel` prints a single-use link that keeps you signed in.** Once the route is
+  registered, it prints one link per global key, such as
+  `https://ui.edit.dev.tosijs.net/?t=KFMRPWQT`. The link carries a one-use code, never the key.
+  Opening it starts a session in that workspace and gives the browser the box's key as a
+  cookie across the preview domain for 30 days. From then on that browser opens every
+  workspace holding the key, and the box's root list, without another link, across dev-server
+  restarts. The edit link expires after the usual link window (5 minutes,
+  `tunnel.linkTtlMinutes`); the view link is read-only and lasts a day (`--share-ttl`).
+  `--link --global` and `--link --global --share` print fresh ones. Plain `--link` and
+  `--link --share` are unchanged.
+- **It only offers a link that means what it says.** It reads the box's `PREVIEW_DOMAIN` and a
+  sha256 of each key over ssh (the keys stay on the box). It prints no link for a key this
+  workspace refuses or the box does not share, and says why instead.
+- **The box's root page lists every workspace** and says what your key opens in each: `edit`,
+  `view`, or nothing. A workspace that is offline, or whose dev server is on a tosijs-ui before
+  1.16.26, shows as not answering. In 1.16.26 those rows were hidden, so a workspace on an
+  older tosijs-ui vanished from the page meant for picking one. Workspaces are now listed above
+  the deployed builds.
+- **`?t=<key>` on any preview host takes `&to=<label>`** and sends you on to
+  `<label>.<preview domain>`, and the edit key's cookie lasts 30 days there too, as the view
+  key's always has.
+
+### Security
+
+- **The box's access log recorded every link credential** (affected: 1.9.0 to 1.16.27). Caddy
+  logs the request URI, so each `?t=<key>` visit wrote that key, and each link redemption its
+  code, to `/var/log/caddy/preview.log`. The template now redacts `t` and `token` there.
+  **Re-run `tosijs-caddy-install`, then scrub the old logs** (`/var/log/caddy/preview*.log*`) **or
+  rotate your keys.** Caddy already kept cookies out of the log.
+- **The `to` redirect stays under the preview domain.** `to` must be DNS labels (lowercase
+  letters, digits, `-`, separated by `.`); anything else, including a path, a second `to` or
+  encoded line breaks, falls back to `/`. Checked against Caddy 2.6.2 and 2.11.7.
+
 ## 1.16.27
 
 ### Deploy

package/bin/resolve-site-config.ts

@@ -34,6 +34,8 @@ export interface PreviewConfig {
     localPort?: number
     url?: string
     requireToken?: boolean
+    /** see `tunnel.globalKeys` in site-config.ts */
+    globalKeys?: boolean | 'view'
   }
 }
 
@@ -156,6 +158,8 @@ export {
 server reads the global tunnel keys from the same file; it is re-exported here for the bins.
 */
 export { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
+export { resolveGlobalKeys } from '../dist/doc-system/site/dev-auth.js'
+import type { GlobalKeys } from '../dist/doc-system/site/dev-auth.js'
 import { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
 
 /**
@@ -443,3 +447,100 @@ export async function refreshHostIndex(host: string): Promise<void> {
   const out = run.stdout.toString().trim()
   if (out) console.log(`   ${out}`)
 }
+
+/** What the box says about its global keys: its domain, and a fingerprint of each key. */
+export interface BoxKeys {
+  domain?: string
+  /** sha256 hex of the box's PREVIEW_EDIT_TOKEN / PREVIEW_TOKEN, '' when it has none */
+  editSha?: string
+  viewSha?: string
+  problem?: string
+}
+
+/**
+ * Read the box's preview domain, and fingerprints of its two keys, in one ssh call.
+ *
+ * The file is SOURCED, as the installer and Caddy's own install read it, so all three agree on
+ * quoting, `export` and comments. The keys never leave the box: only their sha256 does, which is
+ * enough to say "this machine's key is not the box's", the one mismatch that makes a link
+ * open this workspace and nothing else.
+ */
+export async function previewBoxKeys(host: string): Promise<BoxKeys> {
+  const script =
+    // Checked first: bash as a login shell carries on past a failed `.`, which read as "sets
+    // no PREVIEW_DOMAIN" when the file was missing or unreadable.
+    '[ -r /etc/caddy/preview.env ] || { echo "/etc/caddy/preview.env is missing or unreadable" >&2; exit 1; }; ' +
+    'set -a; . /etc/caddy/preview.env; set +a; ' +
+    'printf "%s\\n" "${PREVIEW_DOMAIN:-}"; ' +
+    'for k in "${PREVIEW_EDIT_TOKEN:-}" "${PREVIEW_TOKEN:-}"; do ' +
+    'if [ -n "$k" ]; then printf %s "$k" | { sha256sum 2>/dev/null || shasum -a 256; } | cut -d" " -f1; else echo; fi; done'
+  // Never prompt or hang: `--link --global` waits on this.
+  const read =
+    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host} ${script}`
+      .nothrow()
+      .quiet()
+  if (read.exitCode !== 0) {
+    return {
+      problem: `could not read /etc/caddy/preview.env on ${host}: ${read.stderr
+        .toString()
+        .trim()
+        .slice(0, 160)}`,
+    }
+  }
+  const [domain = '', editSha = '', viewSha = ''] = read.stdout
+    .toString()
+    .split('\n')
+    .map((line) => line.trim())
+  if (!/^[a-z0-9.-]+$/i.test(domain)) {
+    return {
+      problem: `/etc/caddy/preview.env on ${host} sets no PREVIEW_DOMAIN`,
+    }
+  }
+  return { domain, editSha, viewSha }
+}
+
+const sha256 = (text: string) =>
+  new Bun.CryptoHasher('sha256').update(text).digest('hex')
+
+/**
+ * Which single-use links `tosijs-tunnel` can honestly offer, and why not the rest.
+ *
+ * A link hands the browser this machine's key as a cookie across the box's domain, so it is
+ * only worth printing when this workspace accepts the key AND the box holds the same one; with a
+ * different key on the box, the cookie would open this workspace and not the box's root or any
+ * other workspace, which is not what the link says.
+ */
+export function planGlobalLinks(
+  local: { keys: GlobalKeys; problems: string[] },
+  box: BoxKeys
+): { kinds: ('edit' | 'view')[]; domain?: string; notes: string[] } {
+  const notes = [...local.problems]
+  const { keys } = local
+  const wanted: ('edit' | 'view')[] = []
+  if (keys.edit && (keys.editGrants ?? 'edit') === 'edit') wanted.push('edit')
+  if (keys.view) wanted.push('view')
+  if (wanted.length === 0) {
+    if (notes.length === 0)
+      notes.push(
+        'no global key on this machine (PREVIEW_EDIT_TOKEN / PREVIEW_TOKEN in ~/local-secrets/tosijs-preview.env), or tunnel.globalKeys turns them off'
+      )
+    return { kinds: [], notes }
+  }
+  if (!box.domain) {
+    notes.push(box.problem ?? 'the box did not say what its preview domain is')
+    return { kinds: [], notes }
+  }
+  const kinds = wanted.filter((kind) => {
+    const mine = kind === 'edit' ? keys.edit! : keys.view!
+    const theirs = kind === 'edit' ? box.editSha : box.viewSha
+    if (theirs === sha256(mine)) return true
+    const name = kind === 'edit' ? 'PREVIEW_EDIT_TOKEN' : 'PREVIEW_TOKEN'
+    notes.push(
+      theirs
+        ? `${name} here is not the box's, so no ${kind} link: put the same value in both files`
+        : `the box has no ${name}, so no ${kind} link: add it to /etc/caddy/preview.env and re-run tosijs-caddy-install`
+    )
+    return false
+  })
+  return { kinds, domain: box.domain, notes }
+}

package/bin/tunnel.ts

@@ -32,9 +32,13 @@ always requires a session.
 
 import { $ } from 'bun'
 import {
+  planGlobalLinks,
+  previewBoxKeys,
   previewRootFor,
+  readLocalSecret,
   registerCaddyFragment,
   refreshHostIndex,
+  resolveGlobalKeys,
   resolveDevPort,
   resolvePreviewHost,
   resolveSiteConfig,
@@ -45,7 +49,7 @@ import {
 const { has, flag } = parseArgv(process.argv.slice(2), {
   bin: 'tosijs-tunnel',
   summary: 'expose the local dev server through the preview host',
-  flags: ['close', 'link', 'status', 'share'],
+  flags: ['close', 'link', 'status', 'share', 'global'],
   values: ['host', 'port', 'local-port', 'remote-port', 'url', 'share-ttl'],
   usage:
     `  tosijs-tunnel                        open the tunnel (foreground)\n` +
@@ -53,6 +57,8 @@ const { has, flag } = parseArgv(process.argv.slice(2), {
     `  --close                              close a running tunnel\n` +
     `  --link                               print a magic edit link\n` +
     `  --link --share                       print a READ-ONLY link to send to a person\n` +
+    `  --link --global [--share]            a SINGLE-USE link that also gives that browser the\n` +
+    `                                       box's key for 30 days (every workspace, the root list)\n` +
     `  --share-ttl=<minutes>                how long that share link lives (default 1440)\n` +
     `  --host=user@box                      override the configured preview host\n` +
     `  --port= --local-port= --remote-port= override the resolved ports`,
@@ -113,6 +119,60 @@ const publicUrl = flag('url') ?? preview?.tunnel?.url
 // Set by the registration step below; no public URL means there is no route to fail.
 let routed = true
 
+/** Ask the dev server (loopback only) for a link; `query` selects the kind. */
+async function askForLink(
+  query: string
+): Promise<{ url?: string; error?: string }> {
+  const res =
+    await $`curl -sk --max-time 5 https://localhost:${localPort}/__devlink${query}`
+      .nothrow()
+      .quiet()
+  try {
+    return JSON.parse(res.stdout.toString())
+  } catch {
+    return {}
+  }
+}
+
+/*
+Single-use links that also give the browser the box's global key (see GlobalGrant in
+dev-auth.ts): one click opens this workspace, and from then on that browser opens every
+workspace holding the key, and the box's root list, for 30 days, across restarts. The link
+carries a one-use code, never the key. Offered only for keys this workspace accepts and the box
+holds too; `notes` says why any other is missing.
+*/
+async function globalLinks(
+  kinds: ('edit' | 'view')[] = ['edit', 'view'],
+  extraQuery = ''
+): Promise<{
+  links: { kind: 'edit' | 'view'; url: string }[]
+  notes: string[]
+}> {
+  const local = resolveGlobalKeys(preview?.tunnel?.globalKeys, {
+    PREVIEW_TOKEN:
+      process.env.PREVIEW_TOKEN ?? readLocalSecret('PREVIEW_TOKEN'),
+    PREVIEW_EDIT_TOKEN:
+      process.env.PREVIEW_EDIT_TOKEN ?? readLocalSecret('PREVIEW_EDIT_TOKEN'),
+  })
+  const box =
+    local.keys.edit || local.keys.view ? await previewBoxKeys(host!) : {}
+  const plan = planGlobalLinks(local, box)
+  const links: { kind: 'edit' | 'view'; url: string }[] = []
+  for (const kind of plan.kinds.filter((k) => kinds.includes(k))) {
+    const answer = await askForLink(
+      `?global=${kind}&domain=${encodeURIComponent(plan.domain!)}${extraQuery}`
+    )
+    if (answer.url) links.push({ kind, url: answer.url })
+    else
+      plan.notes.push(
+        answer.error ??
+          `the dev server on :${localPort} did not answer, so no ${kind} link: start it (\`bun start\`), then \`tosijs-tunnel --link\``
+      )
+  }
+  return { links, notes: plan.notes }
+}
+let startLinks: Awaited<ReturnType<typeof globalLinks>> | undefined
+
 /*
 Say where this is going, and where the address came from, BEFORE acting on it.
 
@@ -176,18 +236,25 @@ if (has('link')) {
   */
   const share = has('share')
   const shareTtl = flag('share-ttl')
-  const query = share
-    ? `?share=1${shareTtl ? `&ttl=${encodeURIComponent(shareTtl)}` : ''}`
-    : ''
-  const res =
-    await $`curl -sk --max-time 5 https://localhost:${localPort}/__devlink${query}`
-      .nothrow()
-      .quiet()
-  let url = ''
-  try {
-    url = JSON.parse(res.stdout.toString()).url
-  } catch {
-    /* fall through to the error below */
+  const ttl = shareTtl ? `&ttl=${encodeURIComponent(shareTtl)}` : ''
+  /*
+  `--global` asks for a link that also hands over the box's key (see globalLinks): single-use,
+  and the browser keeps every workspace for 30 days. Opt-in, because it is a different promise
+  from the two links above, which are reusable for their window and open this workspace only.
+  A share link spent by a chat app's link preview, or one that opens every workspace, would
+  break the promise `--share` makes to the person you send it to.
+  */
+  let url: string
+  if (has('global')) {
+    const global = await globalLinks([share ? 'view' : 'edit'], ttl)
+    for (const note of global.notes) console.log(`note: ${note}`)
+    url = global.links[0]?.url ?? ''
+    if (!url) {
+      console.error('\nNo single-use global link (see the note above).\n')
+      process.exit(1)
+    }
+  } else {
+    url = (await askForLink(share ? `?share=1${ttl}` : '')).url ?? ''
   }
   if (!url) {
     console.error(
@@ -210,7 +277,15 @@ if (has('link')) {
   */
   const code = new URL(url).searchParams.get('t')
   console.log(
-    `\n🔗 ${share ? 'Share link (READ ONLY)' : 'Edit link'}:\n   ${url}\n` +
+    `\n🔗 ${
+      has('global')
+        ? `Single-use ${
+            share ? 'READ-ONLY ' : ''
+          }link (that browser keeps every workspace for 30 days)`
+        : share
+        ? 'Share link (READ ONLY)'
+        : 'Edit link'
+    }:\n   ${url}\n` +
       (code ? `\n   code:  ${code}   (case-insensitive)\n` : '')
   )
 
@@ -419,8 +494,11 @@ 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!)
+    if (routed) {
+      // The root's list of live workspaces is read from these fragments.
+      await refreshHostIndex(host!)
+      startLinks = await globalLinks()
+    }
   }
 }
 
@@ -438,6 +516,15 @@ if (publicUrl) {
       ? `   ${publicUrl}`
       : `   ${publicUrl}  ⚠️  NOT routed — registration failed above; this URL will not reach here`
   )
+  if (startLinks?.links.length) {
+    console.log(
+      `\n   Single-use links: each opens this workspace, then keeps that browser in every` +
+        `\n   workspace on the box (and its root list) for 30 days:`
+    )
+    for (const { kind, url } of startLinks.links)
+      console.log(`   ${kind}: ${url}${kind === 'view' ? '  (read-only)' : ''}`)
+  }
+  for (const note of startLinks?.notes ?? []) console.log(`   note: ${note}`)
 }
 console.log(`   Ctrl-C to close.\n`)
 

package/deploy/Caddyfile

@@ -36,6 +36,15 @@
 # `root` is the only thing that varies, keeping it in the caller costs one line per
 # project and makes this file work on any Caddy 2.x.
 (preview_site) {
+	# Where a key link lands: `&to=<label>` sends it to `<label>.{{PREVIEW_DOMAIN}}` (so
+	# `tosijs-tunnel` can hand out ONE link that sets the cookie here and opens its workspace),
+	# anything else to this host's root. Only DNS labels match, and the target is always under
+	# the preview domain, so this cannot redirect off-site.
+	map {query.to} {tosi_link_target} {
+		~^([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)$ "https://${1}.{{PREVIEW_DOMAIN}}/"
+		default "/"
+	}
+
 	# THE PREVIEW HOST IS PRIVATE — but gated by a LINK, not a password dialog.
 	#
 	# basicauth used to guard these hosts, and it worked, but it makes the browser throw
@@ -63,11 +72,13 @@
 		header Set-Cookie "tosi_preview=__PREVIEW_TOKEN__; Domain=.{{PREVIEW_DOMAIN}}; Path=/; Max-Age=2592000; HttpOnly; Secure; SameSite=Lax"
 		header Referrer-Policy "no-referrer"
 		header Cache-Control "no-store"
-		redir * / 302
+		redir * {tosi_link_target} 302
 	}
 
 	# 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
+	# whole preview domain for 30 days, the same cookie a workspace's single-use link from
+	# `tosijs-tunnel` sets (that link is the usual way in: it never puts the key in a URL).
+	# 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
@@ -78,10 +89,10 @@
 	# 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 Set-Cookie "tosi_edit=__PREVIEW_EDIT_TOKEN__; Domain=.{{PREVIEW_DOMAIN}}; Path=/; Max-Age=2592000; HttpOnly; Secure; SameSite=Lax"
 		header Referrer-Policy "no-referrer"
 		header Cache-Control "no-store"
-		redir * / 302
+		redir * {tosi_link_target} 302
 	}
 
 	# Anchored at both ends: unanchored, `tosi_edit=<key>x` matched too. That needed the key
@@ -151,6 +162,17 @@
 			roll_size 10MiB
 			roll_keep 3
 		}
+		# Links carry credentials in the query: `t` (a global key, or a single-use code) and
+		# `token`. Caddy already keeps cookies out of this log; this keeps those out too.
+		format filter {
+			wrap json
+			fields {
+				request>uri query {
+					replace t REDACTED
+					replace token REDACTED
+				}
+			}
+		}
 	}
 }
 
@@ -198,6 +220,17 @@
 			roll_size 10MiB
 			roll_keep 3
 		}
+		# Links carry credentials in the query: `t` (a global key, or a single-use code) and
+		# `token`. Caddy already keeps cookies out of this log; this keeps those out too.
+		format filter {
+			wrap json
+			fields {
+				request>uri query {
+					replace t REDACTED
+					replace token REDACTED
+				}
+			}
+		}
 	}
 }
 

package/deploy/build-index.sh

@@ -75,9 +75,10 @@ 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.
+# Tunnelled workspaces: every registered `-tunnel` fragment, ALWAYS listed, so this page is
+# where you pick one. Whether it 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). Hiding the rows
+# that did not answer made a workspace on an older tosijs-ui simply vanish.
 live=""
 for frag in "$ROOT"/_sites/*-tunnel.caddy; do
 	[ -f "$frag" ] || continue
@@ -85,10 +86,10 @@ for frag in "$ROOT"/_sites/*-tunnel.caddy; do
 	host=$(sed -n 's/^\([A-Za-z0-9.-]*\) *{.*/\1/p' "$frag" | head -1)
 	[ -n "$host" ] || continue
 	live="$live
-	<li data-workspace=\"$host\" hidden>
+	<li data-workspace=\"$host\">
 		<a href=\"https://$host/\">
 			<span class=\"name\">$name</span>
-			<span class=\"meta\"><span class=\"access\"></span><code>$host</code></span>
+			<span class=\"meta\"><span class=\"access\">checking…</span><code>$host</code></span>
 		</a>
 	</li>"
 done
@@ -133,16 +134,18 @@ cat > "$OUT/index.html" <<HTML
 	h2 { font-size:1rem; margin:2rem 0 .75rem; font-weight:600; }
 	.access { font-weight:600; }
 	.access.edit { color:#2a8a3e; }
+	.access.none { font-weight:400; }
 	footer { color:var(--dim); font-size:.8rem; margin-top:2.5rem; }
 </style>
 <main>
 	<header>$ICON<h1>tosijs previews</h1></header>
-	<p class="sub">Deployed builds. Each shows the commit it was built from.</p>
+	<p class="sub">Live workspaces, and the builds deployed here.</p>
+	$(if [ -n "$live" ]; then echo "<section id=\"live\"><h2>Live workspaces</h2><ul>$live
+	</ul></section>"; fi)
+	<h2>Deployed builds</h2>
 	$(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>
@@ -162,21 +165,26 @@ cat > "$OUT/index.html" <<HTML
 	}
 
 	// 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.
+	// this origin may read the answer, and it reflects the key cookie this page set. Opening
+	// one trades the key for a session there, so these are plain links. A workspace that is
+	// down and one whose dev server predates this probe (tosijs-ui 1.16.26) look the same
+	// from here: neither gives an answer this page may read.
+	const silent = 'not answering (offline, or tosijs-ui before 1.16.26)'
+	const say = (li, text, kind) => {
+		const label = li.querySelector('.access')
+		label.textContent = text
+		label.className = 'access ' + kind
+	}
 	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((r) => (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
+				if (!info) say(li, silent, 'none')
+				else if (info.access === 'edit') say(li, 'edit', 'edit')
+				else if (info.access === 'view') say(li, 'view', 'view')
+				else say(li, 'up, but your key does not open it', 'none')
 			})
-			.catch(() => {})
+			.catch(() => say(li, silent, 'none'))
 	}
 </script>
 HTML

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

@@ -104,6 +104,24 @@ export interface AuthState {
      * asked of it is the same either way: "may whoever holds this write?"
      */
     readOnly: Set<string>;
+    /**
+     * Link tokens that also hand over a global key (see {@link GlobalGrant}). Such a link is
+     * spent on first use, whatever `linkPolicy` says: it gives the browser a key that outlives
+     * this server.
+     */
+    grants: Map<string, GlobalGrant>;
+    /** Sessions minted from a granting link, until the redirect that sets the key takes them. */
+    sessionGrants: Map<string, GlobalGrant>;
+}
+/**
+ * What a single-use link hands over besides a session here: the box's global `key`, as a
+ * cookie across `domain`, so this browser opens every workspace (and the box's root list)
+ * without another link. The link carries a one-use code; the key itself never appears in a
+ * URL, a terminal or a log.
+ */
+export interface GlobalGrant {
+    key: 'edit' | 'view';
+    domain: string;
 }
 export declare function createAuthState(): AuthState;
 /** Drop anything expired. Called on every use so the maps cannot grow without bound. */
@@ -119,6 +137,7 @@ export declare function prune(state: AuthState, now: number): void;
  */
 export declare function issueLink(state: AuthState, now: number, ttlMs?: number, opts?: {
     readOnly?: boolean;
+    grant?: GlobalGrant;
 }): string;
 /**
  * Read the link settings off a site config, with the defaults applied.
@@ -156,6 +175,30 @@ 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;
+/**
+ * How many unspent granting links may exist at once. Each is a live code that, guessed, hands
+ * over the box's key; a bound keeps the guessing odds where a handful of real links put them.
+ */
+export declare const MAX_OUTSTANDING_GRANTS = 32;
+/** Unspent, unexpired granting links. */
+export declare function outstandingGrants(state: AuthState, now: number): number;
+/** The global key a just-redeemed link hands over with `session`, once. */
+export declare function takeSessionGrant(state: AuthState, session: string): GlobalGrant | undefined;
+/** How long a browser keeps a global key it was given by a link: 30 days. */
+export declare const GLOBAL_KEY_COOKIE_MAX_AGE_S: number;
+/**
+ * The cookie that gives this browser the box's global key across the preview domain, the same
+ * one Caddy sets for `?t=<key>`, so the box's root and every workspace holding the key accept
+ * it. `null` when this server does not hold that key, or would not honour it: a link must not
+ * hand over a key that opens less than it claims.
+ */
+export declare function globalKeyCookie(grant: GlobalGrant, keys: GlobalKeys): string | null;
+/**
+ * The preview domain a granting link may set its cookie on: a plain hostname that the
+ * workspace's own host sits under. Anything else would set a cookie this browser drops (a
+ * domain the host is not under), or one far wider than the preview host (`net`).
+ */
+export declare function grantDomainFor(domain: string | null | undefined, workspaceHost: string): 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;