tosijs-ui 1.16.29 → 1.16.31

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 1.16.31
+
+**Tunnel users: each browser needs one new `tosijs-tunnel --link --global`.** The edit cookie
+from earlier versions held the box's edit key itself, and it no longer opens a workspace (see
+below). Reinstall the box's Caddyfile (`tosijs-caddy-install --go`) to drop `?t=<edit key>`.
+
+**If you used `--global` edit links or `?t=<edit key>` on 1.16.26–1.16.30, rotate the edit
+key.** Those versions put its raw value in browser cookies (for 30 days) and URLs (so browser
+history and anywhere one was pasted), and in 1.16.31 that same value signs every device pass:
+anyone holding a copy could sign passes of their own that `--revoke` cannot see. Set a new
+`PREVIEW_EDIT_TOKEN` in `/etc/caddy/preview.env` on the box and in
+`~/local-secrets/tosijs-preview.env` on each machine, re-run `tosijs-caddy-install --go`, and
+restart the dev servers. Upgrade every project that tunnels through the same box first: a new
+edit link expires the old `tosi_edit` cookie, so a workspace still on tosijs-ui 1.16.30 or
+earlier then opens read-only in that browser.
+
+### Tunnel
+
+- **Each device gets its own edit pass, and you can revoke one.** A `--link --global` edit link
+  used to give the browser the box's edit key as its cookie, so every device held the same
+  credential, and the only way to cut one off was to rotate the key everywhere. Now the link
+  gives that browser a pass for that one device, signed with the edit key, which no longer
+  reaches a browser. `tosijs-tunnel --devices` lists every pass issued, `--revoke=<id>` cuts one device
+  off, and `--label=<name>` names the device a link is for. Revoking ends
+  edit access; the device keeps the shared view key, so it can still browse until you rotate
+  that. Every workspace checks the box's
+  revoked list before it honours a pass, at most a minute old, and ends a revoked device's open
+  sessions within that minute. A workspace that cannot read the list honours no pass at all.
+  An edit link also sets the view key, which opens the box's root list and the static previews.
+- **A link that hands over a key lives five minutes.** The view `--global` link lasted a day;
+  now both kinds expire after five minutes, single use. The cookie it sets is what lasts (30
+  days), not the code that delivers it. `tunnel.linkTtlMinutes` can shorten the window, never
+  lengthen it, and `--share-ttl` no longer applies to these links; to give someone view access
+  later, send a plain `--link --share`.
+- **The edit key has no URL form.** The box no longer accepts `?t=<edit key>`, which made the
+  key a permanent bearer token in browser history and anywhere the URL was pasted. The view key
+  still works that way for the static previews.
+- **The box's workspace list opens each link in a new tab**, so the list stays open as the
+  place you pick the next one.
+
+### Notifications
+
+- **A long message can no longer push the close button out of the notification.** The message
+  column cannot grow past the note, an unbroken string wraps anywhere, and a message is cut off
+  with an ellipsis after four lines (`--notification-max-lines`); the full text is the tooltip,
+  and screen readers get all of it.
+- **Many notifications stack instead of scrolling.** The newest `TosiNotification.maxVisible`
+  (3) stay in view, newest on top; the lowest of them fronts a stack, with older notifications
+  behind it, each one's lower edge showing by `TosiNotification.stackOffsets` (`[16, 8, 4]` px),
+  and the rest hidden until the ones in front close. Stacked notifications show their lower
+  edges straight below the front card, with no sideways offset.
+- **Dismiss all.** A button whenever more than one notification is open, which sits centred
+  over those edges at the bottom, outlined in the colour of the most severe one open (hidden ones included), and
+  `TosiNotification.dismissAll()`. Both fire each notification's `close` callback, as if the
+  user had closed it.
+- **Smoother movement.** A closing notification fades where it is, then the rest move once,
+  straight to their new places; restacking used to slide cards in from wherever their last
+  offset left them. (A pre-release bug is fixed too: notes just pushed into the stack were
+  measured while still in the flow, so the stack sat one card too high.)
+
+## 1.16.30
+
+### Tunnel
+
+- **A dev-server restart no longer costs a key holder their next save.** `bun start` restarts
+  the server whenever a file in its import graph changes, and that includes every component
+  source, so editing an example restarts it. Save to source writes such a file, so the save
+  itself restarted the server, and the NEXT save from the same page was told "This workspace
+  needs an invite link". Reloading recovered the session but lost the unsaved edit. Now a
+  request from the workspace's own page that holds the global key cookie is given a fresh
+  session in place, and the haltija agent bridge's reconnection is too. "Own page" means
+  `Sec-Fetch-Site: same-origin` or an `Origin` that is this host; a sibling workspace's page,
+  which receives the same cookie, gets nothing, nor does a request with neither header. A
+  session opened from a plain `--link` holds no key, so a restart still ends it.
+- **For a key holder, the key cookie now bounds access, not the session.** A key opens a
+  one-day session, but the cookie renews it, so access lasts as long as the cookie (30 days for
+  the edit key) or until you rotate the key and restart the dev servers.
+
 ## 1.16.29
 
 ### Doc system

package/bin/resolve-site-config.ts

@@ -158,7 +158,61 @@ 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'
+export {
+  resolveGlobalKeys,
+  DEVICE_ID_PATTERN,
+} from '../dist/doc-system/site/dev-auth.js'
+import {
+  DEVICE_ID_PATTERN,
+  cleanDeviceLabel,
+} from '../dist/doc-system/site/dev-auth.js'
+
+/*
+The box's device registry (board #3416): one tab-separated line per edit pass issued, written
+by `tosijs-tunnel` over ssh as `printf '%s\n' '<line>'`. So a line may hold no quote, tab or
+newline of its own: every field is checked or cleaned here, and a line that cannot be made safe
+is not written.
+*/
+export const DEVICE_LISTING_SEPARATOR = '--revoked--'
+
+export function deviceRegistryLine(device: {
+  id: string
+  issued: Date
+  project: string
+  label: string
+}): string | null {
+  if (!DEVICE_ID_PATTERN.test(device.id)) return null
+  const project = device.project.replace(/[^\w.-]/g, '').slice(0, 60)
+  return [
+    device.id,
+    device.issued.toISOString(),
+    project,
+    cleanDeviceLabel(device.label),
+  ].join('\t')
+}
+
+export interface DeviceRecord {
+  id: string
+  issued: string
+  project: string
+  label: string
+  revoked: boolean
+}
+
+/** `cat registry.tsv; echo --revoked--; cat revoked.txt` → one record per device, newest first. */
+export function parseDeviceListing(text: string): DeviceRecord[] {
+  const [registry = '', revokedText = ''] = text.split(
+    `${DEVICE_LISTING_SEPARATOR}\n`
+  )
+  const revoked = new Set(revokedText.split('\n').map((line) => line.trim()))
+  const devices: DeviceRecord[] = []
+  for (const line of registry.split('\n')) {
+    const [id = '', issued = '', project = '', label = ''] = line.split('\t')
+    if (!DEVICE_ID_PATTERN.test(id)) continue
+    devices.push({ id, issued, project, label, revoked: revoked.has(id) })
+  }
+  return devices.reverse()
+}
 import type { GlobalKeys } from '../dist/doc-system/site/dev-auth.js'
 import { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
 

package/bin/tunnel.ts

@@ -44,22 +44,39 @@ import {
   resolveSiteConfig,
   resolveTunnelLocalPort,
   parseArgv,
+  deviceRegistryLine,
+  parseDeviceListing,
+  DEVICE_LISTING_SEPARATOR,
+  DEVICE_ID_PATTERN,
 } from './resolve-site-config.ts'
 
 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', 'global'],
-  values: ['host', 'port', 'local-port', 'remote-port', 'url', 'share-ttl'],
+  flags: ['close', 'link', 'status', 'share', 'global', 'devices'],
+  values: [
+    'host',
+    'port',
+    'local-port',
+    'remote-port',
+    'url',
+    'share-ttl',
+    'label',
+    'revoke',
+  ],
   usage:
     `  tosijs-tunnel                        open the tunnel (foreground)\n` +
     `  --status                             report whether a tunnel is up\n` +
     `  --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` +
+    `  --link --global [--share]            a SINGLE-USE 5-minute link that also keeps that\n` +
+    `                                       browser in every workspace and the root list for\n` +
+    `                                       30 days (edit: a revocable device pass)\n` +
+    `  --label=<name>                       name the device a --global edit link is for\n` +
+    `  --devices                            list the devices given an edit pass, and which are revoked\n` +
+    `  --revoke=<device id>                 revoke one device's edit pass, on every workspace\n` +
+    `  --share-ttl=<minutes>                how long a plain share link lives (default 1440)\n` +
     `  --host=user@box                      override the configured preview host\n` +
     `  --port= --local-port= --remote-port= override the resolved ports`,
 })
@@ -122,7 +139,7 @@ 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 }> {
+): Promise<{ url?: string; device?: string; error?: string }> {
   const res =
     await $`curl -sk --max-time 5 https://localhost:${localPort}/__devlink${query}`
       .nothrow()
@@ -142,8 +159,7 @@ carries a one-use code, never the key. Offered only for keys this workspace acce
 holds too; `notes` says why any other is missing.
 */
 async function globalLinks(
-  kinds: ('edit' | 'view')[] = ['edit', 'view'],
-  extraQuery = ''
+  kinds: ('edit' | 'view')[] = ['edit', 'view']
 ): Promise<{
   links: { kind: 'edit' | 'view'; url: string }[]
   notes: string[]
@@ -159,9 +175,27 @@ async function globalLinks(
   const plan = planGlobalLinks(local, box)
   const links: { kind: 'edit' | 'view'; url: string }[] = []
   for (const kind of plan.kinds.filter((k) => kinds.includes(k))) {
+    const label = flag('label')
     const answer = await askForLink(
-      `?global=${kind}&domain=${encodeURIComponent(plan.domain!)}${extraQuery}`
+      `?global=${kind}&domain=${encodeURIComponent(plan.domain!)}${
+        label ? `&label=${encodeURIComponent(label)}` : ''
+      }`
     )
+    if (answer.url && answer.device) {
+      // Recorded before the link is shown, so every pass in a browser is on the box's list.
+      const recorded = await registerDevice({
+        id: answer.device,
+        project: projectName,
+        // The links printed at start are recorded too, used or not; say which they were.
+        label: label ?? (has('link') ? '' : 'printed at tunnel start'),
+      })
+      if (!recorded) {
+        plan.notes.push(
+          `could not record device ${answer.device} on ${host}, so no ${kind} link: it could not be listed or revoked`
+        )
+        continue
+      }
+    }
     if (answer.url) links.push({ kind, url: answer.url })
     else
       plan.notes.push(
@@ -173,6 +207,33 @@ async function globalLinks(
 }
 let startLinks: Awaited<ReturnType<typeof globalLinks>> | undefined
 
+/*
+DEVICES (board #3416). Each --global edit link is a pass for one device. The box keeps the
+record: `_devices/registry.tsv` (not served) lists every pass issued, and `_index/revoked.txt`
+(served beside the root list, behind its cookie gate) is what every workspace reads before it
+honours a pass. Both live under the preview root, written over the same ssh as the rest.
+*/
+const devicesRoot = () =>
+  previewRootFor(
+    preview?.path ?? '/srv/preview/placeholder',
+    preview?.caddySitesDir
+  )
+
+async function registerDevice(device: {
+  id: string
+  project: string
+  label: string
+}): Promise<boolean> {
+  const line = deviceRegistryLine({ ...device, issued: new Date() })
+  if (!line) return false
+  const root = devicesRoot()
+  const run =
+    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host!} ${`mkdir -p ${root}/_devices && printf '%s\\n' '${line}' >> ${root}/_devices/registry.tsv`}`
+      .nothrow()
+      .quiet()
+  return run.exitCode === 0
+}
+
 /*
 Say where this is going, and where the address came from, BEFORE acting on it.
 
@@ -218,6 +279,67 @@ async function running(): Promise<number[]> {
   return out.trim().split('\n').filter(Boolean).map(Number)
 }
 
+if (has('devices')) {
+  const root = devicesRoot()
+  const read =
+    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host!} ${`cat ${root}/_devices/registry.tsv 2>/dev/null; echo ${DEVICE_LISTING_SEPARATOR}; cat ${root}/_index/revoked.txt 2>/dev/null; true`}`
+      .nothrow()
+      .quiet()
+  if (read.exitCode !== 0) {
+    console.error(
+      `\nCould not read the device list on ${host}: ${read.stderr
+        .toString()
+        .trim()}\n`
+    )
+    process.exit(1)
+  }
+  const devices = parseDeviceListing(read.stdout.toString())
+  if (!devices.length) {
+    console.log(
+      '\nNo edit passes issued yet (`tosijs-tunnel --link --global`).\n'
+    )
+  } else {
+    console.log('')
+    for (const d of devices)
+      console.log(
+        `  ${d.id}  ${d.revoked ? 'REVOKED' : 'active '}  ${d.issued}  ${
+          d.project
+        }${d.label ? `  "${d.label}"` : ''}`
+      )
+    console.log(
+      `\n  Revoke one with \`tosijs-tunnel --revoke=<id>\`. A pass also expires 30 days after it was issued.\n`
+    )
+  }
+  process.exit(0)
+}
+
+if (flag('revoke') !== undefined) {
+  const id = flag('revoke')!
+  if (!DEVICE_ID_PATTERN.test(id)) {
+    console.error(
+      `\n${JSON.stringify(
+        id
+      )} is not a device id (ten letters and digits; see --devices).\n`
+    )
+    process.exit(1)
+  }
+  const root = devicesRoot()
+  const run =
+    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host!} ${`mkdir -p ${root}/_index && printf '%s\\n' ${id} >> ${root}/_index/revoked.txt && chmod 644 ${root}/_index/revoked.txt`}`
+      .nothrow()
+      .quiet()
+  if (run.exitCode !== 0) {
+    console.error(
+      `\nCould not revoke ${id} on ${host}: ${run.stderr.toString().trim()}\n`
+    )
+    process.exit(1)
+  }
+  console.log(
+    `\n🔒 ${id} revoked. Every workspace stops honouring its edit pass, and ends its edit sessions, within a minute. It keeps the shared view key until you rotate that.\n`
+  )
+  process.exit(0)
+}
+
 if (has('link')) {
   /*
   Ask the dev server over loopback. The previous version ran
@@ -238,15 +360,16 @@ if (has('link')) {
   const shareTtl = flag('share-ttl')
   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
+  `--global` asks for a link that also hands over a global credential (see globalLinks): single-use,
+  valid five minutes whatever `--share-ttl` says, 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)
+    const global = await globalLinks([share ? 'view' : 'edit'])
     for (const note of global.notes) console.log(`note: ${note}`)
     url = global.links[0]?.url ?? ''
     if (!url) {

package/deploy/Caddyfile

@@ -75,25 +75,17 @@
 		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 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
-	# opens workspaces read-only the same way. See `globalKeys` in doc-site-system.md.
+	# THE GLOBAL EDIT KEY has NO URL form, and no browser holds it. A browser that opens a
+	# workspace's single-use link (`tosijs-tunnel --link --global`, a one-use code valid five
+	# minutes) gets a signed pass for that one device, plus the view key below; the cookie lasts
+	# 30 days, the code that delivers it does not (the maintainer's rule, 2026-10-20). Through
+	# 1.16.30 `?t=<edit key>` here set the raw key as a cookie, a permanent bearer token for
+	# writing source on every workspace that no one device could lose on its own.
 	#
-	# 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=2592000; HttpOnly; Secure; SameSite=Lax"
-		header Referrer-Policy "no-referrer"
-		header Cache-Control "no-store"
-		redir * {tosi_link_target} 302
-	}
+	# The gate below still accepts the raw edit key: the dev servers present it to read
+	# `revoked.txt` (the root's revoked-device list, which `tosijs-tunnel --revoke` appends to).
+	# Rotating it (edit preview.env here and on each machine, re-run the installer) invalidates
+	# every device pass at once.
 
 	# Anchored at both ends: unanchored, `tosi_edit=<key>x` matched too. That needed the key
 	# anyway, but the dev servers compare exactly, and the gate should agree with them.

package/deploy/build-index.sh

@@ -27,6 +27,9 @@ html() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;
 OUT="$ROOT/_index"
 mkdir -p "$OUT"
 
+# Every link opens in its own tab, so this page stays open as the place you pick the next one.
+# target=_blank implies noopener, so a workspace gets no handle on this page.
+
 # Collect deployed projects. A directory only counts if it has a version.json — a
 # half-finished rsync or a stray folder should not appear as a live preview.
 rows=""
@@ -64,7 +67,7 @@ for dir in "$ROOT"/*/; do
 	count=$((count + 1))
 	rows="$rows
 	<li>
-		<a href=\"//$host\">
+		<a href=\"//$host\" target=\"_blank\">
 			<span class=\"name\">$site</span>
 			<span class=\"meta\">
 				<code>${commit:-unknown}</code>
@@ -87,7 +90,7 @@ for frag in "$ROOT"/_sites/*-tunnel.caddy; do
 	[ -n "$host" ] || continue
 	live="$live
 	<li data-workspace=\"$host\">
-		<a href=\"https://$host/\">
+		<a href=\"https://$host/\" target=\"_blank\">
 			<span class=\"name\">$name</span>
 			<span class=\"meta\"><span class=\"access\">checking…</span><code>$host</code></span>
 		</a>

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

@@ -112,6 +112,8 @@ export interface AuthState {
     grants: Map<string, GlobalGrant>;
     /** Sessions minted from a granting link, until the redirect that sets the key takes them. */
     sessionGrants: Map<string, GlobalGrant>;
+    /** Sessions minted from a device pass → that device, so revoking it ends them too. */
+    sessionDevices: Map<string, string>;
 }
 /**
  * What a single-use link hands over besides a session here: the box's global `key`, as a
@@ -122,6 +124,9 @@ export interface AuthState {
 export interface GlobalGrant {
     key: 'edit' | 'view';
     domain: string;
+    /** An edit grant's device id and label, which the pass it becomes carries. */
+    device?: string;
+    label?: string;
 }
 export declare function createAuthState(): AuthState;
 /** Drop anything expired. Called on every use so the maps cannot grow without bound. */
@@ -164,6 +169,18 @@ export declare function resolveLinkSettings(tunnel?: {
 export declare function resolveShareTtlMs(tunnel?: {
     shareTtlMinutes?: number;
 }, override?: number): number;
+/**
+ * How long a link that hands over a global key (edit or view) is redeemable: the edit-link
+ * window, and never more than five minutes.
+ *
+ * The maintainer's rule: the cookie is what lasts, the code that delivers it does not. A view
+ * grant used to live as long as a share link (a day), on the grounds that a person opens it
+ * when they get to it; but what it hands over is a 30-day key to every workspace, so the code
+ * gets the short window whatever it opens. `linkTtlMinutes` may shorten it, never lengthen it.
+ */
+export declare function resolveGrantTtlMs(tunnel?: {
+    linkTtlMinutes?: number;
+}): number;
 /**
  * Redeem a link token for a session token, or return null.
  *
@@ -177,7 +194,7 @@ export declare function resolveShareTtlMs(tunnel?: {
 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.
+ * over a global credential; 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. */
@@ -188,11 +205,37 @@ export declare function takeSessionGrant(state: AuthState, session: string): Glo
 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
+ * one Caddy sets for `?t=<view key>` and checks for both keys, 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;
+export declare function globalKeyCookie(grant: GlobalGrant, keys: GlobalKeys, now?: number): string | null;
+/**
+ * Every cookie a redeemed granting link sets: the key cookie itself, and for an edit grant the
+ * view key too (Caddy can only compare a fixed value, so the box's root list and the static
+ * previews still open on the shared view key), and an expiry for any raw edit key cookie an
+ * earlier version left in the browser.
+ */
+export declare function grantCookies(grant: GlobalGrant, keys: GlobalKeys, now?: number): string[];
+/** The cookie holding an edit device pass, across the preview domain. */
+export declare const GLOBAL_PASS_COOKIE = "tosi_pass";
+export interface DevicePass {
+    device: string;
+    domain: string;
+    label: string;
+    /** ms since the epoch */
+    exp: number;
+}
+/** Device ids: ten lowercase letters and digits, safe in a shell line and a file name. */
+export declare const DEVICE_ID_PATTERN: RegExp;
+export declare function mintDeviceId(): string;
+/** A device label: what `--label` may say, kept to characters any listing can print. */
+export declare function cleanDeviceLabel(label: unknown): string;
+export declare function signPass(pass: DevicePass, key: string): string;
+/** The pass in this cookie header, if it is signed with `key` and unexpired; else null. */
+export declare function readPass(cookieHeader: string | null | undefined, key: string | undefined, now: number): DevicePass | null;
+/** End every session minted from a pass for a device that is now revoked. */
+export declare function revokeDeviceSessions(state: AuthState, revoked: ReadonlySet<string>): number;
 /**
  * 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
@@ -416,19 +459,26 @@ export declare function sessionMayWrite(state: AuthState, token: string | null |
 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. */
+/**
+ * Caddy's cookie for the raw edit key. Browsers no longer get it (they get a device pass); a
+ * dev server presents it to read the revoked list, and a redeemed edit link expires any copy an
+ * earlier version left in a browser.
+ */
 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.
+ * live in memory). While the key cookie lasts, the next page load or same-origin request mints
+ * another, so for a key holder it is the COOKIE's lifetime that ends access, not this. Revoking a
+ * device ends the sessions its pass opened within a minute (revokeDeviceSessions); 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.
+ * one: per page load, and per request from a page left open across a restart until its first
+ * renewed cookie lands. So this bounds a browser stuck reloading, not an attacker.
  */
 export declare const MAX_SESSIONS = 1000;
 export interface GlobalKeys {
@@ -457,8 +507,17 @@ export declare function resolveGlobalKeys(setting: unknown, secrets: {
     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;
+/** What a device pass needs checked besides its signature: the time, and the revoked list. */
+export interface PassCheck {
+    now: number;
+    /** Revoked device ids, or null when the list could not be read: then no pass is honoured. */
+    revoked: ReadonlySet<string> | null;
+}
+/**
+ * What the global-key cookies on a request grant: an edit pass wins over the view key. The raw
+ * edit key in a cookie is no longer accepted: it could not be revoked per device.
+ */
+export declare function globalKeyAccess(cookieHeader: string | null | undefined, keys: GlobalKeys, check?: PassCheck): '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;
@@ -472,16 +531,52 @@ export declare function isNavigation(request: {
  * 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.
  */
+interface KeyOpts {
+    auth: AuthState;
+    keys: GlobalKeys;
+    now: number;
+    /** See PassCheck: omitted or null, no edit pass is honoured. */
+    revoked?: ReadonlySet<string> | null;
+}
 export declare function globalKeyExchange(request: {
     method: string;
     headers: {
         get(name: string): string | null;
     };
-}, opts: {
+}, opts: KeyOpts & {
     viaTunnel: boolean;
-    auth: AuthState;
-    keys: GlobalKeys;
-    now: number;
+}): 'edit' | 'view' | null;
+/**
+ * Should a request from this workspace's OWN page, that is not a page load, trade a global key
+ * for a session in place?
+ *
+ * Sessions live in memory, and `bun start` restarts the process whenever a file in its import
+ * graph changes, which includes every component source and so every doc-comment example. Save
+ * to source writes exactly such a file. So the save restarts the server, and the next save from
+ * the same page arrived holding a dead session and was told "This workspace needs an invite
+ * link". A reload would have exchanged the key, and lost the unsaved edit (the maintainer,
+ * 2026-10-20: a restart must not reset a key holder).
+ *
+ * The answer is the page-load exchange's, with two extra conditions, because no redirect is
+ * involved: the session is issued and used on this same request.
+ * - Positive evidence that the request comes from this origin: `Sec-Fetch-Site: same-origin`,
+ *   or, from a browser that sends no fetch metadata, an `Origin` that is this host. Absence of
+ *   both is NOT enough here (unlike `isSameOriginRequest`, which allows it for curl and our
+ *   own CLI, whose requests are not a browser spending an ambient cookie): every host under the preview domain
+ *   is the same site and receives the key cookie, so a sibling workspace's page must not be
+ *   able to spend it here.
+ *
+ * A WebSocket upgrade (the haltija bridge) qualifies too; browsers send `Origin` and
+ * `Sec-Fetch-Site` on the handshake, and the 101 carries the cookie.
+ */
+export declare function globalKeyRefresh(request: {
+    method: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}, opts: KeyOpts & {
+    viaTunnel: boolean;
+    host: string;
 }): 'edit' | 'view' | null;
 /**
  * The origin allowed to read this workspace's liveness answer: the box's own list.
@@ -600,3 +695,4 @@ export declare function resolveLinkArrival(opts: {
     redeemed: string | null;
     hasValidSession: boolean;
 }): LinkArrival;
+export {};