@blamejs/core 0.14.27 → 0.15.0

package/lib/cluster.js

@@ -50,16 +50,88 @@ var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
-var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
 var validateOpts = require("./validate-opts");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
+// The external-DB schema quotes every column identifier, so Postgres
+// stores them case-preserving. The boot-time chain-tip + vault-key-
+// consistency statements compose through b.sql, which quotes every
+// identifier by construction (double-quote on Postgres / SQLite, backtick
+// on MySQL) so an unquoted fold-to-lowercase reference can't miss the
+// column.
+
 // Lazy: vault → db → cluster forms a load-time chain, and external-db is
 // loaded before its init has run; both are safe to call once cluster
 // reaches runtime, but eager require here would deadlock the load order.
 var externalDb = lazyRequire(function () { return require("./external-db"); });
 var vault = lazyRequire(function () { return require("./vault"); });
+// b.sql builder + the `?`->`$N` placeholderizer + the framework-table
+// name resolver. clusterStorage requires cluster, so these are lazy to
+// stay clear of the load cycle; resolved at runtime when the boot-time
+// rollback / vault-key-consistency checks run.
+var sql = lazyRequire(function () { return require("./sql"); });
+var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
+var frameworkSchema = lazyRequire(function () { return require("./framework-schema"); });
+
+// b.sql speaks postgres | sqlite | mysql; the cluster's configuredDialect
+// is one of those (validated at init). Used so the boot-time chain-tip /
+// vault-key-consistency statements emit the right identifier quoting.
+function _bDialect() {
+  return configuredDialect === "mysql" ? "mysql"
+       : configuredDialect === "sqlite" ? "sqlite" : "postgres";
+}
+
+// Emit a b.sql builder + run it against the configured external-DB
+// backend. b.sql emits `?` placeholders; the externalDb driver receives
+// the SQL verbatim, so translate to `$N` for Postgres (passthrough for
+// SQLite / MySQL).
+function _runClusterQuery(builder) {
+  var built = builder.toSql();
+  return externalDb().query(
+    clusterStorage().placeholderize(built.sql, configuredDialect),
+    built.params,
+    { backend: configuredExternalDbBackend }
+  );
+}
+
+// "The framework-internal table this check needs does not exist yet" —
+// the signal that a gates-only cluster (leader election wired, but
+// framework state still resident in per-node SQLite without
+// frameworkSchema.ensureSchema) should SKIP the boot-time rollback /
+// vault-key-consistency check instead of FATAL-refusing boot. Each
+// backend phrases the missing-relation fault differently, and not all
+// drivers carry a stable structured code, so this matches BOTH the
+// driver phrasing AND the portable code/SQLSTATE when present:
+//
+//   - SQLite:    "no such table: X"
+//   - Postgres:  "relation "X" does not exist"  (SQLSTATE 42P01)
+//   - MySQL:     "Table 'db.X' doesn't exist"   (errno 1146, SQLSTATE 42S02)
+//
+// The earlier message-only test recognized the SQLite/Postgres phrasing
+// ("no such table" / "does not exist") but NOT MySQL's "doesn't exist"
+// (the apostrophe-contracted form), so a gates-only MySQL cluster boot
+// mis-fired the skip and surfaced ER_NO_SUCH_TABLE instead of completing.
+function _isMissingTableError(e) {
+  if (!e) return false;
+  // Structured code / SQLSTATE first — driver-stable, locale-independent.
+  // mysql2-shape: e.errno === 1146 / e.code === "ER_NO_SUCH_TABLE";
+  // the docker-exec shim + ANSI drivers surface SQLSTATE 42S02 (MySQL) /
+  // 42P01 (Postgres) on e.code / e.sqlState.
+  var code     = (e.code != null) ? String(e.code) : "";
+  var sqlState = (e.sqlState != null) ? String(e.sqlState) : "";
+  if (e.errno === 1146) return true;
+  if (code === "ER_NO_SUCH_TABLE" || code === "42S02" || code === "42P01" ||
+      sqlState === "42S02" || sqlState === "42P01") {
+    return true;
+  }
+  // Driver phrasing fallback. "doesn't exist" (MySQL apostrophe form) is
+  // covered alongside "does not exist" (Postgres) and "no such table"
+  // (SQLite). The MySQL message embeds the table name in quotes, so the
+  // bare "doesn't exist" substring is the portable anchor.
+  var msg = e.message || "";
+  return /no such table|does not exist|doesn't exist|relation .* does not exist/i.test(msg);
+}
 
 var DEFAULT_LEASE_TTL    = C.TIME.seconds(30);
 var DEFAULT_HEARTBEAT    = C.TIME.seconds(10);
@@ -324,8 +396,16 @@ async function init(opts) {
   // framework state — the operator owns rollback detection in that
   // case.
   if (configuredExternalDbBackend) {
-    await _checkChainTipRollback("audit",   "_blamejs_audit_log",   "_blamejs_audit_tip");
-    await _checkChainTipRollback("consent", "_blamejs_consent_log", "_blamejs_consent_tip");
+    // Resolve the chain + tip table names through frameworkSchema so the
+    // configurable framework-table prefix is honored (the names are
+    // `_blamejs_`-prefixed and self-mapped, so the resolve is a no-op under
+    // the default prefix).
+    await _checkChainTipRollback("audit",
+      frameworkSchema().tableName("audit_log"),                                   // allow:hand-rolled-sql — logical-name reference
+      frameworkSchema().tableName("_blamejs_audit_tip"));                         // allow:hand-rolled-sql — logical-name reference
+    await _checkChainTipRollback("consent",
+      frameworkSchema().tableName("consent_log"),                                 // allow:hand-rolled-sql — logical-name reference
+      frameworkSchema().tableName("_blamejs_consent_tip"));                       // allow:hand-rolled-sql — logical-name reference
     // Vault-key consistency: every node in a cluster must hold the
     // SAME vault key. A node booting with a different key would seal
     // new writes under a key the rest of the cluster can't unseal,
@@ -373,26 +453,16 @@ async function init(opts) {
 //     hash → FATAL via process.exit(1). Same posture as the
 //     single-node audit.tip sidecar rollback check.
 async function _checkChainTipRollback(chainName, logTable, tipTable) {
-  // Both tables are framework-internal constants from the call sites
-  // (`_blamejs_audit_log`, `_blamejs_consent_log`, etc.). Validate +
-  // quote per the framework's identifier-quoting convention so a
-  // future rename can't silently break the query.
-  safeSql.validateIdentifier(logTable, { allowReserved: true });
-  safeSql.validateIdentifier(tipTable, { allowReserved: true });
-  var qLogTable = safeSql.quoteIdentifier(logTable);
-  var qTipTable = safeSql.quoteIdentifier(tipTable);
-
+  // Both tables are framework-internal constants resolved at the call
+  // sites through frameworkSchema. b.sql quotes every identifier by
+  // construction; the dialect-final SQL is placeholderized to `$N` for
+  // Postgres (passthrough for SQLite).
   var tipRows;
   try {
-    tipRows = await externalDb().query(
-      "SELECT atMonotonicCounter, rowHash FROM " + qTipTable +
-      " WHERE scope = " + (configuredDialect === "postgres" ? "$1" : "?"),
-      [chainName],
-      { backend: configuredExternalDbBackend }
-    );
+    tipRows = await _runClusterQuery(sql().select(tipTable, { dialect: _bDialect() })
+      .columns(["atMonotonicCounter", "rowHash"]).where("scope", chainName));
   } catch (e) {
-    var msg = (e && e.message) || "";
-    if (/no such table|does not exist|relation .* does not exist/i.test(msg)) {
+    if (_isMissingTableError(e)) {
       log(chainName + "-tip table not present — skipping rollback check (cluster gates-only mode)");
       return;
     }
@@ -406,11 +476,8 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   var tipCounter = Number(tip.atMonotonicCounter);
   var tipHash = tip.rowHash;
 
-  var currentRows = await externalDb().query(
-    "SELECT MAX(monotonicCounter) AS m FROM " + qLogTable,
-    [],
-    { backend: configuredExternalDbBackend }
-  );
+  var currentRows = await _runClusterQuery(sql().select(logTable, { dialect: _bDialect() })
+    .max("monotonicCounter", "m"));
   var currentMax = (currentRows.rows && currentRows.rows[0] && currentRows.rows[0].m)
     ? Number(currentRows.rows[0].m)
     : 0;
@@ -426,12 +493,8 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   }
 
   if (tipHash) {
-    var hashRows = await externalDb().query(
-      "SELECT rowHash FROM " + qLogTable + " WHERE monotonicCounter = " +
-      (configuredDialect === "postgres" ? "$1" : "?"),
-      [tipCounter],
-      { backend: configuredExternalDbBackend }
-    );
+    var hashRows = await _runClusterQuery(sql().select(logTable, { dialect: _bDialect() })
+      .columns(["rowHash"]).where("monotonicCounter", tipCounter));
     if (hashRows.rows && hashRows.rows.length > 0) {
       var rowAtTip = hashRows.rows[0].rowHash;
       if (rowAtTip !== tipHash) {
@@ -492,12 +555,13 @@ function _vaultKeyFingerprint() {
 // non-constant, so the column is nullable and treated as epoch 0 when
 // absent on legacy rows.
 async function _ensureRotationEpochColumn() {
+  var stateTable = frameworkSchema().tableName("_blamejs_cluster_state");           // allow:hand-rolled-sql — logical-name reference
   try {
-    await externalDb().query(
-      "ALTER TABLE _blamejs_cluster_state ADD COLUMN rotationEpoch BIGINT",
-      [],
-      { backend: configuredExternalDbBackend }
-    );
+    var alter = sql().alterTable(stateTable,
+      { addColumn: { name: "rotationEpoch", type: "BIGINT" } },
+      { dialect: _bDialect() }).sql;
+    await externalDb().query(clusterStorage().placeholderize(alter, configuredDialect), [],
+      { backend: configuredExternalDbBackend });
   } catch (_e) { /* column already exists (or table absent — caught upstream) */ }
 }
 
@@ -533,29 +597,23 @@ async function _checkVaultKeyConsistency() {
     return;
   }
   var nowMs = Date.now();
-  var ph = configuredDialect === "postgres";
+  var stateTable = frameworkSchema().tableName("_blamejs_cluster_state");           // allow:hand-rolled-sql — logical-name reference
 
   // First boot: try to record THIS node's fingerprint. ON CONFLICT DO
   // NOTHING means the FIRST node to boot wins; subsequent nodes
   // observe whatever's already there. Every node then SELECTs and
   // compares — any mismatch (including ours after a losing race)
-  // surfaces the drift.
+  // surfaces the drift. The scope value binds like any other param; b.sql
+  // folds DO NOTHING to the MySQL `scope = scope` no-op automatically.
   try {
-    await externalDb().query(
-      "INSERT INTO _blamejs_cluster_state " +
-      "  (scope, vaultKeyFp, recordedAt, recordedByNode) " +
-      "VALUES ('state', " +
-      (ph ? "$1, $2, $3" : "?, ?, ?") + ") " +
-      "ON CONFLICT (scope) DO NOTHING",
-      [localFp, nowMs, nodeId],
-      { backend: configuredExternalDbBackend }
-    );
+    await _runClusterQuery(sql().upsert(stateTable, { dialect: _bDialect() })
+      .values({ scope: "state", vaultKeyFp: localFp, recordedAt: nowMs, recordedByNode: nodeId })
+      .onConflict(["scope"]).doNothing());
   } catch (e) {
     // Table missing → the cluster-provider-db ensureSchema didn't run
     // (custom provider that doesn't create _blamejs_cluster_state).
     // Skip silently — same defensive posture as the audit-tip check.
-    var msg = (e && e.message) || "";
-    if (/no such table|does not exist|relation .* does not exist/i.test(msg)) {
+    if (_isMissingTableError(e)) {
       log("cluster-state table not present — skipping vault-key consistency check (custom provider)");
       return;
     }
@@ -569,12 +627,9 @@ async function _checkVaultKeyConsistency() {
 
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
-  var rows = await externalDb().query(
-    "SELECT vaultKeyFp, recordedByNode, recordedAt, rotationEpoch FROM _blamejs_cluster_state " +
-    "WHERE scope = 'state'",
-    [],
-    { backend: configuredExternalDbBackend }
-  );
+  var rows = await _runClusterQuery(sql().select(stateTable, { dialect: _bDialect() })
+    .columns(["vaultKeyFp", "recordedByNode", "recordedAt", "rotationEpoch"])
+    .where("scope", "state"));
   if (!rows.rows || rows.rows.length === 0) {
     // Should never happen — we just INSERTed. Surface as fatal so the
     // condition isn't silently ignored.
@@ -628,27 +683,20 @@ async function _checkVaultKeyConsistency() {
     var priorEpoch = (canonical.rotationEpoch != null) ? Number(canonical.rotationEpoch) : 0;
     if (!isFinite(priorEpoch) || priorEpoch < 0) priorEpoch = 0;
     var nextEpoch = priorEpoch + 1;
-    await externalDb().query(
-      "UPDATE _blamejs_cluster_state SET " +
-      "  vaultKeyFp = " + (ph ? "$1" : "?") + ", " +
-      "  recordedAt = " + (ph ? "$2" : "?") + ", " +
-      "  recordedByNode = " + (ph ? "$3" : "?") + ", " +
-      "  rotationEpoch = " + (ph ? "$4" : "?") + " " +
-      "WHERE scope = 'state' AND vaultKeyFp = " + (ph ? "$5" : "?"),
-      [localFp, nowMs, nodeId, nextEpoch, canonical.vaultKeyFp],
-      { backend: configuredExternalDbBackend }
-    );
+    await _runClusterQuery(sql().update(stateTable, { dialect: _bDialect() })
+      .set({
+        vaultKeyFp: localFp, recordedAt: nowMs,
+        recordedByNode: nodeId, rotationEpoch: nextEpoch,
+      })
+      .where("scope", "state").where("vaultKeyFp", canonical.vaultKeyFp));
     // Re-read so the post-adopt state reflects whoever actually won the
     // advance (this node, or a peer that adopted the SAME rotated key a
     // beat earlier). A surviving mismatch here means the row now carries a
     // fingerprint that is neither the old one nor ours — a real drift that
     // the rotation declaration does not cover, so fail closed.
-    var after = await externalDb().query(
-      "SELECT vaultKeyFp, recordedByNode, rotationEpoch FROM _blamejs_cluster_state " +
-      "WHERE scope = 'state'",
-      [],
-      { backend: configuredExternalDbBackend }
-    );
+    var after = await _runClusterQuery(sql().select(stateTable, { dialect: _bDialect() })
+      .columns(["vaultKeyFp", "recordedByNode", "rotationEpoch"])
+      .where("scope", "state"));
     var post = (after.rows && after.rows[0]) || canonical;
     if (post.vaultKeyFp !== localFp) {
       throw _err("VAULT_KEY_DRIFT",

package/lib/compliance.js

@@ -1065,6 +1065,28 @@ var POSTURE_DEFAULTS = Object.freeze({
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  true,
   }),
+  // UK GDPR (DPA 2018 + retained EU GDPR) — Art. 17 right to erasure
+  // applies identically to GDPR, including residual B-tree pages.
+  "uk-gdpr": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
+  // Japan APPI — deletion/cessation right with residue-cleanup floor.
+  "appi-jp": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
+  // Singapore PDPA — right to erasure with effectiveness floor.
+  "pdpa-sg": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
   // v0.8.70 — 2026 effective deadlines
   "modpa": Object.freeze({
     // Maryland Online Data Privacy Act (effective 2026-10-01) —

package/lib/consent.js

@@ -46,6 +46,8 @@ var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var chainWriter = require("./chain-writer");
 var safeAsync = require("./safe-async");
+var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var lazyRequire = require("./lazy-require");
 var C = require("./constants");
 var { ClusterError } = require("./framework-error");
@@ -304,10 +306,18 @@ function isGranted(opts) {
   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);
+  // Local db() handle: emit the LOCAL table name (consent_log) quoted so
+  // the camelCase subjectIdHash / monotonicCounter columns resolve, and
+  // run the built { sql, params } against the prepared statement.
+  var isGrantedBuilt = sql.select("consent_log", { dialect: "sqlite", quoteName: true })
+    .columns(["action"])
+    .where("subjectIdHash", hash)
+    .where("purpose", opts.purpose)
+    .orderBy("monotonicCounter", "desc")
+    .limit(1)
+    .toSql();
+  var isGrantedStmt = db().prepare(isGrantedBuilt.sql);
+  var row = isGrantedStmt.get.apply(isGrantedStmt, isGrantedBuilt.params);
   if (!row) return false;
   return row.action === "granted";
 }
@@ -409,30 +419,69 @@ async function _appendConsentRow(fields) {
 }
 
 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.
+  // Single atomic INSERT … ON CONFLICT(scope) DO UPDATE … WHERE … RETURNING
+  // via b.sql. Same canonical fencing-token guard as _blamejs_audit_tip: the
+  // fenced WHERE 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. On
+  // rejection RETURNING produces 0 rows.
+  //
+  // The consent-tip is external-only; its LOGICAL name IS the
+  // `_blamejs_`-prefixed name (self-mapped in LOCAL_TO_EXTERNAL), passed
+  // bare to b.sql so clusterStorage rewrites it (and the same bare name
+  // inside the guarded fence) to the configured prefix and placeholderizes.
+  //
+  // Dialect is the ACTIVE backend (clusterStorage.dialect()) so the fence's
+  // identifier quoting + conflict-expression idiom match the server the SQL
+  // dispatches to. The fence text itself is dialect-specific because the
+  // builder folds it verbatim: on Postgres / SQLite the upsert keeps a
+  // `WHERE "<table>"."fencingToken" <= EXCLUDED."fencingToken"` guard (and a
+  // RETURNING row that signals fenced-out via 0 rows); on MySQL there is no
+  // WHERE and no EXCLUDED, so the builder folds the same guard into per-column
+  // `IF(<table>.`fencingToken` <= VALUES(`fencingToken`), VALUES(col), col)`
+  // — the fence must therefore reference `VALUES(...)` with backticks. The
+  // bare table qualifier (no quoteName) lets clusterStorage rewrite the
+  // logical `_blamejs_consent_tip` to the configured prefix inside the fence
+  // exactly as it does for the table name.
+  var d = clusterStorage.dialect();
+  var qFence = safeSql.quoteIdentifier("fencingToken", d);
+  var tipFence = d === "mysql"
+    ? "_blamejs_consent_tip." + qFence + " <= VALUES(" + qFence + ")"     // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+    : "_blamejs_consent_tip." + qFence + " <= EXCLUDED." + qFence;        // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+  var tipBuilt = sql.upsert("_blamejs_consent_tip", { dialect: d })   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+    .columns(["scope", "atMonotonicCounter", "rowHash", "signedAt", "fencingToken"])
+    .values({
+      scope:              "consent",
+      atMonotonicCounter: counter,
+      rowHash:            rowHash,
+      signedAt:           signedAt,
+      fencingToken:       fencingToken,
+    })
+    .onConflict(["scope"])
+    .doUpdateFromExcluded(["atMonotonicCounter", "rowHash", "signedAt", "fencingToken"])
+    // guardColumn pins fencingToken LAST in the MySQL SET list so every
+    // other column's IF() evaluates the guard against the PRE-UPDATE token
+    // (MySQL evaluates SET left-to-right; a later assignment would otherwise
+    // see fencingToken already overwritten). Ignored on Postgres / SQLite,
+    // which apply the WHERE atomically.
+    .conflictWhere(tipFence, [], { guardColumn: "fencingToken" })
+    .returning(["fencingToken"])
+    .toSql();
   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]
-    ),
+    clusterStorage.execute(tipBuilt.sql, tipBuilt.params),
     FRAMEWORK_SQL_TIMEOUT_MS,
     { name: "consent.upsertConsentTip" }
   );
-  if (!result.rows || result.rows.length === 0) {
+  // MySQL upsert has no RETURNING — the builder emits a readback SELECT
+  // alongside, but a fenced-out lower-token write still SUCCEEDS as a no-op
+  // INSERT…ON DUPLICATE KEY UPDATE (the IF() keeps the stored values), so
+  // there is no 0-rows signal to detect. The DB-level fence still PRESERVES
+  // the tip (the security property); the FENCED_OUT throw is the
+  // Postgres/SQLite RETURNING-0-rows path only. On MySQL clusterStorage is
+  // not a supported framework backend, so the consent-tip never dispatches
+  // there in production — the threaded dialect makes the SAME builders emit
+  // valid MySQL for operators driving these shapes against MySQL directly.
+  if (d !== "mysql" && (!result.rows || result.rows.length === 0)) {
     throw new ClusterError(
       "FENCED_OUT",
       "consent-tip update rejected: incoming fencingToken=" + fencingToken +

package/lib/constants.js

@@ -156,22 +156,27 @@ var PQC_GROUPS = Object.freeze({
   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.
+// Highest-first preference list for OUTBOUND TLS (clients only — the
+// server's accept-groups are configured separately). Node TLS picks the
+// first mutually-supported group during the handshake, so a peer that
+// advertises SecP384r1MLKEM1024 (P-384 + ML-KEM-1024) gets it, then the
+// X25519 / SecP256r1 ML-KEM hybrids. X25519 (classical) is the LAST-RESORT
+// fallback for peers that support no ML-KEM hybrid yet — still most of the
+// public TLS surface in 2026 (webhooks, OAuth/OIDC, ACME, third-party APIs).
 //
-// 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.
+// The framework always PREFERS a hybrid on every handshake; classical
+// X25519 is only negotiated when the peer offers none of the hybrids. When
+// a connection lands on classical instead, the outbound path emits a
+// `tls.classical_downgrade` audit event (lib/pqc-agent.js) so operators can
+// see which peers forced a non-PQC negotiation and track their
+// dependencies' PQC readiness. Weaker non-hybrid classical groups
+// (P-256 / P-384) are deliberately NOT offered — the fallback floor is the
+// X25519 group.
 var TLS_GROUP_PREFERENCE = Object.freeze([
   "SecP384r1MLKEM1024",
   "X25519MLKEM768",
   "SecP256r1MLKEM768",
+  "X25519",
 ]);
 
 var TLS_GROUP_CURVE_STR = TLS_GROUP_PREFERENCE.join(":");