@blamejs/core 0.4.1

package/lib/consent.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * Consent log — GDPR Art. 6/7 lawful-basis tracking with hash chain.
+ *
+ * consent_log is baked into db.js's schema runner alongside audit_log.
+ * Same tamper-evidence design: per-row SHA3-512 hash chain, append-only,
+ * verified at boot.
+ *
+ * Lawful-basis consistency: any audit-recorded operation declared under
+ * `lawfulBasis: 'consent'` should reference a current consent_log entry.
+ * The framework records consent grants/withdrawals here; enforcement of
+ * consent before processing is the app's responsibility — query
+ * `consent.isActive(subjectId, purpose)` at the trust boundary.
+ *
+ * Public API:
+ *   consent.grant({ subjectId, purpose, lawfulBasis, scope?, channel, evidenceRef? })
+ *   consent.withdraw({ subjectId, purpose, reason? })
+ *   consent.isGranted({ subjectId, purpose }) → boolean
+ *   consent.history(subjectId) → array of consent_log rows (decrypted)
+ *   consent.verify() → { ok, rowsVerified, breakAt? }
+ */
+var auditChain = require("./audit-chain");
+var cluster = require("./cluster");
+var clusterStorage = require("./cluster-storage");
+var chainWriter = require("./chain-writer");
+var safeAsync = require("./safe-async");
+var lazyRequire = require("./lazy-require");
+var C = require("./constants");
+var { ClusterError } = require("./framework-error");
+
+// Wall-clock cap on the tip upsert. Same value as audit's
+// FRAMEWORK_SQL_TIMEOUT_MS — a misbehaving external-db driver
+// shouldn't hang a consent write forever.
+var FRAMEWORK_SQL_TIMEOUT_MS = C.TIME.seconds(30);
+
+var LAWFUL_BASES = ["consent", "contract", "legal_obligation", "vital_interests", "public_task", "legitimate_interests"];
+var ACTIONS = ["granted", "withdrawn", "expired", "superseded"];
+
+var HASHABLE_COLS = [
+  "_id", "recordedAt", "monotonicCounter",
+  "subjectId", "subjectIdHash",
+  "purpose", "lawfulBasis", "action",
+  "scope", "channel", "evidenceRef",
+];
+
+var db = lazyRequire(function () { return require("./db"); });
+
+// Race-safe chain append for consent_log. Inherits the same Mutex /
+// counter-primer / retry-wrapped reads / timeout-bounded writes that
+// audit_log uses. (Before this primitive landed, consent.js had a chain-
+// fork race identical to audit.js's pre-Mutex bug; switching to chain-
+// writer fixes it as a side effect of consolidating the duplication.)
+var _chainWriter = chainWriter.create({
+  table:           "consent_log",
+  hashableColumns: HASHABLE_COLS,
+  columnsForInsert: [
+    "_id", "recordedAt", "monotonicCounter",
+    "subjectId", "subjectIdHash",
+    "purpose", "lawfulBasis", "action",
+    "scope", "channel", "evidenceRef",
+    "prevHash", "rowHash", "nonce", "fencingToken",
+  ],
+});
+
+// ---- Public API ----
+
+function grant(opts) {
+  cluster.requireLeader();
+  if (!opts || !opts.subjectId || !opts.purpose || !opts.lawfulBasis || !opts.channel) {
+    throw new Error("consent.grant requires { subjectId, purpose, lawfulBasis, channel }");
+  }
+  if (LAWFUL_BASES.indexOf(opts.lawfulBasis) === -1) {
+    throw new Error("invalid lawfulBasis: '" + opts.lawfulBasis + "' (must be one of " + LAWFUL_BASES.join(", ") + ")");
+  }
+  return _appendConsentRow({
+    subjectId:    opts.subjectId,
+    purpose:      opts.purpose,
+    lawfulBasis:  opts.lawfulBasis,
+    action:       "granted",
+    scope:        opts.scope ? JSON.stringify(opts.scope) : null,
+    channel:      opts.channel,
+    evidenceRef:  opts.evidenceRef || null,
+  });
+}
+
+function withdraw(opts) {
+  cluster.requireLeader();
+  if (!opts || !opts.subjectId || !opts.purpose) {
+    throw new Error("consent.withdraw requires { subjectId, purpose }");
+  }
+  return _appendConsentRow({
+    subjectId:    opts.subjectId,
+    purpose:      opts.purpose,
+    lawfulBasis:  "consent",
+    action:       "withdrawn",
+    scope:        null,
+    channel:      opts.channel || "api",
+    evidenceRef:  opts.reason ? "reason:" + opts.reason : null,
+  });
+}
+
+function isGranted(opts) {
+  if (!opts || !opts.subjectId || !opts.purpose) {
+    throw new Error("consent.isGranted requires { subjectId, purpose }");
+  }
+  // Find the most recent consent row for this (subjectId, purpose).
+  // subjectId is sealed → look up via subjectIdHash (derived).
+  var hash = db().hashFor("consent_log", "subjectId", opts.subjectId);
+  if (!hash) {
+    throw new Error("consent_log subjectId is missing a derived hash — schema misconfigured");
+  }
+  var row = db().prepare(
+    "SELECT action FROM consent_log WHERE subjectIdHash = ? AND purpose = ? " +
+    "ORDER BY monotonicCounter DESC LIMIT 1"
+  ).get(hash, opts.purpose);
+  if (!row) return false;
+  return row.action === "granted";
+}
+
+function history(subjectId) {
+  if (!subjectId) throw new Error("consent.history requires a subjectId");
+  var hash = db().hashFor("consent_log", "subjectId", subjectId);
+  if (!hash) {
+    throw new Error("consent_log subjectId is missing a derived hash — schema misconfigured");
+  }
+  var rows = db().from("consent_log")
+    .where({ subjectIdHash: hash })
+    .orderBy("monotonicCounter", "asc")
+    .all();
+  return rows;
+}
+
+async function verify(opts) {
+  return await auditChain.verifyChain(
+    function (sql, params) { return clusterStorage.executeAll(sql, params || []); },
+    "consent_log",
+    opts
+  );
+}
+
+// ---- Internal: append a chain-linked row ----
+
+async function _appendConsentRow(fields) {
+  if (ACTIONS.indexOf(fields.action) === -1) {
+    throw new Error("invalid consent action: " + fields.action);
+  }
+  var row = await _chainWriter.append({
+    subjectId:        fields.subjectId,
+    purpose:          fields.purpose,
+    lawfulBasis:      fields.lawfulBasis,
+    action:           fields.action,
+    scope:            fields.scope,
+    channel:          fields.channel,
+    evidenceRef:      fields.evidenceRef,
+  });
+  // Cluster mode: keep _blamejs_consent_tip current so cluster.init's
+  // boot-time rollback check has an authoritative tip to compare
+  // against. Mirrors the audit-tip upsert pattern from audit.js with
+  // the same WHERE-clause fencing guard.
+  if (cluster.isClusterMode()) {
+    await _upsertConsentTip(
+      Number(row.monotonicCounter),
+      row.rowHash,
+      String(row.recordedAt),
+      cluster.fencingToken()
+    );
+  }
+  return row;
+}
+
+async function _upsertConsentTip(counter, rowHash, signedAt, fencingToken) {
+  // Single atomic INSERT … ON CONFLICT DO UPDATE … WHERE … RETURNING.
+  // Same canonical fencing-token guard as _blamejs_audit_tip: the
+  // WHERE clause enforces monotonic-non-decreasing fencingToken at
+  // the DB level so a partitioned old leader can't overwrite the tip
+  // even if its application-layer cluster.requireLeader() gate let
+  // the call through.
+  var result = await safeAsync.withTimeout(
+    clusterStorage.execute(
+      "INSERT INTO _blamejs_consent_tip " +
+      "  (scope, atMonotonicCounter, rowHash, signedAt, fencingToken) " +
+      "VALUES ('consent', ?, ?, ?, ?) " +
+      "ON CONFLICT (scope) DO UPDATE SET " +
+      "  atMonotonicCounter = EXCLUDED.atMonotonicCounter, " +
+      "  rowHash            = EXCLUDED.rowHash, " +
+      "  signedAt           = EXCLUDED.signedAt, " +
+      "  fencingToken       = EXCLUDED.fencingToken " +
+      "WHERE _blamejs_consent_tip.fencingToken <= EXCLUDED.fencingToken " +
+      "RETURNING fencingToken",
+      [counter, rowHash, signedAt, fencingToken]
+    ),
+    FRAMEWORK_SQL_TIMEOUT_MS,
+    { name: "consent.upsertConsentTip" }
+  );
+  if (!result.rows || result.rows.length === 0) {
+    throw new ClusterError(
+      "FENCED_OUT",
+      "consent-tip update rejected: incoming fencingToken=" + fencingToken +
+      " is below the stored token (this leader has been fenced out " +
+      "by a higher-token successor)",
+      true
+    );
+  }
+}
+
+// ---- Test helpers ----
+
+function _resetForTest() {
+  _chainWriter._resetForTest();
+  db.reset();
+}
+
+module.exports = {
+  grant:         grant,
+  withdraw:      withdraw,
+  isGranted:     isGranted,
+  history:       history,
+  verify:        verify,
+  LAWFUL_BASES:  LAWFUL_BASES,
+  ACTIONS:       ACTIONS,
+  _resetForTest: _resetForTest,
+};

package/lib/constants.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Framework constants — values fixed by blamejs design.
+ *
+ * App-specific values (paths, asset versions, theme, animation, OAuth
+ * allowlists) are supplied via createApp() configuration in the consuming
+ * app. Nothing in this file is mutable per-deployment.
+ *
+ * Naming follows the roadmap "Naming conventions" section: SCREAMING_SNAKE
+ * for constants, lowercase namespace exports.
+ */
+
+var pkg = require("../package.json");
+
+// ---- Time helpers (ms) ----
+// Functional generators instead of pre-defined discrete constants:
+// any duration the framework or app needs is built from these, so the
+// reader sees the unit at the call site (`C.TIME.minutes(45)` instead of
+// adding a new FORTY_FIVE_MIN constant). All return integer milliseconds.
+//
+// Tier A validation: these are config-time helpers. Throw on non-finite
+// or negative input so a typo (`C.TIME.minutes(opts.x)` where opts.x is
+// undefined) surfaces at boot instead of silently becoming `NaN` or `0`
+// and shipping a 0ms timeout into production.
+function _validateDuration(unit, n) {
+  if (typeof n !== "number" || !isFinite(n) || n < 0) {
+    throw new TypeError("C.TIME." + unit + ": expected non-negative finite number, got " +
+      (typeof n) + " " + JSON.stringify(n));
+  }
+}
+var TIME = Object.freeze({
+  seconds: function (n) { _validateDuration("seconds", n); return n * 1000; },
+  minutes: function (n) { _validateDuration("minutes", n); return n * 60000; },
+  hours:   function (n) { _validateDuration("hours",   n); return n * 3600000; },
+  days:    function (n) { _validateDuration("days",    n); return n * 86400000; },
+  weeks:   function (n) { _validateDuration("weeks",   n); return n * 604800000; },
+});
+
+// ---- Byte helpers (binary / IEC units) ----
+// Same pattern as TIME — units at the call site instead of pre-baked
+// constants. Returns bytes; multiplications are 1024-based per IEC 80000-13
+// (KiB/MiB/GiB), since every existing byte literal in the framework
+// already uses 1024 multiplication.
+//
+// Tier A validation: same rationale as TIME — bad input surfaces at the
+// call site, not as a silent NaN cap that disables size limits.
+function _validateBytes(unit, n) {
+  if (typeof n !== "number" || !isFinite(n) || n < 0) {
+    throw new TypeError("C.BYTES." + unit + ": expected non-negative finite number, got " +
+      (typeof n) + " " + JSON.stringify(n));
+  }
+}
+var BYTES = Object.freeze({
+  kib: function (n) { _validateBytes("kib", n); return n * 1024; },
+  mib: function (n) { _validateBytes("mib", n); return n * 1024 * 1024; },
+  gib: function (n) { _validateBytes("gib", n); return n * 1024 * 1024 * 1024; },
+});
+
+// ---- Crypto envelope versioning ----
+// Every encrypted blob starts with a 4-byte header that identifies the
+// algorithms used. This enables algorithm agility — any component can
+// be swapped without re-encrypting existing data. Old envelopes always
+// remain readable; new writes use ACTIVE.{KEM, CIPHER, KDF}.
+//
+// See roadmap "Modernity posture: highest practical bar, forward only"
+// for the algorithm rotation policy.
+
+var ENVELOPE_MAGIC = 0xE1;
+
+var KEM_IDS = Object.freeze({
+  ML_KEM_1024:        0x02,
+  ML_KEM_1024_P384:   0x03,
+});
+
+var CIPHER_IDS = Object.freeze({
+  XCHACHA20_POLY1305: 0x02,
+});
+
+var KDF_IDS = Object.freeze({
+  SHAKE256:           0x02,
+});
+
+// ---- Credential hash envelope (separate from data envelope) ----
+// Used for storing verifiable digests of credentials (API key secrets,
+// shared bearer tokens, etc.) where the framework needs forward-
+// compatible algorithm rotation. The credential envelope format is:
+//
+//   byte 0: 0xC1 (CREDENTIAL_MAGIC — distinct from 0xE1 storage envelope)
+//   byte 1: <CRED_HASH_IDS algorithm ID>
+//   bytes 2..N: algorithm-specific payload
+//
+// Encoded base64 (URL-safe) so the column type stays TEXT. The verify
+// path dispatches on byte 1, so historical credentials always remain
+// verifiable regardless of what ACTIVE.CRED_HASH points at today.
+//
+// Why a separate magic byte from 0xE1: storage-envelope blobs and
+// credential-envelope strings live in different columns and have
+// different lifetimes; making the magic byte distinct prevents a
+// confused-deputy mix-up where a corrupted credential field decodes
+// as a storage envelope.
+
+var CREDENTIAL_MAGIC = 0xC1;
+
+var CRED_HASH_IDS = Object.freeze({
+  SHAKE256:   0x01,    // XOF digest of operator-chosen length. Default
+                       // 64 bytes; payload length itself drives the
+                       // output size on verify, so a future operator
+                       // can request 96 bytes without an algorithm
+                       // rotation. Suitable for high-entropy secrets
+                       // (>= 128 bits random) where memory-hardness
+                       // buys nothing. Same family as the framework
+                       // KDF, so the verify path uses one primitive.
+  ARGON2ID:   0x02,    // PHC string payload. Suitable for low-entropy
+                       // or paranoia-mode storage; cost ~250ms per
+                       // verify. Defer to b.auth.password's PHC parser.
+});
+
+var ACTIVE = Object.freeze({
+  KEM:        KEM_IDS.ML_KEM_1024_P384,
+  CIPHER:     CIPHER_IDS.XCHACHA20_POLY1305,
+  KDF:        KDF_IDS.SHAKE256,
+  CRED_HASH:  CRED_HASH_IDS.SHAKE256,
+});
+
+// ---- Storage-buffer envelope marker ----
+// Used by encryptPacked / decryptPacked for symmetric buffer encryption.
+// Single-byte version preceding nonce + ciphertext.
+var FORMAT = Object.freeze({
+  XCHACHA20_POLY1305: 0x02,
+});
+
+// ---- PQC TLS group IDs (IANA TLS Supported Groups Registry) ----
+var PQC_GROUPS = Object.freeze({
+  X25519MLKEM768:        0x11EC,
+  SecP384r1MLKEM1024:    0x11ED,
+});
+
+// Highest-first preference list. Node TLS picks the first mutually-
+// supported group during the handshake, so SecP384r1MLKEM1024
+// (P-384 + ML-KEM-1024) is what we always use when the peer also
+// advertises it. X25519MLKEM768 is the only fallback — both are
+// PQC hybrids with current standardized parameter sets.
+//
+// Weaker hybrids (e.g. P-256 + ML-KEM-768) are deliberately excluded
+// from the framework's default preference. An operator integrating
+// with a peer that only supports a weaker PQC group constructs their
+// own https.Agent outside lib/pqc-agent so the downgrade is visible
+// in the diff — the framework primitive cannot be coaxed into
+// negotiating below this list.
+var TLS_GROUP_PREFERENCE = Object.freeze([
+  "SecP384r1MLKEM1024",
+  "X25519MLKEM768",
+]);
+
+var TLS_GROUP_CURVE_STR = TLS_GROUP_PREFERENCE.join(":");
+
+// ---- Vault sealed-value prefix ----
+var VAULT_PREFIX = "vault:";
+
+// ---- Default hash namespaces for derived-hash indexed lookups ----
+// Apps add their own via app-config registries. The 'bj-' namespace
+// prevents collision between framework-derived and app-derived hashes.
+var HASH_PREFIX = Object.freeze({
+  EMAIL:       "bj-email:",
+  IP:          "bj-ip:",
+  TOKEN:       "bj-token:",
+});
+
+module.exports = {
+  version:                pkg.version,
+  TIME:                   TIME,
+  BYTES:                  BYTES,
+  ENVELOPE_MAGIC:         ENVELOPE_MAGIC,
+  CREDENTIAL_MAGIC:       CREDENTIAL_MAGIC,
+  KEM_IDS:                KEM_IDS,
+  CIPHER_IDS:             CIPHER_IDS,
+  KDF_IDS:                KDF_IDS,
+  CRED_HASH_IDS:          CRED_HASH_IDS,
+  ACTIVE:                 ACTIVE,
+  FORMAT:                 FORMAT,
+  PQC_GROUPS:             PQC_GROUPS,
+  TLS_GROUP_PREFERENCE:   TLS_GROUP_PREFERENCE,
+  TLS_GROUP_CURVE_STR:    TLS_GROUP_CURVE_STR,
+  VAULT_PREFIX:           VAULT_PREFIX,
+  HASH_PREFIX:            HASH_PREFIX,
+};