@atelic-action/ui 0.15.0 → 0.16.0

package/src/scripts/build-gate-payload.mjs

@@ -0,0 +1,175 @@
+/**
+ * Seals a document into the payload the `Gate` component reads.
+ *
+ * One content key encrypts the document once (AES-GCM). That key is then
+ * wrapped once per reader, under a key derived from that reader's own email
+ * address with PBKDF2. So every reader opens the same document with the one
+ * thing they always know, and the emitted payload carries no plaintext: not
+ * the document, and not even a hash the reader list could be checked
+ * against. Nor a reader's address: it is the secret their key derives from,
+ * so listing it beside their wrapped key would hand the document to anyone
+ * who reads the page's script. Payloads sealed before 2026-10-08 did list
+ * it; the gate now tells HubSpot who opened the document from the address
+ * the reader typed. The secret is still never anything beyond that address,
+ * which is the gate's deliberate, documented security tier. See GATE.md.
+ *
+ * Node's webcrypto is the same algorithm surface the browser exposes, so the
+ * two sides are byte compatible by construction rather than by agreement.
+ * The parameters below are the contract; changing one here without changing
+ * the matching constant in `Gate` (@atelic-action/ui/artifact) makes every
+ * existing payload unopenable.
+ *
+ * CLI (bin/atelic-seal-document.mjs runs this file's `main` under Node):
+ *   atelic-seal-document <config.json> [out.json]
+ *   bun run seal <config.json> [out.json]   (the form a site offers)
+ *
+ * Config shape (paths resolve relative to the config file):
+ *   { "content": "./proposal.html",
+ *     "people": [{ "id": "kyle", "email": "kyle@example.com" }] }
+ */
+import { webcrypto } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+
+/** PBKDF2 work factor. Mirrored by Gate; changing it breaks old payloads. */
+export const PBKDF2_ITERATIONS = 200000;
+export const PBKDF2_HASH = "SHA-256";
+/** Byte lengths: content key, GCM nonce, per person PBKDF2 salt. */
+export const KEY_BYTES = 32;
+export const IV_BYTES = 12;
+export const SALT_BYTES = 16;
+
+const encoder = new TextEncoder();
+
+/**
+ * The one normalization both sides share: an email is its letters and
+ * digits, uppercased. So "Dana@Example.com", "dana@example.com" and a stray
+ * space are all the same key, and a reader typing their own address cannot
+ * miss by punctuation or case. Mirrored in Gate; the two implementations
+ * must agree exactly.
+ */
+export function normalizeEmail(email) {
+	return String(email ?? "")
+		.toUpperCase()
+		.replace(/[^A-Z0-9]/g, "");
+}
+
+function toBase64(bytes) {
+	return Buffer.from(bytes).toString("base64");
+}
+
+function randomBytes(length) {
+	return webcrypto.getRandomValues(new Uint8Array(length));
+}
+
+/** Derive one reader's wrapping key from their email and their own salt. */
+async function deriveKey(email, salt) {
+	const material = await webcrypto.subtle.importKey(
+		"raw",
+		encoder.encode(normalizeEmail(email)),
+		"PBKDF2",
+		false,
+		["deriveKey"],
+	);
+	return webcrypto.subtle.deriveKey(
+		{ name: "PBKDF2", salt, iterations: PBKDF2_ITERATIONS, hash: PBKDF2_HASH },
+		material,
+		{ name: "AES-GCM", length: 256 },
+		false,
+		["encrypt", "decrypt"],
+	);
+}
+
+/**
+ * Encrypt `contentHtml` once and wrap the content key for each person.
+ * `people` is [{ id, email }]; the email is the reader's secret and their
+ * identity, so both survive into the payload alongside the wrap.
+ */
+export async function sealDocument(contentHtml, people) {
+	if (typeof contentHtml !== "string" || contentHtml.length === 0) {
+		throw new Error("contentHtml is empty; nothing to seal");
+	}
+	if (!Array.isArray(people) || people.length === 0) {
+		throw new Error("no people; a payload nobody can open is not worth building");
+	}
+
+	const contentKeyBytes = randomBytes(KEY_BYTES);
+	const contentKey = await webcrypto.subtle.importKey(
+		"raw",
+		contentKeyBytes,
+		{ name: "AES-GCM" },
+		false,
+		["encrypt"],
+	);
+	const civ = randomBytes(IV_BYTES);
+	const ct = new Uint8Array(
+		await webcrypto.subtle.encrypt(
+			{ name: "AES-GCM", iv: civ },
+			contentKey,
+			encoder.encode(contentHtml),
+		),
+	);
+
+	const seen = new Set();
+	const sealed = [];
+	for (const person of people) {
+		const id = person?.id;
+		if (!id) throw new Error("every person needs an id");
+		if (seen.has(id)) throw new Error(`duplicate person id: ${id}`);
+		seen.add(id);
+		if (!person.email || !normalizeEmail(person.email)) {
+			throw new Error(`person ${id} has no email (or none that survives normalization)`);
+		}
+
+		const salt = randomBytes(SALT_BYTES);
+		const iv = randomBytes(IV_BYTES);
+		const key = await deriveKey(person.email, salt);
+		const wrapped = new Uint8Array(
+			await webcrypto.subtle.encrypt({ name: "AES-GCM", iv }, key, contentKeyBytes),
+		);
+		// The id a config gives a reader is often their first name, which
+		// beside the site's domain all but spells the address that is their
+		// key. So the payload carries a plain ordinal, and the config's id
+		// stays in the config, where it names a reader in an error message.
+		sealed.push({
+			id: `r${sealed.length + 1}`,
+			salt: toBase64(salt),
+			iv: toBase64(iv),
+			wrapped: toBase64(wrapped),
+		});
+	}
+
+	return { civ: toBase64(civ), ct: toBase64(ct), people: sealed };
+}
+
+/**
+ * The command: `args` is the command line after the command's own name.
+ * Both paths resolve against the working directory.
+ */
+export async function main(args = argv.slice(2)) {
+	const [configPath, outPath] = args;
+	if (!configPath) {
+		stderr.write("usage: atelic-seal-document <config.json> [out.json]\n");
+		exit(1);
+	}
+
+	const configFile = resolve(configPath);
+	const config = JSON.parse(readFileSync(configFile, "utf8"));
+	if (!config.content) throw new Error(`${configPath} has no "content" path`);
+
+	const contentHtml = readFileSync(resolve(dirname(configFile), config.content), "utf8");
+	const payload = await sealDocument(contentHtml, config.people);
+
+	const out = resolve(outPath ?? "gate-payload.json");
+	writeFileSync(out, `${JSON.stringify(payload, null, "\t")}\n`);
+	stdout.write(`[gate] ${out} (${payload.people.length} readers)\n`);
+}
+
+/** Runs `main` and turns a failure into the one line the command prints. */
+export function cli(args = argv.slice(2)) {
+	return main(args).catch((error) => {
+		stderr.write(`[gate] ${error.message}\n`);
+		exit(1);
+	});
+}

package/src/scripts/check-access.ts

@@ -0,0 +1,93 @@
+/**
+ * The build guard for a private artifact, and the first step of `bun run
+ * build`. The practice's FOOTPRINT.md, Privacy: anything that carries a
+ * private signal is never hosted publicly, and a private artifact deploys
+ * only to a host with the wall armed. So when site.config.ts says
+ * `access: "private"` and the build is running on Vercel, the three
+ * variables that arm the wall must be set on the project, or the build
+ * fails before anything ships. A local build of a private artifact passes
+ * with a warning, because the wall only ever runs on the host.
+ *
+ * Usage: atelic-check-access   (run by `bun run build`, from the site's root)
+ * Exits 1 when a private artifact would deploy without its wall.
+ */
+import { loadSite } from "./site-config";
+
+/** What arms the wall (ACCESS-GATE.md, Turn It On). */
+export const WALL_VARIABLES = ["GATE_SESSION_SECRET", "GATE_ALLOWLIST", "RESEND_API_KEY"] as const;
+
+export interface AccessDecision {
+	verdict: "pass" | "warn" | "fail";
+	message: string;
+}
+
+function list(names: readonly string[]): string {
+	if (names.length === 1) return names[0];
+	return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+/**
+ * The decision, kept pure so it can be tested without a build: the
+ * artifact's `access` line and the environment the build runs in.
+ * `VERCEL` is set by Vercel on every build, and nowhere else.
+ */
+export function decideAccess(
+	access: unknown,
+	env: Record<string, string | undefined>,
+): AccessDecision {
+	if (access === "public") {
+		return {
+			verdict: "pass",
+			message: "[access] public: built from public signals, no wall needed.",
+		};
+	}
+	if (access !== "private") {
+		return {
+			verdict: "fail",
+			message:
+				'[access] src/site.config.ts has no access line. Set access to "public" (built only from public signals) or "private" (anything from the owner\'s own consoles), per the practice\'s FOOTPRINT.md, Privacy.',
+		};
+	}
+	const missing = WALL_VARIABLES.filter((name) => !env[name]?.trim());
+	if (!env.VERCEL) {
+		const owed = missing.length
+			? ` Before it deploys, set ${list(missing)} on its Vercel project, or the build there fails.`
+			: "";
+		return {
+			verdict: "warn",
+			message: `[access] private, built locally: the wall only runs on the host, so this build is not a deploy.${owed}`,
+		};
+	}
+	if (missing.length === 0) {
+		return {
+			verdict: "pass",
+			message: "[access] private, and the wall's variables are set on this project.",
+		};
+	}
+	return {
+		verdict: "fail",
+		message: `[access] This artifact is private (src/site.config.ts, access: "private"), and the wall is not armed on this Vercel project. Set ${list(missing)} in the project's Settings, Environment Variables, for this environment, then redeploy. ACCESS-GATE.md says what each one holds. Nothing private deploys without the wall.`,
+	};
+}
+
+/**
+ * The command: reads the config of the site in `cwd` and decides. The
+ * config is found from the working directory, since this file no longer
+ * lives in the site.
+ */
+export async function main(cwd: string = process.cwd()): Promise<void> {
+	let access: unknown;
+	try {
+		access = (await loadSite(cwd)).access;
+	} catch (error) {
+		console.error(`[access] ${(error as Error).message}`);
+		process.exit(1);
+	}
+	const decision = decideAccess(access, process.env);
+	if (decision.verdict === "fail") {
+		console.error(decision.message);
+		process.exit(1);
+	}
+	if (decision.verdict === "warn") console.warn(decision.message);
+	else console.log(decision.message);
+}

package/src/scripts/check-links.ts

@@ -0,0 +1,104 @@
+/**
+ * External link checker: scans every prerendered page in dist/client for
+ * outbound hrefs and media sources, then verifies each URL responds.
+ * Internal link integrity is already enforced at build time by the
+ * prerender crawler; this covers the links that rot silently — booking
+ * portals, map embeds, hosted images, font stylesheets.
+ *
+ * Usage: atelic-check-links, or `bun run check:links` in a site (requires a
+ * completed `bun build`, and runs from the site's root)
+ * Exits 1 if any external link is dead.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = "dist/client";
+const ATTR_URL = /(?:href|src)="(https?:\/\/[^"]+)"/g;
+// Hosts that reject bots or are placeholders; skip rather than false-alarm.
+// Substack 403s datacenter IPs (GitHub runners) regardless of user agent.
+const SKIP_HOSTS = new Set(["example.com", "schema.org", "www.schema.org", "substack.com"]);
+const SKIP_SUFFIXES = [".example.com", ".substack.com"];
+
+function htmlFiles(dir: string): string[] {
+	return readdirSync(dir).flatMap((name) => {
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) return htmlFiles(path);
+		return name.endsWith(".html") ? [path] : [];
+	});
+}
+
+function canonicalHost(html: string): string | null {
+	const match = html.match(/rel="canonical" href="(https?:\/\/[^"]+)"/);
+	return match ? new URL(match[1]).hostname : null;
+}
+
+function collectUrls(): Map<string, Set<string>> {
+	const urls = new Map<string, Set<string>>();
+	const files = htmlFiles(ROOT);
+	// The site's own canonical/OG URLs reference the production domain, which
+	// may not be cut over yet — and internal integrity is already enforced by
+	// the prerender crawler. Skip the canonical host entirely.
+	const ownHost = files.map((f) => canonicalHost(readFileSync(f, "utf8"))).find(Boolean);
+	for (const file of files) {
+		// Preconnect hints are bare origins (they often 404 at "/") — they warm
+		// connections, they aren't content links.
+		const html = readFileSync(file, "utf8").replace(/<link rel="preconnect"[^>]*>/g, "");
+		for (const match of html.matchAll(ATTR_URL)) {
+			const url = match[1].replace(/&amp;/g, "&");
+			const host = new URL(url).hostname;
+			if (SKIP_HOSTS.has(host) || SKIP_SUFFIXES.some((s) => host.endsWith(s))) continue;
+			if (ownHost && (host === ownHost || host === `www.${ownHost}`)) continue;
+			if (!urls.has(url)) urls.set(url, new Set());
+			urls.get(url)?.add(file.replace(`${ROOT}/`, ""));
+		}
+	}
+	return urls;
+}
+
+async function probe(url: string): Promise<number> {
+	const attempt = async (method: "HEAD" | "GET") => {
+		const res = await fetch(url, {
+			method,
+			redirect: "follow",
+			signal: AbortSignal.timeout(15000),
+			headers: { "user-agent": "Mozilla/5.0 (link-check; +https://atelic.me)" },
+		});
+		return res.status;
+	};
+	try {
+		const status = await attempt("HEAD");
+		// Some hosts reject HEAD; retry with GET before judging.
+		return status >= 400 ? await attempt("GET") : status;
+	} catch {
+		try {
+			return await attempt("GET");
+		} catch {
+			return 0;
+		}
+	}
+}
+
+/** The command: checks the build in the working directory. */
+export async function main(): Promise<void> {
+	const urls = collectUrls();
+	console.log(`[links] checking ${urls.size} external URLs across ${ROOT}`);
+
+	let failures = 0;
+	for (const [url, pages] of urls) {
+		const status = await probe(url);
+		const ok = status >= 200 && status < 400;
+		if (!ok) {
+			failures++;
+			console.error(`  DEAD (${status || "no response"}): ${url}`);
+			console.error(`        referenced by: ${[...pages].join(", ")}`);
+		} else {
+			console.log(`  ok (${status}): ${url}`);
+		}
+	}
+
+	if (failures > 0) {
+		console.error(`[links] ${failures} dead external link(s)`);
+		process.exit(1);
+	}
+	console.log("[links] all external links alive");
+}