hecks 3.9.1 → 3.11.0

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

@@ -0,0 +1,133 @@
+__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, never by what was sent: a command may set fields from
+// arguments that are not fields (a clearing argument), so the arguments are no evidence. The command
+// took effect when the instance's state changed, and for a lifecycle move when it reached the state
+// the move names. When the state did not change at all (a repeated command, a move to the state it
+// is already in) the answer's last refusal decides, and only if it names this verb.
+import type { Answer, HostClient } from "@hecks/client";
+import { DomainUnavailable } from "@hecks/client";
+
+import { qualified } from "./names.ts";
+import type { Aggregate, Command } from "./schema.ts";
+import { problemsOf } from "./ui/block_list.js";
+import type { Problem } from "./ui/blocks.ts";
+
+export type State = Record<string, unknown>;
+export type Outcome = { ok: true; id: string } | { ok: false; message: string; field?: string; problems?: Problem[] };
+
+/** 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, qualified(agg)).find(([key]) => key === id)?.[1];
+}
+
+/**
+ * A client that asks the host to read once and remembers the answer, for a request that only reads:
+ * the page and the navigation's counts then come from one read of the host.
+ */
+export function reading(client: HostClient): HostClient {
+  let held: Promise<Answer> | undefined;
+  return new Proxy(client, {
+    get(target, key) {
+      if (key === "read") return () => (held ??= target.read());
+      const member = Reflect.get(target, key, target);
+      return typeof member === "function" ? member.bind(target) : member;
+    },
+  });
+}
+
+/**
+ * A value as it is compared: the keys of an object in order and each null left out, since one answer
+ * of a host may echo a slot that was never set as null where another leaves it out, in an order of its own.
+ */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value === null || typeof value !== "object") return value;
+  const held = Object.entries(value as object).filter(([, part]) => part !== null);
+  return Object.fromEntries(held.sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, part]) => [key, canonical(part)]));
+}
+
+const sameState = (a: State | undefined, b: State | undefined): boolean => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+
+/** Whether the host's refusal names this aggregate's verb: by its chapter too when the editor spans several. */
+function refusedLast(answer: Answer, agg: Aggregate, command: Command): boolean {
+  const last = (answer.refusals ?? []).at(-1);
+  if (last === undefined) return false;
+  const verb = String(last.verb ?? "");
+  return verb.replace(/^.*::/, "") === `${agg.name}.${command.name}` && (!agg.chapter || !verb.includes("::") || verb.startsWith(`${agg.chapter}::`));
+}
+
+/** Whether `after` shows the command took effect, given the instance as it was `before`. */
+export function applied(agg: Aggregate, command: Command, 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);
+  return move && agg.lifecycle ? after[agg.lifecycle.field] === move.to : true;
+}
+
+const label = (name: string): string => name.replace(/_/g, " ");
+
+/** The command's attribute a value object's name stands for, to name the offending field. */
+function fieldOf(command: Command, type: string): string {
+  const held = command.attributes.find((attr) => attr.type === type);
+  return held ? label(held.name) : type;
+}
+
+/**
+ * The words for a refusal. The host words a given as `<Command> refused — <condition>`, which reads
+ * as though the condition were the reason, so it is shown as the condition that was not met; an
+ * invariant is shown as the field and the rule, without the value that offended (raw JSON).
+ */
+export function refusalText(refusal: { kind?: string; error?: string } | undefined, command: Command): string {
+  const error = refusal?.error ?? "";
+  const refused = /^.+? refused — (.+)$/s.exec(error);
+  if (refusal?.kind === "GivenNotMet" && refused) return `Not allowed unless ${refused[1]}.`;
+  if (refusal?.kind === "EnsuresNotMet" && refused) return `Not allowed: the result would break this rule: ${refused[1]}.`;
+  const invariant = /^(.+?) invariant violated — (.+?)(?: \(given .*\))?$/s.exec(error);
+  if (invariant) return `${fieldOf(command, invariant[1])}: ${invariant[2]}.`;
+  if (refusal?.kind === "InvariantViolation" && refused) return `${refused[1]}.`;
+  return error || `The domain did not apply ${command.name}.`;
+}
+
+/** The name of the command's attribute a refused invariant is about, so its input can be marked; undefined when none. */
+export function refusedField(refusal: { kind?: string; error?: string } | undefined, command: Command): string | undefined {
+  const invariant = /^(.+?) invariant violated — /s.exec(refusal?.error ?? "");
+  return invariant ? command.attributes.find((attr) => attr.type === invariant[1])?.name : undefined;
+}
+
+/** 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 {
+  return refusalText((answer.refusals ?? []).at(-1), command);
+}
+
+/**
+ * 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(`${qualified(agg)}.${command.name}`, args, to, command.role ?? undefined);
+    const after = id ? instanceIn(client, answer, agg, id) : undefined;
+    if (id && applied(agg, command, before, after, answer)) return { ok: true, id };
+    const last = (answer.refusals ?? []).at(-1);
+    const problems: Problem[] = problemsOf(last?.error, command.attributes, args, agg.valueObjects);
+    const field = refusedField(last, command);
+    return { ok: false, message: refusalMessage(answer, command), field, problems };
+  } 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,29 @@
+__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__,
+  brand: __BRAND__,
+  logo: __LOGO__,
+  basePath: __BASE_PATH__,
+  ssoPath: __SSO_PATH__,
+  login: __LOGIN__,
+  sessionCookie: __SESSION_COOKIE__,
+  sessionMaxAge: 28800,
+  flashMaxAge: 60,
+  hostCookie: __HOST_COOKIE__,
+  hostEnv: __HOST_ENV__,
+  hostDefault: __HOST_DEFAULT__,
+  roles: __ROLES__,
+  mediaDir: __MEDIA_DIR__,
+  mediaMaxBytes: __MEDIA_MAX_BYTES__,
+  pageSize: __PAGE_SIZE__,
+  /** Where a record is shown on the site, with `{key}`, `{kind}`, `{slug}` and `{id}`; null for no preview. */
+  preview: __PREVIEW__ as string | null,
+  accountPath: "/accounts/me",
+  membersPath: "/members",
+  rememberMs: 60000,
+  timeoutMs: 5000,
+} as const;

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

@@ -0,0 +1,52 @@
+__BANNER__
+
+// A notice that survives one redirect: "Published." after a command succeeds and the person is sent
+// to the page that shows the result. It is carried in a short-lived cookie that is signed (so a
+// visitor cannot make the editor say something), holds only a kind and a sentence, and is read
+// once: the page that shows it clears it in the same response. There is no server-side state.
+// The sentence is escaped wherever it is shown; it is encoded as base64url so no character of it can
+// break out of the cookie.
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { EDITOR } from "./config.ts";
+
+export type FlashKind = "success" | "error" | "info";
+
+export interface Flash {
+  kind: FlashKind;
+  message: string;
+}
+
+const SUFFIX = ":editor-flash";
+const NAME = `${EDITOR.sessionCookie}_flash`;
+const ATTRIBUTES = `Path=${EDITOR.basePath}; HttpOnly; SameSite=Lax`;
+const KINDS: readonly string[] = ["success", "error", "info"];
+
+const sign = (secret: string, payload: string): string => createHmac("sha256", secret + SUFFIX).update(payload).digest("base64url");
+
+/** The `Set-Cookie` value that carries `flash` to the next page. */
+export function flashCookie(flash: Flash, secret: string, now: () => number = Date.now): string {
+  const payload = Buffer.from(JSON.stringify({ k: flash.kind, m: flash.message.slice(0, 300), t: Math.floor(now() / 1000) })).toString("base64url");
+  const secure = process.env.NODE_ENV === "production" ? "; Secure" : "";
+  return `${NAME}=${payload}.${sign(secret, payload)}; ${ATTRIBUTES}; Max-Age=${EDITOR.flashMaxAge}${secure}`;
+}
+
+/** The `Set-Cookie` value that spends the notice. */
+export const spentFlash = (): string => `${NAME}=; ${ATTRIBUTES}; Max-Age=0`;
+
+/** The notice a `Cookie` header carries, or null when it has none, it was forged or it has expired. */
+export function readFlash(header: string | null, secret: string, now: () => number = Date.now): Flash | null {
+  const raw = header?.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${NAME}=`))?.slice(NAME.length + 1);
+  const [payload, signature] = raw?.split(".") ?? [];
+  if (!payload || !signature || !secret) return null;
+  const expected = Buffer.from(sign(secret, payload));
+  const given = Buffer.from(signature);
+  if (expected.length !== given.length || !timingSafeEqual(expected, given)) return null;
+  try {
+    const found = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    const fresh = typeof found.t === "number" && now() / 1000 - found.t <= EDITOR.flashMaxAge && now() / 1000 >= found.t - 5;
+    return fresh && KINDS.includes(found.k) && typeof found.m === "string" ? { kind: found.k, message: found.m } : null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,43 @@
+__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 { DomainRefusal, HostClient, rowsOf } from "@hecks/client";
+import type { Answer } 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 domain to address, when it is not the chapter the editor edits (pictures kept in another chapter). */
+  domain?: string;
+}
+
+/** 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: options.domain ?? SCHEMA.domain, url: hostUrl(options), fetch: options.fetch, timeoutMs: EDITOR.timeoutMs });
+}
+
+/**
+ * The rows a query answered. A host that has no such query for its running domain (a declared
+ * query the Rust host does not generate) answers with no entry at all, which `rowsOf` reads as
+ * null; that is a refusal here, not an empty list, or a list page, a picker or the picture
+ * listing would show nothing while the records are there.
+ *
+ * @throws {DomainRefusal} when the host refused the question or did not answer it
+ */
+export function rowsAnswered(answer: Answer, name: string): Record<string, unknown>[] {
+  const rows = rowsOf(answer, name);
+  if (rows === null) throw new DomainRefusal("QueryNotAnswered", `The host did not answer ${name}.`);
+  return rows as Record<string, unknown>[];
+}

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

@@ -0,0 +1,177 @@
+__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 } 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 { hostClient, rowsAnswered } from "../host.ts";
+import type { HostOptions } from "../host.ts";
+import { mayEdit, qualified } from "../names.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 {
+  const own = (candidate: Aggregate): boolean => candidate.name === media.aggregate && (candidate.chapter ?? SCHEMA.domain) === (media.domain ?? SCHEMA.domain);
+  return media.definition ?? (SCHEMA.aggregates.find(own) as Aggregate);
+}
+
+/** Whether a person in `role` may use the pictures: not when the chapter that holds them limits its roles to others. */
+export function mediaOpen(role: string | null): boolean {
+  const media = SCHEMA.media as Media;
+  return mayEdit(aggregateOf(media), role);
+}
+
+/** 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);
+  const everything = async () => client.instancesOf(await client.read(), qualified(agg)).map(([, state]) => state);
+  if (!media.listing) return everything();
+  const name = `${qualified(agg)}.${media.listing}`;
+  try {
+    return rowsAnswered(await client.query(name, {}), name) as State[];
+  } catch (err) {
+    // The listing only narrows what is offered; a host that does not answer it still holds the pictures.
+    if (err instanceof DomainRefusal) return everything();
+    throw err;
+  }
+}
+
+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`. When the
+ * pictures are kept in another chapter (`media.domain`), they are read and registered through a
+ * client for that chapter, not the editor's own.
+ */
+export function mediaHandler(storage: MediaStorage = diskStorage(), options: HostOptions = {}) {
+  const media = SCHEMA.media as Media;
+  const elsewhere = media.domain ? hostClient({ ...options, domain: media.domain }) : null;
+  return (editors: HostClient, request: Request, rest: string[]): Promise<Response> | Response => {
+    const client = elsewhere ?? editors;
+    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;
+      }
+    },
+  };
+}