@curia-sh/cli 0.4.1

package/src/root.mjs

@@ -0,0 +1,196 @@
+import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { isAbsolute, join } from 'node:path'
+
+import { Refusal } from './exit.mjs'
+import { writeAtomically } from './atomic.mjs'
+
+// The installation root the lifecycle interface acts on.
+//
+// The launcher exports `CURIA_ROOT` for the root it was installed for, so a
+// nondefault root stays explicit in the launcher and never has to be typed.
+// Without it, the default root follows the XDG base directory rules.
+export function installationRoot(env) {
+  if (env.CURIA_ROOT) return env.CURIA_ROOT
+  if (env.XDG_DATA_HOME) return join(env.XDG_DATA_HOME, 'curia')
+  return join(env.HOME ?? '', '.local', 'share', 'curia')
+}
+
+// The seven boundaries of an installation root, in the order the operator
+// documentation lists them. Each is one directory, mode 0700, owned by the
+// operator. Lifecycle commands act on them as whole units.
+export const BOUNDARIES = Object.freeze(['config', 'secrets', 'state', 'work', 'versions', 'cache', 'run'])
+
+const OWNER_ONLY_DIR = 0o700
+const OWNER_ONLY_FILE = 0o600
+
+// The one safe way into an installation root. Every lifecycle command calls it
+// before it touches anything, and it refuses (exit 3, nothing changed) when:
+//
+//   - the command runs as root;
+//   - the root is not an absolute path;
+//   - the root, a boundary directory, or the installation record is a
+//     symbolic link;
+//   - the root or a boundary is owned by another user or is reachable by the
+//     group or by others;
+//   - the root is nonempty and holds no installation record.
+//
+// It returns the root's status so the caller decides what the operation may
+// do: `absent` (nothing there), `empty` (an empty directory), or `installed`
+// (a record is present, and it is returned). A record that is present but
+// malformed is a failure, not a refusal, so a damaged installation never reads
+// as a fresh one.
+export function openRoot(root, { uid }) {
+  if (uid === 0) {
+    throw new Refusal('this command runs as root. Curia runs unprivileged: run it as the operator that owns the installation.')
+  }
+  if (!isAbsolute(root)) {
+    throw new Refusal(`the installation root must be an absolute path, got ${root}. Set CURIA_ROOT to an absolute path or run the installed launcher.`)
+  }
+
+  const rootStat = ownerOnlyDirectory(root, { uid, what: 'the installation root' })
+  if (rootStat === null) return { root, status: 'absent', record: null }
+
+  for (const name of BOUNDARIES) {
+    ownerOnlyDirectory(join(root, name), { uid, what: `${name}/ in the installation root` })
+  }
+  const record = readInstallationRecord(root)
+  if (record) return { root, status: 'installed', record }
+
+  if (readdirSync(root).length === 0) return { root, status: 'empty', record: null }
+  throw new Refusal(`${root} is not empty and holds no installation record, so it is not a Curia installation. Choose an empty or absent directory, or move what is there out of the way.`)
+}
+
+// Creates the root and the seven boundaries with owner-only permissions. The
+// modes are set explicitly, not through the umask. It is idempotent: it adds a
+// missing boundary to an existing root and leaves the rest alone. It never
+// widens or narrows a directory that exists, so a boundary with broad
+// permissions is refused here as in `openRoot`.
+export function ensureLayout(root, { uid }) {
+  if (ownerOnlyDirectory(root, { uid, what: 'the installation root' }) === null) {
+    mkdirSync(root, { recursive: true })
+    chmodSync(root, OWNER_ONLY_DIR)
+  }
+  for (const name of BOUNDARIES) {
+    const dir = join(root, name)
+    if (ownerOnlyDirectory(dir, { uid, what: `${name}/ in the installation root` }) === null) {
+      mkdirSync(dir, { mode: OWNER_ONLY_DIR })
+      chmodSync(dir, OWNER_ONLY_DIR)
+    }
+  }
+}
+
+// The lstat of a directory that must be owned by `uid`, mode 0700, and not a
+// symbolic link. Returns null when the path does not exist. Every other
+// deviation is a refusal that names the path and the corrective action.
+function ownerOnlyDirectory(path, { uid, what }) {
+  let stat
+  try {
+    stat = lstatSync(path)
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw e
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Refusal(`${what} is a symbolic link: ${path}. Curia does not follow links there. Replace the link with a real directory.`)
+  }
+  if (!stat.isDirectory()) {
+    throw new Refusal(`${what} is not a directory: ${path}. Move the file out of the way or choose another root.`)
+  }
+  if (stat.uid !== uid) {
+    throw new Refusal(`${what} is owned by user ${stat.uid}, not by you (user ${uid}): ${path}. Run the command as the owner, or choose another root.`)
+  }
+  const mode = stat.mode & 0o777
+  if ((mode & 0o077) !== 0) {
+    throw new Refusal(`${what} has mode ${octal(mode)}, which lets other users reach it: ${path}. Run 'chmod 0700 ${path}' and try again.`)
+  }
+  return stat
+}
+
+function octal(mode) {
+  return `0${mode.toString(8).padStart(3, '0')}`
+}
+
+// The installation record: `state/installation.json`, the one file that says
+// which version is active. It holds only the record format, a random
+// installation ID, and the active version. The launcher reads the same file
+// with `sed`, so its shape stays flat: one JSON object, one key per line,
+// `activeVersion` a string.
+export const RECORD_FORMAT = 1
+const RECORD_KEYS = Object.freeze(['format', 'installationId', 'activeVersion'])
+
+export function recordPath(root) {
+  return join(root, 'state', 'installation.json')
+}
+
+export function createInstallationRecord(activeVersion) {
+  return { format: RECORD_FORMAT, installationId: randomBytes(16).toString('hex'), activeVersion }
+}
+
+// Returns the record, or `null` when the root holds none. A record that is
+// present but unreadable as a record is an error: a half-written or foreign
+// file must not read as "no installation". A record that is a symbolic link
+// is refused, because the file is security-sensitive and must live in state/.
+export function readInstallationRecord(root) {
+  const path = recordPath(root)
+  let text
+  try {
+    if (lstatSync(path).isSymbolicLink()) {
+      throw new Refusal(`the installation record ${path} is a symbolic link. Replace the link with the real file or remove it.`)
+    }
+    text = readFileSync(path, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw e
+  }
+  let record
+  try {
+    record = JSON.parse(text)
+  } catch {
+    record = null
+  }
+  if (!isRecord(record)) {
+    throw new Error(`${path} is not a Curia installation record`)
+  }
+  return record
+}
+
+function isRecord(record) {
+  return record !== null
+    && typeof record === 'object'
+    && record.format === RECORD_FORMAT
+    && typeof record.activeVersion === 'string'
+    && typeof record.installationId === 'string'
+}
+
+// Writes the record atomically, owner-only. The record must hold exactly the
+// three documented keys, so nothing operator-specific or generated slips in.
+export function writeInstallationRecord(root, record) {
+  const foreign = Object.keys(record).filter((k) => !RECORD_KEYS.includes(k))
+  if (foreign.length > 0 || !isRecord(record)) {
+    throw new Error(`the installation record holds only ${RECORD_KEYS.join(', ')}; refusing to write ${JSON.stringify(record)}${foreign.length ? ` (unexpected: ${foreign.join(', ')})` : ''}`)
+  }
+  const ordered = Object.fromEntries(RECORD_KEYS.map((k) => [k, record[k]]))
+  writeAtomically(recordPath(root), JSON.stringify(ordered, null, 2) + '\n', { mode: OWNER_ONLY_FILE })
+}
+
+// The paths of an installed version. The launcher reads the first two: the
+// pinned Node runtime and the lifecycle interface's entry point, where
+// `versions/<version>/cli/` holds the unpacked `@curia-sh/cli` package (the
+// tarball's `package/` directory). The rest are what the release manifest
+// (`cli/src/manifest.mjs`) verifies: the manifest the package embeds, the
+// retained package tarball and bundle archive exactly as downloaded, and the
+// unpacked Compose bundle the lifecycle interface starts.
+export function versionPaths(root, version) {
+  const dir = join(root, 'versions', version)
+  return {
+    dir,
+    node: join(dir, 'node', 'bin', 'node'),
+    cli: join(dir, 'cli', 'bin', 'curia.mjs'),
+    manifest: join(dir, 'cli', 'manifest.json'),
+    package: join(dir, 'cli.tgz'),
+    bundleArchive: join(dir, 'bundle.tar.gz'),
+    bundleChecksum: join(dir, 'bundle.tar.gz.sha256'),
+    bundle: join(dir, 'bundle', 'compose.yaml'),
+  }
+}

package/src/secrets.mjs

@@ -0,0 +1,149 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeAtomically } from './atomic.mjs'
+
+// The long-lived credentials Curia owns, one owner-only file each under
+// `secrets/` in the installation root (#867, implementing #851 and #852).
+//
+// A long-lived credential reaches a consumer through a file and nothing else:
+// never an environment variable, a Compose interpolation, a command argument,
+// a log line, a diagnostic, or a browser response. The service is the one
+// process that reads and replaces these files. Every other consumer gets a
+// copy of the one credential it needs, written by the service into that
+// consumer's own directory, or a renewable token derived from it.
+//
+// Renewable tokens (GitHub App installation tokens, agent tokens) and
+// session-bound capabilities are not on this list. They live under `run/` and
+// `work/` and are recreated or bound to a session.
+export const SECRET_FILES = Object.freeze([
+  Object.freeze({
+    name: 'discord-bot-token',
+    holds: 'the Discord bot token, one line',
+    writer: 'the Discord integration step of setup',
+  }),
+  Object.freeze({
+    name: 'github-app.json',
+    holds: 'the GitHub App: `{ "id": "<app id>", "pem": "<private key>" }`',
+    writer: 'the GitHub integration step of setup, from the manifest conversion',
+  }),
+  Object.freeze({
+    name: 'anthropic.json',
+    holds: 'the Anthropic subscription credential the service adopted',
+    writer: 'the Anthropic integration step of setup, or `reauth anthropic`',
+  }),
+  Object.freeze({
+    name: 'codex-auth.json',
+    holds: 'the OpenAI Codex credential, refreshed by the service',
+    writer: 'the OpenAI integration step of setup, or `reauth codex`, and the service on refresh',
+  }),
+])
+
+export const SECRET_NAMES = Object.freeze(SECRET_FILES.map((s) => s.name))
+
+export const SECRET_MODE = 0o600
+
+// A secret boundary that is not met. It is not a `Refusal`: the process that
+// meets one decides what it means. The service refuses to boot on it, and
+// `curia doctor` reports it. The message never carries a secret value.
+export class SecretError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'SecretError'
+  }
+}
+
+export function secretPath(root, name) {
+  if (!SECRET_NAMES.includes(name)) {
+    throw new SecretError(`${name} is not a secret Curia knows. The secret files are ${SECRET_NAMES.join(', ')}.`)
+  }
+  return join(root, 'secrets', name)
+}
+
+// The secret's text, or `null` when the file is absent. A file that is a
+// symbolic link, that another user owns, or that the group or others can read
+// is refused, because a secret that reaches past its owner is no longer a
+// secret and the fix is the operator's.
+export function readSecret(root, name, { uid = process.getuid?.() } = {}) {
+  const file = secretPath(root, name)
+  const fault = inspect(file, { uid })
+  if (fault === 'absent') return null
+  if (fault) throw new SecretError(fault)
+  return readFileSync(file, 'utf8')
+}
+
+// Writes the secret atomically at mode 0600. A symbolic link at the target is
+// replaced by the file, never followed. The parent `secrets/` exists because
+// `ensureLayout` created it.
+export function writeSecret(root, name, text) {
+  const file = secretPath(root, name)
+  if (typeof text !== 'string' || text.trim() === '') {
+    throw new SecretError(`refusing to write an empty ${name}`)
+  }
+  writeAtomically(file, text, { mode: SECRET_MODE })
+}
+
+// Presence and refusals by name, for a diagnostic. No value is read.
+export function secretsStatus(root, { uid = process.getuid?.() } = {}) {
+  const status = {}
+  for (const name of SECRET_NAMES) {
+    const fault = inspect(secretPath(root, name), { uid })
+    if (fault === 'absent') status[name] = { state: 'absent' }
+    else if (fault) status[name] = { state: 'refused', why: fault }
+    else status[name] = { state: 'present' }
+  }
+  return status
+}
+
+function inspect(file, { uid }) {
+  let stat
+  try {
+    stat = lstatSync(file)
+  } catch (e) {
+    if (e.code === 'ENOENT') return 'absent'
+    throw e
+  }
+  if (stat.isSymbolicLink()) {
+    return `${file} is a symbolic link. Curia does not follow links in secrets/. Replace the link with the real file.`
+  }
+  if (!stat.isFile()) {
+    return `${file} is not a regular file. Move it out of the way and write the secret again.`
+  }
+  if (uid !== undefined && stat.uid !== uid) {
+    return `${file} is owned by user ${stat.uid}, not by you (user ${uid}). Run the service as the owner, or write the secret again as yourself.`
+  }
+  if ((stat.mode & 0o077) !== 0) {
+    return `${file} has mode 0${(stat.mode & 0o777).toString(8).padStart(3, '0')}, which lets other users read it. Run 'chmod 0600 ${file}' and try again.`
+  }
+  return null
+}
+
+// The environment keys that used to carry a long-lived credential into the
+// service, or would if an operator set them. A service running from an
+// installation root refuses to boot while any of them is set, naming the key
+// and the secret file to use instead, so a credential never enters a process
+// environment by habit.
+export const CREDENTIAL_ENV_KEYS = Object.freeze([
+  'DISCORD_BOT_TOKEN',
+  'CURIA_GH_APP_ID',
+  'CURIA_GH_APP_KEY_FILE',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+])
+
+export function credentialsInEnvironment(env) {
+  return CREDENTIAL_ENV_KEYS.filter((key) => typeof env[key] === 'string' && env[key] !== '')
+}
+
+// Every occurrence of every given value replaced, for text that may carry a
+// secret on its way to a log or a response.
+export function redact(text, values) {
+  let out = String(text)
+  for (const value of values) {
+    if (typeof value !== 'string' || value === '') continue
+    out = out.split(value).join('[redacted]')
+  }
+  return out
+}

package/src/stable.mjs

@@ -0,0 +1,314 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+import { Refusal } from './exit.mjs'
+import { RELEASE_REPOSITORY, isReleaseVersion } from './manifest.mjs'
+
+// The stable-release index and release selection (#871, implementing #849
+// and #854).
+//
+// Every published Curia release is immutable and stays published. Which one
+// an installation should run is a separate, mutable fact, and this module is
+// the one place that says how that fact is published, proven, and read:
+//
+//   - The index is one small signed file, `release/stable.json` on the `main`
+//     branch of alp82/curia, served raw from GitHub. It names the recommended
+//     stable release and the versions that were withdrawn. It never restates
+//     a manifest: a version is a name here, and the release manifest is what
+//     says what the version is made of.
+//   - The index is signed with one Ed25519 key. The private key lives only in
+//     the repository secret the promotion workflow reads; the public key ships
+//     inside this package as `stable-index.pub`, so an installed version
+//     trusts the key that the package it verified carries, and nothing else.
+//     A host needs no `gh` login and no extra tool to verify it.
+//   - `promote` and `withdraw` are the only two transitions. Each one changes
+//     selection metadata and nothing else: no artifact is rebuilt, replaced,
+//     or deleted. The sequence number rises on every change, so a consumer
+//     that remembers the last sequence it accepted can refuse an older index.
+//   - `selectRelease` is the one selection rule. With nothing requested it
+//     picks the stable release. An exact version is honored as asked. A
+//     prerelease is selected only with the explicit `--prerelease` request,
+//     and a withdrawn version is never selected.
+//
+// `curia update` (#883) calls `fetchStableIndex` and `selectRelease`; the
+// service's daily check and the Curia app read the same index through the
+// same functions; the bootstrap (#872) reads the same file. Every read of
+// the network goes through `stableProbes`, so a test hands in a fake.
+
+export class StableIndexError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'StableIndexError'
+  }
+}
+
+export const STABLE_INDEX_FORMAT = 1
+export const STABLE_INDEX_PATH = 'release/stable.json'
+export const STABLE_INDEX_URL = `https://raw.githubusercontent.com/${RELEASE_REPOSITORY}/main/${STABLE_INDEX_PATH}`
+
+// The public key's file name inside the package, beside package.json.
+export const STABLE_INDEX_KEY_FILE = 'stable-index.pub'
+
+const SIGNATURE_ALGORITHM = 'ed25519'
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/
+
+export function isPrerelease(version) {
+  return isReleaseVersion(version) && version.includes('-')
+}
+
+export function releaseNotesUrl(version) {
+  return `https://github.com/${RELEASE_REPOSITORY}/releases/tag/v${version}`
+}
+
+// ---------------------------------------------------------------------------
+// The index: create, render, parse.
+
+export function createStableIndex({ sequence = 0, updated, stable = null, withdrawn = [] } = {}) {
+  return validate({ format: STABLE_INDEX_FORMAT, sequence, updated, stable, withdrawn })
+}
+
+// The one text form: keys in contract order, the withdrawn list sorted, two-
+// space indentation, one trailing newline. This is what the signature covers.
+export function renderStableIndex(index) {
+  return `${JSON.stringify(validate(index), null, 2)}\n`
+}
+
+export function parseStableIndex(text) {
+  return validate(json(text, 'the index'))
+}
+
+function json(text, what) {
+  try {
+    return JSON.parse(text)
+  } catch (e) {
+    throw new StableIndexError(`${what} is not JSON: ${e.message}`)
+  }
+}
+
+function validate(i) {
+  if (i === null || typeof i !== 'object' || Array.isArray(i)) throw new StableIndexError('the index must be a JSON object')
+  if (i.format !== STABLE_INDEX_FORMAT) throw new StableIndexError(`format must be ${STABLE_INDEX_FORMAT}, got ${JSON.stringify(i.format)}`)
+  onlyKeys(i, ['format', 'sequence', 'updated', 'stable', 'withdrawn'], 'the index')
+  if (!Number.isInteger(i.sequence) || i.sequence < 0) throw new StableIndexError(`sequence must be a nonnegative integer, got ${JSON.stringify(i.sequence)}`)
+  if (typeof i.updated !== 'string' || !TIMESTAMP.test(i.updated) || Number.isNaN(Date.parse(i.updated))) {
+    throw new StableIndexError(`updated must be an ISO 8601 UTC timestamp like 2026-09-02T10:00:00Z, got ${JSON.stringify(i.updated)}`)
+  }
+  if (!Array.isArray(i.withdrawn)) throw new StableIndexError(`withdrawn must be an array of versions, got ${JSON.stringify(i.withdrawn)}`)
+  i.withdrawn.forEach((v, n) => {
+    if (!isReleaseVersion(v)) throw new StableIndexError(`withdrawn[${n}] must be a release version like 1.2.3, got ${JSON.stringify(v)}`)
+  })
+  const withdrawn = [...new Set(i.withdrawn)].sort(compareVersions)
+  if (i.stable !== null) {
+    if (!isReleaseVersion(i.stable)) throw new StableIndexError(`stable must be a release version like 1.2.3 or null, got ${JSON.stringify(i.stable)}`)
+    if (isPrerelease(i.stable)) throw new StableIndexError(`stable must not be a prerelease, got ${i.stable}`)
+    if (withdrawn.includes(i.stable)) throw new StableIndexError(`stable ${i.stable} is withdrawn, and a withdrawn version is never the stable release`)
+  }
+  return { format: STABLE_INDEX_FORMAT, sequence: i.sequence, updated: i.updated, stable: i.stable, withdrawn }
+}
+
+function onlyKeys(value, allowed, what) {
+  for (const key of allowed) if (!(key in value)) throw new StableIndexError(`${key} is missing from ${what}`)
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new StableIndexError(`${key} is not part of ${what}`)
+}
+
+// Numeric order on the three parts, then a prerelease before its release,
+// then the prerelease suffixes as text. Enough to keep the list readable.
+function compareVersions(a, b) {
+  const [ac, as = null] = a.split('-', 2)
+  const [bc, bs = null] = b.split('-', 2)
+  const an = ac.split('.').map(Number)
+  const bn = bc.split('.').map(Number)
+  for (let n = 0; n < 3; n += 1) if (an[n] !== bn[n]) return an[n] - bn[n]
+  if (as === bs) return 0
+  if (as === null) return 1
+  if (bs === null) return -1
+  return as < bs ? -1 : 1
+}
+
+// ---------------------------------------------------------------------------
+// The key and the signature.
+
+// The pinned key's short name: the first 16 hex characters of the SHA-256 of
+// the public key's DER form. A signature names the key it was made with, so
+// a mismatch says which key each side holds instead of only "invalid".
+export function keyFingerprint(publicKey) {
+  const key = typeof publicKey === 'object' && publicKey?.type === 'public' ? publicKey : createPublicKey(publicKey)
+  const der = key.export({ type: 'spki', format: 'der' })
+  return createHash('sha256').update(der).digest('hex').slice(0, 16)
+}
+
+// One Ed25519 pair in PEM form. `deploy/release/keygen.mjs` calls this once,
+// commits the public key into the package, and hands the private key to the
+// repository secret without writing it anywhere else.
+export function generateStableIndexKeys() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  const publicPem = publicKey.export({ type: 'spki', format: 'pem' })
+  return { publicKey: publicPem, privateKey: privateKey.export({ type: 'pkcs8', format: 'pem' }), fingerprint: keyFingerprint(publicPem) }
+}
+
+// The signed file: the index and its signature over the canonical index
+// text. Deterministic, so signing the same index twice writes the same file.
+export function signStableIndex(index, privateKey) {
+  const canonical = renderStableIndex(index)
+  const key = createPrivateKey(privateKey)
+  if (key.asymmetricKeyType !== SIGNATURE_ALGORITHM) throw new StableIndexError(`the signing key must be ${SIGNATURE_ALGORITHM}, got ${key.asymmetricKeyType}`)
+  const value = sign(null, Buffer.from(canonical), key).toString('base64')
+  const envelope = { index: JSON.parse(canonical), signature: { algorithm: SIGNATURE_ALGORITHM, key: keyFingerprint(createPublicKey(key)), value } }
+  return `${JSON.stringify(envelope, null, 2)}\n`
+}
+
+// Returns the index when the file's signature verifies against `publicKey`,
+// and throws a `StableIndexError` that says why otherwise. Nothing passes by
+// absence: no pinned key, no signature, another key, or a changed byte all
+// fail.
+export function verifyStableIndex(text, { publicKey }) {
+  if (!publicKey) throw new StableIndexError('no stable-index public key is pinned in this version, so no index can be trusted')
+  const envelope = json(text, 'the stable-release index')
+  if (envelope === null || typeof envelope !== 'object' || Array.isArray(envelope)) throw new StableIndexError('the stable-release index must be a JSON object')
+  if (!('index' in envelope)) throw new StableIndexError('the stable-release index signature is missing: the file is a bare index, not a signed one')
+  const index = validate(envelope.index)
+  const signature = envelope.signature
+  if (signature === null || signature === undefined) throw new StableIndexError('the stable-release index signature is missing')
+  if (typeof signature !== 'object' || Array.isArray(signature)) throw new StableIndexError('the stable-release index signature must be an object')
+  if (signature.algorithm !== SIGNATURE_ALGORITHM) throw new StableIndexError(`signature.algorithm must be ${SIGNATURE_ALGORITHM}, got ${JSON.stringify(signature.algorithm)}`)
+  const pinned = keyFingerprint(publicKey)
+  if (signature.key !== pinned) throw new StableIndexError(`the stable-release index is signed with key ${signature.key}, and this version pins key ${pinned}. Update the lifecycle interface to a version that pins the current key.`)
+  if (typeof signature.value !== 'string') throw new StableIndexError('signature.value must be a base64 string')
+  const ok = verify(null, Buffer.from(renderStableIndex(index)), createPublicKey(publicKey), Buffer.from(signature.value, 'base64'))
+  if (!ok) throw new StableIndexError(`the stable-release index signature does not verify against key ${pinned}. The file was changed after it was signed: do not trust it, and report it at https://github.com/${RELEASE_REPOSITORY}/issues.`)
+  return index
+}
+
+// The public key this package ships, or null when the file is absent or empty.
+export function pinnedPublicKey(file = new URL(`../${STABLE_INDEX_KEY_FILE}`, import.meta.url)) {
+  try {
+    const text = readFileSync(file, 'utf8').trim()
+    return text ? `${text}\n` : null
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw e
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The two transitions. Pure: index in, index out, the input untouched.
+
+function releaseVersion(version) {
+  if (!isReleaseVersion(version)) throw new Refusal(`${version} is not a release version like 1.2.3.`)
+  return version
+}
+
+function next(index, changes, { updated }) {
+  return validate({ ...index, ...changes, sequence: index.sequence + 1, updated })
+}
+
+export function promote(index, version, { updated }) {
+  const current = validate(index)
+  releaseVersion(version)
+  if (isPrerelease(version)) throw new Refusal(`${version} is a prerelease, and a prerelease is never the stable release. Publish it as a release version first.`)
+  if (current.withdrawn.includes(version)) throw new Refusal(`${version} is withdrawn. A withdrawn version is never promoted; publish a fixed release and promote that.`)
+  if (current.stable === version) return current
+  return next(current, { stable: version }, { updated })
+}
+
+export function withdraw(index, version, { updated }) {
+  const current = validate(index)
+  releaseVersion(version)
+  if (current.withdrawn.includes(version)) return current
+  return next(current, {
+    stable: current.stable === version ? null : current.stable,
+    withdrawn: [...current.withdrawn, version],
+  }, { updated })
+}
+
+// ---------------------------------------------------------------------------
+// Selection.
+
+// The one rule. Returns `{ version, selection }` with `selection` one of
+// `stable`, `exact`, or `prerelease`, or throws a `Refusal` that names the
+// condition. It decides from the index alone; whether the version's
+// artifacts exist and verify is the release verification's question, asked
+// after selection.
+export function selectRelease(index, { requested = null, prerelease = false } = {}) {
+  const current = validate(index)
+  if (requested === null) {
+    if (prerelease) throw new Refusal('--prerelease needs an exact version, such as 1.3.0-rc.1. Without it, Curia selects the stable release.')
+    if (current.stable === null) throw new Refusal('no stable release is recommended right now. Ask for an exact version, or wait for the next stable release.')
+    return { version: current.stable, selection: 'stable' }
+  }
+  if (!isReleaseVersion(requested)) throw new Refusal(`${requested} is not a release version like 1.2.3.`)
+  if (current.withdrawn.includes(requested)) {
+    throw new Refusal(`${requested} is withdrawn: the release notes at ${releaseNotesUrl(requested)} say why. Choose another version, or run the command without a version for the stable release.`)
+  }
+  if (isPrerelease(requested)) {
+    if (!prerelease) throw new Refusal(`${requested} is a prerelease. A prerelease is never selected by accident: to install it anyway, add --prerelease.`)
+    return { version: requested, selection: 'prerelease' }
+  }
+  if (prerelease) throw new Refusal(`${requested} is not a prerelease. Run the command without --prerelease.`)
+  return { version: requested, selection: 'exact' }
+}
+
+// The command-line shape `curia update` gives selection: one optional exact
+// version and one optional `--prerelease`. A `StableIndexError` here is a
+// usage error for the caller to report as such.
+export function selectionFromArgs(args) {
+  let requested = null
+  let prerelease = false
+  for (const arg of args) {
+    if (arg === '--prerelease') prerelease = true
+    else if (arg.startsWith('-')) throw new StableIndexError(`unknown option: ${arg}`)
+    else if (requested !== null) throw new StableIndexError(`one version at most, got ${requested} and ${arg}`)
+    else requested = arg
+  }
+  return { requested, prerelease }
+}
+
+const SELECTION_WORDS = {
+  stable: 'the stable release',
+  exact: 'the exact version requested',
+  prerelease: 'the exact prerelease requested',
+}
+
+export function renderSelection({ version, selection }) {
+  return `selected ${version}, ${SELECTION_WORDS[selection]}\n`
+}
+
+// ---------------------------------------------------------------------------
+// Fetching.
+
+// The one network boundary: the raw file on the main branch. Null when it
+// does not download, for whatever reason; the caller reports that as a failed
+// check and never as an empty index.
+export const stableProbes = Object.freeze({
+  stableIndex: async () => {
+    try {
+      const response = await fetch(STABLE_INDEX_URL, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(30_000) })
+      if (!response.ok) return null
+      return await response.text()
+    } catch {
+      return null
+    }
+  },
+})
+
+function renderIndexLine(index) {
+  const withdrawn = index.withdrawn.length ? `withdrawn ${index.withdrawn.join(', ')}` : 'nothing withdrawn'
+  return `stable-release index: sequence ${index.sequence}, stable ${index.stable ?? 'none'}, ${withdrawn}\n`
+}
+
+// Downloads the index, verifies it against the pinned key, prints one line,
+// and returns `{ ok, index, error }`. A failed fetch carries the reason and no
+// index, so a caller cannot select from a file that did not verify.
+export async function fetchStableIndex({ stdout, publicKey = pinnedPublicKey() }, probes = stableProbes) {
+  let result
+  try {
+    const text = await probes.stableIndex()
+    if (text === null || text === undefined) throw new StableIndexError(`the stable-release index could not be downloaded from ${STABLE_INDEX_URL}. Check outbound access to raw.githubusercontent.com and run the command again.`)
+    result = { ok: true, index: verifyStableIndex(text, { publicKey }), error: null }
+  } catch (e) {
+    if (!(e instanceof StableIndexError)) throw e
+    result = { ok: false, index: null, error: e.message }
+  }
+  stdout.write(result.ok ? renderIndexLine(result.index) : `stable-release index: failed. ${result.error}\n`)
+  return result
+}