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

package/src/lib/errors.ts

@@ -0,0 +1,84 @@
+/**
+ * Error taxonomy.
+ *
+ * Every failure the API reports on purpose is an `ApiError` carrying a stable
+ * machine-readable `code`. Anything else that reaches the error middleware is
+ * treated as a bug: logged with its stack, reported as a bare 500.
+ */
+
+import type { FieldIssue } from "@micacms/core";
+
+export type ErrorCode =
+  | "bad_request"
+  | "validation_failed"
+  | "unauthenticated"
+  | "forbidden"
+  | "not_found"
+  | "conflict"
+  | "payload_too_large"
+  | "unsupported_media_type"
+  | "rate_limited"
+  | "internal_error"
+  /** An identity provider Mica depends on could not be reached. */
+  | "service_unavailable";
+
+const STATUS: Record<ErrorCode, number> = {
+  bad_request: 400,
+  validation_failed: 422,
+  unauthenticated: 401,
+  forbidden: 403,
+  not_found: 404,
+  conflict: 409,
+  payload_too_large: 413,
+  unsupported_media_type: 415,
+  rate_limited: 429,
+  internal_error: 500,
+  service_unavailable: 503,
+};
+
+export interface ApiErrorBody {
+  error: {
+    code: ErrorCode;
+    message: string;
+    issues?: FieldIssue[];
+  };
+}
+
+export class ApiError extends Error {
+  override name = "ApiError";
+  readonly code: ErrorCode;
+  readonly status: number;
+  readonly issues?: FieldIssue[];
+  /** Extra response headers, e.g. `Retry-After` on a rate limit. */
+  readonly headers?: Record<string, string>;
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    options: { issues?: FieldIssue[]; headers?: Record<string, string>; cause?: unknown } = {},
+  ) {
+    super(message, { cause: options.cause });
+    this.code = code;
+    this.status = STATUS[code];
+    this.issues = options.issues;
+    this.headers = options.headers;
+  }
+
+  toBody(): ApiErrorBody {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.issues ? { issues: this.issues } : {}),
+      },
+    };
+  }
+}
+
+export const badRequest = (message: string) => new ApiError("bad_request", message);
+export const unauthenticated = (message = "Authentication required.") =>
+  new ApiError("unauthenticated", message);
+export const forbidden = (message = "You do not have access to this resource.") =>
+  new ApiError("forbidden", message);
+export const notFound = (message = "Not found.") => new ApiError("not_found", message);
+export const conflict = (message: string) => new ApiError("conflict", message);

package/src/lib/file-type.ts

@@ -0,0 +1,108 @@
+/**
+ * Content sniffing for uploads.
+ *
+ * The browser-supplied MIME type is attacker-controlled and must not be
+ * trusted: an executable renamed to `.jpg` arrives as `image/jpeg`. The stored
+ * type is derived from the bytes instead, and the extension is regenerated
+ * from it rather than taken from the filename.
+ */
+
+export interface DetectedType {
+  mimeType: string;
+  extension: string;
+}
+
+const startsWith = (bytes: Uint8Array, signature: number[], offset = 0): boolean =>
+  signature.every((byte, index) => bytes[offset + index] === byte);
+
+const ascii = (bytes: Uint8Array, offset: number, length: number): string =>
+  Array.from(bytes.slice(offset, offset + length), (byte) => String.fromCharCode(byte)).join("");
+
+export function detectFileType(bytes: Uint8Array): DetectedType | null {
+  if (bytes.length < 12) return null;
+
+  if (startsWith(bytes, [0xff, 0xd8, 0xff])) {
+    return { mimeType: "image/jpeg", extension: "jpg" };
+  }
+
+  if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+    return { mimeType: "image/png", extension: "png" };
+  }
+
+  const header = ascii(bytes, 0, 6);
+  if (header === "GIF87a" || header === "GIF89a") {
+    return { mimeType: "image/gif", extension: "gif" };
+  }
+
+  if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 4) === "WEBP") {
+    return { mimeType: "image/webp", extension: "webp" };
+  }
+
+  // ISO base media formats declare their brand at offset 8, after the box size.
+  if (ascii(bytes, 4, 4) === "ftyp") {
+    const brand = ascii(bytes, 8, 4);
+    if (brand === "avif" || brand === "avis") {
+      return { mimeType: "image/avif", extension: "avif" };
+    }
+    if (brand === "heic" || brand === "heix" || brand === "mif1") {
+      return { mimeType: "image/heic", extension: "heic" };
+    }
+    if (brand === "isom" || brand === "mp42" || brand === "M4V ") {
+      return { mimeType: "video/mp4", extension: "mp4" };
+    }
+  }
+
+  if (ascii(bytes, 0, 5) === "%PDF-") {
+    return { mimeType: "application/pdf", extension: "pdf" };
+  }
+
+  if (isSvg(bytes)) {
+    return { mimeType: "image/svg+xml", extension: "svg" };
+  }
+
+  return null;
+}
+
+/** SVG has no magic number, so look for a root `<svg>` in the leading text. */
+function isSvg(bytes: Uint8Array): boolean {
+  const head = new TextDecoder("utf-8", { fatal: false })
+    .decode(bytes.slice(0, 1024))
+    .trimStart()
+    .toLowerCase();
+
+  if (head.startsWith("<svg")) return true;
+  if (head.startsWith("<?xml") || head.startsWith("<!doctype svg")) {
+    return head.includes("<svg");
+  }
+  return false;
+}
+
+const IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "image/avif",
+  "image/heic",
+]);
+
+const DOCUMENT_TYPES = new Set(["application/pdf"]);
+
+export const isImageType = (mimeType: string): boolean => IMAGE_TYPES.has(mimeType);
+
+/**
+ * Whether a detected type is acceptable for a field's `accept` setting.
+ * `any` deliberately does not mean "anything": only the types listed here can
+ * be stored at all.
+ */
+export function isAccepted(mimeType: string, accept: "image" | "document" | "any"): boolean {
+  if (accept === "image") return IMAGE_TYPES.has(mimeType);
+  if (accept === "document") return DOCUMENT_TYPES.has(mimeType);
+  return IMAGE_TYPES.has(mimeType) || DOCUMENT_TYPES.has(mimeType) || mimeType === "video/mp4";
+}
+
+/**
+ * SVG can carry scripts, so Mica neither stores nor shows it (#86). It is still
+ * detected, so that the refusal can say why.
+ */
+export const SVG_TYPE = "image/svg+xml";

package/src/lib/id.ts

@@ -0,0 +1,6 @@
+import { randomBytes } from "node:crypto";
+
+/** URL-safe random token for sessions and one-time links. */
+export function randomToken(bytes = 32): string {
+  return randomBytes(bytes).toString("base64url");
+}

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