@novacraft-engineering/pulsar-cli 1.4.0 → 1.5.0

package/README.md

@@ -25,7 +25,9 @@ pulsar login <apiUrl>                 # authenticate (API key or browser), saved
 pulsar apps                           # list your apps and deployment keys
 
 pulsar release <app> <deployment> --platform ios|android --target <ver> \
-       [--rollout 25] [--mandatory] [--disabled] [--devices id1,id2,...] [--description "fix crash"]
+       [--rollout 25] [--mandatory] [--disabled] [--devices id1,id2,...] [--description "fix crash"] \
+       [--private-key key.pem] [--bundle-key <file>]
+       [--plain-copy-for-old-builds | --plain | --only-older-builds]
 
 pulsar promote <app> <from> <to> [--rollout 100]
 pulsar rollback <app> <deployment>
@@ -35,6 +37,11 @@ pulsar deployment add <app> <name>    # create a new deployment (e.g. QA)
 pulsar history <app> <deployment>     # release history
 pulsar patch <app> <deployment> <label> [--rollout N] [--mandatory] [--disable] [--enable] [--devices id1,id2,...]
 pulsar migrate --from <serverUrl> --access-key <key>   # move apps from RevoPush / code-push-server (see below)
+
+pulsar keygen                         # write pulsar-private.pem + pulsar-public.pem for code signing
+pulsar bundle-key create --app <name> [--out <file>]   # create a private-bundles key (see below)
+pulsar bundle-key id [--bundle-key <file>]             # print the key ids in PULSAR_BUNDLE_KEY or the file
+pulsar changes --app <name> --deployment <dep> --label <vN>   # unlock a private release locally, print what changed
 ```
 
 ### Targeting a release's reach
@@ -53,6 +60,74 @@ then downloads it in the background and swaps it in on next launch.
 
 Auth is read from `PULSAR_API_URL` / `PULSAR_TOKEN` env, or `~/.pulsar/config.json` (written by `pulsar login`). Nothing is committed.
 
+## Code signing
+
+```bash
+pulsar keygen
+```
+
+Writes `pulsar-private.pem` (mode 0600) and `pulsar-public.pem` in the current folder. Put the
+public key in your app as `CodePushPublicKey` (iOS `Info.plist`, Android `strings.xml`). From then on
+the device rejects any update not signed with the matching private key.
+
+- `--private-key <file>` signs the release locally with that key.
+- `PULSAR_SIGNING_KEY` does the same with the key itself in the environment, which suits CI.
+- With neither, the CLI asks Pulsar to sign with the app's stored key. If Pulsar holds no key for
+  the app, the release goes out unsigned and the CLI says so.
+
+## Private bundles (encrypted releases)
+
+When an app's Private bundles setting is Manual unlock or Auto unlock, `pulsar release` encrypts
+the bundle, diff, manifest and source map before upload, so Pulsar stores and serves only ciphertext.
+It is not protection against reverse engineering: the key ships inside your store build. Full guide:
+[usepulsar.dev/docs/private-bundles](https://usepulsar.dev/docs/private-bundles).
+
+```bash
+pulsar bundle-key create --app MyApp
+```
+
+Generates a key, writes `pulsar-bundle-key-MyApp.txt` (mode 0600, never overwrites an existing
+file; `--out <file>` to choose the path), registers the key id with Pulsar and prints the
+`Info.plist` / `strings.xml` snippets. Back the key up: Pulsar can't recover it, and builds that
+carry only a lost key can't receive OTAs until a store build ships a new one.
+
+The key string is `kid:base64key`, comma separated for several keys. The same string goes in
+`PULSAR_BUNDLE_KEY` and in `CodePushBundleKeys` (SDK 1.8 or later):
+
+```xml
+<!-- iOS Info.plist -->
+<key>CodePushBundleKeys</key><string>KID:BASE64KEY</string>
+
+<!-- Android res/values/strings.xml -->
+<string moduleConfig="true" name="CodePushBundleKeys">KID:BASE64KEY</string>
+```
+
+Releasing a private app needs the bundle key and a local signing key:
+
+```bash
+export PULSAR_BUNDLE_KEY="$(cat pulsar-bundle-key-MyApp.txt)"
+export PULSAR_SIGNING_KEY="$(cat pulsar-private.pem)"
+pulsar release MyApp Production --platform ios --target 1.4.0
+```
+
+- `--bundle-key <file>` reads the key string from a file instead of `PULSAR_BUNDLE_KEY`.
+- `--plain-copy-for-old-builds` also uploads the signed, unencrypted zip of the same release, so
+  builds that can't open the encrypted copy still get the fix. Pulsar can read that copy.
+- `--plain` releases unencrypted on purpose while private bundles are on: every build gets it, and
+  Pulsar can read it.
+- `--only-older-builds` releases unencrypted only to builds that can't open private releases; builds
+  holding the key keep their encrypted release.
+- `pulsar history` tags releases `[private]`, `[private + plain copy]` and `[plain, older builds only]`.
+- Each encrypted release prints its reach (devices that will get it, devices that stay on their
+  current bundle). A mandatory encrypted release with no reach and no plain copy is blocked.
+- The CLI warns when a key registered for the app is missing from the keys you gave it, and wraps
+  each release for every key it is given, which is how you rotate.
+- Older builds are never sent a release they can't open; they stay on their current bundle.
+
+`pulsar changes --app MyApp --deployment Production --label v12` downloads that release's encrypted
+manifests and source maps, unlocks them on your machine and prints what changed. The key never
+leaves your machine.
+
 ## Migrating from RevoPush / code-push-server
 
 `pulsar migrate` copies apps from any server that speaks the CodePush management API
@@ -99,6 +174,8 @@ Both env vars are all a GitHub Actions / GitLab CI job needs:
     PULSAR_TOKEN: ${{ secrets.PULSAR_TOKEN }}
 ```
 
+Add `PULSAR_SIGNING_KEY` to sign locally, and `PULSAR_BUNDLE_KEY` for apps with private bundles on.
+
 Or connect the repo in the dashboard and fire a release for any commit without leaving the browser.
 
 ## Related

package/envelope.js

@@ -0,0 +1,215 @@
+const MAGIC = [0x50, 0x4c, 0x53, 0x42];
+const VERSION = 1;
+const PREFIX_LENGTH = 9;
+const MAX_HEADER = 16384;
+export const SEGMENT_SIZE = 65536;
+const TAG_LENGTH = 16;
+export const ALGORITHM = 'A256GCM-SEG64K';
+export const KINDS = ['full', 'diff', 'manifest', 'sourcemap'];
+export const SEALED_CONTENT_TYPE = 'application/vnd.pulsar.sealed';
+
+const KID_PATTERN = /^[0-9a-f]{16}$/;
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const subtle = () => globalThis.crypto.subtle;
+
+export function toBase64(bytes) {
+  let binary = '';
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  for (let offset = 0; offset < view.length; offset += 0x8000) {
+    binary += String.fromCharCode(...view.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+}
+
+export function fromBase64(text) {
+  const binary = atob(String(text));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+const toHex = (bytes) => [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+
+export async function kidOf(rawKey) {
+  const digest = new Uint8Array(await subtle().digest('SHA-256', rawKey));
+  return toHex(digest.subarray(0, 8));
+}
+
+export async function generateKeyString() {
+  const raw = globalThis.crypto.getRandomValues(new Uint8Array(32));
+  return `${await kidOf(raw)}:${toBase64(raw)}`;
+}
+
+export async function parseKeys(keyString) {
+  const entries = String(keyString || '')
+    .split(/[\s,]+/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (!entries.length) throw new Error('No bundle key given');
+  const keys = [];
+  for (const entry of entries) {
+    const [kid, encoded, extra] = entry.split(':');
+    if (extra !== undefined || !KID_PATTERN.test(kid || '') || !encoded) throw new Error('A bundle key must look like <kid>:<base64 key>');
+    let raw;
+    try {
+      raw = fromBase64(encoded);
+    } catch {
+      throw new Error(`Bundle key ${kid} is not valid base64`);
+    }
+    if (raw.length !== 32) throw new Error(`Bundle key ${kid} must be 32 bytes`);
+    if ((await kidOf(raw)) !== kid) throw new Error(`Bundle key ${kid} does not match its key id`);
+    keys.push({kid, key: raw});
+  }
+  return keys;
+}
+
+async function aesKey(material, usages) {
+  if (material instanceof Uint8Array || material instanceof ArrayBuffer) {
+    return subtle().importKey('raw', material, 'AES-GCM', false, usages);
+  }
+  return material;
+}
+
+export function isSealed(bytes) {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  return view.length >= 4 && MAGIC.every((value, index) => view[index] === value);
+}
+
+function validateHeader(header) {
+  if (!header || typeof header !== 'object' || Array.isArray(header)) throw new Error('Envelope header is not an object');
+  if (header.alg !== ALGORITHM) throw new Error('Unsupported envelope algorithm');
+  if (!KINDS.includes(header.kind)) throw new Error('Unknown envelope kind');
+  if (typeof header.appId !== 'string' || !header.appId || header.appId.length > 128) throw new Error('Envelope header has no app id');
+  if (!HASH_PATTERN.test(header.packageHash || '')) throw new Error('Envelope header has no package hash');
+  if (header.kind === 'diff' && !HASH_PATTERN.test(header.baseHash || '')) throw new Error('Diff envelope has no base hash');
+  if (fromBase64(header.nonce || '').length !== 7) throw new Error('Envelope nonce must be 7 bytes');
+  if (!Array.isArray(header.keys) || !header.keys.length || header.keys.length > 16) throw new Error('Envelope must wrap 1 to 16 keys');
+  for (const entry of header.keys) {
+    if (!KID_PATTERN.test(entry?.kid || '')) throw new Error('Envelope key id is malformed');
+    if (fromBase64(entry.iv || '').length !== 12 || fromBase64(entry.wrapped || '').length !== 48) throw new Error('Envelope key entry is malformed');
+  }
+}
+
+export function parseEnvelope(bytes) {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (!isSealed(view)) throw new Error('Not a sealed Pulsar file');
+  if (view.length < PREFIX_LENGTH || view[4] !== VERSION) throw new Error('Unsupported envelope version');
+  const headerLength = new DataView(view.buffer, view.byteOffset, view.byteLength).getUint32(5);
+  if (headerLength < 1 || headerLength > MAX_HEADER || PREFIX_LENGTH + headerLength > view.length) throw new Error('Envelope header length is out of range');
+  const headerBytes = view.subarray(PREFIX_LENGTH, PREFIX_LENGTH + headerLength);
+  let header;
+  try {
+    header = JSON.parse(decoder.decode(headerBytes));
+  } catch {
+    throw new Error('Envelope header is not JSON');
+  }
+  validateHeader(header);
+  return {header, headerBytes, payloadOffset: PREFIX_LENGTH + headerLength};
+}
+
+const wrapContext = (kid, header) => encoder.encode(`pulsar-dek|v1|${kid}|${header.appId}|${header.packageHash}|${header.kind}`);
+
+function segmentNonce(prefix, index, last) {
+  const nonce = new Uint8Array(12);
+  nonce.set(prefix, 0);
+  new DataView(nonce.buffer).setUint32(7, index);
+  nonce[11] = last ? 1 : 0;
+  return nonce;
+}
+
+export async function seal({plaintext, keys, appId, packageHash, kind, baseHash}, {random = (length) => globalThis.crypto.getRandomValues(new Uint8Array(length))} = {}) {
+  const body = plaintext instanceof Uint8Array ? plaintext : new Uint8Array(plaintext);
+  if (!keys?.length) throw new Error('No bundle key given');
+  const dataKeyRaw = random(32);
+  const header = {
+    alg: ALGORITHM,
+    nonce: toBase64(random(7)),
+    appId,
+    packageHash,
+    kind,
+    ...(kind === 'diff' ? {baseHash} : {}),
+    keys: [],
+  };
+  for (const {kid, key} of keys) {
+    const iv = random(12);
+    const wrapped = await subtle().encrypt({name: 'AES-GCM', iv, additionalData: wrapContext(kid, header)}, await aesKey(key, ['encrypt']), dataKeyRaw);
+    header.keys.push({kid, iv: toBase64(iv), wrapped: toBase64(new Uint8Array(wrapped))});
+  }
+  validateHeader(header);
+  const headerBytes = encoder.encode(JSON.stringify(header));
+  if (headerBytes.length > MAX_HEADER) throw new Error('Envelope header is too large');
+  const aad = new Uint8Array(await subtle().digest('SHA-256', headerBytes));
+  const dataKey = await subtle().importKey('raw', dataKeyRaw, 'AES-GCM', false, ['encrypt']);
+  const prefix = fromBase64(header.nonce);
+  const segmentCount = Math.max(1, Math.ceil(body.length / SEGMENT_SIZE));
+  const parts = [];
+  for (let index = 0; index < segmentCount; index++) {
+    const chunk = body.subarray(index * SEGMENT_SIZE, (index + 1) * SEGMENT_SIZE);
+    const iv = segmentNonce(prefix, index, index === segmentCount - 1);
+    parts.push(new Uint8Array(await subtle().encrypt({name: 'AES-GCM', iv, additionalData: aad}, dataKey, chunk)));
+  }
+  const total = PREFIX_LENGTH + headerBytes.length + parts.reduce((sum, part) => sum + part.length, 0);
+  const output = new Uint8Array(total);
+  output.set(MAGIC, 0);
+  output[4] = VERSION;
+  new DataView(output.buffer).setUint32(5, headerBytes.length);
+  output.set(headerBytes, PREFIX_LENGTH);
+  let offset = PREFIX_LENGTH + headerBytes.length;
+  for (const part of parts) {
+    output.set(part, offset);
+    offset += part.length;
+  }
+  return output;
+}
+
+export async function unwrapDataKey(header, keys) {
+  for (const entry of header.keys) {
+    const match = keys.find((candidate) => candidate.kid === entry.kid);
+    if (!match) continue;
+    try {
+      const raw = await subtle().decrypt(
+        {name: 'AES-GCM', iv: fromBase64(entry.iv), additionalData: wrapContext(entry.kid, header)},
+        await aesKey(match.key, ['decrypt']),
+        fromBase64(entry.wrapped),
+      );
+      return subtle().importKey('raw', raw, 'AES-GCM', false, ['decrypt']);
+    } catch {
+      throw new Error(`Bundle key ${entry.kid} could not unlock this file`);
+    }
+  }
+  throw new Error(`None of your bundle keys can open this file (it needs ${header.keys.map((entry) => entry.kid).join(' or ')})`);
+}
+
+export async function open(bytes, keys, expected = {}) {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const {header, headerBytes, payloadOffset} = parseEnvelope(view);
+  for (const field of ['appId', 'packageHash', 'kind', 'baseHash']) {
+    if (expected[field] !== undefined && header[field] !== expected[field]) throw new Error(`Envelope ${field} does not match`);
+  }
+  const dataKey = await unwrapDataKey(header, keys);
+  const aad = new Uint8Array(await subtle().digest('SHA-256', headerBytes));
+  const prefix = fromBase64(header.nonce);
+  const payload = view.subarray(payloadOffset);
+  const stride = SEGMENT_SIZE + TAG_LENGTH;
+  const segmentCount = Math.max(1, Math.ceil(payload.length / stride));
+  if (payload.length < TAG_LENGTH || (payload.length % stride !== 0 && payload.length % stride < TAG_LENGTH)) throw new Error('Envelope payload is truncated');
+  const parts = [];
+  for (let index = 0; index < segmentCount; index++) {
+    const segment = payload.subarray(index * stride, (index + 1) * stride);
+    const iv = segmentNonce(prefix, index, index === segmentCount - 1);
+    try {
+      parts.push(new Uint8Array(await subtle().decrypt({name: 'AES-GCM', iv, additionalData: aad}, dataKey, segment)));
+    } catch {
+      throw new Error('Envelope failed authentication: the file was altered, truncated or is for another release');
+    }
+  }
+  const output = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    output.set(part, offset);
+    offset += part.length;
+  }
+  return {header, plaintext: output};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novacraft-engineering/pulsar-cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Pulsar OTA release CLI — bundle, hash, and ship React Native updates over-the-air.",
   "type": "module",
   "bin": {
@@ -10,6 +10,9 @@
     "pulsar.js",
     "hash.js",
     "migrate.js",
+    "private.js",
+    "envelope.js",
+    "releaseCompare.js",
     "README.md",
     "LICENSE"
   ],
@@ -27,7 +30,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/hash.test.js && node test/security.test.js && node test/signing.test.js && node test/entry.test.js && node test/migrate.test.js"
+    "test": "node test/hash.test.js && node test/security.test.js && node test/signing.test.js && node test/entry.test.js && node test/migrate.test.js && node test/envelope.test.js && node test/private.test.js"
   },
   "keywords": [
     "cli",

package/private.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {api, die, getFlag, loadConfig, resolveApp} from './pulsar.js';
+import {seal, open, parseKeys, generateKeyString, SEALED_CONTENT_TYPE} from './envelope.js';
+import {compareManifests, compareModules, manifestParts} from './releaseCompare.js';
+
+export async function loadBundleKeys(args) {
+  const keyFile = getFlag(args, 'bundle-key');
+  if (keyFile && !fs.existsSync(keyFile)) die(`no bundle key file at ${keyFile}`);
+  const keyString = keyFile ? fs.readFileSync(keyFile, 'utf8') : (process.env.PULSAR_BUNDLE_KEY || '').trim();
+  if (!keyString) return [];
+  try {
+    return await parseKeys(keyString);
+  } catch (err) {
+    die(`bundle key: ${err.message}`);
+  }
+}
+
+export async function privateContext(app, args, localKey) {
+  let settings;
+  try {
+    settings = await api(`/apps/${app.id}/private-bundles`, {optional: true});
+  } catch {
+    return null;
+  }
+  if (!settings || settings.mode === 'off') return null;
+  if (!localKey) die(`${app.name} uses private bundles, which need local signing: pass --private-key <file> or set PULSAR_SIGNING_KEY. Nothing was uploaded.`);
+  const plain = args.includes('--only-older-builds') ? 'older' : args.includes('--plain') ? 'all' : null;
+  if (plain && args.includes('--plain-copy-for-old-builds')) die('--plain-copy-for-old-builds goes with an encrypted release; drop it when releasing plain. Nothing was uploaded.');
+  const given = await loadBundleKeys(args);
+  const registered = new Set(settings.keys.map((entry) => entry.kid));
+  const keys = given.filter((key) => registered.has(key.kid));
+  if (plain) return {keys, readiness: settings.readiness, plain};
+  if (!given.length) die(`${app.name} uses private bundles: pass --bundle-key <file> or set PULSAR_BUNDLE_KEY, or release plain on purpose with --plain or --only-older-builds. Nothing was uploaded.`);
+  if (!keys.length) die(`none of your bundle keys (${given.map((key) => key.kid).join(', ')}) are registered for ${app.name}. Registered: ${[...registered].join(', ') || 'none'}`);
+  const missing = [...registered].filter((kid) => !keys.some((key) => key.kid === kid));
+  if (missing.length) console.log(`⚠ registered key ${missing.join(', ')} wasn't given, so builds holding only that key won't get this release`);
+  return {keys, readiness: settings.readiness, plain: null};
+}
+
+export function reportReach(context, {mandatory, plainCopy}) {
+  const {total = 0, ready = 0, windowDays = 30} = context.readiness || {};
+  const left = total - ready;
+  if (context.plain === 'all') {
+    console.log(`• plain release on purpose: reaches all ${total} devices seen in the last ${windowDays} days, and Pulsar can read it`);
+    return;
+  }
+  if (context.plain === 'older') {
+    console.log(`• plain release for older builds only: reaches the ${left} of ${total} devices that can't open private releases; Pulsar can read it. The ${ready} that can keep their encrypted release`);
+    if (mandatory && left === 0) die('every recent device can open private releases, so an older-builds-only release would reach nobody. Nothing was uploaded.');
+    return;
+  }
+  if (plainCopy) {
+    console.log(`• private release: ${ready} of ${total} devices seen in the last ${windowDays} days get the encrypted copy; ${left} get the plain copy for older builds, which Pulsar can read`);
+    return;
+  }
+  console.log(`• private release: reaches ${ready} of ${total} devices seen in the last ${windowDays} days; ${left} stay on their current bundle`);
+  if (mandatory && ready === 0) {
+    die('no device can open private releases yet, so a mandatory one would reach nobody. Ship store builds with SDK 1.8 and the bundle key, or add --plain-copy-for-old-builds. Nothing was uploaded.');
+  }
+}
+
+export const sealArtifact = (context, app, packageHash, plaintext, kind, extra = {}) =>
+  seal({plaintext: new Uint8Array(plaintext), keys: context.keys, appId: app.id, packageHash, kind, ...extra});
+
+export async function openArtifact(keys, bytes, expected) {
+  return Buffer.from((await open(new Uint8Array(bytes), keys, expected)).plaintext);
+}
+
+export const sealedHeaders = {'content-type': SEALED_CONTENT_TYPE};
+
+async function cmdBundleKeyCreate(args) {
+  const appName = getFlag(args, 'app');
+  if (!appName) die('Usage: pulsar bundle-key create --app <name> [--out <file>] [--platform ios|android]');
+  const app = await resolveApp(appName, getFlag(args, 'platform'));
+  const outFile = getFlag(args, 'out', `pulsar-bundle-key-${app.name.replace(/[^A-Za-z0-9._-]+/g, '-')}.txt`);
+  if (fs.existsSync(outFile)) die(`${outFile} already exists. Pick another --out; never overwrite a bundle key.`);
+  const keyString = await generateKeyString();
+  const [{kid}] = await parseKeys(keyString);
+  fs.writeFileSync(outFile, `${keyString}\n`, {mode: 0o600, flag: 'wx'});
+  console.log(`✓ wrote bundle key ${kid} to ${path.resolve(outFile)} (owner-only)`);
+  try {
+    await api(`/apps/${app.id}/private-bundles`, {method: 'PUT', body: {addKids: [kid]}, optional: true});
+    console.log(`✓ registered key id ${kid} with ${app.name}`);
+  } catch (err) {
+    console.log(`⚠ couldn't register the key id (${err.message}). An admin can add ${kid} under Private bundles in the dashboard.`);
+  }
+  console.log('\nBack this file up now (password manager or secrets vault). If it is lost, builds that carry only this key can\'t receive updates until a new store build ships.');
+  console.log('\nCI: set PULSAR_BUNDLE_KEY to the file\'s contents.');
+  console.log('\niOS Info.plist:');
+  console.log(`  <key>CodePushBundleKeys</key>\n  <string>${keyString}</string>`);
+  console.log('\nAndroid res/values/strings.xml:');
+  console.log(`  <string moduleConfig="true" name="CodePushBundleKeys">${keyString}</string>`);
+}
+
+async function cmdBundleKeyId(args) {
+  const keys = await loadBundleKeys(args);
+  if (!keys.length) die('pass --bundle-key <file> or set PULSAR_BUNDLE_KEY');
+  for (const key of keys) console.log(key.kid);
+}
+
+export async function cmdBundleKey(args) {
+  const [sub, ...rest] = args;
+  if (sub === 'create') return cmdBundleKeyCreate(rest);
+  if (sub === 'id') return cmdBundleKeyId(rest);
+  die('Usage: pulsar bundle-key <create|id> [--app <name>] [--bundle-key <file>]');
+}
+
+async function fetchSealed(app, deployment, label, kind) {
+  const {apiUrl, token} = loadConfig();
+  const response = await fetch(`${apiUrl.replace(/\/$/, '')}/apps/${app.id}/deployments/${deployment}/releases/${label}/sealed/${kind}`, {headers: {authorization: `Bearer ${token}`}});
+  if (!response.ok) return null;
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+export async function cmdChanges(args) {
+  const appName = getFlag(args, 'app');
+  const deployment = getFlag(args, 'deployment', 'Staging');
+  const label = getFlag(args, 'label');
+  if (!appName || !label) die('Usage: pulsar changes --app <name> --deployment <Staging|Production> --label <vN> [--base <vM>] [--bundle-key <file>]');
+  const app = await resolveApp(appName, getFlag(args, 'platform'));
+  const base = getFlag(args, 'base');
+  const summary = await api(`/apps/${app.id}/deployments/${deployment}/releases/${label}/changes${base ? `?base=${encodeURIComponent(base)}` : ''}`);
+  if (!summary.base) return console.log(`${label} has nothing earlier to compare with.`);
+  let files = summary.files;
+  let modules = summary.modules;
+  if (summary.sealed) {
+    const keys = await loadBundleKeys(args);
+    if (!keys.length) die('this release is private: pass --bundle-key <file> or set PULSAR_BUNDLE_KEY to unlock it here');
+    const releases = await api(`/apps/${app.id}/deployments/${deployment}/releases`);
+    const hashOf = (wanted) => releases.find((entry) => entry.label === wanted)?.packageHash;
+    const unlock = async (wanted, kind) => {
+      const bytes = await fetchSealed(app, deployment, wanted, kind);
+      if (!bytes) return null;
+      return JSON.parse((await openArtifact(keys, bytes, {appId: app.id, packageHash: hashOf(wanted), kind})).toString('utf8'));
+    };
+    const [before, after] = (await Promise.all([unlock(summary.base, 'manifest'), unlock(summary.target, 'manifest')])).map(manifestParts);
+    files = before.files && after.files ? compareManifests(before.files, after.files) : null;
+    let beforeModules = before.modules;
+    let afterModules = after.modules;
+    if (!beforeModules || !afterModules) {
+      const [beforeMap, afterMap] = await Promise.all([unlock(summary.base, 'sourcemap'), unlock(summary.target, 'sourcemap')]);
+      beforeModules = beforeMap?.sources || null;
+      afterModules = afterMap?.sources || null;
+    }
+    modules = beforeModules && afterModules ? compareModules(beforeModules, afterModules) : null;
+  }
+  console.log(`${summary.target} compared with ${summary.base}${summary.sealed ? ' (unlocked on this machine)' : ''}`);
+  if (!files && !modules) return console.log('No file list or source map was uploaded for one of these releases.');
+  if (files) {
+    console.log(`  files: ${files.counts.added} added, ${files.counts.modified} modified, ${files.counts.removed} removed, ${files.counts.unchanged} unchanged`);
+    for (const entry of files.added) console.log(`  + ${entry.path}`);
+    for (const entry of files.modified) console.log(`  ~ ${entry.path}`);
+    for (const entry of files.removed) console.log(`  - ${entry.path}`);
+  }
+  if (modules) {
+    console.log(`  modules: ${modules.counts.added} added, ${modules.counts.removed} removed`);
+    for (const name of modules.added) console.log(`  + ${name}`);
+    for (const name of modules.removed) console.log(`  - ${name}`);
+  }
+}

package/pulsar.js

@@ -9,6 +9,7 @@ import crypto from 'node:crypto';
 import {fileURLToPath} from 'node:url';
 import {computePackageHash, fileHashes} from './hash.js';
 import {migrate} from './migrate.js';
+import {privateContext, reportReach, sealArtifact, openArtifact, sealedHeaders, cmdBundleKey, cmdChanges} from './private.js';
 
 // Code signing: sign the package hash into an RS256 JWT the client verifies against its
 // CodePushPublicKey (Info.plist). Both native SDKs read it from <update>/CodePush/.codepushrelease
@@ -42,14 +43,16 @@ function loadConfig() {
   return {
     apiUrl: process.env.PULSAR_API_URL || fromFile.apiUrl,
     token: process.env.PULSAR_TOKEN || fromFile.token,
+    deviceId: fromFile.deviceId,
   };
 }
 
 function saveConfig(config) {
   // The config holds a bearer token — keep the dir and file owner-only so other local users on a
   // shared host can't read the session.
+  const deviceId = config.deviceId || loadConfig().deviceId;
   fs.mkdirSync(CONFIG_DIR, {recursive: true, mode: 0o700});
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {mode: 0o600});
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify({...config, deviceId}, null, 2), {mode: 0o600});
   try { fs.chmodSync(CONFIG_FILE, 0o600); } catch { /* best-effort on pre-existing files */ }
 }
 
@@ -347,8 +350,9 @@ async function cmdLogin(args) {
 
   const email = await prompt('Email: ');
   const password = await prompt('Password: ', true);
-  const {token, user} = await api('/auth/login', {method: 'POST', body: {email, password}, allowAnonymous: true});
-  saveConfig({apiUrl, token});
+  const deviceId = loadConfig().deviceId || crypto.randomBytes(16).toString('hex');
+  const {token, user} = await api('/auth/login', {method: 'POST', body: {email, password}, headers: {'x-device-id': deviceId}, allowAnonymous: true});
+  saveConfig({apiUrl, token, deviceId});
   console.log(`✓ logged in as ${user.email} (${user.platformRole})`);
 }
 
@@ -389,9 +393,14 @@ async function signForApp(app, deployment, contentsDir, packageHash, localKey) {
 
 // Sign and push an already-built bundle to one app's deployment, then generate and upload a
 // differential patch against whatever that deployment was serving.
-async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath} = {}) {
+async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath, reachReported = false} = {}) {
+  const privateBundles = await privateContext(app, args, localKey);
+  const sealing = Boolean(privateBundles) && !privateBundles.plain;
+  const plainCopy = sealing && args.includes('--plain-copy-for-old-builds');
+  if (privateBundles && !reachReported) reportReach(privateBundles, {mandatory: args.includes('--mandatory'), plainCopy});
   await signForApp(app, deployment, contentsDir, packageHash, localKey);
-  const zip = fs.readFileSync(zipContents(contentsDir));
+  const plainZip = fs.readFileSync(zipContents(contentsDir));
+  const zip = sealing ? Buffer.from(await sealArtifact(privateBundles, app, packageHash, plainZip, 'full')) : plainZip;
   let prevLatest = null;
   try {
     const existing = await api(`/apps/${app.id}/deployments/${deployment}/releases`, {optional: true});
@@ -423,7 +432,11 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
     body: zip,
     onUploadProgress: uploadProgress(`uploading ${(zip.length / 1e6).toFixed(1)}MB bundle`),
     headers: {
-      'content-type': 'application/zip',
+      ...(sealing
+        ? {...sealedHeaders, 'x-encrypted': '1', 'x-key-ids': privateBundles.keys.map((key) => key.kid).join(','), 'x-release-signature': fs.readFileSync(path.join(contentsDir, SIGNATURE_PATH), 'utf8')}
+        : {'content-type': 'application/zip'}),
+      ...(privateBundles?.plain === 'all' ? {'x-plain': '1'} : {}),
+      ...(privateBundles?.plain === 'older' ? {'x-audience': 'older-builds'} : {}),
       'x-app-version': getFlag(args, 'target'),
       'x-package-hash': packageHash,
       'x-is-mandatory': String(args.includes('--mandatory')),
@@ -446,7 +459,18 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
     release.targetFromLabels?.length ? `devices on ${release.targetFromLabels.join('/')}` : null,
   ].filter(Boolean);
   const reach = scopes.length ? scopes.join(' + ') : `${release.rollout}% of devices`;
-  console.log(`✓ released ${release.label} to ${app.name}/${deployment} — ${release.isDisabled ? 'DISABLED' : reach}`);
+  const privacy = release.encrypted ? ' (private)' : release.olderBuildsOnly ? ' (plain, older builds only)' : privateBundles ? ' (plain)' : '';
+  console.log(`✓ released ${release.label} to ${app.name}/${deployment} — ${release.isDisabled ? 'DISABLED' : reach}${privacy}`);
+  if (plainCopy) {
+    await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/plain-copy`, {
+      method: 'POST',
+      raw: true,
+      body: plainZip,
+      onUploadProgress: uploadProgress(`uploading ${(plainZip.length / 1e6).toFixed(1)}MB plain copy for older builds`),
+      headers: {'content-type': 'application/zip'},
+    });
+    console.log('• plain copy uploaded: older builds get this release too, and Pulsar can read that copy');
+  }
   if (release.approval && !release.approval.approvedAt) {
     console.log(`⏸ waiting for approval: ${deployment} needs a second admin or owner to approve ${release.label} in the dashboard before devices get it`);
   }
@@ -457,22 +481,35 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
   if (release.rolloutRamp) console.log(`  gradual rollout — ${release.rollout}% to ${release.rolloutRamp.to}% over ${release.rolloutRamp.hours}h`);
 
   try {
-    await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/manifest`, {method: 'POST', body: {files: fileManifest(contentsDir)}, optional: true});
+    const files = {files: fileManifest(contentsDir)};
+    const sealedManifest = () => {
+      let modules = null;
+      try {
+        modules = sourcemapPath && fs.existsSync(sourcemapPath) ? JSON.parse(fs.readFileSync(sourcemapPath, 'utf8')).sources || null : null;
+      } catch {
+        modules = null;
+      }
+      return Buffer.from(JSON.stringify(modules ? {...files, modules} : files));
+    };
+    await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/manifest`, sealing
+      ? {method: 'POST', raw: true, optional: true, body: await sealArtifact(privateBundles, app, packageHash, sealedManifest(), 'manifest'), headers: sealedHeaders}
+      : {method: 'POST', body: files, optional: true});
   } catch (err) {
     console.log(`• file list not recorded: ${err.message}`);
   }
   if (sourcemapPath && fs.existsSync(sourcemapPath)) {
     try {
-      const map = fs.readFileSync(sourcemapPath);
+      const plainMap = fs.readFileSync(sourcemapPath);
+      const map = sealing ? Buffer.from(await sealArtifact(privateBundles, app, packageHash, plainMap, 'sourcemap')) : plainMap;
       await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/sourcemap`, {
         method: 'POST',
         raw: true,
         optional: true,
         body: map,
         onUploadProgress: uploadProgress(`uploading ${(map.length / 1e6).toFixed(1)}MB source map`),
-        headers: {'content-type': 'application/json'},
+        headers: sealing ? sealedHeaders : {'content-type': 'application/json'},
       });
-      console.log('• source map uploaded: crash stacks for this release will show your source files');
+      console.log(sealing ? '• source map uploaded, encrypted: unlock it in the dashboard or with pulsar changes' : '• source map uploaded: crash stacks for this release will show your source files');
     } catch (err) {
       console.log(`• source map not uploaded: ${err.message}`);
     }
@@ -481,16 +518,24 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
   if (!args.includes('--no-diff') && prevLatest && prevLatest.packageHash && prevLatest.packageHash !== packageHash) {
     try {
       const {apiUrl} = loadConfig();
-      const baseZip = await fetchBlob(apiUrl, app.id, `${prevLatest.packageHash}.zip`);
+      const baseFile = prevLatest.encrypted && prevLatest.blobKey ? prevLatest.blobKey.slice(app.id.length + 1) : `${prevLatest.packageHash}.zip`;
+      let baseZip = await fetchBlob(apiUrl, app.id, baseFile);
+      if (prevLatest.encrypted) {
+        if (!privateBundles?.keys.length) throw new Error(`${prevLatest.label} is private and no bundle key was given`);
+        baseZip = await openArtifact(privateBundles.keys, baseZip, {appId: app.id, packageHash: prevLatest.packageHash, kind: 'full'});
+      }
       const diffDir = await buildDiffPackage(baseZip, contentsDir);
-      const diffZip = fs.readFileSync(zipContents(diffDir));
+      const plainDiff = fs.readFileSync(zipContents(diffDir));
+      const diffZip = sealing
+        ? Buffer.from(await sealArtifact(privateBundles, app, packageHash, plainDiff, 'diff', {baseHash: prevLatest.packageHash}))
+        : plainDiff;
       await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/diff`, {
         method: 'POST',
         raw: true,
         optional: true,
         body: diffZip,
         onUploadProgress: uploadProgress(`uploading ${(diffZip.length / 1e6).toFixed(1)}MB diff`),
-        headers: {'content-type': 'application/zip', 'x-base-hash': prevLatest.packageHash},
+        headers: {...(sealing ? sealedHeaders : {'content-type': 'application/zip'}), 'x-base-hash': prevLatest.packageHash},
       });
       const saved = Math.round((1 - diffZip.length / zip.length) * 100);
       console.log(`• diff vs ${prevLatest.label}: ${(diffZip.length / 1e3).toFixed(0)} KB (${saved}% smaller)`);
@@ -503,11 +548,23 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
 
 // Build the JS bundle once and return what every target app's release is made from. A local key
 // (--private-key <file>, or PULSAR_SIGNING_KEY holding the key itself) overrides Pulsar's signing.
-function buildOnce(args) {
-  const platform = getFlag(args, 'platform', 'ios');
+function localSigningKey(args) {
   const privateKeyPath = getFlag(args, 'private-key');
   if (privateKeyPath && !fs.existsSync(privateKeyPath)) die(`no signing key at ${privateKeyPath} — drop --private-key to have Pulsar sign`);
-  const localKey = privateKeyPath ? fs.readFileSync(privateKeyPath, 'utf8') : (process.env.PULSAR_SIGNING_KEY || '').trim();
+  return privateKeyPath ? fs.readFileSync(privateKeyPath, 'utf8') : (process.env.PULSAR_SIGNING_KEY || '').trim();
+}
+
+async function checkPrivateBeforeBuild(apps, args) {
+  const localKey = localSigningKey(args);
+  for (const app of apps) {
+    const context = await privateContext(app, args, localKey);
+    if (context) reportReach(context, {mandatory: args.includes('--mandatory'), plainCopy: args.includes('--plain-copy-for-old-builds')});
+  }
+}
+
+function buildOnce(args) {
+  const platform = getFlag(args, 'platform', 'ios');
+  const localKey = localSigningKey(args);
   const contentsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-build-'));
   const sourcemapPath = args.includes('--no-sourcemap') ? null : `${contentsDir}.map`;
   bundle(platform, contentsDir, sourcemapPath);
@@ -518,14 +575,15 @@ function buildOnce(args) {
 
 async function cmdRelease(args) {
   const [nameOrId, deployment = 'Staging'] = args;
-  if (!nameOrId) die('Usage: pulsar release <app> <Staging|Production> --platform ios|android --target <ver> [--mandatory] [--disabled] [--rollout N] [--schedule +6h|ISO] [--ramp 100@48] [--from v6,ota,binary] [--devices id1,id2,...] [--device-models model1;model2] [--users u1,u2] [--private-key key.pem] [--no-diff] [--no-sourcemap] [--max-growth <percent>] [--description "..."]');
+  if (!nameOrId) die('Usage: pulsar release <app> <Staging|Production> --platform ios|android --target <ver> [--mandatory] [--disabled] [--rollout N] [--schedule +6h|ISO] [--ramp 100@48] [--from v6,ota,binary] [--devices id1,id2,...] [--device-models model1;model2] [--users u1,u2] [--private-key key.pem] [--bundle-key key.txt] [--plain-copy-for-old-builds | --plain | --only-older-builds] [--no-diff] [--no-sourcemap] [--max-growth <percent>] [--description "..."]');
   if (!getFlag(args, 'target')) die('--target <binary version> is required (e.g. --target 1.0.0)');
   const app = await resolveApp(nameOrId, getFlag(args, 'platform', 'ios'));
   if (app.os !== getFlag(args, 'platform', 'ios')) {
     console.log(`• note: resolved app "${app.name}" is ${app.os}; bundling ${getFlag(args, 'platform', 'ios')}`);
   }
+  await checkPrivateBeforeBuild([app], args);
   const {contentsDir, packageHash, localKey, sourcemapPath} = buildOnce(args);
-  await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath});
+  await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath, reachReported: true});
 }
 
 // Release the same built bundle to several apps at once (shared-codebase / white-label fleets).
@@ -550,11 +608,12 @@ async function cmdReleaseTrain(args) {
   apps = apps.filter((app) => app.os === platform);
   if (!apps.length) die(`No ${platform} apps matched.`);
 
+  await checkPrivateBeforeBuild(apps, args);
   const {contentsDir, packageHash, localKey, sourcemapPath} = buildOnce(args);
   console.log(`• release train → ${apps.length} app(s): ${apps.map((app) => app.name).join(', ')}`);
   for (const app of apps) {
     try {
-      await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath});
+      await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath, reachReported: true});
     } catch (err) {
       console.log(`✗ ${app.name}: ${err.message}`);
     }
@@ -601,7 +660,8 @@ async function cmdHistory(args) {
   const releases = await api(`/apps/${app.id}/deployments/${deployment}/releases`);
   if (!releases.length) return console.log('(no releases)');
   for (const release of [...releases].reverse()) {
-    const flags = `${release.isMandatory ? ' [mandatory]' : ''}${release.isDisabled ? ' [disabled]' : ''}`;
+    const privacy = release.encrypted ? ` [private${release.plainCopy ? ' + plain copy' : ''}]` : release.olderBuildsOnly ? ' [plain, older builds only]' : release.plainOnPurpose ? ' [plain]' : '';
+    const flags = `${release.isMandatory ? ' [mandatory]' : ''}${release.isDisabled ? ' [disabled]' : ''}${privacy}`;
     const rollout = release.currentRollout ?? release.rollout;
     const state = release.state && release.state !== 'live' ? ` [${release.state}]` : '';
     const when = release.startsAt ? ` starts ${new Date(release.startsAt).toLocaleString()}` : '';
@@ -683,7 +743,7 @@ async function cmdKeys(args) {
   console.log(`✓ wrote ${Object.keys(vars).length} key(s) to ${target} (${written.size} updated, ${missing.length} added)`);
 }
 
-export {saveConfig, browserLogin, signCodePushJWT, SIGNATURE_PATH, api, die, getFlag, loadConfig, pushBuiltRelease, splitList};
+export {saveConfig, browserLogin, signCodePushJWT, SIGNATURE_PATH, api, die, getFlag, loadConfig, pushBuiltRelease, splitList, resolveApp};
 
 // Only dispatch when run as the CLI — importing the module (e.g. from tests) must not execute a command.
 // Compare real paths: a global install runs through a bin symlink, so argv[1] is not this file's path.
@@ -709,6 +769,8 @@ if (invokedAsCli()) {
     patch: cmdPatch,
     keygen: cmdKeygen,
     keys: cmdKeys,
+    'bundle-key': cmdBundleKey,
+    changes: cmdChanges,
     migrate,
   };
 
@@ -719,7 +781,7 @@ if (invokedAsCli()) {
   }
 
   (commands[command] || (() => {
-    console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen|migrate>');
+    console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen|bundle-key|changes|migrate>');
     process.exit(command ? 1 : 0);
   }))(rest);
 }

package/releaseCompare.js

@@ -0,0 +1,45 @@
+const LIST_LIMIT = 200;
+
+export function compareManifests(before, after) {
+  const added = [];
+  const removed = [];
+  const modified = [];
+  let unchanged = 0;
+  for (const [filePath, entry] of Object.entries(after)) {
+    const previous = before[filePath];
+    if (!previous) added.push({path: filePath, size: entry.size});
+    else if (previous.hash !== entry.hash) modified.push({path: filePath, before: previous.size, after: entry.size});
+    else unchanged += 1;
+  }
+  for (const [filePath, entry] of Object.entries(before)) if (!after[filePath]) removed.push({path: filePath, size: entry.size});
+  const total = (manifest) => Object.values(manifest).reduce((sum, entry) => sum + entry.size, 0);
+  const bySize = (left, right) => (right.size ?? Math.abs(right.after - right.before)) - (left.size ?? Math.abs(left.after - left.before));
+  return {
+    added: added.sort(bySize).slice(0, LIST_LIMIT),
+    removed: removed.sort(bySize).slice(0, LIST_LIMIT),
+    modified: modified.sort(bySize).slice(0, LIST_LIMIT),
+    counts: {added: added.length, removed: removed.length, modified: modified.length, unchanged},
+    size: {before: total(before), after: total(after)},
+  };
+}
+
+export const moduleName = (source) => {
+  const text = String(source || '');
+  const match = /(?:^|\/)(node_modules\/.*)$/.exec(text) || /(?:^|\/)(src\/.*)$/.exec(text);
+  return match ? match[1] : text.replace(/^.*\/(?=[^/]+\/[^/]+$)/, '');
+};
+
+export function compareModules(beforeSources, afterSources) {
+  const before = new Set((beforeSources || []).map(moduleName));
+  const after = new Set((afterSources || []).map(moduleName));
+  const added = [...after].filter((name) => !before.has(name));
+  const removed = [...before].filter((name) => !after.has(name));
+  return {added: added.slice(0, LIST_LIMIT), removed: removed.slice(0, LIST_LIMIT), counts: {added: added.length, removed: removed.length}};
+}
+
+export function manifestParts(document) {
+  if (document?.files && typeof document.files === 'object' && !Array.isArray(document.files)) {
+    return {files: document.files, modules: Array.isArray(document.modules) ? document.modules : null};
+  }
+  return {files: document || null, modules: null};
+}