@growth-labs/cms 0.1.0

package/src/routes/ai.ts

@@ -0,0 +1,461 @@
+// AI house-style assist routes (P4 Tasks 3 + 4).
+// createAiRoutes(config) — streaming actions: proofreadAndTighten + suggestHeadlines (SSE)
+//                        — sync actions: generateKeyTakeaways + draftMetaDescription.
+//
+// Architecture:
+// - Every AI call goes through the injected LlmDispatch hook (config.hooks.llm).
+//   Absent hook → 501. This is the §9 hard constraint.
+// - The streaming actions call dispatch({ ...prompt, stream: true }) and return the
+//   result as a text/event-stream Response. If the hook returns { text } (a non-
+//   streaming implementation), the text is wrapped as a single SSE event (graceful
+//   fallback).
+// - Streaming actions are read-only suggestions — they NEVER write back to D1.
+// - Sync actions (takeaways, meta-description) call dispatch({ ...prompt, stream: false }),
+//   apply the ai_locked_fields gate, persist when allowed, and return the result.
+// - OG-image generation lands in Task 5.
+
+import {
+	headlinesPrompt,
+	metaDescriptionPrompt,
+	proofreadPrompt,
+	takeawaysPrompt,
+} from '../engine/ai-prompts.js'
+import { applyAiWrite, parseLockedFields } from '../engine/ai-writeback.js'
+import { buildOgCardSpec } from '../engine/og-render.js'
+import { type ContentItemRecord, getContentItem } from '../engine/publisher.js'
+import type { LlmDispatchResult } from '../providers/types.js'
+import type { CmsRouteConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import { type Authz, type Capability, json, type RouteContext, requireId } from './context.js'
+import { buildImageAssetKey, insertMediaAsset, publicUrlFor } from './media-lib.js'
+
+/**
+ * AI editorial assists are write-adjacent surfaces (proofread/headlines are
+ * read-only suggestions; takeaways/meta/og persist). They gate on the
+ * edit_own_draft capability via requireRole when the host wires the role seam
+ * (any of the 5 roles holds it — no launch-role lockout), falling back to the
+ * flat requirePublisher gate otherwise. Actual write-back is additionally gated
+ * by the ownership-aware content routes.
+ */
+async function aiGuard(authz: Authz, ctx: RouteContext): Promise<Response | null> {
+	if (authz.requireRole) {
+		return authz.requireRole('edit_own_draft' satisfies Capability, ctx)
+	}
+	return authz.requirePublisher(ctx)
+}
+
+export interface AiRouteHandlers {
+	/** POST /content/:id/ai/proofread — SSE streaming proofread & tighten. */
+	proofreadAndTighten(ctx: RouteContext): Promise<Response>
+	/** POST /content/:id/ai/headlines — SSE streaming 5-headline suggestions. */
+	suggestHeadlines(ctx: RouteContext): Promise<Response>
+	/** POST /content/:id/ai/takeaways — sync: generate + persist 3 key takeaways. */
+	generateKeyTakeaways(ctx: RouteContext): Promise<Response>
+	/** POST /content/:id/ai/meta-description — sync: draft + persist meta description (<160 chars). */
+	draftMetaDescription(ctx: RouteContext): Promise<Response>
+	/** POST /content/:id/ai/og-image — render + persist a social-card OG image via the injected OgImageRenderer. */
+	generateOgImage(ctx: RouteContext): Promise<Response>
+}
+
+/**
+ * Clamp a meta description to at most `limit` characters, breaking at a word
+ * boundary. Trailing whitespace is trimmed from the result.
+ *
+ * Algorithm: if the text is already within the limit, return it unchanged.
+ * Otherwise find the last space at or before position `limit` and cut there.
+ * If there is no space before `limit`, perform a hard cut at `limit`.
+ */
+export function clampMeta(text: string, limit: number): string {
+	const trimmed = text.trim()
+	if (trimmed.length <= limit) return trimmed
+
+	// Find the last space at or before `limit`.
+	const slice = trimmed.slice(0, limit)
+	const lastSpace = slice.lastIndexOf(' ')
+	if (lastSpace > 0) {
+		return slice.slice(0, lastSpace).trimEnd()
+	}
+	// No space found — hard cut.
+	return slice.trimEnd()
+}
+
+/**
+ * Tolerant JSON parse for the takeaways LLM response.
+ * The LLM is instructed to return a JSON array of 3 strings; in practice it may
+ * return malformed JSON or wrap the array in markdown. We try JSON.parse first;
+ * on failure we wrap the raw text as a single-element array so the caller always
+ * gets a string[].
+ */
+function parseTakeawaysText(text: string): string[] {
+	const t = text.trim()
+	try {
+		const parsed = JSON.parse(t)
+		if (Array.isArray(parsed)) {
+			return parsed.map((item) => String(item))
+		}
+		// Non-array JSON — wrap it
+		return [String(parsed)]
+	} catch {
+		// Not JSON — return the raw text as a single element
+		return [t]
+	}
+}
+
+/**
+ * Wrap a ReadableStream or { text } result from LlmDispatch as an SSE Response.
+ *
+ * - ReadableStream → pass through as text/event-stream (the provider does SSE framing).
+ * - { text } → wrap the text as one SSE data event (graceful fallback for sync impls).
+ */
+function isUnavailableLlmResult(
+	result: LlmDispatchResult,
+): result is { text: string; status: 'unavailable'; reason?: string } {
+	return !(result instanceof ReadableStream) && result.status === 'unavailable'
+}
+
+function llmUnavailableResponse(
+	result: { reason?: string },
+	extra: Record<string, unknown> = {},
+): Response {
+	return json(
+		{
+			error: 'AI generation is unavailable',
+			written: false,
+			...(result.reason ? { reason: result.reason } : {}),
+			...extra,
+		},
+		503,
+	)
+}
+
+function toSseResponse(result: LlmDispatchResult): Response {
+	if (isUnavailableLlmResult(result)) return llmUnavailableResponse(result)
+
+	const headers = {
+		'Content-Type': 'text/event-stream',
+		'Cache-Control': 'no-cache',
+		'X-Content-Type-Options': 'nosniff',
+	}
+
+	if (result instanceof ReadableStream) {
+		return new Response(result, { status: 200, headers })
+	}
+
+	// { text } fallback: emit a single SSE data event
+	const body = `data: ${result.text}\n\n`
+	return new Response(body, { status: 200, headers })
+}
+
+/**
+ * Load the article body markdown for a given content item id.
+ * Returns null if the item does not exist or has no article_content row.
+ */
+async function loadArticleBody(
+	ctx: RouteContext,
+	id: string,
+): Promise<{ item: ContentItemRecord; bodyMarkdown: string } | null> {
+	const item = await getContentItem(ctx.db, id)
+	if (!item) return null
+
+	// For non-article types we still load the body if available; for article/newsletter
+	// the body_markdown column is in article_content.
+	const row = await ctx.db
+		.prepare('SELECT body_markdown FROM article_content WHERE content_id = ? LIMIT 1')
+		.bind(id)
+		.first<{ body_markdown: string | null }>()
+
+	const bodyMarkdown = row?.body_markdown ?? ''
+	return { item, bodyMarkdown }
+}
+
+export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
+	const resolved = resolveConfig(config)
+
+	async function proofreadAndTighten(ctx: RouteContext): Promise<Response> {
+		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
+		const authGuard = await aiGuard(resolved.authz, ctx)
+		if (authGuard) return authGuard
+
+		// Guard: llm hook must be configured.
+		if (!resolved.hooks.llm) {
+			return json({ error: 'AI generation is not configured' }, 501)
+		}
+
+		// Resolve the content id.
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const { id } = idResult
+
+		// Load the item + body.
+		const loaded = await loadArticleBody(ctx, id)
+		if (!loaded) return json({ error: 'Not found' }, 404)
+
+		const { bodyMarkdown } = loaded
+
+		// Build the prompt and dispatch (streaming).
+		const prompt = proofreadPrompt({ body: bodyMarkdown })
+		const result = await resolved.hooks.llm.dispatch({ ...prompt, stream: true })
+
+		return toSseResponse(result)
+	}
+
+	async function suggestHeadlines(ctx: RouteContext): Promise<Response> {
+		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
+		const authGuard = await aiGuard(resolved.authz, ctx)
+		if (authGuard) return authGuard
+
+		// Guard: llm hook must be configured.
+		if (!resolved.hooks.llm) {
+			return json({ error: 'AI generation is not configured' }, 501)
+		}
+
+		// Resolve the content id.
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const { id } = idResult
+
+		// Load the item + body.
+		const loaded = await loadArticleBody(ctx, id)
+		if (!loaded) return json({ error: 'Not found' }, 404)
+
+		const { item, bodyMarkdown } = loaded
+
+		// Build the prompt and dispatch (streaming).
+		const prompt = headlinesPrompt({ title: item.title, body: bodyMarkdown })
+		const result = await resolved.hooks.llm.dispatch({ ...prompt, stream: true })
+
+		return toSseResponse(result)
+	}
+
+	async function generateKeyTakeaways(ctx: RouteContext): Promise<Response> {
+		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
+		const authGuard = await aiGuard(resolved.authz, ctx)
+		if (authGuard) return authGuard
+
+		// Guard: llm hook must be configured.
+		if (!resolved.hooks.llm) {
+			return json({ error: 'AI generation is not configured' }, 501)
+		}
+
+		// Resolve the content id.
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const { id } = idResult
+
+		// Load the item.
+		const item = await getContentItem(ctx.db, id)
+		if (!item) return json({ error: 'Not found' }, 404)
+
+		// Takeaways only makes sense for articles (mirrors regenerate-takeaways guard).
+		if (item.type !== 'article') {
+			return json({ error: 'Invalid content type — takeaways require an article' }, 400)
+		}
+
+		// Load the article body.
+		const bodyRow = await ctx.db
+			.prepare('SELECT body_markdown FROM article_content WHERE content_id = ? LIMIT 1')
+			.bind(id)
+			.first<{ body_markdown: string | null }>()
+		const bodyMarkdown = bodyRow?.body_markdown ?? ''
+
+		// Build the prompt and dispatch (sync).
+		const prompt = takeawaysPrompt({ body: bodyMarkdown })
+		const result = await resolved.hooks.llm.dispatch({ ...prompt, stream: false })
+		if (isUnavailableLlmResult(result)) {
+			return llmUnavailableResponse(result, { takeaways: [] })
+		}
+
+		// result should be { text } for a sync (stream:false) call
+		const text = 'text' in result ? result.text : ''
+		const takeaways = parseTakeawaysText(text)
+
+		// Apply the ai_locked_fields write-back gate.
+		const lockedFields = parseLockedFields(item.ai_locked_fields)
+		const writeResult = applyAiWrite({
+			locked: lockedFields,
+			field: 'ai_takeaways',
+			value: takeaways,
+		})
+
+		if (writeResult.written) {
+			const now = Math.floor(Date.now() / 1000)
+			await ctx.db
+				.prepare(
+					`UPDATE article_content
+					SET ai_takeaways = ?,
+						ai_takeaways_at = ?,
+						ai_takeaways_model = ?
+					WHERE content_id = ?`,
+				)
+				.bind(JSON.stringify(takeaways), now, 'llm-dispatch', id)
+				.run()
+		}
+
+		return json({
+			takeaways: writeResult.value,
+			written: writeResult.written,
+			...(writeResult.written ? {} : { locked: true }),
+		})
+	}
+
+	async function draftMetaDescription(ctx: RouteContext): Promise<Response> {
+		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
+		const authGuard = await aiGuard(resolved.authz, ctx)
+		if (authGuard) return authGuard
+
+		// Guard: llm hook must be configured.
+		if (!resolved.hooks.llm) {
+			return json({ error: 'AI generation is not configured' }, 501)
+		}
+
+		// Resolve the content id.
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const { id } = idResult
+
+		// Load the item.
+		const item = await getContentItem(ctx.db, id)
+		if (!item) return json({ error: 'Not found' }, 404)
+
+		// Load the article body (best-effort — non-article types use empty string).
+		let bodyMarkdown = ''
+		if (item.type === 'article' || item.type === 'newsletter') {
+			const bodyRow = await ctx.db
+				.prepare('SELECT body_markdown FROM article_content WHERE content_id = ? LIMIT 1')
+				.bind(id)
+				.first<{ body_markdown: string | null }>()
+			bodyMarkdown = bodyRow?.body_markdown ?? ''
+		}
+
+		// Build the prompt and dispatch (sync).
+		const prompt = metaDescriptionPrompt({ title: item.title, body: bodyMarkdown })
+		const result = await resolved.hooks.llm.dispatch({ ...prompt, stream: false })
+		if (isUnavailableLlmResult(result)) {
+			return llmUnavailableResponse(result, { description: null })
+		}
+
+		// result should be { text } for a sync (stream:false) call
+		const rawText = 'text' in result ? result.text : ''
+
+		// Belt-and-braces: clamp to 160 chars at a word boundary.
+		const description = clampMeta(rawText, 160)
+
+		// Apply the ai_locked_fields write-back gate.
+		const lockedFields = parseLockedFields(item.ai_locked_fields)
+		const writeResult = applyAiWrite({
+			locked: lockedFields,
+			field: 'description',
+			value: description,
+		})
+
+		if (writeResult.written) {
+			await ctx.db
+				.prepare('UPDATE content_items SET description = ?, updated_at = unixepoch() WHERE id = ?')
+				.bind(description, id)
+				.run()
+		}
+
+		return json({
+			description: writeResult.value,
+			written: writeResult.written,
+			...(writeResult.written ? {} : { locked: true }),
+		})
+	}
+
+	async function generateOgImage(ctx: RouteContext): Promise<Response> {
+		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
+		const authGuard = await aiGuard(resolved.authz, ctx)
+		if (authGuard) return authGuard
+
+		// Guard: ogRenderer hook must be configured.
+		if (!resolved.hooks.ogRenderer) {
+			return json({ error: 'OG image rendering is not configured' }, 501)
+		}
+
+		// Guard: bucket must be available.
+		if (!ctx.bucket) {
+			return json({ error: 'Missing R2 bucket configuration' }, 500)
+		}
+
+		// Resolve the content id.
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const { id } = idResult
+
+		// Load the content item.
+		const item = await getContentItem(ctx.db, id)
+		if (!item) return json({ error: 'Not found' }, 404)
+
+		// Build the card spec from the content row.
+		// Brand defaults to the configured mediaPublicDomain as a publication label
+		// (stripped of TLD) or a generic fallback.
+		const brand = resolved.mediaPublicDomain
+			? resolved.mediaPublicDomain.split('.').slice(0, -1).join('.') || resolved.mediaPublicDomain
+			: 'The Publication'
+
+		const cardSpec = buildOgCardSpec(item, { brand })
+
+		// Render the OG image via the injected renderer.
+		const pngBytes = await resolved.hooks.ogRenderer.render(cardSpec)
+
+		// Persist the PNG to R2.
+		const imageKey = buildImageAssetKey(item.slug, 'og-image.png', crypto.randomUUID())
+		await ctx.bucket.put(imageKey, pngBytes, {
+			httpMetadata: { contentType: 'image/png' },
+		})
+
+		// Insert a media_assets row.
+		const publicUrl = publicUrlFor({
+			r2Binding: resolved.mediaR2Binding,
+			objectKey: imageKey,
+			publicDomain: resolved.mediaPublicDomain,
+		})
+		await insertMediaAsset(ctx.db, {
+			id: imageKey,
+			siteId: resolved.mediaSiteId,
+			assetType: 'image',
+			sourceType: 'ai-og-image',
+			originalFilename: 'og-image.png',
+			status: 'ready',
+			objectKey: imageKey,
+			publicUrl,
+			url: publicUrl,
+			width: null,
+			height: null,
+			variantsJson: null,
+			r2Binding: resolved.mediaR2Binding,
+		})
+
+		// Apply the ai_locked_fields write-back gate for ai_og_image_id.
+		const lockedFields = parseLockedFields(item.ai_locked_fields)
+		const writeResult = applyAiWrite({
+			locked: lockedFields,
+			field: 'ai_og_image_id',
+			value: imageKey,
+		})
+
+		if (writeResult.written) {
+			await ctx.db
+				.prepare(
+					'UPDATE content_items SET ai_og_image_id = ?, updated_at = unixepoch() WHERE id = ?',
+				)
+				.bind(imageKey, id)
+				.run()
+		}
+
+		return json({
+			ogImageId: imageKey,
+			url: publicUrl,
+			written: writeResult.written,
+			...(writeResult.written ? {} : { locked: true }),
+		})
+	}
+
+	return {
+		proofreadAndTighten,
+		suggestHeadlines,
+		generateKeyTakeaways,
+		draftMetaDescription,
+		generateOgImage,
+	}
+}

package/src/routes/analytics.ts

@@ -0,0 +1,78 @@
+// src/routes/analytics.ts — Analytics route factory (P5 Task 5).
+// All four handlers are AnalyticsProvider passthrough: KPIs, reads-over-time,
+// top content, and traffic sources. Each handler accepts a ?range= param
+// (7d / 30d / 90d, defaulting to 30d) and returns the ProviderResult
+// {status, data} envelope unchanged — the screen branches on status.
+// No D1 analytics query anywhere; reads/sessions/etc are the provider's domain.
+
+import { nullProviders } from '../providers/null.js'
+import type { CmsProviders, DateRange } from '../providers/types.js'
+import type { Authz, RouteContext } from './context.js'
+import { json } from './context.js'
+
+export interface AnalyticsRouteConfig {
+	authz: Authz
+	providers?: Partial<CmsProviders>
+}
+
+export interface AnalyticsRouteHandlers {
+	kpis(ctx: RouteContext): Promise<Response>
+	readsTimeSeries(ctx: RouteContext): Promise<Response>
+	topContent(ctx: RouteContext): Promise<Response>
+	trafficSources(ctx: RouteContext): Promise<Response>
+	articleDetail(ctx: RouteContext): Promise<Response>
+}
+
+/** Parse ?range=<Nd> from the request URL, defaulting to 30d. */
+function parseRange(url: string): DateRange {
+	const u = new URL(url)
+	const raw = u.searchParams.get('range') ?? '30d'
+	const match = /^(\d+)d$/.exec(raw)
+	const days = match ? Number(match[1]) : 30
+	const to = Math.floor(Date.now() / 1000)
+	const from = to - days * 24 * 60 * 60
+	return { from, to }
+}
+
+export function createAnalyticsRoutes(config: AnalyticsRouteConfig): AnalyticsRouteHandlers {
+	const providers: CmsProviders = { ...nullProviders, ...(config.providers ?? {}) }
+
+	return {
+		async kpis(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const range = parseRange(ctx.request.url)
+			return json(await providers.analytics.getKpis(range))
+		},
+
+		async readsTimeSeries(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const range = parseRange(ctx.request.url)
+			return json(await providers.analytics.getReadsTimeSeries(range))
+		},
+
+		async topContent(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const range = parseRange(ctx.request.url)
+			return json(await providers.analytics.getTopContent(range))
+		},
+
+		async trafficSources(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const range = parseRange(ctx.request.url)
+			return json(await providers.analytics.getTrafficSources(range))
+		},
+
+		async articleDetail(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const url = new URL(ctx.request.url)
+			const range = parseRange(ctx.request.url)
+			const slug = url.searchParams.get('slug') ?? ''
+			return json(await providers.analytics.getArticleDetail(slug, range))
+		},
+	}
+}

package/src/routes/api-keys.ts

@@ -0,0 +1,133 @@
+// api-keys.ts — API key route factories (P7 Task 7).
+//
+// Routes:
+//   POST   /settings/api-keys          create (returns raw key ONCE)
+//   GET    /settings/api-keys          list (masked, no hash/raw)
+//   DELETE /settings/api-keys/:id      revoke
+//
+// All routes gated on requireRole('manage_api_keys') — owner + senior_editor only.
+// The create route returns the rawKey ONCE in the response body with an explicit
+// one-time-reveal envelope; it is never retrievable again.
+//
+// Re-exports verifyCmsApiKey for the content-API gateway (consumed by Fronts at cutover).
+
+import { createApiKey, listApiKeys, revokeApiKey } from '../engine/api-keys.js'
+import type { Authz, Capability, RouteContext } from './context.js'
+import { json } from './context.js'
+
+export { verifyCmsApiKey } from '../engine/api-keys.js'
+
+export interface ApiKeyRouteConfig {
+	authz: Authz
+	workspaceId: string
+}
+
+export interface ApiKeyRouteHandlers {
+	create(ctx: RouteContext): Promise<Response>
+	list(ctx: RouteContext): Promise<Response>
+	revoke(ctx: RouteContext): Promise<Response>
+}
+
+export function createApiKeyRoutes(config: ApiKeyRouteConfig): ApiKeyRouteHandlers {
+	function requireWorkspace(): Response | null {
+		if (!config.workspaceId) {
+			return json(
+				{ error: 'Configuration error: workspaceId is required for API key routes.' },
+				500,
+			)
+		}
+		return null
+	}
+
+	async function gate(ctx: RouteContext): Promise<Response | null> {
+		if (config.authz.requireRole) {
+			return config.authz.requireRole('manage_api_keys' satisfies Capability, ctx)
+		}
+		return null
+	}
+
+	return {
+		// -----------------------------------------------------------------------
+		// POST /settings/api-keys
+		// Creates an API key. Returns the rawKey ONCE — it is never retrievable again.
+		// -----------------------------------------------------------------------
+		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 name = b?.name
+			if (!name || typeof name !== 'string' || !name.trim()) {
+				return json({ error: 'name is required' }, 400)
+			}
+
+			const rawScopes: unknown = b?.scopes ?? []
+			if (!Array.isArray(rawScopes) || rawScopes.some((s) => typeof s !== 'string')) {
+				return json({ error: 'scopes must be an array of strings' }, 400)
+			}
+			const scopes = rawScopes as string[]
+
+			const result = await createApiKey(ctx.db, {
+				workspaceId: config.workspaceId,
+				name: name.trim(),
+				scopes,
+			})
+
+			// Return the rawKey ONCE with an explicit one-time-reveal envelope.
+			// The client MUST copy the key — it cannot be retrieved again.
+			return json(
+				{
+					id: result.id,
+					name: name.trim(),
+					rawKey: result.rawKey,
+					masked: result.masked,
+					oneTimeReveal: true,
+					notice: 'Copy this key now — it will not be shown again.',
+				},
+				201,
+			)
+		},
+
+		// -----------------------------------------------------------------------
+		// GET /settings/api-keys
+		// Returns masked API key list — no hash, no raw key.
+		// -----------------------------------------------------------------------
+		async list(ctx: RouteContext): Promise<Response> {
+			const wsErr = requireWorkspace()
+			if (wsErr) return wsErr
+			const denied = await gate(ctx)
+			if (denied) return denied
+
+			const keys = await listApiKeys(ctx.db, config.workspaceId)
+			return json({ apiKeys: keys })
+		},
+
+		// -----------------------------------------------------------------------
+		// DELETE /settings/api-keys/:id
+		// Revokes (deletes) an API key.
+		// -----------------------------------------------------------------------
+		async revoke(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 revoke to the authenticated caller's workspace (resolved
+			// from config, never the client) — closes a cross-workspace IDOR.
+			await revokeApiKey(ctx.db, id, config.workspaceId)
+			return json({ ok: true, id })
+		},
+	}
+}