@blamejs/core 0.7.107 → 0.8.4

package/lib/crypto.js

@@ -164,7 +164,26 @@ function verify(data, signature, publicKeyPem) {
 function encrypt(plaintext, publicKeys) {
   var mlkemPubPem = typeof publicKeys === "string" ? publicKeys : publicKeys.publicKey;
   var ecPubPem = typeof publicKeys === "string" ? null : publicKeys.ecPublicKey;
-  if (!ecPubPem) return encryptMlkemOnly(plaintext, mlkemPubPem);
+  if (!ecPubPem) {
+    // Operator passed only an ML-KEM public key — silently dropping
+    // the P-384 hybrid leg means the operator's defense-in-depth
+    // posture (classical ECDH backstop on top of PQC KEM) is gone
+    // without any signal. Emit on next tick (crypto must not import
+    // audit synchronously — audit imports crypto for chain hashing).
+    // Operators who genuinely want KEM-only should call
+    // encryptMlkemOnly explicitly so this audit doesn't fire.
+    setImmediate(function () {
+      try {
+        var auditMod = require("./audit");                                          // allow:inline-require — circular-load defense (audit imports crypto)
+        auditMod.safeEmit({
+          action:   "system.crypto.hybrid_disabled",
+          outcome:  "success",
+          metadata: { reason: "no-ec-public-key", note: "encrypt() received only mlkem; ecPublicKey absent — call encryptMlkemOnly explicitly to silence" },
+        });
+      } catch (_e) { /* drop-silent — best-effort */ }
+    });
+    return encryptMlkemOnly(plaintext, mlkemPubPem);
+  }
 
   var mlkemPub = nodeCrypto.createPublicKey(mlkemPubPem);
   var kem = nodeCrypto.encapsulate(mlkemPub);
@@ -361,6 +380,37 @@ function encryptMlkem768X25519(plaintext, recipient) {
   ]).toString("base64");
 }
 
+// Symmetric named-pair to encryptMlkem768X25519. Operators wiring the
+// IETF / Cloudflare / Chrome TLS-1.3 hybrid (codepoint 0x11EC) want
+// the encrypt + decrypt halves under symmetric, discoverable names.
+//
+// The generic b.crypto.decrypt already dispatches by KEM ID and
+// handles ML_KEM_768_X25519 envelopes correctly; this helper REJECTS
+// any other KEM ID at the head, so an operator who calls
+// decryptMlkem768X25519 with a ciphertext sealed under a different
+// algorithm gets a clear error rather than the generic "unsupported
+// KEM ID" path.
+//
+//   recipient: { privateKey, x25519PrivateKey }   — operator's keys
+//   ciphertext: base64 envelope from encryptMlkem768X25519
+function decryptMlkem768X25519(ciphertext, recipient) {
+  if (!recipient || typeof recipient !== "object" ||
+      !recipient.privateKey || !recipient.x25519PrivateKey) {
+    throw new Error("decryptMlkem768X25519 requires { privateKey, x25519PrivateKey } " +
+                    "(privateKey is the ML-KEM-768 PEM, x25519PrivateKey is the X25519 PEM)");
+  }
+  var packed = Buffer.from(ciphertext, "base64");
+  if (packed[0] !== C.ENVELOPE_MAGIC) {
+    throw new Error("decryptMlkem768X25519: invalid envelope (bad magic byte)");
+  }
+  if (packed[1] !== C.KEM_IDS.ML_KEM_768_X25519) {
+    throw new Error("decryptMlkem768X25519: envelope KEM ID is " + packed[1] +
+                    ", expected " + C.KEM_IDS.ML_KEM_768_X25519 +
+                    " (ML_KEM_768_X25519). Use b.crypto.decrypt for KEM-id dispatch.");
+  }
+  return decryptEnvelope(packed, recipient);
+}
+
 // ---- Cert-peer envelope primitives ----
 //
 // The framework's default `encrypt` / `decrypt` source the recipient
@@ -487,6 +537,65 @@ function decryptEnvelopeAsCertPeer(envelope, opts) {
 // Operator-audit accessor — exposes every supported KEM hybrid for
 // compliance audit visibility ("which envelopes does this deploy
 // accept on decrypt?").
+// ---- Certificate fingerprint helpers ----
+//
+// Operators pinning peer-cert fingerprints (mtls bootstrap, webhook
+// verification, certificate transparency cross-checks) want a stable
+// SHA3-512 hash of the DER bytes plus a colon-separated hex form that
+// matches what most operator tooling renders for X.509 fingerprints.
+// hashCertFingerprint accepts either a Buffer (DER) or a PEM string;
+// if PEM, the BEGIN/END envelope is stripped and the base64 body is
+// decoded before hashing. The hash is the framework's standard SHA3-
+// 512 (not SHA-256 — operators using OpenSSL's `-sha256` defaults can
+// keep their own SHA-256 hashes, this primitive is the framework-
+// canonical form). Returns { hex, colon } so callers can compare
+// against either rendering.
+function _pemToDer(pemOrDer) {
+  if (Buffer.isBuffer(pemOrDer)) return pemOrDer;
+  if (typeof pemOrDer !== "string") {
+    throw new TypeError("crypto.hashCertFingerprint: input must be a Buffer (DER) or a PEM-encoded string");
+  }
+  var match = pemOrDer.match(/-----BEGIN [A-Z0-9 ]+-----([\s\S]+?)-----END [A-Z0-9 ]+-----/);
+  if (!match) {
+    throw new TypeError("crypto.hashCertFingerprint: PEM input lacks BEGIN/END markers");
+  }
+  return Buffer.from(match[1].replace(/\s+/g, ""), "base64");
+}
+function hashCertFingerprint(pemOrDer) {
+  var der = _pemToDer(pemOrDer);
+  var digest = hash(der, "sha3-512");
+  var hex = digest.toString("hex");
+  // Colon-separated, uppercase — matches openssl x509 -fingerprint
+  // output style (which is SHA-1 by default, but the rendering shape
+  // operators expect is the same).
+  var colon = hex.toUpperCase().match(/.{2}/g).join(":");
+  return { hex: hex, colon: colon };
+}
+// Compares a peer's PEM/DER cert against an allowlist of pinned
+// fingerprints. Allowlist entries may be the colon form, the lower-
+// case hex form, or both — every comparison runs through
+// timingSafeEqual to avoid leaking which entry matched.
+function isCertRevoked(pemOrDer, denyList) {
+  if (!Array.isArray(denyList)) {
+    throw new TypeError("crypto.isCertRevoked: denyList must be an array of fingerprint strings");
+  }
+  var fp = hashCertFingerprint(pemOrDer);
+  var fpHex = Buffer.from(fp.hex, "hex");
+  var fpColon = Buffer.from(fp.colon);
+  for (var i = 0; i < denyList.length; i++) {
+    var entry = denyList[i];
+    if (typeof entry !== "string" || entry.length === 0) continue;
+    var normalized = entry.indexOf(":") !== -1 ? entry.toUpperCase() : entry.toLowerCase();
+    var normalizedBuf = entry.indexOf(":") !== -1 ? Buffer.from(normalized) : Buffer.from(normalized, "hex");
+    var compareBuf  = entry.indexOf(":") !== -1 ? fpColon : fpHex;
+    if (normalizedBuf.length === compareBuf.length &&
+        nodeCrypto.timingSafeEqual(normalizedBuf, compareBuf)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 var SUPPORTED_KEM_ALGORITHMS = Object.freeze([
   { id: "ml-kem-1024",          envelopeId: C.KEM_IDS.ML_KEM_1024,        description: "ML-KEM-1024 KEM-only (legacy single-component)" },
   { id: "ml-kem-1024-p384",     envelopeId: C.KEM_IDS.ML_KEM_1024_P384,   description: "ML-KEM-1024 + ECDH P-384 hybrid (framework default)" },
@@ -501,6 +610,9 @@ module.exports = {
   kdf:                         kdf,
   // Comparison
   timingSafeEqual:             timingSafeEqual,
+  // Cert fingerprint helpers
+  hashCertFingerprint:         hashCertFingerprint,
+  isCertRevoked:               isCertRevoked,
   // Random
   generateBytes:               generateBytes,
   generateToken:               generateToken,
@@ -515,6 +627,7 @@ module.exports = {
   encrypt:                     encrypt,
   decrypt:                     decrypt,
   encryptMlkem768X25519:       encryptMlkem768X25519,
+  decryptMlkem768X25519:       decryptMlkem768X25519,
   encryptEnvelopeAsCertPeer:   encryptEnvelopeAsCertPeer,
   decryptEnvelopeAsCertPeer:   decryptEnvelopeAsCertPeer,
   SUPPORTED_KEM_ALGORITHMS:    SUPPORTED_KEM_ALGORITHMS,

package/lib/db.js

@@ -585,7 +585,21 @@ function decryptToTmp() {
   }
   var packed = fs.readFileSync(encPath);
   if (packed.length < 26) return; // too short to be a valid envelope
-  atomicFile.writeSync(dbPath, decryptPacked(packed, encKey));
+  // AAD binds the envelope to this deployment's data dir so two
+  // installs sharing the same operator passphrase can't swap each
+  // other's db.enc files. Backwards-compat: if the AAD-bound decrypt
+  // fails, retry without AAD for envelopes written by pre-AAD
+  // versions (one-release transition window).
+  var aad = _dbEncAad(dataDir);
+  try {
+    atomicFile.writeSync(dbPath, decryptPacked(packed, encKey, aad));
+  } catch (_e) {
+    atomicFile.writeSync(dbPath, decryptPacked(packed, encKey));
+  }
+}
+
+function _dbEncAad(dir) {
+  return Buffer.from("blamejs.db-enc.v1\0" + (dir || ""), "utf8");
 }
 
 function encryptToDisk() {
@@ -593,7 +607,7 @@ function encryptToDisk() {
   // Force WAL checkpoint so the .db file holds all committed transactions.
   try { runSql(database, "PRAGMA wal_checkpoint(TRUNCATE)"); } catch (_e) { /* best effort */ }
   if (!fs.existsSync(dbPath)) return;
-  atomicFile.writeSync(encPath, encryptPacked(fs.readFileSync(dbPath), encKey));
+  atomicFile.writeSync(encPath, encryptPacked(fs.readFileSync(dbPath), encKey, _dbEncAad(dataDir)));
 }
 
 // Remove the plaintext DB + WAL/SHM sidecar files. On Windows these can't be
@@ -691,6 +705,23 @@ async function init(opts) {
   // dominates with audit-chain emissions and cascade fan-out.
   runSql(database, "PRAGMA secure_delete=ON");
 
+  // Boot-time integrity check — refuse to boot on B-tree corruption.
+  // SQLite normally surfaces corruption only when a query stumbles on
+  // a bad page; that's a "first failure during request handling"
+  // surface, not a clean fail-closed boot. integrity_check is fast on
+  // the freshly-decrypted-into-tmpfs file (<1 second on a typical
+  // multi-MB DB) and the result is "ok" or a list of issues.
+  if (opts.skipBootIntegrityCheck !== true) {
+    var ic = database.prepare("PRAGMA integrity_check").all();
+    var icIssues = ic.map(function (r) { return r && r.integrity_check; })
+                     .filter(function (s) { return s && s !== "ok"; });
+    if (icIssues.length > 0) {
+      throw new DbError("db/integrity-check-failed",
+        "PRAGMA integrity_check at boot reported " + icIssues.length +
+        " issue(s): " + icIssues.slice(0, 3).join("; "));
+    }
+  }
+
   // PRAGMA integrity_check — refuse boot on B-tree corruption (per
   // audit-batch finding). SQLite returns "ok" for a healthy database;
   // any other result means corruption. Catching it at boot beats
@@ -1264,7 +1295,7 @@ module.exports = {
         catch (_e) { /* drop-silent */ }
         if (auditOn) {
           try { audit.safeEmit({
-            action: "system.db.integrity_ok", outcome: "ok", metadata: {},
+            action: "system.db.integrity_ok", outcome: "success", metadata: {},
           }); } catch (_e) { /* drop-silent */ }
         }
         return;
@@ -1274,7 +1305,7 @@ module.exports = {
       catch (_e) { /* drop-silent */ }
       if (auditOn) {
         try { audit.safeEmit({
-          action: "system.db.integrity_corrupt", outcome: "fail",
+          action: "system.db.integrity_corrupt", outcome: "failure",
           metadata: { issueCount: issues.length },
         }); } catch (_e) { /* drop-silent */ }
       }

package/lib/dev.js

@@ -48,13 +48,24 @@
  */
 
 var path = require("path");
-var childProcess = require("child_process");
 var fs = require("fs");
+var lazyRequire = require("./lazy-require");
 var logModule = require("./log");
 var nb = require("./numeric-bounds");
+var safeEnv = require("./parsers/safe-env");
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
+// child_process is required ONLY when dev.create() is actually
+// called — not at module load. The dev primitive spawns subprocesses
+// (nodemon-style restart loop) by design; isolating the dependency
+// behind lazy-load means a production process that never calls
+// b.dev.create() never loads child_process, and supply-chain scanners
+// inspecting a deployed bundle don't see it as a top-level dep of an
+// otherwise hermetic framework. Production deployments additionally
+// refuse to construct dev.create() — see _refuseInProduction below.
+var childProcess = lazyRequire(function () { return require("child_process"); });
+
 class DevError extends FrameworkError {
   constructor(code, message) {
     super(message, code);
@@ -123,9 +134,25 @@ function create(opts) {
   var env          = opts.env || process.env;
   var cwd          = opts.cwd || process.cwd();
 
-  // Test seams
+  // dev.create() is intended for development-mode use only —
+  // restarting subprocesses on file change is a feature operators
+  // run on their laptop, never in production. Refusing here means a
+  // mis-configured production deployment that accidentally wires the
+  // dev primitive crashes loudly at boot rather than spawning shells
+  // on every save. Operators with a legitimate cross-cutting need
+  // (e.g. a CI runner that uses dev() to drive end-to-end tests)
+  // explicitly opt in via opts.allowProduction with an audited reason.
+  if (safeEnv.readVar("NODE_ENV") === "production" && !opts.allowProduction) {
+    throw new DevError("dev/refused-in-production",
+      "b.dev.create: dev mode refuses to load when NODE_ENV=production. " +
+      "Set opts.allowProduction:true with an audited reason if a non-dev " +
+      "context legitimately needs subprocess spawn-on-watch behaviour.");
+  }
+
+  // Test seams. childProcess is lazily-required; calling spawn here
+  // pulls in node's child_process module on first dev.create() use.
   var spawnFn = opts._spawn || function (cmd, sargs, sopts) {
-    return childProcess.spawn(cmd, sargs, sopts);
+    return childProcess().spawn(cmd, sargs, sopts);
   };
   var watchFn = opts._watch || function (dir, wopts, listener) {
     return fs.watch(dir, wopts, listener);

package/lib/dual-control.js

@@ -186,7 +186,25 @@ function create(opts) {
     if (!approverRoles) return true;
     if (!actor || !Array.isArray(actor.roles)) return false;
     for (var i = 0; i < approverRoles.length; i++) {
-      if (actor.roles.indexOf(approverRoles[i]) !== -1) return true;
+      var required = approverRoles[i];
+      // Wildcard match — actor's "security:*" satisfies a required
+      // "security:officer" (matching the b.permissions.match
+      // semantics elsewhere in the framework). Without this, an
+      // operator with a wildcard-shaped role can't approve dual-
+      // control flows even when b.permissions would consider the
+      // role assignment satisfied.
+      for (var j = 0; j < actor.roles.length; j++) {
+        var actorRole = actor.roles[j];
+        if (actorRole === required) return true;
+        if (typeof actorRole === "string" &&
+            actorRole.length > 0 &&
+            actorRole.charAt(actorRole.length - 1) === "*") {
+          var prefix = actorRole.slice(0, -1);
+          if (typeof required === "string" && required.indexOf(prefix) === 0) {
+            return true;
+          }
+        }
+      }
     }
     return false;
   }

package/lib/external-db.js

@@ -570,6 +570,16 @@ function _buildSessionGucsStatements(sessionGucs) {
       // Postgres SET accepts on/off/true/false — render true/false.
       literal = value ? "true" : "false";
     } else if (typeof value === "string") {
+      // Cap the value length so an operator-controlled tenant_id of
+      // 100 KB doesn't hit Postgres' SET LOCAL parser with payload
+      // that bloats query logs and consumes max_stack_depth. The cap
+      // is generous for legitimate tenant identifiers but rejects
+      // amplification.
+      if (value.length > C.BYTES.kib(4)) {
+        throw _err("INVALID_SESSION_GUCS",
+          "sessionGucs['" + name + "']: value exceeds 4 KiB cap (got " +
+          value.length + " chars)", true);
+      }
       literal = "'" + value.replace(/'/g, "''") + "'";
     } else if (value === null || value === undefined) {
       throw _err("INVALID_SESSION_GUCS",

package/lib/file-upload.js

@@ -763,7 +763,7 @@ function create(opts) {
     return { paths: paths, totalBytes: totalBytes, totalHashHex: totalHashHex };
   }
 
-  function _checkAllowedFileType(firstChunkBody) {
+  function _checkAllowedFileType(firstChunkBody, claimedMime) {
     if (!allowedFileTypes || allowedFileTypes.length === 0) return;
     if (!fileType) return;   // create() guards this; defensive
     var detected = fileType.detect(firstChunkBody);
@@ -787,6 +787,30 @@ function create(opts) {
         "fileUpload.finalize: detected MIME '" + detectedMime +
         "' not in allowedFileTypes (" + allowedFileTypes.join(", ") + ")");
     }
+    // Cross-check claimed MIME (Content-Type header) against detected
+    // magic bytes. When both exist and disagree, refuse — downstream
+    // renderers / storage layers that trust metadata.contentType
+    // (CDN cache routing, MIME-sniff fallbacks, attachment-disposition
+    // decisions) will mis-handle the file. The strict-MIME check is
+    // load-bearing for image-pipelines that pass to image processors:
+    // a "image/png" claim with PDF magic bytes lands in image-rendering
+    // code-paths that will exec PDF parsers with surprising semantics.
+    if (claimedMime && typeof claimedMime === "string" && claimedMime.indexOf("/") !== -1) {
+      var claimedNormalized = claimedMime.split(";")[0].trim().toLowerCase();
+      if (claimedNormalized && claimedNormalized !== detectedMime) {
+        // Wildcard / family acceptance: "image/jpeg" claim + "image/jpg"
+        // detect (synonyms) is OK; "image/png" claim + "image/jpeg"
+        // detect is NOT.
+        var claimedFamily = claimedNormalized.split("/")[0];
+        var detectedFamily = detectedMime.split("/")[0];
+        if (claimedFamily !== detectedFamily) {
+          throw _err("MIME_CLAIM_MISMATCH",
+            "fileUpload.finalize: claimed Content-Type '" + claimedNormalized +
+            "' disagrees with detected magic-byte MIME '" + detectedMime +
+            "'. Refusing to proceed with mis-typed file.");
+        }
+      }
+    }
   }
 
   function _streamFromChunkPaths(paths /* totalBytes */) {
@@ -842,8 +866,11 @@ function create(opts) {
       firstChunk = pieces[0];
     }
 
-    // MIME allowlist gate (if configured).
-    try { _checkAllowedFileType(firstChunk); }
+    // MIME allowlist gate (if configured). Pass the operator-supplied
+    // contentType from upload metadata so the cross-check can refuse
+    // claimed-vs-detected mismatches.
+    var claimedMime = (meta && meta.metadata && meta.metadata.contentType) || null;
+    try { _checkAllowedFileType(firstChunk, claimedMime); }
     catch (e) {
       _emitObs("fileUpload.mime_rejected", 1);
       _emitAudit("fileUpload.finalize", {

package/lib/flag-cache.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Flag-evaluation cache — per-targetingKey TTL'd cache wrapping a
+ * downstream provider so a high-traffic request path does not hit
+ * the provider on every flag read.
+ *
+ *   var raw = b.flag.providers.localFile({ path: "./flags.json", watch: true });
+ *   var cached = b.flag.cache(raw, { ttlMs: 60_000, maxEntries: 10000 });
+ *
+ *   var flag = b.flag.create({ provider: cached });
+ *
+ * Cache key: `${targetingKey}::${flagKey}`. Entries TTL out after
+ * `ttlMs` (default 30 s). When the cache hits its `maxEntries` cap,
+ * oldest entries are evicted (insertion-order via a Map).
+ *
+ * Cache is bypassed for evaluation contexts without a `targetingKey`
+ * (flag value depends on every attribute, not a stable key).
+ *
+ * Operators with a hot-reload need pass `bustOn: "flag-reload"` and
+ * call `cached.bust()` from their reload handler — clears the entire
+ * map.
+ */
+
+var validateOpts = require("./validate-opts");
+var lazyRequire  = require("./lazy-require");
+var C            = require("./constants");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+function cache(downstream, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["ttlMs", "maxEntries", "audit"], "flag.cache");
+  if (!downstream || typeof downstream.evaluate !== "function") {
+    throw new FlagError("flag/bad-cache",
+      "cache: downstream provider must implement .evaluate()");
+  }
+  // allow:numeric-opt-Infinity — defaults clamped + ttl-floor enforced below
+  var ttlMs = (typeof opts.ttlMs === "number" && opts.ttlMs > 0)
+    ? opts.ttlMs
+    : C.TIME.seconds(30);
+  if (ttlMs < C.TIME.seconds(1)) {
+    throw new FlagError("flag/bad-cache",
+      "cache: ttlMs must be >= 1000ms - got " + ttlMs);
+  }
+  // allow:numeric-opt-Infinity — maxEntries default + Math.floor coerce; throws on bad type at config time
+  var maxEntries = (typeof opts.maxEntries === "number" && opts.maxEntries > 0)
+    ? Math.floor(opts.maxEntries)
+    : 10000;                                       // allow:raw-byte-literal — entry-count default
+  var auditOn = opts.audit === true;            // off by default — too chatty
+  var entries = new Map();
+  var hits   = 0;
+  var misses = 0;
+  var evictions = 0;
+
+  function _evictExpired(nowMs) {
+    var iter = entries.entries();
+    var step = iter.next();
+    while (!step.done) {
+      if (step.value[1].expiresAt <= nowMs) {
+        entries.delete(step.value[0]);
+        evictions += 1;
+      }
+      step = iter.next();
+    }
+  }
+
+  function _evictOldest() {
+    var first = entries.keys().next();
+    if (!first.done) {
+      entries.delete(first.value);
+      evictions += 1;
+    }
+  }
+
+  return {
+    kind: "cache:" + (downstream.kind || "unknown"),
+    list: typeof downstream.list === "function"
+      ? function () { return downstream.list(); }
+      : function () { return []; },
+    evaluate: function (flagKey, ctx) {
+      var tk = (ctx && typeof ctx.targetingKey === "string") ? ctx.targetingKey : null;
+      if (!tk) {
+        misses += 1;
+        return downstream.evaluate(flagKey, ctx);
+      }
+      var key = tk + "::" + flagKey;
+      var now = Date.now();
+      var entry = entries.get(key);
+      if (entry && entry.expiresAt > now) {
+        hits += 1;
+        return entry.value;
+      }
+      if (entry) entries.delete(key);
+      var freshResult = downstream.evaluate(flagKey, ctx);
+      misses += 1;
+      // Don't cache flag-not-found — operator might add it later.
+      if (freshResult && freshResult.reason !== "flag_not_found") {
+        if (entries.size >= maxEntries) _evictOldest();
+        entries.set(key, { value: freshResult, expiresAt: now + ttlMs });
+      }
+      // Periodic sweep — evict expired on every 100th miss.
+      if (misses % 100 === 0) _evictExpired(now);
+      return freshResult;
+    },
+    bust: function () {
+      var prevSize = entries.size;
+      entries.clear();
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:   "flag.cache.bust",
+            outcome:  "success",
+            actor:    null,
+            metadata: { prevSize: prevSize },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      return prevSize;
+    },
+    stats: function () {
+      return {
+        size:      entries.size,
+        hits:      hits,
+        misses:    misses,
+        evictions: evictions,
+        hitRatio:  (hits + misses) === 0 ? 0 : hits / (hits + misses),
+        ttlMs:     ttlMs,
+        maxEntries: maxEntries,
+      };
+    },
+  };
+}
+
+module.exports = { cache: cache, FlagError: FlagError };

package/lib/flag-evaluation-context.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Flag evaluation context — the operator-supplied object describing
+ * the subject of a flag evaluation: targeting key, user attributes,
+ * tenant id, environment, custom attributes.
+ *
+ * Per the OpenFeature specification:
+ *   - `targetingKey` is the canonical identity for percentage-bucket
+ *     stickiness (so a 50% rollout consistently picks the SAME 50%
+ *     of users across re-evaluations).
+ *   - All other attributes flow through targeting rules.
+ *
+ * The framework's helper produces a frozen, normalised context object.
+ * Operators compose contexts incrementally: start from `fromRequest`
+ * (extracts user / tenant / locale from req), augment with `merge`,
+ * then evaluate.
+ */
+
+var nodeCrypto    = require("crypto");
+var validateOpts  = require("./validate-opts");
+var lazyRequire   = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var fwCrypto = lazyRequire(function () { return require("./crypto"); });
+
+function _normalize(input, label) {
+  if (input == null) return {};
+  if (typeof input !== "object" || Array.isArray(input)) {
+    throw new FlagError("flag/bad-context",
+      (label || "context") + ": must be a plain object");
+  }
+  var out = {};
+  for (var key in input) {
+    if (!Object.prototype.hasOwnProperty.call(input, key)) continue;
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+      continue;                                          // poisoned-keys defense
+    }
+    out[key] = input[key];
+  }
+  return out;
+}
+
+function create(input) {
+  var normalised = _normalize(input, "create");
+  if (normalised.targetingKey != null &&
+      typeof normalised.targetingKey !== "string") {
+    throw new FlagError("flag/bad-context",
+      "create: targetingKey must be a string");
+  }
+  return Object.freeze(normalised);
+}
+
+function merge(base, overlay) {
+  var b = _normalize(base, "merge.base");
+  var o = _normalize(overlay, "merge.overlay");
+  var out = {};
+  for (var k1 in b) {
+    if (Object.prototype.hasOwnProperty.call(b, k1)) out[k1] = b[k1];
+  }
+  for (var k2 in o) {
+    if (Object.prototype.hasOwnProperty.call(o, k2)) out[k2] = o[k2];
+  }
+  return Object.freeze(out);
+}
+
+function fromRequest(req, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["userKey", "tenantKey", "extra"], "flag.context.fromRequest");
+  if (!req || typeof req !== "object") {
+    return create({});
+  }
+  var ctx = {};
+  if (req.user) {
+    if (typeof req.user.id === "string")    ctx.userId = req.user.id;
+    if (typeof req.user.role === "string")  ctx.role   = req.user.role;
+    if (typeof req.user.email === "string") ctx.email  = req.user.email;
+    if (req.user.tenantId != null)          ctx.tenantId = req.user.tenantId;
+  }
+  var headers = req.headers || {};
+  if (typeof headers["accept-language"] === "string") {
+    ctx.locale = headers["accept-language"].split(",")[0].split(";")[0].trim();
+  }
+  if (typeof headers["user-agent"] === "string") {
+    ctx.userAgent = headers["user-agent"];
+  }
+  // Targeting key: prefer explicit userKey opt, then user.id, then a
+  // request-stable hash of (clientIp + userAgent) for anonymous flows.
+  var tk = null;
+  if (typeof opts.userKey === "string" && opts.userKey.length > 0) {
+    tk = opts.userKey;
+  } else if (req.user && typeof req.user.id === "string") {
+    tk = req.user.id;
+  } else {
+    var ip = (typeof headers["x-forwarded-for"] === "string" &&
+              headers["x-forwarded-for"].split(",")[0].trim()) ||
+             (req.connection && req.connection.remoteAddress) || "";
+    var ua = headers["user-agent"] || "";
+    tk = "anon:" + fwCrypto().sha3Hash(ip + ":" + ua).slice(0, 16);   // allow:raw-byte-literal — base16 prefix len
+  }
+  ctx.targetingKey = tk;
+
+  if (opts.extra && typeof opts.extra === "object") {
+    for (var k in opts.extra) {
+      if (Object.prototype.hasOwnProperty.call(opts.extra, k)) {
+        if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+        ctx[k] = opts.extra[k];
+      }
+    }
+  }
+  return create(ctx);
+}
+
+// Percentage-bucket helper — deterministic hash of (targetingKey +
+// flagKey) into [0, 100) for percentage-based rollouts.
+function bucketOf(targetingKey, flagKey) {
+  if (typeof targetingKey !== "string" || typeof flagKey !== "string" ||
+      targetingKey.length === 0 || flagKey.length === 0) {
+    return 0;
+  }
+  var digest = nodeCrypto.createHash("sha3-512")
+    .update(flagKey + ":" + targetingKey).digest();
+  // Use first 4 bytes as a uint32, then mod 10000 → 0.00-99.99 with
+  // sub-percent granularity.
+  var n = digest.readUInt32BE(0);
+  return (n % 10000) / 100;                                 // allow:raw-byte-literal — bucket-precision divisor
+}
+
+module.exports = {
+  create:       create,
+  merge:        merge,
+  fromRequest:  fromRequest,
+  bucketOf:     bucketOf,
+  FlagError:    FlagError,
+};