@micacms/runtime 0.5.0 → 0.6.0-rc.2

package/src/lib/logger.ts

@@ -0,0 +1,87 @@
+/**
+ * Structured logging.
+ *
+ * JSON lines in production so a log shipper can parse them; a compact
+ * human-readable form in development.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+const ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: 100,
+};
+
+export interface Logger {
+  debug(message: string, fields?: Record<string, unknown>): void;
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(message: string, fields?: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): Logger;
+}
+
+const COLORS: Record<Exclude<LogLevel, "silent">, string> = {
+  debug: "",
+  info: "",
+  warn: "",
+  error: "",
+};
+
+export function createLogger(options: {
+  level: LogLevel;
+  pretty: boolean;
+  bindings?: Record<string, unknown>;
+}): Logger {
+  const threshold = ORDER[options.level];
+  const bindings = options.bindings ?? {};
+
+  const write = (level: Exclude<LogLevel, "silent">, message: string, fields?: Record<string, unknown>) => {
+    if (ORDER[level] < threshold) return;
+
+    const payload = { ...bindings, ...fields };
+    const stream = level === "error" || level === "warn" ? process.stderr : process.stdout;
+
+    if (options.pretty) {
+      const extra = Object.keys(payload).length > 0 ? ` ${formatFields(payload)}` : "";
+      stream.write(`${COLORS[level]}${level.padEnd(5)} ${message}${extra}\n`);
+      return;
+    }
+
+    stream.write(
+      `${JSON.stringify({
+        time: new Date().toISOString(),
+        level,
+        message,
+        ...payload,
+      })}\n`,
+    );
+  };
+
+  return {
+    debug: (message, fields) => write("debug", message, fields),
+    info: (message, fields) => write("info", message, fields),
+    warn: (message, fields) => write("warn", message, fields),
+    error: (message, fields) => write("error", message, fields),
+    child: (extra) =>
+      createLogger({ ...options, bindings: { ...bindings, ...extra } }),
+  };
+}
+
+function formatFields(fields: Record<string, unknown>): string {
+  return Object.entries(fields)
+    .map(([key, value]) => `${key}=${format(value)}`)
+    .join(" ");
+}
+
+function format(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return value.stack ?? value.message;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/lib/ports.ts

@@ -0,0 +1,17 @@
+/**
+ * The port Mica listens on when nobody says otherwise.
+ *
+ * 6422 is `MICA` on a telephone keypad, which is the only reason anybody will
+ * remember it. What matters more is what it is not: 3000, 4000, 4173, 4200,
+ * 4321, 5000, 5173, 8000, 8080 and 1313 all belong to something a developer is
+ * likely to be running beside Mica — Astro's dev server most of all — and IANA
+ * has 6420 and 6421 assigned but not 6422, so nothing on the machine is
+ * expected to want it.
+ *
+ * A port collision is a bad first minute: the command fails, and the reason is
+ * somebody else's software. Picking an unfashionable number is the whole fix.
+ */
+export const DEFAULT_PORT = 6422;
+
+/** The address the CLI prints and the browser opens. */
+export const DEFAULT_BASE_URL = `http://localhost:${DEFAULT_PORT}`;

package/src/lib/rate-limit.ts

@@ -0,0 +1,72 @@
+/**
+ * Fixed-window rate limiting, in memory.
+ *
+ * The CMS is a single process by design, so an in-memory counter is
+ * sufficient and avoids a Redis dependency. The trade-off is deliberate:
+ * counters reset on restart. Mica checks no passwords; the identity provider
+ * does, with its own limits, so a restart-and-retry loop gains little.
+ */
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  /** Seconds until the window resets. */
+  retryAfter: number;
+}
+
+export interface RateLimiter {
+  check(key: string): RateLimitResult;
+  size(): number;
+  stop(): void;
+}
+
+export interface RateLimiterOptions {
+  limit: number;
+  windowMs: number;
+  /** How often expired buckets are swept. */
+  sweepMs?: number;
+}
+
+export function createRateLimiter(options: RateLimiterOptions): RateLimiter {
+  const buckets = new Map<string, { count: number; resetAt: number }>();
+
+  const sweep = setInterval(() => {
+    const now = Date.now();
+    for (const [key, bucket] of buckets) {
+      if (bucket.resetAt <= now) buckets.delete(key);
+    }
+  }, options.sweepMs ?? Math.max(options.windowMs, 60_000));
+
+  // A sweep timer must not keep the process alive on shutdown.
+  sweep.unref?.();
+
+  return {
+    check(key) {
+      const now = Date.now();
+      const bucket = buckets.get(key);
+
+      if (!bucket || bucket.resetAt <= now) {
+        buckets.set(key, { count: 1, resetAt: now + options.windowMs });
+        return { allowed: true, remaining: options.limit - 1, retryAfter: 0 };
+      }
+
+      bucket.count++;
+      const retryAfter = Math.ceil((bucket.resetAt - now) / 1000);
+
+      if (bucket.count > options.limit) {
+        return { allowed: false, remaining: 0, retryAfter };
+      }
+
+      return { allowed: true, remaining: options.limit - bucket.count, retryAfter };
+    },
+
+    size() {
+      return buckets.size;
+    },
+
+    stop() {
+      clearInterval(sweep);
+      buckets.clear();
+    },
+  };
+}

package/src/lib/schema-stats.ts

@@ -0,0 +1,183 @@
+/**
+ * Summarises a content model.
+ *
+ * The admin already receives the whole model and could count fields itself, but
+ * the interesting numbers are the recursive ones — objects and repeaters nest —
+ * and the relation graph, which is only visible after walking every branch.
+ * Doing it here keeps that walk in one place, next to the schema checks that
+ * use the same shapes.
+ *
+ * Pure: it reads a `Site` and nothing else, so it is the same answer for the
+ * same model whatever the state of the database.
+ */
+
+import {
+  listedFields,
+  resolveSlugField,
+  resolveTitleField,
+  type AnyField,
+  type FieldKind,
+  type FieldMap,
+  type Site,
+} from "@micacms/core";
+
+export interface KindUsage {
+  kind: FieldKind;
+  count: number;
+}
+
+export interface RelationEdge {
+  /** Collection or singleton the field is declared in. */
+  from: string;
+  fromType: "collection" | "singleton";
+  /** Dotted path to the field, with `[]` marking a repeater. */
+  path: string;
+  /** Collection the relation points at. */
+  to: string;
+  multiple: boolean;
+}
+
+export interface FieldCounts {
+  /** Fields declared directly on the collection or singleton. */
+  top: number;
+  /** Every field, including those nested in objects and repeaters. */
+  total: number;
+  required: number;
+}
+
+export interface CollectionStats {
+  name: string;
+  label: string;
+  fields: FieldCounts;
+  titleField: string | null;
+  slugField: string | null;
+  listed: number;
+  sortable: boolean;
+  /** Deepest level of nesting; 1 means no objects or repeaters. */
+  depth: number;
+}
+
+export interface SingletonStats {
+  name: string;
+  label: string;
+  fields: FieldCounts;
+  depth: number;
+}
+
+export interface SchemaStats {
+  collections: CollectionStats[];
+  singletons: SingletonStats[];
+  totals: FieldCounts & { collections: number; singletons: number };
+  /** Field kinds in use, most used first. */
+  kinds: KindUsage[];
+  relations: RelationEdge[];
+}
+
+/** The two kinds that carry a nested `fields` map. */
+function children(field: AnyField): FieldMap | null {
+  return field.kind === "object" || field.kind === "repeater" ? field.fields : null;
+}
+
+/**
+ * Depth-first walk over a field map, visiting nested fields too.
+ *
+ * `path` is what an editor would say out loud — `blocks[].heading` rather than
+ * `blocks.fields.heading` — so it can be printed as-is.
+ */
+function walk(
+  fields: FieldMap,
+  visit: (key: string, field: AnyField, path: string, depth: number) => void,
+  prefix = "",
+  depth = 1,
+): void {
+  for (const [key, field] of Object.entries(fields)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    visit(key, field, path, depth);
+
+    const nested = children(field);
+    if (nested) {
+      walk(nested, visit, field.kind === "repeater" ? `${path}[]` : path, depth + 1);
+    }
+  }
+}
+
+function countFields(fields: FieldMap): { counts: FieldCounts; depth: number } {
+  const counts: FieldCounts = { top: Object.keys(fields).length, total: 0, required: 0 };
+  let deepest = 1;
+
+  walk(fields, (_key, field, _path, depth) => {
+    counts.total++;
+    if (field.required) counts.required++;
+    if (depth > deepest) deepest = depth;
+  });
+
+  return { counts, depth: deepest };
+}
+
+export function schemaStats(site: Site): SchemaStats {
+  const kinds = new Map<FieldKind, number>();
+  const relations: RelationEdge[] = [];
+
+  const totals: FieldCounts & { collections: number; singletons: number } = {
+    collections: 0,
+    singletons: 0,
+    top: 0,
+    total: 0,
+    required: 0,
+  };
+
+  const tally = (fields: FieldMap, from: string, fromType: RelationEdge["fromType"]): void => {
+    walk(fields, (_key, field, path) => {
+      kinds.set(field.kind, (kinds.get(field.kind) ?? 0) + 1);
+
+      if (field.kind === "relation") {
+        relations.push({ from, fromType, path, to: field.collection, multiple: field.multiple ?? false });
+      }
+    });
+  };
+
+  const collections = Object.values(site.collections).map((def): CollectionStats => {
+    const { counts, depth } = countFields(def.fields);
+    tally(def.fields, def.name, "collection");
+
+    totals.collections++;
+    totals.top += counts.top;
+    totals.total += counts.total;
+    totals.required += counts.required;
+
+    return {
+      name: def.name,
+      label: def.label,
+      fields: counts,
+      // The same resolution the editor sees, not the raw declaration: both keys
+      // are optional in the model and fall back to a convention.
+      titleField: resolveTitleField(def) ?? null,
+      slugField: resolveSlugField(def) ?? null,
+      listed: listedFields(def).length,
+      sortable: def.sortable ?? false,
+      depth,
+    };
+  });
+
+  const singletons = Object.values(site.singletons).map((def): SingletonStats => {
+    const { counts, depth } = countFields(def.fields);
+    tally(def.fields, def.name, "singleton");
+
+    totals.singletons++;
+    totals.top += counts.top;
+    totals.total += counts.total;
+    totals.required += counts.required;
+
+    return { name: def.name, label: def.label, fields: counts, depth };
+  });
+
+  return {
+    collections,
+    singletons,
+    totals,
+    kinds: [...kinds]
+      .map(([kind, count]) => ({ kind, count }))
+      .sort((a, b) => b.count - a.count || a.kind.localeCompare(b.kind)),
+    relations,
+  };
+}

package/src/lib/version.ts

@@ -0,0 +1,29 @@
+/**
+ * The version of this build, read from the package manifest.
+ *
+ * Read rather than imported: an import would need a JSON module attribute and
+ * would put a second copy of the manifest in `dist/`. The file is a fixed
+ * distance from this module in both layouts — `src/lib` and `dist/lib`
+ * are the same depth below the package root, and the Docker image copies
+ * `package.json` next to `dist/` — so one path serves both.
+ *
+ * A missing or unreadable manifest is not worth failing a request over; the
+ * system page shows "unknown" instead.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+function readVersion(): string {
+  try {
+    const manifest = fs.readFileSync(
+      path.resolve(import.meta.dirname, "../../package.json"),
+      "utf8",
+    );
+    return (JSON.parse(manifest) as { version?: string }).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export const VERSION = readVersion();

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();
+  };
+}