@growth-labs/cms 0.8.20 → 0.8.23

package/src/routes/foundry-publish.ts

@@ -1,11 +1,15 @@
+import { isCanonicalHost, sha256Hex, verifyFoundryRequest } from '@growth-labs/foundry-signing'
 import { z } from 'zod'
-import { verifyHmac } from '../engine/foundry-dispatch.js'
+import { type PublicationReconciler, publishOne } from '../engine/publication.js'
+import { PublishContentValidationError } from '../engine/publisher.js'
+import { createRevisionWithDelta } from '../engine/revisions.js'
 import { buildContentPath, slugify } from '../engine/slug.js'
+import { type FoundryArticleV2, FoundryArticleV2Schema } from '../foundry-emit.js'
 import { type ContentRouteConfig, createContentRoutes } from './content.js'
 import { json, type RouteContext } from './context.js'
+import { markFoundryMachineContext } from './machine-context.js'
 import { insertMediaAsset } from './media-lib.js'
 
-const MAX_SKEW_SECONDS = 300
 const SOURCE_PREFIX = 'foundry:'
 
 const PutSchema = z
@@ -26,10 +30,60 @@ interface FoundryArticleRow {
 	slug: string
 }
 
+/**
+ * The per-publication opt-in for the publish transition (M3-18). It lives on the
+ * route's config (`ContentRouteConfig.foundryPublish`); the Astro adapter reads it
+ * from `locals.cmsHooks.foundryPublish`. Only `autoPublish === true` turns it on.
+ */
+export interface FoundryPublishOptions {
+	/** `true` enables v2 PUTs (drafts, in-place edits of published items) and POST /publish. */
+	autoPublish?: boolean
+	/**
+	 * The publication's LIVE surfaces (sitemap, feed, .md twin, ...), resolved per
+	 * request and handed to `publishOne`. The route never passes
+	 * `allowNoSurfaces`: an absent or empty list refuses the publish with 503
+	 * before anything is written.
+	 */
+	surfaces?: (ctx: RouteContext) => PublicationReconciler[] | Promise<PublicationReconciler[]>
+	/** Forwarded to `publishOne`; each named surface must be present. */
+	requiredSurfaceNames?: string[]
+	/** Forwarded to `publishOne` for its ledger. */
+	packageVersion?: string | null
+	/**
+	 * Declares that the publication's scheduler publishes scheduled items through
+	 * `publishOne` with these live surfaces. Without it, POST /publish refuses a
+	 * future publishAt with `409 scheduling_requires_surface_scheduler`, because
+	 * the legacy scheduled sweep (engine/cron.ts runScheduledPublish) publishes
+	 * with no surfaces.
+	 */
+	scheduling?: 'publishOne'
+	/**
+	 * The namespace this publication's archive bridge writes into
+	 * `content_items.source_id` (`<namespace>:<relpath>`, e.g. `warfronts`; see a
+	 * channel repo's scripts/archive-import/compiler.mjs SOURCE_NAMESPACE and
+	 * buildSourceId). Only items under exactly this prefix can be adopted; with
+	 * none declared, nothing can.
+	 */
+	bridgeSourceNamespace?: string
+	/**
+	 * REQUIRED when `autoPublish` is on: this publication's canonical host,
+	 * lowercase with no scheme and no port (e.g. `warfronts.pub`). The Foundry
+	 * HMAC secret is shared by every site, so a publication that declares a host
+	 * (here or as `ContentRouteConfig.foundryCanonicalHost`, with or without
+	 * `autoPublish`) verifies the host-bound `foundry-cms-v2` string with THIS
+	 * host (never the request's Host header) on every /api/cms/foundry/* verb,
+	 * and refuses the legacy dot form and a request signed for another site.
+	 * Malformed, or disagreeing with `foundryCanonicalHost`: every verb answers 503.
+	 */
+	canonicalHost?: string
+}
+
 export interface FoundryPublishRouteHandlers {
 	put(ctx: RouteContext): Promise<Response>
 	get(ctx: RouteContext): Promise<Response>
 	unpublish(ctx: RouteContext): Promise<Response>
+	/** M3-18: publish (or resync) through publishOne; 409 unless the publication opted in. */
+	publish(ctx: RouteContext): Promise<Response>
 }
 
 async function resolveSecret(env: Record<string, unknown> | undefined): Promise<string | null> {
@@ -46,36 +100,32 @@ async function resolveSecret(env: Record<string, unknown> | undefined): Promise<
 	return null
 }
 
-async function sha256(value: string): Promise<string> {
-	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value))
-	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
-}
-
 async function authenticate(
 	ctx: RouteContext,
 	body: string,
+	canonicalHost: string | null = null,
 ): Promise<{ bodyHash: string } | { error: Response }> {
 	const secret = await resolveSecret(ctx.env)
 	if (!secret) return { error: json({ error: 'GL_CMS_FOUNDRY_UNCONFIGURED' }, 503) }
 
-	const timestamp = (ctx.request.headers.get('X-Foundry-Timestamp') ?? '').trim()
-	if (!/^\d{1,15}$/.test(timestamp)) return { error: json({ error: 'unauthorized' }, 401) }
-	const seconds = Number.parseInt(timestamp, 10)
-	if (
-		!Number.isSafeInteger(seconds) ||
-		Math.abs(Math.floor(Date.now() / 1_000) - seconds) > MAX_SKEW_SECONDS
-	) {
-		return { error: json({ error: 'unauthorized' }, 401) }
-	}
-
-	const bodyHash = await sha256(body)
+	// The one Foundry route-family verifier (@growth-labs/foundry-signing): the
+	// host-bound foundry-cms-v2 string with this publication's CONFIGURED
+	// canonical host when it opted in (M3-18), else the legacy dot string,
+	// byte-for-byte as before.
 	const path = new URL(ctx.request.url).pathname
-	const signed = `${ctx.request.method}.${path}.${timestamp}.${bodyHash}`
-	const signature = ctx.request.headers.get('X-Foundry-Signature') ?? ''
-	if (!(await verifyHmac(secret, signed, signature))) {
-		console.warn('[cms] foundry article request rejected: invalid signature', { path })
+	const verified = await verifyFoundryRequest(secret, {
+		method: ctx.request.method,
+		host: canonicalHost,
+		path,
+		timestampHeader: ctx.request.headers.get('X-Foundry-Timestamp'),
+		signatureHeader: ctx.request.headers.get('X-Foundry-Signature'),
+		body,
+	})
+	if (!verified) {
+		console.warn('[cms] foundry article request rejected', { path })
 		return { error: json({ error: 'unauthorized' }, 401) }
 	}
+	const bodyHash = await sha256Hex(body)
 	return { bodyHash }
 }
 
@@ -140,7 +190,9 @@ function nativeContext(
 	params: Record<string, string>,
 	query = '',
 ): RouteContext {
-	return {
+	// Every caller has already verified the Foundry HMAC: the native context it
+	// builds is the machine's, and is marked as such (see machine-context.ts).
+	return markFoundryMachineContext({
 		...ctx,
 		request: new Request(`${new URL(ctx.request.url).origin}/internal/cms${query}`, {
 			method,
@@ -149,7 +201,7 @@ function nativeContext(
 		}),
 		params,
 		userId: 'foundry',
-	}
+	})
 }
 
 async function upsertReceipt(
@@ -172,7 +224,7 @@ async function upsertReceipt(
 }
 
 async function heroAssetId(url: string): Promise<string> {
-	return `foundry-hero-${(await sha256(url)).slice(0, 24)}`
+	return `foundry-hero-${(await sha256Hex(url)).slice(0, 24)}`
 }
 
 async function persistHeroAsset(
@@ -215,17 +267,654 @@ async function mapUpdateConflict(response: Response, id: string): Promise<Respon
 	return response
 }
 
+// --- v2 (M3-18): opt-in publish transition, verbatim slug, one-time adoption ---
+//
+// Everything below runs only when `config.foundryPublish.autoPublish === true`
+// AND the body declares `schemaVersion: 2`. Every other request takes the v1
+// path above, unchanged.
+
+type ContentHandlers = ReturnType<typeof createContentRoutes>
+
+function autoPublishEnabled(config: ContentRouteConfig): boolean {
+	return config.foundryPublish?.autoPublish === true
+}
+
+/**
+ * The canonical host this publication declared for the Foundry route family:
+ * the static `foundryCanonicalHost` and/or the opt-in's
+ * `foundryPublish.canonicalHost`. `null` when neither is declared. A declared
+ * host is never downgraded to the legacy form: a malformed host, or two that
+ * disagree, resolve to `{ host: null }`, which fails closed.
+ */
+function declaredCanonicalHost(config: ContentRouteConfig): { host: string | null } | null {
+	const declared = [config.foundryCanonicalHost, config.foundryPublish?.canonicalHost].filter(
+		(value) => value !== undefined,
+	)
+	if (declared.length === 0) return null
+	const [first] = declared
+	const agreed = declared.every(
+		(value) => typeof value === 'string' && isCanonicalHost(value) && value === first,
+	)
+	return { host: agreed ? (first as string) : null }
+}
+
+function isV2Payload(payload: unknown): boolean {
+	return (
+		typeof payload === 'object' &&
+		payload !== null &&
+		!Array.isArray(payload) &&
+		(payload as { schemaVersion?: unknown }).schemaVersion === 2
+	)
+}
+
+async function resolveLiveSurfaces(
+	ctx: RouteContext,
+	config: ContentRouteConfig,
+): Promise<PublicationReconciler[] | null> {
+	const resolve = config.foundryPublish?.surfaces
+	if (typeof resolve !== 'function') return null
+	try {
+		const surfaces = await resolve(ctx)
+		return Array.isArray(surfaces) && surfaces.length > 0 ? surfaces : null
+	} catch (error) {
+		console.error('[cms] foundry publish surfaces could not be resolved', error)
+		return null
+	}
+}
+
+interface ContentCandidate {
+	id: string
+	status: FoundryArticleRow['status']
+	type: string
+	slug: string
+	source_id: string | null
+	deleted_at: number | null
+	bound_external_id: string | null
+}
+
+interface Adoption {
+	content_id: string
+	from_source_id: string
+	matched_by: 'source_id' | 'slug'
+}
+
+async function findCandidate(
+	ctx: RouteContext,
+	column: 'source_id' | 'slug',
+	value: string,
+): Promise<ContentCandidate | null> {
+	return ctx.db
+		.prepare(
+			`SELECT c.id, c.status, c.type, c.slug, c.source_id, c.deleted_at,
+			        f.external_id AS bound_external_id
+			 FROM content_items c
+			 LEFT JOIN cms_foundry_articles f ON f.content_id = c.id
+			 WHERE c.${column} = ?
+			 LIMIT 1`,
+		)
+		.bind(value)
+		.first<ContentCandidate>()
+}
+
+function slugConflict(id: string, slug: string, contentId: string): Response {
+	return json({ error: 'slug_conflict', external_id: id, slug, content_id: contentId }, 409)
+}
+
+const BRIDGE_NAMESPACE = /^[a-z0-9][a-z0-9-]{0,63}$/
+
+function bridgePrefix(config: ContentRouteConfig): string | null {
+	const namespace = config.foundryPublish?.bridgeSourceNamespace
+	return typeof namespace === 'string' && BRIDGE_NAMESPACE.test(namespace) ? `${namespace}:` : null
+}
+
+function adoptable(
+	config: ContentRouteConfig,
+	id: string,
+	candidate: ContentCandidate,
+	matchedBy: Adoption['matched_by'],
+): { candidate: ContentCandidate; matchedBy: Adoption['matched_by'] } | { error: Response } {
+	const reason =
+		candidate.deleted_at !== null
+			? 'deleted'
+			: candidate.type !== 'article'
+				? 'not_article'
+				: candidate.bound_external_id !== null || candidate.source_id?.startsWith(SOURCE_PREFIX)
+					? 'bound_to_another_external_id'
+					: !candidate.source_id
+						? 'not_bridge_imported'
+						: null
+	if (reason) {
+		return {
+			error: json(
+				{ error: 'adoption_conflict', external_id: id, content_id: candidate.id, reason },
+				409,
+			),
+		}
+	}
+	// Only the publication's own archive bridge namespace is adoptable: any
+	// other source (another importer, another publication's bridge) is refused.
+	const prefix = bridgePrefix(config)
+	if (!prefix || !candidate.source_id?.startsWith(prefix) || candidate.source_id === prefix) {
+		return {
+			error: json(
+				{
+					error: 'adoption_source_not_bridge',
+					external_id: id,
+					content_id: candidate.id,
+					source_id: candidate.source_id,
+				},
+				409,
+			),
+		}
+	}
+	return { candidate, matchedBy }
+}
+
+/**
+ * One-time adoption, before anything is created: `adoptSourceId` resolves by
+ * exact source_id; without it, the verbatim slug resolves the item. Only a
+ * bridge-imported article (a non-foundry source_id) that no external id owns
+ * can be adopted. Two different items named by one request is ambiguous; a slug
+ * held by an item the request did not name is a conflict. Never a duplicate.
+ */
+async function resolveAdoption(
+	ctx: RouteContext,
+	config: ContentRouteConfig,
+	id: string,
+	body: FoundryArticleV2,
+): Promise<
+	| { candidate: ContentCandidate | null; matchedBy: Adoption['matched_by'] | null }
+	| { error: Response }
+> {
+	const slugHolder = await findCandidate(ctx, 'slug', body.slug)
+	if (body.adoptSourceId) {
+		const bySource = await findCandidate(ctx, 'source_id', body.adoptSourceId)
+		if (!bySource) {
+			if (slugHolder) return { error: slugConflict(id, body.slug, slugHolder.id) }
+			return { candidate: null, matchedBy: null }
+		}
+		if (slugHolder && slugHolder.id !== bySource.id) {
+			return {
+				error: json(
+					{
+						error: 'adoption_ambiguous',
+						external_id: id,
+						candidates: [
+							{ content_id: bySource.id, matched_by: 'source_id' },
+							{ content_id: slugHolder.id, matched_by: 'slug' },
+						],
+					},
+					409,
+				),
+			}
+		}
+		return adoptable(config, id, bySource, 'source_id')
+	}
+	if (!slugHolder) return { candidate: null, matchedBy: null }
+	return adoptable(config, id, slugHolder, 'slug')
+}
+
+/**
+ * Bind the adopted item to `foundry:<external_id>` and record the adoption in
+ * the activity ledger in ONE D1 batch (one transaction). The UPDATE is a CAS on
+ * the item's prior source_id and on it having no receipt row, so a concurrent
+ * adoption or a racing bind can never produce a second owner.
+ */
+async function bindAdoption(
+	ctx: RouteContext,
+	config: ContentRouteConfig,
+	id: string,
+	candidate: ContentCandidate,
+): Promise<boolean> {
+	const sourceId = `${SOURCE_PREFIX}${id}`
+	await ctx.db.batch([
+		ctx.db
+			.prepare(
+				`UPDATE content_items SET source_id = ?, updated_at = unixepoch()
+				 WHERE id = ? AND deleted_at IS NULL AND type = 'article' AND source_id = ?
+				   AND NOT EXISTS (SELECT 1 FROM cms_foundry_articles WHERE content_id = ?)`,
+			)
+			.bind(sourceId, candidate.id, candidate.source_id, candidate.id),
+		ctx.db
+			.prepare(
+				`INSERT INTO cms_activity_log (id, workspace_id, user_id, action, target_id, target_title, type)
+				 SELECT ?, ?, 'foundry', 'foundry.adopted', id, title, type
+				 FROM content_items WHERE id = ? AND source_id = ? AND changes() = 1`,
+			)
+			.bind(crypto.randomUUID(), config.activeWorkspaceId ?? 'default', candidate.id, sourceId),
+	])
+	const bound = await ctx.db
+		.prepare('SELECT source_id FROM content_items WHERE id = ? LIMIT 1')
+		.bind(candidate.id)
+		.first<{ source_id: string | null }>()
+	return bound?.source_id === sourceId
+}
+
+function publishFailure(id: string, error: unknown): Response {
+	if (error instanceof PublishContentValidationError) {
+		return json({ error: 'publish_validation_failed', external_id: id, errors: error.errors }, 422)
+	}
+	console.error('[cms] foundry article publish failed', {
+		externalId: id,
+		error: error instanceof Error ? error.message : String(error),
+	})
+	return json({ error: 'publish_failed', external_id: id }, 502)
+}
+
+const FOUNDRY_PUT_TAG = 'foundry.put:'
+
+async function canonicalVersion(ctx: RouteContext, contentId: string): Promise<number | null> {
+	const row = await ctx.db
+		.prepare('SELECT canonical_version FROM content_items WHERE id = ? LIMIT 1')
+		.bind(contentId)
+		.first<{ canonical_version: number | null }>()
+	return row?.canonical_version ?? null
+}
+
+/**
+ * Record what this v2 PUT wrote as a History revision (the autosave/restore
+ * mechanism; it never moves the published pointer), created_by `foundry` and
+ * tagged with the request hash. POST /publish on a published item resyncs only
+ * while the item's canonical_version still equals this revision's. A snapshot
+ * that is not purely Foundry's write (another canonical write landed between
+ * the write and the snapshot) is re-tagged so it can never vouch for a resync.
+ */
+async function recordFoundryWrite(
+	ctx: RouteContext,
+	contentId: string,
+	bodyHash: string,
+	priorVersion: number | null,
+): Promise<void> {
+	const revision = await createRevisionWithDelta(ctx.db, contentId, {
+		createdBy: 'foundry',
+		tag: `${FOUNDRY_PUT_TAG}${bodyHash}`,
+	})
+	if (!revision || priorVersion === null) return
+	const recorded = await ctx.db
+		.prepare(
+			`SELECT json_extract(payload_json, '$.item.canonical_version') AS version
+			 FROM content_revisions WHERE id = ? LIMIT 1`,
+		)
+		.bind(revision.id)
+		.first<{ version: number | null }>()
+	if (recorded?.version !== priorVersion + 1) {
+		await ctx.db
+			.prepare("UPDATE content_revisions SET tag = 'foundry.put.unverified' WHERE id = ?")
+			.bind(revision.id)
+			.run()
+	}
+}
+
+/** True while the working copy is still exactly what Foundry's last v2 PUT wrote. */
+async function lastFoundryWriteCurrent(
+	ctx: RouteContext,
+	row: FoundryArticleRow,
+): Promise<boolean> {
+	const versions = await ctx.db
+		.prepare(
+			`SELECT c.canonical_version AS current_version,
+			        (SELECT json_extract(r.payload_json, '$.item.canonical_version')
+			         FROM content_revisions r
+			         WHERE r.content_id = c.id AND r.created_by = 'foundry' AND r.tag = ?
+			         ORDER BY r.created_at DESC, r.rowid DESC LIMIT 1) AS put_version
+			 FROM content_items c
+			 WHERE c.id = ? AND c.deleted_at IS NULL
+			 LIMIT 1`,
+		)
+		.bind(`${FOUNDRY_PUT_TAG}${row.request_sha256}`, row.content_id)
+		.first<{ current_version: number | null; put_version: number | null }>()
+	return (
+		versions !== null &&
+		versions.put_version !== null &&
+		versions.current_version === versions.put_version
+	)
+}
+
+/** The v2 receipt: the four v1 fields plus the stored request hash. */
+function v2Receipt(
+	row: Pick<FoundryArticleRow, 'external_id' | 'receipt_id' | 'status' | 'slug' | 'request_sha256'>,
+) {
+	return { ...receipt(row), request_sha256: row.request_sha256 }
+}
+
+/** v2 PUTs may write a machine draft or edit a published item in place (a resync). */
+const V2_WRITABLE: ReadonlySet<FoundryArticleRow['status']> = new Set(['draft', 'published'])
+
+async function putV2(
+	ctx: RouteContext,
+	config: ContentRouteConfig,
+	handlers: { draft: ContentHandlers; published: ContentHandlers },
+	id: string,
+	payload: unknown,
+	bodyHash: string,
+): Promise<Response> {
+	const parsed = FoundryArticleV2Schema.safeParse(payload)
+	if (!parsed.success)
+		return json({ error: 'invalid_request', details: parsed.error.flatten() }, 400)
+	const body = parsed.data
+
+	const prior = await findArticle(ctx, id)
+	if (prior?.request_sha256 === bodyHash) {
+		console.info('[cms] foundry article request deduplicated', {
+			externalId: id,
+			receiptId: prior.receipt_id,
+		})
+		return json(v2Receipt(prior))
+	}
+
+	let bound = prior
+		? { id: prior.content_id, status: prior.status, type: prior.type as string, slug: prior.slug }
+		: await findContentBySource(ctx, id)
+	if (bound && bound.type !== 'article') return json({ error: 'external_id_conflict' }, 409)
+	// Scheduled, review and archived items stay human-owned.
+	if (bound && !V2_WRITABLE.has(bound.status)) return approvalConflict(id, bound.status)
+
+	let adoption: Adoption | null = null
+	if (bound) {
+		const holder = await findCandidate(ctx, 'slug', body.slug)
+		if (holder && holder.id !== bound.id) return slugConflict(id, body.slug, holder.id)
+	} else {
+		const resolved = await resolveAdoption(ctx, config, id, body)
+		if ('error' in resolved) return resolved.error
+		if (resolved.candidate && resolved.matchedBy) {
+			const candidate = resolved.candidate
+			if (!(await bindAdoption(ctx, config, id, candidate))) {
+				return json(
+					{
+						error: 'adoption_conflict',
+						external_id: id,
+						content_id: candidate.id,
+						reason: 'binding_raced',
+					},
+					409,
+				)
+			}
+			adoption = {
+				content_id: candidate.id,
+				from_source_id: candidate.source_id as string,
+				matched_by: resolved.matchedBy,
+			}
+			console.info('[cms] foundry article adopted', { externalId: id, ...adoption })
+			if (!V2_WRITABLE.has(candidate.status)) {
+				return json(
+					{
+						error: 'published_requires_approval',
+						external_id: id,
+						state: candidate.status,
+						adoption,
+					},
+					409,
+				)
+			}
+			bound = {
+				id: candidate.id,
+				status: candidate.status,
+				type: candidate.type,
+				slug: candidate.slug,
+			}
+		}
+	}
+
+	// The canonical version Foundry's write must produce is one over this.
+	const priorVersion = bound ? await canonicalVersion(ctx, bound.id) : null
+	const heroImageId = body.hero_image_url
+		? await heroAssetId(body.hero_image_url)
+		: (body.hero_image_key ?? undefined)
+	const nativeBody = {
+		title: body.title,
+		slug: body.slug,
+		...(heroImageId ? { heroImageId } : {}),
+		...(body.description !== undefined
+			? { description: body.description, excerpt: body.description }
+			: {}),
+		...(body.author !== undefined ? { byline: body.author } : {}),
+		...(body.desk !== undefined ? { primaryCategory: body.desk } : {}),
+		...(body.tags !== undefined ? { tags: body.tags } : {}),
+		...(body.visibility !== undefined ? { visibility: body.visibility } : {}),
+		content: { bodyMarkdown: body.body_html, bodyHtml: body.body_html },
+	}
+
+	let nativeResponse: Response
+	if (bound) {
+		// Each write is a CAS on the status it was read in: a draft stays a
+		// draft write, and a published item is edited in place only while it is
+		// still published (its live revision changes only on POST /publish).
+		const writer = bound.status === 'published' ? handlers.published : handlers.draft
+		nativeResponse = await mapUpdateConflict(
+			await writer.update(nativeContext(ctx, 'PATCH', nativeBody, { id: bound.id })),
+			id,
+		)
+	} else {
+		try {
+			nativeResponse = await handlers.draft.create(
+				nativeContext(
+					ctx,
+					'POST',
+					{ ...nativeBody, type: 'article', sourceId: `${SOURCE_PREFIX}${id}` },
+					{},
+				),
+			)
+		} catch (error) {
+			const raced = await findContentBySource(ctx, id)
+			if (raced?.type !== 'article') throw error
+			nativeResponse = await mapUpdateConflict(
+				await handlers.draft.update(nativeContext(ctx, 'PATCH', nativeBody, { id: raced.id })),
+				id,
+			)
+		}
+	}
+	if (!nativeResponse.ok) return nativeResponse
+	if (body.hero_image_url && heroImageId) {
+		await persistHeroAsset(ctx, config, heroImageId, body.hero_image_url)
+	}
+	const written = await findContentBySource(ctx, id)
+	if (!written) return json({ error: 'write_failed' }, 500)
+	// The native writer suffixes a taken slug; a v2 slug is verbatim or refused.
+	if (written.slug !== body.slug) return slugConflict(id, body.slug, written.id)
+	// A draft carries the requested publication time for POST /publish to act on.
+	await ctx.db
+		.prepare(
+			`UPDATE content_items SET publish_at = ?
+			 WHERE id = ? AND status = 'draft' AND deleted_at IS NULL`,
+		)
+		.bind(body.publishAt ? Math.floor(Date.parse(body.publishAt) / 1_000) : null, written.id)
+		.run()
+
+	const item = await findContentBySource(ctx, id)
+	if (!item) return json({ error: 'write_failed' }, 500)
+	await recordFoundryWrite(ctx, item.id, bodyHash, priorVersion)
+	const receiptId = crypto.randomUUID()
+	await upsertReceipt(ctx, {
+		externalId: id,
+		contentId: item.id,
+		receiptId,
+		requestHash: bodyHash,
+	})
+	console.info('[cms] foundry article upserted', { externalId: id, receiptId })
+	const result = v2Receipt({
+		external_id: id,
+		receipt_id: receiptId,
+		status: item.status,
+		slug: item.slug,
+		request_sha256: bodyHash,
+	})
+	return json(adoption ? { ...result, adoption } : result)
+}
+
+/** True when the live revision already carries the item's current canonical edit. */
+async function publishedRevisionCurrent(ctx: RouteContext, contentId: string): Promise<boolean> {
+	const row = await ctx.db
+		.prepare(
+			`SELECT c.canonical_version AS current_version,
+			        json_extract(r.payload_json, '$.item.canonical_version') AS published_version
+			 FROM content_items c
+			 JOIN content_revisions r ON r.id = c.published_revision_id AND r.content_id = c.id
+			 WHERE c.id = ? AND c.status = 'published' AND c.deleted_at IS NULL
+			 LIMIT 1`,
+		)
+		.bind(contentId)
+		.first<{ current_version: number | null; published_version: number | null }>()
+	return (
+		row !== null && row.current_version !== null && row.current_version === row.published_version
+	)
+}
+
+async function publishV2(
+	ctx: RouteContext,
+	config: ContentRouteConfig,
+	content: ContentHandlers,
+	id: string,
+	row: FoundryArticleRow,
+): Promise<Response> {
+	// Idempotent: a scheduled item belongs to the engine's scheduler, and a
+	// published item whose live revision is current has nothing to resync.
+	if (row.status === 'scheduled') return json(v2Receipt(row))
+	if (row.status === 'published' && (await publishedRevisionCurrent(ctx, row.content_id))) {
+		return json(v2Receipt(row))
+	}
+	if (!V2_WRITABLE.has(row.status)) return approvalConflict(id, row.status)
+	// Publish, schedule and resync alike act on the working copy only while it is
+	// still exactly what Foundry's last v2 PUT wrote: a human edit since then (to
+	// a draft or a published item) is never machine-published or machine-scheduled.
+	if (!(await lastFoundryWriteCurrent(ctx, row))) {
+		return json({ error: 'human_edit_pending', external_id: id }, 409)
+	}
+
+	const item = await ctx.db
+		.prepare('SELECT publish_at, published_at FROM content_items WHERE id = ? LIMIT 1')
+		.bind(row.content_id)
+		.first<{ publish_at: number | null; published_at: number | null }>()
+	if (!item) return json({ error: 'not_found' }, 404)
+	const now = Math.floor(Date.now() / 1_000)
+
+	if (row.status === 'draft' && item.publish_at !== null && item.publish_at > now) {
+		// A scheduled item is published later by the site's scheduler, not here.
+		// Unless the publication declares that scheduler projects through
+		// publishOne with its live surfaces, it would publish with none: refuse
+		// at the request instead of leaving a silent gap.
+		if (config.foundryPublish?.scheduling !== 'publishOne') {
+			return json(
+				{
+					error: 'scheduling_requires_surface_scheduler',
+					external_id: id,
+					publish_at: new Date(item.publish_at * 1_000).toISOString(),
+				},
+				409,
+			)
+		}
+		const scheduled = await content.action(
+			nativeContext(
+				ctx,
+				'POST',
+				{ publishAt: new Date(item.publish_at * 1_000).toISOString() },
+				{ id: row.content_id },
+				'?action=schedule',
+			),
+		)
+		if (!scheduled.ok) return scheduled
+	} else {
+		// Fail closed before any write: a publish needs the publication's live surfaces.
+		const surfaces = await resolveLiveSurfaces(ctx, config)
+		if (!surfaces) {
+			return json({ error: 'GL_CMS_FOUNDRY_PUBLISH_UNCONFIGURED', external_id: id }, 503)
+		}
+		// A resync keeps the original publication time; a first publish takes the
+		// requested (past) time, else now.
+		const publishedAt =
+			row.status === 'published' ? (item.published_at ?? now) : (item.publish_at ?? now)
+		// The native publish action, unchanged, with only its commit step swapped
+		// for publishOne + live surfaces: readiness, body guard, dek, tag check,
+		// activity log, takeaways, FAQ and the content.published webhook all run
+		// exactly as for an editor's publish.
+		const commit: NonNullable<ContentRouteConfig['publishCommit']> = async (_ctx, input) => {
+			const published = await publishOne(ctx.db, {
+				contentId: input.contentId,
+				now: input.now,
+				publishedAt,
+				createdBy: 'foundry',
+				surfaces,
+				...(config.foundryPublish?.requiredSurfaceNames
+					? { requiredSurfaceNames: config.foundryPublish.requiredSurfaceNames }
+					: {}),
+				packageVersion: config.foundryPublish?.packageVersion ?? null,
+			})
+			console.info('[cms] foundry article published', {
+				externalId: id,
+				attemptId: published.attemptId,
+				revisionId: published.revisionId,
+				surfaceStatus: published.surfaceStatus,
+				resync: row.status === 'published',
+			})
+		}
+		const publisher = createContentRoutes({ ...machineConfig(config), publishCommit: commit })
+		let response: Response
+		try {
+			response = await publisher.action(
+				nativeContext(ctx, 'POST', undefined, { id: row.content_id }, '?action=publish'),
+			)
+		} catch (error) {
+			return publishFailure(id, error)
+		}
+		if (!response.ok) return response
+	}
+
+	const after = await findArticle(ctx, id)
+	if (!after) return json({ error: 'write_failed' }, 500)
+	const receiptId = crypto.randomUUID()
+	await upsertReceipt(ctx, {
+		externalId: id,
+		contentId: row.content_id,
+		receiptId,
+		requestHash: row.request_sha256,
+	})
+	return json(v2Receipt({ ...after, receipt_id: receiptId }))
+}
+
 export function createFoundryPublishRoutes(
 	config: ContentRouteConfig,
 ): FoundryPublishRouteHandlers {
 	const content = createContentRoutes(machineConfig(config))
+	// A publication that declares a canonical host (statically, or on its
+	// opt-in) verifies host-bound only, with or without autoPublish; an opted-in
+	// one must declare it. Missing (when opted in), malformed or conflicting
+	// fails closed on every machine verb instead of falling back to the unbound
+	// form (the HMAC secret is shared by every site). Nothing declared and not
+	// opted in: the legacy form, byte-for-byte as before.
+	const declaration = declaredCanonicalHost(config)
+	const signingHost = declaration?.host ?? null
+	const hostUnconfigured = declaration ? declaration.host === null : autoPublishEnabled(config)
+	if (hostUnconfigured) {
+		console.error(
+			'[cms] the Foundry canonicalHost is missing (autoPublish is on), invalid, or conflicting',
+		)
+	}
+	const verify = (
+		ctx: RouteContext,
+		body: string,
+	): Promise<{ bodyHash: string } | { error: Response }> =>
+		hostUnconfigured
+			? Promise.resolve({
+					error: json(
+						{
+							error: 'GL_CMS_FOUNDRY_HOST_UNCONFIGURED',
+							detail:
+								'a declared canonicalHost must be valid and agree, and is required when autoPublish is on',
+						},
+						503,
+					),
+				})
+			: authenticate(ctx, body, signingHost)
+	// Built only for an opted-in publication: the in-place writer for a published item.
+	const publishedWriter = autoPublishEnabled(config)
+		? createContentRoutes({ ...machineConfig(config), updateStatusConstraint: 'published' })
+		: null
 
 	return {
 		async put(ctx) {
 			const id = externalId(ctx)
 			if (!id) return json({ error: 'invalid_external_id' }, 400)
 			const rawBody = await ctx.request.text()
-			const auth = await authenticate(ctx, rawBody)
+			const auth = await verify(ctx, rawBody)
 			if ('error' in auth) return auth.error
 			let payload: unknown
 			try {
@@ -233,6 +922,16 @@ export function createFoundryPublishRoutes(
 			} catch {
 				return json({ error: 'invalid_json' }, 400)
 			}
+			if (autoPublishEnabled(config) && isV2Payload(payload)) {
+				return putV2(
+					ctx,
+					config,
+					{ draft: content, published: publishedWriter ?? content },
+					id,
+					payload,
+					auth.bodyHash,
+				)
+			}
 			const parsed = PutSchema.safeParse(payload)
 			if (!parsed.success)
 				return json({ error: 'invalid_request', details: parsed.error.flatten() }, 400)
@@ -284,7 +983,7 @@ export function createFoundryPublishRoutes(
 					)
 				} catch (error) {
 					const raced = await findContentBySource(ctx, id)
-					if (!raced || raced.type !== 'article') throw error
+					if (raced?.type !== 'article') throw error
 					nativeResponse = await mapUpdateConflict(
 						await content.update(nativeContext(ctx, 'PATCH', body, { id: raced.id })),
 						id,
@@ -320,11 +1019,12 @@ export function createFoundryPublishRoutes(
 		async get(ctx) {
 			const id = externalId(ctx)
 			if (!id) return json({ error: 'invalid_external_id' }, 400)
-			const auth = await authenticate(ctx, '')
+			const auth = await verify(ctx, '')
 			if ('error' in auth) return auth.error
 			const row = await findArticle(ctx, id)
 			if (!row) return json({ error: 'not_found' }, 404)
 			console.info('[cms] foundry article read', { externalId: id, receiptId: row.receipt_id })
+			if (autoPublishEnabled(config)) return json(v2Receipt(row))
 			return json(receipt(row))
 		},
 
@@ -332,7 +1032,7 @@ export function createFoundryPublishRoutes(
 			const id = externalId(ctx)
 			if (!id) return json({ error: 'invalid_external_id' }, 400)
 			const rawBody = await ctx.request.text()
-			const auth = await authenticate(ctx, rawBody)
+			const auth = await verify(ctx, rawBody)
 			if ('error' in auth) return auth.error
 			const row = await findArticle(ctx, id)
 			if (!row) return json({ error: 'not_found' }, 404)
@@ -352,5 +1052,22 @@ export function createFoundryPublishRoutes(
 			console.info('[cms] foundry article unpublished', { externalId: id, receiptId })
 			return json(receipt(result))
 		},
+
+		async publish(ctx) {
+			const id = externalId(ctx)
+			if (!id) return json({ error: 'invalid_external_id' }, 400)
+			const rawBody = await ctx.request.text()
+			const auth = await verify(ctx, rawBody)
+			if ('error' in auth) return auth.error
+			// POST /publish takes no body: anything sent is refused, never ignored.
+			if (rawBody.length > 0 || !/^0?$/.test(ctx.request.headers.get('Content-Length') ?? '')) {
+				return json({ error: 'invalid_request', detail: 'publish takes no request body' }, 400)
+			}
+			const row = await findArticle(ctx, id)
+			if (!row) return json({ error: 'not_found' }, 404)
+			// Without the publication's opt-in the machine route stays draft-only.
+			if (!autoPublishEnabled(config)) return approvalConflict(id, row.status)
+			return publishV2(ctx, config, content, id, row)
+		},
 	}
 }