codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/pairing-server.js

@@ -0,0 +1,323 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pairing_server_exports = {};
+__export(pairing_server_exports, {
+  deriveConfirmationCode: () => import_peer_auth.deriveConfirmationCode,
+  getAllAddresses: () => getAllAddresses,
+  isPairingServerActive: () => isPairingServerActive,
+  startPairingServer: () => startPairingServer,
+  stopPairingServer: () => stopPairingServer
+});
+module.exports = __toCommonJS(pairing_server_exports);
+var import_node_http = __toESM(require("node:http"));
+var import_node_os = __toESM(require("node:os"));
+var import_node_crypto = require("node:crypto");
+var import_peer_auth = require("./peer-auth");
+var import_sdp_fingerprint = require("../../shared/lib/sdp-fingerprint");
+var import_sdp_minimal = require("../../shared/lib/sdp-minimal");
+var import_peer_auth2 = require("./peer-auth");
+const PAIRING_TIMEOUT_MS = 6e4;
+const CODE_LENGTH = 6;
+const NONCE_BYTES = 16;
+const MAX_BODY_BYTES = 256 * 1024;
+const SOCKET_TIMEOUT_MS = 15e3;
+const MAX_CODE_ATTEMPTS = 5;
+let activeServer = null;
+let activeTimeout = null;
+function startPairingServer(opts) {
+  stopPairingServer();
+  const code = generateCode();
+  const nonce = (0, import_node_crypto.randomBytes)(NONCE_BYTES).toString("hex");
+  const pairingId = (0, import_node_crypto.randomUUID)();
+  const sharedSecret = (0, import_peer_auth.generateSharedSecret)();
+  const sdpParams = (0, import_sdp_minimal.extractSdpParams)(opts.offerSdp, opts.iceCandidates);
+  return new Promise((resolveStart, rejectStart) => {
+    let answerResolve = null;
+    let answerReject = null;
+    let answered = false;
+    let codeAttempts = 0;
+    let offerClaimedBy = null;
+    const answerPromise = new Promise((res, rej) => {
+      answerResolve = res;
+      answerReject = rej;
+    });
+    const noteBadCode = () => {
+      codeAttempts += 1;
+      if (codeAttempts >= MAX_CODE_ATTEMPTS) {
+        console.warn(`[PairingServer] ${codeAttempts} wrong pairing codes \u2014 closing the window`);
+        answerReject?.(new Error("Too many incorrect pairing codes"));
+        stopThis();
+      }
+    };
+    const readBody = (req) => new Promise((resolve, reject) => {
+      let body = "";
+      let size = 0;
+      req.on("data", (chunk) => {
+        size += Buffer.byteLength(chunk);
+        if (size > MAX_BODY_BYTES) {
+          reject(new Error("Request body too large"));
+          req.destroy();
+          return;
+        }
+        body += chunk;
+      });
+      req.on("end", () => resolve(body));
+      req.on("error", reject);
+    });
+    const stopThis = () => {
+      if (activeServer === server) {
+        stopPairingServer();
+        return;
+      }
+      try {
+        server.closeAllConnections?.();
+        server.close();
+      } catch {
+      }
+    };
+    const server = import_node_http.default.createServer((req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+      if (req.method === "POST" && url.pathname === "/offer") {
+        readBody(req).then((body) => {
+          let data;
+          try {
+            data = JSON.parse(body);
+          } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid JSON" }));
+            return;
+          }
+          if (data.c !== code) {
+            noteBadCode();
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid pairing code" }));
+            return;
+          }
+          const source = req.socket.remoteAddress ?? "unknown";
+          if (offerClaimedBy !== null && offerClaimedBy !== source) {
+            res.writeHead(409, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Offer already claimed" }));
+            return;
+          }
+          offerClaimedBy = source;
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            offer: opts.offerSdp,
+            ice: opts.iceCandidates,
+            fingerprint: opts.fingerprint,
+            nonce,
+            pairingId
+          }));
+        }).catch((err) => {
+          console.warn(`[PairingServer] Rejected offer request: ${err.message}`);
+          if (!res.headersSent) {
+            res.writeHead(413, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Request body too large" }));
+          }
+        });
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/answer") {
+        readBody(req).then((body) => {
+          let data;
+          try {
+            data = JSON.parse(body);
+          } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid JSON" }));
+            return;
+          }
+          if (typeof data.fingerprint !== "string" || typeof data.mac !== "string") {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Missing fingerprint or mac" }));
+            return;
+          }
+          if (!(0, import_peer_auth2.macsEqual)((0, import_peer_auth2.computeAnswerMac)(code, nonce, data.fingerprint), data.mac)) {
+            noteBadCode();
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid pairing code" }));
+            return;
+          }
+          if (data.nonce !== nonce) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Nonce mismatch" }));
+            return;
+          }
+          if (typeof data.answer !== "string" || typeof data.fingerprint !== "string") {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Missing answer or fingerprint" }));
+            return;
+          }
+          if (answered) {
+            res.writeHead(409, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Already answered" }));
+            return;
+          }
+          const source = req.socket.remoteAddress ?? "unknown";
+          if (offerClaimedBy !== null && source !== offerClaimedBy) {
+            console.warn(`[PairingServer] Rejected answer from ${source} \u2014 the offer was claimed by another client`);
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not the client that requested the offer" }));
+            return;
+          }
+          let sdpFingerprint;
+          try {
+            sdpFingerprint = (0, import_sdp_fingerprint.extractSingleFingerprint)(data.answer);
+          } catch (err) {
+            console.warn(`[PairingServer] Rejected answer \u2014 unusable SDP: ${err.message}`);
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Answer SDP does not commit to a single certificate" }));
+            return;
+          }
+          if (!(0, import_sdp_fingerprint.fingerprintsEqual)(sdpFingerprint, data.fingerprint)) {
+            console.warn("[PairingServer] Rejected answer \u2014 claimed fingerprint disagrees with the SDP");
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Claimed fingerprint does not match the answer SDP" }));
+            return;
+          }
+          answered = true;
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ accepted: true, pairingId }));
+          if (activeTimeout) {
+            clearTimeout(activeTimeout);
+            activeTimeout = null;
+          }
+          const answer = {
+            answerSdp: data.answer,
+            iceCandidates: Array.isArray(data.ice) ? data.ice : [],
+            fingerprint: sdpFingerprint,
+            nonce: String(data.nonce),
+            pairingId
+          };
+          answerResolve?.(answer);
+          setTimeout(stopThis, 500);
+        }).catch((err) => {
+          console.warn(`[PairingServer] Rejected answer body: ${err.message}`);
+          if (!res.headersSent) {
+            res.writeHead(413, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Request body too large" }));
+          }
+        });
+        return;
+      }
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+    });
+    server.setTimeout(SOCKET_TIMEOUT_MS, (socket) => socket.destroy());
+    server.headersTimeout = SOCKET_TIMEOUT_MS;
+    server.requestTimeout = SOCKET_TIMEOUT_MS;
+    server.on("error", (err) => {
+      console.error("[PairingServer] Error:", err);
+      rejectStart(err);
+    });
+    server.listen(0, "0.0.0.0", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        rejectStart(new Error("Failed to get server address"));
+        return;
+      }
+      activeServer = server;
+      const port = addr.port;
+      const addresses = getAllAddresses();
+      const lanAddress = addresses[0] ?? "127.0.0.1";
+      console.log(`[PairingServer] Listening on ${addresses.join(", ") || lanAddress}:${port} (code=${code})`);
+      activeTimeout = setTimeout(() => {
+        if (!answered) {
+          console.log("[PairingServer] Timed out after 60s");
+          answerReject?.(new Error("Pairing timed out"));
+        }
+        stopPairingServer();
+      }, PAIRING_TIMEOUT_MS);
+      resolveStart({
+        code,
+        address: lanAddress,
+        addresses,
+        port,
+        nonce,
+        pairingId,
+        sdpParams,
+        sharedSecret,
+        waitForAnswer: () => answerPromise,
+        stop: stopThis
+      });
+    });
+  });
+}
+function stopPairingServer() {
+  if (activeTimeout) {
+    clearTimeout(activeTimeout);
+    activeTimeout = null;
+  }
+  if (activeServer) {
+    try {
+      activeServer.closeAllConnections?.();
+      activeServer.close();
+    } catch {
+    }
+    activeServer = null;
+    console.log("[PairingServer] Stopped");
+  }
+}
+function isPairingServerActive() {
+  return activeServer !== null;
+}
+function generateCode() {
+  const num = (0, import_node_crypto.randomBytes)(4).readUInt32BE(0) % 1e6;
+  return num.toString().padStart(CODE_LENGTH, "0");
+}
+function getAllAddresses() {
+  const out = [];
+  const interfaces = import_node_os.default.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const addr of interfaces[name] ?? []) {
+      if (addr.family === "IPv4" && !addr.internal) out.push(addr.address);
+    }
+  }
+  const rank = (ip) => {
+    if (/^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)) return 0;
+    if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip)) return 1;
+    return 2;
+  };
+  return out.sort((a, b) => rank(a) - rank(b));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deriveConfirmationCode,
+  getAllAddresses,
+  isPairingServerActive,
+  startPairingServer,
+  stopPairingServer
+});

package/src/backend/services/pairing-service.js

@@ -0,0 +1,200 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pairing_service_exports = {};
+__export(pairing_service_exports, {
+  cancelPairing: () => cancelPairing,
+  confirmPairing: () => confirmPairing,
+  getConfirmationCode: () => getConfirmationCode,
+  getDesktopFingerprint: () => getDesktopFingerprint,
+  getPairingId: () => getPairingId,
+  getPairingNonce: () => getPairingNonce,
+  getStoredAnswer: () => getStoredAnswer,
+  getStoredOfferSdp: () => getStoredOfferSdp,
+  initiatePairing: () => initiatePairing,
+  isPairingActive: () => isPairingActive
+});
+module.exports = __toCommonJS(pairing_service_exports);
+var import_pairing_server = require("./pairing-server");
+var import_paired_device_service = require("./paired-device-service");
+var import_sdp_minimal = require("../../shared/lib/sdp-minimal");
+var import_webrtc_service = require("./webrtc-service");
+var import_types = require("../../shared/types");
+var import_peer_capabilities = require("./peer-capabilities");
+let activePairing = null;
+async function initiatePairing(offerSdp, iceCandidates, fingerprint) {
+  cancelPairing();
+  const server = await (0, import_pairing_server.startPairingServer)({
+    offerSdp,
+    iceCandidates,
+    fingerprint
+  });
+  const qrPayload = {
+    v: 5,
+    hs: server.addresses,
+    // every reachable host — LAN and VPN alike
+    p: server.port,
+    c: server.code,
+    iu: server.sdpParams.iu,
+    ip: server.sdpParams.ip,
+    fp: (0, import_sdp_minimal.stripColonFingerprint)(server.sdpParams.fp),
+    cp: server.sdpParams.candidatePort,
+    mms: server.sdpParams.maxMessageSize,
+    n: server.nonce
+  };
+  console.log(
+    `[Pairing] v5 initiated \u2014 code=${server.code} addr=${server.address}:${server.port} qr=${JSON.stringify(qrPayload).length}B`
+  );
+  activePairing = {
+    server,
+    desktopFingerprint: fingerprint,
+    offerSdp,
+    answer: null,
+    confirmCode: null,
+    sharedSecret: server.sharedSecret
+  };
+  const wrappedWait = async () => {
+    const answer = await server.waitForAnswer();
+    if (activePairing) {
+      activePairing.answer = answer;
+      activePairing.confirmCode = (0, import_pairing_server.deriveConfirmationCode)(
+        server.nonce,
+        fingerprint,
+        answer.fingerprint
+      );
+    }
+    return answer;
+  };
+  return {
+    qrPayload,
+    offerSdp,
+    waitForAnswer: wrappedWait
+  };
+}
+function getConfirmationCode() {
+  return activePairing?.confirmCode ?? null;
+}
+function getStoredOfferSdp() {
+  return activePairing?.offerSdp ?? null;
+}
+function getStoredAnswer() {
+  return activePairing?.answer ?? null;
+}
+function getDesktopFingerprint() {
+  return activePairing?.desktopFingerprint ?? null;
+}
+function getPairingNonce() {
+  return activePairing?.server.nonce ?? null;
+}
+function getPairingId() {
+  return activePairing?.server.pairingId ?? null;
+}
+function confirmPairing(userCode, deviceAlias, deviceType) {
+  if (!activePairing?.answer || !activePairing.confirmCode) {
+    console.warn("[Pairing] No answer received yet \u2014 cannot confirm");
+    return null;
+  }
+  if (userCode !== activePairing.confirmCode) {
+    console.warn("[Pairing] Confirmation code mismatch");
+    return null;
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const device = {
+    fingerprint: activePairing.answer.fingerprint,
+    pairingId: activePairing.server.pairingId,
+    alias: deviceAlias,
+    deviceType,
+    pairedAt: now,
+    lastConnected: null,
+    // A REAL SECRET, not the `''` with a `// TODO` beside it that every record
+    // used to carry (Phase 19, finding 1.2). Reconnect now requires a proof
+    // computed with this; a `pairingId` on its own no longer gets in.
+    sharedSecret: activePairing.sharedSecret,
+    instanceId: null,
+    // Pairing a phone does not hand it a shell or the settings that control
+    // network exposure — those are granted per device, afterwards (finding 17).
+    capabilities: [...import_peer_capabilities.DEFAULT_GRANTS],
+    confirmedAt: now
+  };
+  (0, import_paired_device_service.upsertPairedDevice)(device);
+  console.log(`[Pairing] Confirmed \u2014 device "${deviceAlias}" (${device.fingerprint.slice(0, 12)}\u2026)`);
+  deliverPairingSecret(device);
+  activePairing = null;
+  return device;
+}
+const SECRET_DELIVERY_WINDOW_MS = 6e4;
+function deliverPairingSecret(device) {
+  const payload = JSON.stringify({
+    type: "pairing.secret",
+    pairingId: device.pairingId,
+    secret: device.sharedSecret
+  });
+  if ((0, import_webrtc_service.sendToPeer)(device.fingerprint, import_types.DATA_CHANNELS.CONTROL, payload)) {
+    console.log(`[Pairing] Delivered the reconnect secret to "${device.alias}"`);
+    (0, import_paired_device_service.touchPairedDevice)(device.fingerprint);
+    return;
+  }
+  console.log(`[Pairing] Control channel not open yet \u2014 will hand "${device.alias}" its secret when it is`);
+  let settled = false;
+  const finish = (ok) => {
+    if (settled) return;
+    settled = true;
+    unsubscribe();
+    clearTimeout(timer);
+    if (ok) {
+      console.log(`[Pairing] Delivered the reconnect secret to "${device.alias}"`);
+      (0, import_paired_device_service.touchPairedDevice)(device.fingerprint);
+    } else {
+      console.warn(
+        `[Pairing] Never managed to deliver the reconnect secret to "${device.alias}" \u2014 that device will have to pair again.`
+      );
+    }
+  };
+  const unsubscribe = (0, import_webrtc_service.onConnectionStateChange)((fingerprint, state) => {
+    if (fingerprint !== device.fingerprint || state !== "connected") return;
+    if ((0, import_webrtc_service.sendToPeer)(device.fingerprint, import_types.DATA_CHANNELS.CONTROL, payload)) finish(true);
+  });
+  const timer = setTimeout(() => finish(false), SECRET_DELIVERY_WINDOW_MS);
+  if (typeof timer === "object" && timer && "unref" in timer) {
+    timer.unref();
+  }
+}
+function cancelPairing() {
+  if (activePairing) {
+    activePairing.server.stop();
+    activePairing = null;
+    console.log("[Pairing] Cancelled");
+  } else {
+    (0, import_pairing_server.stopPairingServer)();
+  }
+}
+function isPairingActive() {
+  return activePairing !== null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cancelPairing,
+  confirmPairing,
+  getConfirmationCode,
+  getDesktopFingerprint,
+  getPairingId,
+  getPairingNonce,
+  getStoredAnswer,
+  getStoredOfferSdp,
+  initiatePairing,
+  isPairingActive
+});

package/src/backend/services/pantry-resolution-service.js

@@ -0,0 +1,166 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pantry_resolution_service_exports = {};
+__export(pantry_resolution_service_exports, {
+  resolveReference: () => resolveReference,
+  resolveReferences: () => resolveReferences,
+  scanPlanReferences: () => scanPlanReferences
+});
+module.exports = __toCommonJS(pantry_resolution_service_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_confined_fs = require("./confined-fs");
+var import_trusted_roots = require("./trusted-roots");
+var import_node_os = __toESM(require("node:os"));
+var import_node_path = __toESM(require("node:path"));
+var import_plans_home = require("./plans-home");
+function resolveReferences(references, projectRoot) {
+  return references.map((ref) => resolveReference(ref, projectRoot));
+}
+function resolveReference(reference, projectRoot) {
+  if (!reference || typeof reference !== "string") {
+    return { reference, status: "external", reason: "Invalid reference" };
+  }
+  if (reference.startsWith("http://") || reference.startsWith("https://")) {
+    return { reference, status: "resolved" };
+  }
+  if (reference.startsWith("userdata://")) {
+    const userDataDir = process.env.CODETRELLIS_DATA_DIR ?? import_node_path.default.join(import_node_os.default.homedir(), ".codetrellis");
+    const rel = reference.replace(/^userdata:\/\//, "");
+    const absPath = import_node_path.default.resolve(userDataDir, rel);
+    if (!absPath.startsWith(import_node_path.default.resolve(userDataDir) + import_node_path.default.sep)) {
+      return { reference, status: "external", reason: "Invalid path traversal" };
+    }
+    if (import_node_fs.default.existsSync(absPath)) {
+      return { reference, status: "resolved", absolutePath: absPath };
+    }
+    return {
+      reference,
+      status: "external",
+      reason: "User-local content \u2014 not available outside the original workspace"
+    };
+  }
+  if (!import_node_path.default.isAbsolute(reference)) {
+    const absPath = import_node_path.default.resolve(projectRoot, reference);
+    const normRoot = import_node_path.default.resolve(projectRoot);
+    if (!absPath.startsWith(normRoot + import_node_path.default.sep) && absPath !== normRoot) {
+      return { reference, status: "external", reason: "Invalid path traversal" };
+    }
+    if (import_node_fs.default.existsSync(absPath)) {
+      return { reference, status: "resolved", absolutePath: absPath };
+    }
+    return {
+      reference,
+      status: "external",
+      reason: "Team-only content \u2014 request access from the item author"
+    };
+  }
+  const owningRoot = (0, import_trusted_roots.listTrustedRoots)().find((r) => (0, import_confined_fs.isWithin)(r, reference));
+  if (owningRoot) {
+    if (import_node_fs.default.existsSync(reference)) {
+      return { reference, status: "resolved", absolutePath: reference };
+    }
+  }
+  return {
+    reference,
+    status: "external",
+    reason: "Referenced file is not part of an open project on this machine"
+  };
+}
+function scanPlanReferences(projectRoot, planSlug) {
+  projectRoot = (0, import_plans_home.plansHome)(projectRoot) ?? projectRoot;
+  const planDir = import_node_path.default.join(projectRoot, ".codetrellis", "plans", planSlug);
+  if (!import_node_fs.default.existsSync(planDir)) {
+    return { total: 0, resolved: 0, external: 0, externals: [] };
+  }
+  const references = extractReferencesFromDir(planDir);
+  const resolutions = resolveReferences(references, projectRoot);
+  const externals = resolutions.filter((r) => r.status === "external");
+  return {
+    total: resolutions.length,
+    resolved: resolutions.length - externals.length,
+    external: externals.length,
+    externals
+  };
+}
+function extractReferencesFromDir(dir) {
+  const refs = [];
+  let entries;
+  try {
+    entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return refs;
+  }
+  for (const entry of entries) {
+    const fullPath = import_node_path.default.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      refs.push(...extractReferencesFromDir(fullPath));
+    } else if (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml")) {
+      refs.push(...extractReferencesFromYaml(fullPath));
+    }
+  }
+  return refs;
+}
+function extractReferencesFromYaml(filePath) {
+  const refs = [];
+  let content;
+  try {
+    content = import_node_fs.default.readFileSync(filePath, "utf-8");
+  } catch {
+    return refs;
+  }
+  const lines = content.split("\n");
+  let inAttachments = false;
+  let attachmentsIndent = -1;
+  for (const line of lines) {
+    const attMatch = line.match(/^(\s*)attachments:\s*$/);
+    if (attMatch) {
+      inAttachments = true;
+      attachmentsIndent = attMatch[1].length;
+      continue;
+    }
+    if (inAttachments) {
+      if (line.trim() && !line.startsWith(" ".repeat(attachmentsIndent + 1))) {
+        inAttachments = false;
+        attachmentsIndent = -1;
+        continue;
+      }
+      const valMatch = line.match(/^\s+value:\s*["']?([^"'\n]+)["']?\s*$/);
+      if (valMatch) {
+        const val = valMatch[1].trim();
+        if (val) refs.push(val);
+      }
+    }
+  }
+  return refs;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveReference,
+  resolveReferences,
+  scanPlanReferences
+});