@blamejs/core 0.4.1

package/lib/session.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * Session store — DB-backed, vault-sealed, sid-hashed-at-rest.
+ *
+ * Single-node: stored in the framework's main DB under `_blamejs_sessions`
+ * (baked into db.js's FRAMEWORK_SCHEMA — apps cannot opt out).
+ * Cluster mode: stored in external-db under the same name (via
+ * frameworkSchema.ensureSchema). cluster-storage.execute routes the SQL
+ * to the right place based on cluster.isClusterMode(); session.js itself
+ * doesn't branch on mode.
+ *
+ * Token discipline:
+ *   - The session id (sid) is a 32-byte random value returned to the caller
+ *     once. The caller stores it in a cookie / authorization header / etc.
+ *   - The DB primary key is sha3('bj-session:' || sid) — the sid itself
+ *     never lands in the database. DB exfiltration alone cannot impersonate
+ *     a session: the attacker would also need the original sid (which only
+ *     the user has).
+ *   - data is vault-sealed JSON; userId is sealed; userIdHash indexes for
+ *     destroyAllForUser without unsealing every row.
+ *
+ * Public API:
+ *
+ *   session.create({ userId, data?, ttlMs? })  → { token, expiresAt }
+ *   session.verify(token)                      → { userId, data, createdAt, expiresAt, lastActivity } or null
+ *   session.destroy(token)                     → boolean
+ *   session.destroyAllForUser(userId)          → number deleted
+ *   session.touch(token, { extendBy? })        → boolean (updates lastActivity, optionally extends expiresAt)
+ *   session.purgeExpired()                     → number deleted
+ *   session.count()                            → number of active (non-expired) sessions
+ *
+ * Cluster posture per blamejs-cluster-spec.md:
+ *   create / destroy / destroyAllForUser / touch / purgeExpired
+ *     — leader-only (cluster.requireLeader gate at call entry)
+ *   verify / count
+ *     — anywhere (any node can read shared session state)
+ */
+var { generateToken, sha3Hash } = require("./crypto");
+var safeJson = require("./safe-json");
+var cryptoField = require("./crypto-field");
+var clusterStorage = require("./cluster-storage");
+var cluster = require("./cluster");
+var C = require("./constants");
+var { SessionError } = require("./framework-error");
+
+var _err = SessionError.factory;
+
+var DEFAULT_TTL_MS = C.TIME.days(7);
+var SID_NAMESPACE  = "bj-session:";
+
+// Column order used for INSERT — kept as a constant so the placeholders
+// list and the values list stay in sync. Must match _blamejs_sessions's
+// schema in db.js (single-node) and framework-schema.js (cluster mode).
+var SESSION_COLS = ["sidHash", "userId", "userIdHash", "data", "createdAt", "expiresAt", "lastActivity"];
+
+function _hashSid(sid) {
+  return sha3Hash(SID_NAMESPACE + sid);
+}
+
+// Build a sealed row object with all SESSION_COLS keys present (null
+// where not set). The cryptoField.sealRow call seals userId/data and
+// produces userIdHash from userId.
+function _sealForInsert(row) {
+  var sealed = cryptoField.sealRow("_blamejs_sessions", row);
+  for (var i = 0; i < SESSION_COLS.length; i++) {
+    if (!(SESSION_COLS[i] in sealed)) sealed[SESSION_COLS[i]] = null;
+  }
+  return sealed;
+}
+
+// ---- Public API ----
+
+async function create(opts) {
+  cluster.requireLeader();
+  if (!opts || !opts.userId) {
+    throw _err("INVALID_ARG", "session.create requires { userId }", true);
+  }
+  var ttl = typeof opts.ttlMs === "number" ? opts.ttlMs : DEFAULT_TTL_MS;
+  if (ttl <= 0) throw _err("INVALID_ARG", "session.create: ttlMs must be > 0", true);
+
+  var sid       = generateToken(32);             // 64 hex chars; only place the plaintext sid lives
+  var sidHash   = _hashSid(sid);
+  var nowMs     = Date.now();
+  var expiresAt = nowMs + ttl;
+
+  var sealed = _sealForInsert({
+    sidHash:      sidHash,
+    userId:       opts.userId,
+    data:         opts.data ? JSON.stringify(opts.data) : null,
+    createdAt:    nowMs,
+    expiresAt:    expiresAt,
+    lastActivity: nowMs,
+  });
+  var values = SESSION_COLS.map(function (c) { return sealed[c]; });
+  var placeholders = SESSION_COLS.map(function () { return "?"; }).join(", ");
+  var quoted = SESSION_COLS.map(function (c) { return '"' + c + '"'; }).join(", ");
+  await clusterStorage.execute(
+    "INSERT INTO _blamejs_sessions (" + quoted + ") VALUES (" + placeholders + ")",
+    values
+  );
+
+  return { token: sid, expiresAt: expiresAt };
+}
+
+async function verify(token) {
+  if (typeof token !== "string" || token.length === 0) return null;
+  var sidHash = _hashSid(token);
+
+  var row = await clusterStorage.executeOne(
+    "SELECT sidHash, userId, userIdHash, data, createdAt, expiresAt, lastActivity " +
+    "FROM _blamejs_sessions WHERE sidHash = ?",
+    [sidHash]
+  );
+  if (!row) return null;
+  if (Number(row.expiresAt) < Date.now()) {
+    // Expired — clean up and return null. Cleanup is leader-only;
+    // verify is anywhere, so a follower observing an expired row
+    // skips the cleanup (next leader-side call will purge it).
+    if (cluster.isLeader()) {
+      try { await _deleteBySidHash(sidHash); } catch (_e) { /* best-effort */ }
+    }
+    return null;
+  }
+  // Unseal sealed columns (userId, data) using the cryptoField pipeline
+  // so we return cleartext to the caller — same shape as the previous
+  // db().from(...).first() path delivered.
+  var unsealed = cryptoField.unsealRow("_blamejs_sessions", row);
+  var data = null;
+  if (unsealed.data) {
+    try { data = safeJson.parse(unsealed.data); } catch (_e) { data = null; }
+  }
+  return {
+    userId:       unsealed.userId,
+    data:         data,
+    createdAt:    Number(unsealed.createdAt),
+    expiresAt:    Number(unsealed.expiresAt),
+    lastActivity: Number(unsealed.lastActivity),
+  };
+}
+
+async function destroy(token) {
+  cluster.requireLeader();
+  if (typeof token !== "string" || token.length === 0) return false;
+  return await _deleteBySidHash(_hashSid(token));
+}
+
+async function _deleteBySidHash(sidHash) {
+  var result = await clusterStorage.execute(
+    "DELETE FROM _blamejs_sessions WHERE sidHash = ?",
+    [sidHash]
+  );
+  return (result.rowCount || 0) > 0;
+}
+
+async function destroyAllForUser(userId) {
+  cluster.requireLeader();
+  if (!userId) throw _err("INVALID_ARG", "session.destroyAllForUser requires a userId", true);
+  // userId is sealed; look up via derived userIdHash.
+  var lookup = cryptoField.lookupHash("_blamejs_sessions", "userId", userId);
+  if (!lookup) {
+    throw _err("MISCONFIGURED",
+      "_blamejs_sessions schema is missing the userIdHash derived hash — framework misconfigured",
+      true);
+  }
+  var result = await clusterStorage.execute(
+    "DELETE FROM _blamejs_sessions WHERE userIdHash = ?",
+    [lookup.value]
+  );
+  return result.rowCount || 0;
+}
+
+async function touch(token, opts) {
+  cluster.requireLeader();
+  opts = opts || {};
+  if (typeof token !== "string" || token.length === 0) return false;
+  var sidHash = _hashSid(token);
+  var nowMs = Date.now();
+  // Two SQL paths so the SET list stays static (no dynamic column
+  // assembly) and matches the call shape clusterStorage expects.
+  // extendBy resets expiresAt relative to NOW, not relative to the
+  // current expiresAt — a soaked session with continuous traffic
+  // shouldn't accumulate unbounded expiry.
+  if (typeof opts.extendBy === "number" && opts.extendBy > 0) {
+    var newExpires = nowMs + opts.extendBy;
+    var result = await clusterStorage.execute(
+      "UPDATE _blamejs_sessions SET lastActivity = ?, expiresAt = ? " +
+      "WHERE sidHash = ? AND expiresAt >= ?",
+      [nowMs, newExpires, sidHash, nowMs]
+    );
+    return (result.rowCount || 0) > 0;
+  }
+  var result2 = await clusterStorage.execute(
+    "UPDATE _blamejs_sessions SET lastActivity = ? " +
+    "WHERE sidHash = ? AND expiresAt >= ?",
+    [nowMs, sidHash, nowMs]
+  );
+  return (result2.rowCount || 0) > 0;
+}
+
+// rotate(oldToken, opts?) — session fixation defense. Generates a fresh
+// sid for the same userId + data, atomically replacing the old sid in
+// the row. Standard pattern: call after auth state changes (login from
+// anonymous, MFA verified, role escalation) so any sid an attacker
+// might have planted pre-login becomes invalid.
+//
+//   opts:
+//     data:   optional replacement session data (re-sealed)
+//     ttlMs:  optional new TTL; if absent, expiresAt is preserved
+//     reason: free-form audit metadata ('login', 'mfa', etc.)
+//
+// Returns { token, expiresAt } on success, or null when the old token
+// doesn't exist / has expired (operator distinguishes by checking
+// for null).
+//
+// Atomicity: single UPDATE swaps sidHash. The old + new tokens never
+// coexist — the moment the UPDATE commits, only the new token verifies.
+// Backends that can't do the WHERE-guarded UPDATE atomically (none of
+// the framework's supported backends fall in that bucket) would need
+// a transactional shim.
+async function rotate(oldToken, opts) {
+  cluster.requireLeader();
+  if (typeof oldToken !== "string" || oldToken.length === 0) return null;
+  opts = opts || {};
+
+  var newSid       = generateToken(32);
+  var newSidHash   = _hashSid(newSid);
+  var oldSidHash   = _hashSid(oldToken);
+  var nowMs        = Date.now();
+  var newExpires   = (typeof opts.ttlMs === "number" && opts.ttlMs > 0)
+                       ? nowMs + opts.ttlMs : null;
+
+  var setParts = ['"sidHash" = ?', '"lastActivity" = ?'];
+  var setParams = [newSidHash, nowMs];
+
+  if (opts.data !== undefined) {
+    var dataJson = opts.data ? JSON.stringify(opts.data) : null;
+    var sealedRow = cryptoField.sealRow("_blamejs_sessions", { data: dataJson });
+    setParts.push('"data" = ?');
+    setParams.push(sealedRow.data);
+  }
+  if (newExpires !== null) {
+    setParts.push('"expiresAt" = ?');
+    setParams.push(newExpires);
+  }
+
+  var sql = "UPDATE _blamejs_sessions SET " + setParts.join(", ") +
+            " WHERE sidHash = ? AND expiresAt >= ?";
+  var params = setParams.concat([oldSidHash, nowMs]);
+  var result = await clusterStorage.execute(sql, params);
+  if ((result.rowCount || 0) === 0) return null;
+
+  // Read the row's effective expiresAt to return — single source of truth.
+  var row = await clusterStorage.executeOne(
+    'SELECT "expiresAt" FROM _blamejs_sessions WHERE sidHash = ?',
+    [newSidHash]
+  );
+  var expiresAt = row ? Number(row.expiresAt) : null;
+
+  // Audit emit — best-effort. The framework's audit chain logs the
+  // privilege transition so post-incident review can trace which
+  // session id covered which privilege state.
+  try {
+    var audit = require("./audit");
+    audit.emit({
+      action:  "auth.session.rotate",
+      outcome: "success",
+      metadata: { reason: opts.reason || "explicit" },
+    });
+  } catch (_e) { /* boot-order tolerance */ }
+
+  return { token: newSid, expiresAt: expiresAt };
+}
+
+async function purgeExpired() {
+  cluster.requireLeader();
+  var result = await clusterStorage.execute(
+    "DELETE FROM _blamejs_sessions WHERE expiresAt < ?",
+    [Date.now()]
+  );
+  return result.rowCount || 0;
+}
+
+async function count() {
+  var row = await clusterStorage.executeOne(
+    "SELECT COUNT(*) AS c FROM _blamejs_sessions WHERE expiresAt >= ?",
+    [Date.now()]
+  );
+  return row ? Number(row.c) : 0;
+}
+
+function _resetForTest() { /* no module state to reset; clusterStorage and cryptoField own theirs */ }
+
+module.exports = {
+  create:               create,
+  verify:               verify,
+  destroy:              destroy,
+  destroyAllForUser:    destroyAllForUser,
+  touch:                touch,
+  rotate:               rotate,
+  purgeExpired:         purgeExpired,
+  count:                count,
+  DEFAULT_TTL_MS:       DEFAULT_TTL_MS,
+  _resetForTest:        _resetForTest,
+};

package/lib/slug.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * b.slug — URL-safe slug generation.
+ *
+ *   b.slug("Hello, World!")                           // "hello-world"
+ *   b.slug("café", { preserveUnicode: false })        // "cafe"
+ *   b.slug("Привет мир", { preserveUnicode: true })   // "привет-мир"
+ *
+ *   var slug = b.slug.create({ maxLength: 60 });
+ *   slug("Title");
+ *
+ *   var s = await b.slug.unique("Hello, World!", function (cand) {
+ *     return db.bundles.exists({ slug: cand });
+ *   });
+ *   // → "hello-world", or "hello-world-2", "hello-world-3", ...
+ *
+ * The default ASCII path uses Unicode NFKD decomposition + combining-mark
+ * strip (`café` → `cafe`) and drops anything outside `[a-zA-Z0-9]`. The
+ * `preserveUnicode: true` path uses NFC and only drops Unicode punctuation,
+ * symbols, and separators — Cyrillic, Greek, CJK, and other scripts pass
+ * through. Operators with non-Latin user content opt into preserveUnicode.
+ *
+ * Validation tiers:
+ *
+ *   - Opts at first call (every public fn) → Tier A (throw)
+ *   - title not a string                   → Tier A (throw)
+ *   - title normalizes to empty            → Tier C (return opts.fallback)
+ *   - unique() exhausts maxAttempts        → Tier A (throw SlugError)
+ *
+ * Out of scope (v1):
+ *   - Word-by-word transliteration tables (Russian → English, Chinese →
+ *     Pinyin). Use preserveUnicode: true as the v1 escape hatch.
+ *   - Stemming / lemmatization / stopword removal.
+ *   - HTML-tag stripping (sanitize textually before slugging).
+ */
+
+var { SlugError } = require("./framework-error");
+var _err = SlugError.factory;
+
+// ---- Defaults ----
+
+var DEFAULTS = Object.freeze({
+  separator:       "-",
+  lowercase:       true,
+  maxLength:       80,
+  preserveUnicode: false,
+  fallback:        "",
+});
+
+// Common reserved web slugs. Operators extend (e.g. via Set union with
+// router.getReservedSlugs()) and pass into b.slug.unique's isUsed predicate.
+// Returned as a fresh Set on each access via the getter so callers cannot
+// mutate the shared reference.
+var _RESERVED = Object.freeze([
+  "admin", "api", "auth", "login", "logout", "signup", "signin", "signout",
+  "register", "settings", "account", "profile", "users", "user", "me",
+  "static", "assets", "public", "favicon.ico", "robots.txt", "sitemap.xml",
+  "health", "metrics", "ping", "status",
+  "docs", "doc", "help", "support", "terms", "privacy", "legal",
+  "search", "feed", "rss", "atom",
+  "new", "edit", "delete", "create", "update",
+]);
+
+// ---- Tier-A validation helpers ----
+
+function _isPositiveInt(n) {
+  return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;
+}
+
+function _validateOpts(name, opts) {
+  if (typeof opts.separator !== "string" || opts.separator.length !== 1) {
+    throw _err("BAD_OPT", name + ": separator must be a single-character string, got " +
+      typeof opts.separator + " " + JSON.stringify(opts.separator), true);
+  }
+  if (typeof opts.lowercase !== "boolean") {
+    throw _err("BAD_OPT", name + ": lowercase must be a boolean, got " + typeof opts.lowercase, true);
+  }
+  if (opts.maxLength !== null && !_isPositiveInt(opts.maxLength)) {
+    throw _err("BAD_OPT", name + ": maxLength must be a positive integer or null, got " +
+      typeof opts.maxLength + " " + JSON.stringify(opts.maxLength), true);
+  }
+  if (typeof opts.preserveUnicode !== "boolean") {
+    throw _err("BAD_OPT", name + ": preserveUnicode must be a boolean, got " +
+      typeof opts.preserveUnicode, true);
+  }
+  if (typeof opts.fallback !== "string") {
+    throw _err("BAD_OPT", name + ": fallback must be a string, got " + typeof opts.fallback, true);
+  }
+}
+
+// ---- Core slugify ----
+
+// Drops Unicode marks (combining accents) after NFKD decomposition.
+// The two regexes are pre-compiled because slug() is on the hot path
+// for any title-driven workflow (uploads, bundle creation, seeders).
+var _COMBINING_MARKS = /\p{M}+/gu;
+// Anything outside ASCII alphanumeric → separator (default ASCII path).
+var _NON_ASCII_ALNUM = /[^a-zA-Z0-9]+/g;
+// Unicode-preserving path: drop punctuation, symbols, separators only.
+// \p{P} = Punctuation, \p{S} = Symbol, \p{Z} = Separator (incl. spaces),
+// \p{C} = Control/format. Letters and Numbers in any script pass through.
+var _UNICODE_NON_ALNUM = /[\p{P}\p{S}\p{Z}\p{C}]+/gu;
+
+function _slugify(title, opts) {
+  if (typeof title !== "string") {
+    throw _err("BAD_TITLE", "slug: title must be a string, got " + typeof title, true);
+  }
+
+  var sep = opts.separator;
+  // Build a regex to collapse runs of the chosen separator. Escape since
+  // separator is operator-supplied (validated single-char, but could be
+  // a regex meta-char like "." or "-").
+  var sepEsc = sep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  var collapseSep = new RegExp(sepEsc + "+", "g");
+  var trimSep    = new RegExp("^" + sepEsc + "+|" + sepEsc + "+$", "g");
+
+  var s = title;
+
+  if (opts.preserveUnicode) {
+    s = s.normalize("NFC");
+    s = s.replace(_UNICODE_NON_ALNUM, sep);
+  } else {
+    s = s.normalize("NFKD").replace(_COMBINING_MARKS, "");
+    s = s.replace(_NON_ASCII_ALNUM, sep);
+  }
+
+  if (opts.lowercase) {
+    // Use locale-independent toLowerCase for both paths so slug output
+    // is deterministic across hosts (Turkish-locale dotted-i etc. would
+    // otherwise drift).
+    s = s.toLowerCase();
+  }
+
+  s = s.replace(collapseSep, sep).replace(trimSep, "");
+
+  if (opts.maxLength !== null && s.length > opts.maxLength) {
+    s = _truncateAtSeparator(s, opts.maxLength, sep);
+  }
+
+  if (s.length === 0) return opts.fallback;
+  return s;
+}
+
+// Truncate at the last separator that keeps length ≤ maxLength.
+// If there's no separator within the cap, fall back to char truncation
+// (single-token long inputs).
+function _truncateAtSeparator(s, maxLength, sep) {
+  if (s.length <= maxLength) return s;
+  var slice = s.slice(0, maxLength);
+  var lastSep = slice.lastIndexOf(sep);
+  if (lastSep > 0) return slice.slice(0, lastSep);
+  return slice;
+}
+
+// ---- Public surface ----
+
+function slug(title, callOpts) {
+  var opts = Object.assign({}, DEFAULTS, callOpts || {});
+  _validateOpts("slug", opts);
+  return _slugify(title, opts);
+}
+
+function create(creatorOpts) {
+  var merged = Object.assign({}, DEFAULTS, creatorOpts || {});
+  _validateOpts("slug.create", merged);
+  // Bound function: per-call opts override creator opts.
+  return function boundSlug(title, callOpts) {
+    var opts = Object.assign({}, merged, callOpts || {});
+    _validateOpts("slug", opts);
+    return _slugify(title, opts);
+  };
+}
+
+async function unique(title, isUsed, callOpts) {
+  if (typeof isUsed !== "function") {
+    throw _err("BAD_ISUSED", "slug.unique: isUsed must be a function, got " + typeof isUsed, true);
+  }
+  callOpts = callOpts || {};
+  var opts = Object.assign({}, DEFAULTS, callOpts);
+  _validateOpts("slug.unique", opts);
+
+  var maxAttempts = (callOpts.maxAttempts !== undefined) ? callOpts.maxAttempts : 100;
+  if (!_isPositiveInt(maxAttempts)) {
+    throw _err("BAD_OPT", "slug.unique: maxAttempts must be a positive integer, got " +
+      typeof maxAttempts + " " + JSON.stringify(maxAttempts), true);
+  }
+  var start = (callOpts.start !== undefined) ? callOpts.start : 2;
+  if (!_isPositiveInt(start)) {
+    throw _err("BAD_OPT", "slug.unique: start must be a positive integer, got " +
+      typeof start + " " + JSON.stringify(start), true);
+  }
+  var suffixSep = (callOpts.suffixSeparator !== undefined) ? callOpts.suffixSeparator : opts.separator;
+  if (typeof suffixSep !== "string" || suffixSep.length === 0) {
+    throw _err("BAD_OPT", "slug.unique: suffixSeparator must be a non-empty string, got " +
+      typeof suffixSep, true);
+  }
+
+  var base = _slugify(title, opts);
+  // First attempt: bare base.
+  var used = await isUsed(base);
+  if (!used) return base;
+
+  // Subsequent attempts: base + suffixSep + n, starting at `start`.
+  // The bare base counted as attempt 1; we have maxAttempts-1 numeric tries left.
+  for (var i = 0; i < maxAttempts - 1; i++) {
+    var n = start + i;
+    var candidate = base + suffixSep + n;
+    // If maxLength would be exceeded by the suffix, truncate the base further
+    // so the final candidate fits.
+    if (opts.maxLength !== null && candidate.length > opts.maxLength) {
+      var roomForBase = opts.maxLength - (suffixSep.length + String(n).length);
+      if (roomForBase < 1) {
+        // Pathological case: caller's maxLength can't hold any base with this suffix.
+        throw _err("UNIQUE_EXHAUSTED",
+          "slug.unique: maxLength " + opts.maxLength + " too small for suffix '" +
+          suffixSep + n + "' (base would need " + roomForBase + " chars)", true);
+      }
+      var truncBase = _truncateAtSeparator(base, roomForBase, opts.separator);
+      candidate = truncBase + suffixSep + n;
+    }
+    var taken = await isUsed(candidate);
+    if (!taken) return candidate;
+  }
+
+  throw _err("UNIQUE_EXHAUSTED",
+    "slug.unique: exhausted " + maxAttempts + " attempts for base '" + base + "'", true);
+}
+
+// b.slug is the function itself with sub-API hung off it (callable
+// namespace pattern). Operators get the 90% case (`b.slug("title")`) in
+// one line and reach the rest via `b.slug.create`, `b.slug.unique`,
+// `b.slug.RESERVED`, `b.slug.DEFAULTS`, `b.slug.SlugError`.
+//
+// The shared RESERVED Set is intentionally mutable so an app can
+// extend it once at boot:
+//   b.slug.RESERVED.add("my-reserved-route");
+slug.create    = create;
+slug.unique    = unique;
+slug.RESERVED  = new Set(_RESERVED);
+slug.DEFAULTS  = DEFAULTS;
+slug.SlugError = SlugError;
+
+module.exports = slug;