@growth-labs/cms 0.1.0

package/src/engine/webhook-signer.ts

@@ -0,0 +1,139 @@
+// webhook-signer.ts — HMAC-SHA256 signing for outbound webhook payloads (P7 Task 9).
+//
+// Security invariants (spec §12 scope guard 4):
+//   - The signing secret is NEVER stored in D1, in a row, in a log, or in a response.
+//   - The secret is read ONLY from ctx.env (a Cloudflare Secrets Store binding wired
+//     by the host at cutover). The package defines the seam; the host injects the impl.
+//   - A missing binding produces an unsigned/disabled state — never a crash, never a D1
+//     read, never an exception that propagates past the try/catch in the caller.
+//
+// Uses Web Crypto (crypto.subtle) — workerd-native, no node:crypto.
+
+import type { D1Database } from './d1.js'
+import { validateWebhookUrl } from './url-guard.js'
+import { buildWebhookEnvelope, listWebhooks, updateWebhookStatus } from './webhooks.js'
+
+// ---------------------------------------------------------------------------
+// HMAC signer (pure, testable in isolation)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign a webhook body with HMAC-SHA256 using the given secret.
+ *
+ * Returns the hex-encoded HMAC digest. Uses Web Crypto (crypto.subtle) —
+ * workerd-native, no node:crypto dependency.
+ *
+ * Called by the default dispatchWebhook impl with the secret read from ctx.env.
+ * Tests can call this directly to assert the signing behaviour.
+ */
+export async function signWebhookBody(body: string, secret: string): Promise<string> {
+	const enc = new TextEncoder()
+	const keyMaterial = await crypto.subtle.importKey(
+		'raw',
+		enc.encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign'],
+	)
+	const sig = await crypto.subtle.sign('HMAC', keyMaterial, enc.encode(body))
+	return Array.from(new Uint8Array(sig))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('')
+}
+
+// ---------------------------------------------------------------------------
+// Default dispatchWebhook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * The Cloudflare Secrets Store binding name for the webhook HMAC secret.
+ * The host wires a [[secrets_store_secrets]] binding with this name.
+ * Callers that need a custom binding name supply their own dispatchWebhook.
+ */
+export const WEBHOOK_HMAC_BINDING = 'WEBHOOK_HMAC_SECRET'
+
+/**
+ * Build the package-default dispatchWebhook implementation.
+ *
+ * The impl:
+ *   1. Loads registered webhook URLs for the workspace + eventType from D1.
+ *   2. Reads the HMAC signing secret from ctx.env[bindingName] (Secrets Store).
+ *      If the binding is absent, dispatches unsigned (no crash, no D1 read).
+ *   3. Builds the standard envelope, signs the body (if secret present), POSTs.
+ *   4. Updates last_status / last_fired_at on each webhook row.
+ *
+ * The package defines the seam; the host can override by injecting its own impl.
+ */
+export function buildDefaultDispatchWebhook(
+	db: D1Database,
+	options: { bindingName?: string } = {},
+): (
+	ctx: { env?: Record<string, unknown> },
+	payload: { eventType: string; workspaceId: string; data: unknown },
+) => Promise<void> {
+	const bindingName = options.bindingName ?? WEBHOOK_HMAC_BINDING
+
+	return async (ctx, { eventType, workspaceId, data }) => {
+		// Load registered webhooks for this workspace + event.
+		const all = await listWebhooks(db, workspaceId)
+		const matching = all.filter((w) => w.eventType === eventType)
+		if (matching.length === 0) return
+
+		// Build the envelope once; reuse for all matching webhooks.
+		const envelope = buildWebhookEnvelope({ eventType, workspaceId, data })
+		const body = JSON.stringify(envelope)
+
+		// Read the signing secret from ctx.env (Secrets Store binding only).
+		// A missing binding means we dispatch unsigned — never a crash or D1 read.
+		const secret =
+			ctx.env && typeof ctx.env[bindingName] === 'string' ? (ctx.env[bindingName] as string) : null
+
+		let signature: string | null = null
+		if (secret) {
+			try {
+				signature = await signWebhookBody(body, secret)
+			} catch {
+				// Signing failure → dispatch unsigned; never propagate.
+			}
+		}
+
+		// POST to each matching URL.
+		for (const webhook of matching) {
+			// Defense in depth: re-validate the stored URL at fire time. The route
+			// guard rejects unsafe URLs on create, but a row could predate the guard
+			// or be written out-of-band — never POST to a loopback/link-local/
+			// metadata/private/internal target. Mark the delivery 'blocked' and skip.
+			if (!validateWebhookUrl(webhook.url).ok) {
+				try {
+					await updateWebhookStatus(db, webhook.id, 'blocked')
+				} catch {
+					// Status update failure must not propagate.
+				}
+				continue
+			}
+
+			const headers: Record<string, string> = {
+				'Content-Type': 'application/json',
+				'X-Masthead-Event': eventType,
+				'X-Masthead-Delivery': envelope.id,
+			}
+			if (signature) {
+				headers['X-Masthead-Signature'] = `sha256=${signature}`
+			}
+
+			let status = 'error'
+			try {
+				const res = await fetch(webhook.url, { method: 'POST', headers, body })
+				status = String(res.status)
+			} catch {
+				status = 'error'
+			}
+
+			try {
+				await updateWebhookStatus(db, webhook.id, status)
+			} catch {
+				// Status update failure must not propagate.
+			}
+		}
+	}
+}

package/src/engine/webhooks.ts

@@ -0,0 +1,224 @@
+// webhooks.ts — CMS webhooks engine (P7 Task 8).
+//
+// Implements:
+//   WEBHOOK_EVENTS        — 12-event enum (the authoritative list)
+//   createWebhook()       — validate event type, insert row (no secret column)
+//   listWebhooks()        — list all webhooks for a workspace
+//   deleteWebhook()       — delete a webhook row by id
+//   updateWebhookStatus() — update last_status + last_fired_at after a dispatch
+//   buildWebhookEnvelope()— build the standard payload envelope
+//
+// Security invariants (spec §12 scope guard 4 + §8):
+//   - cms_webhooks has NO secret column — deliberately omitted in migration 0010.
+//   - The HMAC signing secret lives ONLY in ctx.env (Cloudflare Secrets Store
+//     binding wired by the host). No engine function reads or writes a secret to D1.
+//   - buildWebhookEnvelope is a pure function — no secret access here.
+
+import type { D1Database } from './d1.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** The 12 webhook event types (authoritative; spec §12 §Task 8). */
+export const WEBHOOK_EVENTS = [
+	'content.published',
+	'content.unpublished',
+	'content.scheduled',
+	'content.created',
+	'content.deleted',
+	'content.review',
+	'content.duplicated',
+	'video.processed',
+	'video.failed',
+	'author.created',
+	'media.uploaded',
+	'webhook.test',
+] as const
+
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number]
+
+export interface CreateWebhookInput {
+	workspaceId: string
+	eventType: string
+	url: string
+}
+
+/** A webhook registration record (no secret field). */
+export interface WebhookRecord {
+	id: string
+	workspaceId: string
+	eventType: string
+	url: string
+	lastStatus: string | null
+	lastFiredAt: number | null
+	createdAt: number
+}
+
+/** The standard outbound webhook payload envelope. */
+export interface WebhookEnvelope {
+	/** Unique id for this delivery (UUID). */
+	id: string
+	/** The event type, e.g. 'content.published'. */
+	event: string
+	/** The workspace the event originated in. */
+	workspaceId: string
+	/** Unix epoch seconds of when the event occurred. */
+	occurredAt: number
+	/** Event-specific data payload. */
+	data: unknown
+}
+
+// ---------------------------------------------------------------------------
+// createWebhook
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a new webhook for a workspace.
+ *
+ * Validates the eventType against the WEBHOOK_EVENTS enum; rejects unknown
+ * values so misconfigured hooks surface early. The row has NO secret column —
+ * the HMAC secret is read from ctx.env at dispatch time only.
+ */
+export async function createWebhook(
+	db: D1Database,
+	input: CreateWebhookInput,
+): Promise<WebhookRecord> {
+	const validEvents: ReadonlySet<string> = new Set(WEBHOOK_EVENTS)
+	if (!validEvents.has(input.eventType)) {
+		throw new Error(
+			`Invalid event type: '${input.eventType}'. Must be one of: ${WEBHOOK_EVENTS.join(', ')}`,
+		)
+	}
+
+	const id = crypto.randomUUID()
+	const now = Math.floor(Date.now() / 1000)
+
+	await db
+		.prepare(
+			`INSERT INTO cms_webhooks (id, workspace_id, event_type, url, created_at)
+			 VALUES (?, ?, ?, ?, ?)`,
+		)
+		.bind(id, input.workspaceId, input.eventType, input.url, now)
+		.run()
+
+	return {
+		id,
+		workspaceId: input.workspaceId,
+		eventType: input.eventType,
+		url: input.url,
+		lastStatus: null,
+		lastFiredAt: null,
+		createdAt: now,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// listWebhooks
+// ---------------------------------------------------------------------------
+
+/**
+ * List all webhooks registered for a workspace.
+ * Ordered by created_at ASC (deterministic).
+ */
+export async function listWebhooks(db: D1Database, workspaceId: string): Promise<WebhookRecord[]> {
+	const result = await db
+		.prepare(
+			`SELECT id, workspace_id, event_type, url, last_status, last_fired_at, created_at
+			 FROM cms_webhooks
+			 WHERE workspace_id = ?
+			 ORDER BY created_at ASC`,
+		)
+		.bind(workspaceId)
+		.all<{
+			id: string
+			workspace_id: string
+			event_type: string
+			url: string
+			last_status: string | null
+			last_fired_at: number | null
+			created_at: number
+		}>()
+
+	return (result.results ?? []).map((row) => ({
+		id: row.id,
+		workspaceId: row.workspace_id,
+		eventType: row.event_type,
+		url: row.url,
+		lastStatus: row.last_status,
+		lastFiredAt: row.last_fired_at,
+		createdAt: row.created_at,
+	}))
+}
+
+// ---------------------------------------------------------------------------
+// deleteWebhook
+// ---------------------------------------------------------------------------
+
+/**
+ * Delete a webhook registration by its id, SCOPED to the caller's workspace.
+ *
+ * The workspaceId is resolved from the authenticated caller (auth/locals) and
+ * MUST be passed by the route — never trusted from the client. Scoping the
+ * DELETE by workspace_id closes a cross-workspace IDOR: a member of workspace A
+ * cannot delete workspace B's webhook by id.
+ *
+ * No-ops for non-existent / out-of-workspace ids (idempotent).
+ */
+export async function deleteWebhook(
+	db: D1Database,
+	id: string,
+	workspaceId: string,
+): Promise<void> {
+	await db
+		.prepare(`DELETE FROM cms_webhooks WHERE id = ? AND workspace_id = ?`)
+		.bind(id, workspaceId)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// updateWebhookStatus
+// ---------------------------------------------------------------------------
+
+/**
+ * Update the last_status and last_fired_at on a webhook row.
+ * Called after a dispatch attempt (success or failure) to record the result.
+ */
+export async function updateWebhookStatus(
+	db: D1Database,
+	id: string,
+	status: string,
+): Promise<void> {
+	const now = Math.floor(Date.now() / 1000)
+	await db
+		.prepare(`UPDATE cms_webhooks SET last_status = ?, last_fired_at = ? WHERE id = ?`)
+		.bind(status, now, id)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// buildWebhookEnvelope
+// ---------------------------------------------------------------------------
+
+/** Input for building a standard webhook payload envelope. */
+export interface BuildWebhookEnvelopeInput {
+	eventType: string
+	workspaceId: string
+	data: unknown
+}
+
+/**
+ * Build the standard outbound webhook payload envelope.
+ *
+ * Pure function — no D1 access, no secret access.
+ * Format: { id, event, workspaceId, occurredAt, data }
+ */
+export function buildWebhookEnvelope(input: BuildWebhookEnvelopeInput): WebhookEnvelope {
+	return {
+		id: crypto.randomUUID(),
+		event: input.eventType,
+		workspaceId: input.workspaceId,
+		occurredAt: Math.floor(Date.now() / 1000),
+		data: input.data,
+	}
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+// @growth-labs/cms — the reusable Fronts-proven publishing/admin engine, as a
+// package (NOT a shared engine). See docs/reference/cms-reuse-decision.md.
+//
+// This package ships the D1 schema contract (the 11-table
+// content/revision/media/authors/foundry-callback set) + its TypeScript row
+// types (WS7-04/06 foundation) AND the publishing engine — the content
+// data-access core (WS7-05):
+//
+//   WS7-05 (this release) — the publishing engine: publisher.ts core
+//            (createContent, updateContentItem, scheduleContent,
+//            publishContent, unpublishContent, duplicateContentItem,
+//            createRevision, getContentSnapshot,
+//            setContentTags/setContentRelations, ensureUniqueSlug, countWords,
+//            estimateReadTime, validation guards) + its validators / sanitize /
+//            slug helpers + publisher-cron. Every function takes an injected
+//            D1Database (the site supplies its own binding); NO Fronts imports
+//            remain. Carries the INSERT…SELECT duplicateContentItem
+//            column-alignment gotcha (inventory §6) — the column lists are
+//            ported verbatim against this schema or a duplicate silently drops
+//            fields.
+//   WS7-07 (this release) — the API routes: the /api/v1/publisher/*
+//            content/authors/media/cron handlers, as framework-agnostic
+//            mountable factories with auth/authz INJECTED. Available at the
+//            `@growth-labs/cms/routes` subpath (kept off the root so the
+//            engine/schema imports stay zod-free). The Foundry media-dispatch
+//            routes (dispatch-video + callback) + their state-machine glue land
+//            in bead 08 (gated on OD-CMS7); the article-takeaways publish
+//            dispatch is exposed as an OPTIONAL injected hook so the package
+//            carries no Foundry/Hermes coupling.
+
+// The publishing engine — the content data-access core (WS7-05). Also
+// available at the `@growth-labs/cms/engine` subpath.
+export * from './engine/index.js'
+
+// Injected-provider interfaces + null implementations (spec §3.3).
+export * from './providers/index.js'
+
+// Route-layer user types (exported at root for convenience; full routes surface at @growth-labs/cms/routes).
+export type { CmsUser } from './routes/context.js'
+
+export {
+	type ArticleContentRow,
+	type AuthorRow,
+	applyMigrations,
+	// migration contract
+	CMS_MIGRATION_SQL,
+	CMS_MIGRATIONS_0002_PLUS,
+	// table contract
+	CMS_TABLES,
+	type CmsActivityLogRow,
+	type CmsApiKeyRow,
+	type CmsNotificationRow,
+	type CmsRole,
+	type CmsTableName,
+	type CmsWebhookRow,
+	type ContentContributorRow,
+	type ContentImportRow,
+	type ContentItemRow,
+	type ContentRelationRow,
+	type ContentRevisionRow,
+	type ContentSlugRedirectRow,
+	type ContentStatus,
+	type ContentTagLinkRow,
+	type ContentTagRow,
+	// row + domain types
+	type ContentType,
+	type ContentVisibility,
+	type FoundryCallbackEventRow,
+	type MastheadUserRow,
+	type MediaAssetRow,
+	NON_CMS_TABLES,
+	type PodcastContentRow,
+	splitStatements,
+	type VideoContentRow,
+	type VideoProcessingState,
+	type WorkspaceInviteRow,
+	type WorkspaceMembershipRow,
+	type WorkspaceSettingsRow,
+} from './schema/index.js'