pulse-updates 1.3.8 → 1.3.9

package/scripts/publish.mjs

@@ -119,6 +119,122 @@ async function hashFileSHA256(filePath) {
   });
 }
 
+const NATIVE_MODULE_EVIDENCE_VERSION = 1;
+const NATIVE_MODULE_NAME = /^[\w.$-]{1,128}$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function validateNativeModules(value, source) {
+  if (!Array.isArray(value) || value.length > 4096) {
+    throw new Error(`Invalid native-module evidence in ${source}: nativeModules must be an array`);
+  }
+  if (!value.every((name) => typeof name === 'string' && NATIVE_MODULE_NAME.test(name))) {
+    throw new Error(`Invalid native-module evidence in ${source}: nativeModules contains an invalid name`);
+  }
+  const canonical = [...new Set(value)].sort();
+  if (canonical.length !== value.length || canonical.some((name, index) => name !== value[index])) {
+    throw new Error(`Invalid native-module evidence in ${source}: nativeModules must be sorted and unique`);
+  }
+  return [...value];
+}
+
+function validateEvidenceContext(value, config, source) {
+  if (value.schemaVersion !== NATIVE_MODULE_EVIDENCE_VERSION
+    || value.platform !== config.platform
+    || value.runtimeVersion !== config.runtimeVersion
+    || value.channel !== config.channel) {
+    throw new Error(
+      `Invalid native-module evidence in ${source}: release context does not match ` +
+      `${config.runtimeVersion}/${config.platform}/${config.channel}`
+    );
+  }
+  if (!SHA256_HEX.test(value.scannedBundleSha256 ?? '')
+    || !SHA256_HEX.test(value.uploadBundleSha256 ?? '')) {
+    throw new Error(`Invalid native-module evidence in ${source}: bundle SHA-256 is missing or invalid`);
+  }
+}
+
+/**
+ * Persist the capability scan beside a hash of the exact post-Hermes artifact. A wrapper that
+ * deliberately transforms that artifact (for example Bastion) must first verify
+ * scannedBundleSha256, then replace uploadBundleSha256 with the transformed artifact hash. The
+ * --skip-bundle pass verifies the latter before it creates anything server-side.
+ */
+export async function writeNativeModulesEvidence(evidencePath, config, bundlePath, nativeModules) {
+  const resolved = path.resolve(evidencePath);
+  const canonicalModules = validateNativeModules(nativeModules, resolved);
+  const bundleSha256 = await hashFileSHA256(bundlePath);
+  const evidence = {
+    schemaVersion: NATIVE_MODULE_EVIDENCE_VERSION,
+    platform: config.platform,
+    runtimeVersion: config.runtimeVersion,
+    channel: config.channel,
+    scannedBundleSha256: bundleSha256,
+    uploadBundleSha256: bundleSha256,
+    nativeModules: canonicalModules,
+  };
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  const temporary = `${resolved}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(evidence)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, resolved);
+  } finally {
+    // renameSync removes the source on success. On every failure path, including a destination
+    // that becomes invalid concurrently, do not strand capability evidence in a readable temp file.
+    try { fs.unlinkSync(temporary); } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  return evidence;
+}
+
+/** Read and bind capability evidence to the exact artifact about to be uploaded. */
+export async function readNativeModulesEvidence(evidencePath, config, bundlePath) {
+  const resolved = path.resolve(evidencePath);
+  let evidence;
+  try {
+    evidence = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  } catch (error) {
+    throw new Error(`Native-module evidence is missing or unreadable at ${resolved}: ${error.message}`);
+  }
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    throw new Error(`Invalid native-module evidence in ${resolved}: expected an object`);
+  }
+  validateEvidenceContext(evidence, config, resolved);
+  const nativeModules = validateNativeModules(evidence.nativeModules, resolved);
+  const uploadBundleSha256 = await hashFileSHA256(bundlePath);
+  if (uploadBundleSha256 !== evidence.uploadBundleSha256) {
+    throw new Error(
+      `Native-module evidence does not describe the upload artifact: expected ` +
+      `${evidence.uploadBundleSha256}, got ${uploadBundleSha256}`
+    );
+  }
+  return { ...evidence, nativeModules };
+}
+
+export function createReleaseRequest(config, metadata, nativeModules, nativeModulesVerified) {
+  return {
+    runtimeVersion: config.runtimeVersion,
+    platform: config.platform,
+    channel: config.channel,
+    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    // A verified empty array is evidence too. Legacy --skip-bundle calls without the handoff file
+    // retain their old omitted-field behaviour, while guarded wrappers cannot silently bypass ABI
+    // preflight by turning a real scan into an absent fingerprint.
+    nativeModules: nativeModulesVerified
+      ? nativeModules
+      : (nativeModules.length ? nativeModules : undefined),
+    // Which binary this bundle is for, when it is only for one. A runtime version is not always a
+    // single build — on iOS it is MARKETING_VERSION, which stays put across re-submissions — and a
+    // bundle wrapped with one build's key cannot be opened by another, which stops that app from
+    // starting rather than merely leaving it un-updated. Naming the build keeps the manifest from
+    // handing it to the wrong one. Omitted for unwrapped bundles, which every build can load.
+    // Spread rather than assign: an explicit `nativeBuild: undefined` is invisible over the wire
+    // but not to a caller comparing the request it built, and unwrapped bundles have no build to
+    // name.
+    ...(config.nativeBuild ? { nativeBuild: config.nativeBuild } : {}),
+  };
+}
+
 /**
  * Calculate MD5 hash of a file (for asset key - matches Metro/expo format)
  */
@@ -826,6 +942,10 @@ function loadConfig(options) {
     apiKey: options['api-key'] || process.env.PULSE_API_KEY || fileConfig.apiKey,
     runtimeVersion,
     platform,
+    // Only ever what the operator states. It could be read from the pbxproj or build.gradle, but a
+    // guess here is the failure it exists to prevent: the checkout is not reliably the build the
+    // update is for, which is the whole reason a runtime version is not enough on its own.
+    nativeBuild: options['native-build'] || process.env.PULSE_NATIVE_BUILD || fileConfig.nativeBuild,
     channel: options.channel || fileConfig.channel || 'production',
     bundleDir: options['bundle-dir'] || fileConfig.bundleDir || './dist',
     entryFile: options['entry-file'] || fileConfig.entryFile || 'index.ts',
@@ -844,7 +964,7 @@ function loadConfig(options) {
 /**
  * Main publish command
  */
-async function publish(options) {
+export async function publish(options) {
   const config = loadConfig(options);
 
   // Validate required config
@@ -873,25 +993,60 @@ async function publish(options) {
   log(`Bundle Dir: ${bundleDir}\n`);
 
   let nativeModules = [];
+  let nativeModulesVerified = false;
+  const nativeModulesFileOption = options['native-modules-file'];
+  if (nativeModulesFileOption !== undefined
+    && (typeof nativeModulesFileOption !== 'string' || !nativeModulesFileOption.trim())) {
+    throw new Error('--native-modules-file requires a path');
+  }
+  const nativeModulesFile = nativeModulesFileOption
+    ? path.resolve(nativeModulesFileOption)
+    : null;
+  const bundlePath = path.join(bundleDir, config.platform, 'index.bundle');
 
   // Step 1: Create bundle (unless skipped)
   if (!config.skipBundle) {
     logStep('1/6', 'Creating bundle...');
-    const bundlePath = createBundle(config.platform, bundleDir, config.entryFile);
-    logSuccess(`Bundle created: ${bundlePath}`);
+    const createdBundlePath = createBundle(config.platform, bundleDir, config.entryFile);
+    logSuccess(`Bundle created: ${createdBundlePath}`);
 
     // Crash-prediction fingerprint: extract native module references from the plain JS bundle
     // (must happen BEFORE Hermes bytecode compilation, while the bundle is still readable JS).
-    nativeModules = extractNativeModules(bundlePath);
+    nativeModules = extractNativeModules(createdBundlePath);
+    nativeModulesVerified = true;
     log(`Native modules referenced: ${nativeModules.length}${nativeModules.length ? ` (${nativeModules.join(', ')})` : ''}`);
 
     // Step 2: Compile with Hermes
     logStep('2/6', 'Compiling with Hermes...');
-    compileWithHermes(bundlePath, config.platform, { requireHermes: config.requireHermes });
+    compileWithHermes(createdBundlePath, config.platform, { requireHermes: config.requireHermes });
     logSuccess('Hermes compilation complete');
+    if (nativeModulesFile) {
+      await writeNativeModulesEvidence(
+        nativeModulesFile,
+        config,
+        createdBundlePath,
+        nativeModules,
+      );
+      log(`Native-module evidence written: ${nativeModulesFile}`);
+    }
   } else {
     logStep('1/6', 'Skipping bundle creation (--skip-bundle)');
     logStep('2/6', 'Skipping Hermes compilation');
+    if (nativeModulesFile) {
+      const evidence = await readNativeModulesEvidence(
+        nativeModulesFile,
+        config,
+        bundlePath,
+      );
+      nativeModules = evidence.nativeModules;
+      nativeModulesVerified = true;
+      log(`Native-module evidence verified: ${nativeModules.length}${nativeModules.length ? ` (${nativeModules.join(', ')})` : ''}`);
+    } else {
+      logWarning(
+        '--skip-bundle has no --native-modules-file; preserving legacy behaviour without a ' +
+        'capability fingerprint. Guarded release wrappers should fail before reaching this path.'
+      );
+    }
   }
 
   // Step 3: Collect assets and calculate hashes
@@ -929,13 +1084,12 @@ async function publish(options) {
       'Content-Type': 'application/json',
       'X-API-Key': config.apiKey,
     },
-    body: JSON.stringify({
-      runtimeVersion: config.runtimeVersion,
-      platform: config.platform,
-      channel: config.channel,
-      metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
-      nativeModules: nativeModules.length ? nativeModules : undefined,
-    }),
+    body: JSON.stringify(createReleaseRequest(
+      config,
+      metadata,
+      nativeModules,
+      nativeModulesVerified,
+    )),
   });
 
   if (!createResponse.ok) {
@@ -963,13 +1117,63 @@ async function publish(options) {
   // modules that weren't in the previous good release for this runtime version — native code can't ship
   // over the air, so it would crash the installed cohort. Override with --allow-native-change.
   let preflight = null;
+  // Any verified capability scan (a direct build or a two-pass evidence handoff) requires a valid
+  // server answer: an unavailable or malformed preflight is not evidence that the OTA is safe, so
+  // it must stop before any asset upload/finalize. Only legacy --skip-bundle without evidence has
+  // no capability set to enforce; --no-native-check remains the one explicit escape hatch.
+  const requiresVerifiedPreflight = nativeModulesVerified && !options['no-native-check'];
+  let pfRes = null;
   try {
-    const pfRes = await fetch(`${config.apiUrl}/api/releases/${release.id}/preflight`, {
+    pfRes = await fetch(`${config.apiUrl}/api/releases/${release.id}/preflight`, {
       headers: { 'X-API-Key': config.apiKey },
     });
-    if (pfRes.ok) preflight = await pfRes.json();
-  } catch {
-    log('⚠  Preflight check could not run (server unreachable); continuing.');
+  } catch (error) {
+    if (requiresVerifiedPreflight) {
+      throw new Error(
+        `Native ABI preflight could not reach the server; refusing capability-verified publish: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+    logWarning('Preflight check could not run (server unreachable); continuing legacy publish.');
+  }
+  if (pfRes && !pfRes.ok) {
+    if (requiresVerifiedPreflight) {
+      throw new Error(`Native ABI preflight failed with HTTP ${pfRes.status}; refusing capability-verified publish.`);
+    }
+    logWarning(`Preflight check returned HTTP ${pfRes.status}; continuing legacy publish.`);
+  }
+  if (pfRes?.ok) {
+    let decodedPreflight = false;
+    try {
+      preflight = await pfRes.json();
+      decodedPreflight = true;
+    } catch (error) {
+      if (requiresVerifiedPreflight) {
+        throw new Error(
+          `Native ABI preflight returned invalid JSON; refusing capability-verified publish: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+      logWarning('Preflight check returned invalid JSON; continuing legacy publish.');
+    }
+    const validPreflight = decodedPreflight
+      && preflight !== null
+      && typeof preflight === 'object'
+      && !Array.isArray(preflight)
+      && typeof preflight.ok === 'boolean'
+      && Array.isArray(preflight.warnings)
+      && preflight.warnings.every((warning) => typeof warning === 'string')
+      && Array.isArray(preflight.newNativeModules)
+      && preflight.newNativeModules.every((moduleName) => typeof moduleName === 'string');
+    if (decodedPreflight && !validPreflight) {
+      preflight = null;
+      if (requiresVerifiedPreflight) {
+        throw new Error('Native ABI preflight returned an invalid response schema; refusing capability-verified publish.');
+      }
+      logWarning('Preflight check returned an invalid response schema; continuing legacy publish.');
+    }
   }
   if (preflight) {
     for (const w of preflight.warnings || []) log(`⚠  ${w}`);
@@ -1456,8 +1660,15 @@ ${colors.cyan}Options:${colors.reset}
   --channel <channel>     Release channel (default: production)
   --bundle-dir <dir>      Output directory (default: ./dist)
   --bundle <file>         Embedded bundle for register-capabilities (otherwise built automatically)
+  --native-build <n>      The build this bundle is for (iOS CFBundleVersion, Android versionCode).
+                          Required when the bundle is wrapped with a per-build key: without it the
+                          manifest serves the bundle to every build sharing the runtime version,
+                          and the ones holding a different key cannot start.
   --entry-file <file>     Entry file (default: index.ts)
   --skip-bundle           Skip bundle creation (use existing)
+  --native-modules-file <file>
+                          Capability evidence handoff for a two-pass/--skip-bundle publish. The
+                          build pass writes it; the upload pass validates its context and SHA-256.
   --dry-run               Build + validate locally without creating a release on the server
   --allow-native-change   Publish even though new native modules were detected (you certify they're
                           already in the installed binary). Default is FAIL-CLOSED: a new native module