@hollware/server 1.0.0-rc.1 → 1.0.0-rc.2

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { A as revisionTags, C as entryEmbeddings, D as publications, E as outbox, F as users, I as ROLE_SCOPES, L as effectiveScopes, M as schedules, N as sites, O as reviewComments, P as tokens, R as isRole, S as entries, T as members, a as dropExpired, f as membershipsOf, g as removePasskey, j as revisions, k as reviews, n as createInvitation, o as endSession, p as passkeySummaries, s as endSessions, u as findSession, w as invitations, x as deliveries } from "./store-DjA9s95l.mjs";
-import { CHUNKER_VERSION, ConfigError, EVENT_ID_HEADER, HollwareError, INDEXNOW_KEY, OPERATIONS, OPERATION_AUDIT_ACTIONS, PREVIEW_QUERY_PARAM, SCOPES, SIGNATURE_HEADER, TIMESTAMP_HEADER, canSignPreviews, canonicalJson, chunksOf, compileSites, definitionsFromConfig, describeBuiltInContracts, describeCatalog, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isAuditAction, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, makePreviewToken, newId, processMarkdown, publish, renderHtml, resolveConfig, runContracts, search, signWebhook, siteDefinitionData, sizeLimitViolation, tagsOfChange, tagsOfSiteChange, uniqueSlugViolation, uniqueTranslationViolation, verifyPreviewToken } from "@hollware/core";
+import { A as revisionTags, C as entryEmbeddings, D as publications, E as outbox, F as users, I as ROLE_SCOPES, L as effectiveScopes, M as schedules, N as sites, O as reviewComments, P as tokens, R as isRole, S as entries, T as members, a as dropExpired, f as membershipsOf, g as removePasskey, j as revisions, k as reviews, n as createInvitation, o as endSession, p as passkeySummaries, s as endSessions, u as findSession, w as invitations, x as deliveries } from "./store-ApxKV0Sc.mjs";
+import { CHUNKER_VERSION, ConfigError, EVENT_ID_HEADER, HollwareError, INDEXNOW_KEY, MAX_ASSET_BYTES, OPERATIONS, OPERATION_AUDIT_ACTIONS, PREVIEW_QUERY_PARAM, SCOPES, SIGNATURE_HEADER, TIMESTAMP_HEADER, assetIdOf, canSignPreviews, canonicalJson, checkSvg, chunksOf, compileSites, conversionOf, definitionsFromConfig, describeBuiltInContracts, describeCatalog, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isAuditAction, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, makePreviewToken, newId, processMarkdown, publish, renderHtml, resolveAssetReferences, resolveConfig, runContracts, search, signWebhook, siteDefinitionData, sizeLimitViolation, sniffImage, tagsOfChange, tagsOfSiteChange, uniqueSlugViolation, uniqueTranslationViolation, verifyPreviewToken } from "@hollware/core";
 import { Hono } from "hono";
 import { drizzle } from "drizzle-orm/d1";
 import { and, asc, desc, eq, getTableColumns, gt, inArray, isNotNull, isNull, lte, ne, or, sql } from "drizzle-orm";
@@ -10,7 +10,7 @@ import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, McpServer, accepted
 import * as z from "zod";
 import { WorkerEntrypoint } from "cloudflare:workers";
 //#region package.json
-var version = "1.0.0-rc.1";
+var version = "1.0.0-rc.2";
 //#endregion
 //#region src/auth/responses.ts
 /** The challenge of every 401 and 403 (RFC 6750). */
@@ -257,6 +257,237 @@ async function checkPersonalToken(db, token, options) {
 	};
 }
 //#endregion
+//#region src/ops/errors.ts
+/**
+* The error of something that must never happen: a bug of Hollware, not a mistake of the caller.
+* Like the `internal` error of the adapters, its message says nothing about the cause, which goes
+* to the log through `cause`, and its fix names the request id the operator finds the log line by.
+*/
+function internalError$1(context, cause) {
+	return new HollwareError("internal", "The operation failed on the server.", `Try again. If it keeps failing, give the site operator this request id: ${context.requestId}.`, { cause: new Error(cause) });
+}
+/**
+* The error for an answer of the store that the call it came from can never get: an entry that
+* is created cannot conflict, a publish has no slug to take. It is a bug, not an outcome of the
+* operation, so it is not one of the outcomes of its spec.
+*/
+function unexpectedAnswer(context, call, answer) {
+	return internalError$1(context, `The store answered ${answer.outcome} to ${call}, which it never does.`);
+}
+//#endregion
+//#region src/ops/actor.ts
+/**
+* Who a write is made by: the person behind the token of the call, with what its client said
+* about itself. A personal token writes as itself (ADR-019); an OAuth access token writes as the
+* client the person allowed, whose id goes with what the client said (ADR-026). The adapters check
+* the scopes of the operation before any handler runs and never route a write for the RPC
+* binding, so reaching one with it is a bug, answered as `internal` before anything is read or
+* written.
+*/
+function actorOf$1(context) {
+	const { principal } = context;
+	if (principal.kind === "token") return {
+		kind: "token",
+		userId: principal.userId,
+		tokenId: principal.tokenId,
+		meta: context.client
+	};
+	if (principal.kind === "oauth") return {
+		kind: "oauth_client",
+		userId: principal.userId,
+		tokenId: null,
+		meta: {
+			...context.client,
+			oauthClient: principal.clientId
+		}
+	};
+	throw internalError$1(context, `A write was routed for a principal of kind ${principal.kind}; only a person writes.`);
+}
+//#endregion
+//#region src/ops/assets.ts
+const NO_BUCKET = {
+	message: "This Hollware keeps no images: its Worker has no R2 bucket bound as MEDIA.",
+	fix: "Add { \"binding\": \"MEDIA\", \"bucket_name\": \"<name>\" } to r2_buckets in wrangler.jsonc, and run hollware deploy, which creates the bucket."
+};
+/** The keys of an asset's files in R2: the file served, and the file as it was uploaded. */
+const servedKey = (site, id) => `sites/${site}/${id}`;
+const originalKey = (site, id) => `originals/${site}/${id}`;
+/** An asset as the operations answer it. */
+function assetView(row, media) {
+	return {
+		id: row.id,
+		reference: `asset:${row.id}`,
+		url: `${media.baseUrl}${row.site}/${row.id}`,
+		format: row.format,
+		width: row.width,
+		height: row.height,
+		bytes: row.bytes,
+		originalFormat: row.originalFormat,
+		originalBytes: row.originalBytes,
+		alt: row.alt,
+		filename: row.filename,
+		createdAt: row.createdAt
+	};
+}
+function bytesOfBase64(data) {
+	const clean = data.replace(/\s/g, "");
+	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(clean) || clean.length % 4 !== 0) return null;
+	const binary = atob(clean);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+async function sha256Of(bytes) {
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The error code of the Images binding, such as 9412 (not an image) or 9422 (no allowance left). */
+function imagesCode(error) {
+	const code = typeof error === "object" && error !== null ? Reflect.get(error, "code") : null;
+	if (typeof code === "number") return code;
+	const match = /\b(9\d{3})\b/.exec(error instanceof Error ? error.message : String(error));
+	return match === null ? null : Number(match[1]);
+}
+const refused$1 = (message, fix) => ({
+	outcome: "refused",
+	problem: {
+		message,
+		fix
+	}
+});
+const NOT_READABLE = refused$1("Cloudflare Images could not read this file as an image: it may be damaged or cut short.", "Open it in an image editor, save it again, and upload that.");
+const NO_ALLOWANCE = {
+	outcome: "unavailable",
+	problem: {
+		message: "This month's allowance of image conversions is used up (5,000 on Cloudflare's Free plan): nothing was kept.",
+		fix: "Upload it next month, set the media format of the site to \"original\" to keep files as they come, or move the account to the Paid plan of Images."
+	}
+};
+const uploadAsset = async (input, context) => {
+	const media = context.media ?? null;
+	if (media === null) return {
+		outcome: "unavailable",
+		problem: NO_BUCKET
+	};
+	const original = bytesOfBase64(input.data);
+	if (original === null || original.length === 0) return refused$1("data is not base64.", "Send the file encoded in base64, with its padding.");
+	if (original.length > MAX_ASSET_BYTES) return refused$1(`The file is ${original.length} bytes, more than the ${MAX_ASSET_BYTES} an image may be.`, "Make it smaller (fewer pixels, or a format such as WebP) and upload it again.");
+	const originalFormat = sniffImage(original);
+	if (originalFormat === null) return refused$1("This file is not an image Hollware takes: JPEG, PNG, WebP, AVIF, GIF or SVG, judged by its bytes.", "Export it as one of those formats and upload it again.");
+	const sha256 = await sha256Of(original);
+	const id = assetIdOf(sha256);
+	const site = context.site.key;
+	const existing = await media.catalog.byId(site, id);
+	if (existing !== null) return {
+		outcome: "exists",
+		asset: assetView(existing, media)
+	};
+	let served = original;
+	let format = originalFormat;
+	let width = null;
+	let height = null;
+	if (originalFormat === "image/svg+xml") {
+		const problem = checkSvg(new TextDecoder().decode(original));
+		if (problem !== null) return refused$1(`This SVG is refused: ${problem.reason}.`, problem.fix);
+	} else if (media.images !== null) try {
+		const info = await media.images.info(original);
+		if ("width" in info) {
+			width = info.width;
+			height = info.height;
+		}
+		const conversion = conversionOf(originalFormat, width, context.site.media);
+		if (conversion !== null) {
+			const converted = await media.images.convert(original, conversion);
+			served = converted.bytes;
+			format = converted.format;
+			if (conversion.width !== void 0 && width !== null && height !== null) {
+				height = Math.max(1, Math.round(height * conversion.width / width));
+				width = conversion.width;
+			}
+		}
+	} catch (error) {
+		const code = imagesCode(error);
+		if (code === 9422) return NO_ALLOWANCE;
+		if (code === 9412) return NOT_READABLE;
+		throw error;
+	}
+	await media.files.put(servedKey(site, id), served, format);
+	await media.files.put(originalKey(site, id), original, originalFormat);
+	const { row, created } = await media.catalog.insert({
+		id,
+		site,
+		sha256,
+		format,
+		width,
+		height,
+		bytes: served.length,
+		originalFormat,
+		originalBytes: original.length,
+		alt: input.alt,
+		filename: input.filename,
+		createdBy: actorOf$1(context).userId,
+		createdAt: context.clock.now().toISOString()
+	});
+	return {
+		outcome: created ? "created" : "exists",
+		asset: assetView(row, media)
+	};
+};
+/** The cursor of a page: the `createdAt` and id of its last row, in base64url. */
+const cursorOf = (row) => btoa(`${row.createdAt}|${row.id}`).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+function parseCursor(cursor) {
+	if (cursor === void 0) return null;
+	try {
+		const padded = cursor.replace(/-/g, "+").replace(/_/g, "/");
+		const [createdAt, id] = atob(padded + "=".repeat((4 - padded.length % 4) % 4)).split("|");
+		return createdAt !== void 0 && id !== void 0 ? {
+			createdAt,
+			id
+		} : null;
+	} catch {
+		return null;
+	}
+}
+const listAssets = async (input, context) => {
+	const media = context.media ?? null;
+	if (media === null) return {
+		outcome: "ok",
+		assets: [],
+		nextCursor: null
+	};
+	const rows = await media.catalog.list(context.site.key, input.limit + 1, parseCursor(input.cursor));
+	const page = rows.slice(0, input.limit);
+	const last = page.at(-1);
+	return {
+		outcome: "ok",
+		assets: page.map((row) => assetView(row, media)),
+		nextCursor: rows.length > input.limit && last !== void 0 ? cursorOf(last) : null
+	};
+};
+const getAsset = async (input, context) => {
+	const media = context.media ?? null;
+	if (media === null) return { outcome: "not_found" };
+	const row = await media.catalog.byId(context.site.key, input.id);
+	return row === null ? { outcome: "not_found" } : {
+		outcome: "ok",
+		asset: assetView(row, media)
+	};
+};
+/**
+* The URL an `asset:` reference of the site resolves to: where the Worker serves the image, or
+* the reference as it is when the Worker serves no media.
+*/
+function assetUrlOf(context) {
+	const base = context.media?.baseUrl;
+	return (id) => base === void 0 ? `asset:${id}` : `${base}${context.site.key}/${id}`;
+}
+/**
+* A value as a read of the published site sees it (RPC, the read API): every `asset:` reference
+* in it as the image's URL. Over MCP, an agent reads what it wrote.
+*/
+function forReaders(context, value) {
+	return context.view === "published" ? resolveAssetReferences(value, assetUrlOf(context)) : value;
+}
+//#endregion
 //#region src/db/d1.ts
 /**
 * Drizzle's D1 driver is typed over a `D1Database`, but at runtime it only calls `prepare` and
@@ -2074,7 +2305,7 @@ function boundedJson(value) {
 * The actor of a principal. A person signed in to the admin is a `user`, with the admin as their
 * client; any other OAuth client is an `oauth_client`; a personal or read token is a `token`.
 */
-function actorOf$1(principal, meta, adminClientId) {
+function actorOf(principal, meta, adminClientId) {
 	if (principal.kind === "oauth") return {
 		kind: principal.clientId === adminClientId ? "user" : "oauth_client",
 		userId: principal.userId,
@@ -2398,7 +2629,7 @@ function createSecretStore(db, now) {
 * went wrong goes to the log and never to the caller, whose agent could repeat it to a person or
 * to another system. The request id is how the operator finds the log line.
 */
-function internalError$1(requestId, cause) {
+function internalError(requestId, cause) {
 	return new HollwareError("internal", "The operation failed on the server.", `Try again. If it keeps failing, give the site operator this request id: ${requestId}.`, { cause });
 }
 /** The fix of `timeout`, by effect: a write that ran out of time may still finish. */
@@ -3532,7 +3763,8 @@ const NAMING_FIELDS = [
 	"id",
 	"entryId",
 	"reviewId",
-	"name"
+	"name",
+	"filename"
 ];
 const FIELD_MAX = 200;
 function isAudited(name) {
@@ -3545,7 +3777,7 @@ function idOf(value) {
 	const id = record(value)["id"];
 	return typeof id === "string" ? id : null;
 }
-/** What the call acted on: the entry, review or comment of its answer, else its site. */
+/** What the call acted on: the entry, review, comment or asset of its answer, else its site. */
 function targetOf(output, site) {
 	const entry = idOf(output["entry"]);
 	if (entry !== null) return {
@@ -3562,6 +3794,11 @@ function targetOf(output, site) {
 		type: "comment",
 		id: comment
 	};
+	const asset = idOf(output["asset"]);
+	if (asset !== null) return {
+		type: "asset",
+		id: asset
+	};
 	return {
 		type: "site",
 		id: site
@@ -3704,6 +3941,116 @@ function semanticOfEnv(env) {
 	return semanticOf(env, typeof model === "string" && model !== "" ? model : DEFAULT_EMBEDDING_MODEL);
 }
 //#endregion
+//#region src/media/cloudflare.ts
+const streamOf = (bytes) => new Blob([bytes]).stream();
+/** R2 as the store of asset files. */
+function r2Files(bucket) {
+	return {
+		async put(key, bytes, contentType) {
+			await bucket.put(key, bytes, { httpMetadata: { contentType } });
+		},
+		async get(key) {
+			const object = await bucket.get(key);
+			if (object === null) return null;
+			return {
+				body: object.body,
+				contentType: object.httpMetadata?.contentType ?? "application/octet-stream"
+			};
+		}
+	};
+}
+function imagesConverter(images) {
+	return {
+		async info(bytes) {
+			const info = await images.info(streamOf(bytes));
+			if (typeof info !== "object" || info === null) throw new Error("Images answered no info");
+			const format = Reflect.get(info, "format");
+			if (format === "image/svg+xml") return { format };
+			const width = Reflect.get(info, "width");
+			const height = Reflect.get(info, "height");
+			if (typeof format !== "string" || typeof width !== "number" || typeof height !== "number") throw new Error("Images answered an info without format, width and height");
+			return {
+				format,
+				width,
+				height
+			};
+		},
+		async convert(bytes, conversion) {
+			let transformer = images.input(streamOf(bytes));
+			if (conversion.width !== void 0) transformer = transformer.transform({
+				width: conversion.width,
+				fit: "scale-down"
+			});
+			const result = await transformer.output({
+				format: conversion.format,
+				quality: conversion.quality,
+				anim: conversion.anim
+			});
+			return {
+				bytes: new Uint8Array(await new Response(result.image()).arrayBuffer()),
+				format: result.contentType()
+			};
+		}
+	};
+}
+const rowOf = (row) => ({
+	id: row.id,
+	site: row.site_id,
+	sha256: row.sha256,
+	format: row.format,
+	width: row.width,
+	height: row.height,
+	bytes: row.bytes,
+	originalFormat: row.original_format,
+	originalBytes: row.original_bytes,
+	alt: row.alt,
+	filename: row.filename,
+	createdBy: row.created_by,
+	createdAt: row.created_at
+});
+/** The rows of `assets` in D1, always of one site. */
+function d1Catalog(db) {
+	const byId = async (site, id) => {
+		const row = await db.prepare("SELECT * FROM assets WHERE site_id = ? AND id = ?").bind(site, id).first();
+		return row === null ? null : rowOf(row);
+	};
+	return {
+		byId,
+		async insert(asset) {
+			const written = await db.prepare(`INSERT INTO assets (id, site_id, sha256, format, width, height, bytes, original_format,
+             original_bytes, alt, filename, created_by, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT (site_id, sha256) DO NOTHING
+           RETURNING *`).bind(asset.id, asset.site, asset.sha256, asset.format, asset.width, asset.height, asset.bytes, asset.originalFormat, asset.originalBytes, asset.alt, asset.filename, asset.createdBy, asset.createdAt, asset.createdAt).first();
+			if (written !== null) return {
+				row: rowOf(written),
+				created: true
+			};
+			const existing = await db.prepare("SELECT * FROM assets WHERE site_id = ? AND sha256 = ?").bind(asset.site, asset.sha256).first();
+			if (existing === null) throw new Error(`No asset of ${asset.sha256} after a conflict`);
+			return {
+				row: rowOf(existing),
+				created: false
+			};
+		},
+		async list(site, limit, cursor) {
+			const { results } = await (cursor === null ? db.prepare("SELECT * FROM assets WHERE site_id = ? ORDER BY created_at DESC, id DESC LIMIT ?").bind(site, limit) : db.prepare(`SELECT * FROM assets WHERE site_id = ? AND (created_at, id) < (?, ?)
+                 ORDER BY created_at DESC, id DESC LIMIT ?`).bind(site, cursor.createdAt, cursor.id, limit)).all();
+			return results.map(rowOf);
+		}
+	};
+}
+/** Media of a Worker: `null` without its R2 bucket, and without conversion when `IMAGES` is not bound. */
+function mediaOfEnv(env) {
+	if (env.MEDIA === void 0 || env.HOLLWARE_PUBLIC_URL === void 0) return null;
+	return {
+		files: r2Files(env.MEDIA),
+		images: env.IMAGES === void 0 ? null : imagesConverter(env.IMAGES),
+		catalog: d1Catalog(env.DB),
+		baseUrl: `${env.HOLLWARE_PUBLIC_URL.replace(/\/$/, "")}/assets/`
+	};
+}
+//#endregion
 //#region src/analytics/cloudflare.ts
 /** The dataset of Analytics Engine when the Worker names none. */
 const DEFAULT_ANALYTICS_DATASET = "hollware_page_views";
@@ -3863,6 +4210,7 @@ function installOpsApi(app, options) {
 			notify: options.notify(c, requestId, site.key),
 			semantic: semanticOfEnv(c.env),
 			analytics: analyticsReaderOf(c.env),
+			media: mediaOfEnv(c.env),
 			...options.structure === void 0 ? {} : { structure: options.structure(c.env.DB, c.env.HOLLWARE_SECRET) }
 		};
 		/** The line of the call, after it answered or failed. */
@@ -4188,7 +4536,7 @@ async function writeForPerson(db, log, siteOf, userId, line) {
 * The ceremonies, with SimpleWebAuthn and its parsers, in a chunk of their own: only these four
 * routes use them, and a Worker that serves MCP never pays for them at startup (`budgets.json`).
 */
-const ceremonies = () => import("./ceremonies-CI3DkOEL.mjs");
+const ceremonies = () => import("./ceremonies-zTn1U6BD.mjs");
 /**
 * The cookie of a signed-in person: only `/authorize` reads it (ADR-026), and the sign-out below
 * it, `/authorize/signout`, which the path of the cookie reaches too.
@@ -4819,7 +5167,7 @@ function createGateway(options) {
 	* The activity log of a request (ADR-037), for an actor known once the client has said what it
 	* is. A person in the admin is a `user`; any other OAuth client, an `oauth_client`.
 	*/
-	const auditOf = (c, principal, adminClientId) => (meta) => auditAs(c, actorOf$1(principal, meta, adminClientId));
+	const auditOf = (c, principal, adminClientId) => (meta) => auditAs(c, actorOf(principal, meta, adminClientId));
 	/**
 	* A protected route: the resource server of `resource` answers a request without a token and a
 	* token it refuses (401, logged with the reason), and `proceed` gets the principal of the rest.
@@ -4889,9 +5237,10 @@ function createGateway(options) {
 		c.set("requestId", crypto.randomUUID());
 		await next();
 		const https = c.env.HOLLWARE_PUBLIC_URL?.startsWith("https://") === true;
-		if (!(!c.res.headers.has("x-content-type-options") || https && !c.res.headers.has("strict-transport-security"))) return;
+		if (!(!c.res.headers.has("x-content-type-options") || !c.res.headers.has("x-robots-tag") || https && !c.res.headers.has("strict-transport-security"))) return;
 		const headers = new Headers(c.res.headers);
 		if (!headers.has("x-content-type-options")) headers.set("x-content-type-options", "nosniff");
+		if (!headers.has("x-robots-tag")) headers.set("x-robots-tag", "noindex, nofollow");
 		if (https && !headers.has("strict-transport-security")) headers.set("strict-transport-security", "max-age=31536000");
 		c.res = new Response(c.res.body, {
 			status: c.res.status,
@@ -4938,6 +5287,10 @@ function createGateway(options) {
 		await options.refresh?.(c.env.DB);
 		await next();
 	});
+	app.get("/robots.txt", () => new Response("User-agent: *\nDisallow: /\n", { headers: {
+		"content-type": "text/plain; charset=utf-8",
+		"cache-control": "public, max-age=86400"
+	} }));
 	app.get("/health", () => Response.json({ ok: true }, { headers: { "cache-control": "no-store" } }));
 	app.all("/mcp", async (c) => protectWrites(c, "mcp", async (principal) => {
 		const requestId = c.get("requestId");
@@ -4955,7 +5308,8 @@ function createGateway(options) {
 				notify: notify(c, requestId, site.key),
 				semantic: semanticOfEnv(c.env),
 				analytics: analyticsReaderOf(c.env),
-				structure: structureOf(db, c.env.HOLLWARE_SECRET)
+				structure: structureOf(db, c.env.HOLLWARE_SECRET),
+				media: mediaOfEnv(c.env)
 			},
 			...principal.kind === "read" ? {} : { audit: {
 				log: auditOf(c, principal, null),
@@ -5049,6 +5403,45 @@ function createGateway(options) {
 		structure: structureOf,
 		audit: async (c, principal) => auditOf(c, principal, (await adminClient(oauth(c.env.HOLLWARE_PUBLIC_URL), c.env)).clientId)
 	});
+	app.get("/assets/:site/:id", async (c) => {
+		const { site, id } = c.req.param();
+		const media = mediaOfEnv(c.env);
+		const file = media === null || !isSiteKey(site) || !ASSET_ID.test(id) ? null : await media.files.get(servedKey(site, id));
+		if (file === null) return Response.json({
+			code: "not_found",
+			message: "There is no image at this URL.",
+			fix: "Use the url that upload_asset or get_asset gave the image."
+		}, {
+			status: 404,
+			headers: { "cache-control": "no-store" }
+		});
+		const headers = new Headers({
+			"content-type": file.contentType,
+			"cache-control": "public, max-age=31536000, immutable",
+			"cross-origin-resource-policy": "cross-origin"
+		});
+		if (file.contentType === "image/svg+xml") headers.set("content-security-policy", "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+		return new Response(file.body, { headers });
+	});
+	app.get("/v1/assets/:id/original", (c) => protectWrites(c, "v1", async (principal) => {
+		if (missingScopes(principal, ["content:read"]).length > 0) return insufficientScope(["content:read"], oauth(c.env.HOLLWARE_PUBLIC_URL).metadataUrls.v1);
+		const id = c.req.param("id");
+		const media = mediaOfEnv(c.env);
+		const row = media === null || !ASSET_ID.test(id) ? null : await media.catalog.byId(principal.site, id);
+		const file = media === null || row === null ? null : await media.files.get(originalKey(row.site, row.id));
+		if (file === null) return Response.json({
+			code: "not_found",
+			message: `The site has no image ${id}.`,
+			fix: "List the images of the site with list_assets."
+		}, {
+			status: 404,
+			headers: { "cache-control": "no-store" }
+		});
+		return new Response(file.body, { headers: {
+			"content-type": file.contentType,
+			"cache-control": "private, no-store"
+		} });
+	}));
 	if (options.read !== void 0) installReadApi(app, {
 		read: options.read,
 		corsOrigins: (site) => sites.get(site)?.cors.origins ?? [],
@@ -5063,6 +5456,8 @@ function createGateway(options) {
 		return await app.fetch(request, env, ctx);
 	};
 }
+/** The id of an asset: `ast_` and 26 hexadecimal characters, from the hash of its file. */
+const ASSET_ID = /^ast_[0-9a-f]{26}$/;
 /** The group of a route that is rate limited, or `null` for one that is not (T-10). */
 function limitedRoute(method, pathname) {
 	if (method !== "POST") return null;
@@ -5261,6 +5656,9 @@ const OUTPUT_TOO_LARGE_FIX = {
 	get_translations: "The translations do not fit in one answer. Read each one with get_entry instead.",
 	list_entries: "Ask for less: pass a smaller limit, or narrow the list with locale, tag or status.",
 	list_reviews: "Ask for less: pass a smaller limit.",
+	list_assets: "Ask for less: pass a smaller limit.",
+	get_asset: "Nothing to ask for less of: the answer is one asset. Try again.",
+	upload_asset: "The operation ran and the image may have been kept: list the images with list_assets before you upload it again.",
 	publish: "The operation ran and its change may have been applied: read the entry with get_entry before you repeat it.",
 	request_changes: "The operation ran and its change may have been applied: read the review with list_reviews before you repeat it.",
 	request_review: "The operation ran and its review may have been asked: read it with list_reviews before you repeat it.",
@@ -5535,7 +5933,7 @@ function createMcpEndpoint(options) {
 		try {
 			result = spec.name === "publish" ? await performPublish() : answerResult(spec, await perform(input));
 		} catch (error) {
-			failure = error instanceof HollwareError ? error : internalError$1(call.requestId, error);
+			failure = error instanceof HollwareError ? error : internalError(call.requestId, error);
 			isError = true;
 			result = errorResult(failure);
 		}
@@ -5727,7 +6125,8 @@ async function run(deps, env, method, site, schema, build, handler, viewOf = ()
 		clock: deps.clock,
 		client: null,
 		requestId,
-		semantic: semanticOfEnv(env)
+		semantic: semanticOfEnv(env),
+		media: mediaOfEnv(env)
 	};
 	try {
 		return await handler(input, context);
@@ -6352,53 +6751,6 @@ const contentStats = async (input, context) => {
 	};
 };
 //#endregion
-//#region src/ops/errors.ts
-/**
-* The error of something that must never happen: a bug of Hollware, not a mistake of the caller.
-* Like the `internal` error of the adapters, its message says nothing about the cause, which goes
-* to the log through `cause`, and its fix names the request id the operator finds the log line by.
-*/
-function internalError(context, cause) {
-	return new HollwareError("internal", "The operation failed on the server.", `Try again. If it keeps failing, give the site operator this request id: ${context.requestId}.`, { cause: new Error(cause) });
-}
-/**
-* The error for an answer of the store that the call it came from can never get: an entry that
-* is created cannot conflict, a publish has no slug to take. It is a bug, not an outcome of the
-* operation, so it is not one of the outcomes of its spec.
-*/
-function unexpectedAnswer(context, call, answer) {
-	return internalError(context, `The store answered ${answer.outcome} to ${call}, which it never does.`);
-}
-//#endregion
-//#region src/ops/actor.ts
-/**
-* Who a write is made by: the person behind the token of the call, with what its client said
-* about itself. A personal token writes as itself (ADR-019); an OAuth access token writes as the
-* client the person allowed, whose id goes with what the client said (ADR-026). The adapters check
-* the scopes of the operation before any handler runs and never route a write for the RPC
-* binding, so reaching one with it is a bug, answered as `internal` before anything is read or
-* written.
-*/
-function actorOf(context) {
-	const { principal } = context;
-	if (principal.kind === "token") return {
-		kind: "token",
-		userId: principal.userId,
-		tokenId: principal.tokenId,
-		meta: context.client
-	};
-	if (principal.kind === "oauth") return {
-		kind: "oauth_client",
-		userId: principal.userId,
-		tokenId: null,
-		meta: {
-			...context.client,
-			oauthClient: principal.clientId
-		}
-	};
-	throw internalError(context, `A write was routed for a principal of kind ${principal.kind}; only a person writes.`);
-}
-//#endregion
 //#region src/ops/collections.ts
 /**
 * Which collection and locale a call names, checked against the config of the site before
@@ -6528,7 +6880,7 @@ function revisionOf(input) {
 const createDraft = async (input, context) => {
 	const collection = requireCollection(context.site, input.collection);
 	requireLocale(context.site, input.locale);
-	const actor = actorOf(context);
+	const actor = actorOf$1(context);
 	const processed = await processFor(context.site, collection, input.markdown);
 	if (!processed.ok) return {
 		outcome: "refused",
@@ -6605,13 +6957,13 @@ const getEntry$1 = async (input, context) => {
 	return {
 		outcome: "ok",
 		entry: {
-			...entrySummary(found),
+			...forReaders(context, entrySummary(found)),
 			revision: revision.id,
 			verdict: verdictView(revision.verdict),
 			lastPublication: publicationView(publication),
 			...input.formats.includes("markdown") ? { markdown: revision.markdown } : {},
-			...input.formats.includes("document") ? { document: revision.document } : {},
-			...input.formats.includes("html") ? { html: await renderHtml(revision.document) } : {}
+			...input.formats.includes("document") ? { document: forReaders(context, revision.document) } : {},
+			...input.formats.includes("html") ? { html: await renderHtml(resolveAssetReferences(revision.document, assetUrlOf(context))) } : {}
 		},
 		...related === void 0 ? {} : { related }
 	};
@@ -6635,7 +6987,7 @@ const getTranslations$1 = async (input, context) => {
 	if (group.length === 0) return { outcome: "not_found" };
 	return {
 		outcome: "ok",
-		entries: group.map(entrySummary)
+		entries: group.map((entry) => forReaders(context, entrySummary(entry)))
 	};
 };
 //#endregion
@@ -6656,7 +7008,7 @@ const listEntries$1 = async (input, context) => {
 	});
 	return {
 		outcome: "ok",
-		entries: page.entries.map(entrySummary),
+		entries: page.entries.map((entry) => forReaders(context, entrySummary(entry))),
 		nextCursor: page.nextCursor
 	};
 };
@@ -6741,7 +7093,7 @@ const search$1 = async (input, context) => {
 		outcome: "ok",
 		mode,
 		results: hits.map((hit) => ({
-			entry: entrySummary(hit.entry),
+			entry: forReaders(context, entrySummary(hit.entry)),
 			snippet: hit.snippet,
 			score: hit.score
 		}))
@@ -6794,11 +7146,11 @@ function siteEventFor(input) {
 /** How many slugs of refused entries an answer names. */
 const EXAMPLES = 3;
 function structureOf(context) {
-	if (context.structure === void 0) throw internalError(context, "An operation on the structure ran where the structure is not reachable.");
+	if (context.structure === void 0) throw internalError$1(context, "An operation on the structure ran where the structure is not reachable.");
 	return context.structure;
 }
 function actor(context) {
-	const { userId, meta } = actorOf(context);
+	const { userId, meta } = actorOf$1(context);
 	return {
 		userId,
 		meta
@@ -6849,7 +7201,7 @@ async function impactOf(context, store, current, next) {
 /** The definition of the site of the call, as stored, with its version. */
 async function currentOf(context) {
 	const stored = await structureOf(context).store.read(context.site.key);
-	if (stored === null) throw internalError(context, `The site ${context.site.key} is served and has no definition in D1.`);
+	if (stored === null) throw internalError$1(context, `The site ${context.site.key} is served and has no definition in D1.`);
 	return {
 		version: stored.version,
 		definition: siteDefinitionData.parse(stored.definition)
@@ -7027,7 +7379,7 @@ const publish$1 = async (input, context) => {
 	const mayPublish = context.principal.scopes.includes("content:publish");
 	if (!mayPublish && (input.group.length > 0 || input.publishAt !== void 0)) throw new HollwareError("invalid_input", "Without content:publish, publish asks for a review of one entry, now: not of a group, and not at a time.", "Publish each entry on its own, without group and publishAt; a person who may publish approves it.");
 	if (input.group.length > 0) return publishGroup(input, context);
-	const actor = actorOf(context);
+	const actor = actorOf$1(context);
 	const found = await context.store.findEntryById(context.site.key, input.id, "head");
 	if (found === null) return { outcome: "not_found" };
 	const { entry, revision } = found;
@@ -7173,7 +7525,7 @@ function asPublished(lookup, ids) {
 */
 async function publishGroup(input, context) {
 	if (input.publishAt !== void 0) throw new HollwareError("invalid_input", "A group cannot be scheduled: publishAt schedules one entry.", "Publish the group now, without publishAt, or schedule its entries one by one.");
-	const actor = actorOf(context);
+	const actor = actorOf$1(context);
 	const members = [{
 		id: input.id,
 		version: input.version
@@ -7360,7 +7712,7 @@ const approveReview = async (input, context) => {
 };
 /** Closes a pending review with a note, without publishing. */
 const requestChanges = async (input, context) => {
-	const { userId } = actorOf(context);
+	const { userId } = actorOf$1(context);
 	const closed = await context.store.requestChanges(context.site.key, {
 		id: input.id,
 		note: input.note,
@@ -7379,7 +7731,7 @@ const requestChanges = async (input, context) => {
 const commentReview = async (input, context) => {
 	const answer = await context.store.commentReview(context.site.key, {
 		reviewId: input.id,
-		actor: actorOf(context),
+		actor: actorOf$1(context),
 		body: input.body
 	});
 	return answer.outcome === "commented" ? {
@@ -7475,7 +7827,7 @@ const restoreEntry = async (input, context) => {
 * leaves an entry that is not published as it is.
 */
 const unpublish = async (input, context) => {
-	const actor = actorOf(context);
+	const actor = actorOf$1(context);
 	const found = await context.store.findEntryById(context.site.key, input.id, "head");
 	if (found === null) return { outcome: "not_found" };
 	const { entry } = found;
@@ -7519,7 +7871,7 @@ const unpublish = async (input, context) => {
 * no revision and no version, which is what makes importing the same files twice a no-op.
 */
 const updateDraft = async (input, context) => {
-	const actor = actorOf(context);
+	const actor = actorOf$1(context);
 	const found = await context.store.findEntryById(context.site.key, input.id, "head");
 	if (found === null) return { outcome: "not_found" };
 	const { entry, revision } = found;
@@ -7620,9 +7972,11 @@ const handlers = defineHandlers({
 	delete_entry: deleteEntry,
 	delete_site: deleteSite,
 	describe_site: describeSite$1,
+	get_asset: getAsset,
 	get_entry: getEntry$1,
 	get_structure: getStructure,
 	get_translations: getTranslations$1,
+	list_assets: listAssets,
 	list_entries: listEntries$1,
 	search: search$1,
 	list_reviews: listReviews,
@@ -7636,6 +7990,7 @@ const handlers = defineHandlers({
 	unpublish,
 	update_site: updateSite,
 	update_draft: updateDraft,
+	upload_asset: uploadAsset,
 	validate
 });
 //#endregion