@the-open-engine-company/zeroshot 8.0.0

package/README.md

@@ -0,0 +1,7 @@
+# `@the-open-engine-company/zeroshot`
+
+Thin installer for the canonical `zeroshot` executable. The package selects the release archive for the current Node platform and architecture, verifies it against that release's `SHA256SUMS`, and installs only the verified executable.
+
+Installation fails closed with `UNSUPPORTED_ZEROSHOT_HOST` when the host has no declared release target. Source compilation and cross-target substitution are not supported.
+
+Supported hosts are Linux x64/arm64, macOS x64/arm64, and Windows x64.

package/bin/zeroshot.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { selectTarget } = require('../lib/install');
+
+try {
+  const { executable } = selectTarget();
+  const binary = path.join(__dirname, 'native', executable);
+  if (!fs.existsSync(binary)) {
+    throw new Error(
+      `NATIVE_BINARY_MISSING: ${binary}; reinstall @the-open-engine-company/zeroshot`
+    );
+  }
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  if (result.signal) process.kill(process.pid, result.signal);
+  else process.exitCode = result.status === null ? 1 : result.status;
+} catch (error) {
+  process.stderr.write(`zeroshot: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/install.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+
+const { install } = require('./lib/install');
+
+install().catch((error) => {
+  process.stderr.write(`zeroshot install failed: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/lib/install.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const https = require('https');
+const path = require('path');
+const { URL } = require('url');
+const {
+  archiveName,
+  extractExecutable,
+  parseChecksumManifest,
+  targetForHost,
+  verifyArchive,
+} = require('./release-artifacts');
+
+const RELEASE_BASE_URL = 'https://github.com/the-open-engine/zeroshot/releases/download';
+const RELEASE_TAG_PREFIX = 'v';
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_ARCHIVE_BYTES = 256 * 1024 * 1024;
+const TARGETS = Object.freeze(
+  require('../targets.json').map((declaration) => Object.freeze({ ...declaration }))
+);
+const HOST_TARGETS = Object.freeze(
+  Object.fromEntries(TARGETS.map((target) => [`${target.platform}/${target.arch}`, target]))
+);
+
+function selectTarget(platform = process.platform, arch = process.arch) {
+  const { target, executable } = targetForHost(TARGETS, platform, arch);
+  return { target, executable };
+}
+
+function download(url, maximumBytes, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      { headers: { 'user-agent': '@the-open-engine-company/zeroshot' } },
+      (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          response.resume();
+          if (redirects >= 5)
+            return reject(new Error(`DOWNLOAD_FAILED: too many redirects for ${url}`));
+          return download(
+            new URL(response.headers.location, url).toString(),
+            maximumBytes,
+            redirects + 1
+          ).then(resolve, reject);
+        }
+        if (response.statusCode !== 200) {
+          response.resume();
+          return reject(new Error(`DOWNLOAD_FAILED: ${url} returned HTTP ${response.statusCode}`));
+        }
+        const chunks = [];
+        let length = 0;
+        response.on('data', (chunk) => {
+          length += chunk.length;
+          if (length > maximumBytes)
+            request.destroy(new Error(`DOWNLOAD_FAILED: ${url} exceeds ${maximumBytes} bytes`));
+          else chunks.push(chunk);
+        });
+        response.on('end', () => resolve(Buffer.concat(chunks)));
+      }
+    );
+    request.on('error', reject);
+  });
+}
+
+function isReleaseVersion(version) {
+  if (typeof version !== 'string') return false;
+  const prereleaseStart = version.indexOf('-');
+  const core = prereleaseStart === -1 ? version : version.slice(0, prereleaseStart);
+  const prerelease = prereleaseStart === -1 ? '' : version.slice(prereleaseStart + 1);
+  const coreParts = core.split('.');
+  if (coreParts.length !== 3 || coreParts.some((part) => !part || !/^\d+$/.test(part))) {
+    return false;
+  }
+  return (
+    !prerelease ||
+    prerelease
+      .split('.')
+      .every(
+        (part) =>
+          part &&
+          [...part].every(
+            (character) =>
+              (character >= '0' && character <= '9') ||
+              (character >= 'A' && character <= 'Z') ||
+              (character >= 'a' && character <= 'z') ||
+              character === '-'
+          )
+      )
+  );
+}
+
+async function install(options = {}) {
+  const packageRoot = options.packageRoot || path.resolve(__dirname, '..');
+  const metadata =
+    options.packageMetadata ||
+    JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  if (!isReleaseVersion(metadata.version) || metadata.version === '0.0.0-development') {
+    throw new Error(
+      `UNRELEASED_SHIM_VERSION: cannot install binary for package version ${metadata.version}`
+    );
+  }
+  const selected = selectTarget(options.platform, options.arch);
+  const filename = archiveName(metadata.version, selected.target);
+  const baseUrl = `${RELEASE_BASE_URL}/${RELEASE_TAG_PREFIX}${metadata.version}`;
+  const fetchBuffer = options.fetchBuffer || download;
+  const manifest = await fetchBuffer(`${baseUrl}/SHA256SUMS`, MAX_MANIFEST_BYTES);
+  const archive = await fetchBuffer(`${baseUrl}/${filename}`, MAX_ARCHIVE_BYTES);
+  verifyArchive(filename, archive, manifest.toString('utf8'));
+  const executable = extractExecutable(archive, selected.executable);
+
+  const nativeDirectory = path.join(packageRoot, 'bin', 'native');
+  const destination = path.join(nativeDirectory, selected.executable);
+  const temporary = `${destination}.${process.pid}.tmp`;
+  fs.mkdirSync(nativeDirectory, { recursive: true });
+  try {
+    fs.writeFileSync(temporary, executable, { mode: 0o755, flag: 'wx' });
+    fs.renameSync(temporary, destination);
+    if (process.platform !== 'win32') fs.chmodSync(destination, 0o755);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  return destination;
+}
+
+module.exports = {
+  HOST_TARGETS,
+  RELEASE_BASE_URL,
+  RELEASE_TAG_PREFIX,
+  archiveName,
+  extractExecutable,
+  install,
+  parseChecksumManifest,
+  selectTarget,
+  verifyArchive,
+};

package/lib/release-artifacts.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const crypto = require('crypto');
+const zlib = require('zlib');
+
+function archiveName(version, target) {
+  return `zeroshot-v${version}-${target}.tar.gz`;
+}
+
+function targetForHost(declarations, platform, arch) {
+  const found = declarations.find(
+    (candidate) => candidate.platform === platform && candidate.arch === arch
+  );
+  if (!found) {
+    throw new Error(
+      `UNSUPPORTED_ZEROSHOT_HOST: no prebuilt binary for ${platform}/${arch}; supported hosts: ${declarations
+        .map((candidate) => `${candidate.platform}/${candidate.arch}`)
+        .join(', ')}`
+    );
+  }
+  return found;
+}
+
+function parseChecksumManifest(text) {
+  const checksums = new Map();
+  for (const line of text.split(/\r?\n/)) {
+    if (!line) continue;
+    const match = /^([0-9a-f]{64}) {2}([^/\\]+)$/.exec(line);
+    if (!match) throw new Error(`invalid SHA256SUMS line: ${line}`);
+    if (checksums.has(match[2])) throw new Error(`duplicate SHA256SUMS entry: ${match[2]}`);
+    checksums.set(match[2], match[1]);
+  }
+  return checksums;
+}
+
+function sha256(contents) {
+  return crypto.createHash('sha256').update(contents).digest('hex');
+}
+
+function verifyChecksum(filename, contents, manifest) {
+  const checksums = manifest instanceof Map ? manifest : parseChecksumManifest(manifest);
+  const expected = checksums.get(filename);
+  if (!expected) throw new Error(`CHECKSUM_MISSING: SHA256SUMS has no entry for ${filename}`);
+  const actual = sha256(contents);
+  if (actual !== expected) {
+    throw new Error(`CHECKSUM_MISMATCH: ${filename} expected ${expected} but received ${actual}`);
+  }
+  return true;
+}
+
+function verifyArchive(filename, archive, manifestText) {
+  return verifyChecksum(filename, archive, manifestText);
+}
+
+function parseTarSize(header) {
+  const value = header.toString('ascii').replace(/\0.*$/, '').trim();
+  if (!/^[0-7]+$/.test(value)) throw new Error('invalid tar entry size');
+  return Number.parseInt(value, 8);
+}
+
+function extractExecutable(archive, expectedName) {
+  let tar;
+  try {
+    tar = zlib.gunzipSync(archive);
+  } catch (error) {
+    throw new Error(`ARCHIVE_INVALID: cannot decompress release archive: ${error.message}`);
+  }
+  let offset = 0;
+  let executable = null;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) {
+      if (!tar.subarray(offset).every((byte) => byte === 0)) {
+        throw new Error('ARCHIVE_INVALID: unexpected data after tar terminator');
+      }
+      break;
+    }
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+    const size = parseTarSize(header.subarray(124, 136));
+    const start = offset + 512;
+    const end = start + size;
+    if (end > tar.length) throw new Error('ARCHIVE_INVALID: truncated tar entry');
+    if (name === expectedName) {
+      if (executable) throw new Error(`ARCHIVE_INVALID: duplicate ${expectedName}`);
+      executable = Buffer.from(tar.subarray(start, end));
+    } else {
+      throw new Error(`ARCHIVE_INVALID: unexpected archive entry ${name}`);
+    }
+    offset = start + Math.ceil(size / 512) * 512;
+  }
+  if (!executable) throw new Error(`ARCHIVE_INVALID: archive does not contain ${expectedName}`);
+  return executable;
+}
+
+module.exports = {
+  archiveName,
+  extractExecutable,
+  parseChecksumManifest,
+  sha256,
+  targetForHost,
+  verifyArchive,
+  verifyChecksum,
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@the-open-engine-company/zeroshot",
+  "version": "8.0.0",
+  "description": "Verified prebuilt binary installer for the standalone Zeroshot engine",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-open-engine/zeroshot.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "zeroshot": "bin/zeroshot.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "install.js",
+    "targets.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/targets.json

@@ -0,0 +1,32 @@
+[
+  {
+    "platform": "linux",
+    "arch": "x64",
+    "target": "x86_64-unknown-linux-musl",
+    "executable": "zeroshot"
+  },
+  {
+    "platform": "linux",
+    "arch": "arm64",
+    "target": "aarch64-unknown-linux-musl",
+    "executable": "zeroshot"
+  },
+  {
+    "platform": "darwin",
+    "arch": "x64",
+    "target": "x86_64-apple-darwin",
+    "executable": "zeroshot"
+  },
+  {
+    "platform": "darwin",
+    "arch": "arm64",
+    "target": "aarch64-apple-darwin",
+    "executable": "zeroshot"
+  },
+  {
+    "platform": "win32",
+    "arch": "x64",
+    "target": "x86_64-pc-windows-msvc",
+    "executable": "zeroshot.exe"
+  }
+]