@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,133 @@
+/**
+ * License enforcement gate. The single decision point the CLI, the hook, and
+ * the dashboard all call.
+ *
+ * Order: cached `.mlic` present -> signature valid -> not expired -> machine
+ * matches -> not revoked/suspended (cached) -> (optional, throttled) online
+ * heartbeat -> within the offline grace window. Returns a structured verdict;
+ * callers decide how to surface a denial.
+ *
+ * NOTE (honest limit): Merlin is files Claude Code reads, so a determined user
+ * can edit this check out of the source. This is a proportionate, contract-
+ * backed gate, not unbreakable DRM (see the plan's scope note).
+ */
+
+"use strict";
+
+const activation = require("./activation");
+
+const HEARTBEAT_INTERVAL_S = 72 * 3600; // refresh at most every 72h
+const GRACE_WINDOW_S = 7 * 86400; // tolerate 7 days offline since last OK heartbeat
+const TERMINAL = ["revoked", "suspended", "expired"];
+
+function deny(reason, message) {
+  return { allowed: false, reason, message };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.dir]            cache dir override (tests)
+ * @param {string} [opts.publicKeyHex]   operator pubkey override (tests)
+ * @param {boolean} [opts.allowHeartbeat=false]  may hit the network when stale
+ * @param {function} [opts.fetchImpl]    fetch override (tests)
+ * @param {string}  [opts.fingerprint]   fingerprint override (tests)
+ * @param {function} [opts.now]          () => ms clock (tests)
+ * @param {number} [opts.heartbeatIntervalS]
+ * @param {number} [opts.graceWindowS]
+ * @returns {Promise<{allowed:boolean, reason?:string, message?:string, serial?:number}>}
+ */
+async function assertLicensed(opts = {}) {
+  const {
+    dir,
+    publicKeyHex,
+    allowHeartbeat = false,
+    fetchImpl,
+    fingerprint,
+    now = () => Date.now(),
+    heartbeatIntervalS = HEARTBEAT_INTERVAL_S,
+    graceWindowS = GRACE_WINDOW_S,
+  } = opts;
+
+  let license;
+  try {
+    license = activation.readCachedLicense({ dir, publicKeyHex });
+  } catch (e) {
+    return deny("invalid", `License file is invalid: ${e.message}`);
+  }
+  if (!license) {
+    return deny(
+      "no_license",
+      "No Merlin license found. Run: merlin activate <key> --email <you@example.com>",
+    );
+  }
+
+  const nowS = Math.floor(now() / 1000);
+  if (license.expires_at <= nowS) {
+    return deny(
+      "expired",
+      `License #${license.serial} has expired. Contact us to renew.`,
+    );
+  }
+
+  const fp = fingerprint || require("./fingerprint").fingerprint();
+  if (license.fingerprint_hash !== fp) {
+    return deny(
+      "machine_mismatch",
+      `License #${license.serial} is bound to a different machine. Re-run "merlin activate" on this machine.`,
+    );
+  }
+
+  let state = activation.readState(dir);
+  if (state.last_status === "revoked") {
+    return deny(
+      "revoked",
+      "Your Merlin license has been revoked. Contact support.",
+    );
+  }
+  if (state.last_status === "suspended") {
+    return deny(
+      "suspended",
+      "Your Merlin license is suspended (copy detected). Contact support.",
+    );
+  }
+
+  const lastHb = state.last_heartbeat || 0;
+  const stale = nowS - lastHb > heartbeatIntervalS;
+  if (allowHeartbeat && stale) {
+    try {
+      const hb = await activation.heartbeat({
+        dir,
+        publicKeyHex,
+        fetchImpl,
+        now,
+      });
+      if (TERMINAL.includes(hb.status)) {
+        return deny(hb.status, hb.message_to_user || `License ${hb.status}.`);
+      }
+      state = activation.readState(dir); // pick up refreshed last_heartbeat
+    } catch {
+      // offline — fall through to the grace check
+    }
+  }
+
+  // Grace anchor: last successful heartbeat if we have one, else the license's
+  // issuance time. NEVER let a missing/corrupt state file (lastOk falsy) skip
+  // the grace check — that lets anyone delete or truncate license-state.json and
+  // run offline forever. With no anchor at all, fail CLOSED (require online).
+  const lastOk = state.last_heartbeat || license.issued_at || 0;
+  if (nowS - lastOk > graceWindowS) {
+    return deny(
+      "grace_expired",
+      `No successful license heartbeat in ${Math.round(graceWindowS / 86400)} days. ` +
+        'Reconnect and run "merlin license --refresh".',
+    );
+  }
+
+  return { allowed: true, serial: license.serial };
+}
+
+module.exports = {
+  HEARTBEAT_INTERVAL_S,
+  GRACE_WINDOW_S,
+  assertLicensed,
+};

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

@@ -0,0 +1,42 @@
+/**
+ * HMAC-SHA256 over the heartbeat payload — proves the client owns the
+ * `api_key_local` from its signed `.mlic` without sending the key itself.
+ *
+ * Canonical payload string:
+ *   `${serial}:${fingerprint_hash}:${version}:${ts_signed}:${nonce}`.
+ * Byte-for-byte parity with the license server's HMAC implementation (which uses
+ * Web Crypto); node:crypto's createHmac produces the identical hex digest for the
+ * same key + message, so server-side verify accepts it. The per-beat `nonce`
+ * binds the signature to a single request so the Worker can reject replays.
+ */
+
+"use strict";
+
+const { createHmac } = require("node:crypto");
+
+/** The exact string both sides HMAC. Order + separators are parity-critical. */
+function canonicalHeartbeat(args) {
+  return [
+    args.serial,
+    args.fingerprint_hash,
+    args.version,
+    args.ts_signed,
+    args.nonce,
+  ].join(":");
+}
+
+/**
+ * Hex HMAC-SHA256 of the canonical heartbeat string, keyed by api_key_local.
+ * @param {{serial:number, fingerprint_hash:string, version:string, ts_signed:number, api_key_local:string}} args
+ * @returns {string} lowercase hex digest (64 chars)
+ */
+function heartbeatHmac(args) {
+  return createHmac("sha256", args.api_key_local)
+    .update(canonicalHeartbeat(args), "utf8")
+    .digest("hex");
+}
+
+module.exports = {
+  canonicalHeartbeat,
+  heartbeatHmac,
+};

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

@@ -0,0 +1,144 @@
+/**
+ * Human license key codec: `MRL-#N-XXXX-XXXX-XXXX-XXXX` (prefix MRL).
+ *
+ * The key is a CLAIM TICKET, not an authorization token — it identifies a
+ * license to the activation endpoint, nothing more. Runtime gating is done
+ * entirely by the Ed25519-signed `.mlic` bundle (see ./license.js).
+ *
+ * Anatomy (80 bits encoded as 16 Crockford Base32 chars, 4 groups of 4):
+ *   [ serial_check : 8 bits ][ nonce : 48 bits ][ crc24 : 24 bits ]
+ *
+ *   - serial_check = low byte of CRC-24 over the decimal serial string.
+ *   - nonce        = 48 random bits, makes keys unguessable / unique.
+ *   - crc24        = CRC-24/OPENPGP over the preceding 7 bytes. Detects a
+ *     typo BEFORE the network round-trip.
+ */
+
+"use strict";
+
+const { randomBytes } = require("node:crypto");
+const {
+  crc24,
+  crockfordDecode,
+  crockfordEncode,
+  CrockfordDecodeError,
+} = require("./crc");
+
+class KeyFormatError extends Error {}
+class KeyChecksumError extends Error {}
+class KeySerialMismatchError extends Error {}
+
+// `MRL`, optional `#`, decimal serial, then four Crockford groups. Tolerant of
+// lowercase and surrounding whitespace; normalization happens before this.
+const KEY_RE =
+  /^MRL-#?(\d{1,9})-([0-9A-Z]{4})-([0-9A-Z]{4})-([0-9A-Z]{4})-([0-9A-Z]{4})$/;
+
+/** Low byte of CRC-24 over the decimal serial string — the embedded check. */
+function serialCheckByte(serial) {
+  return crc24(Buffer.from(String(serial), "utf8")) & 0xff;
+}
+
+/** Build a valid human key for a serial. `nonce` (48-bit) is for tests. */
+function generateKey(serial, nonce) {
+  if (!Number.isInteger(serial) || serial < 1) {
+    throw new KeyFormatError(
+      `serial must be a positive integer, got ${serial}`,
+    );
+  }
+  const n = nonce === undefined ? randomNonce48() : nonce & 0xffffffffffffn; // clamp to 48 bits
+
+  const data = new Uint8Array(7);
+  data[0] = serialCheckByte(serial);
+  for (let i = 0; i < 6; i++) {
+    data[1 + i] = Number((n >> BigInt((5 - i) * 8)) & 0xffn);
+  }
+
+  const checksum = crc24(data);
+  const full = new Uint8Array(10);
+  full.set(data, 0);
+  full[7] = (checksum >> 16) & 0xff;
+  full[8] = (checksum >> 8) & 0xff;
+  full[9] = checksum & 0xff;
+
+  const encoded = crockfordEncode(full); // 16 chars
+  const groups = encoded.match(/.{4}/g).join("-");
+  return `MRL-#${serial}-${groups}`;
+}
+
+/**
+ * Parse + validate a human key. Throws KeyFormatError on structural problems,
+ * KeyChecksumError on a CRC-24 mismatch (typo), KeySerialMismatchError if the
+ * encoded serial-check disagrees with the typed `#N`.
+ */
+function parseKey(raw) {
+  const normalized = raw.trim().toUpperCase().replace(/\s+/g, "");
+  const m = KEY_RE.exec(normalized);
+  if (!m) {
+    throw new KeyFormatError(
+      "invalid format — expected MRL-#N-XXXX-XXXX-XXXX-XXXX",
+    );
+  }
+
+  const serial = Number.parseInt(m[1], 10);
+  const encoded = m[2] + m[3] + m[4] + m[5];
+
+  let full;
+  try {
+    full = crockfordDecode(encoded);
+  } catch (e) {
+    if (e instanceof CrockfordDecodeError) {
+      throw new KeyChecksumError("the key contains invalid characters");
+    }
+    throw e;
+  }
+  if (full.length !== 10) {
+    throw new KeyFormatError(
+      `key decoded to ${full.length} bytes, expected 10`,
+    );
+  }
+
+  const data = full.subarray(0, 7);
+  const storedCrc = (full[7] << 16) | (full[8] << 8) | full[9];
+  if (crc24(data) !== storedCrc) {
+    throw new KeyChecksumError("the key looks mistyped (checksum failed)");
+  }
+
+  if (data[0] !== serialCheckByte(serial)) {
+    throw new KeySerialMismatchError(
+      `the key does not match serial #${serial}`,
+    );
+  }
+
+  let nonce = 0n;
+  for (let i = 1; i < 7; i++) {
+    nonce = (nonce << 8n) | BigInt(data[i]);
+  }
+  return { serial, nonceHex: nonce.toString(16).padStart(12, "0") };
+}
+
+/** True if `raw` is a structurally + checksum valid key. Never throws. */
+function isValidKey(raw) {
+  try {
+    parseKey(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function randomNonce48() {
+  const b = randomBytes(6);
+  let n = 0n;
+  for (const byte of b) n = (n << 8n) | BigInt(byte);
+  return n;
+}
+
+module.exports = {
+  generateKey,
+  parseKey,
+  isValidKey,
+  serialCheckByte,
+  KeyFormatError,
+  KeyChecksumError,
+  KeySerialMismatchError,
+};

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

@@ -0,0 +1,212 @@
+/**
+ * Client-side `.mlic` loader + verifier (signed-JSON wire format; zero extra
+ * runtime deps — node:crypto only).
+ *
+ * `.mlic` envelope (UTF-8 JSON):
+ *   { "payload_b64": "<base64url of the canonical-JSON payload bytes>",
+ *     "sig_b64":     "<base64url of the 64-byte Ed25519 signature>" }
+ *
+ * The signature covers the EXACT payload bytes that were base64url-encoded, so
+ * verification is over transmitted bytes (no re-canonicalization needed).
+ *
+ * Ed25519 verification uses node:crypto by wrapping the raw 32-byte public key
+ * in its SPKI DER envelope.
+ */
+
+"use strict";
+
+const { createPublicKey, verify: cryptoVerify } = require("node:crypto");
+const { readFileSync } = require("node:fs");
+
+// Operator Ed25519 license-signing public key. Clients verify every `.mlic`
+// against this key.
+//
+// KEY SPLIT (decision 2026-06-14, executed 2026-06-21): Merlin uses its OWN
+// dedicated Ed25519 signing keypair, generated into the operator VeraCrypt
+// vault as `merlin-private.pem` and decoupled from the sibling FF product.
+// This public half MUST stay in lockstep with the Worker's OPERATOR_PUBKEY_HEX
+// (`licensing/cloudflare/src/lib/ed25519.ts`) and the operator signing key.
+const PUBLIC_KEY_HEX =
+  "78f497ee907ca764fd54b64085739384958257bc84d04a30cc441dd53c65d67e";
+
+const SCHEMA_VERSION_MAX = 1;
+
+class LicenseError extends Error {}
+class LicenseNotFound extends LicenseError {}
+class LicenseMalformed extends LicenseError {}
+class LicenseInvalidSignature extends LicenseError {}
+class LicenseExpired extends LicenseError {}
+class LicenseFingerprintMismatch extends LicenseError {}
+class LicenseSchemaUnsupported extends LicenseError {}
+
+// Standard SPKI DER prefix for an Ed25519 public key (12 bytes), then 32 raw.
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+function operatorPublicKey(publicKeyHex = PUBLIC_KEY_HEX) {
+  if (publicKeyHex.length !== 64) {
+    throw new LicenseError(
+      `public key must be 64 hex chars, got ${publicKeyHex.length}`,
+    );
+  }
+  const der = Buffer.concat([
+    SPKI_ED25519_PREFIX,
+    Buffer.from(publicKeyHex, "hex"),
+  ]);
+  return createPublicKey({ key: der, format: "der", type: "spki" });
+}
+
+const REQUIRED_FIELDS = [
+  "schema_version",
+  "serial",
+  "client_id",
+  "fingerprint_hash",
+  "issued_at",
+  "expires_at",
+  "features",
+  "api_key_local",
+];
+
+/**
+ * Verify + shape-check a `.mlic` envelope (string or Buffer of the JSON file).
+ * @param {string|Buffer} raw - the `.mlic` file contents
+ * @param {object} [opts]
+ * @param {string} [opts.publicKeyHex] - override the operator key (tests only)
+ * @returns {object} the validated License payload
+ */
+function parseLicenseBundle(raw, opts = {}) {
+  const publicKeyHex = opts.publicKeyHex || PUBLIC_KEY_HEX;
+
+  let envelope;
+  try {
+    envelope = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
+  } catch (e) {
+    throw new LicenseMalformed(`license is not valid JSON: ${e.message}`);
+  }
+
+  if (
+    !envelope ||
+    typeof envelope !== "object" ||
+    typeof envelope.payload_b64 !== "string" ||
+    typeof envelope.sig_b64 !== "string"
+  ) {
+    throw new LicenseMalformed(
+      "bundle missing required string keys 'payload_b64' and 'sig_b64'",
+    );
+  }
+
+  const payloadBuf = Buffer.from(envelope.payload_b64, "base64url");
+  const signature = Buffer.from(envelope.sig_b64, "base64url");
+  if (signature.length !== 64) {
+    throw new LicenseMalformed(
+      `signature is ${signature.length} bytes, expected 64 (Ed25519)`,
+    );
+  }
+  if (payloadBuf.length === 0) {
+    throw new LicenseMalformed("payload is empty");
+  }
+
+  const ok = cryptoVerify(
+    null,
+    payloadBuf,
+    operatorPublicKey(publicKeyHex),
+    signature,
+  );
+  if (!ok) {
+    throw new LicenseInvalidSignature(
+      "signature does not match the operator public key",
+    );
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(payloadBuf.toString("utf8"));
+  } catch (e) {
+    throw new LicenseMalformed(`payload is not valid JSON: ${e.message}`);
+  }
+  if (!payload || typeof payload !== "object") {
+    throw new LicenseMalformed("payload must be a JSON object");
+  }
+
+  const missing = REQUIRED_FIELDS.filter((k) => !(k in payload));
+  if (missing.length > 0) {
+    throw new LicenseMalformed(
+      `payload missing keys: ${missing.sort().join(", ")}`,
+    );
+  }
+
+  if (
+    typeof payload.schema_version !== "number" ||
+    payload.schema_version > SCHEMA_VERSION_MAX
+  ) {
+    throw new LicenseSchemaUnsupported(
+      `schema_version=${String(payload.schema_version)} is newer than this ` +
+        `build supports (max ${SCHEMA_VERSION_MAX})`,
+    );
+  }
+
+  return {
+    schema_version: payload.schema_version,
+    serial: payload.serial,
+    client_id: payload.client_id,
+    fingerprint_hash: payload.fingerprint_hash,
+    issued_at: payload.issued_at,
+    expires_at: payload.expires_at,
+    features: [...payload.features],
+    api_key_local: payload.api_key_local,
+  };
+}
+
+/** Read, signature-verify, and shape-check a `.mlic` file. */
+function loadLicense(filePath, opts = {}) {
+  let data;
+  try {
+    data = readFileSync(filePath);
+  } catch (e) {
+    throw new LicenseNotFound(
+      `could not read license at ${filePath}: ${e.message}`,
+    );
+  }
+  return parseLicenseBundle(data, opts);
+}
+
+function verifyExpiration(license, now = Math.floor(Date.now() / 1000)) {
+  if (license.expires_at <= now) {
+    throw new LicenseExpired(
+      `license #${license.serial} expired at ${license.expires_at} (now=${now})`,
+    );
+  }
+}
+
+/**
+ * Verify the license is bound to this machine. Pass `currentFingerprint` in
+ * tests; otherwise it is computed live via ./fingerprint.
+ */
+function verifyMachineBinding(license, currentFingerprint) {
+  const current =
+    currentFingerprint !== undefined
+      ? currentFingerprint
+      : require("./fingerprint").fingerprint();
+  if (license.fingerprint_hash !== current) {
+    throw new LicenseFingerprintMismatch(
+      `license #${license.serial} is bound to another machine ` +
+        `(expected ${license.fingerprint_hash.slice(0, 16)}…, got ${current.slice(0, 16)}…)`,
+    );
+  }
+}
+
+module.exports = {
+  PUBLIC_KEY_HEX,
+  SCHEMA_VERSION_MAX,
+  operatorPublicKey,
+  parseLicenseBundle,
+  loadLicense,
+  verifyExpiration,
+  verifyMachineBinding,
+  LicenseError,
+  LicenseNotFound,
+  LicenseMalformed,
+  LicenseInvalidSignature,
+  LicenseExpired,
+  LicenseFingerprintMismatch,
+  LicenseSchemaUnsupported,
+};

package/.merlin-core/core/mcp/README.md

@@ -0,0 +1,16 @@
+# MCP Integration
+
+The MCP module provides integration with the Model Context Protocol, enabling dynamic capability discovery and management. It includes the MCP registry for capability tracking, connectors for external systems, capability mappers for feature resolution, and symlink managers for dynamic linking.
+
+## Contents
+
+- **registry/** - MCP capability registry and metadata management
+- **connector/** - Connections to external MCP servers and services
+- **capability-mapper/** - Maps model capabilities to available features
+- **symlink-manager/** - Dynamic symlink management for flexible integration
+- **mcp-manager.js** - Main MCP orchestrator and coordinator
+
+## Related
+
+- [Execution](../execution/README.md)
+- [Alkimia](../alkimia/README.md)