@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/lib/keystore.js

@@ -0,0 +1,585 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { pathToFileURL, fileURLToPath } = require('node:url');
+
+const { MeteorCloudError, fail } = require('./errors');
+const { p256PublicJwk } = require('./jose');
+const { writeFileDurable } = require('./durable');
+
+const DPAPI_MODULE = '@meteorlive/dpapi';
+const MAX_KEY_FILE_SIZE = 16 * 1024;
+
+/**
+ * Where an installation's private key lives, and the only three things the SDK
+ * is ever allowed to ask of it.
+ *
+ * The interface deliberately has no `exportPrivateKey`. `sign()` takes bytes and
+ * returns a signature, which is the exact shape a Windows CNG persisted key
+ * (`NCryptSignHash` against a non-exportable handle) can satisfy. Every backend
+ * below is a stepping stone to that one; none of them may widen the interface.
+ *
+ * `keyReference` is a URI so that a config file written by one tier can be read
+ * by a client that supports a different set of tiers and fail loudly rather than
+ * silently reaching for the wrong key:
+ *
+ *   file://<abs path>          PKCS#8 PEM on disk, mode 0600            (dev / non-Windows)
+ *   dpapi://<abs path>         DPAPI CurrentUser-wrapped PKCS#8 DER     (Windows default)
+ *   cng://<container>          non-exportable CNG key handle            (Windows, strongest)
+ *
+ * `cng://` is spelled exactly as the C++ SDK spells it, and its containers live
+ * in the same `meteorlive/` namespace, because the installation config is a
+ * cross-SDK wire contract (see test/storage.test.js). A config written by one
+ * SDK has to be readable by the other; a Node-only `windows-cng://` spelling,
+ * which is what this comment used to reserve, would have split them.
+ */
+class KeyStore {
+  /** @returns {string} the URI scheme this store owns, without the colon. */
+  get scheme() {
+    throw new MeteorCloudError('KeyStore.scheme is not implemented', { kind: 'keystore' });
+  }
+
+  /**
+   * Creates a fresh P-256 key and returns its `keyReference` URI.
+   * Must refuse to overwrite an existing key: silently replacing one would
+   * orphan a live installation whose public key the server still trusts.
+   */
+  // eslint-disable-next-line no-unused-vars
+  async create(name) {
+    throw new MeteorCloudError('KeyStore.create is not implemented', { kind: 'keystore' });
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  async publicJwk(keyReference) {
+    throw new MeteorCloudError('KeyStore.publicJwk is not implemented', { kind: 'keystore' });
+  }
+
+  /** @returns {Promise<Buffer>} 64-byte IEEE P1363 ECDSA signature over `data`. */
+  // eslint-disable-next-line no-unused-vars
+  async sign(keyReference, data) {
+    throw new MeteorCloudError('KeyStore.sign is not implemented', { kind: 'keystore' });
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  async exists(keyReference) {
+    throw new MeteorCloudError('KeyStore.exists is not implemented', { kind: 'keystore' });
+  }
+
+  /**
+   * Destroys the local key. This does NOT revoke the installation — the server
+   * still holds the public key until the user revokes it on the web console.
+   */
+  // eslint-disable-next-line no-unused-vars
+  async destroy(keyReference) {
+    throw new MeteorCloudError('KeyStore.destroy is not implemented', { kind: 'keystore' });
+  }
+}
+
+function parseKeyReference(keyReference) {
+  if (typeof keyReference !== 'string' || !keyReference) fail('keyReference is required');
+  let parsed;
+  try {
+    parsed = new URL(keyReference);
+  } catch (cause) {
+    throw new MeteorCloudError('keyReference is not a valid URI', { kind: 'validation', cause });
+  }
+  const scheme = parsed.protocol.replace(/:$/, '');
+  if (scheme === 'file' || scheme === 'dpapi') {
+    // Both forms use an empty authority: `<scheme>:///<abs path>`. A non-empty
+    // host would be a UNC-style reference to another machine, which is never
+    // what a local key store means.
+    if (parsed.host) fail('keyReference must use an empty authority (three slashes)');
+    let filePath;
+    try {
+      // The WHATWG protocol setter refuses to convert between a special scheme
+      // (`file:`) and a non-special one (`dpapi:`) — assigning it is a silent
+      // no-op. Rebuilding the href as a string is the only conversion that works,
+      // and getting this wrong would resolve a DPAPI-wrapped key as plain PEM.
+      filePath = fileURLToPath(new URL(`file://${parsed.pathname}`));
+    } catch (cause) {
+      throw new MeteorCloudError('keyReference does not resolve to an absolute path', {
+        kind: 'validation',
+        cause
+      });
+    }
+    if (!path.isAbsolute(filePath)) fail('keyReference path must be absolute');
+    return { scheme, path: filePath };
+  }
+  if (scheme === 'cng') {
+    // A container name, not a path: nothing here ever reaches the filesystem,
+    // which is the entire point of the tier. `new URL('cng://meteorlive/x')`
+    // puts "meteorlive" in host and "/x" in pathname, so the container is
+    // reassembled rather than read off one field.
+    const container = `${parsed.host}${parsed.pathname}`;
+    if (!/^meteorlive\/[A-Za-z0-9._-]{1,128}$/.test(container)) {
+      fail(
+        'a cng:// keyReference must name a container under meteorlive/, ' +
+          'e.g. cng://meteorlive/<id>',
+        { kind: 'keystore' }
+      );
+    }
+    return { scheme, container };
+  }
+  if (scheme === 'windows-cng') {
+    // Only ever appeared in 0.3-era documentation as a reserved name; no
+    // release ever wrote one. Named explicitly so anyone who typed it from
+    // those docs is sent to the spelling both SDKs actually use.
+    fail(
+      'windows-cng:// was never implemented; the non-exportable tier is spelled ' +
+        'cng://meteorlive/<id>, the same as in the C++ SDK',
+      { kind: 'keystore' }
+    );
+  }
+  fail(`unsupported keyReference scheme: ${scheme}`, { kind: 'keystore' });
+}
+
+function keyReferenceFor(scheme, filePath) {
+  const fileUrl = pathToFileURL(path.resolve(filePath)).toString();
+  if (scheme === 'file') return fileUrl;
+  // See parseKeyReference: `url.protocol = 'dpapi:'` on a file: URL does nothing
+  // at all, so the scheme is swapped textually.
+  return `${scheme}://${fileUrl.slice('file://'.length)}`;
+}
+
+async function readKeyFile(filePath) {
+  let stat;
+  try {
+    stat = await fsp.lstat(filePath);
+  } catch (cause) {
+    throw new MeteorCloudError('installation key is missing; re-run the bind flow', {
+      kind: 'keystore',
+      cause
+    });
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    fail('installation key must be a regular file', { kind: 'keystore' });
+  }
+  if (stat.size < 1 || stat.size > MAX_KEY_FILE_SIZE) {
+    fail('installation key file size is implausible', { kind: 'keystore' });
+  }
+  if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+    // POSIX permission bits are meaningless on Windows (ACLs are the real
+    // control), so the check is skipped there rather than reported as a pass.
+    fail('installation key is readable by group or other; expected mode 0600', {
+      kind: 'keystore'
+    });
+  }
+  try {
+    return await fsp.readFile(filePath);
+  } catch (cause) {
+    throw new MeteorCloudError('cannot read installation key', { kind: 'keystore', cause });
+  }
+}
+
+async function writeNewKeyFile(filePath, contents) {
+  try {
+    // 'wx' rather than 'w': overwriting would destroy the private half of an
+    // installation the server still considers active. Durable because a key
+    // that is only in the page cache is a key a power cut can take away, and
+    // this one cannot be regenerated — see lib/durable.js.
+    await writeFileDurable(filePath, contents, { mode: 0o600, flag: 'wx' });
+  } catch (cause) {
+    if (cause && cause.code === 'EEXIST') {
+      fail('a key already exists at this reference; destroy it explicitly before rebinding', {
+        kind: 'keystore'
+      });
+    }
+    throw new MeteorCloudError('cannot write installation key', { kind: 'keystore', cause });
+  }
+  if (process.platform !== 'win32') await fsp.chmod(filePath, 0o600);
+}
+
+function signWithPrivateKey(privateKey, data) {
+  // 'ieee-p1363' is what makes this a JOSE ES256 signature. The Node default is
+  // DER, which verifies fine with OpenSSL and fails every JWT library on earth.
+  return crypto.sign('sha256', data, { key: privateKey, dsaEncoding: 'ieee-p1363' });
+}
+
+/**
+ * Tier 2 (dev / non-Windows): PKCS#8 PEM at `file://<path>`, mode 0600.
+ *
+ * The honest threat model: this protects against nothing but other local users.
+ * Copying the file to another machine yields a working installation identity.
+ * It exists so the SDK is testable and usable on macOS/Linux CI, and so the
+ * bind flow can be exercised without a native module. Windows production
+ * deployments must use `dpapi://` (or CNG once it lands).
+ */
+class FileKeyStore extends KeyStore {
+  get scheme() {
+    return 'file';
+  }
+
+  async create(name) {
+    const filePath = path.resolve(name);
+    const { privateKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
+    const pem = privateKey.export({ type: 'pkcs8', format: 'pem' });
+    await writeNewKeyFile(filePath, pem);
+    return keyReferenceFor('file', filePath);
+  }
+
+  async _privateKey(keyReference) {
+    const { scheme, path: filePath } = parseKeyReference(keyReference);
+    if (scheme !== 'file') fail(`FileKeyStore cannot handle ${scheme}:// references`, { kind: 'keystore' });
+    const pem = await readKeyFile(filePath);
+    try {
+      return crypto.createPrivateKey(pem);
+    } catch (cause) {
+      throw new MeteorCloudError('installation key is not a usable PKCS#8 private key', {
+        kind: 'keystore',
+        cause
+      });
+    }
+  }
+
+  async publicJwk(keyReference) {
+    return p256PublicJwk(await this._privateKey(keyReference));
+  }
+
+  async sign(keyReference, data) {
+    return signWithPrivateKey(await this._privateKey(keyReference), data);
+  }
+
+  async exists(keyReference) {
+    const { path: filePath } = parseKeyReference(keyReference);
+    try {
+      const stat = await fsp.lstat(filePath);
+      return stat.isFile() && !stat.isSymbolicLink();
+    } catch (_) {
+      return false;
+    }
+  }
+
+  async destroy(keyReference) {
+    const { path: filePath } = parseKeyReference(keyReference);
+    try {
+      await fsp.rm(filePath, { force: true });
+    } catch (cause) {
+      throw new MeteorCloudError('cannot destroy installation key', { kind: 'keystore', cause });
+    }
+  }
+}
+
+/**
+ * Tier 1 (Windows default): PKCS#8 DER wrapped with DPAPI
+ * `CryptProtectData(CRYPTPROTECT_UI_FORBIDDEN, CurrentUser)` at `dpapi://<path>`.
+ *
+ * The optional peer module `@meteorlive/dpapi` ships in this repository and
+ * exports exactly:
+ *
+ *   protectData(plaintext: Buffer, entropy?: Buffer): Buffer
+ *   unprotectData(ciphertext: Buffer, entropy?: Buffer): Buffer
+ *
+ * i.e. a thin binding over CryptProtectData / CryptUnprotectData with the
+ * CurrentUser scope. Nothing here shells out: a `powershell -Command` bridge
+ * would put PKCS#8 bytes on a command line and into the process table, which is
+ * a worse exposure than the plaintext file it is trying to replace.
+ *
+ * A future `windows-cng://` store may call NCryptSignHash against a
+ * non-exportable handle. That does not require a contract change because
+ * `key_reference` already carries the tier.
+ */
+class DpapiKeyStore extends KeyStore {
+  constructor(options = {}) {
+    super();
+    // Injectable so the interface, error path and wrapping round-trip are all
+    // testable on a machine that has no DPAPI at all.
+    this._backend = options.backend;
+    this._entropy = options.entropy;
+  }
+
+  get scheme() {
+    return 'dpapi';
+  }
+
+  _dpapi() {
+    let backend = this._backend;
+    if (!backend) {
+      if (process.platform !== 'win32') {
+        fail('dpapi:// key references are only usable on Windows', { kind: 'keystore' });
+      }
+      try {
+        // eslint-disable-next-line global-require, import/no-unresolved
+        backend = require(DPAPI_MODULE);
+      } catch (cause) {
+        throw new MeteorCloudError(
+          `optional peer dependency ${DPAPI_MODULE} is not installed; ` +
+            `install it to use dpapi:// key storage, or bind with a file:// keyReference`,
+          { kind: 'keystore', cause }
+        );
+      }
+    }
+    // Checked on every resolution, including an injected backend: a partial
+    // implementation must fail here rather than at `protectData is not a
+    // function` somewhere deep inside a bind.
+    if (typeof backend.protectData !== 'function' || typeof backend.unprotectData !== 'function') {
+      fail(`${DPAPI_MODULE} does not implement protectData/unprotectData`, { kind: 'keystore' });
+    }
+    this._backend = backend;
+    return backend;
+  }
+
+  async create(name) {
+    const filePath = path.resolve(name);
+    const backend = this._dpapi();
+    const { privateKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
+    const der = privateKey.export({ type: 'pkcs8', format: 'der' });
+    let wrapped;
+    try {
+      wrapped = backend.protectData(der, this._entropy);
+    } catch (cause) {
+      throw new MeteorCloudError('DPAPI refused to protect the installation key', {
+        kind: 'keystore',
+        cause
+      });
+    } finally {
+      der.fill(0);
+    }
+    if (!Buffer.isBuffer(wrapped) || wrapped.length === 0) {
+      fail('DPAPI backend returned an empty blob', { kind: 'keystore' });
+    }
+    await writeNewKeyFile(filePath, wrapped);
+    return keyReferenceFor('dpapi', filePath);
+  }
+
+  async _privateKey(keyReference) {
+    const { scheme, path: filePath } = parseKeyReference(keyReference);
+    if (scheme !== 'dpapi') fail(`DpapiKeyStore cannot handle ${scheme}:// references`, { kind: 'keystore' });
+    const backend = this._dpapi();
+    const wrapped = await readKeyFile(filePath);
+    let der;
+    try {
+      der = backend.unprotectData(wrapped, this._entropy);
+    } catch (cause) {
+      throw new MeteorCloudError(
+        'DPAPI could not unprotect the installation key; the key was created by a ' +
+          'different Windows user or on a different machine — re-run the bind flow',
+        { kind: 'keystore', cause }
+      );
+    }
+    try {
+      return crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+    } catch (cause) {
+      throw new MeteorCloudError('unprotected installation key is not valid PKCS#8', {
+        kind: 'keystore',
+        cause
+      });
+    } finally {
+      if (Buffer.isBuffer(der)) der.fill(0);
+    }
+  }
+
+  async publicJwk(keyReference) {
+    return p256PublicJwk(await this._privateKey(keyReference));
+  }
+
+  async sign(keyReference, data) {
+    return signWithPrivateKey(await this._privateKey(keyReference), data);
+  }
+
+  async exists(keyReference) {
+    const { path: filePath } = parseKeyReference(keyReference);
+    try {
+      const stat = await fsp.lstat(filePath);
+      return stat.isFile() && !stat.isSymbolicLink();
+    } catch (_) {
+      return false;
+    }
+  }
+
+  async destroy(keyReference) {
+    const { path: filePath } = parseKeyReference(keyReference);
+    try {
+      await fsp.rm(filePath, { force: true });
+    } catch (cause) {
+      throw new MeteorCloudError('cannot destroy installation key', { kind: 'keystore', cause });
+    }
+  }
+}
+
+
+const CNG_MODULE = '@meteorlive/cng';
+
+/**
+ * Tier 0 — a P-256 key that lives inside the Windows CNG key storage provider
+ * and is created non-exportable.
+ *
+ * The difference from `dpapi://` is worth stating plainly, because both are
+ * "the OS protects the key" and only one of them survives an attacker who owns
+ * this process. DPAPI stops the key being readable *on disk*: to sign, the SDK
+ * asks Windows to unwrap it, and for that moment the private bytes are in
+ * Node's heap. Here they are never anywhere — the key is generated inside the
+ * KSP with `NCRYPT_EXPORT_POLICY = 0` set before finalize, and every signature
+ * is produced by `NCryptSignHash` inside the provider.
+ *
+ * What that does and does not buy: an attacker holding the user's token can
+ * still ask the KSP to sign for as long as they hold it. What they cannot do is
+ * take the key away and sign later, elsewhere, forever. Revoking the
+ * installation ends the first; nothing ends the second.
+ *
+ * The backend is injectable for the same reason DpapiKeyStore's is — so the
+ * whole path is testable on a machine with no CNG at all.
+ */
+class CngKeyStore extends KeyStore {
+  constructor(options = {}) {
+    super();
+    this._backend = options.backend;
+  }
+
+  get scheme() {
+    return 'cng';
+  }
+
+  _cng() {
+    let backend = this._backend;
+    if (!backend) {
+      if (process.platform !== 'win32') {
+        fail('cng:// key references are only usable on Windows', { kind: 'keystore' });
+      }
+      try {
+        // eslint-disable-next-line global-require, import/no-unresolved
+        backend = require(CNG_MODULE);
+      } catch (cause) {
+        throw new MeteorCloudError(
+          `optional peer dependency ${CNG_MODULE} is not installed; ` +
+            `install it to use cng:// key storage, or bind with a dpapi:// keyReference`,
+          { kind: 'keystore', cause }
+        );
+      }
+    }
+    for (const name of ['createKey', 'publicKeyBlob', 'signDigest', 'keyExists', 'deleteKey']) {
+      if (typeof backend[name] !== 'function') {
+        fail(`${CNG_MODULE} does not implement ${name}`, { kind: 'keystore' });
+      }
+    }
+    this._backend = backend;
+    return backend;
+  }
+
+  /**
+   * `name` is the container's leaf, not a path — this tier never touches the
+   * filesystem. connect() passes the same locally generated id it would have
+   * used as a filename, so a caller that hands over a path gets its basename.
+   */
+  async create(name) {
+    const leaf = String(name || '').replace(/^.*[\\/]/, '');
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(leaf)) {
+      fail('a cng:// key name must be 1-128 characters of [A-Za-z0-9._-]', { kind: 'keystore' });
+    }
+    const container = `meteorlive/${leaf}`;
+    const backend = this._cng();
+    // Refuses rather than overwrites, in the addon: replacing a container would
+    // destroy the private half of an installation the server still trusts.
+    backend.createKey(container);
+    return `cng://${container}`;
+  }
+
+  _container(keyReference) {
+    const { scheme, container } = parseKeyReference(keyReference);
+    if (scheme !== 'cng') fail(`CngKeyStore cannot handle ${scheme}:// references`, { kind: 'keystore' });
+    return container;
+  }
+
+  async publicJwk(keyReference) {
+    const backend = this._cng();
+    const blob = backend.publicKeyBlob(this._container(keyReference));
+    if (!Buffer.isBuffer(blob)) fail('CNG backend returned no public key blob', { kind: 'keystore' });
+    return publicJwkFromEccBlob(blob);
+  }
+
+  /**
+   * The digest is computed here and the raw signature comes back from the
+   * provider. `NCryptSignHash` on an ECDSA key emits fixed-width r||s, which is
+   * already what JOSE calls P1363 — so unlike the software tiers there is no
+   * DER to convert, and no place for a conversion bug to live.
+   */
+  async sign(keyReference, data) {
+    const backend = this._cng();
+    const digest = crypto.createHash('sha256').update(data).digest();
+    const signature = backend.signDigest(this._container(keyReference), digest);
+    if (!Buffer.isBuffer(signature) || signature.length !== 64) {
+      fail('CNG backend returned a signature that is not 64-byte P1363', { kind: 'keystore' });
+    }
+    return signature;
+  }
+
+  async exists(keyReference) {
+    try {
+      return this._cng().keyExists(this._container(keyReference)) === true;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  async destroy(keyReference) {
+    const backend = this._cng();
+    try {
+      backend.deleteKey(this._container(keyReference));
+    } catch (cause) {
+      throw new MeteorCloudError('cannot destroy installation key', { kind: 'keystore', cause });
+    }
+  }
+}
+
+/**
+ * Reads X and Y out of a BCRYPT_ECCKEY_BLOB.
+ *
+ * Layout: ULONG dwMagic, ULONG cbKey, then cbKey bytes of X and cbKey of Y,
+ * both big-endian and already the fixed width a JWK wants — so this is a split,
+ * not a conversion. The magic is checked because a provider handing back a
+ * different curve would otherwise produce a JWK that claims P-256 and is not,
+ * and every assertion signed against it would fail at the server with nothing
+ * pointing back here.
+ */
+function publicJwkFromEccBlob(blob) {
+  const ECDSA_PUBLIC_P256_MAGIC = 0x31534345;
+  if (blob.length < 8) fail('CNG public key blob is truncated', { kind: 'keystore' });
+  const magic = blob.readUInt32LE(0);
+  const keyBytes = blob.readUInt32LE(4);
+  if (magic !== ECDSA_PUBLIC_P256_MAGIC || keyBytes !== 32) {
+    fail('CNG public key blob is not an ECDSA P-256 public key', { kind: 'keystore' });
+  }
+  if (blob.length < 8 + keyBytes * 2) fail('CNG public key blob is truncated', { kind: 'keystore' });
+  return {
+    kty: 'EC',
+    crv: 'P-256',
+    x: blob.subarray(8, 8 + keyBytes).toString('base64url'),
+    y: blob.subarray(8 + keyBytes, 8 + keyBytes * 2).toString('base64url')
+  };
+}
+
+/**
+ * Picks the backend a `keyReference` demands. Callers that already hold a
+ * KeyStore instance should pass it explicitly instead — this exists so a client
+ * constructed from nothing but a config file can still sign.
+ */
+function createKeyStore(keyReference, options = {}) {
+  const { scheme } = parseKeyReference(keyReference);
+  if (scheme === 'file') return new FileKeyStore();
+  if (scheme === 'dpapi') return new DpapiKeyStore(options.dpapi || {});
+  if (scheme === 'cng') return new CngKeyStore(options.cng || {});
+  return fail(`unsupported keyReference scheme: ${scheme}`, { kind: 'keystore' });
+}
+
+/**
+ * The tier a fresh bind should use on this platform: DPAPI on Windows, plain
+ * file everywhere else. Callers may override; `connect()` calls this when they
+ * do not.
+ */
+function defaultKeyStoreScheme() {
+  return process.platform === 'win32' ? 'dpapi' : 'file';
+}
+
+module.exports = {
+  KeyStore,
+  FileKeyStore,
+  DpapiKeyStore,
+  CngKeyStore,
+  createKeyStore,
+  parseKeyReference,
+  keyReferenceFor,
+  defaultKeyStoreScheme,
+  DPAPI_MODULE,
+  CNG_MODULE
+};