dsh-coding-subscription-oauth 0.5.8 → 0.6.2

package/src/imagine-routes.ts

@@ -1,461 +1,463 @@
-/**
- * Same-origin GET routes for generated Imagine images and video artifacts.
- * The Host webServer only accepts exact paths, so this registrar keeps a
- * bounded table of opaque ids and registers one exact disposer per remembered
- * image ref or media artifact.
- * @module dsh-coding-subscription-oauth/imagine-routes
- */
-
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
-import {
-	DEFAULT_IMAGE_DOWNLOAD_MAX_BYTES,
-	type ImagineImageAttachmentRef,
-	type ImagineImageMediaType,
-	imagineImageDownloadHeaders,
-	imagineImagePath,
-	isSafeImagineAttachmentId,
-	parseImagineImagePath,
-} from "./grok-imagine.ts";
-import {
-	createTrustedImagineAuthz,
-	imagineMediaPath,
-	isSafeMediaArtifactId,
-	MEDIA_STORE_MAX_BYTES,
-	type MediaArtifactMeta,
-	type MediaDownloadView,
-	MediaStoreError,
-	type MediaStoreVideoType,
-	mediaDownloadHeaders,
-	parseImagineMediaPath,
-	type TrustedImagineAuthz,
-} from "./media-store.ts";
-import { isTrustedLoopbackWebRequest } from "./web-origin.ts";
-
-/** Hard ceiling for live exact download routes. Callers cannot raise this. */
-export const IMAGINE_ROUTE_MAX_ENTRIES = 64;
-
-/** Hard ceiling for remembered image routes. Callers cannot raise this. */
-export const IMAGINE_IMAGE_ROUTE_TTL_MS = 60 * 60 * 1000;
-
-const IMAGE_MEDIA_TYPES = new Set<string>(["image/png", "image/jpeg", "image/webp", "image/gif"]);
-const VIDEO_MEDIA_TYPES = new Set<string>(["video/mp4", "video/webm"]);
-
-/** Structural `ctx.webServer` + optional `ctx.effect` surface used by the registrar. */
-export interface ImagineRouteContext {
-	readonly webServer: {
-		register(route: {
-			kind: "exact";
-			path: string;
-			handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
-		}): () => void;
-	};
-	effect?(setup: () => () => void | Promise<void>, label?: string): unknown;
-}
-
-/** Attachment seam used at GET time. Only metadata is retained in the registry. */
-export interface ImagineRouteAttachmentStore {
-	readonly imageLimits?: { readonly maxImageBytes?: number };
-	readImage(
-		ref: ImagineImageAttachmentRef,
-		signal?: AbortSignal,
-	): Promise<{ ref: ImagineImageAttachmentRef; data: Uint8Array }>;
-}
-
-/** Structural media download seam. Production adapts `MediaStore.openDownload`. */
-export interface ImagineMediaDownloadStore {
-	readForDownload(artifactId: string, authz: TrustedImagineAuthz): Promise<MediaDownloadView>;
-}
-
-export interface ImagineRouteOptions {
-	readonly attachments: ImagineRouteAttachmentStore;
-	readonly media: ImagineMediaDownloadStore;
-	readonly now?: () => number;
-	/** Capped at {@link IMAGINE_ROUTE_MAX_ENTRIES}. */
-	readonly maxEntries?: number;
-	/** Capped at {@link IMAGINE_IMAGE_ROUTE_TTL_MS}. */
-	readonly imageTtlMs?: number;
-}
-
-export interface ImagineRouteRegistry {
-	rememberImages(refs: readonly ImageAttachmentRef[] | readonly ImagineImageAttachmentRef[]): void;
-	rememberArtifact(meta: MediaArtifactMeta): void;
-	revokeImages(): void;
-	revokeArtifacts(): void;
-	dispose(): void;
-}
-
-interface ImageRouteEntry {
-	readonly kind: "image";
-	readonly id: string;
-	readonly path: string;
-	readonly routeToken: symbol;
-	ref: ImagineImageAttachmentRef;
-	expiresAt: number;
-	readonly disposeRoute: () => void;
-}
-
-interface MediaRouteEntry {
-	readonly kind: "media";
-	readonly id: string;
-	readonly path: string;
-	readonly routeToken: symbol;
-	meta: MediaArtifactMeta;
-	expiresAt: number;
-	readonly disposeRoute: () => void;
-}
-
-type RouteEntry = ImageRouteEntry | MediaRouteEntry;
-
-type RouteHandler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
-
-/** Register the bounded exact-path Imagine download registry. */
-export function registerImagineRoutes(ctx: ImagineRouteContext, options: ImagineRouteOptions): ImagineRouteRegistry {
-	const now = options.now ?? Date.now;
-	const maxEntries = clampPositive(options.maxEntries, IMAGINE_ROUTE_MAX_ENTRIES);
-	const imageTtlMs = clampPositive(options.imageTtlMs, IMAGINE_IMAGE_ROUTE_TTL_MS);
-	const entries = new Map<string, RouteEntry>();
-	let disposed = false;
-
-	const wrapDisposer = (release: () => void): (() => void) => {
-		let released = false;
-		return () => {
-			if (released) return;
-			released = true;
-			try {
-				release();
-			} catch {
-				// One route disposer must not strand the rest of the table.
-			}
-		};
-	};
-
-	const evict = (key: string): void => {
-		const entry = entries.get(key);
-		if (entry === undefined) return;
-		entries.delete(key);
-		entry.disposeRoute();
-	};
-
-	const evictExpired = (at: number): void => {
-		for (const [key, entry] of [...entries]) {
-			if (entry.expiresAt <= at) evict(key);
-		}
-	};
-
-	const evictOldest = (): void => {
-		const oldest = entries.keys().next().value;
-		if (oldest !== undefined) evict(oldest);
-	};
-
-	const lookupKey = (kind: RouteEntry["kind"], id: string): string => `${kind}:${id}`;
-
-	const registerExact = (path: string, handler: RouteHandler): (() => void) =>
-		wrapDisposer(
-			ctx.webServer.register({
-				kind: "exact",
-				path,
-				handler,
-			}),
-		);
-
-	const isCurrent = (kind: RouteEntry["kind"], id: string, routeToken: symbol): boolean => {
-		if (disposed) return false;
-		const entry = entries.get(lookupKey(kind, id));
-		return entry !== undefined && entry.kind === kind && entry.routeToken === routeToken && entry.expiresAt > now();
-	};
-
-	const handleGet = async (
-		kind: RouteEntry["kind"],
-		id: string,
-		routeToken: symbol,
-		req: IncomingMessage,
-		res: ServerResponse,
-	): Promise<void> => {
-		if ((req.method ?? "") !== "GET") {
-			json(res, 405, { error: "method not allowed" });
-			return;
-		}
-		if (!isTrustedLoopbackWebRequest(req)) {
-			json(res, 403, { error: "forbidden" });
-			return;
-		}
-		if (!isCurrent(kind, id, routeToken)) {
-			const key = lookupKey(kind, id);
-			const current = entries.get(key);
-			if (current?.routeToken === routeToken && current.expiresAt <= now()) evict(key);
-			json(res, 404, { error: "not found" });
-			return;
-		}
-		const key = lookupKey(kind, id);
-		const entry = entries.get(key);
-		if (entry === undefined || entry.kind !== kind) {
-			json(res, 404, { error: "not found" });
-			return;
-		}
-		try {
-			if (entry.kind === "image") {
-				await serveImage(options.attachments, entry, req, res, () => isCurrent(kind, id, routeToken));
-			} else {
-				await serveMedia(options.media, entry, res, () => isCurrent(kind, id, routeToken));
-			}
-		} catch (error: unknown) {
-			if (res.headersSent) return;
-			if (!isCurrent(kind, id, routeToken)) {
-				json(res, 404, { error: "not found" });
-				return;
-			}
-			json(res, statusFor(error), { error: publicErrorMessage(error) });
-		}
-	};
-
-	const rememberImage = (input: ImageAttachmentRef | ImagineImageAttachmentRef): void => {
-		if (disposed) return;
-		const at = now();
-		evictExpired(at);
-		const ref = cloneImageRef(input);
-		if (ref === undefined) return;
-		if (ref.bytes > maxImageBytes(options.attachments)) return;
-		let path: string;
-		try {
-			path = imagineImagePath(ref.attachmentId);
-		} catch {
-			return;
-		}
-		if (parseImagineImagePath(path) !== ref.attachmentId) return;
-		const key = lookupKey("image", ref.attachmentId);
-		const existing = entries.get(key);
-		if (existing?.kind === "image") {
-			entries.delete(key);
-			existing.ref = ref;
-			existing.expiresAt = at + imageTtlMs;
-			entries.set(key, existing);
-			return;
-		}
-		while (entries.size >= maxEntries) evictOldest();
-		const routeToken = Symbol(ref.attachmentId);
-		const release = registerExact(path, (req, res) => handleGet("image", ref.attachmentId, routeToken, req, res));
-		entries.set(key, {
-			kind: "image",
-			id: ref.attachmentId,
-			path,
-			routeToken,
-			ref,
-			expiresAt: at + imageTtlMs,
-			disposeRoute: release,
-		});
-	};
-
-	const rememberArtifact = (input: MediaArtifactMeta): void => {
-		if (disposed) return;
-		const at = now();
-		evictExpired(at);
-		const meta = cloneArtifactMeta(input);
-		if (meta === undefined || meta.expiresAt <= at) return;
-		let path: string;
-		try {
-			path = imagineMediaPath(meta.artifactId);
-		} catch {
-			return;
-		}
-		if (parseImagineMediaPath(path) !== meta.artifactId) return;
-		const key = lookupKey("media", meta.artifactId);
-		const existing = entries.get(key);
-		if (existing?.kind === "media") {
-			entries.delete(key);
-			existing.meta = meta;
-			existing.expiresAt = meta.expiresAt;
-			entries.set(key, existing);
-			return;
-		}
-		while (entries.size >= maxEntries) evictOldest();
-		const routeToken = Symbol(meta.artifactId);
-		const release = registerExact(path, (req, res) => handleGet("media", meta.artifactId, routeToken, req, res));
-		entries.set(key, {
-			kind: "media",
-			id: meta.artifactId,
-			path,
-			routeToken,
-			meta,
-			expiresAt: meta.expiresAt,
-			disposeRoute: release,
-		});
-	};
-
-	const dispose = (): void => {
-		if (disposed) return;
-		disposed = true;
-		for (const key of [...entries.keys()]) evict(key);
-	};
-
-	if (typeof ctx.effect === "function") {
-		ctx.effect(() => dispose, "dsh-coding-subscription-oauth: imagine download routes");
-	}
-
-	return {
-		rememberImages(refs) {
-			for (const ref of refs) rememberImage(ref);
-		},
-		rememberArtifact,
-		revokeImages() {
-			for (const [key, entry] of [...entries]) {
-				if (entry.kind === "image") evict(key);
-			}
-		},
-		revokeArtifacts() {
-			for (const [key, entry] of [...entries]) {
-				if (entry.kind === "media") evict(key);
-			}
-		},
-		dispose,
-	};
-}
-
-async function serveImage(
-	attachments: ImagineRouteAttachmentStore,
-	entry: ImageRouteEntry,
-	req: IncomingMessage,
-	res: ServerResponse,
-	alive: () => boolean,
-): Promise<void> {
-	const limit = maxImageBytes(attachments);
-	if (entry.ref.bytes > limit) {
-		json(res, 404, { error: "not found" });
-		return;
-	}
-	const stored = await attachments.readImage(cloneImageRef(entry.ref) ?? entry.ref, requestSignal(req));
-	if (res.headersSent) return;
-	if (!alive()) {
-		json(res, 404, { error: "not found" });
-		return;
-	}
-	if (!sameImageIdentity(entry.ref, stored.ref) || stored.data.byteLength > limit) {
-		json(res, 404, { error: "not found" });
-		return;
-	}
-	const headers = imagineImageDownloadHeaders({
-		...stored.ref,
-		bytes: stored.data.byteLength,
-	});
-	res.writeHead(200, {
-		"Content-Type": headers["Content-Type"],
-		"Content-Length": String(stored.data.byteLength),
-		"Cache-Control": headers["Cache-Control"],
-		"X-Content-Type-Options": headers["X-Content-Type-Options"],
-	});
-	res.end(Buffer.from(stored.data));
-}
-
-async function serveMedia(
-	media: ImagineMediaDownloadStore,
-	entry: MediaRouteEntry,
-	res: ServerResponse,
-	alive: () => boolean,
-): Promise<void> {
-	const authz = createTrustedImagineAuthz({ authorized: true });
-	const view = await media.readForDownload(entry.id, authz);
-	if (res.headersSent) return;
-	if (!alive()) {
-		json(res, 404, { error: "not found" });
-		return;
-	}
-	if (
-		view.meta.artifactId !== entry.id ||
-		view.meta.mediaType !== entry.meta.mediaType ||
-		view.meta.bytes !== view.body.byteLength ||
-		view.body.byteLength > MEDIA_STORE_MAX_BYTES
-	) {
-		json(res, 404, { error: "not found" });
-		return;
-	}
-	const headers = mediaDownloadHeaders({ ...entry.meta, bytes: view.body.byteLength });
-	res.writeHead(200, {
-		"Content-Type": headers["Content-Type"],
-		"Content-Length": headers["Content-Length"],
-		"Content-Disposition": headers["Content-Disposition"],
-		"Cache-Control": headers["Cache-Control"],
-		"X-Content-Type-Options": headers["X-Content-Type-Options"],
-	});
-	res.end(Buffer.from(view.body));
-}
-
-function requestSignal(req: IncomingMessage): AbortSignal | undefined {
-	const candidate = req as IncomingMessage & { signal?: unknown };
-	return candidate.signal instanceof AbortSignal ? candidate.signal : undefined;
-}
-
-function maxImageBytes(attachments: ImagineRouteAttachmentStore): number {
-	const configured = attachments.imageLimits?.maxImageBytes;
-	if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
-		return DEFAULT_IMAGE_DOWNLOAD_MAX_BYTES;
-	}
-	return Math.min(Math.floor(configured), DEFAULT_IMAGE_DOWNLOAD_MAX_BYTES);
-}
-
-function cloneImageRef(input: ImageAttachmentRef | ImagineImageAttachmentRef): ImagineImageAttachmentRef | undefined {
-	if (typeof input.attachmentId !== "string" || !isSafeImagineAttachmentId(input.attachmentId)) return undefined;
-	if (!IMAGE_MEDIA_TYPES.has(input.mediaType)) return undefined;
-	if (!Number.isFinite(input.bytes) || input.bytes < 0) return undefined;
-	if (!Number.isFinite(input.width) || !Number.isFinite(input.height)) return undefined;
-	const cloned: ImagineImageAttachmentRef = {
-		attachmentId: input.attachmentId,
-		mediaType: input.mediaType as ImagineImageMediaType,
-		bytes: Math.trunc(input.bytes),
-		width: Math.trunc(input.width),
-		height: Math.trunc(input.height),
-	};
-	if (typeof input.name === "string") cloned.name = input.name;
-	return cloned;
-}
-
-function cloneArtifactMeta(input: MediaArtifactMeta): MediaArtifactMeta | undefined {
-	if (typeof input.artifactId !== "string" || !isSafeMediaArtifactId(input.artifactId)) return undefined;
-	if (!VIDEO_MEDIA_TYPES.has(input.mediaType)) return undefined;
-	if (!Number.isFinite(input.bytes) || input.bytes <= 0) return undefined;
-	if (!Number.isFinite(input.createdAt) || input.createdAt <= 0) return undefined;
-	if (!Number.isFinite(input.expiresAt) || input.expiresAt <= input.createdAt) return undefined;
-	const cloned: MediaArtifactMeta = {
-		artifactId: input.artifactId,
-		mediaType: input.mediaType as MediaStoreVideoType,
-		bytes: Math.trunc(input.bytes),
-		createdAt: input.createdAt,
-		expiresAt: input.expiresAt,
-	};
-	if (typeof input.name === "string") cloned.name = input.name;
-	return cloned;
-}
-
-function sameImageIdentity(expected: ImagineImageAttachmentRef, actual: ImagineImageAttachmentRef): boolean {
-	return actual.attachmentId === expected.attachmentId && IMAGE_MEDIA_TYPES.has(actual.mediaType);
-}
-
-function statusFor(error: unknown): number {
-	if (error instanceof MediaStoreError) {
-		if (error.code === "NOT_FOUND" || error.code === "EXPIRED" || error.code === "INVALID_ID") return 404;
-		if (error.code === "FORBIDDEN") return 403;
-	}
-	return 500;
-}
-
-function publicErrorMessage(error: unknown): string {
-	if (error instanceof MediaStoreError) {
-		if (error.code === "NOT_FOUND" || error.code === "EXPIRED" || error.code === "INVALID_ID") return "not found";
-		if (error.code === "FORBIDDEN") return "forbidden";
-	}
-	return "download failed";
-}
-
-function clampPositive(value: number | undefined, ceiling: number): number {
-	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return ceiling;
-	return Math.min(Math.floor(value), ceiling);
-}
-
-function json(res: ServerResponse, status: number, value: unknown): void {
-	if (res.headersSent) return;
-	res.writeHead(status, {
-		"content-type": "application/json; charset=utf-8",
-		"cache-control": "no-store",
-		"x-content-type-options": "nosniff",
-	});
-	res.end(JSON.stringify(value));
-}
+/**
+ * Same-origin GET routes for generated Imagine images and video artifacts.
+ * The Host webServer only accepts exact paths, so this registrar keeps a
+ * bounded table of opaque ids and registers one exact disposer per remembered
+ * image ref or media artifact.
+ * @module dsh-coding-subscription-oauth/imagine-routes
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
+import {
+	DEFAULT_IMAGE_DOWNLOAD_MAX_BYTES,
+	type ImagineImageAttachmentRef,
+	type ImagineImageMediaType,
+	imagineImageDownloadHeaders,
+	imagineImagePath,
+	isSafeImagineAttachmentId,
+	parseImagineImagePath,
+} from "./grok-imagine.ts";
+import {
+	createTrustedImagineAuthz,
+	imagineMediaPath,
+	isSafeMediaArtifactId,
+	MEDIA_STORE_MAX_BYTES,
+	type MediaArtifactMeta,
+	type MediaDownloadView,
+	MediaStoreError,
+	type MediaStoreVideoType,
+	mediaDownloadHeaders,
+	parseImagineMediaPath,
+	type TrustedImagineAuthz,
+} from "./media-store.ts";
+import { LOOPBACK_OWNER_REQUEST_POLICY, type OwnerRequestPolicy } from "./web-origin.ts";
+
+/** Hard ceiling for live exact download routes. Callers cannot raise this. */
+export const IMAGINE_ROUTE_MAX_ENTRIES = 64;
+
+/** Hard ceiling for remembered image routes. Callers cannot raise this. */
+export const IMAGINE_IMAGE_ROUTE_TTL_MS = 60 * 60 * 1000;
+
+const IMAGE_MEDIA_TYPES = new Set<string>(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+const VIDEO_MEDIA_TYPES = new Set<string>(["video/mp4", "video/webm"]);
+
+/** Structural `ctx.webServer` + optional `ctx.effect` surface used by the registrar. */
+export interface ImagineRouteContext {
+	readonly webServer: {
+		register(route: {
+			kind: "exact";
+			path: string;
+			handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+		}): () => void;
+	};
+	effect?(setup: () => () => void | Promise<void>, label?: string): unknown;
+}
+
+/** Attachment seam used at GET time. Only metadata is retained in the registry. */
+export interface ImagineRouteAttachmentStore {
+	readonly imageLimits?: { readonly maxImageBytes?: number };
+	readImage(
+		ref: ImagineImageAttachmentRef,
+		signal?: AbortSignal,
+	): Promise<{ ref: ImagineImageAttachmentRef; data: Uint8Array }>;
+}
+
+/** Structural media download seam. Production adapts `MediaStore.openDownload`. */
+export interface ImagineMediaDownloadStore {
+	readForDownload(artifactId: string, authz: TrustedImagineAuthz): Promise<MediaDownloadView>;
+}
+
+export interface ImagineRouteOptions {
+	readonly attachments: ImagineRouteAttachmentStore;
+	readonly media: ImagineMediaDownloadStore;
+	readonly now?: () => number;
+	/** Capped at {@link IMAGINE_ROUTE_MAX_ENTRIES}. */
+	readonly maxEntries?: number;
+	/** Capped at {@link IMAGINE_IMAGE_ROUTE_TTL_MS}. */
+	readonly imageTtlMs?: number;
+	readonly ownerRequestPolicy?: OwnerRequestPolicy;
+}
+
+export interface ImagineRouteRegistry {
+	rememberImages(refs: readonly ImageAttachmentRef[] | readonly ImagineImageAttachmentRef[]): void;
+	rememberArtifact(meta: MediaArtifactMeta): void;
+	revokeImages(): void;
+	revokeArtifacts(): void;
+	dispose(): void;
+}
+
+interface ImageRouteEntry {
+	readonly kind: "image";
+	readonly id: string;
+	readonly path: string;
+	readonly routeToken: symbol;
+	ref: ImagineImageAttachmentRef;
+	expiresAt: number;
+	readonly disposeRoute: () => void;
+}
+
+interface MediaRouteEntry {
+	readonly kind: "media";
+	readonly id: string;
+	readonly path: string;
+	readonly routeToken: symbol;
+	meta: MediaArtifactMeta;
+	expiresAt: number;
+	readonly disposeRoute: () => void;
+}
+
+type RouteEntry = ImageRouteEntry | MediaRouteEntry;
+
+type RouteHandler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+
+/** Register the bounded exact-path Imagine download registry. */
+export function registerImagineRoutes(ctx: ImagineRouteContext, options: ImagineRouteOptions): ImagineRouteRegistry {
+	const now = options.now ?? Date.now;
+	const maxEntries = clampPositive(options.maxEntries, IMAGINE_ROUTE_MAX_ENTRIES);
+	const imageTtlMs = clampPositive(options.imageTtlMs, IMAGINE_IMAGE_ROUTE_TTL_MS);
+	const ownerRequestPolicy = options.ownerRequestPolicy ?? LOOPBACK_OWNER_REQUEST_POLICY;
+	const entries = new Map<string, RouteEntry>();
+	let disposed = false;
+
+	const wrapDisposer = (release: () => void): (() => void) => {
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			try {
+				release();
+			} catch {
+				// One route disposer must not strand the rest of the table.
+			}
+		};
+	};
+
+	const evict = (key: string): void => {
+		const entry = entries.get(key);
+		if (entry === undefined) return;
+		entries.delete(key);
+		entry.disposeRoute();
+	};
+
+	const evictExpired = (at: number): void => {
+		for (const [key, entry] of [...entries]) {
+			if (entry.expiresAt <= at) evict(key);
+		}
+	};
+
+	const evictOldest = (): void => {
+		const oldest = entries.keys().next().value;
+		if (oldest !== undefined) evict(oldest);
+	};
+
+	const lookupKey = (kind: RouteEntry["kind"], id: string): string => `${kind}:${id}`;
+
+	const registerExact = (path: string, handler: RouteHandler): (() => void) =>
+		wrapDisposer(
+			ctx.webServer.register({
+				kind: "exact",
+				path,
+				handler,
+			}),
+		);
+
+	const isCurrent = (kind: RouteEntry["kind"], id: string, routeToken: symbol): boolean => {
+		if (disposed) return false;
+		const entry = entries.get(lookupKey(kind, id));
+		return entry !== undefined && entry.kind === kind && entry.routeToken === routeToken && entry.expiresAt > now();
+	};
+
+	const handleGet = async (
+		kind: RouteEntry["kind"],
+		id: string,
+		routeToken: symbol,
+		req: IncomingMessage,
+		res: ServerResponse,
+	): Promise<void> => {
+		if ((req.method ?? "") !== "GET") {
+			json(res, 405, { error: "method not allowed" });
+			return;
+		}
+		if (!ownerRequestPolicy.authorize(req).authorized) {
+			json(res, 403, { error: "forbidden" });
+			return;
+		}
+		if (!isCurrent(kind, id, routeToken)) {
+			const key = lookupKey(kind, id);
+			const current = entries.get(key);
+			if (current?.routeToken === routeToken && current.expiresAt <= now()) evict(key);
+			json(res, 404, { error: "not found" });
+			return;
+		}
+		const key = lookupKey(kind, id);
+		const entry = entries.get(key);
+		if (entry === undefined || entry.kind !== kind) {
+			json(res, 404, { error: "not found" });
+			return;
+		}
+		try {
+			if (entry.kind === "image") {
+				await serveImage(options.attachments, entry, req, res, () => isCurrent(kind, id, routeToken));
+			} else {
+				await serveMedia(options.media, entry, res, () => isCurrent(kind, id, routeToken));
+			}
+		} catch (error: unknown) {
+			if (res.headersSent) return;
+			if (!isCurrent(kind, id, routeToken)) {
+				json(res, 404, { error: "not found" });
+				return;
+			}
+			json(res, statusFor(error), { error: publicErrorMessage(error) });
+		}
+	};
+
+	const rememberImage = (input: ImageAttachmentRef | ImagineImageAttachmentRef): void => {
+		if (disposed) return;
+		const at = now();
+		evictExpired(at);
+		const ref = cloneImageRef(input);
+		if (ref === undefined) return;
+		if (ref.bytes > maxImageBytes(options.attachments)) return;
+		let path: string;
+		try {
+			path = imagineImagePath(ref.attachmentId);
+		} catch {
+			return;
+		}
+		if (parseImagineImagePath(path) !== ref.attachmentId) return;
+		const key = lookupKey("image", ref.attachmentId);
+		const existing = entries.get(key);
+		if (existing?.kind === "image") {
+			entries.delete(key);
+			existing.ref = ref;
+			existing.expiresAt = at + imageTtlMs;
+			entries.set(key, existing);
+			return;
+		}
+		while (entries.size >= maxEntries) evictOldest();
+		const routeToken = Symbol(ref.attachmentId);
+		const release = registerExact(path, (req, res) => handleGet("image", ref.attachmentId, routeToken, req, res));
+		entries.set(key, {
+			kind: "image",
+			id: ref.attachmentId,
+			path,
+			routeToken,
+			ref,
+			expiresAt: at + imageTtlMs,
+			disposeRoute: release,
+		});
+	};
+
+	const rememberArtifact = (input: MediaArtifactMeta): void => {
+		if (disposed) return;
+		const at = now();
+		evictExpired(at);
+		const meta = cloneArtifactMeta(input);
+		if (meta === undefined || meta.expiresAt <= at) return;
+		let path: string;
+		try {
+			path = imagineMediaPath(meta.artifactId);
+		} catch {
+			return;
+		}
+		if (parseImagineMediaPath(path) !== meta.artifactId) return;
+		const key = lookupKey("media", meta.artifactId);
+		const existing = entries.get(key);
+		if (existing?.kind === "media") {
+			entries.delete(key);
+			existing.meta = meta;
+			existing.expiresAt = meta.expiresAt;
+			entries.set(key, existing);
+			return;
+		}
+		while (entries.size >= maxEntries) evictOldest();
+		const routeToken = Symbol(meta.artifactId);
+		const release = registerExact(path, (req, res) => handleGet("media", meta.artifactId, routeToken, req, res));
+		entries.set(key, {
+			kind: "media",
+			id: meta.artifactId,
+			path,
+			routeToken,
+			meta,
+			expiresAt: meta.expiresAt,
+			disposeRoute: release,
+		});
+	};
+
+	const dispose = (): void => {
+		if (disposed) return;
+		disposed = true;
+		for (const key of [...entries.keys()]) evict(key);
+	};
+
+	if (typeof ctx.effect === "function") {
+		ctx.effect(() => dispose, "dsh-coding-subscription-oauth: imagine download routes");
+	}
+
+	return {
+		rememberImages(refs) {
+			for (const ref of refs) rememberImage(ref);
+		},
+		rememberArtifact,
+		revokeImages() {
+			for (const [key, entry] of [...entries]) {
+				if (entry.kind === "image") evict(key);
+			}
+		},
+		revokeArtifacts() {
+			for (const [key, entry] of [...entries]) {
+				if (entry.kind === "media") evict(key);
+			}
+		},
+		dispose,
+	};
+}
+
+async function serveImage(
+	attachments: ImagineRouteAttachmentStore,
+	entry: ImageRouteEntry,
+	req: IncomingMessage,
+	res: ServerResponse,
+	alive: () => boolean,
+): Promise<void> {
+	const limit = maxImageBytes(attachments);
+	if (entry.ref.bytes > limit) {
+		json(res, 404, { error: "not found" });
+		return;
+	}
+	const stored = await attachments.readImage(cloneImageRef(entry.ref) ?? entry.ref, requestSignal(req));
+	if (res.headersSent) return;
+	if (!alive()) {
+		json(res, 404, { error: "not found" });
+		return;
+	}
+	if (!sameImageIdentity(entry.ref, stored.ref) || stored.data.byteLength > limit) {
+		json(res, 404, { error: "not found" });
+		return;
+	}
+	const headers = imagineImageDownloadHeaders({
+		...stored.ref,
+		bytes: stored.data.byteLength,
+	});
+	res.writeHead(200, {
+		"Content-Type": headers["Content-Type"],
+		"Content-Length": String(stored.data.byteLength),
+		"Cache-Control": headers["Cache-Control"],
+		"X-Content-Type-Options": headers["X-Content-Type-Options"],
+	});
+	res.end(Buffer.from(stored.data));
+}
+
+async function serveMedia(
+	media: ImagineMediaDownloadStore,
+	entry: MediaRouteEntry,
+	res: ServerResponse,
+	alive: () => boolean,
+): Promise<void> {
+	const authz = createTrustedImagineAuthz({ authorized: true });
+	const view = await media.readForDownload(entry.id, authz);
+	if (res.headersSent) return;
+	if (!alive()) {
+		json(res, 404, { error: "not found" });
+		return;
+	}
+	if (
+		view.meta.artifactId !== entry.id ||
+		view.meta.mediaType !== entry.meta.mediaType ||
+		view.meta.bytes !== view.body.byteLength ||
+		view.body.byteLength > MEDIA_STORE_MAX_BYTES
+	) {
+		json(res, 404, { error: "not found" });
+		return;
+	}
+	const headers = mediaDownloadHeaders({ ...entry.meta, bytes: view.body.byteLength });
+	res.writeHead(200, {
+		"Content-Type": headers["Content-Type"],
+		"Content-Length": headers["Content-Length"],
+		"Content-Disposition": headers["Content-Disposition"],
+		"Cache-Control": headers["Cache-Control"],
+		"X-Content-Type-Options": headers["X-Content-Type-Options"],
+	});
+	res.end(Buffer.from(view.body));
+}
+
+function requestSignal(req: IncomingMessage): AbortSignal | undefined {
+	const candidate = req as IncomingMessage & { signal?: unknown };
+	return candidate.signal instanceof AbortSignal ? candidate.signal : undefined;
+}
+
+function maxImageBytes(attachments: ImagineRouteAttachmentStore): number {
+	const configured = attachments.imageLimits?.maxImageBytes;
+	if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+		return DEFAULT_IMAGE_DOWNLOAD_MAX_BYTES;
+	}
+	return Math.min(Math.floor(configured), DEFAULT_IMAGE_DOWNLOAD_MAX_BYTES);
+}
+
+function cloneImageRef(input: ImageAttachmentRef | ImagineImageAttachmentRef): ImagineImageAttachmentRef | undefined {
+	if (typeof input.attachmentId !== "string" || !isSafeImagineAttachmentId(input.attachmentId)) return undefined;
+	if (!IMAGE_MEDIA_TYPES.has(input.mediaType)) return undefined;
+	if (!Number.isFinite(input.bytes) || input.bytes < 0) return undefined;
+	if (!Number.isFinite(input.width) || !Number.isFinite(input.height)) return undefined;
+	const cloned: ImagineImageAttachmentRef = {
+		attachmentId: input.attachmentId,
+		mediaType: input.mediaType as ImagineImageMediaType,
+		bytes: Math.trunc(input.bytes),
+		width: Math.trunc(input.width),
+		height: Math.trunc(input.height),
+	};
+	if (typeof input.name === "string") cloned.name = input.name;
+	return cloned;
+}
+
+function cloneArtifactMeta(input: MediaArtifactMeta): MediaArtifactMeta | undefined {
+	if (typeof input.artifactId !== "string" || !isSafeMediaArtifactId(input.artifactId)) return undefined;
+	if (!VIDEO_MEDIA_TYPES.has(input.mediaType)) return undefined;
+	if (!Number.isFinite(input.bytes) || input.bytes <= 0) return undefined;
+	if (!Number.isFinite(input.createdAt) || input.createdAt <= 0) return undefined;
+	if (!Number.isFinite(input.expiresAt) || input.expiresAt <= input.createdAt) return undefined;
+	const cloned: MediaArtifactMeta = {
+		artifactId: input.artifactId,
+		mediaType: input.mediaType as MediaStoreVideoType,
+		bytes: Math.trunc(input.bytes),
+		createdAt: input.createdAt,
+		expiresAt: input.expiresAt,
+	};
+	if (typeof input.name === "string") cloned.name = input.name;
+	return cloned;
+}
+
+function sameImageIdentity(expected: ImagineImageAttachmentRef, actual: ImagineImageAttachmentRef): boolean {
+	return actual.attachmentId === expected.attachmentId && IMAGE_MEDIA_TYPES.has(actual.mediaType);
+}
+
+function statusFor(error: unknown): number {
+	if (error instanceof MediaStoreError) {
+		if (error.code === "NOT_FOUND" || error.code === "EXPIRED" || error.code === "INVALID_ID") return 404;
+		if (error.code === "FORBIDDEN") return 403;
+	}
+	return 500;
+}
+
+function publicErrorMessage(error: unknown): string {
+	if (error instanceof MediaStoreError) {
+		if (error.code === "NOT_FOUND" || error.code === "EXPIRED" || error.code === "INVALID_ID") return "not found";
+		if (error.code === "FORBIDDEN") return "forbidden";
+	}
+	return "download failed";
+}
+
+function clampPositive(value: number | undefined, ceiling: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return ceiling;
+	return Math.min(Math.floor(value), ceiling);
+}
+
+function json(res: ServerResponse, status: number, value: unknown): void {
+	if (res.headersSent) return;
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store",
+		"x-content-type-options": "nosniff",
+	});
+	res.end(JSON.stringify(value));
+}