metergraph-cli 0.0.0-stage → 0.2.0-preview.0

package/src/constants.js

@@ -0,0 +1,176 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+export const PACKAGE_NAME = packageJson.name;
+export const VERSION = packageJson.version;
+
+export const SCHEMA_VERSION = 1;
+export const DEFAULT_ORIGIN = "https://app.metergraph.dev";
+
+export const DEFAULT_TIMEOUT_MS = 5000;
+export const MIN_TIMEOUT_MS = 100;
+export const MAX_TIMEOUT_MS = 30000;
+export const MAX_BODY_BYTES = 32 * 1024;
+
+// The public guide a person follows to connect an application to Metergraph.
+// It is the next action wherever the CLI itself cannot help, such as doctor
+// results and sign in from a cloud runtime.
+export const CONNECTION_GUIDE_URL =
+  "https://www.metergraph.dev/docs/guides/agent-access/";
+
+// Deployment profiles recognized by the probe contract. Any other value,
+// including a well-formed one, is reported as unsupported and never echoed.
+export const SUPPORTED_PROFILES = Object.freeze([
+  "local",
+  "managed",
+  "byoc-core",
+]);
+
+// Clients that load project skills from a native directory, from each
+// client's own documentation. Every client has its own directory, so
+// installing for one never touches another client's files.
+export const SKILL_CLIENTS = Object.freeze({
+  codex: Object.freeze({ label: "Codex", dir: ".agents" }),
+  claude: Object.freeze({ label: "Claude Code", dir: ".claude" }),
+  cursor: Object.freeze({ label: "Cursor", dir: ".cursor" }),
+});
+export const SKILL_RUNTIMES = Object.freeze(["local", "cloud"]);
+
+// Recognized values that cannot load project skill files. They get a pointer
+// to the connection guide instead of a usage error, and nothing is written.
+export const HANDOFF_SKILL_CLIENTS = Object.freeze({
+  "claude-desktop": "Claude Desktop",
+  chatgpt: "ChatGPT",
+});
+export const HANDOFF_SKILL_RUNTIMES = Object.freeze(["cloud-no-shell"]);
+
+// Sign in needs a browser on the same machine as the CLI, because the browser
+// hands the authorization back to a loopback listener. Other runtimes are
+// recognized so they get a handoff instead of a usage error.
+export const LOGIN_RUNTIMES = Object.freeze(["local"]);
+export const HANDOFF_LOGIN_RUNTIMES = Object.freeze(["cloud", "cloud-no-shell"]);
+
+// How long login waits for the browser to finish, and the fixed deadline for
+// each group of HTTP requests around it.
+export const LOGIN_DEFAULT_TIMEOUT_MS = 300000;
+export const LOGIN_MIN_TIMEOUT_MS = 1000;
+export const LOGIN_MAX_TIMEOUT_MS = 900000;
+export const AUTH_HTTP_TIMEOUT_MS = 15000;
+
+// The only scope this CLI requests. It never asks for agent:read (Debug) or
+// agent:replay, and never falls back to them.
+export const METADATA_SCOPE = "agent:metadata";
+
+// The service's agent access contract version, as sent in schema_version by
+// GET /v1/agent/workspace and GET /v1/agent/capabilities. It is the
+// service's own string and is unrelated to SCHEMA_VERSION, the version of
+// this CLI's JSON output.
+export const AGENT_CONTRACT_VERSION = "metergraph.agent-access/v1";
+
+// Exact paths on the chosen origin. Discovered metadata must name exactly
+// these, so a tampered document cannot send the CLI anywhere else.
+export const AUTH_PATHS = Object.freeze({
+  resource: "/v1/agent/mcp",
+  issuer: "/v1/oauth",
+  authorization: "/v1/oauth/authorize",
+  token: "/v1/oauth/token",
+  registration: "/v1/oauth/register",
+  revocation: "/v1/oauth/revoke",
+  signup: "/v1/auth/signup",
+  workspace: "/v1/agent/workspace",
+  capabilities: "/v1/agent/capabilities",
+});
+
+// Bearer-protected Metadata read endpoints. They are fixed paths on the bound
+// origin; the transport accepts a query string only on the paths listed in
+// READ_QUERY_KEYS, and only with those keys. GET /v1/agent/routes takes no
+// query at all, so its rows are bounded by the response size limit and cut to
+// --limit locally.
+export const READ_PATHS = Object.freeze({
+  usage: "/v1/agent/usage",
+  routes: "/v1/agent/routes",
+  traces: "/v1/agent/traces",
+});
+export const READ_QUERY_KEYS = Object.freeze({
+  "/v1/agent/usage": Object.freeze(["days", "limit"]),
+  "/v1/agent/traces": Object.freeze(["days", "limit", "route", "status", "cursor"]),
+  "/v1/cli/setup/credential": Object.freeze(["family_id"]),
+});
+
+// Read commands share one total deadline for every request they make,
+// including a token refresh. It is never reset per request or page.
+export const READ_DEFAULT_TIMEOUT_MS = 15000;
+export const READ_MIN_TIMEOUT_MS = 1000;
+export const READ_MAX_TIMEOUT_MS = 60000;
+// A client bound below the service's own max_response_bytes. A larger body is
+// discarded and reported as response_too_large, never read further.
+export const READ_MAX_BYTES = 1024 * 1024;
+export const READ_MAX_DAYS = 90;
+export const READ_MAX_LIMIT = 200;
+export const READ_DEFAULT_DAYS = 7;
+export const READ_DEFAULT_LIMIT = 50;
+export const TRACES_DEFAULT_LIMIT = 20;
+export const MAX_CURSOR_LENGTH = 512;
+export const MAX_FILTER_LENGTH = 256;
+
+// One exit code per outcome. Documented in README.md; changing a value is a
+// breaking change for scripts. New outcomes are appended.
+export const EXIT_CODES = Object.freeze({
+  ok: 0,
+  internal_error: 1,
+  invalid_input: 2,
+  authentication_required: 3,
+  connection_failed: 4,
+  unhealthy: 5,
+  unsupported: 6,
+  redirect_rejected: 7,
+  conflict: 8,
+  filesystem_error: 9,
+  authorization_failed: 10,
+  verification_failed: 11,
+  login_required: 12,
+  revocation_unconfirmed: 13,
+  capability_unavailable: 14,
+  permission_denied: 15,
+  rate_limited: 16,
+  cancelled: 17,
+});
+
+export const EXIT_CODE_MEANINGS = Object.freeze({
+  ok: "Command succeeded. Doctor does not return this in this preview.",
+  internal_error: "Unexpected internal failure in the CLI.",
+  invalid_input: "Unknown command or argument, or an invalid option value. No request was made.",
+  authentication_required:
+    "Service is reachable, healthy and supported, and requires authentication. No workspace is connected.",
+  connection_failed: "The origin could not be reached, the connection failed, or the probe timed out.",
+  unhealthy:
+    "The service answered but reported that it is not healthy, or answered with a server error.",
+  unsupported:
+    "The service answered with a response, deployment profile or status this CLI does not support, " +
+    "or the skill client or runtime cannot use project skill files, " +
+    "or sign in cannot run in this environment. Nothing was written.",
+  redirect_rejected: "The service answered with a redirect. Redirects are never followed.",
+  conflict:
+    "The skill target is not owned by this CLI, was modified, is unsafe, is locked or needs an explicit update, " +
+    "or the project is bound to a different origin or workspace. Nothing was changed.",
+  filesystem_error:
+    "Project or credential files could not be read or written. Partial changes were rolled back unless the message says otherwise.",
+  authorization_failed:
+    "Browser authorization did not finish: it was denied, cancelled, timed out or returned an invalid callback. Nothing was saved.",
+  verification_failed:
+    "The service issued a grant that does not match the requested origin, workspace, client, resource or Metadata scope. Nothing was saved.",
+  login_required:
+    "No usable sign in for this project: none was saved, it expired, was revoked, lost access or could not be refreshed safely. Run login again.",
+  revocation_unconfirmed:
+    "Local credentials were removed, but the service did not confirm that the grant was revoked.",
+  capability_unavailable:
+    "The service does not make this read available to the project's Metadata grant. No data was read.",
+  permission_denied:
+    "The service refused this read for the signed in grant, for example for a missing scope or permission.",
+  rate_limited: "The service asked the CLI to slow down. Nothing was retried. Try again later.",
+  cancelled:
+    "A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry.",
+});

package/src/deployment-credential.js

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Reads the separate Metadata agent credential for deployment verification
+// from one explicit, absolute, private file. There is no argv, stdin or
+// environment variable form. The file is read, never copied, written or
+// persisted, and the token is returned only to the verifier that asked for
+// it. Results are { ok: true, token } or { ok: false, outcome, reason } with
+// fixed tokens: no path, file content or system error text is ever returned.
+//
+// The file must be a regular file owned by the current user with mode 0600
+// and exactly one link, holding one bearer token and at most one trailing
+// newline. No component of the path may be a symbolic link, so callers pass
+// the canonical path (on macOS, /private/var/... rather than /var/...). The
+// directory holding the file must be owned by the current user or root and
+// must not be writable by group or others. Higher directories may be writable
+// by others only when the sticky bit is set, which is how shared temporary
+// directories such as /tmp are protected; the file's own directory gets no
+// such allowance.
+//
+// Windows has no owner-only mode bits to check, and this CLI has no proof of
+// a file's ACL, so the read fails closed there with a platform handoff.
+
+const MAX_PATH_LENGTH = 4096;
+// No token is shorter than this, so a fixed string that is shorter can never
+// contain one.
+export const CREDENTIAL_MIN_LENGTH = 16;
+const TOKEN = new RegExp(`^[\\x21-\\x7e]{${CREDENTIAL_MIN_LENGTH},8192}$`);
+// The longest token plus a CRLF line ending.
+export const CREDENTIAL_MAX_BYTES = 8192 + 2;
+
+const OPEN_FLAGS =
+  fs.constants.O_RDONLY |
+  (fs.constants.O_NOFOLLOW ?? 0) |
+  // A FIFO opened without O_NONBLOCK blocks until a writer appears.
+  (fs.constants.O_NONBLOCK ?? 0) |
+  (fs.constants.O_NOCTTY ?? 0);
+
+const fail = (reason) => ({ ok: false, outcome: "filesystem_error", reason });
+
+// options.afterOpen and options.afterRead are test seams only: afterOpen runs
+// after the file is opened and before it is checked, afterRead after the
+// content is read and before it is checked again, so a test can replace,
+// rewrite or chmod the file in between.
+export function readCredentialFile(file, { platform = process.platform, afterOpen = null, afterRead = null } = {}) {
+  if (platform === "win32") return { ok: false, outcome: "unsupported", reason: "platform_credential_handoff" };
+  if (!validPath(file)) return fail("credential_path_invalid");
+  const uid = process.getuid();
+
+  const parents = checkParents(file, uid);
+  if (!parents.ok) return parents;
+
+  let before;
+  try {
+    before = fs.lstatSync(file, { bigint: true });
+  } catch (error) {
+    return fail(error?.code === "ENOENT" ? "credential_missing" : "credential_unreadable");
+  }
+  if (before.isSymbolicLink()) return fail("credential_symlink");
+  const problem = credentialStatProblem(before, uid);
+  if (problem !== null) return fail(problem);
+
+  let fd;
+  try {
+    fd = fs.openSync(file, OPEN_FLAGS);
+  } catch (error) {
+    if (error?.code === "ELOOP") return fail("credential_symlink");
+    return fail(error?.code === "ENOENT" ? "credential_changed" : "credential_unreadable");
+  }
+  let buffer = null;
+  try {
+    if (afterOpen !== null) afterOpen();
+    const opened = fs.fstatSync(fd, { bigint: true });
+    // No links left means the name was moved away or replaced after the open.
+    if (opened.nlink === 0n) return fail("credential_changed");
+    const openedProblem = credentialStatProblem(opened, uid);
+    if (openedProblem !== null) return fail(openedProblem);
+    if (!sameInode(opened, before)) return fail("credential_changed");
+
+    buffer = Buffer.alloc(CREDENTIAL_MAX_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = fs.readSync(fd, buffer, length, buffer.length - length, length);
+      if (count === 0) break;
+      length += count;
+    }
+    if (length > CREDENTIAL_MAX_BYTES) return fail("credential_too_large");
+    if (afterRead !== null) afterRead();
+
+    // After the read the file must still pass every check and be the same
+    // file with the same metadata. Rewriting it in place, even with content
+    // of the same length, or changing its mode, owner or links moves ctime or
+    // mtime, which are compared to the nanosecond.
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (after.nlink === 0n) return fail("credential_changed");
+    const afterProblem = credentialStatProblem(after, uid);
+    if (afterProblem !== null) return fail(afterProblem);
+    if (!unchanged(after, opened) || after.size !== BigInt(length)) return fail("credential_changed");
+    let current;
+    try {
+      current = fs.lstatSync(file, { bigint: true });
+    } catch {
+      return fail("credential_changed");
+    }
+    if (!unchanged(current, opened)) return fail("credential_changed");
+    // Every directory above it must still be the ones checked.
+    const again = checkParents(file, uid);
+    if (!again.ok) return again;
+    if (again.inodes.some((inode, index) => !sameInode(inode, parents.inodes[index]))) {
+      return fail("credential_changed");
+    }
+
+    return parseToken(buffer.subarray(0, length));
+  } catch {
+    return fail("credential_unreadable");
+  } finally {
+    if (buffer !== null) buffer.fill(0);
+    fs.closeSync(fd);
+  }
+}
+
+// Returns a fixed reason when a stat of the credential file is not a private,
+// owner-only, singly linked regular file of a usable size, otherwise null.
+// Accepts number or bigint stats. Exported for tests that cannot create files
+// owned by another user.
+export function credentialStatProblem(stat, uid) {
+  if (!stat.isFile()) return "credential_not_regular";
+  if (Number(stat.uid) !== uid) return "credential_not_owner";
+  if ((Number(stat.mode) & 0o7777) !== 0o600) return "credential_permissions_unsafe";
+  if (Number(stat.nlink) !== 1) return "credential_hardlinked";
+  if (Number(stat.size) === 0) return "credential_empty";
+  if (Number(stat.size) > CREDENTIAL_MAX_BYTES) return "credential_too_large";
+  return null;
+}
+
+function validPath(file) {
+  return (
+    typeof file === "string" &&
+    file.length > 1 &&
+    file.length <= MAX_PATH_LENGTH &&
+    !file.includes("\0") &&
+    path.isAbsolute(file) &&
+    path.normalize(file) === file &&
+    !file.endsWith(path.sep)
+  );
+}
+
+// Checks every directory from the root down to the file's own directory.
+// Returns { ok: true, inodes } so a second walk can prove nothing moved.
+function checkParents(file, uid) {
+  const directories = [];
+  for (let dir = path.dirname(file); ; dir = path.dirname(dir)) {
+    directories.unshift(dir);
+    if (path.dirname(dir) === dir) break;
+  }
+  const inodes = [];
+  for (const [index, dir] of directories.entries()) {
+    let stat;
+    try {
+      stat = fs.lstatSync(dir);
+    } catch (error) {
+      return fail(error?.code === "ENOENT" ? "credential_missing" : "credential_unreadable");
+    }
+    if (stat.isSymbolicLink()) return fail("credential_path_symlink");
+    if (!stat.isDirectory()) return fail("credential_path_invalid");
+    if (stat.uid !== uid && stat.uid !== 0) return fail("credential_parent_unsafe");
+    const shared = (stat.mode & 0o022) !== 0;
+    const own = index === directories.length - 1;
+    if (shared && (own || (stat.mode & 0o1000) === 0)) return fail("credential_parent_unsafe");
+    inodes.push(stat);
+  }
+  return { ok: true, inodes };
+}
+
+function sameInode(a, b) {
+  return a.dev === b.dev && a.ino === b.ino;
+}
+
+// The same file with the same owner, mode, links, size and change times.
+// Both are bigint stats, so times compare to the nanosecond.
+function unchanged(a, b) {
+  return (
+    sameInode(a, b) &&
+    a.uid === b.uid &&
+    a.mode === b.mode &&
+    a.nlink === b.nlink &&
+    a.size === b.size &&
+    a.mtimeNs === b.mtimeNs &&
+    a.ctimeNs === b.ctimeNs
+  );
+}
+
+function parseToken(bytes) {
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return fail("credential_malformed");
+  }
+  if (text.endsWith("\r\n")) text = text.slice(0, -2);
+  else if (text.endsWith("\n")) text = text.slice(0, -1);
+  if (text.length === 0) return fail("credential_empty");
+  // One token only: any whitespace means a second token, a label such as
+  // "Bearer" or a second line.
+  if (!TOKEN.test(text)) return fail("credential_malformed");
+  return { ok: true, token: text };
+}