@valbuild/server 0.136.9 → 0.137.0

package/dist/valbuild-server.cjs.prod.js

@@ -14,12 +14,15 @@ var internal = require('@valbuild/shared/internal');
 var server = require('@valbuild/ui/server');
 var crypto$1 = require('crypto');
 var z = require('zod');
+var http = require('node:http');
+var https = require('node:https');
+var net = require('node:net');
 var sizeOf = require('image-size');
 var zodValidationError = require('zod-validation-error');
 var os = require('os');
 var sucrase = require('sucrase');
-var http = require('http');
-var https = require('https');
+var http$1 = require('http');
+var https$1 = require('https');
 var fs$1 = require('fs/promises');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
@@ -48,10 +51,13 @@ var fs__default = /*#__PURE__*/_interopDefault(fs);
 var vm__default = /*#__PURE__*/_interopDefault(vm);
 var crypto__default = /*#__PURE__*/_interopDefault(crypto$1);
 var z__default = /*#__PURE__*/_interopDefault(z);
-var sizeOf__default = /*#__PURE__*/_interopDefault(sizeOf);
-var os__default = /*#__PURE__*/_interopDefault(os);
 var http__default = /*#__PURE__*/_interopDefault(http);
 var https__default = /*#__PURE__*/_interopDefault(https);
+var net__default = /*#__PURE__*/_interopDefault(net);
+var sizeOf__default = /*#__PURE__*/_interopDefault(sizeOf);
+var os__default = /*#__PURE__*/_interopDefault(os);
+var http__default$1 = /*#__PURE__*/_interopDefault(http$1);
+var https__default$1 = /*#__PURE__*/_interopDefault(https$1);
 var fs__default$1 = /*#__PURE__*/_interopDefault(fs$1);
 
 class ValSyntaxError {
@@ -2599,6 +2605,572 @@ function encodeJwt(payload, sessionKey) {
   return `${jwtHeaderBase64}.${payloadBase64}.${crypto__default["default"].createHmac("sha256", sessionKey).update(`${jwtHeaderBase64}.${payloadBase64}`).digest("base64")}`;
 }
 
+/**
+ * Just the part of `ValServerConfig` this decision needs.
+ *
+ * Narrower than the whole thing on purpose: a `ValServerConfig` carries the api
+ * key, the secret and the content URLs, and a function that took one would look
+ * like it might consult them. It also makes this testable with an object
+ * literal rather than a cast.
+ */
+
+/**
+ * The `val.config` the Studio is told about, which is not quite the one on disk.
+ *
+ * `gitBranch` is optional in `val.config`, and a proxy-mode server that mirrors
+ * into a repository usually knows the branch when the file does not: setting it
+ * in the environment is how a Vercel deployment does it
+ * (`VERCEL_GIT_COMMIT_REF`), and the example app does not set it at all.
+ *
+ * Git is OPTIONAL in http mode — a project can run on credentials alone, with
+ * no repository to mirror into — so "http" no longer implies a branch exists.
+ * That changed under this function rather than being designed into it: the
+ * original said proxy mode "refuses to start without `VAL_GIT_BRANCH`", which
+ * was true when it was written and is not any more. With no mirror there is
+ * nothing to fill in and nothing to say, which is the same answer fs mode gets.
+ *
+ * The Studio reads `config.gitBranch` and nothing else, so without this a
+ * correctly configured project gets a History pane reading "this project has no
+ * gitBranch configured" while the server behind it is busy committing to one,
+ * and a status bar with no branch on it.
+ *
+ * Narrow on purpose:
+ *
+ * - **`val.config` wins.** A branch named in the file is the author's answer,
+ *   and the environment's is the fallback.
+ * - **Every other mode is left alone.** Neither `fs` nor `memory` has a branch:
+ *   `ValOpsFS` has no commits of its own, and a memory host holds its own
+ *   source and never had any. Nor does an http project with no git mirror. The
+ *   shell hides what needs a branch rather than being handed a name that means
+ *   nothing.
+ *
+ * The modes are enumerated rather than written as "http, or anything else", and
+ * that is worth keeping: `memory` arrived after this function did, and spelling
+ * every mode out is what turned "does this one have a branch?" into a compile
+ * error somebody had to answer instead of a default that silently applied.
+ */
+function clientConfig(options) {
+  if (options.mode !== "http" || options.git === undefined) {
+    return options.config;
+  }
+  if (options.config.gitBranch !== undefined) {
+    return options.config;
+  }
+  return {
+    ...options.config,
+    gitBranch: options.git.branch
+  };
+}
+
+/**
+ * Which IP addresses this server may open a connection to.
+ *
+ * The link check makes outbound requests to addresses an editor supplies,
+ * which is the definition of SSRF: without this, "check my external links"
+ * is a button that turns the app's server into a probe for whatever is
+ * reachable from inside the network it runs in - a database on a private
+ * subnet, an admin panel on localhost, and on every major cloud the instance
+ * metadata service on 169.254.169.254, which hands out credentials.
+ *
+ * So the rule is a DENY LIST of address ranges rather than an allow list of
+ * hostnames: an editor is allowed to check any real site on the internet, and
+ * nothing else. It is applied to the RESOLVED address, in the lookup the
+ * socket then connects to - a public name is free to resolve to 127.0.0.1,
+ * and checking the name would catch none of it.
+ */
+
+/** Why an address may not be connected to. Reported, not just counted. */
+
+const REASON_TEXT = {
+  unspecified: "an unspecified address",
+  loopback: "a loopback address",
+  private: "a private address",
+  "link-local": "a link-local address",
+  "unique-local": "a unique local address",
+  multicast: "a multicast address",
+  reserved: "a reserved address",
+  unparseable: "an address that could not be read"
+};
+function describeBlocked(reason) {
+  return REASON_TEXT[reason];
+}
+
+/** `null` when the address is a public one this server may talk to. */
+function blockedAddressReason(address) {
+  // A scope/zone id (`fe80::1%eth0`) is not part of the address, and leaving
+  // it on would make the address unparseable — which fails closed, but for the
+  // wrong reason and with the wrong message.
+  const bare = address.split("%")[0];
+  const v4 = parseIPv4(bare);
+  if (v4 !== null) {
+    return blockedIPv4(v4);
+  }
+  const v6 = parseIPv6(bare);
+  if (v6 !== null) {
+    return blockedIPv6(v6);
+  }
+  // Fail closed. Anything that reaches here is not something `dns.lookup`
+  // produced, and connecting to an address this cannot read is exactly the
+  // case a deny list must not wave through.
+  return "unparseable";
+}
+function parseIPv4(text) {
+  const parts = text.split(".");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const octets = [];
+  for (const part of parts) {
+    // Deliberately strict: `010` is octal to `inet_aton` and decimal to
+    // `Number`, and `1e2` parses as 100. A resolver never produces either, so
+    // anything that is not plain digits is not an address - and a leading
+    // zero is refused outright rather than read as decimal, because that is
+    // the one form where this and `inet_aton` would read the SAME string as
+    // two different addresses. `0` itself is an octet; `01` is not.
+    if (!/^(0|[1-9]\d{0,2})$/.test(part)) {
+      return null;
+    }
+    const value = Number(part);
+    if (value > 255) {
+      return null;
+    }
+    octets.push(value);
+  }
+  return [octets[0], octets[1], octets[2], octets[3]];
+}
+
+/** Eight hextets, with `::` expanded and a trailing IPv4 form accepted. */
+function parseIPv6(text) {
+  if (!text.includes(":")) {
+    return null;
+  }
+  // A trailing dotted quad is rewritten into the two hextets it IS, before
+  // anything else looks at the string. Splitting the address around it
+  // instead means handling a `::` that the split lands inside - which is
+  // exactly where `::127.0.0.1` went wrong.
+  let normalized = text;
+  const lastColon = text.lastIndexOf(":");
+  const tail = text.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const v4 = parseIPv4(tail);
+    if (v4 === null) {
+      return null;
+    }
+    const high = (v4[0] << 8 | v4[1]).toString(16);
+    const low = (v4[2] << 8 | v4[3]).toString(16);
+    normalized = `${text.slice(0, lastColon + 1)}${high}:${low}`;
+  }
+  const doubleColon = normalized.indexOf("::");
+  if (doubleColon !== normalized.lastIndexOf("::")) {
+    return null;
+  }
+  let groups;
+  if (doubleColon === -1) {
+    groups = normalized.split(":");
+    if (groups.length !== 8) {
+      return null;
+    }
+  } else {
+    const left = normalized.slice(0, doubleColon);
+    const right = normalized.slice(doubleColon + 2);
+    const before = left === "" ? [] : left.split(":");
+    const after = right === "" ? [] : right.split(":");
+    if (before.length + after.length > 7) {
+      // `::` stands for AT LEAST one group of zeros, so eight written groups
+      // beside it is one too many.
+      return null;
+    }
+    groups = [...before, ...new Array(8 - before.length - after.length).fill("0"), ...after];
+  }
+  const hextets = [];
+  for (const group of groups) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(group)) {
+      return null;
+    }
+    hextets.push(parseInt(group, 16));
+  }
+  return hextets.length === 8 ? hextets : null;
+}
+function blockedIPv4(octets) {
+  const [a, b, c] = octets;
+  if (a === 0) return "unspecified"; // 0.0.0.0/8
+  if (a === 10) return "private"; // 10.0.0.0/8
+  if (a === 127) return "loopback"; // 127.0.0.0/8
+  if (a === 100 && b >= 64 && b <= 127) return "private"; // 100.64.0.0/10 CGNAT
+  if (a === 169 && b === 254) return "link-local"; // 169.254.0.0/16 — cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return "private"; // 172.16.0.0/12
+  if (a === 192 && b === 168) return "private"; // 192.168.0.0/16
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return "reserved"; // 192.0.0.0/24, TEST-NET-1
+  if (a === 192 && b === 88 && c === 99) return "reserved"; // 6to4 relay anycast
+  if (a === 198 && (b === 18 || b === 19)) return "reserved"; // benchmarking
+  if (a === 198 && b === 51 && c === 100) return "reserved"; // TEST-NET-2
+  if (a === 203 && b === 0 && c === 113) return "reserved"; // TEST-NET-3
+  if (a >= 240) return "reserved"; // 240.0.0.0/4, incl. 255.255.255.255
+  if (a >= 224) return "multicast"; // 224.0.0.0/4
+  return null;
+}
+function blockedIPv6(h) {
+  const leadingZeros = h[0] === 0 && h[1] === 0 && h[2] === 0 && h[3] === 0 && h[4] === 0;
+  if (leadingZeros && h[5] === 0xffff) {
+    // ::ffff:0:0/96 — an IPv4 address wearing an IPv6 hat, and the form a
+    // dual-stack resolver hands back. Judged as the IPv4 address it is, or
+    // this whole list would be one `::ffff:` away from being bypassed.
+    return blockedIPv4(v4Of(h[6], h[7]));
+  }
+  if (leadingZeros && h[5] === 0) {
+    // ::/128 unspecified, ::1/128 loopback, and the deprecated
+    // IPv4-compatible ::a.b.c.d — all of which are local or nothing.
+    if (h[6] === 0 && h[7] === 0) return "unspecified";
+    if (h[6] === 0 && h[7] === 1) return "loopback";
+    return blockedIPv4(v4Of(h[6], h[7])) ?? "reserved";
+  }
+  if (h[0] === 0x64 && h[1] === 0xff9b) return "reserved"; // NAT64
+  if (h[0] === 0x100 && h[1] === 0 && h[2] === 0 && h[3] === 0) {
+    return "reserved"; // 100::/64 discard-only
+  }
+  if (h[0] === 0x2001 && h[1] === 0x0db8) return "reserved"; // documentation
+  if ((h[0] & 0xfe00) === 0xfc00) return "unique-local"; // fc00::/7
+  if ((h[0] & 0xffc0) === 0xfe80) return "link-local"; // fe80::/10
+  if ((h[0] & 0xff00) === 0xff00) return "multicast"; // ff00::/8
+  return null;
+}
+function v4Of(high, low) {
+  return [high >> 8, high & 0xff, low >> 8, low & 0xff];
+}
+
+/**
+ * Opening one external URL and reporting what answered.
+ *
+ * Mirrors `ExternalUrlProbeResult` in the Studio - the two are checked against
+ * each other by the API route's zod schema, which is the only place they meet.
+ */
+
+const DEFAULT_TIMEOUT_MS$1 = 5000;
+const DEFAULT_MAX_REDIRECTS = 5;
+
+/**
+ * A browser-ish identity.
+ *
+ * Not a disguise: plenty of sites answer 403 to a request with no `User-Agent`
+ * at all, and reporting those as broken would be a check that cries wolf. It
+ * says what it is and where to complain.
+ */
+const USER_AGENT = "Val-Studio-LinkCheck/1.0 (+https://val.build; link checker)";
+
+/**
+ * A `lookup` that refuses to hand back an address this server may not reach.
+ *
+ * This, rather than a check on the hostname or a check after the fact, is what
+ * closes the hole. The socket connects to the address the lookup RETURNS, so
+ * validating inside it leaves no window between the check and the connection —
+ * a name that resolves to 93.184.216.34 once and 127.0.0.1 the next time gets
+ * no second chance, because there is only ever one resolution and it is this
+ * one.
+ */
+/**
+ * What a refused lookup tells the CALLER.
+ *
+ * Deliberately the same words `ENETUNREACH` gets, and deliberately without the
+ * address. The guard stops the connection, but the first version of it handed
+ * back the DNS answer it had just refused to use - "vault.prod.svc resolves to
+ * a private address (10.42.7.19)" - which travels through `readableError` into
+ * the response and onto the screen. That turns an endpoint that cannot reach
+ * the internal network into one that MAPS it: twenty names a request, existence
+ * confirmed and address included, without a single connection being made.
+ *
+ * True rather than evasive: this server genuinely did not reach the host. And
+ * because a real external host that is down produces the same sentence, the
+ * answer no longer says which of the two happened. The operator still gets the
+ * detail, in the log, where it belongs.
+ *
+ * A hostname the caller wrote as a literal address is different and keeps its
+ * specific message (see the literal check in `probeUrl`): repeating
+ * `127.0.0.1` to someone who just typed `127.0.0.1` reveals nothing.
+ */
+const REFUSED_MESSAGE = "the host could not be reached";
+function guardedLookup(lookup) {
+  const guarded = (hostname, options, callback) => {
+    // The overloads differ only in whether `options` was passed; `net` always
+    // calls through with both, and this forwards whatever it was given.
+    return lookup(hostname, options, (err, address, family) => {
+      if (err) {
+        callback(err, "", 0);
+        return;
+      }
+      const addresses = Array.isArray(address) ? address : [{
+        address,
+        family: family ?? 0
+      }];
+      for (const entry of addresses) {
+        const reason = blockedAddressReason(entry.address);
+        if (reason !== null) {
+          // Server-side only. This is the half an operator needs to work out
+          // why a link check refused a URL, and the half a caller must not
+          // be given.
+          console.warn(`[val] link check refused ${hostname}: resolves to ${describeBlocked(reason)} (${entry.address})`);
+          callback(new Error(REFUSED_MESSAGE), "", 0);
+          return;
+        }
+      }
+      // Forwarded in the shape it arrived in: `net` reads it back according
+      // to whether it asked for `all`.
+      if (Array.isArray(address)) {
+        callback(null, address, family);
+      } else {
+        callback(null, address, family ?? 0);
+      }
+    }
+    // The callback shape above is the union of both overloads, which the
+    // published types split apart.
+    );
+  };
+  return guarded;
+}
+
+/** The statuses that mean "ask again with GET" rather than "no". */
+function needsGetFallback(code) {
+  /*
+   * Only where the server said the METHOD was the problem.
+   *
+   * A 403 is the tempting third case - some WAFs and proxies do refuse HEAD
+   * with one, and this repo's own sandbox is an example - but retrying every
+   * 403 with a GET means downloading a page for each of them, on a check whose
+   * whole point is to be cheap enough to run over a few hundred URLs. And it
+   * would buy little: 403 is already reported as "may be fine for a visitor,
+   * cannot be checked from here" rather than as a broken link, which is the
+   * right answer either way.
+   */
+  return code === 405 || code === 501;
+}
+async function probeUrl(rawUrl, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
+  const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const now = options.now ?? (() => Date.now());
+  const started = now();
+  const deadline = started + timeoutMs;
+  let url;
+  try {
+    url = new URL(rawUrl.trim());
+  } catch {
+    return {
+      kind: "skipped",
+      message: "Not opened: this is not a URL."
+    };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return {
+      kind: "skipped",
+      message: "Not opened: only http:// and https:// can be checked."
+    };
+  }
+  let method = "HEAD";
+  let redirects = 0;
+  for (;;) {
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      return {
+        kind: "timeout",
+        ms: timeoutMs
+      };
+    }
+    /*
+     * A hostname that is ALREADY an address never reaches the lookup.
+     *
+     * `net.connect` checks for an IP literal first and connects straight to
+     * it, so `guardedLookup` is simply not called for
+     * `http://169.254.169.254/` — which is the single most valuable URL an
+     * attacker could ask this server to open. Checked here, per hop, because a
+     * redirect can introduce one at any point in the chain.
+     *
+     * This was a real hole, found by a test that asserted the local server
+     * received nothing and watched it receive something.
+     */
+    const literal = bareHost(url.hostname);
+    if (net__default["default"].isIP(literal) !== 0) {
+      const reason = blockedAddressReason(literal);
+      if (reason !== null) {
+        return {
+          kind: "unreachable",
+          message: `${literal} is ${describeBlocked(reason)}`
+        };
+      }
+    }
+    let response;
+    try {
+      response = await requestOnce(url, method, remaining, options.request);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message === TIMED_OUT) {
+        return {
+          kind: "timeout",
+          ms: timeoutMs
+        };
+      }
+      return {
+        kind: "unreachable",
+        message
+      };
+    }
+    if (method === "HEAD" && needsGetFallback(response.code)) {
+      method = "GET";
+      continue;
+    }
+    const location = response.location;
+    if (location !== undefined && response.code >= 300 && response.code < 400) {
+      if (redirects >= maxRedirects) {
+        return {
+          kind: "unreachable",
+          message: `too many redirects (${maxRedirects})`
+        };
+      }
+      let next;
+      try {
+        next = new URL(location, url);
+      } catch {
+        return {
+          kind: "unreachable",
+          message: `redirected to something that is not a URL (${location})`
+        };
+      }
+      if (next.protocol !== "http:" && next.protocol !== "https:") {
+        // A redirect to `file:` or `gopher:` is a redirect out of what this
+        // is allowed to open, and the address guard would never see it.
+        return {
+          kind: "unreachable",
+          message: `redirected to ${next.protocol}//, which cannot be checked`
+        };
+      }
+      url = next;
+      redirects++;
+      // A redirect answers the method question too: a server that refused
+      // HEAD at the old URL says nothing about the new one.
+      method = "HEAD";
+      continue;
+    }
+    return {
+      kind: "answered",
+      code: response.code,
+      finalUrl: url.toString(),
+      ms: Math.max(0, Math.round(now() - started))
+    };
+  }
+}
+
+/**
+ * A hostname with the IPv6 brackets off.
+ *
+ * `new URL("http://[::1]/").hostname` is `"[::1]"`, brackets and all, and
+ * `net.isIP` says 0 to that — so the bracketed form sailed past the literal
+ * check and failed later with "host could not be found". Which looks like a
+ * refusal, and is not one.
+ */
+function bareHost(hostname) {
+  return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+const TIMED_OUT = "val:link-check-timeout";
+function requestOnce(url, method, timeoutMs, requestImpl) {
+  const impl = requestImpl ?? (url.protocol === "http:" ? http__default["default"].request : https__default["default"].request);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = fn => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    const req = impl({
+      protocol: url.protocol,
+      hostname: url.hostname,
+      port: url.port === "" ? undefined : url.port,
+      path: `${url.pathname}${url.search}`,
+      method,
+      headers: {
+        // No cookies, no authorization, no forwarded headers: this request
+        // is the server's own and carries none of its identity.
+        "user-agent": USER_AGENT,
+        accept: "*/*",
+        // A redirect chain is followed by hand, one guarded hop at a time.
+        "accept-encoding": "identity"
+      },
+      // Every DNS answer is checked before a socket is opened. See
+      // `guardedLookup` — this is the line that makes the whole feature safe.
+      lookup: guardedLookup(defaultLookup()),
+      // Node's default agent keeps sockets alive between requests, and a
+      // pooled socket was resolved by a PREVIOUS lookup. A fresh connection
+      // per probe is what keeps the guard in front of every one of them.
+      agent: false,
+      timeout: timeoutMs
+    }, res => {
+      const location = res.headers.location;
+      // The body is never read: a status and a `Location` is the whole
+      // answer, and downloading a page to throw it away is bandwidth spent
+      // on somebody else's server.
+      res.destroy();
+      finish(() => resolve({
+        code: res.statusCode ?? 0,
+        location: typeof location === "string" ? location : undefined
+      }));
+    });
+    req.on("timeout", () => {
+      req.destroy();
+      finish(() => reject(new Error(TIMED_OUT)));
+    });
+    req.on("error", error => {
+      finish(() => reject(new Error(readableError(error))));
+    });
+    req.end();
+  });
+}
+
+/** `dns.lookup`, read lazily so a test can swap `node:dns` wholesale. */
+function defaultLookup() {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const dns = require("node:dns");
+  return dns.lookup;
+}
+
+/** What went wrong, in words rather than in errno. */
+function readableError(error) {
+  /*
+   * The guard's own refusal, recognised by its message rather than by a code.
+   * `net` destroys the socket with the Error the lookup gave it, and the
+   * message survives that trip verbatim; whether a custom `code` does is an
+   * implementation detail this does not need to bet on.
+   */
+  if (error.message === REFUSED_MESSAGE) {
+    return REFUSED_MESSAGE;
+  }
+  switch (error.code) {
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+      return "the host could not be found";
+    case "ECONNREFUSED":
+      return "the connection was refused";
+    case "ECONNRESET":
+      return "the connection was reset";
+    case "EHOSTUNREACH":
+    case "ENETUNREACH":
+      return "the host could not be reached";
+    case "CERT_HAS_EXPIRED":
+      return "its certificate has expired";
+    case "ERR_TLS_CERT_ALTNAME_INVALID":
+      return "its certificate is for a different host";
+    case "DEPTH_ZERO_SELF_SIGNED_CERT":
+    case "SELF_SIGNED_CERT_IN_CHAIN":
+      return "its certificate is self-signed";
+    default:
+      /*
+       * A fixed string, not `error.message`.
+       *
+       * Whatever Node or OpenSSL put in there is written for a server log, and
+       * some of it names things the caller should not learn - a resolved
+       * address, a certificate's subject, a path. The cases above cover what is
+       * worth telling an editor; anything else is noise to them and a leak
+       * waiting to happen.
+       */
+      return "the request failed";
+  }
+}
+
 /* eslint-disable @typescript-eslint/no-unused-vars */
 const jsonOps = new patch.JSONOps();
 /**
@@ -4554,6 +5126,9 @@ class ValOps {
       // group whose id is undefined, all the way to the client.
       ...(saveRes.value.patchGroupId !== undefined ? {
         patchGroupId: saveRes.value.patchGroupId
+      } : {}),
+      ...(saveRes.value.headVersion !== undefined ? {
+        headVersion: saveRes.value.headVersion
       } : {})
     });
   }
@@ -7706,6 +8281,16 @@ const GetApplicablePatches = z.z.object({
       commitSha: z.z.string()
     }).nullable()
   })),
+  /**
+   * The head of the chain. See `OrderedPatches.headPatchId`. Optional because
+   * a content service that predates it sends nothing.
+   */
+  headPatchId: internal.PatchId.nullable().optional(),
+  /**
+   * The chain version of that head. See `OrderedPatches.headVersion`.
+   * Optional for the same reason.
+   */
+  headVersion: z.z.number().optional(),
   commits: z.z.array(z.z.object({
     commitSha: z.z.string(),
     /*
@@ -7781,15 +8366,39 @@ const SavePatchResponse = z.z.object({
    * Optional: a content API that predates patch groups does not send one, and
    * absence has to keep meaning "no groups here" rather than failing the save.
    */
-  patchGroupId: z.z.string().optional()
+  patchGroupId: z.z.string().optional(),
+  /**
+   * The chain version this write made, comparable with `headVersion` on the
+   * listing. Optional: a content service that predates it sends nothing.
+   */
+  headVersion: z.z.number().optional()
 });
 const DeletePatchesResponse = z.z.object({
   deleted: z.z.array(PatchId),
   errors: z.z.array(z.z.object({
     message: z.z.string(),
     patchId: PatchId
-  })).optional()
+  })).optional(),
+  /**
+   * The chain version each branch the delete changed is now at, keyed by
+   * branch. Optional: a content service that predates it sends none.
+   */
+  headVersions: z.z.record(z.z.string(), z.z.number()).optional()
 });
+/**
+ * This client's own branch's entry in a per-branch version map.
+ *
+ * A delete can span branches, so the content service answers per branch. With
+ * no branch of its own (a build with no repository, where the service resolves
+ * it), the only entry is ours when there is exactly one; with several, none can
+ * be picked, and a wrong one would floor this client at another chain's count.
+ */
+function ownBranchVersion(headVersions, branch) {
+  if (headVersions === undefined) return undefined;
+  if (branch !== undefined) return headVersions[branch];
+  const versions = Object.values(headVersions);
+  return versions.length === 1 ? versions[0] : undefined;
+}
 const SavePatchFileResponse = z.z.object({
   patchId: PatchId,
   filePath: ModuleFilePath
@@ -7809,7 +8418,9 @@ const CommitResponse = z.z.object({
    */
   parent: z.z.string().optional(),
   tree: z.z.string().optional(),
-  branch: z.z.string()
+  branch: z.z.string(),
+  /** The chain version the publish moved the branch to; absent if it applied nothing. */
+  headVersion: z.z.number().optional()
 });
 // #region history wire schemas
 //
@@ -8173,7 +8784,9 @@ class ValOpsHttp extends ValOps {
    * An allow list rather than a prefix check, because this method holds a
    * credential and the browser chooses the path. `/publish/{id}` and its three
    * steps are the publish conversation; `/build-target` is what a build needs
-   * to know before it starts; `/project-source` is what it builds.
+   * to know before it starts; `/project-source` is what it builds;
+   * `/update-target` is the same question as `/build-target` for a managed
+   * project moving onto its template's current dependencies.
    *
    * `/project-source` is here rather than on a route of its own because it is
    * one of the three things a publish asks for and none of them are useful
@@ -8187,7 +8800,7 @@ class ValOpsHttp extends ValOps {
    * segment gets through.
    */
   static publishApiPathAllowed(path) {
-    if (path === "/build-target" || path === "/project-source" || path === "/publish") {
+    if (path === "/build-target" || path === "/project-source" || path === "/update-target" || path === "/publish") {
       return true;
     }
     return /^\/publish\/[A-Za-z0-9_-]+(\/(artifacts|verify|promote))?$/.test(path);
@@ -8431,6 +9044,16 @@ class ValOpsHttp extends ValOps {
       deployments: allPatchData.deployments || [],
       patches,
       appliedPatches,
+      /*
+       * The CHAIN head, not the publish head below. Spread: absent is a content
+       * service that does not report it, which is not the same as `null`.
+       */
+      ...(allPatchData.headPatchId !== undefined ? {
+        headPatchId: allPatchData.headPatchId
+      } : {}),
+      ...(allPatchData.headVersion !== undefined ? {
+        headVersion: allPatchData.headVersion
+      } : {}),
       /*
        * The PUBLISH head, which is not `commitSha`.
        *
@@ -8555,6 +9178,10 @@ class ValOpsHttp extends ValOps {
      * the same treatment and a home on `OrderedPatches` first.
      */
     let commits;
+    // A fact about the branch too, so taken from the first chunk that has it
+    // for the same reason `commits` is.
+    let headPatchId;
+    let headVersion;
     if (patchIds === undefined || patchIds.length === 0) {
       return this.fetchPatchesInternal({
         patchIds: patchIds,
@@ -8575,6 +9202,16 @@ class ValOpsHttp extends ValOps {
       if (commits === undefined && res.commits !== undefined) {
         commits = res.commits;
       }
+      /*
+       * The NEWEST head among the chunks: each is its own request, so a later
+       * one can have seen a write an earlier one did not. Taken with its own
+       * version, so the two always describe one read. Without versions (an
+       * older content service) the first head stands, as before.
+       */
+      if (res.headPatchId !== undefined && (headPatchId === undefined || res.headVersion !== undefined && (headVersion === undefined || res.headVersion > headVersion))) {
+        headPatchId = res.headPatchId;
+        headVersion = res.headVersion;
+      }
     }
     // Chunking is a query-string-length workaround, NOT a filter: the content
     // api returns every applicable patch per request regardless of which
@@ -8607,6 +9244,12 @@ class ValOpsHttp extends ValOps {
       // readers do — sees the same shape the unchunked path gives it.
       ...(commits !== undefined ? {
         commits
+      } : {}),
+      ...(headPatchId !== undefined ? {
+        headPatchId
+      } : {}),
+      ...(headVersion !== undefined ? {
+        headVersion
       } : {})
     };
   }
@@ -8702,7 +9345,13 @@ class ValOpsHttp extends ValOps {
             commits,
             deployments,
             patches,
-            errors
+            errors,
+            ...(data.headPatchId !== undefined ? {
+              headPatchId: data.headPatchId
+            } : {}),
+            ...(data.headVersion !== undefined ? {
+              headVersion: data.headVersion
+            } : {})
           };
         }
         console.error("Could not parse patches response. Error: " + zodValidationError.fromError(parsed.error));
@@ -9072,6 +9721,9 @@ class ValOpsHttp extends ValOps {
              */
             ...(parsed.data.patchGroupId !== undefined ? {
               patchGroupId: parsed.data.patchGroupId
+            } : {}),
+            ...(parsed.data.headVersion !== undefined ? {
+              headVersion: parsed.data.headVersion
             } : {})
           });
         }
@@ -9395,18 +10047,25 @@ class ValOpsHttp extends ValOps {
       if (res.ok) {
         const parsed = DeletePatchesResponse.safeParse(await res.json());
         if (parsed.success) {
+          var _this$git;
           const errors = {};
           for (const err of parsed.data.errors || []) {
             errors[err.patchId] = err;
           }
+          const headVersion = ownBranchVersion(parsed.data.headVersions, (_this$git = this.git) === null || _this$git === void 0 ? void 0 : _this$git.branch);
+          const version = headVersion !== undefined ? {
+            headVersion
+          } : {};
           if (Object.keys(errors).length === 0) {
             return {
-              deleted: parsed.data.deleted
+              deleted: parsed.data.deleted,
+              ...version
             };
           }
           return {
             deleted: parsed.data.deleted,
-            errors
+            errors,
+            ...version
           };
         }
         return {
@@ -9536,6 +10195,9 @@ class ValOpsHttp extends ValOps {
             } : {}),
             ...(parsed.data.tree !== undefined ? {
               tree: parsed.data.tree
+            } : {}),
+            ...(parsed.data.headVersion !== undefined ? {
+              headVersion: parsed.data.headVersion
             } : {})
           };
         }
@@ -12305,7 +12967,10 @@ const ValServer = (valModules, options, callbacks) => {
             ...(sourceMode ? {
               sourceMode
             } : {}),
-            config: options.config
+            // Not `options.config` verbatim: in proxy mode the branch the
+            // server resolved is filled in where the file did not name one.
+            // See `clientConfig`.
+            config: clientConfig(options)
           }
         };
       }
@@ -12398,6 +13063,46 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    "/external-urls/check": {
+      POST: async req => {
+        /*
+         * The same door as every other route, which in fs mode is an open one.
+         *
+         * `getAuth` returns anonymous success when there is no `valSecret` and
+         * nothing requires auth — a developer's own machine, where there is no
+         * credential to require and 29 other routes already behave this way.
+         * So this is not a session gate in fs mode, and it is not meant to be
+         * the thing that makes the endpoint safe: what does that is
+         * `addressGuard`, which refuses every address that is not on the
+         * public internet, on the RESOLVED address, at every redirect hop.
+         */
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        /*
+         * Every URL in the batch at once, and nothing beyond it.
+         *
+         * The concurrency here is the batch size the route caps at, which is
+         * what keeps "check a thousand links" from becoming a thousand
+         * simultaneous outbound sockets: the client sends ten, waits, sends
+         * the next ten. Doing them in parallel WITHIN a batch is what makes a
+         * batch worth having — ten five-second timeouts in series is a minute.
+         */
+        const results = await Promise.all(req.body.urls.map(async url => [url, await probeUrl(url)]));
+        return {
+          status: 200,
+          json: {
+            results: Object.fromEntries(results)
+          }
+        };
+      }
+    },
     "/direct-file-upload-settings": {
       POST: async req => {
         const cookies = req.cookies;
@@ -12705,6 +13410,13 @@ const ValServer = (valModules, options, callbacks) => {
          * re-read when a fetch has missing ids to ask for.
          */
         let patchGroupIdFromStore;
+        /*
+         * The chain version the LAST patch made — the head this batch leaves.
+         * The client keeps the highest version it has seen, so a `/stat` read
+         * before this write cannot put its parent back behind it. Absent in
+         * `fs` mode and from an older content API.
+         */
+        let headVersion;
         for (const patch of patches) {
           const createPatchRes = await serverOps.createPatch(patch.path, patch.patch, patch.patchId, parentRef, sessionId, authorId, patchGroup);
           if (fp.result.isErr(createPatchRes)) {
@@ -12741,6 +13453,7 @@ const ValServer = (valModules, options, callbacks) => {
             if (createPatchRes.value.patchGroupId !== undefined) {
               patchGroupIdFromStore = createPatchRes.value.patchGroupId;
             }
+            headVersion = createPatchRes.value.headVersion;
           }
         }
         return {
@@ -12753,6 +13466,9 @@ const ValServer = (valModules, options, callbacks) => {
             // client reads absence as "staging is not available here".
             ...(patchGroupIdFromStore !== undefined ? {
               patchGroupId: patchGroupIdFromStore
+            } : {}),
+            ...(headVersion !== undefined ? {
+              headVersion
             } : {})
           }
         };
@@ -12892,7 +13608,7 @@ const ValServer = (valModules, options, callbacks) => {
         };
       },
       DELETE: async req => {
-        var _req$body;
+        var _req$body, _req$body2;
         const query = req.query;
         const cookies = req.cookies;
         const auth = getAuth(cookies);
@@ -12945,6 +13661,17 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
+        if (((_req$body2 = req.body) === null || _req$body2 === void 0 ? void 0 : _req$body2.reportHeadVersion) === true) {
+          return {
+            status: 200,
+            json: {
+              deleted: ids,
+              ...("headVersion" in deleteRes && deleteRes.headVersion !== undefined ? {
+                headVersion: deleteRes.headVersion
+              } : {})
+            }
+          };
+        }
         return {
           status: 200,
           json: ids
@@ -13991,6 +14718,9 @@ const ValServer = (valModules, options, callbacks) => {
                 ...(managedBranch !== null ? {
                   branch: managedBranch
                 } : {}),
+                ...(commitRes.headVersion !== undefined ? {
+                  headVersion: commitRes.headVersion
+                } : {}),
                 ...(committedBinaries !== null ? {
                   binaryFiles: committedBinaries.files,
                   ...(committedBinaries.unread.length > 0 ? {
@@ -16429,7 +17159,7 @@ async function getFileBufferFromRemote(ref, fileExt, currentFileHash, projectRoo
 async function downloadFileFromRemote(ref, filePath) {
   return new Promise((resolve, reject) => {
     const url = new URL(ref);
-    const client = url.protocol === "https:" ? https__default["default"] : http__default["default"];
+    const client = url.protocol === "https:" ? https__default$1["default"] : http__default$1["default"];
     const request = client.get(url, response => {
       if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
         // Handle redirects