@crombolo/server 0.11.0 → 0.13.1

package/src/setup.ts

@@ -0,0 +1,288 @@
+/**
+ * "Set up your new site": the first administrator, created from the browser on a
+ * production install that was given no password. Guarded by `CROMBOLO_SETUP_CODE`,
+ * which the owner chooses and which nothing here ever prints, logs or echoes.
+ * docs/operations.md.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { hashPassword, passwordConfigJson } from '@crombolo/auth'
+import {
+  DEFAULT_PASSWORD_CONFIGURATION,
+  isValidEmail,
+  isValidPassword,
+  type PasswordConfiguration,
+} from '@crombolo/core'
+import { completeSetup, type Db, readSetupState } from '@crombolo/data'
+
+export const MIN_SETUP_CODE_LENGTH = 16
+export const SETUP_CODE_VARIABLE = 'CROMBOLO_SETUP_CODE'
+
+export type CodeCheck = 'unavailable' | 'accepted' | 'refused'
+
+const digest = (value: string) => createHash('sha256').update(value).digest()
+
+/** Compared as digests, so neither the length nor the content leaks through timing. */
+export function checkSetupCode(configured: string | undefined, given: string): CodeCheck {
+  if (!configured || configured.length < MIN_SETUP_CODE_LENGTH) return 'unavailable'
+  return timingSafeEqual(digest(configured), digest(given)) ? 'accepted' : 'refused'
+}
+
+export interface SetupForm {
+  name: string
+  email: string
+  password: string
+  confirm: string
+  code: string
+}
+
+export type SetupErrors = Partial<Record<keyof SetupForm, string>>
+
+export function validateSetupForm(
+  form: SetupForm,
+  passwords: PasswordConfiguration = DEFAULT_PASSWORD_CONFIGURATION,
+): SetupErrors {
+  const errors: SetupErrors = {}
+  if (!form.name.trim()) errors.name = 'Enter your name.'
+  if (!isValidEmail(form.email.trim())) errors.email = 'Enter an e-mail address.'
+  if (!isValidPassword(form.password, passwords))
+    errors.password = `Use at least ${passwords.minimumPasswordLength} characters.`
+  else if (form.password !== form.confirm) errors.confirm = 'The passwords do not match.'
+  if (!form.code) errors.code = 'Enter the setup code.'
+  return errors
+}
+
+/** Failed attempts per caller within a window, and across all callers. */
+export class AttemptLimiter {
+  #failures = new Map<string, number[]>()
+  #all: number[] = []
+  readonly #max: number
+  readonly #maxAll: number
+  readonly #windowMs: number
+  readonly #now: () => number
+
+  constructor(
+    options: { max?: number; maxAll?: number; windowMs?: number; now?: () => number } = {},
+  ) {
+    this.#max = options.max ?? 5
+    this.#maxAll = options.maxAll ?? 50
+    this.#windowMs = options.windowMs ?? 15 * 60_000
+    this.#now = options.now ?? Date.now
+  }
+
+  #recent(times: number[]): number[] {
+    const since = this.#now() - this.#windowMs
+    return times.filter((t) => t > since)
+  }
+
+  blocked(key: string): boolean {
+    this.#all = this.#recent(this.#all)
+    const mine = this.#recent(this.#failures.get(key) ?? [])
+    this.#failures.set(key, mine)
+    return mine.length >= this.#max || this.#all.length >= this.#maxAll
+  }
+
+  fail(key: string): void {
+    const now = this.#now()
+    this.#failures.set(key, [...(this.#failures.get(key) ?? []), now])
+    this.#all.push(now)
+  }
+}
+
+export type SetupView =
+  | { kind: 'unavailable' }
+  | { kind: 'form'; errors: SetupErrors; name: string; email: string; limited?: boolean }
+  | { kind: 'done'; backOfficePath: string }
+
+const escapeHtml = (value: string): string =>
+  value.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string,
+  )
+
+function field(
+  label: string,
+  name: keyof SetupForm,
+  type: string,
+  errors: SetupErrors,
+  value = '',
+  autocomplete = 'off',
+): string {
+  const error = errors[name]
+  return `<label for="${name}">${label}</label>
+  <input id="${name}" name="${name}" type="${type}" value="${escapeHtml(value)}" autocomplete="${autocomplete}" required${error ? ` aria-invalid="true" aria-describedby="${name}-error"` : ''}>
+  ${error ? `<p class="error" id="${name}-error">${escapeHtml(error)}</p>` : ''}`
+}
+
+/** The page itself: plain HTML, no script, so it works before anything else does. */
+export function setupPage(view: SetupView, siteName: string): string {
+  const site = escapeHtml(siteName)
+  let body: string
+  if (view.kind === 'unavailable') {
+    body = `<h1>Set up your new site</h1>
+  <p>${site} is running, and is ready for its first administrator.</p>
+  <p>To protect this page, add a setting named <code>${SETUP_CODE_VARIABLE}</code> to the server, with a value of at least ${MIN_SETUP_CODE_LENGTH} characters that only you know. Restart the server, then come back to this page and enter it.</p>
+  <p class="fine">Where you add settings depends on where the site runs: in your hosting provider's console it is usually called environment variables.</p>`
+  } else if (view.kind === 'done') {
+    body = `<h1>Your site is ready</h1>
+  <p>Your administrator account has been created.</p>
+  <p><a class="cta" href="${escapeHtml(view.backOfficePath)}">Sign in</a></p>
+  <p class="fine">You can now remove the <code>${SETUP_CODE_VARIABLE}</code> setting from the server: it is not needed again.</p>`
+  } else {
+    const { errors } = view
+    body = `<h1>Set up your new site</h1>
+  <p>Create the administrator account for ${site}.</p>
+  ${view.limited ? '<p class="error" role="alert">Too many attempts. Wait a few minutes and try again.</p>' : ''}
+  <form method="post">
+  ${field('Your name', 'name', 'text', errors, view.name, 'name')}
+  ${field('E-mail', 'email', 'email', errors, view.email, 'email')}
+  ${field('Password', 'password', 'password', errors, '', 'new-password')}
+  ${field('Confirm password', 'confirm', 'password', errors, '', 'new-password')}
+  ${field('Setup code', 'code', 'password', errors)}
+  <p class="fine">The setup code is the value of the <code>${SETUP_CODE_VARIABLE}</code> setting on the server.</p>
+  <button type="submit">Create the account</button>
+  </form>`
+  }
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>Set up your new site</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+    font: 16px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+    background: #f6f5f3; color: #1b1b1b; }
+  main { width: 100%; max-width: 30rem; padding: 2.5rem 1rem; box-sizing: border-box; }
+  h1 { font-size: 1.6rem; margin: 0 0 .75rem; }
+  p { margin: 0 0 1rem; }
+  label { display: block; font-weight: 600; margin: 1rem 0 .25rem; }
+  input { width: 100%; box-sizing: border-box; padding: .5rem; font: inherit; border: 1px solid #b9b6ae; border-radius: 4px; }
+  button, a.cta { display: inline-block; margin-top: 1.25rem; padding: .55rem 1rem; border: 0; border-radius: 4px;
+    background: #1b1b1b; color: #fff; font: inherit; text-decoration: none; cursor: pointer; }
+  code { font-size: .9em; background: #e9e7e2; padding: .1em .35em; border-radius: 3px; }
+  .error { color: #a3261b; margin: .25rem 0 0; }
+  .fine { font-size: .85rem; color: #6b6b63; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #16171a; color: #e8e6e3; }
+    input { background: #1f2124; color: inherit; border-color: #45474b; }
+    code { background: #26282c; }
+    button, a.cta { background: #e8e6e3; color: #16171a; }
+    .error { color: #f08a7e; }
+    .fine { color: #9a9a93; }
+  }
+</style>
+</head>
+<body>
+<main>
+  ${body}
+</main>
+</body>
+</html>
+`
+}
+
+export interface SetupRoutesOptions {
+  db: Db
+  setupCode: string | undefined
+  siteName: string
+  backOfficePath: string
+  /** Who is asking, for the attempt limit. */
+  clientKey: (request: Request) => string
+  limiter?: AttemptLimiter
+  passwords?: PasswordConfiguration
+}
+
+export interface SetupRoutes {
+  readonly path: string
+  /** True until the first administrator exists; read from the database until then. */
+  pending(): Promise<boolean>
+  handle(request: Request): Promise<Response>
+}
+
+const page = (html: string, status = 200) =>
+  new Response(html, {
+    status,
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'no-store',
+      'x-frame-options': 'DENY',
+      'referrer-policy': 'no-referrer',
+    },
+  })
+
+export function createSetupRoutes(options: SetupRoutesOptions): SetupRoutes {
+  const path = `${options.backOfficePath}/setup`
+  const limiter = options.limiter ?? new AttemptLimiter()
+  let closed = false
+
+  const pending = async () => {
+    if (closed) return false
+    const state = await readSetupState(options.db)
+    if (state !== 'pending') closed = true
+    return state === 'pending'
+  }
+
+  const render = (view: SetupView, status = 200) => page(setupPage(view, options.siteName), status)
+  const formView = (
+    errors: SetupErrors,
+    form?: Partial<SetupForm>,
+    limited = false,
+  ): SetupView => ({
+    kind: 'form',
+    errors,
+    name: form?.name ?? '',
+    email: form?.email ?? '',
+    limited,
+  })
+
+  return {
+    path,
+    pending,
+    async handle(request) {
+      if (!(await pending()))
+        return new Response(null, { status: 303, headers: { location: options.backOfficePath } })
+      const configured = checkSetupCode(options.setupCode, '')
+      if (configured === 'unavailable') return render({ kind: 'unavailable' })
+      if (request.method === 'GET') return render(formView({}))
+      if (request.method !== 'POST') return new Response('Method Not Allowed', { status: 405 })
+
+      const origin = request.headers.get('origin')
+      if (origin && origin !== new URL(request.url).origin)
+        return new Response('Forbidden', { status: 403 })
+
+      const key = options.clientKey(request)
+      const data = await request.formData().catch(() => new FormData())
+      const value = (name: string) => {
+        const entry = data.get(name)
+        return typeof entry === 'string' ? entry : ''
+      }
+      const form: SetupForm = {
+        name: value('name'),
+        email: value('email'),
+        password: value('password'),
+        confirm: value('confirm'),
+        code: value('code'),
+      }
+      if (limiter.blocked(key)) return render(formView({}, form, true), 429)
+      const errors = validateSetupForm(form, options.passwords)
+      if (Object.keys(errors).length > 0) return render(formView(errors, form), 400)
+      if (checkSetupCode(options.setupCode, form.code) !== 'accepted') {
+        limiter.fail(key)
+        return render(formView({ code: 'That is not the setup code.' }, form), 400)
+      }
+
+      const email = form.email.trim()
+      const result = await completeSetup(
+        options.db,
+        { name: form.name.trim(), login: email, email, password: form.password },
+        { hashPassword, passwordConfig: passwordConfigJson() },
+      )
+      closed = true
+      if (result === 'closed')
+        return new Response(null, { status: 303, headers: { location: options.backOfficePath } })
+      return render({ kind: 'done', backOfficePath: options.backOfficePath })
+    },
+  }
+}

package/src/status.ts

@@ -30,6 +30,7 @@ import { loadSchemaDirectory } from '@crombolo/schema'
 import { BundleConfigurationError, bundleChainsFor, pendingBundleSteps } from './bundle-tables.ts'
 import { type CromboloConfig, describeDatabase, VERSION } from './config.ts'
 import { type EmailAvailability, emailAvailability, resolveEmailPort } from './email.ts'
+import { formTypesFor } from './form-types.ts'
 import { assertViewRuntime } from './view-runtime.ts'
 
 export interface SiteStatus {
@@ -111,7 +112,7 @@ async function contentCounts(db: Db): Promise<SiteStatus['content']> {
 }
 
 /** The vendored client's version, which is a fact about this deployment too. */
-function backofficeVersion(): string | undefined {
+export function backofficeVersion(): string | undefined {
   for (const base of [join(import.meta.dir, '..', '..'), process.cwd()]) {
     const file = join(base, 'backoffice-dist', 'package.json')
     if (!existsSync(file)) continue
@@ -125,7 +126,9 @@ function backofficeVersion(): string | undefined {
 }
 
 export async function siteStatus(config: CromboloConfig): Promise<SiteStatus> {
-  const loaded = existsSync(config.schemaDir) ? loadSchemaDirectory(config.schemaDir) : undefined
+  const loaded = existsSync(config.schemaDir)
+    ? loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
+    : undefined
   const status: SiteStatus = {
     site: {
       name: config.siteName,

package/src/transfer-dashboard.ts

@@ -0,0 +1,219 @@
+/**
+ * Answering a content import's conflicts, and running it, from the Changes
+ * dashboard. docs/content-transfer.md, "In the backoffice".
+ *
+ * The answers are stored, not written beside the bundle: an installed bundle
+ * lives in `node_modules`, which a redeploy replaces and other nodes do not
+ * share. They are laid over the bundle's own `resolutions.json` at import, and
+ * can be downloaded as that file to commit with it.
+ */
+import {
+  type Db,
+  type PendingTransfer,
+  type TransferAnswer,
+  TransferAnswerRepository,
+} from '@crombolo/data'
+import { isResolution, nodeResolutionProblems, type Resolution } from '@crombolo/transfer'
+import { BackupRequiredError } from './backup.ts'
+import {
+  CommandError,
+  checkBundleContent,
+  installBundleContent,
+  PassphraseError,
+  pendingResolutionsFile,
+} from './bundle-install.ts'
+import type { CromboloConfig } from './config.ts'
+
+export interface PendingTransferView {
+  bundleId: string
+  label: string | null
+  checkedAt: string
+  publish: boolean
+  allowMissingBlobs: boolean
+  answers: Array<Pick<TransferAnswer, 'nodeKey' | 'handle' | 'resolution' | 'answeredBy'>>
+}
+
+/** The imports waiting on the dashboard, with the answers given so far. */
+export async function pendingTransfers(db: Db): Promise<PendingTransferView[]> {
+  const repo = new TransferAnswerRepository(db)
+  const out: PendingTransferView[] = []
+  for (const pending of await repo.allPending())
+    out.push({
+      bundleId: pending.bundleId,
+      label: pending.label,
+      checkedAt: pending.checkedAt.toISOString(),
+      publish: pending.publish,
+      allowMissingBlobs: pending.allowMissingBlobs,
+      answers: (await repo.answers(pending.bundleId)).map(
+        ({ nodeKey, handle, resolution, answeredBy }) => ({
+          nodeKey,
+          handle,
+          resolution,
+          answeredBy,
+        }),
+      ),
+    })
+  return out
+}
+
+const HANDLE = /^(\*|[A-Za-z][A-Za-z0-9_]*(@[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*)?)$/
+const NODE_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** What is wrong with an answer as sent, if anything. Pure. */
+export function answerProblems(body: Record<string, unknown>): string[] {
+  const nodeKey = typeof body.nodeKey === 'string' ? body.nodeKey : ''
+  const handle = typeof body.handle === 'string' ? body.handle : ''
+  if (!NODE_KEY.test(nodeKey)) return ['The answer names no item.']
+  if (!HANDLE.test(handle)) return ['The answer names no field.']
+  if (body.resolution === null) return []
+  if (typeof body.resolution !== 'string' || !isResolution(body.resolution))
+    return ['That is not one of the answers on offer.']
+  return nodeResolutionProblems(nodeKey, { [handle]: body.resolution }).length > 0
+    ? ['Only a whole item can be left out.']
+    : []
+}
+
+export interface TransferActionContext {
+  db: Db
+  config: CromboloConfig
+  /** Who is acting, recorded with each answer. */
+  user: string
+  /** After an import lands: the published cache was built before it. */
+  onApplied(): void
+}
+
+const unreadable = (error: CommandError) =>
+  Response.json(
+    {
+      ok: false,
+      message: 'This bundle can no longer be read on this server.',
+      detail: error.problems,
+    },
+    { status: 409 },
+  )
+
+async function recheck(
+  ctx: TransferActionContext,
+  pending: PendingTransfer,
+  passphrase: string | undefined,
+) {
+  const result = await checkBundleContent(ctx.db, ctx.config, {
+    bundle: pending.target,
+    under: pending.under ?? undefined,
+    publish: pending.publish,
+    allowMissingBlobs: pending.allowMissingBlobs,
+    by: ctx.user,
+    passphrase,
+  })
+  return {
+    ok: true,
+    outstanding: result.check.outstanding.length,
+    blocking: result.check.outstanding.filter((f) => f.kind === 'blocking').length,
+    publishRefusals: result.publishRefusals.length,
+  }
+}
+
+/**
+ * `<bundleId>/answer`, `/missing-files`, `/check`, `/import` and
+ * `/resolutions`. Undefined for anything else.
+ */
+export async function handleTransferAction(
+  request: Request,
+  action: string,
+  ctx: TransferActionContext,
+): Promise<Response | undefined> {
+  const match = /^([^/]+)\/(answer|missing-files|check|import|resolutions)$/.exec(action)
+  if (!match) return undefined
+  const bundleId = decodeURIComponent(match[1] as string)
+  const verb = match[2] as string
+  const repo = new TransferAnswerRepository(ctx.db)
+  const pending = await repo.pending(bundleId)
+  if (!pending)
+    return Response.json(
+      { ok: false, message: 'Nothing is waiting to be imported from this bundle.' },
+      { status: 404 },
+    )
+
+  try {
+    if (verb === 'resolutions' && request.method === 'GET') {
+      const file = (await pendingResolutionsFile(ctx.db, ctx.config, bundleId)) as string
+      return new Response(file, {
+        headers: {
+          'content-type': 'application/json',
+          'content-disposition': 'attachment; filename="resolutions.json"',
+        },
+      })
+    }
+    if (request.method !== 'POST') return undefined
+    const body = (await request.json().catch(() => ({}))) as Record<string, unknown>
+    // For this request only: an encrypted bundle's passphrase is never stored.
+    const passphrase =
+      typeof body.passphrase === 'string' && body.passphrase !== '' ? body.passphrase : undefined
+
+    if (verb === 'answer') {
+      const problems = answerProblems(body)
+      if (problems.length > 0)
+        return Response.json({ ok: false, message: problems[0] }, { status: 400 })
+      await repo.answer(bundleId, {
+        nodeKey: body.nodeKey as string,
+        handle: body.handle as string,
+        resolution: (body.resolution as Resolution | null) ?? null,
+        by: ctx.user,
+      })
+      return Response.json(await recheck(ctx, pending, passphrase))
+    }
+    if (verb === 'missing-files') {
+      await repo.setAllowMissingBlobs(bundleId, body.allow === true)
+      return Response.json(
+        await recheck(ctx, { ...pending, allowMissingBlobs: body.allow === true }, passphrase),
+      )
+    }
+    if (verb === 'check') return Response.json(await recheck(ctx, pending, passphrase))
+
+    const result = await installBundleContent(ctx.db, ctx.config, {
+      bundle: pending.target,
+      under: pending.under ?? undefined,
+      publish: pending.publish,
+      allowMissingBlobs: pending.allowMissingBlobs,
+      backupTaken: body.backupTaken === true,
+      label: pending.label ?? undefined,
+      by: ctx.user,
+      passphrase,
+    })
+    if (result.runId) ctx.onApplied()
+    const names = new Map(result.check.plan.map((entry) => [entry.key, entry.name] as const))
+    return Response.json(
+      {
+        ok: Boolean(result.runId),
+        runId: result.runId ?? null,
+        counts: result.check.counts,
+        published: result.published,
+        publishFailures: result.publishFailures.map((failure) => ({
+          name: names.get(failure.key) ?? failure.key,
+          reason: failure.reason,
+        })),
+        outstanding: result.check.outstanding.length,
+        problems: result.problems,
+      },
+      { status: result.runId ? 200 : 409 },
+    )
+  } catch (error) {
+    if (error instanceof PassphraseError)
+      return Response.json(
+        { ok: false, needsPassphrase: true, message: error.message },
+        { status: 409 },
+      )
+    if (error instanceof CommandError) return unreadable(error)
+    if (error instanceof BackupRequiredError)
+      return Response.json(
+        {
+          ok: false,
+          needsBackup: true,
+          message:
+            'This site takes no backup by itself before an import. Take one, then confirm it to go ahead.',
+        },
+        { status: 409 },
+      )
+    throw error
+  }
+}

package/src/upgrade-summary.ts

@@ -0,0 +1,43 @@
+/** What the Changes dashboard says about this site's installs and upgrades, read from the ledger. */
+import type { LedgerRow } from '@crombolo/data'
+
+export interface UpgradeSummary {
+  version: string
+  installedAt: string | null
+  /** The last run of framework steps after the install, if there has been one. */
+  lastUpgrade: { at: string; release: string | null; steps: number } | null
+}
+
+/** Steps this far apart or closer belong to one run. */
+const RUN_GAP_MS = 10 * 60_000
+
+/** SQLite and Postgres hand dates back differently; the dashboard gets ISO. */
+const iso = (at: string) => {
+  const time = Date.parse(at)
+  return Number.isNaN(time) ? at : new Date(time).toISOString()
+}
+
+const releaseOf = (row: LedgerRow) => /^release (\S+)/.exec(row.note ?? '')?.[1] ?? null
+
+export function summariseUpgrades(ledger: readonly LedgerRow[], version: string): UpgradeSummary {
+  const core = ledger
+    .filter((row) => !row.bundle && (row.kind === 'expand' || row.kind === 'contract'))
+    .sort((a, b) => a.id - b.id)
+  const first = core[0]
+  if (!first) return { version, installedAt: null, lastUpgrade: null }
+  let start = core.length - 1
+  while (
+    start > 0 &&
+    Date.parse(core[start]?.appliedAt ?? '') - Date.parse(core[start - 1]?.appliedAt ?? '') <=
+      RUN_GAP_MS
+  )
+    start--
+  const run = core.slice(start)
+  const last = run.at(-1) as LedgerRow
+  return {
+    version,
+    installedAt: iso(first.appliedAt),
+    lastUpgrade:
+      start === 0 ? null : { at: iso(last.appliedAt), release: releaseOf(last), steps: run.length },
+  }
+}

package/src/url-settings.ts

@@ -0,0 +1,91 @@
+/**
+ * How the site's URLs are built (story 110): Umbraco's
+ * `HideTopLevelNodeFromPath`, kept in `schema/schema.toml` and changed there or
+ * in Settings. Either way every URL can move, so the old ones are redirected,
+ * as a rename's are. docs/rendering.md, "URLs".
+ */
+
+import { existsSync } from 'node:fs'
+import {
+  appendCacheInstruction,
+  type Db,
+  readUrlOptions,
+  sameUrlOptions,
+  type UrlOptions,
+  writeUrlOptions,
+} from '@crombolo/data'
+import {
+  type DocumentRoute,
+  PublishedCache,
+  type PublishedCacheOptions,
+  type PublishedContentSource,
+} from '@crombolo/render'
+import { createSchemaFileWriter } from './adapters/schema-files.ts'
+import type { CromboloConfig } from './config.ts'
+import { schemaFiles } from './ports.ts'
+import type { RedirectTracker } from './redirects.ts'
+
+export interface UrlChangeContext {
+  db: Db
+  config: CromboloConfig
+  source: PublishedContentSource
+  cacheOptions?: PublishedCacheOptions
+  cache: PublishedCache
+  tracker: RedirectTracker
+}
+
+/**
+ * Every route the site had under `before`, read from a cache built with it,
+ * then handed to the tracker against the routes it has now. The live cache is
+ * dropped first, so "now" is the new setting.
+ */
+export async function redirectAfterUrlChange(
+  ctx: UrlChangeContext,
+  before: UrlOptions,
+): Promise<void> {
+  const old = new PublishedCache(
+    { ...ctx.source, loadUrlOptions: async () => before },
+    ctx.cacheOptions,
+  )
+  const captured: DocumentRoute[] = []
+  for (const key of await old.childKeys(null)) captured.push(...(await old.routes(key, true)))
+  ctx.cache.invalidate()
+  await ctx.tracker.commit(captured)
+}
+
+export type UrlSettingOutcome =
+  | { ok: true; options: UrlOptions }
+  | { ok: false; status: number; message: string }
+
+/** Whether Settings may change it here: not when the files are kept read-only. Pure. */
+export function urlSettingEditable(
+  config: Pick<CromboloConfig, 'schemaDir' | 'schemaWritable'>,
+  managed: boolean,
+): boolean {
+  return !managed || config.schemaWritable
+}
+
+/** The change Settings makes: the database, the file, redirects, and the other nodes. */
+export async function changeUrlOptions(
+  ctx: UrlChangeContext,
+  next: UrlOptions,
+): Promise<UrlSettingOutcome> {
+  if (!urlSettingEditable(ctx.config, existsSync(ctx.config.schemaDir)))
+    return {
+      ok: false,
+      status: 409,
+      message:
+        'This site keeps its address settings with its files, and they cannot be changed in this environment.',
+    }
+  const before = await readUrlOptions(ctx.db)
+  if (sameUrlOptions(before, next)) return { ok: true, options: before }
+  await writeUrlOptions(ctx.db, next)
+  await createSchemaFileWriter(ctx.db, schemaFiles(ctx.config)).writeUrlOptions(next)
+  await redirectAfterUrlChange(ctx, before)
+  await appendCacheInstruction(ctx.db, {
+    kind: 'schema',
+    payload: { urls: next },
+    by: ctx.config.nodeId,
+  })
+  return { ok: true, options: next }
+}