@xagents_in/unmask 0.1.3 → 0.1.4

package/dist/cli/hosted.mjs

@@ -3,7 +3,8 @@ import { parsePackageSpec } from "../core/acquire.mjs";
 import { LocalInputError } from "../core/pipeline.mjs";
 import { validateReport } from "../core/report.mjs";
 
-const DEFAULT_SERVER_URL = "https://unmask-386156642190.asia-south1.run.app";
+export const DEFAULT_SERVER_URL =
+  "https://unmask-386156642190.asia-south1.run.app";
 const defaults = Object.freeze({
   totalTimeoutMs: 600000,
   requestTimeoutMs: 15000,
@@ -11,7 +12,7 @@ const defaults = Object.freeze({
   pollMs: 3000,
 });
 const failure = (code, message) => new LocalInputError(code, message);
-function serverOrigin(value) {
+export function serverOrigin(value) {
   if (!value)
     throw failure(
       "hosted-configuration",
@@ -88,17 +89,30 @@ async function readJson(response, maxBytes) {
     throw failure("hosted-response", "The hosted response is not valid JSON.");
   }
 }
-export async function checkHosted(
+async function runHosted(
   spec,
   {
     serverUrl = DEFAULT_SERVER_URL,
     fetchImpl = globalThis.fetch,
     signal,
     limits: overrides = {},
+    existingReportId,
+    optionalDetails = false,
+    onStatus,
   } = {},
+  withDetails = false,
 ) {
   const claim = parsePackageSpec(spec);
   const origin = serverOrigin(serverUrl);
+  if (
+    existingReportId !== undefined &&
+    (typeof existingReportId !== "string" ||
+      !/^[a-f0-9]{32}$/.test(existingReportId))
+  )
+    throw failure(
+      "hosted-configuration",
+      "Use a recorded 32-character lowercase hexadecimal report ID.",
+    );
   const limits = { ...defaults, ...overrides };
   if (
     Object.keys(limits).some(
@@ -147,46 +161,54 @@ export async function checkHosted(
       if (response) await discard(response);
     }
   }
+  const status = (phase) => {
+    try {
+      onStatus?.(phase);
+    } catch {}
+  };
   try {
-    const reportUrl = await request(
-      origin + "/check",
-      {
-        method: "POST",
-        headers: {
-          "content-type": "application/x-www-form-urlencoded",
-          accept: "application/json",
-        },
-        body: new URLSearchParams({ package: spec }),
-      },
-      async (response) => {
-        if (response.status !== 303)
-          throw failure(
-            "hosted-submit-failed",
-            `The hosted service did not accept the check (HTTP ${response.status}). No local fallback was attempted.`,
-          );
-        const location = response.headers.get("location");
-        let url;
-        try {
-          url = new URL(location, origin);
-        } catch {}
-        if (
-          !location ||
-          location.length > 2048 ||
-          !url ||
-          url.origin !== origin ||
-          url.username ||
-          url.password ||
-          url.search ||
-          url.hash ||
-          !/^\/r\/[a-f0-9]{32}$/.test(url.pathname)
-        )
-          throw failure(
-            "hosted-response",
-            "The hosted service returned an invalid report location.",
-          );
-        return url.href + ".json";
-      },
-    );
+    if (!existingReportId) status("submitting");
+    const reportUrl = existingReportId
+      ? `${origin}/r/${existingReportId}.json`
+      : await request(
+          origin + "/check",
+          {
+            method: "POST",
+            headers: {
+              "content-type": "application/x-www-form-urlencoded",
+              accept: "application/json",
+            },
+            body: new URLSearchParams({ package: spec }),
+          },
+          async (response) => {
+            if (response.status !== 303)
+              throw failure(
+                "hosted-submit-failed",
+                `The hosted service did not accept the check (HTTP ${response.status}). No local fallback was attempted.`,
+              );
+            const location = response.headers.get("location");
+            let url;
+            try {
+              url = new URL(location, origin);
+            } catch {}
+            if (
+              !location ||
+              location.length > 2048 ||
+              !url ||
+              url.origin !== origin ||
+              url.username ||
+              url.password ||
+              url.search ||
+              url.hash ||
+              !/^\/r\/[a-f0-9]{32}$/.test(url.pathname)
+            )
+              throw failure(
+                "hosted-response",
+                "The hosted service returned an invalid report location.",
+              );
+            return url.href + ".json";
+          },
+        );
     const id = new URL(reportUrl).pathname.slice(3, -5);
     for (;;) {
       const result = await request(
@@ -208,8 +230,14 @@ export async function checkHosted(
                 "hosted-response",
                 "The hosted service returned an invalid pending report.",
               );
+            status(value.status);
             return null;
           }
+          if (
+            ["failed", "incomplete"].includes(value?.status) &&
+            value.id === id
+          )
+            throw advisoryOnly(value.advisoryResult, claim);
           try {
             validateReport(value);
             if (
@@ -227,7 +255,34 @@ export async function checkHosted(
           return value;
         },
       );
-      if (result) return result;
+      if (result) {
+        if (!withDetails) return result;
+        status("details");
+        const detailsUrl = reportUrl.replace(/\.json$/, ".details.json");
+        const fetchDetails = () =>
+          request(
+            detailsUrl,
+            { headers: { accept: "application/json" } },
+            async (response) => {
+              if (response.status !== 200)
+                throw failure(
+                  "hosted-details-failed",
+                  `Hosted package details are unavailable (HTTP ${response.status}).`,
+                );
+              const value = await readJson(
+                response,
+                Math.min(limits.maxBodyBytes, 4194304),
+              );
+              validateDetails(value, result);
+              return value;
+            },
+          );
+        // Check summaries keep a completed report when only details fail.
+        const details = optionalDetails
+          ? await fetchDetails().catch(() => null)
+          : await fetchDetails();
+        return { report: result, details, reportUrl, detailsUrl };
+      }
       await delay(limits.pollMs, undefined, { signal: lifetime });
     }
   } catch (error) {
@@ -249,3 +304,156 @@ export async function checkHosted(
     clearTimeout(totalTimer);
   }
 }
+
+function validateDetails(value, report) {
+  const list = (entry) =>
+    entry &&
+    Array.isArray(entry.items) &&
+    entry.items.length <= 20000 &&
+    entry.items.every(
+      (item) =>
+        item !== null && typeof item === "object" && !Array.isArray(item),
+    ) &&
+    ["total", "returned", "omitted"].every(
+      (key) => Number.isSafeInteger(entry[key]) && entry[key] >= 0,
+    ) &&
+    entry.returned === entry.items.length &&
+    entry.total === entry.returned + entry.omitted;
+  const identity = value?.identity?.items?.[0];
+  if (
+    value?.detailsVersion !== "1" ||
+    value?.reportSchemaVersion !== report.schemaVersion ||
+    !list(value.identity) ||
+    identity?.requested?.name !== report.inputs.claim.name ||
+    identity?.requested?.version !== report.inputs.claim.version ||
+    identity?.artifactDigests?.sha256 !== report.inputs.artifact.sha256 ||
+    !list(value.declarations?.fields) ||
+    !list(value.scripts?.entries) ||
+    !Array.isArray(value.dependencies?.categories) ||
+    value.dependencies.categories.length > 6 ||
+    value.dependencies.categories.some(
+      (category) => !list(category?.entries),
+    ) ||
+    !list(value.provenance?.facts) ||
+    !list(value.inventory?.files)
+  )
+    throw failure(
+      "hosted-details-invalid",
+      "Hosted details failed version, identity or inventory validation.",
+    );
+  const check = value.vulnerabilityCheck;
+  if (
+    check &&
+    (check.source !== "OSV" ||
+      ![
+        "found",
+        "none-reported",
+        "incomplete",
+        "unavailable",
+        "not-assessed",
+      ].includes(check.status) ||
+      typeof check.complete !== "boolean" ||
+      !Array.isArray(check.advisories) ||
+      check.complete !== ["found", "none-reported"].includes(check.status) ||
+      (check.status === "found" && check.advisories.length === 0) ||
+      (check.status === "none-reported" && check.advisories.length !== 0) ||
+      (check.package &&
+        (check.package.ecosystem !== "npm" ||
+          check.package.name !== report.inputs.claim.name ||
+          check.package.version !== report.inputs.claim.version)) ||
+      (check.complete &&
+        (!check.package || !["found", "none-reported"].includes(check.status))))
+  )
+    throw failure(
+      "hosted-details-invalid",
+      "Hosted OSV details failed status or identity validation.",
+    );
+}
+
+const ADVISORY_ASSESSMENTS = {
+  found: "advisories-reported",
+  "none-reported": "no-advisory-reported",
+  incomplete: "advisory-lookup-incomplete",
+  unavailable: "advisory-lookup-unavailable",
+};
+const bounded = (value, max, optional = false) =>
+  (optional && value === undefined) ||
+  (typeof value === "string" && Buffer.byteLength(value) <= max);
+const strings = (value, count, max) =>
+  Array.isArray(value) &&
+  value.length <= count &&
+  value.every((item) => bounded(item, max));
+function advisoryRecord(item) {
+  return (
+    item !== null &&
+    typeof item === "object" &&
+    !Array.isArray(item) &&
+    typeof item.id === "string" &&
+    /^[a-zA-Z0-9:_.-]{1,256}$/.test(item.id) &&
+    bounded(item.summary, 2048, true) &&
+    bounded(item.databaseSeverity, 64, true) &&
+    (item.aliases === undefined || strings(item.aliases, 16, 256))
+  );
+}
+function advisoryOnly(result, claim) {
+  const check = result?.vulnerabilityCheck;
+  const exact = (item) =>
+    item?.ecosystem === "npm" &&
+    item.name === claim.name &&
+    item.version === claim.version;
+  const complete = ["found", "none-reported"].includes(check?.status);
+  if (
+    result?.schemaVersion !== "1" ||
+    result.kind !== "advisory-only" ||
+    result.safetyVerdict !== "not-provided" ||
+    result.artifactVerification?.status !== "not-performed" ||
+    result.sourceComparison?.status !== "not-performed" ||
+    !bounded(result.artifactVerification.reason, 128, true) ||
+    !bounded(result.notice, 1024) ||
+    !exact(result.package) ||
+    !exact(check?.package) ||
+    check.schemaVersion !== "1" ||
+    check.source !== "OSV" ||
+    !bounded(check.queriedAt, 64) ||
+    !Number.isFinite(Date.parse(check.queriedAt)) ||
+    !Number.isSafeInteger(check.pagesFetched) ||
+    check.pagesFetched < 0 ||
+    check.pagesFetched > 100 ||
+    (complete && (check.pagesFetched === 0 || check.reasons.length !== 0)) ||
+    (!complete && check.reasons.length === 0) ||
+    !Object.hasOwn(ADVISORY_ASSESSMENTS, check.status) ||
+    result.assessment !== ADVISORY_ASSESSMENTS[check.status] ||
+    check.complete !== complete ||
+    !strings(check.reasons, 16, 128) ||
+    !Array.isArray(check.advisories) ||
+    check.advisories.length > 100 ||
+    !check.advisories.every(advisoryRecord) ||
+    result.advisoryCount !== check.advisories.length ||
+    (check.status === "found" && check.advisories.length === 0) ||
+    (check.status === "none-reported" && check.advisories.length !== 0)
+  )
+    return failure(
+      "hosted-report-failed",
+      "The hosted analysis did not finish and returned no valid advisory-only result. No local fallback was attempted.",
+    );
+  const error = failure(
+    "hosted-advisory-only",
+    "The registry artifact could not be analyzed; only exact-version advisories are available. No verdict is claimed.",
+  );
+  error.advisoryResult = result;
+  return error;
+}
+
+export async function checkHosted(spec, options) {
+  return runHosted(spec, options);
+}
+
+export async function getHostedDetails(spec, options) {
+  return runHosted(spec, options, true);
+}
+
+export async function getHostedDetailsForReport(spec, reportId, options = {}) {
+  if (reportId === undefined)
+    throw failure("hosted-configuration", "An existing report ID is required.");
+  return runHosted(spec, { ...options, existingReportId: reportId }, true);
+}

package/dist/cli/info.mjs

@@ -0,0 +1,125 @@
+import { parsePackageSpec, AcquisitionError } from "../core/acquire.mjs";
+import { LocalInputError } from "../core/pipeline.mjs";
+import { getHostedDetails } from "./hosted.mjs";
+
+export function terminalText(value, max = 2048) {
+  const text =
+    typeof value === "string" ? value : (JSON.stringify(value) ?? "unknown");
+  const escaped = text.replace(
+    /[\x00-\x1f\x7f-\x9f\u061c\u200b-\u200f\u2028-\u202e\u2060\u2066-\u2069\ufeff]/g,
+    (char) => "\\u" + char.charCodeAt(0).toString(16).padStart(4, "0"),
+  );
+  return escaped.length > max
+    ? escaped.slice(0, max) + "… [truncated]"
+    : escaped;
+}
+
+export function aiLines(model) {
+  const lines = [
+    `AI: ${terminalText(model.status)}${model.reason ? " (" + terminalText(model.reason) + ")" : ""}`,
+  ];
+  if (
+    model.status === "complete" &&
+    typeof model.summary === "string" &&
+    model.summary.trim()
+  )
+    lines.push(`AI summary: ${terminalText(model.summary)}`);
+  return lines;
+}
+
+export function exactPackage(spec) {
+  try {
+    return parsePackageSpec(spec);
+  } catch (error) {
+    if (error instanceof AcquisitionError)
+      throw new LocalInputError(error.code, error.message);
+    throw error;
+  }
+}
+
+export function hostedOptions(runtime) {
+  return {
+    serverUrl: (runtime.env ?? process.env).UNMASK_SERVER_URL,
+    fetchImpl: runtime.fetchImpl,
+    signal: runtime.signal,
+    limits: runtime.hostedLimits,
+  };
+}
+
+function rows(list, render, max = 100) {
+  const items = list?.items ?? [];
+  const lines = items.slice(0, max).map(render);
+  const omitted = (list?.omitted ?? 0) + Math.max(0, items.length - max);
+  if (omitted)
+    lines.push(`  ${omitted} entries omitted by hosted/terminal limits.`);
+  return lines;
+}
+
+export function renderInfo({ details, report, reportUrl }) {
+  const claim = report.inputs.claim;
+  const text = terminalText;
+  const lines = [
+    `UNMASK info ${text(claim.name)}@${text(claim.version)}`,
+    "Publisher declarations (runtime behavior unverified):",
+    ...rows(
+      details.declarations.fields,
+      (item) =>
+        `  ${text(item.field)}: ${text(item.status === "declared" ? item.value : item.status)}`,
+    ),
+    "Scripts (never executed):",
+    `  Status: ${text(details.scripts.status)}`,
+    ...rows(
+      details.scripts.entries,
+      (item) =>
+        `  ${text(item.name)}: ${text(item.value)}${item.installHook ? " [install hook]" : ""}`,
+    ),
+    "Dependencies (declared only; transitive dependencies not assessed):",
+  ];
+  for (const category of details.dependencies.categories)
+    lines.push(
+      `  ${text(category.field)}: ${text(category.status)}; declared=${text(category.declaredCount)}`,
+      ...rows(
+        category.entries,
+        (item) =>
+          `    ${text(item.name)}${Object.hasOwn(item, "value") ? ": " + text(item.value) : ""} [${text(item.status)}]`,
+      ),
+    );
+  lines.push(
+    "Provenance (report-recorded verification status):",
+    ...rows(
+      details.provenance.facts,
+      (item) => `  ${text(item.field)}: ${text(item.value)}`,
+    ),
+  );
+  const check = details.vulnerabilityCheck;
+  lines.push(
+    `OSV exact-package query: ${text(check?.status ?? "not-assessed")}; complete=${check?.complete === true}`,
+  );
+  if (check?.queriedAt) lines.push(`  Queried at: ${text(check.queriedAt)}`);
+  if (check?.reasons?.length) lines.push(`  Reasons: ${text(check.reasons)}`);
+  const advisories = check?.advisories ?? [];
+  for (const item of advisories.slice(0, 100))
+    lines.push(
+      `  ${text(item?.id)}: ${text(item?.summary ?? "No summary recorded")}`,
+    );
+  if (advisories.length > 100)
+    lines.push(
+      `  ${advisories.length - 100} advisory records omitted from terminal output.`,
+    );
+  lines.push(
+    ...aiLines(report.model),
+    `Inventory complete: ${details.inventory.complete === true}; coverage complete: ${report.coverage.complete === true}`,
+    "This is not a safety verdict. No findings never means safe; missing or omitted facts remain unassessed.",
+    `Report: ${text(reportUrl)}`,
+  );
+  return lines.join("\n") + "\n";
+}
+
+export async function infoCommand(args, runtime = {}) {
+  if (args.length !== 1)
+    throw new LocalInputError("usage", "Use info name@exact-version");
+  exactPackage(args[0]);
+  const result = await getHostedDetails(args[0], hostedOptions(runtime));
+  (runtime.stdout ?? process.stdout).write(renderInfo(result));
+  return 0;
+}

package/dist/cli/init.mjs

@@ -0,0 +1,57 @@
+import {
+  DEFAULT_PROFILE,
+  GUARD_CONFIG_SCHEMA,
+  GuardConfigError,
+  createGuardConfig,
+  loadGuardSettings,
+  validateSetting,
+} from "../core/guard-config.mjs";
+import { parseCommandOptions } from "./config.mjs";
+
+const USAGE =
+  "Use init [--profile strict|balanced|audit] [--project DIR]; it only creates a new .unmask.json and never installs or runs anything";
+
+export async function runInit(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,
+      [],
+      ["--project", "--profile"],
+    );
+    if (positional.length) throw new GuardConfigError("usage", USAGE);
+    const profile = validateSetting(
+      "profile",
+      options.profile ?? DEFAULT_PROFILE,
+    );
+    const project = options.project ?? runtime.cwd ?? process.cwd();
+    const created = await createGuardConfig(
+      project,
+      { schemaVersion: GUARD_CONFIG_SCHEMA, profile },
+      { now },
+    );
+    const loaded = await loadGuardSettings(project, { now });
+    if (loaded.source !== "file" || loaded.settings.profile !== profile)
+      throw new GuardConfigError(
+        "verify-failed",
+        "The created configuration did not read back as written",
+      );
+    stdout.write(
+      `Created ${created.file} with profile ${profile} (enforcement ${loaded.settings.enforcement}).\nNext: unmask config show; add exact expiring exceptions only with unmask exceptions add.\n`,
+    );
+    for (const warning of loaded.warnings)
+      stderr.write(`warning: ${warning}\n`);
+    return 0;
+  } catch (error) {
+    if (error instanceof GuardConfigError) {
+      stderr.write(`${error.code}: ${error.message}\n`);
+      return 2;
+    }
+    stderr.write(
+      "init-failed: Guard configuration could not be created; no file is claimed.\n",
+    );
+    return 1;
+  }
+}