@blamejs/core 0.4.1

package/lib/cookies.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * cookies — cookie parse/serialize + access-gated sealed cookies.
+ *
+ * RFC 6265 cookie plumbing the framework was duplicating across
+ * middleware: a parser in attach-user, ad-hoc Set-Cookie strings in
+ * route handlers, no shared place for attribute defaults. This is the
+ * single primitive.
+ *
+ * Two surfaces:
+ *
+ *   1. Module-level (stateless): cookies.parse / cookies.serialize.
+ *      Useful in test fixtures and code that doesn't have a vault.
+ *
+ *   2. Instance (cookies.create): bound defaults for cookie attributes,
+ *      a wired vault for sealed reads/writes, and req/res helpers.
+ *
+ *   var cookies = b.cookies.create({
+ *     vault: b.vault,                  // required for sealed* methods
+ *     defaults: {
+ *       httpOnly: true,
+ *       secure:   true,                // default true; HTTPS expected
+ *       sameSite: "Lax",
+ *       path:     "/",
+ *       maxAge:   7 * 86400,           // seconds
+ *     },
+ *   });
+ *
+ *   cookies.parse("a=1; b=2")           → { a: "1", b: "2" }
+ *   cookies.serialize("name", "v",
+ *     { maxAge: 3600 })                 → "name=v; Max-Age=3600; Path=/; HttpOnly; SameSite=Lax; Secure"
+ *
+ *   cookies.read(req, "name")           → "v" or null
+ *   cookies.write(res, "name", "v", {}) // appends to existing Set-Cookie
+ *   cookies.clear(res, "name", {})      // expire by Max-Age=0
+ *
+ *   cookies.writeSealed(res, "session", sid)  // vault.seal then write
+ *   cookies.readSealed(req, "session")        // read then vault.unseal
+ *
+ * Sealed-cookie purpose: the cookie value is a vault.seal of the real
+ * value. Without the framework's vault key, no client can hand-craft a
+ * valid cookie value, so the API is unreachable via curl-with-arbitrary-
+ * cookies or any tool that hasn't been through the framework's crypto
+ * flow. The vault prefix is stripped on write and re-added on read so
+ * the cookie carries only the base64 envelope.
+ *
+ * Defense in serialize/parse:
+ *   - Cookie name must be a valid token (no CTLs, no separator chars).
+ *   - Cookie value must not contain CRLF, semicolon, or comma.
+ *   - Value is percent-encoded on write, percent-decoded on read.
+ *   - Domain / Path are CRLF-stripped to defeat header injection
+ *     attempts via operator-controlled but improperly-escaped inputs.
+ */
+
+var C = require("./constants");
+var validateOpts = require("./validate-opts");
+var { FrameworkError } = require("./framework-error");
+
+class CookieError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "CookieError";
+    this.permanent = true;
+    this.isCookieError = true;
+  }
+}
+
+// RFC 6265 cookie-name token: VCHAR minus separators. Reject anything
+// outside this range — embeddings of CTLs / separators / whitespace
+// would break parsing on the next hop.
+var TOKEN_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
+// Reject CRLF, NUL, semicolon, comma in cookie value pre-encoding.
+var FORBIDDEN_VALUE_RE = /[\r\n\0;,]/;
+
+function _validateName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new CookieError("cookies/invalid-name",
+      "cookie name must be a non-empty string");
+  }
+  if (!TOKEN_RE.test(name)) {
+    throw new CookieError("cookies/invalid-name",
+      "cookie name '" + name + "' contains forbidden characters");
+  }
+}
+
+function _validateValue(value) {
+  if (typeof value !== "string") {
+    throw new CookieError("cookies/invalid-value",
+      "cookie value must be a string");
+  }
+  if (FORBIDDEN_VALUE_RE.test(value)) {
+    throw new CookieError("cookies/invalid-value",
+      "cookie value contains forbidden control character (CRLF/NUL/;/,)");
+  }
+}
+
+// Strip CRLF/NUL defensively from operator-supplied attribute strings
+// (Domain, Path, SameSite). Even if the attribute is constant in the
+// caller's code, attribute strings flow into Set-Cookie which is a
+// header — never trust unscrubbed values reach the wire.
+function _scrubAttr(s) {
+  if (typeof s !== "string") return s;
+  return s.replace(/[\r\n\0]/g, "");
+}
+
+function parse(cookieHeader) {
+  var out = {};
+  if (typeof cookieHeader !== "string" || cookieHeader.length === 0) return out;
+  var pairs = cookieHeader.split(/;\s*/);
+  for (var i = 0; i < pairs.length; i++) {
+    var pair = pairs[i];
+    if (!pair) continue;
+    var eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    var k = pair.slice(0, eq).trim();
+    if (!k) continue;
+    var v = pair.slice(eq + 1).trim();
+    // Strip surrounding double-quotes per RFC 6265 §5.2.
+    if (v.length >= 2 && v.charAt(0) === '"' && v.charAt(v.length - 1) === '"') {
+      v = v.slice(1, -1);
+    }
+    try { v = decodeURIComponent(v); }
+    catch (_e) { /* malformed encoding — keep raw */ }
+    // Last write wins per RFC; matches every browser's behavior.
+    out[k] = v;
+  }
+  return out;
+}
+
+function serialize(name, value, attrs) {
+  _validateName(name);
+  _validateValue(value);
+  attrs = attrs || {};
+
+  var parts = [name + "=" + encodeURIComponent(value)];
+
+  if (attrs.maxAge !== undefined && attrs.maxAge !== null) {
+    var maxAge = Number(attrs.maxAge);
+    if (!Number.isFinite(maxAge) || Math.floor(maxAge) !== maxAge) {
+      throw new CookieError("cookies/invalid-attr",
+        "cookie attr maxAge must be an integer (seconds)");
+    }
+    parts.push("Max-Age=" + maxAge);
+  }
+  if (attrs.expires !== undefined && attrs.expires !== null) {
+    var d = attrs.expires instanceof Date ? attrs.expires : new Date(attrs.expires);
+    if (isNaN(d.getTime())) {
+      throw new CookieError("cookies/invalid-attr",
+        "cookie attr expires must be a Date or parseable date string");
+    }
+    parts.push("Expires=" + d.toUTCString());
+  }
+  if (attrs.domain) {
+    parts.push("Domain=" + _scrubAttr(String(attrs.domain)));
+  }
+  if (attrs.path !== undefined && attrs.path !== null) {
+    parts.push("Path=" + _scrubAttr(String(attrs.path)));
+  }
+  if (attrs.httpOnly) parts.push("HttpOnly");
+  if (attrs.sameSite) {
+    var ss = String(attrs.sameSite);
+    var ssLow = ss.toLowerCase();
+    var ssNorm;
+    if      (ssLow === "strict") ssNorm = "Strict";
+    else if (ssLow === "lax")    ssNorm = "Lax";
+    else if (ssLow === "none")   ssNorm = "None";
+    else throw new CookieError("cookies/invalid-attr",
+      "cookie attr sameSite must be Strict, Lax, or None");
+    parts.push("SameSite=" + ssNorm);
+    // SameSite=None requires Secure per spec; force it on so operators
+    // don't ship a cookie that browsers silently drop.
+    if (ssNorm === "None") attrs = Object.assign({}, attrs, { secure: true });
+  }
+  if (attrs.secure) parts.push("Secure");
+  if (attrs.partitioned) parts.push("Partitioned");
+  if (attrs.priority) {
+    var p = String(attrs.priority);
+    var pLow = p.toLowerCase();
+    var pNorm;
+    if      (pLow === "low")    pNorm = "Low";
+    else if (pLow === "medium") pNorm = "Medium";
+    else if (pLow === "high")   pNorm = "High";
+    else throw new CookieError("cookies/invalid-attr",
+      "cookie attr priority must be Low, Medium, or High");
+    parts.push("Priority=" + pNorm);
+  }
+  return parts.join("; ");
+}
+
+// Append a Set-Cookie header preserving any already on the response.
+function _appendSetCookie(res, header) {
+  if (!res || typeof res.setHeader !== "function") {
+    throw new CookieError("cookies/no-set-header",
+      "response object has no setHeader (not a Node http.ServerResponse?)");
+  }
+  var existing;
+  if (typeof res.getHeader === "function") existing = res.getHeader("Set-Cookie");
+  var arr;
+  if (Array.isArray(existing))      arr = existing.slice();
+  else if (existing !== undefined)  arr = [existing];
+  else                              arr = [];
+  arr.push(header);
+  res.setHeader("Set-Cookie", arr);
+}
+
+function _readCookieFromReq(req, name) {
+  if (!req || !req.headers) return null;
+  var header = req.headers.cookie;
+  if (!header) return null;
+  var jar = parse(header);
+  return Object.prototype.hasOwnProperty.call(jar, name) ? jar[name] : null;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["vault", "defaults"], "b.cookies");
+  var vault = opts.vault || null;
+  // Defaults applied on every write unless the per-call attrs override.
+  // secure defaults to true: cookies should never be sent in cleartext;
+  // operators developing locally over http opt out explicitly.
+  var defaults = Object.assign({
+    httpOnly: true,
+    secure:   true,
+    sameSite: "Lax",
+    path:     "/",
+  }, opts.defaults || {});
+
+  function _mergeAttrs(callerAttrs) {
+    return Object.assign({}, defaults, callerAttrs || {});
+  }
+
+  function read(req, name)               { return _readCookieFromReq(req, name); }
+  function write(res, name, value, attrs) {
+    _appendSetCookie(res, serialize(name, value, _mergeAttrs(attrs)));
+  }
+  function clear(res, name, attrs) {
+    // Expire-now cookie. Domain + Path must match the original write
+    // for the browser to actually delete it — operators pass the same
+    // attrs they used on write (or rely on the same defaults).
+    var attrsExp = Object.assign({}, _mergeAttrs(attrs), { maxAge: 0 });
+    delete attrsExp.expires;
+    _appendSetCookie(res, serialize(name, "", attrsExp));
+  }
+
+  function _requireVault() {
+    if (!vault || typeof vault.seal !== "function" || typeof vault.unseal !== "function") {
+      throw new CookieError("cookies/no-vault",
+        "sealed cookies require opts.vault (a value with .seal/.unseal)");
+    }
+  }
+
+  // Vault.seal returns "vault:<base64>". We strip the constant prefix
+  // on the wire to keep cookies short, and re-add it before unseal.
+  // Within a vault major version the prefix is stable for the cookie's
+  // entire Max-Age window, so this is safe.
+  function writeSealed(res, name, value, attrs) {
+    _requireVault();
+    if (typeof value !== "string") {
+      throw new CookieError("cookies/invalid-value",
+        "sealed cookie value must be a string before sealing");
+    }
+    var sealed = vault.seal(value);
+    var stripped = sealed.startsWith(C.VAULT_PREFIX)
+      ? sealed.substring(C.VAULT_PREFIX.length)
+      : sealed;
+    write(res, name, stripped, attrs);
+  }
+  function readSealed(req, name) {
+    _requireVault();
+    var raw = _readCookieFromReq(req, name);
+    if (raw === null) return null;
+    try { return vault.unseal(C.VAULT_PREFIX + raw); }
+    catch (_e) { return null; }
+  }
+
+  return {
+    parse:       parse,
+    serialize:   function (n, v, a) { return serialize(n, v, _mergeAttrs(a)); },
+    read:        read,
+    write:       write,
+    clear:       clear,
+    writeSealed: writeSealed,
+    readSealed:  readSealed,
+    defaults:    defaults,
+  };
+}
+
+module.exports = {
+  create:       create,
+  parse:        parse,
+  serialize:    serialize,
+  CookieError:  CookieError,
+};

package/lib/credential-hash.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * b.credentialHash — envelope-versioned credential hashing.
+ *
+ * Stores a verifiable digest of a credential (API key secret, shared
+ * bearer token, etc.) as a base64-encoded envelope:
+ *
+ *     byte 0: 0xC1 (CREDENTIAL_MAGIC)
+ *     byte 1: <algorithm ID>
+ *     bytes 2..N: algorithm-specific payload
+ *
+ * The verify path dispatches on byte 1, so old credentials remain
+ * verifiable regardless of what ACTIVE.CRED_HASH points at today.
+ * When a new algorithm becomes the framework default, existing rows
+ * surface via `needsRehash()` and the next successful verify rotates
+ * them transparently — same pattern as `b.auth.password.needsRehash`.
+ *
+ *   var env = await b.credentialHash.hash(secretBytes);
+ *   // → "wQEx..." (base64)
+ *
+ *   var ok = await b.credentialHash.verify(secretBytes, env);
+ *   // → true / false
+ *
+ *   var info = b.credentialHash.inspect(env);
+ *   // → { algoId, algoName, payloadBytes }
+ *
+ *   if (b.credentialHash.needsRehash(env)) {
+ *     await db.update({ credentialHash: await b.credentialHash.hash(secretBytes) });
+ *   }
+ *
+ * Active algorithm: SHAKE256 (0x01). Suitable for high-entropy random
+ * secrets (≥ 128 bits) — fast verify (microseconds), brute-force
+ * infeasible at the entropy level the framework generates. SHAKE256
+ * is an XOF: the envelope payload length drives the digest size, so
+ * a future operator can request a 96-byte (or 32-byte) digest without
+ * a primitive change — the same algorithm ID covers all output sizes.
+ * Operators with low-entropy or operator-supplied secrets should pin
+ * Argon2id (0x02) per-registry: `hash(s, { algo: "argon2id" })`.
+ *
+ * Why SHAKE256 over SHA3-512 as the active:
+ *   - SHAKE256 is an extensible-output function (XOF). The envelope
+ *     payload's actual byte length tells the verify path how many
+ *     bytes to recompute. Changing digest size = no algo rotation.
+ *   - Same family as the framework KDF (`crypto.kdf`), so one
+ *     primitive does double duty.
+ *   - SHA-3 family fixed-size mode locks the byte count at 64 — the
+ *     moment we want a different size, we'd have to rotate algos.
+ *
+ * Why not Argon2id by default for api-key:
+ *   - Argon2id at framework defaults costs ~250ms per verify call.
+ *     For request-path verification that's a real latency hit.
+ *     SHAKE256 is microseconds.
+ *   - For ≥128-bit random secrets, the memory-hard property buys
+ *     nothing — brute force is infeasible regardless of hash.
+ *
+ * Why the envelope still matters with SHAKE256 as active:
+ *   - Algorithm agility — when SHA-3 family ever shows weakness, or
+ *     a stronger XOF lands, ACTIVE.CRED_HASH rotates with no need
+ *     to re-issue every credential. Old rows verify under their
+ *     stored algo byte; new rows use the active.
+ *   - Transparent rehash via needsRehash() drains old algos at the
+ *     pace of organic verify traffic.
+ *
+ * Validation tiers:
+ *
+ *   - hash() opts (algo, params)         → Tier A (throw)
+ *   - hash() secret type / length        → Tier A (throw)
+ *   - verify() envelope shape unparsable → Tier C (return false)
+ *   - verify() unknown algo ID           → Tier C (return false)
+ *   - inspect() bad envelope             → Tier C (return null)
+ */
+
+var crypto = require("./crypto");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var { FrameworkError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+
+function _emitEvent(name, value, labels) {
+  try { observability().event(name, value, labels || {}); }
+  catch (_e) { /* Tier B: hot-path observability sink */ }
+}
+
+// Default SHAKE256 output size for newly-issued credentials. 128
+// bytes (1024 bits) is double the SHAKE256 capacity (512 bits, which
+// caps collision-resistance); the extra bytes don't add to that
+// guarantee but cost nothing — base64 expansion is ~172 chars in a
+// TEXT column, verify is sub-microsecond, and a longer digest hurts
+// no foreseeable attack while protecting against any unforeseen
+// partial-collision attack class. Per the framework's modernity
+// posture (highest practical bar where cost is negligible), default
+// to the larger size; operators pass `{ params: { length: 64 } }`
+// to opt into the SHA3-512-comparable byte count if they need it.
+var SHAKE256_DEFAULT_LENGTH = 128;
+
+function _shake256(secret, length) {
+  // crypto.kdf wraps SHAKE256 with arbitrary output length. That's the
+  // exact primitive we need — the framework's KDF and credential-hash
+  // share one underlying XOF.
+  return crypto.kdf(secret, length);
+}
+
+
+// auth/password is required lazily because it imports the (large)
+// argon2 vendor; loading it for SHA3-only callers is wasted work.
+var passwordPrimitive = lazyRequire(function () { return require("./auth/password"); });
+
+class CredentialHashError extends FrameworkError {
+  constructor(message, code) {
+    super(message, code || "credential-hash/invalid");
+    this.name = "CredentialHashError";
+    this.isCredentialHashError = true;
+  }
+}
+
+var ALGOS = Object.freeze({
+  SHAKE256: "shake256",
+  ARGON2ID: "argon2id",
+});
+
+var DEFAULTS = Object.freeze({
+  algo: ALGOS.SHAKE256,
+});
+
+// Map between human-readable algo names (used in opts) and the wire
+// algorithm IDs (used in the envelope byte). The envelope byte is
+// what's persisted; the string is what operators read in code.
+var NAME_TO_ID = Object.freeze({
+  "shake256": C.CRED_HASH_IDS.SHAKE256,
+  "argon2id": C.CRED_HASH_IDS.ARGON2ID,
+});
+var ID_TO_NAME = Object.freeze({
+  0x01: "shake256",
+  0x02: "argon2id",
+});
+
+// ---- Tier-A validation ----
+
+function _validateSecret(secret) {
+  if (typeof secret !== "string" && !Buffer.isBuffer(secret)) {
+    throw new CredentialHashError(
+      "credentialHash: secret must be a string or Buffer, got " + typeof secret,
+      "credential-hash/bad-secret");
+  }
+  var len = Buffer.isBuffer(secret) ? secret.length : Buffer.byteLength(secret, "utf8");
+  if (len === 0) {
+    throw new CredentialHashError(
+      "credentialHash: secret must be non-empty",
+      "credential-hash/bad-secret");
+  }
+}
+
+function _validateOpts(opts) {
+  if (!opts) return;
+  if (opts.algo !== undefined && typeof opts.algo !== "string") {
+    throw new CredentialHashError(
+      "credentialHash: algo must be a string ('sha3-512' or 'argon2id')",
+      "credential-hash/bad-opt");
+  }
+  if (opts.algo !== undefined && !Object.prototype.hasOwnProperty.call(NAME_TO_ID, opts.algo)) {
+    throw new CredentialHashError(
+      "credentialHash: unknown algo '" + opts.algo + "', expected one of " +
+        JSON.stringify(Object.keys(NAME_TO_ID)),
+      "credential-hash/bad-opt");
+  }
+  if (opts.params !== undefined && (typeof opts.params !== "object" || Array.isArray(opts.params))) {
+    throw new CredentialHashError(
+      "credentialHash: params must be a plain object",
+      "credential-hash/bad-opt");
+  }
+}
+
+// ---- Envelope (de)serialization ----
+
+function _envelope(algoId, payload) {
+  var head = Buffer.from([C.CREDENTIAL_MAGIC, algoId]);
+  return Buffer.concat([head, payload]).toString("base64");
+}
+
+function _decodeEnvelope(env) {
+  if (typeof env !== "string" || env.length === 0) return null;
+  var buf;
+  try { buf = Buffer.from(env, "base64"); }
+  catch (_e) { return null; }
+  if (buf.length < 2) return null;
+  if (buf[0] !== C.CREDENTIAL_MAGIC) return null;
+  var algoId = buf[1];
+  if (!Object.prototype.hasOwnProperty.call(ID_TO_NAME, algoId)) return null;
+  return { algoId: algoId, payload: buf.slice(2) };
+}
+
+// ---- Public surface ----
+
+async function hash(secret, opts) {
+  _validateSecret(secret);
+  _validateOpts(opts);
+  var algoName = (opts && opts.algo) || DEFAULTS.algo;
+  var algoId = NAME_TO_ID[algoName];
+
+  if (algoId === C.CRED_HASH_IDS.SHAKE256) {
+    var length = (opts && opts.params && opts.params.length) || SHAKE256_DEFAULT_LENGTH;
+    if (typeof length !== "number" || !isFinite(length) || length < 16 || Math.floor(length) !== length) {
+      throw new CredentialHashError(
+        "credentialHash.hash: SHAKE256 length must be an integer >= 16, got " + JSON.stringify(length),
+        "credential-hash/bad-opt");
+    }
+    var env = _envelope(algoId, _shake256(secret, length));
+    _emitEvent("credentialHash.hash", 1, { algo: algoName });
+    return env;
+  }
+  if (algoId === C.CRED_HASH_IDS.ARGON2ID) {
+    var plain = Buffer.isBuffer(secret) ? secret.toString("utf8") : secret;
+    var phc = await passwordPrimitive().hash(plain, opts && opts.params);
+    var argonEnv = _envelope(algoId, Buffer.from(phc, "utf8"));
+    _emitEvent("credentialHash.hash", 1, { algo: algoName });
+    return argonEnv;
+  }
+  // Unreachable — _validateOpts rejects unknown algos.
+  throw new CredentialHashError(
+    "credentialHash.hash: unsupported algo id 0x" + algoId.toString(16),
+    "credential-hash/unsupported");
+}
+
+async function verify(secret, envelope) {
+  // Tier C: any malformed input → false. Lets operators write
+  //   if (!await ch.verify(s, row.hash)) return res.status(401);
+  // without try/catch ceremony. We still reject obvious caller bugs
+  // (non-string-or-Buffer secret) loudly because that signals broken
+  // request plumbing rather than a bad credential.
+  if (typeof secret !== "string" && !Buffer.isBuffer(secret)) {
+    _emitEvent("credentialHash.verify", 1, { outcome: "failure", reason: "bad-secret-type" });
+    return false;
+  }
+  var len = Buffer.isBuffer(secret) ? secret.length : Buffer.byteLength(secret, "utf8");
+  if (len === 0) {
+    _emitEvent("credentialHash.verify", 1, { outcome: "failure", reason: "empty-secret" });
+    return false;
+  }
+
+  var decoded = _decodeEnvelope(envelope);
+  if (!decoded) {
+    _emitEvent("credentialHash.verify", 1, { outcome: "failure", reason: "bad-envelope" });
+    return false;
+  }
+  var algoName = ID_TO_NAME[decoded.algoId];
+
+  if (decoded.algoId === C.CRED_HASH_IDS.SHAKE256) {
+    var expected = _shake256(secret, decoded.payload.length);
+    var ok = crypto.timingSafeEqual(expected, decoded.payload);
+    _emitEvent("credentialHash.verify", 1,
+      { outcome: ok ? "success" : "failure", algo: algoName });
+    return ok;
+  }
+  if (decoded.algoId === C.CRED_HASH_IDS.ARGON2ID) {
+    var phc = decoded.payload.toString("utf8");
+    var plain = Buffer.isBuffer(secret) ? secret.toString("utf8") : secret;
+    var argOk = false;
+    try { argOk = await passwordPrimitive().verify(phc, plain); }
+    catch (_e) { argOk = false; }
+    _emitEvent("credentialHash.verify", 1,
+      { outcome: argOk ? "success" : "failure", algo: algoName });
+    return argOk;
+  }
+  _emitEvent("credentialHash.verify", 1, { outcome: "failure", reason: "unknown-algo" });
+  return false;
+}
+
+function inspect(envelope) {
+  var decoded = _decodeEnvelope(envelope);
+  if (!decoded) return null;
+  return {
+    algoId:       decoded.algoId,
+    algoName:     ID_TO_NAME[decoded.algoId],
+    payloadBytes: decoded.payload.length,
+  };
+}
+
+function needsRehash(envelope, opts) {
+  var decoded = _decodeEnvelope(envelope);
+  if (!decoded) return true;     // unrecognized → migrate aggressively
+  var targetAlgoName = (opts && opts.algo) || DEFAULTS.algo;
+  var targetId = NAME_TO_ID[targetAlgoName] || C.ACTIVE.CRED_HASH;
+  if (decoded.algoId !== targetId) return true;
+  if (decoded.algoId === C.CRED_HASH_IDS.ARGON2ID) {
+    // Defer the parameter-lag check to the password primitive's
+    // own needsRehash so the threshold stays in one place.
+    var phc = decoded.payload.toString("utf8");
+    try { return passwordPrimitive().needsRehash(phc, opts && opts.params); }
+    catch (_e) { return true; }
+  }
+  return false;
+}
+
+module.exports = {
+  hash:                 hash,
+  verify:               verify,
+  inspect:              inspect,
+  needsRehash:          needsRehash,
+  ALGOS:                ALGOS,
+  DEFAULTS:             DEFAULTS,
+  CredentialHashError:  CredentialHashError,
+};