mlx-bun 0.0.9 → 0.0.11

package/src/lora.ts

@@ -31,6 +31,12 @@ export interface AdapterInfo {
   /** Adapter tensors for modules outside the 7 target suffixes
    *  (per-layer-input projections etc.) — skipped, like the reference. */
   skippedTensors: number;
+  /** Actual resident bytes of this adapter's mounted lora_a/lora_b arrays
+   *  (sum of MlxArray.nbytes — the real RAM cost while mounted, not the
+   *  on-disk safetensors size). Web chat's adapter routing table (plan
+   *  §5.6/§9 Phase 2) shows this per loaded adapter instead of guessing
+   *  from file size. */
+  ramBytes: number;
 }
 
 /** Read every tensor from an adapter safetensors file (small, f32) into
@@ -266,6 +272,7 @@ export class AdapterManager {
       linear.loraState = this.#model.loraState;
     }
 
+    const ramBytes = validated.reduce((sum, { lw }) => sum + lw.a.nbytes + lw.b.nbytes, 0);
     const info: AdapterInfo = {
       id,
       path,
@@ -274,6 +281,7 @@ export class AdapterManager {
       sizeBytes: statSync(weightsFile).size,
       mountedLayers: validated.length,
       skippedTensors: skipped,
+      ramBytes,
     };
     this.#mounted.set(id, info);
     this.#arrays.set(id, validated.flatMap(({ lw }) => [lw.a, lw.b]));

package/src/md-modules.d.ts

@@ -5,3 +5,45 @@ declare module "*.md" {
   const content: string;
   export default content;
 }
+
+// Same deal for vendored text-imported assets under src/web/vendor/ (see
+// that dir's README) — served as raw strings via `with { type: "text" }`,
+// but bun-types has no ambient declaration for .js/.css read as text.
+// Scoped to the vendor path (not a blanket "*.js"/"*.css") so ordinary JS/CSS
+// module resolution elsewhere in the repo is untouched.
+declare module "./web/vendor/*.js" {
+  const content: string;
+  export default content;
+}
+declare module "./web/vendor/*.css" {
+  const content: string;
+  export default content;
+}
+
+// The frontend bundle (plan §7/§9 Phase 2 module split): GENERATED from
+// src/web/src/*.ts by scripts/build-web.ts into src/web/app.js, imported as
+// raw text in src/server.ts the same way as the vendored assets above.
+// Must stay a glob ("./web/*.js"), not the exact "./web/app.js" path — TS's
+// ambient-module resolution only matches the real on-disk src/web/app.js
+// against a wildcard pattern here, not an exact-path declaration (verified
+// 2026-07: an exact-path declare module silently failed to match while the
+// file existed, and "cannot find module" once it didn't — a TS quirk, not
+// intentional design; keep the glob if this ever needs revisiting).
+declare module "./web/*.js" {
+  const content: string;
+  export default content;
+}
+
+// PWA sources (plan §9 Phase 3): manifest.webmanifest + icon.svg,
+// text-imported into src/server.ts the same way. Globs, not exact paths —
+// the app.js comment above already found (2026-07) that TS's ambient
+// module resolution only matches a real on-disk file against a wildcard
+// pattern, not an exact-path declaration; same quirk applies here.
+declare module "./web/*.webmanifest" {
+  const content: string;
+  export default content;
+}
+declare module "./web/*.svg" {
+  const content: string;
+  export default content;
+}

package/src/media-fetch.ts

@@ -0,0 +1,284 @@
+// Remote media (image_url / audio_url) fetching with an SSRF/resource-
+// exhaustion policy. A chat request's URL is attacker-controlled input to
+// a server that may hold credentials for its LAN (the classic target:
+// cloud metadata at 169.254.169.254, router admin pages, other local
+// services), so by default the destination of every hop — the original
+// URL and each redirect — must be a public http(s) host, the whole fetch
+// is wall-clock bounded, and the response is size-capped.
+//
+// Escape hatch: `mlx-bun serve --allow-private-media` (or
+// MLX_BUN_ALLOW_PRIVATE_MEDIA=1) re-permits private/loopback/link-local
+// destinations — this is a local single-user server and pointing it at a
+// NAS or another LAN box is legitimate. Scheme/timeout/size limits still
+// apply.
+//
+// DNS names are resolved and every resolved address is checked before the
+// fetch. The fetch itself re-resolves, so a DNS-rebinding attacker who
+// controls TTLs can theoretically race the check — accepted for a local
+// single-user server (fixing it needs pinned-address dialing, which
+// bun's fetch doesn't expose).
+//
+// This module must stay free of mlx imports so tests/media-fetch.test.ts
+// runs model-free.
+
+import { lookup } from "node:dns/promises";
+
+export interface MediaFetchPolicy {
+  /** Permit private/loopback/link-local destinations (LAN hosts). */
+  allowPrivate: boolean;
+  /** Wall-clock budget for the whole fetch — every redirect hop plus the
+   *  body read share one AbortSignal.timeout. */
+  timeoutMs: number;
+  /** Response body cap in bytes (checked against Content-Length up front
+   *  AND while streaming, since the header is optional/spoofable). */
+  maxBytes: number;
+  maxRedirects: number;
+}
+
+export function defaultMediaFetchPolicy(): MediaFetchPolicy {
+  return {
+    allowPrivate: process.env.MLX_BUN_ALLOW_PRIVATE_MEDIA === "1",
+    // 10 s / 64 MB: well above what a 30 s audio clip (~5 MB of 16 kHz
+    // WAV, less compressed) or any supported image needs.
+    timeoutMs: 10_000,
+    maxBytes: 64 * 1024 * 1024,
+    maxRedirects: 5,
+  };
+}
+
+const PRIVATE_HINT =
+  "private/loopback hosts are blocked by default; start the server with " +
+  "--allow-private-media (or MLX_BUN_ALLOW_PRIVATE_MEDIA=1) to fetch from LAN hosts";
+
+function parseIpv4(s: string): number[] | null {
+  const parts = s.split(".");
+  if (parts.length !== 4) return null;
+  const out: number[] = [];
+  for (const p of parts) {
+    if (!/^\d{1,3}$/.test(p)) return null;
+    const n = Number(p);
+    if (n > 255) return null;
+    out.push(n);
+  }
+  return out;
+}
+
+function blockedIpv4(o: number[]): boolean {
+  const [a, b] = o as [number, number];
+  if (a === 0 || a === 10 || a === 127) return true; // this-net, 10/8, loopback
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64/10
+  if (a === 169 && b === 254) return true; // link-local (cloud metadata lives here)
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+  if (a === 192 && b === 168) return true; // 192.168/16
+  if (a >= 224) return true; // multicast + reserved + broadcast
+  return false;
+}
+
+/** Expand an IPv6 literal (with `::` compression, an optional zone index,
+ *  and an optional dotted-quad tail like ::ffff:127.0.0.1) into its 8
+ *  16-bit groups. null = not valid IPv6. */
+function parseIpv6(addr: string): number[] | null {
+  let s = addr;
+  const pct = s.indexOf("%");
+  if (pct !== -1) s = s.slice(0, pct);
+  if (s.includes(".")) {
+    // rewrite the dotted-quad tail as two hex groups
+    const i = s.lastIndexOf(":");
+    const v4 = parseIpv4(s.slice(i + 1));
+    if (!v4) return null;
+    s =
+      s.slice(0, i + 1) +
+      (((v4[0]! << 8) | v4[1]!).toString(16)) + ":" +
+      (((v4[2]! << 8) | v4[3]!).toString(16));
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const toGroups = (part: string): number[] | null => {
+    if (part === "") return [];
+    const out: number[] = [];
+    for (const g of part.split(":")) {
+      if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null;
+      out.push(parseInt(g, 16));
+    }
+    return out;
+  };
+  const head = toGroups(halves[0]!);
+  if (head === null) return null;
+  if (halves.length === 1) return head.length === 8 ? head : null;
+  const tail = toGroups(halves[1]!);
+  if (tail === null) return null;
+  if (head.length + tail.length > 7) return null;
+  return [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+}
+
+function blockedIpv6(g: number[]): boolean {
+  if (g.every((x) => x === 0)) return true; // :: unspecified
+  if (g.slice(0, 7).every((x) => x === 0) && g[7] === 1) return true; // ::1
+  if ((g[0]! & 0xffc0) === 0xfe80) return true; // link-local fe80::/10
+  if ((g[0]! & 0xfe00) === 0xfc00) return true; // ULA fc00::/7
+  if ((g[0]! & 0xff00) === 0xff00) return true; // multicast ff00::/8
+  // v4-mapped (::ffff:0:0/96) and NAT64 (64:ff9b::/96) embed an IPv4
+  // address in the low 32 bits — judge the embedded address.
+  const v4Embedded =
+    (g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff) ||
+    (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((x) => x === 0));
+  if (v4Embedded)
+    return blockedIpv4([g[6]! >> 8, g[6]! & 0xff, g[7]! >> 8, g[7]! & 0xff]);
+  return false;
+}
+
+/** True when `addr` is a private/loopback/link-local/reserved IP literal
+ *  — or unparseable as an IP at all (fail closed; callers only pass
+ *  things believed to be addresses). Accepts bracketed IPv6. */
+export function isBlockedAddress(addr: string): boolean {
+  let s = addr;
+  if (s.startsWith("[") && s.endsWith("]")) s = s.slice(1, -1);
+  const v4 = parseIpv4(s);
+  if (v4) return blockedIpv4(v4);
+  const v6 = parseIpv6(s);
+  if (v6) return blockedIpv6(v6);
+  return true;
+}
+
+/** Sync per-hop destination check: scheme + hostname-literal policy.
+ *  Returns a rejection reason or null. DNS names pass here and get their
+ *  resolved addresses checked in fetchMediaBytes (async). Exported pure
+ *  so the policy is testable without any network. */
+export function checkMediaUrl(u: URL, policy: MediaFetchPolicy): string | null {
+  if (u.protocol !== "http:" && u.protocol !== "https:")
+    return `unsupported url scheme "${u.protocol.replace(/:$/, "")}" (only http/https)`;
+  const host =
+    u.hostname.startsWith("[") && u.hostname.endsWith("]")
+      ? u.hostname.slice(1, -1)
+      : u.hostname;
+  if (!host) return "missing host";
+  if (policy.allowPrivate) return null;
+  const lower = host.toLowerCase();
+  if (lower === "localhost" || lower.endsWith(".localhost"))
+    return `destination "${host}" — ${PRIVATE_HINT}`;
+  // WHATWG URL parsing already canonicalized numeric IPv4 forms
+  // (http://2130706433/, http://0x7f000001/ → 127.0.0.1).
+  if (parseIpv4(lower) || parseIpv6(lower)) {
+    if (isBlockedAddress(lower)) return `destination "${host}" — ${PRIVATE_HINT}`;
+  }
+  return null;
+}
+
+async function assertResolvesPublic(
+  hostname: string,
+  kind: string,
+  policy: MediaFetchPolicy,
+): Promise<void> {
+  if (policy.allowPrivate) return;
+  const host =
+    hostname.startsWith("[") && hostname.endsWith("]")
+      ? hostname.slice(1, -1)
+      : hostname;
+  if (parseIpv4(host) || parseIpv6(host)) return; // literal — checked sync
+  let addrs: { address: string }[];
+  try {
+    addrs = await lookup(host, { all: true, verbatim: true });
+  } catch {
+    throw new Error(`${kind} fetch failed: could not resolve host "${host}"`);
+  }
+  for (const a of addrs) {
+    if (isBlockedAddress(a.address))
+      throw new Error(
+        `${kind} url rejected: host "${host}" resolves to ${a.address} — ${PRIVATE_HINT}`,
+      );
+  }
+}
+
+/** Fetch image/audio bytes for an OpenAI-style image_url/audio_url part.
+ *  data: URLs decode locally (no policy — the bytes came in the request);
+ *  http(s) URLs go through the destination policy above, with every
+ *  redirect hop re-validated, one wall-clock timeout, and a streaming
+ *  size cap. Throws Error with a client-presentable message — callers
+ *  surface it as a 400 (the prompt-build catch in server.ts). */
+export async function fetchMediaBytes(
+  url: string,
+  kind: "image" | "audio",
+  policy: MediaFetchPolicy = defaultMediaFetchPolicy(),
+): Promise<Uint8Array> {
+  if (url.startsWith("data:")) {
+    const comma = url.indexOf(",");
+    if (comma === -1) throw new Error("malformed data: URL");
+    const meta = url.slice(0, comma);
+    const body = url.slice(comma + 1);
+    if (!meta.includes("base64")) throw new Error("data: URL must be base64");
+    return Uint8Array.from(Buffer.from(body, "base64"));
+  }
+  let current: URL;
+  try {
+    current = new URL(url);
+  } catch {
+    throw new Error(`unsupported ${kind} url scheme: ${url.slice(0, 16)}`);
+  }
+  const capMb = Math.round(policy.maxBytes / (1024 * 1024));
+  const signal = AbortSignal.timeout(policy.timeoutMs);
+  let overCap = false;
+  try {
+    for (let hop = 0; ; hop++) {
+      const reason = checkMediaUrl(current, policy);
+      if (reason) throw new Error(`${kind} url rejected: ${reason}`);
+      await assertResolvesPublic(current.hostname, kind, policy);
+      const res = await fetch(current, { redirect: "manual", signal });
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers.get("location");
+        if (!loc)
+          throw new Error(`${kind} fetch failed: ${res.status} redirect without location`);
+        if (hop >= policy.maxRedirects)
+          throw new Error(`${kind} fetch failed: more than ${policy.maxRedirects} redirects`);
+        try {
+          await res.body?.cancel();
+        } catch {}
+        try {
+          current = new URL(loc, current);
+        } catch {
+          throw new Error(`${kind} fetch failed: malformed redirect location`);
+        }
+        continue;
+      }
+      if (!res.ok) throw new Error(`${kind} fetch failed: ${res.status} ${current}`);
+      const declared = Number(res.headers.get("content-length") ?? "0");
+      if (declared > policy.maxBytes) {
+        overCap = true;
+        try {
+          await res.body?.cancel();
+        } catch {}
+        throw new Error(`${kind} response exceeds the ${capMb} MB limit`);
+      }
+      if (!res.body) return new Uint8Array(await res.arrayBuffer());
+      // stream + count: Content-Length is optional (chunked) and spoofable
+      const reader = res.body.getReader();
+      const chunks: Uint8Array[] = [];
+      let total = 0;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > policy.maxBytes) {
+          overCap = true;
+          try {
+            await reader.cancel();
+          } catch {}
+          throw new Error(`${kind} response exceeds the ${capMb} MB limit`);
+        }
+        chunks.push(value);
+      }
+      const out = new Uint8Array(total);
+      let off = 0;
+      for (const c of chunks) {
+        out.set(c, off);
+        off += c.byteLength;
+      }
+      return out;
+    }
+  } catch (e) {
+    if (signal.aborted && !overCap)
+      throw new Error(
+        `${kind} fetch timed out after ${policy.timeoutMs} ms: ${url.slice(0, 200)}`,
+      );
+    throw e;
+  }
+}

package/src/memory/rest.ts

@@ -0,0 +1,245 @@
+// Memory REST wrappers — thin loopback JSON routes over src/memory/vault.ts
+// for the web chat's Memory panel (docs/design/web-chat-redesign.md §5.5,
+// §9 Phase 2). These are HTTP-only conveniences for the frontend: the
+// agent-tool surface (src/memory/tools.ts) stays read-only and unchanged,
+// and every route here is itself read-only except /init, which delegates to
+// the same `setupVault` the CLI's `mlx-bun memory init` calls (never
+// duplicated logic).
+//
+// Every handler returns a Response and never throws — a missing vault or a
+// bad param degrades to `{ ok: false, error }` (never a 500), matching the
+// rest of server.ts's /api/* conventions. Route dispatch (matching
+// url.pathname + method) lives in server.ts; this file is the pure handler
+// bodies so they're unit-testable without booting a model context (see
+// tests/memory-rest.test.ts).
+
+import { realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, resolve, sep } from "node:path";
+import {
+  vaultRoot, vaultStatus, listArticles, listReferenceDocs, readArticle,
+  searchArticles, getArticleLinks, resolveArticleRelPath, articleHistory, articleDiff,
+  setupVault, type VaultStatus,
+} from "./vault";
+import { parseInfobox, parseLead, parseSeriesBanner, articleStructure } from "./article";
+
+function jsonOk<T extends object>(body: T, init?: ResponseInit): Response {
+  return Response.json({ ok: true, ...body }, init);
+}
+
+function jsonErr(error: string, status = 400): Response {
+  return Response.json({ ok: false, error }, { status });
+}
+
+/** `{ ok:false, enabled:false }` shape shared by every route when no vault
+ *  exists yet — never a throw, never a 404: the frontend uses this to
+ *  render the first-run consent card instead of an error toast. */
+function noVault(root: string): Response {
+  return Response.json({ ok: false, enabled: false, error: "no memory vault yet", root });
+}
+
+// ---- GET /api/memory/status -------------------------------------------
+
+export async function handleMemoryStatus(): Promise<Response> {
+  const st = await vaultStatus();
+  if (!st.exists) return noVault(st.root);
+  return jsonOk({ enabled: true, status: st satisfies VaultStatus });
+}
+
+// ---- GET /api/memory/list ----------------------------------------------
+
+export async function handleMemoryList(): Promise<Response> {
+  const root = vaultRoot();
+  const st = await vaultStatus(root);
+  if (!st.exists) return noVault(root);
+  const [articles, reference] = await Promise.all([listArticles(root), listReferenceDocs(root)]);
+  return jsonOk({ articles, reference });
+}
+
+// ---- GET /api/memory/search?q=&scope= -----------------------------------
+
+export async function handleMemorySearch(url: URL): Promise<Response> {
+  const root = vaultRoot();
+  const st = await vaultStatus(root);
+  if (!st.exists) return noVault(root);
+  const q = (url.searchParams.get("q") ?? "").trim();
+  if (!q) return jsonErr("q is required");
+  const scopeParam = url.searchParams.get("scope");
+  const scope = scopeParam === "articles" || scopeParam === "reference" ? scopeParam : "all";
+  const limitParam = Number(url.searchParams.get("limit") ?? "50");
+  const limit = Number.isFinite(limitParam) && limitParam > 0 ? Math.min(limitParam, 200) : 50;
+  try {
+    const { summaries, hits } = await searchArticles(root, q, { limit, scope });
+    return jsonOk({ summaries, hits });
+  } catch (e) {
+    return jsonErr((e as Error).message);
+  }
+}
+
+// ---- GET /api/memory/article?name= --------------------------------------
+//
+// Rendered source + metadata: the article's raw Markdown plus the
+// deterministic structure the panel needs to render it without re-parsing
+// client-side (infobox, lead, series banner, section skeleton).
+
+export async function handleMemoryArticle(url: URL): Promise<Response> {
+  const root = vaultRoot();
+  const st = await vaultStatus(root);
+  if (!st.exists) return noVault(root);
+  const name = (url.searchParams.get("name") ?? "").trim();
+  if (!name) return jsonErr("name is required");
+  try {
+    const { path, content } = await readArticle(root, name);
+    return jsonOk({
+      name,
+      path,
+      content,
+      infobox: parseInfobox(content),
+      lead: parseLead(content),
+      series: parseSeriesBanner(content),
+      structure: articleStructure(content),
+    });
+  } catch (e) {
+    return jsonErr((e as Error).message, 404);
+  }
+}
+
+// ---- GET /api/memory/links?name= -----------------------------------------
+
+export async function handleMemoryLinks(url: URL): Promise<Response> {
+  const root = vaultRoot();
+  const st = await vaultStatus(root);
+  if (!st.exists) return noVault(root);
+  const name = (url.searchParams.get("name") ?? "").trim();
+  if (!name) return jsonErr("name is required");
+  try {
+    const links = await getArticleLinks(root, name);
+    return jsonOk({ name, ...links });
+  } catch (e) {
+    return jsonErr((e as Error).message, 404);
+  }
+}
+
+// ---- GET /api/memory/history?name= ---------------------------------------
+
+export async function handleMemoryHistory(url: URL): Promise<Response> {
+  const root = vaultRoot();
+  const st = await vaultStatus(root);
+  if (!st.exists) return noVault(root);
+  const name = (url.searchParams.get("name") ?? "").trim();
+  if (!name) return jsonErr("name is required");
+  const limitParam = Number(url.searchParams.get("limit") ?? "50");
+  const limit = Number.isFinite(limitParam) && limitParam > 0 ? Math.min(limitParam, 200) : 50;
+  try {
+    const relPath = await resolveArticleRelPath(root, name); // throws if not found — validates `name`
+    const entries = await articleHistory(root, relPath, limit);
+    return jsonOk({ name, isGitRepo: st.isGitRepo, entries });
+  } catch (e) {
+    return jsonErr((e as Error).message, 404);
+  }
+}
+
+// ---- GET /api/memory/diff?name=&rev= -------------------------------------
+
+/** Full 40-hex or an abbreviated (≥4 hex) commit hash — never a ref
+ *  expression (`HEAD~1`, `main^`, `refs/...`), which could otherwise be
+ *  abused to walk outside the intended commit or (in principle) smuggle
+ *  option-like text into the argv. `rev` is passed to Bun.spawn as its own
+ *  argv element (never through a shell), but this check is the defense
+ *  against a caller trying to pass anything other than a bare commit id. */
+const REV_RE = /^[0-9a-f]{4,40}$/;
+
+export async function handleMemoryDiff(url: URL): Promise<Response> {
+  const root = vaultRoot();
+  const st = await vaultStatus(root);
+  if (!st.exists) return noVault(root);
+  const name = (url.searchParams.get("name") ?? "").trim();
+  const rev = (url.searchParams.get("rev") ?? "").trim();
+  if (!name) return jsonErr("name is required");
+  if (!rev) return jsonErr("rev is required");
+  if (!REV_RE.test(rev)) return jsonErr("rev must be a commit hash (4-40 hex chars)");
+  try {
+    const relPath = await resolveArticleRelPath(root, name); // throws if not found — validates `name`
+    const diff = await articleDiff(root, rev, relPath);
+    if (diff === null) return jsonErr("commit not found or no diff for this article at that revision", 404);
+    return jsonOk({ name, rev, diff });
+  } catch (e) {
+    return jsonErr((e as Error).message, 404);
+  }
+}
+
+// ---- POST /api/memory/init { path?: string } -----------------------------
+//
+// The consent-card backend: wraps the exact same `setupVault` the CLI's
+// `mlx-bun memory init` calls (src/cli.ts, `case "memory":` → `sub === "init"`)
+// — same idempotent create-dirs/README/Meta-pages/git-init behavior, minus
+// the CLI's interactive extras (seed-from-existing-vault prompt, nightly
+// schedule prompt), which stay CLI-only/TTY-gated and are out of scope here.
+//
+// Unlike the CLI (which only ever calls setupVault(vaultRoot()) — a
+// user-supplied path there is a read-only *seed source*, never the
+// setupVault target), this route takes `path` straight from an untrusted
+// loopback caller. setupVault() mkdir -p's subdirectories into it and, if
+// it isn't already a git repo, runs `git init && git add . && git commit`
+// there — pointed at an arbitrary directory that's a destructive foot-gun
+// (force-commits whatever's already there into a fresh history). There is
+// no product reason for the web panel to redirect the vault root outside
+// the machine's own tmp/vault trees, so `path` is confined to those before
+// it ever reaches setupVault; anything else 400s instead of writing files.
+
+/** realpath() of the deepest existing ancestor of `path`, with the
+ *  non-existent tail (e.g. a not-yet-created vault dir) re-appended
+ *  literally. Needed because macOS resolves `/var/folders/...` (os.tmpdir())
+ *  through a `/private` symlink: a brand-new mkdtemp path under it won't
+ *  literal-prefix-match the realpath'd tmpdir unless we walk up to a real
+ *  segment the same way. */
+async function realpathNearest(path: string): Promise<string> {
+  let cur = resolve(path);
+  const tail: string[] = [];
+  while (true) {
+    try {
+      return [await realpath(cur), ...tail.reverse()].join(sep);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return resolve(path); // hit the fs root without finding anything real
+      tail.push(cur.slice(parent.length + 1));
+      cur = parent;
+    }
+  }
+}
+
+/** Is `candidate` equal to or a descendant of `ancestor`, after resolving
+ *  symlinks on both sides? */
+async function isUnder(candidate: string, ancestor: string): Promise<boolean> {
+  const realAncestor = await realpathNearest(ancestor);
+  const realCandidate = await realpathNearest(candidate);
+  return realCandidate === realAncestor || realCandidate.startsWith(realAncestor + sep);
+}
+
+/** Confine an init target to the machine's own vault/tmp trees — the only
+ *  legitimate destinations for this route (default vault root, or a tmp dir
+ *  for tests). Rejects anything else rather than handing setupVault() an
+ *  arbitrary, possibly pre-existing directory to mkdir/git-init into. */
+async function isAllowedVaultTarget(path: string): Promise<boolean> {
+  return (await isUnder(path, vaultRoot())) || (await isUnder(path, tmpdir()));
+}
+
+export async function handleMemoryInit(request: Request): Promise<Response> {
+  let body: { path?: string } = {};
+  try {
+    body = (await request.json()) as { path?: string };
+  } catch {
+    // empty body is fine — defaults to vaultRoot()
+  }
+  const root = body.path && body.path.trim() ? body.path.trim() : vaultRoot();
+  if (!(await isAllowedVaultTarget(root))) {
+    return jsonErr("path must be under the memory vault root or a temp directory", 400);
+  }
+  try {
+    const res = await setupVault(root);
+    const st = await vaultStatus(res.root);
+    return jsonOk({ result: res, status: st });
+  } catch (e) {
+    return jsonErr((e as Error).message, 500);
+  }
+}