@taprootio/site-authoring 0.1.0

package/src/session.js

@@ -0,0 +1,316 @@
+import {
+  CLI_BINARY_NAME,
+  CLI_NAME,
+  CLI_VERSION,
+  DEFAULT_API_BASE_URL,
+  PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  RESULT_SCHEMA_VERSION,
+  VERB_LOGIN,
+  VERB_USE,
+} from "./constants.js";
+import { loadSiteConfig } from "./config.js";
+import {
+  credentialApiOrigin,
+  readCredentialStore,
+  selectCredential,
+  updateCredentialMetadata,
+} from "./credentials.js";
+import { SiteAuthoringError } from "./errors.js";
+import { exchangeSiteAuthoringToken } from "./api.js";
+import { SiteApiClient } from "./transport.js";
+import { readStoredApiBaseUrl } from "./settings.js";
+
+/**
+ * The two things every verb does at its edges: open a credentialed session, and
+ * shape the one machine-readable result that reaches stdout.
+ *
+ * Since TR00645 the credential a verb runs on is usually not the credential on
+ * disk. What is stored is an account-scoped sign-in that authorizes nothing;
+ * what a verb needs is a site credential, minted on demand by exchanging that
+ * sign-in for one. The exchange happens here so no verb has to know it happened.
+ *
+ * The exchanged credential is held in memory for the life of the process and
+ * never written down. That is deliberate: it expires within the hour, it is
+ * cheap to mint again, and a short-lived secret in a file is a long-lived
+ * secret in a backup.
+ */
+
+/** The optional seams a test (or a future caller) may inject. */
+const CLIENT_OPTION_KEYS = ["fetch", "signal", "sleep", "now", "timeoutSignal"];
+
+function progressSink(invocation) {
+  return typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
+}
+
+function keyMissingError() {
+  return new SiteAuthoringError(
+    "auth.key_missing",
+    `No Taproot sign-in is available. Run '${CLI_BINARY_NAME} ${VERB_LOGIN}' to authorize this CLI, `
+      + `or set ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} to a site-scoped Taproot site authoring key.`,
+  );
+}
+
+function siteMissingError() {
+  return new SiteAuthoringError(
+    "config.site_missing",
+    `No site is selected. Run '${CLI_BINARY_NAME} ${VERB_USE} <site>' to choose one, `
+      + "or set siteId in taproot-site.json.",
+  );
+}
+
+async function loadConfig(invocation) {
+  return await loadSiteConfig({
+    cwd: invocation.cwd ?? process.cwd(),
+    configPath: invocation.configPath,
+  });
+}
+
+function buildClientOptions(invocation, apiBaseUrl, token) {
+  const clientOptions = { apiBaseUrl, ...(token === undefined ? {} : { token }) };
+  for (const key of CLIENT_OPTION_KEYS) {
+    if (invocation[key] !== undefined) clientOptions[key] = invocation[key];
+  }
+  return clientOptions;
+}
+
+/**
+ * The stored sign-in for the configured origin, or a refusal naming `login`.
+ *
+ * Read before the configuration, and that ordering is load bearing: "there is
+ * no credential anywhere" is knowable without a configuration, and answering it
+ * first preserves the long-standing promise that a credential-less invocation
+ * stops before reading config, resolving a workspace path, or building a
+ * request.
+ */
+async function requireSignIn(environment, resolveApiBaseUrl) {
+  const store = await readCredentialStore(environment);
+  // Emptiness is answered before the configuration is resolved at all. That
+  // ordering is a promise, not an optimization: a credential-less invocation
+  // must stop before reading config, resolving a workspace path, or building a
+  // request, and answering "no credential anywhere" needs none of those.
+  if (store.credentials.length === 0) throw keyMissingError();
+  const stored = selectCredential(store.credentials, credentialApiOrigin(await resolveApiBaseUrl()));
+  if (stored === undefined) throw keyMissingError();
+  return stored;
+}
+
+/**
+ * Opens an account-authorized session: the sign-in credential itself, used for
+ * the two things it can do. Never used to author.
+ */
+export async function openAccountSession(invocation = {}) {
+  const environment = invocation.environment ?? process.env;
+  // Tolerates a missing configuration for the same reason `login` does: `sites`
+  // and `use` are what an operator runs *before* there is one, and requiring
+  // the file they exist to produce would be a loop.
+  let resolved;
+  const signIn = await requireSignIn(environment, async () => {
+    resolved = await openAnonymousSession({ ...invocation, client: null });
+    return resolved.apiBaseUrl;
+  });
+  const { config, apiBaseUrl } = resolved;
+  const client = invocation.client
+    ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, signIn.key));
+  return {
+    config,
+    apiBaseUrl,
+    client,
+    signIn,
+    now: invocation.now ?? Date.now,
+    onProgress: progressSink(invocation),
+  };
+}
+
+/**
+ * Opens a site-authorized session for the configured site.
+ *
+ * Two credential sources, in the one order that keeps existing automation
+ * unaffected:
+ *
+ * `TAPROOT_SITE_KEY` wins outright and byte-for-byte, and skips the exchange
+ * entirely. CI and non-interactive agents set it deliberately, and a stored
+ * sign-in silently overriding it would be the worst kind of surprise. Presence
+ * is authoritative even when the value is empty or malformed — including CI
+ * that masked a missing secret into an empty string — because an operator who
+ * set the variable meant that credential and no other; falling through would
+ * run the command as a different identity. The transport rejects an unusable
+ * value with a clear code instead.
+ *
+ * There is deliberately no second environment variable for the sign-in
+ * credential. One override, one precedence rule.
+ */
+/**
+ * Which Taproot to talk to. Machine state, then the production default — the
+ * project has no say since TR00645, so every session path resolves it here
+ * rather than reaching into a config field that no longer exists.
+ */
+export async function resolveApiBaseUrl(environment) {
+  return (await readStoredApiBaseUrl(environment)) ?? DEFAULT_API_BASE_URL;
+}
+
+export async function openSession(invocation = {}) {
+  const environment = invocation.environment ?? process.env;
+  const onProgress = progressSink(invocation);
+  const now = invocation.now ?? Date.now;
+
+  // The endpoint is resolved inside each branch, not ahead of both. The
+  // stored-sign-in branch promises to answer "no credential anywhere" before
+  // it reads anything else, and the machine settings file is something else:
+  // resolving it first would turn an empty store plus a malformed settings
+  // file into a settings error, in front of the one answer that needs no file
+  // at all.
+  const environmentToken = environment?.[PUBLISH_KEY_ENVIRONMENT_VARIABLE];
+  if (environmentToken !== undefined) {
+    const apiBaseUrl = await resolveApiBaseUrl(environment);
+    const config = await loadConfig(invocation);
+    if (!config.siteId) throw siteMissingError();
+    const client = invocation.client
+      ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, environmentToken));
+    return { config, client, siteId: config.siteId, now, onProgress };
+  }
+
+  let config;
+  let apiBaseUrl;
+  const signIn = await requireSignIn(environment, async () => {
+    apiBaseUrl = await resolveApiBaseUrl(environment);
+    config = await loadConfig(invocation);
+    return apiBaseUrl;
+  });
+  if (!config.siteId) throw siteMissingError();
+
+  // The server is the authority on expiry, so an expired sign-in is still sent
+  // — the clock here may simply be wrong. What is worth saying out loud is that
+  // the credential is already past the expiry it recorded, so a refusal that
+  // follows is explained rather than mysterious.
+  if (signIn.keyExpiresAt !== undefined && Date.parse(signIn.keyExpiresAt) <= now()) {
+    onProgress(
+      `The stored sign-in expired at ${signIn.keyExpiresAt}. `
+        + `If Taproot refuses it, run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+    );
+  }
+
+  // A caller may supply the site client directly (tests, and the verbs that
+  // already hold one); otherwise the sign-in is exchanged for one.
+  if (invocation.client) {
+    return { config, client: invocation.client, siteId: config.siteId, now, onProgress };
+  }
+
+  const accountClient = new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, signIn.key));
+  const exchanged = await exchangeSiteAuthoringToken(accountClient, {
+    siteId: config.siteId,
+    capabilities: invocation.capabilities ?? [],
+  });
+  // Two non-secret facts the store should now carry: the sign-in's slid
+  // deadline, and what this exchange actually produced — the latter is the only
+  // thing that lets `whoami` answer offline with the real grant rather than the
+  // ceiling.
+  //
+  // A compare-and-set, not a save: the record was read before a network round
+  // trip, and in that window a concurrent logout may have removed it or a
+  // login replaced it. Writing the pre-flight copy back would resurrect a
+  // discarded credential or overwrite a newer one.
+  //
+  // Best-effort: failing a command because its *metadata* could not be recorded
+  // would trade a working run for a cosmetic accuracy, and the next exchange
+  // tries again.
+  try {
+    await updateCredentialMetadata(
+      environment,
+      credentialApiOrigin(apiBaseUrl),
+      signIn.keyId,
+      {
+        ...(exchanged.signInExpiresAt === undefined ? {} : { keyExpiresAt: exchanged.signInExpiresAt }),
+        lastExchange: {
+          siteId: exchanged.siteId,
+          capabilities: exchanged.capabilities,
+          expiresAt: exchanged.expiresAt,
+        },
+      },
+    );
+  } catch {
+    // Deliberately swallowed; see above.
+  }
+
+  const client = new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, exchanged.key));
+  return {
+    config,
+    client,
+    siteId: config.siteId,
+    exchanged: {
+      keyId: exchanged.keyId,
+      keyPrefix: exchanged.keyPrefix,
+      expiresAt: exchanged.expiresAt,
+      capabilities: exchanged.capabilities,
+    },
+    now,
+    onProgress,
+  };
+}
+
+/**
+ * The credential-free half of the session seam, for the verbs that manage the
+ * credential rather than use it.
+ *
+ * Since TR00645 `login` needs no site and therefore no configuration at all:
+ * the account sign-in is addressed by API origin, which has a default. So the
+ * configuration is loaded when one is discoverable and quietly skipped when it
+ * is not — which is what lets `npm i -g` then `login` work in any directory.
+ */
+export async function openAnonymousSession(invocation = {}) {
+  let config;
+  try {
+    config = await loadConfig(invocation);
+  } catch (error) {
+    // Only "there is no configuration here" is tolerated, and only when the
+    // caller did not name one. Every other config failure — malformed JSON, a
+    // duplicate key, an unsafe workspace path, an unreviewed API origin —
+    // surfaces. Swallowing those would silently fall back to the production
+    // origin and let  overwrite a configuration written for another one.
+    if (invocation.configPath !== undefined) throw error;
+    if (!(error instanceof SiteAuthoringError) || error.code !== "config.not_found") throw error;
+    config = undefined;
+  }
+
+  // The endpoint comes from the machine, not the project (TR00645). It has to:
+  // `login`, `sites`, and `use` all run before a project configuration exists,
+  // so a project-pinned endpoint could never have told the first of them where
+  // to go.
+  const apiBaseUrl = await resolveApiBaseUrl(invocation.environment ?? process.env);
+  // `client: null` is how openAccountSession borrows the config resolution
+  // without paying for an anonymous client it will immediately replace.
+  const client = invocation.client === null
+    ? undefined
+    : invocation.client ?? SiteApiClient.anonymous(buildClientOptions(invocation, apiBaseUrl));
+  return {
+    config,
+    apiBaseUrl,
+    client,
+    now: invocation.now ?? Date.now,
+    onProgress: progressSink(invocation),
+  };
+}
+
+/**
+ * Bounds a list that is about to travel in a result. The result must fit
+ * `LIMITS.githubOutputBytes`, and an unbounded per-item report over a large
+ * site would blow that bound and turn a successful run into an
+ * `output.too_large` failure — losing the record of work that already
+ * happened. Truncation is reported, never silent.
+ */
+export function boundedList(values, maximum) {
+  const items = values.slice(0, maximum);
+  return items.length === values.length
+    ? { items, count: values.length }
+    : { items, count: values.length, truncated: true };
+}
+
+export function successResult(verb, siteId, payload = {}) {
+  return {
+    schemaVersion: RESULT_SCHEMA_VERSION,
+    ok: true,
+    cli: { name: CLI_NAME, version: CLI_VERSION },
+    verb,
+    ...(siteId === undefined ? {} : { siteId }),
+    ...payload,
+  };
+}

package/src/settings-catalog.js

@@ -0,0 +1,187 @@
+import { parseTheme } from "@taprootio/espalier/shared/theme";
+
+import { SiteAuthoringError } from "./errors.js";
+import { projectFooterSettingsForWorkspace } from "./footer-contract.js";
+
+/**
+ * The settings surface the authoring CLI covers.
+ *
+ * `GetSettings` answers with a oneof-shaped envelope: one property per group,
+ * and — because proto3 omits zero values — a field the site has never set is
+ * simply absent rather than present-and-default. A snapshot that inherited that
+ * omission would be unreadable: an agent could not tell "unset" from "not part
+ * of this group", and a later diff would churn. So the projection below
+ * materializes every in-scope field at its zero value, which is exactly what
+ * the server would answer with.
+ *
+ * Scope (TR00604's refinement):
+ * - The four theme-gated groups are covered. `SETTING_TYPE_SITE_RUNTIME_PREFERENCES`
+ *   is not: it is gated on `site.settings.manage` rather than theme management,
+ *   promotes immediately rather than through staging, and is site administration
+ *   rather than authored presentation.
+ * - `lightTheme` and `darkTheme` are decoded into readable JSON objects. Theme
+ *   push validates and re-encodes them only at the wire boundary.
+ * - `footerSettings` is snapshotted as its structured document. Theme push
+ *   overlays only its scheme colors onto a fresh server read before using the
+ *   optimistic-concurrency footer endpoint.
+ * - `membershipsEnabled` is excluded. It appears in the publishing-preferences
+ *   message but not in the group's settable field set: it is a plan-derived
+ *   flag the server computes, not site configuration a workspace owns.
+ *
+ * `wireType` records how a field crosses `SetSetting`, whose `value` is a bare
+ * string for every type. Theme push uses it for scalar writes; complete themes
+ * and footer settings take their dedicated validated paths. It also lets the
+ * read projection normalize an omitted field to the right zero value.
+ */
+
+export const SETTINGS_TYPE_TAPROOT_STYLES = "SETTING_TYPE_TAPROOT_STYLES";
+export const SETTINGS_TYPE_BRAND = "SETTING_TYPE_BRAND";
+export const SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES = "SETTING_TYPE_SITE_PUBLISHING_PREFERENCES";
+export const SETTINGS_TYPE_SITE_HEADER = "SETTING_TYPE_SITE_HEADER";
+
+function stringFields(...names) {
+  return names.map((name) => ({ name, wireType: "string" }));
+}
+
+export const SETTINGS_GROUPS = Object.freeze([
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    // The property `GetSettingsResponse` carries this group's message under.
+    responseProperty: "styleSettings",
+    // The workspace file `pull` writes this group into.
+    file: "taproot-styles.json",
+    candidateSelectable: true,
+    fields: Object.freeze([
+      { name: "lightTheme", wireType: "theme" },
+      { name: "darkTheme", wireType: "theme" },
+      ...stringFields(
+        "defaultScheme",
+        "fontBrand",
+        "fontWeightBrand",
+        "lightLogoId",
+        "lightLogoUrl",
+        "darkLogoId",
+        "darkLogoUrl",
+        "lightCanvasImageId",
+        "lightCanvasImageUrl",
+        "darkCanvasImageId",
+        "darkCanvasImageUrl",
+      ),
+      { name: "lightCanvasImageOpacity", wireType: "double" },
+      { name: "darkCanvasImageOpacity", wireType: "double" },
+    ]),
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_BRAND,
+    responseProperty: "brandSettings",
+    file: "brand.json",
+    candidateSelectable: true,
+    fields: Object.freeze(stringFields("faviconId", "faviconUrl")),
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    responseProperty: "headerSettings",
+    file: "site-header.json",
+    candidateSelectable: true,
+    fields: Object.freeze([
+      ...stringFields(
+        "headerLayout",
+        "brandText",
+        "brandColor",
+        "logoAlt",
+        "navMenuDisplay",
+        "headerPosition",
+        "lightBrandColor",
+        "darkBrandColor",
+      ),
+      { name: "showThemeToggle", wireType: "boolean" },
+      { name: "showBrandText", wireType: "boolean" },
+      { name: "brandLogoSize", wireType: "string" },
+      { name: "brandHoverGrow", wireType: "boolean" },
+    ]),
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+    responseProperty: "sitePublishingPreferences",
+    file: "site-publishing-preferences.json",
+    candidateSelectable: true,
+    fields: Object.freeze([
+      // `commentsMode` is an enum; on the wire it is the enum's name string,
+      // and an omitted value reads as the zero member — which is spelled
+      // UNSPECIFIED here, not UNKNOWN as most of this contract's enums are
+      // (protos/Settings.proto). A snapshot naming a member that does not
+      // exist is worse than one that omits the field.
+      { name: "commentsMode", wireType: "enum", zero: "SITE_COMMENTS_MODE_UNSPECIFIED" },
+      ...stringFields("tiptapImagePlacement"),
+      { name: "allowSearch", wireType: "boolean" },
+      { name: "albumSeamless", wireType: "boolean" },
+      { name: "tiptapImageMaxHeightVh", wireType: "int" },
+      { name: "tiptapImageBorderWidth", wireType: "int" },
+      { name: "albumBorderWidth", wireType: "int" },
+      { name: "footerSettings", wireType: "document", zero: {} },
+    ]),
+  }),
+]);
+
+export const CANDIDATE_SELECTABLE_SETTINGS_TYPES = Object.freeze(
+  SETTINGS_GROUPS.filter((group) => group.candidateSelectable).map((group) => group.settingsType),
+);
+
+function zeroValue(field) {
+  if (field.wireType === "boolean") return false;
+  if (field.wireType === "int" || field.wireType === "double") return 0;
+  if (field.wireType === "theme" || field.wireType === "document") return field.zero ?? {};
+  return field.zero ?? "";
+}
+
+function normalizeField(field, value) {
+  if (value === undefined || value === null) {
+    const zero = zeroValue(field);
+    return field.wireType === "document" && field.name === "footerSettings"
+      ? projectFooterSettingsForWorkspace(zero)
+      : zero;
+  }
+  if (field.wireType === "theme") return decodeTheme(value, field.name);
+  if (field.wireType === "document") {
+    const document_ = typeof value === "object" && !Array.isArray(value) ? value : zeroValue(field);
+    return field.name === "footerSettings" ? projectFooterSettingsForWorkspace(document_) : document_;
+  }
+  if (field.wireType === "boolean") return value === true;
+  if (field.wireType === "int" || field.wireType === "double") {
+    // Transcoded 64-bit and some 32-bit numerics arrive as strings.
+    const numeric = typeof value === "string" ? Number(value) : value;
+    return typeof numeric === "number" && Number.isFinite(numeric) ? numeric : zeroValue(field);
+  }
+  return typeof value === "string" ? value : zeroValue(field);
+}
+
+function decodeTheme(value, field) {
+  if (value === "") return {};
+  const theme = typeof value === "string" ? parseTheme(value) : undefined;
+  if (!theme) {
+    throw new SiteAuthoringError(
+      "api.theme_contract",
+      "Taproot returned a non-empty theme that could not be decoded.",
+      { field },
+    );
+  }
+  return theme;
+}
+
+/**
+ * Projects one `GetSettings` response down to the fields this CLI covers,
+ * materializing the zero value for every field proto3 omitted. Fields outside
+ * the catalog are dropped rather than snapshotted, so the workspace never
+ * records something the CLI cannot round-trip.
+ */
+export function projectSettingsGroup(group, response) {
+  const message = response !== null && typeof response === "object" && !Array.isArray(response)
+    ? response[group.responseProperty]
+    : undefined;
+  const source = message !== null && typeof message === "object" && !Array.isArray(message) ? message : {};
+  const projected = {};
+  for (const field of group.fields) {
+    projected[field.name] = normalizeField(field, source[field.name]);
+  }
+  return projected;
+}

package/src/settings.js

@@ -0,0 +1,157 @@
+import { lstat, mkdir, open, unlink } from "node:fs/promises";
+import path from "node:path";
+
+import { atomicWriteFile } from "./atomic-file.js";
+import { readBoundedFile } from "./bounded-file.js";
+import { parseJsonWithDuplicateGuard } from "./json-guard.js";
+import { credentialStoreDirectory } from "./credentials.js";
+import {
+  CREDENTIAL_DIRECTORY_MODE,
+  DEFAULT_API_BASE_URL,
+  ENVIRONMENT_LOCAL,
+  ENVIRONMENT_PRODUCTION,
+  LIMITS,
+  LOCAL_API_BASE_URL,
+  SETTINGS_FILE_MODE,
+  SETTINGS_FILE_NAME,
+  SETTINGS_VERSION,
+} from "./constants.js";
+import { SiteAuthoringError } from "./errors.js";
+import { validateApiBaseUrl } from "./config.js";
+
+/**
+ * Which Taproot this machine talks to (TR00645).
+ *
+ * Deliberately not the credential store, though it sits beside it. The store
+ * holds secrets at 0600 and is keyed by origin; this holds one non-secret
+ * choice *of* an origin, and conflating them would either widen the store's
+ * shape or narrow this file's permissions for no reason. Absent means
+ * production, so the file existing at all is the exception.
+ */
+export function settingsPath(environment = {}) {
+  return path.join(credentialStoreDirectory(environment), SETTINGS_FILE_NAME);
+}
+
+/** The named environment an origin corresponds to, for reporting. */
+export function environmentNameFor(apiBaseUrl) {
+  if (apiBaseUrl === DEFAULT_API_BASE_URL) return ENVIRONMENT_PRODUCTION;
+  if (apiBaseUrl === LOCAL_API_BASE_URL) return ENVIRONMENT_LOCAL;
+  return "custom";
+}
+
+/**
+ * Resolves `local` / `production` / an explicit URL to a validated base URL.
+ * The explicit form exists for a loopback port during development; it clears
+ * exactly the bar a configuration's own origin had to clear, so `env` cannot
+ * reach somewhere `taproot-site.json` could not.
+ */
+export function resolveEnvironmentSelector(selector) {
+  if (selector === ENVIRONMENT_PRODUCTION) return DEFAULT_API_BASE_URL;
+  if (selector === ENVIRONMENT_LOCAL) return LOCAL_API_BASE_URL;
+  return validateApiBaseUrl(selector);
+}
+
+/**
+ * The stored endpoint, or undefined when none is set.
+ *
+ * A malformed settings file refuses rather than falling back to production:
+ * an operator who set this to local and then reads a corrupt file back should
+ * be told, not silently pointed at the live Taproot.
+ */
+export async function readStoredApiBaseUrl(environment = {}) {
+  const filePath = settingsPath(environment);
+  // The same bounded, no-follow read the credential store uses, for the same
+  // reason: this path is under the operator's home and editable by anything
+  // running as them. A plain readFile would follow a symlink to a FIFO and
+  // block, or to a device and read until memory ran out — both before any
+  // size check on the result could run.
+  const bytes = await readBoundedFile(filePath, {
+    maximumBytes: LIMITS.settingsBytes,
+    failures: {
+      isOwn: (error) => error instanceof SiteAuthoringError,
+      inspect: () => new SiteAuthoringError("settings.unreadable", `Could not inspect '${filePath}'.`),
+      notRegular: () =>
+        new SiteAuthoringError("settings.not_regular", `'${filePath}' must be a regular file, not a link or directory.`),
+      tooLarge: () =>
+        new SiteAuthoringError("settings.too_large", `'${filePath}' is larger than ${LIMITS.settingsBytes} bytes.`),
+      changed: () => new SiteAuthoringError("settings.changed", `'${filePath}' changed while it was being read.`),
+      read: () => new SiteAuthoringError("settings.unreadable", `Could not read '${filePath}'.`),
+    },
+  });
+  if (bytes === undefined) return undefined;
+  const contents = bytes.toString("utf8");
+
+  // Duplicate-guarded, not JSON.parse: this file is hand-editable, and a
+  // second `apiBaseUrl` would make what it visibly says and where it routes a
+  // credential two different Taproots.
+  const parsed = parseJsonWithDuplicateGuard(contents, {
+    onDuplicate: (key) =>
+      new SiteAuthoringError("settings.duplicate_key", `'${filePath}' declares '${key}' more than once.`),
+    onInvalid: () => new SiteAuthoringError("settings.malformed", `'${filePath}' is not valid JSON.`),
+  });
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new SiteAuthoringError("settings.malformed", `'${filePath}' must be a JSON object.`);
+  }
+  if (parsed.schemaVersion !== SETTINGS_VERSION) {
+    throw new SiteAuthoringError("settings.unsupported_version", `'${filePath}' must declare schemaVersion ${SETTINGS_VERSION}.`);
+  }
+  if (typeof parsed.apiBaseUrl !== "string") {
+    throw new SiteAuthoringError("settings.malformed", `'${filePath}' has no apiBaseUrl.`);
+  }
+  // Re-validated on the way out, not just on the way in: the file is editable
+  // by hand, and this is the last point before the value becomes the origin a
+  // credential is sent to.
+  return validateApiBaseUrl(parsed.apiBaseUrl);
+}
+
+async function ensureSettingsDirectory(directory) {
+  try {
+    await mkdir(directory, { recursive: true, mode: CREDENTIAL_DIRECTORY_MODE });
+  } catch {
+    throw new SiteAuthoringError("settings.unwritable", "Could not create the configuration directory.");
+  }
+  let stats;
+  try {
+    stats = await lstat(directory);
+  } catch {
+    throw new SiteAuthoringError("settings.unwritable", "Could not inspect the configuration directory.");
+  }
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new SiteAuthoringError(
+      "settings.directory_invalid",
+      "The configuration directory must be a real directory, not a link or file.",
+    );
+  }
+}
+
+/**
+ * Records the endpoint. Production clears the file rather than writing the
+ * default into it, so "no file" and "production" stay the same state and there
+ * is only one thing a fresh machine can mean.
+ */
+export async function writeStoredApiBaseUrl(environment, apiBaseUrl) {
+  const filePath = settingsPath(environment);
+  if (apiBaseUrl === DEFAULT_API_BASE_URL) {
+    try {
+      await unlink(filePath);
+    } catch (error) {
+      if (!error || typeof error !== "object" || error.code !== "ENOENT") {
+        throw new SiteAuthoringError("settings.unwritable", `Could not clear '${filePath}'.`);
+      }
+    }
+    return filePath;
+  }
+
+  await ensureSettingsDirectory(path.dirname(filePath));
+  const contents = `${JSON.stringify({ schemaVersion: SETTINGS_VERSION, apiBaseUrl }, undefined, 2)}\n`;
+  await atomicWriteFile(filePath, contents, {
+    mode: SETTINGS_FILE_MODE,
+    openDirectory: open,
+    failures: {
+      inspect: () => new SiteAuthoringError("settings.unwritable", `Could not inspect '${filePath}'.`),
+      notRegular: () => new SiteAuthoringError("settings.not_regular", `'${filePath}' is not a regular file.`),
+      write: () => new SiteAuthoringError("settings.unwritable", `Could not write '${filePath}'.`),
+    },
+  });
+  return filePath;
+}