@xagents_in/unmask 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cappybara contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# UNMASK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See what actually shipped.
+
+UNMASK compares an npm package's published bytes with a selected source archive.
+It produces a JSON report and an HTML evidence viewer: matching files, changed
+bytes, artifact-only files, uninspected content, and observations to review.
+A completed report is not a safety verdict.
+
+Built for **Problem 04: Published Package vs Source Code Integrity Analyzer** at
+Hacktoberfest 2026, Hack Day Sonipat. See [HACKATHON.md](HACKATHON.md).
+
+## Status
+
+The local candidate includes an npm CLI, a shared analyzer, a website with a
+bounded job queue, and an optional hosted Gemma adapter. It uses plain ESM
+JavaScript on Node.js 24.22.2. The intended npm name is `@xagents_in/unmask`;
+version `0.1.0` is configured for public npm publication. The default service is
+`https://unmask-386156642190.asia-south1.run.app`. Publication, public access and final
+model/runtime acceptance must still be verified; this configuration is not a
+released-artifact claim.
+
+The analyzer reads package contents as data. It does not install the inspected
+package, run its scripts, follow archive links, or reproduce its build.
+Source selection is a claim about correspondence, not proof of publisher trust.
+
+## Run locally
+
+Use Node.js 24.22.2, pinned in `.nvmrc`:
+
+```bash
+npm ci --ignore-scripts
+npm run build
+npm test
+npm run check
+npm run check:package
+```
+
+Check an exact public npm version through your configured UNMASK service:
+
+```bash
+node dist/cli/main.mjs check chalk@6.0.1 --out /tmp/unmask-chalk-report
+```
+
+Choose a fresh output directory for each check. The command writes `report.json`
+and `report.html` and refuses to replace existing report files. Public-package
+checks send only the exact package spec to the hosted service; the service owns
+acquisition and model policy. `UNMASK_SERVER_URL` overrides the default service.
+It must be an HTTPS origin, or a loopback HTTP origin for local testing. Hosted
+failure never falls back to local acquisition.
+See [CLI configuration and data flow](docs/cli.md).
+
+To analyze local archives without network acquisition:
+
+```bash
+node dist/cli/main.mjs check --offline --tarball /path/to/package.tgz --source-archive /path/to/source.tar.gz --commit FULL_40_CHARACTER_LOWERCASE_COMMIT_SHA --source-root ARCHIVE_TOP_LEVEL_DIRECTORY --source-dir '' --cache-dir /tmp/unmask-local-cache --out /tmp/unmask-local-report
+```
+
+`--source-dir ''` explicitly selects the repository root. For a monorepo, supply
+the package's directory relative to that root. Omit all source options for an
+artifact-only report. An optional `--claim name@version` checks an explicit
+identity claim against the artifact manifest.
+
+Exit codes: `0` means analysis completed; `2` means analysis was incomplete or
+input acquisition failed; `3` means a default review-policy finding; `1` means an
+internal error. Findings remain visible when incomplete analysis takes priority.
+Exit `0` never means a package is safe.
+
+Start the website locally:
+
+```bash
+UNMASK_MODEL=off HOST=127.0.0.1 PORT=3000 node dist/server/main.mjs
+```
+
+Visit `http://127.0.0.1:3000`. The website accepts exact public npm versions,
+queues analysis, and serves the same report format as the CLI. It accepts no
+uploads. Its development worker limits and temporary-file cleanup do not
+constitute an operating-system security sandbox.
+
+## Inspection limits
+
+- File correspondence uses hashes and bounded byte comparisons. Transpilation,
+  minification, sourcemaps and declared output locations do not prove equivalence.
+- Syntax cues use a bounded JavaScript parser. TypeScript, JSX, unsupported syntax,
+  dynamic behavior and unretained content remain uninspected.
+- Literal novelty means only "not found in inspected source". Missing or
+  insufficient source cannot establish full-source absence.
+- Ambiguous source-package selection is incomplete. For example, multiple
+  same-name manifests in Axios source require an explicit local source directory;
+  the website currently has no such override.
+- This candidate covers npm only. PyPI and continuous release monitoring are
+  not implemented.
+
+## Models and releases
+
+Model output is advisory and cannot change deterministic policy findings. The
+adapter has recorded-transport tests, but real endpoint availability, account
+quotas and usefulness still require validation. Hosted CLI checks follow the
+service's published model/data disclosure and never read a local provider key.
+Only offline local checks use `--allow-model`; without that flag no local model
+client is constructed. The flag alone does not configure an offline provider.
+See [HACKATHON.md](HACKATHON.md) for the exact candidate and remaining AI gate.
+
+`npm test` runs product and release-tooling tests, including a packed tarball
+installed into a temporary directory and invoked through its real CLI binary.
+`npm run check` checks formatting; it is not static type checking. Product tests
+and local HTTP checks do not establish deployment readiness.
+
+Release publication is enabled for the `0.1.0` candidate, subject to CI and runtime
+release gates. The flow builds an immutable
+versioned artifact in CI, then a deployer selects that release separately.
+See [release prerequisites](docs/releases.md). npm access is not required for
+local builds or testing.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for review, test and comment conventions.
+Every remote change after the initial event commit goes through a PR. Repository
+permissions and code-owner enforcement must be verified on GitHub; the
+CODEOWNERS file alone does not enforce them.
+
+## License
+
+[MIT](LICENSE).

package/dist/cli/hosted.mjs

@@ -0,0 +1,251 @@
+import { setTimeout as delay } from "node:timers/promises";
+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";
+const defaults = Object.freeze({
+  totalTimeoutMs: 600000,
+  requestTimeoutMs: 15000,
+  maxBodyBytes: 64 * 1024 * 1024,
+  pollMs: 3000,
+});
+const failure = (code, message) => new LocalInputError(code, message);
+function serverOrigin(value) {
+  if (!value)
+    throw failure(
+      "hosted-configuration",
+      "UNMASK_SERVER_URL must be a nonempty service origin.",
+    );
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw failure(
+      "hosted-configuration",
+      "UNMASK_SERVER_URL must be a service origin.",
+    );
+  }
+  if (
+    typeof value !== "string" ||
+    value.length > 2048 ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/" ||
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw failure(
+      "hosted-configuration",
+      "Use an HTTPS service origin, or loopback HTTP for local testing, without credentials, path, query or fragment.",
+    );
+  return url.origin;
+}
+async function discard(response) {
+  try {
+    await response.body?.cancel();
+  } catch {}
+}
+async function readJson(response, maxBytes) {
+  if (
+    !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(
+      response.headers.get("content-type") ?? "",
+    )
+  )
+    throw failure("hosted-response", "The hosted service did not return JSON.");
+  const declared = response.headers.get("content-length");
+  if (
+    declared !== null &&
+    (!/^\d+$/.test(declared) || Number(declared) > maxBytes)
+  )
+    throw failure(
+      "hosted-response",
+      "The hosted response exceeds the body limit.",
+    );
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of response.body ?? []) {
+    size += chunk.byteLength;
+    if (size > maxBytes)
+      throw failure(
+        "hosted-response",
+        "The hosted response exceeds the body limit.",
+      );
+    chunks.push(chunk);
+  }
+  try {
+    return JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        Buffer.concat(chunks, size),
+      ),
+    );
+  } catch {
+    throw failure("hosted-response", "The hosted response is not valid JSON.");
+  }
+}
+export async function checkHosted(
+  spec,
+  {
+    serverUrl = DEFAULT_SERVER_URL,
+    fetchImpl = globalThis.fetch,
+    signal,
+    limits: overrides = {},
+  } = {},
+) {
+  const claim = parsePackageSpec(spec);
+  const origin = serverOrigin(serverUrl);
+  const limits = { ...defaults, ...overrides };
+  if (
+    Object.keys(limits).some(
+      (key) =>
+        !Object.hasOwn(defaults, key) ||
+        !Number.isSafeInteger(limits[key]) ||
+        limits[key] < 1 ||
+        limits[key] > defaults[key],
+    )
+  )
+    throw failure(
+      "hosted-configuration",
+      "Hosted transport limits are invalid.",
+    );
+  const controller = new AbortController();
+  const totalTimer = setTimeout(
+    () => controller.abort(),
+    limits.totalTimeoutMs,
+  );
+  const lifetime = signal
+    ? AbortSignal.any([signal, controller.signal])
+    : controller.signal;
+  async function request(url, options, consume) {
+    const attempt = new AbortController();
+    const timer = setTimeout(() => attempt.abort(), limits.requestTimeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        ...options,
+        redirect: "manual",
+        credentials: "omit",
+        referrerPolicy: "no-referrer",
+        signal: AbortSignal.any([lifetime, attempt.signal]),
+      });
+      if (
+        response.redirected ||
+        (response.url && new URL(response.url).origin !== origin)
+      )
+        throw failure(
+          "hosted-response",
+          "The hosted service returned an unexpected redirect.",
+        );
+      return await consume(response);
+    } finally {
+      clearTimeout(timer);
+      if (response) await discard(response);
+    }
+  }
+  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";
+      },
+    );
+    const id = new URL(reportUrl).pathname.slice(3, -5);
+    for (;;) {
+      const result = await request(
+        reportUrl,
+        { headers: { accept: "application/json" } },
+        async (response) => {
+          if (![200, 202].includes(response.status))
+            throw failure(
+              "hosted-report-failed",
+              `The hosted report is unavailable (HTTP ${response.status}). No local fallback was attempted.`,
+            );
+          const value = await readJson(response, limits.maxBodyBytes);
+          if (response.status === 202) {
+            if (
+              value?.id !== id ||
+              !["queued", "running"].includes(value.status)
+            )
+              throw failure(
+                "hosted-response",
+                "The hosted service returned an invalid pending report.",
+              );
+            return null;
+          }
+          try {
+            validateReport(value);
+            if (
+              value.inputs.claim?.name !== claim.name ||
+              value.inputs.claim?.version !== claim.version ||
+              ![0, 2, 3].includes(value.policy.exitCode)
+            )
+              throw new TypeError();
+          } catch {
+            throw failure(
+              "hosted-report-invalid",
+              "The hosted report failed schema, identity or deterministic policy validation.",
+            );
+          }
+          return value;
+        },
+      );
+      if (result) return result;
+      await delay(limits.pollMs, undefined, { signal: lifetime });
+    }
+  } catch (error) {
+    if (error instanceof LocalInputError) throw error;
+    if (
+      lifetime.aborted ||
+      error?.name === "AbortError" ||
+      error?.name === "TimeoutError"
+    )
+      throw failure(
+        "hosted-timeout",
+        "The hosted check timed out or was cancelled. No local fallback was attempted.",
+      );
+    throw failure(
+      "hosted-unavailable",
+      "The hosted service could not be reached or its response could not be read. No local fallback was attempted.",
+    );
+  } finally {
+    clearTimeout(totalTimer);
+  }
+}

package/dist/cli/main.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { mkdir, open, unlink } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { analyzeLocal, LocalInputError } from "../core/pipeline.mjs";
+import { renderReport } from "../viewer/render.mjs";
+import { parsePackageSpec, AcquisitionError } from "../core/acquire.mjs";
+import { addConfiguredModel } from "../core/online.mjs";
+import { modelClientFromEnv } from "../model/config.mjs";
+import { checkHosted } from "./hosted.mjs";
+
+const names = {
+  "--tarball": "tarballPath",
+  "--source-archive": "sourceArchivePath",
+  "--commit": "commit",
+  "--source-root": "sourceRoot",
+  "--source-dir": "sourceDir",
+  "--cache-dir": "cacheDir",
+  "--out": "out",
+  "--claim": "claim",
+};
+function exactClaim(spec) {
+  try {
+    return parsePackageSpec(spec);
+  } catch (error) {
+    if (error instanceof AcquisitionError)
+      throw new LocalInputError(error.code, error.message);
+    throw error;
+  }
+}
+function parse(argv) {
+  if (argv[0] !== "check")
+    throw new LocalInputError(
+      "usage",
+      "Use check name@version or an explicit local tarball with --offline",
+    );
+  const options = {};
+  let start = 1;
+  if (argv[1] && !argv[1].startsWith("--")) {
+    exactClaim(argv[1]);
+    options.registrySpec = argv[1];
+    start = 2;
+  }
+  const seen = new Set();
+  for (let index = start; index < argv.length; index++) {
+    const key = argv[index];
+    if (seen.has(key))
+      throw new LocalInputError(
+        "duplicate-option",
+        "Each option may be supplied only once",
+      );
+    seen.add(key);
+    if (key === "--offline") {
+      options.offline = true;
+      continue;
+    }
+    if (key === "--allow-model") {
+      options.allowModel = true;
+      continue;
+    }
+    if (!Object.hasOwn(names, key))
+      throw new LocalInputError(
+        "unknown-option",
+        "Only the documented check options are supported",
+      );
+    const value = argv[++index];
+    if (
+      value === undefined ||
+      value.startsWith("--") ||
+      (!value && key !== "--source-dir")
+    )
+      throw new LocalInputError(
+        "missing-value",
+        "An option is missing its value",
+      );
+    options[names[key]] = value;
+  }
+  if (!options.out)
+    throw new LocalInputError("usage", "Check requires --out DIR");
+  if (options.registrySpec) {
+    if (
+      options.offline ||
+      options.allowModel ||
+      [
+        "tarballPath",
+        "sourceArchivePath",
+        "commit",
+        "sourceRoot",
+        "sourceDir",
+        "claim",
+      ].some((key) => Object.hasOwn(options, key))
+    )
+      throw new LocalInputError(
+        "conflicting-mode",
+        "Hosted checks cannot be combined with local, offline or --allow-model options",
+      );
+  } else if (!options.offline)
+    throw new LocalInputError(
+      "usage",
+      "Local tarball check requires --offline",
+    );
+  if (!options.registrySpec && !options.cacheDir)
+    throw new LocalInputError(
+      "usage",
+      "Offline check requires --cache-dir DIR and --out DIR",
+    );
+  if (options.claim !== undefined) options.claim = exactClaim(options.claim);
+  return options;
+}
+async function writeReports(directory, report) {
+  const json = JSON.stringify(report, null, 2) + "\n";
+  const html = renderReport(report);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const created = [];
+  const handles = [];
+  try {
+    for (const filename of ["report.json", "report.html"]) {
+      const destination = path.join(directory, filename);
+      const handle = await open(destination, "wx", 0o600);
+      handles.push(handle);
+      created.push(destination);
+    }
+    await handles[0].writeFile(json);
+    await handles[1].writeFile(html);
+  } catch (error) {
+    await Promise.allSettled(handles.map((handle) => handle.close()));
+    handles.length = 0;
+    await Promise.allSettled(created.map((filename) => unlink(filename)));
+    if (typeof error.code === "string" && /^E[A-Z]+$/.test(error.code))
+      throw new LocalInputError(
+        "output-write-failed",
+        "Output requires a writable directory without existing report files",
+      );
+    throw error;
+  } finally {
+    await Promise.allSettled(handles.map((handle) => handle.close()));
+  }
+}
+
+async function configuredModel(allowModel, runtime) {
+  if (!allowModel) return undefined;
+  if (Object.hasOwn(runtime, "model")) return runtime.model ?? null;
+  try {
+    const factory = runtime.modelFactory ?? modelClientFromEnv;
+    const client = await factory(runtime.env ?? process.env);
+    if (client === undefined || client === null) return null;
+    if (typeof client.explain !== "function")
+      throw new TypeError("Invalid model client");
+    return (report) =>
+      client.explain(report, { allowLocal: true, signal: runtime.signal });
+  } catch {
+    process.stderr.write(
+      "model-configuration-invalid: Model configuration is invalid; deterministic analysis will continue.\n",
+    );
+    return async () => ({
+      status: "unavailable",
+      reason: "configuration-invalid",
+    });
+  }
+}
+
+export async function main(argv = process.argv.slice(2), runtime = {}) {
+  try {
+    const { out, offline, allowModel, registrySpec, ...options } = parse(argv);
+    let report;
+    if (registrySpec)
+      report = await checkHosted(registrySpec, {
+        serverUrl: (runtime.env ?? process.env).UNMASK_SERVER_URL,
+        fetchImpl: runtime.fetchImpl,
+        signal: runtime.signal,
+        limits: runtime.hostedLimits,
+      });
+    else {
+      const model = await configuredModel(allowModel, runtime);
+      report = await analyzeLocal({ ...options, limits: runtime.limits });
+      if (allowModel) report = await addConfiguredModel(report, model);
+      if (!allowModel)
+        report = {
+          ...report,
+          model: { status: "not-sent", reason: "consent-required" },
+        };
+    }
+    await writeReports(out, report);
+    process.stdout.write(`Report written to ${path.resolve(out)}\n`);
+    return report.policy.exitCode;
+  } catch (error) {
+    if (error instanceof LocalInputError) {
+      process.stderr.write(`${error.code}: ${error.message}\n`);
+      return 2;
+    }
+    process.stderr.write(
+      "Internal analysis error; no completed result is claimed.\n",
+    );
+    return 1;
+  }
+}
+
+function isEntrypoint(filename) {
+  if (!filename) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) === realpathSync(filename)
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint(process.argv[1])) process.exitCode = await main();