@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/fleet-vm-probe-target.js

@@ -0,0 +1,282 @@
+'use strict';
+// Where the fleet dashboard sends a per-VM editor-API probe, and how to read
+// the answer.
+//
+// The dashboard gets ALL per-VM live data — reachability, feature, step,
+// selectedPlan, credential health, preview — by probing each VM's editor API.
+// On a laptop that probe goes to `127.0.0.1:PORT_BASE+N`, which is fed by an SSH
+// `-L` forward the vm-watchdog creates. On the GCE operator host those forwards
+// cannot exist: the watchdog runs as root, the fleet VMs use metadata SSH keys
+// (OS Login is OFF) and refuse root login, so `gcloud compute ssh` fails
+// `Permission denied (publickey)`. No forwards ⇒ dead local ports ⇒ every card
+// reads "unreachable" with no progress.
+//
+// On GCE we therefore probe each VM through the LB hostname it is already wired
+// to (`https://vm-<N>.editor.<domain>`), authenticated with an IAP identity
+// token minted by the operator service account. Same paths, same downstream
+// parsing — only the transport changes.
+//
+// Pure logic only — no I/O, no env reads, no clock — so it stays unit-testable
+// in isolation (npm/fleet-vm-probe-target.test.js), exactly like vm-urls.js.
+
+// Loopback host for the laptop probe. The SSH `-L` forward binds here, so the
+// probe must too — 'localhost' could resolve to ::1 and miss an IPv4-only bind.
+const LOCAL_HOST = '127.0.0.1';
+
+/** Resolve where a per-VM editor-API probe should be sent.
+ *
+ *  Returns a descriptor the caller dispatches on:
+ *    { mode: 'lb',    url, headers, authMissing }  — GCE: absolute LB URL
+ *    { mode: 'local', host, port, path, headers }  — laptop: forwarded port
+ *
+ *  `authMissing` is true when a GCE probe has no IAP token to attach. The caller
+ *  must NOT treat the resulting response as reachable — an unauthenticated
+ *  request to an IAP-fronted backend gets a 302 to the Google login page, which
+ *  is "auth misconfigured", not "the VM is up". See classifyProbeResponse.
+ *
+ *  `sessionToken` (optional): the fail-closed editor requires each VM's own
+ *  editor session token in `Authorization` on every gated control-API request.
+ *  When one is supplied, it rides in `Authorization` and the IAP token moves to
+ *  `Proxy-Authorization` (IAP honors it there), so both credentials are present
+ *  without colliding on `Authorization`. When it is absent, header shape is
+ *  byte-for-byte today's behavior (IAP in `Authorization`), keeping the open
+ *  `/api/session-info` reachability probe unchanged.
+ */
+function resolveVmProbeTarget({ onGce, url, n, portBase, path, iapToken, sessionToken } = {}) {
+  const probePath = path == null ? '/' : String(path);
+  if (!probePath.startsWith('/')) {
+    throw new Error(`probe path must start with "/", got: ${probePath}`);
+  }
+
+  if (!onGce) {
+    const base = Number(portBase);
+    const num = Number(n);
+    if (!Number.isInteger(base) || !Number.isInteger(num)) {
+      throw new Error('local probe requires integer portBase and n');
+    }
+    return { mode: 'local', host: LOCAL_HOST, port: base + num, path: probePath, headers: {} };
+  }
+
+  // GCE: the LB URL is the ONLY way in. A VM with no derived URL (legacy
+  // quick-tunnel mode, or a roster entry the URL derivation skipped) has no
+  // reachable address on this host, so fail loud rather than silently falling
+  // back to a local port that is guaranteed dead.
+  const origin = url == null ? '' : String(url).trim().replace(/\/+$/, '');
+  if (origin === '') {
+    throw new Error(`VM-${n} has no LB URL to probe (FLEET_DOMAIN not configured?)`);
+  }
+
+  const token = iapToken == null ? '' : String(iapToken).trim();
+  const session = sessionToken == null ? '' : String(sessionToken).trim();
+  // With a session token the fail-closed editor's own credential owns
+  // `Authorization`; IAP still fronts the LB, so its token moves to
+  // `Proxy-Authorization`. Without one, keep exactly today's IAP-in-
+  // `Authorization` shape. `authMissing` stays keyed on the IAP token alone —
+  // IAP is still required to reach the LB even when a session token is present.
+  let headers;
+  if (session !== '') {
+    headers = { Authorization: `Bearer ${session}` };
+    if (token !== '') headers['Proxy-Authorization'] = `Bearer ${token}`;
+  } else {
+    headers = token === '' ? {} : { Authorization: `Bearer ${token}` };
+  }
+  return {
+    mode: 'lb',
+    url: origin + probePath,
+    headers,
+    authMissing: token === '',
+  };
+}
+
+// The one open control-API endpoint: `/api/session-info` answers WITHOUT the
+// editor's session token — it is the reachability probe. Every other control-API
+// path is gated under fail-closed auth, so the dashboard must attach the VM's
+// session token or get a 401. Kept here (pure, tested) rather than inline in the
+// caller so the open-vs-gated boundary has one authoritative home.
+const OPEN_PROBE_PATHS = new Set(['/api/session-info']);
+
+/** True when a probe path needs the VM's editor session token attached.
+ *
+ *  Only the open reachability probe (`/api/session-info`) is exempt; every other
+ *  control-API path is gated under fail-closed auth. A query string is ignored so
+ *  `/api/session-info?foo` still reads as the open path. */
+function pathNeedsSessionToken(apiPath) {
+  const p = (apiPath == null ? '' : String(apiPath)).split('?')[0];
+  return p !== '' && !OPEN_PROBE_PATHS.has(p);
+}
+
+// Hostname IAP redirects an unauthenticated request to. Matching this is what
+// separates "the token is missing/expired" from "the VM is genuinely down" —
+// both would otherwise read as a non-200 and blank the card identically.
+const IAP_LOGIN_HOST = 'accounts.google.com';
+
+/** Classify a probe response into the three outcomes the dashboard cares about.
+ *
+ *    'ok'                 — 200; caller still has to parse the body.
+ *    'auth-misconfigured' — IAP rejected or challenged us (302→login, 401, 403).
+ *                           The VM may be perfectly healthy; OUR credential is
+ *                           the problem, so this must never render as reachable
+ *                           and must never feed a reset decision.
+ *    'unreachable'        — anything else: the VM/LB backend is not serving.
+ */
+function classifyProbeResponse({ status, location } = {}) {
+  const code = Number(status);
+  if (code === 200) return 'ok';
+  if (code === 401 || code === 403) return 'auth-misconfigured';
+  if (code >= 300 && code < 400) {
+    const to = location == null ? '' : String(location);
+    return to.includes(IAP_LOGIN_HOST) ? 'auth-misconfigured' : 'unreachable';
+  }
+  return 'unreachable';
+}
+
+/** Name the LIKELY cause behind an 'auth-misconfigured' probe, for logs only.
+ *
+ * 401 and 403 both mean "our credential is the problem", so they deliberately
+ * share one outcome — but they have opposite fixes, and telling them apart
+ * previously cost a live `curl` session against the backend (2026-07-20):
+ *
+ *    401 — the fail-closed editor rejected our session token. IAP now rides in
+ *          Proxy-Authorization, so a 401 from the backend means the VM's own
+ *          editor session token in Authorization was missing, stale, or wrong —
+ *          the dashboard invalidates its cached token and self-heals next poll.
+ *    403 — the token is valid but the caller is not authorized. The automation SA
+ *          is missing roles/iap.httpsResourceAccessor on that backend service.
+ *
+ * Returns null for any other status, so callers can log unconditionally.
+ * Diagnostic only — this never feeds a reachability or reset decision. */
+function describeAuthMisconfig(status) {
+  const code = Number(status);
+  if (code === 401) {
+    return "session token rejected — the fail-closed editor requires this VM's " +
+      'own editor session token in Authorization; the dashboard fetch was ' +
+      'missing/stale (it invalidates the cached token and re-fetches next poll)';
+  }
+  if (code === 403) {
+    return 'missing accessor — the automation service account lacks ' +
+      'roles/iap.httpsResourceAccessor on this backend service ' +
+      '(re-grant: bash scripts/gcp/iap-access.sh <N> grant)';
+  }
+  return null;
+}
+
+/** Map a probe outcome (+ optional transport reason) to the per-VM card shape
+ *  the dashboard merges into `state.vms[n]`.
+ *
+ *  The rule this encodes: an 'auth-misconfigured' outcome is NOT reachable, and
+ *  stays distinguishable from a dead VM. Collapsing the two would either render
+ *  a broken credential as a healthy VM, or let our own expired token look like N
+ *  dead boxes and feed a reset decision. Anything unrecognized fails closed to
+ *  unreachable rather than leaking a truthy `reachable`. */
+function probeOutcomeToInfo(outcome, error) {
+  if (outcome === 'ok') return { reachable: true };
+  if (outcome === 'auth-misconfigured') {
+    return { reachable: false, error: 'auth-misconfigured', authMisconfigured: true };
+  }
+  return error ? { reachable: false, error } : { reachable: false };
+}
+
+/** Merge a parsed `/api/session-info` body into the per-VM card shape.
+ *
+ *  The contract, in one place instead of inlined in the dashboard's probe:
+ *    • an unreachable card never takes a body (a credential fault or a dead VM
+ *      must not gain fields from whatever the transport happened to return);
+ *    • a reachable card takes the body ONLY when it is a usable object.
+ *
+ *  That second rule used to be accidental rather than stated. The expression was
+ *  `info.reachable ? { ...info, ...json } : info`, and spreading `null` (or an
+ *  array, or a scalar) is a silent no-op — so an unusable body produced a card
+ *  that read reachable with `clientProject` and `editorIdentity` absent, which is
+ *  indistinguishable from a VM that genuinely reports neither. The resulting card
+ *  shape is deliberately UNCHANGED by making the rule explicit; what changes is
+ *  that the caller can now see the fault (probeBodyFault) and log it instead of
+ *  discovering it days later through a blank card. Pure. */
+function mergeSessionInfoBody(info, json) {
+  if (!info || !info.reachable) return info;
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) return info;
+  return { ...info, ...json };
+}
+
+/** Name the fault when a probe SUCCEEDED at the transport layer but its body is
+ *  not a usable object, else null.
+ *
+ *  This is the hole that cost a full diagnostic session on 2026-07-29. The card
+ *  merge is `info.reachable ? { ...info, ...json } : info`, and spreading `null`
+ *  (or an array, or a JSON scalar) is a silent no-op — so a VM answering 200 with
+ *  an unusable body produced a card that read REACHABLE with every session-info
+ *  field absent (`clientProject` and `editorIdentity` null), and emitted no log
+ *  line at all. `stickyClientProject` then hid it for as long as a previously
+ *  polled value survived in memory, so the fault only surfaced after a dashboard
+ *  restart cleared the sticky cache.
+ *
+ *  A 'bad-json' transport error is the sibling case: the body was unparseable, so
+ *  the probe already fails closed to unreachable — correct, but equally silent.
+ *  Callers pass that through here too so both paths get one loud warning.
+ *
+ *  Returns a short, log-safe fault name:
+ *    'bad-json'    — body did not parse (caller passes error === 'bad-json')
+ *    'null-body'   — parsed to JSON null
+ *    'array-body'  — parsed to an array
+ *    '<type>-body' — parsed to a scalar (number/string/boolean)
+ *  and null when the body is a usable object (the normal case) or the outcome was
+ *  never 'ok' (already classified by probeOutcomeToInfo). Pure. */
+function probeBodyFault(outcome, json, error) {
+  if (error === 'bad-json') return 'bad-json';
+  if (outcome !== 'ok') return null;
+  if (json === null || json === undefined) return 'null-body';
+  if (Array.isArray(json)) return 'array-body';
+  if (typeof json !== 'object') return `${typeof json}-body`;
+  return null;
+}
+
+/** The log line for a probe-body fault, naming the VM, the fault and the HTTP
+ *  status — the three things that were missing when this failure mode cost a
+ *  full diagnostic session with zero log output to work from.
+ *
+ *  A missing status renders as `?` rather than `undefined`: the transport error
+ *  paths (timeout, socket error) never saw a response, and `HTTP undefined` reads
+ *  like a bug in the logger instead of an absent status.
+ *
+ *  Diagnostic only — this never feeds a reachability decision, same contract as
+ *  its sibling describeAuthMisconfig. Pure. */
+function describeProbeBodyFault(n, fault, status) {
+  const code = status == null || status === '' ? '?' : String(status);
+  return `probe VM-${n} /api/session-info: ${fault} (HTTP ${code}) — ` +
+    'card identity (clientProject/editorIdentity) absent this poll';
+}
+
+/** Per-VM, per-fault throttle for probe-fault warnings.
+ *
+ *  The poll cycle runs every ~3s across the whole fleet, so warning on every
+ *  faulted probe would bury the log. Throttling per (VM, fault) keeps a
+ *  persistent fault to one line per interval while still surfacing a NEW fault on
+ *  a different VM immediately.
+ *
+ *  Deterministic: the caller supplies `now`, so no clock is read here and the
+ *  behavior is unit-testable. */
+function createProbeFaultThrottle(intervalMs = 300000) {
+  const last = new Map();
+  return {
+    shouldWarn(n, fault, now) {
+      const key = `${n}:${fault}`;
+      const prev = last.get(key);
+      if (prev != null && now - prev < intervalMs) return false;
+      last.set(key, now);
+      return true;
+    },
+  };
+}
+
+module.exports = {
+  LOCAL_HOST,
+  IAP_LOGIN_HOST,
+  resolveVmProbeTarget,
+  pathNeedsSessionToken,
+  classifyProbeResponse,
+  describeAuthMisconfig,
+  probeOutcomeToInfo,
+  mergeSessionInfoBody,
+  probeBodyFault,
+  describeProbeBodyFault,
+  createProbeFaultThrottle,
+};

package/npm/fleet-vm-readiness.js

@@ -36,6 +36,20 @@
 //   'half-wired'   — LB mode, the editor backend service is ABSENT (never
 //                    created). The permanent 503 case — the public URL will fail
 //                    until re-wired. The state that had NO signal before.
+//   'iap-access-missing' — LB mode, the EDITOR backend service is IAP-enabled but
+//                    has NO accessor binding, so IAP authorizes nobody: the public
+//                    URL returns "Error code 51" for everyone even when the backend
+//                    is healthy. Distinct from 'half-wired' (there the backend is
+//                    absent; here it exists and serves, but nobody's granted) — the
+//                    exact "wired + IAP-enabled but 51s in the browser" gap.
+//   'preview-iap-access-missing' — LB mode, the editor surface grants access but
+//                    the dedicated PREVIEW backend has no accessor binding. The
+//                    editor URL works, but the framed Live Preview (served from the
+//                    separate preview host on client-routed stacks) is blank for
+//                    every authorized user because nobody is granted THERE. A
+//                    softer, non-URL-blocking warning than 'iap-access-missing'
+//                    (the editor link is live) — the monitoring blind spot the
+//                    editor-only IAP probe used to hide.
 //   'starting'     — LB mode, the editor backend exists but is UNHEALTHY (LB has
 //                    not yet marked it HEALTHY). The transient 503 case; flips to
 //                    'ready' on its own once the health check passes.
@@ -48,15 +62,84 @@
 // supplied): there is no LB to health-check, so the backend-health branch is
 // skipped and readiness degrades to today's reachability/broker behavior — no
 // regression, no gcloud calls.
+//   'ws-dead'      — reachable + LB-healthy, but the public WebSocket path is
+//                    dead: the LB either refused the upgrade outright
+//                    (publicWsHealth 'unwired') or the backend-service timeout is
+//                    below the fleet minimum so the LB severs the socket on a
+//                    fixed interval (the VM5 guillotine). The editor answers HTTP
+//                    but the Build tab can't hold a terminal — NOT 'ready'.
+//   'cli-missing'  — the editor is up but the build-agent CLI isn't installed
+//                    (`providerAuth.cliInstalled === false`): a provisioning
+//                    fault, not a usable VM.
+//   'auth-unsettled' — the auth probe is wedged at `unknown` (timing out — the
+//                    exact VM5 auth shape): we can't even tell if login is
+//                    needed. A provisioning fault distinct from a clean
+//                    needs-login.
+//   'needs-login'  — CLI installed and auth SETTLED to `needs-login`: a
+//                    legitimate, expected state (the user must authenticate),
+//                    surfaced with the Authenticate affordance — NOT a fault and
+//                    NOT a provisioning fault that holds rostering.
 const READINESS_STATES = [
   'provisioning',
   'unreachable',
   'half-wired',
+  'iap-access-missing',
+  'preview-iap-access-missing',
   'starting',
   'broker-down',
+  'ws-dead',
+  'cli-missing',
+  'auth-unsettled',
+  'needs-login',
   'ready',
 ];
 
+// The WS-timeout floor classifier lives next to classifyPublicUrlHealth (the
+// public-URL probe is one concern); readiness consumes its verdict.
+const fpub = require('./fleet-public-url');
+
+// Classify the build-agent usability axis from the editor's own `providerAuth`
+// subtree (vm: Readiness Verifies Real Usability). control-api emits the SAME
+// `providerAuth` (with `cliInstalled` + settled `state`) on BOTH /api/config and
+// /api/session-info via build_provider_auth_json, so the dashboard reads it
+// straight off the gathered VM record — no re-derivation. Returns one verdict:
+//   'cli-missing'    — `cliInstalled === false`: a provisioning fault.
+//   'auth-unsettled' — CLI installed but `state === 'unknown'` (probe wedged /
+//                      timing out — the VM5 shape): a provisioning fault.
+//   'needs-login'    — CLI installed, `state === 'needs-login'`: a LEGITIMATE,
+//                      actionable state, not a fault.
+//   'ready'          — CLI installed, `state === 'authenticated'`: usable.
+//   'unknown'        — providerAuth absent (older editor / probe never landed),
+//                      or any other shape: absence of evidence, never a fault.
+// Only an EXPLICIT `cliInstalled === false` / `state === 'unknown'` is a fault;
+// missing fields stay 'unknown' so an older editor never reads as broken.
+function classifyAgentUsability(providerAuth) {
+  if (!providerAuth || typeof providerAuth !== 'object') return 'unknown';
+  if (providerAuth.cliInstalled === false) return 'cli-missing';
+  if (providerAuth.cliInstalled !== true) return 'unknown';
+  if (providerAuth.state === 'unknown') return 'auth-unsettled';
+  if (providerAuth.state === 'needs-login') return 'needs-login';
+  if (providerAuth.state === 'authenticated') return 'ready';
+  return 'unknown';
+}
+
+// Map the agent-usability verdict to the tri-state the rostering gate
+// (fleet-cleanup's reapVerdict) consumes, mirroring `projectWired`'s
+// true|false|null contract so a flaky probe can never strand a healthy VM:
+//   false — a PROVISIONING FAULT ('cli-missing' / 'auth-unsettled'): the box is
+//           not usable, so don't roster it as healthy (the VM5 false-green).
+//   true  — usable enough to roster: 'ready', or a legitimate 'needs-login'
+//           (the user must auth, but that's an expected state, not a
+//           half-provisioned box that should be held back).
+//   null  — 'unknown' (no providerAuth / probe couldn't decide): absence of
+//           evidence must NEVER block rostering, exactly like reapVerdict's null
+//           tolerance for projectWired.
+function agentRosterReady(verdict) {
+  if (verdict === 'cli-missing' || verdict === 'auth-unsettled') return false;
+  if (verdict === 'ready' || verdict === 'needs-login') return true;
+  return null;
+}
+
 // A VM mid-provision: an Add (incl. its recovering re-run) that is queued
 // (number reserved, cloud:up not started) or running. Its public URL has no
 // meaningful readiness yet, so this takes precedence over every other signal —
@@ -94,11 +177,61 @@ function deriveVmReadiness(v, ctx) {
     // 'healthy' falls through to ready; 'unknown' (get-health errored) is
     // absence-of-evidence — never rendered as a problem, falls through too.
   }
+  // 3b. IAP access: the backend is IAP-enabled but has NO accessor binding, so
+  //     IAP authorizes nobody and the public URL returns "Error code 51" for
+  //     everyone — even when the backend is healthy. A wiring-class fault a plain
+  //     GET / backend-health probe are both blind to. Only an EXPLICIT
+  //     'no-accessor' verdict fires; absence/'unknown' is never a fault (an older
+  //     dashboard that never gathered it must not read as broken). Gated on
+  //     lbMode — legacy quick-tunnel mode has no per-BES IAP to check.
+  if (c.lbMode && v.iapAccess === 'no-accessor') return 'iap-access-missing';
   // 4. Reachable but the broker daemon is down: the VM can't start a session.
   if (c.brokerStatus === 'down') return 'broker-down';
-  // 5. Reachable, broker up, and (LB mode) the editor backend is HEALTHY —
-  //    genuinely ready: green, clickable, public URL actually routes.
+  // 5. WS-usability (LB mode): the editor answers HTTP and the backend is
+  //    LB-healthy, but the public WebSocket path is dead — either the LB refused
+  //    the upgrade outright (publicWsHealth 'unwired') or the backend-service
+  //    timeout is below the fleet minimum so the LB severs the socket on a fixed
+  //    interval (the VM5 guillotine). Either way the Build tab can't hold a
+  //    terminal, so this is NOT 'ready'. Skipped in legacy mode (no LB). An
+  //    'unknown'/absent WS verdict is absence-of-evidence — never a fault.
+  if (c.lbMode) {
+    // Deterministic guillotine first: a BES timeout below the fleet minimum
+    // severs the socket on a fixed interval — trustworthy, no probe needed.
+    if (fpub.classifyWsTimeout(v.backendTimeoutSec) === 'ws-timeout-too-low') return 'ws-dead';
+    // The public WS probe is IAP-blind and false-positives `unwired` on a
+    // genuinely-healthy VM (VM-1, 2026-07-01: wired + HEALTHY + IAP-granted,
+    // yet `publicWsHealth: unwired` → phantom ws-dead → URL gated "not ready").
+    // Only trust an `unwired` verdict when the backend is NOT already HEALTHY —
+    // a HEALTHY backend with a valid/unknown timeout is never ws-dead.
+    if (v.publicWsHealth === 'unwired' && !(bh && bh.editor === 'healthy')) return 'ws-dead';
+  }
+  // 6. Agent usability: the box is up and the WS path carries frames, but the
+  //    build agent itself may not be usable — CLI not installed, or the auth
+  //    probe wedged at 'unknown'. A legitimate 'needs-login' surfaces as its own
+  //    actionable state (Authenticate), distinct from a provisioning fault.
+  //    Absence of providerAuth (older editor / unprobed) falls through to ready.
+  const usability = classifyAgentUsability(v.providerAuth);
+  if (usability === 'cli-missing') return 'cli-missing';
+  if (usability === 'auth-unsettled') return 'auth-unsettled';
+  if (usability === 'needs-login') return 'needs-login';
+  // 6b. Preview-host IAP gap: the editor surface grants access (the URL routes
+  //     and the box is otherwise ready) but the dedicated preview backend has no
+  //     accessor, so the framed Live Preview is blank for authorized users. A
+  //     softer warning than the editor 'iap-access-missing' — it does NOT block
+  //     the editor link (see URL_BLOCKED_READINESS) — so it is checked last, just
+  //     before 'ready'. Only an EXPLICIT 'preview-no-accessor' verdict fires;
+  //     absence/'unknown' is never a fault. Gated on lbMode like its editor twin.
+  if (c.lbMode && v.iapAccess === 'preview-no-accessor') return 'preview-iap-access-missing';
+  // 7. Reachable, broker up, WS carries frames, agent usable, and (LB mode) the
+  //    editor backend is HEALTHY — genuinely ready: green, clickable, the public
+  //    URL routes AND holds a WebSocket.
   return 'ready';
 }
 
-module.exports = { deriveVmReadiness, READINESS_STATES, isProvisioning };
+module.exports = {
+  deriveVmReadiness,
+  READINESS_STATES,
+  isProvisioning,
+  classifyAgentUsability,
+  agentRosterReady,
+};

package/npm/google-ingress.js

@@ -194,6 +194,20 @@ function dashboardHostRule(domain) {
   };
 }
 
+/** Extract the VM number from an LB-ingress resource name this module mints
+ *  (`vm-<N>-<surface>-neg` or `vm-<N>-<surface>-bes`, surface ∈ SURFACES).
+ *  Returns the number, or null for any name that isn't a per-VM ingress resource
+ *  (the shared `codeyam-dashboard-*` backend, a foreign resource, junk). The
+ *  inverse of negName / backendServiceName — the orphan sweep uses it to map the
+ *  live LB backends back to the VM numbers that own them. The surface alternation
+ *  is built from SURFACES so it stays in lockstep with the name derivations.
+ *  Pure. */
+function vmNumberFromResourceName(name) {
+  const re = new RegExp(`^vm-(\\d+)-(?:${SURFACES.join('|')})-(?:neg|bes)$`);
+  const m = re.exec(String(name == null ? '' : name).trim());
+  return m ? Number(m[1]) : null;
+}
+
 module.exports = {
   SURFACES,
   EDITOR_PORT,
@@ -201,6 +215,7 @@ module.exports = {
   normalizeSurface,
   negName,
   backendServiceName,
+  vmNumberFromResourceName,
   urlMapHostRules,
   hostRuleOperation,
   backendNegAttachOperation,