@wathba-cli/cli 1.3.5

package/README.md

@@ -0,0 +1,27 @@
+# `@wathba-cli/cli`
+
+The official npm distribution of the Wathba CLI.
+
+```sh
+npm install --global @wathba-cli/cli
+wathba version --json
+```
+
+The package contains no npm dependencies. During installation it selects the
+matching native Wathba release for macOS, Linux, or Windows on x64 or ARM64,
+authenticates Wathba's signed release metadata, verifies the archive digest,
+and runs the staged CLI's independent release verifier before installing it.
+
+The native installer remains available from `https://install.wathba.info`.
+An npm-managed installation must be updated through npm:
+
+```sh
+npm install --global @wathba-cli/cli@latest
+```
+
+Install the embedded operator skills explicitly when an agent host needs them:
+
+```sh
+wathba skill agent install --json --no-input
+wathba skill bootstrap install --json --no-input
+```

package/bin/wathba.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+const { ensureInstalled } = require('../lib/install');
+const { exitLikeChild, launch } = require('../lib/launcher');
+
+ensureInstalled()
+  .then(({ binary }) => exitLikeChild(launch(binary, process.argv.slice(2))))
+  .catch((error) => {
+    console.error(`wathba: ${error.message}`);
+    process.exitCode = 1;
+  });

package/install.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+'use strict';
+
+const { ensureInstalled, InstallError } = require('./lib/install');
+
+ensureInstalled()
+  .then(({ binary, installed }) => {
+    if (installed) console.error(`Wathba CLI installed at ${binary}`);
+  })
+  .catch((error) => {
+    if (error instanceof InstallError && error.transient) {
+      console.error(`Wathba CLI download was deferred: ${error.message}`);
+      console.error('The wathba command will retry on first use.');
+      return;
+    }
+    console.error(`Wathba CLI installation failed: ${error.message}`);
+    process.exitCode = 1;
+  });

package/lib/install.js

@@ -0,0 +1,589 @@
+'use strict';
+
+const childProcess = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const { artifactFiles, selectPlatform } = require('./platform');
+
+const RELEASE_CONFIG_SCHEMA = 'wathba.npm.release-config.v1';
+const RELEASE_ROOT_SCHEMA = 'wathba.cli.distribution-root.v1';
+const SIGNED_ENVELOPE_SCHEMA = 'wathba.distribution.signed-envelope.v1';
+const LATEST_SCHEMA = 'wathba.distribution.latest.v1';
+const MANIFEST_SCHEMA = 'wathba.distribution.manifest.v1';
+const REVOCATIONS_SCHEMA = 'wathba.distribution.revocations.v1';
+const INSTALL_STATE_SCHEMA = 'wathba.npm.install-state.v1';
+const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+const NO_CACHE_CONTROL = 'no-cache';
+const MAX_METADATA_BYTES = 4 * 1024 * 1024;
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const MAX_SIGNATURE_BYTES = 16 * 1024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_REDIRECTS = 5;
+const MAX_SIGNED_INTEGER = 9223372036854775807n;
+
+class InstallError extends Error {
+  constructor(message, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'InstallError';
+    this.transient = options.transient === true;
+  }
+}
+
+function exactKeys(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new InstallError(`${label} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new InstallError(`${label} has unsupported fields`);
+  }
+}
+
+function parseJSON(buffer, label) {
+  try {
+    return JSON.parse(Buffer.isBuffer(buffer) ? buffer.toString('utf8') : buffer);
+  } catch (error) {
+    throw new InstallError(`${label} is not valid JSON`, { cause: error });
+  }
+}
+
+function decodeBase64(value, label, urlSafe = false) {
+  if (typeof value !== 'string' || value === '') throw new InstallError(`${label} is empty`);
+  const pattern = urlSafe ? /^[A-Za-z0-9_-]+$/ : /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+  if (!pattern.test(value)) throw new InstallError(`${label} is not valid base64`);
+  const encoding = urlSafe ? 'base64url' : 'base64';
+  const decoded = Buffer.from(value, encoding);
+  if (decoded.toString(encoding) !== value) throw new InstallError(`${label} is not canonical base64`);
+  return decoded;
+}
+
+function decodeRootTrust(encoded) {
+  const payload = decodeBase64(encoded, 'distribution root trust', true);
+  if (payload.length > 32 * 1024) throw new InstallError('distribution root trust is too large');
+  const document = parseJSON(payload, 'distribution root trust');
+  exactKeys(document, ['schemaVersion', 'keyId', 'publicKeySpki'], 'distribution root trust');
+  if (document.schemaVersion !== RELEASE_ROOT_SCHEMA || !/^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/.test(document.keyId)) {
+    throw new InstallError('distribution root trust schema or key id is invalid');
+  }
+  const spki = decodeBase64(document.publicKeySpki, 'distribution root public key', true);
+  let publicKey;
+  try {
+    publicKey = crypto.createPublicKey({ key: spki, format: 'der', type: 'spki' });
+  } catch (error) {
+    throw new InstallError('distribution root public key is invalid', { cause: error });
+  }
+  const details = publicKey.asymmetricKeyDetails || {};
+  if (publicKey.asymmetricKeyType !== 'rsa' || details.modulusLength < 3072 || details.publicExponent !== 65537n) {
+    throw new InstallError('distribution root must be RSA-3072 or stronger with exponent 65537');
+  }
+  return { keyId: document.keyId, publicKey };
+}
+
+function verifyDetached(payload, signature, trust) {
+  if (!Buffer.isBuffer(signature) || signature.length === 0 || signature.length > MAX_SIGNATURE_BYTES) {
+    throw new InstallError('distribution signature has an invalid size');
+  }
+  const valid = crypto.verify('sha256', payload, {
+    key: trust.publicKey,
+    padding: crypto.constants.RSA_PKCS1_PADDING,
+  }, signature);
+  if (!valid) throw new InstallError('distribution signature verification failed');
+}
+
+function openSignedEnvelope(encoded, trust) {
+  const envelope = parseJSON(encoded, 'latest signed envelope');
+  exactKeys(envelope, ['schema_version', 'payload_base64', 'signature_base64'], 'latest signed envelope');
+  if (envelope.schema_version !== SIGNED_ENVELOPE_SCHEMA) {
+    throw new InstallError('latest signed envelope schema is incompatible');
+  }
+  const payload = decodeBase64(envelope.payload_base64, 'latest envelope payload');
+  const signature = decodeBase64(envelope.signature_base64, 'latest envelope signature');
+  verifyDetached(payload, signature, trust);
+  return payload;
+}
+
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+function canonicalVersion(packageVersion) {
+  const version = `v${packageVersion}`;
+  if (!isCanonicalVersion(version)) throw new InstallError(`npm package version ${packageVersion} is not a canonical Wathba release`);
+  return version;
+}
+
+function isCanonicalVersion(version) {
+  const match = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(version);
+  if (!match) return false;
+  if (match.slice(1, 4).some((part) => BigInt(part) > MAX_SIGNED_INTEGER)) return false;
+  if (!match[4]) return true;
+  return match[4].split('.').every((part) => !/^0[0-9]+$/.test(part));
+}
+
+function compareVersions(left, right) {
+  if (!isCanonicalVersion(left) || !isCanonicalVersion(right)) throw new InstallError('cannot compare invalid release versions');
+  const parse = (version) => {
+    const raw = version.slice(1);
+    const separator = raw.indexOf('-');
+    const core = separator === -1 ? raw : raw.slice(0, separator);
+    const prerelease = separator === -1 ? '' : raw.slice(separator + 1);
+    return { core: core.split('.').map(BigInt), prerelease: prerelease ? prerelease.split('.') : [] };
+  };
+  const leftVersion = parse(left);
+  const rightVersion = parse(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftVersion.core[index] !== rightVersion.core[index]) return leftVersion.core[index] < rightVersion.core[index] ? -1 : 1;
+  }
+  if (leftVersion.prerelease.length === 0 || rightVersion.prerelease.length === 0) {
+    return leftVersion.prerelease.length === rightVersion.prerelease.length ? 0 : leftVersion.prerelease.length === 0 ? 1 : -1;
+  }
+  const length = Math.min(leftVersion.prerelease.length, rightVersion.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = leftVersion.prerelease[index];
+    const rightPart = rightVersion.prerelease[index];
+    if (leftPart === rightPart) continue;
+    const leftNumeric = /^[0-9]+$/.test(leftPart) && BigInt(leftPart) <= MAX_SIGNED_INTEGER;
+    const rightNumeric = /^[0-9]+$/.test(rightPart) && BigInt(rightPart) <= MAX_SIGNED_INTEGER;
+    if (leftNumeric && rightNumeric) return BigInt(leftPart) < BigInt(rightPart) ? -1 : 1;
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftPart < rightPart ? -1 : 1;
+  }
+  return leftVersion.prerelease.length === rightVersion.prerelease.length ? 0 : leftVersion.prerelease.length < rightVersion.prerelease.length ? -1 : 1;
+}
+
+function isRFC3339(value) {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/.exec(value);
+  if (!match) return false;
+  const [, year, month, day, hour, minute, second, , zoneHour = '0', zoneMinute = '0'] = match;
+  const numeric = [year, month, day, hour, minute, second, zoneHour, zoneMinute].map(Number);
+  const leapYear = numeric[0] % 4 === 0 && (numeric[0] % 100 !== 0 || numeric[0] % 400 === 0);
+  const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][numeric[1] - 1];
+  return numeric[1] >= 1 && numeric[1] <= 12 && numeric[2] >= 1 && numeric[2] <= daysInMonth
+    && numeric[3] <= 23 && numeric[4] <= 59 && numeric[5] <= 59 && numeric[6] <= 23 && numeric[7] <= 59;
+}
+
+function requireSHA(value, label) {
+  if (typeof value !== 'string' || !/^[a-f0-9]{64}$/i.test(value)) throw new InstallError(`${label} has an invalid SHA-256`);
+  return value.toLowerCase();
+}
+
+function positiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new InstallError(`${label} must be a positive integer`);
+  return value;
+}
+
+function parseChannel(value, label) {
+  exactKeys(value, ['version', 'sequence', 'released_at', 'manifest_sha256', 'checksums_sha256', 'revocations_sha256'], label);
+  if (!isCanonicalVersion(value.version) || !isRFC3339(value.released_at)) throw new InstallError(`${label} is invalid`);
+  return {
+    version: value.version,
+    sequence: positiveInteger(value.sequence, `${label} sequence`),
+    manifestSHA256: requireSHA(value.manifest_sha256, `${label} manifest`),
+    checksumsSHA256: requireSHA(value.checksums_sha256, `${label} checksums`),
+    revocationsSHA256: requireSHA(value.revocations_sha256, `${label} revocations`),
+  };
+}
+
+function parseLatest(payload) {
+  const value = parseJSON(payload, 'latest metadata');
+  const allowed = ['schema_version', 'sequence', 'revocations_version', 'revocations_sha256', 'stable', 'beta', 'rollback'];
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new InstallError('latest metadata must be an object');
+  const keys = Object.keys(value);
+  if (keys.some((key) => !allowed.includes(key)) || !['schema_version', 'sequence', 'revocations_version', 'revocations_sha256', 'stable'].every((key) => keys.includes(key))) {
+    throw new InstallError('latest metadata has unsupported or missing fields');
+  }
+  if (value.schema_version !== LATEST_SCHEMA || !isCanonicalVersion(value.revocations_version)) throw new InstallError('latest metadata schema is invalid');
+  const latest = {
+    sequence: positiveInteger(value.sequence, 'latest sequence'),
+    revocationsVersion: value.revocations_version,
+    revocationsSHA256: requireSHA(value.revocations_sha256, 'latest revocations'),
+    stable: parseChannel(value.stable, 'stable channel'),
+    beta: value.beta === undefined || value.beta === null ? null : parseChannel(value.beta, 'beta channel'),
+    rollback: null,
+  };
+  if (latest.stable.sequence > latest.sequence || latest.beta && latest.beta.sequence > latest.sequence) {
+    throw new InstallError('release channel sequence exceeds latest sequence');
+  }
+  if (value.rollback !== undefined && value.rollback !== null) {
+    exactKeys(value.rollback, ['from_version', 'to_version', 'sequence'], 'latest rollback authorization');
+    const rollback = {
+      fromVersion: value.rollback.from_version,
+      toVersion: value.rollback.to_version,
+      sequence: positiveInteger(value.rollback.sequence, 'latest rollback sequence'),
+    };
+    if (!isCanonicalVersion(rollback.fromVersion) || !isCanonicalVersion(rollback.toVersion)
+      || compareVersions(rollback.toVersion, rollback.fromVersion) >= 0
+      || rollback.sequence !== latest.sequence || rollback.toVersion !== latest.stable.version) {
+      throw new InstallError('latest rollback authorization is invalid');
+    }
+    latest.rollback = rollback;
+  }
+  return latest;
+}
+
+function parseRevocations(payload) {
+  const value = parseJSON(payload, 'revocations metadata');
+  exactKeys(value, ['schema_version', 'sequence', 'issued_at', 'blocked_versions'], 'revocations metadata');
+  if (value.schema_version !== REVOCATIONS_SCHEMA || !isRFC3339(value.issued_at) || !Array.isArray(value.blocked_versions)) {
+    throw new InstallError('revocations metadata is invalid');
+  }
+  const seen = new Set();
+  for (const version of value.blocked_versions) {
+    if (!isCanonicalVersion(version) || seen.has(version)) throw new InstallError('revocations metadata contains an invalid or duplicate version');
+    seen.add(version);
+  }
+  return { sequence: positiveInteger(value.sequence, 'revocations sequence'), blockedVersions: [...seen] };
+}
+
+function parseManifest(payload) {
+  const value = parseJSON(payload, 'release manifest');
+  exactKeys(value, ['schema_version', 'version', 'sequence', 'source_commit', 'checksums_sha256', 'artifacts'], 'release manifest');
+  if (value.schema_version !== MANIFEST_SCHEMA || !isCanonicalVersion(value.version) || !/^[a-f0-9]{40}$/i.test(value.source_commit)) {
+    throw new InstallError('release manifest identity is invalid');
+  }
+  requireSHA(value.checksums_sha256, 'release manifest checksums');
+  exactKeys(value.artifacts, Object.keys(artifactFiles), 'release manifest artifacts');
+  const artifacts = {};
+  for (const [key, expectedFile] of Object.entries(artifactFiles)) {
+    const artifact = value.artifacts[key];
+    exactKeys(artifact, ['file', 'sha256'], `release artifact ${key}`);
+    if (artifact.file !== expectedFile) throw new InstallError(`release artifact ${key} has an unexpected filename`);
+    artifacts[key] = { file: artifact.file, sha256: requireSHA(artifact.sha256, `release artifact ${key}`) };
+  }
+  return {
+    version: value.version,
+    sequence: positiveInteger(value.sequence, 'release manifest sequence'),
+    sourceCommit: value.source_commit.toLowerCase(),
+    artifacts,
+  };
+}
+
+function validateCacheControl(headers, expected, label) {
+  const actual = headers && typeof headers.get === 'function' ? headers.get('cache-control') : headers['cache-control'];
+  if (actual !== expected) throw new InstallError(`${label} has unexpected cache-control ${JSON.stringify(actual)}`);
+}
+
+function requestBuffer(url, options = {}, redirectCount = 0) {
+  const maxBytes = options.maxBytes || MAX_METADATA_BYTES;
+  const timeout = options.timeout || DEFAULT_TIMEOUT_MS;
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:' && !(options.allowHTTP === true && parsed.protocol === 'http:')) {
+    return Promise.reject(new InstallError(`refusing insecure download URL ${url}`));
+  }
+  const transport = parsed.protocol === 'https:' ? https : http;
+  return new Promise((resolve, reject) => {
+    const request = transport.get(parsed, {
+      headers: { 'User-Agent': '@wathba-cli/cli', Accept: 'application/octet-stream, application/json' },
+    }, (response) => {
+      const status = response.statusCode || 0;
+      if ([301, 302, 303, 307, 308].includes(status)) {
+        response.resume();
+        if (!response.headers.location || redirectCount >= MAX_REDIRECTS) {
+          reject(new InstallError('download exceeded the redirect limit'));
+          return;
+        }
+        const redirected = new URL(response.headers.location, parsed);
+        if (parsed.protocol === 'https:' && redirected.protocol !== 'https:') {
+          reject(new InstallError('refusing an HTTPS download redirect to an insecure URL'));
+          return;
+        }
+        requestBuffer(redirected.href, options, redirectCount + 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) {
+        response.resume();
+        reject(new InstallError(`GET ${parsed.href} failed with HTTP ${status}`, { transient: status === 408 || status === 429 || status >= 500 }));
+        return;
+      }
+      const chunks = [];
+      let size = 0;
+      response.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+          response.destroy(new InstallError(`GET ${parsed.href} exceeded ${maxBytes} bytes`));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.once('end', () => resolve({ body: Buffer.concat(chunks), headers: response.headers }));
+      response.once('error', (error) => reject(error instanceof InstallError ? error : new InstallError(`GET ${parsed.href} failed`, { cause: error, transient: true })));
+    });
+    request.setTimeout(timeout, () => request.destroy(new InstallError(`GET ${parsed.href} timed out`, { transient: true })));
+    request.once('error', (error) => reject(error instanceof InstallError ? error : new InstallError(`GET ${parsed.href} failed`, { cause: error, transient: true })));
+  });
+}
+
+async function retry(task, attempts = 3) {
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await task(attempt);
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof InstallError && error.transient) || attempt === attempts) throw error;
+      await new Promise((resolve) => setTimeout(resolve, attempt * 200));
+    }
+  }
+  throw lastError;
+}
+
+async function fetchSignedPair(payloadURL, signatureURL, trust, options) {
+  let verificationError;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    const suffix = attempt === 1 ? '' : `${payloadURL.includes('?') ? '&' : '?'}wathba_pair_retry=${attempt}-${Date.now()}`;
+    const signatureSuffix = attempt === 1 ? '' : `${signatureURL.includes('?') ? '&' : '?'}wathba_pair_retry=${attempt}-${Date.now()}`;
+    const payload = await retry(() => requestBuffer(payloadURL + suffix, { ...options, maxBytes: MAX_METADATA_BYTES }));
+    const signature = await retry(() => requestBuffer(signatureURL + signatureSuffix, { ...options, maxBytes: MAX_SIGNATURE_BYTES }));
+    validateCacheControl(payload.headers, IMMUTABLE_CACHE_CONTROL, 'signed metadata');
+    validateCacheControl(signature.headers, IMMUTABLE_CACHE_CONTROL, 'metadata signature');
+    try {
+      verifyDetached(payload.body, signature.body, trust);
+      return payload.body;
+    } catch (error) {
+      verificationError = error;
+    }
+  }
+  throw new InstallError(`signed metadata pair remained inconsistent: ${verificationError.message}`);
+}
+
+async function resolveArtifact(options) {
+  const baseURL = options.baseURL.replace(/\/+$/, '');
+  const version = options.version;
+  const platform = options.platform || selectPlatform();
+  const trust = decodeRootTrust(options.rootBase64);
+  const requestOptions = { allowHTTP: options.allowHTTP === true, timeout: options.timeout };
+
+  const envelope = await retry(() => requestBuffer(`${baseURL}/latest.signed.json`, { ...requestOptions, maxBytes: MAX_METADATA_BYTES }));
+  validateCacheControl(envelope.headers, NO_CACHE_CONTROL, 'latest signed envelope');
+  const latestPayload = openSignedEnvelope(envelope.body, trust);
+  const latest = parseLatest(latestPayload);
+
+  const revocationsPath = `${baseURL}/releases/${latest.revocationsVersion}/revocations.json`;
+  const revocationsPayload = await fetchSignedPair(revocationsPath, `${revocationsPath}.sig`, trust, requestOptions);
+  if (sha256(revocationsPayload) !== latest.revocationsSHA256) throw new InstallError('signed revocations do not match authenticated latest metadata');
+  const revocations = parseRevocations(revocationsPayload);
+  if (revocations.sequence !== latest.sequence) throw new InstallError('revocations sequence does not match latest metadata');
+  if (revocations.blockedVersions.includes(version)) throw new InstallError(`Wathba release ${version} has been revoked`);
+
+  const manifestPath = `${baseURL}/releases/${version}/manifest.json`;
+  const manifestPayload = await fetchSignedPair(manifestPath, `${manifestPath}.sig`, trust, requestOptions);
+  const manifest = parseManifest(manifestPayload);
+  if (manifest.version !== version || manifest.sequence > latest.sequence) throw new InstallError('release manifest is outside the authenticated release sequence');
+  const channel = latest.stable.version === version ? latest.stable : latest.beta && latest.beta.version === version ? latest.beta : null;
+  if (channel && (channel.sequence !== manifest.sequence || channel.manifestSHA256 !== sha256(manifestPayload))) {
+    throw new InstallError('release manifest does not match its authenticated channel');
+  }
+
+  const artifact = manifest.artifacts[platform.key];
+  if (!artifact) throw new InstallError(`release manifest does not support ${platform.key}`);
+  const archive = await retry(() => requestBuffer(`${baseURL}/releases/${version}/${artifact.file}`, { ...requestOptions, maxBytes: MAX_ARCHIVE_BYTES }));
+  validateCacheControl(archive.headers, IMMUTABLE_CACHE_CONTROL, 'release archive');
+  if (sha256(archive.body) !== artifact.sha256) throw new InstallError('release archive SHA-256 verification failed');
+  return { archive: archive.body, artifact, latest, manifest, platform, trust };
+}
+
+function extractArchive(archivePath, destination, platform, spawnSync = childProcess.spawnSync) {
+  let result;
+  if (platform.windows) {
+    const command = [
+      '-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+      '-Command',
+      "Expand-Archive -LiteralPath $env:WATHBA_NPM_ARCHIVE -DestinationPath $env:WATHBA_NPM_EXTRACT -Force",
+    ];
+    result = spawnSync('powershell.exe', command, {
+      env: { ...process.env, WATHBA_NPM_ARCHIVE: archivePath, WATHBA_NPM_EXTRACT: destination },
+      encoding: 'utf8', windowsHide: true,
+    });
+  } else {
+    result = spawnSync('tar', ['-xzf', archivePath, '-C', destination], { encoding: 'utf8', windowsHide: true });
+  }
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.error && result.error.message || '').trim();
+    throw new InstallError(`could not extract the Wathba release archive${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+function verifyCandidate(binary, version, baseURL, spawnSync = childProcess.spawnSync) {
+  const result = spawnSync(binary, [
+    'self-update', '--verify-only', '--version', version,
+    '--install-base-url', baseURL, '--json', '--no-input',
+  ], {
+    env: { ...process.env, WATHBA_INSTALL_METHOD: 'npm' },
+    encoding: 'utf8', windowsHide: true, maxBuffer: MAX_METADATA_BYTES,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || result.error && result.error.message || '').trim();
+    throw new InstallError(`the staged Wathba CLI rejected its release provenance${detail ? `: ${detail}` : ''}`);
+  }
+  let envelope;
+  try {
+    envelope = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new InstallError('the staged Wathba CLI returned invalid verification output', { cause: error });
+  }
+  if (envelope.schema_version !== 'wathba.output.v1' || envelope.ok !== true || !envelope.data || envelope.data.verify_only !== true) {
+    throw new InstallError('the staged Wathba CLI did not confirm release verification');
+  }
+}
+
+function readRuntimeConfig(packageRoot) {
+  const config = parseJSON(fs.readFileSync(path.join(packageRoot, 'lib', 'release-config.json')), 'npm release configuration');
+  exactKeys(config, ['schemaVersion', 'installBaseUrl', 'distributionRootBase64'], 'npm release configuration');
+  if (config.schemaVersion !== RELEASE_CONFIG_SCHEMA || !config.installBaseUrl.startsWith('https://') || !config.distributionRootBase64) {
+    throw new InstallError('npm release configuration has not been prepared by the Wathba release workflow');
+  }
+  return config;
+}
+
+function packageVersion(packageRoot) {
+  const metadata = parseJSON(fs.readFileSync(path.join(packageRoot, 'package.json')), 'npm package metadata');
+  return metadata.version;
+}
+
+function binaryDigest(file) {
+  return sha256(fs.readFileSync(file));
+}
+
+function installedBinary(packageRoot, version, platform) {
+  const binary = path.join(packageRoot, 'binaries', platform.binary);
+  const statePath = path.join(packageRoot, 'binaries', 'install-state.json');
+  try {
+    const state = parseJSON(fs.readFileSync(statePath), 'npm install state');
+    exactKeys(state, ['schemaVersion', 'version', 'artifact', 'archiveSHA256', 'binarySHA256'], 'npm install state');
+    const binaryStat = fs.lstatSync(binary);
+    if (state.schemaVersion !== INSTALL_STATE_SCHEMA || state.version !== version
+      || state.artifact !== artifactFiles[platform.key] || !binaryStat.isFile() || binaryStat.isSymbolicLink()) return null;
+    requireSHA(state.archiveSHA256, 'npm install state archive');
+    const expectedBinarySHA256 = requireSHA(state.binarySHA256, 'npm install state binary');
+    if (binaryDigest(binary) !== expectedBinarySHA256) return null;
+    return binary;
+  } catch (_) {
+    return null;
+  }
+}
+
+async function acquireLock(lockPath, timeout = 30_000) {
+  const started = Date.now();
+  while (true) {
+    try {
+      return fs.openSync(lockPath, 'wx', 0o600);
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs > 5 * 60_000) fs.unlinkSync(lockPath);
+      } catch (_) {}
+      if (Date.now() - started > timeout) throw new InstallError('timed out waiting for another Wathba npm installation');
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+}
+
+function commitBinary(source, packageRoot, version, artifact) {
+  const binaryDir = path.join(packageRoot, 'binaries');
+  fs.mkdirSync(binaryDir, { recursive: true, mode: 0o755 });
+  const target = path.join(binaryDir, path.basename(source));
+  const temporary = path.join(binaryDir, `.${path.basename(source)}-${process.pid}-${Date.now()}.tmp`);
+  fs.copyFileSync(source, temporary, fs.constants.COPYFILE_EXCL);
+  if (process.platform !== 'win32') fs.chmodSync(temporary, 0o755);
+  // Windows requires a writable handle when fsync flushes the file buffer.
+  const handle = fs.openSync(temporary, 'r+');
+  try { fs.fsyncSync(handle); } finally { fs.closeSync(handle); }
+  try { fs.renameSync(temporary, target); } catch (error) {
+    if (!['EEXIST', 'EPERM'].includes(error.code)) throw error;
+    fs.rmSync(target, { force: true });
+    fs.renameSync(temporary, target);
+  }
+  const state = {
+    schemaVersion: INSTALL_STATE_SCHEMA,
+    version,
+    artifact: artifact.file,
+    archiveSHA256: artifact.sha256,
+    binarySHA256: binaryDigest(target),
+  };
+  const stateTemporary = path.join(binaryDir, `.install-state-${process.pid}-${Date.now()}.tmp`);
+  fs.writeFileSync(stateTemporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  fs.renameSync(stateTemporary, path.join(binaryDir, 'install-state.json'));
+  return target;
+}
+
+async function installRelease(options) {
+  const resolved = await resolveArtifact(options);
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'wathba-npm-'));
+  try {
+    const archivePath = path.join(temporary, resolved.artifact.file);
+    const extractPath = path.join(temporary, 'extract');
+    fs.mkdirSync(extractPath, { mode: 0o700 });
+    fs.writeFileSync(archivePath, resolved.archive, { mode: 0o600 });
+    (options.extractArchive || extractArchive)(archivePath, extractPath, resolved.platform, options.spawnSync);
+    const candidate = path.join(extractPath, resolved.platform.binary);
+    const stat = fs.lstatSync(candidate);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0) throw new InstallError('release archive does not contain the expected Wathba binary');
+    if (!resolved.platform.windows) fs.chmodSync(candidate, 0o755);
+    (options.verifyCandidate || verifyCandidate)(candidate, options.version, options.baseURL, options.spawnSync);
+    return commitBinary(candidate, options.packageRoot, options.version, resolved.artifact);
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+async function ensureInstalled(options = {}) {
+  const packageRoot = options.packageRoot || path.resolve(__dirname, '..');
+  const npmVersion = options.packageVersion || packageVersion(packageRoot);
+  const version = canonicalVersion(npmVersion);
+  const platform = options.platform || selectPlatform();
+  const existing = installedBinary(packageRoot, version, platform);
+  if (existing) return { binary: existing, installed: false, version };
+
+  const binaryDir = path.join(packageRoot, 'binaries');
+  fs.mkdirSync(binaryDir, { recursive: true, mode: 0o755 });
+  const lockPath = path.join(binaryDir, '.install.lock');
+  const lockHandle = await acquireLock(lockPath, options.lockTimeout);
+  try {
+    const afterLock = installedBinary(packageRoot, version, platform);
+    if (afterLock) return { binary: afterLock, installed: false, version };
+    const config = options.config || (options.baseURL && options.rootBase64
+      ? { installBaseUrl: options.baseURL, distributionRootBase64: options.rootBase64 }
+      : readRuntimeConfig(packageRoot));
+    const binary = await installRelease({
+      ...options,
+      packageRoot,
+      version,
+      platform,
+      baseURL: options.baseURL || config.installBaseUrl,
+      rootBase64: options.rootBase64 || config.distributionRootBase64,
+    });
+    return { binary, installed: true, version };
+  } finally {
+    try { fs.closeSync(lockHandle); } catch (_) {}
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+module.exports = {
+  IMMUTABLE_CACHE_CONTROL,
+  INSTALL_STATE_SCHEMA,
+  InstallError,
+  canonicalVersion,
+  compareVersions,
+  decodeRootTrust,
+  ensureInstalled,
+  extractArchive,
+  fetchSignedPair,
+  installedBinary,
+  isCanonicalVersion,
+  openSignedEnvelope,
+  parseLatest,
+  parseManifest,
+  parseRevocations,
+  requestBuffer,
+  resolveArtifact,
+  sha256,
+  verifyCandidate,
+  verifyDetached,
+};

package/lib/launcher.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+
+function launch(binary, args, options = {}) {
+  const spawnProcess = options.spawn || spawn;
+  const env = { ...(options.env || process.env), WATHBA_INSTALL_METHOD: 'npm' };
+  return spawnProcess(binary, args, { stdio: 'inherit', env, windowsHide: false });
+}
+
+function exitLikeChild(child) {
+  const forwarded = [];
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    if (process.platform === 'win32' && signal === 'SIGHUP') {
+      continue;
+    }
+    const handler = () => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    };
+    process.on(signal, handler);
+    forwarded.push([signal, handler]);
+  }
+
+  child.once('error', (error) => {
+    for (const [signal, handler] of forwarded) process.off(signal, handler);
+    console.error(`wathba: could not start the installed CLI: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.once('exit', (code, signal) => {
+    for (const [name, handler] of forwarded) process.off(name, handler);
+    if (signal && process.platform !== 'win32') {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = Number.isInteger(code) ? code : 1;
+  });
+}
+
+module.exports = { exitLikeChild, launch };

package/lib/platform.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const artifactFiles = Object.freeze({
+  darwin_arm64: 'wathba_Darwin_arm64.tar.gz',
+  darwin_x86_64: 'wathba_Darwin_x86_64.tar.gz',
+  linux_arm64: 'wathba_Linux_arm64.tar.gz',
+  linux_x86_64: 'wathba_Linux_x86_64.tar.gz',
+  windows_arm64: 'wathba_Windows_arm64.zip',
+  windows_x86_64: 'wathba_Windows_x86_64.zip',
+});
+
+function selectPlatform(platform = process.platform, arch = process.arch) {
+  const osName = platform === 'win32' ? 'windows' : platform;
+  const archName = arch === 'x64' || arch === 'amd64' || arch === 'x86_64'
+    ? 'x86_64'
+    : arch === 'arm64' || arch === 'aarch64'
+      ? 'arm64'
+      : '';
+  if (!['darwin', 'linux', 'windows'].includes(osName)) {
+    throw new Error(`Unsupported operating system: ${platform}`);
+  }
+  if (!archName) {
+    throw new Error(`Unsupported architecture: ${arch}`);
+  }
+  const key = `${osName}_${archName}`;
+  return {
+    key,
+    file: artifactFiles[key],
+    binary: osName === 'windows' ? 'wathba.exe' : 'wathba',
+    windows: osName === 'windows',
+  };
+}
+
+module.exports = { artifactFiles, selectPlatform };

package/lib/release-config.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": "wathba.npm.release-config.v1",
+  "installBaseUrl": "https://install.wathba.info",
+  "distributionRootBase64": "eyJzY2hlbWFWZXJzaW9uIjoid2F0aGJhLmNsaS5kaXN0cmlidXRpb24tcm9vdC52MSIsImtleUlkIjoid2F0aGJhLWRpc3RyaWJ1dGlvbi1yb290LTIwMjYtMDciLCJwdWJsaWNLZXlTcGtpIjoiTUlJQm9qQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FZOEFNSUlCaWdLQ0FZRUFzX0VscnJDOTAtaVNTOHRJc0xZTHRsWk9WX05CdjFIMkNCYnZRT1ByTC01QU5FdTNpdUphdVVCbUk5S3M2VTJUdFRKUVRoWUd0YW5BNnhDdFlZcFdQZlVpVndpaVl3NXNsQTRuNHNCSW11SEJvWkNqbzNrVWt2Q1I2RDVOdlJmaVFBSjVSRnVPOV9nNDlNUlc1MExPcHp1LTQwQ0g1S2pHZ2k0UUJXM3NER0FvakdJeG5rSmtrQ25yanQ0UHJvdmJqVHNqLUNuZFdjRHd4V1dLN0p1cjZYRnVwSnpCcmVVTEk0Ymd5N0tzeGJEbmUzYkRhVXFjS0NPTWw3bzlLN3BJcEd3TGNjRXd3ZTdWM1FhWXJYYVNWRkJ0UkR6WnJTejVmQXl1TGRTQ1UzcDYwYkxCemRTUHhwLThySFIzaEVuOTh4MlJnWlRzaUkxZFpKM21KNE5yMW9kNm9vSjNVQVVkbzF6SWd6T2h5ZXBpa3hWOHMtTXhMVmQ5emtUVHlVX3UwT3R2a2daSUMzNWFRbUIyZXBjZUFiUXZvZ1ZaTU0wWHB4cUJ0cjRuNExNNHN2cG1DcVFhRUwtTVhNbG5DbGRfMXBCMkd2SVNGTU5adkZFNm4xTU1CQ2dSaEdXempuQVFZeDBoeURRSld4WXlnVFNtN0tVbVh4TWxiTHVwOV8zWkFnTUJBQUUifQ"
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@wathba-cli/cli",
+  "version": "1.3.5",
+  "description": "Agent-first CLI for the Wathba developer platform",
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/wathba-org/wathba-cli#readme",
+  "bugs": {
+    "url": "https://github.com/wathba-org/wathba-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wathba-org/wathba-cli.git"
+  },
+  "type": "commonjs",
+  "bin": {
+    "wathba": "bin/wathba.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "test": "node --test"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "install.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}