@micacms/runtime 0.5.0 → 0.6.0-rc.1

package/src/context.ts

@@ -0,0 +1,167 @@
+/**
+ * Builds the runtime's services for one site, with no module-level singletons.
+ * The app supplies the working tree's files and the owner policy, so the
+ * runtime stays authentication-neutral.
+ */
+
+import type { Site } from "@micacms/core";
+
+import type { RuntimeConfig } from "./config.js";
+import { createLogger, type Logger } from "./lib/logger.js";
+import { createRateLimiter, type RateLimiter } from "./lib/rate-limit.js";
+import { readOnlyParts } from "./schema.js";
+import { createMediaService, type MediaService } from "./services/media.js";
+import type { ContentStagingService } from "./services/changes.js";
+import { createContentStore, type ContentStore } from "./services/content-store.js";
+import { createWorkingTreeStagingService } from "./services/staging.js";
+import { createWorkspaceLocks, lockedFiles, type WorkspaceLocks } from "./workspace/locks.js";
+import type { OwnerPolicy } from "./workspace/policy.js";
+import type { ContentFiles } from "./workspace/files.js";
+import type { GitTree } from "./workspace/tree.js";
+
+/** The one site this process serves. Several sites means several processes. */
+export interface SiteContext {
+  /** Identifies this site in logs. */
+  id: string;
+  /** The content model, read from the repository at startup. */
+  model: Site;
+  /** The working tree's files behind the workspace locks. Only Publish makes a commit. */
+  contentRepository: ContentFiles;
+  /**
+   * Revision of `.mica/schema.json` when the model was loaded. The publish
+   * drift gate compares against it.
+   */
+  schemaRevision: string | null;
+  /** Collections and singletons this build cannot write, from `readOnlyParts`, with the reason. */
+  readOnly: ReadonlyMap<string, string>;
+}
+
+export const DEFAULT_SITE_ID = "default";
+
+/** Facts about the composition that the System page shows and the runtime cannot know. */
+export interface OperationalInfo {
+  /** How this deployment authenticates, in words. */
+  auth: string;
+  /** What decides who may edit, in the operator's own words. */
+  admission?: string;
+  dataDir?: string;
+  sessionTtlHours?: number;
+  sessionIdleHours?: number;
+  /** Names of the secrets this process generated for itself. */
+  generatedSecrets?: string[];
+}
+
+/** What /ready asks the composition. */
+export interface RuntimeHealth {
+  /**
+   * Whether the site can be edited, with short reason codes. Never names the
+   * repository: the endpoint is public.
+   */
+  ready?: () => { ok: boolean; reasons: string[] };
+}
+
+export interface RuntimeContext {
+  config: RuntimeConfig;
+  site: SiteContext;
+  logger: Logger;
+  services: {
+    content: ContentStore;
+    media: MediaService;
+    staging: ContentStagingService;
+  };
+  limiters: {
+    api: RateLimiter;
+  };
+  operational(): OperationalInfo;
+  health: RuntimeHealth;
+  shutdown(): Promise<void>;
+}
+
+export interface CreateRuntimeContextOptions {
+  config: RuntimeConfig;
+  model: Site;
+  /** The working tree's files, without locks. The app builds it. */
+  files: ContentFiles;
+  /** Revision of the manifest the model was read from. Null when unknown. */
+  schemaRevision?: string | null;
+  siteId?: string;
+  logger?: Logger;
+  operational?: () => OperationalInfo;
+  health?: RuntimeHealth;
+  /** Who owns the working tree. Defaults to the developer. */
+  policy?: OwnerPolicy;
+  /** Shared with the owner's own work on the tree, such as a sync. */
+  locks?: WorkspaceLocks;
+  /** See `WorkingTreeStagingDeps.tree`. */
+  tree?: GitTree;
+  onShutdown?: () => void | Promise<void>;
+}
+
+export function createRuntimeContext(options: CreateRuntimeContextOptions): RuntimeContext {
+  const { config, model } = options;
+
+  const logger =
+    options.logger ??
+    createLogger({
+      level: config.MICA_LOG_LEVEL,
+      pretty: !config.isProduction,
+    });
+
+  const schemaRevision = options.schemaRevision ?? null;
+
+  // Services write through the lock wrapper; staging takes the locks itself.
+  const locks = options.locks ?? createWorkspaceLocks();
+
+  const readOnly = readOnlyParts(model);
+  for (const reason of readOnly.values()) logger.warn("Read-only in this version of Mica", { reason });
+
+  const site: SiteContext = {
+    id: options.siteId ?? DEFAULT_SITE_ID,
+    model,
+    contentRepository: lockedFiles(options.files, locks.tree),
+    schemaRevision,
+    readOnly,
+  };
+
+  const services = {
+    content: createContentStore(model, site.contentRepository, readOnly),
+    media: createMediaService({
+      files: site.contentRepository,
+      maxBytes: config.MICA_MAX_UPLOAD_BYTES,
+    }),
+    staging: createWorkingTreeStagingService({
+      model,
+      files: options.files,
+      contentRoot: config.contentRoot,
+      schemaRevision,
+      readOnly,
+      publishEnabled: config.MICA_LOCAL_PUBLISH,
+      logger,
+      locks,
+      ...(options.policy ? { policy: options.policy } : {}),
+      ...(options.tree ? { tree: options.tree } : {}),
+    }),
+  };
+
+  const limiters = {
+    // Generous: it stops runaway scripts, it does not shape traffic.
+    api: createRateLimiter({ limit: 600, windowMs: 60_000 }),
+  };
+
+  return {
+    config,
+    site,
+    logger,
+    services,
+    limiters,
+    operational:
+      options.operational ??
+      (() => ({ auth: "unspecified" })),
+    health: options.health ?? {},
+
+    async shutdown() {
+      limiters.api.stop();
+      await options.onShutdown?.();
+    },
+  };
+}

package/src/http.ts

@@ -0,0 +1,46 @@
+import type { Context } from "hono";
+
+import type { AccessContext } from "@micacms/core";
+
+import type { RuntimeContext } from "./context.js";
+import type { Logger } from "./lib/logger.js";
+
+export interface Env {
+  Variables: {
+    ctx: RuntimeContext;
+    logger: Logger;
+    requestId: string;
+    /**
+     * Who this request acts as. The auth surface's gate sets it on every admin
+     * route; the runtime never sets it.
+     */
+    access: AccessContext;
+  };
+}
+
+/**
+ * Client IP. Reads `X-Forwarded-For` only with MICA_TRUST_PROXY, or a client could
+ * spoof its address past the rate limit. The right-most entry is the address
+ * the proxy saw; the entries to its left come from the client.
+ */
+export function clientIp(c: Context<Env>): string {
+  const { config } = c.get("ctx");
+
+  if (config.MICA_TRUST_PROXY) {
+    const forwarded = c.req.header("x-forwarded-for");
+    const last = forwarded?.split(",").at(-1)?.trim();
+    if (last) return last;
+  }
+
+  const info = c.env as { incoming?: { socket?: { remoteAddress?: string } } } | undefined;
+  return info?.incoming?.socket?.remoteAddress ?? "unknown";
+}
+
+/**
+ * The commit author. Null in the local editor, where the commit keeps the
+ * developer's own Git identity.
+ */
+export function actorOf(c: Context<Env>): { id: string; email: string; name: string } | null {
+  const identity = c.get("access")?.identity;
+  return identity ? { id: identity.subject, email: identity.email, name: identity.name } : null;
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+/**
+ * @micacms/runtime: the single-site, authentication-neutral Mica runtime.
+ * It must never import an auth implementation; the composing app supplies the `AuthSurface`.
+ */
+
+export { createApp, allowAll, type AuthSurface, type CreateAppOptions } from "./app.js";
+export {
+  createRuntimeContext,
+  DEFAULT_SITE_ID,
+  type CreateRuntimeContextOptions,
+  type OperationalInfo,
+  type RuntimeContext,
+  type RuntimeHealth,
+  type SiteContext,
+} from "./context.js";
+export {
+  bool,
+  ConfigError,
+  deriveRuntime,
+  describeConfigIssues,
+  list,
+  loadEnvFile,
+  LOOPBACK,
+  runtimeEnv,
+  withoutBlanks,
+  type RuntimeConfig,
+  type RuntimeEnv,
+} from "./config.js";
+export { startServer, type StartServerOptions } from "./server.js";
+export { actorOf, clientIp, type Env } from "./http.js";
+export {
+  checkSchema,
+  layoutProblems,
+  loadSchema,
+  readOnlyParts,
+  SchemaError,
+  schemaFingerprint,
+  schemaOrigin,
+} from "./schema.js";
+export {
+  allowedOrigins,
+  errorHandler,
+  originGuard,
+  rateLimit,
+  requestContext,
+  securityHeaders,
+} from "./middleware/index.js";
+export { adminAssetsExist } from "./routes/admin-spa.js";
+export {
+  ApiError,
+  badRequest,
+  conflict,
+  forbidden,
+  notFound,
+  unauthenticated,
+  type ApiErrorBody,
+  type ErrorCode,
+} from "./lib/errors.js";
+export { createLogger, type Logger } from "./lib/logger.js";
+export { createRateLimiter, type RateLimiter } from "./lib/rate-limit.js";
+export { randomToken } from "./lib/id.js";
+export { DEFAULT_BASE_URL, DEFAULT_PORT } from "./lib/ports.js";
+export { VERSION } from "./lib/version.js";
+export {
+  analyseChanges,
+  classifyPath,
+  describeProblems,
+  flattenProblems,
+  type AnnotatedChange,
+  type ChangeOwner,
+  type ContentStagingService,
+  type RepositoryInfo,
+  type PublishInput,
+  type StagingProblem,
+  type StagingStatus,
+  type StagingValidation,
+} from "./services/changes.js";
+export {
+  createWorkingTreeStagingService,
+  type WorkingTreeStagingDeps,
+} from "./services/staging.js";
+export { createMediaService, formatBytes, type MediaFile, type MediaService } from "./services/media.js";
+export {
+  createContentStore,
+  ContentError,
+  ValidationError,
+  type ContentStore,
+  type SavedEntry,
+  type SaveEntryInput,
+} from "./services/content-store.js";
+export {
+  checkChangePaths,
+  ConflictError,
+  contentFiles,
+  FilesError,
+  type Author,
+  type ContentFiles,
+  type ContentFilesOptions,
+  type FileChange,
+  type FileChanges,
+} from "./workspace/files.js";
+export {
+  developerEnvironment,
+  firstLine,
+  GitError,
+  gitRunner,
+  type GitCallOptions,
+  type GitRunner,
+  type GitRunnerOptions,
+} from "./workspace/git.js";
+export {
+  createMutex,
+  createReadWriteLock,
+  createWorkspaceLocks,
+  lockedFiles,
+  type Mutex,
+  type ReadWriteLock,
+  type WorkspaceLocks,
+} from "./workspace/locks.js";
+export type {
+  OwnerPolicy,
+  PublishAvailability,
+  RepositoryDescription,
+  SyncConflict,
+  SyncStatus,
+} from "./workspace/policy.js";
+export { developerPolicy, type DeveloperPolicyOptions } from "./workspace/developer.js";
+export {
+  commitPaths,
+  headRevision,
+  headSource,
+  inRepo,
+  listTreeChanges,
+  LITERAL,
+  locateTree,
+  parseStatus,
+  recommitPaths,
+  type GitTree,
+  type TreeChange,
+} from "./workspace/tree.js";
+export { schemaStats } from "./lib/schema-stats.js";

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}`;