@growth-labs/cms 0.1.0

package/src/routes/webhooks.ts

@@ -0,0 +1,233 @@
+// webhooks.ts — Webhook route factories (P7 Task 8).
+//
+// Routes:
+//   POST   /settings/webhooks           create (validate event type, no secret stored)
+//   GET    /settings/webhooks           list
+//   DELETE /settings/webhooks/:id       delete
+//   POST   /settings/webhooks/:id/test  test (fires webhook.test envelope via dispatchWebhook hook)
+//
+// All routes gated on requireRole('manage_webhooks') — owner + senior_editor only.
+//
+// Security: the HMAC signing secret is NEVER stored in D1. It is read from
+// ctx.env (a Cloudflare Secrets Store binding) by the injected dispatchWebhook
+// hook. This file and the engine have no access to the secret.
+
+import { validateWebhookUrl } from '../engine/url-guard.js'
+import {
+	buildWebhookEnvelope,
+	createWebhook,
+	deleteWebhook,
+	listWebhooks,
+	updateWebhookStatus,
+	type WebhookRecord,
+} from '../engine/webhooks.js'
+import type { Authz, Capability, RouteContext } from './context.js'
+import { json } from './context.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional injected hook to dispatch a webhook payload to registered URLs.
+ * The hook is responsible for:
+ *   1. Loading the webhook URL for the given workspaceId + eventType.
+ *   2. Signing the body with HMAC-SHA256 using the secret from ctx.env.
+ *   3. POSTing to the webhook URL.
+ *   4. Calling updateWebhookStatus to record the result.
+ *
+ * The package defines the seam; the host injects the impl at cutover.
+ * A missing hook is gracefully treated as a no-op (the route still succeeds).
+ */
+export type DispatchWebhookHook = (
+	ctx: RouteContext,
+	payload: {
+		eventType: string
+		workspaceId: string
+		data: unknown
+	},
+) => Promise<void>
+
+export interface WebhookRouteConfig {
+	authz: Authz
+	workspaceId: string
+	/** Optional injected dispatch hook. Omit to disable actual dispatch. */
+	dispatchWebhook?: DispatchWebhookHook
+}
+
+export interface WebhookRouteHandlers {
+	create(ctx: RouteContext): Promise<Response>
+	list(ctx: RouteContext): Promise<Response>
+	delete(ctx: RouteContext): Promise<Response>
+	test(ctx: RouteContext): Promise<Response>
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createWebhookRoutes(config: WebhookRouteConfig): WebhookRouteHandlers {
+	function requireWorkspace(): Response | null {
+		if (!config.workspaceId) {
+			return json(
+				{ error: 'Configuration error: workspaceId is required for webhook routes.' },
+				500,
+			)
+		}
+		return null
+	}
+
+	async function gate(ctx: RouteContext): Promise<Response | null> {
+		if (config.authz.requireRole) {
+			return config.authz.requireRole('manage_webhooks' satisfies Capability, ctx)
+		}
+		return null
+	}
+
+	return {
+		// -----------------------------------------------------------------------
+		// POST /settings/webhooks
+		// Registers a new webhook. Validates the eventType against the 12-event
+		// enum. The row has NO secret column — the HMAC secret lives in ctx.env.
+		// -----------------------------------------------------------------------
+		async create(ctx: RouteContext): Promise<Response> {
+			const wsErr = requireWorkspace()
+			if (wsErr) return wsErr
+			const denied = await gate(ctx)
+			if (denied) return denied
+
+			let body: unknown
+			try {
+				body = await ctx.request.json()
+			} catch {
+				return json({ error: 'Invalid JSON' }, 400)
+			}
+
+			const b = body as Record<string, unknown>
+			const eventType = b?.eventType
+			const url = b?.url
+
+			if (!eventType || typeof eventType !== 'string' || !eventType.trim()) {
+				return json({ error: 'eventType is required' }, 400)
+			}
+			if (!url || typeof url !== 'string' || !url.trim()) {
+				return json({ error: 'url is required' }, 400)
+			}
+
+			// SSRF guard — reject loopback/link-local/metadata/private/internal targets
+			// and non-https schemes BEFORE persisting (defense-in-depth re-checked at
+			// fire time). See engine/url-guard.ts for the policy.
+			const urlCheck = validateWebhookUrl(url.trim())
+			if (!urlCheck.ok) {
+				return json({ error: `Invalid webhook url: ${urlCheck.reason}` }, 400)
+			}
+
+			let webhook: WebhookRecord
+			try {
+				webhook = await createWebhook(ctx.db, {
+					workspaceId: config.workspaceId,
+					eventType: eventType.trim(),
+					url: url.trim(),
+				})
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err)
+				if (message.toLowerCase().includes('invalid event')) {
+					return json({ error: message }, 400)
+				}
+				throw err
+			}
+
+			return json(
+				{
+					id: webhook.id,
+					workspaceId: webhook.workspaceId,
+					eventType: webhook.eventType,
+					url: webhook.url,
+					lastStatus: webhook.lastStatus,
+					lastFiredAt: webhook.lastFiredAt,
+					createdAt: webhook.createdAt,
+				},
+				201,
+			)
+		},
+
+		// -----------------------------------------------------------------------
+		// GET /settings/webhooks
+		// Returns the list of registered webhooks for the workspace.
+		// -----------------------------------------------------------------------
+		async list(ctx: RouteContext): Promise<Response> {
+			const wsErr = requireWorkspace()
+			if (wsErr) return wsErr
+			const denied = await gate(ctx)
+			if (denied) return denied
+
+			const webhooks = await listWebhooks(ctx.db, config.workspaceId)
+			return json({ webhooks })
+		},
+
+		// -----------------------------------------------------------------------
+		// DELETE /settings/webhooks/:id
+		// Deletes a webhook registration.
+		// -----------------------------------------------------------------------
+		async delete(ctx: RouteContext): Promise<Response> {
+			const wsErr = requireWorkspace()
+			if (wsErr) return wsErr
+			const denied = await gate(ctx)
+			if (denied) return denied
+
+			const id = ctx.params.id
+			if (!id) return json({ error: 'Missing id' }, 400)
+
+			// Scope the delete to the authenticated caller's workspace (resolved
+			// from config, never the client) — closes a cross-workspace IDOR.
+			await deleteWebhook(ctx.db, id, config.workspaceId)
+			return json({ ok: true, id })
+		},
+
+		// -----------------------------------------------------------------------
+		// POST /settings/webhooks/:id/test
+		// Fires a webhook.test envelope through the injected dispatchWebhook hook.
+		// Records last_status = 'test'. Returns 200 even when no hook is injected
+		// (graceful no-op — mirrors the dispatchTakeaways pattern).
+		// -----------------------------------------------------------------------
+		async test(ctx: RouteContext): Promise<Response> {
+			const wsErr = requireWorkspace()
+			if (wsErr) return wsErr
+			const denied = await gate(ctx)
+			if (denied) return denied
+
+			const id = ctx.params.id
+			if (!id) return json({ error: 'Missing id' }, 400)
+
+			// Verify the webhook exists before dispatching
+			const rows = await listWebhooks(ctx.db, config.workspaceId)
+			const webhook = rows.find((w) => w.id === id)
+			if (!webhook) return json({ error: 'Webhook not found' }, 404)
+
+			const envelope = buildWebhookEnvelope({
+				eventType: 'webhook.test',
+				workspaceId: config.workspaceId,
+				data: { webhookId: id, url: webhook.url },
+			})
+
+			// Fire the hook if injected; gracefully skip if absent (no 501).
+			if (config.dispatchWebhook) {
+				try {
+					await config.dispatchWebhook(ctx, {
+						eventType: envelope.event,
+						workspaceId: envelope.workspaceId,
+						data: envelope.data,
+					})
+				} catch (err) {
+					// Dispatch failure must NOT fail the route — same pattern as dispatchTakeaways.
+					console.error('[cms] dispatchWebhook test error:', err)
+				}
+			}
+
+			// Record the test attempt
+			await updateWebhookStatus(ctx.db, id, 'test')
+
+			return json({ ok: true, id, envelopeId: envelope.id })
+		},
+	}
+}

package/src/schema/index.ts

@@ -0,0 +1,45 @@
+// Public surface of the CMS schema contract: the table list, the row types, and
+// the migration SQL + apply helper. The publishing engine (publisher.ts) is
+// ported in WS7-05 and will build on these types.
+
+export {
+	applyMigrations,
+	CMS_MIGRATION_SQL,
+	CMS_MIGRATIONS_0002_PLUS,
+	splitStatements,
+} from './migrations.js'
+export {
+	CMS_TABLES,
+	type CmsTableName,
+	NON_CMS_TABLES,
+} from './tables.js'
+
+export type {
+	ArticleContentRow,
+	AuthorRow,
+	CmsActivityLogRow,
+	CmsApiKeyRow,
+	CmsNotificationRow,
+	CmsRole,
+	CmsWebhookRow,
+	ContentContributorRow,
+	ContentImportRow,
+	ContentItemRow,
+	ContentRelationRow,
+	ContentRevisionRow,
+	ContentSlugRedirectRow,
+	ContentStatus,
+	ContentTagLinkRow,
+	ContentTagRow,
+	ContentType,
+	ContentVisibility,
+	FoundryCallbackEventRow,
+	MastheadUserRow,
+	MediaAssetRow,
+	PodcastContentRow,
+	VideoContentRow,
+	VideoProcessingState,
+	WorkspaceInviteRow,
+	WorkspaceMembershipRow,
+	WorkspaceSettingsRow,
+} from './types.js'

package/src/schema/insights-ingest.ts

@@ -0,0 +1,126 @@
+import { z } from 'zod'
+
+// HMAC insights-ingest payload — the board for ONE (site_id, run_date).
+// Posted to POST /admin/api/content/insights-ingest, HMAC-SHA256 over the raw
+// body in X-Foundry-Signature vs the per-site insights ingest secret (Secrets
+// Store binding). Field names are byte-identical to the migration 0016 columns
+// so the ingest route binds payload -> row with no remapping.
+//
+// Replay safety lives in meta: the route dedupes on meta.event_id (mirroring
+// foundry_callback_events) and rejects/no-ops any meta.run_attempt that is
+// equal-or-lower than the run_attempt already landed for (site_id, run_date) in
+// content_insight_runs. HMAC authenticates the SENDER; it does NOT prevent
+// replay — run_attempt is the monotonic guard.
+
+// Reusable evidence/brief JSON shapes (stored as TEXT NOT NULL, zod-validated).
+export const InsightEvidenceDemandSchema = z.object({
+	query: z.string().min(1),
+	impressions: z.number().int().nonnegative(),
+	clicks: z.number().int().nonnegative(),
+	ctr: z.number().min(0).max(1),
+	position: z.number().nonnegative(),
+	trend: z.number(),
+})
+
+export const InsightEvidenceOpportunitySchema = z.object({
+	basis: z.string().min(1),
+	source_count: z.number().int().nonnegative(),
+})
+
+export const InsightEvidenceSchema = z.union([
+	InsightEvidenceDemandSchema,
+	InsightEvidenceOpportunitySchema,
+])
+
+/** One recent competitor article — the COMPETITOR-WATCH pulse evidence (carried in
+ *  the opaque brief blob; the board surfaces it as the raw rival signal). */
+export const InsightCompetitorArticleSchema = z.object({
+	title: z.string().min(1),
+	url: z.string().url(),
+	outlet: z.string().optional(),
+	published: z.string().optional(),
+	covered: z.boolean().optional(),
+})
+
+export const InsightBriefSchema = z.object({
+	why_now: z.string().min(1),
+	angle: z.string().min(1),
+	cluster: z.object({
+		canonical: z.string().min(1),
+		spokes: z.array(z.string().min(1)),
+	}),
+	sources: z.array(
+		z.object({
+			title: z.string().min(1),
+			url: z.string().url(),
+		}),
+	),
+	/**
+	 * Which open-web discovery STREAM produced this opportunity row (the theater
+	 * split). REQUIRED here: Zod strips unknown brief keys, so without this field the
+	 * Foundry-sent brief.discoveryKind is SILENTLY dropped at ingest and the board
+	 * can never split the two opportunity sub-kinds. Optional value so old briefs
+	 * (and demand rows) still parse.
+	 */
+	discoveryKind: z.enum(['competitor', 'audience_question']).optional(),
+	/** COMPETITOR-WATCH pulse: the recent rival articles per theater (raw signal). */
+	competitor_articles: z.array(InsightCompetitorArticleSchema).optional(),
+})
+
+// One suggestion row. Names == content_insights columns. id/run_id/created_at
+// are server-assigned on insert and are NOT carried in the wire payload; the
+// route mints id, sets run_id = meta.run_id, created_at = unixepoch().
+export const InsightSuggestionRowSchema = z.object({
+	site_id: z.string().min(1),
+	run_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+	desk: z.string().min(1),
+	suggestion_type: z.enum(['cluster', 'tracker']),
+	signal_type: z.enum(['demand', 'opportunity']),
+	is_best_bet: z.union([z.literal(0), z.literal(1)]),
+	best_bet_rank: z.number().int().positive().nullable(),
+	desk_rank: z.number().int().nonnegative(),
+	headline: z.string().min(1),
+	evidence: InsightEvidenceSchema,
+	brief: InsightBriefSchema,
+	intent_key: z.string().min(1),
+	beat: z.enum(['defense', 'intelligence', 'diplomacy', 'analysis']).nullable(),
+})
+
+export const InsightsIngestMetaSchema = z.object({
+	event_id: z.string().min(1),
+	run_id: z.string().min(1),
+	site_id: z.string().min(1),
+	run_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+	run_attempt: z.number().int().positive(),
+	generated_at: z.number().int().positive(),
+	content_hash: z.string().min(1),
+	status: z.enum(['running', 'completed', 'partial', 'failed']),
+	counts: z.object({
+		demand_count: z.number().int().nonnegative(),
+		opportunity_count: z.number().int().nonnegative(),
+	}),
+	error: z.string().nullable().optional(),
+})
+
+export const InsightsIngestPayloadSchema = z
+	.object({
+		meta: InsightsIngestMetaSchema,
+		rows: z.array(InsightSuggestionRowSchema),
+	})
+	// Every row's (site_id, run_date) must match meta (the route scopes the
+	// replace DELETE by meta.site_id + meta.run_date — never run_date alone).
+	.superRefine((payload, ctx) => {
+		for (const [i, row] of payload.rows.entries()) {
+			if (row.site_id !== payload.meta.site_id || row.run_date !== payload.meta.run_date) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['rows', i],
+					message: 'row (site_id, run_date) must equal meta (site_id, run_date)',
+				})
+			}
+		}
+	})
+
+export type InsightsIngestPayload = z.infer<typeof InsightsIngestPayloadSchema>
+export type InsightsIngestMeta = z.infer<typeof InsightsIngestMetaSchema>
+export type InsightSuggestionRowPayload = z.infer<typeof InsightSuggestionRowSchema>