@xagents_in/unmask 0.1.2 → 0.1.4

package/dist/core/registry-facts.mjs

@@ -0,0 +1,342 @@
+import { AcquisitionError, fetchBlob, parsePackageSpec } from "./acquire.mjs";
+
+export const REGISTRY_FACTS_LIMITS = Object.freeze({
+  maxBytes: 1024 * 1024,
+  timeoutMs: 10000,
+  maxValueBytes: 8192,
+  maxItems: 100,
+});
+const object = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string";
+const stringMap = (value) => object(value) && Object.values(value).every(text);
+const record = (value, keys) =>
+  Object.fromEntries(
+    keys
+      .filter((key) => Object.hasOwn(value, key))
+      .map((key) => [key, value[key]]),
+  );
+const person = (value) => object(value) && text(value.name);
+
+export function registryIdentity(spec) {
+  const identity = parsePackageSpec(spec);
+  if (
+    identity.version
+      .split(/[.+-]/)
+      .slice(0, 3)
+      .some((part) => !Number.isSafeInteger(Number(part)))
+  )
+    throw new AcquisitionError(
+      "invalid-package-spec",
+      "Expected exact package name@version",
+    );
+  return identity;
+}
+
+export async function readRegistryDocument(name, version, options = {}) {
+  registryIdentity(`${name}@${version ?? "0.0.0"}`);
+  const maxBytes = options.maxBytes ?? REGISTRY_FACTS_LIMITS.maxBytes;
+  const timeoutMs = options.timeoutMs ?? REGISTRY_FACTS_LIMITS.timeoutMs;
+  if (
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 1 ||
+    maxBytes > REGISTRY_FACTS_LIMITS.maxBytes ||
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs < 1 ||
+    timeoutMs > REGISTRY_FACTS_LIMITS.timeoutMs
+  )
+    throw new TypeError("Invalid registry facts limits");
+  const url = `https://registry.npmjs.org/${encodeURIComponent(name)}${version === undefined ? "" : `/${encodeURIComponent(version)}`}`;
+  const blob = await fetchBlob(url, {
+    fetchImpl: options.fetchImpl,
+    signal: options.signal,
+    maxBytes,
+    timeoutMs,
+  });
+  let document;
+  try {
+    document = JSON.parse(blob.bytes.toString("utf8"));
+  } catch {
+    throw new AcquisitionError(
+      "invalid-registry-document",
+      "Registry metadata is not JSON",
+    );
+  }
+  if (
+    !object(document) ||
+    document.name !== name ||
+    (version !== undefined && document.version !== version)
+  )
+    throw new AcquisitionError(
+      "registry-identity-mismatch",
+      "Registry identity differs from request",
+    );
+  return {
+    document,
+    source: {
+      url,
+      retrievedAt: new Date().toISOString(),
+      sha256: blob.digest.sha256,
+      bytes: blob.observation.bytes,
+    },
+  };
+}
+
+function claim(document, key, valid, project = (value) => value) {
+  const result = { pointer: `/${key}`, status: "not-recorded" };
+  if (!Object.hasOwn(document, key)) return result;
+  const value = document[key];
+  if (
+    Buffer.byteLength(JSON.stringify(value)) >
+      REGISTRY_FACTS_LIMITS.maxValueBytes ||
+    (Array.isArray(value) && value.length > REGISTRY_FACTS_LIMITS.maxItems)
+  )
+    return { ...result, status: "omitted-limit" };
+  if (!valid(value)) return { ...result, status: "invalid-type" };
+  return {
+    ...result,
+    status: "registry-reported-unverified",
+    value: project(value),
+  };
+}
+
+export function projectRegistryClaims(document) {
+  return {
+    maintainers: claim(
+      document,
+      "maintainers",
+      (value) =>
+        Array.isArray(value) &&
+        value.length <= REGISTRY_FACTS_LIMITS.maxItems &&
+        value.every(person),
+      (value) => value.map((item) => ({ name: item.name })),
+    ),
+    publisher: claim(document, "_npmUser", person, (value) => ({
+      name: value.name,
+    })),
+    deprecated: claim(document, "deprecated", text),
+    license: claim(
+      document,
+      "license",
+      (value) =>
+        text(value) ||
+        (object(value) &&
+          text(value.type) &&
+          (value.url === undefined || text(value.url))),
+      (value) => (text(value) ? value : record(value, ["type", "url"])),
+    ),
+    engines: claim(document, "engines", stringMap),
+    repository: claim(
+      document,
+      "repository",
+      (value) =>
+        text(value) ||
+        (object(value) &&
+          text(value.url) &&
+          ["type", "directory"].every(
+            (key) => value[key] === undefined || text(value[key]),
+          )),
+      (value) =>
+        text(value) ? value : record(value, ["type", "url", "directory"]),
+    ),
+  };
+}
+
+export async function getRegistryFacts(spec, options = {}) {
+  const identity = registryIdentity(spec);
+  const { document, source } = await readRegistryDocument(
+    identity.name,
+    identity.version,
+    options,
+  );
+  return {
+    schemaVersion: "1",
+    identity,
+    source,
+    verifiedObservations: {
+      documentIdentity: "matches-exact-request",
+      documentDigest: "sha256-of-retrieved-bytes",
+    },
+    unverifiedClaims: projectRegistryClaims(document),
+    scope: {
+      method: "bounded-public-npm-metadata",
+      safetyVerdict: "not-provided",
+      modelAssessment: "not-performed-metadata-only",
+      artifactInspection: "not-performed",
+      limitation:
+        "Registry declarations only. Maintainers and publisher names are recorded metadata, not verified identities or ownership history. Repository, license and engine declarations are not independently verified. Missing deprecation does not establish support or safety. No popularity-based safety inference.",
+    },
+  };
+}
+
+const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const metadataFields = ["deprecated", "license", "engines", "repository"];
+const recorded = (claim) => claim.status === "registry-reported-unverified";
+function stable(value) {
+  return JSON.stringify(
+    object(value)
+      ? Object.fromEntries(
+          Object.keys(value)
+            .sort(order)
+            .map((key) => [key, value[key]]),
+        )
+      : value,
+  );
+}
+function timestamp(value) {
+  if (
+    typeof value !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
+  )
+    return null;
+  const canonical = value.includes(".") ? value : value.replace("Z", ".000Z");
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === canonical
+    ? canonical
+    : null;
+}
+function compareRelease(current, previous, ambiguousTime) {
+  if (ambiguousTime) return { status: "not-assessed-ambiguous-time" };
+  if (!previous) return { status: "not-assessed-no-predecessor" };
+  const left = previous.claims;
+  const right = current.claims;
+  const publisher =
+    recorded(left.publisher) && recorded(right.publisher)
+      ? {
+          status:
+            left.publisher.value.name === right.publisher.value.name
+              ? "unchanged"
+              : "changed",
+          before: left.publisher.value.name,
+          after: right.publisher.value.name,
+        }
+      : { status: "not-assessed" };
+  const unassessedFields = metadataFields.filter(
+    (field) => !recorded(left[field]) || !recorded(right[field]),
+  );
+  const metadataChanges = metadataFields
+    .filter(
+      (field) =>
+        recorded(left[field]) &&
+        recorded(right[field]) &&
+        stable(left[field].value) !== stable(right[field].value),
+    )
+    .map((field) => ({
+      field,
+      before: left[field].value,
+      after: right[field].value,
+    }));
+  return {
+    status:
+      unassessedFields.length || publisher.status === "not-assessed"
+        ? "partial"
+        : "compared",
+    againstVersion: previous.version,
+    publisher,
+    metadataChanges,
+    unassessedFields,
+  };
+}
+
+export async function getRegistryHistory(name, options = {}) {
+  registryIdentity(`${name}@0.0.0`);
+  const limit = options.limit ?? 20;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+    throw new TypeError("Invalid registry history limit");
+  const { document, source } = await readRegistryDocument(
+    name,
+    undefined,
+    options,
+  );
+  const times = object(document.time) ? document.time : {};
+  const versions = object(document.versions) ? document.versions : {};
+  const keys = [
+    ...new Set([
+      ...Object.keys(times).filter(
+        (key) => !["created", "modified"].includes(key),
+      ),
+      ...Object.keys(versions),
+    ]),
+  ];
+  if (keys.length > 5000)
+    throw new AcquisitionError(
+      "registry-history-cap",
+      "Registry version history exceeds record limit",
+    );
+  let invalidVersionKeys = 0,
+    undatedVersions = 0;
+  const timeline = [];
+  for (const version of keys) {
+    try {
+      registryIdentity(`${name}@${version}`);
+    } catch {
+      invalidVersionKeys++;
+      continue;
+    }
+    const releasedAt = timestamp(times[version]);
+    if (!releasedAt) {
+      undatedVersions++;
+      continue;
+    }
+    const entry = versions[version];
+    const metadataStatus = !Object.hasOwn(versions, version)
+      ? "not-recorded"
+      : !object(entry)
+        ? "invalid-type"
+        : entry.name !== name || entry.version !== version
+          ? "identity-mismatch"
+          : "registry-reported-unverified";
+    const claims = projectRegistryClaims(
+      metadataStatus === "registry-reported-unverified" ? entry : {},
+    );
+    for (const claim of Object.values(claims))
+      claim.pointer = `/versions/${version}${claim.pointer}`;
+    timeline.push({
+      version,
+      releasedAt,
+      timePointer: `/time/${version}`,
+      metadataStatus,
+      claims,
+    });
+  }
+  timeline.sort(
+    (a, b) => order(a.releasedAt, b.releasedAt) || order(a.version, b.version),
+  );
+  const counts = new Map();
+  for (const entry of timeline)
+    counts.set(entry.releasedAt, (counts.get(entry.releasedAt) ?? 0) + 1);
+  for (let i = 0; i < timeline.length; i++) {
+    const entry = timeline[i];
+    entry.comparison = compareRelease(
+      entry,
+      timeline[i - 1],
+      counts.get(entry.releasedAt) > 1 ||
+        (i > 0 && counts.get(timeline[i - 1].releasedAt) > 1),
+    );
+  }
+  return {
+    schemaVersion: "1",
+    status: timeline.length ? "recorded-history" : "history-unavailable",
+    identity: { name },
+    source,
+    timeline: timeline.slice(-limit).reverse(),
+    coverage: {
+      recordedVersions: keys.length - invalidVersionKeys,
+      datedVersions: timeline.length,
+      undatedVersions,
+      invalidVersionKeys,
+      returned: Math.min(limit, timeline.length),
+      omitted: Math.max(0, timeline.length - limit),
+      recordLimit: 5000,
+    },
+    scope: {
+      method: "adjacent-dated-version-records-in-current-registry-snapshot",
+      historicalEdits: "not-assessed-single-snapshot",
+      ownershipTransfers: "not-assessed",
+      safetyVerdict: "not-provided",
+      modelAssessment: "not-performed-metadata-only",
+      limitation:
+        "Publish times and declarations are registry-reported and unverified. Comparisons describe differences between adjacent dated records in this snapshot, not edits over time or proven ownership transfers. Missing, malformed or omitted fields remain unassessed. Removed releases may retain dates without metadata. Equal timestamps do not establish ordering. Changes, unchanged metadata and popularity do not establish safety.",
+    },
+  };
+}

package/dist/core/report-exploration.mjs

@@ -0,0 +1,328 @@
+import { createHash } from "node:crypto";
+
+const states = new Map([
+  ["changed", "changed"],
+  ["artifact-only", "added"],
+  ["byte-identical", "identical"],
+  ["not-compared", "not-compared"],
+]);
+const digest = (value) => (/^[a-f0-9]{64}$/.test(value ?? "") ? value : null);
+const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const EXPLORATION_BYTE_LIMIT = 131072;
+export const explorationLimitations = [
+  "States compare artifact and selected source, not releases or version history.",
+  "Source-only paths are recorded observations; their hashes, file types and excerpts may be unavailable.",
+  "Incomplete inventories and unassessed files do not establish safety or absence.",
+];
+
+export function safeExplorationPath(value, { prefix = false } = {}) {
+  if (
+    typeof value !== "string" ||
+    value.length > 4096 ||
+    /[\x00-\x1f\x7f\\%:]/.test(value)
+  )
+    return false;
+  if (prefix && value === "") return true;
+  const parts = (
+    prefix && value.endsWith("/") ? value.slice(0, -1) : value
+  ).split("/");
+  return parts.every((part) => part && part !== "." && part !== "..");
+}
+
+export function explorationJson(value) {
+  return JSON.stringify(value).replace(
+    /[<>&\u2028\u2029]/g,
+    (character) =>
+      `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+export function reportFileRows(report, { reportId } = {}) {
+  if (reportId !== undefined && !/^[a-f0-9]{32}$/.test(reportId))
+    throw new TypeError("Invalid report identity");
+  const rows = [];
+  const paths = new Set();
+  let omitted = 0;
+  for (const file of report.files ?? []) {
+    if (
+      !states.has(file.state) ||
+      !safeExplorationPath(file.originalPath) ||
+      (file.path !== null && !safeExplorationPath(file.path))
+    ) {
+      omitted++;
+      continue;
+    }
+    if (file.path !== null) paths.add(file.path);
+    rows.push({
+      path: file.path,
+      originalPath: file.originalPath,
+      state: states.get(file.state),
+      comparisonState: file.state,
+      size:
+        Number.isSafeInteger(file.size) && file.size >= 0 ? file.size : null,
+      artifactSha256: digest(file.artifactSha256),
+      sourceSha256: digest(file.sourceSha256),
+      reason:
+        typeof file.reason === "string" ? file.reason.slice(0, 128) : null,
+    });
+  }
+  for (const path of new Set(report.coverage?.sourceOnly ?? [])) {
+    if (!safeExplorationPath(path)) {
+      omitted++;
+      continue;
+    }
+    if (paths.has(path)) continue;
+    rows.push({
+      path,
+      originalPath: null,
+      state: "removed",
+      comparisonState: "source-only",
+      size: null,
+      artifactSha256: null,
+      sourceSha256: null,
+      reason: "recorded-source-only",
+    });
+  }
+  rows.sort(
+    (a, b) =>
+      order(a.path ?? a.originalPath, b.path ?? b.originalPath) ||
+      order(a.originalPath ?? "", b.originalPath ?? ""),
+  );
+  if (reportId !== undefined)
+    for (const file of rows) {
+      file.fileId = `f-${createHash("sha256")
+        .update(
+          JSON.stringify([
+            "unmask-file-id-v1",
+            reportId,
+            file.path,
+            file.originalPath,
+          ]),
+        )
+        .digest("base64url")}`;
+    }
+  return { rows, omitted };
+}
+
+export function buildReportFileInventory(
+  report,
+  { state = "all", prefix = "", offset = 0, limit = 50 } = {},
+  context = {},
+) {
+  if (
+    !["all", "removed", ...states.values()].includes(state) ||
+    !safeExplorationPath(prefix, { prefix: true }) ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    !Number.isSafeInteger(limit) ||
+    limit < 1 ||
+    limit > 100
+  )
+    throw new TypeError("Invalid inventory query");
+  const { rows, omitted } = reportFileRows(report, context);
+  const filtered = rows.filter(
+    (file) =>
+      (state === "all" || file.state === state) &&
+      (file.path ?? file.originalPath).startsWith(prefix),
+  );
+  const files = [];
+  let bytes = 0;
+  for (const file of filtered.slice(offset, offset + limit)) {
+    const size = Buffer.byteLength(explorationJson(file)) + 1;
+    if (
+      bytes + size >
+      EXPLORATION_BYTE_LIMIT -
+        Buffer.byteLength(explorationJson({ prefix })) -
+        8192
+    )
+      break;
+    bytes += size;
+    files.push(file);
+  }
+  return {
+    schemaVersion: "1",
+    scope: "artifact-source",
+    state,
+    prefix,
+    offset,
+    limit,
+    total: filtered.length,
+    files,
+    nextOffset:
+      offset + files.length < filtered.length ? offset + files.length : null,
+    omittedUnsafePaths: omitted,
+    inventoryComplete: report.coverage?.inventory?.complete === true,
+    sourceComplete: report.coverage?.sourceComplete === true,
+    limitations: explorationLimitations,
+  };
+}
+
+function validRange(value, size) {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    value.every((number) => Number.isSafeInteger(number) && number >= 0) &&
+    value[0] <= value[1] &&
+    value[1] <= size
+  );
+}
+
+function recordedExcerpt(item) {
+  const unavailable = {
+    excerpt: null,
+    excerptRange: null,
+    recordedExcerptRange: null,
+    excerptTruncated: false,
+    excerptStatus: "not-recorded",
+  };
+  if (item.excerpt === undefined) return unavailable;
+  if (
+    typeof item.excerpt !== "string" ||
+    !validRange(item.excerptRange, item.size) ||
+    item.excerptRange[0] !== item.range[0] ||
+    item.excerptRange[1] > item.range[1] ||
+    Buffer.byteLength(item.excerpt) !==
+      item.excerptRange[1] - item.excerptRange[0]
+  )
+    return { ...unavailable, excerptStatus: "invalid-recorded-range" };
+  let excerpt = "",
+    bytes = 0;
+  for (const character of item.excerpt) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > 2048) break;
+    bytes += size;
+    excerpt += character;
+  }
+  return {
+    excerpt,
+    excerptRange: [item.excerptRange[0], item.excerptRange[0] + bytes],
+    recordedExcerptRange: item.excerptRange,
+    excerptTruncated: bytes < Buffer.byteLength(item.excerpt),
+    excerptStatus: "recorded",
+  };
+}
+
+export function buildReportFileEvidence(report, selection, context = {}) {
+  const keys = Object.keys(selection ?? {});
+  if (
+    keys.length !== 1 ||
+    !["path", "originalPath", "fileId"].includes(keys[0]) ||
+    (keys[0] === "fileId"
+      ? !/^[a-f0-9]{32}$/.test(context.reportId ?? "") ||
+        !/^f-[A-Za-z0-9_-]{43}$/.test(selection.fileId)
+      : !safeExplorationPath(selection[keys[0]]))
+  )
+    throw new TypeError("Invalid file selection");
+  const { rows } = reportFileRows(report, context);
+  const matches = rows.filter((file) =>
+    keys[0] === "fileId"
+      ? file.fileId === selection.fileId
+      : keys[0] === "path"
+        ? file.path === selection.path
+        : file.path === null && file.originalPath === selection.originalPath,
+  );
+  if (matches.length !== 1) return null;
+  const file = matches[0];
+  const rawFile = (report.files ?? []).find(
+    (item) =>
+      item.path === file.path && item.originalPath === file.originalPath,
+  );
+  const samePathEvidence = (report.evidence ?? []).filter((item) =>
+    file.path === null
+      ? item.side === "artifact" &&
+        item.path === null &&
+        item.originalPath === file.originalPath
+      : item.path === file.path &&
+        (file.state !== "removed" || item.side === "source"),
+  );
+  if (file.state === "removed") {
+    const hashes = new Set(
+      samePathEvidence
+        .filter(
+          (item) =>
+            digest(item.fileSha256) &&
+            digest(item.blobDigest) &&
+            item.blobDigest === report.inputs?.sourceArchive?.sha256,
+        )
+        .map((item) => item.fileSha256),
+    );
+    if (hashes.size === 1) file.sourceSha256 = [...hashes][0];
+  }
+  const candidateIds = new Set([
+    ...(rawFile?.evidenceIds ?? []),
+    ...samePathEvidence.map((item) => item.id),
+  ]);
+  const result = {
+    schemaVersion: "1",
+    scope: "artifact-source",
+    file,
+    recordedOnly: true,
+    evidence: [],
+    evidenceStatus: "unavailable",
+    evidenceOmitted: 0,
+    invalidEvidenceOmitted: 0,
+    limitations: [
+      ...explorationLimitations,
+      "Only previously recorded excerpts are returned; omitted text is not fetched or reconstructed. Hashes are recorded claims, not new artifact verification. Render excerpts as text, never HTML.",
+    ],
+  };
+  const evidenceById = new Map();
+  for (const item of report.evidence ?? [])
+    evidenceById.set(item.id, evidenceById.has(item.id) ? null : item);
+  let bytes = Buffer.byteLength(explorationJson(result));
+  for (const id of candidateIds) {
+    const item = evidenceById.get(id);
+    const expectedHash =
+      item?.side === "artifact" ? file.artifactSha256 : file.sourceSha256;
+    const input =
+      item?.side === "artifact"
+        ? report.inputs?.artifact
+        : report.inputs?.sourceArchive;
+    if (
+      !item ||
+      !/^ev-[a-f0-9]{64}$/.test(id) ||
+      !["artifact", "source"].includes(item.side) ||
+      item.path !== file.path ||
+      !safeExplorationPath(item.originalPath) ||
+      (item.side === "artifact" &&
+        (item.originalPath !== file.originalPath || item.size !== file.size)) ||
+      !expectedHash ||
+      item.fileSha256 !== expectedHash ||
+      !digest(item.blobDigest) ||
+      item.blobDigest !== input?.sha256 ||
+      !Number.isSafeInteger(item.size) ||
+      item.size < 0 ||
+      !validRange(item.range, item.size)
+    ) {
+      result.invalidEvidenceOmitted++;
+      continue;
+    }
+    const evidence = {
+      id,
+      side: item.side,
+      path: item.path,
+      originalPath: item.originalPath,
+      fileSha256: item.fileSha256,
+      blobDigest: item.blobDigest,
+      size: item.size,
+      range: item.range,
+      ...recordedExcerpt(item),
+    };
+    const size = Buffer.byteLength(explorationJson(evidence)) + 1;
+    if (
+      result.evidence.length >= 32 ||
+      bytes + size > EXPLORATION_BYTE_LIMIT - 2048
+    ) {
+      result.evidenceOmitted++;
+      continue;
+    }
+    bytes += size;
+    result.evidence.push(evidence);
+  }
+  if (result.evidence.length)
+    result.evidenceStatus =
+      result.evidenceOmitted || result.invalidEvidenceOmitted
+        ? "partial"
+        : "recorded";
+  return result;
+}

package/dist/core/report.mjs

@@ -225,6 +225,13 @@ export function validateReport(report) {
       typeof report.run === "object",
     "Invalid model or run section",
   );
+  requireValue(
+    report.model.assessment === undefined ||
+      (report.model.status === "complete" &&
+        report.model.assessment?.source === "model" &&
+        typeof report.model.summary === "string"),
+    "Model assessment requires a completed model result",
+  );
   const coverage = report.coverage;
   requireValue(
     coverage &&