@xagents_in/unmask 0.1.3 → 0.1.4

package/dist/cli/file.mjs

@@ -0,0 +1,271 @@
+import { isDeepStrictEqual } from "node:util";
+import { LocalInputError } from "../core/pipeline.mjs";
+import { getHostedDetailsForReport } from "./hosted.mjs";
+import { exactPackage, hostedOptions, terminalText } from "./info.mjs";
+
+const MAX_BYTES = 131072;
+const fail = (code, message) => new LocalInputError(code, message);
+const invalid = () =>
+  fail(
+    "file-evidence-invalid",
+    "Recorded file evidence failed schema, report, file or evidence validation.",
+  );
+function parse(args) {
+  const usage = () =>
+    fail(
+      "usage",
+      "Use file name@exact-version --report REPORT_ID --file-id FILE_ID",
+    );
+  if (args.length !== 5) throw usage();
+  exactPackage(args[0]);
+  const options = { spec: args[0] };
+  for (let index = 1; index < args.length; index += 2) {
+    const key =
+      args[index] === "--report"
+        ? "reportId"
+        : args[index] === "--file-id"
+          ? "fileId"
+          : null;
+    if (!key || Object.hasOwn(options, key)) throw usage();
+    options[key] = args[index + 1];
+  }
+  if (
+    !/^[a-f0-9]{32}$/.test(options.reportId ?? "") ||
+    !/^f-[A-Za-z0-9_-]{43}$/.test(options.fileId ?? "")
+  )
+    throw usage();
+  return options;
+}
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const range = (value, size) =>
+  Array.isArray(value) &&
+  value.length === 2 &&
+  value.every(integer) &&
+  value[0] <= value[1] &&
+  value[1] <= size;
+
+function validateEvidence(value, report, options) {
+  const file = value?.file;
+  if (
+    value?.schemaVersion !== "1" ||
+    value.reportId !== options.reportId ||
+    value.scope !== "artifact-source" ||
+    value.recordedOnly !== true ||
+    file?.fileId !== options.fileId ||
+    !Array.isArray(value.evidence) ||
+    value.evidence.length > 32 ||
+    !["recorded", "partial", "unavailable"].includes(value.evidenceStatus) ||
+    !integer(value.evidenceOmitted) ||
+    !integer(value.invalidEvidenceOmitted) ||
+    !Array.isArray(value.limitations) ||
+    value.limitations.length > 16 ||
+    value.limitations.some(
+      (item) => typeof item !== "string" || item.length > 4096,
+    )
+  )
+    throw invalid();
+  if (file.state === "removed") {
+    if (
+      file.comparisonState !== "source-only" ||
+      !report.coverage.sourceOnly.includes(file.path) ||
+      file.originalPath !== null ||
+      file.artifactSha256 !== null ||
+      file.size !== null ||
+      (file.sourceSha256 !== null &&
+        !report.evidence.some(
+          (item) =>
+            item.side === "source" &&
+            item.path === file.path &&
+            item.fileSha256 === file.sourceSha256 &&
+            item.blobDigest === report.inputs.sourceArchive?.sha256,
+        ))
+    )
+      throw invalid();
+  } else {
+    const raw = report.files.find(
+      (item) =>
+        item.path === file.path && item.originalPath === file.originalPath,
+    );
+    const states = {
+      "byte-identical": "identical",
+      changed: "changed",
+      "artifact-only": "added",
+      "not-compared": "not-compared",
+    };
+    if (
+      !raw ||
+      file.comparisonState !== raw.state ||
+      file.state !== states[raw.state] ||
+      file.size !== raw.size ||
+      file.artifactSha256 !== raw.artifactSha256 ||
+      file.sourceSha256 !== (raw.sourceSha256 ?? null)
+    )
+      throw invalid();
+  }
+  const status =
+    value.evidence.length === 0
+      ? "unavailable"
+      : value.evidenceOmitted || value.invalidEvidenceOmitted
+        ? "partial"
+        : "recorded";
+  if (value.evidenceStatus !== status) throw invalid();
+  const known = new Map(report.evidence.map((item) => [item.id, item]));
+  const seen = new Set();
+  for (const item of value.evidence) {
+    const raw = known.get(item?.id);
+    if (
+      !raw ||
+      seen.has(item.id) ||
+      item.path !== file.path ||
+      ![
+        "side",
+        "path",
+        "originalPath",
+        "size",
+        "fileSha256",
+        "blobDigest",
+        "range",
+      ].every((key) => isDeepStrictEqual(item[key], raw[key])) ||
+      item.fileSha256 !==
+        (item.side === "artifact" ? file.artifactSha256 : file.sourceSha256) ||
+      (item.side === "artifact" && item.originalPath !== file.originalPath)
+    )
+      throw invalid();
+    seen.add(item.id);
+    if (typeof item.excerptTruncated !== "boolean") throw invalid();
+    if (item.excerpt === null) {
+      if (
+        !["not-recorded", "invalid-recorded-range"].includes(
+          item.excerptStatus,
+        ) ||
+        item.excerptRange !== null
+      )
+        throw invalid();
+    } else if (
+      item.excerptStatus !== "recorded" ||
+      typeof item.excerpt !== "string" ||
+      typeof raw.excerpt !== "string" ||
+      !raw.excerpt.startsWith(item.excerpt) ||
+      Buffer.byteLength(item.excerpt) > 2048 ||
+      !range(item.excerptRange, item.size) ||
+      !isDeepStrictEqual(item.recordedExcerptRange, raw.excerptRange) ||
+      item.excerptRange[0] !== raw.excerptRange?.[0] ||
+      item.excerptRange[1] > raw.excerptRange?.[1] ||
+      Buffer.byteLength(item.excerpt) !==
+        item.excerptRange[1] - item.excerptRange[0]
+    )
+      throw invalid();
+  }
+}
+
+async function fetchEvidence(url, runtime) {
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    Math.min(runtime.hostedLimits?.requestTimeoutMs ?? 15000, 15000),
+  );
+  const signal = runtime.signal
+    ? AbortSignal.any([runtime.signal, controller.signal])
+    : controller.signal;
+  let response;
+  try {
+    response = await (runtime.fetchImpl ?? globalThis.fetch)(url.href, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      redirect: "manual",
+      credentials: "omit",
+      referrerPolicy: "no-referrer",
+      signal,
+    });
+    if (
+      response.status !== 200 ||
+      response.redirected ||
+      (response.url && new URL(response.url).origin !== url.origin)
+    )
+      throw fail(
+        "file-evidence-unavailable",
+        `Stored file evidence is unavailable (HTTP ${response.status}); no new check was submitted.`,
+      );
+    const declared = response.headers.get("content-length");
+    if (
+      !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(
+        response.headers.get("content-type") ?? "",
+      ) ||
+      (declared !== null &&
+        (!/^\d+$/.test(declared) || Number(declared) > MAX_BYTES))
+    )
+      throw invalid();
+    let bytes = 0;
+    const chunks = [];
+    for await (const chunk of response.body ?? []) {
+      bytes += chunk.byteLength;
+      if (bytes > MAX_BYTES) throw invalid();
+      chunks.push(chunk);
+    }
+    try {
+      return JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(
+          Buffer.concat(chunks, bytes),
+        ),
+      );
+    } catch {
+      throw invalid();
+    }
+  } catch (error) {
+    if (error instanceof LocalInputError) throw error;
+    throw fail(
+      "file-evidence-unavailable",
+      signal.aborted
+        ? "Stored file evidence timed out or was cancelled; no new check was submitted."
+        : "Stored file evidence could not be read; no new check was submitted.",
+    );
+  } finally {
+    clearTimeout(timeout);
+    try {
+      await response?.body?.cancel();
+    } catch {}
+  }
+}
+
+function render(value, options) {
+  const file = value.file,
+    text = terminalText;
+  const lines = [
+    `UNMASK file ${text(options.spec)}`,
+    `${text(file.path ?? file.originalPath)} [${text(file.state)}] ${file.size === null ? "size unavailable" : file.size + " bytes"}`,
+    `Report ID: ${options.reportId}; File ID: ${options.fileId}`,
+    `artifact-sha256=${text(file.artifactSha256 ?? "unavailable")} source-sha256=${text(file.sourceSha256 ?? "unavailable")}`,
+    `Previously recorded evidence only: ${text(value.evidenceStatus)}; omitted=${value.evidenceOmitted}; invalid omitted=${value.invalidEvidenceOmitted}.`,
+  ];
+  for (const item of value.evidence) {
+    lines.push(
+      `  ${text(item.side)} ${text(item.id)} bytes [${item.range.join(", ")}]`,
+      item.excerpt === null
+        ? `    Excerpt: ${text(item.excerptStatus)}`
+        : `    Excerpt [${item.excerptRange.join(", ")}]: ${text(item.excerpt)}`,
+    );
+    if (item.excerptTruncated)
+      lines.push("    Recorded excerpt truncated by the API limit.");
+  }
+  for (const limitation of value.limitations)
+    lines.push(`  ${text(limitation)}`);
+  lines.push(
+    "This is not a safety verdict. No file was opened, reconstructed or executed locally.",
+  );
+  return lines.join("\n") + "\n";
+}
+
+export async function fileCommand(args, runtime = {}) {
+  const options = parse(args);
+  const { report, reportUrl } = await getHostedDetailsForReport(
+    options.spec,
+    options.reportId,
+    hostedOptions(runtime),
+  );
+  const url = new URL(`/r/${options.reportId}/file.json`, reportUrl);
+  url.searchParams.set("fileId", options.fileId);
+  const evidence = await fetchEvidence(url, runtime);
+  validateEvidence(evidence, report, options);
+  (runtime.stdout ?? process.stdout).write(render(evidence, options));
+  return 0;
+}

package/dist/cli/files.mjs

@@ -0,0 +1,141 @@
+import { LocalInputError } from "../core/pipeline.mjs";
+import { getHostedDetails, getHostedDetailsForReport } from "./hosted.mjs";
+import { exactPackage, hostedOptions, terminalText, aiLines } from "./info.mjs";
+
+const states = ["byte-identical", "changed", "artifact-only", "not-compared"];
+const usage = () =>
+  new LocalInputError(
+    "usage",
+    "Use files name@exact-version [--report ID] [--path TEXT] [--state STATE] [--limit 1..200] [--offset N]",
+  );
+function parse(args) {
+  if (!args[0]) throw usage();
+  exactPackage(args[0]);
+  const options = {
+    spec: args[0],
+    path: "",
+    state: "all",
+    limit: 50,
+    offset: 0,
+  };
+  const seen = new Set();
+  for (let index = 1; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (
+      !["--path", "--state", "--limit", "--offset", "--report"].includes(
+        flag,
+      ) ||
+      seen.has(flag) ||
+      value === undefined
+    )
+      throw usage();
+    seen.add(flag);
+    if (flag === "--report") {
+      if (!/^[a-f0-9]{32}$/.test(value)) throw usage();
+      options.reportId = value;
+    } else if (flag === "--path") {
+      if (value.length > 1024) throw usage();
+      options.path = value;
+    } else if (flag === "--state") {
+      if (!["all", ...states].includes(value)) throw usage();
+      options.state = value;
+    } else {
+      if (
+        !/^(0|[1-9][0-9]*)$/.test(value) ||
+        !Number.isSafeInteger(Number(value))
+      )
+        throw usage();
+      const number = Number(value);
+      if (flag === "--limit" && (number < 1 || number > 200)) throw usage();
+      options[flag.slice(2)] = number;
+    }
+  }
+  return options;
+}
+
+function validateFiles(list) {
+  const digest = (value) =>
+    typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+  if (
+    list.items.some(
+      (file) =>
+        !(file.path === null || typeof file.path === "string") ||
+        typeof file.originalPath !== "string" ||
+        !states.includes(file.state) ||
+        !Number.isSafeInteger(file.size) ||
+        file.size < 0 ||
+        !digest(file.artifactSha256) ||
+        (file.sourceSha256 !== undefined && !digest(file.sourceSha256)),
+    )
+  )
+    throw new LocalInputError(
+      "hosted-details-invalid",
+      "Hosted file inventory contains invalid paths, states, sizes or hashes.",
+    );
+}
+
+export function renderFiles({ details, report, reportUrl }, options) {
+  const reportId = new URL(reportUrl).pathname
+    .split("/")[2]
+    .replace(/\.json$/, "");
+  const inventory = details.inventory;
+  validateFiles(inventory.files);
+  const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  const files = inventory.files.items
+    .filter(
+      (file) =>
+        (options.state === "all" || file.state === options.state) &&
+        (file.path ?? file.originalPath).includes(options.path),
+    )
+    .sort(
+      (a, b) =>
+        order(a.path ?? "", b.path ?? "") ||
+        order(a.originalPath, b.originalPath),
+    );
+  const page = files.slice(options.offset, options.offset + options.limit);
+  const start = page.length ? options.offset + 1 : 0;
+  const end = page.length ? options.offset + page.length : 0;
+  const text = terminalText;
+  const lines = [
+    `UNMASK files ${text(options.spec)}`,
+    "Scope: accepted artifact regular files; source-only paths and inert links are outside this list.",
+    `Filters: path contains ${text(JSON.stringify(options.path))}; state=${text(options.state)}`,
+    `Rows ${start}-${end} of ${files.length} matching returned records; hosted projected total=${inventory.files.total}.`,
+    `Inventory complete: ${inventory.complete === true}; ${inventory.files.omitted} records omitted by hosted projection.`,
+  ];
+  if (inventory.files.omitted)
+    lines.push(
+      "Filtering and pagination cover returned records only; omitted records may also match.",
+    );
+  for (const file of page)
+    lines.push(
+      `${text(file.path ?? file.originalPath)} [${text(file.state)}] ${file.size} bytes`,
+      `  artifact-sha256=${file.artifactSha256} source-sha256=${file.sourceSha256 ?? "unavailable"}`,
+    );
+  if (options.offset + page.length < files.length)
+    lines.push(
+      `Next offset: ${options.offset + page.length} (use the same filters and limit).`,
+    );
+  lines.push(...aiLines(report.model));
+  lines.push(
+    "This is not a safety verdict; byte-identical means only recorded byte correspondence.",
+    `Report: ${text(reportUrl)}`,
+    `Report ID: ${reportId}`,
+    `Reuse this report for paging: --report ${reportId} (with the same exact package spec and filters; no new check).`,
+  );
+  return lines.join("\n") + "\n";
+}
+
+export async function filesCommand(args, runtime = {}) {
+  const options = parse(args);
+  const result = options.reportId
+    ? await getHostedDetailsForReport(
+        options.spec,
+        options.reportId,
+        hostedOptions(runtime),
+      )
+    : await getHostedDetails(options.spec, hostedOptions(runtime));
+  (runtime.stdout ?? process.stdout).write(renderFiles(result, options));
+  return 0;
+}

package/dist/cli/history.mjs

@@ -0,0 +1,232 @@
+import {
+  AcquisitionError,
+  fetchBlob,
+  parsePackageSpec,
+} from "../core/acquire.mjs";
+import { LocalInputError } from "../core/pipeline.mjs";
+
+const MAX_PACKUMENT_BYTES = 40 * 1024 * 1024;
+const TIMEOUT_MS = 20000;
+const DEFAULT_LIMIT = 15;
+const MAX_LIMIT = 100;
+const RECENT_MS = 7 * 24 * 60 * 60 * 1000;
+const INSTALL_SCRIPTS = ["preinstall", "install", "postinstall"];
+const usage = () =>
+  new LocalInputError("usage", "Use history NAME [--limit 1-100] [--json]");
+export function parseHistoryArgs(argv) {
+  const options = { limit: DEFAULT_LIMIT, json: false };
+  const seen = new Set();
+  let name;
+  for (let index = 0; index < argv.length; index++) {
+    const value = argv[index];
+    if (seen.has(value)) throw usage();
+    if (value === "--json") options.json = true;
+    else if (value === "--limit") {
+      const raw = argv[++index];
+      if (!/^[1-9][0-9]{0,2}$/.test(raw ?? "") || Number(raw) > MAX_LIMIT)
+        throw new LocalInputError(
+          "invalid-limit",
+          `--limit must be an integer from 1 to ${MAX_LIMIT}`,
+        );
+      options.limit = Number(raw);
+    } else if (value.startsWith("--") || name !== undefined) throw usage();
+    else name = value;
+    if (value.startsWith("--")) seen.add(value);
+  }
+  if (name === undefined) throw usage();
+  try {
+    parsePackageSpec(`${name}@0.0.0`);
+  } catch (error) {
+    if (error instanceof AcquisitionError)
+      throw new LocalInputError(
+        "invalid-package-name",
+        "History requires a bare npm package name without a version",
+      );
+    throw error;
+  }
+  return { ...options, name };
+}
+const UNSAFE =
+  /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+const JSON_UNSAFE = /[\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+const escapeUnsafe = (text, pattern = UNSAFE) =>
+  text.replace(
+    pattern,
+    (char) => "\\u" + char.charCodeAt(0).toString(16).padStart(4, "0"),
+  );
+const abbreviate = (value, max) =>
+  value.length > max ? value.slice(0, max) + "..." : value;
+const validDate = (value) =>
+  typeof value === "string" && Number.isFinite(Date.parse(value));
+function exactPin(name, version) {
+  try {
+    parsePackageSpec(`${name}@${version}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+export function summarizeHistory(packument, { limit, now = Date.now() }) {
+  if (!packument || typeof packument !== "object" || Array.isArray(packument))
+    throw new LocalInputError(
+      "registry-invalid",
+      "Registry metadata is not a JSON object",
+    );
+  const versions =
+    packument.versions && typeof packument.versions === "object"
+      ? packument.versions
+      : {};
+  const time =
+    packument.time && typeof packument.time === "object" ? packument.time : {};
+  const tags = new Map();
+  for (const [tag, version] of Object.entries(packument["dist-tags"] ?? {}))
+    if (typeof version === "string")
+      tags.set(version, [...(tags.get(version) ?? []), tag]);
+  const known = new Set([
+    ...Object.keys(versions),
+    ...Object.keys(time).filter(
+      (key) => !["created", "modified"].includes(key) && validDate(time[key]),
+    ),
+  ]);
+  const releases = [];
+  for (const version of known) {
+    const manifest = Object.hasOwn(versions, version)
+      ? versions[version]
+      : undefined;
+    const available = Boolean(manifest && typeof manifest === "object");
+    releases.push({
+      version,
+      exactPin: exactPin(packument.name, version),
+      published: validDate(time[version]) ? time[version] : null,
+      available,
+      tags: tags.get(version) ?? [],
+      deprecated:
+        available && typeof manifest.deprecated === "string"
+          ? manifest.deprecated
+          : null,
+      installScripts: available
+        ? INSTALL_SCRIPTS.filter(
+            (name) => typeof manifest.scripts?.[name] === "string",
+          )
+        : [],
+      recent: validDate(time[version])
+        ? now - Date.parse(time[version]) < RECENT_MS
+        : false,
+    });
+  }
+  const stamp = (release) =>
+    release.published ? Date.parse(release.published) : 0;
+  releases.sort(
+    (a, b) => stamp(b) - stamp(a) || (a.version < b.version ? 1 : -1),
+  );
+  const selectable = (release) =>
+    release.available && !release.deprecated && release.exactPin;
+  const latest = releases.find(
+    (release) => release.version === packument["dist-tags"]?.latest,
+  );
+  const candidate =
+    latest && selectable(latest)
+      ? latest
+      : releases.find(
+          (release) => selectable(release) && !release.version.includes("-"),
+        );
+  return {
+    name: packument.name,
+    totalVersions: releases.length,
+    removedVersions: releases.filter((release) => !release.available).length,
+    deprecatedVersions: releases.filter((release) => release.deprecated).length,
+    distTags: Object.fromEntries(
+      [...tags].flatMap(([version, names]) =>
+        names.map((tag) => [tag, version]),
+      ),
+    ),
+    unpublished: Boolean(time.unpublished),
+    shown: releases.slice(0, limit),
+    candidate: candidate?.version ?? null,
+  };
+}
+export function renderHistory(summary) {
+  const lines = [
+    `History ${summary.name}: ${summary.totalVersions} versions, ${summary.deprecatedVersions} deprecated, ${summary.removedVersions} removed from registry`,
+    `Dist-tags: ${
+      Object.entries(summary.distTags)
+        .map(
+          ([tag, version]) =>
+            `${abbreviate(tag, 40)}=${abbreviate(version, 64)}`,
+        )
+        .join(", ") || "none"
+    }`,
+  ];
+  if (summary.unpublished)
+    lines.push("! The package is marked unpublished in the registry.");
+  lines.push(`Newest ${summary.shown.length} releases:`);
+  for (const release of summary.shown) {
+    const marks = [
+      ...release.tags.map((tag) => `[${abbreviate(tag, 40)}]`),
+      ...(release.available ? [] : ["[removed]"]),
+      ...(release.recent ? ["[recent]"] : []),
+      ...(release.installScripts.length
+        ? [`[install scripts: ${release.installScripts.join(",")}]`]
+        : []),
+    ];
+    lines.push(
+      `  ${(release.published ?? "unknown date").slice(0, 10)}  ${abbreviate(release.version, 64)}${marks.length ? " " + marks.join(" ") : ""}`,
+    );
+    if (release.deprecated)
+      lines.push(`      deprecated: ${abbreviate(release.deprecated, 160)}`);
+  }
+  lines.push("Selection guidance:");
+  if (summary.candidate)
+    lines.push(
+      `  Pin an exact version, e.g. ${summary.name}@${summary.candidate}, and check it first: unmask check ${summary.name}@${summary.candidate} --out DIR`,
+    );
+  else
+    lines.push(
+      "  No non-deprecated stable release is available; do not select a version without review.",
+    );
+  lines.push(
+    "  Avoid ranges and dist-tags in installs; removed versions cannot be verified from the registry.",
+    "  Release age, popularity or a lack of findings is not proof of safety.",
+  );
+  return lines.map((line) => escapeUnsafe(line)).join("\n") + "\n";
+}
+export async function runHistory(argv, runtime = {}) {
+  const { name, limit, json } = parseHistoryArgs(argv);
+  const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+  let packument;
+  try {
+    const blob = await fetchBlob(url, {
+      fetchImpl: runtime.fetchImpl,
+      signal: runtime.signal,
+      maxBytes: MAX_PACKUMENT_BYTES,
+      timeoutMs: TIMEOUT_MS,
+    });
+    packument = JSON.parse(blob.bytes.toString("utf8"));
+  } catch (error) {
+    if (error instanceof AcquisitionError)
+      throw new LocalInputError(
+        error.observation?.status === 404
+          ? "registry-not-found"
+          : "registry-unavailable",
+        error.observation?.status === 404
+          ? `The registry has no package named ${name}.`
+          : `Registry metadata could not be read (${error.code}).`,
+      );
+    throw new LocalInputError(
+      "registry-invalid",
+      "Registry metadata is not valid JSON",
+    );
+  }
+  if (packument?.name !== name)
+    throw new LocalInputError(
+      "registry-identity-mismatch",
+      "Registry metadata names a different package",
+    );
+  const summary = summarizeHistory(packument, { limit, now: runtime.now });
+  (runtime.stdout ?? process.stdout).write(
+    json
+      ? escapeUnsafe(JSON.stringify(summary, null, 2), JSON_UNSAFE) + "\n"
+      : renderHistory(summary),
+  );
+  return 0;
+}