@xagents_in/unmask 0.1.2 → 0.1.4

package/dist/model/summary.mjs

@@ -0,0 +1,183 @@
+export const SUMMARY_POLICY = "every-check-2";
+const SUMMARY_TEMPLATE = "≤600 chars";
+const SUMMARY_TASK =
+  " Ground summary and assessment in scope and evidence; no safety verdicts.";
+const ASSESSMENT_TEMPLATE = {
+  uncertainty: "unchecked ≤300",
+  nextAction: "review step ≤200",
+};
+const VERDICT =
+  /\b(?:(?:un)?safe(?:ly|ty)?|benign|harmless|malware-free|risk-free|trustworthy|no risks?)\b/iu;
+// Only exact caveat templates may mention safety; any other negation still counts as a verdict.
+const CAVEAT =
+  /\bnot (?:a |an )?(?:proof|evidence|guarantee|indication)(?: that)?(?: (?:the|this) package| it)?(?: is)? safe\b|\b(?:not a|no) safety (?:verdict|signal|claim|guarantee)\b|\bdoes not (?:mean|imply|prove|establish|show) (?:that )?(?:it|the package|this package) is safe\b/giu;
+const ABSENCE_CLAIM =
+  /\b(?:absent|missing|lacks?|omits?)\b|does not (?:exist|contain|include)|not (?:present|in)\b|not found(?! within supplied evidence)/iu;
+const SCOPED_ABSENCE =
+  /\b(?:absent|missing|not (?:present|found|in))\s+(?:(?:from|in|within)\s+)?(?:the\s+)?(?:selected source|supplied (?:evidence|scope))\b|\bsource(?: archive)? (?:is|was) (?:missing|absent)\b|\bomits?\s+\d+\s+(?:evidence\s+)?(?:items?|groups?)\b/giu;
+const REVIEW_STEP =
+  /^(?:review|inspect|compare|confirm|verify|check|locate|examine|trace|investigate|read|diff|audit)\b/iu;
+const GO_AHEAD =
+  /\b(?:proceed|go ahead|approve|ok(?:ay)? to|fine to|safe to|allow(?:ed)? to install)\b/iu;
+// Controls, invisible format characters and line separators are rejected; newline and tab stay allowed.
+const CONTROL = /(?![\n\t])[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+const FENCE = /^\s*```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*```\s*$/u;
+export const hasControl = (value) => CONTROL.test(value);
+// One whole-body code fence is unwrapped; JSON embedded in other prose is still rejected.
+export const unfence = (raw) => FENCE.exec(raw)?.[1] ?? raw;
+const counter = (value) =>
+  Number.isSafeInteger(value) && value >= 0 ? value : null;
+const ruleIds = (items) =>
+  [
+    ...new Set(
+      items
+        .map((item) => item?.ruleId)
+        .filter(
+          (id) => typeof id === "string" && /^[a-z0-9-]{1,64}$/u.test(id),
+        ),
+    ),
+  ].sort();
+const list = (value) => (Array.isArray(value) ? value : []);
+
+export function scopeFor(report, bundle) {
+  const files = list(report.files);
+  const states = {};
+  for (const file of files) {
+    const state = /^[a-z-]{1,32}$/u.test(file?.state ?? "")
+      ? file.state
+      : "other";
+    states[state] = (states[state] ?? 0) + 1;
+  }
+  const coverage = report.coverage ?? {};
+  const findings = list(report.policy?.findings);
+  const cues = list(report.cues);
+  const supplied = new Set(list(bundle.evidenceGroups).map((g) => g.ruleId));
+  const scope = {
+    files: files.length,
+    states,
+    inventory: counter(coverage.inventory?.files),
+    complete: coverage.inventory?.complete === true,
+    compared: counter(coverage.compared?.files),
+    syntax: counter(coverage.syntaxInspected?.files),
+    source: /^[a-z-]{1,32}$/u.test(report.source?.status ?? "")
+      ? report.source.status
+      : "unknown",
+    exit: counter(report.policy?.exitCode),
+    findings: findings.length,
+    cues: cues.length,
+    // Rule IDs already named by a supplied group are not repeated.
+    unseenRules: ruleIds([...findings, ...cues])
+      .filter((id) => !supplied.has(id))
+      .slice(0, 6),
+    supplied: bundle.selected.size,
+    omitted: bundle.omittedEvidenceIds.length,
+  };
+  for (const [key, value] of Object.entries(scope))
+    if (value === null || (Array.isArray(value) && !value.length))
+      delete scope[key];
+  return scope;
+}
+
+export function summaryBundle(promptFor, report, inputLimit) {
+  let limit = inputLimit;
+  for (let pass = 0; pass < 6; pass++) {
+    const bundle = promptFor(report, limit);
+    const scope = scopeFor(report, bundle);
+    const payload = JSON.parse(bundle.prompt);
+    const prompt = JSON.stringify({
+      ...payload,
+      task: payload.task + SUMMARY_TASK,
+      output: {
+        summary: SUMMARY_TEMPLATE,
+        assessment: ASSESSMENT_TEMPLATE,
+        ...payload.output,
+      },
+      scope,
+    });
+    const over = Buffer.byteLength(prompt) + 256 - inputLimit;
+    if (over <= 0 || pass === 5) return { ...bundle, prompt, scope };
+    // Repack below the bytes actually used so each pass strictly shrinks evidence.
+    limit = Math.min(limit, Buffer.byteLength(bundle.prompt) + 256) - over;
+  }
+}
+
+function prose(value, max, secret) {
+  return (
+    typeof value === "string" &&
+    value.trim().length > 0 &&
+    value.length <= max &&
+    !value.includes(secret) &&
+    !hasControl(value) &&
+    !VERDICT.test(value.replace(CAVEAT, " ")) &&
+    !ABSENCE_CLAIM.test(value.replace(SCOPED_ABSENCE, " "))
+  );
+}
+
+const NONE = "(?:no|zero|0|without(?: any)?)\\s+";
+const UNLOCALIZED = "(?!\\s+(?:in|for|on|within)\\b)";
+const NO_FINDINGS = new RegExp(
+  `\\b${NONE}(?:default\\s+)?(?:policy\\s+)?findings?\\b${UNLOCALIZED}`,
+  "iu",
+);
+const NO_CUES = new RegExp(
+  `\\b${NONE}(?:review\\s+)?(?:cues?|suggestions?|observations?)\\b${UNLOCALIZED}`,
+  "iu",
+);
+const ALL_SAME = new RegExp(
+  `\\b(?:all|every|each)\\b[^.;]{0,40}?\\b(?:byte-identical|identical|unchanged|match(?:es|ed)?)\\b|\\b(?:no|zero)\\s+(?:file\\s+)?(?:changes?|differences?)\\b${UNLOCALIZED}|\\bno\\s+files?\\s+(?:changed|differ(?:s|ed)?)\\b|\\bnothing\\s+(?:changed|differs)\\b`,
+  "iu",
+);
+// Whole-report claims must not contradict the deterministic scope the model was given.
+export function consistentWithScope(value, scope = {}) {
+  const states = scope.states ?? {};
+  const differs = Object.keys(states).some(
+    (state) => state !== "byte-identical" && states[state] > 0,
+  );
+  return !(
+    (scope.findings > 0 && NO_FINDINGS.test(value)) ||
+    (scope.cues > 0 && NO_CUES.test(value)) ||
+    (differs && ALL_SAME.test(value))
+  );
+}
+
+export function validSummary(value, secret, scope) {
+  return prose(value, 600, secret) && consistentWithScope(value, scope);
+}
+
+export function validAssessment(value, secret) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 2 &&
+    prose(value.uncertainty, 300, secret) &&
+    prose(value.nextAction, 200, secret) &&
+    REVIEW_STEP.test(value.nextAction.trim()) &&
+    !GO_AHEAD.test(value.nextAction)
+  );
+}
+
+export function checkedScopeFor(bundle) {
+  const { scope } = bundle;
+  const notChecked = ["runtime-behavior"];
+  if (scope.omitted) notChecked.push("omitted-evidence");
+  if (!scope.complete) notChecked.push("incomplete-inventory");
+  if (!["selected", "resolved"].includes(scope.source))
+    notChecked.push("unselected-source");
+  for (const [key, code] of [
+    ["compared", "uncompared-files"],
+    ["syntax", "uninspected-syntax"],
+  ])
+    if (!(scope[key] >= (scope.inventory ?? 0))) notChecked.push(code);
+  return {
+    basis: "deterministic-prompt-selection",
+    evidenceSupplied: scope.supplied,
+    evidenceOmitted: scope.omitted,
+    groupsSupplied: bundle.evidenceGroups.length,
+    groupsOmitted: bundle.omittedEvidenceGroups.length,
+    paths: [...new Set([...bundle.selected.values()].map((e) => e.path))]
+      .sort()
+      .slice(0, 16),
+    notChecked,
+  };
+}

package/dist/server/advisory-result.mjs

@@ -0,0 +1,137 @@
+import {
+  boundedVulnerabilityCheck,
+  unavailableVulnerabilityCheck,
+} from "./enrichment.mjs";
+
+const escape = (value) =>
+  String(value ?? "").replace(
+    /[&<>"']/g,
+    (ch) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[
+        ch
+      ],
+  );
+
+const ASSESSMENTS = {
+  found: "advisories-reported",
+  incomplete: "advisory-lookup-incomplete",
+  "none-reported": "no-advisory-reported",
+  unavailable: "advisory-lookup-unavailable",
+};
+
+export function advisoryOnlyResult(vulnerabilityCheck, { artifactReason }) {
+  const status = vulnerabilityCheck?.status;
+  const assessment = ASSESSMENTS[status] ?? "advisory-lookup-unavailable";
+  return {
+    schemaVersion: "1",
+    kind: "advisory-only",
+    package: vulnerabilityCheck?.package ?? null,
+    assessment,
+    advisoryCount: vulnerabilityCheck?.advisories?.length ?? 0,
+    artifactVerification: { status: "not-performed", reason: artifactReason },
+    sourceComparison: { status: "not-performed", reason: artifactReason },
+    safetyVerdict: "not-provided",
+    notice:
+      assessment === "advisories-reported" ||
+      (assessment === "advisory-lookup-incomplete" &&
+        vulnerabilityCheck.advisories.length > 0)
+        ? "Published advisories match this exact version. The registry artifact was not inspected, so no tarball or source evidence is included."
+        : "No artifact was inspected. Absence of a current advisory, or an unavailable lookup, is not evidence of safety, and an unacquirable artifact is not by itself evidence of malware.",
+    vulnerabilityCheck,
+  };
+}
+
+export function renderAdvisoryResult(result) {
+  const check = result.vulnerabilityCheck;
+  const items = (check?.advisories ?? [])
+    .slice(0, 50)
+    .map(
+      (item) =>
+        `<li><code>${escape(item.id)}</code>${item.aliases?.length ? ` (${item.aliases.map(escape).join(", ")})` : ""}${item.summary ? `: ${escape(item.summary)}` : ""}</li>`,
+    )
+    .join("");
+  return `<section aria-label="Advisory-only result"><h2>Advisory-only result</h2><p class="status failed">${escape(result.assessment)}</p><p>${escape(result.notice)}</p>${items ? `<ul>${items}</ul>` : ""}<p class="meta">OSV lookup status: <code>${escape(check?.status)}</code>${check?.reasons?.length ? `; reasons: <code>${check.reasons.map(escape).join(", ")}</code>` : ""}. Artifact verification: <code>${escape(result.artifactVerification.status)}</code>.</p></section>`;
+}
+
+export function withAdvisoryResult(statusHtml, job) {
+  if (!job.advisoryResult) return statusHtml;
+  return statusHtml.replace(
+    "</div></main>",
+    () => renderAdvisoryResult(job.advisoryResult) + "</div></main>",
+  );
+}
+
+export const ADVISORY_ENDPOINT_LIMITS = Object.freeze({
+  maxLookups: 30,
+  windowMs: 600000,
+  maxActive: 2,
+  timeoutMs: 15000,
+});
+
+export function createAdvisoryService({
+  lookup,
+  clock,
+  limits = ADVISORY_ENDPOINT_LIMITS,
+}) {
+  const inflight = new Map();
+  const shutdown = new AbortController();
+  let admissions = [];
+  function run(spec) {
+    const controller = new AbortController();
+    const signal = AbortSignal.any([shutdown.signal, controller.signal]);
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = clock.setTimeout(() => {
+        controller.abort();
+        resolve(unavailableVulnerabilityCheck(spec, clock, "timeout"));
+      }, limits.timeoutMs);
+      timer?.unref?.();
+    });
+    return Promise.race([
+      Promise.resolve()
+        .then(() => lookup(spec, { signal }))
+        .then((value) => boundedVulnerabilityCheck(value, spec, clock))
+        .catch(() =>
+          unavailableVulnerabilityCheck(spec, clock, "lookup-failed"),
+        ),
+      timeout,
+    ])
+      .then((check) =>
+        advisoryOnlyResult(check, { artifactReason: "not-requested" }),
+      )
+      .finally(() => {
+        clock.clearTimeout(timer);
+        inflight.delete(spec);
+      });
+  }
+  return {
+    request(spec) {
+      const existing = inflight.get(spec);
+      if (existing) return { promise: existing, reused: true };
+      const now = clock.now();
+      admissions = admissions.filter((time) => now - time < limits.windowMs);
+      if (
+        shutdown.signal.aborted ||
+        inflight.size >= limits.maxActive ||
+        admissions.length >= limits.maxLookups
+      )
+        return {
+          retryAfter: Math.max(
+            1,
+            Math.ceil(
+              (admissions.length >= limits.maxLookups
+                ? admissions[0] + limits.windowMs - now
+                : limits.timeoutMs) / 1000,
+            ),
+          ),
+        };
+      admissions.push(now);
+      const promise = run(spec);
+      inflight.set(spec, promise);
+      return { promise, reused: false };
+    },
+    close() {
+      shutdown.abort();
+    },
+  };
+}

package/dist/server/app.mjs

@@ -1,8 +1,17 @@
 import { createServer } from "node:http";
+import { createRegistryFactsHandler } from "./registry-facts.mjs";
+import { guardDecisionResponse } from "./guard-decision.mjs";
 import { buildPackageDetails } from "../core/package-details.mjs";
 import { attachVulnerabilityCheck } from "./enrichment.mjs";
+import {
+  createAdvisoryService,
+  withAdvisoryResult,
+} from "./advisory-result.mjs";
+import { createDependencyScreening } from "./dependency-screening.mjs";
+import { serveExport } from "./exports.mjs";
 import { createQueue, resolveLimits, systemClock } from "./queue.mjs";
 import { createReportStore } from "./store.mjs";
+import { handleReportExploration } from "./report-exploration.mjs";
 import { renderReport } from "../viewer/render.mjs";
 import {
   renderHome,
@@ -102,9 +111,11 @@ export function createCacheKeyPrefix(versionInfo, limits) {
 export function createApp({
   runAnalysis,
   enrichJob,
+  advisoryLookup,
   versionInfo,
   limits: overrides,
   clock = systemClock,
+  registryFacts = {},
 } = {}) {
   if (typeof runAnalysis !== "function")
     throw new TypeError("runAnalysis is required");
@@ -119,6 +130,7 @@ export function createApp({
     );
   if (enrichJob !== undefined && typeof enrichJob !== "function")
     throw new TypeError("enrichJob must be a function");
+  const registryFactsHandler = createRegistryFactsHandler(registryFacts);
   const limits = resolveLimits(overrides);
   const version = Object.fromEntries(
     ["version", "commit", "tarballSha256"].map((key) => [
@@ -133,6 +145,10 @@ export function createApp({
     clock,
   });
   const keyPrefix = createCacheKeyPrefix(versionInfo, limits);
+  const screenDependencies = createDependencyScreening({
+    lookup: advisoryLookup,
+    clock,
+  });
   const queue = createQueue({
     runAnalysis,
     enrichJob,
@@ -141,6 +157,8 @@ export function createApp({
     clock,
     keyPrefix,
   });
+  const advisories =
+    enrichJob && createAdvisoryService({ lookup: enrichJob, clock });
   const server = createServer(
     { maxHeaderSize: 8192, headersTimeout: 10000, requestTimeout: 15000 },
     (req, res) => {
@@ -172,8 +190,28 @@ export function createApp({
       function error(status, title, message, headers) {
         send(status, renderError({ title, message }), undefined, headers);
       }
+      async function advisoryEndpoint(params) {
+        const spec =
+          params.size === 1 && parseNameAtExactVersion(params.get("package"));
+        if (!spec) return json(400, { error: "invalid-package-spec" });
+        if (!advisories)
+          return json(503, { error: "advisory-lookup-disabled" });
+        const result = advisories.request(spec);
+        if (!result.promise)
+          return json(
+            429,
+            { error: "rate-limited", retryAfter: result.retryAfter },
+            { "retry-after": String(result.retryAfter) },
+          );
+        return json(200, await result.promise, {
+          "x-unmask-reused": String(result.reused),
+        });
+      }
       async function handle() {
         const path = req.url;
+        if (await registryFactsHandler(req, json)) return;
+        if (path === "/api/dependency-screening")
+          return screenDependencies(req, res, json);
         if (path === "/check") {
           if (req.method !== "POST")
             return error(
@@ -250,6 +288,25 @@ export function createApp({
             "x-unmask-reused": String(result.reused),
           });
         }
+        const decisionMatch =
+          /^\/r\/([a-f0-9]{32})\.decision\.json(\?[^#]*)?$/.exec(path);
+        if (decisionMatch) {
+          if (req.method !== "GET")
+            return json(405, { error: "method-unavailable" }, { allow: "GET" });
+          const decisionJob = queue.get(decisionMatch[1]);
+          // A job without a report keeps its exact-version advisory lookup inside advisoryResult.
+          const result = guardDecisionResponse(
+            decisionJob?.advisoryResult && !decisionJob.vulnerabilityCheck
+              ? {
+                  ...decisionJob,
+                  vulnerabilityCheck:
+                    decisionJob.advisoryResult.vulnerabilityCheck,
+                }
+              : decisionJob,
+            { search: decisionMatch[2] ?? "" },
+          );
+          return json(result.status, result.body, result.headers);
+        }
         if (req.method !== "GET")
           return error(
             405,
@@ -257,9 +314,13 @@ export function createApp({
             "Use the release form to start a check.",
             { allow: "GET" },
           );
+        if (handleReportExploration({ path, getJob: queue.get, send })) return;
         if (path === "/") return send(200, renderHome());
         if (path === "/healthz") return json(200, { status: "ok" });
         if (path === "/version") return json(200, version);
+        if (path.startsWith("/api/advisory?"))
+          return advisoryEndpoint(new URLSearchParams(path.slice(14)));
+        if (serveExport({ path, queue, versionInfo: version, send })) return;
         const match = /^\/r\/([a-f0-9]{32})(\.details\.json|\.json)?$/.exec(
           path,
         );
@@ -305,7 +366,7 @@ export function createApp({
           return send(200, renderCompleted(renderReport(job.report), job));
         return send(
           200,
-          renderStatus(job),
+          withAdvisoryResult(renderStatus(job), job),
           undefined,
           pending ? { "retry-after": "3" } : {},
         );
@@ -319,6 +380,9 @@ export function createApp({
       );
     },
   );
-  server.on("close", () => queue.close());
+  server.on("close", () => {
+    queue.close();
+    advisories?.close();
+  });
   return server;
 }