@blamejs/core 0.8.52 → 0.8.58

package/lib/auth/passkey.js

@@ -121,20 +121,55 @@ async function verifyRegistration(opts) {
   _requireString(opts.expectedOrigin, "expectedOrigin");
   _requireString(opts.expectedRPID, "expectedRPID");
 
-  return await _vendor().verifyRegistrationResponse({
+  var rv = await _vendor().verifyRegistrationResponse({
     response:           opts.response,
     expectedChallenge:  opts.expectedChallenge,
     expectedOrigin:     opts.expectedOrigin,
     expectedRPID:       opts.expectedRPID,
     requireUserVerification: opts.requireUserVerification !== false,
   });
+  // WebAuthn L3 §6.1.3 — surface authenticator-data BE/BS flags as
+  // named fields. backupEligible (BE) signals the credential CAN be
+  // backed up to a cloud account; backupState (BS) signals it IS
+  // currently backed up. Operators key trust decisions on these
+  // (single-device passkey → require step-up; multi-device synced
+  // passkey → strong signal). The vendor parses authData and exposes
+  // credentialDeviceType ("singleDevice" | "multiDevice") and
+  // credentialBackedUp (boolean) on registrationInfo; we map them to
+  // the spec's flag names and add them to the top-level result so
+  // callers don't have to dig through registrationInfo.
+  if (rv && rv.registrationInfo) {
+    rv.backupEligible = rv.registrationInfo.credentialDeviceType === "multiDevice";
+    rv.backupState    = rv.registrationInfo.credentialBackedUp === true;
+  } else {
+    rv = rv || {};
+    rv.backupEligible = false;
+    rv.backupState    = false;
+  }
+  return rv;
 }
 
 // ---- Authentication ----
 
+// startAuthentication accepts an optional `mediation` token that the
+// caller passes through verbatim to the browser as
+// `navigator.credentials.get({ publicKey, mediation })`. The descriptor
+// itself doesn't carry mediation — it's a separate argument on the
+// page — but startAuthentication echoes it onto the returned options
+// so the operator's transport (typically a JSON GET) carries it to
+// the page without losing the value. Allowed tokens per the W3C
+// Credential Management spec: "silent" / "optional" / "required" /
+// "conditional". "conditional" enables passkey autofill on
+// <input autocomplete="webauthn">.
+var ALLOWED_MEDIATION = { silent: 1, optional: 1, required: 1, conditional: 1 };
+
 async function startAuthentication(opts) {
   if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
   _requireString(opts.rpId, "rpId");
+  if (opts.mediation !== undefined && !ALLOWED_MEDIATION[opts.mediation]) {
+    throw new AuthError("auth-passkey/bad-mediation",
+      "mediation must be one of silent/optional/required/conditional");
+  }
 
   var options = await _vendor().generateAuthenticationOptions({
     rpID:               opts.rpId,
@@ -148,9 +183,169 @@ async function startAuthentication(opts) {
   } else {
     options.hints = opts.hints;
   }
+  if (opts.mediation !== undefined) {
+    options.mediation = opts.mediation;
+  }
+  return options;
+}
+
+// conditionalAuthOptions — convenience wrapper for the passkey-autofill
+// flow (mediation: "conditional"). Browsers require an empty
+// allowCredentials list, presence-only userVerification (so the
+// autofill chip can surface without forcing biometric), and a present
+// challenge. Returns an object shaped for
+// `navigator.credentials.get({ publicKey: <opts>, mediation: "conditional" })`.
+async function conditionalAuthOptions(opts) {
+  if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
+  _requireString(opts.rpId, "rpId");
+
+  var options = await _vendor().generateAuthenticationOptions({
+    rpID:               opts.rpId,
+    // For conditional UI the spec mandates an empty allowCredentials
+    // list — discoverable credentials only. Supplying a list here
+    // suppresses the autofill chip in current browsers.
+    allowCredentials:   [],
+    userVerification:   opts.userVerification || "preferred",
+    timeout:            opts.timeout,
+    extensions:         opts.extensions,
+  });
+  options.mediation = "conditional";
+  if (!opts.hints) {
+    options.hints = ["client-device", "hybrid"];
+  } else {
+    options.hints = opts.hints;
+  }
   return options;
 }
 
+// ---- WebAuthn L3 extension helpers (PRF / largeBlob / credBlob) ----
+//
+// Pre-compute the spec-correct shape so callers don't have to remember
+// (a) what the field is called this year, (b) which inputs travel as
+// base64url vs Uint8Array, (c) which support the {support:"required"}
+// contract. Validation tier: throw at config-time. Misuse here is a
+// coding bug, not a request-shape thing.
+
+function _b64urlExtInput(value, name) {
+  // Accept a base64url string OR a Buffer / Uint8Array. Normalize the
+  // wire shape to base64url (the JSON descriptor ships base64url; the
+  // browser turns it into an ArrayBuffer before passing to the
+  // authenticator).
+  if (typeof value === "string") {
+    if (value.length === 0 || !safeBuffer.BASE64URL_RE.test(value)) {
+      throw new AuthError("auth-passkey/bad-extension-input",
+        name + " must be base64url (no padding) when string");
+    }
+    return value;
+  }
+  if (Buffer.isBuffer(value)) {
+    return value.toString("base64url");
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value).toString("base64url");
+  }
+  throw new AuthError("auth-passkey/bad-extension-input",
+    name + " must be base64url string, Buffer, or Uint8Array");
+}
+
+// PRF (Pseudo-Random Function) extension — WebAuthn L3 §10.1.2.
+// Authenticator-bound HKDF source. eval inputs are 32-byte salts; the
+// authenticator returns deterministic 32-byte outputs the operator
+// uses as a key-encryption key (vault unlock, file-encryption seed).
+// Shape: `{ prf: { eval: { first, second? } } }` per extension-id "prf".
+function _prfExt(args) {
+  if (!args || !args.eval) {
+    throw new AuthError("auth-passkey/missing-eval",
+      "extensions.prf({ eval: { first, second? } }) is required");
+  }
+  if (args.eval.first === undefined || args.eval.first === null) {
+    throw new AuthError("auth-passkey/missing-prf-first",
+      "extensions.prf eval.first is required");
+  }
+  var out = { prf: { eval: { first: _b64urlExtInput(args.eval.first, "eval.first") } } };
+  if (args.eval.second !== undefined && args.eval.second !== null) {
+    out.prf.eval.second = _b64urlExtInput(args.eval.second, "eval.second");
+  }
+  return out;
+}
+
+// largeBlob extension — WebAuthn L3 §10.3.
+// Per-credential opaque blob storage. At registration the operator
+// asks for support: "preferred" | "required". At auth time the
+// operator asks to read OR write, never both in the same assertion.
+function _largeBlobExt(args) {
+  if (!args) {
+    throw new AuthError("auth-passkey/missing-largeblob",
+      "extensions.largeBlob({ support? | read? | write? }) is required");
+  }
+  var out = { largeBlob: {} };
+  var SUPPORT = { preferred: 1, required: 1 };
+  var modes = 0;
+  if (args.support !== undefined) {
+    if (!SUPPORT[args.support]) {
+      throw new AuthError("auth-passkey/bad-largeblob-support",
+        "extensions.largeBlob support must be 'preferred' or 'required'");
+    }
+    out.largeBlob.support = args.support;
+    modes++;
+  }
+  if (args.read === true) {
+    out.largeBlob.read = true;
+    modes++;
+  } else if (args.read !== undefined && args.read !== false) {
+    throw new AuthError("auth-passkey/bad-largeblob-read",
+      "extensions.largeBlob read must be a boolean");
+  }
+  if (args.write !== undefined && args.write !== null) {
+    if (!Buffer.isBuffer(args.write) && !(args.write instanceof Uint8Array)) {
+      throw new AuthError("auth-passkey/bad-largeblob-write",
+        "extensions.largeBlob write must be a Uint8Array / Buffer");
+    }
+    out.largeBlob.write = Buffer.from(args.write).toString("base64url");
+    modes++;
+  }
+  if (modes === 0) {
+    throw new AuthError("auth-passkey/empty-largeblob",
+      "extensions.largeBlob({}) needs support, read, or write");
+  }
+  if (args.read === true && args.write !== undefined && args.write !== null) {
+    throw new AuthError("auth-passkey/conflicting-largeblob",
+      "extensions.largeBlob — read and write are mutually exclusive");
+  }
+  return out;
+}
+
+// credBlob extension — WebAuthn L3 §10.5.
+// Server-supplied opaque blob (≤32 bytes per CTAP2.1) bound to the
+// credential at registration. Returned in subsequent assertions.
+// Shape: `{ credBlob: <base64url> }`.
+function _credBlobExt(args) {
+  if (!args || args.blob === undefined || args.blob === null) {
+    throw new AuthError("auth-passkey/missing-credblob",
+      "extensions.credBlob({ blob }) is required");
+  }
+  var buf;
+  if (Buffer.isBuffer(args.blob)) {
+    buf = args.blob;
+  } else if (args.blob instanceof Uint8Array) {
+    buf = Buffer.from(args.blob);
+  } else {
+    throw new AuthError("auth-passkey/bad-credblob",
+      "extensions.credBlob blob must be a Uint8Array / Buffer");
+  }
+  if (buf.length === 0 || buf.length > 32) {                                       // allow:raw-byte-literal — CTAP2.1 §11.1 credBlob max
+    throw new AuthError("auth-passkey/credblob-bad-length",
+      "extensions.credBlob blob must be 1-32 bytes (CTAP2.1 §11.1)");
+  }
+  return { credBlob: buf.toString("base64url") };
+}
+
+var extensions = {
+  prf:       _prfExt,
+  largeBlob: _largeBlobExt,
+  credBlob:  _credBlobExt,
+};
+
 async function verifyAuthentication(opts) {
   if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
   if (!opts.response) {
@@ -164,7 +359,7 @@ async function verifyAuthentication(opts) {
       "opts.credential { id, publicKey, counter? } is required");
   }
 
-  return await _vendor().verifyAuthenticationResponse({
+  var rv = await _vendor().verifyAuthenticationResponse({
     response:           opts.response,
     expectedChallenge:  opts.expectedChallenge,
     expectedOrigin:     opts.expectedOrigin,
@@ -177,6 +372,21 @@ async function verifyAuthentication(opts) {
     },
     requireUserVerification: opts.requireUserVerification !== false,
   });
+  // WebAuthn L3 §6.1.3 — same BE/BS surfacing as verifyRegistration.
+  // Authentication assertions also carry the BE/BS bits in authData; a
+  // credential that registered as single-device but later asserts as
+  // multi-device (or vice versa) is a backup-state-changed signal worth
+  // auditing at the operator level. We expose the current values so the
+  // caller can compare against what they persisted at registration.
+  if (rv && rv.authenticationInfo) {
+    rv.backupEligible = rv.authenticationInfo.credentialDeviceType === "multiDevice";
+    rv.backupState    = rv.authenticationInfo.credentialBackedUp === true;
+  } else {
+    rv = rv || {};
+    rv.backupEligible = false;
+    rv.backupState    = false;
+  }
+  return rv;
 }
 
 // ---- WebAuthn Signal API (W3C draft, 2024) ----
@@ -265,6 +475,8 @@ module.exports = {
   verifyRegistration:           verifyRegistration,
   startAuthentication:          startAuthentication,
   verifyAuthentication:         verifyAuthentication,
+  conditionalAuthOptions:       conditionalAuthOptions,
+  extensions:                   extensions,
   signalUnknownCredential:      signalUnknownCredential,
   signalAllAcceptedCredentials: signalAllAcceptedCredentials,
   signalCurrentUserDetails:     signalCurrentUserDetails,

package/lib/auth-bot-challenge.js

@@ -136,7 +136,7 @@ function _defaultKeyExtractor(req) {
  * @signature b.authBotChallenge.create(opts)
  * @since     0.8.48
  * @status    stable
- * @related   b.middleware.botGuard, b.auth.lockout, b.auth.atoKillSwitch
+ * @related   b.middleware.botGuard
  *
  * Build an adaptive bot-challenge gate. Returns
  * `{ middleware, recordFailure, recordSuccess, check, reset }`.

package/lib/credential-hash.js

@@ -173,7 +173,7 @@ function _decodeEnvelope(env) {
  * @since      0.2.28
  * @status     stable
  * @compliance pci-dss, soc2, hipaa
- * @related    b.credentialHash.verify, b.credentialHash.needsRehash, b.auth.password.hash
+ * @related    b.credentialHash.verify, b.credentialHash.needsRehash
  *
  * Hash a credential secret into a base64 envelope ready for storage in
  * a `credentialHash` column. Default algorithm is SHAKE256 with a
@@ -345,7 +345,7 @@ function inspect(envelope) {
  * @signature  b.credentialHash.needsRehash(envelope, opts?)
  * @since      0.2.28
  * @status     stable
- * @related    b.credentialHash.hash, b.credentialHash.verify, b.auth.password.needsRehash
+ * @related    b.credentialHash.hash, b.credentialHash.verify
  *
  * Returns `true` when the stored envelope was produced under an
  * algorithm or parameter set that no longer matches the framework

package/lib/db-collection.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * @module     b.db.collection
+ * @nav        Data
+ * @title      Collection
+ * @order      210
+ * @card       Mongo-style facade over `b.db.from(name)`. Wraps the
+ *             chainable Query builder in `{ insert, find, findOne,
+ *             update, remove, count, paginate }` for codebases
+ *             migrating from MongoDB or for primitives that prefer
+ *             the document-store call shape.
+ *
+ * @intro
+ *   `b.db.collection(name)` returns a small adapter that maps Mongo-
+ *   shape calls onto the framework's query-builder primitives:
+ *
+ *     b.db.collection("users").findOne({ email: "alice@x.com" });
+ *       → b.db.from("users").where({ email: "alice@x.com" }).first();
+ *
+ *     b.db.collection("users").update({ _id }, { $set: { name } });
+ *       → b.db.from("users").where({ _id }).updateOne({ name });
+ *
+ *     b.db.collection("users").update({ _id }, { $inc: { failed: 1 } });
+ *       → b.db.from("users").where({ _id }).increment("failed", 1);
+ *
+ *   Operators migrating from a Mongo-shaped codebase (HermitStash and
+ *   peers) can drop in this facade without rewriting every call site
+ *   to the chainable builder. New code typically reaches for the
+ *   builder directly — `b.db.from(...)` is more expressive and
+ *   doesn't pretend to be Mongo.
+ *
+ *   Supported update operators: `$set` (assign), `$inc` (atomic
+ *   increment per column — composes `Query.increment`), `$unset`
+ *   (set to NULL).
+ */
+
+var lazyRequire = require("./lazy-require");
+
+// db.js → db-collection.js → db.from() would create a require cycle.
+// Defer the lookup to call-time so the binding lands after both
+// modules finish loading.
+var db = lazyRequire(function () { return require("./db"); });
+
+function _validateQueryShape(query) {
+  if (!query || typeof query !== "object" || Array.isArray(query)) {
+    throw new TypeError("collection: query must be a plain object");
+  }
+}
+
+function _applyQuery(builder, query) {
+  // Mongo-shape supports `field: value` for equality and `field:
+  // { $gt: x }` / `{ $lt: x }` / `{ $gte: x }` / `{ $lte: x }` /
+  // `{ $ne: x }` / `{ $in: [...] }` / `{ $like: "pattern" }` for
+  // operators. Anything else throws — refuse silently translating
+  // unknown operators into something that might match more rows
+  // than intended.
+  var keys = Object.keys(query);
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    var v = query[k];
+    if (v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date)) {
+      var opKeys = Object.keys(v);
+      for (var j = 0; j < opKeys.length; j += 1) {
+        var op = opKeys[j];
+        var val = v[op];
+        switch (op) {
+          case "$eq":  builder.where(k, "=",  val); break;
+          case "$ne":  builder.where(k, "!=", val); break;
+          case "$gt":  builder.where(k, ">",  val); break;
+          case "$gte": builder.where(k, ">=", val); break;
+          case "$lt":  builder.where(k, "<",  val); break;
+          case "$lte": builder.where(k, "<=", val); break;
+          case "$in":
+            if (!Array.isArray(val)) {
+              throw new TypeError("collection: $in requires an array (got " + typeof val + ")");
+            }
+            builder.where(k, "IN", val);
+            break;
+          case "$like":
+            if (typeof val !== "string") {
+              throw new TypeError("collection: $like requires a string");
+            }
+            builder.where(k, "LIKE", val);
+            break;
+          default:
+            throw new TypeError("collection: unsupported query operator '" + op +
+              "' on field '" + k + "' (allowed: $eq / $ne / $gt / $gte / $lt / $lte / $in / $like)");
+        }
+      }
+    } else {
+      builder.where(k, "=", v);
+    }
+  }
+}
+
+function _splitUpdateOperators(update) {
+  // Allow either Mongo-shape `{ $set: {...}, $inc: {...} }` OR plain
+  // `{ field: value, ... }` (treated as $set). Returns a tuple of
+  // sets / increments / unsets so the caller can dispatch.
+  if (!update || typeof update !== "object" || Array.isArray(update)) {
+    throw new TypeError("collection: update must be a plain object");
+  }
+  var keys = Object.keys(update);
+  var hasOperator = keys.some(function (k) { return k.charAt(0) === "$"; });
+  if (!hasOperator) {
+    return { sets: update, incs: null, unsets: null };
+  }
+  var sets = null;
+  var incs = null;
+  var unsets = null;
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    if (k === "$set") {
+      if (!update[k] || typeof update[k] !== "object") {
+        throw new TypeError("collection: $set value must be an object");
+      }
+      sets = update[k];
+    } else if (k === "$inc") {
+      if (!update[k] || typeof update[k] !== "object") {
+        throw new TypeError("collection: $inc value must be an object");
+      }
+      incs = update[k];
+    } else if (k === "$unset") {
+      if (!update[k] || typeof update[k] !== "object") {
+        throw new TypeError("collection: $unset value must be an object");
+      }
+      unsets = update[k];
+    } else {
+      throw new TypeError("collection: unsupported update operator '" + k +
+        "' (allowed: $set / $inc / $unset; or pass a plain object for an implicit $set)");
+    }
+  }
+  return { sets: sets, incs: incs, unsets: unsets };
+}
+
+/**
+ * @primitive b.db.collection
+ * @signature b.db.collection(name)
+ * @since     0.8.58
+ * @status    stable
+ * @related   b.db.from, b.db
+ *
+ * Returns a Mongo-style adapter for the named table. Each method
+ * dispatches to `b.db.from(name)` under the hood; sealed-column
+ * semantics, derived-hash translation, and audit emission carry
+ * through unchanged.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [{
+ *     name: "users",
+ *     columns: { _id: "TEXT PRIMARY KEY", email: "TEXT", failed: "INTEGER NOT NULL DEFAULT 0" },
+ *   }] });
+ *   var users = b.db.collection("users");
+ *   users.insert({ _id: "u1", email: "alice@x.com" });
+ *   users.findOne({ email: "alice@x.com" });
+ *   users.update({ _id: "u1" }, { $inc: { failed: 1 } });
+ *   users.update({ _id: "u1" }, { $set: { failed: 0 } });
+ *   users.remove({ _id: "u1" });
+ */
+function collection(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("collection(name): name must be a non-empty string");
+  }
+  return {
+    name: name,
+
+    // Insert one document. Returns the inserted row with `_id` filled
+    // in (if absent on input). Composes Query.insertOne.
+    insert: function (doc) {
+      return db().from(name).insertOne(doc);
+    },
+
+    // Insert many. Returns array of inserted rows.
+    insertMany: function (docs) {
+      return db().from(name).insertMany(docs);
+    },
+
+    // Find rows matching the query. Returns an array. Pass `opts.limit`
+    // / `opts.offset` / `opts.orderBy` / `opts.orderDir` for paging.
+    find: function (query, opts) {
+      _validateQueryShape(query || {});
+      var q = db().from(name);
+      _applyQuery(q, query || {});
+      if (opts && opts.orderBy) q.orderBy(opts.orderBy, opts.orderDir || "asc");
+      if (opts && opts.limit !== undefined) q.limit(opts.limit);
+      if (opts && opts.offset !== undefined) q.offset(opts.offset);
+      return q.all();
+    },
+
+    // Find one row, or null. Equivalent to `.find(...).all()[0]` but
+    // emits `LIMIT 1` so the engine doesn't materialise the rest.
+    findOne: function (query) {
+      _validateQueryShape(query);
+      var q = db().from(name);
+      _applyQuery(q, query);
+      return q.first() || null;
+    },
+
+    // Update rows matching the query. Accepts Mongo `{ $set, $inc,
+    // $unset }` operator form OR a plain field-map (treated as $set).
+    // Returns the number of rows changed.
+    //
+    // `$inc` composes Query.increment so the SQL is
+    //   UPDATE table SET col = COALESCE(col, 0) + ? WHERE ...
+    // — atomic across concurrent writers, no fetch/mutate/store race.
+    update: function (query, update, opts) {
+      _validateQueryShape(query || {});
+      var split = _splitUpdateOperators(update);
+      var single = !(opts && opts.many === true);
+      var changed = 0;
+
+      // $inc — apply increments per column. Each call shares the
+      // where-clause but is its own UPDATE statement (one SQL per
+      // bumped column). The where filter must be re-built per call
+      // because Query is single-shot.
+      if (split.incs) {
+        var incCols = Object.keys(split.incs);
+        for (var i = 0; i < incCols.length; i += 1) {
+          var qInc = db().from(name);
+          _applyQuery(qInc, query || {});
+          var delta = split.incs[incCols[i]];
+          if (typeof delta !== "number" || !Number.isInteger(delta)) {
+            throw new TypeError("collection.update: $inc.'" + incCols[i] + "' must be an integer");
+          }
+          changed += qInc.increment(incCols[i], delta);
+        }
+      }
+
+      // $set / plain-object form — single UPDATE with the merged
+      // changes object.
+      var setObj = null;
+      if (split.sets) setObj = Object.assign({}, split.sets);
+      if (split.unsets) {
+        if (!setObj) setObj = {};
+        Object.keys(split.unsets).forEach(function (k) { setObj[k] = null; });
+      }
+      if (setObj && Object.keys(setObj).length > 0) {
+        var qSet = db().from(name);
+        _applyQuery(qSet, query || {});
+        if (single) {
+          changed += (qSet.updateOne(setObj) ? 1 : 0);
+        } else {
+          changed += qSet.updateMany(setObj);
+        }
+      }
+
+      return changed;
+    },
+
+    // Convenience — `updateMany(query, update)` shorthand for
+    // `update(query, update, { many: true })`.
+    updateMany: function (query, update) {
+      return this.update(query, update, { many: true });
+    },
+
+    // Remove rows matching the query. Returns the number of rows
+    // deleted. Default deletes ONE row; pass `{ many: true }` to
+    // delete all matches (matches the framework's `deleteMany` rule
+    // — no unconditional deletes).
+    remove: function (query, opts) {
+      _validateQueryShape(query || {});
+      var q = db().from(name);
+      _applyQuery(q, query || {});
+      if (opts && opts.many === true) {
+        return q.deleteMany();
+      }
+      return q.deleteOne() ? 1 : 0;
+    },
+
+    // Count rows matching the query.
+    count: function (query) {
+      _validateQueryShape(query || {});
+      var q = db().from(name);
+      _applyQuery(q, query || {});
+      return q.count();
+    },
+
+    // Paginate — `{ items, total, limit, offset, page, totalPages }`.
+    // Composes Query.paginate.
+    paginate: function (query, opts) {
+      _validateQueryShape(query || {});
+      var q = db().from(name);
+      _applyQuery(q, query || {});
+      return q.paginate(opts || {});
+    },
+  };
+}
+
+module.exports = { collection: collection };