secure-hash-vault 1.0.0

package/dist/index.cjs

@@ -0,0 +1,792 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CipherForge: () => CipherForge,
+  CipherForgeError: () => CipherForgeError,
+  CipherVaultError: () => CipherVaultError,
+  DecryptionError: () => DecryptionError,
+  EncryptionError: () => EncryptionError,
+  InvalidConfigError: () => InvalidConfigError,
+  InvalidPasswordHashError: () => InvalidPasswordHashError,
+  InvalidPayloadError: () => InvalidPayloadError,
+  PasswordVerificationError: () => PasswordVerificationError,
+  SecureHashVaultClient: () => SecureHashVaultClient,
+  SecureHashVaultError: () => SecureHashVaultError,
+  cipherForge: () => cipherForge,
+  cipherVault: () => cipherVault,
+  createCipherForge: () => createCipherForge,
+  createCipherVault: () => createCipherVault,
+  createSecureHashVault: () => createSecureHashVault,
+  decryptBuffer: () => decryptBuffer,
+  decryptFile: () => decryptFile,
+  decryptJson: () => decryptJson,
+  decryptText: () => decryptText,
+  default: () => index_default,
+  detectPayload: () => detectPayload,
+  encryptBuffer: () => encryptBuffer,
+  encryptFile: () => encryptFile,
+  encryptJson: () => encryptJson,
+  encryptText: () => encryptText,
+  fromBase64Url: () => fromBase64Url,
+  fromHex: () => fromHex,
+  generatePepper: () => generatePepper,
+  generateSalt: () => generateSalt,
+  hashPassword: () => hashPassword,
+  needsRehash: () => needsRehash,
+  randomBuffer: () => randomBuffer,
+  secureVault: () => secureVault,
+  toBase64Url: () => toBase64Url,
+  toHex: () => toHex,
+  verifyPassword: () => verifyPassword
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/crypto/decryptBuffer.ts
+var import_node_crypto2 = require("crypto");
+
+// src/core/constants.ts
+var PASSWORD_FORMAT_PREFIX = "$cv$";
+var PASSWORD_VERSION = "v1";
+var PASSWORD_ALGORITHM = "scrypt";
+var ENCRYPTION_FORMAT = "cv.enc.v1";
+var ENCRYPTION_COMPACT_PREFIX = "$cvenc$";
+var ENCRYPTION_VERSION = "v1";
+var ENCRYPTION_ALGORITHM = "aes-256-gcm";
+var ENCRYPTION_KDF = "scrypt";
+var DEFAULT_PASSWORD_PARAMS = {
+  N: 16384,
+  r: 8,
+  p: 1,
+  keyLen: 64
+};
+var DEFAULT_ENCRYPTION_PARAMS = {
+  N: 16384,
+  r: 8,
+  p: 1,
+  keyLen: 32
+};
+var DEFAULT_SALT_LENGTH = 16;
+var DEFAULT_IV_LENGTH = 12;
+
+// src/core/errors.ts
+var SecureHashVaultError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var CipherForgeError = class extends SecureHashVaultError {
+};
+var CipherVaultError = class extends CipherForgeError {
+};
+var InvalidPasswordHashError = class extends SecureHashVaultError {
+};
+var PasswordVerificationError = class extends SecureHashVaultError {
+};
+var EncryptionError = class extends SecureHashVaultError {
+};
+var DecryptionError = class extends SecureHashVaultError {
+};
+var InvalidPayloadError = class extends SecureHashVaultError {
+};
+var InvalidConfigError = class extends SecureHashVaultError {
+};
+
+// src/core/encoding.ts
+function toBase64Url(input) {
+  const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input, "utf8");
+  return buffer.toString("base64url");
+}
+function fromBase64Url(value, fieldName = "value") {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new InvalidPayloadError(`${fieldName} must be a non-empty base64url string.`);
+  }
+  try {
+    return Buffer.from(value, "base64url");
+  } catch (error) {
+    throw new InvalidPayloadError(`${fieldName} is not valid base64url data.`, { cause: error });
+  }
+}
+function toHex(input) {
+  const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input, "utf8");
+  return buffer.toString("hex");
+}
+function fromHex(value, fieldName = "value") {
+  if (typeof value !== "string" || value.length === 0 || !/^[\da-f]+$/i.test(value)) {
+    throw new InvalidPayloadError(`${fieldName} must be a non-empty hex string.`);
+  }
+  return Buffer.from(value, "hex");
+}
+
+// src/core/kdf.ts
+var import_node_crypto = require("crypto");
+async function deriveScryptKey(secret, salt, params) {
+  const maxmem = Math.max(32 * 1024 * 1024, 128 * params.N * params.r + 1024 * 1024);
+  return new Promise((resolve, reject) => {
+    (0, import_node_crypto.scrypt)(
+      secret,
+      salt,
+      params.keyLen,
+      {
+        N: params.N,
+        r: params.r,
+        p: params.p,
+        maxmem
+      },
+      (error, derivedKey) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(derivedKey);
+      }
+    );
+  });
+}
+function applyPepper(password, pepper) {
+  if (!pepper) {
+    return Buffer.from(password, "utf8");
+  }
+  return Buffer.concat([Buffer.from(password, "utf8"), Buffer.from("\0", "utf8"), Buffer.from(pepper, "utf8")]);
+}
+
+// src/core/validators.ts
+function assertPassword(password) {
+  if (typeof password !== "string") {
+    throw new InvalidConfigError("Password must be a string.");
+  }
+  if (password.length === 0) {
+    throw new InvalidConfigError("Password cannot be empty.");
+  }
+}
+function assertSecret(secret) {
+  if (typeof secret !== "string") {
+    throw new InvalidConfigError("Secret must be a string.");
+  }
+  if (secret.length === 0) {
+    throw new InvalidConfigError("Secret cannot be empty.");
+  }
+}
+function assertPasswordAlgorithm(algorithm) {
+  if (algorithm !== void 0 && algorithm !== PASSWORD_ALGORITHM) {
+    throw new InvalidConfigError(`Unsupported password algorithm: ${String(algorithm)}.`);
+  }
+}
+function assertEncryptionAlgorithm(algorithm) {
+  if (algorithm !== void 0 && algorithm !== ENCRYPTION_ALGORITHM) {
+    throw new InvalidConfigError(`Unsupported encryption algorithm: ${String(algorithm)}.`);
+  }
+}
+function normalizeScryptParams(defaults, params) {
+  const normalized = { ...defaults, ...params };
+  validateScryptParams(normalized);
+  return normalized;
+}
+function validateScryptParams(params) {
+  const { N, r, p, keyLen } = params;
+  if (!Number.isInteger(N) || N < 4096 || N > 1048576 || (N & N - 1) !== 0) {
+    throw new InvalidConfigError("scrypt N must be a power-of-two integer between 4096 and 1048576.");
+  }
+  if (!Number.isInteger(r) || r < 1 || r > 32) {
+    throw new InvalidConfigError("scrypt r must be an integer between 1 and 32.");
+  }
+  if (!Number.isInteger(p) || p < 1 || p > 16) {
+    throw new InvalidConfigError("scrypt p must be an integer between 1 and 16.");
+  }
+  if (!Number.isInteger(keyLen) || keyLen < 32 || keyLen > 128) {
+    throw new InvalidConfigError("scrypt keyLen must be an integer between 32 and 128.");
+  }
+}
+
+// src/utils/safeJson.ts
+function parseJson(value, message = "Invalid JSON payload.") {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new InvalidPayloadError(message, { cause: error });
+  }
+}
+function stringifyJson(value) {
+  try {
+    return JSON.stringify(value);
+  } catch (error) {
+    throw new InvalidPayloadError("Value cannot be serialized to JSON.", { cause: error });
+  }
+}
+
+// src/crypto/cryptoFormat.ts
+function serializeCryptoParams(params) {
+  return `N=${params.N},r=${params.r},p=${params.p},keyLen=${params.keyLen}`;
+}
+function parseCryptoParams(value) {
+  const record = {};
+  for (const pair of value.split(",")) {
+    const [key, rawValue] = pair.split("=");
+    if (!key || rawValue === void 0 || !["N", "r", "p", "keyLen"].includes(key)) {
+      throw new InvalidPayloadError("Encrypted payload contains malformed KDF parameters.");
+    }
+    record[key] = Number(rawValue);
+  }
+  const { N, r, p, keyLen } = record;
+  if (!N || !r || !p || !keyLen) {
+    throw new InvalidPayloadError("Encrypted payload is missing required KDF parameters.");
+  }
+  const params = { N, r, p, keyLen };
+  validateScryptParams(params);
+  return params;
+}
+function payloadToCompact(payload) {
+  return `${ENCRYPTION_COMPACT_PREFIX}${ENCRYPTION_VERSION}$${payload.algorithm}$${payload.kdf}$${serializeCryptoParams(payload.params)}$${payload.salt}$${payload.iv}$${payload.tag}$${payload.cipherText}`;
+}
+function parseEncryptedPayload(payload) {
+  if (typeof payload === "string") {
+    if (payload.startsWith(ENCRYPTION_COMPACT_PREFIX)) {
+      return parseCompactPayload(payload);
+    }
+    return parseJson(payload, "Encrypted payload string must be compact format or JSON.");
+  }
+  if (!payload || typeof payload !== "object") {
+    throw new InvalidPayloadError("Encrypted payload must be an object or string.");
+  }
+  validatePayloadShape(payload);
+  return payload;
+}
+function validatePayloadShape(payload) {
+  if (payload.format !== ENCRYPTION_FORMAT) {
+    throw new InvalidPayloadError("Unsupported encrypted payload format.");
+  }
+  if (payload.algorithm !== ENCRYPTION_ALGORITHM) {
+    throw new InvalidPayloadError("Unsupported encrypted payload algorithm.");
+  }
+  if (payload.kdf !== ENCRYPTION_KDF) {
+    throw new InvalidPayloadError("Unsupported encrypted payload KDF.");
+  }
+  validateScryptParams(payload.params);
+  for (const field of ["salt", "iv", "tag", "cipherText"]) {
+    if (typeof payload[field] !== "string" || payload[field].length === 0) {
+      throw new InvalidPayloadError(`Encrypted payload field ${field} must be a non-empty string.`);
+    }
+  }
+}
+function parseCompactPayload(compact) {
+  const parts = compact.split("$");
+  const [, prefix, version, algorithm, kdf, rawParams, salt, iv, tag, cipherText] = parts;
+  if (parts.length !== 10 || prefix !== "cvenc" || version !== ENCRYPTION_VERSION || algorithm !== ENCRYPTION_ALGORITHM || kdf !== ENCRYPTION_KDF || !rawParams || !salt || !iv || !tag || !cipherText) {
+    throw new InvalidPayloadError("Malformed compact encrypted payload.");
+  }
+  return {
+    format: ENCRYPTION_FORMAT,
+    algorithm,
+    kdf,
+    params: parseCryptoParams(rawParams),
+    salt,
+    iv,
+    tag,
+    cipherText
+  };
+}
+
+// src/crypto/decryptBuffer.ts
+async function decryptBuffer(payload, secret, options = {}) {
+  assertSecret(secret);
+  try {
+    const parsed = parseEncryptedPayload(payload);
+    const key = await deriveScryptKey(secret, fromBase64Url(parsed.salt, "salt"), parsed.params);
+    const decipher = (0, import_node_crypto2.createDecipheriv)(ENCRYPTION_ALGORITHM, key, fromBase64Url(parsed.iv, "iv"));
+    if (options.aad) {
+      decipher.setAAD(Buffer.from(options.aad, "utf8"));
+    }
+    decipher.setAuthTag(fromBase64Url(parsed.tag, "auth tag"));
+    return Buffer.concat([
+      decipher.update(fromBase64Url(parsed.cipherText, "cipherText")),
+      decipher.final()
+    ]);
+  } catch (error) {
+    throw new DecryptionError("Decryption failed. Check the secret, payload, and authenticated data.", {
+      cause: error
+    });
+  }
+}
+
+// src/crypto/decryptFile.ts
+var import_promises = require("fs/promises");
+var import_node_crypto3 = require("crypto");
+
+// src/utils/metadata.ts
+function createdAt() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function withCreatedAt(metadata) {
+  return {
+    ...metadata ?? {},
+    createdAt: typeof metadata?.createdAt === "string" ? metadata.createdAt : createdAt()
+  };
+}
+
+// src/crypto/decryptFile.ts
+async function decryptFile(inputPath, outputPath, secret, options = {}) {
+  assertSecret(secret);
+  try {
+    const file = await (0, import_promises.readFile)(inputPath);
+    const headerEnd = file.indexOf(10);
+    if (headerEnd <= 0) {
+      throw new InvalidPayloadError("Encrypted file is missing CipherForge header.");
+    }
+    const header = parseJson(file.subarray(0, headerEnd).toString("utf8"), "Encrypted file header is invalid.");
+    if (header.format !== "cv.file.v1" || header.algorithm !== ENCRYPTION_ALGORITHM || header.kdf !== "scrypt") {
+      throw new InvalidPayloadError("Unsupported encrypted file format.");
+    }
+    const body = file.subarray(headerEnd + 1);
+    if (body.length < 16) {
+      throw new InvalidPayloadError("Encrypted file is missing authentication tag.");
+    }
+    const cipherText = body.subarray(0, body.length - 16);
+    const tag = body.subarray(body.length - 16);
+    const params = parseCryptoParams(header.params);
+    const key = await deriveScryptKey(secret, fromBase64Url(header.salt, "salt"), params);
+    const decipher = (0, import_node_crypto3.createDecipheriv)(ENCRYPTION_ALGORITHM, key, fromBase64Url(header.iv, "iv"));
+    if (options.aad) {
+      decipher.setAAD(Buffer.from(options.aad, "utf8"));
+    } else if (header.aad) {
+      throw new InvalidPayloadError("Encrypted file requires authenticated data.");
+    }
+    decipher.setAuthTag(tag);
+    await (0, import_promises.writeFile)(outputPath, Buffer.concat([decipher.update(cipherText), decipher.final()]));
+    const inputStats = await (0, import_promises.stat)(inputPath);
+    const outputStats = await (0, import_promises.stat)(outputPath);
+    return {
+      inputPath,
+      outputPath,
+      bytesRead: inputStats.size,
+      bytesWritten: outputStats.size,
+      algorithm: ENCRYPTION_ALGORITHM,
+      createdAt: createdAt()
+    };
+  } catch (error) {
+    throw new DecryptionError("File decryption failed. Check the secret, payload, and authenticated data.", {
+      cause: error
+    });
+  }
+}
+
+// src/crypto/decryptText.ts
+async function decryptText(payload, secret, options = {}) {
+  const buffer = await decryptBuffer(payload, secret, options);
+  return buffer.toString("utf8");
+}
+
+// src/crypto/decryptJson.ts
+async function decryptJson(payload, secret, options = {}) {
+  return parseJson(await decryptText(payload, secret, options), "Decrypted payload is not valid JSON.");
+}
+
+// src/crypto/encryptBuffer.ts
+var import_node_crypto5 = require("crypto");
+
+// src/core/random.ts
+var import_node_crypto4 = require("crypto");
+function randomBuffer(size = DEFAULT_SALT_LENGTH) {
+  if (!Number.isInteger(size) || size < 8 || size > 1024) {
+    throw new InvalidConfigError("Random byte size must be an integer between 8 and 1024.");
+  }
+  return (0, import_node_crypto4.randomBytes)(size);
+}
+function generateSalt(size = DEFAULT_SALT_LENGTH) {
+  return toBase64Url(randomBuffer(size));
+}
+function generatePepper(size = 32) {
+  return toBase64Url(randomBuffer(size));
+}
+
+// src/crypto/encryptBuffer.ts
+async function encryptBuffer(buffer, secret, options = {}) {
+  if (!Buffer.isBuffer(buffer)) {
+    throw new EncryptionError("encryptBuffer input must be a Buffer.");
+  }
+  assertSecret(secret);
+  assertEncryptionAlgorithm(options.algorithm);
+  try {
+    const params = normalizeScryptParams(DEFAULT_ENCRYPTION_PARAMS, options.params);
+    const salt = randomBuffer(DEFAULT_SALT_LENGTH);
+    const iv = randomBuffer(DEFAULT_IV_LENGTH);
+    const key = await deriveScryptKey(secret, salt, params);
+    const cipher = (0, import_node_crypto5.createCipheriv)(ENCRYPTION_ALGORITHM, key, iv);
+    if (options.aad) {
+      cipher.setAAD(Buffer.from(options.aad, "utf8"));
+    }
+    const cipherText = Buffer.concat([cipher.update(buffer), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const payload = {
+      format: ENCRYPTION_FORMAT,
+      algorithm: ENCRYPTION_ALGORITHM,
+      kdf: ENCRYPTION_KDF,
+      params,
+      iv: toBase64Url(iv),
+      salt: toBase64Url(salt),
+      tag: toBase64Url(tag),
+      cipherText: toBase64Url(cipherText),
+      metadata: withCreatedAt(options.metadata)
+    };
+    return options.output === "compact" ? payloadToCompact(payload) : payload;
+  } catch (error) {
+    throw new EncryptionError("Encryption failed.", { cause: error });
+  }
+}
+
+// src/crypto/encryptFile.ts
+var import_node_fs = require("fs");
+var import_promises2 = require("fs/promises");
+var import_node_crypto6 = require("crypto");
+var import_promises3 = require("stream/promises");
+async function encryptFile(inputPath, outputPath, secret, options = {}) {
+  assertSecret(secret);
+  try {
+    const params = normalizeScryptParams(DEFAULT_ENCRYPTION_PARAMS, options.params);
+    const salt = randomBuffer(DEFAULT_SALT_LENGTH);
+    const iv = randomBuffer(DEFAULT_IV_LENGTH);
+    const key = await deriveScryptKey(secret, salt, params);
+    const cipher = (0, import_node_crypto6.createCipheriv)(ENCRYPTION_ALGORITHM, key, iv);
+    if (options.aad) {
+      cipher.setAAD(Buffer.from(options.aad, "utf8"));
+    }
+    const header = Buffer.from(
+      JSON.stringify({
+        format: "cv.file.v1",
+        algorithm: ENCRYPTION_ALGORITHM,
+        kdf: "scrypt",
+        params: serializeCryptoParams(params),
+        salt: toBase64Url(salt),
+        iv: toBase64Url(iv),
+        aad: options.aad ? true : void 0
+      }) + "\n",
+      "utf8"
+    );
+    const output = (0, import_node_fs.createWriteStream)(outputPath);
+    output.write(header);
+    await (0, import_promises3.pipeline)((0, import_node_fs.createReadStream)(inputPath), cipher, output, { end: false });
+    output.write(cipher.getAuthTag());
+    output.end();
+    const inputStats = await (0, import_promises2.stat)(inputPath);
+    const outputStats = await (0, import_promises2.stat)(outputPath);
+    return {
+      inputPath,
+      outputPath,
+      bytesRead: inputStats.size,
+      bytesWritten: outputStats.size,
+      algorithm: ENCRYPTION_ALGORITHM,
+      createdAt: createdAt()
+    };
+  } catch (error) {
+    throw new EncryptionError("File encryption failed.", { cause: error });
+  }
+}
+
+// src/crypto/encryptText.ts
+async function encryptText(plainText, secret, options = {}) {
+  if (typeof plainText !== "string") {
+    throw new TypeError("plainText must be a string.");
+  }
+  return encryptBuffer(Buffer.from(plainText, "utf8"), secret, options);
+}
+
+// src/crypto/encryptJson.ts
+async function encryptJson(data, secret, options = {}) {
+  return encryptText(stringifyJson(data), secret, options);
+}
+
+// src/password/passwordFormat.ts
+function serializePasswordParams(params) {
+  return `N=${params.N},r=${params.r},p=${params.p},keyLen=${params.keyLen}`;
+}
+function parsePasswordParams(value) {
+  const pairs = value.split(",");
+  const record = {};
+  for (const pair of pairs) {
+    const [key, rawValue] = pair.split("=");
+    if (!key || rawValue === void 0 || !["N", "r", "p", "keyLen"].includes(key)) {
+      throw new InvalidPasswordHashError("Password hash contains malformed scrypt parameters.");
+    }
+    const numberValue = Number(rawValue);
+    if (!Number.isInteger(numberValue)) {
+      throw new InvalidPasswordHashError("Password hash contains non-integer scrypt parameters.");
+    }
+    record[key] = numberValue;
+  }
+  const { N, r, p, keyLen } = record;
+  if (!N || !r || !p || !keyLen) {
+    throw new InvalidPasswordHashError("Password hash is missing required scrypt parameters.");
+  }
+  const params = { N, r, p, keyLen };
+  validateScryptParams(params);
+  return params;
+}
+function formatPasswordHash(params, salt, hash) {
+  return `${PASSWORD_FORMAT_PREFIX}${PASSWORD_VERSION}$${PASSWORD_ALGORITHM}$${serializePasswordParams(params)}$${salt}$${hash}`;
+}
+function parsePasswordHash(storedHash) {
+  if (typeof storedHash !== "string" || storedHash.length === 0) {
+    throw new InvalidPasswordHashError("Stored password hash must be a non-empty string.");
+  }
+  if (!storedHash.startsWith(PASSWORD_FORMAT_PREFIX)) {
+    throw new InvalidPasswordHashError("Unsupported password hash format. Password hashes cannot be decrypted.");
+  }
+  const parts = storedHash.split("$");
+  const [, prefix, version, algorithm, rawParams, salt, hash] = parts;
+  if (parts.length !== 7 || prefix !== "cv" || version !== PASSWORD_VERSION || algorithm !== PASSWORD_ALGORITHM) {
+    throw new InvalidPasswordHashError("Malformed CipherForge password hash.");
+  }
+  if (!rawParams || !salt || !hash) {
+    throw new InvalidPasswordHashError("Password hash is missing metadata, salt, or hash value.");
+  }
+  return {
+    prefix,
+    version,
+    algorithm,
+    params: parsePasswordParams(rawParams),
+    salt,
+    hash
+  };
+}
+
+// src/password/hashPassword.ts
+async function hashPassword(password, options = {}) {
+  assertPassword(password);
+  assertPasswordAlgorithm(options.algorithm);
+  const params = normalizeScryptParams(DEFAULT_PASSWORD_PARAMS, options.params);
+  const salt = options.salt ?? generateSalt(options.saltLength ?? DEFAULT_SALT_LENGTH);
+  const saltBuffer = fromBase64Url(salt, "salt");
+  const passwordBuffer = applyPepper(password, options.pepper);
+  const derivedKey = await deriveScryptKey(passwordBuffer, saltBuffer, params);
+  const hash = toBase64Url(derivedKey);
+  return {
+    algorithm: PASSWORD_ALGORITHM,
+    version: PASSWORD_VERSION,
+    hash: formatPasswordHash(params, salt, hash),
+    salt,
+    params,
+    createdAt: createdAt()
+  };
+}
+
+// src/password/needsRehash.ts
+function needsRehash(storedHash, currentOptions = {}) {
+  assertPasswordAlgorithm(currentOptions.algorithm);
+  let parsed;
+  try {
+    parsed = parsePasswordHash(storedHash);
+  } catch (error) {
+    if (error instanceof InvalidPasswordHashError) {
+      return true;
+    }
+    throw error;
+  }
+  const currentParams = normalizeScryptParams(DEFAULT_PASSWORD_PARAMS, currentOptions.params);
+  return parsed.version !== PASSWORD_VERSION || parsed.algorithm !== PASSWORD_ALGORITHM || parsed.params.N !== currentParams.N || parsed.params.r !== currentParams.r || parsed.params.p !== currentParams.p || parsed.params.keyLen !== currentParams.keyLen;
+}
+
+// src/core/timingSafe.ts
+var import_node_crypto7 = require("crypto");
+function timingSafeCompare(left, right) {
+  if (left.length !== right.length) {
+    const paddedLeft = Buffer.alloc(Math.max(left.length, right.length));
+    const paddedRight = Buffer.alloc(Math.max(left.length, right.length));
+    left.copy(paddedLeft);
+    right.copy(paddedRight);
+    (0, import_node_crypto7.timingSafeEqual)(paddedLeft, paddedRight);
+    return false;
+  }
+  return (0, import_node_crypto7.timingSafeEqual)(left, right);
+}
+
+// src/password/verifyPassword.ts
+async function verifyPassword(password, storedHash, options = {}) {
+  assertPassword(password);
+  try {
+    const parsed = parsePasswordHash(storedHash);
+    const saltBuffer = fromBase64Url(parsed.salt, "salt");
+    const expected = fromBase64Url(parsed.hash, "password hash");
+    const candidate = await deriveScryptKey(applyPepper(password, options.pepper), saltBuffer, parsed.params);
+    const valid = timingSafeCompare(Buffer.from(toBase64Url(candidate)), Buffer.from(toBase64Url(expected)));
+    return {
+      valid,
+      needsRehash: valid ? needsRehash(storedHash, options.currentOptions ?? {}) : false,
+      algorithm: parsed.algorithm,
+      version: parsed.version
+    };
+  } catch (error) {
+    throw new PasswordVerificationError("Password verification failed. Password hashes cannot be decrypted.", {
+      cause: error
+    });
+  }
+}
+
+// src/utils/detectPayload.ts
+function detectPayload(value) {
+  if (Buffer.isBuffer(value)) {
+    return "buffer";
+  }
+  if (typeof value === "string") {
+    if (value.startsWith(PASSWORD_FORMAT_PREFIX)) {
+      return "password-hash";
+    }
+    if (value.startsWith(ENCRYPTION_COMPACT_PREFIX)) {
+      return "encrypted-payload";
+    }
+    try {
+      const parsed = JSON.parse(value);
+      return parsed.format === ENCRYPTION_FORMAT ? "encrypted-payload" : "json";
+    } catch {
+      return "plain-text";
+    }
+  }
+  if (value && typeof value === "object" && value.format === ENCRYPTION_FORMAT) {
+    return "encrypted-payload";
+  }
+  if (value && typeof value === "object") {
+    return "json";
+  }
+  return "unknown";
+}
+
+// src/client/SecureHashVaultClient.ts
+var SecureHashVaultClient = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.password = {
+      hash: (password, options2) => hashPassword(password, { ...this.options.password, ...options2 }),
+      verify: (password, storedHash, options2) => {
+        const currentOptions = options2?.currentOptions ?? this.options.password;
+        return verifyPassword(password, storedHash, {
+          ...options2,
+          ...currentOptions ? { currentOptions } : {}
+        });
+      },
+      needsRehash: (storedHash, options2) => needsRehash(storedHash, { ...this.options.password, ...options2 })
+    };
+    this.crypto = {
+      encryptText: (plainText, secret, options2) => encryptText(plainText, secret, { ...this.options.encryption, ...options2 }),
+      decryptText,
+      encryptJson: (data, secret, options2) => encryptJson(data, secret, { ...this.options.encryption, ...options2 }),
+      decryptJson,
+      encryptBuffer: (buffer, secret, options2) => encryptBuffer(buffer, secret, { ...this.options.encryption, ...options2 }),
+      decryptBuffer,
+      encryptFile: (inputPath, outputPath, secret, options2) => encryptFile(inputPath, outputPath, secret, { ...this.options.encryption, ...options2 }),
+      decryptFile
+    };
+  }
+  options;
+  password;
+  crypto;
+  hash(password, options) {
+    return this.password.hash(password, options);
+  }
+  verify(password, storedHash, options) {
+    return this.password.verify(password, storedHash, options);
+  }
+  async encrypt(data, secret, options) {
+    if (Buffer.isBuffer(data)) {
+      return this.crypto.encryptBuffer(data, secret, options);
+    }
+    if (typeof data === "string") {
+      return this.crypto.encryptText(data, secret, options);
+    }
+    if (data && typeof data === "object") {
+      return this.crypto.encryptJson(data, secret, options);
+    }
+    throw new InvalidPayloadError("encrypt() supports strings, Buffers, objects, and arrays.");
+  }
+  async decrypt(payload, secret, options) {
+    if (options?.as === "buffer") {
+      return this.crypto.decryptBuffer(payload, secret, options);
+    }
+    const decryptedText = await this.crypto.decryptText(payload, secret, options);
+    if (options?.as === "json") {
+      return JSON.parse(decryptedText);
+    }
+    const detected = detectPayload(decryptedText);
+    if (detected === "json") {
+      try {
+        return JSON.parse(decryptedText);
+      } catch {
+        return decryptedText;
+      }
+    }
+    return decryptedText;
+  }
+  decryptPasswordHash() {
+    throw new InvalidPayloadError("Password hashes cannot be decrypted. Use verifyPassword() or vault.password.verify().");
+  }
+};
+
+// src/client/createSecureHashVault.ts
+function createCipherForge(options = {}) {
+  return new SecureHashVaultClient(options);
+}
+var createCipherVault = createCipherForge;
+var createSecureHashVault = createCipherVault;
+
+// src/index.ts
+var cipherForge = createCipherForge();
+var CipherForge = cipherForge;
+var cipherVault = cipherForge;
+var secureVault = cipherForge;
+var index_default = cipherForge;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CipherForge,
+  CipherForgeError,
+  CipherVaultError,
+  DecryptionError,
+  EncryptionError,
+  InvalidConfigError,
+  InvalidPasswordHashError,
+  InvalidPayloadError,
+  PasswordVerificationError,
+  SecureHashVaultClient,
+  SecureHashVaultError,
+  cipherForge,
+  cipherVault,
+  createCipherForge,
+  createCipherVault,
+  createSecureHashVault,
+  decryptBuffer,
+  decryptFile,
+  decryptJson,
+  decryptText,
+  detectPayload,
+  encryptBuffer,
+  encryptFile,
+  encryptJson,
+  encryptText,
+  fromBase64Url,
+  fromHex,
+  generatePepper,
+  generateSalt,
+  hashPassword,
+  needsRehash,
+  randomBuffer,
+  secureVault,
+  toBase64Url,
+  toHex,
+  verifyPassword
+});
+//# sourceMappingURL=index.cjs.map