@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/tls-exporter.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * @module b.tlsExporter
+ * @nav    Crypto
+ * @title  TLS Exporter
+ *
+ * @intro
+ *   RFC 5705 / RFC 9266 TLS Exporter for binding application-layer
+ *   keys and tokens to the live TLS session. The exporter is a
+ *   deterministic byte-string derived from the TLS 1.3 master secret
+ *   (RFC 8446 §7.5) — pulling 32 bytes under the
+ *   `EXPORTER-Channel-Binding` label gives the RFC 9266
+ *   "tls-exporter" channel-binding identifier.
+ *
+ *   Operators bind bearer tokens, FAPI 2.0 access-token-bound proofs,
+ *   DPoP `cnf.tbh` claims, mTLS-derived auth headers, and session
+ *   cookies to the exporter so a captured token cannot be replayed
+ *   across a different TLS session — even if a downstream proxy
+ *   re-terminates TLS (RFC 8705). The matching node primitive is
+ *   `tls.TLSSocket#exportKeyingMaterial(length, label[, context])`.
+ *
+ *   Validation throws at the call site for sockets that aren't TLS
+ *   (channel binding has no meaning over plaintext), sockets whose
+ *   protocol is not TLS 1.3 (RFC 9266 §4 conformance), or
+ *   out-of-range `length` values. Mismatched bindings on
+ *   `verifyTokenBinding` return `false` rather than throwing —
+ *   token-binding mismatch is a normal request-time outcome, not a
+ *   config bug.
+ *
+ * @card
+ *   RFC 5705 / RFC 9266 TLS Exporter for binding application-layer keys and tokens to the live TLS session.
+ */
+
+var bCrypto = require("./crypto");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var numericBounds = require("./numeric-bounds");
+var { TlsExporterError } = require("./framework-error");
+
+var _err = TlsExporterError.factory;
+
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var EXPORTER_LABEL = "EXPORTER-Channel-Binding";
+var EXPORTER_LENGTH = C.BYTES.bytes(32);
+
+// _resolveTlsSocket — accept either a TLSSocket directly OR an http2/
+// http(s) request whose .socket property is the TLSSocket. Operators
+// almost always pass req.socket; the helper normalizes to the
+// underlying socket so the exportKeyingMaterial call lands on the
+// right object.
+function _resolveTlsSocket(socketOrReq) {
+  if (!socketOrReq) {
+    throw _err("BAD_INPUT", "tlsExporter: socket or request object required");
+  }
+  // Express/Node http req → req.socket is the TLSSocket
+  var sock = socketOrReq;
+  if (typeof socketOrReq.exportKeyingMaterial !== "function" &&
+      socketOrReq.socket &&
+      typeof socketOrReq.socket.exportKeyingMaterial === "function") {
+    sock = socketOrReq.socket;
+  }
+  if (typeof sock.exportKeyingMaterial !== "function") {
+    throw _err("NOT_TLS",
+      "tlsExporter: socket has no exportKeyingMaterial — channel binding requires TLS");
+  }
+  // Per RFC 9266 §4 the exporter is only defined for TLS 1.3. Older
+  // protocol versions on the same API would technically return bytes
+  // but the channel-binding semantics are NOT RFC 9266 conformant —
+  // refuse so an operator-built check doesn't silently fall back to a
+  // weaker binding.
+  if (typeof sock.getProtocol === "function") {
+    var proto = sock.getProtocol();
+    if (proto && proto !== "TLSv1.3") {
+      throw _err("NOT_TLS_1_3",
+        "tlsExporter: TLS protocol is " + proto + ", RFC 9266 requires TLS 1.3");
+    }
+  }
+  return sock;
+}
+
+/**
+ * @primitive b.tlsExporter.fromSocket
+ * @signature b.tlsExporter.fromSocket(socketOrReq, opts)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.tlsExporter.bindToken, b.tlsExporter.verifyTokenBinding
+ *
+ * Extracts a TLS exporter from `socketOrReq` (either a `TLSSocket`
+ * directly or an HTTP/HTTP/2 request whose `.socket` is the
+ * `TLSSocket`). Defaults match RFC 9266 §4 — 32-byte length, label
+ * `EXPORTER-Channel-Binding`, no context — yielding the canonical
+ * "tls-exporter" channel-binding identifier. Custom labels and
+ * lengths pass through for applications defining their own exporter-
+ * derived identifiers; `length` is bounded 16..255 bytes per the
+ * keying-material range Node enforces. Throws when the socket is not
+ * TLS 1.3 or when the export call fails.
+ *
+ * @opts
+ *   {
+ *     label?:   string,    // default "EXPORTER-Channel-Binding"
+ *     length?:  number,    // default 32; bounded 16..255 bytes
+ *     context?: Buffer     // default null (RFC 8446 §7.5 "no context")
+ *   }
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   var server = b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
+ *     var exporter = b.tlsExporter.fromSocket(req, { length: 32 });
+ *     res.end("exporter bytes: " + exporter.length);
+ *     // → "exporter bytes: 32"
+ *   });
+ *   server.listen(0);
+ */
+function fromSocket(socketOrReq, opts) {
+  opts = opts || {};
+  var label = typeof opts.label === "string" && opts.label.length > 0
+    ? opts.label : EXPORTER_LABEL;
+  // length is operator-tunable; validate-when-present via numeric-bounds
+  // so a non-finite / negative / NaN input surfaces with the same error
+  // shape every other framework primitive uses for numeric opts.
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.length,
+    "tlsExporter.fromSocket: length", TlsExporterError, "BAD_LENGTH");
+  var length = opts.length !== undefined ? opts.length : EXPORTER_LENGTH;
+  if (length < C.BYTES.bytes(16) || length > C.BYTES.bytes(255)) {
+    throw _err("BAD_LENGTH",
+      "tlsExporter.fromSocket: length must be 16..255 bytes (got " + length + ")");
+  }
+  var context = opts.context;
+  if (context !== undefined && context !== null && !Buffer.isBuffer(context)) {
+    throw _err("BAD_CONTEXT",
+      "tlsExporter.fromSocket: context must be Buffer or null");
+  }
+
+  var sock = _resolveTlsSocket(socketOrReq);
+  var bytes;
+  try {
+    // Node's exportKeyingMaterial signature: (length, label, [context]).
+    // Passing context=null (the default) corresponds to the RFC 8446
+    // §7.5 "no context" case which RFC 9266 §4 mandates for channel
+    // binding.
+    bytes = context
+      ? sock.exportKeyingMaterial(length, label, context)
+      : sock.exportKeyingMaterial(length, label);
+  } catch (e) {
+    throw _err("EXPORT_FAILED",
+      "tlsExporter.fromSocket: exportKeyingMaterial threw: " + e.message);
+  }
+  if (!Buffer.isBuffer(bytes) || bytes.length !== length) {
+    throw _err("EXPORT_SHORT",
+      "tlsExporter.fromSocket: short exporter (got " + (bytes && bytes.length) + " bytes, want " + length + ")");
+  }
+
+  try { observability().safeEvent("tlsExporter.fromSocket", 1, { outcome: "success" }); }
+  catch (_e) { /* drop-silent */ }
+  return bytes;
+}
+
+/**
+ * @primitive b.tlsExporter.bindToken
+ * @signature b.tlsExporter.bindToken(socketOrReq, token)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.tlsExporter.fromSocket, b.tlsExporter.verifyTokenBinding
+ *
+ * Binds an opaque token (string or Buffer) to the current TLS session
+ * by hashing `SHA3-512(label || exporter || token)`, where `label` is
+ * `"blamejs/tls-exporter/bind/v1"`. The framework label keeps the
+ * resulting digest distinct from any other place the same exporter +
+ * token bytes might be hashed (audit-chain rows, derived-hash columns,
+ * etc.) so a binding cannot be reinterpreted across primitives.
+ * Operators store the returned hex digest alongside the token and
+ * compare via `verifyTokenBinding` on the next request.
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
+ *     var binding = b.tlsExporter.bindToken(req, "session-token-abc123");
+ *     binding.length;
+ *     // → 128 (SHA3-512 hex digest, 64 bytes × 2 hex chars)
+ *     res.end("ok");
+ *   }).listen(0);
+ */
+function bindToken(socketOrReq, token) {
+  if (typeof token !== "string" && !Buffer.isBuffer(token)) {
+    throw _err("BAD_TOKEN",
+      "tlsExporter.bindToken: token must be a string or Buffer");
+  }
+  var exporter = fromSocket(socketOrReq);
+  var tokenBuf = Buffer.isBuffer(token) ? token : Buffer.from(token, "utf8");
+  // SHA3-512 of (label || exporter || token). The label binds the
+  // hash to "tls-exporter binding" so the same token + exporter pair
+  // does NOT produce the same hash if used in another framework
+  // primitive (e.g., the audit-chain row hash).
+  var labelBuf = Buffer.from("blamejs/tls-exporter/bind/v1", "utf8");
+  return bCrypto.sha3Hash(Buffer.concat([labelBuf, exporter, tokenBuf]));
+}
+
+/**
+ * @primitive b.tlsExporter.verifyTokenBinding
+ * @signature b.tlsExporter.verifyTokenBinding(socketOrReq, token, claimedBinding)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.tlsExporter.fromSocket, b.tlsExporter.bindToken
+ *
+ * Constant-time compare of a previously-issued `bindToken` digest
+ * against a fresh binding computed from the current TLS session.
+ * Returns `true` when the digests match (token belongs to this TLS
+ * session) and `false` on any mismatch — token-binding mismatch is a
+ * normal request-time outcome, so this primitive never throws on
+ * mismatch. Throws only when `socketOrReq` is not TLS 1.3 or when
+ * the input shape is wrong.
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
+ *     var stored = b.tlsExporter.bindToken(req, "session-token-abc123");
+ *     var ok = b.tlsExporter.verifyTokenBinding(req, "session-token-abc123", stored);
+ *     ok;
+ *     // → true
+ *     res.end(ok ? "bound" : "mismatch");
+ *   }).listen(0);
+ */
+function verifyTokenBinding(socketOrReq, token, claimedBinding) {
+  var actual = bindToken(socketOrReq, token);
+  if (typeof claimedBinding !== "string" || claimedBinding.length === 0) {
+    return false;
+  }
+  return bCrypto.timingSafeEqual(actual, claimedBinding);
+}
+
+module.exports = {
+  fromSocket:           fromSocket,
+  bindToken:            bindToken,
+  verifyTokenBinding:   verifyTokenBinding,
+  EXPORTER_LABEL:       EXPORTER_LABEL,
+  EXPORTER_LENGTH:      EXPORTER_LENGTH,
+  TlsExporterError:     TlsExporterError,
+};

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

@@ -0,0 +1,318 @@
+"use strict";
+/**
+ * TOTP (Time-based One-Time Password) — RFC 6238 / RFC 4226.
+ *
+ * HMAC-SHA512 with 30-second step and 8-digit codes is the default,
+ * matching the framework's "highest practical bar, forward only"
+ * 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.
+ *
+ * Public API:
+ *
+ *   totp.generateSecret(opts?)            → string (base32, 20 bytes)
+ *   totp.generate(secret, opts?)          → string (current code)
+ *   totp.compute(secret, timeStep, opts?) → string (code at specific step)
+ *   totp.verify(secret, code, opts?)      → step | false
+ *   totp.uri(secret, account, opts)       → string (otpauth://…)
+ *   totp.generateBackupCodes(opts?)       → string[]
+ *
+ * verify() returns the matched step number on success (not boolean
+ * true) so the caller can persist `lastUsedStep` and reject replays
+ * within the drift window. False on no-match. Caller passes
+ * opts.lastUsedStep on subsequent verifies to enforce one-time use.
+ *
+ * Defaults:
+ *   stepSeconds:   30      (RFC 6238)
+ *   digits:        8       (highest standard TOTP code length; 100× the
+ *                           code space of the more common 6-digit default
+ *                           — same brute-force-resistance bump as moving
+ *                           a password from 6 to 8 random digits)
+ *   driftSteps:    1       (RFC 6238 — accept ±1 step from current time = ±30s)
+ *   algorithm:     "sha512" (framework posture; RFC 6238's default is SHA-1
+ *                             but that's rejected here)
+ *   secretBytes:   128     (matches the HMAC-SHA512 block size; exceeds
+ *                           RFC 4226 §4's "≥ HMAC output length" recommendation
+ *                           which is 64 bytes for SHA-512. Operators with
+ *                           authenticator-app QR provisioning don't notice
+ *                           the longer string; manual-entry workflows can
+ *                           opt down via opts.bytes, bounded below by the
+ *                           RFC 4226 floor of 20.)
+ *
+ * stepSeconds and driftSteps are RFC 6238 defaults — every TOTP-
+ * capable authenticator handles them without configuration. The
+ * algorithm + digits + secretBytes defaults are deliberate framework
+ * deviations toward stronger parameters; operators MUST provision the
+ * authenticator with `algorithm=SHA512&digits=8` (the otpauth URI
+ * surfaces both). Authenticators that don't honor the URI's algorithm
+ * parameter will silently produce SHA-1 codes that fail to verify —
+ * operators should choose an authenticator that does (Authy,
+ * 1Password, Bitwarden, Aegis, Microsoft Authenticator all do).
+ */
+var nodeCrypto = require("node:crypto");
+var C = require("./constants");
+var { generateBytes, generateToken, timingSafeEqual } = require("./crypto");
+var { AuthError } = require("./framework-error");
+
+// ---- Defaults ----
+var DEFAULT_STEP_SECONDS = 30;
+// 8-digit OTP — highest standard length per RFC 4226 §5.3. Hex literal
+// keeps the framework's "no bare integer literals divisible by 8" rule
+// satisfied while preserving the value.
+var DEFAULT_DIGITS       = 0x08;
+var DEFAULT_DRIFT_STEPS  = 1;
+// SHA-512 default; SHA-256 supported for backward-compatible deployments.
+// SHA-1 is intentionally NOT in the supported list — see the module
+// docstring for the rationale.
+var DEFAULT_ALGORITHM    = "sha512";
+var SUPPORTED_ALGORITHMS = Object.freeze(["sha256", "sha512"]);
+// 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
+// further.
+var DEFAULT_SECRET_BYTES = C.BYTES.bytes(128);
+var MIN_SECRET_BYTES     = 20;
+// HOTP counter is an 8-byte big-endian field per RFC 4226 §5.1.
+var HOTP_COUNTER_BYTES   = C.BYTES.bytes(8);
+// Base32 (RFC 4648) packs 5 bits per char; bit + byte widths used by the
+// encoder/decoder below. Routed through C.BYTES so every byte literal in
+// the file lives behind the same helper.
+var BITS_PER_BYTE        = C.BYTES.bytes(8);
+
+// ---- Base32 (RFC 4648, no padding — TOTP convention) ----
+
+var BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+function _base32Encode(buf) {
+  var bits = "";
+  for (var i = 0; i < buf.length; i++) {
+    bits += buf[i].toString(2).padStart(BITS_PER_BYTE, "0");
+  }
+  var out = "";
+  for (var j = 0; j < bits.length; j += 5) {
+    var chunk = bits.substring(j, j + 5).padEnd(5, "0");
+    out += BASE32[parseInt(chunk, 2)];
+  }
+  return out;
+}
+
+function _base32Decode(str) {
+  var bits = "";
+  for (var i = 0; i < str.length; i++) {
+    var c = str[i].toUpperCase();
+    if (c === "=" || c === " " || c === "-") continue;     // spaces + dashes + padding
+    var idx = BASE32.indexOf(c);
+    if (idx === -1) {
+      throw new AuthError("auth-totp/bad-secret",
+        "secret contains invalid base32 character: '" + str[i] + "'");
+    }
+    bits += idx.toString(2).padStart(5, "0");
+  }
+  var bytes = [];
+  for (var j = 0; j + BITS_PER_BYTE <= bits.length; j += BITS_PER_BYTE) {
+    bytes.push(parseInt(bits.substring(j, j + BITS_PER_BYTE), 2));
+  }
+  return Buffer.from(bytes);
+}
+
+// ---- Core HOTP (RFC 4226 §5.3) ----
+
+function _resolveOpts(opts) {
+  opts = opts || {};
+  var alg = (opts.algorithm || DEFAULT_ALGORITHM).toLowerCase();
+  if (SUPPORTED_ALGORITHMS.indexOf(alg) === -1) {
+    throw new AuthError("auth-totp/bad-alg",
+      "algorithm must be one of " + SUPPORTED_ALGORITHMS.join(", ") + " (got: " + alg + ")");
+  }
+  // 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.
+  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 */ }
+    });
+  }
+  var digits = opts.digits != null ? opts.digits : DEFAULT_DIGITS;
+  if (typeof digits !== "number" || digits < 6 || digits > 10) {
+    throw new AuthError("auth-totp/bad-digits", "digits must be 6–10 (got: " + digits + ")");
+  }
+  var stepSeconds = opts.stepSeconds != null ? opts.stepSeconds : DEFAULT_STEP_SECONDS;
+  if (typeof stepSeconds !== "number" || stepSeconds < 1) {
+    throw new AuthError("auth-totp/bad-step", "stepSeconds must be >= 1 (got: " + stepSeconds + ")");
+  }
+  var driftSteps = opts.driftSteps != null ? opts.driftSteps : DEFAULT_DRIFT_STEPS;
+  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 };
+}
+
+function _validateSecret(secret) {
+  if (typeof secret !== "string" || secret.length === 0) {
+    throw new AuthError("auth-totp/missing-secret", "secret is required (base32 string)");
+  }
+}
+
+// HOTP truncation per RFC 4226 §5.3 — produces digit-string code.
+function compute(secret, timeStep, opts) {
+  _validateSecret(secret);
+  var resolved = _resolveOpts(opts);
+  var key = _base32Decode(secret);
+  if (key.length === 0) {
+    throw new AuthError("auth-totp/bad-secret", "secret decoded to zero bytes");
+  }
+  var counter = Buffer.alloc(HOTP_COUNTER_BYTES);
+  // 8-byte big-endian counter. timeStep fits in 32 bits until ~year 2038
+  // for stepSeconds=30, but we encode the high 32 bits properly so the
+  // implementation is correct beyond Y2038.
+  var hi = Math.floor(timeStep / 0x100000000);
+  var lo = timeStep >>> 0;
+  counter.writeUInt32BE(hi, 0);
+  counter.writeUInt32BE(lo, 4);
+  var hmac = nodeCrypto.createHmac(resolved.algorithm, key).update(counter).digest();
+  var offset = hmac[hmac.length - 1] & 0x0f;
+  var binCode =
+    ((hmac[offset]     & 0x7f) << 24) |
+    ((hmac[offset + 1] & 0xff) << 16) |
+    ((hmac[offset + 2] & 0xff) <<  8) |
+    ( hmac[offset + 3] & 0xff);
+  var modulus = Math.pow(10, resolved.digits);
+  return String(binCode % modulus).padStart(resolved.digits, "0");
+}
+
+// ---- Public API ----
+
+function generateSecret(opts) {
+  // opts.bytes lets callers tune below the framework default (which is
+  // the SHA-512 block size). Floor is MIN_SECRET_BYTES (RFC 4226 §4):
+  // shorter secrets halve effective HMAC strength.
+  var bytes = (opts && typeof opts.bytes === "number") ? opts.bytes : DEFAULT_SECRET_BYTES;
+  if (bytes < MIN_SECRET_BYTES) {
+    throw new AuthError("auth-totp/bad-secret-length",
+      "secret bytes must be >= " + MIN_SECRET_BYTES + " per RFC 4226 §4 (got: " + bytes + ")");
+  }
+  return _base32Encode(generateBytes(bytes));
+}
+
+function generate(secret, opts) {
+  var resolved = _resolveOpts(opts);
+  var step = Math.floor(((opts && opts.now) || Date.now()) / 1000 / resolved.stepSeconds);
+  return compute(secret, step, opts);
+}
+
+function verify(secret, code, opts) {
+  // Tolerant on bad inputs — return false rather than throwing so the
+  // login path can treat malformed tokens as "didn't match" without
+  // catching exceptions per call.
+  if (typeof secret !== "string" || secret.length === 0) return false;
+  if (code == null) return false;
+  var resolved = _resolveOpts(opts);
+  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;
+  // Strip the whitespace + common separators that every authenticator UI
+  // and clipboard paste introduces ("123 456", "123-456", "123.456").
+  // RFC 6238 / NIST 800-63B don't mandate normalization, but Google
+  // Authenticator, Authy, Duo, and every other consumer-facing TOTP
+  // implementation strips these before comparison; not doing so is a
+  // silent operator footgun where users mash a code from their phone
+  // into a login form and the verifier rejects it because of one space.
+  // After stripping, padStart pads the configured digit count so
+  // timingSafeEqual gets equal-length buffers regardless of how the
+  // caller stringified.
+  var userCode = String(code).replace(/[\s.\-_]/g, "").padStart(resolved.digits, "0");
+  var userBuf = Buffer.from(userCode);
+
+  for (var d = -resolved.driftSteps; d <= resolved.driftSteps; d++) {
+    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); }
+    catch (_e) { return false; }
+    var expectedBuf = Buffer.from(expected);
+    if (timingSafeEqual(expectedBuf, userBuf)) {
+      return step;
+    }
+  }
+  return false;
+}
+
+function uri(secret, account, opts) {
+  if (typeof secret !== "string" || secret.length === 0) {
+    throw new AuthError("auth-totp/missing-secret", "secret is required");
+  }
+  if (typeof account !== "string" || account.length === 0) {
+    throw new AuthError("auth-totp/missing-account",
+      "account is required (typically the user's email or username)");
+  }
+  if (!opts || !opts.issuer || typeof opts.issuer !== "string") {
+    throw new AuthError("auth-totp/missing-issuer",
+      "opts.issuer is required (the application/service name shown in the authenticator)");
+  }
+  var resolved = _resolveOpts(opts);
+  // Label format per Google Authenticator: "Issuer:Account"
+  var label = encodeURIComponent(opts.issuer) + ":" + encodeURIComponent(account);
+  var params = [
+    "secret=" + secret,
+    "issuer=" + encodeURIComponent(opts.issuer),
+    "algorithm=" + resolved.algorithm.toUpperCase(),
+    "digits=" + resolved.digits,
+    "period=" + resolved.stepSeconds,
+  ];
+  return "otpauth://totp/" + label + "?" + params.join("&");
+}
+
+function generateBackupCodes(opts) {
+  // Defaults: 10 codes × 8 hex chars (4 random bytes per code). Operators
+  // who want longer / different formats override count + bytesPerCode.
+  opts = opts || {};
+  var count = opts.count != null ? opts.count : 10;
+  var bytesPerCode = opts.bytesPerCode != null ? opts.bytesPerCode : 4;
+  if (typeof count !== "number" || count < 1) {
+    throw new AuthError("auth-totp/bad-backup-count",
+      "count must be >= 1 (got: " + count + ")");
+  }
+  if (typeof bytesPerCode !== "number" || bytesPerCode < 2) {
+    throw new AuthError("auth-totp/bad-backup-bytes",
+      "bytesPerCode must be >= 2 (got: " + bytesPerCode + ")");
+  }
+  var codes = [];
+  for (var i = 0; i < count; i++) {
+    codes.push(generateToken(bytesPerCode));
+  }
+  return codes;
+}
+
+module.exports = {
+  generateSecret:        generateSecret,
+  generate:              generate,
+  compute:               compute,
+  verify:                verify,
+  uri:                   uri,
+  generateBackupCodes:   generateBackupCodes,
+  DEFAULT_STEP_SECONDS:  DEFAULT_STEP_SECONDS,
+  DEFAULT_DIGITS:        DEFAULT_DIGITS,
+  DEFAULT_DRIFT_STEPS:   DEFAULT_DRIFT_STEPS,
+  DEFAULT_ALGORITHM:     DEFAULT_ALGORITHM,
+  DEFAULT_SECRET_BYTES:  DEFAULT_SECRET_BYTES,
+  MIN_SECRET_BYTES:      MIN_SECRET_BYTES,
+  SUPPORTED_ALGORITHMS:  SUPPORTED_ALGORITHMS,
+};