@xagents_in/unmask 0.1.1 → 0.1.3

package/dist/model/client.mjs

@@ -9,7 +9,6 @@ const MODELS = new Set([
   "gemini-3-flash-preview",
 ]);
 export const DEFAULT_MODEL_ROUTE = Object.freeze([
-  Object.freeze({ modelId: "gemini-3.5-flash", thinkingLevel: "high" }),
   Object.freeze({
     modelId: "gemini-3-flash-preview",
     thinkingLevel: "minimal",
@@ -661,28 +660,46 @@ const delay = (ms, signal) =>
 function quotaScope(body, modelId) {
   const details = body?.error?.details;
   if (!Array.isArray(details) || details.length > 32) return "unknown";
+  const windows = [];
+  const normalize = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, "");
+  function bindingWindow(binding, identity) {
+    if (/hour|week|month|year|second/.test(identity)) return null;
+    if (binding.includes("perminute") && !/day|daily/.test(identity))
+      return "minute";
+    if (binding.includes("perday") && !identity.includes("perminute"))
+      return "daily";
+    return null;
+  }
   for (const info of details.filter(
     (item) => item?.["@type"] === "type.googleapis.com/google.rpc.ErrorInfo",
   )) {
     const metadata = info.metadata;
-    const identity =
-      `${info.reason ?? ""} ${metadata?.quota_limit ?? ""} ${metadata?.quota_metric ?? ""}`
-        .toLowerCase()
-        .replace(/[^a-z0-9]/g, "");
-    if (identity.includes("day")) return "daily";
+    const binding = normalize(
+      `${metadata?.quota_limit ?? ""} ${metadata?.quota_metric ?? ""}`,
+    );
+    const reason = normalize(String(info.reason ?? ""));
     if (
       ["global", "project"].includes(metadata?.scope) ||
-      (identity.includes("perproject") && !identity.includes("permodel"))
+      reason.includes("global") ||
+      (reason.includes("project") && !reason.includes("model")) ||
+      (binding.includes("perproject") && !binding.includes("permodel"))
     )
       return "global";
+    const window = bindingWindow(binding, binding + reason);
     if (
       !metadata ||
+      !["", "ratelimitexceeded", "quotaexceeded", "resourceexhausted"].includes(
+        reason,
+      ) ||
       ![modelId, `models/${modelId}`].includes(metadata.model) ||
-      !identity.includes("permodel") ||
-      !identity.includes("perminute") ||
-      /hour|week|month|year|second/.test(identity)
+      !binding.includes("permodel") ||
+      !window ||
+      (metadata.scope !== undefined &&
+        metadata.scope !== "model" &&
+        !(metadata.scope === "daily" && window === "daily"))
     )
       return "unknown";
+    windows.push(window);
   }
   const violations = [];
   for (const detail of details) {
@@ -697,40 +714,34 @@ function quotaScope(body, modelId) {
     violations.push(...detail.violations);
   }
   if (!violations.length) return "unknown";
-  if (
-    violations.some((item) =>
-      `${item?.quotaId ?? ""} ${item?.quotaMetric ?? ""}`
-        .toLowerCase()
-        .replace(/[^a-z0-9]/g, "")
-        .includes("day"),
-    )
-  )
-    return "daily";
   for (const item of violations) {
     const dimensions = item?.quotaDimensions;
     if (
       !dimensions ||
       typeof dimensions !== "object" ||
       Array.isArray(dimensions) ||
-      !Object.hasOwn(dimensions, "model")
+      !Object.hasOwn(dimensions, "model") ||
+      ["global", "project"].includes(dimensions.scope)
     )
       return "global";
-    if (["global", "project", "daily"].includes(dimensions.scope))
-      return dimensions.scope === "daily" ? "daily" : "global";
     if (![modelId, `models/${modelId}`].includes(dimensions.model))
       return "unknown";
-    const binding = `${item.quotaId ?? ""} ${item.quotaMetric ?? ""}`
-      .toLowerCase()
-      .replace(/[^a-z0-9]/g, "");
+    const binding = normalize(
+      `${item.quotaId ?? ""} ${item.quotaMetric ?? ""}`,
+    );
     if (!binding.includes("permodel"))
       return binding.includes("perproject") ? "global" : "unknown";
+    const window = bindingWindow(binding, binding);
     if (
-      !binding.includes("perminute") ||
-      /hour|week|month|year|second/.test(binding)
+      !window ||
+      (dimensions.scope !== undefined &&
+        dimensions.scope !== "model" &&
+        !(dimensions.scope === "daily" && window === "daily"))
     )
       return "unknown";
+    windows.push(window);
   }
-  return "model";
+  return windows.includes("daily") ? "model-daily" : "model";
 }
 
 export function createGemmaClient(options = {}) {
@@ -753,6 +764,11 @@ export function createGemmaClient(options = {}) {
     )
   )
     throw new TypeError("Invalid model route");
+  if (
+    new Set(requestedRoute.map((item) => item.modelId)).size !==
+    requestedRoute.length
+  )
+    throw new TypeError("Invalid model route: duplicate model");
   if (
     options.route !== undefined &&
     options.modelId !== undefined &&
@@ -795,10 +811,16 @@ export function createGemmaClient(options = {}) {
   }));
   const generationConfig = route[0].generationConfig;
   const routingPolicy = {
-    version: "ordered-fallback-1",
+    version: "ordered-fallback-2",
     maxGenerationAttempts: Math.max(2, route.length),
-    fallthrough: ["model-scoped-429", "transient-5xx", "timeout"],
+    fallthrough: [
+      "model-scoped-minute-429",
+      "model-scoped-daily-429",
+      "transient-5xx",
+      "timeout",
+    ],
     invalidOutputRetry: "same-tier",
+    modelDailyFallback: "next-tier-no-wait",
   };
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
   const now = options.now ?? (() => performance.now());
@@ -1108,12 +1130,17 @@ export function createGemmaClient(options = {}) {
                   body = await jsonResponse(response, controller.signal);
                 } catch {}
                 failureScope = quotaScope(body, tier.modelId);
-                const retry = failureScope === "model";
+                const retry =
+                  failureScope === "model" ||
+                  (failureScope === "model-daily" &&
+                    tierIndex + 1 < route.length);
                 throw Object.assign(
                   new Failure(
                     "quota",
                     retry,
-                    retryDelay(response, wallNow()),
+                    failureScope === "model-daily"
+                      ? 0
+                      : retryDelay(response, wallNow()),
                     retry,
                   ),
                   { scope: failureScope },

package/dist/server/app.mjs

@@ -1,6 +1,10 @@
 import { createServer } from "node:http";
+import { createRegistryFactsHandler } from "./registry-facts.mjs";
+import { buildPackageDetails } from "../core/package-details.mjs";
+import { attachVulnerabilityCheck } from "./enrichment.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,
@@ -99,9 +103,11 @@ export function createCacheKeyPrefix(versionInfo, limits) {
 
 export function createApp({
   runAnalysis,
+  enrichJob,
   versionInfo,
   limits: overrides,
   clock = systemClock,
+  registryFacts = {},
 } = {}) {
   if (typeof runAnalysis !== "function")
     throw new TypeError("runAnalysis is required");
@@ -114,6 +120,9 @@ export function createApp({
     throw new TypeError(
       "versionInfo requires version, commit and tarballSha256 strings",
     );
+  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) => [
@@ -128,7 +137,14 @@ export function createApp({
     clock,
   });
   const keyPrefix = createCacheKeyPrefix(versionInfo, limits);
-  const queue = createQueue({ runAnalysis, store, limits, clock, keyPrefix });
+  const queue = createQueue({
+    runAnalysis,
+    enrichJob,
+    store,
+    limits,
+    clock,
+    keyPrefix,
+  });
   const server = createServer(
     { maxHeaderSize: 8192, headersTimeout: 10000, requestTimeout: 15000 },
     (req, res) => {
@@ -162,6 +178,7 @@ export function createApp({
       }
       async function handle() {
         const path = req.url;
+        if (await registryFactsHandler(req, json)) return;
         if (path === "/check") {
           if (req.method !== "POST")
             return error(
@@ -245,10 +262,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);
-        const match = /^\/r\/([a-f0-9]{32})(\.json)?$/.exec(path);
+        const match = /^\/r\/([a-f0-9]{32})(\.details\.json|\.json)?$/.exec(
+          path,
+        );
         if (!match)
           return error(
             404,
@@ -265,10 +285,21 @@ export function createApp({
         const pending = ["queued", "running"].includes(job.status);
         if (match[2]) {
           if (job.report)
-            return json(200, job.report, {
-              "content-disposition":
-                'attachment; filename="unmask-report.json"',
-            });
+            return json(
+              200,
+              match[2] === ".details.json"
+                ? attachVulnerabilityCheck(
+                    buildPackageDetails(job.report),
+                    job.vulnerabilityCheck,
+                  )
+                : job.report,
+              {
+                "content-disposition":
+                  match[2] === ".details.json"
+                    ? 'attachment; filename="unmask-package-details.json"'
+                    : 'attachment; filename="unmask-report.json"',
+              },
+            );
           const { key, ...publicJob } = job;
           return json(
             pending ? 202 : 200,

package/dist/server/enrichment.mjs

@@ -0,0 +1,116 @@
+export const DETAILS_RESPONSE_LIMITS = Object.freeze({
+  packageDetailsBytes: 2097152,
+  vulnerabilityCheckBytes: 2096128,
+  combinedBytes: 4194304,
+});
+
+export function unavailableVulnerabilityCheck(spec, clock, reason) {
+  const separator = typeof spec === "string" ? spec.lastIndexOf("@") : -1;
+  return {
+    schemaVersion: "1",
+    source: "OSV",
+    package:
+      separator > 0
+        ? {
+            ecosystem: "npm",
+            name: spec.slice(0, separator),
+            version: spec.slice(separator + 1),
+          }
+        : null,
+    queriedAt: new Date(clock.now()).toISOString(),
+    status: "unavailable",
+    complete: false,
+    reasons: [reason],
+    advisories: [],
+    pagesFetched: 0,
+    limits: { resultBytes: DETAILS_RESPONSE_LIMITS.vulnerabilityCheckBytes },
+  };
+}
+
+export function boundedVulnerabilityCheck(value, spec, clock) {
+  try {
+    const json = JSON.stringify(value);
+    if (
+      Buffer.byteLength(json) > DETAILS_RESPONSE_LIMITS.vulnerabilityCheckBytes
+    )
+      return unavailableVulnerabilityCheck(spec, clock, "result-byte-cap");
+    const snapshot = JSON.parse(json);
+    if (
+      snapshot.schemaVersion !== "1" ||
+      snapshot.source !== "OSV" ||
+      !["found", "none-reported", "incomplete", "unavailable"].includes(
+        snapshot.status,
+      ) ||
+      snapshot.complete !==
+        ["found", "none-reported"].includes(snapshot.status) ||
+      !Array.isArray(snapshot.reasons) ||
+      !snapshot.reasons.every((reason) => typeof reason === "string") ||
+      !Array.isArray(snapshot.advisories) ||
+      snapshot.advisories.some(
+        (item) => !item || typeof item !== "object" || Array.isArray(item),
+      ) ||
+      (snapshot.status === "found" && snapshot.advisories.length === 0) ||
+      (snapshot.status === "none-reported" &&
+        snapshot.advisories.length !== 0) ||
+      !Number.isSafeInteger(snapshot.pagesFetched) ||
+      snapshot.pagesFetched < 0 ||
+      (snapshot.complete &&
+        (snapshot.pagesFetched === 0 || snapshot.reasons.length !== 0)) ||
+      typeof snapshot.queriedAt !== "string" ||
+      !Number.isFinite(Date.parse(snapshot.queriedAt)) ||
+      !snapshot.limits ||
+      typeof snapshot.limits !== "object"
+    )
+      throw new TypeError("Invalid vulnerability enrichment");
+    const expected = unavailableVulnerabilityCheck(
+      spec,
+      clock,
+      "unused",
+    ).package;
+    if (
+      snapshot.package !== null &&
+      (snapshot.package.ecosystem !== "npm" ||
+        snapshot.package.name !== expected?.name ||
+        snapshot.package.version !== expected?.version)
+    )
+      throw new TypeError("Vulnerability enrichment identity mismatch");
+    if (snapshot.complete && snapshot.package === null)
+      throw new TypeError("Vulnerability enrichment identity missing");
+    return snapshot;
+  } catch {
+    return unavailableVulnerabilityCheck(spec, clock, "invalid-result");
+  }
+}
+
+export function attachVulnerabilityCheck(details, value) {
+  const vulnerabilityCheck = value ?? {
+    source: "OSV",
+    status: "not-assessed",
+    complete: false,
+    reasons: ["hosted-enrichment-disabled"],
+    advisories: [],
+  };
+  const complete =
+    vulnerabilityCheck.complete === true &&
+    ["found", "none-reported"].includes(vulnerabilityCheck.status);
+  const result = {
+    ...details,
+    scope: {
+      ...details.scope,
+      vulnerabilityScan: complete
+        ? "OSV-exact-package-query-complete"
+        : "not-assessed",
+      knownVulnerabilities: complete
+        ? "queried-exact-package-only"
+        : "not-assessed",
+    },
+    vulnerabilityCheck,
+    responseLimits: DETAILS_RESPONSE_LIMITS,
+  };
+  if (
+    Buffer.byteLength(JSON.stringify(result)) >
+    DETAILS_RESPONSE_LIMITS.combinedBytes
+  )
+    throw new TypeError("Combined details response exceeds cap");
+  return result;
+}

package/dist/server/main.mjs

@@ -47,6 +47,7 @@ export async function startServer({
   runnerOptions = {},
   versionInfo,
   modelClient,
+  enrichJob,
 } = {}) {
   if (
     typeof host !== "string" ||
@@ -62,6 +63,14 @@ export async function startServer({
       : modelClient === undefined
         ? await modelClientFromEnv()
         : modelClient;
+  const enrichment =
+    enrichJob === null
+      ? undefined
+      : enrichJob === undefined
+        ? (await import("../core/advisories.mjs")).lookupNpmAdvisories
+        : enrichJob;
+  if (enrichment !== undefined && typeof enrichment !== "function")
+    throw new TypeError("enrichJob must be a function or null");
   const run = await createRunner({
     ...runnerOptions,
     tempRoot,
@@ -81,6 +90,13 @@ export async function startServer({
   };
   const server = createApp({
     runAnalysis,
+    enrichJob:
+      enrichment === undefined
+        ? undefined
+        : (spec, { signal }) =>
+            enrichment(spec, {
+              signal: AbortSignal.any([signal, shutdown.signal]),
+            }),
     versionInfo: {
       ...(versionInfo || (await loadVersionInfo())),
       modelConfigDigest:

package/dist/server/queue.mjs

@@ -1,4 +1,8 @@
 import { randomBytes } from "node:crypto";
+import {
+  boundedVulnerabilityCheck,
+  unavailableVulnerabilityCheck,
+} from "./enrichment.mjs";
 
 export const DEFAULT_LIMITS = Object.freeze({
   maxBodyBytes: 4096,
@@ -28,6 +32,7 @@ export function resolveLimits(overrides = {}) {
 
 export function createQueue({
   runAnalysis,
+  enrichJob,
   store,
   limits,
   clock = systemClock,
@@ -39,7 +44,20 @@ export function createQueue({
   let admissions = [];
   function persist(job) {
     if (!store.put(job)) {
-      const { report, ...small } = job;
+      if (
+        job.report &&
+        job.vulnerabilityCheck &&
+        store.put({
+          ...job,
+          vulnerabilityCheck: unavailableVulnerabilityCheck(
+            job.nameAtExactVersion,
+            clock,
+            "storage-byte-cap",
+          ),
+        })
+      )
+        return;
+      const { report, vulnerabilityCheck, ...small } = job;
       store.put({ ...small, status: "incomplete", reason: "report-too-large" });
     }
   }
@@ -61,12 +79,26 @@ export function createQueue({
     job.status = "running";
     job.startedAt = clock.now();
     const controller = new AbortController();
+    let coreReport;
     const timer = clock.setTimeout(() => {
-      job.status = "incomplete";
-      job.reason = "execution-timeout";
       job.finishedAt = clock.now();
+      if (coreReport) {
+        job.status = coreReport.policy.exitCode === 2 ? "incomplete" : "done";
+        persist({
+          ...publicJob(job),
+          report: coreReport,
+          vulnerabilityCheck: unavailableVulnerabilityCheck(
+            job.nameAtExactVersion,
+            clock,
+            "aborted",
+          ),
+        });
+      } else {
+        job.status = "incomplete";
+        job.reason = "execution-timeout";
+        persist(job);
+      }
       controller.abort();
-      persist(job);
     }, limits.executionMs);
     timer?.unref?.();
     job.cancel = () => {
@@ -77,7 +109,7 @@ export function createQueue({
       .then(() =>
         runAnalysis(job.nameAtExactVersion, { signal: controller.signal }),
       )
-      .then((report) => {
+      .then(async (report) => {
         if (job.status !== "running" || closed) return;
         if (
           !report ||
@@ -86,9 +118,56 @@ export function createQueue({
           ![0, 2, 3].includes(report.policy?.exitCode)
         )
           throw new TypeError("Invalid report");
+        coreReport = report;
+        let vulnerabilityCheck;
+        if (enrichJob) {
+          let abort;
+          const interrupted = new Promise((resolve) => {
+            abort = () =>
+              resolve(
+                unavailableVulnerabilityCheck(
+                  job.nameAtExactVersion,
+                  clock,
+                  "aborted",
+                ),
+              );
+            controller.signal.addEventListener("abort", abort, { once: true });
+            if (controller.signal.aborted) abort();
+          });
+          try {
+            const value = await Promise.race([
+              Promise.resolve().then(() =>
+                enrichJob(job.nameAtExactVersion, {
+                  signal: controller.signal,
+                }),
+              ),
+              interrupted,
+            ]);
+            vulnerabilityCheck = boundedVulnerabilityCheck(
+              value,
+              job.nameAtExactVersion,
+              clock,
+            );
+          } catch {
+            vulnerabilityCheck = unavailableVulnerabilityCheck(
+              job.nameAtExactVersion,
+              clock,
+              "lookup-failed",
+            );
+          } finally {
+            controller.signal.removeEventListener("abort", abort);
+          }
+        }
+        if (job.status !== "running" || closed) return;
         const status = report.policy.exitCode === 2 ? "incomplete" : "done";
         const finishedAt = clock.now();
-        persist({ ...publicJob(job), status, report, finishedAt });
+        persist({
+          ...publicJob(job),
+          status,
+          report,
+          finishedAt,
+          ...(vulnerabilityCheck ? { vulnerabilityCheck } : {}),
+        });
         job.status = status;
         job.finishedAt = finishedAt;
       })

package/dist/server/registry-facts.mjs

@@ -0,0 +1,118 @@
+import {
+  getRegistryFacts,
+  getRegistryHistory,
+  registryIdentity,
+} from "../core/registry-facts.mjs";
+
+export function createRegistryFactsHandler(options = {}) {
+  const maxConcurrent = options.maxConcurrent ?? 2;
+  const maxRequests = options.maxRequests ?? 30;
+  if (
+    !Number.isSafeInteger(maxConcurrent) ||
+    maxConcurrent < 1 ||
+    maxConcurrent > 2 ||
+    !Number.isSafeInteger(maxRequests) ||
+    maxRequests < 1 ||
+    maxRequests > 30
+  )
+    throw new TypeError("Invalid registry lookup admission limits");
+  let active = 0,
+    used = 0,
+    windowStart = Date.now();
+  return async function handleRegistryFacts(req, json) {
+    const url = new URL(req.url, "http://localhost");
+    const history = url.pathname === "/api/registry/history";
+    if (url.pathname !== "/api/registry/facts" && !history) return false;
+    if (req.method !== "GET") {
+      json(
+        405,
+        { status: "rejected", reason: "method-not-allowed" },
+        { allow: "GET" },
+      );
+      return true;
+    }
+    const spec = url.searchParams.get("package");
+    let limit = 20;
+    try {
+      const allowed = history ? ["package", "limit"] : ["package"];
+      if (
+        !spec ||
+        [...url.searchParams.keys()].some((key) => !allowed.includes(key)) ||
+        allowed.some((key) => url.searchParams.getAll(key).length > 1)
+      )
+        throw new Error();
+      if (history) {
+        registryIdentity(`${spec}@0.0.0`);
+        if (url.searchParams.has("limit")) {
+          const raw = url.searchParams.get("limit");
+          if (!/^[1-9]\d{0,2}$/.test(raw)) throw new Error();
+          limit = Number(raw);
+          if (limit > 100) throw new Error();
+        }
+      } else registryIdentity(spec);
+    } catch {
+      json(400, {
+        status: "rejected",
+        reason: history
+          ? "package-name-and-bounded-limit-required"
+          : "exact-package-required",
+      });
+      return true;
+    }
+    const now = Date.now();
+    if (now - windowStart >= 60000) {
+      used = 0;
+      windowStart = now;
+    }
+    if (active >= maxConcurrent || used >= maxRequests) {
+      json(
+        429,
+        { status: "unavailable", reason: "registry-lookup-limit" },
+        {
+          "retry-after": String(
+            Math.max(1, Math.ceil((60000 - (now - windowStart)) / 1000)),
+          ),
+        },
+      );
+      return true;
+    }
+    used++;
+    active++;
+    try {
+      json(
+        200,
+        history
+          ? await getRegistryHistory(spec, { ...options, limit })
+          : await getRegistryFacts(spec, options),
+      );
+    } catch (error) {
+      const reason = [
+        "acquisition-timeout",
+        "response-cap",
+        "redirect-refused",
+        "invalid-registry-document",
+        "registry-identity-mismatch",
+        "http-status",
+        "network-failure",
+        "invalid-response",
+        "registry-history-cap",
+      ].includes(error.code)
+        ? error.code
+        : "registry-unavailable";
+      const status =
+        reason === "acquisition-timeout"
+          ? 504
+          : error.observation?.status === 404
+            ? 404
+            : 502;
+      json(status, {
+        status: "unavailable",
+        reason,
+        safetyVerdict: "not-provided",
+      });
+    } finally {
+      active--;
+    }
+    return true;
+  };
+}