@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/public-workers/check-calendar-public-route.ts

@@ -0,0 +1,41 @@
+/** Verify that the anonymous calendar feed hostname actually reaches its public Worker. */
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTenantConfig } from '../tenants/tenant-config.js';
+
+type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+
+const MISSING_FEED = `/feed/${'A'.repeat(43)}.ics`;
+const ROBOTS = 'User-agent: *\nDisallow: /\n';
+const NOINDEX = 'noindex, nofollow, noarchive';
+
+export async function checkCalendarPublicRoute(origin: string, fetcher: Fetcher = fetch): Promise<void> {
+    const options: RequestInit = { redirect: 'manual', signal: AbortSignal.timeout(10_000) };
+    const missing = await fetcher(`${origin}${MISSING_FEED}`, options);
+    const missingBody = await missing.text();
+    if (missing.status !== 404 || missingBody !== 'Not found' || missing.headers.get('X-Robots-Tag') !== NOINDEX) {
+        const body = missingBody.includes('There is nothing here yet') ? 'Cloudflare placeholder'
+            : missingBody.includes('error code: 1042') ? 'Cloudflare error 1042'
+            : missingBody.startsWith('<!DOCTYPE html>') ? 'unexpected HTML'
+            : JSON.stringify(missingBody.slice(0, 80));
+        throw new Error(`Public calendar route did not reach the Worker at ${origin}/feed/… (HTTP ${missing.status}, ${body}). Check the Worker deployment, workers.dev route, and Access rules.`);
+    }
+    const robots = await fetcher(`${origin}/robots.txt`, options);
+    if (robots.status !== 200 || await robots.text() !== ROBOTS || robots.headers.get('X-Robots-Tag') !== NOINDEX) {
+        throw new Error(`Public calendar Worker is not serving ${origin}/robots.txt (HTTP ${robots.status}). Check the Worker deployment and route.`);
+    }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const { infrastructure } = await loadTenantConfig();
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        try {
+            await checkCalendarPublicRoute(infrastructure.calendarPublicOrigin);
+            break;
+        } catch (cause) {
+            if (attempt === 5) throw cause;
+            await new Promise((resolve) => setTimeout(resolve, 5_000));
+        }
+    }
+    console.log(`Public calendar Worker is serving anonymously at ${infrastructure.calendarPublicOrigin}`);
+}

package/src/public-workers/check-gallery-public-route.ts

@@ -0,0 +1,43 @@
+/** Verify that the anonymous Gallery hostname actually reaches its public Worker. */
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTenantConfig } from '../tenants/tenant-config.js';
+
+type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+
+const MISSING_GALLERY = '/g/00000000-0000-4000-8000-000000000000';
+const ROBOTS = 'User-agent: *\nDisallow: /\n';
+
+export async function checkGalleryPublicRoute(origin: string, fetcher: Fetcher = fetch): Promise<void> {
+    const options: RequestInit = { redirect: 'manual', signal: AbortSignal.timeout(10_000) };
+    const missing = await fetcher(`${origin}${MISSING_GALLERY}`, options);
+    const missingBody = await missing.text();
+    if (missing.status !== 404 || missingBody !== 'Not found'
+        || missing.headers.get('X-Robots-Tag') !== 'noindex, nofollow, noarchive') {
+        const body = missingBody.includes('There is nothing here yet') ? 'Cloudflare placeholder'
+            : missingBody.includes('error code: 1042') ? 'Cloudflare error 1042'
+            : missingBody.startsWith('<!DOCTYPE html>') ? 'unexpected HTML'
+            : JSON.stringify(missingBody.slice(0, 80));
+        throw new Error(`Public Gallery route did not reach the Worker at ${origin}${MISSING_GALLERY} (HTTP ${missing.status}, ${body}). Check the Worker deployment, workers.dev route, and Access rules.`);
+    }
+
+    const robots = await fetcher(`${origin}/robots.txt`, options);
+    if (robots.status !== 200 || await robots.text() !== ROBOTS
+        || robots.headers.get('X-Robots-Tag') !== 'noindex, nofollow, noarchive') {
+        throw new Error(`Public Gallery Worker is not serving ${origin}/robots.txt (HTTP ${robots.status}). Check the Worker deployment and route.`);
+    }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const { infrastructure } = await loadTenantConfig();
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        try {
+            await checkGalleryPublicRoute(infrastructure.galleryPublicOrigin);
+            break;
+        } catch (cause) {
+            if (attempt === 5) throw cause;
+            await new Promise((resolve) => setTimeout(resolve, 5_000));
+        }
+    }
+    console.log(`Public Gallery Worker is serving anonymously at ${infrastructure.galleryPublicOrigin}`);
+}

package/src/public-workers/gallery-public-config.ts

@@ -0,0 +1,22 @@
+/** The public Gallery Worker's config (generated by `host-configs.ts`). */
+import type { InfrastructureDefinition } from '../tenants/tenant-config.js';
+import { WRANGLER_BASE } from '../tenants/wrangler-base.js';
+
+/**
+ * The public Gallery Worker: the public bucket and the canonical origin. `main` is the bundle that
+ * `hearthlog gallery-public:build` writes beside the config: Svelte renders the page on the server.
+ */
+export function buildGalleryPublicConfig(infrastructure: InfrastructureDefinition) {
+    return {
+        name: infrastructure.galleryPublicWorker,
+        main: './dist/worker/index.js',
+        compatibility_date: WRANGLER_BASE.compatibility_date,
+        // Svelte's server renderer keeps per-render context in AsyncLocalStorage.
+        compatibility_flags: ['nodejs_als'],
+        workers_dev: true,
+        preview_urls: false,
+        observability: { enabled: true },
+        vars: { PUBLIC_ORIGIN: infrastructure.galleryPublicOrigin },
+        r2_buckets: [{ binding: 'GALLERY_PUBLIC', bucket_name: infrastructure.galleryPublicBucket }],
+    };
+}

package/src/receipt.ts

@@ -0,0 +1,74 @@
+/**
+ * A deployment receipt: which steps of `hearthlog apply` finished and which
+ * resources they concern. It lives in the operator's protected state and
+ * holds no secret, so it can be read, copied, and attached to a support
+ * request. A resumed apply trusts it to skip finished steps, which is how it
+ * avoids minting a second set of credentials.
+ */
+
+import type { DeploymentPlan, StepId } from './plan.js';
+
+export interface Receipt {
+    schemaVersion: 1;
+    siteId: string;
+    origin: string;
+    /** `kind:name` of every planned resource; a changed plan is not this receipt's deployment. */
+    resources: string[];
+    modules: Array<{ id: string; version: string }>;
+    steps: Partial<Record<StepId, { completedAt: string }>>;
+}
+
+const SECRET_KEY = /token|secret|password|credential|private|signing/i;
+
+export function newReceipt(plan: DeploymentPlan): Receipt {
+    return {
+        schemaVersion: 1,
+        siteId: plan.siteId,
+        origin: plan.origin,
+        resources: plan.resources.map((resource) => `${resource.kind}:${resource.name}`).sort(),
+        modules: plan.modules.map(({ id, version }) => ({ id, version })),
+        steps: {},
+    };
+}
+
+export function stepDone(receipt: Receipt, step: StepId): boolean {
+    return receipt.steps[step] !== undefined;
+}
+
+export function recordStep(receipt: Receipt, step: StepId, at: Date): Receipt {
+    return { ...receipt, steps: { ...receipt.steps, [step]: { completedAt: at.toISOString() } } };
+}
+
+/** Why a saved receipt cannot be resumed against this plan; empty when it can. */
+export function receiptProblems(receipt: Receipt, plan: DeploymentPlan): string[] {
+    const problems: string[] = [];
+    if (receipt.schemaVersion !== 1) problems.push(`the receipt has schema version ${String(receipt.schemaVersion)}, not 1`);
+    if (receipt.siteId !== plan.siteId) problems.push(`the receipt is for site "${receipt.siteId}", not "${plan.siteId}"`);
+    const current = newReceipt(plan);
+    if (receipt.origin !== current.origin) problems.push(`the receipt is for ${receipt.origin}, the plan for ${current.origin}`);
+    if (JSON.stringify(receipt.resources) !== JSON.stringify(current.resources)) {
+        problems.push('the planned resources differ from those the receipt recorded; remove the receipt only if you mean to start over');
+    }
+    return problems;
+}
+
+/** Serializes a receipt, refusing anything shaped like a secret. */
+export function serializeReceipt(receipt: Receipt): string {
+    const walk = (value: unknown, path: string): void => {
+        if (value === null || typeof value !== 'object') return;
+        for (const [key, inner] of Object.entries(value)) {
+            if (SECRET_KEY.test(key)) throw new Error(`A receipt must hold no secrets (found "${path}${key}")`);
+            walk(inner, `${path}${key}.`);
+        }
+    };
+    walk(receipt, '');
+    return `${JSON.stringify(receipt, null, 2)}\n`;
+}
+
+export function parseReceipt(text: string): Receipt {
+    const value = JSON.parse(text) as Receipt;
+    if (value === null || typeof value !== 'object' || value.schemaVersion !== 1 || typeof value.siteId !== 'string') {
+        throw new Error('Not a deployment receipt');
+    }
+    return value;
+}

package/src/root.ts

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * The repository a command works on: the nearest directory, from the working directory upward, that
+ * holds `tenants.json`. Commands act on the host they are run in, not on where this package is installed.
+ */
+export function hostRoot(start: string = process.cwd()): string {
+    let directory = resolve(start);
+    for (;;) {
+        if (existsSync(join(directory, "tenants.json")) || existsSync(join(directory, "tenants"))) return directory;
+        const parent = dirname(directory);
+        if (parent === directory) return resolve(start);
+        directory = parent;
+    }
+}

package/src/security/audit-push.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env npx tsx
+/**
+ * The gate before anything is pushed to a public repository (plan, section 4, rule 7).
+ *
+ * Run it on the exact directory you are about to push: a snapshot with its first commit made, or
+ * a module or platform clone. It reads the forbidden-identities file
+ * (`packages/tooling/src/security/forbidden-identities.ts`) and fails when
+ *
+ *   - any file name, file content, or binary file contains a forbidden value;
+ *   - the directory has git history and any commit's author or committer is not one of the
+ *     allowed author addresses (GitHub's own `noreply` addresses are accepted);
+ *   - any commit message, tag, or branch name contains a forbidden value, or any commit's diff does;
+ *   - the repository's own git identity (`user.email`) is not an allowed address.
+ *
+ * Nothing it prints is a value from the list: findings name an entry by number.
+ *
+ * Usage: pnpm audit:push -- <directory> [--json]   (exit 1 unless the directory is clean)
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { forbiddenIn, forbiddenInBytes, forbiddenLabel, loadForbiddenList, maskForbidden, type ForbiddenList } from "./forbidden-identities.js";
+
+export interface PushFinding {
+    where: string;
+    kind: string;
+    detail: string;
+}
+
+const SAFE_NOREPLY = /^(?:noreply@github\.com|[0-9]*\+?[a-z0-9-]+@users\.noreply\.github\.com)$/i;
+
+/** Every file under the directory except `.git`, as relative paths. */
+export function listFiles(directory: string): string[] {
+    // In a repository, what could be pushed is what git tracks or would add: an ignored `node_modules` is not part of it.
+    if (existsSync(join(directory, ".git"))) {
+        const listed = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd: directory, maxBuffer: 256 * 1024 * 1024 });
+        return [...new Set(listed.toString("utf8").split("\0").filter(Boolean))].filter((file) => existsSync(join(directory, file)));
+    }
+    const files: string[] = [];
+    const walk = (current: string) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (entry.name === ".git") continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory()) walk(path);
+            else if (entry.isFile()) files.push(relative(directory, path));
+        }
+    };
+    walk(directory);
+    return files;
+}
+
+export function auditFiles(directory: string, list: ForbiddenList): PushFinding[] {
+    const findings: PushFinding[] = [];
+    for (const file of listFiles(directory)) {
+        const shown = maskForbidden(file, list.forbidden);
+        for (const entry of forbiddenIn(file, list.forbidden)) findings.push({ where: shown, kind: "file-name", detail: forbiddenLabel(entry) });
+        const path = join(directory, file);
+        if (lstatSync(path).size > 64 * 1024 * 1024) {
+            findings.push({ where: shown, kind: "too-large-to-scan", detail: "larger than 64 MiB" });
+            continue;
+        }
+        for (const entry of forbiddenInBytes(readFileSync(path), list.forbidden)) findings.push({ where: shown, kind: "content", detail: forbiddenLabel(entry) });
+    }
+    return findings;
+}
+
+function git(directory: string, args: string[]): string {
+    return execFileSync("git", ["-C", directory, ...args], { encoding: "utf8", maxBuffer: 1024 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+/** Authors, committers, messages, refs, diffs, and the repository's own identity. */
+export function auditHistory(directory: string, list: ForbiddenList): PushFinding[] {
+    const findings: PushFinding[] = [];
+    if (!existsSync(join(directory, ".git"))) return findings;
+    const allowed = new Set(list.allowedAuthorEmails);
+    const isAllowed = (email: string) => allowed.has(email.toLowerCase()) || SAFE_NOREPLY.test(email);
+
+    let log = "";
+    try {
+        log = git(directory, ["log", "--all", "--format=%H%x1f%an%x1f%ae%x1f%cn%x1f%ce%x1f%B%x1e"]);
+    } catch {
+        // A repository without commits has nothing to check yet.
+    }
+    for (const record of log.split("\x1e").map((entry) => entry.trim()).filter(Boolean)) {
+        const [commit = "", authorName = "", authorEmail = "", committerName = "", committerEmail = "", message = ""] = record.split("\x1f");
+        const where = `commit ${commit.slice(0, 10)}`;
+        if (!isAllowed(authorEmail)) findings.push({ where, kind: "author-not-allowed", detail: "author address is not in allowedAuthorEmails" });
+        if (!isAllowed(committerEmail)) findings.push({ where, kind: "committer-not-allowed", detail: "committer address is not in allowedAuthorEmails" });
+        for (const entry of forbiddenIn([authorName, authorEmail, committerName, committerEmail, message].join("\n"), list.forbidden)) {
+            findings.push({ where, kind: "commit-metadata", detail: forbiddenLabel(entry) });
+        }
+    }
+    const refs = git(directory, ["for-each-ref", "--format=%(refname)%09%(taggername)%09%(taggeremail)%09%(contents)"]);
+    for (const entry of forbiddenIn(refs, list.forbidden)) findings.push({ where: "refs and tags", kind: "ref-metadata", detail: forbiddenLabel(entry) });
+    let patches = "";
+    try {
+        patches = git(directory, ["log", "--all", "-p", "--format=", "--no-color"]);
+    } catch {
+        // No commits.
+    }
+    for (const entry of forbiddenIn(patches, list.forbidden)) findings.push({ where: "history diffs", kind: "history-content", detail: forbiddenLabel(entry) });
+
+    let identity = "";
+    try {
+        identity = git(directory, ["config", "user.email"]).trim();
+    } catch {
+        // None configured: the commit would fail, which is the safe outcome.
+    }
+    if (identity && !isAllowed(identity)) findings.push({ where: "git config", kind: "identity-not-allowed", detail: "user.email in this repository is not in allowedAuthorEmails" });
+    return findings;
+}
+
+export function auditPush(directory: string, list: ForbiddenList = loadForbiddenList()): PushFinding[] {
+    if (list.allowedAuthorEmails.length === 0) {
+        return [{ where: list.path, kind: "no-allowed-authors", detail: '"allowedAuthorEmails" must list the address commits may carry' }];
+    }
+    return [...auditFiles(directory, list), ...auditHistory(directory, list)];
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const args = process.argv.slice(2).filter((argument) => argument !== "--");
+    const directory = args.find((argument) => !argument.startsWith("--"));
+    if (!directory || !existsSync(directory)) {
+        console.error("Usage: pnpm audit:push -- <directory> [--json]");
+        process.exit(1);
+    }
+    const root = resolve(directory);
+    const findings = auditPush(root);
+    const history = existsSync(join(root, ".git")) ? "with git history" : "no git history yet (make the first commit under the personal identity, then run this again)";
+    if (args.includes("--json")) {
+        process.stdout.write(`${JSON.stringify({ directory: root, findings }, null, 2)}\n`);
+    } else {
+        for (const finding of findings.slice(0, 40)) console.log(`${finding.where}: ${finding.kind}: ${finding.detail}`);
+        if (findings.length > 40) console.log(`… ${findings.length - 40} more`);
+        console.log(`\n${findings.length} finding(s) in ${root}, ${history}.`);
+    }
+    process.exit(findings.length ? 1 : 0);
+}

package/src/security/forbidden-identities.ts

@@ -0,0 +1,107 @@
+/**
+ * The identities that must never reach a public repository (plan, section 4).
+ *
+ * They live in a file in the operator's home directory, never in the repository: a committed
+ * list of forbidden values would itself leak them. The audit and the snapshot refuse to run
+ * without it, and nothing here, in an error, or in a report prints a value from it; findings name
+ * the entry by number.
+ *
+ *   {
+ *     "forbidden": ["strings, matched case-insensitively anywhere: addresses, domains, company names"],
+ *     "allowedAuthorEmails": ["the only address commits may carry"]
+ *   }
+ *
+ * The location is `$HEARTHLOG_FORBIDDEN_FILE`, else `$XDG_CONFIG_HOME/hearthlog/forbidden.json`,
+ * else `~/.config/hearthlog/forbidden.json`.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ForbiddenList {
+    path: string;
+    /** Lower-cased, distinct, each at least `MIN_LENGTH` characters. */
+    forbidden: string[];
+    /** Commit authors and committers the push gate accepts. */
+    allowedAuthorEmails: string[];
+}
+
+export class ForbiddenListError extends Error {}
+
+const MIN_LENGTH = 4;
+const MAX_LENGTH = 200;
+
+export function forbiddenListPath(env: NodeJS.ProcessEnv = process.env): string {
+    if (env.HEARTHLOG_FORBIDDEN_FILE) return env.HEARTHLOG_FORBIDDEN_FILE;
+    return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "hearthlog", "forbidden.json");
+}
+
+/** Validates the file's content. Errors say what is wrong, never what the values are. */
+export function parseForbiddenList(text: string, path: string): ForbiddenList {
+    let value: unknown;
+    try {
+        value = JSON.parse(text);
+    } catch {
+        throw new ForbiddenListError(`${path} is not valid JSON.`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ForbiddenListError(`${path} must be a JSON object.`);
+    const record = value as Record<string, unknown>;
+    const strings = (key: string, minimum: number): string[] => {
+        const entries = record[key];
+        if (entries === undefined) return [];
+        if (!Array.isArray(entries) || entries.some((entry) => typeof entry !== "string")) throw new ForbiddenListError(`"${key}" in ${path} must be a list of strings.`);
+        const trimmed = (entries as string[]).map((entry) => entry.trim());
+        const index = trimmed.findIndex((entry) => entry.length < minimum || entry.length > MAX_LENGTH);
+        if (index !== -1) throw new ForbiddenListError(`"${key}" entry #${index + 1} in ${path} must be ${minimum} to ${MAX_LENGTH} characters.`);
+        return [...new Set(trimmed.map((entry) => entry.toLowerCase()))];
+    };
+    const forbidden = strings("forbidden", MIN_LENGTH);
+    if (forbidden.length === 0) throw new ForbiddenListError(`"forbidden" in ${path} must list at least one string.`);
+    const allowedAuthorEmails = strings("allowedAuthorEmails", 3);
+    const bad = allowedAuthorEmails.findIndex((email) => !email.includes("@"));
+    if (bad !== -1) throw new ForbiddenListError(`"allowedAuthorEmails" entry #${bad + 1} in ${path} is not an email address.`);
+    return { path, forbidden, allowedAuthorEmails };
+}
+
+export function loadForbiddenList(env: NodeJS.ProcessEnv = process.env): ForbiddenList {
+    const path = forbiddenListPath(env);
+    let text: string;
+    try {
+        text = readFileSync(path, "utf8");
+    } catch {
+        throw new ForbiddenListError(
+            `The forbidden-identities file ${path} does not exist. It lists what must never be published (work addresses, employer and company names). ` +
+                "Create it with `pnpm audit:forbidden:init`, review it, and run this again.",
+        );
+    }
+    return parseForbiddenList(text, path);
+}
+
+/** Entry numbers (1-based) of the forbidden strings that occur in the text. */
+export function forbiddenIn(text: string, forbidden: readonly string[]): number[] {
+    const lower = text.toLowerCase();
+    const found: number[] = [];
+    forbidden.forEach((entry, index) => {
+        if (lower.includes(entry)) found.push(index + 1);
+    });
+    return found;
+}
+
+/** The same search over bytes, so an image's metadata or a binary file cannot hide a value. */
+export function forbiddenInBytes(buffer: Buffer, forbidden: readonly string[]): number[] {
+    return forbiddenIn(buffer.toString("latin1"), forbidden.map((entry) => Buffer.from(entry, "utf8").toString("latin1")));
+}
+
+/** The text with every forbidden value replaced by its entry number, for paths a report must show. */
+export function maskForbidden(text: string, forbidden: readonly string[]): string {
+    let masked = text;
+    [...forbidden.entries()]
+        .sort((a, b) => b[1].length - a[1].length)
+        .forEach(([index, entry]) => {
+            masked = masked.replace(new RegExp(entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi"), `<forbidden #${index + 1}>`);
+        });
+    return masked;
+}
+
+export const forbiddenLabel = (entry: number): string => `forbidden entry #${entry}`;

package/src/security/forbidden-init.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env npx tsx
+/**
+ * Writes a first forbidden-identities file from the identities already in this repository's git
+ * history (`packages/tooling/src/security/forbidden-identities.ts` describes the file).
+ *
+ * Every author and committer address except your personal one, GitHub and tool `noreply`
+ * addresses, and bots becomes an entry, together with the domain's name when it is not a free
+ * mail provider (so a company name in a file is caught as well as its addresses). Nothing is
+ * printed except counts and the path: open the file to review it, and add what history cannot
+ * know (company names, tax numbers) with `--add`.
+ *
+ * Usage: pnpm audit:forbidden:init [--personal <email>] [--add <string>]... [--force]
+ *
+ * The personal address defaults to the global `git config user.email`. The file is written with
+ * mode 0600 and is never overwritten without `--force`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { forbiddenListPath, parseForbiddenList } from "./forbidden-identities.js";
+
+const FREE_MAIL = new Set(["gmail.com", "googlemail.com", "gmx.com", "gmx.net", "gmx.de", "outlook.com", "hotmail.com", "live.com", "icloud.com", "me.com", "yahoo.com", "proton.me", "protonmail.com", "seznam.cz", "email.cz", "centrum.cz", "post.cz"]);
+const NOT_A_PERSON = /(?:noreply|no-reply|\[bot\]|users\.noreply\.github\.com|^bot@)/i;
+
+export interface Identity {
+    name: string;
+    email: string;
+}
+
+/** Candidate entries from history identities: addresses plus the name of a non-free-mail domain. */
+export function candidateEntries(identities: readonly Identity[], personal: string): { entries: string[]; addresses: number; names: number } {
+    const entries = new Set<string>();
+    let addresses = 0;
+    let names = 0;
+    for (const { name, email } of identities) {
+        const address = email.trim().toLowerCase();
+        if (!address.includes("@") || address === personal.toLowerCase() || NOT_A_PERSON.test(address) || NOT_A_PERSON.test(name)) continue;
+        if (!entries.has(address)) addresses += 1;
+        entries.add(address);
+        const domain = address.split("@")[1]!;
+        if (FREE_MAIL.has(domain)) continue;
+        const label = domain.split(".").slice(0, -1).pop() ?? "";
+        if (label.length >= 4 && !entries.has(label)) {
+            entries.add(label);
+            names += 1;
+        }
+    }
+    return { entries: [...entries], addresses, names };
+}
+
+function git(args: string[], cwd?: string): string {
+    return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const args = process.argv.slice(2).filter((argument) => argument !== "--");
+    const value = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] : undefined);
+    const personal = value("--personal") ?? git(["config", "--global", "user.email"]).trim();
+    if (!personal.includes("@")) {
+        console.error("Pass your personal address with --personal <email>, or set the global git user.email to it.");
+        process.exit(1);
+    }
+    const path = forbiddenListPath();
+    if (existsSync(path) && !args.includes("--force")) {
+        console.error(`${path} exists. Edit it, or pass --force to replace it.`);
+        process.exit(1);
+    }
+    const log = git(["log", "--all", "--format=%an%x1f%ae%x1e%cn%x1f%ce%x1e"]);
+    const identities = log
+        .split("\x1e")
+        .map((record) => record.trim())
+        .filter(Boolean)
+        .map((record) => {
+            const [name = "", email = ""] = record.split("\x1f");
+            return { name, email };
+        });
+    const { entries, addresses, names } = candidateEntries(identities, personal);
+    const added = args.flatMap((argument, index) => (argument === "--add" && args[index + 1] ? [args[index + 1]!] : []));
+    const file = { forbidden: [...new Set([...entries, ...added])], allowedAuthorEmails: [personal.toLowerCase()] };
+    parseForbiddenList(JSON.stringify(file), path); // refuse to write what the loader would reject
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    console.log(`Wrote ${path}: ${addresses} address(es) and ${names} domain name(s) from history, ${added.length} added by hand.`);
+    console.log("Open the file to review it. Nothing was printed from it.");
+}

package/src/tenants/host-configs.ts

@@ -0,0 +1,96 @@
+/**
+ * The Worker configs of a stack's backend: its Ledger, its public calendar feed Worker, and its public Gallery Worker.
+ *
+ * A stack is the shared one (every site without `tenants/<id>/deployment.json`) or a site's own. Each Worker gets a
+ * folder in `.generated/`: `shared/<worker>/` or `sites/<id>/<worker>/`, holding `wrangler.jsonc` (paths relative to
+ * the folder, as wrangler resolves them) and, for the two that have one, the entry file that re-exports the
+ * platform package. The files are gitignored and deterministic, regenerated by `hearthlog build` and the deploy tools.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+import { GENERATED_DIRECTORY } from "../compose/compose-modules.js";
+import { packageDirectory } from "../host/write-host.js";
+import { buildCalendarPublicConfig } from "../public-workers/calendar-public-config.js";
+import { buildGalleryPublicConfig } from "../public-workers/gallery-public-config.js";
+import { buildLedgerConfig } from "./ledger-config.js";
+import { infrastructureFor, loadTenantConfig, type InfrastructureDefinition } from "./tenant-config.js";
+
+export type HostWorker = "ledger" | "calendar-public" | "gallery-public";
+/** "shared" or a site id. */
+export type Stack = string;
+
+export function hostWorkerDirectory(stack: Stack, worker: HostWorker): string {
+    return stack === "shared"
+        ? join(GENERATED_DIRECTORY, "shared", worker)
+        : join(GENERATED_DIRECTORY, "sites", stack, worker);
+}
+
+export function hostWorkerConfigPath(stack: Stack, worker: HostWorker): string {
+    return join(hostWorkerDirectory(stack, worker), "wrangler.jsonc");
+}
+
+const LEDGER_ENTRY = `// The Ledger Worker's entry. The code is \`@hearthlog/ledger\`; the Durable Object classes keep these
+// exact names because deployed data is tied to them.
+export { AppRegistry, LedgerApp, default } from "@hearthlog/ledger/index.js";
+`;
+
+const CALENDAR_ENTRY = `// The public calendar feed Worker's entry; the code is \`@hearthlog/cloudflare\`.
+export { default, handleCalendarPublicRequest, type CalendarPublicEnv } from "@hearthlog/cloudflare/calendar-public.js";
+`;
+
+function calendarTsconfig(directory: string): string {
+    const types = join(packageDirectory("@hearthlog/cloudflare"), "types", "worker-configuration.d.ts");
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: "ES2022", module: "ESNext", moduleResolution: "Bundler", lib: ["ES2022", "DOM"],
+            strict: true, noEmit: true, skipLibCheck: true, types: [],
+        },
+        include: ["index.ts", relative(directory, types)],
+    }, null, 2)}\n`;
+}
+
+async function write(path: string, content: string): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+}
+
+const json = (value: unknown) => `${JSON.stringify(value, null, 2)}\n`;
+
+/**
+ * Write the configs of one stack. A build passes its own site's stack ("shared" for a site on the shared stack),
+ * because its catalog holds only its own modules; `check:tenants` passes each stack in turn.
+ */
+export async function generateHostConfigs(stack: Stack): Promise<string[]> {
+    const { infrastructure: shared, sites, stacks } = await loadTenantConfig(undefined, { only: stack === "shared" ? "" : stack });
+    const written: string[] = [];
+    const emit = async (worker: HostWorker, config: unknown, files: Record<string, string> = {}) => {
+        const directory = hostWorkerDirectory(stack, worker);
+        await write(join(directory, "wrangler.jsonc"), json(config));
+        written.push(join(directory, "wrangler.jsonc"));
+        for (const [name, content] of Object.entries(files)) await write(join(directory, name), content);
+    };
+    let infrastructure: InfrastructureDefinition = shared;
+    let ledgerAccount: string | undefined;
+    let calendarSites = stacks.filter((entry) => entry.shared).map((entry) => entry.id);
+    let gallery = true;
+    if (stack !== "shared") {
+        const site = sites.find((candidate) => candidate.id === stack);
+        if (!site?.deployment) throw new Error(`Site "${stack}" has no tenants/${stack}/deployment.json, so it has no stack of its own`);
+        infrastructure = infrastructureFor(site, shared);
+        ledgerAccount = site.deployment.accountId;
+        calendarSites = [site.id];
+        gallery = site.features.includes("gallery");
+    } else if (calendarSites.length === 0) {
+        return written;
+    }
+    await emit("ledger", buildLedgerConfig(infrastructure, ledgerAccount), { "index.ts": LEDGER_ENTRY });
+    const calendarDirectory = hostWorkerDirectory(stack, "calendar-public");
+    await emit("calendar-public", buildCalendarPublicConfig(infrastructure, calendarSites), {
+        "index.ts": CALENDAR_ENTRY,
+        "tsconfig.json": calendarTsconfig(calendarDirectory),
+    });
+    if (gallery) await emit("gallery-public", buildGalleryPublicConfig(infrastructure));
+    return written;
+}