emdash 0.29.0 → 0.31.0

package/src/api/handlers/media-upload.ts

@@ -0,0 +1,210 @@
+/**
+ * Programmatic media upload handler (MCP `media_upload` tool).
+ *
+ * Accepts file bytes as base64 or fetches them from an external URL
+ * (SSRF-guarded), then runs the same pipeline as the multipart REST
+ * upload route: allowlist + size validation, content-hash deduplication,
+ * storage upload, image metadata enrichment, and record creation.
+ */
+
+import * as path from "node:path";
+
+import type { Kysely } from "kysely";
+import { ulid } from "ulidx";
+
+import { MediaRepository, type MediaItem } from "../../database/repositories/media.js";
+import type { Database } from "../../database/types.js";
+import { enrichImageMetadata } from "../../media/enrich.js";
+import { matchesMimeAllowlist, normalizeMime } from "../../media/mime.js";
+import { SsrfError, ssrfSafeFetch } from "../../security/ssrf.js";
+import type { Storage } from "../../storage/types.js";
+import { decodeBase64Bytes } from "../../utils/base64.js";
+import { computeContentHash } from "../../utils/hash.js";
+import { CONTENT_TYPE_RE, DEFAULT_MAX_UPLOAD_SIZE, formatFileSize } from "../schemas/media.js";
+import type { ApiResult } from "../types.js";
+import { GLOBAL_UPLOAD_ALLOWLIST } from "./media-allowlist.js";
+
+export interface MediaUploadInput {
+	/** Original filename (e.g. 'logo.png'); the extension is kept on the storage key. */
+	filename: string;
+	/** Base64-encoded file contents. Exactly one of `base64` / `url` must be set. */
+	base64?: string;
+	/** External http(s) URL to fetch the file from. Exactly one of `base64` / `url` must be set. */
+	url?: string;
+	/**
+	 * MIME type. Required with `base64`; optional with `url` (falls back to
+	 * the response's Content-Type header).
+	 */
+	contentType?: string;
+	/** Alt text stored on the media record. */
+	alt?: string;
+	authorId?: string;
+	/** Upload size limit in bytes (defaults to DEFAULT_MAX_UPLOAD_SIZE). */
+	maxUploadSize?: number;
+}
+
+export type MediaUploadResult = ApiResult<{
+	item: MediaItem & { url: string };
+	deduplicated?: boolean;
+}>;
+
+function fail(code: string, message: string): MediaUploadResult {
+	return { success: false, error: { code, message } };
+}
+
+/** Same relative-URL shape the REST media routes return. */
+function withUrl(item: MediaItem): MediaItem & { url: string } {
+	return { ...item, url: `/_emdash/api/media/file/${item.storageKey}` };
+}
+
+/** Strip parameters from a Content-Type header value (e.g. '; charset=...'). */
+function bareMime(headerValue: string): string {
+	return (headerValue.split(";")[0] ?? "").trim();
+}
+
+/**
+ * Acquire the file bytes and MIME type from either the base64 payload or
+ * the external URL. Returns an error result on any validation failure.
+ */
+async function acquireBytes(
+	input: MediaUploadInput,
+	maxUploadSize: number,
+): Promise<{ bytes: Uint8Array; mimeType: string } | MediaUploadResult> {
+	if (input.base64) {
+		if (!input.contentType) {
+			return fail("VALIDATION_ERROR", "contentType is required when uploading base64 data");
+		}
+		// Cheap size precheck on the encoded string (decoded size is ~3/4 of
+		// the base64 length) before allocating the decoded buffer.
+		if ((input.base64.length * 3) / 4 > maxUploadSize) {
+			return fail(
+				"PAYLOAD_TOO_LARGE",
+				`File exceeds maximum size of ${formatFileSize(maxUploadSize)}`,
+			);
+		}
+		try {
+			return { bytes: decodeBase64Bytes(input.base64), mimeType: input.contentType };
+		} catch {
+			return fail("VALIDATION_ERROR", "Invalid base64 data");
+		}
+	}
+
+	// url mode — the caller guarantees exactly one source, so url is set here
+	const url = input.url;
+	if (!url) {
+		return fail("VALIDATION_ERROR", "Provide exactly one of 'base64' or 'url'");
+	}
+	let response: Response;
+	try {
+		response = await ssrfSafeFetch(url, { headers: { accept: "*/*" } });
+	} catch (error) {
+		if (error instanceof SsrfError) {
+			return fail("VALIDATION_ERROR", `URL not allowed: ${error.message}`);
+		}
+		return fail("FETCH_ERROR", "Failed to fetch file from URL");
+	}
+	if (!response.ok) {
+		return fail("FETCH_ERROR", `Failed to fetch file from URL (HTTP ${response.status})`);
+	}
+
+	const contentLength = response.headers.get("Content-Length");
+	if (contentLength && parseInt(contentLength, 10) > maxUploadSize) {
+		return fail(
+			"PAYLOAD_TOO_LARGE",
+			`File exceeds maximum size of ${formatFileSize(maxUploadSize)}`,
+		);
+	}
+
+	const mimeType = input.contentType ?? bareMime(response.headers.get("Content-Type") ?? "");
+	if (!mimeType) {
+		return fail("VALIDATION_ERROR", "Could not determine MIME type — pass contentType explicitly");
+	}
+
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	return { bytes, mimeType };
+}
+
+/**
+ * Upload a media file from base64 data or an external URL.
+ *
+ * Mirrors the REST `POST /_emdash/api/media` route: global MIME allowlist,
+ * size limit, content-hash dedupe (returns the existing item with
+ * `deduplicated: true`), storage upload with cleanup on failure, and
+ * image metadata enrichment (dimensions, blurhash, dominant color).
+ */
+export async function handleMediaUpload(
+	db: Kysely<Database>,
+	storage: Storage,
+	input: MediaUploadInput,
+): Promise<MediaUploadResult> {
+	if (!input.base64 === !input.url) {
+		return fail("VALIDATION_ERROR", "Provide exactly one of 'base64' or 'url'");
+	}
+
+	const rawMax = input.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
+	if (!Number.isFinite(rawMax) || rawMax <= 0) {
+		return fail("CONFIGURATION_ERROR", "Invalid maxUploadSize configuration");
+	}
+
+	const acquired = await acquireBytes(input, rawMax);
+	if ("success" in acquired) return acquired;
+	const { bytes } = acquired;
+
+	// Validate the raw MIME string before normalize/allowlist: normalizeMime
+	// only strips parameters and matchesMimeAllowlist only checks startsWith,
+	// so without this a crafted value like "image/png\r\nX-Evil: 1" would
+	// reach the storage backend's ContentType header and be echoed by the
+	// media file serving route.
+	if (!CONTENT_TYPE_RE.test(acquired.mimeType)) {
+		return fail("VALIDATION_ERROR", "Invalid content type");
+	}
+	const mimeType = normalizeMime(acquired.mimeType);
+
+	if (!matchesMimeAllowlist(mimeType, GLOBAL_UPLOAD_ALLOWLIST)) {
+		return fail("INVALID_TYPE", "File type not allowed");
+	}
+	if (bytes.byteLength > rawMax) {
+		return fail("PAYLOAD_TOO_LARGE", `File exceeds maximum size of ${formatFileSize(rawMax)}`);
+	}
+
+	try {
+		const contentHash = await computeContentHash(bytes);
+		const repo = new MediaRepository(db);
+
+		const existing = await repo.findByContentHash(contentHash);
+		if (existing) {
+			return { success: true, data: { item: withUrl(existing), deduplicated: true } };
+		}
+
+		const storageKey = `${ulid()}${path.extname(input.filename)}`;
+		await storage.upload({ key: storageKey, body: bytes, contentType: mimeType });
+
+		try {
+			const enriched = await enrichImageMetadata(bytes, mimeType);
+			const item = await repo.create({
+				filename: input.filename,
+				mimeType,
+				size: bytes.byteLength,
+				width: enriched.width,
+				height: enriched.height,
+				alt: input.alt,
+				storageKey,
+				contentHash,
+				blurhash: enriched.blurhash,
+				dominantColor: enriched.dominantColor,
+				authorId: input.authorId,
+			});
+			return { success: true, data: { item: withUrl(item) } };
+		} catch (error) {
+			// Don't leave an orphaned object in storage when record creation fails
+			try {
+				await storage.delete(storageKey);
+			} catch {
+				// Ignore cleanup errors
+			}
+			throw error;
+		}
+	} catch {
+		return fail("UPLOAD_ERROR", "Upload failed");
+	}
+}

package/src/api/handlers/media-usage.ts

@@ -1,22 +1,150 @@
 import type { Kysely } from "kysely";
 
+import {
+	MediaUsageRepository,
+	type MediaUsageCollectionIndexStatusScope,
+	type MediaUsageEntryGroup,
+} from "../../database/repositories/media-usage.js";
+import { MediaRepository } from "../../database/repositories/media.js";
+import { InvalidCursorError } from "../../database/repositories/types.js";
 import type { Database } from "../../database/types.js";
+import {
+	CONTENT_MEDIA_USAGE_ADAPTER_ID,
+	CONTENT_MEDIA_USAGE_COLLECTION_SCOPE,
+} from "../../media/usage/content-refresh.js";
 import {
 	repairContentMediaUsageAll,
 	repairContentMediaUsageCollection,
 	type ContentMediaUsageRepairAllResult,
 	type ContentMediaUsageRepairCollectionResult,
 } from "../../media/usage/content-repair.js";
+import { CONTENT_SOURCE_SCHEMA_VERSION } from "../../media/usage/content-snapshots.js";
 import { ErrorCode } from "../errors.js";
-import type { MediaUsageRepairRequest, MediaUsageRepairResponse } from "../schemas/media-usage.js";
+import type {
+	MediaUsageCoverage,
+	MediaUsageCoverageStatus,
+	MediaUsageDetailsResponse,
+	MediaUsageEntryDetail,
+	MediaUsageOccurrenceDetail,
+	MediaUsageRepairRequest,
+	MediaUsageRepairResponse,
+	MediaUsageSummary,
+} from "../schemas/media-usage.js";
 import type { ApiResult } from "../types.js";
 
-export type { MediaUsageRepairRequest, MediaUsageRepairResponse } from "../schemas/media-usage.js";
+export type {
+	MediaUsageCoverage,
+	MediaUsageCoverageStatus,
+	MediaUsageDetailsResponse,
+	MediaUsageEntryDetail,
+	MediaUsageOccurrenceDetail,
+	MediaUsageSourceDetail,
+	MediaUsageRepairRequest,
+	MediaUsageRepairResponse,
+	MediaUsageSummary,
+} from "../schemas/media-usage.js";
 
 type ContentMediaUsageRepairResult =
 	| ContentMediaUsageRepairCollectionResult
 	| ContentMediaUsageRepairAllResult;
 
+export function aggregateMediaUsageCoverageStatus(
+	scopes: readonly MediaUsageCollectionIndexStatusScope[],
+): MediaUsageCoverageStatus {
+	const statuses = scopes.map(normalizeMediaUsageCoverageStatus);
+	if (statuses.every((status) => status === "complete")) {
+		return "complete";
+	}
+	if (statuses.includes("unknown")) return "unknown";
+	if (statuses.includes("running")) return "running";
+	if (statuses.includes("stale")) return "stale";
+	if (statuses.includes("partial")) return "partial";
+	if (statuses.every((status) => status === "never")) return "never";
+	if (statuses.every((status) => status === "failed")) return "failed";
+	return "partial";
+}
+
+export async function handleMediaUsageSummaries(
+	db: Kysely<Database>,
+	mediaIds: readonly string[],
+	options: { includeCount: boolean },
+): Promise<ApiResult<Record<string, MediaUsageSummary>>> {
+	if (mediaIds.length === 0) return { success: true, data: {} };
+
+	try {
+		const repository = new MediaUsageRepository(db);
+		const coverage = await loadMediaUsageCoverage(repository);
+		const counts = options.includeCount
+			? await repository.findActiveEntryCountsByMediaIds(mediaIds)
+			: null;
+		const summaries: Record<string, MediaUsageSummary> = {};
+
+		for (const mediaId of new Set(mediaIds)) {
+			summaries[mediaId] = {
+				count: counts ? (counts.get(mediaId) ?? 0) : null,
+				coverage,
+			};
+		}
+
+		return { success: true, data: summaries };
+	} catch (error) {
+		console.error("[media-usage] summary read failed:", error);
+		return {
+			success: false,
+			error: {
+				code: ErrorCode.MEDIA_USAGE_READ_ERROR,
+				message: "Failed to read media usage",
+			},
+		};
+	}
+}
+
+export async function handleMediaUsageDetails(
+	db: Kysely<Database>,
+	mediaId: string,
+	options: { cursor?: string; limit?: number },
+): Promise<ApiResult<MediaUsageDetailsResponse>> {
+	try {
+		const media = await new MediaRepository(db).findById(mediaId);
+		if (!media) {
+			return {
+				success: false,
+				error: {
+					code: ErrorCode.NOT_FOUND,
+					message: `Media item not found: ${mediaId}`,
+				},
+			};
+		}
+
+		const repository = new MediaUsageRepository(db);
+		const coverage = await loadMediaUsageCoverage(repository);
+		const page = await repository.findCurrentEntryUsagePageByMediaId(mediaId, options);
+		return {
+			success: true,
+			data: {
+				items: page.items.map(toMediaUsageEntryDetail),
+				...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+				coverage,
+			},
+		};
+	} catch (error) {
+		if (error instanceof InvalidCursorError) {
+			return {
+				success: false,
+				error: { code: ErrorCode.INVALID_CURSOR, message: error.message },
+			};
+		}
+		console.error("[media-usage] detail read failed:", error);
+		return {
+			success: false,
+			error: {
+				code: ErrorCode.MEDIA_USAGE_READ_ERROR,
+				message: "Failed to read media usage",
+			},
+		};
+	}
+}
+
 export async function handleMediaUsageRepair(
 	db: Kysely<Database>,
 	input: MediaUsageRepairRequest,
@@ -78,3 +206,84 @@ function toMediaUsageRepairCollectionSummary(result: ContentMediaUsageRepairColl
 		completedAt: result.completedAt,
 	};
 }
+
+function normalizeMediaUsageCoverageStatus(
+	scope: MediaUsageCollectionIndexStatusScope,
+): MediaUsageCoverageStatus {
+	if (scope.status === null) return "never";
+	if (scope.status === "complete") {
+		return scope.schemaVersion === CONTENT_SOURCE_SCHEMA_VERSION ? "complete" : "stale";
+	}
+	if (
+		scope.status === "never" ||
+		scope.status === "running" ||
+		scope.status === "partial" ||
+		scope.status === "failed" ||
+		scope.status === "stale"
+	) {
+		return scope.status;
+	}
+	return "unknown";
+}
+
+async function loadMediaUsageCoverage(
+	repository: MediaUsageRepository,
+): Promise<MediaUsageCoverage> {
+	const scopes = await repository.findCollectionIndexStatusScopes({
+		adapterId: CONTENT_MEDIA_USAGE_ADAPTER_ID,
+		scopeType: CONTENT_MEDIA_USAGE_COLLECTION_SCOPE,
+	});
+	return {
+		scope: "all_content_collections",
+		status: aggregateMediaUsageCoverageStatus(scopes),
+	};
+}
+
+function toMediaUsageEntryDetail(group: MediaUsageEntryGroup): MediaUsageEntryDetail {
+	const preferred =
+		group.sources.find(({ source }) => source.sourceVariant === "draft_overlay") ??
+		group.sources.find(({ source }) => source.sourceVariant === "columns");
+	if (!preferred) {
+		throw new Error("Media usage entry has no supported source");
+	}
+
+	return {
+		collection: group.collectionSlug,
+		contentId: group.contentId,
+		title: preferred.source.contentTitle,
+		slug: preferred.source.contentSlug,
+		locale: preferred.source.locale,
+		status: preferred.source.contentStatus,
+		scheduledAt: preferred.source.contentScheduledAt,
+		deletedAt: group.contentDeletedAt,
+		sources: group.sources.flatMap(({ source, occurrences }) => {
+			if (source.sourceVariant !== "columns" && source.sourceVariant !== "draft_overlay") {
+				return [];
+			}
+			return [
+				{
+					variant: source.sourceVariant,
+					occurrences: occurrences.map((occurrence) => ({
+						fieldSlug: occurrence.fieldSlug,
+						fieldPath: occurrence.fieldPath,
+						occurrenceIndex: occurrence.occurrenceIndex,
+						referenceType: normalizeMediaUsageReferenceType(occurrence.referenceType),
+					})),
+				},
+			];
+		}),
+	};
+}
+
+function normalizeMediaUsageReferenceType(
+	referenceType: string,
+): MediaUsageOccurrenceDetail["referenceType"] {
+	if (
+		referenceType === "image_field" ||
+		referenceType === "file_field" ||
+		referenceType === "portable_text_image"
+	) {
+		return referenceType;
+	}
+	return "unknown";
+}

package/src/api/handlers/menus.ts

@@ -25,7 +25,7 @@ import {
 	type UpdateMenuItemInput as UpdateMenuItemRepoInput,
 } from "../../database/repositories/menu.js";
 import type { Database } from "../../database/types.js";
-import { getI18nConfig } from "../../i18n/config.js";
+import { getI18nConfig, resolveConfiguredLocale } from "../../i18n/config.js";
 import type { ApiResult } from "../types.js";
 
 // Re-export entity types so route files and tests can import them from the
@@ -89,7 +89,8 @@ async function resolveMenu(
 	name: string,
 	options: { locale?: string },
 ): Promise<ResolveMenuResult> {
-	const matches = await repo.findByName(name, options);
+	const locale = options.locale ? resolveConfiguredLocale(options.locale) : undefined;
+	const matches = await repo.findByName(name, { locale });
 	if (matches.length === 0) {
 		return {
 			success: false,
@@ -124,7 +125,8 @@ export async function handleMenuList(
 ): Promise<ApiResult<MenuListItem[]>> {
 	try {
 		const repo = new MenuRepository(db);
-		const items = await repo.findMany(options);
+		const locale = options.locale ? resolveConfiguredLocale(options.locale) : undefined;
+		const items = await repo.findMany({ locale });
 		return { success: true, data: items };
 	} catch {
 		return {
@@ -175,7 +177,9 @@ export async function handleMenuCreate(
 
 		// Duplicate guard: same (name, locale). Falls back to the configured
 		// defaultLocale to match the column DEFAULT set by migration 036.
-		const effectiveLocale = input.locale ?? getI18nConfig()?.defaultLocale ?? "en";
+		const effectiveLocale = input.locale
+			? resolveConfiguredLocale(input.locale)
+			: (getI18nConfig()?.defaultLocale ?? "en");
 		if (await repo.existsByNameAndLocale(input.name, effectiveLocale)) {
 			return {
 				success: false,
@@ -188,7 +192,7 @@ export async function handleMenuCreate(
 			};
 		}
 
-		const menu = await repo.create(input);
+		const menu = await repo.create({ ...input, locale: effectiveLocale });
 		return { success: true, data: menu };
 	} catch {
 		return {
@@ -212,7 +216,8 @@ export async function handleMenuGet(
 ): Promise<ApiResult<MenuWithItems>> {
 	try {
 		const repo = new MenuRepository(db);
-		const matches = await repo.findByName(name, options);
+		const locale = options.locale ? resolveConfiguredLocale(options.locale) : undefined;
+		const matches = await repo.findByName(name, { locale });
 		if (matches.length === 0) {
 			return {
 				success: false,

package/src/api/handlers/oauth-authorization.ts

@@ -16,8 +16,8 @@ import type { Kysely } from "kysely";
 import {
 	generatePrefixedToken,
 	hashApiToken,
+	isValidScope,
 	TOKEN_PREFIXES,
-	VALID_SCOPES,
 } from "../../auth/api-tokens.js";
 import { withTransaction } from "../../database/transaction.js";
 import type { Database } from "../../database/types.js";
@@ -87,11 +87,7 @@ export { validateRedirectUri };
 function normalizeScopes(requested?: string): string[] {
 	if (!requested) return [];
 
-	const validSet = new Set<string>(VALID_SCOPES);
-	const scopes = requested
-		.split(" ")
-		.filter(Boolean)
-		.filter((s) => validSet.has(s));
+	const scopes = requested.split(" ").filter(Boolean).filter(isValidScope);
 
 	return scopes;
 }