@xagents_in/unmask 0.1.3 → 0.1.4

package/dist/cli/doctor.mjs

@@ -0,0 +1,354 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import path from "node:path";
+import { LocalInputError } from "../core/pipeline.mjs";
+
+const DEFAULT_SERVER_URL = "https://unmask-386156642190.asia-south1.run.app";
+const MAX_JSON_BYTES = 16384;
+const fail = () =>
+  new LocalInputError(
+    "doctor-usage",
+    "Use doctor [--offline] [--server-url ORIGIN] [--project DIR] [--json].",
+  );
+function parse(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index++) {
+    const key = argv[index];
+    if (
+      !["--offline", "--json", "--server-url", "--project"].includes(key) ||
+      Object.hasOwn(result, key)
+    )
+      throw fail();
+    if (["--offline", "--json"].includes(key)) result[key] = true;
+    else {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) throw fail();
+      result[key] = value;
+    }
+  }
+  if (result["--offline"] && result["--server-url"]) throw fail();
+  return result;
+}
+function serviceOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw fail();
+  }
+  if (
+    value.length > 2048 ||
+    url.username ||
+    url.password ||
+    url.pathname !== "/" ||
+    url.search ||
+    url.hash ||
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw fail();
+  return url.origin;
+}
+async function serviceJson(
+  origin,
+  route,
+  { fetchImpl = globalThis.fetch, signal } = {},
+) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  let response;
+  try {
+    response = await fetchImpl(origin + route, {
+      headers: { accept: "application/json" },
+      redirect: "manual",
+      credentials: "omit",
+      referrerPolicy: "no-referrer",
+      signal: signal
+        ? AbortSignal.any([signal, controller.signal])
+        : controller.signal,
+    });
+    if (
+      response.status !== 200 ||
+      response.redirected ||
+      (response.url && new URL(response.url).origin !== origin) ||
+      !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(
+        response.headers.get("content-type") ?? "",
+      )
+    )
+      throw new Error();
+    const declared = response.headers.get("content-length");
+    if (
+      declared !== null &&
+      (!/^\d+$/.test(declared) || Number(declared) > MAX_JSON_BYTES)
+    )
+      throw new Error();
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of response.body ?? []) {
+      size += chunk.byteLength;
+      if (size > MAX_JSON_BYTES) throw new Error();
+      chunks.push(chunk);
+    }
+    return JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        Buffer.concat(chunks, size),
+      ),
+    );
+  } finally {
+    clearTimeout(timer);
+    try {
+      await response?.body?.cancel();
+    } catch {}
+  }
+}
+async function fallbackConfig(cwd) {
+  try {
+    if (!(await lstat(cwd)).isDirectory()) throw new Error();
+  } catch {
+    return {
+      id: "config",
+      status: "error",
+      message: "Project directory does not exist or is not a directory.",
+      action: "Use --project with an existing project directory.",
+    };
+  }
+  const filename = path.join(cwd, ".unmask.json");
+  let handle;
+  try {
+    const stat = await lstat(filename);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_JSON_BYTES)
+      throw new Error();
+    handle = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const current = await handle.stat();
+    if (
+      current.dev !== stat.dev ||
+      current.ino !== stat.ino ||
+      current.size > MAX_JSON_BYTES
+    )
+      throw new Error();
+    const bytes = Buffer.alloc(MAX_JSON_BYTES + 1);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > MAX_JSON_BYTES) throw new Error();
+    const value = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        bytes.subarray(0, bytesRead),
+      ),
+    );
+    if (
+      !value ||
+      Array.isArray(value) ||
+      !["strict", "balanced", "audit"].includes(value.profile)
+    )
+      throw new Error();
+    return {
+      id: "config",
+      status: "unknown",
+      message:
+        "Project config has a recognized profile; full guard schema validation requires the guard configuration command.",
+      action:
+        "Run unmask config show to validate the complete policy before enabling an install guard.",
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return {
+        id: "config",
+        status: "warning",
+        message: "No project guard configuration found.",
+        action: "Use unmask config to explicitly configure a guard policy.",
+      };
+    return {
+      id: "config",
+      status: "error",
+      message:
+        "Project guard configuration is unreadable, oversized, linked or invalid.",
+      action:
+        "Inspect the project guard config locally; do not store credentials in it.",
+    };
+  } finally {
+    await handle?.close();
+  }
+}
+async function projectConfig(cwd, inspector) {
+  if (inspector === null) return fallbackConfig(cwd);
+  try {
+    if (!inspector) {
+      try {
+        inspector = (await import("../core/guard-config.mjs"))
+          .inspectGuardConfig;
+      } catch (error) {
+        if (
+          error.code === "ERR_MODULE_NOT_FOUND" &&
+          error.url ===
+            new URL("../core/guard-config.mjs", import.meta.url).href
+        )
+          return fallbackConfig(cwd);
+        throw error;
+      }
+    }
+    const result = await inspector(cwd);
+    if (result?.status === "default")
+      return {
+        id: "config",
+        status: "warning",
+        message:
+          "No explicit project guard configuration; default policy applies.",
+        action:
+          "Use unmask config to explicitly inspect and choose a project guard policy.",
+      };
+    if (result?.status !== "ok") throw new Error();
+    return {
+      id: "config",
+      status: "ok",
+      message:
+        "Project guard configuration passed the installed guard schema validator.",
+      action:
+        "Run unmask config show to inspect the policy before enabling an install guard.",
+    };
+  } catch {
+    return {
+      id: "config",
+      status: "error",
+      message:
+        "Project guard configuration failed the installed guard schema validator.",
+      action:
+        "Inspect .unmask.json locally with unmask config; do not store credentials in it.",
+    };
+  }
+}
+export async function inspectDoctor({
+  cwd = process.cwd(),
+  nodeVersion = process.version,
+  offline = false,
+  serverUrl = DEFAULT_SERVER_URL,
+  fetchImpl,
+  signal,
+  configInspector,
+} = {}) {
+  const origin = serviceOrigin(serverUrl);
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(nodeVersion);
+  const supported =
+    match &&
+    (Number(match[1]) > 24 ||
+      (Number(match[1]) === 24 &&
+        (Number(match[2]) > 22 ||
+          (Number(match[2]) === 22 && Number(match[3]) >= 2))));
+  const checks = [
+    {
+      id: "node",
+      status:
+        nodeVersion.replace(/^v/, "") === "24.22.2"
+          ? "ok"
+          : supported
+            ? "warning"
+            : "error",
+      message:
+        nodeVersion.replace(/^v/, "") === "24.22.2"
+          ? "Node matches the exact 24.22.2 package engine pin."
+          : supported
+            ? "Node differs from the exact 24.22.2 package engine pin; compatibility is unverified."
+            : "Node is older than the pinned 24.22.2 runtime or its version is invalid.",
+      action:
+        "Use the repository-pinned Node 24.22.2 for reproducible results.",
+    },
+    await projectConfig(cwd, configInspector),
+  ];
+  const result = {
+    schemaVersion: "1",
+    checks,
+    node: {
+      version: match ? match.slice(1).join(".") : null,
+      required: "24.22.2",
+    },
+    service: { origin },
+    limitations: [
+      "Diagnostics do not assess package safety or make a model request.",
+      "Only the nonsecret UNMASK_SERVER_URL environment value is consulted; shell startup files are not read and active shell guard interception is unverified.",
+    ],
+  };
+  if (offline)
+    checks.push({
+      id: "service",
+      status: "skipped",
+      message: "Hosted diagnostics skipped explicitly.",
+      action: "Run doctor without --offline to check the service.",
+    });
+  else {
+    try {
+      const version = await serviceJson(origin, "/version", {
+        fetchImpl,
+        signal,
+      });
+      if (
+        typeof version?.version !== "string" ||
+        !/^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/.test(version.version) ||
+        version.version.length > 100 ||
+        !/^[a-f0-9]{40}$/.test(version.commit) ||
+        !/^[a-f0-9]{64}$/.test(version.tarballSha256)
+      )
+        throw new Error();
+      result.service = {
+        origin,
+        version: version.version,
+        commit: version.commit,
+        tarballSha256: version.tarballSha256,
+      };
+      checks.push({
+        id: "service",
+        status: "ok",
+        message: "Hosted version endpoint responded with valid metadata.",
+        action:
+          "A completed package check is still required to verify the analysis path.",
+      });
+    } catch {
+      checks.push({
+        id: "service",
+        status: "error",
+        message:
+          "Hosted version diagnostics unavailable or invalid within bounded limits.",
+        action:
+          "Check connectivity and the explicit --server-url origin; retry doctor. No package was submitted.",
+      });
+    }
+  }
+  checks.push({
+    id: "guard",
+    status: "unknown",
+    message:
+      "Active shell guard integration cannot be verified from a child process.",
+    action:
+      "In a build with guard commands, use unmask enable for explicit setup, then run type npm in the invoking shell to verify interception.",
+  });
+  return result;
+}
+export async function doctorCommand(argv, runtime = {}) {
+  const options = parse(argv);
+  const result = await inspectDoctor({
+    cwd: options["--project"] ?? runtime.cwd,
+    nodeVersion: runtime.nodeVersion,
+    offline: !!options["--offline"],
+    serverUrl:
+      options["--server-url"] ?? (runtime.env ?? process.env).UNMASK_SERVER_URL,
+    fetchImpl: runtime.fetchImpl,
+    signal: runtime.signal,
+    configInspector: runtime.configInspector,
+  });
+  const stdout = runtime.stdout ?? process.stdout;
+  stdout.write(
+    options["--json"]
+      ? JSON.stringify(result, null, 2) + "\n"
+      : `UNMASK doctor\nNode ${result.node.version ?? "unknown"}; required ${result.node.required}\nService ${result.service.version ?? "unverified"} at ${result.service.origin}\n` +
+          result.checks
+            .map(
+              (check) =>
+                `${check.id}: ${check.status} — ${check.message}\n  ${check.action}`,
+            )
+            .join("\n") +
+          "\n" +
+          result.limitations.join("\n") +
+          "\n",
+  );
+  return result.checks.some((check) => check.status === "error") ? 1 : 0;
+}

package/dist/cli/exceptions.mjs

@@ -0,0 +1,170 @@
+import {
+  GuardConfigError,
+  activeExceptionFor,
+  exactPackage,
+  exceptionStatuses,
+  newException,
+  readGuardConfig,
+  writeGuardConfig,
+} from "../core/guard-config.mjs";
+import { parseCommandOptions } from "./config.mjs";
+
+const USAGE =
+  "Use exceptions list [--json], exceptions check NAME@VERSION [--json], exceptions add NAME@VERSION --reason TEXT --expires YYYY-MM-DD, exceptions remove NAME@VERSION or exceptions prune; each accepts --project DIR";
+const SCOPE =
+  "Exceptions apply only to the exact name@version listed, only until expiry, never to ranges, tags or wildcards. In enforcing profiles (strict, balanced) they never waive known malware; the audit profile blocks nothing.";
+
+const line = (entry) =>
+  `${entry.name}@${entry.version} ${entry.status === "active" ? "active" : "EXPIRED (not applied)"} expires=${entry.expires} created=${entry.created} reason=${JSON.stringify(entry.reason)}`;
+
+function audit(stdout, action, entry, file) {
+  stdout.write(
+    `audit: ${action} exception ${entry.name}@${entry.version} expires=${entry.expires} reason=${JSON.stringify(entry.reason)} file=${file}\n`,
+  );
+}
+
+export async function runExceptions(args, runtime = {}) {
+  const stdout = runtime.stdout ?? process.stdout;
+  const stderr = runtime.stderr ?? process.stderr;
+  const now = runtime.now ? runtime.now() : new Date();
+  try {
+    const { positional, options } = parseCommandOptions(
+      args,
+      ["--json"],
+      ["--project", "--reason", "--expires"],
+    );
+    const [action, spec, ...extra] = positional;
+    const project = options.project ?? runtime.cwd ?? process.cwd();
+    const mutation =
+      options.reason !== undefined || options.expires !== undefined;
+    if (extra.length || (action !== "add" && mutation))
+      throw new GuardConfigError("usage", USAGE);
+    if (action === "list" && !spec) {
+      const loaded = await readGuardConfig(project, { now });
+      const entries = exceptionStatuses(loaded.config, now);
+      if (options.json)
+        stdout.write(
+          JSON.stringify(
+            {
+              path: loaded.file,
+              source: loaded.source,
+              checkedAt: now.toISOString(),
+              scope: SCOPE,
+              exceptions: entries,
+            },
+            null,
+            2,
+          ) + "\n",
+        );
+      else
+        stdout.write(
+          [
+            `Guard exceptions: ${loaded.file} (${entries.filter((e) => e.status === "active").length} active, ${entries.filter((e) => e.status === "expired").length} expired)`,
+            ...entries.map((entry) => `  ${line(entry)}`),
+            SCOPE,
+          ].join("\n") + "\n",
+        );
+      return 0;
+    }
+    if (action === "prune" && !spec && !options.json) {
+      const loaded = await readGuardConfig(project, { now });
+      const current = loaded.config.exceptions ?? [];
+      const expired = exceptionStatuses(loaded.config, now).filter(
+        (entry) => entry.status === "expired",
+      );
+      const saved = expired.length
+        ? await writeGuardConfig(
+            project,
+            {
+              ...loaded.config,
+              exceptions: current.filter(
+                (entry) => Date.parse(entry.expires) > now.getTime(),
+              ),
+            },
+            { now },
+          )
+        : loaded;
+      for (const entry of expired) audit(stdout, "pruned", entry, saved.file);
+      stdout.write(`Pruned ${expired.length} expired exception(s)\n`);
+      return 0;
+    }
+    if (action === "check" && spec) {
+      const identity = exactPackage(spec);
+      const loaded = await readGuardConfig(project, { now });
+      const entry = activeExceptionFor(loaded.config, identity, { now });
+      const result = {
+        package: `${identity.name}@${identity.version}`,
+        exception: entry,
+        knownMalwareWaived: false,
+        scope: SCOPE,
+      };
+      stdout.write(
+        options.json
+          ? JSON.stringify(result, null, 2) + "\n"
+          : `${entry ? `Active exception: ${line(entry)}` : `No active exception for ${result.package}`}\n${SCOPE}\n`,
+      );
+      return 0;
+    }
+    if (options.json || !spec) throw new GuardConfigError("usage", USAGE);
+    if (action === "add") {
+      if (options.reason === undefined || options.expires === undefined)
+        throw new GuardConfigError(
+          "usage",
+          "Exceptions require --reason TEXT and --expires YYYY-MM-DD",
+        );
+      const entry = newException(spec, options.reason, options.expires, now);
+      const loaded = await readGuardConfig(project, { now });
+      const current = loaded.config.exceptions ?? [];
+      if (
+        current.some(
+          (e) => e.name === entry.name && e.version === entry.version,
+        )
+      )
+        throw new GuardConfigError(
+          "duplicate-exception",
+          `An exception for ${spec} already exists; remove it first`,
+        );
+      const saved = await writeGuardConfig(
+        project,
+        {
+          ...loaded.config,
+          exceptions: [...current, entry],
+        },
+        { now },
+      );
+      audit(stdout, "added", entry, saved.file);
+      return 0;
+    }
+    if (action === "remove") {
+      const { name, version } = exactPackage(spec);
+      const loaded = await readGuardConfig(project, { now });
+      const current = loaded.config.exceptions ?? [];
+      const entry = current.find(
+        (e) => e.name === name && e.version === version,
+      );
+      if (!entry)
+        throw new GuardConfigError(
+          "missing-exception",
+          `No exception exists for ${name}@${version}`,
+        );
+      const saved = await writeGuardConfig(
+        project,
+        {
+          ...loaded.config,
+          exceptions: current.filter((e) => e !== entry),
+        },
+        { now },
+      );
+      audit(stdout, "removed", entry, saved.file);
+      return 0;
+    }
+    throw new GuardConfigError("usage", USAGE);
+  } catch (error) {
+    if (error instanceof GuardConfigError) {
+      stderr.write(`${error.code}: ${error.message}\n`);
+      return 2;
+    }
+    stderr.write("Guard exception error; no change is claimed.\n");
+    return 1;
+  }
+}