@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/licensing/activation.js

@@ -0,0 +1,281 @@
+/**
+ * Client activation + heartbeat — talks to the license server and
+ * manages the local license cache at `~/.merlin/`.
+ *
+ * Flow (activate):
+ *   parse MRL-#N key -> compute fingerprint -> POST /v1/activate-request ->
+ *   poll /v1/activate-status/:id until `signed` -> verify the returned .mlic
+ *   (signature + binding + expiry) -> cache it.
+ *
+ * All network + filesystem + crypto edges are injectable (fetchImpl, dir,
+ * publicKeyHex, fingerprint) so the flow is unit-testable without a live
+ * license server or the production key.
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { randomBytes } = require("node:crypto");
+const { parseKey } = require("./key");
+const { fingerprint } = require("./fingerprint");
+const { heartbeatHmac } = require("./hmac");
+const {
+  parseLicenseBundle,
+  verifyExpiration,
+  verifyMachineBinding,
+} = require("./license");
+
+const DEFAULT_API_BASE =
+  process.env.MERLIN_LICENSE_API || "https://licenses.merlincompany.com.br";
+const CLIENT_VERSION = "merlin/0.1.0";
+const POLL_INTERVAL_MS = 30_000;
+const POLL_TIMEOUT_MS = 10 * 60_000;
+const FETCH_TIMEOUT_MS = 8_000; // abort a single request if the server hangs
+
+/** AbortSignal that fires after FETCH_TIMEOUT_MS (undefined if unsupported). */
+function fetchTimeout() {
+  const AS = globalThis.AbortSignal;
+  return AS && AS.timeout ? AS.timeout(FETCH_TIMEOUT_MS) : undefined;
+}
+
+function merlinDir(dir) {
+  return dir || path.join(os.homedir(), ".merlin");
+}
+function licensePath(dir) {
+  return path.join(merlinDir(dir), "license.mlic");
+}
+function statePath(dir) {
+  return path.join(merlinDir(dir), "license-state.json");
+}
+
+function readState(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(dir), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeState(dir, state) {
+  fs.mkdirSync(merlinDir(dir), { recursive: true });
+  // Atomic write: a bare writeFileSync can leave a torn/half-written file if the
+  // process dies mid-write or two writers race (the hook + the dashboard's 72h
+  // beat both call this). Write to a temp file, then rename (atomic on the same
+  // filesystem) so readers only ever see a complete state file.
+  const target = statePath(dir);
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, target);
+}
+
+/** Read + verify the cached `.mlic` offline. Returns the License or null. */
+function readCachedLicense(opts = {}) {
+  const p = licensePath(opts.dir);
+  if (!fs.existsSync(p)) return null;
+  return parseLicenseBundle(fs.readFileSync(p, "utf8"), {
+    publicKeyHex: opts.publicKeyHex,
+  });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Run the full activation handshake and cache the signed license.
+ * @returns {Promise<{serial:number, expires_at:number, client_id:string}>}
+ */
+async function activate(opts = {}) {
+  const {
+    key,
+    email,
+    apiBase = DEFAULT_API_BASE,
+    dir,
+    fetchImpl = globalThis.fetch,
+    publicKeyHex,
+    pollIntervalMs = POLL_INTERVAL_MS,
+    timeoutMs = POLL_TIMEOUT_MS,
+    now = () => Date.now(),
+  } = opts;
+
+  const { serial } = parseKey(key); // throws on a bad key
+  if (!email || !email.includes("@")) {
+    throw new Error("a valid --email is required to activate");
+  }
+  const fp = opts.fingerprint || fingerprint();
+
+  const reqRes = await fetchImpl(`${apiBase}/v1/activate-request`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      serial,
+      fingerprint_hash: fp,
+      client_email: email,
+    }),
+    signal: fetchTimeout(),
+  });
+  if (!reqRes.ok) {
+    throw new Error(`activate-request failed: HTTP ${reqRes.status}`);
+  }
+  const { activation_id } = await reqRes.json();
+  // The server returns an opaque random token (not an enumerable id). We must
+  // re-present our fingerprint on every status poll so the Worker only releases
+  // the signed .mlic to this machine (caller binding — see Worker #6).
+  if (typeof activation_id !== "string" || activation_id.length === 0) {
+    throw new Error("activate-request returned no activation_id");
+  }
+  const statusUrl =
+    `${apiBase}/v1/activate-status/${encodeURIComponent(activation_id)}` +
+    `?fp=${encodeURIComponent(fp)}`;
+
+  const deadline = now() + timeoutMs;
+  let mlicB64 = null;
+  // Poll until the operator signs (or we time out).
+  for (;;) {
+    const statusRes = await fetchImpl(statusUrl, { signal: fetchTimeout() });
+    if (statusRes.ok) {
+      const s = await statusRes.json();
+      if (s.status === "signed" && s.license_mlic_b64) {
+        mlicB64 = s.license_mlic_b64;
+        break;
+      }
+      if (s.status === "rejected" || s.status === "expired") {
+        throw new Error(`activation ${s.status} by operator`);
+      }
+    }
+    if (now() >= deadline) {
+      throw new Error(
+        `activation timed out after ${Math.round(timeoutMs / 60000)} min; ` +
+          `run "merlin activate" again once the operator has signed`,
+      );
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  const mlic = Buffer.from(mlicB64, "base64").toString("utf8");
+  const license = parseLicenseBundle(mlic, { publicKeyHex }); // verifies sig
+  verifyMachineBinding(license, fp);
+  verifyExpiration(license);
+
+  fs.mkdirSync(merlinDir(dir), { recursive: true });
+  fs.writeFileSync(licensePath(dir), mlic, "utf8");
+  writeState(dir, {
+    activated_at: Math.floor(now() / 1000),
+    last_heartbeat: Math.floor(now() / 1000),
+    last_status: "active",
+  });
+
+  return {
+    serial: license.serial,
+    expires_at: license.expires_at,
+    client_id: license.client_id,
+  };
+}
+
+/**
+ * Send one heartbeat to the license server and persist the returned status.
+ * @returns {Promise<{status:string, message_to_user?:string}>}
+ */
+async function heartbeat(opts = {}) {
+  const {
+    apiBase = DEFAULT_API_BASE,
+    dir,
+    fetchImpl = globalThis.fetch,
+    publicKeyHex,
+    version = CLIENT_VERSION,
+    now = () => Date.now(),
+  } = opts;
+
+  const license = readCachedLicense({ dir, publicKeyHex });
+  if (!license)
+    throw new Error("no cached license — run `merlin activate` first");
+
+  const ts_signed = Math.floor(now() / 1000);
+  // Per-beat nonce: binds this HMAC to a single request so the server rejects a
+  // captured-and-replayed heartbeat (copy-share detection, even within the
+  // clock-skew window). The nonce is part of the canonical HMAC string.
+  const nonce = randomBytes(16).toString("hex");
+  const hmac = heartbeatHmac({
+    serial: license.serial,
+    fingerprint_hash: license.fingerprint_hash,
+    version,
+    ts_signed,
+    nonce,
+    api_key_local: license.api_key_local,
+  });
+
+  const res = await fetchImpl(`${apiBase}/v1/heartbeat`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      serial: license.serial,
+      fingerprint_hash: license.fingerprint_hash,
+      version,
+      ts_signed,
+      nonce,
+      hmac,
+    }),
+    signal: fetchTimeout(),
+  });
+  const body = await res.json().catch(() => ({}));
+  // Only trust a server-supplied status on a 2xx response. A non-2xx body
+  // (transient 5xx, CDN error page, MITM downgrade) must NEVER write a terminal
+  // status — the offline gate would treat revoked/suspended as a hard lockout
+  // and brick a valid paying customer on a blip.
+  const status = res.ok ? body.status || "unknown" : `http_${res.status}`;
+
+  const state = readState(dir);
+  state.last_status = status;
+  if (res.ok && (status === "active" || status === "ok")) {
+    state.last_heartbeat = ts_signed;
+  }
+  writeState(dir, state);
+
+  return {
+    status,
+    message_to_user: res.ok ? body.message_to_user : undefined,
+  };
+}
+
+/** Offline status summary for `merlin license`. Never throws. */
+function status(opts = {}) {
+  const dir = opts.dir;
+  let license = null;
+  let error = null;
+  try {
+    license = readCachedLicense({ dir, publicKeyHex: opts.publicKeyHex });
+  } catch (e) {
+    error = e.message;
+  }
+  const state = readState(dir);
+  if (!license) {
+    return { valid: false, reason: error || "no license cached", state };
+  }
+  const fp = opts.fingerprint || fingerprint();
+  const expired =
+    license.expires_at <= Math.floor((opts.nowMs || Date.now()) / 1000);
+  const fingerprintMatch = license.fingerprint_hash === fp;
+  return {
+    valid: !expired && fingerprintMatch,
+    serial: license.serial,
+    client_id: license.client_id,
+    expires_at: license.expires_at,
+    expired,
+    fingerprintMatch,
+    last_heartbeat: state.last_heartbeat || null,
+    last_status: state.last_status || null,
+  };
+}
+
+module.exports = {
+  DEFAULT_API_BASE,
+  CLIENT_VERSION,
+  merlinDir,
+  licensePath,
+  statePath,
+  readCachedLicense,
+  readState,
+  writeState,
+  activate,
+  heartbeat,
+  status,
+};

package/.merlin-core/core/licensing/crc.js

@@ -0,0 +1,103 @@
+/**
+ * CRC-24 (OpenPGP / RFC 4880) + Crockford Base32 — pure, zero-dependency.
+ *
+ * Parity-critical primitives behind the human license key
+ * `MRL-#N-XXXX-XXXX-XXXX-XXXX`. Pinned here so any operator-side key generator
+ * produces keys this parser accepts bit-for-bit. The algorithm is pinned in one
+ * auditable place rather than delegated to a dependency.
+ *
+ * CRC-24: poly 0x864CFB, init 0xB704CE, 24-bit output (RFC 4880 §6.1).
+ * Crockford Base32: charset 0123456789ABCDEFGHJKMNPQRSTVWXYZ (excludes
+ * I, L, O, U to avoid visual ambiguity).
+ */
+
+"use strict";
+
+const CROCKFORD_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+const CRC24_INIT = 0xb704ce;
+const CRC24_POLY = 0x864cfb;
+
+/** CRC-24/OPENPGP over raw bytes. Returns a 24-bit unsigned integer. */
+function crc24(data) {
+  let crc = CRC24_INIT;
+  for (const byte of data) {
+    crc ^= byte << 16;
+    for (let i = 0; i < 8; i++) {
+      crc <<= 1;
+      if (crc & 0x1000000) crc ^= CRC24_POLY;
+    }
+  }
+  return crc & 0xffffff;
+}
+
+/**
+ * Encode bytes to Crockford Base32, MSB-first, no padding.
+ * 10 bytes (80 bits) -> exactly 16 characters.
+ */
+function crockfordEncode(bytes) {
+  let value = 0;
+  let bits = 0;
+  let out = "";
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += CROCKFORD_ALPHABET[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    out += CROCKFORD_ALPHABET[(value << (5 - bits)) & 31];
+  }
+  return out;
+}
+
+// Decode map: canonical chars + Crockford's tolerated aliases (I/L -> 1,
+// O -> 0). U is intentionally NOT aliased — it's an invalid char.
+const DECODE_MAP = (() => {
+  const map = {};
+  for (let i = 0; i < CROCKFORD_ALPHABET.length; i++) {
+    map[CROCKFORD_ALPHABET[i]] = i;
+  }
+  map["I"] = 1;
+  map["L"] = 1;
+  map["O"] = 0;
+  return map;
+})();
+
+class CrockfordDecodeError extends Error {}
+
+/**
+ * Decode a Crockford Base32 string back to bytes. Input is uppercased and
+ * I/L/O aliases are folded before lookup. Throws on any out-of-charset
+ * character. 16 chars -> 10 bytes.
+ */
+function crockfordDecode(input) {
+  let value = 0;
+  let bits = 0;
+  const out = [];
+  for (const rawCh of input.toUpperCase()) {
+    const idx = DECODE_MAP[rawCh];
+    if (idx === undefined) {
+      throw new CrockfordDecodeError(
+        `invalid Crockford Base32 character: ${rawCh}`,
+      );
+    }
+    value = (value << 5) | idx;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+module.exports = {
+  CROCKFORD_ALPHABET,
+  crc24,
+  crockfordEncode,
+  crockfordDecode,
+  CrockfordDecodeError,
+};

package/.merlin-core/core/licensing/entitlement.js

@@ -0,0 +1,99 @@
+/**
+ * entitlement.js — feature entitlement reader for Merlin Modules (v3.5).
+ *
+ * `assertFeature(id)` answers "does the current license grant feature <id>?".
+ * It is **warn-only**: the license system is dormant today (`features:["all"]`,
+ * see license.js), so this NEVER throws and NEVER blocks — it returns a verdict
+ * the caller logs. provision-module.mjs uses it to warn, not to gate.
+ *
+ * Reads the cached `.mlic` via the canonical reader (activation.readCachedLicense,
+ * same path gate.js uses). Tests inject a `license` object directly.
+ *
+ * @module core/licensing/entitlement
+ */
+
+"use strict";
+
+const activation = require("./activation");
+
+/**
+ * @param {string} featureId - the module id / license feature to check
+ * @param {object} [opts]
+ * @param {object} [opts.license] - inject a parsed license (tests)
+ * @param {string} [opts.dir] - cache dir override (tests)
+ * @param {string} [opts.publicKeyHex] - operator pubkey override (tests)
+ * @returns {{entitled: boolean, reason: string, mode: "warn"}}
+ */
+function assertFeature(featureId, opts = {}) {
+  let license = opts.license;
+  if (!license) {
+    try {
+      license = activation.readCachedLicense({
+        dir: opts.dir,
+        publicKeyHex: opts.publicKeyHex,
+      });
+    } catch (e) {
+      // Malformed / bad-signature license — warn, never block (dormant system).
+      return {
+        entitled: false,
+        reason: `license unreadable: ${e.message}`,
+        mode: "warn",
+      };
+    }
+  }
+
+  if (!license) {
+    return {
+      entitled: false,
+      reason: "no license present (dormant) — entitlement not enforced",
+      mode: "warn",
+    };
+  }
+
+  const features = Array.isArray(license.features) ? license.features : [];
+  const entitled = features.includes(featureId) || features.includes("all");
+  return {
+    entitled,
+    reason: entitled
+      ? `feature "${featureId}" granted (present or "all")`
+      : `feature "${featureId}" not in license features`,
+    mode: "warn",
+  };
+}
+
+/**
+ * Module-aware entitlement check (v3.5 modules↔license wiring). Honors the
+ * manifest's `kind`/`access_policy`:
+ *   - standalone-app → entitlement is **git repo access** (GitHub-enforced),
+ *     NOT a license feature (research §4.2) → `applicable:false`, basis "git-access".
+ *   - in-platform / framework-capability → the license feature == the module id.
+ * `mode` is "warn" (default — license dormant, never blocks) or "block".
+ *
+ * @param {object} manifest - a module manifest
+ * @param {object} [opts] - { mode, dir, publicKeyHex, license }
+ * @returns {{applicable:boolean, basis:string, entitled:boolean, reason:string, mode:string}}
+ */
+function checkEntitlement(manifest, opts = {}) {
+  const mode = opts.mode === "block" ? "block" : "warn";
+
+  if (manifest && manifest.kind === "standalone-app") {
+    return {
+      applicable: false,
+      basis: "git-access",
+      entitled: true, // repo access is the gate (not checked here)
+      reason: `standalone-app: entitlement is git access to ${manifest.repo || "the module repo"} (access_policy: ${manifest.access_policy || "unset"})`,
+      mode,
+    };
+  }
+
+  const v = assertFeature(manifest && manifest.id, opts);
+  return {
+    applicable: true,
+    basis: "license-feature",
+    entitled: v.entitled,
+    reason: v.reason,
+    mode,
+  };
+}
+
+module.exports = { assertFeature, checkEntitlement };

package/.merlin-core/core/licensing/fingerprint.js

@@ -0,0 +1,104 @@
+/**
+ * Machine fingerprint — computed at activation and bound to the signed license.
+ *
+ * The CLI collects this fingerprint at `merlin activate` and ships it to the
+ * operator, who binds the signed license to it. The runtime gate re-computes
+ * the fingerprint and rejects a license whose `fingerprint_hash` doesn't match.
+ * THEREFORE this implementation must be bit-for-bit identical to every other
+ * license consumer/generator, or a license minted against one view of a machine
+ * will be rejected on that same machine.
+ *
+ * Parity choices (do NOT "improve" these):
+ *   1. disk serial via spawnSync of the exact shell commands the reference
+ *      implementation uses
+ *      (wmic / system_profiler / /sys/class/block/sda/device/serial), NOT a
+ *      package that enumerates disks differently per OS.
+ *   2. node-machine-id `machineIdSync(true)` returns the RAW OS GUID. Without
+ *      `true` it returns an HMAC of the GUID and parity breaks.
+ *
+ * `fingerprintFromParts` is the pure, dependency-free core (the tested path).
+ */
+
+"use strict";
+
+const { createHash } = require("node:crypto");
+const { readFileSync } = require("node:fs");
+const { hostname, platform } = require("node:os");
+const { spawnSync } = require("node:child_process");
+
+/** sha256(machineid || '||' || disk_serial || '||' || hostname) as lowercase hex. */
+function fingerprintFromParts(machineidId, diskSerial, host) {
+  const payload = [machineidId, diskSerial, host].join("||");
+  return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+
+function diskSerial() {
+  const plat = platform();
+  try {
+    if (plat === "win32") {
+      const r = spawnSync(
+        "wmic",
+        ["diskdrive", "where", "Index=0", "get", "SerialNumber", "/value"],
+        { encoding: "utf8", timeout: 5000 },
+      );
+      if (r.status === 0 && r.stdout) {
+        for (const line of r.stdout.split(/\r?\n/)) {
+          if (line.startsWith("SerialNumber=")) {
+            return line.split("=", 2)[1].trim();
+          }
+        }
+      }
+    } else if (plat === "darwin") {
+      const r = spawnSync("system_profiler", ["SPHardwareDataType"], {
+        encoding: "utf8",
+        timeout: 5000,
+      });
+      if (r.status === 0 && r.stdout) {
+        for (const line of r.stdout.split(/\r?\n/)) {
+          if (line.includes("Serial Number")) {
+            const colonIdx = line.indexOf(":");
+            if (colonIdx !== -1) return line.slice(colonIdx + 1).trim();
+          }
+        }
+      }
+    } else if (plat === "linux") {
+      try {
+        return readFileSync(
+          "/sys/class/block/sda/device/serial",
+          "utf8",
+        ).trim();
+      } catch {
+        /* fall through */
+      }
+    }
+  } catch {
+    /* fall through */
+  }
+  return "";
+}
+
+let cache = null;
+
+/** Compute (and cache) this machine's fingerprint. Requires node-machine-id. */
+function fingerprint() {
+  if (cache !== null) return cache;
+  // Lazy require so the pure `fingerprintFromParts` path (and its tests) work
+  // without the native node-machine-id binding installed.
+  const machineId = require("node-machine-id");
+  cache = fingerprintFromParts(
+    machineId.machineIdSync(true),
+    diskSerial(),
+    hostname(),
+  );
+  return cache;
+}
+
+function resetFingerprintCache() {
+  cache = null;
+}
+
+module.exports = {
+  fingerprintFromParts,
+  fingerprint,
+  resetFingerprintCache,
+};