@micacms/runtime 0.5.0-rc.2 → 0.6.0-rc.1

package/src/middleware/index.ts

@@ -0,0 +1,234 @@
+/**
+ * Middleware.
+ *
+ * Ordering matters and is asserted in `app.ts`:
+ *   requestContext → guards → securityHeaders → errorBoundary → rateLimit
+ *   → originGuard → the auth surface's gate → route
+ *
+ * The gate itself is not here. Whether a request is anybody — a session
+ * middleware, `allowAll()` — belongs to the composing app, which is what
+ * keeps this package authentication-neutral.
+ */
+
+import { ContentPathError } from "@micacms/core";
+import type { ErrorHandler, MiddlewareHandler } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+import { ApiError, badRequest } from "../lib/errors.js";
+import { clientIp, type Env } from "../http.js";
+import { randomToken } from "../lib/id.js";
+
+/** Attaches the container, a request id and a scoped logger; logs the result. */
+export function requestContext(ctx: Env["Variables"]["ctx"]): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    // A client's id is logged and echoed, so only a short, plain one is kept (#150).
+    const offered = c.req.header("x-request-id");
+    const requestId = offered && /^[A-Za-z0-9_-]{1,64}$/.test(offered) ? offered : randomToken(8);
+    const logger = ctx.logger.child({ requestId });
+
+    c.set("ctx", ctx);
+    c.set("requestId", requestId);
+    c.set("logger", logger);
+    c.header("x-request-id", requestId);
+
+    const startedAt = performance.now();
+    await next();
+    const duration = Math.round(performance.now() - startedAt);
+
+    const line = {
+      method: c.req.method,
+      path: new URL(c.req.url).pathname,
+      status: c.res.status,
+      duration,
+    };
+
+    /**
+     * "Am I signed in?" — "No."
+     *
+     * `/auth/me` is the SPA's first request on every page load, and a 401 is
+     * one of its two correct answers, not a rejection worth a warning. Logging
+     * it as one puts a scary line in the terminal of everybody who has simply
+     * opened the editor while signed out.
+     */
+    const expected401 = c.res.status === 401 && line.path === "/api/auth/me";
+
+    if (c.res.status >= 500) logger.error("Request failed", line);
+    else if (c.res.status >= 400 && !expected401) logger.warn("Request rejected", line);
+    else logger.debug("Request", line);
+  };
+}
+
+/**
+ * Same-origin only. `blob:` and `data:` images cover previews; a route that
+ * needs a stricter policy, such as the sandbox on media files, sets its own.
+ */
+export const CONTENT_SECURITY_POLICY = [
+  "default-src 'self'",
+  "img-src 'self' blob: data:",
+  "object-src 'none'",
+  "base-uri 'none'",
+  "frame-ancestors 'none'",
+].join("; ");
+
+export function securityHeaders(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    await next();
+
+    if (!c.res.headers.has("content-security-policy")) {
+      c.header("content-security-policy", CONTENT_SECURITY_POLICY);
+    }
+    // Only for an https public URL: HSTS over plain HTTP is ignored, and on
+    // localhost it would pin a developer's other projects to https.
+    if (c.get("ctx").config.MICA_PUBLIC_URL.startsWith("https://")) {
+      c.header("strict-transport-security", "max-age=31536000");
+    }
+
+    c.header("x-content-type-options", "nosniff");
+    c.header("referrer-policy", "same-origin");
+    c.header("x-frame-options", "DENY");
+    // The admin is a first-party SPA; nothing here needs to be embedded.
+    c.header("permissions-policy", "geolocation=(), microphone=(), camera=()");
+  };
+}
+
+/** Files in one upload request; the Media view sends a selection in one request. */
+export const MAX_FILES_PER_UPLOAD = 10;
+
+/** Far more than any entry's JSON, and small enough to refuse a flood early. */
+export const MAX_JSON_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Refuses an oversized body before a handler reads it into memory (#148). An
+ * upload may carry `MAX_FILES_PER_UPLOAD` files of `MICA_MAX_UPLOAD_BYTES`, plus
+ * room for the multipart framing; every other request gets `MAX_JSON_BYTES`.
+ */
+export function requestSizeLimit(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    const { config } = c.get("ctx");
+    const upload = c.req.method === "POST" && c.req.path === "/api/admin/media";
+    const maxSize = upload
+      ? config.MICA_MAX_UPLOAD_BYTES * MAX_FILES_PER_UPLOAD + 1024 * 1024
+      : MAX_JSON_BYTES;
+
+    return bodyLimit({
+      maxSize,
+      onError: (ctx) => {
+        const refused = new ApiError(
+          "payload_too_large",
+          upload
+            ? "The upload is too large. Upload fewer or smaller files at a time."
+            : "The request is too large.",
+        );
+        return ctx.json(refused.toBody(), 413);
+      },
+    })(c, next);
+  };
+}
+
+/**
+ * Converts thrown errors into the API error envelope. Deliberate failures
+ * (`ApiError`) are reported as-is; anything else is a bug and becomes a bare
+ * 500, with the stack kept in the log rather than sent to the client.
+ *
+ * Registered with `app.onError`, not as middleware: Hono's `compose` wraps each
+ * handler individually and routes a throw to `onError` at that level, so a
+ * try/catch in an outer middleware would never see it.
+ */
+export function errorHandler(): ErrorHandler<Env> {
+  return (error, c) => {
+    const logger = c.get("logger") ?? c.get("ctx").logger;
+
+    if (error instanceof ApiError) {
+      logger.debug("Handled error", { code: error.code, message: error.message });
+      return c.json(error.toBody(), error.status as ContentfulStatusCode, error.headers);
+    }
+
+    // A path that could leave the content root is the client's mistake, not a bug.
+    if (error instanceof ContentPathError) {
+      logger.warn("Refused content path", { message: error.message });
+      const refused = badRequest(error.message);
+      return c.json(refused.toBody(), refused.status as ContentfulStatusCode);
+    }
+
+    logger.error("Unhandled error", {
+      error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+      path: new URL(c.req.url).pathname,
+    });
+
+    return c.json(
+      {
+        error: {
+          code: "internal_error" as const,
+          message: "Something went wrong. Please try again.",
+          requestId: c.get("requestId"),
+        },
+      },
+      500,
+    );
+  };
+}
+
+/** Coarse per-IP limit, applied to the whole API surface. */
+export function rateLimit(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    const { limiters } = c.get("ctx");
+    const result = limiters.api.check(clientIp(c));
+
+    if (!result.allowed) {
+      throw new ApiError("rate_limited", "Too many requests. Please slow down.", {
+        headers: { "retry-after": String(result.retryAfter) },
+      });
+    }
+
+    await next();
+  };
+}
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+const normaliseOrigin = (value: string): string => {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return value;
+  }
+};
+
+export function allowedOrigins(config: {
+  MICA_PUBLIC_URL: string;
+  adminOrigins: string[];
+}): string[] {
+  return [...new Set([config.MICA_PUBLIC_URL, ...config.adminOrigins].map(normaliseOrigin))];
+}
+
+/**
+ * First CSRF layer: the browser sets `Origin` on every state-changing request
+ * and a page on another site cannot forge it.
+ *
+ * Applied to the whole API — including sign-in, which has no session yet and
+ * so cannot use the token check below.
+ */
+export function originGuard(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    if (SAFE_METHODS.has(c.req.method)) {
+      await next();
+      return;
+    }
+
+    const { config } = c.get("ctx");
+    const origin = c.req.header("origin");
+
+    if (origin) {
+      if (!allowedOrigins(config).includes(normaliseOrigin(origin))) {
+        throw new ApiError("forbidden", "Request origin is not allowed.");
+      }
+    } else if (config.isProduction) {
+      // A browser always sends Origin on writes; its absence means the request
+      // did not come from one. Tolerated in development for curl-based testing.
+      throw new ApiError("forbidden", "Missing Origin header.");
+    }
+
+    await next();
+  };
+}

package/src/routes/admin-content.ts

@@ -0,0 +1,197 @@
+/**
+ * Admin routes for entries and singletons. The content store holds every rule;
+ * these routes only parse and serialize. The API path is the repository path,
+ * Git is the history, and `revision` makes concurrent edits safe.
+ */
+
+import { ReadOnlyError, ValidationError } from "../services/content-store.js";
+import { ConflictError } from "../workspace/files.js";
+import { collectionEntryPath, compareEntries, entryTitle, LayoutError, singletonPath } from "@micacms/core";
+import { Hono } from "hono";
+import { z } from "zod";
+
+import { ApiError, badRequest, notFound } from "../lib/errors.js";
+import type { Env } from "../http.js";
+
+const saveSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+  slug: z.string().max(120).optional(),
+  /**
+   * The revision the editor opened. `null` asserts that the entry does not
+   * exist, so two parallel creates cannot overwrite.
+   */
+  revision: z.string().nullable().optional(),
+});
+
+const reorderSchema = z.object({ slugs: z.array(z.string().min(1)).max(2000) });
+
+async function jsonBody(c: { req: { json(): Promise<unknown> } }): Promise<unknown> {
+  return c.req.json().catch(() => {
+    throw badRequest("The request body must be valid JSON.");
+  });
+}
+
+/** Maps a conflict to 409 and a validation failure to 422; other errors go to the error handler. */
+async function handled<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof ConflictError || error instanceof ReadOnlyError || error instanceof LayoutError) {
+      throw new ApiError("conflict", error.message);
+    }
+    if (error instanceof ValidationError) {
+      throw new ApiError("validation_failed", error.message, { issues: error.issues });
+    }
+    throw error;
+  }
+}
+
+export function adminContentRoutes(): Hono<Env> {
+  const app = new Hono<Env>();
+
+  app.get("/collections/:collection/entries", async (c) => {
+    const { content } = c.get("ctx").services;
+    const collection = c.req.param("collection");
+    const def = content.requireCollection(collection);
+
+    const entries = await handled(() => content.list(collection));
+    const search = c.req.query("search")?.trim().toLowerCase();
+
+    const items = entries
+      .map((entry) => ({
+        slug: entry.slug,
+        position: entry.position,
+        title: entryTitle(def, entry.data),
+        data: entry.data,
+      }))
+      // Content trees are small, so an in-memory substring match is sufficient.
+      .filter((item) => !search || JSON.stringify(item.data).toLowerCase().includes(search))
+      .sort(compareEntries(def));
+
+    return c.json({ items, total: items.length });
+  });
+
+  app.post("/collections/:collection/entries", async (c) => {
+    const { content } = c.get("ctx").services;
+    const parsed = saveSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("The entry payload is malformed.");
+
+    const saved = await handled(() =>
+      content.save(c.req.param("collection"), {
+        data: parsed.data.data,
+        expectedRevision: parsed.data.revision ?? null,
+      }),
+    );
+
+    return c.json(saved, 201);
+  });
+
+  app.post("/collections/:collection/reorder", async (c) => {
+    const { content } = c.get("ctx").services;
+    const parsed = reorderSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("Expected a list of entry slugs.");
+
+    await handled(() => content.reorder(c.req.param("collection"), parsed.data.slugs));
+    return c.json({ ok: true });
+  });
+
+  /** Server-side slug generation, so the URL preview matches what is saved. */
+  app.get("/collections/:collection/slug", async (c) => {
+    const { content } = c.get("ctx").services;
+    const source = c.req.query("source") ?? "";
+    if (!source.trim()) return c.json({ slug: "" });
+
+    return c.json({
+      slug: await handled(() =>
+        content.suggestSlug(c.req.param("collection"), source, c.req.query("except")),
+      ),
+    });
+  });
+
+  app.get("/collections/:collection/entries/:slug", async (c) => {
+    const { content } = c.get("ctx").services;
+    const collection = c.req.param("collection");
+    const slug = c.req.param("slug");
+
+    const entry = await handled(() => content.get(collection, slug));
+    if (!entry) throw notFound("This entry no longer exists.");
+
+    const def = content.requireCollection(collection);
+
+    return c.json({
+      collection,
+      slug: entry.slug,
+      position: entry.position,
+      title: entryTitle(def, entry.data),
+      data: entry.data,
+      // From the model, so the editor need not know when an entry is a directory.
+      path: collectionEntryPath(def.fields, collection, entry.slug),
+      revision: await content.revisionOf(collection, slug),
+    });
+  });
+
+  app.put("/collections/:collection/entries/:slug", async (c) => {
+    const { content } = c.get("ctx").services;
+    const parsed = saveSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("The entry payload is malformed.");
+
+    const saved = await handled(() =>
+      content.save(c.req.param("collection"), {
+        data: parsed.data.data,
+        slug: c.req.param("slug"),
+        expectedRevision: parsed.data.revision,
+      }),
+    );
+
+    return c.json(saved);
+  });
+
+  app.delete("/collections/:collection/entries/:slug", async (c) => {
+    const { content } = c.get("ctx").services;
+
+    await handled(() =>
+      content.remove(c.req.param("collection"), c.req.param("slug")),
+    );
+
+    return c.json({ ok: true });
+  });
+
+  /** Entries elsewhere that point at this one — shown before a delete. */
+  app.get("/collections/:collection/entries/:slug/references", async (c) => {
+    const { content } = c.get("ctx").services;
+    const references = await handled(() =>
+      content.findReferences(c.req.param("collection"), c.req.param("slug")),
+    );
+
+    return c.json({ references });
+  });
+
+  app.get("/singletons/:name", async (c) => {
+    const { content } = c.get("ctx").services;
+    const name = c.req.param("name");
+    const def = content.requireSingleton(name);
+
+    return c.json({
+      name,
+      label: def.label,
+      path: singletonPath(def.fields, name),
+      data: await handled(() => content.getSingleton(name)),
+      revision: await content.revisionOfSingleton(name),
+    });
+  });
+
+  app.put("/singletons/:name", async (c) => {
+    const { content } = c.get("ctx").services;
+    const body = (await jsonBody(c)) as { data?: unknown; revision?: string | null };
+
+    const saved = await handled(() =>
+      content.saveSingleton(c.req.param("name"), body?.data ?? {}, {
+        expectedRevision: body?.revision,
+      }),
+    );
+
+    return c.json(saved);
+  });
+
+  return app;
+}

package/src/routes/admin-media.ts

@@ -0,0 +1,96 @@
+/**
+ * Admin media routes. Media is files in the content repository, and there is no delete endpoint.
+ * An upload is written on its own, before the entry save, because the editor needs its path first.
+ */
+
+import { Hono } from "hono";
+
+import { ApiError, badRequest, notFound } from "../lib/errors.js";
+import { isImageType } from "../lib/file-type.js";
+import { MAX_FILES_PER_UPLOAD } from "../middleware/index.js";
+import type { Env } from "../http.js";
+
+export function adminMediaRoutes(): Hono<Env> {
+  const app = new Hono<Env>();
+
+  app.get("/", async (c) => {
+    const { media } = c.get("ctx").services;
+    return c.json({ items: await media.list() });
+  });
+
+  app.post("/", async (c) => {
+    const ctx = c.get("ctx");
+    const form = await c.req.formData().catch(() => {
+      throw badRequest("Expected a multipart upload.");
+    });
+
+    // The cast picks one of the two structurally different `File` types (Node's and undici's).
+    const files = form
+      .getAll("file")
+      .filter((value) => typeof value !== "string") as unknown as File[];
+
+    if (files.length === 0) throw badRequest("No file was uploaded.");
+    if (files.length > MAX_FILES_PER_UPLOAD) {
+      throw badRequest(`Upload at most ${MAX_FILES_PER_UPLOAD} files at a time.`);
+    }
+
+    const accept = form.get("accept");
+    // An entry's own `media/` directory or the shared one; the media service refuses anything else.
+    const directory = typeof form.get("directory") === "string" ? String(form.get("directory")) : undefined;
+    // The media service accepts `/gallery/x/media` too; take the owner from the path it will write to.
+    const owner = (directory ?? "").replace(/^[/\\]+/, "").split(/[/\\]/)[0] ?? "";
+    const readOnly = ctx.site.readOnly.get(`collections.${owner}`) ?? ctx.site.readOnly.get(`singletons.${owner}`);
+    if (readOnly) throw new ApiError("conflict", readOnly);
+
+    const prepared = await Promise.all(
+      files.map((file) =>
+        ctx.services.media.prepare({
+          file,
+          directory,
+          accept: accept === "image" || accept === "document" ? accept : "any",
+        }),
+      ),
+    );
+
+    await ctx.site.contentRepository.apply({
+      changes: prepared.map((item) => ({
+        type: "write" as const,
+        path: item.file.path,
+        contents: item.contents,
+      })),
+    });
+
+    return c.json({ items: prepared.map((item) => item.file) }, 201);
+  });
+
+  /**
+   * Serves a file to the editor, behind the admin gate. The site build reads
+   * the repository, not this route.
+   */
+  app.get("/file/*", async (c) => {
+    const { media } = c.get("ctx").services;
+    const mediaPath = c.req.path.replace(/^.*\/file\//, "");
+
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(mediaPath);
+    } catch {
+      throw badRequest("The file path is not valid.");
+    }
+
+    const found = await media.read(decoded);
+    if (!found) throw notFound("No such file.");
+
+    return c.body(found.bytes as unknown as ArrayBuffer, 200, {
+      // Text without a charset is decoded by guessing; the repository's text is UTF-8.
+      "content-type": found.mimeType.startsWith("text/") ? `${found.mimeType}; charset=utf-8` : found.mimeType,
+      "cache-control": "private, max-age=60",
+      // A file opened directly runs nothing and reaches nothing on this origin.
+      "content-security-policy": "sandbox; default-src 'none'",
+      // An image is shown as a preview; anything else is downloaded, never rendered here.
+      ...(isImageType(found.mimeType) ? {} : { "content-disposition": "attachment" }),
+    });
+  });
+
+  return app;
+}

package/src/routes/admin-spa.ts

@@ -0,0 +1,82 @@
+/**
+ * Serves the built administration SPA.
+ *
+ * Small enough to do directly rather than pull in a static-file middleware,
+ * and doing it here means the caching rules are explicit: hashed asset files
+ * are immutable, `index.html` never is — otherwise a deploy leaves editors on
+ * a stale bundle pointing at assets that no longer exist.
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+
+import { Hono, type Context } from "hono";
+
+import type { Env } from "../http.js";
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".map": "application/json; charset=utf-8",
+};
+
+export function adminAssetsExist(directory: string): boolean {
+  return fs.existsSync(path.join(directory, "index.html"));
+}
+
+export function adminSpaRoutes(directory: string): Hono<Env> {
+  const app = new Hono<Env>();
+  const root = path.resolve(directory);
+
+  const send = async (c: Context<Env>, filePath: string, immutable: boolean) => {
+    const stat = await fsp.stat(filePath);
+    const extension = path.extname(filePath).toLowerCase();
+
+    return c.body(Readable.toWeb(fs.createReadStream(filePath)) as ReadableStream<Uint8Array>, 200, {
+      "content-type": CONTENT_TYPES[extension] ?? "application/octet-stream",
+      "content-length": String(stat.size),
+      "cache-control": immutable
+        ? "public, max-age=31536000, immutable"
+        : "no-cache, must-revalidate",
+    });
+  };
+
+  app.get("/*", async (c) => {
+    const url = new URL(c.req.url);
+    const relative = decodeURIComponent(url.pathname.replace(/^\/admin\/?/, ""));
+    const target = path.join(root, relative);
+
+    // Never serve outside the build directory, whatever the path contains.
+    if (relative && !path.relative(root, target).startsWith("..")) {
+      try {
+        const stat = await fsp.stat(target);
+        if (stat.isFile()) {
+          // Vite emits hashed filenames under /assets, so those are immutable.
+          return await send(c, target, relative.startsWith("assets/"));
+        }
+      } catch {
+        // Fall through to the SPA entry point.
+      }
+    }
+
+    // Any other path belongs to the client-side router.
+    try {
+      return await send(c, path.join(root, "index.html"), false);
+    } catch {
+      return c.text("The admin interface has not been built. Run `rush build`.", 503);
+    }
+  });
+
+  return app;
+}