vigilnz 0.0.1

package/README.md

@@ -0,0 +1,278 @@
+# vigilnz
+
+**Vigilnz is a security scanner for your code and container images.** It runs
+SAST, secret, SCA (dependency), IaC and SBOM scans against your local
+working directory, prints a readable report, and can sync findings to your
+Vigilnz dashboard.
+
+This npm package is a **thin installer/wrapper** around the native Vigilnz
+CLI binary — it downloads the right prebuilt binary for your platform,
+verifies it against a checksum pinned inside this package, and runs it with
+your arguments passed through unchanged.
+
+- Scans run **entirely against your local filesystem**. Nothing is cloned or
+  downloaded, and no Git remote is required.
+- **No source code is ever uploaded** — only findings metadata, and only
+  when you're signed in. Use `--no-upload` to keep a run fully local.
+
+## Install
+
+**As a command-line tool (recommended):**
+
+```bash
+npm install -g vigilnz
+vigilnz scan .
+```
+
+**Without installing:**
+
+```bash
+npx vigilnz scan .
+```
+
+## Quick start
+
+```bash
+vigilnz login          # sign in via your browser
+vigilnz scan           # scan the current directory
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vigilnz scan [path]` | Scan a local directory (SAST, secret, SCA, IaC, SBOM) |
+| `vigilnz scan-image <image>` | Scan a local Docker image for vulnerabilities |
+| `vigilnz login` | Authenticate the CLI with your Vigilnz account |
+| `vigilnz logout` | Remove stored credentials |
+| `vigilnz whoami` | Show which account you're signed in as |
+| `vigilnz config` | Show sign-in status and local configuration |
+| `vigilnz version` | Print the CLI version |
+
+Run `vigilnz <command> --help` for the full, authoritative flag list.
+
+## `vigilnz scan` — scan a directory
+
+The path is optional; with no path the current directory is scanned.
+
+```bash
+vigilnz scan                 # scan the current directory
+vigilnz scan .               # same, explicit
+vigilnz scan ./src/lib       # scan a specific directory
+vigilnz scan /abs/path       # relative or absolute
+```
+
+### What it scans
+
+| Type | What it finds |
+|---|---|
+| `sast` | Insecure code patterns |
+| `secret` | Hardcoded secrets and keys (values are masked, never uploaded) |
+| `sca` | Known vulnerabilities in your dependencies |
+| `iac` | Infrastructure-as-code misconfigurations (including Dockerfiles) |
+| `sbom` | Software bill of materials for your dependencies |
+
+All five run by default. SCA and SBOM work by collecting only your
+dependency manifest and lock files (`package.json`, `go.mod`, `pom.xml`,
+`requirements.txt`, `Cargo.toml`, …) — never source code. Because they
+require that upload, both are skipped under `--no-upload`; use
+`--local-audit` for a fully offline dependency check.
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--scan-types <list>` | Which scans to run (default `sast,secret,sca,iac,sbom`) |
+| `--fail-on <severity>` | Exit `1` if any finding is at or above `critical`\|`high`\|`medium`\|`low` |
+| `--json` | Print the report as a single JSON document |
+| `--no-upload` | Never send results anywhere; keep the scan entirely local |
+| `--remote` | Require the upload to succeed — fail the scan if it can't be sent (CI) |
+| `--include <paths>` | Comma-separated repo-relative paths to limit the scan to |
+| `--no-gitignore` | Don't skip files matched by `.gitignore` |
+| `--local-audit` | Also run the ecosystem's own audit tools alongside Vigilnz SCA |
+| `--max-concurrency <n>` | Max parallel file-scanning workers (`0` = auto) |
+
+`--local-audit` additionally runs `npm audit`, `pip-audit`, `govulncheck` or
+`cargo-audit` where available. Its results are reported and counted
+separately from Vigilnz SCA, so the two are never confused. Java/Maven/Gradle
+projects have no comparable local tool and are skipped with a notice — scan
+them with the default flow instead.
+
+### Examples
+
+```bash
+vigilnz scan ./src --scan-types sast,secret    # only these two scans
+vigilnz scan --json > report.json              # machine-readable output
+vigilnz scan ./backend --fail-on high          # fail on high+ findings
+vigilnz scan . --local-audit                   # add local dependency audit
+vigilnz scan . --no-upload                     # never leaves this machine
+vigilnz scan . --remote --fail-on high         # strict CI mode
+```
+
+## `vigilnz scan-image` — scan a Docker image
+
+Scans an image **already present in your local Docker daemon**. It never
+pulls or downloads an image.
+
+```bash
+vigilnz scan-image nginx:latest
+vigilnz scan-image myapp:v1 --json
+```
+
+Reports four separate categories: vulnerabilities, misconfigurations,
+secrets, and binary-hash vulnerabilities. Misconfiguration checks cover both
+image config/history (root user, exposed ports, missing healthcheck, …) and
+the image filesystem (SSH keys, credential files, `.env` files, world-writable
+paths, SUID/SGID binaries, EOL base image, …).
+
+Only small metadata leaves your machine — the detected package inventory,
+binary hashes, the image's own OCI config/history, per-layer file path lists,
+and already-masked findings. Never the image, its layers, or raw secret
+values.
+
+Dockerfile analysis is **not** part of this command — run
+`vigilnz scan <path>` against a repo containing a Dockerfile for that.
+
+| Flag | Description |
+|---|---|
+| `--json` | Print the report as a single JSON document |
+
+## Authentication
+
+A Vigilnz account is required to scan.
+
+```bash
+vigilnz login                  # browser sign-in
+vigilnz login --no-browser     # print the URL instead of opening a browser
+vigilnz login --force          # switch accounts without logging out first
+```
+
+The authorization URL is always printed first, so sign-in still works over
+SSH, in a container, or on a headless host — copy it to a browser anywhere.
+
+**For non-interactive environments**, supply an API key instead and no browser
+is involved:
+
+```bash
+vigilnz login --api-key <key>
+VIGILNZ_API_KEY=<key> vigilnz login
+```
+
+Create the key from your Vigilnz dashboard, and keep it in a secret store —
+never in your repository. The resulting token is written to your user config
+directory with owner-only permissions; the raw API key itself is never
+written to disk.
+
+`--api-key` is read by `vigilnz login`, which exchanges it for that stored
+token — so sign in first, then scan:
+
+```bash
+vigilnz login --api-key <key>
+vigilnz scan . --fail-on high
+```
+
+```bash
+vigilnz whoami                 # which account am I signed in as?
+vigilnz config                 # sign-in status + config file path
+vigilnz logout                 # remove stored credentials
+```
+
+## Exit codes
+
+Stable across releases, so CI can rely on them:
+
+| Code | Meaning |
+|---|---|
+| `0` | Scan completed, no policy violation |
+| `1` | Findings violate the configured policy (`--fail-on`) |
+| `2` | Scanner or runtime error |
+| `3` | Authentication or configuration error |
+
+This wrapper mirrors the binary's exit code and signal exactly, so these
+work identically through `npx`.
+
+## Global options
+
+| Flag | Description |
+|---|---|
+| `--api-key <key>` | API key to sign in with (see [Authentication](#authentication)) |
+| `--config <path>` | Path to the config file (default: your OS user config dir) |
+| `-v`, `--verbose` | Show redacted diagnostic detail on errors (never secrets) |
+
+## This package exposes no importable module
+
+`vigilnz` is a **CLI-only** package. It has no `main` and no `exports` entry
+point, so there is nothing to `require()` or `import`:
+
+```js
+const vigilnz = require('vigilnz'); // ✗ throws MODULE_NOT_FOUND
+import 'vigilnz';                   // ✗ throws ERR_MODULE_NOT_FOUND
+```
+
+Run it as a command instead (`npx vigilnz ...` or a global install). There is
+deliberately no JavaScript API: the CLI is a Go binary
+with its own authentication and configuration, and every distribution channel
+wraps that one binary rather than reimplementing it. To trigger a scan from
+Node, spawn the CLI as a child process and read its exit code — exit codes and
+stdio pass through this wrapper unchanged.
+
+## Supported platforms
+
+| OS | Architecture |
+|---|---|
+| Windows | x64 (arm64 runs the x64 build via Windows' built-in emulation — no native windows-arm64 binary is published) |
+| Linux | x64, arm64 |
+| macOS | x64, arm64 |
+
+This package deliberately does **not** declare npm's `os`/`cpu` fields. Those
+are independent lists and cannot express "every combination except
+windows+arm64", so declaring them would hard-fail installs on platforms that
+actually work. Platform support is enforced at runtime instead, with an
+actionable error.
+
+## If the install-time download fails
+
+The `postinstall` hook is **fail-soft**: if it cannot reach the download host
+it prints a warning and lets your install succeed. Nothing is broken — the
+binary is downloaded automatically the first time you run `vigilnz`. This
+also covers installs that skip lifecycle scripts entirely
+(`npm install --ignore-scripts`).
+
+That means a failed download can never break your `npm install` because of a
+proxy, an offline machine, or a CDN blip.
+
+## Environment variables
+
+**CLI**
+
+- `VIGILNZ_API_KEY` — API key for `vigilnz login`, for non-interactive use. Equivalent to `--api-key`.
+
+**This npm wrapper**
+
+- `VIGILNZ_CLI_CDN_URL` — override the download host (default `https://releases.vigilnz.com/releases`), for private mirrors or air-gapped environments.
+- `VIGILNZ_CLI_SKIP_DOWNLOAD=1` — skip the postinstall download entirely; you're responsible for placing the binary at `bin/vigilnz-bin/vigilnz(.exe)` yourself.
+
+## How downloads are verified
+
+The expected SHA256 digests live in `checksums/checksums.json`, **inside this
+published package**, pinned when the version is released.
+
+They are deliberately not fetched from the release host at install time:
+verifying a download against a checksum from the same host only proves that
+host agrees with itself. Pinning the digests here puts them behind npm
+registry integrity instead.
+
+Verification **fails closed** — if the pinned digest is missing, malformed, or
+stamped for a different version, the download is refused rather than falling
+back to trusting the host.
+
+Every distribution channel (direct binary, this npm package, Homebrew,
+Docker) runs the exact same CLI binary — only the reported distribution
+differs, so the Vigilnz Platform can show which channel a scan came from
+(e.g. "Vigilnz CLI · npm").
+
+## License
+
+The license for this wrapper is not finalized yet. The Vigilnz CLI binary it
+downloads, and the Vigilnz platform it connects to, are governed by the
+Vigilnz terms of service.

package/bin/vigilnz.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// File:    vigilnz.js
+// Purpose: npm distribution wrapper entry point. Locates the native
+//          Vigilnz CLI binary (downloaded by install.js) and execs it with
+//          every argument passed through unmodified — this file contains
+//          NO scan logic of its own. Every distribution channel (binary,
+//          npm, Homebrew, Docker, ...) wraps one real CLI implementation.
+//
+//          Self-heals a missing binary (e.g. `npx vigilnz` on an npm
+//          version that skips lifecycle scripts, or an install that used
+//          --ignore-scripts) by running the same download step
+//          install.js's postinstall hook already ran, once, on demand.
+// Author:  Vigilnz
+// Date:    2026-08-23
+// Modified: 2026-08-27 — verify the self-healed download against the digest
+//           pinned in this tarball (lib/checksums.js), the same source
+//           install.js's postinstall path uses. This supersedes an earlier
+//           same-day fix that passed fallbackNames through to a CDN-fetched
+//           SHA256SUMS: that file is no longer fetched at runtime at all.
+//           Because postinstall is now fail-soft, this path is the real
+//           install for anyone behind a proxy at install time — it must
+//           stay working.
+
+'use strict';
+
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const { resolvePlatform, artifactUrl } = require('../lib/platform');
+const { binaryDestPath } = require('../lib/binaryPath');
+const { downloadVerified } = require('../lib/download');
+const { pinnedChecksumFor } = require('../lib/checksums');
+
+async function ensureBinary() {
+  const { platformDir, binName, remoteFileName } = resolvePlatform();
+  const destPath = binaryDestPath(binName);
+  if (fs.existsSync(destPath)) {
+    return destPath;
+  }
+
+  const pkg = require('../package.json');
+  process.stderr.write('[vigilnz] Binary not found — downloading now (this only happens once)...\n');
+  await downloadVerified({
+    binaryUrl: artifactUrl(pkg.version, platformDir, remoteFileName),
+    expectedSha256: pinnedChecksumFor(remoteFileName, pkg.version),
+    artifactName: remoteFileName,
+    destPath,
+  });
+  return destPath;
+}
+
+async function main() {
+  let binaryPath;
+  try {
+    binaryPath = await ensureBinary();
+  } catch (err) {
+    process.stderr.write(`[vigilnz] Unable to locate or download the Vigilnz CLI binary: ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Pass every argument through untouched, inherit stdio so interactive
+  // prompts (vigilnz login) and colored output work exactly as running
+  // the binary directly would. VIGILNZ_CLI_DISTRIBUTION overrides the
+  // binary's compiled-in default so scan uploads report this channel
+  // correctly — npm never builds its own binary, it downloads the same
+  // prebuilt artifact every channel uses, so the compile-time value alone
+  // would misreport here. A caller that already set the var (e.g. for
+  // testing) is left untouched.
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+    env: { ...process.env, VIGILNZ_CLI_DISTRIBUTION: process.env.VIGILNZ_CLI_DISTRIBUTION || 'npm' },
+  });
+
+  if (result.error) {
+    process.stderr.write(`[vigilnz] Failed to run the Vigilnz CLI binary: ${result.error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  // Mirror the child's exit code/signal exactly, so CI pipelines relying on
+  // `vigilnz scan --fail-on ...`'s exit code see the same result they would
+  // running the binary directly.
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+  process.exitCode = result.status ?? 1;
+}
+
+main();

package/checksums/checksums.json

@@ -0,0 +1,10 @@
+{
+  "version": "0.0.1",
+  "artifacts": {
+    "vigilnz-windows-amd64.exe": "a6c4a4d1e4a0a70249241c3466b7c6931f4ef1bb34fedb2cf23c50017f89dc32",
+    "vigilnz-linux-amd64": "572bc1ad4b9ac20e1fbe32168174e36304488be990f0d9e6b8260e73e3ed4392",
+    "vigilnz-linux-arm64": "87bc197fa1e4734e3e41e7ac06b52cc2790c734568d02a17490df7ad419548e3",
+    "vigilnz-darwin-amd64": "42f0da8eb6a0333e9b09b906a5c593206f3f04de2dbdb979075174e582fdff53",
+    "vigilnz-darwin-arm64": "5bcef2b111d12d337852aeca4ad7fd13dec7b58c2668b6a2fd295130bc26bd1d"
+  }
+}

package/install.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// File:    install.js
+// Purpose: npm postinstall hook — downloads the correct prebuilt Vigilnz
+//          CLI binary for the current OS/architecture from the public
+//          release CDN, verifies it against the SHA256 digest pinned in
+//          this tarball (checksums/checksums.json), and stores it inside
+//          this package (bin/vigilnz-bin/). This package never builds or
+//          reimplements the CLI itself — every distribution channel wraps
+//          one real implementation.
+//
+//          FAIL-SOFT BY DESIGN: this hook never exits non-zero. npm treats
+//          a failing postinstall as a failed install, which would break the
+//          whole dependency install of any project that merely lists
+//          vigilnz as a devDependency — and npm does NOT roll the package
+//          back, so it leaves a half-installed tree behind. A blocked
+//          proxy or an offline CI runner must not do that. Instead we warn
+//          here and let bin/vigilnz.js download on first actual use — the
+//          same fail-soft posture other native-binary npm wrappers take.
+//
+//          VIGILNZ_CLI_SKIP_DOWNLOAD=1 skips this entirely — for offline/
+//          air-gapped installs where the binary is placed by some other
+//          means (e.g. a corporate mirror step) before first run.
+// Author:  Vigilnz
+// Date:    2026-08-23
+// Modified: 2026-08-27 — dropped an unused `path` import; verify against
+//           the pinned digest instead of a CDN-fetched SHA256SUMS; made
+//           the hook fail-soft (warn + exit 0) so it cannot break a
+//           consumer's `npm install`.
+
+'use strict';
+
+const fs = require('fs');
+const { resolvePlatform, artifactUrl } = require('./lib/platform');
+const { downloadVerified } = require('./lib/download');
+const { binaryDestPath } = require('./lib/binaryPath');
+const { pinnedChecksumFor } = require('./lib/checksums');
+
+/**
+ * Explain a non-fatal failure without dumping a stack trace into a
+ * consumer's install log, and point at every real escape hatch.
+ *
+ * @param {Error} err
+ */
+function warnNonFatal(err) {
+  process.stderr.write(
+    `\n[vigilnz] WARNING: could not install the Vigilnz CLI binary now:\n` +
+      `  ${err.message}\n` +
+      '\n[vigilnz] This is not fatal — your install continues, and the binary will be\n' +
+      '[vigilnz] downloaded automatically the first time you run `vigilnz`.\n' +
+      '[vigilnz] If that machine also cannot reach the download host, you can:\n' +
+      '[vigilnz]   - Set VIGILNZ_CLI_CDN_URL to a private mirror\n' +
+      '[vigilnz]   - Set VIGILNZ_CLI_SKIP_DOWNLOAD=1 and place the binary yourself\n\n'
+  );
+}
+
+async function main() {
+  if (process.env.VIGILNZ_CLI_SKIP_DOWNLOAD === '1') {
+    console.log('[vigilnz] VIGILNZ_CLI_SKIP_DOWNLOAD=1 set — skipping binary download.');
+    return;
+  }
+
+  const pkg = require('./package.json');
+  const version = pkg.version;
+  const { platformDir, binName, remoteFileName } = resolvePlatform();
+  const destPath = binaryDestPath(binName);
+
+  if (fs.existsSync(destPath)) {
+    console.log(`[vigilnz] Binary already present at ${destPath} — skipping download.`);
+    return;
+  }
+
+  console.log(`[vigilnz] Downloading Vigilnz CLI v${version} for ${platformDir}...`);
+  await downloadVerified({
+    binaryUrl: artifactUrl(version, platformDir, remoteFileName),
+    expectedSha256: pinnedChecksumFor(remoteFileName, version),
+    artifactName: remoteFileName,
+    destPath,
+  });
+  console.log(`[vigilnz] Installed to ${destPath}`);
+}
+
+main().catch((err) => {
+  warnNonFatal(err);
+  // Deliberately exit 0 — see the FAIL-SOFT note in the file header.
+  process.exitCode = 0;
+});

package/lib/binaryPath.js

@@ -0,0 +1,19 @@
+// File:    binaryPath.js
+// Purpose: Single source of truth for where the downloaded Vigilnz CLI
+//          binary lives on disk, shared by install.js and bin/vigilnz.js.
+// Author:  Vigilnz
+// Date:    2026-08-23
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @param {string} binName - "vigilnz" or "vigilnz.exe" (see lib/platform.js)
+ * @returns {string} absolute path inside this package where the binary is stored
+ */
+function binaryDestPath(binName) {
+  return path.join(__dirname, '..', 'bin', 'vigilnz-bin', binName);
+}
+
+module.exports = { binaryDestPath };

package/lib/checksums.js

@@ -0,0 +1,129 @@
+// File:    checksums.js
+// Purpose: Reads the SHA256 digests that are PINNED INSIDE this npm
+//          tarball (checksums/checksums.json), rather than fetching a
+//          SHA256SUMS file from the same CDN the binary itself comes from.
+//
+//          Why this matters: verifying a download against a checksum
+//          fetched from that same host only proves "the host agrees with
+//          itself" — whoever can tamper with one can tamper with both.
+//          Pinning the digests in the published package puts them behind
+//          npm registry integrity instead, so the trust anchor is the
+//          registry rather than the release host. The Homebrew channel
+//          does the equivalent by baking digests into its formula.
+//
+//          The digest file is generated at publish time and is deliberately
+//          NOT committed, so a stale digest set can never be published by
+//          accident; the release pipeline verifies it before publishing.
+// Author:  Vigilnz
+// Date:    2026-08-27
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** Location of the generated, tarball-pinned digest set. */
+const CHECKSUMS_PATH = path.join(__dirname, '..', 'checksums', 'checksums.json');
+
+/**
+ * Every platform the release pipeline actually publishes. windows-arm64 is
+ * absent on purpose (see lib/platform.js) — keep this in sync with what
+ * the pipeline builds.
+ */
+const PUBLISHED_PLATFORMS = [
+  'windows-amd64',
+  'linux-amd64',
+  'linux-arm64',
+  'darwin-amd64',
+  'darwin-arm64',
+];
+
+const SHA256_HEX_LENGTH = 64;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+
+/**
+ * Load and structurally validate the pinned digest set.
+ *
+ * @param {string} [filePath] - override, for tests only. Production callers
+ *        must use the default: tests that wrote to the real path used to
+ *        leave a bogus digest set behind, which `npm pack` then shipped.
+ * @returns {{ version: string, artifacts: Record<string, string> }}
+ * @throws {Error} if the file is missing, unparseable, or malformed
+ */
+function loadPinnedChecksums(filePath = CHECKSUMS_PATH) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `No pinned checksum file at ${filePath} (${err.code}). This package was ` +
+        'published without its checksums being stamped, or you are running from ' +
+        'a source checkout where they have not been generated yet.'
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Pinned checksum file ${filePath} is not valid JSON: ${err.message}`);
+  }
+
+  if (!parsed || typeof parsed.version !== 'string' || !parsed.artifacts) {
+    throw new Error(
+      `Pinned checksum file ${filePath} is malformed: expected {version, artifacts}.`
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Look up the pinned digest for one release artifact, failing closed on any
+ * problem — a missing entry, a malformed digest, or a digest set stamped for
+ * a different CLI version. There is deliberately NO fallback to downloading
+ * SHA256SUMS from the CDN: that fallback would silently restore exactly the
+ * weaker trust model this module exists to remove.
+ *
+ * @param {string} artifactName - remote artifact name, e.g. "vigilnz-linux-amd64"
+ * @param {string} expectedVersion - the version being installed (package.json's own)
+ * @param {string} [filePath] - override, for tests only (see loadPinnedChecksums)
+ * @returns {string} lowercase 64-char hex digest
+ * @throws {Error} if no trustworthy digest is available
+ */
+function pinnedChecksumFor(artifactName, expectedVersion, filePath = CHECKSUMS_PATH) {
+  const { version, artifacts } = loadPinnedChecksums(filePath);
+
+  // Guards against stamping drift: a checksums.json left over from an
+  // earlier version would otherwise verify this version's binary against
+  // the wrong digest and fail with a confusing "corrupted download".
+  if (version !== expectedVersion) {
+    throw new Error(
+      `Pinned checksums are for CLI v${version} but this package is v${expectedVersion}. ` +
+        'This package was built with a mismatched checksum set — please report it.'
+    );
+  }
+
+  const digest = artifacts[artifactName];
+  if (typeof digest !== 'string') {
+    throw new Error(
+      `Pinned checksums have no entry for ${artifactName} ` +
+        `(have: ${Object.keys(artifacts).sort().join(', ') || 'none'}).`
+    );
+  }
+
+  const normalized = digest.trim().toLowerCase();
+  if (!SHA256_PATTERN.test(normalized)) {
+    throw new Error(
+      `Pinned digest for ${artifactName} is not a ${SHA256_HEX_LENGTH}-char hex sha256: "${digest}".`
+    );
+  }
+  return normalized;
+}
+
+module.exports = {
+  loadPinnedChecksums,
+  pinnedChecksumFor,
+  CHECKSUMS_PATH,
+  PUBLISHED_PLATFORMS,
+  SHA256_PATTERN,
+};

package/lib/download.js

@@ -0,0 +1,141 @@
+// File:    download.js
+// Purpose: Download + SHA256-verify one Vigilnz CLI release artifact.
+//          Shared by install.js (postinstall) and bin/vigilnz.js's
+//          lazy-self-heal path (npx / --ignore-scripts installs that
+//          skipped postinstall). Uses only Node built-ins — no runtime
+//          dependency footprint for a package whose whole job is being a
+//          thin wrapper.
+// Author:  Vigilnz
+// Date:    2026-08-23
+// Modified: 2026-08-27 — downloadVerified now takes the expected digest
+//           from the caller (lib/checksums.js reads it from the pinned,
+//           in-tarball checksums.json) instead of fetching SHA256SUMS from
+//           the same host as the binary, which only proved that host agreed
+//           with itself. findChecksum stays exported: the release pipeline's
+//           stamping step still parses the sha256sum-format SHA256SUMS at
+//           publish time to build that pinned set.
+
+'use strict';
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+const path = require('path');
+
+const MAX_REDIRECTS = 5;
+
+/**
+ * GET a URL to a Buffer, following redirects (S3/CloudFront commonly
+ * 301/302 on a stale cache miss). Rejects on any non-2xx final status.
+ * Picks http vs https by URL scheme — the default public CDN is always
+ * https, but a private mirror (VIGILNZ_CLI_CDN_URL, or a test server)
+ * may reasonably be plain http on an internal network.
+ *
+ * @param {string} url
+ * @param {number} [redirectsLeft]
+ * @returns {Promise<Buffer>}
+ */
+function fetchBuffer(url, redirectsLeft = MAX_REDIRECTS) {
+  const transport = url.startsWith('http://') ? http : https;
+  return new Promise((resolve, reject) => {
+    const req = transport.get(url, { headers: { 'User-Agent': 'vigilnz-npm-cli' } }, (res) => {
+      const { statusCode, headers } = res;
+      if (statusCode >= 300 && statusCode < 400 && headers.location && redirectsLeft > 0) {
+        res.resume();
+        fetchBuffer(headers.location, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (statusCode !== 200) {
+        res.resume();
+        reject(new Error(`GET ${url} returned HTTP ${statusCode}`));
+        return;
+      }
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    req.setTimeout(60_000, () => req.destroy(new Error(`GET ${url} timed out after 60s`)));
+  });
+}
+
+/**
+ * Parse a `sha256sum`-format SHA256SUMS file (`<hex>  <filename>` per line,
+ * matching the release pipeline's checksum generation) and return the hex
+ * digest for one file name.
+ *
+ * @param {string} sha256sumsText
+ * @param {string} fileName
+ * @returns {string | null}
+ */
+function findChecksum(sha256sumsText, fileName, fallbackNames = []) {
+  const entries = [];
+
+  for (const line of sha256sumsText.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(/^([a-f0-9]{64})\s+\*?(.+)$/i);
+    if (match) {
+      entries.push({
+        digest: match[1].toLowerCase(),
+        name: path.basename(match[2].trim()),
+      });
+    }
+  }
+
+  for (const wanted of [fileName, ...fallbackNames]) {
+    const hit = entries.find((entry) => entry.name === wanted);
+    if (hit) return hit.digest;
+  }
+
+  // Deliberately NO "if there's only one entry, use it" fallback: a lone
+  // entry naming a different artifact would then be verified against,
+  // which is exactly the case test/download.test.js guards. Matching is by
+  // name only — an unmatched name returns null and the caller fails.
+  return null;
+}
+
+/**
+ * Download one binary artifact, verify it against a digest the CALLER
+ * supplies (pinned in this tarball — see lib/checksums.js), and write it to
+ * destPath (0755 on non-Windows). Throws with a clear message on any
+ * network, HTTP, or checksum-mismatch failure — never writes a partial or
+ * unverified file to destPath.
+ *
+ * @param {{ binaryUrl: string, expectedSha256: string, artifactName: string, destPath: string }} opts
+ */
+async function downloadVerified({ binaryUrl, expectedSha256, artifactName, destPath }) {
+  const expected = String(expectedSha256 || '')
+    .trim()
+    .toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(expected)) {
+    // Fail before spending bandwidth: an absent/garbage expected digest
+    // must never degrade into "download it and hope".
+    throw new Error(
+      `Refusing to download ${artifactName} without a valid pinned sha256 digest ` +
+        `(got "${expectedSha256}").`
+    );
+  }
+
+  const binary = await fetchBuffer(binaryUrl);
+
+  const actual = crypto.createHash('sha256').update(binary).digest('hex');
+  if (actual !== expected) {
+    throw new Error(
+      `Checksum mismatch for ${artifactName}: expected ${expected}, got ${actual}. ` +
+        'The download may be corrupted or tampered with — not installing it.'
+    );
+  }
+
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  const tmpPath = `${destPath}.download-${process.pid}`;
+  fs.writeFileSync(tmpPath, binary, { mode: 0o755 });
+  fs.renameSync(tmpPath, destPath); // atomic on the same filesystem — no partially-written binary left behind
+  if (process.platform !== 'win32') {
+    fs.chmodSync(destPath, 0o755);
+  }
+}
+
+module.exports = { downloadVerified, fetchBuffer, findChecksum };

package/lib/platform.js

@@ -0,0 +1,97 @@
+// File:    platform.js
+// Purpose: OS/CPU-architecture detection and download-URL construction for
+//          the Vigilnz CLI's npm distribution wrapper. This is the ONLY
+//          place that knows the published release-artifact layout — a
+//          version bump or a new platform target only needs a change here,
+//          never in install.js/bin/vigilnz.js.
+//
+//          This package never reimplements any scan logic — it only
+//          locates and executes the single native Vigilnz CLI binary.
+// Author:  Vigilnz
+// Date:    2026-08-23
+
+'use strict';
+
+/**
+ * Public host serving CLI release artifacts — deliberately SEPARATE from
+ * the API the CLI talks to at runtime. Never point this at an application
+ * backend.
+ */
+const DEFAULT_CDN_BASE_URL = 'https://releases.vigilnz.com/releases';
+
+/** Override for private mirrors / air-gapped installs / CI testing. */
+function cdnBaseUrl() {
+  return (process.env.VIGILNZ_CLI_CDN_URL || DEFAULT_CDN_BASE_URL).replace(/\/+$/, '');
+}
+
+/**
+ * Maps Node's process.platform to the release's OS name and the local
+ * binary filename — must stay in sync with the platforms the release
+ * pipeline publishes.
+ */
+const PLATFORM_MAP = {
+  win32: { os: 'windows', binName: 'vigilnz.exe' },
+  linux: { os: 'linux', binName: 'vigilnz' },
+  darwin: { os: 'darwin', binName: 'vigilnz' },
+};
+
+/** Maps Node's process.arch to the architecture names releases publish under. */
+const ARCH_MAP = {
+  x64: 'amd64',
+  arm64: 'arm64',
+};
+
+/**
+ * Resolve the current process's platform/arch into this release's naming
+ * scheme, or throw a clear, actionable error for an unsupported combination
+ * — either one the release pipeline never produces (e.g. 32-bit Windows),
+ * or windows/arm64 specifically, which is deliberately excluded.
+ *
+ * @returns {{ platformDir: string, binName: string, remoteFileName: string }}
+ */
+function resolvePlatform() {
+  const platformEntry = PLATFORM_MAP[process.platform];
+  const goArch = ARCH_MAP[process.arch];
+
+  if (!platformEntry || !goArch) {
+    throw new Error(
+      `Vigilnz CLI has no prebuilt binary for ${process.platform}/${process.arch}. ` +
+        'Supported: Windows/Linux/macOS on x64 or arm64 (Windows/arm64 excepted — see below). ' +
+        'Build the CLI from source for this platform, or set VIGILNZ_CLI_SKIP_DOWNLOAD=1 ' +
+        'and place a binary yourself.'
+    );
+  }
+
+  if (platformEntry.os === 'windows' && goArch === 'arm64') {
+    throw new Error(
+      'Vigilnz CLI has no prebuilt binary for windows/arm64. Windows 11 on ARM can ' +
+        'run the windows-amd64 build via its built-in x64 emulation instead: set ' +
+        'VIGILNZ_CLI_SKIP_DOWNLOAD=1 and place that binary yourself.'
+    );
+  }
+
+  const platformDir = `${platformEntry.os}-${goArch}`;
+  const ext = platformEntry.os === 'windows' ? '.exe' : '';
+  return {
+    platformDir,
+    binName: platformEntry.binName,
+    // The name the file actually has on releases.vigilnz.com — distinct
+    // from binName, which is the LOCAL name this package stores/execs the
+    // binary as once downloaded (see lib/binaryPath.js).
+    remoteFileName: `vigilnz-${platformDir}${ext}`,
+  };
+}
+
+/**
+ * Build the download URL for one release artifact.
+ *
+ * @param {string} version - CLI version (matches this package's own package.json version)
+ * @param {string} platformDir - e.g. "linux-amd64" (from resolvePlatform())
+ * @param {string} fileName - the remote binary name (resolvePlatform().remoteFileName) or "SHA256SUMS"
+ * @returns {string}
+ */
+function artifactUrl(version, platformDir, fileName) {
+  return `${cdnBaseUrl()}/v${version}/${platformDir}/${fileName}`;
+}
+
+module.exports = { resolvePlatform, artifactUrl, cdnBaseUrl, DEFAULT_CDN_BASE_URL };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "vigilnz",
+  "version": "0.0.1",
+  "description": "Vigilnz security scanner CLI — thin installer/wrapper that downloads and runs the native Vigilnz CLI binary. No scan logic lives in this package.",
+  "bin": {
+    "vigilnz": "bin/vigilnz.js"
+  },
+  "files": [
+    "bin/vigilnz.js",
+    "lib/",
+    "checksums/",
+    "install.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node install.js",
+    "stamp-checksums": "node scripts/stamp-checksums.js",
+    "prepack": "node scripts/stamp-checksums.js --check",
+    "prepublishOnly": "node scripts/stamp-checksums.js --check",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "vigilnz",
+    "security",
+    "sast",
+    "sca",
+    "secret-scanning",
+    "iac",
+    "sbom",
+    "container-scanning"
+  ],
+  "author": "Vigilnz",
+  "license": "UNKNOWN",
+  "homepage": "https://vigilnz.com"
+}