@micacms/runtime 0.5.0 → 0.6.0-rc.2

package/src/config.ts

@@ -0,0 +1,113 @@
+/**
+ * The environment variables the runtime reads. There is no `loadConfig`: each
+ * app builds its own schema from `runtimeEnv`, because the variables and
+ * defaults are what make one app different from another.
+ */
+
+import path from "node:path";
+import { z } from "zod";
+
+import { DEFAULT_BASE_URL, DEFAULT_PORT } from "./lib/ports.js";
+
+/** In Zod 4, `.default` takes the output value and skips the transform. */
+export const bool = (fallback: boolean) =>
+  z
+    .enum(["true", "false", "1", "0"])
+    .transform((value) => value === "true" || value === "1")
+    .default(fallback);
+
+/** Splits a comma-separated list, trims entries and drops empty ones. */
+export const list = (value: string | undefined): string[] =>
+  (value ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+export class ConfigError extends Error {
+  override name = "ConfigError";
+}
+
+/** Hostnames that are this machine, and nowhere else. */
+export const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1", "0:0:0:0:0:0:0:1"]);
+
+/** The variables the runtime itself reads. Apps spread this into their schema. */
+export const runtimeEnv = {
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  MICA_LOG_LEVEL: z.enum(["debug", "info", "warn", "error", "silent"]).default("info"),
+
+  /** The listen address. The app sets the default. */
+  HOST: z.string().optional(),
+  PORT: z.coerce.number().int().min(1).max(65535).default(DEFAULT_PORT),
+
+  /** Public origin of the CMS itself. Used for cookies, CORS and media URLs. */
+  MICA_PUBLIC_URL: z.string().url().default(DEFAULT_BASE_URL),
+
+  /** The content root this Mica serves: a directory in a Git working tree. Each app sets it. */
+  MICA_CONTENT_ROOT: z.string(),
+
+  /** `false` disables commit and push: Publish shows the pending changes read-only. */
+  MICA_LOCAL_PUBLISH: bool(true),
+
+  MICA_MAX_UPLOAD_BYTES: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(25 * 1024 * 1024),
+
+  /** Read the client IP from X-Forwarded-For. Only enable behind a proxy. */
+  MICA_TRUST_PROXY: bool(false),
+  /** Extra browser origins allowed to call the admin API (dev Vite server). */
+  MICA_ADMIN_ORIGINS: z.string().optional(),
+  /** Overrides where the built admin SPA is served from. */
+  MICA_ADMIN_DIR: z.string().optional(),
+};
+
+const runtimeSchema = z.object(runtimeEnv);
+export type RuntimeEnv = z.infer<typeof runtimeSchema>;
+
+/**
+ * Adds the derived values to the parsed environment. Each app calls it from its
+ * own `transform`.
+ */
+export function deriveRuntime<T extends RuntimeEnv>(env: T) {
+  return {
+    ...env,
+    isProduction: env.NODE_ENV === "production",
+    contentRoot: path.resolve(env.MICA_CONTENT_ROOT),
+    adminOrigins: list(env.MICA_ADMIN_ORIGINS),
+  };
+}
+
+/** What the runtime requires of a finished configuration. */
+export type RuntimeConfig = ReturnType<typeof deriveRuntime<RuntimeEnv>> & {
+  /** Resolved by the app: the runtime never guesses an address. */
+  HOST: string;
+};
+
+/** Loads `./.env` into `process.env`. Variables that are already set win. */
+export function loadEnvFile(): void {
+  try {
+    process.loadEnvFile();
+  } catch (error) {
+    // A missing `.env` is normal; an unreadable or malformed one must not start
+    // the server with defaults.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new ConfigError(`Could not read .env: ${(error as Error).message}`);
+    }
+  }
+}
+
+/** Treats a blank variable as unset, so a verbatim copy of `.env.example` with blanks is valid. */
+export function withoutBlanks(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries(
+    Object.entries(env).filter(([, value]) => value !== undefined && value.trim() !== ""),
+  );
+}
+
+/** Formats a Zod refusal the way a person at a terminal reads it. */
+export function describeConfigIssues(error: z.ZodError): string {
+  const details = error.issues
+    .map((issue) => `  ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("\n");
+  return `Invalid environment configuration:\n${details}`;
+}

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,102 @@
+/**
+ * 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;
+}
+
+// No HEIC: Astro's image service cannot read it, so a site could not show it.
+const IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp", "image/avif"]);
+
+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");
+}