@growth-labs/cms 0.5.29 → 0.5.30

package/src/engine/publication-receipt/canonical-json.ts

@@ -0,0 +1,123 @@
+// RFC 8785 JSON Canonicalization Scheme (#342).
+//
+// A publication receipt is hashed and signed, and the same bytes must be
+// reproducible by Foundry from the same object. Canonicalization is what makes
+// that true: `JSON.stringify` alone is not stable, because object key order
+// follows insertion order rather than a defined sort.
+//
+// Deliberately implemented rather than pulled from a dependency. The whole
+// value here is that both sides agree byte-for-byte, so the algorithm should be
+// readable, pinned, and covered by the RFC's own vectors rather than tracking
+// someone else's semver.
+
+export class CanonicalJsonError extends Error {
+	readonly code: 'non_finite_number' | 'unsupported_type' | 'circular_reference'
+
+	constructor(code: CanonicalJsonError['code'], message: string) {
+		super(message)
+		this.name = 'CanonicalJsonError'
+		this.code = code
+	}
+}
+
+type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
+
+/**
+ * Serialize `value` per RFC 8785.
+ *
+ * Three things do the work, and each is load-bearing:
+ *
+ * 1. Object keys sort by UTF-16 code unit. JavaScript's default string sort is
+ *    already a UTF-16 code-unit comparison, which is exactly what §3.2.3
+ *    requires — so `.sort()` here is the specified behaviour, not a shortcut.
+ * 2. Numbers use ECMAScript `Number::toString`, which `JSON.stringify` applies.
+ *    §3.2.2.3 defers to that same algorithm, so the platform is authoritative
+ *    and reimplementing it would only introduce drift.
+ * 3. Strings use `JSON.stringify`'s escaping, which since ES2019 emits
+ *    well-formed output (lone surrogates escaped rather than passed through) —
+ *    §3.2.2.2's requirement.
+ *
+ * Non-finite numbers throw rather than becoming `null` as `JSON.stringify`
+ * would. A receipt containing `NaN` is a bug, and silently signing `null` in
+ * its place would make that bug undetectable downstream.
+ */
+export function canonicalJson(value: JsonValue): string {
+	return write(value, new Set())
+}
+
+function write(value: JsonValue, seen: Set<object>): string {
+	if (value === null) return 'null'
+
+	switch (typeof value) {
+		case 'boolean':
+			return value ? 'true' : 'false'
+
+		case 'number': {
+			if (!Number.isFinite(value)) {
+				throw new CanonicalJsonError(
+					'non_finite_number',
+					`Cannot canonicalize non-finite number: ${String(value)}`,
+				)
+			}
+			// -0 serializes as "0" per RFC 8785 §3.2.2.3; JSON.stringify agrees.
+			return JSON.stringify(value)
+		}
+
+		case 'string':
+			return JSON.stringify(value)
+
+		case 'object':
+			break
+
+		default:
+			throw new CanonicalJsonError(
+				'unsupported_type',
+				`Cannot canonicalize value of type ${typeof value}`,
+			)
+	}
+
+	const object = value as object
+	if (seen.has(object)) {
+		throw new CanonicalJsonError('circular_reference', 'Cannot canonicalize a circular structure')
+	}
+	seen.add(object)
+
+	try {
+		if (Array.isArray(value)) {
+			return `[${value.map((entry) => write(entry, seen)).join(',')}]`
+		}
+
+		const record = value as { [key: string]: JsonValue }
+		// Undefined-valued keys are omitted, matching JSON.stringify. RFC 8785
+		// has no representation for them.
+		const keys = Object.keys(record)
+			.filter((key) => record[key] !== undefined)
+			.sort()
+
+		const members = keys.map(
+			(key) => `${JSON.stringify(key)}:${write(record[key] as JsonValue, seen)}`,
+		)
+		return `{${members.join(',')}}`
+	} finally {
+		seen.delete(object)
+	}
+}
+
+/** Canonical UTF-8 bytes, which are what gets hashed and signed. */
+export function canonicalJsonBytes(value: JsonValue): Uint8Array {
+	return new TextEncoder().encode(canonicalJson(value))
+}
+
+/** Lowercase hex SHA-256 of the canonical bytes. */
+export async function canonicalJsonSha256(value: JsonValue): Promise<string> {
+	// `Uint8Array.from` yields an ArrayBuffer-backed copy. TextEncoder returns
+	// `Uint8Array<ArrayBufferLike>`, which may be SharedArrayBuffer-backed and
+	// so is not a `BufferSource`. Same idiom as sha256Hex in
+	// @growth-labs/monitoring's site-agent signature helper.
+	const copy = Uint8Array.from(canonicalJsonBytes(value))
+	const digest = await globalThis.crypto.subtle.digest('SHA-256', copy)
+	return Array.from(new Uint8Array(digest))
+		.map((byte) => byte.toString(16).padStart(2, '0'))
+		.join('')
+}

package/src/engine/publication-receipt/receipt.ts

@@ -0,0 +1,160 @@
+// `site.publication.receipt.v1` — the signed handoff receipt (#342).
+//
+// A receipt is the site's terminal, non-repudiable statement about one
+// publication attempt. Foundry must be able to verify it without trusting the
+// transport and without re-querying the site, so everything it needs to judge
+// the claim is inside the signed body.
+//
+// The site persists the canonical bytes and signature exactly once BEFORE
+// network delivery; a retry resends those stored bytes verbatim. That is why
+// nothing in the body is derived at sign time — the nonce and timestamps are
+// inputs, not defaults. A schema that generated its own nonce would produce a
+// different receipt on every retry and break replay-safety by construction.
+
+import { z } from 'zod'
+import { canonicalJson, type JsonValue } from './canonical-json.js'
+
+export const SITE_PUBLICATION_RECEIPT_SCHEMA = 'site.publication.receipt.v1' as const
+export const SITE_PUBLICATION_RECEIPT_AUDIENCE = 'foundry:site-publication-receipt' as const
+
+/** Lowercase hex SHA-256. */
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, 'expected lowercase hex sha-256')
+
+/** A bounded identifier: printable ASCII, no whitespace, capped. */
+const identifier = z
+	.string()
+	.min(1)
+	.max(256)
+	.regex(/^[\x21-\x7e]+$/, 'expected a bounded printable identifier')
+
+/** RFC 3339 UTC instant, seconds precision, `Z` only — no local offsets. */
+const instant = z
+	.string()
+	.regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/, 'expected an RFC 3339 UTC instant')
+
+/** A count that must stay bounded so a receipt cannot carry unbounded claims. */
+const boundedCount = z.number().int().min(0).max(1_000_000)
+
+export const publicationProbeSchema = z
+	.object({
+		/** What was probed, e.g. `html` or `markdown`. */
+		kind: z.enum(['html', 'markdown']),
+		url: z.string().url().max(2048),
+		status: z.number().int().min(100).max(599),
+		/** SHA-256 of the exact bytes observed, so Foundry can compare. */
+		digest: sha256Hex,
+	})
+	.strict()
+
+export const publicationProjectionCountsSchema = z
+	.object({
+		seo: boundedCount,
+		search: boundedCount,
+		sitemap: boundedCount,
+		feed: boundedCount,
+	})
+	.strict()
+
+export const sitePublicationReceiptBodySchema = z
+	.object({
+		schema: z.literal(SITE_PUBLICATION_RECEIPT_SCHEMA),
+		audience: z.literal(SITE_PUBLICATION_RECEIPT_AUDIENCE),
+
+		/** Success and failure are both signed; a silent failure is unverifiable. */
+		outcome: z.enum(['success', 'failure']),
+
+		/** Identity of the publishing property (the site). */
+		property: z.object({ id: identifier, origin: z.string().url().max(2048) }).strict(),
+
+		/** Identity of the thing published, stable across revisions. */
+		content: z
+			.object({
+				stableId: identifier,
+				slug: identifier,
+				revisionId: identifier,
+			})
+			.strict(),
+
+		/** What produced it. */
+		source: z
+			.object({
+				commit: z.string().regex(/^[0-9a-f]{40}$/, 'expected a full git sha'),
+				foundryHandoffId: identifier,
+				foundryRunId: identifier,
+			})
+			.strict(),
+
+		/** Logical database identity — never a connection string or credential. */
+		database: z.object({ logicalId: identifier }).strict(),
+
+		/** Hash of the public media manifest, not the media itself. */
+		publicMediaManifestHash: sha256Hex,
+
+		projections: publicationProjectionCountsSchema,
+		probes: z.array(publicationProbeSchema).max(16),
+
+		/** How to undo this publication. */
+		rollback: z.object({ pointer: identifier }).strict(),
+
+		/** Replay identity. Supplied by the caller and persisted, never generated here. */
+		nonce: identifier,
+		issuedAt: instant,
+
+		/** Present only when `outcome` is `failure`, and bounded. */
+		failureReason: z.string().min(1).max(512).optional(),
+	})
+	.strict()
+	.superRefine((body, ctx) => {
+		if (body.outcome === 'failure' && body.failureReason === undefined) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['failureReason'],
+				message: 'a failure receipt must state its reason',
+			})
+		}
+		if (body.outcome === 'success' && body.failureReason !== undefined) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['failureReason'],
+				message: 'a success receipt must not carry a failure reason',
+			})
+		}
+	})
+
+export type SitePublicationReceiptBody = z.infer<typeof sitePublicationReceiptBodySchema>
+
+export class PublicationReceiptError extends Error {
+	readonly code: 'invalid_body' | 'invalid_key'
+
+	constructor(code: PublicationReceiptError['code'], message: string) {
+		super(message)
+		this.name = 'PublicationReceiptError'
+		this.code = code
+	}
+}
+
+/**
+ * Validate a receipt body and return its canonical RFC 8785 form.
+ *
+ * Validation happens before canonicalization on purpose: signing an unvalidated
+ * body would produce a verifiable signature over a malformed claim, which is
+ * strictly worse than refusing, because downstream would trust it.
+ */
+export function canonicalizeReceiptBody(body: unknown): {
+	body: SitePublicationReceiptBody
+	canonical: string
+} {
+	const parsed = sitePublicationReceiptBodySchema.safeParse(body)
+	if (!parsed.success) {
+		throw new PublicationReceiptError(
+			'invalid_body',
+			`Receipt body failed validation: ${parsed.error.issues
+				.map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+				.join('; ')}`,
+		)
+	}
+	return {
+		body: parsed.data,
+		canonical: canonicalJson(parsed.data as unknown as JsonValue),
+	}
+}

package/src/engine/publication-receipt/signature.ts

@@ -0,0 +1,112 @@
+// Ed25519 signature envelope for `site.publication.receipt.v1` (#342).
+//
+// Signs the RFC 8785 canonical bytes of the receipt body, so the signature is
+// over exactly what Foundry will re-canonicalize and compare — not over a
+// re-serialization that might differ in key order.
+//
+// crypto.subtle only; never node:crypto. The package runs in Workers.
+
+import { canonicalJsonSha256 } from './canonical-json.js'
+import {
+	canonicalizeReceiptBody,
+	PublicationReceiptError,
+	SITE_PUBLICATION_RECEIPT_AUDIENCE,
+	type SitePublicationReceiptBody,
+	sitePublicationReceiptBodySchema,
+} from './receipt.js'
+
+export interface SignedPublicationReceipt {
+	body: SitePublicationReceiptBody
+	/** The exact bytes that were signed. Persist these, not a re-serialization. */
+	canonical: string
+	/** Lowercase hex SHA-256 of `canonical`. */
+	bodyHash: string
+	/** Base64url, unpadded. */
+	signature: string
+	/** Key id the verifier should select. */
+	kid: string
+	audience: typeof SITE_PUBLICATION_RECEIPT_AUDIENCE
+}
+
+function toBase64Url(bytes: Uint8Array): string {
+	let binary = ''
+	for (const byte of bytes) binary += String.fromCharCode(byte)
+	return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function fromBase64Url(value: string): Uint8Array {
+	if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+		throw new PublicationReceiptError('invalid_body', 'Signature is not unpadded base64url')
+	}
+	const padded = value.replace(/-/g, '+').replace(/_/g, '/')
+	const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4))
+	const bytes = new Uint8Array(binary.length)
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
+	return bytes
+}
+
+/** ArrayBuffer-backed copy — TextEncoder output is not a `BufferSource`. */
+function encode(value: string): Uint8Array<ArrayBuffer> {
+	return Uint8Array.from(new TextEncoder().encode(value))
+}
+
+/**
+ * Validate, canonicalize and sign a receipt body.
+ *
+ * Deterministic: the same body and key always produce the same bytes and the
+ * same signature, which is what makes "retries resend byte-identical bytes"
+ * achievable. Nothing is generated here — the nonce and `issuedAt` come from
+ * the caller, who is responsible for persisting them once.
+ */
+export async function signPublicationReceipt(
+	body: unknown,
+	key: CryptoKey,
+	kid: string,
+): Promise<SignedPublicationReceipt> {
+	if (key.type !== 'private') {
+		throw new PublicationReceiptError('invalid_key', 'Signing requires an Ed25519 private key')
+	}
+	const { body: validated, canonical } = canonicalizeReceiptBody(body)
+	const signature = await globalThis.crypto.subtle.sign({ name: 'Ed25519' }, key, encode(canonical))
+	return {
+		body: validated,
+		canonical,
+		bodyHash: await canonicalJsonSha256(validated as never),
+		signature: toBase64Url(new Uint8Array(signature)),
+		kid,
+		audience: SITE_PUBLICATION_RECEIPT_AUDIENCE,
+	}
+}
+
+/**
+ * Verify a receipt as Foundry would: re-canonicalize the body from scratch and
+ * check the signature over THOSE bytes.
+ *
+ * Deliberately ignores any `canonical` string supplied alongside the receipt. A
+ * verifier that trusts the sender's canonical form would accept a signature
+ * over bytes that do not match the body it then acts on — which is the whole
+ * attack canonicalization exists to prevent.
+ */
+export async function verifyPublicationReceipt(
+	receipt: { body: unknown; signature: string },
+	key: CryptoKey,
+): Promise<boolean> {
+	const parsed = sitePublicationReceiptBodySchema.safeParse(receipt.body)
+	if (!parsed.success) return false
+	if (parsed.data.audience !== SITE_PUBLICATION_RECEIPT_AUDIENCE) return false
+
+	let signatureBytes: Uint8Array
+	try {
+		signatureBytes = fromBase64Url(receipt.signature)
+	} catch {
+		return false
+	}
+
+	const { canonical } = canonicalizeReceiptBody(parsed.data)
+	return await globalThis.crypto.subtle.verify(
+		{ name: 'Ed25519' },
+		key,
+		Uint8Array.from(signatureBytes),
+		encode(canonical),
+	)
+}

package/src/engine/publication.ts

@@ -819,6 +819,8 @@ function assertPublicationSnapshotBodyValid(
 		},
 		{
 			source: 'publish-one',
+			// #329: source-section defects block at publish, warn on save.
+			blockSourceSectionDefects: true,
 			contentId,
 			requireBody: true,
 		},

package/src/engine/publisher.ts

@@ -1210,6 +1210,8 @@ export async function evaluateContentBodyForPublish(
 			source,
 			contentId: id,
 			requireBody: true,
+			// #329: source-section defects block at publish, warn on save.
+			blockSourceSectionDefects: true,
 		},
 	)
 }

package/src/engine/source-sections.ts

@@ -0,0 +1,153 @@
+// Canonical normalization for article "Sources" / "References" sections
+// (packages#329).
+//
+// Editors paste these sections out of Word and Google Docs, which produces
+// Markdown that renders wrongly rather than not at all: manual `●` bullets
+// become separate paragraphs, a bold line used as a heading becomes an empty
+// `h2`, and `[**title**](url)` keeps its `**` inside the anchor text because
+// renderers protect generated links before evaluating inline emphasis.
+//
+// This lives in the package, not in a site, so the CMS save path, preview
+// path, import path and every site integration share one behaviour.
+
+const NBSP = ' '
+const SECTION_WORDS = ['sources', 'references'] as const
+
+export interface SourceSectionNormalization {
+	markdown: string
+	/** True when normalization altered the document. Callers use this to decide
+	 *  whether a cached `body_html` render must be invalidated. */
+	changed: boolean
+}
+
+/** `## Sources`, `### References:` — returns its level and canonical word. */
+function matchHeadingBoundary(line: string): { level: number; word: string } | null {
+	const match = /^(#{1,6})\s+(.*)$/.exec(line)
+	if (!match) return null
+	const level = match[1]?.length ?? 0
+	const word = canonicalWord(stripTrailingColon(match[2] ?? ''))
+	return word ? { level, word } : null
+}
+
+/** A standalone bold line used as a heading: `**Sources:**`, `__References__`. */
+function matchBoldBoundary(line: string): { word: string } | null {
+	const match = /^\s*(\*\*|__)(.+?)\1\s*$/.exec(line)
+	if (!match) return null
+	const word = canonicalWord(stripTrailingColon(match[2] ?? ''))
+	return word ? { word } : null
+}
+
+function stripTrailingColon(value: string): string {
+	return value.replace(/\s*:\s*$/, '')
+}
+
+/** Returns the canonical capitalisation, or null when this is not a boundary. */
+function canonicalWord(rawText: string): string | null {
+	const visible = rawText.replaceAll(NBSP, ' ').replace(/[*_]/g, '').trim().toLowerCase()
+	const found = SECTION_WORDS.find((candidate) => candidate === visible)
+	return found ? `${found[0]?.toUpperCase()}${found.slice(1)}` : null
+}
+
+/** A line whose visible content is empty once emphasis and spacing are removed. */
+function isFormattingOnly(line: string): boolean {
+	if (line.trim() === '') return false // a real blank line is structural
+	return (
+		line
+			.replaceAll(NBSP, ' ')
+			.replace(/[*_~`]/g, '')
+			.trim() === ''
+	)
+}
+
+function headingLevel(line: string): number | null {
+	const match = /^(#{1,6})\s+\S/.exec(line)
+	return match ? (match[1]?.length ?? null) : null
+}
+
+/**
+ * Unwrap emphasis that covers an ENTIRE link label: `[**t**](u)` -> `[t](u)`.
+ *
+ * Partial emphasis (`[a **b** c](u)`) is intentional and preserved, and an
+ * unbalanced marker (`[**a](u)`) is ambiguous — repairing it would be guessing
+ * at intent. The URL is never touched.
+ */
+function unwrapWholeLabelEmphasis(line: string): string {
+	return line.replace(/\[([^\]]*)\]\(/g, (whole, label: string) => {
+		const match = /^(\*\*|__|\*|_)([\s\S]+)\1$/.exec(label.trim())
+		if (!match) return whole
+		const inner = match[2] ?? ''
+		// Only unwrap when the delimiter genuinely wraps the whole label rather
+		// than being two adjacent runs, e.g. `**a** and **b**`.
+		if (inner.includes(match[1] as string)) return whole
+		return `[${inner}](`
+	})
+}
+
+function normalizeSectionLine(line: string): string {
+	let next = line
+
+	// Manual Unicode bullets become real list markers.
+	next = next.replace(/^(\s*)[●•▪]\s*/u, '$1- ')
+
+	// Non-breaking-space indentation after a list marker collapses to one space.
+	next = next.replace(
+		new RegExp(`^(\\s*[-*+])[ ${NBSP}]+`, 'u'),
+		(_m, marker: string) => `${marker} `,
+	)
+
+	next = unwrapWholeLabelEmphasis(next)
+	return next
+}
+
+/**
+ * Rewrite `Sources` / `References` sections to the canonical shape.
+ *
+ * Only lines inside a bounded section are touched. A section starts at an ATX
+ * heading or a standalone bold line whose visible text is `Sources` or
+ * `References` (with an optional trailing colon), and ends at the next heading
+ * of the same or higher level, or at end of document.
+ *
+ * Deliberately does NOT rewrite URLs, invent titles for bare URLs, repair
+ * unbalanced emphasis, or alter anything outside a section — each of those
+ * requires guessing at editorial intent.
+ */
+export function normalizeSourceSections(markdown: string): SourceSectionNormalization {
+	const usesCrlf = markdown.includes('\r\n')
+	const lines = markdown.replace(/\r\n/g, '\n').split('\n')
+	const out: string[] = []
+
+	let sectionLevel: number | null = null
+
+	for (const line of lines) {
+		if (sectionLevel !== null) {
+			const level = headingLevel(line)
+			if (level !== null && level <= sectionLevel) {
+				sectionLevel = null // section closed; fall through to boundary checks
+			} else {
+				if (isFormattingOnly(line)) continue
+				out.push(normalizeSectionLine(line))
+				continue
+			}
+		}
+
+		const heading = matchHeadingBoundary(line)
+		if (heading) {
+			sectionLevel = heading.level
+			out.push(`${'#'.repeat(heading.level)} ${heading.word}`)
+			continue
+		}
+
+		const bold = matchBoldBoundary(line)
+		if (bold) {
+			sectionLevel = 2
+			out.push(`## ${bold.word}`)
+			continue
+		}
+
+		out.push(line)
+	}
+
+	const joined = out.join('\n')
+	const result = usesCrlf ? joined.replace(/\n/g, '\r\n') : joined
+	return { markdown: result, changed: result !== markdown }
+}