@growth-labs/cms 0.5.30 → 0.5.31

package/src/routes/fronts-publish.ts

@@ -0,0 +1,292 @@
+// Fronts publish routes (cms/Masthead side) — the two machine-to-machine seams
+// the out-of-process Fronts publish worker (foundryd) drives:
+//
+//   GET  /admin/api/fronts/schedule?window=<from>..<to>  — the poll surface.
+//   POST /admin/api/fronts/publish-callback              — the callback receiver.
+//
+// AUTH reuses the existing M2M primitive (`verifyHmac` + `X-Foundry-Signature`
+// against `ctx.env.FOUNDRY_HMAC_SECRET` — a per-Worker secret string OR a Secrets
+// Store binding `{ get() }`; no new auth scheme, no shared secret in code/D1),
+// hardened against replay with a REQUIRED `X-Foundry-Timestamp`:
+//
+//   X-Foundry-Timestamp: <unix seconds, within ±300s of now>
+//   X-Foundry-Signature: sha256=HMAC(secret, `${timestamp}\n${payload}`)
+//
+// where payload is the raw query string (`url.search`) for the GET poll and the
+// raw body for the POST callback. Binding the signature to a fresh timestamp
+// stops replay: without it a no-`window` GET would sign HMAC(secret,"") — a
+// CONSTANT — so one captured URL+header pair would be a permanent bearer
+// credential for the pre-publication embargo schedule.
+//
+// Both endpoints ship ENABLED behind FRONTS_PUBLISH_ENABLED (a rollback lever,
+// default ON). Failures are loud: bad/stale HMAC → 401 + warn log; a `live`
+// callback that cannot commit through the ledger → 500 + error log; disabled → 503.
+
+import { z } from 'zod'
+import { verifyHmac } from '../engine/foundry-dispatch.js'
+import {
+	applyFrontsPublishCallback,
+	isFrontsPublishEnabled,
+	listFrontsPublishSchedule,
+} from '../engine/fronts-publish.js'
+import { hydrateFrontsPublishIntents } from '../engine/fronts-publish-intent.js'
+import { publicUrlFor } from '../ui/screens/public-url.js'
+import { type CmsRouteConfig, resolveConfig } from './config.js'
+import { json, type RouteContext } from './context.js'
+
+/**
+ * Resolve the Foundry HMAC secret from ctx.env.FOUNDRY_HMAC_SECRET — the SAME
+ * binding the existing foundry-callback route uses. Supports a plain string
+ * (test injection / per-Worker secret) or a Secrets Store binding `{ get() }`.
+ * Returns null → the route answers 500 "not configured".
+ */
+async function resolveFoundryHmacSecret(
+	env: Record<string, unknown> | undefined,
+): Promise<string | null> {
+	const raw = env?.FOUNDRY_HMAC_SECRET
+	if (typeof raw === 'string') return raw || null
+	if (raw && typeof (raw as { get?: unknown }).get === 'function') {
+		try {
+			const val = await (raw as { get(): Promise<string> }).get()
+			return typeof val === 'string' && val.length > 0 ? val : null
+		} catch {
+			return null
+		}
+	}
+	return null
+}
+
+/** Max clock skew (seconds) tolerated on X-Foundry-Timestamp — the replay window. */
+const SIGNATURE_MAX_SKEW_SECONDS = 300
+
+/** Parse the X-Foundry-Timestamp header (strict unix epoch seconds) or null. */
+function parseTimestampSeconds(raw: string): number | null {
+	const trimmed = raw.trim()
+	// Strict integer seconds so the exact header bytes are what foundryd signs.
+	if (!/^\d{1,15}$/.test(trimmed)) return null
+	const seconds = Number.parseInt(trimmed, 10)
+	return Number.isSafeInteger(seconds) ? seconds : null
+}
+
+/**
+ * Verify a foundryd-signed M2M request: a fresh `X-Foundry-Timestamp` (unix
+ * seconds within ±{@link SIGNATURE_MAX_SKEW_SECONDS}) plus `X-Foundry-Signature`
+ * = HMAC over `${timestamp}\n${payload}`. Returns null when authentic, or a 401
+ * Response (with a loud warn log) to short-circuit the handler.
+ */
+async function verifyFoundrySignedRequest(
+	request: Request,
+	secret: string,
+	payload: string,
+	label: string,
+): Promise<Response | null> {
+	const tsRaw = (request.headers.get('X-Foundry-Timestamp') ?? '').trim()
+	const ts = parseTimestampSeconds(tsRaw)
+	if (ts === null) {
+		console.warn(`[cms] ${label} rejected: missing or invalid X-Foundry-Timestamp`)
+		return json({ error: 'Missing or invalid X-Foundry-Timestamp' }, 401)
+	}
+	const now = Math.floor(Date.now() / 1_000)
+	if (Math.abs(now - ts) > SIGNATURE_MAX_SKEW_SECONDS) {
+		console.warn(`[cms] ${label} rejected: stale X-Foundry-Timestamp (skew ${now - ts}s)`)
+		return json({ error: 'Stale or future X-Foundry-Timestamp' }, 401)
+	}
+	const signature = request.headers.get('X-Foundry-Signature') ?? ''
+	const valid = await verifyHmac(secret, `${tsRaw}\n${payload}`, signature)
+	if (!valid) {
+		console.warn(`[cms] ${label} rejected: invalid X-Foundry-Signature`)
+		return json({ error: 'Invalid signature' }, 401)
+	}
+	return null
+}
+
+const ReceiptSchema = z.object({
+	published_urls: z.array(z.string()).nullish(),
+	platform_post_ids: z.array(z.string()).nullish(),
+	sha256: z.string().nullish(),
+})
+
+const CallbackSchema = z
+	.object({
+		event_id: z.string().min(1).optional(),
+		intent_id: z.string().min(1).nullish(),
+		content_id: z.string().min(1),
+		version: z.number().int().nullish(),
+		correlation_id: z.string().min(1).nullish(),
+		status: z.enum(['queued', 'publishing', 'live', 'late', 'failed']),
+		occurred_at: z.union([z.string(), z.number()]).nullish(),
+		receipt: ReceiptSchema.nullish(),
+		error: z.string().nullish(),
+	})
+	.strip()
+
+export interface FrontsPublishRouteHandlers {
+	/** GET /fronts/schedule?window=<from>..<to> — items due for foundryd to publish. */
+	schedule(ctx: RouteContext): Promise<Response>
+	/** POST /fronts/publish-callback — foundryd's outbound lifecycle callback. */
+	publishCallback(ctx: RouteContext): Promise<Response>
+}
+
+/** Parse `window=<from>..<to>` into unix-seconds bounds; defaults to now..now+1h. */
+function parseWindow(
+	value: string | null,
+	nowSeconds: number,
+): { fromSeconds: number; toSeconds: number } | { error: string } {
+	if (!value) return { fromSeconds: nowSeconds, toSeconds: nowSeconds + 3600 }
+	const parts = value.split('..')
+	if (parts.length !== 2) return { error: 'window must be "<from>..<to>"' }
+	const parseBound = (raw: string): number | null => {
+		const trimmed = raw.trim()
+		if (!trimmed) return null
+		if (/^\d+$/.test(trimmed)) return Number.parseInt(trimmed, 10)
+		const ms = Date.parse(trimmed)
+		return Number.isNaN(ms) ? null : Math.floor(ms / 1_000)
+	}
+	const fromSeconds = parseBound(parts[0])
+	const toSeconds = parseBound(parts[1])
+	if (fromSeconds === null || toSeconds === null) {
+		return { error: 'window bounds must be ISO-8601 timestamps or unix seconds' }
+	}
+	if (toSeconds < fromSeconds) return { error: 'window end precedes its start' }
+	return { fromSeconds, toSeconds }
+}
+
+export function createFrontsPublishRoutes(config: CmsRouteConfig): FrontsPublishRouteHandlers {
+	const resolved = resolveConfig(config)
+	return {
+		async schedule(ctx) {
+			const hmacSecret = await resolveFoundryHmacSecret(ctx.env)
+			if (!hmacSecret) return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
+
+			const url = new URL(ctx.request.url)
+			// The GET poll has no body; the payload is the exact query string
+			// foundryd sent (leading '?' included, or '' when empty), bound to the
+			// required timestamp so an empty-window poll can't sign a constant.
+			const denied = await verifyFoundrySignedRequest(
+				ctx.request,
+				hmacSecret,
+				url.search,
+				'fronts/schedule',
+			)
+			if (denied) return denied
+
+			if (!isFrontsPublishEnabled(ctx.env)) {
+				return json({ error: 'fronts_publish_disabled' }, 503)
+			}
+
+			const now = Math.floor(Date.now() / 1_000)
+			const window = parseWindow(url.searchParams.get('window'), now)
+			if ('error' in window) return json({ error: window.error }, 400)
+
+			// `items` is the UNCHANGED 0026 legacy schedule shape — an existing
+			// consumer keeps working byte-for-byte. `intents` is the canonical
+			// publish-intent contract (packages#500) hydrated over the SAME due
+			// predicate, and `incomplete` names every due item that cannot form a
+			// complete intent, so a missing canonical field is an explicit, visible
+			// contract error rather than a silently short `intents` array.
+			const items = await listFrontsPublishSchedule(ctx.db, {
+				toSeconds: window.toSeconds,
+				nowSeconds: now,
+			})
+			const hydrated = await hydrateFrontsPublishIntents(ctx.db, {
+				toSeconds: window.toSeconds,
+				nowSeconds: now,
+				mediaPublicDomain: resolved.mediaPublicDomain,
+				// Site-RELATIVE paths: the CMS does not know the site origin, and the
+				// consumer joins its own trusted configured origin. A host-supplied
+				// origin is deliberately deferred (packages-docs/cms.md).
+				resolveContentUrl: (row) => publicUrlFor(row),
+			})
+			return json({
+				ok: true,
+				now,
+				window: { from: window.fromSeconds, to: window.toSeconds },
+				count: items.length,
+				items,
+				intents: hydrated.intents,
+				incomplete: hydrated.incomplete,
+			})
+		},
+
+		async publishCallback(ctx) {
+			const hmacSecret = await resolveFoundryHmacSecret(ctx.env)
+			if (!hmacSecret) return json({ error: 'FOUNDRY_HMAC_SECRET is not configured' }, 500)
+
+			let rawBody: string
+			try {
+				rawBody = await ctx.request.text()
+			} catch {
+				return json({ error: 'Failed to read request body' }, 400)
+			}
+
+			const denied = await verifyFoundrySignedRequest(
+				ctx.request,
+				hmacSecret,
+				rawBody,
+				'fronts/publish-callback',
+			)
+			if (denied) return denied
+
+			if (!isFrontsPublishEnabled(ctx.env)) {
+				return json({ error: 'fronts_publish_disabled' }, 503)
+			}
+
+			let raw: unknown
+			try {
+				raw = JSON.parse(rawBody)
+			} catch {
+				return json({ error: 'Invalid JSON body' }, 400)
+			}
+			const parsed = CallbackSchema.safeParse(raw)
+			if (!parsed.success) {
+				return json({ error: 'Invalid payload', details: parsed.error.flatten() }, 400)
+			}
+
+			// Idempotency key: body event_id, else the Idempotency-Key header.
+			const eventId = parsed.data.event_id ?? ctx.request.headers.get('Idempotency-Key') ?? null
+			if (!eventId) {
+				return json({ error: 'Missing event_id / Idempotency-Key' }, 400)
+			}
+
+			const result = await applyFrontsPublishCallback(ctx.db, {
+				eventId,
+				intentId: parsed.data.intent_id ?? null,
+				contentId: parsed.data.content_id,
+				version: parsed.data.version ?? null,
+				correlationId: parsed.data.correlation_id ?? null,
+				status: parsed.data.status,
+				occurredAt: parsed.data.occurred_at ?? null,
+				receipt: parsed.data.receipt ?? null,
+				error: parsed.data.error ?? null,
+			})
+
+			if (!result.contentFound) {
+				return json({ error: 'content_not_found', contentId: parsed.data.content_id }, 404)
+			}
+			if (result.ledgerError) {
+				// A confirmed `live` that could not be committed through the ledger is a
+				// hard, loud failure — never a silent zero.
+				console.error(
+					`[cms] fronts/publish-callback ledger commit failed for content ${parsed.data.content_id}: ${result.ledgerError}`,
+				)
+				return json(
+					{
+						ok: false,
+						error: 'ledger_publish_failed',
+						detail: result.ledgerError,
+						status: result.status,
+					},
+					500,
+				)
+			}
+
+			return json({
+				ok: true,
+				deduped: result.deduped,
+				status: result.status,
+				published: result.published,
+				attemptId: result.attemptId,
+			})
+		},
+	}
+}

package/src/routes/index.ts

@@ -100,6 +100,11 @@ export {
 	type DashboardRouteConfig,
 	type DashboardRouteHandlers,
 } from './dashboard.js'
+// Fronts publish surface — the HMAC schedule poll + publish-callback receiver.
+export {
+	createFrontsPublishRoutes,
+	type FrontsPublishRouteHandlers,
+} from './fronts-publish.js'
 // Import routes — two-step parse→confirm pipeline.
 export { createImportRoutes, type ImportRouteHandlers } from './imports.js'
 // Media routes.
@@ -198,6 +203,7 @@ import {
 } from './content-insights.js'
 import { type CronRouteHandlers, createCronRoutes } from './cron.js'
 import { createDashboardRoutes, type DashboardRouteHandlers } from './dashboard.js'
+import { createFrontsPublishRoutes, type FrontsPublishRouteHandlers } from './fronts-publish.js'
 import { createImportRoutes, type ImportRouteHandlers } from './imports.js'
 import { createMediaRoutes, type MediaRouteHandlers } from './media.js'
 import { createPreviewRoutes, type PreviewRouteHandlers } from './preview.js'
@@ -231,6 +237,7 @@ export interface CmsRoutes {
 	apiKeys: ApiKeyRouteHandlers
 	webhooks: WebhookRouteHandlers
 	contentInsights: ContentInsightsRouteHandlers
+	frontsPublish: FrontsPublishRouteHandlers
 }
 
 /**
@@ -297,5 +304,6 @@ export function createCmsRoutes(
 			authz: config.authz,
 			activeWorkspaceId: config.activeWorkspaceId,
 		}),
+		frontsPublish: createFrontsPublishRoutes(base),
 	}
 }

package/src/schema/migrations.ts

@@ -841,6 +841,42 @@ ALTER TABLE article_content
   ADD COLUMN layout_json TEXT;
 	`,
 	},
+	{
+		id: '0026_fronts_publish',
+		sql: `
+ALTER TABLE content_items
+  ADD COLUMN fronts_publish_status TEXT
+  CHECK (fronts_publish_status IS NULL OR fronts_publish_status IN ('queued','publishing','live','late','failed'));
+CREATE TABLE fronts_publish_events (
+  event_id TEXT PRIMARY KEY,
+  intent_id TEXT,
+  content_id TEXT NOT NULL,
+  version INTEGER,
+  correlation_id TEXT,
+  status TEXT NOT NULL CHECK (status IN ('queued','publishing','live','late','failed')),
+  occurred_at INTEGER,
+  receipt_json TEXT,
+  error TEXT,
+  published INTEGER NOT NULL DEFAULT 0,
+  attempt_id TEXT,
+  received_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  FOREIGN KEY (content_id) REFERENCES content_items(id) ON DELETE CASCADE
+);
+CREATE INDEX idx_fronts_publish_events_content ON fronts_publish_events(content_id, received_at DESC);
+CREATE INDEX idx_fronts_publish_events_intent ON fronts_publish_events(intent_id);
+	`,
+	},
+	{
+		id: '0027_fronts_publish_intent',
+		sql: `
+ALTER TABLE content_items
+  ADD COLUMN canonical_version INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE content_items
+  ADD COLUMN fronts_channel_targets TEXT;
+ALTER TABLE content_items
+  ADD COLUMN fronts_publish_trigger_token TEXT;
+	`,
+	},
 ]
 
 /**

package/src/schema/tables.ts

@@ -43,6 +43,8 @@ export const CMS_TABLES = [
 	'content_insights',
 	'content_insight_runs',
 	'content_insight_dismissals',
+	// Fronts publish-callback receiver log (migration 0026)
+	'fronts_publish_events',
 ] as const
 
 export type CmsTableName = (typeof CMS_TABLES)[number]

package/src/schema/types.ts

@@ -20,6 +20,18 @@ export type ContentStatus = 'draft' | 'scheduled' | 'review' | 'published' | 'ar
 /** content_items.visibility CHECK domain. */
 export type ContentVisibility = 'free' | 'premium'
 
+/**
+ * content_items.fronts_publish_status CHECK domain (migration 0026).
+ *
+ * The lifecycle of an item handed to the out-of-process Fronts publish worker
+ * (foundryd): it acknowledges the intent (`queued`), begins pushing to the
+ * external surfaces (`publishing`), confirms every surface is live (`live`),
+ * misses its target window (`late`), or gives up (`failed`). Only `live` (with a
+ * receipt) flips the item to `published`. NULL means the item was never routed
+ * through the additive Fronts publish path (the untouched D1 cron path owns it).
+ */
+export type FrontsPublishStatus = 'queued' | 'publishing' | 'live' | 'late' | 'failed'
+
 /** video_content.processing_state CHECK domain (bead 08 state machine). */
 export type VideoProcessingState =
 	| 'pending'
@@ -76,6 +88,55 @@ export interface ContentItemRow {
 	metadata_json: string
 	/** Optional namespaced source key used for idempotent archive imports (migration 0020). */
 	source_id: string | null
+	/**
+	 * Lifecycle marker for the additive out-of-process Fronts publish path
+	 * (migration 0026). NULL for items the legacy D1 cron path owns.
+	 */
+	fronts_publish_status: FrontsPublishStatus | null
+	/**
+	 * Monotonic integer revision of this item's canonical content (migration
+	 * 0027). 1 on create; advanced by `updateContentItem` only. This is the
+	 * `version` component of `intent_id = masthead:<content_id>:<version>`, so it
+	 * is deliberately NOT advanced by `fronts_publish_status` marker writes or by
+	 * a schedule poll.
+	 */
+	canonical_version: number
+	/**
+	 * JSON array of Fronts publish target slugs (migration 0027), or NULL when
+	 * the item has not been armed for the out-of-process publish path. NULL is a
+	 * loud hydration error, never an empty target list. Distinct from `channel`,
+	 * which is the single editorial Fronts channel slug.
+	 */
+	fronts_channel_targets: string | null
+	/**
+	 * Raw CMS-owned per-item publish trigger token (migration 0027), secret at
+	 * rest like `video_content.processing_trigger_token`. Never leaves the
+	 * package: the publish-intent contract exposes only `sha256:<hex>` of it.
+	 */
+	fronts_publish_trigger_token: string | null
+}
+
+/**
+ * Durable receiver log for foundryd's outbound publish callbacks (migration
+ * 0026). One row per `event_id` — the idempotency key. `receipt_json` stores the
+ * platform receipt (published_urls / platform_post_ids / sha256); `attempt_id`
+ * links to the `content_publication_attempts` 2PC ledger row when a confirmed
+ * `live` callback drove the publish.
+ */
+export interface FrontsPublishEventRow {
+	event_id: string
+	intent_id: string | null
+	content_id: string
+	version: number | null
+	correlation_id: string | null
+	status: FrontsPublishStatus
+	occurred_at: number | null
+	receipt_json: string | null
+	error: string | null
+	/** 1 when this callback flipped (or confirmed) the item to published. */
+	published: number
+	attempt_id: string | null
+	received_at: number
 }
 
 /** Standalone topic taxonomy row. Counts are derived from content_items.primary_topic. */

package/src/ui/api/fronts/publish-callback.ts

@@ -0,0 +1,18 @@
+// src/ui/api/fronts/publish-callback.ts
+// POST /admin/api/fronts/publish-callback — receiver for foundryd's outbound
+// publish-lifecycle callbacks. Idempotent by event_id / Idempotency-Key. On a
+// confirmed `live` (with a receipt) it drives the item to published through the
+// content_publication_attempts 2PC ledger. HMAC-SHA256 (X-Foundry-Signature vs
+// env.FOUNDRY_HMAC_SECRET) only — NOT behind requirePublisher.
+import type { APIContext } from 'astro'
+import type { RouteContext } from '../../../routes/context.js'
+import { createFrontsPublishRoutes } from '../../../routes/fronts-publish.js'
+import { buildSiteAuthz } from '../_authz.js'
+
+function toCtx(c: APIContext): RouteContext {
+	const env = (c.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
+	return { request: c.request, params: {}, db: env.SITE_DB as RouteContext['db'], env }
+}
+
+export const POST = (c: APIContext) =>
+	createFrontsPublishRoutes({ authz: buildSiteAuthz(c) }).publishCallback(toCtx(c))

package/src/ui/api/fronts/schedule.ts

@@ -0,0 +1,18 @@
+// src/ui/api/fronts/schedule.ts
+// GET /admin/api/fronts/schedule?window=<from>..<to> — the machine-to-machine
+// poll surface for the out-of-process Fronts publish worker (foundryd). Returns
+// `scheduled` items due for publishing. HMAC-SHA256 (X-Foundry-Signature vs
+// env.FOUNDRY_HMAC_SECRET) only — NOT behind requirePublisher. Sibling of the
+// content foundry-callback / insights-ingest M2M routes.
+import type { APIContext } from 'astro'
+import type { RouteContext } from '../../../routes/context.js'
+import { createFrontsPublishRoutes } from '../../../routes/fronts-publish.js'
+import { buildSiteAuthz } from '../_authz.js'
+
+function toCtx(c: APIContext): RouteContext {
+	const env = (c.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
+	return { request: c.request, params: {}, db: env.SITE_DB as RouteContext['db'], env }
+}
+
+export const GET = (c: APIContext) =>
+	createFrontsPublishRoutes({ authz: buildSiteAuthz(c) }).schedule(toCtx(c))