metergraph-cli 0.1.0 → 0.2.0-preview.1

package/src/auth-binding.js

@@ -0,0 +1,202 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { Stop, isSlot } from "./auth-store.js";
+import { SUPPORTED_PROFILES } from "./constants.js";
+import { parseOrigin } from "./origin.js";
+
+// The project binding, .metergraph/project.json, names which origin,
+// workspace and profile a project is signed in to and which credential slot
+// in the user's private store holds the grant. It holds no credential, user
+// name or absolute path, so it is safe to commit. Other files in .metergraph,
+// such as skill receipts, are never touched.
+
+export const BINDING_PATH = ".metergraph/project.json";
+const DIR = ".metergraph";
+const FILE = "project.json";
+const LOCK = "project.lock";
+const MAX_BYTES = 16 * 1024;
+const KEYS = ["credential_slot", "deployment_profile", "origin", "schema_version", "workspace_id"].join();
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+
+export function resolveProject(project) {
+  try {
+    const real = fs.realpathSync(path.resolve(project ?? process.cwd()));
+    if (fs.statSync(real).isDirectory()) return real;
+  } catch {
+    // Fall through to the fixed error.
+  }
+  throw new Stop("invalid_input", "invalid_project");
+}
+
+// Returns { binding, content } or null when the project is not bound.
+export function readBinding(root) {
+  try {
+    const dir = lstatOrNull(path.join(root, DIR));
+    if (dir === null) return null;
+    if (!dir.isDirectory()) throw new Stop("conflict", "unsafe_path");
+    const content = readRegular(path.join(root, DIR, FILE));
+    if (content === null) return null;
+    const binding = parse(content);
+    if (binding === null) throw new Stop("conflict", "binding_invalid");
+    return { binding, content };
+  } catch (error) {
+    if (error instanceof Stop) throw error;
+    throw new Stop("filesystem_error", "read_failed");
+  }
+}
+
+export function bindingFor({ origin, workspaceId, profile, slot }) {
+  return {
+    schema_version: 1,
+    origin,
+    workspace_id: workspaceId,
+    deployment_profile: profile,
+    credential_slot: slot,
+  };
+}
+
+// Writes binding in place of previous (the { content } readBinding saw, or
+// null). Under the project lock, the file must still be exactly previous, so
+// a concurrent change is never overwritten. A failed write leaves the
+// previous file and removes a .metergraph directory this call created.
+export function writeBinding(root, binding, previous) {
+  const content = Buffer.from(`${JSON.stringify(binding, null, 2)}\n`);
+  if (parse(content) === null) throw new Error("binding is not valid");
+  const dir = path.join(root, DIR);
+  let created = false;
+  try {
+    try {
+      fs.mkdirSync(dir);
+      created = true;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (!fs.lstatSync(dir).isDirectory()) throw new Stop("conflict", "unsafe_path");
+    }
+    withProjectLock(dir, () => {
+      expectUnchanged(dir, previous);
+      replace(dir, content);
+    });
+  } catch (error) {
+    if (created) {
+      try {
+        fs.rmdirSync(dir);
+      } catch {
+        // Not empty. An empty directory is harmless.
+      }
+    }
+    if (error instanceof Stop) throw error;
+    throw new Stop("filesystem_error", "binding_write_failed");
+  }
+}
+
+// Removes the binding if it is still exactly previous.
+export function removeBinding(root, previous) {
+  const dir = path.join(root, DIR);
+  try {
+    withProjectLock(dir, () => {
+      expectUnchanged(dir, previous);
+      fs.unlinkSync(path.join(dir, FILE));
+    });
+  } catch (error) {
+    if (error instanceof Stop) throw error;
+    throw new Stop("filesystem_error", "binding_write_failed");
+  }
+}
+
+function withProjectLock(dir, work) {
+  const lock = path.join(dir, LOCK);
+  try {
+    fs.closeSync(fs.openSync(lock, "wx"));
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Stop("conflict", "binding_locked");
+    throw error;
+  }
+  try {
+    return work();
+  } finally {
+    try {
+      fs.unlinkSync(lock);
+    } catch {
+      // Reported by the next run as a held lock.
+    }
+  }
+}
+
+function expectUnchanged(dir, previous) {
+  const now = readRegular(path.join(dir, FILE));
+  const same = previous === null ? now === null : now !== null && now.equals(previous.content);
+  if (!same) throw new Stop("conflict", "binding_changed");
+}
+
+function replace(dir, content) {
+  const dest = path.join(dir, FILE);
+  const temp = path.join(dir, `.${FILE}.${randomBytes(6).toString("hex")}.tmp`);
+  const fd = fs.openSync(temp, "wx", 0o666);
+  try {
+    try {
+      fs.writeFileSync(fd, content);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(temp, dest);
+  } catch (error) {
+    try {
+      fs.unlinkSync(temp);
+    } catch {
+      // Already renamed or never created.
+    }
+    throw error;
+  }
+}
+
+// Accepts only the exact shape this CLI writes.
+function parse(content) {
+  let value;
+  try {
+    value = JSON.parse(content.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  if (Object.keys(value).sort().join() !== KEYS) return null;
+  if (value.schema_version !== 1) return null;
+  if (typeof value.origin !== "string" || parseOrigin(value.origin) !== value.origin) return null;
+  if (typeof value.workspace_id !== "string" || !UUID.test(value.workspace_id)) return null;
+  if (!SUPPORTED_PROFILES.includes(value.deployment_profile)) return null;
+  if (!isSlot(value.credential_slot)) return null;
+  return value;
+}
+
+function lstatOrNull(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function readRegular(file) {
+  const stat = lstatOrNull(file);
+  if (stat === null) return null;
+  if (!stat.isFile()) throw new Stop("conflict", "unsafe_path");
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ELOOP") throw new Stop("conflict", "unsafe_path");
+    throw error;
+  }
+  try {
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile()) throw new Stop("conflict", "unsafe_path");
+    if (opened.size > MAX_BYTES) throw new Stop("conflict", "binding_invalid");
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}

package/src/auth-browser.js

@@ -0,0 +1,74 @@
+import childProcess from "node:child_process";
+import path from "node:path";
+
+// 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
+// ever on a command line. Resolves true when the launcher started, false
+// when it could not be started. A started launcher does not prove that a
+// browser opened, so callers still wait for the callback with a deadline.
+export function openBrowser(url) {
+  const { command, args } = launcher();
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = childProcess.spawn(command, [...args, url], {
+        shell: false,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+    child.once("error", () => resolve(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}
+
+function launcher() {
+  if (process.platform === "darwin") return { command: "/usr/bin/open", args: [] };
+  if (process.platform === "win32") {
+    return {
+      command: path.win32.join(systemRoot(), "System32", "rundll32.exe"),
+      args: ["url.dll,FileProtocolHandler"],
+    };
+  }
+  return { command: "/usr/bin/xdg-open", args: [] };
+}
+
+// The Windows directory, from SystemRoot only when it is a plain absolute
+// drive path, otherwise the standard location.
+export function systemRoot() {
+  const value = process.env.SystemRoot;
+  if (typeof value === "string" && /^[A-Za-z]:\\[A-Za-z0-9 ._\\-]*$/.test(value) && !value.includes("..")) {
+    return value;
+  }
+  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.
+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;
+}

package/src/auth-callback.js

@@ -0,0 +1,177 @@
+import { timingSafeEqual } from "node:crypto";
+import http from "node:http";
+
+// 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
+// code or one error. Anything else is answered with a fixed page and the
+// listener keeps waiting, so a stray or forged request cannot end the flow.
+// Pages are static: no code, state or other request value is reflected, and
+// nothing about a request is logged.
+
+export const CALLBACK_PATH = "/callback";
+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"]);
+
+const PAGE_HEADERS = {
+  "content-type": "text/html; charset=utf-8",
+  "cache-control": "no-store",
+  "content-security-policy": "default-src 'none'",
+  "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
+//     synchronously: from the moment it returns, a matching callback is
+//     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: "denied" }                  the user or server declined
+//     { kind: "error", reason }           authorization_error,
+//                                         callback_issuer_mismatch or
+//                                         callback_invalid
+//     { kind: "timeout" } or { kind: "cancelled" }
+//   close() stops the listener, destroys every socket and settles a pending
+//   wait as cancelled, clearing its timer. It is safe to call more than once
+//   and must be called on every outcome, including early returns.
+export async function startCallbackListener() {
+  const sockets = new Set();
+  let handler = (request, response) => respond(response, 503, PAGES.invalid);
+  const server = http.createServer(
+    { maxHeaderSize: 8192, requestTimeout: 10000, headersTimeout: 10000 },
+    (request, response) => handler(request, response),
+  );
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+  });
+  server.on("clientError", (error, socket) => socket.destroy());
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, HOST, () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  const { port } = server.address();
+  const host = `${HOST}:${port}`;
+  const redirectUri = `http://${host}${CALLBACK_PATH}`;
+
+  let closed = false;
+  let armed = false;
+  // Settles the pending wait, if any. Replaced when wait() arms.
+  let settlePending = () => {};
+
+  const close = async () => {
+    settlePending({ kind: "cancelled" });
+    if (closed) return;
+    closed = true;
+    const done = new Promise((resolve) => server.close(() => resolve()));
+    for (const socket of sockets) socket.destroy();
+    await done;
+  };
+
+  const wait = ({ state, issuer, requireIss, timeoutMs, cancel }) => {
+    if (armed) throw new Error("callback listener is already armed");
+    armed = true;
+    // The executor runs synchronously, so the handler and timer are in
+    // place before wait() returns.
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer = null;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        if (timer !== null) clearTimeout(timer);
+        cancel?.removeEventListener("abort", onCancel);
+        resolve(result);
+      };
+      const onCancel = () => finish({ kind: "cancelled" });
+      settlePending = finish;
+
+      handler = (request, response) => {
+        if (settled) return respond(response, 410, PAGES.invalid);
+        const verdict = inspect(request, { host, state, issuer, requireIss });
+        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);
+        finish(result);
+      };
+
+      if (closed || cancel?.aborted) {
+        onCancel();
+        return;
+      }
+      timer = setTimeout(() => finish({ kind: "timeout" }), timeoutMs);
+      cancel?.addEventListener("abort", onCancel, { once: true });
+    });
+  };
+
+  return { redirectUri, wait, close };
+}
+
+function respond(response, status, body) {
+  response.writeHead(status, { ...PAGE_HEADERS, "content-length": Buffer.byteLength(body) });
+  response.end(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 }) {
+  const url = request.url ?? "";
+  if (url.length > MAX_URL_LENGTH) return { status: 414 };
+  if (request.method !== "GET") return { status: 405 };
+  if (request.headers.host !== host) return { status: 400 };
+  const mark = url.indexOf("?");
+  const pathname = mark === -1 ? url : url.slice(0, mark);
+  if (pathname !== CALLBACK_PATH) return { status: 404 };
+
+  let params;
+  try {
+    params = new URLSearchParams(mark === -1 ? "" : url.slice(mark + 1));
+  } catch {
+    return { status: 400 };
+  }
+  const seen = new Set();
+  for (const key of params.keys()) {
+    if (!ALLOWED_PARAMS.has(key) || seen.has(key)) return { status: 400 };
+    seen.add(key);
+  }
+  // Only a request that carries this flow's exact state can end it.
+  if (!seen.has("state") || !sameText(params.get("state"), state)) return { status: 400 };
+
+  if (seen.has("iss") ? params.get("iss") !== 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" } };
+    return params.get("error") === "access_denied"
+      ? { status: 200, result: { kind: "denied" } }
+      : { status: 200, result: { kind: "error", reason: "authorization_error" } };
+  }
+  const code = params.get("code");
+  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 } };
+}
+
+function sameText(actual, expected) {
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}