@orbit-tools/cli 0.6.0 → 0.7.1

package/README.md

@@ -3,9 +3,9 @@
 npm proxy for the [Orbit](https://github.com/danieljhkim/orbit) CLI.
 
 On install, downloads the matching prebuilt `orbit` binary from
-[GitHub Releases](https://github.com/danieljhkim/orbit/releases), verifies its
-SHA-256 against the published `orbit-checksums.txt`, and exposes it as the
-`orbit` command.
+[GitHub Releases](https://github.com/danieljhkim/orbit/releases), authenticates
+the signed `orbit-checksums.txt` with the package-pinned release trust set,
+verifies the archive SHA-256, and exposes it as the `orbit` command.
 
 ## Usage
 
@@ -31,8 +31,11 @@ Windows is not currently published. Use WSL or build from source.
 
 | Variable | Effect |
 |---|---|
-| `ORBIT_BINARY` | Path to a local `orbit` binary; bypasses download. |
-| `ORBIT_BINARY_VERSION` | Override the release tag to install (e.g. `v0.3.1`). |
+| `ORBIT_BINARY` | Path to a local `orbit` binary; bypasses download and trusts that path as the binary source. |
+| `ORBIT_RELEASE_PUBLIC_KEY_FILE` | **Deprecated** in favor of `ORBIT_RELEASE_TRUSTED_KEYS_FILE`. Single-key override for the trusted checksum-signing public key; requires `ORBIT_RELEASE_PUBLIC_KEY_FILE_ACKNOWLEDGE_TRUST_CHANGE=1`, logs a deprecation notice when active. |
+| `ORBIT_RELEASE_PUBLIC_KEY_FILE_ACKNOWLEDGE_TRUST_CHANGE=1` | Required acknowledgement that `ORBIT_RELEASE_PUBLIC_KEY_FILE` replaces the release authenticity trust root. |
+| `ORBIT_RELEASE_TRUSTED_KEYS_FILE` | Preferred test/operations override for the full trusted signing-key set, including key IDs, `not_after`, and `revoked_at`; requires `ORBIT_RELEASE_TRUSTED_KEYS_FILE_ACKNOWLEDGE_TRUST_CHANGE=1` and logs when active. |
+| `ORBIT_RELEASE_TRUSTED_KEYS_FILE_ACKNOWLEDGE_TRUST_CHANGE=1` | Required acknowledgement that `ORBIT_RELEASE_TRUSTED_KEYS_FILE` replaces the release authenticity trust root. |
 | `ORBIT_SKIP_DOWNLOAD=1` | Skip postinstall download (lazy install on first run still works). |
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbit-tools/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "npm proxy for the Orbit CLI. Downloads the matching native binary from GitHub Releases on install and forwards all invocations.",
   "bin": {
     "orbit": "bin/orbit.js"
@@ -12,6 +12,7 @@
   "files": [
     "bin/",
     "scripts/",
+    "release-signing.pub",
     "README.md",
     "LICENSE"
   ],

package/release-signing.pub

@@ -0,0 +1,11 @@
+-----BEGIN PUBLIC KEY-----
+MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAoQGLKOvvsvXriGIQ0oxA
+PcDyVHLM1iqXBCYXg+blQU41haEkG1eYabvDfeGcyGaC4awW7Q2uCZK05+/Hdjpe
+cRUVxP+QWKCAHyretQwOsoXzutZjJgId/ZRiUJPS/FeJOSv0xrayaol0tmfeJ4mH
+gFseCLq+mIIWIPRvXmYiKaUB//bjF79w/m4VXlyBhfi6n+f6x2UPG+gjjsjwG6mn
+Orec31AAFCIIX69YAd21D3MBc4S89/LoYZCq3neDscZ09Y+e6Jg2HpoBstvqSnq/
+3s34unLuIRlyB8jyK8CrdzT1E6YVB7+riAjycE9XMlLOQ2xA4tl6CKIx5YTKHyeW
+npMLlbzNaVfFT7p3IPTxsoEI0SB3ZtO7/XhzuOvOpklYcqjW2DGw/yzr2epAqHE/
+y4rLO3hkxWhxfgF5KPSR2iftc3LMONRGWELK6jpD5KB7No5vwIvjpVPUc5xA45Xw
+tT/bo0mm4TvrumxYr1xyEHrdum+ej/WYz/0BZQlwDOtXAgMBAAE=
+-----END PUBLIC KEY-----

package/scripts/install-binary.js

@@ -10,12 +10,67 @@ const os = require('node:os');
 
 const PKG = require('../package.json');
 const BINARY_REPO = PKG.config.orbit.binaryRepo;
-// Convention: npm package version is kept in lockstep with the orbit release tag.
-// `0.3.1` → fetches `v0.3.1` from GitHub Releases. Override with $ORBIT_BINARY_VERSION.
-const BINARY_VERSION = process.env.ORBIT_BINARY_VERSION || `v${PKG.version}`;
+const CHECKSUM_FILE = 'orbit-checksums.txt';
+const CHECKSUM_SIGNATURE_FILE = 'orbit-checksums.txt.sig';
+// npm package version is kept in lockstep with the orbit release tag. `0.3.1`
+// → fetches `v0.3.1` from GitHub Releases. The mapping is intentionally strict:
+// older orbit binaries can no longer be installed through this package, so the
+// trust set only needs to cover the current release.
+const BINARY_VERSION = `v${PKG.version}`;
 const PKG_ROOT = path.resolve(__dirname, '..');
 const BIN_DIR = path.join(PKG_ROOT, 'binaries');
 const BIN_PATH = path.join(BIN_DIR, process.platform === 'win32' ? 'orbit.exe' : 'orbit');
+const PUBLIC_KEY_OVERRIDE = process.env.ORBIT_RELEASE_PUBLIC_KEY_FILE;
+const PUBLIC_KEY_OVERRIDE_ACK_ENV = 'ORBIT_RELEASE_PUBLIC_KEY_FILE_ACKNOWLEDGE_TRUST_CHANGE';
+const TRUSTED_KEYS_OVERRIDE = process.env.ORBIT_RELEASE_TRUSTED_KEYS_FILE;
+const TRUSTED_KEYS_OVERRIDE_ACK_ENV = 'ORBIT_RELEASE_TRUSTED_KEYS_FILE_ACKNOWLEDGE_TRUST_CHANGE';
+const TRUSTED_PUBLIC_KEY_PATH = PUBLIC_KEY_OVERRIDE
+  ? path.resolve(PUBLIC_KEY_OVERRIDE)
+  : path.join(PKG_ROOT, 'release-signing.pub');
+const TRUSTED_KEYS_OVERRIDE_PATH = TRUSTED_KEYS_OVERRIDE ? path.resolve(TRUSTED_KEYS_OVERRIDE) : null;
+// orbit-release-key-4 is a PLACEHOLDER pre-staged for the next rotation. The
+// PEM below was generated locally and the matching private key is NOT held by
+// release infrastructure — no production signature will ever verify against
+// it. Replace with a real keypair (generated on the signing host) before
+// rotating off key-3.
+const TRUSTED_RELEASE_KEYS = Object.freeze([
+  Object.freeze({
+    id: 'orbit-release-key-3',
+    notAfter: '2029-12-31',
+    revokedAt: null,
+    publicKeyPem: `-----BEGIN PUBLIC KEY-----
+MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAoQGLKOvvsvXriGIQ0oxA
+PcDyVHLM1iqXBCYXg+blQU41haEkG1eYabvDfeGcyGaC4awW7Q2uCZK05+/Hdjpe
+cRUVxP+QWKCAHyretQwOsoXzutZjJgId/ZRiUJPS/FeJOSv0xrayaol0tmfeJ4mH
+gFseCLq+mIIWIPRvXmYiKaUB//bjF79w/m4VXlyBhfi6n+f6x2UPG+gjjsjwG6mn
+Orec31AAFCIIX69YAd21D3MBc4S89/LoYZCq3neDscZ09Y+e6Jg2HpoBstvqSnq/
+3s34unLuIRlyB8jyK8CrdzT1E6YVB7+riAjycE9XMlLOQ2xA4tl6CKIx5YTKHyeW
+npMLlbzNaVfFT7p3IPTxsoEI0SB3ZtO7/XhzuOvOpklYcqjW2DGw/yzr2epAqHE/
+y4rLO3hkxWhxfgF5KPSR2iftc3LMONRGWELK6jpD5KB7No5vwIvjpVPUc5xA45Xw
+tT/bo0mm4TvrumxYr1xyEHrdum+ej/WYz/0BZQlwDOtXAgMBAAE=
+-----END PUBLIC KEY-----
+`,
+  }),
+  Object.freeze({
+    id: 'orbit-release-key-4',
+    notAfter: '2030-12-31',
+    revokedAt: null,
+    publicKeyPem: `-----BEGIN PUBLIC KEY-----
+MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAiEVVbwQYDnbPg86xYrI8
+Ddm6qpkEJ6GSJOW9NfR/eLpqwwaeWb3EPR9H/U39Rrt8ABPAGObLG9vuvSzg8YqU
+Rz6NjtrSKQ4k9xO/up+qQ/zRsHkOyISEx+6MnIrw5hY/IfkrZ+3+jm8IfXJ+VAjS
+VepR+o58u73ycrnLG1eXWIHtjED3SQSPffJjxSvVDEb3ogiJAsWClCMWNLnEjsQc
+IHYrNdS5N0m5tfcIb9LiV2cDVXgdwdRUU41Ks9sWvBQIHrNup721UWyMdJoK1hTI
+rc4PST3WTHQwFcQvVaAqod9MDPkQYlgD7IjiPkSGLHyIs52kNgFXY55E5DlU4O4e
+9QDbyQTGzZI0XlnoqAuCIXbcNXjMZuEn9UjVN35NeObsj6F/yL07YUhvORnxozjL
+41ouRFtFTWFHNenthtZnH9SUV4+O2cKDmtJpPJd68ZJ/NBqJHM4a6cteT72HJzLb
+t6yto3B43nTeXtp9ozRjetznPnPD7gmI6Zq1P2ce8v49AgMBAAE=
+-----END PUBLIC KEY-----
+`,
+  }),
+]);
+let publicKeyOverrideLogged = false;
+let trustedKeysOverrideLogged = false;
 
 function log(msg) {
   process.stderr.write(`@orbit-tools/cli: ${msg}\n`);
@@ -78,13 +133,215 @@ function parseChecksums(text) {
   return out;
 }
 
-function extractTarGz(archivePath, destDir) {
-  const result = spawnSync('tar', ['-xzf', archivePath, '-C', destDir], { stdio: 'inherit' });
+function acknowledgeTrustedPublicKeyOverride() {
+  if (PUBLIC_KEY_OVERRIDE && TRUSTED_KEYS_OVERRIDE) {
+    throw new Error('ORBIT_RELEASE_PUBLIC_KEY_FILE and ORBIT_RELEASE_TRUSTED_KEYS_FILE cannot both be set');
+  }
+  if (!PUBLIC_KEY_OVERRIDE) {
+    return;
+  }
+  if (process.env[PUBLIC_KEY_OVERRIDE_ACK_ENV] !== '1') {
+    throw new Error(`ORBIT_RELEASE_PUBLIC_KEY_FILE requires ${PUBLIC_KEY_OVERRIDE_ACK_ENV}=1`);
+  }
+  if (!publicKeyOverrideLogged) {
+    log(`ORBIT_RELEASE_PUBLIC_KEY_FILE=${TRUSTED_PUBLIC_KEY_PATH} set; trusting replacement release signing key`);
+    log('ORBIT_RELEASE_PUBLIC_KEY_FILE is deprecated; prefer ORBIT_RELEASE_TRUSTED_KEYS_FILE for the full trust set (key IDs, notAfter, revokedAt)');
+    publicKeyOverrideLogged = true;
+  }
+}
+
+function acknowledgeTrustedKeysOverride() {
+  if (PUBLIC_KEY_OVERRIDE && TRUSTED_KEYS_OVERRIDE) {
+    throw new Error('ORBIT_RELEASE_PUBLIC_KEY_FILE and ORBIT_RELEASE_TRUSTED_KEYS_FILE cannot both be set');
+  }
+  if (!TRUSTED_KEYS_OVERRIDE) {
+    return;
+  }
+  if (process.env[TRUSTED_KEYS_OVERRIDE_ACK_ENV] !== '1') {
+    throw new Error(`ORBIT_RELEASE_TRUSTED_KEYS_FILE requires ${TRUSTED_KEYS_OVERRIDE_ACK_ENV}=1`);
+  }
+  if (!trustedKeysOverrideLogged) {
+    log(`ORBIT_RELEASE_TRUSTED_KEYS_FILE=${TRUSTED_KEYS_OVERRIDE_PATH} set; trusting replacement release signing key set`);
+    trustedKeysOverrideLogged = true;
+  }
+}
+
+function readTrustedKeysManifest(manifestPath) {
+  const manifestDir = path.dirname(manifestPath);
+  return fs
+    .readFileSync(manifestPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+    .map((line) => {
+      const [id, notAfter, revokedAt, publicKeyPath, ...extra] = line.split('|');
+      if (!id || !publicKeyPath || extra.length > 0) {
+        throw new Error(`invalid trusted release signing key record: ${line}`);
+      }
+      const resolvedPublicKeyPath = path.isAbsolute(publicKeyPath)
+        ? publicKeyPath
+        : path.resolve(manifestDir, publicKeyPath);
+      return {
+        id,
+        notAfter: notAfter || null,
+        revokedAt: revokedAt || null,
+        publicKeyPem: fs.readFileSync(resolvedPublicKeyPath, 'utf8'),
+      };
+    });
+}
+
+function normalizeTrustedReleaseKeys(trustedKeys) {
+  if (typeof trustedKeys === 'string') {
+    return [
+      {
+        id: 'override',
+        notAfter: null,
+        revokedAt: null,
+        publicKeyPem: trustedKeys,
+      },
+    ];
+  }
+
+  if (!Array.isArray(trustedKeys) || trustedKeys.length === 0) {
+    throw new Error('at least one trusted release signing key is required');
+  }
+
+  return trustedKeys.map((key) => {
+    if (!key || !key.id || !key.publicKeyPem) {
+      throw new Error('trusted release signing keys require id and publicKeyPem');
+    }
+    const notAfter = key.notAfter || null;
+    const revokedAt = key.revokedAt || null;
+    // Mirror the shell-side awk regex (release_date_number) so a malformed
+    // override like notAfter: "next month" fails closed instead of silently
+    // becoming "never expires" under lexicographic comparison.
+    if (notAfter !== null && !/^\d{4}-\d{2}-\d{2}$/.test(notAfter)) {
+      throw new Error(`trusted release signing key ${key.id} has invalid notAfter: ${notAfter} (expected YYYY-MM-DD)`);
+    }
+    if (revokedAt !== null && !/^\d{4}-\d{2}-\d{2}$/.test(revokedAt)) {
+      throw new Error(`trusted release signing key ${key.id} has invalid revokedAt: ${revokedAt} (expected YYYY-MM-DD)`);
+    }
+    return {
+      id: key.id,
+      notAfter,
+      revokedAt,
+      publicKeyPem: key.publicKeyPem,
+    };
+  });
+}
+
+function readTrustedReleaseKeys() {
+  acknowledgeTrustedPublicKeyOverride();
+  acknowledgeTrustedKeysOverride();
+
+  if (PUBLIC_KEY_OVERRIDE) {
+    return normalizeTrustedReleaseKeys(fs.readFileSync(TRUSTED_PUBLIC_KEY_PATH, 'utf8'));
+  }
+  if (TRUSTED_KEYS_OVERRIDE_PATH) {
+    return normalizeTrustedReleaseKeys(readTrustedKeysManifest(TRUSTED_KEYS_OVERRIDE_PATH));
+  }
+  return TRUSTED_RELEASE_KEYS;
+}
+
+function releaseDateString(date = new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+
+function assertTrustedKeyUsable(key, verificationDate = new Date()) {
+  if (key.revokedAt) {
+    throw new Error(`release checksum signature was made by revoked release signing key ${key.id} (revoked ${key.revokedAt})`);
+  }
+  if (key.notAfter && releaseDateString(verificationDate) > key.notAfter) {
+    throw new Error(`release checksum signature was made by expired release signing key ${key.id} (not_after ${key.notAfter})`);
+  }
+}
+
+function verifyWithPublicKey(checksumText, signatureBuf, publicKeyPem) {
+  const verifier = crypto.createVerify('RSA-SHA256');
+  verifier.update(checksumText, 'utf8');
+  verifier.end();
+  return verifier.verify(publicKeyPem, signatureBuf);
+}
+
+function verifyChecksumSignature(
+  checksumText,
+  signatureBuf,
+  trustedKeys = readTrustedReleaseKeys(),
+  verificationDate = new Date()
+) {
+  for (const key of normalizeTrustedReleaseKeys(trustedKeys)) {
+    if (verifyWithPublicKey(checksumText, signatureBuf, key.publicKeyPem)) {
+      assertTrustedKeyUsable(key, verificationDate);
+      log(`authenticated ${CHECKSUM_FILE} with release signing key ${key.id}`);
+      return key.id;
+    }
+  }
+  throw new Error(`release checksum signature verification failed for ${CHECKSUM_FILE}: no trusted release signing key matched`);
+}
+
+function verifyArchiveChecksum(asset, archiveBuf, checksumText) {
+  const checksums = parseChecksums(checksumText);
+  const expected = checksums[asset];
+  if (!expected) {
+    throw new Error(`checksum entry for ${asset} was not found in ${CHECKSUM_FILE}`);
+  }
+  const actual = sha256(archiveBuf);
+  if (actual !== expected) {
+    throw new Error(`checksum mismatch for ${asset}: expected ${expected}, got ${actual}`);
+  }
+}
+
+function runTar(args, options = {}) {
+  const result = spawnSync('tar', args, { encoding: 'utf8', ...options });
+  if (result.error) {
+    throw result.error;
+  }
   if (result.status !== 0) {
-    fail(`tar extraction failed (status ${result.status}). Is 'tar' installed?`);
+    const stderr = result.stderr ? `: ${result.stderr.trim()}` : '';
+    throw new Error(`tar ${args.join(' ')} failed (status ${result.status})${stderr}`);
+  }
+  return result.stdout || '';
+}
+
+function validateArchiveMemberName(member) {
+  if (member === 'orbit') {
+    return;
+  }
+  if (!member || member.startsWith('/') || member.includes('..') || path.isAbsolute(member)) {
+    throw new Error(`unsafe release archive member: ${member || '<empty>'}`);
+  }
+  throw new Error(`unexpected release archive member: ${member}`);
+}
+
+function validateArchiveMembers(archivePath) {
+  const members = runTar(['-tzf', archivePath])
+    .split(/\r?\n/)
+    .filter((line) => line.length > 0);
+  if (members.length !== 1) {
+    throw new Error("release archive must contain only the 'orbit' binary");
+  }
+  validateArchiveMemberName(members[0]);
+}
+
+function validateExtractedBinary(extractedBinary) {
+  const stat = fs.lstatSync(extractedBinary);
+  if (stat.isSymbolicLink()) {
+    throw new Error('release archive member is a symlink: orbit');
+  }
+  if (!stat.isFile()) {
+    throw new Error('release archive member must be a regular file: orbit');
+  }
+  if (stat.nlink !== 1) {
+    throw new Error('release archive member must not be a hard link: orbit');
   }
 }
 
+function extractTarGz(archivePath, destDir) {
+  validateArchiveMembers(archivePath);
+  runTar(['-xzf', archivePath, '-C', destDir, 'orbit'], { stdio: 'inherit' });
+  validateExtractedBinary(path.join(destDir, 'orbit'));
+}
+
 async function main() {
   if (process.env.ORBIT_SKIP_DOWNLOAD === '1') {
     log('ORBIT_SKIP_DOWNLOAD=1 set; skipping binary download.');
@@ -99,12 +356,23 @@ async function main() {
   const asset = `orbit-${target}.tar.gz`;
   const baseUrl = `https://github.com/${BINARY_REPO}/releases/download/${BINARY_VERSION}`;
   const archiveUrl = `${baseUrl}/${asset}`;
-  const checksumUrl = `${baseUrl}/orbit-checksums.txt`;
+  const checksumUrl = `${baseUrl}/${CHECKSUM_FILE}`;
+  const checksumSignatureUrl = `${baseUrl}/${CHECKSUM_SIGNATURE_FILE}`;
 
   log(`installing orbit ${BINARY_VERSION} for ${target}...`);
 
   fs.mkdirSync(BIN_DIR, { recursive: true });
 
+  let checksumText;
+  let signatureBuf;
+  try {
+    checksumText = (await fetchBuffer(checksumUrl)).toString('utf8');
+    signatureBuf = await fetchBuffer(checksumSignatureUrl);
+    verifyChecksumSignature(checksumText, signatureBuf);
+  } catch (err) {
+    fail(`could not authenticate ${CHECKSUM_FILE}: ${err.message}`);
+  }
+
   let archiveBuf;
   try {
     archiveBuf = await fetchBuffer(archiveUrl);
@@ -113,35 +381,45 @@ async function main() {
   }
 
   try {
-    const checksumText = (await fetchBuffer(checksumUrl)).toString('utf8');
-    const checksums = parseChecksums(checksumText);
-    const expected = checksums[asset];
-    if (!expected) {
-      fail(`checksum entry for ${asset} was not found in orbit-checksums.txt`);
-    } else {
-      const actual = sha256(archiveBuf);
-      if (actual !== expected) {
-        fail(`checksum mismatch for ${asset}: expected ${expected}, got ${actual}`);
-      }
-    }
+    verifyArchiveChecksum(asset, archiveBuf, checksumText);
   } catch (err) {
-    fail(`could not verify checksum for ${asset}: ${err.message}`);
+    fail(err.message);
   }
 
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'orbit-cli-'));
-  const archivePath = path.join(tmpDir, asset);
-  fs.writeFileSync(archivePath, archiveBuf);
-  extractTarGz(archivePath, tmpDir);
+  try {
+    const archivePath = path.join(tmpDir, asset);
+    fs.writeFileSync(archivePath, archiveBuf);
+    extractTarGz(archivePath, tmpDir);
 
-  const extractedBinary = path.join(tmpDir, 'orbit');
-  if (!fs.existsSync(extractedBinary)) {
-    fail(`extracted archive did not contain 'orbit' binary at ${extractedBinary}`);
+    const extractedBinary = path.join(tmpDir, 'orbit');
+    if (!fs.existsSync(extractedBinary)) {
+      fail(`extracted archive did not contain 'orbit' binary at ${extractedBinary}`);
+    }
+    fs.copyFileSync(extractedBinary, BIN_PATH);
+    fs.chmodSync(BIN_PATH, 0o755);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
   }
-  fs.copyFileSync(extractedBinary, BIN_PATH);
-  fs.chmodSync(BIN_PATH, 0o755);
-  fs.rmSync(tmpDir, { recursive: true, force: true });
 
   log(`installed orbit binary at ${BIN_PATH}`);
 }
 
-main().catch((err) => fail(err && err.message ? err.message : String(err)));
+if (require.main === module) {
+  main().catch((err) => fail(err && err.message ? err.message : String(err)));
+}
+
+module.exports = {
+  TRUSTED_RELEASE_KEYS,
+  parseChecksums,
+  sha256,
+  acknowledgeTrustedPublicKeyOverride,
+  acknowledgeTrustedKeysOverride,
+  extractTarGz,
+  normalizeTrustedReleaseKeys,
+  readTrustedReleaseKeys,
+  validateArchiveMembers,
+  validateExtractedBinary,
+  verifyArchiveChecksum,
+  verifyChecksumSignature,
+};