seemore 1.10.9 → 1.11.0

package/dist/index.d.ts

@@ -106,14 +106,32 @@ declare const configSchema: z.ZodObject<{
         "export-html": "export-html";
     }>>>;
     exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    auth: z.ZodPreprocess<z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        remember: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>, unknown>;
 }, z.core.$strip>;
 /** What a user writes in `seemore.config.ts`. */
-type SeemoreConfig = Omit<z.input<typeof configSchema>, 'features' | 'theme' | 'search'> & {
+type SeemoreConfig = Omit<z.input<typeof configSchema>, 'features' | 'theme' | 'search' | 'auth'> & {
     /** An array of {@link FeatureFlag} also works, but the map is the documented form. */
     features?: FeatureMap | FeatureFlag[];
     theme?: Theme;
     search?: z.input<typeof searchSchema>;
+    /**
+     * Password protection: `seemore build` encrypts the site, and visitors unlock it with the
+     * password. The password itself comes from `SEEMORE_PASSWORD` at build time, never from here.
+     */
+    auth?: boolean | AuthOptions;
 };
+interface AuthOptions {
+    /**
+     * A stable name the key is derived from; defaults to `title`. Set it if you expect to
+     * rename the site, so visitors stay unlocked. Changing it logs everyone out.
+     */
+    id?: string;
+    /** How long a visitor stays unlocked after their last visit: `'12h'` or `'7d'`. Default `'1d'`. */
+    remember?: `${number}h` | `${number}d`;
+}
 type SearchConfig = {
     provider: 'static';
 } | {
@@ -152,6 +170,11 @@ interface ResolvedSeemoreConfig {
     search: SearchConfig;
     pageActions: ActionId[];
     exclude: string[];
+    /** Present when the site is password-protected. Nothing here is ever sent to the browser. */
+    auth?: {
+        id: string;
+        remember: number;
+    };
     /** Directory the config was resolved from — relative paths in it hang off this. */
     root: string;
     /** Absolute path of the config file, when there is one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seemore",
-  "version": "1.10.9",
+  "version": "1.11.0",
   "description": "Let AI write the Markdown. Let seemore show it better — zero config documentation framework.",
   "license": "MIT",
   "type": "module",

package/src/app/entry.client.tsx

@@ -4,9 +4,22 @@ import { RouterProvider, createBrowserRouter } from 'react-router';
 import { config } from 'virtual:seemore/config';
 import { decodePath, stripBase, toBasename } from '../shared/base.js';
 import { createRouteObjects } from './router.js';
+import { onVitePreloadError } from './lib/chunkReload.js';
 import { preloadPage } from './lib/pages.js';
 import './styles/globals.css';
 
+// Vite dispatches this when a chunk preload fails and rethrows when it is not cancelled.
+// One reload picks up the new chunk names after a deploy; the guard keeps a genuinely
+// broken chunk from looping.
+window.addEventListener('vite:preloadError', (event) => {
+  event.preventDefault();
+  try {
+    onVitePreloadError(sessionStorage, Date.now(), () => window.location.reload());
+  } catch {
+    // Storage unavailable (private mode): a reload without a guard could loop.
+  }
+});
+
 const container = document.getElementById('root');
 if (container === null) throw new Error('seemore: #root is missing from the page shell.');
 

package/src/app/layout/Header.tsx

@@ -1,9 +1,10 @@
 import { Link, useLocation } from 'react-router';
-import { Moon, PanelLeft, Search, Sun } from 'lucide-react';
+import { LogOut, Moon, PanelLeft, Search, Sun } from 'lucide-react';
 import { useSearchContext } from 'fumadocs-ui/contexts/search';
 import { SidebarTrigger } from 'fumadocs-ui/components/sidebar/base';
 import { useTheme } from 'fumadocs-ui/provider/base';
 import { config } from 'virtual:seemore/config';
+import { lockSite } from '../lib/auth.js';
 import { useSidebarCollapse } from './Sidebar.js';
 
 export function Header() {
@@ -59,6 +60,13 @@ export function Header() {
         </button>
       ) : undefined}
 
+      {/* Read directly, not through a helper, so an unprotected bundle folds this away. */}
+      {import.meta.env.SEEMORE_AUTH ? (
+        <button type="button" className="seemore-lock" aria-label="Lock site" title="Lock site" onClick={() => void lockSite()}>
+          <LogOut aria-hidden="true" />
+        </button>
+      ) : undefined}
+
       <button
         type="button"
         className="seemore-theme-toggle"

package/src/app/lib/auth.ts

@@ -0,0 +1,31 @@
+import { config } from 'virtual:seemore/config';
+import { parseManifest } from '../../shared/auth/crypto.js';
+import { LOCK_MESSAGE, MANIFEST_FILE, recordId } from '../../shared/auth/files.js';
+import { indexedDbStore } from '../../shared/auth/store.js';
+
+/**
+ * The Lock button: forget the key now rather than when `remember` runs out. The stored key is
+ * deleted, the worker drops the content key it holds in memory, and the reload lands on the
+ * lock shell.
+ */
+export async function lockSite(): Promise<void> {
+  try {
+    const response = await fetch(config.base + MANIFEST_FILE, { cache: 'no-store' });
+    const { salt } = parseManifest(await response.json()).kdf;
+    await indexedDbStore().delete(recordId(new URL(config.base, window.location.origin).href, salt));
+  } catch {
+    // The worker forgets it below as well.
+  }
+
+  const worker = navigator.serviceWorker?.controller;
+  if (worker) {
+    await new Promise<void>((resolve) => {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = () => resolve();
+      worker.postMessage({ type: LOCK_MESSAGE }, [channel.port2]);
+      setTimeout(resolve, 3000);
+    });
+  }
+
+  window.location.reload();
+}

package/src/app/lib/chunkReload.ts

@@ -0,0 +1,23 @@
+/** sessionStorage key holding the time of the last chunk-failure reload. */
+export const CHUNK_RELOAD_KEY = 'seemore:chunk-reload';
+
+/** How long one reload blocks the next: a second failure inside the window renders the error instead of looping. */
+export const CHUNK_RELOAD_WINDOW_MS = 5_000;
+
+/**
+ * One reload for a chunk that vanished under the open tab — a deploy renamed the hashed
+ * files, and the fresh HTML names the new ones. The timestamp guard allows one reload per
+ * window: a reload that lands on the same failure falls through to the error boundary
+ * instead of looping, and once the window passes, a later deploy recovers normally.
+ */
+export function onVitePreloadError(storage: Storage, now: number, reload: () => void): void {
+  const last = storage.getItem(CHUNK_RELOAD_KEY);
+  if (last !== null && now - Number(last) < CHUNK_RELOAD_WINDOW_MS) return;
+  try {
+    storage.setItem(CHUNK_RELOAD_KEY, String(now));
+  } catch {
+    // Storage blocked means no guard, and an unguarded reload could loop forever.
+    return;
+  }
+  reload();
+}

package/src/app/mdx/Pdf.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useState, type ComponentProps } from 'react';
 import { FileText } from 'lucide-react';
+import { isRemoteHref } from '../../shared/base.js';
 
 /**
  * Sibling PDFs render in the browser's own viewer.
@@ -23,6 +24,7 @@ import { FileText } from 'lucide-react';
  */
 export function Pdf({ src, title, ...props }: ComponentProps<'embed'> & { src: string }) {
   const [unsupported, setUnsupported] = useState(false);
+  const file = useDecryptedUrl(src);
 
   useEffect(() => {
     const noPdfViewerApi = 'pdfViewerEnabled' in navigator && !navigator.pdfViewerEnabled;
@@ -34,8 +36,9 @@ export function Pdf({ src, title, ...props }: ComponentProps<'embed'> & { src: s
 
   return (
     <span className={unsupported ? 'seemore-pdf seemore-pdf-unsupported' : 'seemore-pdf'}>
-      <embed src={src} type="application/pdf" title={title} {...props} />
-      <a className="seemore-pdf-fallback" href={src} download>
+      {file === undefined ? undefined : <embed src={file} type="application/pdf" title={title} {...props} />}
+      {/* A blob URL has no file name of its own, so a protected build names the download. */}
+      <a className="seemore-pdf-fallback" href={file ?? src} download={file?.startsWith('blob:') ? src.split('/').pop() : true}>
         <FileText className="seemore-pdf-fallback-icon" aria-hidden="true" />
         <span className="seemore-pdf-fallback-title">Download {title ?? 'PDF'}</span>
       </a>
@@ -43,4 +46,37 @@ export function Pdf({ src, title, ...props }: ComponentProps<'embed'> & { src: s
   );
 }
 
+/**
+ * The URL to hand `<embed>`. On a password-protected build the file on the host is ciphertext,
+ * and browsers load `<embed>` without going through the service worker that decrypts — so the
+ * PDF is fetched first, which does go through it, and embedded as a blob. The raw address is
+ * never embedded: WebKit caches that ciphertext response and serves it to later fetches too.
+ */
+function useDecryptedUrl(src: string): string | undefined {
+  // A remote PDF is not on this host, so it was never encrypted — and a cross-origin fetch of
+  // it would usually be refused anyway.
+  const encrypted = import.meta.env.SEEMORE_AUTH && !isRemoteHref(src);
+  const [url, setUrl] = useState<string | undefined>(encrypted ? undefined : src);
+
+  useEffect(() => {
+    if (!encrypted) return;
+    let revoked = false;
+    let blobUrl: string | undefined;
+    void fetch(src)
+      .then((response) => (response.ok ? response.blob() : Promise.reject(new Error(String(response.status)))))
+      .then((blob) => {
+        if (revoked) return;
+        blobUrl = URL.createObjectURL(blob.type === 'application/pdf' ? blob : new Blob([blob], { type: 'application/pdf' }));
+        setUrl(blobUrl);
+      })
+      .catch(() => undefined);
+    return () => {
+      revoked = true;
+      if (blobUrl !== undefined) URL.revokeObjectURL(blobUrl);
+    };
+  }, [src, encrypted]);
+
+  return url;
+}
+
 export default Pdf;

package/src/app/styles/globals.css

@@ -62,7 +62,7 @@
   }
 
   .seemore-search-trigger {
-    @apply ms-auto inline-flex shrink-0 items-center gap-2 rounded-lg border border-fd-border p-2 text-sm text-fd-muted-foreground sm:px-3 sm:py-1.5;
+    @apply ms-auto inline-flex shrink-0 cursor-pointer items-center gap-2 rounded-lg border border-fd-border p-2 text-sm text-fd-muted-foreground sm:px-3 sm:py-1.5;
   }
 
   /* Icon only where there is no room for the label. */
@@ -75,7 +75,8 @@
     @apply rounded border border-fd-border px-1 text-xs;
   }
 
-  .seemore-theme-toggle {
+  .seemore-theme-toggle,
+  .seemore-lock {
     @apply shrink-0;
   }
 
@@ -103,8 +104,9 @@
     @apply h-4 w-4 animate-spin rounded-full border-2 border-fd-muted-foreground/30 border-t-fd-muted-foreground;
   }
 
-  .seemore-theme-toggle {
-    @apply rounded-lg border border-fd-border p-2;
+  .seemore-theme-toggle,
+  .seemore-lock {
+    @apply cursor-pointer rounded-lg border border-fd-border p-2;
   }
 
   .seemore-icon-dark {

package/src/app/virtual.d.ts

@@ -15,3 +15,8 @@ declare module 'virtual:seemore/routes' {
 declare module 'virtual:seemore/config' {
   export const config: import('../shared/types.js').ClientConfig;
 }
+
+interface ImportMetaEnv {
+  /** Defined by the client build: whether the site is password-protected (`auth`). */
+  readonly SEEMORE_AUTH?: boolean;
+}

package/src/shared/auth/crypto.ts

@@ -0,0 +1,190 @@
+/**
+ * Password protection's cryptography.
+ *
+ * All of it is WebCrypto — `globalThis.crypto.subtle` exists in the browser, in a service
+ * worker and in Node ≥ 20 — so the build that encrypts and the browser that decrypts share
+ * this one implementation.
+ *
+ * Envelope encryption: the password derives a key-encryption key (KEK), which wraps a random
+ * content key made fresh by every build. Visitors keep the KEK, so a deploy with the same
+ * password never logs them out, and old ciphertext can never be mixed with new.
+ */
+
+export const KDF_ITERATIONS = 600_000;
+
+/** `SMP1`: the first four bytes of every encrypted file. */
+export const MAGIC = new Uint8Array([0x53, 0x4d, 0x50, 0x31]);
+
+const IV_BYTES = 12;
+const HEADER_BYTES = MAGIC.length + IV_BYTES;
+const SALT_PREFIX = 'seemore-auth-v1\0';
+
+/** `auth.json`: public, and holds nothing a guess can be checked against but the wrapped key. */
+export interface AuthManifest {
+  v: 1;
+  kdf: { name: 'PBKDF2'; hash: 'SHA-256'; iterations: number; salt: string };
+  /** The content key, wrapped with the KEK (AES-KW), base64. */
+  key: string;
+  /** Seconds a visitor stays unlocked after their last visit; 0 means only while the tab is open. */
+  remember: number;
+}
+
+const encoder = new TextEncoder();
+
+function subtle(): SubtleCrypto {
+  return globalThis.crypto.subtle;
+}
+
+/** A password typed on macOS and on Windows must derive the same key. */
+export function normalisePassword(password: string): string {
+  return password.normalize('NFC');
+}
+
+/**
+ * Derived from the site's stable name, not random: a random salt per build would log every
+ * visitor out on every deploy. Prefixed, so the digest is never a plain hash of the title.
+ */
+export async function deriveSalt(id: string): Promise<Uint8Array<ArrayBuffer>> {
+  return new Uint8Array(await subtle().digest('SHA-256', encoder.encode(SALT_PREFIX + id)));
+}
+
+/** Non-extractable: page code can use the stored key, never read its bytes. */
+export async function deriveKek(
+  password: string,
+  salt: Uint8Array<ArrayBuffer>,
+  iterations: number = KDF_ITERATIONS,
+): Promise<CryptoKey> {
+  const material = await subtle().importKey('raw', encoder.encode(normalisePassword(password)), 'PBKDF2', false, [
+    'deriveKey',
+  ]);
+  return await subtle().deriveKey(
+    { name: 'PBKDF2', hash: 'SHA-256', salt, iterations },
+    material,
+    { name: 'AES-KW', length: 256 },
+    false,
+    ['wrapKey', 'unwrapKey'],
+  );
+}
+
+export async function generateContentKey(): Promise<CryptoKey> {
+  return await subtle().generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+}
+
+export async function wrapContentKey(contentKey: CryptoKey, kek: CryptoKey): Promise<Uint8Array<ArrayBuffer>> {
+  return new Uint8Array(await subtle().wrapKey('raw', contentKey, kek, 'AES-KW'));
+}
+
+/**
+ * A wrong password fails here: AES-KW carries its own integrity check. That failure is the
+ * password check — there is no separate verifier to attack.
+ */
+export async function unwrapContentKey(wrapped: Uint8Array<ArrayBuffer>, kek: CryptoKey): Promise<CryptoKey> {
+  return await subtle().unwrapKey('raw', wrapped, kek, 'AES-KW', 'AES-GCM', false, ['decrypt']);
+}
+
+/**
+ * `SMP1 || iv || ciphertext+tag`. The file's published path is the associated data, so a
+ * ciphertext moved to another path fails authentication.
+ */
+export async function encryptFile(
+  key: CryptoKey,
+  path: string,
+  plaintext: Uint8Array<ArrayBuffer>,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const sealed = await subtle().encrypt(
+    { name: 'AES-GCM', iv, additionalData: encoder.encode(path), tagLength: 128 },
+    key,
+    plaintext,
+  );
+  const out = new Uint8Array(HEADER_BYTES + sealed.byteLength);
+  out.set(MAGIC, 0);
+  out.set(iv, MAGIC.length);
+  out.set(new Uint8Array(sealed), HEADER_BYTES);
+  return out;
+}
+
+export function isEncrypted(bytes: Uint8Array): boolean {
+  return bytes.length > HEADER_BYTES && MAGIC.every((byte, index) => bytes[index] === byte);
+}
+
+export async function decryptFile(
+  key: CryptoKey,
+  path: string,
+  bytes: Uint8Array<ArrayBuffer>,
+): Promise<Uint8Array<ArrayBuffer>> {
+  if (!isEncrypted(bytes)) throw new Error(`${path} is not an encrypted file.`);
+  const iv = bytes.slice(MAGIC.length, HEADER_BYTES);
+  const plain = await subtle().decrypt(
+    { name: 'AES-GCM', iv, additionalData: encoder.encode(path), tagLength: 128 },
+    key,
+    bytes.subarray(HEADER_BYTES),
+  );
+  return new Uint8Array(plain);
+}
+
+export interface CreatedManifest {
+  manifest: AuthManifest;
+  contentKey: CryptoKey;
+}
+
+/** A fresh content key, wrapped for this password and site name. */
+export async function createManifest(options: {
+  password: string;
+  id: string;
+  remember: number;
+  iterations?: number;
+}): Promise<CreatedManifest> {
+  const iterations = options.iterations ?? KDF_ITERATIONS;
+  const salt = await deriveSalt(options.id);
+  const kek = await deriveKek(options.password, salt, iterations);
+  const contentKey = await generateContentKey();
+
+  return {
+    contentKey,
+    manifest: {
+      v: 1,
+      kdf: { name: 'PBKDF2', hash: 'SHA-256', iterations, salt: encodeBase64(salt) },
+      key: encodeBase64(await wrapContentKey(contentKey, kek)),
+      remember: options.remember,
+    },
+  };
+}
+
+export function parseManifest(value: unknown): AuthManifest {
+  const manifest = value as Partial<AuthManifest> | null;
+  if (
+    manifest === null ||
+    typeof manifest !== 'object' ||
+    manifest.v !== 1 ||
+    typeof manifest.key !== 'string' ||
+    typeof manifest.remember !== 'number' ||
+    !(manifest.remember > 0) ||
+    typeof manifest.kdf?.salt !== 'string' ||
+    typeof manifest.kdf.iterations !== 'number'
+  ) {
+    throw new Error('auth.json is not a manifest this version of seemore can read.');
+  }
+  return manifest as AuthManifest;
+}
+
+export async function deriveManifestKek(password: string, manifest: AuthManifest): Promise<CryptoKey> {
+  return await deriveKek(password, decodeBase64(manifest.kdf.salt), manifest.kdf.iterations);
+}
+
+export async function unlockManifest(manifest: AuthManifest, kek: CryptoKey): Promise<CryptoKey> {
+  return await unwrapContentKey(decodeBase64(manifest.key), kek);
+}
+
+export function encodeBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export function decodeBase64(text: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}

package/src/shared/auth/files.ts

@@ -0,0 +1,37 @@
+/**
+ * Names shared by the build, the lock shell, the service worker and the app.
+ */
+
+/**
+ * Files a protected build writes unencrypted, relative to the base. Everything else in the
+ * output must be encrypted or the build fails; the configured favicon is added at build time.
+ */
+export const PUBLIC_FILES = [
+  'index.html',
+  '404.html',
+  '200.html',
+  '_redirects',
+  '.nojekyll',
+  '_headers',
+  'sw.js',
+  'auth.json',
+] as const;
+
+export const MANIFEST_FILE = 'auth.json';
+export const WORKER_FILE = 'sw.js';
+/** The app's HTML template: encrypted, and served by the worker for every navigation. */
+export const APP_FILE = 'app.html';
+
+/** Posted to the service worker by the Lock button, to forget the key. */
+export const LOCK_MESSAGE = 'seemore-auth:lock';
+
+/** The id of the lock shell's config element; the worker recognises the lock shell by it. */
+export const SHELL_CONFIG_ID = 'seemore-auth-config';
+
+/**
+ * The stored key's record id: the site's scope and salt, so two protected sites on one origin
+ * never read or delete each other's key.
+ */
+export function recordId(scope: string, salt: string): string {
+  return `${scope} ${salt}`;
+}

package/src/shared/auth/lock.ts

@@ -0,0 +1,152 @@
+/**
+ * The lock screen's script, bundled and inlined into the lock shell. It depends on nothing
+ * in the app bundle, which is encrypted.
+ *
+ * Register the worker, derive the KEK from the typed password, prove it by unwrapping the
+ * manifest's key, store the KEK, and reload — the worker then serves the app.
+ */
+import { deriveManifestKek, parseManifest, unlockManifest, type AuthManifest } from './crypto.js';
+import { MANIFEST_FILE, SHELL_CONFIG_ID, WORKER_FILE, recordId } from './files.js';
+import { indexedDbStore } from './store.js';
+
+interface ShellConfig {
+  base: string;
+}
+
+/** When the last hard-reload recovery ran; guards it from looping. */
+const RESUME_KEY = 'seemore-auth:resume';
+
+const element = <T extends HTMLElement>(id: string) => document.getElementById(id) as T;
+
+const config = JSON.parse(element(SHELL_CONFIG_ID).textContent ?? '{}') as ShellConfig;
+const scope = new URL(config.base, location.origin).href;
+const form = element<HTMLFormElement>('seemore-auth-form');
+const input = element<HTMLInputElement>('seemore-auth-password');
+const button = element<HTMLButtonElement>('seemore-auth-submit');
+const status = element<HTMLParagraphElement>('seemore-auth-status');
+const unsupported = element<HTMLParagraphElement>('seemore-auth-unsupported');
+const buttonLabel = button.textContent ?? 'Unlock';
+
+form.addEventListener('submit', (event) => {
+  event.preventDefault();
+  void submit();
+});
+
+void start();
+
+async function start(): Promise<void> {
+  // Not a secure context, service workers disabled, or a private window that refuses them.
+  if (!window.isSecureContext || !('serviceWorker' in navigator)) return showUnsupported();
+  try {
+    await navigator.serviceWorker.register(config.base + WORKER_FILE, { scope: config.base });
+    // A browser can accept the registration and still never keep it (service workers
+    // blocked by policy): without one, unlocking could only hang.
+    if ((await navigator.serviceWorker.getRegistration(config.base)) === undefined) return showUnsupported();
+  } catch {
+    return showUnsupported();
+  }
+
+  showForm();
+  await resumeAfterHardReload();
+}
+
+function showForm(): void {
+  unsupported.hidden = true;
+  form.hidden = false;
+  input.focus();
+}
+
+function showUnsupported(): void {
+  form.hidden = true;
+  unsupported.hidden = false;
+}
+
+async function submit(): Promise<void> {
+  button.disabled = true;
+  button.textContent = 'Unlocking…';
+  status.textContent = '';
+
+  let manifest: AuthManifest;
+  let kek: CryptoKey;
+  try {
+    manifest = await fetchManifest();
+    kek = await deriveManifestKek(input.value, manifest);
+  } catch {
+    return fail("Couldn't load this site. Check your connection and try again.");
+  }
+
+  try {
+    await unlockManifest(manifest, kek);
+  } catch {
+    return fail('Password is incorrect', true);
+  }
+
+  try {
+    await storeKey(manifest, kek);
+    await controlledByWorker();
+  } catch {
+    return fail("This browser blocked site storage, so the key can't be saved. Allow site data or try another browser.");
+  }
+
+  location.reload();
+}
+
+function fail(message: string, shake = false): void {
+  button.disabled = false;
+  button.textContent = buttonLabel;
+  status.textContent = message;
+  if (shake) {
+    form.classList.remove('lock-shake');
+    void form.offsetWidth;
+    form.classList.add('lock-shake');
+  }
+  input.focus();
+  input.select();
+}
+
+async function fetchManifest(): Promise<AuthManifest> {
+  const response = await fetch(config.base + MANIFEST_FILE, { cache: 'no-store' });
+  if (!response.ok) throw new Error(`${MANIFEST_FILE} answered ${response.status}.`);
+  return parseManifest(await response.json());
+}
+
+async function storeKey(manifest: AuthManifest, kek: CryptoKey): Promise<void> {
+  await indexedDbStore().put(recordId(scope, manifest.kdf.salt), { kek, lastSeen: Date.now() });
+}
+
+/**
+ * `clients.claim()` hands this document to the worker as it activates. If the worker was
+ * already active and this document still is not controlled, a plain reload is what hands it
+ * over, so waiting is capped.
+ */
+async function controlledByWorker(): Promise<void> {
+  const ready = await Promise.race([navigator.serviceWorker.ready.then(() => true), delay(10_000).then(() => false)]);
+  if (!ready) throw new Error('The service worker never became active.');
+  if (navigator.serviceWorker.controller !== null) return;
+  await new Promise<void>((resolve) => {
+    navigator.serviceWorker.addEventListener('controllerchange', () => resolve(), { once: true });
+    setTimeout(resolve, 3000);
+  });
+}
+
+/**
+ * A shift-reload bypasses the worker, so a visitor who is still unlocked lands on the lock
+ * shell. One ordinary reload hands the navigation back to the worker, which decides.
+ */
+async function resumeAfterHardReload(): Promise<void> {
+  if (navigator.serviceWorker.controller !== null) return;
+  try {
+    const manifest = await fetchManifest();
+    if ((await indexedDbStore().get(recordId(scope, manifest.kdf.salt))) === undefined) return;
+    if (Date.now() - Number(sessionStorage.getItem(RESUME_KEY)) < 10_000) return;
+    sessionStorage.setItem(RESUME_KEY, String(Date.now()));
+    await navigator.serviceWorker.ready;
+    location.reload();
+  } catch {
+    // Nothing to resume: the form is already showing.
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}