filegrc 0.1.0

package/src/paths.js

@@ -0,0 +1,137 @@
+import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+
+export function resolveWorkspaceRoot(input = process.cwd()) {
+  let current = resolve(input);
+  if (existsSync(current) && !isDirectory(current)) current = dirname(current);
+
+  while (true) {
+    if (existsSync(join(current, "data", "workspace.json"))) return canonicalWorkspaceRoot(current);
+    if (existsSync(join(current, "workspace.json")) && current.endsWith(`${sep}data`)) {
+      return canonicalWorkspaceRoot(dirname(current));
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  throw new Error("No FileGRC workspace was found from the requested path.");
+}
+
+export function isWithin(parent, candidate) {
+  const path = relative(resolve(parent), resolve(candidate));
+  return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path));
+}
+
+export function resolveDataPath(root, dataRelativePath) {
+  if (typeof dataRelativePath !== "string" || !dataRelativePath) {
+    throw new Error("A non-empty data-relative path is required");
+  }
+  if (!isCanonicalDataPath(dataRelativePath)) {
+    throw new Error(`Unsafe data path: ${dataRelativePath}`);
+  }
+  const dataRoot = join(resolveWorkspaceRoot(root), "data");
+  const target = resolve(dataRoot, dataRelativePath);
+  if (!isWithin(dataRoot, target)) throw new Error(`Path leaves data/: ${dataRelativePath}`);
+  const realDataRoot = realpathSync(dataRoot);
+  const existing = nearestExistingPath(target);
+  if (!isWithin(realDataRoot, realExistingPath(existing, dataRelativePath))) {
+    throw new Error(`Path resolves outside data/: ${dataRelativePath}`);
+  }
+  assertNoSymlinkComponents(dataRoot, target, dataRelativePath);
+  return target;
+}
+
+export function isCanonicalDataPath(value) {
+  return typeof value === "string"
+    && Boolean(value)
+    && !isAbsolute(value)
+    && !value.includes("\0")
+    && !value.includes("\\")
+    && posix.normalize(value) === value;
+}
+
+export function resolveWorkspacePath(root, workspacePath) {
+  if (typeof workspacePath !== "string" || !workspacePath) {
+    throw new Error("A non-empty workspace path is required");
+  }
+  const workspaceRoot = resolveWorkspaceRoot(root);
+  const target = resolve(workspaceRoot, workspacePath);
+  if (!isWithin(workspaceRoot, target)) throw new Error(`Path leaves the workspace: ${workspacePath}`);
+  const existing = nearestExistingPath(target);
+  if (!isWithin(workspaceRoot, realExistingPath(existing, workspacePath))) {
+    throw new Error(`Path resolves outside the workspace: ${workspacePath}`);
+  }
+  assertNoSymlinkComponents(workspaceRoot, target, workspacePath);
+  return target;
+}
+
+export function relativeToWorkspace(root, path) {
+  return relative(resolveWorkspaceRoot(root), path).split(sep).join("/");
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function canonicalWorkspaceRoot(path) {
+  const root = realpathSync(path);
+  const dataPath = join(root, "data");
+  const dataRoot = realpathSync(dataPath);
+  if (!isWithin(root, dataRoot)) {
+    throw new Error("The data directory resolves outside the workspace.");
+  }
+  if (lstatSync(dataPath).isSymbolicLink()) {
+    throw new Error("The data directory must be a real directory, not a symbolic link.");
+  }
+  return root;
+}
+
+function assertNoSymlinkComponents(parent, target, displayPath) {
+  const path = relative(parent, target);
+  if (!path) return;
+  let current = parent;
+  for (const segment of path.split(sep)) {
+    current = join(current, segment);
+    try {
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Path contains a symbolic link: ${displayPath}`);
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+function nearestExistingPath(path) {
+  let current = path;
+  while (!entryExists(current)) {
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return current;
+}
+
+function entryExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function realExistingPath(path, displayPath) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") throw new Error(`Path contains an unavailable symlink: ${displayPath}`);
+    throw error;
+  }
+}

package/src/recurrence.js

@@ -0,0 +1,89 @@
+export function nextCalendarOccurrence(recurrence, asOf) {
+  const boundary = parseCalendarDate(asOf);
+  if (!validCalendarRecurrence(recurrence) || !boundary) return null;
+  if (recurrence.anchorDate >= asOf) return recurrence.anchorDate;
+  const current = calendarOccurrenceIndex(recurrence, asOf);
+  const candidate = calendarOccurrence(recurrence, Math.max(0, current));
+  return candidate >= asOf ? candidate : calendarOccurrence(recurrence, current + 1);
+}
+
+export function validCalendarRecurrence(recurrence) {
+  return Boolean(
+    recurrence
+    && recurrence.mode === "calendar"
+    && Number.isSafeInteger(recurrence.interval)
+    && recurrence.interval > 0
+    && ["day", "week", "month", "year"].includes(recurrence.unit)
+    && parseCalendarDate(recurrence.anchorDate)
+  );
+}
+
+export function calendarOccurrence(recurrence, index) {
+  if (!validCalendarRecurrence(recurrence) || !Number.isInteger(index) || index < 0) return null;
+  const anchor = parseCalendarDate(recurrence.anchorDate);
+  if (recurrence.unit === "day" || recurrence.unit === "week") {
+    const step = recurrence.interval * (recurrence.unit === "week" ? 7 : 1);
+    return formatCalendarDateUtc(new Date(anchor.date.getTime() + index * step * 86_400_000));
+  }
+  const step = recurrence.interval * (recurrence.unit === "year" ? 12 : 1);
+  const monthIndex = anchor.month - 1 + index * step;
+  const year = anchor.year + Math.floor(monthIndex / 12);
+  const month = ((monthIndex % 12) + 12) % 12;
+  const lastDay = utcCalendarDate(year, month + 1, 0).getUTCDate();
+  return formatCalendarDateUtc(utcCalendarDate(year, month, Math.min(anchor.day, lastDay)));
+}
+
+export function calendarOccurrenceIndex(recurrence, date) {
+  const anchor = validCalendarRecurrence(recurrence) ? parseCalendarDate(recurrence.anchorDate) : null;
+  const boundary = parseCalendarDate(date);
+  if (!anchor || !boundary || date < recurrence.anchorDate) return -1;
+  if (recurrence.unit === "day" || recurrence.unit === "week") {
+    const step = recurrence.interval * (recurrence.unit === "week" ? 7 : 1);
+    return Math.floor((boundary.date - anchor.date) / (step * 86_400_000));
+  }
+  const step = recurrence.interval * (recurrence.unit === "year" ? 12 : 1);
+  const elapsedMonths = (boundary.year - anchor.year) * 12 + boundary.month - anchor.month;
+  let index = Math.max(0, Math.floor(elapsedMonths / step));
+  while (index > 0 && calendarOccurrence(recurrence, index) > date) index -= 1;
+  while (calendarOccurrence(recurrence, index + 1) <= date) index += 1;
+  return index;
+}
+
+export function addCalendarDays(value, days) {
+  const parsed = parseCalendarDate(value);
+  if (!parsed || !Number.isInteger(days)) return null;
+  return formatCalendarDateUtc(new Date(parsed.date.getTime() + days * 86_400_000));
+}
+
+export function calendarDayDifference(from, to) {
+  const start = parseCalendarDate(from);
+  const end = parseCalendarDate(to);
+  return start && end ? Math.round((end.date - start.date) / 86_400_000) : null;
+}
+
+export function parseCalendarDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value || "")) return null;
+  const [year, month, day] = value.split("-").map(Number);
+  if (year < 1) return null;
+  const date = utcCalendarDate(year, month - 1, day);
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+    ? { year, month, day, date }
+    : null;
+}
+
+export function utcCalendarDate(year, monthIndex, day) {
+  const date = new Date(0);
+  date.setUTCFullYear(year, monthIndex, day);
+  date.setUTCHours(0, 0, 0, 0);
+  return date;
+}
+
+export function formatCalendarDateUtc(date) {
+  const year = date.getUTCFullYear();
+  if (!Number.isInteger(year) || year < 1 || year > 9999) return null;
+  return [
+    String(year).padStart(4, "0"),
+    String(date.getUTCMonth() + 1).padStart(2, "0"),
+    String(date.getUTCDate()).padStart(2, "0")
+  ].join("-");
+}

package/src/resource-markdown.js

@@ -0,0 +1,63 @@
+import { basename, dirname, extname, join } from "node:path";
+import { getResourceDefinition } from "../model/index.js";
+
+export function resourceDataPath(model, record) {
+  const definition = getResourceDefinition(model, record.type);
+  if (definition.singleton) return definition.singleton;
+  const recordPath = (definition.recordPath ?? "{id}.json").replaceAll("{id}", record.id);
+  return join(definition.collection, recordPath).replaceAll("\\", "/");
+}
+
+export function markdownSlots(model, type) {
+  const definition = getResourceDefinition(model, type);
+  const dedicated = Object.entries(definition.markdown ?? {}).map(([name, slot]) => ({
+    name,
+    label: slot.label ?? humanize(name),
+    primary: Boolean(slot.primary),
+    required: Boolean(slot.required)
+  }));
+  if (dedicated.length) return dedicated;
+  return [{
+    name: model.recordContent.slot,
+    label: model.recordContent.label,
+    primary: true,
+    required: false
+  }];
+}
+
+export function markdownDataPath(model, record, slotName) {
+  const slot = markdownSlots(model, record.type).find(({ name }) => name === slotName);
+  if (!slot) throw new Error(`Unknown Markdown slot "${slotName}" for ${record.type}.`);
+  const recordPath = resourceDataPath(model, record);
+  const extension = extname(recordPath);
+  const stem = basename(recordPath, extension);
+  const suffix = slot.primary ? "" : `-${kebabCase(slot.name)}`;
+  return join(dirname(recordPath), `${stem}${suffix}.md`).replaceAll("\\", "/");
+}
+
+export function markdownEntries(model, record) {
+  return markdownSlots(model, record.type)
+    .map((slot) => ({ ...slot, path: markdownDataPath(model, record, slot.name) }))
+    .filter(({ path }) => path);
+}
+
+export function isMarkdownChoice(value) {
+  return typeof value === "string" && value.startsWith("$markdown:");
+}
+
+function kebabCase(value) {
+  return String(value)
+    .replace(/Path$/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+}
+
+function humanize(value) {
+  return String(value)
+    .replace(/Path$/, "")
+    .replace(/[-_]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/^./, (letter) => letter.toUpperCase());
+}

package/src/search.js

@@ -0,0 +1,27 @@
+export function searchResources(resources, model, options = {}) {
+  const query = String(options.query ?? "").trim().toLowerCase();
+  const filters = options.filters ?? {};
+  return resources.filter((resource) => {
+    if (options.type && resource.type !== options.type) return false;
+    for (const [field, expected] of Object.entries(filters)) {
+      if (expected === undefined || expected === "") continue;
+      const value = resource[field];
+      if (Array.isArray(value) ? !value.includes(expected) : String(value ?? "") !== String(expected)) return false;
+    }
+    if (!query) return true;
+    return searchableValues(resource, model).some((value) => value.includes(query));
+  });
+}
+
+export function searchableValues(resource, model) {
+  const definition = model.resources[resource.type];
+  if (!definition) return [resource.id, resource.type].map((value) => String(value ?? "").toLowerCase());
+  const fields = { ...model.commonFields, ...definition.fields };
+  const values = [resource.id, resource.type];
+  for (const [name, field] of Object.entries(fields)) {
+    if (!field.search || resource[name] === undefined) continue;
+    const value = resource[name];
+    values.push(...(Array.isArray(value) ? value : [value]));
+  }
+  return values.map((value) => String(value).toLowerCase());
+}

package/src/server.js

@@ -0,0 +1,300 @@
+import { createServer as createHttpServer } from "node:http";
+import { readFile, realpath } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { getResourceDefinition } from "../model/index.js";
+import { prepareAuditWorkspace } from "./audit-preparation.js";
+import { generateEvidencePacket, prepareEvidencePacket } from "./evidence-packet.js";
+import { FAVICON_PNG } from "./favicon.js";
+import { createResource, deleteResource, updateContent, updateResource } from "./files.js";
+import { commitAndPushWorkspace, getFileHistory, pullWorkspace, pushWorkspace } from "./git.js";
+import { completeObligationOccurrence, createObligationEvent, planObligations } from "./obligations.js";
+import { isWithin, relativeToWorkspace, resolveWorkspacePath } from "./paths.js";
+import { createAppState } from "./state.js";
+import { loadWorkspace } from "./workspace.js";
+import { APP_SCRIPT, APP_STYLES, renderIndex } from "./web.js";
+
+export function createFileGRCServer(input = process.cwd(), options = {}) {
+  return createHttpServer(async (request, response) => {
+    try {
+      if (!expectedHost(request, options.allowedHosts)) {
+        return json(response, 403, { error: "The request host is not allowed." });
+      }
+      const url = new URL(request.url, "http://localhost");
+      if (["POST", "PUT", "DELETE"].includes(request.method) && !sameOrigin(request)) {
+        return json(response, 403, { error: "Cross-origin writes are not allowed." });
+      }
+      if (request.method === "GET" && url.pathname === "/api/state") {
+        return json(response, 200, await createAppState(input));
+      }
+      if (request.method === "GET" && url.pathname === "/api/history") {
+        const path = url.searchParams.get("path");
+        if (!path || path.includes("..") || !path.startsWith("data/")) return json(response, 400, { error: "A safe data path is required." });
+        return json(response, 200, getFileHistory(input, path));
+      }
+      if (request.method === "GET" && url.pathname === "/api/obligations") {
+        const loaded = await loadWorkspace(input);
+        return json(response, 200, planObligations(loaded.resources, {
+          asOf: url.searchParams.get("asOf") || undefined,
+          from: url.searchParams.get("from") || undefined,
+          through: url.searchParams.get("through") || undefined,
+          now: url.searchParams.get("now") || undefined,
+          includeComplete: url.searchParams.get("includeComplete") === "true"
+        }));
+      }
+      if (request.method === "POST" && url.pathname === "/api/obligation-events") {
+        return json(response, 201, await createObligationEvent(input, await readJson(request)));
+      }
+      if (request.method === "POST" && url.pathname === "/api/obligation-completions") {
+        const payload = await readJson(request);
+        if (!safeSegment(payload.obligationId)) return json(response, 400, { error: "A safe obligation ID is required." });
+        const result = await completeObligationOccurrence(input, {
+          obligationId: payload.obligationId,
+          record: payload.record,
+          content: payload.content,
+          expectedRevision: payload.revision
+        });
+        return json(response, 201, result);
+      }
+      if (request.method === "GET" && url.pathname === "/api/evidence-packet") {
+        return json(response, 200, await prepareEvidencePacket(input, {
+          start: url.searchParams.get("start"),
+          end: url.searchParams.get("end"),
+          auditId: url.searchParams.get("auditId") || undefined
+        }));
+      }
+      if (request.method === "POST" && url.pathname === "/api/evidence-packet") {
+        const payload = await readJson(request);
+        const { packet, output: writtenOutput, files } = await generateEvidencePacket(input, payload);
+        const output = relativeToWorkspace(input, writtenOutput);
+        const outputSegments = output.split("/");
+        const packetUrl = outputSegments.length === 3
+          && outputSegments[0] === ".filegrc"
+          && outputSegments[1] === "evidence-packets"
+          ? `/packet/${outputSegments.map(encodeURIComponent).join("/")}/index.html`
+          : null;
+        return json(response, 201, {
+          packet,
+          output,
+          packetUrl,
+          files
+        });
+      }
+      if (request.method === "POST" && url.pathname === "/api/audit-preparation") {
+        return json(response, 201, await prepareAuditWorkspace(input, await readJson(request)));
+      }
+      if (request.method === "POST" && url.pathname === "/api/resources") {
+        const payload = await readJson(request);
+        const record = payload.record ?? payload;
+        const result = await createResource(input, record, { content: payload.record ? payload.content : undefined });
+        return json(response, 201, { record: result.record });
+      }
+      if (request.method === "POST" && url.pathname === "/api/commit") {
+        const payload = await readJson(request);
+        return json(response, 201, await commitAndPushWorkspace(input, payload.message));
+      }
+      if (request.method === "POST" && url.pathname === "/api/git/pull") {
+        return json(response, 200, await pullWorkspace(input));
+      }
+      if (request.method === "POST" && url.pathname === "/api/git/push") {
+        return json(response, 200, await pushWorkspace(input));
+      }
+      if (request.method === "PUT" && url.pathname === "/api/content") {
+        const payload = await readJson(request);
+        const result = await updateContent(input, payload.path, payload.source, { expectedRevision: payload.revision });
+        return json(response, 200, { path: result.dataRelativePath });
+      }
+      const match = /^\/api\/resource\/([^/]+)\/([^/]+)$/.exec(url.pathname);
+      if (match) {
+        const type = decodeURIComponent(match[1]);
+        const id = decodeURIComponent(match[2]);
+        if (!safeSegment(type) || !safeSegment(id)) return json(response, 400, { error: "Unsafe resource identifier." });
+        if (request.method === "GET") {
+          const state = await createAppState(input);
+          const entry = state.resources.find(({ record }) => record.type === type && record.id === id);
+          return entry ? json(response, 200, entry) : json(response, 404, { error: "Resource not found." });
+        }
+        if (request.method === "PUT") {
+          const payload = await readJson(request);
+          const record = payload.record ?? payload;
+          const result = await updateResource(input, type, id, record, {
+            content: payload.record ? payload.content : undefined,
+            expectedRevision: payload.revision,
+            expectedContentRevisions: payload.contentRevisions
+          });
+          return json(response, 200, { record: result.record });
+        }
+        if (request.method === "DELETE") {
+          const result = await deleteResource(input, type, id, { expectedRevision: url.searchParams.get("revision") });
+          return json(response, 200, { deleted: true, type, id, deletedContent: result.deletedContent });
+        }
+      }
+      if (request.method === "GET" && url.pathname === "/favicon.png") return text(response, 200, FAVICON_PNG, "image/png");
+      if (request.method === "GET" && url.pathname === "/filegrc-app.js") return text(response, 200, APP_SCRIPT, "text/javascript; charset=utf-8");
+      if (request.method === "GET" && url.pathname === "/filegrc.css") return text(response, 200, APP_STYLES, "text/css; charset=utf-8");
+      if (request.method === "GET" && url.pathname.startsWith("/packet/")) {
+        const segments = url.pathname.slice("/packet/".length).split("/").map(decodeURIComponent);
+        if (
+          segments.some((segment) => (
+            !segment
+            || segment === "."
+            || segment === ".."
+            || segment.includes("/")
+            || segment.includes("\\")
+            || segment.includes("\0")
+          ))
+          || segments[0] !== ".filegrc"
+          || segments[1] !== "evidence-packets"
+        ) {
+          return json(response, 400, { error: "A generated evidence-packet path is required." });
+        }
+        const relativePath = segments.join("/");
+        const path = resolveWorkspacePath(input, relativePath);
+        const packetRoot = resolveWorkspacePath(input, ".filegrc/evidence-packets");
+        if (!isWithin(packetRoot, path)) return json(response, 400, { error: "A generated evidence-packet path is required." });
+        const [realPacketRoot, realPath] = await Promise.all([realpath(packetRoot), realpath(path)]);
+        if (realPacketRoot !== resolve(packetRoot) || !isWithin(realPacketRoot, realPath)) {
+          return json(response, 400, { error: "A generated evidence-packet path is required." });
+        }
+        const isPacketIndex = segments.length === 4 && segments.at(-1) === "index.html";
+        return text(response, 200, await readFile(path), packetContentType(path, isPacketIndex));
+      }
+      if (request.method === "GET" && !url.pathname.startsWith("/api/")) return text(response, 200, renderIndex(), "text/html; charset=utf-8");
+      json(response, 404, { error: "Not found." });
+    } catch (error) {
+      const status = statusFor(error);
+      json(response, status, { error: publicErrorMessage(error, status) });
+    }
+  });
+}
+
+export async function serveWorkspace(input = process.cwd(), options = {}) {
+  const host = String(options.host ?? "127.0.0.1").trim();
+  const port = Number(options.port ?? 8787);
+  if (!host) throw new Error("The server host must be a non-empty string.");
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new Error("The server port must be an integer from 0 through 65535.");
+  }
+  const loaded = await loadWorkspace(input);
+  getResourceDefinition(loaded.model, "workspace");
+  const server = createFileGRCServer(loaded.root, { allowedHosts: [host] });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  return {
+    server,
+    root: loaded.root,
+    address: server.address(),
+    url: `http://${urlHost(host)}:${server.address().port}`
+  };
+}
+
+async function readJson(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > 2_000_000) throw new Error("Request body exceeds 2 MB.");
+    chunks.push(chunk);
+  }
+  const source = Buffer.concat(chunks).toString("utf8");
+  if (!source) throw new Error("A JSON request body is required.");
+  const value = JSON.parse(source);
+  if (!value || Array.isArray(value) || typeof value !== "object") {
+    throw new Error("The JSON request body must be an object.");
+  }
+  return value;
+}
+
+function json(response, status, value) {
+  text(response, status, `${JSON.stringify(value, null, 2)}\n`, "application/json; charset=utf-8");
+}
+
+function text(response, status, value, contentType) {
+  response.writeHead(status, {
+    "content-type": contentType,
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    "x-frame-options": "DENY",
+    "referrer-policy": "no-referrer",
+    "permissions-policy": "camera=(), geolocation=(), microphone=()",
+    "cross-origin-resource-policy": "same-origin",
+    "content-security-policy": "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'"
+  });
+  response.end(value);
+}
+
+function packetContentType(path, isPacketIndex = false) {
+  if (isPacketIndex) return "text/html; charset=utf-8";
+  return {
+    ".json": "application/json; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".csv": "text/csv; charset=utf-8"
+  }[extname(path).toLowerCase()] || "application/octet-stream";
+}
+
+function safeSegment(value) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+
+function sameOrigin(request) {
+  const origin = request.headers.origin;
+  if (!origin) return true;
+  try {
+    const expectedProtocol = request.socket.encrypted ? "https:" : "http:";
+    return new URL(origin).origin === `${expectedProtocol}//${request.headers.host}`;
+  } catch {
+    return false;
+  }
+}
+
+function expectedHost(request, allowedHosts = []) {
+  const host = request.headers.host;
+  const localAddress = normalizeAddress(request.socket.localAddress);
+  if (typeof host !== "string" || !host || !localAddress) return false;
+  try {
+    const requested = normalizeAddress(new URL(`http://${host}`).hostname);
+    const allowed = new Set(allowedHosts.map(normalizeAddress));
+    return allowed.has(requested)
+      || requested === localAddress
+      || (isLoopback(localAddress) && (requested === "localhost" || isLoopback(requested)));
+  } catch {
+    return false;
+  }
+}
+
+function normalizeAddress(value) {
+  return String(value ?? "").replace(/^\[|\]$/g, "").replace(/^::ffff:/, "").toLowerCase();
+}
+
+function isLoopback(value) {
+  return value === "::1" || /^127(?:\.\d{1,3}){3}$/.test(value);
+}
+
+function urlHost(host) {
+  const normalized = normalizeAddress(host);
+  const display = normalized === "0.0.0.0" ? "127.0.0.1" : normalized === "::" ? "::1" : host;
+  return display.includes(":") && !display.startsWith("[") ? `[${display}]` : display;
+}
+
+function statusFor(error) {
+  if (error instanceof SyntaxError || error instanceof URIError) return 400;
+  if (/exceeds 2 MB/i.test(error.message)) return 413;
+  if (/changed after you opened|source changed|revision changed/i.test(error.message)) return 409;
+  if (/already exists|target file already exists/i.test(error.message)) return 409;
+  if (/Git could not (?:pull|push)|upstream branch|multiple remotes|no Git remote|check out a branch|before trying to (?:pull|push)/i.test(error.message)) return 409;
+  if (/not found|ENOENT/i.test(error.message)) return 404;
+  if (/invalid|required|unsafe|match|workspace|singleton|commit message|no changes|git history|git user|unknown resource type|must use|must be|content path|data path|path leaves|valid .*date|not found|no active obligations|end date|through date|already exists|EEXIST/i.test(error.message)) return 400;
+  return 500;
+}
+
+function publicErrorMessage(error, status) {
+  if (error?.code === "ENOENT") return "The requested file was not found.";
+  if (status === 500) return "The server could not complete the request.";
+  return error.message;
+}