@blamejs/core 0.6.13 → 0.6.21

package/lib/network.js

@@ -0,0 +1,233 @@
+"use strict";
+
+var ntpCheck = require("./ntp-check");
+var nts      = require("./network-nts");
+var dns      = require("./network-dns");
+var proxy    = require("./network-proxy");
+var trust    = require("./network-tls");
+var heartbeat = require("./network-heartbeat");
+
+var validateOpts = require("./validate-opts");
+var lazyRequire = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+
+var NetworkError = defineClass("NetworkError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("./observability"); });
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var SOCKET_DEFAULTS = {
+  noDelay:           true,
+  keepAlive:         true,
+  keepAliveInitialDelayMs: 0,
+};
+
+function _setSocketNoDelay(value) {
+  if (typeof value !== "boolean") {
+    throw new NetworkError("socket/bad-no-delay", "socket.setDefaultNoDelay: expected boolean, got " + typeof value);
+  }
+  SOCKET_DEFAULTS.noDelay = value;
+}
+
+function _setSocketKeepAlive(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["enable", "initialDelayMs"], "socket.setDefaultKeepAlive");
+  if (opts.enable !== undefined) {
+    if (typeof opts.enable !== "boolean") {
+      throw new NetworkError("socket/bad-keepalive", "socket.setDefaultKeepAlive: enable must be boolean");
+    }
+    SOCKET_DEFAULTS.keepAlive = opts.enable;
+  }
+  if (opts.initialDelayMs !== undefined) {
+    if (typeof opts.initialDelayMs !== "number" || !isFinite(opts.initialDelayMs) || opts.initialDelayMs < 0) {
+      throw new NetworkError("socket/bad-keepalive-delay", "socket.setDefaultKeepAlive: initialDelayMs must be non-negative finite number");
+    }
+    SOCKET_DEFAULTS.keepAliveInitialDelayMs = opts.initialDelayMs;
+  }
+}
+
+// SO_LINGER is intentionally NOT exposed: Node's net.Socket has no
+// public setLinger() method (the option is tracked at
+// nodejs/node#27293 / rejected for the public surface). Reaching into
+// socket._handle to call setLinger is an unstable internal API. The
+// closest operator-exposed semantic is socket.destroy() (RST = "abort
+// on close") vs socket.end() (graceful FIN). Operators needing true
+// SO_LINGER should use a native binding outside the framework. This
+// stub stays in the export with throw-on-call so a future Node release
+// that exposes setLinger can be wired without an API addition.
+function _setSocketLinger(_opts) {
+  throw new NetworkError("socket/linger-not-supported",
+    "socket.setDefaultLinger: SO_LINGER is not exposed by Node's public net.Socket API " +
+    "(see nodejs/node#27293). Use socket.destroy() (abort) vs socket.end() (graceful) " +
+    "to control close semantics, or a native binding if true SO_LINGER is required.");
+}
+
+function _socketDefaults() {
+  return {
+    noDelay:                 SOCKET_DEFAULTS.noDelay,
+    keepAlive:               SOCKET_DEFAULTS.keepAlive,
+    keepAliveInitialDelayMs: SOCKET_DEFAULTS.keepAliveInitialDelayMs,
+  };
+}
+
+function applyToSocket(socket) {
+  if (!socket) return socket;
+  try {
+    if (typeof socket.setNoDelay === "function") socket.setNoDelay(SOCKET_DEFAULTS.noDelay);
+    if (typeof socket.setKeepAlive === "function") {
+      socket.setKeepAlive(SOCKET_DEFAULTS.keepAlive, SOCKET_DEFAULTS.keepAliveInitialDelayMs || 0);
+    }
+  } catch (_e) {}
+  return socket;
+}
+
+var ntpFacade = {
+  querySingle:    ntpCheck.querySingle,
+  checkDrift:     ntpCheck.checkDrift,
+  bootCheck:      ntpCheck.bootCheck,
+  setThresholds:  ntpCheck.setThresholds,
+  getThresholds:  ntpCheck.getThresholds,
+  setServers:     function (list) {
+    if (!Array.isArray(list) || list.length === 0) {
+      throw new NetworkError("ntp/bad-servers", "ntp.setServers: expected non-empty array");
+    }
+    ntpFacade._defaultServers = list.slice();
+    _emitObs("network.ntp.servers.set", { count: list.length });
+  },
+  getServers:     function () {
+    return (ntpFacade._defaultServers || ntpCheck.DEFAULT_SERVERS).slice();
+  },
+  _defaultServers: null,
+  nts:            nts,
+};
+
+function bootFromEnv(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["env", "audit"], "network.bootFromEnv");
+  var env = opts.env || process.env;
+  var applied = { ntp: {}, dns: {}, proxy: false, tls: {}, heartbeat: 0, socket: {} };
+
+  if (env.BLAMEJS_NTP_SERVERS) {
+    var list = String(env.BLAMEJS_NTP_SERVERS).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    if (list.length > 0) { ntpFacade.setServers(list); applied.ntp.servers = list.length; }
+  }
+  var ntpTimeout = env.BLAMEJS_NTP_TIMEOUT_MS;
+  if (ntpTimeout) {
+    var t = parseInt(ntpTimeout, 10);
+    if (isFinite(t) && t > 0) { ntpFacade._defaultTimeoutMs = t; applied.ntp.timeoutMs = t; }
+  }
+  var ntpWarn = env.BLAMEJS_NTP_DRIFT_WARN_MS;
+  var ntpFatal = env.BLAMEJS_NTP_DRIFT_FATAL_MS;
+  if (ntpWarn || ntpFatal) {
+    var thr = {};
+    if (ntpWarn)  { thr.warnMs  = parseInt(ntpWarn, 10);  applied.ntp.warnMs  = thr.warnMs; }
+    if (ntpFatal) { thr.fatalMs = parseInt(ntpFatal, 10); applied.ntp.fatalMs = thr.fatalMs; }
+    ntpCheck.setThresholds(thr);
+  }
+
+  var dnsServers = env.BLAMEJS_DNS_SERVERS;
+  if (dnsServers) {
+    var dl = String(dnsServers).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    if (dl.length > 0) { dns.setServers(dl); applied.dns.servers = dl.length; }
+  }
+  if (env.BLAMEJS_DNS_RESULT_ORDER)  { dns.setResultOrder(env.BLAMEJS_DNS_RESULT_ORDER); applied.dns.resultOrder = env.BLAMEJS_DNS_RESULT_ORDER; }
+  if (env.BLAMEJS_DNS_FAMILY)        { dns.setFamily(parseInt(env.BLAMEJS_DNS_FAMILY, 10)); applied.dns.family = parseInt(env.BLAMEJS_DNS_FAMILY, 10); }
+  if (env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS) { dns.setLookupTimeoutMs(parseInt(env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS, 10)); applied.dns.lookupTimeoutMs = parseInt(env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS, 10); }
+  if (env.BLAMEJS_DNS_CACHE_TTL_MS)      { dns.setCacheTtlMs(parseInt(env.BLAMEJS_DNS_CACHE_TTL_MS, 10)); applied.dns.cacheTtlMs = parseInt(env.BLAMEJS_DNS_CACHE_TTL_MS, 10); }
+  if (env.BLAMEJS_DOH_URL)               { dns.useDnsOverHttps({ url: env.BLAMEJS_DOH_URL }); applied.dns.doh = env.BLAMEJS_DOH_URL; }
+  else if (env.BLAMEJS_DOH_PROVIDER)     { dns.useDnsOverHttps({ provider: env.BLAMEJS_DOH_PROVIDER }); applied.dns.dohProvider = env.BLAMEJS_DOH_PROVIDER; }
+  if (env.BLAMEJS_DOT_HOST)              { dns.useDnsOverTls({ host: env.BLAMEJS_DOT_HOST, port: env.BLAMEJS_DOT_PORT ? parseInt(env.BLAMEJS_DOT_PORT, 10) : 853 }); applied.dns.dot = env.BLAMEJS_DOT_HOST; }
+
+  if (env.HTTP_PROXY || env.http_proxy || env.HTTPS_PROXY || env.https_proxy ||
+      env.NO_PROXY  || env.no_proxy  || env.ALL_PROXY    || env.all_proxy) {
+    applied.proxy = proxy.fromEnv(env);
+  }
+
+  if (env.BLAMEJS_EXTRA_CA_CERTS) {
+    trust.addCa(env.BLAMEJS_EXTRA_CA_CERTS, { label: "BLAMEJS_EXTRA_CA_CERTS" });
+    applied.tls.fileLoaded = env.BLAMEJS_EXTRA_CA_CERTS;
+  }
+  if (env.BLAMEJS_EXTRA_CA_CERTS_DIR) {
+    trust.addCaBundle(env.BLAMEJS_EXTRA_CA_CERTS_DIR, { label: "BLAMEJS_EXTRA_CA_CERTS_DIR" });
+    applied.tls.dirLoaded = env.BLAMEJS_EXTRA_CA_CERTS_DIR;
+  }
+  if (env.BLAMEJS_USE_SYSTEM_TRUST === "1" || env.BLAMEJS_USE_SYSTEM_TRUST === "true") {
+    trust.useSystemTrust(true);
+    applied.tls.systemTrust = true;
+  }
+
+  if (env.BLAMEJS_SOCKET_NO_DELAY)             _setSocketNoDelay(env.BLAMEJS_SOCKET_NO_DELAY === "1" || env.BLAMEJS_SOCKET_NO_DELAY === "true");
+  if (env.BLAMEJS_SOCKET_KEEPALIVE)            _setSocketKeepAlive({ enable: env.BLAMEJS_SOCKET_KEEPALIVE === "1" || env.BLAMEJS_SOCKET_KEEPALIVE === "true" });
+  if (env.BLAMEJS_SOCKET_KEEPALIVE_DELAY_MS)   _setSocketKeepAlive({ initialDelayMs: parseInt(env.BLAMEJS_SOCKET_KEEPALIVE_DELAY_MS, 10) });
+  applied.socket = _socketDefaults();
+
+  var auditOn = opts.audit !== false;
+  if (auditOn) {
+    var sink;
+    try { sink = audit(); } catch (_e) { sink = null; }
+    if (sink && typeof sink.safeEmit === "function") {
+      try {
+        sink.safeEmit({
+          action:   "network.boot.from_env",
+          outcome:  "success",
+          metadata: applied,
+        });
+      } catch (_e) {}
+    }
+  }
+  _emitObs("network.boot.from_env", { source: "env" });
+  return applied;
+}
+
+function snapshot() {
+  return {
+    ntp: {
+      servers:     ntpFacade.getServers(),
+      thresholds:  ntpCheck.getThresholds(),
+    },
+    dns: dns._stateForTest(),
+    proxy: proxy.snapshot(),
+    tls:  {
+      systemTrust: trust.isSystemTrustEnabled(),
+      caCount:     trust.getTrustStore().length,
+    },
+    heartbeat: heartbeat.statuses(),
+    socket: _socketDefaults(),
+  };
+}
+
+function _emitObs(name, fields) {
+  try { observability().emit(name, fields || {}); } catch (_e) {}
+}
+
+function _resetForTest() {
+  ntpFacade._defaultServers = null;
+  ntpFacade._defaultTimeoutMs = null;
+  if (typeof ntpCheck._resetThresholdsForTest === "function") ntpCheck._resetThresholdsForTest();
+  dns._resetForTest();
+  proxy._resetForTest();
+  trust._resetForTest();
+  heartbeat._resetForTest();
+  SOCKET_DEFAULTS.noDelay = true;
+  SOCKET_DEFAULTS.keepAlive = true;
+  SOCKET_DEFAULTS.keepAliveInitialDelayMs = 0;
+}
+
+module.exports = {
+  ntp:        ntpFacade,
+  dns:        dns,
+  proxy:      proxy,
+  tls:        trust,
+  heartbeat:  heartbeat,
+  socket: {
+    setDefaultNoDelay:   _setSocketNoDelay,
+    setDefaultKeepAlive: _setSocketKeepAlive,
+    setDefaultLinger:    _setSocketLinger,
+    defaults:            _socketDefaults,
+    applyToSocket:       applyToSocket,
+  },
+  bootFromEnv:    bootFromEnv,
+  snapshot:       snapshot,
+  NetworkError:   NetworkError,
+  _resetForTest:  _resetForTest,
+};

package/lib/ntp-check.js

@@ -36,6 +36,43 @@ var DEFAULT_SERVERS = ["pool.ntp.org", "time.cloudflare.com"];
 var DEFAULT_PORT    = 123;
 var DEFAULT_TIMEOUT_MS = 3000;
 
+var DEFAULT_DRIFT_WARN_MS  = C.TIME.minutes(5);
+var DEFAULT_DRIFT_FATAL_MS = C.TIME.hours(1);
+
+var thresholds = {
+  warnMs:  DEFAULT_DRIFT_WARN_MS,
+  fatalMs: DEFAULT_DRIFT_FATAL_MS,
+};
+
+function setThresholds(opts) {
+  opts = opts || {};
+  if (opts.warnMs !== undefined) {
+    if (typeof opts.warnMs !== "number" || !isFinite(opts.warnMs) || opts.warnMs < 0) {
+      throw new TypeError("ntpCheck.setThresholds: warnMs must be non-negative finite number, got " + JSON.stringify(opts.warnMs));
+    }
+    thresholds.warnMs = opts.warnMs;
+  }
+  if (opts.fatalMs !== undefined) {
+    if (typeof opts.fatalMs !== "number" || !isFinite(opts.fatalMs) || opts.fatalMs < 0) {
+      throw new TypeError("ntpCheck.setThresholds: fatalMs must be non-negative finite number, got " + JSON.stringify(opts.fatalMs));
+    }
+    thresholds.fatalMs = opts.fatalMs;
+  }
+  if (thresholds.warnMs > thresholds.fatalMs && thresholds.fatalMs > 0) {
+    throw new RangeError("ntpCheck.setThresholds: warnMs (" + thresholds.warnMs +
+      ") must be <= fatalMs (" + thresholds.fatalMs + ")");
+  }
+}
+
+function getThresholds() {
+  return { warnMs: thresholds.warnMs, fatalMs: thresholds.fatalMs };
+}
+
+function _resetThresholdsForTest() {
+  thresholds.warnMs  = DEFAULT_DRIFT_WARN_MS;
+  thresholds.fatalMs = DEFAULT_DRIFT_FATAL_MS;
+}
+
 /**
  * Query an NTP server once. Resolves with { driftMs, serverTimeMs } or
  * rejects with { code, message } where code is one of:
@@ -142,22 +179,26 @@ async function bootCheck(opts) {
   }
   var absMs = Math.abs(result.driftMs);
   var driftStr = (result.driftMs >= 0 ? "+" : "") + result.driftMs + "ms";
-  if (absMs >= C.TIME.hours(1)) {
+  var fatalMs = (opts && typeof opts.driftFatalMs === "number") ? opts.driftFatalMs : thresholds.fatalMs;
+  var warnMs  = (opts && typeof opts.driftWarnMs  === "number") ? opts.driftWarnMs  : thresholds.warnMs;
+  if (fatalMs > 0 && absMs >= fatalMs) {
     return {
       ok:       false,
       severity: "fatal",
       driftMs:  result.driftMs,
       server:   result.server,
-      message:  "clock drift " + driftStr + " from " + result.server + " (>= 1 hour) — refuse to boot",
+      message:  "clock drift " + driftStr + " from " + result.server +
+                " (>= " + fatalMs + "ms) — refuse to boot",
     };
   }
-  if (absMs >= C.TIME.minutes(5)) {
+  if (warnMs > 0 && absMs >= warnMs) {
     return {
       ok:       true,
       severity: "warning",
       driftMs:  result.driftMs,
       server:   result.server,
-      message:  "clock drift " + driftStr + " from " + result.server + " (>= 5 minutes) — investigate",
+      message:  "clock drift " + driftStr + " from " + result.server +
+                " (>= " + warnMs + "ms) — investigate",
     };
   }
   return {
@@ -173,6 +214,11 @@ module.exports = {
   querySingle:               querySingle,
   checkDrift:                checkDrift,
   bootCheck:                 bootCheck,
+  setThresholds:             setThresholds,
+  getThresholds:             getThresholds,
   DEFAULT_SERVERS:           DEFAULT_SERVERS,
+  DEFAULT_DRIFT_WARN_MS:     DEFAULT_DRIFT_WARN_MS,
+  DEFAULT_DRIFT_FATAL_MS:    DEFAULT_DRIFT_FATAL_MS,
   NTP_TO_UNIX_OFFSET_SECONDS: NTP_TO_UNIX_OFFSET_SECONDS,
+  _resetThresholdsForTest:   _resetThresholdsForTest,
 };

package/lib/object-store/azure-blob.js

@@ -400,49 +400,23 @@ function create(config) {
   function presignedUploadUrl(opts)   { return _presign("PUT", "cw", opts); }
   function presignedDownloadUrl(opts) { return _presign("GET", "r",  opts); }
 
-  // Azure SAS doesn't support an equivalent of S3 / GCS POST policy
-  // with a content-length-range constraint. The SAS spec carries
-  // permissions / start / expiry / IP / protocol / resource-content-
-  // headers but no body-size cap — Azure validates the upload at the
-  // service level only via the operator's optional Block Blob size
-  // limit applied at storage-account or container scope, not via the
-  // SAS token itself.
+  // Azure SAS has no equivalent of S3 / GCS POST policy with a
+  // content-length-range constraint — the SAS spec carries permissions
+  // / start / expiry / IP / protocol / resource-content-headers but
+  // no body-size cap. Returning a PUT URL under the POST-policy name
+  // would be a silent shape mismatch (operators wiring an HTML form
+  // expecting multipart fields get a PUT URL with no fields), so the
+  // azure-blob backend refuses cleanly.
   //
-  // Rather than throw NOT_SUPPORTED, this returns the same SAS PUT
-  // shape as presignedUploadUrl with an `enforcement: 'client-only'`
-  // marker so operators making cross-vendor decisions know the
-  // body-size guard is advisory on Azure and must be enforced on the
-  // client side or via a server-side post-upload check.
-  //
-  // For strict server-side body-size enforcement on Azure, the
-  // canonical pattern is: SAS-authorize the upload, then have the
-  // operator's app issue a HEAD on the resulting blob and delete +
-  // 4xx the requester if Content-Length > opts.maxBytes.
-  function presignedUploadPolicy(opts) {
-    opts = opts || {};
-    if (typeof opts.maxBytes !== "number" || !Number.isFinite(opts.maxBytes) ||
-        opts.maxBytes <= 0) {
-      throw _err("INVALID_MAX_BYTES",
-        "presignedUploadPolicy: maxBytes (positive number of bytes) is required " +
-        "(advisory on Azure — see docstring for server-side enforcement)", true);
-    }
-    var underlying = _presign("PUT", "cw", opts);
-    return {
-      url:           underlying.url,
-      method:        "PUT",
-      // SAS uploads are PUT, not multipart POST — there are no form
-      // fields. Operators uploading attach the body directly to the
-      // returned URL with the headers in `headers`.
-      fields:        null,
-      headers:       underlying.headers,
-      expiresAt:     underlying.expiresAt,
-      maxBytes:      opts.maxBytes,
-      enforcement:   "client-only",
-      enforcementNote:
-        "Azure SAS does not natively cap upload size. Operators needing " +
-        "strict size enforcement must HEAD the blob post-upload and reject " +
-        "if Content-Length exceeds maxBytes.",
-    };
+  // For strict server-side body-size enforcement on Azure: use
+  // presignedUploadUrl + a server-side post-upload HEAD that deletes
+  // and 4xxs the requester if Content-Length > limit.
+  function presignedUploadPolicy(_opts) {
+    throw _err("PRESIGN_NOT_SUPPORTED",
+      "azure-blob backend does not support presigned upload policies — " +
+      "Azure SAS has no body-size cap. Use presignedUploadUrl + a server-side " +
+      "HEAD-and-delete check, or switch to an S3 / GCS-compatible backend.",
+      true);
   }
 
   return {

package/lib/pagination.js

@@ -75,10 +75,17 @@
  * module's offset() returns a `total` (from COUNT(*)) and computes
  * `totalPages` so legacy clients can render numbered nav.
  *
+ * Multi-column ordering:
+ *   - orderBy accepts a string (single column), an array of strings
+ *     (multiple columns, all using opts.direction), or an array of
+ *     { column, direction } objects (mixed directions per column).
+ *     The keyset WHERE expands to the standard OR cascade
+ *       (col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ...)
+ *     so successive pages can't repeat or skip rows when ties on the
+ *     leading columns are broken by trailing ones. _id is appended as
+ *     a tiebreaker if not already in the orderBy chain.
+ *
  * Out of scope (with structural reasons documented):
- *   - Multi-column composite orderBy (orderBy: ["a", "b"]). Use raw
- *     SQL + encodeCursor / decodeCursor. The Query builder doesn't
- *     model multi-column ORDER BY today.
  *   - Cursor TTL / expiry. Operators who want time-limited cursors
  *     embed a timestamp in their own state and check at decode-time
  *     before passing to .cursor(). The framework's HMAC tag carries
@@ -202,6 +209,83 @@ function _resolveLimit(opts) {
 
 // ---- Cursor pagination ----
 
+// Normalize opts.orderBy into an array of { column, direction } entries.
+// Accepts:
+//   undefined / null            → [{ column: "_id", direction: opts.direction || "asc" }]
+//   "createdAt"                 → [{ column: "createdAt", direction: opts.direction || "asc" }]
+//   ["createdAt", "_id"]        → all entries default to opts.direction || "asc"
+//   [{column:"a",direction:"desc"}, {column:"b"}]
+//                               → mixed; missing direction defaults to opts.direction || "asc"
+// Always appends an _id tiebreaker if not present, so cursor uniqueness
+// is guaranteed regardless of the operator's spec.
+function _normalizeOrderBy(opts) {
+  var defaultDir = (opts && opts.direction === "desc") ? "desc" : "asc";
+  var raw = opts && opts.orderBy;
+  var entries;
+  if (raw == null) {
+    entries = [{ column: "_id", direction: defaultDir }];
+  } else if (typeof raw === "string") {
+    entries = [{ column: raw, direction: defaultDir }];
+  } else if (Array.isArray(raw)) {
+    entries = raw.map(function (e) {
+      if (typeof e === "string") return { column: e, direction: defaultDir };
+      if (!e || typeof e !== "object" || typeof e.column !== "string") {
+        throw new PaginationError("pagination/bad-orderby",
+          "orderBy[] entries must be strings or { column, direction } objects, got " +
+          JSON.stringify(e));
+      }
+      var d = (e.direction || defaultDir).toLowerCase();
+      if (d !== "asc" && d !== "desc") {
+        throw new PaginationError("pagination/bad-orderby",
+          "orderBy[].direction must be 'asc' | 'desc', got " + JSON.stringify(e.direction));
+      }
+      return { column: e.column, direction: d };
+    });
+  } else {
+    throw new PaginationError("pagination/bad-orderby",
+      "orderBy must be a string, array, or omitted; got " + typeof raw);
+  }
+  for (var i = 0; i < entries.length; i++) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(entries[i].column)) {
+      throw new PaginationError("pagination/bad-orderby",
+        "orderBy column must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
+        JSON.stringify(entries[i].column));
+    }
+  }
+  // Append _id tiebreaker if not already in the chain. Direction
+  // matches the chain's last entry by convention so the tiebreaker
+  // doesn't reverse the natural reading order.
+  var hasId = entries.some(function (e) { return e.column === "_id"; });
+  if (!hasId) {
+    entries.push({ column: "_id", direction: entries[entries.length - 1].direction });
+  }
+  return entries;
+}
+
+// Build the keyset WHERE clause for next-page navigation given the
+// cursor's column values. Each (col, dir) entry expands the OR cascade:
+//   col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ... OR (col0 = ? AND ... AND coln [opn] ?)
+// The compareOp per column flips by direction × forward (XNOR).
+function _buildKeysetWhere(orderEntries, cursorVals, forward) {
+  var clauses = [];
+  var params = [];
+  for (var i = 0; i < orderEntries.length; i++) {
+    var entry = orderEntries[i];
+    // Effective direction: asc + forward → ">", desc + forward → "<", and reversed for backward.
+    var effectiveAsc = (entry.direction === "asc") === forward;
+    var op = effectiveAsc ? ">" : "<";
+    var equalChain = [];
+    for (var j = 0; j < i; j++) {
+      equalChain.push('"' + orderEntries[j].column + '" = ?');
+      params.push(cursorVals[j]);
+    }
+    equalChain.push('"' + entry.column + '" ' + op + ' ?');
+    params.push(cursorVals[i]);
+    clauses.push("(" + equalChain.join(" AND ") + ")");
+  }
+  return { sql: clauses.join(" OR "), params: params };
+}
+
 async function cursor(query, opts) {
   if (!query || typeof query.where !== "function" || typeof query.orderBy !== "function" ||
       typeof query.limit !== "function" || typeof query.all !== "function") {
@@ -213,110 +297,86 @@ async function cursor(query, opts) {
     throw new PaginationError("pagination/no-secret",
       "cursor: opts.secret is required (Buffer or non-empty string for HMAC tagging)");
   }
-  var limit     = _resolveLimit(opts);
-  var orderBy   = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Throw at call site on bad orderBy — the value is interpolated into
-  // a raw SQL fragment for the keyset where-clause. Restrict to
-  // identifier-safe characters so a careless caller piping
-  // `req.query.orderBy` through doesn't create an SQL-injection vector.
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
-    throw new PaginationError("pagination/bad-orderby",
-      "cursor: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
-      JSON.stringify(orderBy));
-  }
-  var direction = (opts.direction === "desc") ? "desc" : "asc";
+  var limit = _resolveLimit(opts);
+  var orderEntries = _normalizeOrderBy(opts);
+  // Cursor compatibility key: array of `column:direction` pairs canonicalizes
+  // the orderBy spec so a stored cursor must match exactly to be replayed.
+  var orderKey = orderEntries.map(function (e) { return e.column + ":" + e.direction; });
 
-  // Decode incoming cursor (if any) and override direction from cursor.
-  // The cursor authoritatively encodes which way we're paging — operators
-  // shouldn't need to round-trip direction in the URL.
   var cursorState = null;
   var forward = (opts.forward !== false);
   if (opts.cursor) {
     cursorState = decodeCursor(opts.cursor, opts.secret);
-    if (cursorState.orderBy !== orderBy || cursorState.dir !== direction) {
+    var cursorKey = Array.isArray(cursorState.orderKey) ? cursorState.orderKey :
+      // Back-compat with v0.6.20 single-column cursors: synthesize the
+      // key from the legacy orderBy/dir fields.
+      [cursorState.orderBy + ":" + cursorState.dir];
+    if (JSON.stringify(cursorKey) !== JSON.stringify(orderKey)) {
       throw new PaginationError("pagination/cursor-mismatch",
-        "cursor was created with orderBy='" + cursorState.orderBy + "' direction='" +
-        cursorState.dir + "' but call uses orderBy='" + orderBy + "' direction='" +
-        direction + "' — operator must use the same opts the cursor was issued under");
+        "cursor orderKey [" + cursorKey.join(", ") + "] does not match call orderKey [" +
+        orderKey.join(", ") + "] — operator must use the same orderBy/direction spec");
     }
     if (typeof cursorState.forward === "boolean") forward = cursorState.forward;
   }
 
-  // Apply the cursor predicate. Direction interacts with forward/backward:
-  //   asc  + forward  → strictly greater than (orderByVal, _id)
-  //   asc  + backward → strictly less than (orderByVal, _id)
-  //   desc + forward  → strictly less than
-  //   desc + backward → strictly greater than
-  // We always SELECT in the direction that matches forward (so the
-  // result rows arrive in the right reading order), then if
-  // backward we reverse client-side at the end.
-  var effectiveAsc = (direction === "asc") === forward; // XNOR
-  var compareOp;
+  // Apply the keyset WHERE if a cursor is present.
   if (cursorState) {
-    compareOp = effectiveAsc ? ">" : "<";
-    // (orderByVal, _id) <op> (?, ?)
-    // Express via OR to be portable across SQLite + Postgres.
-    var oCol = orderBy;
-    query.whereRaw(
-      '"' + oCol + '" ' + compareOp + ' ? OR ("' + oCol + '" = ? AND "_id" ' + compareOp + ' ?)',
-      [cursorState.orderByVal, cursorState.orderByVal, cursorState.id]
-    );
+    var cursorVals;
+    if (Array.isArray(cursorState.vals)) {
+      cursorVals = cursorState.vals;
+    } else {
+      // v0.6.20 single-column shape — synthesize the vals array.
+      cursorVals = [cursorState.orderByVal, cursorState.id];
+      // Drop the synthetic _id append if the legacy cursor already had it
+      if (orderEntries.length === 1) cursorVals = [cursorState.orderByVal];
+    }
+    if (cursorVals.length !== orderEntries.length) {
+      throw new PaginationError("pagination/cursor-mismatch",
+        "cursor encoded " + cursorVals.length + " column value(s) but orderBy has " +
+        orderEntries.length + " — operator changed the orderBy spec mid-flight");
+    }
+    var where = _buildKeysetWhere(orderEntries, cursorVals, forward);
+    query.whereRaw(where.sql, where.params);
   }
-  query.orderBy(orderBy, effectiveAsc ? "asc" : "desc");
-  if (orderBy !== "_id") {
-    // Tiebreaker by _id in the same direction — the framework Query
-    // only models a single orderBy, so we add the tiebreaker as a
-    // raw ORDER BY suffix via _orderLimitOffset cooperation. Today
-    // Query lacks multi-orderBy; we emulate by sorting in-memory
-    // after the fetch using _id within each orderBy group. Keeps
-    // pagination correct without expanding the Query API.
-    // No raw orderBy needed because the WHERE condition above
-    // strictly disambiguates (orderByVal, _id) tuples — successive
-    // pages can't repeat or skip a row even with ties on orderBy.
+
+  // Apply ORDER BY for each entry. When forward=false we reverse direction
+  // per entry so the SQL returns rows in the right reading order; we then
+  // reverse client-side at the end.
+  for (var oi = 0; oi < orderEntries.length; oi++) {
+    var entry = orderEntries[oi];
+    var effectiveDir = ((entry.direction === "asc") === forward) ? "asc" : "desc";
+    query.orderBy(entry.column, effectiveDir);
   }
   query.limit(limit + 1);
 
   var rows = await Promise.resolve(query.all());
 
-  // Tiebreaker stability: when orderBy != _id, the SQL only sorts by
-  // orderBy. Within an orderByVal cluster, sort by _id in JS so the
-  // cursor predicate's _id-based tiebreaker stays consistent with the
-  // returned ordering.
-  if (orderBy !== "_id") {
-    rows.sort(function (a, b) {
-      var av = a[orderBy], bv = b[orderBy];
-      if (av < bv) return effectiveAsc ? -1 : 1;
-      if (av > bv) return effectiveAsc ?  1 : -1;
-      var ai = String(a._id), bi = String(b._id);
-      if (ai < bi) return effectiveAsc ? -1 : 1;
-      if (ai > bi) return effectiveAsc ?  1 : -1;
-      return 0;
-    });
-  }
-
   var hasMore = rows.length > limit;
   var page = hasMore ? rows.slice(0, limit) : rows.slice();
   if (!forward) page.reverse();
 
+  function _valsForRow(row) {
+    return orderEntries.map(function (e) {
+      return e.column === "_id" ? String(row._id) : row[e.column];
+    });
+  }
+
   var nextCursor = null;
   var prevCursor = null;
   if (hasMore && page.length > 0) {
     var last = page[page.length - 1];
     nextCursor = encodeCursor({
-      dir: direction, orderBy: orderBy,
-      orderByVal: last[orderBy], id: String(last._id),
-      forward: true,
+      orderKey: orderKey,
+      vals:     _valsForRow(last),
+      forward:  true,
     }, opts.secret);
   }
-  // Always emit a prev cursor when we have a starting position (the
-  // operator was on a non-first page). Operator UI hides it on the
-  // first page.
   if (cursorState && page.length > 0) {
     var first = page[0];
     prevCursor = encodeCursor({
-      dir: direction, orderBy: orderBy,
-      orderByVal: first[orderBy], id: String(first._id),
-      forward: false,
+      orderKey: orderKey,
+      vals:     _valsForRow(first),
+      forward:  false,
     }, opts.secret);
   }