emdash 0.35.0 → 0.36.0

package/src/astro/routes/api/admin/plugins/registry/artifact.ts

@@ -10,9 +10,9 @@
  * Trust model (CRITICAL): the proxy never accepts an artifact URL from the
  * client. The caller addresses an artifact by its coordinates
  * `(did, slug, version, kind, index)`; the server resolves the *declared*
- * URL from the validated release record fetched from the configured
- * aggregator. The proxy can therefore only ever fetch a URL the publisher
- * declared in their signed release — not an arbitrary caller-supplied URL.
+ * artifact source from the validated release record fetched from the
+ * configured aggregator. Blob-backed images resolve to the record-scoped
+ * Cumulus deployment; URL artifacts retain the external fallback.
  *
  * The publisher-declared URL is still untrusted (an attacker who controls a
  * publisher record, or the aggregator, can point it anywhere), so the
@@ -22,13 +22,24 @@
  */
 
 import type { Did } from "@atcute/lexicons";
+import { evaluateRegistryReleaseWithdrawal } from "@emdash-cms/registry-client/withdrawal";
+import { NSID, RECORD_SCOPED_BLOB_CACHE_TYPE } from "@emdash-cms/registry-lexicons";
+import {
+	recordScopedImageCacheUrl,
+	resolvePublisherPdsEndpoint,
+	type ReleaseArtifactReference,
+} from "@emdash-cms/registry-verification/artifact";
+import { multihashFromBlobCid } from "@emdash-cms/registry-verification/checksum";
+import { fetchVerifiedResource } from "@emdash-cms/registry-verification/fetch";
 import type { APIRoute } from "astro";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError } from "#api/error.js";
-import { assertSafeArtifactUrl } from "#api/index.js";
+import { verifyChecksum } from "#api/handlers/registry.js";
 
+import { fetchRegistryArtifactUrl } from "../../../../../../registry/artifact-fetch.js";
 import { coerceRegistryConfig, validateAggregatorUrl } from "../../../../../../registry/config.js";
+import { resolveAndValidateExternalUrlTarget } from "../../../../../../security/ssrf.js";
 
 export const prerender = false;
 
@@ -39,15 +50,9 @@ export const prerender = false;
  * executes when navigated to as a top-level document), and the publisher
  * supplies the bytes. Rather than serve it behind mitigations, we refuse it
  * end-to-end — the publish CLI rejects SVG artifacts too, so a conforming
- * release never references one. AVIF is included.
+ * release never references one.
  */
-const ALLOWED_IMAGE_TYPES = new Set([
-	"image/png",
-	"image/jpeg",
-	"image/webp",
-	"image/gif",
-	"image/avif",
-]);
+const ALLOWED_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
 
 /** Artifact kinds the proxy can resolve. `screenshot` additionally needs `index`. */
 const ALLOWED_KINDS = new Set(["icon", "banner", "screenshot"]);
@@ -56,11 +61,12 @@ const ALLOWED_KINDS = new Set(["icon", "banner", "screenshot"]);
 const DID_PATTERN = /^did:[a-z]+:.+/;
 /** Slug grammar: ASCII letter then letters / digits / `-` / `_`. Mirrors the install route. */
 const SLUG_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+const CID_PATTERN = /^b[a-z2-7]+$/;
 /** Non-negative integer, for the screenshot index param. */
 const INDEX_PATTERN = /^\d+$/;
 
 /** Cap proxied images so a hostile host can't stream an unbounded body. */
-const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 1024 * 1024;
 
 /** Redirect hops to follow, re-validating each target against SSRF rules. */
 const MAX_REDIRECTS = 5;
@@ -98,40 +104,89 @@ function timedFetch(totalDeadline: number): typeof fetch {
 }
 
 /**
- * Narrow one entry of a release's `artifacts` map to a usable image URL.
+ * Narrow one entry of a release's `artifacts` map to a usable image source.
  *
  * The embedded `release` record is lexicon-validated at the DiscoveryClient
  * boundary, but `artifacts` is an aggregator pass-through typed `unknown`, so
- * the entry's shape is not guaranteed. Returns the `url` string only when the
- * value is an object carrying a non-empty string `url`; everything else
- * (missing key, wrong type, no `url`) yields `null`.
+ * the entry's shape is not guaranteed.
  */
-function declaredArtifactUrl(value: unknown): string | null {
+type DeclaredArtifact = ReleaseArtifactReference & { requiresAuth: boolean };
+
+interface ResolvedArtifact {
+	artifact: DeclaredArtifact;
+	record: {
+		did: string;
+		collection: string;
+		rkey: string;
+		cid: string;
+	};
+	imageCacheUrl?: URL;
+}
+
+function declaredArtifact(value: unknown): DeclaredArtifact | null {
 	if (!value || typeof value !== "object") return null;
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed to non-null object above; url checked below
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed to non-null object above; fields checked below
 	const entry = value as Record<string, unknown>;
 	const url = entry.url;
-	if (typeof url !== "string" || url.length === 0) return null;
-	return url;
+	const blob = entry.blob;
+	const checksum = entry.checksum;
+	const ref = objectProperty(blob, "ref");
+	const blobCid = objectProperty(ref, "$link");
+	const blobMimeType = objectProperty(blob, "mimeType");
+	const blobSize = objectProperty(blob, "size");
+	const hasUrl = typeof url === "string" && url.length > 0;
+	const hasBlob =
+		typeof blobCid === "string" &&
+		blobCid.length > 0 &&
+		typeof blobMimeType === "string" &&
+		Number.isSafeInteger(blobSize) &&
+		Number(blobSize) >= 0;
+	if ((!hasUrl && !hasBlob) || typeof checksum !== "string" || checksum.length === 0) {
+		return null;
+	}
+	return {
+		...(hasUrl ? { url } : {}),
+		...(hasBlob
+			? {
+					blob: {
+						$type: "blob" as const,
+						ref: { $link: blobCid },
+						mimeType: blobMimeType,
+						size: Number(blobSize),
+					},
+				}
+			: {}),
+		checksum,
+		requiresAuth: entry.requiresAuth === true,
+	};
 }
 
 /**
- * Resolve the declared artifact URL for `(kind, index)` from a release's
+ * Resolve the declared artifact source for `(kind, index)` from a release's
  * `artifacts` map. Returns `null` when the requested artifact isn't present
  * or doesn't carry a usable URL.
  */
-function resolveDeclaredUrl(artifacts: unknown, kind: string, index: number): string | null {
+function resolveDeclaredArtifact(
+	artifacts: unknown,
+	kind: string,
+	index: number,
+): DeclaredArtifact | null {
 	if (!artifacts || typeof artifacts !== "object") return null;
 	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed to non-null object above; each entry shape-narrowed by declaredArtifactUrl
 	const map = artifacts as Record<string, unknown>;
 
-	if (kind === "icon") return declaredArtifactUrl(map.icon);
-	if (kind === "banner") return declaredArtifactUrl(map.banner);
+	if (kind === "icon") return declaredArtifact(map.icon);
+	if (kind === "banner") return declaredArtifact(map.banner);
 	// kind === "screenshot"
 	const screenshots = map.screenshots;
 	if (!Array.isArray(screenshots)) return null;
 	if (index < 0 || index >= screenshots.length) return null;
-	return declaredArtifactUrl(screenshots[index]);
+	return declaredArtifact(screenshots[index]);
+}
+
+function objectProperty(value: unknown, key: string): unknown {
+	if (!value || typeof value !== "object") return undefined;
+	return Object.getOwnPropertyDescriptor(value, key)?.value;
 }
 
 export const GET: APIRoute = async ({ url, locals }) => {
@@ -146,12 +201,13 @@ export const GET: APIRoute = async ({ url, locals }) => {
 
 	const did = url.searchParams.get("did");
 	const slug = url.searchParams.get("slug");
+	const cid = url.searchParams.get("cid");
 	const kind = url.searchParams.get("kind");
 	const versionParam = url.searchParams.get("version");
 	const indexParam = url.searchParams.get("index");
 
-	if (!did || !slug || !kind) {
-		return apiError("INVALID_REQUEST", "Missing did, slug, or kind", 400);
+	if (!did || !slug || !cid || !kind) {
+		return apiError("INVALID_REQUEST", "Missing did, slug, cid, or kind", 400);
 	}
 	if (did.length > 256 || !DID_PATTERN.test(did)) {
 		return apiError("INVALID_REQUEST", "Invalid did", 400);
@@ -159,6 +215,9 @@ export const GET: APIRoute = async ({ url, locals }) => {
 	if (slug.length > 64 || !SLUG_PATTERN.test(slug)) {
 		return apiError("INVALID_REQUEST", "Invalid slug", 400);
 	}
+	if (cid.length > 256 || !CID_PATTERN.test(cid)) {
+		return apiError("INVALID_REQUEST", "Invalid release CID", 400);
+	}
 	if (!ALLOWED_KINDS.has(kind)) {
 		return apiError("INVALID_REQUEST", "Invalid kind", 400);
 	}
@@ -196,73 +255,56 @@ export const GET: APIRoute = async ({ url, locals }) => {
 	}
 
 	// Resolve the publisher-declared artifact URL from the release record.
-	let declaredUrl: string;
+	let resolvedArtifact: ResolvedArtifact;
 	try {
-		const resolved = await resolveArtifactUrl(registryConfig, did, slug, version, kind, index);
+		const resolved = await resolveArtifact(registryConfig, did, slug, version, cid, kind, index);
 		if (resolved === null) {
 			return apiError("ARTIFACT_NOT_FOUND", "Artifact not found", 404);
 		}
-		declaredUrl = resolved;
+		resolvedArtifact = resolved;
 	} catch {
 		return apiError("ARTIFACT_RESOLVE_FAILED", "Failed to resolve artifact", 502);
 	}
-
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
 	try {
-		// `assertSafeArtifactUrl` validates scheme / credentials / loopback +
-		// resolves the hostname and rejects private / link-local / metadata
-		// targets (DNS-rebinding defence). It throws a plain Error on any
-		// block, so a rejection here means the URL is unsafe.
-		let current: URL;
-		try {
-			current = await assertSafeArtifactUrl(declaredUrl);
-		} catch {
-			return apiError("ARTIFACT_URL_REJECTED", "Artifact URL is not allowed", 400);
-		}
-
-		let response: Response;
-		for (let hop = 0; ; hop++) {
-			response = await fetch(current.href, { redirect: "manual", signal: controller.signal });
-			if (response.status < 300 || response.status >= 400) break;
-			const location = response.headers.get("location");
-			if (!location) break;
-			if (hop === MAX_REDIRECTS) {
-				return apiError("ARTIFACT_URL_REJECTED", "Too many redirects", 502);
+		const fetchOptions = proxyFetchOptions(controller.signal);
+		let bytes: Uint8Array | undefined;
+		let headers: Headers | undefined;
+		let checksumValid: boolean | undefined;
+		if (resolvedArtifact.imageCacheUrl) {
+			const transformed = await fetchVerifiedResource(resolvedArtifact.imageCacheUrl, fetchOptions);
+			if (transformed.success) {
+				bytes = transformed.value.bytes;
+				headers = transformed.value.headers;
 			}
-			let next: URL;
-			try {
-				next = await assertSafeArtifactUrl(new URL(location, current).href);
-			} catch {
-				return apiError("ARTIFACT_URL_REJECTED", "Redirect target is not allowed", 400);
-			}
-			current = next;
 		}
-
-		if (!response.ok) {
-			return apiError("ARTIFACT_FETCH_FAILED", "Failed to fetch artifact", 502);
+		if (!bytes || !headers) {
+			const raw = await fetchRawArtifact(resolvedArtifact, fetchOptions);
+			if (!raw.success) return artifactFetchError(raw.code);
+			bytes = raw.bytes;
+			headers = raw.headers;
+			checksumValid = raw.checksumValid;
 		}
 
 		// Content-Type allowlist: only image types are proxied. A non-image
 		// (HTML error page, JSON, octet-stream) is rejected so the admin
 		// never renders publisher-controlled markup from the EmDash origin.
-		const rawType = response.headers.get("content-type") ?? "";
+		const rawType = headers.get("content-type") ?? "";
 		const contentType = rawType.split(";", 1)[0]!.trim().toLowerCase();
 		if (!ALLOWED_IMAGE_TYPES.has(contentType)) {
 			return apiError("ARTIFACT_NOT_IMAGE", "Artifact is not an allowed image type", 415);
 		}
 
-		const declaredLength = response.headers.get("content-length");
+		const declaredLength = headers.get("content-length");
 		if (declaredLength) {
 			const declared = Number(declaredLength);
 			if (Number.isFinite(declared) && declared > MAX_IMAGE_BYTES) {
 				return apiError("ARTIFACT_TOO_LARGE", "Artifact exceeds size limit", 413);
 			}
 		}
-
-		const bytes = await readCapped(response, MAX_IMAGE_BYTES);
-		if (bytes === null) {
-			return apiError("ARTIFACT_TOO_LARGE", "Artifact exceeds size limit", 413);
+		if (checksumValid === false) {
+			return artifactFetchError("CHECKSUM_MISMATCH");
 		}
 
 		// Only the allowlisted Content-Type is forwarded — never copy other
@@ -299,22 +341,25 @@ export const GET: APIRoute = async ({ url, locals }) => {
  * left untouched, so a small amount of resolution-pattern duplication is
  * accepted here.
  */
-async function resolveArtifactUrl(
+async function resolveArtifact(
 	registryConfig: { aggregatorUrl: string; acceptLabelers?: string },
 	did: string,
 	slug: string,
 	version: string | undefined,
+	cid: string,
 	kind: string,
 	index: number,
-): Promise<string | null> {
+): Promise<ResolvedArtifact | null> {
 	// Lazy-load the discovery client so the `@atcute/client` dependency only
 	// loads when the registry path is exercised.
-	const { DiscoveryClient } = await import("@emdash-cms/registry-client/discovery");
+	const { DiscoveryClient, registryLabelerPolicy } =
+		await import("@emdash-cms/registry-client/discovery");
 
 	const aggregatorDeadline = Date.now() + AGGREGATOR_TOTAL_BUDGET_MS;
 	const discovery = new DiscoveryClient({
 		aggregatorUrl: registryConfig.aggregatorUrl,
 		acceptLabelers: registryConfig.acceptLabelers,
+		labelerPolicy: registryLabelerPolicy(registryConfig.acceptLabelers),
 		fetch: timedFetch(aggregatorDeadline),
 	});
 
@@ -347,9 +392,65 @@ async function resolveArtifactUrl(
 		return undefined;
 	})();
 
-	if (!releaseView?.release) return null;
+	if (
+		!releaseView?.release ||
+		releaseView.cid !== cid ||
+		releaseView.did !== publisherDid ||
+		releaseView.package !== slug ||
+		(version !== undefined && releaseView.version !== version) ||
+		releaseView.release.package !== slug ||
+		releaseView.release.version !== releaseView.version
+	) {
+		return null;
+	}
+	if (evaluateRegistryReleaseWithdrawal(releaseView, discovery.labelerPolicy).withdrawn) {
+		return null;
+	}
+
+	const descriptor = resolveDeclaredArtifact(releaseView.release.artifacts, kind, index);
+	if (!descriptor || descriptor.requiresAuth || releaseView.release.auth !== undefined) return null;
+	const blobCid = descriptor.blob?.ref.$link;
+	let imageCacheUrl: URL | undefined;
+	if (blobCid) {
+		const expected = multihashFromBlobCid(blobCid);
+		if (!expected.success || expected.value !== descriptor.checksum) return null;
+		const rkey = `${slug}:${releaseView.version}`;
+		const serviceEndpoint = releaseView.artifactCaches
+			.map(recordScopedCacheEndpoint)
+			.find((value) => value !== null);
+		if (serviceEndpoint) {
+			const preset = kind === "icon" ? "avatar" : kind === "banner" ? "banner" : "feed_thumbnail";
+			const cacheUrl = recordScopedImageCacheUrl(
+				serviceEndpoint,
+				preset,
+				{
+					did,
+					collection: NSID.packageRelease,
+					rkey,
+					cid: releaseView.cid,
+				},
+				blobCid,
+			);
+			if (!cacheUrl.success) return null;
+			imageCacheUrl = cacheUrl.value;
+		}
+	}
+	return {
+		artifact: descriptor,
+		record: {
+			did,
+			collection: NSID.packageRelease,
+			rkey: `${slug}:${releaseView.version}`,
+			cid: releaseView.cid,
+		},
+		...(imageCacheUrl ? { imageCacheUrl } : {}),
+	};
+}
 
-	return resolveDeclaredUrl(releaseView.release.artifacts, kind, index);
+function recordScopedCacheEndpoint(value: unknown): string | null {
+	if (objectProperty(value, "$type") !== RECORD_SCOPED_BLOB_CACHE_TYPE) return null;
+	const endpoint = objectProperty(value, "serviceEndpoint");
+	return typeof endpoint === "string" ? endpoint : null;
 }
 
 /**
@@ -357,32 +458,81 @@ async function resolveArtifactUrl(
  * `null` when the cap is breached (the streamed body lied about / omitted
  * Content-Length). The cap is the real defence against an unbounded body.
  */
-async function readCapped(response: Response, limit: number): Promise<Uint8Array | null> {
-	const body = response.body;
-	if (!body) {
-		const buf = new Uint8Array(await response.arrayBuffer());
-		return buf.length > limit ? null : buf;
+function proxyFetchOptions(signal: AbortSignal) {
+	return {
+		fetch: async (url: URL, init: RequestInit) =>
+			fetchRegistryArtifactUrl(url.href, {
+				signal: init.signal instanceof AbortSignal ? init.signal : signal,
+				maxResponseBytes: MAX_IMAGE_BYTES,
+			}),
+		resolveHostname: async (hostname: string) =>
+			(await resolveAndValidateExternalUrlTarget(`https://${hostname}/`)).addresses,
+		allowHttpLocalhost: import.meta.env.DEV,
+		maxBytes: MAX_IMAGE_BYTES,
+		maxRedirects: MAX_REDIRECTS,
+		totalTimeoutMs: FETCH_TIMEOUT_MS,
+	};
+}
+
+async function fetchRawArtifact(
+	resolved: ResolvedArtifact,
+	options: ReturnType<typeof proxyFetchOptions>,
+): Promise<
+	| { success: true; bytes: Uint8Array; headers: Headers; checksumValid: boolean }
+	| { success: false; code: string }
+> {
+	const urls: URL[] = [];
+	const blobCid = resolved.artifact.blob?.ref.$link;
+	let lastCode = "FETCH_FAILED";
+	let checksumMismatch: { bytes: Uint8Array; headers: Headers } | undefined;
+	if (blobCid) {
+		const pds = await resolvePublisherPdsEndpoint(resolved.record.did, options);
+		if (pds.success) {
+			const url = new URL("/xrpc/com.atproto.sync.getBlob", pds.value);
+			url.searchParams.set("did", resolved.record.did);
+			url.searchParams.set("cid", blobCid);
+			urls.push(url);
+		} else {
+			lastCode = pds.error.code;
+		}
 	}
-	const reader = body.getReader();
-	const chunks: Uint8Array[] = [];
-	let total = 0;
-	while (true) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		if (value) {
-			total += value.length;
-			if (total > limit) {
-				await reader.cancel();
-				return null;
-			}
-			chunks.push(value);
+	if (resolved.artifact.url) urls.push(new URL(resolved.artifact.url));
+
+	for (const url of urls) {
+		const fetched = await fetchVerifiedResource(url, options);
+		if (!fetched.success) {
+			lastCode = fetched.error.code;
+			continue;
+		}
+		if (!(await verifyChecksum(fetched.value.bytes, resolved.artifact.checksum))) {
+			lastCode = "CHECKSUM_MISMATCH";
+			checksumMismatch = { bytes: fetched.value.bytes, headers: fetched.value.headers };
+			continue;
 		}
+		return {
+			success: true,
+			bytes: fetched.value.bytes,
+			headers: fetched.value.headers,
+			checksumValid: true,
+		};
+	}
+	if (checksumMismatch) return { success: true, ...checksumMismatch, checksumValid: false };
+	return { success: false, code: lastCode };
+}
+
+function artifactFetchError(code: string): Response {
+	if (code === "CHECKSUM_MISMATCH") {
+		return apiError(
+			"ARTIFACT_CHECKSUM_MISMATCH",
+			"Artifact bytes do not match the approved release record",
+			502,
+		);
+	}
+	if (code === "RESOURCE_SIZE_EXCEEDED") {
+		return apiError("ARTIFACT_TOO_LARGE", "Artifact exceeds size limit", 413);
 	}
-	const combined = new Uint8Array(total);
-	let offset = 0;
-	for (const chunk of chunks) {
-		combined.set(chunk, offset);
-		offset += chunk.length;
+	if (code === "HOST_REJECTED" || code === "INVALID_URL") {
+		return apiError("ARTIFACT_URL_REJECTED", "Artifact URL is not allowed", 400);
 	}
-	return combined;
+	return apiError("ARTIFACT_FETCH_FAILED", "Failed to fetch artifact", 502);
 }

package/src/astro/routes/api/auth/me.ts

@@ -15,16 +15,28 @@ import { authMeActionBody } from "#api/schemas.js";
 import { UserRepository } from "#db/repositories/user.js";
 
 export const GET: APIRoute = async ({ locals }) => {
-	const { user } = locals;
+	const { user, emdash } = locals;
 
 	if (!user) {
 		return apiError("NOT_AUTHENTICATED", "Not authenticated", 401);
 	}
 
+	let userData = user.data;
+	if (locals.__playgroundDb) {
+		if (!emdash) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+		try {
+			const persistedUser = await new UserRepository(emdash.db).findById(user.id);
+			if (persistedUser) userData = persistedUser.data;
+		} catch (error) {
+			return handleError(error, "Failed to fetch current user", "CURRENT_USER_ERROR");
+		}
+	}
+
 	// Check if this is the user's first login (for welcome modal).
 	// The flag is persisted in the user's `data` JSON column so it survives
 	// session expiry / rotation.
-	const isFirstLogin = !user.data?.welcomeDismissed;
+	const isFirstLogin = !userData?.welcomeDismissed;
 
 	// Return safe user info (no sensitive data)
 	return apiSuccess({

package/src/astro/routes/api/media/[id].ts

@@ -92,6 +92,9 @@ export const PUT: APIRoute = async ({ params, request, locals }) => {
 			caption: body.caption,
 			width: body.width,
 			height: body.height,
+			folderId: body.folderId,
+			focalX: body.focalX,
+			focalY: body.focalY,
 		});
 
 		return unwrapResult(result);

package/src/astro/routes/api/media/folders/[id].ts

@@ -0,0 +1,55 @@
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, unwrapResult } from "#api/error.js";
+import {
+	handleMediaFolderDelete,
+	handleMediaFolderGet,
+	handleMediaFolderUpdate,
+} from "#api/handlers/media-folders.js";
+import { isParseError, parseBody } from "#api/parse.js";
+import { mediaFolderBody, mediaFolderIdSchema } from "#api/schemas.js";
+
+export const prerender = false;
+
+function parseFolderId(id: string | undefined): string | Response {
+	const result = mediaFolderIdSchema.safeParse(id);
+	return result.success
+		? result.data
+		: apiError("VALIDATION_ERROR", "Invalid media folder ID", 400);
+}
+
+export const GET: APIRoute = async ({ params, locals }) => {
+	const { emdash, user } = locals;
+	const denied = requirePerm(user, "media:read");
+	if (denied) return denied;
+	if (!emdash) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+	const id = parseFolderId(params.id);
+	if (id instanceof Response) return id;
+	return unwrapResult(await handleMediaFolderGet(emdash.db, id));
+};
+
+export const PUT: APIRoute = async ({ params, request, locals }) => {
+	const { emdash, user } = locals;
+	const denied = requirePerm(user, "media:edit_any");
+	if (denied) return denied;
+	if (!emdash) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+	const id = parseFolderId(params.id);
+	if (id instanceof Response) return id;
+	const body = await parseBody(request, mediaFolderBody);
+	if (isParseError(body)) return body;
+	return unwrapResult(await handleMediaFolderUpdate(emdash.db, id, body));
+};
+
+export const DELETE: APIRoute = async ({ params, locals }) => {
+	const { emdash, user } = locals;
+	const denied = requirePerm(user, "media:edit_any");
+	if (denied) return denied;
+	if (!emdash) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+	const id = parseFolderId(params.id);
+	if (id instanceof Response) return id;
+	return unwrapResult(await handleMediaFolderDelete(emdash.db, id));
+};

package/src/astro/routes/api/media/folders/index.ts

@@ -0,0 +1,37 @@
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, unwrapResult } from "#api/error.js";
+import { handleMediaFolderCreate, handleMediaFolderList } from "#api/handlers/media-folders.js";
+import { isParseError, parseBody, parseQuery } from "#api/parse.js";
+import { mediaFolderBody, mediaFolderListQuery } from "#api/schemas.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ request, locals }) => {
+	const { emdash, user } = locals;
+	const denied = requirePerm(user, "media:read");
+	if (denied) return denied;
+	if (!emdash) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+	const query = parseQuery(new URL(request.url), mediaFolderListQuery);
+	if (isParseError(query)) return query;
+	return unwrapResult(
+		await handleMediaFolderList(emdash.db, {
+			limit: query.limit,
+			cursor: query.cursor,
+			q: query.q,
+		}),
+	);
+};
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const { emdash, user } = locals;
+	const denied = requirePerm(user, "media:edit_any");
+	if (denied) return denied;
+	if (!emdash) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+	const body = await parseBody(request, mediaFolderBody);
+	if (isParseError(body)) return body;
+	return unwrapResult(await handleMediaFolderCreate(emdash.db, body), 201);
+};

package/src/astro/routes/api/media.ts

@@ -55,9 +55,11 @@ export const GET: APIRoute = async ({ request, locals }) => {
 
 	const result = await emdash.handleMediaList({
 		cursor: query.cursor,
+		page: query.page,
 		limit: query.limit,
 		mimeType: query.mimeType,
 		q: query.q,
+		folderId: query.folderId === "unfiled" ? null : query.folderId,
 	});
 
 	if (!result.success) {
@@ -67,7 +69,11 @@ export const GET: APIRoute = async ({ request, locals }) => {
 	// Add URL to each media item (relative URLs for portability)
 	const itemsWithUrl = result.data.items.map((item) => addUrlToMedia(item));
 	if (query.includeUsage !== "1") {
-		return apiSuccess({ items: itemsWithUrl, nextCursor: result.data.nextCursor });
+		return apiSuccess({
+			items: itemsWithUrl,
+			nextCursor: result.data.nextCursor,
+			totalCount: result.data.totalCount,
+		});
 	}
 
 	const includeCount = canReadMediaUsageCount(user, locals.tokenScopes);
@@ -85,7 +91,11 @@ export const GET: APIRoute = async ({ request, locals }) => {
 		itemsWithUsage.push({ ...item, usage });
 	}
 
-	return apiSuccess({ items: itemsWithUsage, nextCursor: result.data.nextCursor });
+	return apiSuccess({
+		items: itemsWithUsage,
+		nextCursor: result.data.nextCursor,
+		totalCount: result.data.totalCount,
+	});
 };
 
 /**