@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/lib/config.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const fsp = require('node:fs/promises');
+const net = require('node:net');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { MeteorCloudError, fail, isObject } = require('./errors');
+const { parseKeyReference } = require('./keystore');
+const { replaceFileDurable } = require('./durable');
+
+const CONFIG_SCHEMA = 'mlc.installation/1';
+const MAX_CONFIG_SIZE = 64 * 1024;
+const INSTALLATION_UID_RE = /^ins_[0-9a-f]{32}$/;
+const PRODUCT_CLIENT_IDS = new Set(['meteormasterai', 'meteorstudio', 'ufocapture-adapter']);
+
+/**
+ * Exactly the members that may appear in the on-disk config. Anything else is a
+ * hard failure on write, which is the mechanism that keeps the file zero-secret:
+ * a future field carrying a token cannot be added by accident, only by editing
+ * this list and the test that asserts it.
+ */
+const CONFIG_KEYS = Object.freeze(['schema', 'issuer', 'client_id', 'installation_uid', 'key_reference']);
+
+/**
+ * Substrings that must never occur in a config file or a journal. Names, not
+ * values — the point is to catch a field named `access_token` before anyone
+ * ever puts a real one there.
+ */
+const FORBIDDEN_CONFIG_SUBSTRINGS = Object.freeze([
+  'access_token',
+  'accessToken',
+  'refresh_token',
+  'refreshToken',
+  'client_secret',
+  'clientSecret',
+  'device_secret',
+  'deviceSecret',
+  'private_key',
+  'privateKey',
+  'PRIVATE KEY',
+  'code_verifier',
+  'codeVerifier',
+  'client_assertion',
+  'clientAssertion',
+  'tmpSecret',
+  'sessionToken',
+  'Authorization'
+]);
+
+function isLoopbackHost(hostname) {
+  const host = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (host === 'localhost' || host === '::1') return true;
+  return net.isIPv4(host) && host.startsWith('127.');
+}
+
+/**
+ * Cleartext HTTP is tolerated only against a loopback host. That is what lets
+ * the whole test suite and a developer's local stack run without certificates,
+ * while a typo that points production at `http://cloud.example.com` still fails
+ * before a single assertion is signed.
+ */
+function validateHttpsOrigin(value, label) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (cause) {
+    throw new MeteorCloudError(`${label} is not a valid URL`, { kind: 'validation', cause });
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    fail(`${label} must not carry credentials, a query or a fragment`);
+  }
+  const loopback = isLoopbackHost(parsed.hostname);
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
+    fail(`${label} must use https (http is allowed only for loopback hosts)`);
+  }
+  if (!loopback && !parsed.hostname.includes('.')) {
+    fail(`${label} must use a fully qualified hostname`);
+  }
+  return parsed;
+}
+
+/**
+ * The issuer may carry a path prefix (SAS mounted under a sub-path), so the
+ * trailing slash is normalised away rather than the path being rejected.
+ */
+function normalizeIssuer(issuer) {
+  const parsed = validateHttpsOrigin(issuer, 'issuer');
+  const pathname = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.origin}${pathname}`;
+}
+
+function normalizeApiBase(apiBase) {
+  const parsed = validateHttpsOrigin(apiBase, 'apiBase');
+  if (!['', '/', '/cloud', '/cloud/'].includes(parsed.pathname)) {
+    fail('apiBase must be an origin, optionally ending in /cloud');
+  }
+  return parsed.origin;
+}
+
+function tokenEndpoint(issuer) {
+  return `${normalizeIssuer(issuer)}/oauth2/token`;
+}
+
+function authorizeEndpoint(issuer) {
+  return `${normalizeIssuer(issuer)}/oauth2/authorize`;
+}
+
+function validateInstallationConfig(input) {
+  if (!isObject(input)) fail('installation config must be an object');
+  // A pre-convergence C++ 0.3-dev build wrote {config_version: 3,
+  // installation_id, client_id: <the installation uid>}. Name that file for
+  // what it is: "schema must be mlc.installation/1" against a document that has
+  // no `schema` member at all sends the reader looking for a typo.
+  if (input.config_version !== undefined && input.schema === undefined) {
+    fail(
+      'this installation config was written by a pre-0.3.0 C++ SDK ' +
+        '(config_version); the current schema is mlc.installation/1 and the ' +
+        'installation must be re-bound'
+    );
+  }
+  const schema = input.schema ?? CONFIG_SCHEMA;
+  if (schema !== CONFIG_SCHEMA) fail(`installation config schema must be ${CONFIG_SCHEMA}`);
+  const issuer = normalizeIssuer(input.issuer);
+  const clientId = input.client_id ?? input.clientId;
+  const installationUid = input.installation_uid ?? input.installationUid;
+  const keyReference = input.key_reference ?? input.keyReference;
+  if (!PRODUCT_CLIENT_IDS.has(clientId)) {
+    // Same cause as above, one layer in: the schema is right but client_id
+    // still holds the installation uid the C++ SDK used to put there.
+    if (INSTALLATION_UID_RE.test(clientId || '')) {
+      fail(
+        'installation config client_id holds an installation uid: it was ' +
+          'written by a pre-0.3.0 C++ SDK and must carry the product client ' +
+          `(${[...PRODUCT_CLIENT_IDS].join(', ')}) instead`
+      );
+    }
+    fail('client_id is not an approved product client');
+  }
+  if (!INSTALLATION_UID_RE.test(installationUid || '')) fail('installation_uid is not canonical');
+  parseKeyReference(keyReference);
+  return { schema, issuer, clientId, installationUid, keyReference };
+}
+
+/**
+ * Throws if `text` looks like it carries a credential. Applied to the config and
+ * the journal before either is written, so the no-secrets rule is enforced by
+ * the writer rather than by a code review.
+ */
+function assertNoSecrets(text, label) {
+  for (const needle of FORBIDDEN_CONFIG_SUBSTRINGS) {
+    if (text.includes(needle)) {
+      fail(`${label} would contain a credential-shaped field (${needle})`);
+    }
+  }
+}
+
+async function loadInstallationConfig(configPath) {
+  if (typeof configPath !== 'string' || !configPath) fail('configPath is required');
+  let text;
+  try {
+    const stat = await fsp.lstat(configPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) fail('installation config must be a regular file');
+    if (stat.size < 1 || stat.size > MAX_CONFIG_SIZE) fail('installation config size is implausible');
+    text = await fsp.readFile(configPath, 'utf8');
+  } catch (error) {
+    if (error instanceof MeteorCloudError) throw error;
+    throw new MeteorCloudError('cannot read installation config', { kind: 'io', cause: error });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new MeteorCloudError('installation config is invalid JSON', { kind: 'validation', cause });
+  }
+  return validateInstallationConfig(parsed);
+}
+
+async function saveInstallationConfig(configPath, config) {
+  if (typeof configPath !== 'string' || !configPath) fail('configPath is required');
+  const validated = validateInstallationConfig(config);
+  const document = {
+    schema: CONFIG_SCHEMA,
+    issuer: validated.issuer,
+    client_id: validated.clientId,
+    installation_uid: validated.installationUid,
+    key_reference: validated.keyReference
+  };
+  const extra = Object.keys(document).filter((key) => !CONFIG_KEYS.includes(key));
+  if (extra.length) fail(`installation config carries unexpected members: ${extra.join(', ')}`);
+  const encoded = `${JSON.stringify(document, null, 2)}\n`;
+  // The scanner runs over the document with key_reference's value masked out.
+  //
+  // That value is a filesystem path the integrator chose, not something we
+  // produce, and `private_key.pem` is about the most natural name a person can
+  // give a private key file. Scanning it made the substring rule fire on the
+  // path itself and refuse to save — permanently, since the name never changes
+  // on its own. The bite was worst inside connect(): it fires *after* the code
+  // exchange, so the server already holds the installation and the one-time
+  // bridge grant is already spent, and the user is left with a registered
+  // installation, a key on disk, and no config naming it.
+  //
+  // Masking does not weaken the guard. What the guard is for is a credential
+  // accidentally serialized into this file, and every other route to that is
+  // still closed: CONFIG_KEYS is a closed allowlist checked just above, the
+  // other four values are validated to be a URL, a client id, and two uids, and
+  // key_reference itself has already been through parseKeyReference. The one
+  // thing still checked in the path is the PEM banner, because a literal
+  // "-----BEGIN PRIVATE KEY-----" in a filename is not a naming choice, it is a
+  // key that ended up somewhere it should never be.
+  assertNoSecrets(encoded.replace(JSON.stringify(document.key_reference), '"<key_reference>"'),
+    'installation config');
+  // Decode before checking: key_reference is a URL, so the spaces in a PEM
+  // banner arrive as %20 and a raw substring test silently never matches.
+  let decodedReference = document.key_reference;
+  try {
+    decodedReference = decodeURIComponent(document.key_reference);
+  } catch (_) {
+    /* malformed escapes: fall back to the raw form, which is still checked */
+  }
+  if (decodedReference.includes('PRIVATE KEY') || document.key_reference.includes('PRIVATE KEY')) {
+    fail('installation config would contain a credential-shaped field (PRIVATE KEY)');
+  }
+
+  const temporary = `${configPath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    // Durable: this config is what names the key. A migration that flips
+    // key_reference and then loses the flip to a power cut leaves an
+    // installation pointing at a PEM that has already been shredded.
+    await replaceFileDurable(configPath, Buffer.from(encoded, 'utf8'), temporary, { mode: 0o600 });
+  } catch (cause) {
+    try {
+      await fsp.rm(temporary, { force: true });
+    } catch (_) {
+      /* best effort */
+    }
+    throw new MeteorCloudError('cannot save installation config', { kind: 'io', cause });
+  }
+  return validated;
+}
+
+module.exports = {
+  CONFIG_SCHEMA,
+  CONFIG_KEYS,
+  FORBIDDEN_CONFIG_SUBSTRINGS,
+  PRODUCT_CLIENT_IDS,
+  INSTALLATION_UID_RE,
+  isLoopbackHost,
+  normalizeIssuer,
+  normalizeApiBase,
+  tokenEndpoint,
+  authorizeEndpoint,
+  validateInstallationConfig,
+  assertNoSecrets,
+  loadInstallationConfig,
+  saveInstallationConfig
+};