@xagents_in/unmask 0.0.0-stage → 0.1.1

package/dist/core/resolve.mjs

@@ -0,0 +1,186 @@
+function repository(value) {
+  const input = typeof value === "string" ? value : value?.url;
+  if (
+    typeof input !== "string" ||
+    input.length > 512 ||
+    /[\s%\\?#\0]/u.test(input)
+  )
+    return null;
+  let pair;
+  if (input.startsWith("github:")) pair = input.slice(7);
+  else if (input.startsWith("git@github.com:"))
+    pair = input.slice("git@github.com:".length);
+  else {
+    const match =
+      /^(https|git\+https|git|ssh|git\+ssh):\/\/([^/]+)\/(.+)$/u.exec(input);
+    if (!match) return null;
+    const ssh = ["ssh", "git+ssh"].includes(match[1]);
+    if (match[2] !== (ssh ? "git@github.com" : "github.com")) return null;
+    pair = match[3];
+  }
+  if (pair.endsWith(".git")) pair = pair.slice(0, -4);
+  const match =
+    /^([a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?)\/([a-z0-9_.-]{1,100})$/iu.exec(
+      pair,
+    );
+  if (!match || match[1].includes("--") || [".", ".."].includes(match[2]))
+    return null;
+  return {
+    owner: match[1].toLowerCase(),
+    repo: match[2].toLowerCase(),
+    repository: `https://github.com/${match[1].toLowerCase()}/${match[2].toLowerCase()}`,
+  };
+}
+function directory(value) {
+  if (value === undefined || value === "") return "";
+  if (
+    typeof value !== "string" ||
+    value.length > 4096 ||
+    /[\0\\]/u.test(value) ||
+    value.startsWith("/") ||
+    /^[a-z]:/iu.test(value) ||
+    value.split("/").some((p) => !p || p === "." || p === "..")
+  )
+    return null;
+  return value;
+}
+function candidate(repo, commit, dir, method) {
+  if (
+    !repo ||
+    typeof commit !== "string" ||
+    !/^[a-f0-9]{40}$/iu.test(commit) ||
+    dir === null
+  )
+    return null;
+  const sha = commit.toLowerCase();
+  return {
+    repository: repo.repository,
+    commit: sha,
+    directory: dir,
+    method,
+    archiveUrl: `https://codeload.github.com/${repo.owner}/${repo.repo}/tar.gz/${sha}`,
+    sourceRoot: `${repo.repo}-${sha}`,
+  };
+}
+function same(a, b) {
+  return a.repository === b.repository && a.commit === b.commit;
+}
+function identity(value) {
+  if (typeof value === "string") {
+    const at = value.lastIndexOf("@");
+    return at > 0
+      ? { name: value.slice(0, at), version: value.slice(at + 1) }
+      : null;
+  }
+  return value &&
+    typeof value.name === "string" &&
+    typeof value.version === "string"
+    ? { name: value.name, version: value.version }
+    : null;
+}
+export function resolveSource({
+  claim,
+  artifactManifest,
+  registryDoc,
+  explicitSource,
+  commit,
+  sourceDir,
+} = {}) {
+  const result = {
+    status: "unresolved",
+    method: "unresolved",
+    candidate: null,
+    alternatives: [],
+    provenance: { status: "not-assessed" },
+    conflicts: [],
+  };
+  const requested = identity(claim),
+    artifact = identity(artifactManifest),
+    registry = identity(registryDoc);
+  if (
+    (requested &&
+      artifact &&
+      (requested.name !== artifact.name ||
+        requested.version !== artifact.version)) ||
+    (requested &&
+      registry &&
+      (requested.name !== registry.name ||
+        requested.version !== registry.version))
+  )
+    result.conflicts.push({
+      code: "identity-claim-conflict",
+      claim: requested,
+      artifact,
+      registry,
+    });
+  const registryRepo = repository(registryDoc?.repository);
+  const artifactRepo = repository(artifactManifest?.repository);
+  if (
+    registryRepo &&
+    artifactRepo &&
+    registryRepo.repository !== artifactRepo.repository
+  )
+    result.conflicts.push({
+      code: "repository-claim-conflict",
+      artifact: artifactRepo.repository,
+      registry: registryRepo.repository,
+    });
+  const publisher = candidate(
+    registryRepo,
+    registryDoc?.gitHead,
+    directory(registryDoc?.repository?.directory),
+    "publisher-gitHead",
+  );
+  if (publisher) result.alternatives.push(publisher);
+  const explicitRepo =
+    typeof explicitSource === "string" ? repository(explicitSource) : null;
+  if (explicitSource !== undefined && !explicitRepo) {
+    result.reason = "unsupported-explicit-repository";
+    return result;
+  }
+  const dir = sourceDir === undefined ? undefined : directory(sourceDir);
+  if (dir === null) {
+    result.reason = "invalid-source-directory";
+    return result;
+  }
+  if (commit !== undefined) {
+    const pinned = candidate(
+      explicitRepo ?? registryRepo ?? artifactRepo,
+      commit,
+      dir ?? "",
+      "user-full-SHA",
+    );
+    if (!pinned) {
+      result.reason = "invalid-user-pin";
+      return result;
+    }
+    if (publisher && !same(publisher, pinned))
+      result.conflicts.push({
+        code: "source-claim-conflict",
+        alternatives: [publisher, pinned],
+      });
+    result.alternatives.push(pinned);
+    return {
+      ...result,
+      status: "selected",
+      method: pinned.method,
+      candidate: pinned,
+    };
+  }
+  if (!publisher) {
+    result.reason = "no-full-sha-source-candidate";
+    return result;
+  }
+  if (explicitRepo && explicitRepo.repository !== publisher.repository) {
+    result.reason = "explicit-repository-disagrees";
+    return result;
+  }
+  const selected =
+    dir === undefined ? publisher : { ...publisher, directory: dir };
+  return {
+    ...result,
+    status: "selected",
+    method: selected.method,
+    candidate: selected,
+  };
+}

package/dist/core/source.mjs

@@ -0,0 +1,106 @@
+function unresolved(reason, directory = null) {
+  return {
+    status: "unresolved",
+    directory,
+    entries: [],
+    manifest: null,
+    reason,
+  };
+}
+function directoryPath(value) {
+  if (
+    typeof value !== "string" ||
+    /[\0\\]/u.test(value) ||
+    value.startsWith("/") ||
+    /^[a-z]:/iu.test(value)
+  )
+    return null;
+  if (value === "") return "";
+  const path = value.replace(/\/+$/u, "");
+  return path.split("/").some((p) => !p || p === "." || p === "..")
+    ? null
+    : path;
+}
+function manifest(entry) {
+  if (entry?.type !== "file" || !Buffer.isBuffer(entry.content)) return null;
+  try {
+    const value = JSON.parse(entry.content.toString("utf8"));
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value
+      : null;
+  } catch {
+    return null;
+  }
+}
+function blocked(entries, directory) {
+  return entries.some(
+    (e) =>
+      e.path !== null &&
+      e.path !== undefined &&
+      e.type !== "directory" &&
+      (e.path === directory || directory.startsWith(e.path + "/")),
+  );
+}
+export function selectSourcePackage(
+  inventory,
+  { directory, packageName } = {},
+) {
+  const entries = inventory.entries;
+  let selected = directory;
+  if (selected !== undefined) {
+    selected = directoryPath(selected);
+    if (selected === null) return unresolved("invalid-directory");
+  } else {
+    if (!inventory.complete) return unresolved("incomplete-inventory");
+    const candidates = entries.filter(
+      (e) =>
+        (e.path === "package.json" || e.path?.endsWith("/package.json")) &&
+        typeof packageName === "string" &&
+        manifest(e)?.name === packageName,
+    );
+    if (candidates.length !== 1)
+      return unresolved(
+        candidates.length ? "ambiguous-manifest" : "manifest-not-found",
+      );
+    selected = candidates[0].path
+      .slice(0, -"package.json".length)
+      .replace(/\/$/u, "");
+  }
+  if (selected && blocked(entries, selected))
+    return unresolved("nonregular-package-root", selected);
+  const prefix = selected ? selected + "/" : "";
+  const selectedEntries = entries
+    .filter(
+      (e) =>
+        typeof e.path === "string" &&
+        e.path.startsWith(prefix) &&
+        e.path !== selected,
+    )
+    .map((e) => ({ ...e, path: e.path.slice(prefix.length) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const existingDirectory = entries.some(
+    (e) =>
+      e.type === "directory" &&
+      (e.path === selected || (selected === "" && e.path === null)),
+  );
+  if (!selectedEntries.length && !existingDirectory)
+    return unresolved("directory-not-found", selected);
+  if (selectedEntries.some((e) => directoryPath(e.path) === null))
+    return unresolved("unsafe-mapped-path", selected);
+  const manifestEntry = selectedEntries.find((e) => e.path === "package.json");
+  const parsed = manifest(manifestEntry);
+  const reason = !manifestEntry
+    ? "missing"
+    : manifestEntry.type !== "file"
+      ? "nonregular-manifest"
+      : !Buffer.isBuffer(manifestEntry.content)
+        ? manifestEntry.inspection
+        : "invalid-json";
+  return {
+    status: "selected",
+    directory: selected,
+    entries: selectedEntries,
+    manifest: parsed,
+    ...(!parsed ? { reason } : {}),
+  };
+}

package/dist/core/syntax.mjs

@@ -0,0 +1,340 @@
+import { parse } from "acorn";
+import { createHash } from "node:crypto";
+import { validateReport } from "./report.mjs";
+
+export const SYNTAX_LIMITS = Object.freeze({
+  fileBytes: 2097152,
+  totalBytesPerSide: 8388608,
+  tokens: 200000,
+  cues: 1000,
+  sourceLiterals: 10000,
+});
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function offsets(text) {
+  const result = new Uint32Array(text.length + 1);
+  let index = 0,
+    bytes = 0;
+  for (const character of text) {
+    result[index] = bytes;
+    if (character.length === 2) result[index + 1] = bytes;
+    index += character.length;
+    bytes += Buffer.byteLength(character);
+    result[index] = bytes;
+  }
+  return result;
+}
+function evidenceFor(side, inventory, entry, node, positions) {
+  const range = [positions[node.start], positions[node.end]];
+  const identity = [
+    side,
+    inventory.digest.sha256,
+    entry.path ?? entry.originalPath,
+    range,
+  ];
+  const evidence = {
+    id: `ev-${hash(JSON.stringify(identity))}`,
+    side,
+    blobDigest: inventory.digest.sha256,
+    path: entry.path,
+    originalPath: entry.originalPath,
+    fileSha256: entry.sha256,
+    size: entry.size,
+    range,
+  };
+  let end = Math.min(range[1], range[0] + 512);
+  while (end > range[0]) {
+    try {
+      evidence.excerpt = new TextDecoder("utf-8", {
+        fatal: true,
+        ignoreBOM: true,
+      }).decode(entry.content.subarray(range[0], end));
+      evidence.excerptRange = [range[0], end];
+      break;
+    } catch {
+      end--;
+    }
+  }
+  return evidence;
+}
+function nameOf(node) {
+  const parts = [];
+  for (let depth = 0; node && depth < 4; depth++) {
+    if (node.type === "Identifier") return [node.name, ...parts].join(".");
+    if (
+      node.type === "CallExpression" &&
+      node.callee?.type === "Identifier" &&
+      node.callee.name === "require" &&
+      node.arguments.length === 1 &&
+      node.arguments[0].type === "Literal" &&
+      typeof node.arguments[0].value === "string"
+    ) {
+      const module = node.arguments[0].value.replace(/^node:/, "");
+      return ["child_process", "http", "https", "net"].includes(module)
+        ? [module, ...parts].join(".")
+        : "";
+    }
+    if (node.type !== "MemberExpression" || node.computed) return "";
+    parts.unshift(node.property.name);
+    node = node.object;
+  }
+  return "";
+}
+function capability(node) {
+  const name = nameOf(node.callee);
+  if (
+    node.type === "CallExpression" &&
+    /^(fetch|globalThis.fetch|https?\.(request|get)|net\.connect)$/.test(name)
+  )
+    return "network-call";
+  if (
+    node.type === "CallExpression" &&
+    /^(child_process\.)?(exec|execSync|execFile|execFileSync|spawn|spawnSync)$/.test(
+      name,
+    )
+  )
+    return "process-execution";
+  if (
+    ["CallExpression", "NewExpression"].includes(node.type) &&
+    /^(eval|Function)$/.test(name)
+  )
+    return "dynamic-code";
+  if (
+    node.type === "MemberExpression" &&
+    nameOf(node).startsWith("process.env.")
+  )
+    return "environment-access";
+  return null;
+}
+function nodes(ast) {
+  const stack = [ast],
+    result = [];
+  while (stack.length) {
+    const node = stack.pop();
+    result.push(node);
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (let i = value.length - 1; i >= 0; i--)
+          if (value[i]?.type) stack.push(value[i]);
+      } else if (value?.type) stack.push(value);
+    }
+  }
+  return result;
+}
+
+export function inspectJavaScript(artifact, source, overrides = {}) {
+  const limits = { ...SYNTAX_LIMITS };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (
+      !(key in limits) ||
+      !Number.isSafeInteger(value) ||
+      value < 0 ||
+      value > limits[key]
+    )
+      throw new TypeError("Syntax limits may only lower defaults");
+    limits[key] = value;
+  }
+  const result = {
+    cues: [],
+    evidence: [],
+    coverage: { files: 0, bytes: 0 },
+    sourceCoverage: { files: 0, bytes: 0 },
+    annotations: [],
+    limits,
+  };
+  const literals = new Map(),
+    candidates = [],
+    evidence = new Map();
+  let sourceLiteralTruncated = false;
+  for (const [side, inventory] of [
+    ["artifact", artifact],
+    ["source", source],
+  ]) {
+    let consumed = 0;
+    const entries = (inventory?.entries || [])
+      .filter((entry) => entry.type === "file")
+      .sort((a, b) =>
+        a.originalPath < b.originalPath
+          ? -1
+          : a.originalPath > b.originalPath
+            ? 1
+            : 0,
+      );
+    for (const entry of entries) {
+      const skip = (reason) =>
+        result.annotations.push({
+          type: "syntax-not-inspected",
+          side,
+          path: entry.path,
+          originalPath: entry.originalPath,
+          reason,
+        });
+      if (!/\.(?:mjs|cjs|js)$/.test(entry.path || entry.originalPath)) {
+        skip("unsupported-syntax");
+        continue;
+      }
+      if (!Buffer.isBuffer(entry.content)) {
+        skip("not-retained");
+        continue;
+      }
+      if (entry.size > limits.fileBytes) {
+        skip("syntax-file-cap");
+        continue;
+      }
+      if (consumed + entry.size > limits.totalBytesPerSide) {
+        skip("syntax-total-cap");
+        continue;
+      }
+      consumed += entry.size;
+      let text, ast;
+      try {
+        text = new TextDecoder("utf-8", {
+          fatal: true,
+          ignoreBOM: true,
+        }).decode(entry.content);
+        const parseAs = (sourceType) => {
+          let tokens = 0;
+          return parse(text, {
+            ecmaVersion: 2025,
+            sourceType,
+            allowHashBang: true,
+            onToken() {
+              if (++tokens > limits.tokens) throw new Error("syntax-token-cap");
+            },
+          });
+        };
+        try {
+          ast = parseAs("module");
+        } catch (error) {
+          if (!(error instanceof SyntaxError)) throw error;
+          ast = parseAs("commonjs");
+        }
+      } catch (error) {
+        skip(
+          error.message === "syntax-token-cap" ? error.message : "parse-failed",
+        );
+        continue;
+      }
+      const coverage =
+        side === "artifact" ? result.coverage : result.sourceCoverage;
+      coverage.files++;
+      coverage.bytes += entry.size;
+      const positions = offsets(text);
+      for (const node of nodes(ast)) {
+        if (side === "source") {
+          if (
+            node.type === "Literal" &&
+            typeof node.value === "string" &&
+            !literals.has(node.value)
+          ) {
+            if (literals.size < limits.sourceLiterals)
+              literals.set(
+                node.value,
+                evidenceFor(side, inventory, entry, node, positions),
+              );
+            else sourceLiteralTruncated = true;
+          }
+          continue;
+        }
+        const kind = capability(node);
+        if (!kind) continue;
+        if (candidates.length >= limits.cues) {
+          skip("syntax-cue-cap");
+          break;
+        }
+        candidates.push({
+          kind,
+          evidence: evidenceFor(side, inventory, entry, node, positions),
+          literal:
+            node.arguments?.[0]?.type === "Literal" &&
+            typeof node.arguments[0].value === "string"
+              ? node.arguments[0].value
+              : null,
+        });
+      }
+    }
+  }
+  const stem = (value) => value.replace(/\.[cm]?[jt]sx?$/, "");
+  const unknownSource = new Set(
+    result.annotations
+      .filter(
+        (item) =>
+          item.type === "syntax-not-inspected" && item.side === "source",
+      )
+      .map((item) => stem(item.path || item.originalPath)),
+  );
+  for (const candidate of candidates) {
+    const ids = [candidate.evidence.id];
+    evidence.set(candidate.evidence.id, candidate.evidence);
+    const match = candidate.literal !== null && literals.get(candidate.literal);
+    if (match) {
+      evidence.set(match.id, match);
+      ids.push(match.id);
+    }
+    result.cues.push({
+      ruleId: `syntax-${candidate.kind}`,
+      priority: "review",
+      summary:
+        "Syntactic capability reference; execution and binding are not proven.",
+      literalStatus:
+        candidate.literal === null
+          ? "no-static-literal"
+          : match
+            ? "found-in-inspected-source"
+            : source
+              ? result.sourceCoverage.files === 0 ||
+                sourceLiteralTruncated ||
+                unknownSource.has(
+                  stem(
+                    candidate.evidence.path || candidate.evidence.originalPath,
+                  ),
+                )
+                ? "not-assessed"
+                : "not-found-in-inspected-source"
+              : "source-unavailable",
+      evidenceIds: ids,
+    });
+  }
+  result.evidence = [...evidence.values()];
+  result.annotations.push({
+    type: "syntax-scope",
+    parser: "acorn@8.19.0",
+    sourceCoverage: result.sourceCoverage,
+    sourceLiteralCount: literals.size,
+    sourceLiteralTruncated,
+    limitation:
+      "Literal matches are not semantic equivalence; missing literals refer only to inspected JavaScript. TypeScript, JSX, source maps, computed aliases and dynamic targets are not resolved.",
+  });
+  return result;
+}
+
+export function addSyntaxInspection(report, inspection) {
+  const result = structuredClone(report);
+  const existing = new Set(result.evidence.map((item) => item.id));
+  for (const item of inspection.evidence)
+    if (!existing.has(item.id)) {
+      result.evidence.push(item);
+      existing.add(item.id);
+    }
+  const byFile = new Map(result.files.map((file) => [file.originalPath, file]));
+  for (const item of inspection.evidence) {
+    const file = item.side === "artifact" && byFile.get(item.originalPath);
+    if (file && !file.evidenceIds.includes(item.id))
+      file.evidenceIds.push(item.id);
+  }
+  const evidenceById = new Map(
+    inspection.evidence.map((item) => [item.id, item]),
+  );
+  for (const cue of inspection.cues) {
+    const item = evidenceById.get(cue.evidenceIds[0]);
+    const file = byFile.get(item.originalPath);
+    const unchanged = file?.state === "byte-identical";
+    if (unchanged)
+      result.annotations.push({ type: "unchanged-capability", ...cue });
+    else result.cues.push(cue);
+  }
+  result.annotations.push(...inspection.annotations);
+  result.coverage.syntaxInspected = inspection.coverage;
+  result.inputs.limits = { ...result.inputs.limits, syntax: inspection.limits };
+  result.inputs.syntaxParser = "acorn@8.19.0";
+  return validateReport(result);
+}