hecks 3.9.1 → 3.10.0

data/lib/hecks/projections/site/cms_editor/templates/src/auth/session.ts.tmpl

@@ -0,0 +1,36 @@
+__BANNER__
+
+// The editor's own session: a signed cookie naming who signed in and until when. It is not the
+// host's session cookie and carries no authority by itself; every request still asks the membership
+// list (membership.ts). The value has the host's account-token format, signed with the shared secret
+// plus a suffix, so a host token cannot be passed off as an editor session.
+import { accountToken, cookieValue, verifyAccountToken } from "@hecks/client";
+
+import { EDITOR } from "../config.ts";
+
+const SUFFIX = ":editor-session";
+
+/** The cookie value for `email`, good for the configured session age. */
+export function signSession(secret: string, email: string, now: () => number = Date.now): string {
+  return accountToken(secret + SUFFIX, email, EDITOR.sessionMaxAge, { now });
+}
+
+/** The email a `Cookie` header's session names, or null when it is absent, forged or expired. */
+export function readSession(header: string | null, secret: string, now: () => number = Date.now): string | null {
+  const value = cookieValue(header, EDITOR.sessionCookie);
+  if (!value || !secret) return null;
+  return verifyAccountToken(value, secret + SUFFIX, { now, normalizeEmail: true })?.email ?? null;
+}
+
+const ATTRIBUTES = `Path=${EDITOR.basePath}; HttpOnly; SameSite=Lax`;
+
+/** The `Set-Cookie` value that starts a session. `Secure` is added outside local development. */
+export function sessionCookie(value: string): string {
+  const secure = process.env.NODE_ENV === "production" ? "; Secure" : "";
+  return `${EDITOR.sessionCookie}=${value}; ${ATTRIBUTES}; Max-Age=${EDITOR.sessionMaxAge}${secure}`;
+}
+
+/** The `Set-Cookie` value that ends a session. */
+export function clearedCookie(): string {
+  return `${EDITOR.sessionCookie}=; ${ATTRIBUTES}; Max-Age=0`;
+}

data/lib/hecks/projections/site/cms_editor/templates/src/auth/sso.ts.tmpl

@@ -0,0 +1,20 @@
+__BANNER__
+
+// The sign-in. The site's admin hand-off sends a signed-in admin here with a short-lived account
+// token from the host (the same hand-off that opens a content system). The token proves an account,
+// not an editor, so nobody gets a session unless the membership list admits them now.
+import { verifyAccountToken } from "@hecks/client";
+
+import { EDITOR } from "../config.ts";
+import type { Membership } from "./membership.ts";
+import { signSession, sessionCookie } from "./session.ts";
+
+export type SignIn = { ok: true; location: string; cookie: string } | { ok: false; status: number; message: string };
+
+/** Checks the hand-off token and starts a session for the person it names. */
+export async function signIn(token: string | null, secret: string, membership: Membership, now: () => number = Date.now): Promise<SignIn> {
+  const claims = token && secret ? verifyAccountToken(token, secret, { now, normalizeEmail: true }) : null;
+  if (!claims) return { ok: false, status: 401, message: "Invalid or expired sign-in token." };
+  if (!(await membership.isAdmitted(claims.email))) return { ok: false, status: 403, message: "This account is not an editor." };
+  return { ok: true, location: EDITOR.basePath, cookie: sessionCookie(signSession(secret, claims.email, now)) };
+}

data/lib/hecks/projections/site/cms_editor/templates/src/commands.ts.tmpl

@@ -0,0 +1,79 @@
+__BANNER__
+
+// Running one command and judging what came of it. The host answers HTTP 200 whether or not the
+// domain refused, and its `refusals` list can carry entries replayed from history, so the outcome is
+// judged by the state that comes back: the instance has to show the change. Only when the state did
+// not change at all (a repeated command, a lifecycle move to the state it is already in) does the
+// answer's last refusal decide, and only if it names this verb.
+import type { Answer, HostClient } from "@hecks/client";
+import { DomainUnavailable } from "@hecks/client";
+
+import type { Aggregate, Command } from "./schema.ts";
+
+export type State = Record<string, unknown>;
+export type Outcome = { ok: true; id: string } | { ok: false; message: string };
+
+/** The text an identity value holds: the part of a value object, or the plain value. */
+export function leaf(value: unknown): string | null {
+  if (value && typeof value === "object") return leaf(Object.values(value as object).find((part) => part !== null && part !== undefined));
+  return value === null || value === undefined ? null : String(value);
+}
+
+/** The id an instance is addressed by. */
+export const idOf = (agg: Aggregate, state: State | undefined): string | null => leaf(state?.[agg.identity]);
+
+/** The state of one instance in an answer, or undefined when the answer holds none by that id. */
+export function instanceIn(client: HostClient, answer: Answer, agg: Aggregate, id: string): State | undefined {
+  return client.instancesOf(answer, agg.name).find(([key]) => key === id)?.[1];
+}
+
+/** True when everything `sent` carries is in `held`; numbers and their text compare equal. */
+export function covers(sent: unknown, held: unknown): boolean {
+  if (Array.isArray(sent)) return Array.isArray(held) && sent.length === held.length && sent.every((item, at) => covers(item, held[at]));
+  if (sent && typeof sent === "object") {
+    const keys = Object.keys(sent);
+    if (!held || typeof held !== "object") return keys.length === 1 && covers((sent as State)[keys[0]], held);
+    return keys.every((key) => covers((sent as State)[key], (held as State)[key]));
+  }
+  return String(sent) === String(held);
+}
+
+const sameState = (a: State | undefined, b: State | undefined): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+function refusedLast(answer: Answer, agg: Aggregate, command: Command): boolean {
+  const last = (answer.refusals ?? []).at(-1);
+  return last !== undefined && String(last.verb ?? "").replace(/^.*::/, "") === `${agg.name}.${command.name}`;
+}
+
+/** Whether `after` shows the command took effect, given the instance as it was `before`. */
+export function applied(agg: Aggregate, command: Command, args: State, before: State | undefined, after: State | undefined, answer: Answer): boolean {
+  if (!after) return false;
+  if (sameState(before, after)) return !refusedLast(answer, agg, command);
+  const move = agg.lifecycle?.transitions.find((transition) => transition.verb === command.name);
+  if (move && agg.lifecycle) return after[agg.lifecycle.field] === move.to;
+  return covers(args, after);
+}
+
+/** The words for a command that changed nothing: the host's last refusal, or a plain statement. */
+export function refusalMessage(answer: Answer, command: Command): string {
+  const last = (answer.refusals ?? []).at(-1);
+  return last?.error ?? `The domain did not apply ${command.name}.`;
+}
+
+/**
+ * Dispatches `command` as the role it declares and judges the outcome. `to` is the instance a
+ * non-creating command acts on; a creating command's instance is addressed by what it was given.
+ */
+export async function runCommand(client: HostClient, agg: Aggregate, command: Command, args: State, to?: string): Promise<Outcome> {
+  try {
+    const id = to ?? idOf(agg, args);
+    const before = id ? instanceIn(client, await client.read(), agg, id) : undefined;
+    const answer = await client.dispatch(`${agg.name}.${command.name}`, args, to, command.role ?? undefined);
+    const after = id ? instanceIn(client, answer, agg, id) : undefined;
+    if (id && applied(agg, command, args, before, after, answer)) return { ok: true, id };
+    return { ok: false, message: refusalMessage(answer, command) };
+  } catch (err) {
+    if (err instanceof DomainUnavailable) return { ok: false, message: `The domain could not be reached: ${err.message}` };
+    throw err;
+  }
+}

data/lib/hecks/projections/site/cms_editor/templates/src/config.ts.tmpl

@@ -0,0 +1,23 @@
+__BANNER__
+
+// What the editor is built from: the project's Editor row, defaults filled. Change the row and run
+// `hecks site site_projection.project_site`; with `--check` it fails when this file is out of date.
+
+export const EDITOR = {
+  title: __TITLE__,
+  basePath: __BASE_PATH__,
+  ssoPath: __SSO_PATH__,
+  login: __LOGIN__,
+  sessionCookie: __SESSION_COOKIE__,
+  sessionMaxAge: 28800,
+  hostCookie: __HOST_COOKIE__,
+  hostEnv: __HOST_ENV__,
+  hostDefault: __HOST_DEFAULT__,
+  roles: __ROLES__,
+  mediaDir: __MEDIA_DIR__,
+  mediaMaxBytes: __MEDIA_MAX_BYTES__,
+  accountPath: "/accounts/me",
+  membersPath: "/members",
+  rememberMs: 60000,
+  timeoutMs: 5000,
+} as const;

data/lib/hecks/projections/site/cms_editor/templates/src/host.ts.tmpl

@@ -0,0 +1,26 @@
+__BANNER__
+
+// The domain host, reached the way every server-side caller reaches it: @hecks/client's HostClient
+// posting to /dispatch from this machine. The host accepts that protocol from a loopback peer only,
+// which is why this server, not the browser, talks to it; it authenticates each person itself
+// (auth/) before any of these calls is made on their behalf.
+import { HostClient } from "@hecks/client";
+
+import { EDITOR } from "./config.ts";
+import { SCHEMA } from "./schema.ts";
+
+export interface HostOptions {
+  /** The host's address, when not read from the environment variable the Editor row names. */
+  url?: string;
+  fetch?: typeof fetch;
+}
+
+/** The host's base URL, without a trailing slash. */
+export function hostUrl(options: HostOptions = {}): string {
+  return (options.url ?? (process.env[EDITOR.hostEnv] || EDITOR.hostDefault)).replace(/\/+$/, "");
+}
+
+/** A client for the domain this editor edits. */
+export function hostClient(options: HostOptions = {}): HostClient {
+  return new HostClient({ domain: SCHEMA.domain, url: hostUrl(options), fetch: options.fetch, timeoutMs: EDITOR.timeoutMs });
+}

data/lib/hecks/projections/site/cms_editor/templates/src/media/handler.ts.tmpl

@@ -0,0 +1,154 @@
+__BANNER__
+
+// The pictures: `POST <base>/media` takes an upload, `GET <base>/media` lists the registered
+// pictures, and `GET <base>/media/<key>` serves one. Every request reaching here is already
+// authenticated by app.ts; nothing is read or written before that.
+//
+// An upload is checked before anything is kept: a bounded read of the body, an allow-list of raster
+// types decided by the picture's own first bytes, a size cap from the Editor row, and alt text. The
+// bytes then go through the storage port under a key made from their own digest, and the domain's
+// register-picture command records the picture (key, alt text, type, size). The domain never holds
+// the bytes, and a client-supplied filename is never used.
+import { createHash } from "node:crypto";
+
+import { DomainRefusal, rowsOf } from "@hecks/client";
+import type { HostClient } from "@hecks/client";
+
+import { instanceIn, leaf, runCommand } from "../commands.ts";
+import type { State } from "../commands.ts";
+import { EDITOR } from "../config.ts";
+import { SCHEMA } from "../schema.ts";
+import type { Aggregate, Media, MediaField } from "../schema.ts";
+import { boundaryOf, parts } from "./multipart.ts";
+import { EXTENSION_OF, KEY_PATTERN, TYPE_OF, sizeOf, sniff } from "./sniff.ts";
+import { diskStorage } from "./storage.ts";
+import type { MediaStorage } from "./storage.ts";
+
+/** The room the form's framing takes beyond the picture's own size cap. */
+const OVERHEAD_BYTES = 65_536;
+
+const json = (value: unknown, status = 200): Response =>
+  new Response(JSON.stringify(value), { status, headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" } });
+
+const refuse = (status: number, error: string): Response => json({ error }, status);
+
+/** The body, or null when it is larger than `limit`: no more than `limit` bytes are ever held. */
+async function readBounded(request: Request, limit: number): Promise<Uint8Array | null> {
+  const declared = Number(request.headers.get("content-length") ?? 0);
+  if (declared > limit) return null;
+  const reader = request.body?.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (reader) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > limit) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+
+/** A value as the command takes it: in the value object's part when the attribute is one. */
+function sent(field: MediaField, value: string | number): unknown {
+  return field.wrap ? { [field.wrap]: value } : value;
+}
+
+function recordOf(media: Media, key: string, alt: string, mime: string, bytes: Uint8Array): State {
+  const record: State = {
+    [media.fields.key.name]: sent(media.fields.key, key),
+    [media.fields.alt.name]: sent(media.fields.alt, alt),
+    [media.fields.mime.name]: sent(media.fields.mime, mime),
+  };
+  const size = sizeOf(bytes, mime);
+  const { width, height } = media.fields;
+  if (size && width) record[width.name] = sent(width, size.width);
+  if (size && height) record[height.name] = sent(height, size.height);
+  return record;
+}
+
+function picture(storage: MediaStorage, media: Media, state: State) {
+  const key = leaf(state[media.fields.key.name]);
+  return key === null ? null : { key, alt: leaf(state[media.fields.alt.name]) ?? "", mime: leaf(state[media.fields.mime.name]) ?? "", url: storage.url(key) };
+}
+
+function aggregateOf(media: Media): Aggregate {
+  return SCHEMA.aggregates.find((candidate) => candidate.name === media.aggregate) as Aggregate;
+}
+
+/** What was uploaded, or the refusal to answer with. */
+async function received(request: Request): Promise<{ file: Uint8Array; alt: string; error?: undefined } | { error: Response }> {
+  const limit = EDITOR.mediaMaxBytes;
+  const body = await readBounded(request, limit + OVERHEAD_BYTES);
+  if (!body) return { error: refuse(413, `A picture may be at most ${limit} bytes.`) };
+  const boundary = boundaryOf(request.headers.get("content-type"));
+  const sections = boundary ? parts(body, boundary) : [];
+  const file = sections.find((part) => part.name === "file" && part.filename !== null);
+  if (!file || file.data.length === 0) return { error: refuse(400, "Choose a picture to upload.") };
+  if (file.data.length > limit) return { error: refuse(413, `A picture may be at most ${limit} bytes.`) };
+  const alt = Buffer.from(sections.find((part) => part.name === "alt")?.data ?? []).toString("utf8").trim();
+  return { file: file.data, alt };
+}
+
+async function upload(client: HostClient, storage: MediaStorage, request: Request, media: Media): Promise<Response> {
+  const got = await received(request);
+  if (got.error) return got.error;
+  const mime = sniff(got.file);
+  if (!mime) return refuse(415, "Only JPEG, PNG, WebP, GIF and AVIF pictures are accepted.");
+  if (got.alt === "") return refuse(422, "Describe the picture in alt text before adding it.");
+  const key = `${createHash("sha256").update(got.file).digest("hex")}.${EXTENSION_OF[mime]}`;
+  const agg = aggregateOf(media);
+  const answer = await client.read();
+  const known = instanceIn(client, answer, agg, key);
+  if (known) return json({ ...picture(storage, media, known), registered: false });
+  await storage.put(key, got.file, mime);
+  const command = agg.commands.find((candidate) => candidate.name === media.command) as NonNullable<typeof agg.commands[number]>;
+  const outcome = await runCommand(client, agg, command, recordOf(media, key, got.alt, mime, got.file));
+  if (!outcome.ok) return refuse(422, outcome.message);
+  return json({ key, alt: got.alt, mime, url: storage.url(key), registered: true }, 201);
+}
+
+async function stateOf(client: HostClient, media: Media): Promise<State[]> {
+  const agg = aggregateOf(media);
+  if (!media.listing) return client.instancesOf(await client.read(), agg.name).map(([, state]) => state);
+  const name = `${agg.name}.${media.listing}`;
+  return (rowsOf(await client.query(name, {}), name) ?? []) as State[];
+}
+
+async function listing(client: HostClient, storage: MediaStorage, media: Media): Promise<Response> {
+  try {
+    const pictures = (await stateOf(client, media)).flatMap((state) => picture(storage, media, state) ?? []);
+    return json({ pictures });
+  } catch (err) {
+    if (err instanceof DomainRefusal) return refuse(422, err.message);
+    throw err;
+  }
+}
+
+async function serve(storage: MediaStorage, key: string): Promise<Response> {
+  const bytes = KEY_PATTERN.test(key) ? await storage.read(key) : null;
+  if (!bytes) return refuse(404, "No such picture.");
+  return new Response(bytes as BodyInit, {
+    headers: {
+      "Content-Type": TYPE_OF[key.slice(key.lastIndexOf(".") + 1)],
+      "Content-Length": String(bytes.length),
+      "X-Content-Type-Options": "nosniff",
+      "Content-Security-Policy": "default-src 'none'; sandbox",
+      "Cache-Control": "private, max-age=300",
+    },
+  });
+}
+
+/** The handler of everything under `<base>/media`, given the path segments after `media`. */
+export function mediaHandler(storage: MediaStorage = diskStorage()) {
+  const media = SCHEMA.media as Media;
+  return (client: HostClient, request: Request, rest: string[]): Promise<Response> | Response => {
+    if (rest.length === 0 && request.method === "POST") return upload(client, storage, request, media);
+    if (rest.length === 0 && request.method === "GET") return listing(client, storage, media);
+    if (rest.length === 1 && request.method === "GET") return serve(storage, rest[0]);
+    return refuse(404, "No such page.");
+  };
+}

data/lib/hecks/projections/site/cms_editor/templates/src/media/multipart.ts.tmpl

@@ -0,0 +1,53 @@
+__BANNER__
+
+// A `multipart/form-data` body read into its parts. The body has already been read within the size
+// cap by the time it gets here, so this only splits it: no part is written anywhere, and a part's
+// filename is returned for information and never used as a path.
+
+export interface Part {
+  name: string;
+  filename: string | null;
+  data: Uint8Array;
+}
+
+/** The most parts a body may have; an upload form has a handful. */
+const MAX_PARTS = 8;
+
+/** The boundary a `Content-Type` header names, or null when it is not a multipart type with one. */
+export function boundaryOf(contentType: string | null): string | null {
+  if (!contentType || !/^multipart\/form-data\s*;/i.test(contentType)) return null;
+  const found = /boundary=(?:"([^"]{1,70})"|([^;\s]{1,70}))/i.exec(contentType);
+  return found ? (found[1] ?? found[2]) : null;
+}
+
+function header(head: string, key: string): string | null {
+  const found = new RegExp(`${key}="([^"]*)"`, "i").exec(head);
+  return found ? found[1] : null;
+}
+
+function partOf(chunk: Buffer): Part | null {
+  const split = chunk.indexOf("\r\n\r\n");
+  if (split < 0) return null;
+  const head = chunk.subarray(0, split).toString("latin1");
+  const name = header(head, "name");
+  if (name === null) return null;
+  return { name, filename: header(head, "filename"), data: chunk.subarray(split + 4) };
+}
+
+/** The parts of `body`, split on `boundary`; a body that is not well formed gives an empty list. */
+export function parts(body: Uint8Array, boundary: string): Part[] {
+  const buffer = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+  const delimiter = Buffer.from(`--${boundary}`);
+  const found: Part[] = [];
+  let at = buffer.indexOf(delimiter);
+  while (at >= 0 && found.length < MAX_PARTS) {
+    const start = at + delimiter.length;
+    if (buffer.subarray(start, start + 2).toString() === "--") break;
+    const next = buffer.indexOf(delimiter, start);
+    if (next < 0) return [];
+    const part = partOf(buffer.subarray(start + 2, Math.max(start + 2, next - 2)));
+    if (part) found.push(part);
+    at = next;
+  }
+  return found;
+}

data/lib/hecks/projections/site/cms_editor/templates/src/media/sniff.ts.tmpl

@@ -0,0 +1,94 @@
+__BANNER__
+
+// What a picture's bytes are. The type an upload claims is never trusted: the first bytes decide,
+// against an allow-list of raster formats (JPEG, PNG, WebP, GIF, AVIF). SVG, which can carry script,
+// and anything else is refused. The same bytes give the picture's size when the format makes it cheap
+// to read, and the storage key is the bytes' own digest with the format's extension, so a key is never
+// built from anything the client sent.
+
+/** The extension each allowed type is stored under. */
+export const EXTENSION_OF: Readonly<Record<string, string>> = {
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/avif": "avif",
+};
+
+/** The type a stored key's extension says it is. */
+export const TYPE_OF: Readonly<Record<string, string>> = Object.fromEntries(Object.entries(EXTENSION_OF).map(([type, ext]) => [ext, type]));
+
+/** A key the editor generated: a SHA-256 digest in hex, a dot, and an allowed extension. */
+export const KEY_PATTERN = /^[0-9a-f]{64}\.(jpg|png|webp|gif|avif)$/;
+
+const ascii = (bytes: Uint8Array, from: number, to: number): string => String.fromCharCode(...bytes.subarray(from, to));
+const be16 = (b: Uint8Array, at: number): number => (b[at] << 8) | b[at + 1];
+const be32 = (b: Uint8Array, at: number): number => ((b[at] << 24) | (b[at + 1] << 16) | (b[at + 2] << 8) | b[at + 3]) >>> 0;
+const le16 = (b: Uint8Array, at: number): number => b[at] | (b[at + 1] << 8);
+const le24 = (b: Uint8Array, at: number): number => b[at] | (b[at + 1] << 8) | (b[at + 2] << 16);
+
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/** AVIF is an ISO file whose first box names an avif brand, as its major brand or a compatible one. */
+function isAvif(bytes: Uint8Array): boolean {
+  if (bytes.length < 16 || ascii(bytes, 4, 8) !== "ftyp") return false;
+  const end = Math.min(be32(bytes, 0), 64, bytes.length);
+  for (let at = 8; at + 4 <= end; at += 4) {
+    const brand = ascii(bytes, at, at + 4);
+    if (brand === "avif" || brand === "avis") return true;
+  }
+  return false;
+}
+
+/** The allowed type the bytes are, or null when they are none of them. */
+export function sniff(bytes: Uint8Array): string | null {
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes.length >= 8 && PNG.every((value, at) => bytes[at] === value)) return "image/png";
+  if (bytes.length >= 6 && ["GIF87a", "GIF89a"].includes(ascii(bytes, 0, 6))) return "image/gif";
+  if (bytes.length >= 12 && ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 12) === "WEBP") return "image/webp";
+  return isAvif(bytes) ? "image/avif" : null;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+function jpegSize(bytes: Uint8Array): Size | null {
+  let at = 2;
+  while (at + 9 < bytes.length) {
+    if (bytes[at] !== 0xff) return null;
+    const marker = bytes[at + 1];
+    if (marker === 0xff) {
+      at += 1;
+    } else if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+      return { height: be16(bytes, at + 5), width: be16(bytes, at + 7) };
+    } else if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      at += 2;
+    } else {
+      at += 2 + be16(bytes, at + 2);
+    }
+  }
+  return null;
+}
+
+function webpSize(bytes: Uint8Array): Size | null {
+  const chunk = ascii(bytes, 12, 16);
+  if (chunk === "VP8X" && bytes.length >= 30) return { width: le24(bytes, 24) + 1, height: le24(bytes, 27) + 1 };
+  if (chunk === "VP8 " && bytes.length >= 30) return { width: le16(bytes, 26) & 0x3fff, height: le16(bytes, 28) & 0x3fff };
+  if (chunk === "VP8L" && bytes.length >= 25) {
+    const bits = (bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24)) >>> 0;
+    return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+  }
+  return null;
+}
+
+/** The picture's size in pixels when the format makes it cheap to read (not AVIF), else null. */
+export function sizeOf(bytes: Uint8Array, type: string): Size | null {
+  let size: Size | null = null;
+  if (type === "image/png" && bytes.length >= 24) size = { width: be32(bytes, 16), height: be32(bytes, 20) };
+  else if (type === "image/gif" && bytes.length >= 10) size = { width: le16(bytes, 6), height: le16(bytes, 8) };
+  else if (type === "image/jpeg") size = jpegSize(bytes);
+  else if (type === "image/webp") size = webpSize(bytes);
+  return size && size.width > 0 && size.height > 0 ? size : null;
+}

data/lib/hecks/projections/site/cms_editor/templates/src/media/storage.ts.tmpl

@@ -0,0 +1,50 @@
+__BANNER__
+
+// Where a picture's bytes are kept. The domain holds a picture's record (key, alt text, type, size)
+// and never its bytes; the bytes go through this port. `diskStorage` writes them under the directory
+// the Editor row names (`media_dir`). A project that keeps pictures in an object store implements the
+// same interface (`put` a key's bytes, `read` them back, and `url` where a browser can show one) and
+// passes it to `createApp({ storage })`; nothing else in the editor changes.
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { EDITOR } from "../config.ts";
+import { KEY_PATTERN } from "./sniff.ts";
+
+export interface MediaStorage {
+  /** Keeps `bytes` under `key`; keeping the same key again keeps the same bytes. */
+  put(key: string, bytes: Uint8Array, mime: string): Promise<void>;
+  /** The address a signed-in editor's browser shows the picture from. */
+  url(key: string): string;
+  /** The bytes kept under `key`, or null when there are none. */
+  read(key: string): Promise<Uint8Array | null>;
+}
+
+/** The directory's file for `key`; a key that is not one this editor generates is refused. */
+function fileFor(directory: string, key: string): string {
+  if (!KEY_PATTERN.test(key)) throw new RangeError("not a picture key");
+  return join(directory, key);
+}
+
+/** Pictures on the local disk, under `directory` (resolved from the working directory). */
+export function diskStorage(directory: string = EDITOR.mediaDir): MediaStorage {
+  const root = resolve(directory);
+  return {
+    async put(key, bytes) {
+      const file = fileFor(root, key);
+      await mkdir(root, { recursive: true });
+      const partial = `${file}.${process.pid}.part`;
+      await writeFile(partial, bytes);
+      await rename(partial, file);
+    },
+    url: (key) => `${EDITOR.basePath}/media/${key}`,
+    async read(key) {
+      try {
+        return await readFile(fileFor(root, key));
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT" || err instanceof RangeError) return null;
+        throw err;
+      }
+    },
+  };
+}

data/lib/hecks/projections/site/cms_editor/templates/src/schema.ts.tmpl

@@ -0,0 +1,85 @@
+__BANNER__
+
+// The domain's shape, read from its bluebook: every aggregate with its attributes, value objects,
+// lifecycle, commands and queries. The pages, the forms and the input parser all read this one
+// constant, so the editor can edit any aggregate; none of it is written by hand.
+
+/** How an attribute's value is entered: `object` is a value object, the rest are single values. */
+export type Kind = "text" | "integer" | "number" | "boolean" | "object" | "reference";
+
+export interface Attr {
+  name: string;
+  /** The type as the bluebook spells it ("String", "Byline"). */
+  type: string;
+  kind: Kind;
+  optional: boolean;
+  /** True for `list_of`: the attribute holds a list of `type`. */
+  list: boolean;
+  /** `body` for an attribute whose value object has the shape of a structured document (blocks of spans). */
+  widget?: "body";
+  /** The aggregate a `reference` points at. */
+  target?: string;
+}
+
+export interface Transition {
+  verb: string;
+  from: string[];
+  to: string;
+}
+
+export interface Lifecycle {
+  field: string;
+  default: string;
+  transitions: Transition[];
+}
+
+export interface Command {
+  name: string;
+  goal: string | null;
+  role: string | null;
+  /** True when the command makes a new instance; false when it acts on one (`reference_to`). */
+  creates: boolean;
+  /** The aggregate the command acts on, when it is not a creating command. */
+  on: string | null;
+  attributes: Attr[];
+}
+
+export interface Query {
+  name: string;
+  description: string | null;
+  attributes: Attr[];
+}
+
+export interface Aggregate {
+  name: string;
+  description: string | null;
+  identity: string;
+  lifecycle: Lifecycle | null;
+  attributes: Attr[];
+  valueObjects: Record<string, Attr[]>;
+  commands: Command[];
+  queries: Query[];
+}
+
+/** How one part of a picture's record is sent: `wrap` is the part of a value object that holds the value. */
+export interface MediaField {
+  name: string;
+  wrap: string | null;
+}
+
+/** The aggregate that registers pictures, when the chapter has one: found by shape, never by name. */
+export interface Media {
+  aggregate: string;
+  command: string;
+  fields: { key: MediaField; alt: MediaField; mime: MediaField; width?: MediaField; height?: MediaField };
+  /** The query that lists the pictures, or null when every instance is read. */
+  listing: string | null;
+}
+
+export interface Schema {
+  domain: string;
+  aggregates: Aggregate[];
+  media?: Media;
+}
+
+export const SCHEMA: Schema = __SCHEMA__;