metergraph-cli 0.2.0 → 0.2.2

package/src/args.js

@@ -21,9 +21,18 @@ import {
   SKILL_CLIENTS,
   SKILL_RUNTIMES,
   TRACES_DEFAULT_LIMIT,
+  MAX_METADATA_FILTERS,
+  MAX_METADATA_KEY_LENGTH,
+  MAX_QUERY_LENGTH,
+  MAX_METADATA_VALUE_LENGTH,
+  USAGE_COMPARISONS,
+  USAGE_DEFAULT_GROUP_BY,
+  USAGE_DIMENSIONS,
+  USAGE_MAX_FILTER_VALUES,
+  USAGE_SORTS,
 } from "./constants.js";
 import { parseOrigin } from "./origin.js";
-import { isCursor, isSafeFilter } from "./read-contract.js";
+import { groupedRequest, hasUnsafeText, isCursor, isSafeFilter, readQuery } from "./read-contract.js";
 
 export const READ_COMMANDS = Object.freeze(["status", "context", "capabilities", "usage", "routes", "traces"]);
 const COMMANDS = new Set(["doctor", "help", "skill", "skills", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
@@ -31,6 +40,10 @@ const HELP_TOPICS = new Set(["doctor", "skill", "skills", "login", "logout", "se
 const SKILL_ACTIONS = new Set(["install", "update"]);
 const SKILLS_ACTIONS = new Set(["install", "update", "list"]);
 const READ_BASE = ["--project", "--config-dir", "--timeout-ms"];
+// The read commands may name where an agent key is sent and which workspace
+// it must be for, and a private file holding the key. The key itself is
+// never an argument.
+const READ_KEY = ["--url", "--workspace", "--agent-token-file"];
 const OPTIONS = {
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
@@ -38,12 +51,17 @@ const OPTIONS = {
   login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
   setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file", "--repository"]),
   logout: new Set(["--project", "--config-dir"]),
-  status: new Set(READ_BASE),
-  context: new Set(READ_BASE),
-  capabilities: new Set(READ_BASE),
-  usage: new Set([...READ_BASE, "--days", "--limit"]),
-  routes: new Set([...READ_BASE, "--limit"]),
-  traces: new Set([...READ_BASE, "--days", "--limit", "--route", "--status", "--cursor"]),
+  status: new Set([...READ_BASE, ...READ_KEY]),
+  context: new Set([...READ_BASE, ...READ_KEY]),
+  capabilities: new Set([...READ_BASE, ...READ_KEY]),
+  usage: new Set([
+    ...READ_BASE, ...READ_KEY, "--days", "--limit", "--metadata", "--metadata-json", "--group-by-metadata",
+    "--group-by", "--route", "--provider", "--model", "--environment", "--since", "--until", "--sort", "--compare",
+  ]),
+  routes: new Set([...READ_BASE, ...READ_KEY, "--limit"]),
+  traces: new Set([
+    ...READ_BASE, ...READ_KEY, "--days", "--limit", "--route", "--status", "--cursor", "--metadata", "--metadata-json",
+  ]),
   verify: new Set([...READ_BASE, "--trace-id", "--request-id", "--since", "--until", "--source", "--days", "--poll-ms", "--max-attempts"]),
 };
 // Requests the read commands recognize and refuse, so a script gets an
@@ -63,23 +81,35 @@ const REFUSED = {
 };
 const REFUSED_MESSAGES = {
   environment_selector_unsupported:
-    "--environment is not supported: the service's agent access contract has no environment selector, " +
-    "so the CLI never sends one. Results cover the bound workspace. No request was made.",
+    "--environment is supported only by usage, which sends it to the grouped usage read. This command has no " +
+    "environment selector, so the CLI never sends one. Results cover the bound workspace. No request was made.",
   workload_filter_unsupported:
     "--workload is not supported by this CLI version: it cannot verify from the returned traces that a " +
     "workload filter was applied, so it never sends one. No request was made.",
   time_range_unsupported:
-    "--since and --until are not supported. Use --days N (1 to 90) for a window relative to now. No request was made.",
+    "--since and --until are supported only by usage. Use --days N (1 to 90) for a window relative to now. " +
+    "No request was made.",
   query_unsupported:
     "Free-form queries are not supported. Use the fixed options of this command. No request was made.",
   content_access_unsupported:
     "Read commands return Metadata only. They never read retained content, debug data or replays. No request was made.",
 };
+// Options that may be given more than once; their values are kept in order.
+const REPEATABLE = new Set(["--metadata"]);
+// usage takes several values for each of its exact-match filters.
+const USAGE_REPEATABLE = new Set(["--route", "--provider", "--model", "--environment"]);
+// usage reads a time range and environments itself, through grouped usage.
+const USAGE_ACCEPTS = new Set(["--environment", "--since", "--until"]);
+// Options that select grouped usage (GET /v1/agent/usage/aggregates).
+const USAGE_GROUPED = [
+  "--group-by", "--group-by-metadata", "--route", "--provider", "--model", "--environment", "--since", "--until", "--sort", "--compare",
+];
 // Options that take no value.
 const FLAGS = {
   login: new Set(["--signup", "--no-browser", "--reconnect"]),
   setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites", "--no-repository"]),
   verify: new Set(["--open", "--no-browser"]),
+  usage: new Set(["--today"]),
 };
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -156,7 +186,7 @@ export function parseArgs(argv) {
     if (READ_COMMANDS.includes(command)) {
       const equals = arg.indexOf("=");
       const name = equals === -1 ? arg : arg.slice(0, equals);
-      if (Object.hasOwn(REFUSED, name)) {
+      if (Object.hasOwn(REFUSED, name) && !(command === "usage" && USAGE_ACCEPTS.has(name))) {
         const { reason } = REFUSED[name];
         return fail(reason, REFUSED_MESSAGES[reason], "unsupported");
       }
@@ -182,6 +212,10 @@ export function parseArgs(argv) {
         if (value === undefined) {
           return fail("missing_value", `${name} requires a value.`);
         }
+        if (REPEATABLE.has(name) || (command === "usage" && USAGE_REPEATABLE.has(name))) {
+          values[name] = [...(values[name] ?? []), value];
+          continue;
+        }
         if (values[name] !== undefined) {
           return fail("duplicate_option", `${name} may be given only once.`);
         }
@@ -223,7 +257,7 @@ export function parseArgs(argv) {
   if (command === "login") return parseLogin(values, flags, json, fail);
   if (command === "setup") return parseSetup(values, flags, json, fail);
   if (command === "verify") return parseVerify(values, flags, json, fail);
-  if (READ_COMMANDS.includes(command)) return parseRead(command, values, json, fail);
+  if (READ_COMMANDS.includes(command)) return parseRead(command, values, flags, json, fail);
   if (command === "logout") {
     const paths = parsePaths(values, fail);
     if (!paths.ok) return paths;
@@ -452,7 +486,7 @@ function parseSetup(values, flags, json, fail) {
 // Read commands take the project and config directory, one total timeout and,
 // where the endpoint supports them, bounded days, limit and trace filters.
 // Out of range values fail here; nothing is clamped.
-function parseRead(command, values, json, fail) {
+function parseRead(command, values, flags, json, fail) {
   const paths = parsePaths(values, fail);
   if (!paths.ok) return paths;
   const rawTimeout = values["--timeout-ms"];
@@ -479,6 +513,29 @@ function parseRead(command, values, json, fail) {
     limit = values["--limit"] === undefined ? fallback : parseBounded(values["--limit"], 1, READ_MAX_LIMIT);
     if (limit === null) return fail("invalid_limit", `--limit must be a whole number from 1 to ${READ_MAX_LIMIT}.`);
   }
+  // Where to read and with which key: the same for every read, grouped usage
+  // included.
+  let origin = null;
+  if (values["--url"] !== undefined) {
+    origin = parseOrigin(values["--url"]);
+    if (origin === null) return fail("invalid_url", INVALID_URL);
+  }
+  const rawWorkspace = values["--workspace"];
+  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
+    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  }
+  const agentTokenFile = values["--agent-token-file"] ?? null;
+  if (agentTokenFile !== null && (agentTokenFile === "" || agentTokenFile.includes("\0"))) {
+    return fail("invalid_agent_token_file", "--agent-token-file must name a private absolute file.");
+  }
+  const target = {
+    origin,
+    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    agentTokenFile,
+  };
+  if (command === "usage" && (USAGE_GROUPED.some((name) => values[name] !== undefined) || flags.has("--today"))) {
+    return parseGroupedUsage(values, flags, json, fail, { paths, timeoutMs, limit, target });
+  }
   const route = values["--route"] ?? null;
   if (route !== null && !isSafeFilter(route)) {
     return fail("invalid_route", "--route must be 1 to 256 characters without control characters.");
@@ -494,9 +551,12 @@ function parseRead(command, values, json, fail) {
       "--cursor must be the next_cursor value from an earlier traces result, at most 512 printable characters.",
     );
   }
-  return {
+  const metadata = parseMetadata(values, fail);
+  if (!metadata.ok) return metadata;
+  const parsed = {
     ok: true,
     command,
+    ...target,
     project: paths.project,
     configDir: paths.configDir,
     timeoutMs,
@@ -505,8 +565,307 @@ function parseRead(command, values, json, fail) {
     route,
     status,
     cursor,
+    metadata: metadata.filters,
+    groupByMetadata: null,
+    json,
+  };
+  // Measure the exact query the command will send (URLSearchParams encoding,
+  // every parameter), so an over-long one fails here and not after sign in.
+  const query = readQuery(parsed);
+  if (query !== null && query.toString().length > MAX_QUERY_LENGTH) {
+    return fail(
+      "query_too_long",
+      "The filters are too long to send in one request. Use fewer or shorter metadata values, or a shorter route or cursor.",
+    );
+  }
+  return parsed;
+}
+
+// Grouped usage: server-side groups by provider, model, route and UTC day,
+// with exact filters and a UTC window. The window is either a preset of whole
+// UTC days (--days N or --today: the current UTC day so far and the N - 1
+// whole UTC days before it) or an explicit --since/--until, never both.
+// Ranking other than by cost and the prior-period comparison are computed
+// from the returned groups and say when those groups are not all of them.
+function parseGroupedUsage(values, flags, json, fail, { paths, timeoutMs, limit, target }) {
+  // A "metadata.<key>" entry takes the rest of the value as the key, so a key
+  // may contain commas and dots; it must come last. --group-by-metadata KEY
+  // is the same dimension, appended last.
+  let groupBy = values["--group-by"] === undefined && values["--group-by-metadata"] !== undefined
+    ? []
+    : [...USAGE_DEFAULT_GROUP_BY];
+  if (values["--group-by"] !== undefined) {
+    const raw = values["--group-by"];
+    const at = raw.startsWith(METADATA_PREFIX) ? 0 : raw.indexOf(`,${METADATA_PREFIX}`);
+    const plain = at === -1 ? raw : raw.slice(0, Math.max(0, at));
+    const metadataPart = at === -1 ? null : raw.slice(at === 0 ? 0 : at + 1);
+    const parts = plain === "" ? [] : plain.split(",").map((part) => part.trim());
+    if (
+      (parts.length === 0 && metadataPart === null) ||
+      !parts.every((part) => USAGE_DIMENSIONS.includes(part)) ||
+      new Set(parts).size !== parts.length
+    ) {
+      return fail(
+        "invalid_group_by",
+        `--group-by must list distinct dimensions from ${USAGE_DIMENSIONS.join(", ")}, comma separated, ` +
+          "optionally ending with metadata.KEY.",
+      );
+    }
+    groupBy = metadataPart === null ? parts : [...parts, metadataPart];
+  }
+  if (values["--group-by-metadata"] !== undefined) {
+    if (groupBy.some((dimension) => dimension.startsWith(METADATA_PREFIX))) {
+      return fail("too_many_metadata_dimensions", "Group by at most one metadata key.");
+    }
+    groupBy = [...groupBy, `${METADATA_PREFIX}${values["--group-by-metadata"]}`];
+  }
+  const metadataDimension = groupBy.find((dimension) => dimension.startsWith(METADATA_PREFIX)) ?? null;
+  if (metadataDimension !== null) {
+    const problem = metadataKeyProblem(metadataDimension.slice(METADATA_PREFIX.length));
+    if (problem !== null) return fail(problem.code, `A metadata grouping key ${problem.message}`);
+  }
+  const filters = {};
+  for (const [option, key] of [["--route", "route"], ["--provider", "provider"], ["--model", "model"], ["--environment", "environment"]]) {
+    const list = values[option] ?? [];
+    if (list.length > USAGE_MAX_FILTER_VALUES) {
+      return fail("too_many_filter_values", `${option} may be given at most ${USAGE_MAX_FILTER_VALUES} times.`);
+    }
+    if (!list.every((value) => isSafeFilter(value) && value.trim() !== "")) {
+      return fail(`invalid_${key}`, `${option} must be 1 to 256 characters without control characters.`);
+    }
+    filters[key] = list.length === 0 ? null : [...new Set(list)];
+  }
+  const today = flags.has("--today");
+  const rawSince = values["--since"];
+  const rawUntil = values["--until"];
+  const explicit = rawSince !== undefined || rawUntil !== undefined;
+  if ([today, explicit, values["--days"] !== undefined].filter(Boolean).length > 1) {
+    return fail("window_conflict", "Use one window: --days N, --today, or --since with an optional --until.");
+  }
+  let days = null;
+  let since = null;
+  let until = null;
+  if (explicit) {
+    if (rawSince === undefined) return fail("invalid_window", "--until needs --since.");
+    since = utcInstant(rawSince);
+    until = rawUntil === undefined ? null : utcInstant(rawUntil);
+    if (since === null || (rawUntil !== undefined && until === null)) {
+      return fail(
+        "invalid_window",
+        "--since and --until must be a UTC date (YYYY-MM-DD, meaning 00:00 UTC) or an ISO 8601 timestamp with Z or an offset.",
+      );
+    }
+    const end = until === null ? Date.now() : Date.parse(until);
+    if (Date.parse(since) >= end) return fail("invalid_window", "--since must be before --until (or before now).");
+    if (end - Date.parse(since) > READ_MAX_DAYS * DAY_MS) {
+      return fail("invalid_window", `The window may span at most ${READ_MAX_DAYS} days.`);
+    }
+  } else {
+    days = today ? 1 : values["--days"] === undefined ? READ_DEFAULT_DAYS : parseBounded(values["--days"], 1, READ_MAX_DAYS);
+    if (days === null) return fail("invalid_days", `--days must be a whole number from 1 to ${READ_MAX_DAYS}.`);
+  }
+  const sort = values["--sort"] ?? (groupBy.length === 1 && groupBy[0] === "day" ? "day" : "cost");
+  if (!USAGE_SORTS.includes(sort)) return fail("invalid_sort", `--sort must be one of ${USAGE_SORTS.join(", ")}.`);
+  if (sort === "day" && !groupBy.includes("day")) {
+    return fail("invalid_sort", "--sort day needs day in --group-by.");
+  }
+  const compare = values["--compare"] ?? null;
+  if (compare !== null && !USAGE_COMPARISONS.includes(compare)) {
+    return fail("invalid_compare", `--compare must be ${USAGE_COMPARISONS.join(" or ")}.`);
+  }
+  if (compare !== null && groupBy.includes("day")) {
+    return fail(
+      "compare_with_day_grouping",
+      "--compare matches groups across two windows, and a UTC day is never in both. " +
+        "For a trend, use --group-by day without --compare.",
+    );
+  }
+  const metadata = parseMetadata(values, fail);
+  if (!metadata.ok) return metadata;
+  const parsed = {
+    ok: true,
+    command: "usage",
+    ...target,
+    project: paths.project,
+    configDir: paths.configDir,
+    timeoutMs,
+    days,
+    limit,
+    route: null,
+    status: null,
+    cursor: null,
+    metadata: metadata.filters,
+    groupByMetadata: metadataDimension === null ? null : metadataDimension.slice(METADATA_PREFIX.length),
+    grouped: { groupBy, filters, since, until, today, sort, compare },
     json,
   };
+  // Measure the exact query the read sends, and for --compare the prior
+  // window's query, which carries two timestamps.
+  const longest = [readQuery(parsed)];
+  if (compare !== null) {
+    const stamp = "0000-00-00T00:00:00.000Z";
+    longest.push(readQuery(parsed, { ...groupedRequest(parsed), days: null, since: stamp, until: stamp }));
+  }
+  if (longest.some((query) => query.toString().length > MAX_QUERY_LENGTH)) {
+    return fail(
+      "query_too_long",
+      "The filters are too long to send in one request. Use fewer or shorter --route, --provider, --model, " +
+        "--environment or --metadata values.",
+    );
+  }
+  return parsed;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const METADATA_PREFIX = "metadata.";
+const UTC_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const ZONED_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+// A window bound as a UTC ISO 8601 string, or null. A date alone is 00:00
+// UTC; a timestamp must carry Z or an offset, so a local time is never read
+// as UTC by accident.
+function utcInstant(raw) {
+  if (typeof raw !== "string" || raw.length > 40) return null;
+  const text = UTC_DATE.test(raw) ? `${raw}T00:00:00Z` : ZONED_TIME.test(raw) ? raw : null;
+  if (text === null) return null;
+  const parsed = Date.parse(text);
+  if (!Number.isFinite(parsed)) return null;
+  // Reject calendar values the parser would roll over, such as 2026-02-30 or
+  // 2026-09-31T12:00:00Z, rather than read a different instant.
+  const [year, month, day] = text.slice(0, 10).split("-").map(Number);
+  const calendar = new Date(Date.UTC(year, month - 1, day));
+  if (calendar.getUTCFullYear() !== year || calendar.getUTCMonth() !== month - 1 || calendar.getUTCDate() !== day) {
+    return null;
+  }
+  const time = /T(\d{2}):(\d{2})(?::(\d{2}))?/.exec(text);
+  if (time && (Number(time[1]) > 23 || Number(time[2]) > 59 || Number(time[3] ?? 0) > 59)) return null;
+  const offset = /([+-])(\d{2}):(\d{2})$/.exec(text);
+  if (offset && (Number(offset[2]) > 23 || Number(offset[3]) > 59)) return null;
+  return new Date(parsed).toISOString();
+}
+
+// Exact customer-metadata filters. --metadata KEY=VALUE splits at the first
+// "=", so a value may contain "=" and a key may not; --metadata-json takes one
+// JSON object for keys with "=" or values that are awkward to quote. Values
+// are opaque strings: nothing is trimmed, case folded or split on a prefix.
+// Returns filters sorted by key, or null when none were given.
+function parseMetadata(values, fail) {
+  const pairs = values["--metadata"] ?? [];
+  const raw = values["--metadata-json"];
+  if (pairs.length > 0 && raw !== undefined) {
+    return fail("metadata_conflict", "Use --metadata or --metadata-json, not both.");
+  }
+  const entries = [];
+  if (raw !== undefined) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return fail("invalid_metadata", '--metadata-json must be a JSON object such as {"prompt_id":"p-1"}.');
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return fail("invalid_metadata", '--metadata-json must be a JSON object such as {"prompt_id":"p-1"}.');
+    }
+    if (duplicateJsonKey(raw)) {
+      return fail("duplicate_metadata_key", "A metadata key may be given only once.");
+    }
+    entries.push(...Object.entries(parsed));
+  } else {
+    for (const pair of pairs) {
+      const equals = pair.indexOf("=");
+      if (equals <= 0) {
+        return fail(
+          "invalid_metadata",
+          "--metadata must be KEY=VALUE with a non-empty key. Use --metadata-json for a key that contains \"=\".",
+        );
+      }
+      entries.push([pair.slice(0, equals), pair.slice(equals + 1)]);
+    }
+  }
+  if (entries.length === 0) return { ok: true, filters: null };
+  if (entries.length > MAX_METADATA_FILTERS) {
+    return fail("too_many_metadata_filters", `At most ${MAX_METADATA_FILTERS} metadata keys may be given.`);
+  }
+  const seen = new Set();
+  for (const [key, value] of entries) {
+    const problem = metadataKeyProblem(key);
+    if (problem !== null) return fail(problem.code, `A metadata key ${problem.message}`);
+    if (seen.has(key)) return fail("duplicate_metadata_key", "A metadata key may be given only once.");
+    seen.add(key);
+    if (typeof value !== "string") {
+      return fail("invalid_metadata", "Metadata values must be strings; they are matched as exact opaque text.");
+    }
+    if (value.length > MAX_METADATA_VALUE_LENGTH || value.includes("\0")) {
+      return fail(
+        "invalid_metadata",
+        `A metadata value must be at most ${MAX_METADATA_VALUE_LENGTH} characters without NUL.`,
+      );
+    }
+  }
+  const filters = entries
+    .map(([key, value]) => ({ key, value }))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return { ok: true, filters };
+}
+
+// JSON.parse keeps the last of two equal keys; the service refuses them, so
+// the CLI refuses them first instead of silently sending one. Scans the
+// already valid JSON text for the top-level object's keys.
+function duplicateJsonKey(raw) {
+  const keys = new Set();
+  let depth = 0;
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index];
+    if (char === "{" || char === "[") depth += 1;
+    else if (char === "}" || char === "]") depth -= 1;
+    else if (char === '"') {
+      let end = index + 1;
+      while (raw[end] !== '"') end += raw[end] === "\\" ? 2 : 1;
+      const token = raw.slice(index, end + 1);
+      let next = end + 1;
+      while (/\s/.test(raw[next] ?? "")) next += 1;
+      if (depth === 1 && raw[next] === ":") {
+        const key = JSON.parse(token);
+        if (keys.has(key)) return true;
+        keys.add(key);
+      }
+      index = end;
+    }
+  }
+  return false;
+}
+
+// Matches the service's rule: lowercased, everything but letters and digits
+// removed, the key must not end in one of these.
+const SENSITIVE_KEY_SUFFIXES = Object.freeze([
+  "accesskey", "apikey", "auth", "authorization", "bearer", "clientsecret", "cookie",
+  "credential", "credentials", "encryptionkey", "jwt", "passwd", "password", "privatekey",
+  "secret", "secretkey", "sessionkey", "signingkey", "token",
+]);
+
+function metadataKeyProblem(key) {
+  // Keys are printed back (filter and grouping lines), so control and
+  // formatting characters that could rewrite terminal or log output are
+  // refused, as they are for every other printed name.
+  if (
+    typeof key !== "string" ||
+    key.length === 0 ||
+    key.length > MAX_METADATA_KEY_LENGTH ||
+    hasUnsafeText(key)
+  ) {
+    return {
+      code: "invalid_metadata_key",
+      message: `must be 1 to ${MAX_METADATA_KEY_LENGTH} characters without control or formatting characters.`,
+    };
+  }
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (SENSITIVE_KEY_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+    return {
+      code: "metadata_key_ineligible",
+      message: "looks like a credential name and cannot be used for filtering or grouping.",
+    };
+  }
+  return null;
 }
 
 function parseBounded(raw, min, max) {

package/src/auth-browser.js

@@ -1,6 +1,8 @@
 import childProcess from "node:child_process";
 import path from "node:path";
 
+import { classifyEnvironment } from "./environment.js";
+
 // Opens a URL with the operating system's own launcher: a fixed executable
 // and an argument array, never a shell. The URL is the authorization request
 // (public client ID, state and PKCE challenge); no token, code or verifier is
@@ -51,24 +53,8 @@ export function systemRoot() {
   return "C:\\Windows";
 }
 
-// Variables whose presence means the browser a person uses is not on this
-// machine, or no person is present. Only presence is checked; values are
-// never read into output.
-const REMOTE_MARKERS = [
-  ["ssh_session", ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"]],
-  ["cloud_workspace", ["CODESPACES", "GITPOD_WORKSPACE_ID", "CLOUD_SHELL"]],
-  ["ci_environment", ["CI"]],
-];
-
-// Returns null for an ordinary local session, or a fixed reason token.
+// Returns null for an ordinary local session (including a local container),
+// or the fixed reason token of a remote or CI session. See environment.js.
 export function detectRemoteSession(env = process.env) {
-  for (const [reason, names] of REMOTE_MARKERS) {
-    for (const name of names) {
-      const value = env[name];
-      if (typeof value === "string" && value !== "" && value !== "0" && value.toLowerCase() !== "false") {
-        return reason;
-      }
-    }
-  }
-  return null;
+  return classifyEnvironment(env, { fileExists: () => false }).reason;
 }

package/src/auth-callback.js

@@ -1,6 +1,8 @@
 import { timingSafeEqual } from "node:crypto";
 import http from "node:http";
 
+import { PAGE_CSP, PAGES } from "./callback-page.js";
+
 // Loopback listener for the OAuth redirect (RFC 8252 section 7.3). It binds
 // 127.0.0.1 on an ephemeral port and accepts exactly one callback: a GET on
 // the fixed path, with the exact Host, one state that matches, and either one
@@ -14,23 +16,19 @@ const HOST = "127.0.0.1";
 const MAX_URL_LENGTH = 4096;
 const MAX_CODE_LENGTH = 2048;
 const ALLOWED_PARAMS = new Set(["code", "state", "error", "error_description", "error_uri", "iss"]);
+// The setup receipt a combined sign-in approval returns next to the code.
+// Accepted only by a wait that asked for it.
+export const SETUP_CODE_PARAM = "ingest_setup_code";
 
 const PAGE_HEADERS = {
   "content-type": "text/html; charset=utf-8",
   "cache-control": "no-store",
-  "content-security-policy": "default-src 'none'",
+  "content-security-policy": PAGE_CSP,
   "referrer-policy": "no-referrer",
   "x-content-type-options": "nosniff",
   "x-frame-options": "DENY",
   connection: "close",
 };
-const page = (text) =>
-  `<!doctype html><meta charset="utf-8"><title>Metergraph CLI</title><p>${text}</p>\n`;
-const PAGES = {
-  done: page("Metergraph CLI: authorization received. You can close this tab and return to the terminal."),
-  failed: page("Metergraph CLI: authorization did not complete. Return to the terminal for details."),
-  invalid: page("Metergraph CLI: this request was not accepted."),
-};
 
 // Starts listening. Resolves with { redirectUri, wait, close }.
 //   wait({ state, issuer, requireIss, timeoutMs, cancel }) arms the listener
@@ -38,7 +36,9 @@ const PAGES = {
 //     accepted and the timeout is running. Call it before the authorization
 //     URL is opened or printed, so a fast browser can never reach an unarmed
 //     listener. It may be called once. The promise resolves with
-//     { kind: "code", code }
+//     { kind: "code", code[, setupCode] } setupCode, the ingest_setup_code
+//                                         value, only when wait() was given
+//                                         acceptSetupCode and it was sent
 //     { kind: "denied" }                  the user or server declined
 //     { kind: "error", reason }           authorization_error,
 //                                         callback_issuer_mismatch or
@@ -85,7 +85,7 @@ export async function startCallbackListener() {
     await done;
   };
 
-  const wait = ({ state, issuer, requireIss, timeoutMs, cancel }) => {
+  const wait = ({ state, issuer, requireIss, timeoutMs, cancel, acceptSetupCode = false }) => {
     if (armed) throw new Error("callback listener is already armed");
     armed = true;
     // The executor runs synchronously, so the handler and timer are in
@@ -105,7 +105,7 @@ export async function startCallbackListener() {
 
       handler = (request, response) => {
         if (settled) return respond(response, 410, PAGES.invalid);
-        const verdict = inspect(request, { host, state, issuer, requireIss });
+        const verdict = inspect(request, { host, state, issuer, requireIss, acceptSetupCode });
         if (verdict.result === undefined) return respond(response, verdict.status, PAGES.invalid);
         const result = verdict.result;
         respond(response, verdict.status, result.kind === "code" ? PAGES.done : PAGES.failed);
@@ -131,7 +131,7 @@ function respond(response, status, body) {
 
 // Returns { status } for a request that is ignored, or { status, result }
 // for the one request that ends the flow.
-function inspect(request, { host, state, issuer, requireIss }) {
+function inspect(request, { host, state, issuer, requireIss, acceptSetupCode }) {
   const url = request.url ?? "";
   if (url.length > MAX_URL_LENGTH) return { status: 414 };
   if (request.method !== "GET") return { status: 405 };
@@ -148,7 +148,9 @@ function inspect(request, { host, state, issuer, requireIss }) {
   }
   const seen = new Set();
   for (const key of params.keys()) {
-    if (!ALLOWED_PARAMS.has(key) || seen.has(key)) return { status: 400 };
+    if (!(ALLOWED_PARAMS.has(key) || (acceptSetupCode && key === SETUP_CODE_PARAM)) || seen.has(key)) {
+      return { status: 400 };
+    }
     seen.add(key);
   }
   // Only a request that carries this flow's exact state can end it.
@@ -158,7 +160,9 @@ function inspect(request, { host, state, issuer, requireIss }) {
     return { status: 400, result: { kind: "error", reason: "callback_issuer_mismatch" } };
   }
   if (seen.has("error")) {
-    if (seen.has("code")) return { status: 400, result: { kind: "error", reason: "callback_invalid" } };
+    if (seen.has("code") || seen.has(SETUP_CODE_PARAM)) {
+      return { status: 400, result: { kind: "error", reason: "callback_invalid" } };
+    }
     return params.get("error") === "access_denied"
       ? { status: 200, result: { kind: "denied" } }
       : { status: 200, result: { kind: "error", reason: "authorization_error" } };
@@ -167,7 +171,12 @@ function inspect(request, { host, state, issuer, requireIss }) {
   if (code === null || code.length === 0 || code.length > MAX_CODE_LENGTH || /[^\x21-\x7e]/.test(code)) {
     return { status: 400, result: { kind: "error", reason: "callback_invalid" } };
   }
-  return { status: 200, result: { kind: "code", code } };
+  if (!seen.has(SETUP_CODE_PARAM)) return { status: 200, result: { kind: "code", code } };
+  const setupCode = params.get(SETUP_CODE_PARAM);
+  if (setupCode.length === 0 || setupCode.length > MAX_CODE_LENGTH || /[^\x21-\x7e]/.test(setupCode)) {
+    return { status: 400, result: { kind: "error", reason: "callback_invalid" } };
+  }
+  return { status: 200, result: { kind: "code", code, setupCode } };
 }
 
 function sameText(actual, expected) {