@growth-labs/cms 0.1.0

package/src/routes/index.ts

@@ -0,0 +1,295 @@
+// Public surface of the @growth-labs/cms API routes (WS7-07). Exposed at the
+// `@growth-labs/cms/routes` subpath. These are framework-agnostic mountable
+// handlers — pure `(ctx: RouteContext) => Promise<Response>` factories that call
+// the WS7-05 publishing engine with auth/authz INJECTED (config.authz). A site
+// (Astro, Workers, Hono, …) supplies a thin adapter that maps its request +
+// bindings + authz impl onto a RouteContext.
+//
+// SCOPE (bead 07): content / authors / media / cron route handlers. The Foundry
+// media-dispatch routes (dispatch-video, callback) + their state-machine glue
+// (video-processing / trigger-token / article-faq / hls-duration /
+// video-transcript) land in bead 08 (gated on OD-CMS7). The article-takeaways
+// publish dispatch is exposed here only as an OPTIONAL injected hook so the
+// package carries no Foundry/Hermes coupling.
+
+// Foundry dispatch provider type (re-exported for convenience in route tests).
+export type { FoundryDispatch } from '../providers/types.js'
+// AI house-style assist routes (P4 Task 3 + 5).
+export { type AiRouteHandlers, createAiRoutes } from './ai.js'
+// Analytics routes — AnalyticsProvider passthrough (P5 Task 5).
+export {
+	type AnalyticsRouteConfig,
+	type AnalyticsRouteHandlers,
+	createAnalyticsRoutes,
+} from './analytics.js'
+// API key routes — POST/GET/DELETE /settings/api-keys + verifyCmsApiKey gateway (P7 Task 7).
+export {
+	type ApiKeyRouteConfig,
+	type ApiKeyRouteHandlers,
+	createApiKeyRoutes,
+	verifyCmsApiKey,
+} from './api-keys.js'
+// Authors routes + the author helpers.
+export {
+	type AuthorRouteHandlers,
+	createAuthorRoutes,
+	ensureUniqueAuthorSlug,
+	normalizeSocialInput,
+	parseSocialJson,
+	serializeSocialInput,
+} from './authors.js'
+// 5-role capability matrix + requireRole/ownership middleware (P7 Task 2).
+export {
+	buildMatrixAuthz,
+	CAPABILITY_MATRIX,
+	type Capability,
+	type ContentAction,
+	type ContentOwnershipContext,
+	canActOnContent,
+	canPerformContentAction,
+	type MatrixAuthzConfig,
+	roleCan,
+} from './authz-matrix.js'
+// Editorial calendar route (P5 Task 7).
+export {
+	type CalendarRouteConfig,
+	type CalendarRouteHandlers,
+	type CalendarRouteItem,
+	createCalendarRoutes,
+} from './calendar.js'
+// Site configuration (theme tokens, taxonomy, binding names, authz).
+export {
+	type CmsRouteConfig,
+	type ResolvedCmsRouteConfig,
+	resolveConfig,
+} from './config.js'
+// Content routes + the optional Foundry takeaways hook + FAQ hook.
+// Note: DispatchWebhookHook is exported from ./webhooks.js (the canonical source).
+export {
+	type ContentRouteConfig,
+	type ContentRouteHandlers,
+	createContentRoutes,
+	type DispatchFaqHook,
+	type DispatchTakeawaysHook,
+	type PublishReadinessHook,
+} from './content.js'
+// Content Insights surface — read/dismiss/undismiss + the HMAC insights-ingest route.
+export {
+	type ContentInsightsRouteConfig,
+	type ContentInsightsRouteHandlers,
+	createContentInsightsRoutes,
+} from './content-insights.js'
+// Request surface + injected-authz contract.
+export {
+	type Authz,
+	type CmsRole,
+	type CmsUser,
+	json,
+	type R2BucketLike,
+	type R2HeadResult,
+	type R2MultipartUpload,
+	type R2UploadedPart,
+	type RouteContext,
+	requireId,
+} from './context.js'
+// Cron route.
+export { type CronRouteHandlers, createCronRoutes } from './cron.js'
+// Dashboard summary route (P5 Task 4).
+export {
+	createDashboardRoutes,
+	type DashboardRouteConfig,
+	type DashboardRouteHandlers,
+} from './dashboard.js'
+// Import routes — two-step parse→confirm pipeline.
+export { createImportRoutes, type ImportRouteHandlers } from './imports.js'
+// Media routes.
+export { createMediaRoutes, type MediaRouteHandlers } from './media.js'
+// Media-core helpers (parameterized media-assets / admin-media / video-upload /
+// image-variant building) — exported for sites that build their own media glue.
+export {
+	buildImageAssetKey,
+	buildVideoSourceKey,
+	contentTypeForVideoFileName,
+	deleteStagedVideoSource,
+	EDITOR_VIDEO_PART_SIZE,
+	EDITORIAL_IMAGE_MAX_HERO_WIDTH,
+	EDITORIAL_IMAGE_MAX_INLINE_WIDTH,
+	getImageVariantUrl,
+	getMediaPublicDomain,
+	insertMediaAsset,
+	isAllowedVideoSource,
+	isVideoSourceKey,
+	isVideoSourceKeyForVideoId,
+	MAX_EDITOR_VIDEO_SOURCE_BYTES,
+	type MediaAssetInsert,
+	type MediaAssetStatus,
+	type MediaAssetType,
+	mediaKey,
+	normalizeVideoFileExtension,
+	normalizeVideoSourceContentType,
+	parseVideoIdSlug,
+	publicUrlFor,
+	VIDEO_SOURCE_PREFIX,
+	videoSourceKeyFromPublicUrl,
+} from './media-lib.js'
+// Preview token routes — HMAC signed-token draft-SSR seam (package side).
+export {
+	createPreviewRoutes,
+	type PreviewRouteHandlers,
+	verifyPreviewToken,
+} from './preview.js'
+// RBAC team routes — GET/PATCH/DELETE /settings/members (P7 Task 4).
+export {
+	createRbacRoutes,
+	type RbacRouteConfig,
+	type RbacRouteHandlers,
+} from './rbac.js'
+// Invite flow — POST /settings/members/invite + POST /invite/accept (P7 Task 5).
+export {
+	createInviteRoutes,
+	type InviteRouteConfig,
+	type InviteRouteHandlers,
+} from './rbac-invites.js'
+// Shell (admin SPA) route handlers.
+export {
+	createShellRoutes,
+	type ShellRouteConfig,
+	type ShellRouteHandlers,
+	type ShellWorkspaceDescriptor,
+} from './shell.js'
+// Subscriptions routes — SubscriptionsProvider passthrough (P5 Task 6).
+export {
+	createSubscriptionsRoutes,
+	type SubscriptionsRouteConfig,
+	type SubscriptionsRouteHandlers,
+} from './subscriptions.js'
+// Tag management routes — GET /tags, GET /tags?q=, DELETE /tags/:id (P3 Task 9).
+export { createTagRoutes, type TagRouteHandlers } from './tags.js'
+// Topic management over content_items.primary_topic.
+export { createTopicRoutes, type TopicRouteHandlers } from './topics.js'
+// Webhook routes — POST/GET/DELETE /settings/webhooks + test (P7 Task 8).
+export {
+	createWebhookRoutes,
+	type DispatchWebhookHook,
+	type WebhookRouteConfig,
+	type WebhookRouteHandlers,
+} from './webhooks.js'
+
+import { type AiRouteHandlers, createAiRoutes } from './ai.js'
+import { type AnalyticsRouteHandlers, createAnalyticsRoutes } from './analytics.js'
+import { type ApiKeyRouteHandlers, createApiKeyRoutes } from './api-keys.js'
+import { type AuthorRouteHandlers, createAuthorRoutes } from './authors.js'
+import { type CalendarRouteHandlers, createCalendarRoutes } from './calendar.js'
+import type { CmsRouteConfig } from './config.js'
+import {
+	type ContentRouteConfig,
+	type ContentRouteHandlers,
+	createContentRoutes,
+} from './content.js'
+import {
+	type ContentInsightsRouteHandlers,
+	createContentInsightsRoutes,
+} from './content-insights.js'
+import { type CronRouteHandlers, createCronRoutes } from './cron.js'
+import { createDashboardRoutes, type DashboardRouteHandlers } from './dashboard.js'
+import { createImportRoutes, type ImportRouteHandlers } from './imports.js'
+import { createMediaRoutes, type MediaRouteHandlers } from './media.js'
+import { createPreviewRoutes, type PreviewRouteHandlers } from './preview.js'
+import { createRbacRoutes, type RbacRouteHandlers } from './rbac.js'
+import {
+	createShellRoutes,
+	type ShellRouteHandlers,
+	type ShellWorkspaceDescriptor,
+} from './shell.js'
+import { createSubscriptionsRoutes, type SubscriptionsRouteHandlers } from './subscriptions.js'
+import { createTagRoutes, type TagRouteHandlers } from './tags.js'
+import { createTopicRoutes, type TopicRouteHandlers } from './topics.js'
+import { createWebhookRoutes, type WebhookRouteHandlers } from './webhooks.js'
+
+export interface CmsRoutes {
+	content: ContentRouteHandlers
+	authors: AuthorRouteHandlers
+	media: MediaRouteHandlers
+	cron: CronRouteHandlers
+	shell: ShellRouteHandlers
+	imports: ImportRouteHandlers
+	preview: PreviewRouteHandlers
+	tags: TagRouteHandlers
+	topics: TopicRouteHandlers
+	ai: AiRouteHandlers
+	dashboard: DashboardRouteHandlers
+	analytics: AnalyticsRouteHandlers
+	subscriptions: SubscriptionsRouteHandlers
+	calendar: CalendarRouteHandlers
+	rbac: RbacRouteHandlers
+	apiKeys: ApiKeyRouteHandlers
+	webhooks: WebhookRouteHandlers
+	contentInsights: ContentInsightsRouteHandlers
+}
+
+/**
+ * Build the full set of CMS route handlers from one config object. The
+ * `dispatchTakeaways` hook (if present on the config) is wired into the content
+ * routes; `dispatchWebhook` (if present) is threaded into both the content routes
+ * (lifecycle transitions) and the webhooks test route. The optional
+ * `workspaces`/`activeWorkspaceId` fields wire the shell routes; they default to
+ * empty so existing callers (P0 routes) are unaffected.
+ */
+export function createCmsRoutes(
+	config: ContentRouteConfig & {
+		workspaces?: ShellWorkspaceDescriptor[]
+		activeWorkspaceId?: string
+	},
+): CmsRoutes {
+	const base: CmsRouteConfig = config
+	return {
+		content: createContentRoutes(config),
+		authors: createAuthorRoutes(base),
+		media: createMediaRoutes(base),
+		cron: createCronRoutes(base),
+		imports: createImportRoutes(base),
+		preview: createPreviewRoutes(base),
+		tags: createTagRoutes(base),
+		topics: createTopicRoutes(base),
+		ai: createAiRoutes(base),
+		shell: createShellRoutes({
+			authz: config.authz,
+			workspaces: config.workspaces ?? [],
+			activeWorkspaceId: config.activeWorkspaceId ?? '',
+			providers: config.providers,
+		}),
+		dashboard: createDashboardRoutes({
+			authz: config.authz,
+			activeWorkspaceId: config.activeWorkspaceId,
+			providers: config.providers ? { ...config.providers } : undefined,
+		}),
+		analytics: createAnalyticsRoutes({
+			authz: config.authz,
+			providers: config.providers ? { ...config.providers } : undefined,
+		}),
+		subscriptions: createSubscriptionsRoutes({
+			authz: config.authz,
+			providers: config.providers ? { ...config.providers } : undefined,
+		}),
+		calendar: createCalendarRoutes({
+			authz: config.authz,
+		}),
+		rbac: createRbacRoutes({
+			authz: config.authz,
+			workspaceId: config.activeWorkspaceId ?? '',
+		}),
+		apiKeys: createApiKeyRoutes({
+			authz: config.authz,
+			workspaceId: config.activeWorkspaceId ?? '',
+		}),
+		webhooks: createWebhookRoutes({
+			authz: config.authz,
+			workspaceId: config.activeWorkspaceId ?? '',
+			dispatchWebhook: config.dispatchWebhook,
+		}),
+		contentInsights: createContentInsightsRoutes({
+			authz: config.authz,
+			activeWorkspaceId: config.activeWorkspaceId,
+		}),
+	}
+}

package/src/routes/media-lib.ts

@@ -0,0 +1,405 @@
+// Media-core helpers the media routes depend on. Ported from
+// fulcrum-labs/fronts src/lib/media-assets.ts + admin-media.ts +
+// admin-video-upload.ts + images.ts (inventory §1: extract + theme-token). The
+// Fronts module-level constants (`media.fronts.co`, `PUBLIC_MEDIA`,
+// `site_id='fronts'`, the image-variant set, the editorial-max widths) are now
+// PARAMETERS supplied by the site via CmsRouteConfig; the Fronts values remain
+// the documented defaults (config.ts).
+//
+// The `media.fronts.co/cdn-cgi/image` transform doc-comment + editorial-max
+// constants are theme-token — kept here as documentation only.
+
+import type { D1Database } from '../engine/d1.js'
+import { slugify } from '../engine/slug.js'
+
+// ---------------------------------------------------------------------------
+// media-assets.ts — insertMediaAsset / publicUrlFor / domain resolution
+// ---------------------------------------------------------------------------
+
+const MEDIA_DOMAIN_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i
+
+/**
+ * Resolve the public media domain, preferring `env.MEDIA_PUBLIC_DOMAIN` when it
+ * looks like a valid host, else the site-configured default. Allows
+ * staging/dev to override without code changes; invalid overrides fall back to
+ * the default so we never construct a malformed URL.
+ */
+export function getMediaPublicDomain(
+	env: { MEDIA_PUBLIC_DOMAIN?: unknown } | null | undefined,
+	fallbackDomain: string,
+): string {
+	const candidate =
+		env && typeof env.MEDIA_PUBLIC_DOMAIN === 'string'
+			? env.MEDIA_PUBLIC_DOMAIN.trim().toLowerCase()
+			: ''
+	if (candidate && MEDIA_DOMAIN_RE.test(candidate)) return candidate
+	return fallbackDomain
+}
+
+export type MediaAssetType = 'image' | 'audio' | 'video'
+export type MediaAssetStatus = 'ready' | 'processing' | 'failed'
+
+export interface MediaAssetInsert {
+	id: string
+	siteId: string
+	assetType: MediaAssetType
+	sourceType: string | null
+	originalFilename: string | null
+	status: MediaAssetStatus
+	objectKey: string
+	publicUrl: string | null
+	url: string | null
+	width: number | null
+	height: number | null
+	variantsJson: string | null
+	r2Binding: string
+}
+
+export function publicUrlFor(opts: {
+	r2Binding: string
+	objectKey: string
+	publicDomain: string
+}): string {
+	const objectKey = opts.objectKey.replace(/^\/+/, '')
+	return `https://${opts.publicDomain}/${objectKey}`
+}
+
+export async function insertMediaAsset(db: D1Database, row: MediaAssetInsert): Promise<void> {
+	// media_assets timestamps are TEXT datetime('now') (NOT unixepoch) — the
+	// documented intentional divergence from the content tables (inventory §5).
+	await db
+		.prepare(
+			`INSERT INTO media_assets (
+				id, site_id, asset_type, source_type, original_filename, status,
+				object_key, public_url, url, width, height, variants_json, r2_binding,
+				created_at, updated_at
+			)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+			ON CONFLICT(id) DO UPDATE SET
+				site_id = excluded.site_id,
+				asset_type = excluded.asset_type,
+				source_type = excluded.source_type,
+				original_filename = excluded.original_filename,
+				status = excluded.status,
+				object_key = excluded.object_key,
+				public_url = excluded.public_url,
+				url = excluded.url,
+				width = excluded.width,
+				height = excluded.height,
+				variants_json = excluded.variants_json,
+				r2_binding = excluded.r2_binding,
+				updated_at = datetime('now')`,
+		)
+		.bind(
+			row.id,
+			row.siteId,
+			row.assetType,
+			row.sourceType,
+			row.originalFilename,
+			row.status,
+			row.objectKey,
+			row.publicUrl,
+			row.url,
+			row.width,
+			row.height,
+			row.variantsJson,
+			row.r2Binding,
+		)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// admin-media.ts — image asset key building
+// ---------------------------------------------------------------------------
+
+/**
+ * Editorial image-upload guidance (theme-token, documentation only): keep new
+ * uploads under these dimensions. The render pipeline routes hero + inline
+ * images through a `/cdn-cgi/image/...` transform, so anything wider than
+ * ~2400px on either edge is bytes the browser never displays.
+ *  - Hero images: 2400 × 1350 (16:9)
+ *  - Inline body images: 1600 × max-aspect-ratio-needed
+ */
+export const EDITORIAL_IMAGE_MAX_HERO_WIDTH = 2400
+export const EDITORIAL_IMAGE_MAX_INLINE_WIDTH = 1600
+
+function normalizeImageSlug(slug: string): string {
+	return slugify(slug.replace(/^fronts-image-/, '')) || 'upload'
+}
+
+function imageExtension(fileName: string): string {
+	const extension = fileName.split('.').pop()?.toLowerCase()
+	if (extension === 'jpeg') return 'jpg'
+	if (extension && /^[a-z0-9]+$/.test(extension)) return extension
+	return 'jpg'
+}
+
+export function buildImageAssetKey(
+	slug: string,
+	fileName: string,
+	uniquePart = crypto.randomUUID(),
+): string {
+	const normalizedSlug = normalizeImageSlug(slug)
+	const suffix = uniquePart.replace(/-/g, '').slice(0, 8).toLowerCase()
+	const extension = imageExtension(fileName)
+	return `images/articles/${normalizedSlug}-${suffix}.${extension}`
+}
+
+// ---------------------------------------------------------------------------
+// images.ts — image variant URL building (cdn-cgi/image transform)
+// ---------------------------------------------------------------------------
+
+const IMAGE_VARIANT_PARAMS: Record<string, string> = {
+	thumbnail: 'width=200,quality=80,format=auto',
+	card: 'width=400,quality=80,format=auto',
+	article: 'width=800,quality=80,format=auto',
+	hero: 'width=1200,quality=80,format=auto',
+	full: 'width=2000,quality=80,format=auto',
+	og: 'width=1200,height=630,fit=cover,quality=80,format=auto',
+}
+
+function normalizeMediaPath(value: unknown, domain: string): string | null {
+	if (typeof value !== 'string') return null
+	const trimmed = value.trim()
+	if (!trimmed) return null
+
+	if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+		let url: URL
+		try {
+			url = new URL(trimmed)
+		} catch {
+			return null
+		}
+		if (url.hostname !== domain) return null
+		const mediaPath = url.pathname.replace(/^\/cdn-cgi\/image\/[^/]+\//, '').replace(/^\/+/, '')
+		return mediaPath || null
+	}
+
+	const mediaPath = trimmed.replace(/^\/cdn-cgi\/image\/[^/]+\//, '').replace(/^\/+/, '')
+	return mediaPath || null
+}
+
+/**
+ * Build a `/cdn-cgi/image/<params>/<path>` transform URL for the named variant.
+ * Returns null when the value is not a media path on the configured domain.
+ */
+export function getImageVariantUrl(value: unknown, variant: string, domain: string): string | null {
+	const mediaPath = normalizeMediaPath(value, domain)
+	if (!mediaPath) return null
+	const params = IMAGE_VARIANT_PARAMS[variant] ?? IMAGE_VARIANT_PARAMS.article
+	return `https://${domain}/cdn-cgi/image/${params}/${mediaPath}`
+}
+
+// ---------------------------------------------------------------------------
+// Podcast object key (Fronts used `@growth-labs/media` `mediaKey`, inlined here
+// to keep the routes self-contained — it's a trivial prefix+slug+ext join).
+// ---------------------------------------------------------------------------
+
+export function mediaKey(prefix: string, slug: string, extension?: string): string {
+	const ext = extension ? `.${extension}` : ''
+	return `${prefix}${slug}${ext}`
+}
+
+export const EDITOR_AUDIO_PART_SIZE = 10 * 1024 * 1024
+export const MAX_EDITOR_AUDIO_SOURCE_BYTES = 2 * 1024 * 1024 * 1024
+
+const AUDIO_EXTENSIONS = new Set(['mp3', 'm4a', 'wav', 'aac'])
+
+const AUDIO_CONTENT_TYPES_BY_EXTENSION: Record<string, string> = {
+	aac: 'audio/aac',
+	m4a: 'audio/mp4',
+	mp3: 'audio/mpeg',
+	wav: 'audio/wav',
+}
+
+function rawAudioFileExtension(fileName: string): string {
+	return fileName.split('.').pop()?.toLowerCase() || ''
+}
+
+export function normalizeAudioFileExtension(fileName: string): string {
+	const extension = rawAudioFileExtension(fileName)
+	if (AUDIO_EXTENSIONS.has(extension)) return extension
+	return 'mp3'
+}
+
+export function normalizeAudioSourceContentType(
+	contentType: string | null | undefined,
+	fileName: string,
+): string {
+	const trimmed = contentType?.trim().toLowerCase() || ''
+	if (trimmed) return trimmed
+	return AUDIO_CONTENT_TYPES_BY_EXTENSION[normalizeAudioFileExtension(fileName)] || 'audio/mpeg'
+}
+
+export function isAllowedAudioSource(
+	contentType: string | null | undefined,
+	fileName: string,
+): boolean {
+	const rawExtension = rawAudioFileExtension(fileName)
+	const normalized = contentType?.trim().toLowerCase() || ''
+	if (!AUDIO_EXTENSIONS.has(rawExtension)) return false
+	if (!normalized) return true
+	if (normalized.startsWith('audio/')) return true
+	if (normalized === 'application/octet-stream') return true
+	return false
+}
+
+export function buildAudioAssetKey(slug: string, fileName: string): string {
+	const normalizedSlug = slugify(slug) || 'podcast'
+	return mediaKey('audio/', normalizedSlug, normalizeAudioFileExtension(fileName))
+}
+
+export function isAudioAssetKey(key: string): boolean {
+	return /^audio\/[a-z0-9][a-z0-9-]*\.[a-z0-9]+$/.test(key)
+}
+
+export function isAudioAssetKeyForSlug(key: string, slug: string, fileName: string): boolean {
+	return isAudioAssetKey(key) && key === buildAudioAssetKey(slug, fileName)
+}
+
+// ---------------------------------------------------------------------------
+// admin-video-upload.ts — video-source key building, allowlist, multipart
+// ---------------------------------------------------------------------------
+
+export const VIDEO_SOURCE_PREFIX = 'video-sources'
+export const EDITOR_VIDEO_PART_SIZE = 5 * 1024 * 1024
+export const MAX_EDITOR_VIDEO_SOURCE_BYTES = 10 * 1024 * 1024 * 1024
+
+const VIDEO_EXTENSIONS = new Set(['mp4', 'm4v', 'mov', 'webm', 'mkv', 'avi', 'mpg', 'mpeg', 'ts'])
+
+const VIDEO_CONTENT_TYPES_BY_EXTENSION: Record<string, string> = {
+	avi: 'video/x-msvideo',
+	m4v: 'video/x-m4v',
+	mkv: 'video/x-matroska',
+	mov: 'video/quicktime',
+	mp4: 'video/mp4',
+	mpeg: 'video/mpeg',
+	mpg: 'video/mpeg',
+	ts: 'video/mp2t',
+	webm: 'video/webm',
+}
+
+const VIDEO_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/
+
+/** Validate + normalize a video id slug (foundry/video-processing.ts). */
+export function parseVideoIdSlug(value: string): string | null {
+	const trimmed = value.trim()
+	if (trimmed !== value) return null
+	if (!VIDEO_ID_RE.test(trimmed)) return null
+	return trimmed
+}
+
+function rawVideoFileExtension(fileName: string): string {
+	return fileName.split('.').pop()?.toLowerCase() || ''
+}
+
+export function normalizeVideoFileExtension(fileName: string): string {
+	const extension = rawVideoFileExtension(fileName)
+	if (VIDEO_EXTENSIONS.has(extension)) return extension
+	return 'mp4'
+}
+
+export function contentTypeForVideoFileName(fileName: string): string {
+	return VIDEO_CONTENT_TYPES_BY_EXTENSION[normalizeVideoFileExtension(fileName)] || 'video/mp4'
+}
+
+export function normalizeVideoSourceContentType(
+	contentType: string | null | undefined,
+	fileName: string,
+): string {
+	const trimmed = contentType?.trim().toLowerCase() || ''
+	if (trimmed) return trimmed
+	return contentTypeForVideoFileName(fileName)
+}
+
+export function isAllowedVideoSource(
+	contentType: string | null | undefined,
+	fileName: string,
+): boolean {
+	const rawExtension = rawVideoFileExtension(fileName)
+	const normalized = contentType?.trim().toLowerCase() || ''
+	// Reject filenames whose extension is not allow-listed regardless of the
+	// claimed content-type — the server constructs the stored key + final
+	// content-type from this extension, so anything outside would be mislabeled.
+	if (!VIDEO_EXTENSIONS.has(rawExtension)) return false
+	if (!normalized) return true
+	if (normalized.startsWith('video/')) return true
+	if (normalized === 'application/octet-stream') return true
+	return false
+}
+
+export function buildVideoSourceKey(
+	videoId: string,
+	fileName: string,
+	uniquePart = crypto.randomUUID(),
+): string {
+	const parsedVideoId = parseVideoIdSlug(videoId)
+	const safeVideoId = parsedVideoId || 'video'
+	const suffix =
+		uniquePart
+			.replace(/[^a-z0-9]/gi, '')
+			.slice(0, 32)
+			.toLowerCase() || crypto.randomUUID().replace(/-/g, '')
+	const extension = normalizeVideoFileExtension(fileName)
+	return `${VIDEO_SOURCE_PREFIX}/${safeVideoId}/${suffix}/original.${extension}`
+}
+
+export function isVideoSourceKey(key: string): boolean {
+	return new RegExp(
+		`^${VIDEO_SOURCE_PREFIX}/[A-Za-z0-9][A-Za-z0-9_-]*/[a-z0-9]{32}/original\\.[a-z0-9]+$`,
+	).test(key)
+}
+
+export function isVideoSourceKeyForVideoId(key: string, videoId: string): boolean {
+	const parsedVideoId = parseVideoIdSlug(videoId)
+	return Boolean(
+		parsedVideoId &&
+			isVideoSourceKey(key) &&
+			key.startsWith(`${VIDEO_SOURCE_PREFIX}/${parsedVideoId}/`),
+	)
+}
+
+export function videoSourceKeyFromPublicUrl(
+	sourceUrl: string,
+	publicDomain: string,
+): string | null {
+	try {
+		const url = new URL(sourceUrl)
+		if (url.hostname.toLowerCase() !== publicDomain.toLowerCase()) return null
+		const key = decodeURIComponent(url.pathname.replace(/^\/+/, ''))
+		return isVideoSourceKey(key) ? key : null
+	} catch {
+		return null
+	}
+}
+
+export async function deleteStagedVideoSource(
+	db: D1Database,
+	bucket: { delete(key: string | string[]): Promise<void> } | undefined,
+	sourceUrl: string,
+	publicDomain: string,
+): Promise<boolean> {
+	const sourceKey = videoSourceKeyFromPublicUrl(sourceUrl, publicDomain)
+	if (!sourceKey) return false
+
+	try {
+		if (bucket && typeof bucket.delete === 'function') {
+			await bucket.delete(sourceKey)
+		}
+	} catch {
+		// R2 cleanup is best-effort; the media asset row is removed below so the
+		// CMS does not offer a stale staged source for retry.
+	}
+
+	await db
+		.prepare(
+			`DELETE FROM media_assets
+			WHERE id = ?
+				AND asset_type = 'video'
+				AND source_type = 'editor-video-source'`,
+		)
+		.bind(sourceKey)
+		.run()
+
+	return true
+}