@elixpo/lixblogs-cli 1.1.2

package/src/config/KeychainCredentialStore.js

@@ -0,0 +1,180 @@
+/**
+ * KeychainCredentialStore — real OS-keychain-backed CredentialStore.
+ *
+ * Uses @napi-rs/keyring: macOS Keychain, Windows Credential Manager, Linux
+ * Secret Service/libsecret. Chosen over `keytar` because keytar is
+ * archived/deprecated (last release Feb 2022, no longer maintained);
+ * @napi-rs/keyring is the actively maintained equivalent with a similar API.
+ *
+ * Each profile's credentials are stored as a single JSON-serialized secret
+ * under a per-profile keychain entry — one entry per profile, not one
+ * entry per token field, so multi-profile isolation (see THREAT_MODEL.md
+ * §5) maps directly onto separate keychain entries rather than a shared
+ * blob multiple profiles could collide in.
+ *
+ * This class throws on any underlying failure — it does NOT catch and
+ * silently return null/succeed. Per #135's "explicit opt-in fallback"
+ * requirement, silent degradation here would be exactly the wrong
+ * behavior; the caller (via GatedCredentialStore, see CredentialStore.js)
+ * is responsible for catching this and prompting for explicit opt-in.
+ */
+
+import { Entry } from "@napi-rs/keyring";
+import { CredentialStore } from "./CredentialStore.js";
+
+const SERVICE_NAME = "lixblogs-cli";
+const PROBE_PROFILE_ID = "__lixblogs_availability_probe__";
+
+function entryFor(profileId) {
+  return new Entry(SERVICE_NAME, profileId);
+}
+
+/**
+ * Checks whether the OS keychain backend is actually reachable.
+ *
+ * IMPORTANT, discovered empirically while building this (not assumed):
+ * on at least one backend (headless Linux, no Secret Service running),
+ * Entry.getPassword() on a missing entry returns null instead of
+ * throwing — even when the backend is completely unreachable. That means
+ * get() alone cannot distinguish "nothing stored yet" from "keychain is
+ * broken." Entry.setPassword() DOES throw reliably when the backend is
+ * unreachable in that same environment, so this probe uses a harmless
+ * write+delete round-trip to get a trustworthy signal there, rather than
+ * inferring availability from get().
+ *
+ * KNOWN LIMITATION, also discovered empirically (not theoretical): on at
+ * least one WSL setup, a probe call that fails (AccessDenied) can be
+ * followed by an unrelated Entry's setPassword() succeeding moments
+ * later, even though the probe itself correctly reported unavailability.
+ * This matches a documented upstream keyring-rs issue where WSL with
+ * systemd enabled has only a Secret Service *session* collection and no
+ * *default* collection — the first call against the (missing) default
+ * collection fails, but the backend appears to recover or fall back on
+ * a subsequent call. Practical implication: this probe is a best-effort
+ * signal, not a guarantee — a single probe result should be trusted for
+ * the immediate decision (fail vs. proceed) but must not be assumed to
+ * hold true for every subsequent call in the same process on every
+ * platform. If this proves unreliable enough in practice, a more robust
+ * approach (e.g. re-probing before every real operation, or shipping a
+ * documented "known platforms" support matrix) should be a follow-up.
+ *
+ * @returns {Promise<{ available: boolean, error?: string }>}
+ */
+export async function probeKeychainAvailability() {
+  const entry = entryFor(PROBE_PROFILE_ID);
+  try {
+    entry.setPassword("probe");
+    entry.deletePassword();
+    return { available: true };
+  } catch (err) {
+    // The underlying native error can include a multi-line Rust stack
+    // trace in its message — take only the first line for anything shown
+    // to a user; the full message is still available via err if needed
+    // for debugging (e.g. --verbose diagnostics, a later issue).
+    const firstLine = String(err.message ?? err).split("\n")[0].trim();
+    return { available: false, error: firstLine };
+  }
+}
+
+export class KeychainCredentialStore extends CredentialStore {
+  async get(profileId) {
+    const entry = entryFor(profileId);
+    let raw;
+    try {
+      raw = entry.getPassword();
+    } catch (err) {
+      // @napi-rs/keyring throws on some platforms/backends when no entry
+      // exists yet — that's a legitimate "not logged in" case, not a
+      // keychain-unavailable failure. Distinguish by message rather than
+      // swallowing all errors, so real unavailability still propagates.
+      if (isNotFoundError(err)) {
+        return null;
+      }
+      throw err;
+    }
+
+    // On some platforms/backends, a missing entry returns null/undefined
+    // rather than throwing (observed behavior, not assumed) — treat that
+    // the same as "not logged in," not as a parse error.
+    if (raw === null || raw === undefined) {
+      return null;
+    }
+
+    return JSON.parse(raw);
+  }
+
+  async set(profileId, credentials) {
+    const entry = entryFor(profileId);
+    entry.setPassword(JSON.stringify(credentials));
+  }
+
+  async delete(profileId) {
+    const entry = entryFor(profileId);
+    try {
+      entry.deletePassword();
+    } catch (err) {
+      if (isNotFoundError(err)) {
+        return; // deleting something that isn't there is not an error
+      }
+      throw err;
+    }
+  }
+
+  async listProfiles() {
+    // @napi-rs/keyring has no "list all entries for a service" API — OS
+    // keychains generally don't expose enumeration without extra
+    // permissions. Tracking known profile IDs is therefore NOT this
+    // class's job; see ProfileRegistry (profileRegistry.js) for how the
+    // CLI tracks "which profiles have I ever logged into" separately from
+    // the keychain itself.
+    throw new Error(
+      "KeychainCredentialStore.listProfiles is not supported directly — " +
+        "use ProfileRegistry to track known profile IDs, then look up each " +
+        "one via get()."
+    );
+  }
+}
+
+function isNotFoundError(err) {
+  const message = String(err?.message ?? "");
+  return /no such|not found|nosuchkeyring|nosuchitem/i.test(message);
+}
+
+/**
+ * RegistryBackedKeychainCredentialStore — combines KeychainCredentialStore
+ * (actual secret storage) with ProfileRegistry (non-sensitive list of known
+ * profile IDs) to satisfy the full CredentialStore interface, including
+ * listProfiles(), which the raw keychain store alone cannot support.
+ *
+ * This is the class CLI wiring should actually construct for real use —
+ * KeychainCredentialStore and ProfileRegistry are exported separately
+ * mainly so each can be tested/reasoned about independently.
+ */
+export class RegistryBackedKeychainCredentialStore extends CredentialStore {
+  /**
+   * @param {import("./ProfileRegistry.js").ProfileRegistry} profileRegistry
+   */
+  constructor(profileRegistry) {
+    super();
+    this._keychain = new KeychainCredentialStore();
+    this._registry = profileRegistry;
+  }
+
+  async get(profileId) {
+    return this._keychain.get(profileId);
+  }
+
+  async set(profileId, credentials) {
+    await this._keychain.set(profileId, credentials);
+    await this._registry.add(profileId); // registry write after secret write succeeds
+  }
+
+  async delete(profileId) {
+    await this._keychain.delete(profileId);
+    await this._registry.remove(profileId);
+  }
+
+  async listProfiles() {
+    return this._registry.list();
+  }
+}

package/src/config/ProfileRegistry.js

@@ -0,0 +1,105 @@
+/**
+ * ProfileRegistry — tracks which profile IDs the user has ever logged into,
+ * so the CLI can support `lixblogs auth status` (no profile given, meaning
+ * "show me all of them") and profile-switching commands.
+ *
+ * This deliberately stores NOTHING sensitive — just profile names/IDs, not
+ * tokens. It's fine for this to live in a plain config file on disk (not
+ * the keychain), since profile *names* aren't a secret; only the
+ * credentials tied to them are, and those live in CredentialStore.
+ *
+ * Rationale for why this exists at all: OS keychains generally don't
+ * support "list all entries for this service" without extra permissions
+ * (see KeychainCredentialStore.listProfiles, which explicitly throws and
+ * points here instead). This registry is what makes listing/switching
+ * profiles possible without asking the OS keychain to do something most
+ * platforms don't reliably support.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+function defaultRegistryPath() {
+  return path.join(os.homedir(), ".config", "lixblogs", "profiles.json");
+}
+
+export class ProfileRegistry {
+  /** @param {string} [registryPath] */
+  constructor(registryPath = defaultRegistryPath()) {
+    this._path = registryPath;
+  }
+
+  /** @returns {Promise<string[]>} */
+  async list() {
+    return (await this._read()).profiles;
+  }
+
+  async getActive() {
+    const data = await this._read();
+    return data.activeProfile && data.profiles.includes(data.activeProfile)
+      ? data.activeProfile
+      : data.profiles[0] || null;
+  }
+
+  async setActive(profileId) {
+    validateProfileId(profileId);
+    const data = await this._read();
+    if (!data.profiles.includes(profileId)) {
+      throw new Error(`Profile "${profileId}" does not exist. Log in with it first.`);
+    }
+    await this._write(data.profiles, profileId);
+  }
+
+  async _read() {
+    try {
+      const raw = await fs.readFile(this._path, "utf8");
+      const data = JSON.parse(raw);
+      const profiles = Array.isArray(data.profiles)
+        ? data.profiles.filter((profile) => typeof profile === "string")
+        : [];
+      return {
+        profiles,
+        activeProfile: typeof data.activeProfile === "string" ? data.activeProfile : null,
+      };
+    } catch (err) {
+      if (err.code === "ENOENT") return { profiles: [], activeProfile: null };
+      throw err;
+    }
+  }
+
+  /** @param {string} profileId */
+  async add(profileId) {
+    validateProfileId(profileId);
+    const data = await this._read();
+    const profiles = new Set(data.profiles);
+    profiles.add(profileId);
+    await this._write([...profiles], data.activeProfile || profileId);
+  }
+
+  /** @param {string} profileId */
+  async remove(profileId) {
+    const data = await this._read();
+    const profiles = data.profiles.filter((id) => id !== profileId);
+    const activeProfile = data.activeProfile === profileId ? profiles[0] || null : data.activeProfile;
+    await this._write(profiles, activeProfile);
+  }
+
+  async _write(profiles, activeProfile = null) {
+    await fs.mkdir(path.dirname(this._path), { recursive: true });
+    const temporaryPath = `${this._path}.${process.pid}.tmp`;
+    await fs.writeFile(
+      temporaryPath,
+      JSON.stringify({ activeProfile, profiles }, null, 2),
+      { encoding: "utf8", mode: 0o600 },
+    );
+    await fs.rename(temporaryPath, this._path);
+  }
+}
+
+export function validateProfileId(profileId) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(profileId || "")) {
+    throw new Error("Profile names must be 1-64 characters using letters, numbers, dot, dash, or underscore.");
+  }
+  return profileId;
+}

package/src/config/config.js

@@ -0,0 +1,60 @@
+/**
+ * config.js — resolves runtime config for the CLI.
+ *
+ * Per #135: "Config precedence: flags → environment → named profile →
+ * defaults." This module implements that precedence for the small set of
+ * values the auth commands need right now (environment, active profile,
+ * API base URL placeholder for later). It's deliberately minimal — full
+ * config-file/profile-file handling belongs to a later CLI-shell issue,
+ * not this one.
+ */
+
+const DEFAULTS = {
+  environment: "production",
+  profile: "default",
+  accountsBaseUrl: "https://accounts.elixpo.com",
+  apiBaseUrl: "https://blogs.elixpo.com",
+};
+
+const ENVIRONMENT_CLIENTS = {
+  development: { clientId: "lixblogs-cli-dev", audience: "localhost" },
+  staging: { clientId: "lixblogs-cli-staging", audience: "staging.blogs.elixpo.com" },
+  production: { clientId: "lixblogs-cli-prod", audience: "blogs.elixpo.com" },
+  test: { clientId: "lixblogs-cli-dev", audience: "localhost" },
+};
+
+/**
+ * @param {Object} params
+ * @param {Object} [params.flags] - parsed CLI flags, e.g. { profile, env }
+ * @param {NodeJS.ProcessEnv} [params.env] - defaults to process.env
+ * @returns {{ environment: string, profile: string, configAllowsProduction: boolean }}
+ */
+export function resolveConfig({ flags = {}, env = process.env } = {}) {
+  const environment =
+    flags.env ?? env.LIXBLOGS_ENV ?? DEFAULTS.environment;
+
+  const profile =
+    flags.profile ?? env.LIXBLOGS_PROFILE ?? DEFAULTS.profile;
+
+  const environmentClient = ENVIRONMENT_CLIENTS[environment] || ENVIRONMENT_CLIENTS.production;
+  const authProvider =
+    flags.authProvider ??
+    env.LIXBLOGS_AUTH_PROVIDER ??
+    (environment === "production" ? "elixpo" : "mock");
+  const accountsBaseUrl =
+    flags.accountsUrl ?? env.LIXBLOGS_ACCOUNTS_URL ?? DEFAULTS.accountsBaseUrl;
+  const apiBaseUrl = flags.apiUrl ?? env.LIXBLOGS_API_URL ?? DEFAULTS.apiBaseUrl;
+  const clientId = flags.clientId ?? env.LIXBLOGS_CLIENT_ID ?? environmentClient.clientId;
+  const audience = flags.audience ?? env.LIXBLOGS_AUDIENCE ?? environmentClient.audience;
+
+  return {
+    environment,
+    profile,
+    profileExplicit: flags.profile !== undefined || env.LIXBLOGS_PROFILE !== undefined,
+    authProvider,
+    accountsBaseUrl,
+    apiBaseUrl,
+    clientId,
+    audience,
+  };
+}

package/src/config/credentialStoreFactory.js

@@ -0,0 +1,63 @@
+/**
+ * credentialStoreFactory.js
+ *
+ * Real OS-keychain storage is now wired in (KeychainCredentialStore, via
+ * @napi-rs/keyring — see that file for why it was chosen over keytar).
+ *
+ * Per #135: "require an explicit opt-in fallback when unavailable." This
+ * means: if the keychain genuinely can't be used (e.g. no Secret Service
+ * running, headless environment), this factory does NOT silently fall
+ * back to something less secure. It throws CredentialStoreUnavailableError
+ * with a clear message; the CLI entry point is responsible for surfacing
+ * that to the user and requiring an explicit --allow-insecure-fallback
+ * flag (or equivalent) before constructing InMemoryCredentialStore for
+ * real use. There is currently no non-memory fallback implementation
+ * (e.g. encrypted file) — InMemoryCredentialStore does not persist between
+ * runs, so using it as a "fallback" is only acceptable for local dev/testing,
+ * not as a real opt-in fallback for end users. Building a real persistent
+ * fallback (e.g. an encrypted-file-backed store) is out of scope here and
+ * should be a follow-up if keychain unavailability turns out to be common
+ * in practice.
+ */
+
+import {
+  GatedCredentialStore,
+  InMemoryCredentialStore,
+  CredentialStoreUnavailableError,
+} from "./CredentialStore.js";
+import {
+  RegistryBackedKeychainCredentialStore,
+  probeKeychainAvailability,
+} from "./KeychainCredentialStore.js";
+import { ProfileRegistry } from "./ProfileRegistry.js";
+
+/**
+ * @param {{ allowInsecureFallback?: boolean }} [options]
+ * @returns {Promise<import("./CredentialStore.js").CredentialStore>}
+ */
+export async function createCredentialStore({ allowInsecureFallback = false, profileRegistry } = {}) {
+  // Proactively probe availability with a real write+delete round-trip
+  // rather than relying on get() to surface failures — see
+  // probeKeychainAvailability's doc comment for why get() alone is not
+  // trustworthy for this on every backend.
+  const probe = await probeKeychainAvailability();
+
+  if (!probe.available) {
+    if (!allowInsecureFallback) {
+      throw new CredentialStoreUnavailableError(
+        `OS keychain is unavailable: ${probe.error}. Re-run with an explicit ` +
+          `fallback flag if you want to opt in to a less secure storage method.`
+      );
+    }
+    process.stderr.write(
+      `warning: OS keychain unavailable (${probe.error}); using in-memory ` +
+        `fallback because --allow-insecure-fallback was passed. Credentials ` +
+        `will NOT persist between CLI runs.\n`
+    );
+    return new InMemoryCredentialStore();
+  }
+
+  const registry = profileRegistry || new ProfileRegistry();
+  const realStore = new RegistryBackedKeychainCredentialStore(registry);
+  return new GatedCredentialStore(realStore);
+}

package/src/config/providerFactory.js

@@ -0,0 +1,42 @@
+/**
+ * providerFactory.js — the single place an AuthProvider gets constructed.
+ *
+ * Every call site that needs an AuthProvider goes through here, not through
+ * `new MockAuthProvider()` directly, so the production gate (see
+ * ../auth/productionGate.js) is impossible to bypass by accident. This is
+ * intentionally a single narrow chokepoint.
+ */
+
+import { MockAuthProvider } from "../auth/MockAuthProvider.js";
+import { ElixpoAuthProvider } from "../auth/ElixpoAuthProvider.js";
+import { assertProviderAllowed } from "../auth/productionGate.js";
+
+/**
+ * @param {{ environment: string, authProvider: string, accountsBaseUrl?: string, clientId?: string, audience?: string }} config
+ * @returns {import("../auth/AuthProvider.js").AuthProvider}
+ */
+export function createAuthProvider(config) {
+  if (config.authProvider === "mock" && config.environment === "production") {
+    throw new Error("The mock auth provider cannot run in production.");
+  }
+  if (config.authProvider !== "mock" && config.authProvider !== "elixpo") {
+    throw new Error(`Unknown auth provider "${config.authProvider}".`);
+  }
+
+  const provider = config.authProvider === "mock"
+    ? new MockAuthProvider()
+    : new ElixpoAuthProvider({
+      accountsBaseUrl: config.accountsBaseUrl,
+      clientId: config.clientId,
+      audience: config.audience,
+      cliVersion: config.cliVersion || "1.1.0",
+      fetchImpl: config.fetchImpl,
+    });
+
+  assertProviderAllowed({
+    providerId: provider.providerId,
+    environment: config.environment,
+  });
+
+  return provider;
+}

package/src/config/redact.js

@@ -0,0 +1,74 @@
+/**
+ * redact.js — token redaction, used everywhere output could leak a
+ * credential: console output, --json output, thrown errors, crash reports.
+ *
+ * Per #135: "Never print tokens in logs, JSON output, telemetry, or crash
+ * reports." This is a hard requirement, tested in redact.test.mjs — not
+ * just documented.
+ */
+
+const REDACTED = "[REDACTED]";
+
+/**
+ * Recursively walks an object/array and replaces any value under a key
+ * matching a known sensitive-field name with REDACTED. Also redacts string
+ * values that look like tokens even under an unrecognized key, as a
+ * defense-in-depth measure (e.g. someone renames a field and forgets to
+ * update this list).
+ */
+const SENSITIVE_KEY_PATTERN = /token|refresh|secret|password|authorization/i;
+
+// Matches our mock token shapes (mock-access-*, mock-refresh-*) as well as
+// generic bearer-token-like strings, so redaction isn't solely dependent on
+// key names.
+const TOKEN_LIKE_VALUE_PATTERN = /^(mock-(access|refresh)-|Bearer\s+)\S+/i;
+
+export function redactValue(value) {
+  if (typeof value === "string" && TOKEN_LIKE_VALUE_PATTERN.test(value)) {
+    return REDACTED;
+  }
+  return value;
+}
+
+export function redactObject(input) {
+  if (Array.isArray(input)) {
+    return input.map((item) => redactObject(item));
+  }
+  if (input && typeof input === "object") {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+      if (SENSITIVE_KEY_PATTERN.test(key)) {
+        out[key] = REDACTED;
+      } else if (typeof value === "object" && value !== null) {
+        out[key] = redactObject(value);
+      } else {
+        out[key] = redactValue(value);
+      }
+    }
+    return out;
+  }
+  return redactValue(input);
+}
+
+/**
+ * Wraps JSON.stringify to redact sensitive fields before serialization.
+ * Use this for --json output and any log line, never JSON.stringify directly
+ * on data that might contain credentials.
+ */
+export function safeJsonStringify(input, space) {
+  return JSON.stringify(redactObject(input), null, space);
+}
+
+/**
+ * Wraps an error for safe display/logging — strips any token-like content
+ * from the error message itself, not just structured fields, since error
+ * messages are free-form strings that could accidentally interpolate a
+ * token (e.g. "failed to refresh mock-refresh-abc123").
+ */
+export function redactErrorMessage(message) {
+  if (typeof message !== "string") return message;
+  return message.replace(
+    /(mock-(access|refresh)-\S+|Bearer\s+\S+)/gi,
+    REDACTED
+  );
+}

package/src/content/markdown.js

@@ -0,0 +1,68 @@
+function text(value) {
+  return [{ type: 'text', text: value }];
+}
+
+export function markdownToBlocks(markdown) {
+  const lines = String(markdown || '').replace(/\r\n/g, '\n').split('\n');
+  const blocks = [];
+  let paragraph = [];
+  const flush = () => {
+    if (!paragraph.length) return;
+    blocks.push({ type: 'paragraph', content: text(paragraph.join(' ').trim()) });
+    paragraph = [];
+  };
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+    if (!trimmed) { flush(); continue; }
+    const fence = trimmed.match(/^```([\w+-]*)/);
+    if (fence) {
+      flush();
+      const code = [];
+      index += 1;
+      while (index < lines.length && !/^```/.test(lines[index].trim())) code.push(lines[index++]);
+      blocks.push(fence[1].toLowerCase() === 'mermaid'
+        ? { type: 'mermaidBlock', props: { diagram: code.join('\n') } }
+        : { type: 'codeBlock', props: { language: fence[1].toLowerCase() }, content: text(code.join('\n')) });
+      continue;
+    }
+    const heading = trimmed.match(/^(#{1,3})\s+(.+)/);
+    if (heading) {
+      flush();
+      blocks.push({ type: 'heading', props: { level: String(heading[1].length) }, content: text(heading[2]) });
+      continue;
+    }
+    const bullet = trimmed.match(/^[-*]\s+(.+)/);
+    if (bullet) { flush(); blocks.push({ type: 'bulletListItem', content: text(bullet[1]) }); continue; }
+    const numbered = trimmed.match(/^\d+\.\s+(.+)/);
+    if (numbered) { flush(); blocks.push({ type: 'numberedListItem', content: text(numbered[1]) }); continue; }
+    const quote = trimmed.match(/^>\s?(.*)/);
+    if (quote) { flush(); blocks.push({ type: 'quote', content: text(quote[1]) }); continue; }
+    const image = trimmed.match(/^!\[([^\]]*)\]\((https:\/\/[^)]+)\)$/);
+    if (image) { flush(); blocks.push({ type: 'image', props: { url: image[2], caption: image[1] } }); continue; }
+    if (/^([-*_])\1{2,}$/.test(trimmed)) { flush(); blocks.push({ type: 'divider' }); continue; }
+    paragraph.push(trimmed);
+  }
+  flush();
+  return blocks;
+}
+
+function blockText(block) {
+  return (block?.content || []).map((item) => typeof item === 'string' ? item : item?.text || '').join('');
+}
+
+export function blocksToMarkdown(blocks) {
+  return (blocks || []).map((block) => {
+    const value = blockText(block);
+    if (block.type === 'heading') return `${'#'.repeat(Number(block.props?.level) || 1)} ${value}`;
+    if (block.type === 'bulletListItem') return `- ${value}`;
+    if (block.type === 'numberedListItem') return `1. ${value}`;
+    if (block.type === 'quote') return `> ${value}`;
+    if (block.type === 'codeBlock') return `\`\`\`${block.props?.language || ''}\n${value}\n\`\`\``;
+    if (block.type === 'mermaidBlock') return `\`\`\`mermaid\n${block.props?.diagram || ''}\n\`\`\``;
+    if (block.type === 'image') return `![${block.props?.caption || ''}](${block.props?.url || ''})`;
+    if (block.type === 'divider') return '---';
+    return value;
+  }).join('\n\n');
+}

package/src/content/validate.js

@@ -0,0 +1,45 @@
+const MAX_CONTENT_BYTES = 1_500_000;
+
+export function countWords(blocks) {
+  const words = [];
+  const walk = (items) => {
+    for (const block of items || []) {
+      for (const item of block?.content || []) {
+        const value = typeof item === 'string' ? item : item?.text || '';
+        words.push(...value.trim().split(/\s+/).filter(Boolean));
+      }
+      if (block?.children) walk(block.children);
+    }
+  };
+  walk(blocks);
+  return words.length;
+}
+
+export function validateBlogInput(input, { publishing = false } = {}) {
+  if (input.title !== undefined && (typeof input.title !== 'string' || input.title.length > 300)) {
+    throw new Error('Title must be 300 characters or fewer.');
+  }
+  if (input.subtitle !== undefined && (typeof input.subtitle !== 'string' || input.subtitle.length > 500)) {
+    throw new Error('Subtitle must be 500 characters or fewer.');
+  }
+  if (input.tags !== undefined && (!Array.isArray(input.tags) || input.tags.length > 5)) {
+    throw new Error('Use at most five tags.');
+  }
+  if (input.coverUrl && !/^https:\/\//i.test(input.coverUrl)) {
+    throw new Error('Cover URLs must use HTTPS.');
+  }
+  if (input.publishedAs && input.publishedAs !== 'personal' && !/^org:[^:]+$/.test(input.publishedAs)) {
+    throw new Error('Publication must be personal or org:<id>.');
+  }
+  if (input.content !== undefined) {
+    if (!Array.isArray(input.content)) throw new Error('Blog content must be a block array.');
+    if (Buffer.byteLength(JSON.stringify(input.content), 'utf8') > MAX_CONTENT_BYTES) {
+      throw new Error('Blog content exceeds the 1.5 MB limit.');
+    }
+  }
+  if (publishing) {
+    if (!input.title?.trim()) throw new Error('A title is required before publishing.');
+    if (countWords(input.content) < 20) throw new Error('A post needs at least 20 words before publishing.');
+  }
+  return input;
+}