@blamejs/blamejs-shop 0.4.90 → 0.4.92

package/lib/vendor/blamejs/lib/log.js

@@ -360,6 +360,9 @@ function create(opts) {
       var store = { requestId: id || null, _extra: {} };
       return _als.run(store, fn);
     }
+    function enterRequestId(id) {
+      _als.enterWith({ requestId: id || null, _extra: {} });
+    }
     function runWithContext(ctx, fn) {
       var existing = _getStore();
       var rid = (ctx && ctx.requestId) || (existing && existing.requestId) || null;
@@ -417,6 +420,7 @@ function create(opts) {
       getLevel:         getLevel,
       isLevelEnabled:   level_in,
       runWithRequestId: runWithRequestId,
+      enterRequestId:   enterRequestId,
       runWithContext:   runWithContext,
       getRequestId:     getRequestId,
       middleware:       middleware,
@@ -639,6 +643,33 @@ function runWithRequestId(id, fn) {
   return _als.run({ requestId: id || null, _extra: {} }, fn);
 }
 
+/**
+ * @primitive b.log.enterRequestId
+ * @signature b.log.enterRequestId(id)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.log.runWithRequestId, b.log.getRequestId
+ *
+ * Bind `id` into the AsyncLocalStorage scope for the REMAINDER of the
+ * current async execution — without nesting a callback. Where
+ * `runWithRequestId(id, fn)` wraps a function (and the binding closes when
+ * `fn` returns), this uses `AsyncLocalStorage.enterWith` so the id survives a
+ * dispatch model that hands control back to its caller before the awaited
+ * work runs — a boolean-`next` middleware chain (`b.router`), where the route
+ * handler executes after the middleware returns. Call it once per request,
+ * inside the per-request async context, so each request stays isolated. The
+ * companion to `b.middleware.requestId({ asyncContext: true })`, which calls
+ * it for you.
+ *
+ * @example
+ *   // inside a per-request middleware, before next():
+ *   b.log.enterRequestId(req.requestId);
+ *   // any awaited handler downstream now sees b.log.getRequestId() === req.requestId
+ */
+function enterRequestId(id) {
+  _als.enterWith({ requestId: id || null, _extra: {} });
+}
+
 module.exports = {
   create:            create,
   boot:              boot,
@@ -649,4 +680,5 @@ module.exports = {
   // instance handy but still need to read ALS state.
   getRequestId:      getRequestId,
   runWithRequestId:  runWithRequestId,
+  enterRequestId:    enterRequestId,
 };

package/lib/vendor/blamejs/lib/middleware/rate-limit.js

@@ -448,6 +448,7 @@ function _resolveBackend(opts) {
  *     pruneIntervalMs: number,
  *     trustedProxies:  string|string[],  // CIDRs of your reverse proxies — peer-gates X-Forwarded-For for the IP key
  *     clientIpResolver: function(req): string|null,  // own the rate-limit key's client IP
+ *     ipKeyMode:       "exact"|"prefix64",  // default "exact"; "prefix64" keys IPv6 by its /64 (IPv4 stays exact) so one end-site can't rotate the low 64 bits to evade the limit
  *     trustProxy:      boolean|number,   // legacy; refused with the default IP key (spoofable) — use trustedProxies
  *   }
  *
@@ -465,7 +466,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "keyFn", "statusOnLimit", "bodyOnLimit", "onDeny", "problemDetails",
-    "header", "headerPrefix", "skipPaths", "scope",
+    "header", "headerPrefix", "skipPaths", "scope", "ipKeyMode",
     "backend", "trustProxy", "trustedProxies", "clientIpResolver", "algorithm",
     // memory backend (token-bucket)
     "burst", "refillPerSecond",
@@ -493,7 +494,22 @@ function create(opts) {
       "or set your own keyFn.");
   }
   var _clientIp = function (req) { return _ipResolver.resolve(req) || "unknown"; };
-  var keyFn = opts.keyFn || _clientIp;
+  // ipKeyMode "prefix64" collapses an IPv6 client to its routing-significant
+  // /64 for the DEFAULT key, so one end-site can't rotate the low 64 bits to
+  // mint unlimited fresh buckets and walk its per-IP limit (RFC 6177); IPv4
+  // stays exact. The audit actor still records the full resolved IP via
+  // _clientIp — only the rate-limit key is bucketed.
+  if (opts.ipKeyMode !== undefined && opts.ipKeyMode !== "exact" && opts.ipKeyMode !== "prefix64") {
+    throw new Error("middleware.rateLimit: ipKeyMode must be \"exact\" (default) or \"prefix64\"");
+  }
+  var _defaultKey = (opts.ipKeyMode === "prefix64")
+    ? function (req) {
+        var ip = _ipResolver.resolve(req);
+        if (!ip) return "unknown";
+        return requestHelpers.ipKey(ip, { ipv6Bits: 64 }) || ip;
+      }
+    : _clientIp;
+  var keyFn = opts.keyFn || _defaultKey;
   var statusOnLimit = opts.statusOnLimit || 429;
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";
   var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;

package/lib/vendor/blamejs/lib/middleware/request-id.js

@@ -8,6 +8,7 @@
 var C = require("../constants");
 var { generateToken } = require("../crypto");
 var validateOpts = require("../validate-opts");
+var log = require("../log");
 
 var DEFAULT_FORMAT = /^[A-Za-z0-9._-]{8,128}$/;
 // Hard cap on inbound header length. The DEFAULT_FORMAT regex caps at
@@ -33,30 +34,43 @@ var MAX_INBOUND_LEN = C.BYTES.bytes(256);
  * the chain — every later primitive expects `req.requestId` to
  * be present for log lines and audit-record metadata.
  *
+ * Pass `asyncContext: true` to additionally bind the id into the framework's
+ * AsyncLocalStorage scope so `b.log.getRequestId()` (and every
+ * `b.log.create`-built logger) returns it inside awaited route-handler code,
+ * not just on `req.requestId`. The `b.router` dispatch model is boolean-`next`
+ * — the route handler runs after this middleware returns — so the binding uses
+ * `AsyncLocalStorage.enterWith` (it persists forward through the awaited
+ * chain) rather than a callback wrap (which would close before the handler
+ * runs). Each request runs in its own async context, so the binding is
+ * request-scoped.
+ *
  * @opts
  *   {
  *     headerName:    string,    // default "X-Request-Id"
  *     trustUpstream: boolean,   // default true; false → always re-mint
  *     formatRegex:   RegExp,    // default /^[A-Za-z0-9._-]{8,128}$/
+ *     asyncContext:  boolean,   // default false; true → bind into b.log ALS for awaited handler code
  *   }
  *
  * @example
  *   var b = require("@blamejs/core");
  *   var app = b.router.create();
- *   app.use(b.middleware.requestId({ trustUpstream: true }));
- *   app.get("/health", function (req, res) {
- *     res.end(req.requestId);
+ *   app.use(b.middleware.requestId({ asyncContext: true }));
+ *   app.get("/health", async function (req, res) {
+ *     await somethingAsync();
+ *     res.end(b.log.getRequestId());   // → the request's id, even after await
  *   });
  */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "headerName", "trustUpstream", "formatRegex",
+    "headerName", "trustUpstream", "formatRegex", "asyncContext",
   ], "middleware.requestId");
   var headerName = (opts.headerName || "X-Request-Id");
   var headerNameLower = headerName.toLowerCase();
   var trustUpstream = opts.trustUpstream !== false;
   var format = opts.formatRegex || DEFAULT_FORMAT;
+  var asyncContext = opts.asyncContext === true;
 
   return function requestId(req, res, next) {
     var inbound = req.headers && req.headers[headerNameLower];
@@ -72,6 +86,12 @@ function create(opts) {
     if (typeof res.setHeader === "function") {
       res.setHeader(headerName, id);
     }
+    // Bind into the log ALS so awaited handler code reads the id via
+    // b.log.getRequestId(). enterWith (not run-with-callback) because the
+    // boolean-next dispatcher runs the handler after this returns.
+    if (asyncContext) {
+      log.enterRequestId(id);
+    }
     next();
   };
 }

package/lib/vendor/blamejs/lib/request-helpers.js

@@ -531,6 +531,55 @@ function ipPrefix(ip, opts) {
   return "";
 }
 
+/**
+ * @primitive b.requestHelpers.ipKey
+ * @signature b.requestHelpers.ipKey(ip, opts?)
+ * @since     0.15.21
+ * @related   b.requestHelpers.ipPrefix, b.requestHelpers.clientIp
+ *
+ * Derive a stable rate-limit / blocklist key from a client IP: the IPv4
+ * address <strong>verbatim</strong> (one IPv4 is one host) but the IPv6
+ * address collapsed to its routing-significant <code>/64</code> prefix. A
+ * single IPv6 end-site is allocated a whole <code>/64</code> (RFC 6177 / RFC
+ * 4291 §2.5.4) and freely rotates the low 64 bits, so keying on the full
+ * 128-bit address lets one site mint unlimited fresh keys — defeating a
+ * per-IP throttle and an exact-address block. Keying on the <code>/64</code>
+ * closes that while still distinguishing real end-sites. Unlike
+ * <code>ipPrefix</code> (which masks IPv4 to a <code>/24</code> pool), this
+ * keeps IPv4 exact — a rate limiter wants per-host IPv4 granularity.
+ *
+ * Returns the canonical key string, or <code>""</code> for a non-string /
+ * empty / unparseable input (caller falls back to its own bucket). An
+ * IPv4-mapped IPv6 address (<code>::ffff:1.2.3.4</code>) folds to its dotted
+ * IPv4 form so a client keys the same however a proxy reported it. Pass
+ * <code>opts.ipv6Bits</code> to override the IPv6 mask width (default 64).
+ *
+ * @opts
+ *   ipv6Bits: number,   // IPv6 mask width in bits (default 64; valid 0..128)
+ *
+ * @example
+ *   b.requestHelpers.ipKey("203.0.113.47");       // → "203.0.113.47" (exact)
+ *   b.requestHelpers.ipKey("2001:db8:1:2:dead:beef:0:1"); // → "2001:db8:1:2:0:0:0:0/64"
+ */
+function ipKey(ip, opts) {
+  if (typeof ip !== "string" || ip.length === 0) return "";
+  opts = opts || {};
+  var v6 = _resolvePrefixBits(opts.ipv6Bits, IPV6_DEFAULT_PREFIX, 128);                          // IPv6 max prefix length in bits
+  var lower = ip.toLowerCase();
+  // IPv4-mapped IPv6 (::ffff:1.2.3.4) → its exact dotted host, so a v4 client
+  // keys identically whether the proxy reported 1.2.3.4 or ::ffff:1.2.3.4.
+  if (lower.indexOf(V4_MAPPED_V6_PREFIX) === 0 && lower.indexOf(".") !== -1) {
+    var m4 = _maskIpv4(lower.substring(V4_MAPPED_V6_PREFIX.length), 32);                         // /32 = exact host
+    return m4 ? m4.replace(/\/32$/, "") : "";
+  }
+  if (ip.indexOf(":") !== -1) return _maskIpv6(ip, v6) || "";                                    // IPv6 → /ipv6Bits prefix
+  if (ip.indexOf(".") !== -1) {                                                                  // IPv4 → exact host, verbatim
+    var m = _maskIpv4(ip, 32);
+    return m ? m.replace(/\/32$/, "") : "";
+  }
+  return "";
+}
+
 /**
  * @primitive b.requestHelpers.trustedProtocol
  * @signature b.requestHelpers.trustedProtocol(opts?)
@@ -1307,6 +1356,7 @@ module.exports = {
   clientIp:                  clientIp,
   trustedClientIp:           trustedClientIp,
   ipPrefix:                  ipPrefix,
+  ipKey:                     ipKey,
   requestProtocol:           requestProtocol,
   trustedProtocol:           trustedProtocol,
   requestHost:               requestHost,

package/lib/vendor/blamejs/lib/safe-path.js

@@ -206,19 +206,33 @@ function _resolveCore(base, rel, opts) {
     }
   }
 
-  // Lexical resolve.
-  var baseResolved = nodePath.resolve(base);
-  var joined = nodePath.resolve(baseResolved, rel);
-  // Cross-check via posix.normalize so a Windows host with mixed
-  // separators still surfaces escapes consistently.
-  var sepChar = isWin ? "\\" : "/";
+  // Lexical resolve + containment using the TARGET platform's path semantics
+  // (nodePath.win32 / nodePath.posix), NOT the runtime's. The runtime nodePath
+  // would treat the OTHER platform's separator as an ordinary filename
+  // character — so a Windows-target validation on a POSIX host would NOT collapse
+  // `ok\..\..\outside` and would wrongly accept a path that escapes the base
+  // when later interpreted with Windows path rules (the cross-platform
+  // backslash-traversal hole). The target module collapses the target's
+  // separators + `..` and its sep matches the resolved output, which both closes
+  // that hole AND stops the inverse false-refusal of legitimate in-base paths.
+  var pathMod = isWin ? nodePath.win32 : nodePath.posix;
+  var baseResolved = pathMod.resolve(base);
+  var joined = pathMod.resolve(baseResolved, rel);
+  var sepChar = pathMod.sep;
   if (joined !== baseResolved && joined.slice(0, baseResolved.length + 1) !== baseResolved + sepChar) {
     _refuse("safe-path/escapes-base",
       "b.safePath.resolve: rel resolves outside base ('" + joined + "' not inside '" + baseResolved + "')");
   }
   if (opts.realpath === true) {
+    // realpath resolves symlinks on the RUNTIME filesystem, so it must use the
+    // runtime path module and runtime-resolved paths (a foreign-platform path
+    // can't be symlink-resolved on this host). The lexical check above already
+    // refused a cross-platform escape; this adds the on-disk symlink check.
+    var rtBaseResolved = nodePath.resolve(base);
+    var rtJoined = nodePath.resolve(rtBaseResolved, rel);
+    var rtSep = nodePath.sep;
     var baseRealpath;
-    try { baseRealpath = nodeFs.realpathSync.native(baseResolved); }
+    try { baseRealpath = nodeFs.realpathSync.native(rtBaseResolved); }
     catch (e) {
       _refuse("safe-path/realpath-base-unresolvable",
         "b.safePath.resolve: opts.realpath set but base realpath failed: " + (e && e.message));
@@ -227,12 +241,12 @@ function _resolveCore(base, rel, opts) {
     // ancestor that exists, and check its realpath. Operators want
     // refusal when ANY ancestor symlink escapes — nodeFs.realpathSync on a
     // non-existent path would throw.
-    var ancestor = joined;
-    while (ancestor.length > baseResolved.length) {
+    var ancestor = rtJoined;
+    while (ancestor.length > rtBaseResolved.length) {
       try {
         var ancRealpath = nodeFs.realpathSync.native(ancestor);
         if (ancRealpath !== baseRealpath &&
-            ancRealpath.slice(0, baseRealpath.length + 1) !== baseRealpath + sepChar) {
+            ancRealpath.slice(0, baseRealpath.length + 1) !== baseRealpath + rtSep) {
           _refuse("safe-path/realpath-escapes-base",
             "b.safePath.resolve: symlink resolution at '" + ancestor +
             "' escapes base realpath '" + baseRealpath + "'");

package/lib/vendor/blamejs/lib/sql.js

@@ -2041,6 +2041,45 @@ class UpdateBuilder extends Builder {
     this._where = new Predicate(this, "AND");
     this._returning = null;
     this._allowNoWhere = false;
+    // guardedUpdate() flips _requireGuard so _render refuses to emit a CAS
+    // statement that has no compare-and-swap fence (which would silently be a
+    // plain unconditional-on-state update). _guardCount tracks guardWhere calls.
+    this._requireGuard = false;
+    this._guardCount = 0;
+  }
+
+  // guardWhere(col, expected) - the compare-and-swap fence. ANDs
+  // `col = <expected>` (a bound ?) into the WHERE so the UPDATE lands ONLY if
+  // the row is STILL in the expected value - the cross-instance atomic claim
+  // (the transaction substitute on autocommit-only substrates: D1 over an HTTP
+  // bridge, any adapter without interactive transactions). An EXPLICIT
+  // `null` becomes `col IS NULL` (since `col = NULL` is never true) so a
+  // null-state fence works; `undefined` is REFUSED rather than silently
+  // collapsing to `IS NULL`, because an omitted/unset expected value would turn
+  // a CAS into "match the NULL-state rows" and update the wrong rows. The
+  // won/lost result is read from rowCount via b.sql.casWon.
+  guardWhere(col, expected) {
+    if (expected === undefined) {
+      throw _err("guardWhere expected value is undefined - pass an explicit null for an " +
+        "IS NULL fence, or a value; refusing to silently match NULL-state rows",
+        "sql-builder/bad-guard-value");
+    }
+    if (expected === null) {
+      this._where.whereNull(col);
+    } else {
+      this._where.whereOp(col, "=", expected);
+    }
+    this._guardCount += 1;
+    return this;
+  }
+
+  // guardWhereOp(col, op, expected) - a non-equality CAS fence (e.g. an
+  // optimistic-version `>=`, or a balance `>= amount` debit guard). Routes the
+  // operator through the same whereOp allowlist every other predicate uses.
+  guardWhereOp(col, op, expected) {
+    this._where.whereOp(col, op, expected);
+    this._guardCount += 1;
+    return this;
   }
 
   // set(obj) - column->value assignments. set(col, value) - single
@@ -2112,6 +2151,11 @@ class UpdateBuilder extends Builder {
 
   _render() {
     if (this._set.length === 0) throw _err("update requires a set(...) call", "sql-builder/empty-set");
+    if (this._requireGuard && this._guardCount === 0) {
+      throw _err("guardedUpdate requires at least one guardWhere(...) / guardWhereOp(...) " +
+        "compare-and-swap fence - without it this is a plain update; use b.sql.update for that",
+        "sql-builder/no-guard");
+    }
     if (this._where.length === 0 && !this._allowNoWhere) {
       throw _err("refusing unconditional update - call where(...) first or allowNoWhere()",
         "sql-builder/no-where");
@@ -3896,6 +3940,93 @@ function insertSelectWhere(tableNameOrRef, opts) { return new InsertSelectWhereB
  */
 function update(tableNameOrRef, opts) { return new UpdateBuilder(tableNameOrRef, opts); }
 
+/**
+ * @primitive  b.sql.guardedUpdate
+ * @signature  b.sql.guardedUpdate(table, opts?)
+ * @since      0.15.21
+ * @status     stable
+ * @related    b.sql.update, b.sql.insertSelectWhere, b.sql.casWon
+ *
+ * Start a compare-and-swap `UPDATE` builder - the cross-instance-safe way to
+ * advance a status / version on a single-statement-per-request backend (D1
+ * over an HTTP bridge, or any autocommit-only adapter without interactive
+ * transactions). It is `b.sql.update` plus a required `guardWhere(col,
+ * expected)` fence: the statement lands ONLY when the row is STILL in the
+ * expected value, so two racing transitions cannot both win. Refuses to
+ * render without at least one `guardWhere(...)` / `guardWhereOp(...)` - an
+ * unfenced one would just be a plain update.
+ *
+ * Read the winner from the result's `rowCount` with `b.sql.casWon(result)`:
+ * exactly one row matched (`won: true`) means this caller made the
+ * transition; zero (`won: false`) means it lost the race and must no-op /
+ * refuse. The sibling of `b.sql.insertSelectWhere` (the conditional-INSERT
+ * debit) for the conditional-UPDATE case, and the b.fsm composition partner
+ * (resolve the destination side-effect-free with `instance.target(event)`,
+ * then guard on the from-state here).
+ *
+ * @opts
+ *   dialect:         string,   // postgres | sqlite | mysql (default sqlite)
+ *   schema:          string,   // schema qualifier
+ *   prefix:          string,   // operator app-table namespace prefix
+ *   allowedColumns:  array,    // column-membership gate set
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   // advance order id=7 from "paid" -> "shipped" iff still "paid"
+ *   var q = b.sql.guardedUpdate("orders")
+ *     .set({ status: "shipped" })
+ *     .where("id", 7)
+ *     .guardWhere("status", "paid")
+ *     .toSql();
+ *   // -> { sql: 'UPDATE orders SET "status" = ? WHERE "id" = ? AND "status" = ?',
+ *   //      params: ["shipped", 7, "paid"] }
+ *   // var res = await b.db.raw(q.sql, q.params);
+ *   // if (!b.sql.casWon(res).won) { return refuse(); }   // lost the race
+ */
+function guardedUpdate(tableNameOrRef, opts) {
+  var builder = new UpdateBuilder(tableNameOrRef, opts);
+  builder._requireGuard = true;
+  return builder;
+}
+
+/**
+ * @primitive  b.sql.casWon
+ * @signature  b.sql.casWon(result)
+ * @since      0.15.21
+ * @status     stable
+ * @related    b.sql.guardedUpdate, b.sql.insertSelectWhere
+ *
+ * Interpret a compare-and-swap result's affected-row count into a won/lost
+ * verdict, owning the `Number(rowCount) === 1` check and the cross-adapter
+ * field-name divergence (`b.db` / `b.externalDb` normalize to `rowCount`; raw
+ * sqlite reports `changes`, raw mysql `affectedRows` / `rowsAffected`).
+ * Returns `{ won, rowCount }` where `won` is true only when exactly one row
+ * was affected. Throws when the result carries no recognizable numeric
+ * row-count field - an indeterminate result must surface, never be silently
+ * read as a win (a phantom win on a CAS is a double-spend).
+ *
+ * @example
+ *   var v = b.sql.casWon(await b.db.raw(q.sql, q.params));
+ *   if (v.won) { applyTransition(); } else { refuseLostRace(v.rowCount); }
+ */
+function casWon(result) {
+  if (!result || typeof result !== "object") {
+    throw _err("casWon: result must be the object returned by the query runner",
+      "sql-builder/bad-cas-result");
+  }
+  var count = null;
+  var fields = ["rowCount", "changes", "affectedRows", "rowsAffected"];
+  for (var i = 0; i < fields.length; i += 1) {
+    var v = result[fields[i]];
+    if (typeof v === "number" && isFinite(v)) { count = v; break; }
+  }
+  if (count === null) {
+    throw _err("casWon: result has no numeric rowCount / changes / affectedRows field - " +
+      "cannot determine the compare-and-swap outcome", "sql-builder/no-row-count");
+  }
+  return { won: count === 1, rowCount: count };
+}
+
 /**
  * @primitive  b.sql.delete
  * @signature  b.sql.delete(table, opts?)
@@ -3976,6 +4107,8 @@ module.exports = {
   insert:        insert,
   insertSelectWhere: insertSelectWhere,
   update:        update,
+  guardedUpdate: guardedUpdate,
+  casWon:        casWon,
   delete:        del,
   upsert:        upsert,
   // Table reference

package/lib/vendor/blamejs/lib/totp.js

@@ -7,16 +7,28 @@
  * posture. SHA-256 is supported as backward-compatible opt-in for
  * deployments whose authenticator app only goes that high.
  *
- * SHA-1 is NOT supported — explicitly rejected at compute(). Most
- * authenticator apps still default to SHA-1 for legacy reasons (it's
- * what RFC 6238 prescribes as the default), but the major modern apps
- * (Authy, 1Password, Bitwarden, Microsoft Authenticator, Aegis) all
- * support SHA-512 when the otpauth URI declares it via the
- * `algorithm` parameter. Operators selecting authenticator apps
- * should verify SHA-512 support — Google Authenticator's older
- * versions and minimal hardware tokens may not. A clear "reject SHA-1
- * and surface" stance is preferable to a silent SHA-1 default that
- * undermines the framework's algorithm posture.
+ * SHA-1 is NOT supported for generation — explicitly rejected at
+ * compute() / generate() / uri(). Most authenticator apps still default
+ * to SHA-1 for legacy reasons (it's what RFC 6238 prescribes as the
+ * default), but the major modern apps (Authy, 1Password, Bitwarden,
+ * Microsoft Authenticator, Aegis) all support SHA-512 when the otpauth
+ * URI declares it via the `algorithm` parameter. Operators selecting
+ * authenticator apps should verify SHA-512 support — Google
+ * Authenticator's older versions and minimal hardware tokens may not. A
+ * clear "reject SHA-1 and surface" stance is preferable to a silent
+ * SHA-1 default that undermines the framework's algorithm posture.
+ *
+ * One verify-only exception exists for migration: a consumer holding
+ * pre-existing RFC-6238-default secrets (SHA-1) can verify a single
+ * legacy code during a re-enrollment flow with
+ * `verify(secret, code, { algorithm: "sha1", verifyOnly: true })`. This
+ * widens nothing on the generation side — compute()/generate()/uri()
+ * still refuse SHA-1, so new-enrollment posture stays SHA-512-only — it
+ * only lets the maintained verifier (separator stripping, 64-bit
+ * counter, drift/replay semantics) authenticate the final legacy login
+ * instead of forcing the consumer to hand-roll a parallel HOTP. Each
+ * such verification emits an `auth.totp.legacy_sha1_verify` audit signal
+ * so a compliance dashboard sees the migration traffic.
  *
  * Public API:
  *
@@ -24,6 +36,9 @@
  *   totp.generate(secret, opts?)          → string (current code)
  *   totp.compute(secret, timeStep, opts?) → string (code at specific step)
  *   totp.verify(secret, code, opts?)      → step | false
+ *                                           (opts.verifyOnly + opts.algorithm
+ *                                            "sha1" accepts a legacy secret;
+ *                                            see the SHA-1 note above)
  *   totp.uri(secret, account, opts)       → string (otpauth://…)
  *   totp.generateBackupCodes(opts?)       → string[]
  *
@@ -77,6 +92,13 @@ var DEFAULT_DRIFT_STEPS  = 1;
 // docstring for the rationale.
 var DEFAULT_ALGORITHM    = "sha512";
 var SUPPORTED_ALGORITHMS = Object.freeze(["sha256", "sha512"]);
+// Algorithms accepted ONLY on the verify() path, and only when the caller
+// explicitly passes { verifyOnly: true } — never by compute()/generate()/
+// uri(). SHA-1 is RFC 6238's default and the algorithm pre-existing secrets
+// were provisioned with; this lets a consumer authenticate a final legacy
+// code during re-enrollment without hand-rolling a parallel HOTP, while
+// keeping new-enrollment generation SHA-512-only.
+var VERIFY_ONLY_ALGORITHMS = Object.freeze(["sha1"]);
 // Default secret length matches the HMAC-SHA512 block size (1024 bits).
 // MIN_SECRET_BYTES is RFC 4226 §4's hard floor — operators can opt down
 // to it for QR provisioning into apps that balk at long secrets, but no
@@ -106,28 +128,51 @@ function _base32Decode(str) {
 
 // ---- Core HOTP (RFC 4226 §5.3) ----
 
-function _resolveOpts(opts) {
+function _emitTotpAudit(action, alg) {
+  setImmediate(function () {
+    try {
+      var auditMod = require("./audit");                                            // allow:inline-require — circular-load defense
+      auditMod.safeEmit({
+        action:   action,
+        outcome:  "success",
+        metadata: { algorithm: alg, frameworkDefault: DEFAULT_ALGORITHM },
+      });
+    } catch (_e) { /* drop-silent */ }
+  });
+}
+
+// ctx.allowVerifyOnly is set ONLY by verify() — it is the single gate that
+// lets a verify-only legacy algorithm (SHA-1) through, and even then only
+// when the caller also passes opts.verifyOnly:true. compute()/generate()/
+// uri() call _resolveOpts with no ctx, so SHA-1 can never reach the
+// generation path regardless of opts.
+function _resolveOpts(opts, ctx) {
   opts = opts || {};
+  var allowVerifyOnly = !!(ctx && ctx.allowVerifyOnly);
   var alg = (opts.algorithm || DEFAULT_ALGORITHM).toLowerCase();
+  var verifyOnly = false;
   if (SUPPORTED_ALGORITHMS.indexOf(alg) === -1) {
-    throw new AuthError("auth-totp/bad-alg",
-      "algorithm must be one of " + SUPPORTED_ALGORITHMS.join(", ") + " (got: " + alg + ")");
+    if (allowVerifyOnly && opts.verifyOnly === true && VERIFY_ONLY_ALGORITHMS.indexOf(alg) !== -1) {
+      // Legacy-secret verification path — accepted, but flagged so the
+      // HOTP core knows this is a one-final-login migration verify and the
+      // audit trail records it.
+      verifyOnly = true;
+    } else {
+      throw new AuthError("auth-totp/bad-alg",
+        "algorithm must be one of " + SUPPORTED_ALGORITHMS.join(", ") + " (got: " + alg + ")" +
+        (VERIFY_ONLY_ALGORITHMS.indexOf(alg) !== -1
+          ? "; " + alg + " is accepted only by verify() with { verifyOnly: true }"
+          : ""));
+    }
   }
   // SHA-256 is supported for back-compat with authenticator apps that
-  // don't yet honor SHA-512. Emit an audit signal each time it's
-  // selected so operator compliance dashboards see which accounts run
-  // on the weaker hash and can plan the migration.
+  // don't yet honor SHA-512. Emit an audit signal when it's selected so
+  // operator compliance dashboards see which accounts run on the weaker
+  // hash and can plan the migration; SHA-1 verify-only gets its own signal.
   if (alg === "sha256") {
-    setImmediate(function () {
-      try {
-        var auditMod = require("./audit");                                          // allow:inline-require — circular-load defense
-        auditMod.safeEmit({
-          action:   "auth.totp.algorithm_downgraded",
-          outcome:  "success",
-          metadata: { algorithm: alg, frameworkDefault: DEFAULT_ALGORITHM },
-        });
-      } catch (_e) { /* drop-silent */ }
-    });
+    _emitTotpAudit("auth.totp.algorithm_downgraded", alg);
+  } else if (verifyOnly) {
+    _emitTotpAudit("auth.totp.legacy_sha1_verify", alg);
   }
   var digits = opts.digits != null ? opts.digits : DEFAULT_DIGITS;
   if (typeof digits !== "number" || digits < 6 || digits > 10) {
@@ -141,7 +186,10 @@ function _resolveOpts(opts) {
   if (typeof driftSteps !== "number" || driftSteps < 0) {
     throw new AuthError("auth-totp/bad-drift", "driftSteps must be >= 0 (got: " + driftSteps + ")");
   }
-  return { algorithm: alg, digits: digits, stepSeconds: stepSeconds, driftSteps: driftSteps };
+  return {
+    algorithm: alg, digits: digits, stepSeconds: stepSeconds,
+    driftSteps: driftSteps, verifyOnly: verifyOnly,
+  };
 }
 
 function _validateSecret(secret) {
@@ -150,10 +198,11 @@ function _validateSecret(secret) {
   }
 }
 
-// HOTP truncation per RFC 4226 §5.3 — produces digit-string code.
-function compute(secret, timeStep, opts) {
-  _validateSecret(secret);
-  var resolved = _resolveOpts(opts);
+// HOTP truncation per RFC 4226 §5.3 — produces a digit-string code from an
+// ALREADY-RESOLVED opts object. Split out from compute() so verify() can run
+// it with a verify-resolved algorithm (including the verify-only SHA-1 path)
+// without going back through compute()'s resolver, which always refuses SHA-1.
+function _hotp(secret, timeStep, resolved) {
   var key = _base32Decode(secret);
   if (key.length === 0) {
     throw new AuthError("auth-totp/bad-secret", "secret decoded to zero bytes");
@@ -177,6 +226,13 @@ function compute(secret, timeStep, opts) {
   return String(binCode % modulus).padStart(resolved.digits, "0");
 }
 
+// Public generation path — always refuses SHA-1 (no verify-only ctx).
+function compute(secret, timeStep, opts) {
+  _validateSecret(secret);
+  var resolved = _resolveOpts(opts);
+  return _hotp(secret, timeStep, resolved);
+}
+
 // ---- Public API ----
 
 function generateSecret(opts) {
@@ -203,7 +259,11 @@ function verify(secret, code, opts) {
   // catching exceptions per call.
   if (typeof secret !== "string" || secret.length === 0) return false;
   if (code == null) return false;
-  var resolved = _resolveOpts(opts);
+  // verify() is the single path that may accept a verify-only legacy
+  // algorithm (SHA-1) — gated on opts.verifyOnly inside _resolveOpts. A
+  // genuinely-bad algorithm/digits/step/drift still throws (a misconfigured
+  // verifier must surface, not silently read as "didn't match").
+  var resolved = _resolveOpts(opts, { allowVerifyOnly: true });
   var nowMs = (opts && opts.now) || Date.now();
   var currentStep = Math.floor(nowMs / 1000 / resolved.stepSeconds);
   var lastUsedStep = (opts && typeof opts.lastUsedStep === "number") ? opts.lastUsedStep : null;
@@ -224,7 +284,11 @@ function verify(secret, code, opts) {
     var step = currentStep + d;
     if (lastUsedStep !== null && step <= lastUsedStep) continue;     // reject replays at-or-below the last accepted step
     var expected;
-    try { expected = compute(secret, step, opts); }
+    // Run the HOTP core with the verify-resolved algorithm directly — going
+    // back through compute() would re-resolve and refuse the verify-only
+    // SHA-1 path. Resolution already happened once above (no per-step audit
+    // spam, and the legacy-verify audit fires exactly once per verify()).
+    try { expected = _hotp(secret, step, resolved); }
     catch (_e) { return false; }
     var expectedBuf = Buffer.from(expected);
     if (timingSafeEqual(expectedBuf, userBuf)) {
@@ -294,4 +358,5 @@ module.exports = {
   DEFAULT_SECRET_BYTES:  DEFAULT_SECRET_BYTES,
   MIN_SECRET_BYTES:      MIN_SECRET_BYTES,
   SUPPORTED_ALGORITHMS:  SUPPORTED_ALGORITHMS,
+  VERIFY_ONLY_ALGORITHMS: VERIFY_ONLY_ALGORITHMS,
 };