tosijs-ui 1.16.32 → 1.16.34

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 1.16.34
+
+Spinning icons keep spinning while the page is busy, which is the only time a loader is on
+screen. Nothing to change unless your CSS or script reaches inside a spin icon: see the last
+bullet.
+
+### Icons
+
+- **`spinN<Icon>` no longer freezes on a busy page** (board #3508). The rotation was started
+  with `el.animate()` on the `<svg>`, and WebKit animates an SVG transform on the main thread,
+  so on Safari and every iOS browser a loader stood still exactly while the page worked. It is
+  now a CSS animation on an HTML element around a static svg, which the browser can run off the
+  main thread.
+- **A spin icon turns as a clone and inside a shadow root.** The animation is in the markup
+  rather than started by script, so `cloneNode` and list templates keep it. The spinning
+  element is a `<tosi-icon-spin>`, which adds one shared stylesheet to the document or shadow
+  root it lands in, because a document-level `@keyframes` does not reach a shadow root in
+  Chromium or Firefox. Nothing is added inside the icon, so a button holding a spinner still
+  has its caption as its `textContent`.
+- **Spin icons hold still under `prefers-reduced-motion: reduce`**, as the live-example spinner
+  already did. Shipped in a patch on the maintainer's call: it is an accessibility default. The
+  rules are wrapped in `:where()`, so a rule of yours that names `tosi-icon-spin` overrides
+  them; for an icon inside a component's shadow root, that rule has to be in the shadow root.
+- **The DOM inside a spin icon changed.** It was `span.tosi-icon-composite > svg`; it is now
+  `span.tosi-icon-composite > tosi-icon-spin > svg`, with a span carrying the suffix transform
+  around `<tosi-icon-spin>` when the name has `s`/`x`/`y`/`r`/`f` suffixes
+  (`spin90Loader40s_30x`). That keeps an offset icon spinning about its own centre, as before,
+  and both hold the svg's size in a taller flex container so the icon does not orbit. Speed
+  and direction are the `--tosi-icon-spin-duration` and `--tosi-icon-spin-direction` custom
+  properties on `<tosi-icon-spin>`.
+
+## 1.16.33
+
+Typing a link on a headset gets much shorter, and a mistyped code no longer sends you off to mint
+a new one. Both are tunnel changes; nothing an adopter's product sees changes. **To get short
+links, re-run `tosijs-caddy-install --go`** on your preview box: until you do, the tunnel says
+the box does not serve them yet and prints the long link as before.
+
+### Tunnel
+
+- **Short links.** `tosijs-tunnel --link --global`, and the links it prints at start, also print
+  `https://<preview domain>/<CODE>`, with the code in two groups of four (`RCQA MHFX`), which
+  are easier to hold in your head than eight letters. The tunnel records which workspace minted
+  the code on the box (`/srv/preview/_codes/<CODE>`), sweeps codes past their five minutes, and
+  reads it back through Caddy before printing it, so a box whose Caddyfile predates short links
+  gets a note instead of a dead link. The code is still redeemed, once and rate-limited, by the
+  dev server that minted it.
+- **A box for a link or a code on the box's own pages.** The page a browser without the preview
+  cookie sees (now `deploy/gate-page.html`, embedded by `tosijs-caddy-install`) has a box that
+  takes a code, in any case and with spaces, or a whole link. A code finds the workspace that
+  minted it; a link is followed only to a host under the preview domain. The root list has the
+  same box, since a browser that still holds the view cookie lands there rather than on the gate.
+  On a headset, open `dev.example.com` (letters and dots only) and type the eight letters.
+- **What short links cost.** The box answers "is this a live code?" without the dev server's
+  rate limit, so a guesser can test codes there faster: about 1 in 100,000 odds at a sustained
+  2,000 requests a second for a code's five minutes, against 1 in 18 million at the workspace.
+  The maintainer accepted that for headset typing. `doc-site-system.md` has the details.
+- **A mistyped code says so.** A code that matches no live link now gets the code box back,
+  naming the code and with it filled in, so a one-letter typo is a one-letter fix. That holds on
+  a workspace's own page and on the box's (a short link with a typo, or a code typed there). A spent code
+  still reads "has been used", and an expired one says it has expired; through 1.16.32 all three
+  read "has been used" (board #3505).
+
 ## 1.16.32
 
 Two new components, a doc search that ranks, and live examples whose toolbar no longer covers

package/bin/caddy-install.ts

@@ -37,6 +37,7 @@ Three deliberate properties:
 
 import { existsSync, readFileSync } from 'fs'
 import {
+  embedGatePage,
   parseArgv,
   resolvePreviewHost,
   resolveSiteConfig,
@@ -93,7 +94,18 @@ if (!existsSync(templatePath)) {
   process.exit(1)
 }
 
-const template = readFileSync(templatePath, 'utf8')
+/*
+`__GATE_PAGE__` is the page a browser without the preview cookie sees (deploy/gate-page.html,
+with its box for a link or a code). It is not a secret, so it is embedded here rather than on the
+box. A template of your own that names it gets the shipped page.
+*/
+const template = embedGatePage(
+  readFileSync(templatePath, 'utf8'),
+  readFileSync(
+    new URL('../deploy/gate-page.html', import.meta.url).pathname,
+    'utf8'
+  )
+)
 
 // The template is delivered inside a quoted heredoc, so it is copied verbatim with no shell
 // expansion. A template containing the delimiter would truncate the file silently — refuse

package/bin/resolve-site-config.ts

@@ -191,6 +191,63 @@ export function deviceRegistryLine(device: {
   ].join('\t')
 }
 
+/*
+SHORT LINKS (board #3504). A single-use code is typed on a headset, where `/`, `=` and digits are
+each a trip to another keyboard page, so the box also answers `https://<domain>/<CODE>` and a box
+on its gate and root pages. For that it has to know which workspace minted the code:
+`tosijs-tunnel` writes `<root>/_codes/<CODE>` holding the full link, and the gate page
+(deploy/gate-page.html) reads it back. The code is still redeemed by the dev server that minted
+it. Files older than the code's five-minute life are swept on the next write; one left over
+only points at a code that no longer redeems.
+
+Both values go into a shell command, so both are checked against narrow patterns, and a pair
+that fails is not written (the long link still works).
+*/
+const SHORT_CODE = /^[ABCDEFGHJKMNPQRSTVWXYZ]{8}$/
+const SHORT_LINK_TARGET = /^https:\/\/[a-z0-9.-]+\/\?t=[A-Z]{8}$/
+
+export function shortCodeScript(
+  root: string,
+  code: string,
+  link: string
+): string | null {
+  if (!SHORT_CODE.test(code) || !SHORT_LINK_TARGET.test(link)) return null
+  if (!link.endsWith(`?t=${code}`)) return null
+  if (!/^\/[\w./-]+$/.test(root)) return null
+  const dir = `${root}/_codes`
+  return (
+    `mkdir -p ${dir} && chmod 755 ${dir} && ` +
+    `find ${dir} -type f -mmin +5 -delete; ` +
+    `printf '%s\\n' '${link}' > ${dir}/${code} && chmod 644 ${dir}/${code}`
+  )
+}
+
+/** `ABCD EFGH`: two groups of four are easier to hold in your head than eight letters. */
+export function groupCode(code: string): string {
+  return code.length === 8 ? `${code.slice(0, 4)} ${code.slice(4)}` : code
+}
+
+/*
+The gate page is a file (deploy/gate-page.html) so it can be read, edited and tested as HTML, and
+is embedded into the Caddyfile's `respond "__GATE_PAGE__"` at install time. Inside a Caddyfile
+quoted string only `\"` is an escape, so a double quote is all that needs escaping; its HTML
+comments are dropped (they are for whoever edits it, and they mention placeholder names Caddy
+would expand).
+*/
+export function embedGatePage(template: string, page: string): string {
+  const stripped = page.replace(/<!--[\s\S]*?-->\n?/g, '').trim()
+  /*
+  Embedded BEFORE the installer substitutes the keys, so a key placeholder here would be filled
+  with the real key and served to anyone without a cookie. The installer's leftover-placeholder
+  guard cannot see that: by then it is a key, not a placeholder.
+  */
+  if (/__PREVIEW_(EDIT_)?TOKEN__/.test(stripped))
+    throw new Error(
+      'the gate page names a key placeholder (__PREVIEW_TOKEN__ / __PREVIEW_EDIT_TOKEN__), which would publish the key on a page anyone can load'
+    )
+  return template.split('__GATE_PAGE__').join(stripped.replace(/"/g, '\\"'))
+}
+
 export interface DeviceRecord {
   id: string
   issued: string

package/bin/tunnel.ts

@@ -45,6 +45,8 @@ import {
   resolveTunnelLocalPort,
   parseArgv,
   deviceRegistryLine,
+  groupCode,
+  shortCodeScript,
   parseDeviceListing,
   DEVICE_LISTING_SEPARATOR,
   DEVICE_ID_PATTERN,
@@ -171,7 +173,7 @@ holds too; `notes` says why any other is missing.
 async function globalLinks(
   kinds: ('edit' | 'view')[] = ['edit', 'view']
 ): Promise<{
-  links: { kind: 'edit' | 'view'; url: string }[]
+  links: { kind: 'edit' | 'view'; url: string; short?: string }[]
   notes: string[]
 }> {
   const local = resolveGlobalKeys(preview?.tunnel?.globalKeys, {
@@ -183,7 +185,7 @@ async function globalLinks(
   const box =
     local.keys.edit || local.keys.view ? await previewBoxKeys(host!) : {}
   const plan = planGlobalLinks(local, box)
-  const links: { kind: 'edit' | 'view'; url: string }[] = []
+  const links: { kind: 'edit' | 'view'; url: string; short?: string }[] = []
   for (const kind of plan.kinds.filter((k) => kinds.includes(k))) {
     const label = flag('label')
     const answer = await askForLink(
@@ -206,8 +208,16 @@ async function globalLinks(
         continue
       }
     }
-    if (answer.url) links.push({ kind, url: answer.url })
-    else
+    if (answer.url) {
+      const short = await registerShortCode(answer.url, plan.domain!)
+      if (!short)
+        plan.notes.push(
+          `no short link (${
+            shortLinkProblem || `could not record it on ${host}`
+          }); the full link still works`
+        )
+      links.push({ kind, url: answer.url, short })
+    } 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\``
@@ -244,6 +254,41 @@ async function registerDevice(device: {
   return run.exitCode === 0
 }
 
+/*
+SHORT LINKS (board #3504): record which workspace a code belongs to, so `https://<domain>/<CODE>`
+(or the code typed into the box on the gate and root pages) finds it. See shortCodeScript.
+Returns the short link, or undefined if it could not be recorded.
+*/
+let shortLinkProblem = ''
+async function registerShortCode(
+  url: string,
+  domain: string
+): Promise<string | undefined> {
+  const code = new URL(url).searchParams.get('t') ?? ''
+  const script = shortCodeScript(devicesRoot(), code, url)
+  if (!script) {
+    shortLinkProblem = `${url} is not a link the box can shorten`
+    return undefined
+  }
+  const run =
+    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host!} ${script}`
+      .nothrow()
+      .quiet()
+  if (run.exitCode !== 0) return undefined
+  // Read it back through Caddy: a box whose Caddyfile predates short links answers with its
+  // gate, and a short link printed over that would lead nowhere.
+  const served = await fetch(`https://${domain}/_codes/${code}`, {
+    signal: AbortSignal.timeout(5000),
+  })
+    .then((res) => (res.ok ? res.text() : ''))
+    .catch(() => '')
+  if (served.trim() !== url) {
+    shortLinkProblem = `the box's Caddyfile does not serve short links yet: run \`tosijs-caddy-install --go\``
+    return undefined
+  }
+  return `https://${domain}/${code}`
+}
+
 /*
 Say where this is going, and where the address came from, BEFORE acting on it.
 
@@ -378,10 +423,12 @@ if (has('link')) {
   break the promise `--share` makes to the person you send it to.
   */
   let url: string
+  let short: string | undefined
   if (has('global')) {
     const global = await globalLinks([share ? 'view' : 'edit'])
     for (const note of global.notes) console.log(`note: ${note}`)
     url = global.links[0]?.url ?? ''
+    short = global.links[0]?.short
     if (!url) {
       console.error('\nNo single-use global link (see the note above).\n')
       process.exit(1)
@@ -419,7 +466,14 @@ if (has('link')) {
         ? 'Share link (READ ONLY)'
         : 'Edit link'
     }:\n   ${url}\n` +
-      (code ? `\n   code:  ${code}   (case-insensitive)\n` : '')
+      (short ? `   ${short}   (the same link, shorter)\n` : '') +
+      (code
+        ? `\n   code:  ${groupCode(code)}   (case-insensitive${
+            short
+              ? `; or open ${new URL(short).host} and type it into the box`
+              : ''
+          })\n`
+        : '')
   )
 
   /*
@@ -654,8 +708,13 @@ if (publicUrl) {
       `\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 { kind, url, short } of startLinks.links) {
+      const code = new URL(url).searchParams.get('t') ?? ''
+      console.log(
+        `   ${kind}: ${url}${kind === 'view' ? '  (read-only)' : ''}` +
+          (short ? `\n         ${short}   code ${groupCode(code)}` : '')
+      )
+    }
   }
   for (const note of startLinks?.notes ?? []) console.log(`   note: ${note}`)
 }

package/deploy/Caddyfile

@@ -93,10 +93,11 @@
 		not header_regexp Cookie "(^|; *)tosi_preview=__PREVIEW_TOKEN__(;|$)"
 		not header_regexp Cookie "(^|; *)tosi_edit=__PREVIEW_EDIT_TOKEN__(;|$)"
 	}
+	# deploy/gate-page.html, embedded by the installer: a box that takes a link or a code.
 	handle @unauthed {
 		header Content-Type "text/html; charset=utf-8"
 		header Cache-Control "no-store"
-		respond "<!doctype html><meta charset=utf-8><title>Link required</title><style>body{font:16px/1.6 system-ui;margin:15vh auto;max-width:30rem;padding:0 1.5rem;color:#222}@media(prefers-color-scheme:dark){body{background:#16171a;color:#e8e8ea}}</style><h1>This preview needs an invite link</h1><p>Ask for one — it sets a cookie and then you can browse normally.</p>" 401
+		respond "__GATE_PAGE__" 401
 	}
 
 	file_server
@@ -191,6 +192,57 @@
 # send someone should still show what you meant an hour later.
 {{PREVIEW_DOMAIN}} {
 	root * /srv/preview/_index
+
+	# SHORT LINKS (board #3504): `https://{{PREVIEW_DOMAIN}}/<CODE>` instead of the workspace's
+	# own `https://<label>.edit.{{PREVIEW_DOMAIN}}/?t=<CODE>`, typed on a headset keyboard.
+	# `tosijs-tunnel --link --global` writes /srv/preview/_codes/<CODE> holding the full link;
+	# the gate page (deploy/gate-page.html) reads it and goes there. Both are answered BEFORE the
+	# cookie gate, because a browser that needs a link has no cookie yet. Neither grants anything:
+	# the code is still redeemed by the dev server that minted it, once, rate-limited.
+	#
+	# What this does cost: the box answers "is this a live code?" without the dev server's rate
+	# limit. Codes are 8 of 22 letters (35.7 bits) and live five minutes, so even sustained
+	# hammering finds one with odds around 1 in 100,000; the maintainer accepted that for
+	# typing a short link on a headset (2026-10-25).
+	#
+	# A missing code is answered with an explicit 404 rather than by file_server, whose error would
+	# reach preview_site's handle_errors: that rewrites to /index.html, and served the cookie-gated
+	# root list to a visitor with no cookie would be the leak this gate exists to prevent.
+	@codefile {
+		path_regexp ^/_codes/[A-Z]{8}$
+		file {
+			root /srv/preview
+		}
+	}
+	handle @codefile {
+		root * /srv/preview
+		header Cache-Control "no-store"
+		header Content-Type "text/plain; charset=utf-8"
+		file_server
+	}
+	handle /_codes/* {
+		header Cache-Control "no-store"
+		respond "" 404
+	}
+	@code {
+		path_regexp ^/[A-Za-z2568-]{8,12}/?$
+	}
+	@codequery {
+		path /
+		query t=*
+		not query t=__PREVIEW_TOKEN__
+	}
+	handle @code {
+		header Content-Type "text/html; charset=utf-8"
+		header Cache-Control "no-store"
+		respond "__GATE_PAGE__" 200
+	}
+	handle @codequery {
+		header Content-Type "text/html; charset=utf-8"
+		header Cache-Control "no-store"
+		respond "__GATE_PAGE__" 200
+	}
+
 	import preview_site
 }
 

package/deploy/build-index.sh

@@ -139,10 +139,21 @@ cat > "$OUT/index.html" <<HTML
 	.access.edit { color:#2a8a3e; }
 	.access.none { font-weight:400; }
 	footer { color:var(--dim); font-size:.8rem; margin-top:2.5rem; }
+	form.code { display:flex; flex-wrap:wrap; align-items:center; gap:.5rem; margin:0 0 2rem 3.75rem; }
+	form.code input, form.code button { font:inherit; padding:.35rem .6rem; border:1px solid var(--line); border-radius:6px; background:var(--card); color:inherit; }
+	form.code input { letter-spacing:.08em; width:11em; }
 </style>
 <main>
 	<header>$ICON<h1>tosijs previews</h1></header>
 	<p class="sub">Live workspaces, and the builds deployed here.</p>
+	<!-- A code from \`tosijs-tunnel --link --global\`: \`/?t=<code>\` is answered by the gate page,
+	     which finds the workspace that minted it (deploy/Caddyfile, short links). A browser that
+	     already holds the view cookie lands HERE, so this page needs the box as much as the gate. -->
+	<form class="code" action="/" method="get">
+		<label for="code">Have a code?</label>
+		<input id="code" name="t" placeholder="eight letters" inputmode="latin" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
+		<button>Go</button>
+	</form>
 	$(if [ -n "$live" ]; then echo "<section id=\"live\"><h2>Live workspaces</h2><ul>$live
 	</ul></section>"; fi)
 	<h2>Deployed builds</h2>

package/deploy/gate-page.html

@@ -0,0 +1,178 @@
+<!DOCTYPE html>
+<!--
+The page a browser without the preview cookie sees, and the page that redeems a short link.
+
+Embedded into the Caddyfile at install time (`__GATE_PAGE__`, by `tosijs-caddy-install`), so it
+must survive being a Caddyfile string:
+  - a double quote is escaped for it, nothing else is, so never write a backslash before one;
+  - `{name}` with no space inside is read as a Caddy placeholder (`{path}`, `{host}`, `{query}`
+    are real ones), so every brace below has whitespace after it.
+`bin/caddy-install.test.ts` checks both.
+
+Short links (board #3504): `tosijs-tunnel --link --global` writes `/_codes/<CODE>` on the box,
+holding the workspace link that code belongs to. `https://<domain>/<CODE>` (or `/?t=<CODE>`, or
+the code typed into the box below) lands here, which looks the code up and goes there. The code
+is still redeemed, single-use and rate-limited, by the dev server that minted it.
+-->
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="referrer" content="no-referrer" />
+<title>Link required</title>
+<style>
+  body {
+    font: 16px/1.6 system-ui;
+    margin: 15vh auto;
+    max-width: 30rem;
+    padding: 0 1.5rem;
+    color: #222;
+  }
+  form {
+    display: flex;
+    gap: 0.5em;
+    margin: 1.5em 0;
+  }
+  input {
+    flex: 1;
+    font: inherit;
+    font-size: 1.25em;
+    letter-spacing: 0.08em;
+    padding: 0.4em 0.6em;
+    border: 1px solid #8888;
+    border-radius: 6px;
+    min-width: 0;
+  }
+  button {
+    font: inherit;
+    font-size: 1.25em;
+    padding: 0.4em 1em;
+    border: 0;
+    border-radius: 6px;
+    background: #2563eb;
+    color: white;
+  }
+  #msg.problem {
+    color: #b91c1c;
+  }
+  @media (prefers-color-scheme: dark) {
+    body {
+      background: #16171a;
+      color: #e8e8ea;
+    }
+    input {
+      background: #222;
+      color: inherit;
+    }
+    #msg.problem {
+      color: #f87171;
+    }
+  }
+</style>
+<h1>This preview needs an invite link</h1>
+<p id="msg">
+  Open the link you were given, or type its code (or paste the whole link) here.
+</p>
+<form id="go">
+  <input
+    id="t"
+    aria-label="link or code"
+    placeholder="link or code"
+    inputmode="latin"
+    autocomplete="off"
+    autocapitalize="off"
+    autocorrect="off"
+    spellcheck="false"
+  />
+  <button>Go</button>
+</form>
+<script>
+  ;(() => {
+    const DOMAIN = '{{PREVIEW_DOMAIN}}'
+    const CODE = /^[ABCDEFGHJKMNPQRSTVWXYZ]{8}$/
+
+    // The same folding as normalizeLinkToken in tosijs-ui's dev-auth.ts (the test compares them).
+    const normalize = (typed) =>
+      typed
+        .replace(/[\s-]/g, '')
+        .toUpperCase()
+        .replace(/5/g, 'S')
+        .replace(/2/g, 'Z')
+        .replace(/8/g, 'B')
+        .replace(/6/g, 'G')
+
+    const ours = (host) => host === DOMAIN || host.endsWith('.' + DOMAIN)
+    const msg = document.getElementById('msg')
+    const say = (text) => {
+      msg.textContent = text
+      msg.className = 'problem'
+    }
+
+    async function redeem(code) {
+      // Codes are looked up at the root, so send any other preview host there.
+      if (location.hostname !== DOMAIN) {
+        location.href = 'https://' + DOMAIN + '/' + code
+        return
+      }
+      msg.textContent = 'Opening ' + code + '…'
+      let target = null
+      try {
+        const res = await fetch('/_codes/' + code, { cache: 'no-store' })
+        if (res.ok) target = new URL((await res.text()).trim())
+      } catch (e) {}
+      if (!target)
+        return say(
+          'No live link has the code ' +
+            code +
+            '. Check it for a typo and try again: a code is eight letters, and case does not matter.'
+        )
+      if (target.protocol !== 'https:' || !ours(target.hostname))
+        return say(
+          'That code points outside ' + DOMAIN + ', so it was not followed.'
+        )
+      location.replace(target.href)
+    }
+
+    function go(typed) {
+      typed = typed.trim()
+      if (!typed) return
+      // A link has a dot, slash or colon; a code never does.
+      if (/[./:]/.test(typed)) {
+        let url = null
+        try {
+          url = new URL(
+            /^https?:\/\//i.test(typed) ? typed : 'https://' + typed
+          )
+        } catch (e) {}
+        if (!url || !ours(url.hostname))
+          return say('That link is not under ' + DOMAIN + '.')
+        url.protocol = 'https:'
+        location.href = url.href
+        return
+      }
+      const code = normalize(typed)
+      if (!CODE.test(code))
+        return say(typed + ' is not a code: a code is eight letters.')
+      redeem(code)
+    }
+
+    document.getElementById('go').addEventListener('submit', (event) => {
+      event.preventDefault()
+      go(document.getElementById('t').value)
+    })
+
+    // Arrived with a code: /<CODE> at the root, or ?t=<CODE> on any preview host. Anything else
+    // (a page path on a static preview, a stale key) just shows the box.
+    const query = new URLSearchParams(location.search).get('t')
+    const path =
+      location.hostname === DOMAIN
+        ? location.pathname.replace(/^\/+|\/+$/g, '')
+        : ''
+    const arrived = normalize(query || path)
+    if (CODE.test(arrived)) {
+      // In the box too, so a typo in the URL is a one-letter fix (board #3505).
+      const box = document.getElementById('t')
+      box.value = arrived
+      box.focus()
+      redeem(arrived)
+    }
+  })()
+</script>

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

@@ -114,7 +114,17 @@ export interface AuthState {
     sessionGrants: Map<string, GlobalGrant>;
     /** Sessions minted from a device pass → that device, so revoking it ends them too. */
     sessionDevices: Map<string, string>;
+    /**
+     * Link codes that have left `links`, folded, with why and until when they are remembered:
+     * so a refused code can be told apart as mistyped, spent or expired (see linkRejection).
+     */
+    retired: Map<string, {
+        why: 'used' | 'expired';
+        until: number;
+    }>;
 }
+/** How long a spent or expired code is remembered, for the message only. */
+export declare const RETIRED_LINK_MEMORY_MS: number;
 /**
  * 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)
@@ -192,6 +202,7 @@ export declare function resolveGrantTtlMs(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;
+export declare function linkRejection(state: AuthState, token: string, now: number): 'used' | 'expired' | 'unknown';
 /**
  * How many unspent granting links may exist at once. Each is a live code that, guessed, hands
  * over a global credential; a bound keeps the guessing odds where a handful of real links put them.

package/dist/doc-system/site/dev-auth.js

@@ -199,6 +199,8 @@ export function safeEqual(a, b) {
         return false;
     return timingSafeEqual(ab, bb);
 }
+/** How long a spent or expired code is remembered, for the message only. */
+export const RETIRED_LINK_MEMORY_MS = 60 * 60 * 1000;
 export function createAuthState() {
     return {
         links: new Map(),
@@ -207,6 +209,7 @@ export function createAuthState() {
         grants: new Map(),
         sessionGrants: new Map(),
         sessionDevices: new Map(),
+        retired: new Map(),
     };
 }
 /** Drop anything expired. Called on every use so the maps cannot grow without bound. */
@@ -216,7 +219,11 @@ export function prune(state, now) {
             state.links.delete(t);
             state.readOnly.delete(t);
             state.grants.delete(t);
+            retire(state, t, 'expired', now);
         }
+    for (const [t, { until }] of state.retired)
+        if (until <= now)
+            state.retired.delete(t);
     for (const [t, exp] of state.sessions)
         if (exp <= now) {
             state.sessions.delete(t);
@@ -313,6 +320,7 @@ export function redeemLink(state, token, now, policy = 'window') {
         state.links.delete(matched);
         state.readOnly.delete(matched);
         state.grants.delete(matched);
+        retire(state, matched, 'used', now);
     }
     /*
     The capability rides from the link to the session it mints, and so does the shorter horizon.
@@ -325,6 +333,24 @@ export function redeemLink(state, token, now, policy = 'window') {
         state.sessionGrants.set(session, grant);
     return session;
 }
+function retire(state, token, why, now) {
+    state.retired.set(normalizeLinkToken(token), {
+        why,
+        until: now + RETIRED_LINK_MEMORY_MS,
+    });
+}
+/*
+Why a code was refused, so the page can say the useful thing (board #3505). A headset user who
+mistyped one letter was told the code "has been used", and went off to mint a new link when
+retyping would have done. Mistyped, spent and expired now read differently.
+
+This tells a guesser nothing useful: "used" and "expired" are said only of codes that can no
+longer open anything, and everything else is "unknown", as before.
+*/
+export function linkRejection(state, token, now) {
+    prune(state, now);
+    return state.retired.get(normalizeLinkToken(token))?.why ?? 'unknown';
+}
 /**
  * How many unspent granting links may exist at once. Each is a live code that, guessed, hands
  * over a global credential; a bound keeps the guessing odds where a handful of real links put them.