@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/tools/migrate-key-to-dpapi.js

@@ -0,0 +1,386 @@
+'use strict';
+
+/**
+ * In-place upgrade of an installation key from the plaintext `file://` tier to
+ * the DPAPI-wrapped `dpapi://` tier.
+ *
+ *   node tools/migrate-key-to-dpapi.js --config C:/ProgramData/MeteorLive/installation.json
+ *
+ * The key does not change: the same P-256 private key ends up wrapped by DPAPI
+ * instead of sitting in a PEM, so the public key the server already trusts stays
+ * valid, `installation_uid` stays valid, and nothing has to be re-bound. Only
+ * `key_reference` moves.
+ *
+ * Flags:
+ *   --config <path>        installation config to migrate (required)
+ *   --backend <module-id>  DPAPI binding to load; default '@meteorlive/dpapi'.
+ *                          A path (relative or absolute) is resolved against the
+ *                          cwd, which is how the tests inject a fake binding.
+ *   --entropy-hex <hex>    optional secondary entropy. It is stored nowhere: every
+ *                          later open of the key must supply the same bytes as
+ *                          `dpapi: { entropy }`, or the key is unreadable forever.
+ *
+ * The step order below is the safety design, not a preference. Nothing is written
+ * until the existing key has been read and parsed; the config is not touched
+ * until the freshly wrapped key has produced a signature that verifies against
+ * the *old* public key; and the plaintext PEM is not destroyed until the config
+ * has stopped pointing at it. Every failure before the config is saved rolls the
+ * new file back and leaves the installation exactly as it was.
+ */
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const { MeteorCloudError, fail } = require('../lib/errors');
+const { loadInstallationConfig, saveInstallationConfig } = require('../lib/config');
+const {
+  DpapiKeyStore,
+  FileKeyStore,
+  parseKeyReference,
+  keyReferenceFor,
+  DPAPI_MODULE
+} = require('../lib/keystore');
+const { jwkThumbprint } = require('../lib/jose');
+const { writeFileDurable } = require('../lib/durable');
+
+/** The members `p256PublicJwk` emits, in RFC 7638 order. */
+const JWK_FIELDS = Object.freeze(['crv', 'kty', 'x', 'y']);
+
+const USAGE =
+  'usage: node tools/migrate-key-to-dpapi.js --config <installation.json> ' +
+  '[--backend <module-id>] [--entropy-hex <hex>]';
+
+/**
+ * `installation.key.pem` -> `installation.key.dpapi`, the pair of names the
+ * README and the integration guide already use for the two tiers. The suffix is
+ * cosmetic — `keyReference` is what selects the store — but a `.pem` file
+ * holding a DPAPI blob is a support call waiting to happen.
+ */
+function dpapiTargetPathFor(sourcePath) {
+  const resolved = path.resolve(sourcePath);
+  const stem = resolved.toLowerCase().endsWith('.pem') ? resolved.slice(0, -4) : resolved;
+  return `${stem}.dpapi`;
+}
+
+function parseEntropyHex(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  // The value itself is secret-shaped, so it is never echoed back in the error.
+  if (typeof value !== 'string' || !/^(?:[0-9a-fA-F]{2})+$/.test(value)) {
+    fail('--entropy-hex must be a non-empty hex string with an even number of digits');
+  }
+  return Buffer.from(value, 'hex');
+}
+
+/**
+ * Resolves the DPAPI binding. An injected `backend` object wins; otherwise the
+ * module id is required, which on a non-Windows host can only ever be a stand-in
+ * supplied by the caller — the real CryptProtectData does not exist there, and
+ * silently "migrating" with a fake would produce a key no Windows machine can
+ * open.
+ */
+function resolveBackend(options) {
+  let backend = options.backend;
+  if (!backend) {
+    const moduleId = options.backendModule || DPAPI_MODULE;
+    if (moduleId === DPAPI_MODULE && process.platform !== 'win32') {
+      fail(
+        `${DPAPI_MODULE} wraps a Windows-only API; run this tool on the Windows machine ` +
+          'that holds the key, or pass --backend <module-id> to supply your own binding',
+        { kind: 'keystore' }
+      );
+    }
+    const target = /^[./\\]/.test(moduleId) || path.isAbsolute(moduleId) ? path.resolve(moduleId) : moduleId;
+    try {
+      // eslint-disable-next-line global-require, import/no-dynamic-require
+      backend = require(target);
+    } catch (cause) {
+      throw new MeteorCloudError(
+        `cannot load the DPAPI backend ${moduleId}; install it next to the SDK ` +
+          '(npm install @meteorlive/dpapi) or point --backend at your own binding',
+        { kind: 'keystore', cause }
+      );
+    }
+  }
+  // Same gate DpapiKeyStore applies: a half-implemented binding must fail here,
+  // not as "protectData is not a function" with a key already half-migrated.
+  if (typeof backend.protectData !== 'function' || typeof backend.unprotectData !== 'function') {
+    fail(`${DPAPI_MODULE} does not implement protectData/unprotectData`, { kind: 'keystore' });
+  }
+  return backend;
+}
+
+/**
+ * Mirrors `writeNewKeyFile` in lib/keystore.js: mode 0600, and 'wx' so an
+ * existing file is never overwritten. The refusal matters more here than at
+ * bind time — the file already sitting there could be the only copy of another
+ * live installation's key.
+ */
+async function writeWrappedKey(filePath, wrapped) {
+  try {
+    // Durable before anything is allowed to touch the PEM. This used to be a
+    // plain writeFile while the *shred* was the only fsync in the SDK, so a
+    // power cut just after a successful migration could make the destruction
+    // stick and the replacement evaporate. See lib/durable.js.
+    await writeFileDurable(filePath, wrapped, { mode: 0o600, flag: 'wx' });
+  } catch (cause) {
+    if (cause && cause.code === 'EEXIST') {
+      fail(
+        `a key already exists at ${filePath}; inspect it and move it aside before ` +
+          'migrating, so an installation that still depends on it is not destroyed',
+        { kind: 'keystore' }
+      );
+    }
+    throw new MeteorCloudError('cannot write the DPAPI-wrapped installation key', {
+      kind: 'keystore',
+      cause
+    });
+  }
+  if (process.platform !== 'win32') await fsp.chmod(filePath, 0o600);
+}
+
+/**
+ * Overwrites the plaintext key with zeros, flushes, then unlinks. Best effort by
+ * construction: on a copy-on-write or flash-translated filesystem the old blocks
+ * may survive, and a backup taken before the migration certainly does. Treat the
+ * PEM as compromised-if-copied rather than as erased.
+ */
+async function shredPlaintextKey(filePath) {
+  let handle;
+  try {
+    handle = await fsp.open(filePath, 'r+');
+    const { size } = await handle.stat();
+    if (size > 0) await handle.write(Buffer.alloc(size), 0, size, 0);
+    await handle.sync();
+  } catch (_) {
+    /* best effort: the unlink below is what actually has to happen */
+  } finally {
+    if (handle) {
+      try {
+        await handle.close();
+      } catch (_) {
+        /* best effort */
+      }
+    }
+  }
+  try {
+    await fsp.rm(filePath, { force: true });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Proves the wrapped key is the same key, before anything irreversible happens.
+ *
+ * Two independent checks: the public JWK must come back field for field, and a
+ * signature produced through the DPAPI store must verify against the public key
+ * derived from the *original* PEM. The first catches a backend that returned
+ * some other key's bytes; the second catches a wrap/unwrap path that produces a
+ * structurally valid but different key.
+ */
+async function verifyMigratedKey(keyStore, keyReference, originalJwk) {
+  const migratedJwk = await keyStore.publicJwk(keyReference);
+  for (const field of JWK_FIELDS) {
+    if (migratedJwk[field] !== originalJwk[field]) {
+      fail(
+        'the DPAPI-wrapped key does not carry the same public key as the PEM; ' +
+          'the plaintext key and the config were left untouched',
+        { kind: 'keystore' }
+      );
+    }
+  }
+  const challenge = crypto.randomBytes(32);
+  const signature = await keyStore.sign(keyReference, challenge);
+  const publicKey = crypto.createPublicKey({ key: originalJwk, format: 'jwk' });
+  const verified = crypto.verify(
+    'sha256',
+    challenge,
+    { key: publicKey, dsaEncoding: 'ieee-p1363' },
+    signature
+  );
+  if (!verified) {
+    fail(
+      'a signature from the DPAPI-wrapped key does not verify against the original ' +
+        'public key; the plaintext key and the config were left untouched',
+      { kind: 'keystore' }
+    );
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.configPath   installation config to migrate
+ * @param {object} [options.backend]    DPAPI binding, injected directly
+ * @param {string} [options.backendModule]  module id to require instead
+ * @param {Buffer} [options.entropy]    secondary entropy for protect/unprotect
+ * @param {(line: string) => void} [options.log]
+ * @returns {Promise<object>} a summary carrying paths and public fingerprints only
+ */
+async function migrateKeyToDpapi(options = {}) {
+  const { configPath } = options;
+  if (typeof configPath !== 'string' || !configPath) fail('configPath is required');
+  const log = typeof options.log === 'function' ? options.log : () => {};
+  const entropy = options.entropy;
+
+  // 1. Load, and decide whether there is anything to do. An unsupported scheme
+  //    (windows-cng://) is already refused by loadInstallationConfig, with the
+  //    message that names the tier.
+  const config = await loadInstallationConfig(configPath);
+  const { scheme, path: sourcePath } = parseKeyReference(config.keyReference);
+  if (scheme === 'dpapi') {
+    log(`nothing to do: ${configPath} already uses the dpapi tier`);
+    log(`key_reference     ${config.keyReference}`);
+    return {
+      status: 'noop',
+      configPath,
+      keyReference: config.keyReference,
+      keyPath: sourcePath,
+      installationUid: config.installationUid
+    };
+  }
+  if (scheme !== 'file') {
+    fail(`cannot migrate a ${scheme}:// key reference; this tool upgrades file:// keys only`, {
+      kind: 'keystore'
+    });
+  }
+
+  const targetPath = dpapiTargetPathFor(sourcePath);
+  if (targetPath === sourcePath) {
+    fail(
+      `the plaintext key is already named ${sourcePath}, which is where the wrapped key ` +
+        'would go; rename it (for example to installation.key.pem) and retry',
+      { kind: 'keystore' }
+    );
+  }
+
+  // 2. Read the existing key. FileKeyStore.publicJwk runs the full file check
+  //    (regular file, plausible size, mode 0600, parses as P-256), so a key that
+  //    is already broken fails here rather than half way through a migration.
+  const originalJwk = await new FileKeyStore().publicJwk(config.keyReference);
+  const pem = await fsp.readFile(sourcePath);
+  let privateKey;
+  try {
+    privateKey = crypto.createPrivateKey(pem);
+  } catch (cause) {
+    throw new MeteorCloudError('installation key is not a usable PKCS#8 private key', {
+      kind: 'keystore',
+      cause
+    });
+  } finally {
+    pem.fill(0);
+  }
+
+  const der = privateKey.export({ type: 'pkcs8', format: 'der' });
+  let backend;
+  let wrapped;
+  try {
+    // 3. Resolve the binding. Never reached on a non-Windows host without an
+    //    explicit --backend.
+    backend = resolveBackend(options);
+    // 4a. Wrap.
+    try {
+      wrapped = backend.protectData(der, entropy);
+    } catch (cause) {
+      throw new MeteorCloudError('the DPAPI backend refused to protect the installation key', {
+        kind: 'keystore',
+        cause
+      });
+    }
+    if (!Buffer.isBuffer(wrapped) || wrapped.length === 0) {
+      fail('the DPAPI backend returned an empty blob', { kind: 'keystore' });
+    }
+  } finally {
+    der.fill(0);
+  }
+
+  const keyStore = new DpapiKeyStore({ backend, entropy });
+  const keyReference = keyReferenceFor('dpapi', targetPath);
+  let wroteTarget = false;
+  try {
+    // 4b. Write, refusing to clobber.
+    await writeWrappedKey(targetPath, wrapped);
+    wroteTarget = true;
+    // 5. Prove it is the same key before anything can be lost.
+    await verifyMigratedKey(keyStore, keyReference, originalJwk);
+    // 6a. Flip the config atomically. Up to this line every failure is a
+    //     no-change failure; after it, the new key is the installation's key.
+    await saveInstallationConfig(configPath, { ...config, keyReference });
+  } catch (error) {
+    if (wroteTarget) {
+      try {
+        await fsp.rm(targetPath, { force: true });
+      } catch (_) {
+        /* best effort: the config still points at the untouched PEM */
+      }
+    }
+    throw error;
+  }
+
+  // 6b. Only now is the plaintext copy redundant.
+  const plaintextKeyRemoved = await shredPlaintextKey(sourcePath);
+
+  // 7. Summary. Paths and a public-key fingerprint only — no key bytes, ever.
+  const thumbprint = jwkThumbprint(originalJwk);
+  log(`migrated ${configPath}`);
+  log(`installation      ${config.installationUid}`);
+  log(`key was           ${sourcePath}`);
+  log(`key now           ${targetPath}`);
+  log(`key_reference     ${keyReference}`);
+  log(`public key        unchanged, JWK thumbprint ${thumbprint} — no re-bind needed`);
+  log(
+    plaintextKeyRemoved
+      ? 'plaintext PEM     zeroed and deleted (best effort; SSDs and backups may retain blocks)'
+      : `plaintext PEM     COULD NOT BE DELETED — remove ${sourcePath} yourself`
+  );
+  if (entropy) {
+    log('entropy           required from now on: pass the same bytes as dpapi.entropy, or the key is unreadable');
+  }
+
+  return {
+    status: 'migrated',
+    configPath,
+    installationUid: config.installationUid,
+    previousKeyReference: config.keyReference,
+    keyReference,
+    previousKeyPath: sourcePath,
+    keyPath: targetPath,
+    publicJwkThumbprint: thumbprint,
+    plaintextKeyRemoved,
+    entropyRequired: Boolean(entropy)
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const match = argv[i].match(/^--([a-z-]+)(?:=(.*))?$/);
+    if (!match) continue;
+    args[match[1]] = match[2] !== undefined ? match[2] : argv[++i];
+  }
+  return args;
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (!args.config) fail(USAGE);
+  await migrateKeyToDpapi({
+    configPath: path.resolve(args.config),
+    backendModule: args.backend,
+    entropy: parseEntropyHex(args['entropy-hex']),
+    // eslint-disable-next-line no-console
+    log: (line) => console.log(line)
+  });
+}
+
+module.exports = { migrateKeyToDpapi, dpapiTargetPathFor, parseEntropyHex, parseArgs };
+
+if (require.main === module) {
+  main(process.argv.slice(2)).catch((error) => {
+    const safe = error && typeof error.toSafeObject === 'function' ? error.toSafeObject() : error;
+    // eslint-disable-next-line no-console
+    console.error(`migration failed: ${(safe && safe.message) || error}`);
+    process.exitCode = 1;
+  });
+}