@taprootio/site-authoring 0.1.0

package/src/appearance-contract.js

@@ -0,0 +1,311 @@
+import { hasControlCharacter, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import {
+  SETTINGS_TYPE_BRAND,
+  SETTINGS_TYPE_SITE_HEADER,
+  SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+  SETTINGS_TYPE_TAPROOT_STYLES,
+} from "./settings-catalog.js";
+import { FOOTER_COLOR_TOKENS, HEADER_BRAND_COLOR_TOKENS, requireAppearanceColor } from "./theme-validation.js";
+
+export const APPEARANCE_FILES = Object.freeze({
+  [SETTINGS_TYPE_TAPROOT_STYLES]: "settings/taproot-styles.json",
+  [SETTINGS_TYPE_BRAND]: "settings/brand.json",
+  [SETTINGS_TYPE_SITE_HEADER]: "settings/site-header.json",
+  [SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]: "settings/site-publishing-preferences.json",
+});
+
+// Declaration order is both mutation order and help order. Adding a writable
+// scalar therefore changes one executable registry instead of a validator,
+// request mapper, and prose list independently.
+export const APPEARANCE_SCALAR_FIELDS = Object.freeze([
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    name: "defaultScheme",
+    path: "taproot-styles.defaultScheme",
+    type: "enum",
+    values: Object.freeze(["system", "light", "dark"]),
+    default: "light",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    name: "fontBrand",
+    path: "taproot-styles.fontBrand",
+    type: "string",
+    default: "",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    name: "fontWeightBrand",
+    path: "taproot-styles.fontWeightBrand",
+    type: "string",
+    default: "",
+  }),
+  ...["lightLogoId", "darkLogoId", "lightCanvasImageId", "darkCanvasImageId"].map((name) =>
+    Object.freeze({
+      settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+      name,
+      path: `taproot-styles.${name}`,
+      type: "site-owned-image-id",
+      default: "",
+    })
+  ),
+  ...["lightCanvasImageOpacity", "darkCanvasImageOpacity"].map((name) =>
+    Object.freeze({
+      settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+      name,
+      path: `taproot-styles.${name}`,
+      type: "number",
+      minimum: 0,
+      maximum: 1,
+      default: 1,
+    })
+  ),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_BRAND,
+    name: "faviconId",
+    path: "brand.faviconId",
+    type: "site-owned-image-id",
+    default: "",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "headerLayout",
+    path: "site-header.headerLayout",
+    type: "enum",
+    values: Object.freeze(["standard", "centered-brand", "minimal"]),
+    default: "standard",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "brandText",
+    path: "site-header.brandText",
+    type: "plain-text",
+    maximumLength: 120,
+    default: "",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "logoAlt",
+    path: "site-header.logoAlt",
+    type: "plain-text",
+    maximumLength: 160,
+    default: "",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "navMenuDisplay",
+    path: "site-header.navMenuDisplay",
+    type: "enum",
+    values: Object.freeze(["auto", "drawer"]),
+    default: "auto",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "headerPosition",
+    path: "site-header.headerPosition",
+    type: "enum",
+    values: Object.freeze(["normal", "sticky"]),
+    default: "normal",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "showThemeToggle",
+    path: "site-header.showThemeToggle",
+    type: "boolean",
+    default: false,
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "showBrandText",
+    path: "site-header.showBrandText",
+    type: "boolean",
+    default: true,
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "brandLogoSize",
+    path: "site-header.brandLogoSize",
+    type: "enum",
+    values: Object.freeze(["standard", "large", "full"]),
+    default: "standard",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "brandHoverGrow",
+    path: "site-header.brandHoverGrow",
+    type: "boolean",
+    default: false,
+  }),
+  ...["brandColor", "lightBrandColor", "darkBrandColor"].map((name) =>
+    Object.freeze({
+      settingsType: SETTINGS_TYPE_SITE_HEADER,
+      name,
+      path: `site-header.${name}`,
+      type: "appearance-color",
+      allowedTokens: HEADER_BRAND_COLOR_TOKENS,
+      default: "",
+    })
+  ),
+]);
+
+export const APPEARANCE_READ_ONLY_FIELDS = Object.freeze([
+  Object.freeze({ file: APPEARANCE_FILES[SETTINGS_TYPE_TAPROOT_STYLES], path: "settings.lightLogoUrl" }),
+  Object.freeze({ file: APPEARANCE_FILES[SETTINGS_TYPE_TAPROOT_STYLES], path: "settings.darkLogoUrl" }),
+  Object.freeze({ file: APPEARANCE_FILES[SETTINGS_TYPE_TAPROOT_STYLES], path: "settings.lightCanvasImageUrl" }),
+  Object.freeze({ file: APPEARANCE_FILES[SETTINGS_TYPE_TAPROOT_STYLES], path: "settings.darkCanvasImageUrl" }),
+  Object.freeze({ file: APPEARANCE_FILES[SETTINGS_TYPE_BRAND], path: "settings.faviconUrl" }),
+]);
+
+export const APPEARANCE_FOOTER_COLOR_FIELDS = Object.freeze(
+  ["light", "dark"].flatMap((scheme) =>
+    Object.keys(FOOTER_COLOR_TOKENS).map((name) =>
+      Object.freeze({
+        file: APPEARANCE_FILES[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES],
+        path: `settings.footerSettings.${scheme}.${name}`,
+        scheme,
+        name,
+        type: "appearance-color",
+        default: "",
+        allowedTokens: FOOTER_COLOR_TOKENS[name],
+      })
+    )
+  ),
+);
+
+export const APPEARANCE_IMAGE_FIELDS = Object.freeze(
+  APPEARANCE_SCALAR_FIELDS.filter((field) => field.type === "site-owned-image-id"),
+);
+
+export function appearanceImageIds(documents) {
+  return [...new Set(APPEARANCE_IMAGE_FIELDS
+    .map((field) => documents[field.settingsType]?.[field.name])
+    .filter((value) => isCanonicalUuid(value)))].sort();
+}
+
+function fail(code, message, field) {
+  throw new SiteAuthoringError(code, message, { field });
+}
+
+function requireString(value, field, maximum = 256 * 1024) {
+  if (typeof value !== "string" || value.length > maximum || hasControlCharacter(value)) {
+    fail("theme.setting_invalid", `${field} must be a bounded printable string.`, field);
+  }
+  return value;
+}
+
+function validateScalar(definition, value, knownImageIds) {
+  switch (definition.type) {
+    case "enum":
+      if (typeof value !== "string" || !definition.values.includes(value)) {
+        fail(
+          "theme.setting_invalid",
+          `${definition.path} must be one of ${definition.values.join(", ")}.`,
+          definition.path,
+        );
+      }
+      return value;
+    case "string":
+      return requireString(value, definition.path);
+    case "plain-text": {
+      const text = requireString(value, definition.path, definition.maximumLength);
+      if ([...text].some((character) => character === "<" || character === ">" || character === "\"")) {
+        fail("theme.setting_invalid", `${definition.path} cannot contain markup-breaking characters.`, definition.path);
+      }
+      return text;
+    }
+    case "site-owned-image-id":
+      if (typeof value !== "string" || (value !== "" && !isCanonicalUuid(value))) {
+        fail(
+          "theme.image_id_invalid",
+          `${definition.path} must be empty or a canonical lowercase site-owned image ID from pull or 'media upload'.`,
+          definition.path,
+        );
+      }
+      if (value !== "" && !knownImageIds.has(value)) {
+        fail(
+          "theme.image_reference_unknown",
+          `${definition.path} must name an image retained from pull or recorded by 'media upload'.`,
+          definition.path,
+        );
+      }
+      return value;
+    case "number":
+      if (
+        typeof value !== "number"
+        || !Number.isFinite(value)
+        || value < definition.minimum
+        || value > definition.maximum
+      ) {
+        fail(
+          "theme.setting_invalid",
+          `${definition.path} must be a number from ${definition.minimum} through ${definition.maximum}.`,
+          definition.path,
+        );
+      }
+      return String(value);
+    case "boolean":
+      if (typeof value !== "boolean") {
+        fail("theme.setting_invalid", `${definition.path} must be true or false.`, definition.path);
+      }
+      return String(value);
+    case "appearance-color":
+      return requireAppearanceColor(value, definition.allowedTokens, definition.path);
+    default:
+      throw new TypeError(`Unknown appearance field type '${definition.type}'.`);
+  }
+}
+
+export function buildAppearanceScalarOperations(documents, knownImageIds) {
+  if (!(knownImageIds instanceof Set)) {
+    throw new TypeError("Appearance validation requires the known site-owned image identities.");
+  }
+  return APPEARANCE_SCALAR_FIELDS.map((definition) => ({
+    settingsType: definition.settingsType,
+    setting: definition.name,
+    value: validateScalar(definition, documents[definition.settingsType]?.[definition.name], knownImageIds),
+  }));
+}
+
+export function footerColorOverlay(workspaceFooter) {
+  if (workspaceFooter === null || typeof workspaceFooter !== "object" || Array.isArray(workspaceFooter)) {
+    fail(
+      "theme.footer_missing",
+      "site-publishing-preferences.footerSettings is missing. Run 'taproot-site pull' again.",
+      "site-publishing-preferences.footerSettings",
+    );
+  }
+  const colors = { light: {}, dark: {} };
+  for (const definition of APPEARANCE_FOOTER_COLOR_FIELDS) {
+    const scheme = workspaceFooter[definition.scheme];
+    if (scheme === null || typeof scheme !== "object" || Array.isArray(scheme)) {
+      fail(
+        "theme.footer_invalid",
+        `footerSettings.${definition.scheme} must be an object.`,
+        `footerSettings.${definition.scheme}`,
+      );
+    }
+    colors[definition.scheme][definition.name] = requireAppearanceColor(
+      scheme[definition.name] === undefined ? "" : scheme[definition.name],
+      definition.allowedTokens,
+      `footerSettings.${definition.scheme}.${definition.name}`,
+    );
+  }
+  return colors;
+}
+
+export function applyFooterColors(currentFooter, colors) {
+  const next = structuredClone(
+    currentFooter !== null && typeof currentFooter === "object" && !Array.isArray(currentFooter)
+      ? currentFooter
+      : {},
+  );
+  for (const scheme of ["light", "dark"]) {
+    next[scheme] = {
+      ...(next[scheme] !== null && typeof next[scheme] === "object" && !Array.isArray(next[scheme])
+        ? next[scheme]
+        : {}),
+      ...colors[scheme],
+    };
+  }
+  return next;
+}

package/src/atomic-file.js

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { chmod, lstat, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * The one durable single-file write in this package (TR00645).
+ *
+ * Two callers need the identical sequence and used to carry their own copy of
+ * it: `writeWorkspaceFile` in `workspace.js`, which replaces a pulled page, and
+ * the credential store in `credentials.js`, which replaces the file holding a
+ * live key. The credential module's comment acknowledged the duplication and
+ * justified it on the grounds that the workspace function is bound to a
+ * validated workspace — true of that function's *path handling*, and not of the
+ * write discipline underneath it. Splitting the two apart leaves one primitive
+ * here and each caller's own containment rules where they belong.
+ *
+ * The discipline, and why each step is in it:
+ *
+ * 1. **`lstat` the destination first.** A symlink or a non-regular file at the
+ *    target is refused rather than followed, so neither caller can be turned
+ *    into a writer of some other file by something planted in its directory.
+ *    `lstat` rather than `stat` is the whole point — `stat` would resolve the
+ *    link and report the target as a perfectly ordinary file.
+ * 2. **Write a temp file in the same directory**, opened
+ *    `O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW`. `O_EXCL` means an attacker cannot
+ *    pre-create the temp path and have us write through it; `O_NOFOLLOW` means
+ *    they cannot pre-create it as a link. Same directory so the rename below is
+ *    a rename and not a cross-device copy.
+ * 3. **fsync before the rename.** The rename is the commit point, and a rename
+ *    that commits a file whose contents have not reached disk is exactly how a
+ *    crash produces a truncated credential or a half-written page.
+ * 4. **Rename over the destination.** Atomic, so a concurrent reader sees the
+ *    complete old file or the complete new one and never a partial write.
+ * 5. **Best-effort parent-directory sync**, which makes the rename itself
+ *    durable. Deliberately swallowed: the replacement is already live, and
+ *    platforms that refuse directory handles must not turn a committed write
+ *    into a reported failure.
+ * 6. **Unlink the temp file on any failure**, so a failed write leaves nothing
+ *    behind to accumulate beside the real one.
+ *
+ * Messages stay with the callers. Both surfaces have their own vocabulary and
+ * their own error codes, and collapsing them into one generic "could not write
+ * file" would make every refusal less useful than the two it replaced — so the
+ * caller supplies the three failures this can produce.
+ */
+
+/**
+ * Replaces one file atomically.
+ *
+ * @param {string} filePath Absolute path to replace. Callers are responsible
+ *   for having validated it and for having created its directory.
+ * @param {string} contents UTF-8 contents to write.
+ * @param {object} options
+ * @param {number} [options.mode] Creation mode for the temp file. Defaults to
+ *   `0600`, the safe choice for both current callers.
+ * @param {boolean} [options.pinMode] Re-apply `mode` with an explicit `chmod`
+ *   after writing. The creation mode is narrowed by the process umask, so a
+ *   file that must be exactly `0600` whatever the operator's umask says needs
+ *   this; a file that only must not be *wider* than `mode` does not. Advisory
+ *   on Windows, so a failure here never fails the write.
+ * @param {Function} [options.openDirectory] Injection seam for the parent
+ *   directory sync, so a test can exercise the unsupported-directory-handle
+ *   path without a platform that has one.
+ * @param {{inspect: Function, notRegular: Function, write: Function}}
+ *   options.failures Factories for this caller's three refusals.
+ * @returns {Promise<string>} The path that was replaced.
+ */
+export async function atomicWriteFile(filePath, contents, {
+  mode = 0o600,
+  pinMode = false,
+  openDirectory = open,
+  failures,
+} = {}) {
+  const directory = path.dirname(filePath);
+
+  let existing;
+  try {
+    existing = await lstat(filePath);
+  } catch (error) {
+    // A missing destination is the ordinary case for a first write, not a
+    // failure. Anything else means we cannot vouch for what is there.
+    if (!error || typeof error !== "object" || error.code !== "ENOENT") {
+      throw failures.inspect();
+    }
+  }
+  if (existing && (existing.isSymbolicLink() || !existing.isFile())) {
+    throw failures.notRegular();
+  }
+
+  const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+  let handle;
+  let renamed = false;
+  try {
+    handle = await open(
+      temporaryPath,
+      fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | (fsConstants.O_NOFOLLOW ?? 0),
+      mode,
+    );
+    await handle.writeFile(contents, { encoding: "utf8" });
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    if (pinMode) {
+      try {
+        await chmod(temporaryPath, mode);
+      } catch {
+        // Best-effort: Windows does not honor POSIX modes.
+      }
+    }
+    await rename(temporaryPath, filePath);
+    renamed = true;
+  } catch (error) {
+    if (error instanceof SiteAuthoringError) throw error;
+    throw failures.write();
+  } finally {
+    await handle?.close().catch(() => {});
+    if (!renamed) await unlink(temporaryPath).catch(() => {});
+  }
+
+  let directoryHandle;
+  try {
+    directoryHandle = await openDirectory(
+      directory,
+      fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0),
+    );
+    await directoryHandle.sync();
+  } catch {
+    // Best-effort durability only; the complete replacement is already live.
+  } finally {
+    await directoryHandle?.close().catch(() => {});
+  }
+  return filePath;
+}

package/src/bounded-file.js

@@ -0,0 +1,59 @@
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+
+/**
+ * One bounded, no-follow read of a small local file, shared by the credential
+ * store and the machine settings (TR00645).
+ *
+ * The discipline: `lstat` first and refuse anything that is not a regular file
+ * (so a symlink is never followed), open with `O_NOFOLLOW | O_NONBLOCK` (so a
+ * FIFO or device swapped in under the path cannot block the process), confirm
+ * the opened inode is the one inspected, and read at most `maximumBytes + 1`
+ * — the extra byte is how "too large" is detected without trusting the size
+ * `lstat` reported. A plain `readFile` does none of that: it follows links,
+ * blocks on a FIFO, and reads an unbounded device to exhaustion before any
+ * post-read size check can run.
+ *
+ * Parameterized the way `atomicWriteFile` is: the caller supplies the failure
+ * factories so each store keeps its own error vocabulary, and one reader keeps
+ * one set of checks. A missing file resolves to `undefined`, because for both
+ * callers absence is a state — no sign-in yet, production by default — rather
+ * than a failure.
+ */
+export async function readBoundedFile(filePath, { maximumBytes, failures }) {
+  let stats;
+  try {
+    stats = await lstat(filePath, { bigint: true });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") return undefined;
+    throw failures.inspect();
+  }
+  if (stats.isSymbolicLink() || !stats.isFile()) throw failures.notRegular();
+  if (stats.size > BigInt(maximumBytes)) throw failures.tooLarge();
+
+  let handle;
+  try {
+    handle = await open(
+      filePath,
+      fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0),
+    );
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isFile() || opened.dev !== stats.dev || opened.ino !== stats.ino) throw failures.changed();
+    const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+    let total = 0;
+    while (total <= maximumBytes) {
+      const { bytesRead } = await handle.read(buffer, total, buffer.byteLength - total, total);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+    }
+    if (total > maximumBytes) throw failures.tooLarge();
+    return buffer.subarray(0, total);
+  } catch (error) {
+    // The factories above produce the caller's own error type; anything else
+    // is the filesystem talking, and gets the caller's generic read failure.
+    if (error instanceof Error && failures.isOwn(error)) throw error;
+    throw failures.read();
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}

package/src/capabilities.js

@@ -0,0 +1,29 @@
+/**
+ * The delegation capabilities an exchanged site credential can carry (TR00645).
+ *
+ * These are the client's copy of `SiteAuthoringKeyEnvelope.CapabilityKeys`, and
+ * the copy is deliberate: the CLI has to name them in `--capabilities` help and
+ * in `whoami` before it has talked to any server, and a value it cannot print
+ * without a network round trip is a value it cannot validate a typo against.
+ *
+ * The server remains the authority. It refuses anything outside its own
+ * envelope rather than trusting this list, so the worst a stale copy here can
+ * do is offer a capability the exchange then declines by name — a clear
+ * refusal, never a silently wider credential.
+ */
+export const CAPABILITY_CONTENT = "delegation.content";
+export const CAPABILITY_DESIGN = "delegation.design";
+export const CAPABILITY_DEPLOYMENTS = "delegation.deployments";
+
+export const SITE_AUTHORING_CAPABILITIES = Object.freeze([
+  CAPABILITY_CONTENT,
+  CAPABILITY_DESIGN,
+  CAPABILITY_DEPLOYMENTS,
+]);
+
+/** What each capability lets an exchanged credential do, for help and `whoami`. */
+export const SITE_AUTHORING_CAPABILITY_SUMMARIES = Object.freeze({
+  "delegation.content": "write pages and media",
+  "delegation.design": "set the theme, navigation, and footer",
+  "delegation.deployments": "stage and deploy",
+});