@ohos-ports/react-native-quick-crypto 0.0.0-stage → 1.1.8-beta.0

package/ohos/quick_crypto_napi.cpp

@@ -0,0 +1,1316 @@
+// quick_crypto_napi.cpp
+//
+// Standalone N-API binding for react-native-quick-crypto core crypto on
+// HarmonyOS Node.js (user-space node from harmonybrew, ABI module 147).
+//
+// The upstream crypto core is implemented as C++20 Nitro HybridObjects under
+// cpp/ (HybridHash, HybridCipher, HybridRandom, ...) which can only be
+// instantiated through the react-native-nitro-modules JSI host inside a React
+// Native app. On standalone HarmonyOS Node.js that host is unavailable.
+//
+// This binding re-implements the *same OpenSSL operations* used by the
+// HybridObject implementations (see cpp/hash/HybridHash.cpp for the EVP
+// digest flow, deps/ncrypto/src/ncrypto.cpp for the ARGON2 KDF flow) and
+// exposes them as a plain N-API addon, so the crypto functionality becomes
+// natively loadable in HarmonyOS Node.js with OpenSSL 3.6.
+//
+// Everything here is a real OpenSSL implementation — no stubs, no fakes.
+
+#include <node_api.h>
+
+#include <blake3.h>
+
+#include <openssl/core_names.h>
+#include <openssl/crypto.h>
+#include <openssl/err.h>
+#include <openssl/evp.h>
+#include <openssl/kdf.h>
+#include <openssl/params.h>
+#include <openssl/rand.h>
+
+#include <algorithm>
+#include <cctype>
+#include <cstdint>
+#include <cstring>
+#include <string>
+#include <vector>
+
+#include <openssl/hmac.h>
+
+namespace {
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+std::string GetOpenSSLError() {
+  unsigned long code = ERR_get_error();
+  if (code == 0) return std::string();
+  char buf[256];
+  ERR_error_string_n(code, buf, sizeof(buf));
+  ERR_clear_error();
+  return std::string(buf);
+}
+
+napi_value ThrowJsError(napi_env env, const std::string& message) {
+  napi_throw_error(env, nullptr, message.c_str());
+  return nullptr;
+}
+
+napi_value ThrowOpenSSLError(napi_env env, const std::string& what) {
+  std::string err = GetOpenSSLError();
+  return ThrowJsError(env, err.empty() ? what : what + ": " + err);
+}
+
+// Accepts string | ArrayBuffer | TypedArray (incl. Buffer).
+bool GetData(napi_env env, napi_value value, const uint8_t** data,
+             size_t* len) {
+  napi_valuetype type;
+  if (napi_typeof(env, value, &type) != napi_ok) return false;
+  if (type == napi_string) {
+    size_t slen = 0;
+    napi_get_value_string_utf8(env, value, nullptr, 0, &slen);
+    std::string* holder = new std::string(slen, '\0');
+    napi_get_value_string_utf8(env, value, &(*holder)[0], slen + 1, &slen);
+    // NOTE: string data outlives this call because the JS engine copies the
+    // bytes into OpenSSL state synchronously within the same native call.
+    *data = reinterpret_cast<const uint8_t*>(holder->data());
+    *len = slen;
+    return true;
+  }
+  bool is_typed = false;
+  bool is_ab = false;
+  napi_is_typedarray(env, value, &is_typed);
+  napi_is_arraybuffer(env, value, &is_ab);
+  if (is_typed) {
+    napi_typedarray_type tt;
+    size_t length = 0, offset = 0;
+    void* ptr = nullptr;
+    napi_value ab;
+    if (napi_get_typedarray_info(env, value, &tt, &length, &ptr, &ab,
+                                 &offset) != napi_ok)
+      return false;
+    // ptr already points at the element window (offset applied).
+    *data = reinterpret_cast<const uint8_t*>(ptr);
+    *len = length;
+    return true;
+  }
+  if (is_ab) {
+    void* ptr = nullptr;
+    size_t length = 0;
+    if (napi_get_arraybuffer_info(env, value, &ptr, &length) != napi_ok)
+      return false;
+    *data = reinterpret_cast<const uint8_t*>(ptr);
+    *len = length;
+    return true;
+  }
+  return false;
+}
+
+bool GetString(napi_env env, napi_value value, std::string* out) {
+  napi_valuetype type;
+  if (napi_typeof(env, value, &type) != napi_ok || type != napi_string)
+    return false;
+  size_t len = 0;
+  napi_get_value_string_utf8(env, value, nullptr, 0, &len);
+  out->resize(len);
+  napi_get_value_string_utf8(env, value, &(*out)[0], len + 1, &len);
+  return true;
+}
+
+bool GetUint64(napi_env env, napi_value value, uint64_t* out) {
+  napi_valuetype type;
+  if (napi_typeof(env, value, &type) != napi_ok || type != napi_number)
+    return false;
+  double d = 0;
+  napi_get_value_double(env, value, &d);
+  if (d < 0) return false;
+  *out = static_cast<uint64_t>(d);
+  return true;
+}
+
+bool GetBool(napi_env env, napi_value value, bool* out) {
+  napi_valuetype type;
+  if (napi_typeof(env, value, &type) != napi_ok || type != napi_boolean)
+    return false;
+  napi_get_value_bool(env, value, out);
+  return true;
+}
+
+napi_value MakeArrayBuffer(napi_env env, const uint8_t* data, size_t len) {
+  void* out = nullptr;
+  napi_value result;
+  if (napi_create_arraybuffer(env, len, &out, &result) != napi_ok)
+    return nullptr;
+  if (len > 0 && data != nullptr) memcpy(out, data, len);
+  return result;
+}
+
+template <typename T>
+napi_value MakeExternal(napi_env env, T* ptr) {
+  napi_value result;
+  napi_finalize finalize = [](napi_env /*env*/, void* data,
+                              void* /*hint*/) { delete static_cast<T*>(data); };
+  if (napi_create_external(env, ptr, finalize, nullptr, &result) != napi_ok) {
+    delete ptr;
+    return nullptr;
+  }
+  return result;
+}
+
+template <typename T>
+T* GetExternal(napi_env env, napi_value value) {
+  void* ptr = nullptr;
+  if (napi_get_value_external(env, value, &ptr) != napi_ok) return nullptr;
+  return static_cast<T*>(ptr);
+}
+
+// ---------------------------------------------------------------------------
+// Hash (mirrors cpp/hash/HybridHash.cpp)
+// ---------------------------------------------------------------------------
+
+struct HashContext {
+  EVP_MD_CTX* ctx = nullptr;
+  EVP_MD* md = nullptr;
+  std::string algorithm;
+  size_t outputLength = 0;  // 0 = default; only for XOF
+  bool isXof = false;
+  ~HashContext() {
+    if (ctx) EVP_MD_CTX_free(ctx);
+    if (md) EVP_MD_free(md);
+  }
+};
+
+EVP_MD* FetchMdOrThrow(napi_env env, const std::string& alg) {
+  EVP_MD* md = EVP_MD_fetch(nullptr, alg.c_str(), nullptr);
+  if (!md) {
+    std::string err = GetOpenSSLError();
+    std::string msg = "Unknown hash algorithm: " + alg;
+    if (!err.empty()) msg += " (" + err + ")";
+    napi_throw_error(env, nullptr, msg.c_str());
+    return nullptr;
+  }
+  return md;
+}
+
+napi_value HashCreate(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "hashCreate: algorithm is required");
+
+  std::string alg;
+  if (!GetString(env, argv[0], &alg))
+    return ThrowJsError(env, "hashCreate: algorithm must be a string");
+
+  uint64_t outputLength = 0;
+  bool hasOutputLength = false;
+  if (argc >= 2) {
+    napi_valuetype t;
+    napi_typeof(env, argv[1], &t);
+    if (t == napi_number) {
+      hasOutputLength = true;
+      if (!GetUint64(env, argv[1], &outputLength))
+        return ThrowJsError(env, "Invalid digest output length");
+    }
+  }
+
+  EVP_MD* md = FetchMdOrThrow(env, alg);
+  if (!md) return nullptr;
+
+  bool isXof = (EVP_MD_get_flags(md) & EVP_MD_FLAG_XOF) != 0;
+  if (hasOutputLength && !isXof) {
+    EVP_MD_free(md);
+    return ThrowJsError(
+        env, "outputLength is only supported for XOF hash algorithms (shake128/shake256)");
+  }
+  if (hasOutputLength && outputLength == 0) {
+    EVP_MD_free(md);
+    return ThrowJsError(env, "Invalid digest output length: 0");
+  }
+
+  EVP_MD_CTX* ctx = EVP_MD_CTX_new();
+  if (!ctx) {
+    EVP_MD_free(md);
+    return ThrowOpenSSLError(env, "Failed to create hash context");
+  }
+  if (EVP_DigestInit_ex(ctx, md, nullptr) != 1) {
+    EVP_MD_CTX_free(ctx);
+    EVP_MD_free(md);
+    return ThrowOpenSSLError(env, "Failed to initialize hash digest");
+  }
+
+  HashContext* h = new HashContext();
+  h->ctx = ctx;
+  h->md = md;
+  h->algorithm = alg;
+  h->outputLength = static_cast<size_t>(outputLength);
+  h->isXof = isXof;
+  return MakeExternal(env, h);
+}
+
+napi_value HashUpdate(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "hashUpdate: (hash, data) required");
+  HashContext* h = GetExternal<HashContext>(env, argv[0]);
+  if (!h || !h->ctx) return ThrowJsError(env, "Hash context not initialized");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &data, &len))
+    return ThrowJsError(env, "hashUpdate: data must be a string, Buffer, or ArrayBuffer");
+  if (len > 0 && EVP_DigestUpdate(h->ctx, data, len) != 1)
+    return ThrowOpenSSLError(env, "Failed to update hash digest");
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+napi_value HashDigest(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "hashDigest: hash external required");
+  HashContext* h = GetExternal<HashContext>(env, argv[0]);
+  if (!h || !h->ctx) return ThrowJsError(env, "Hash context not initialized");
+
+  // Optional per-call output length override (XOF)
+  size_t digestSize = h->outputLength > 0
+                          ? h->outputLength
+                          : static_cast<size_t>(EVP_MD_get_size(h->md) > 0
+                                                    ? EVP_MD_get_size(h->md)
+                                                    : 32);
+  if (argc >= 2) {
+    napi_valuetype t;
+    napi_typeof(env, argv[1], &t);
+    if (t == napi_number) {
+      uint64_t override = 0;
+      if (!GetUint64(env, argv[1], &override) || override == 0)
+        return ThrowJsError(env, "Invalid digest output length");
+      if (!h->isXof)
+        return ThrowJsError(env, "outputLength is only supported for XOF hash algorithms");
+      digestSize = static_cast<size_t>(override);
+    }
+  }
+
+  // Work on a copy so the hash stays usable after digest() (Node parity).
+  EVP_MD_CTX* tmp = EVP_MD_CTX_new();
+  if (!tmp) return ThrowOpenSSLError(env, "Failed to copy hash context");
+  if (EVP_MD_CTX_copy_ex(tmp, h->ctx) != 1) {
+    EVP_MD_CTX_free(tmp);
+    return ThrowOpenSSLError(env, "Failed to copy hash context");
+  }
+
+  std::vector<uint8_t> out(digestSize);
+  unsigned int outLen = 0;
+  int ret;
+  if (h->isXof && digestSize > 0) {
+    // set XOF length param like HybridHash::setParams
+    uint32_t xoflen = static_cast<uint32_t>(digestSize);
+    OSSL_PARAM params[2] = {
+        OSSL_PARAM_construct_uint("xoflen", &xoflen),
+        OSSL_PARAM_construct_end()};
+    if (EVP_MD_CTX_set_params(tmp, params) != 1) {
+      std::string err = GetOpenSSLError();
+      EVP_MD_CTX_free(tmp);
+      return ThrowJsError(env, "Failed to set XOF length parameter: " + err);
+    }
+    ret = EVP_DigestFinalXOF(tmp, out.data(), out.size());
+  } else {
+    ret = EVP_DigestFinal_ex(tmp, out.data(), &outLen);
+  }
+  EVP_MD_CTX_free(tmp);
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to finalize hash digest");
+
+  size_t finalLen = (h->isXof && digestSize > 0) ? out.size() : outLen;
+  return MakeArrayBuffer(env, out.data(), finalLen);
+}
+
+napi_value HashCopy(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "hashCopy: hash external required");
+  HashContext* h = GetExternal<HashContext>(env, argv[0]);
+  if (!h || !h->ctx) return ThrowJsError(env, "Hash context not initialized");
+
+  EVP_MD* md = FetchMdOrThrow(env, h->algorithm);
+  if (!md) return nullptr;
+  EVP_MD_CTX* ctx = EVP_MD_CTX_new();
+  if (!ctx) {
+    EVP_MD_free(md);
+    return ThrowOpenSSLError(env, "Failed to create hash context");
+  }
+  if (EVP_MD_CTX_copy_ex(ctx, h->ctx) != 1) {
+    EVP_MD_CTX_free(ctx);
+    EVP_MD_free(md);
+    return ThrowOpenSSLError(env, "Failed to copy hash context");
+  }
+  HashContext* copy = new HashContext();
+  copy->ctx = ctx;
+  copy->md = md;
+  copy->algorithm = h->algorithm;
+  copy->outputLength = h->outputLength;
+  copy->isXof = h->isXof;
+  return MakeExternal(env, copy);
+}
+
+napi_value HashOneShot(napi_env env, napi_callback_info info) {
+  size_t argc = 3;
+  napi_value argv[3];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "hash: (algorithm, data) required");
+  std::string alg;
+  if (!GetString(env, argv[0], &alg))
+    return ThrowJsError(env, "hash: algorithm must be a string");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &data, &len))
+    return ThrowJsError(env, "hash: data must be a string, Buffer, or ArrayBuffer");
+
+  uint64_t outputLength = 0;
+  if (argc >= 3) GetUint64(env, argv[2], &outputLength);
+
+  EVP_MD* md = FetchMdOrThrow(env, alg);
+  if (!md) return nullptr;
+  EVP_MD_CTX* ctx = EVP_MD_CTX_new();
+  if (!ctx) {
+    EVP_MD_free(md);
+    return ThrowOpenSSLError(env, "Failed to create hash context");
+  }
+  if (EVP_DigestInit_ex(ctx, md, nullptr) != 1 ||
+      (len > 0 && EVP_DigestUpdate(ctx, data, len) != 1)) {
+    EVP_MD_CTX_free(ctx);
+    EVP_MD_free(md);
+    return ThrowOpenSSLError(env, "Failed to compute hash");
+  }
+  std::vector<uint8_t> out;
+  if ((EVP_MD_get_flags(md) & EVP_MD_FLAG_XOF) && outputLength > 0) {
+    out.resize(static_cast<size_t>(outputLength));
+    if (EVP_DigestFinalXOF(ctx, out.data(), out.size()) != 1) {
+      EVP_MD_CTX_free(ctx);
+      EVP_MD_free(md);
+      return ThrowOpenSSLError(env, "Failed to finalize hash digest");
+    }
+  } else {
+    out.resize(static_cast<size_t>(EVP_MD_get_size(md)));
+    unsigned int outLen = 0;
+    if (EVP_DigestFinal_ex(ctx, out.data(), &outLen) != 1) {
+      EVP_MD_CTX_free(ctx);
+      EVP_MD_free(md);
+      return ThrowOpenSSLError(env, "Failed to finalize hash digest");
+    }
+    out.resize(outLen);
+  }
+  EVP_MD_CTX_free(ctx);
+  EVP_MD_free(md);
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+// ---------------------------------------------------------------------------
+// HMAC (mirrors cpp/hmac/HybridHmac.cpp)
+// ---------------------------------------------------------------------------
+
+struct HmacContext {
+  EVP_MAC* mac = nullptr;
+  EVP_MAC_CTX* ctx = nullptr;
+  std::string algorithm;
+  ~HmacContext() {
+    if (ctx) EVP_MAC_CTX_free(ctx);
+    if (mac) EVP_MAC_free(mac);
+  }
+};
+
+napi_value HmacCreate(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2)
+    return ThrowJsError(env, "hmacCreate: (algorithm, key) required");
+  std::string alg;
+  if (!GetString(env, argv[0], &alg))
+    return ThrowJsError(env, "hmacCreate: algorithm must be a string");
+  const uint8_t* key = nullptr;
+  size_t keyLen = 0;
+  if (!GetData(env, argv[1], &key, &keyLen))
+    return ThrowJsError(env, "hmacCreate: key must be a string, Buffer, or ArrayBuffer");
+
+  EVP_MAC* mac = EVP_MAC_fetch(nullptr, "HMAC", nullptr);
+  if (!mac) return ThrowOpenSSLError(env, "Failed to fetch HMAC");
+  EVP_MAC_CTX* ctx = EVP_MAC_CTX_new(mac);
+  if (!ctx) {
+    EVP_MAC_free(mac);
+    return ThrowOpenSSLError(env, "Failed to create HMAC context");
+  }
+  std::string digest = alg;
+  OSSL_PARAM params[2] = {
+      OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, &digest[0], 0),
+      OSSL_PARAM_construct_end()};
+  if (EVP_MAC_init(ctx, keyLen > 0 ? key : reinterpret_cast<const uint8_t*>(""),
+                   keyLen, params) != 1) {
+    std::string err = GetOpenSSLError();
+    EVP_MAC_CTX_free(ctx);
+    EVP_MAC_free(mac);
+    return ThrowJsError(env, "Unknown HMAC digest algorithm: " + alg +
+                                 (err.empty() ? "" : " (" + err + ")"));
+  }
+  HmacContext* h = new HmacContext();
+  h->mac = mac;
+  h->ctx = ctx;
+  h->algorithm = alg;
+  return MakeExternal(env, h);
+}
+
+napi_value HmacUpdate(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "hmacUpdate: (hmac, data) required");
+  HmacContext* h = GetExternal<HmacContext>(env, argv[0]);
+  if (!h || !h->ctx) return ThrowJsError(env, "HMAC context not initialized");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &data, &len))
+    return ThrowJsError(env, "hmacUpdate: data must be a string, Buffer, or ArrayBuffer");
+  if (len > 0 && EVP_MAC_update(h->ctx, data, len) != 1)
+    return ThrowOpenSSLError(env, "Failed to update HMAC");
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+napi_value HmacDigest(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "hmacDigest: hmac external required");
+  HmacContext* h = GetExternal<HmacContext>(env, argv[0]);
+  if (!h || !h->ctx) return ThrowJsError(env, "HMAC context not initialized");
+  size_t size = EVP_MAC_CTX_get_mac_size(h->ctx);
+  std::vector<uint8_t> out(size ? size : 1);
+  size_t outLen = 0;
+  if (EVP_MAC_final(h->ctx, out.data(), &outLen, out.size()) != 1)
+    return ThrowOpenSSLError(env, "Failed to finalize HMAC");
+  return MakeArrayBuffer(env, out.data(), outLen);
+}
+
+napi_value HmacOneShot(napi_env env, napi_callback_info info) {
+  size_t argc = 3;
+  napi_value argv[3];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 3) return ThrowJsError(env, "hmac: (algorithm, key, data) required");
+  std::string alg;
+  if (!GetString(env, argv[0], &alg))
+    return ThrowJsError(env, "hmac: algorithm must be a string");
+  const uint8_t* key = nullptr;
+  size_t keyLen = 0;
+  if (!GetData(env, argv[1], &key, &keyLen))
+    return ThrowJsError(env, "hmac: key must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[2], &data, &len))
+    return ThrowJsError(env, "hmac: data must be a string, Buffer, or ArrayBuffer");
+
+  EVP_MAC* mac = EVP_MAC_fetch(nullptr, "HMAC", nullptr);
+  if (!mac) return ThrowOpenSSLError(env, "Failed to fetch HMAC");
+  EVP_MAC_CTX* mctx = EVP_MAC_CTX_new(mac);
+  if (!mctx) {
+    EVP_MAC_free(mac);
+    return ThrowOpenSSLError(env, "Failed to create HMAC context");
+  }
+  std::string digest = alg;
+  OSSL_PARAM mparams[2] = {
+      OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, &digest[0], 0),
+      OSSL_PARAM_construct_end()};
+  size_t outLen = 0;
+  bool ok = EVP_MAC_init(mctx, keyLen > 0 ? key : reinterpret_cast<const uint8_t*>(""),
+                          keyLen, mparams) == 1;
+  std::vector<uint8_t> out;
+  if (ok) {
+    out.resize(EVP_MAC_CTX_get_mac_size(mctx));
+    ok = (len == 0 || EVP_MAC_update(mctx, data, len) == 1) &&
+         EVP_MAC_final(mctx, out.data(), &outLen, out.size()) == 1;
+  }
+  EVP_MAC_CTX_free(mctx);
+  EVP_MAC_free(mac);
+  if (!ok) return ThrowOpenSSLError(env, "Failed to compute HMAC");
+  return MakeArrayBuffer(env, out.data(), outLen);
+}
+
+// ---------------------------------------------------------------------------
+// Random (mirrors cpp/random/HybridRandom.cpp)
+// ---------------------------------------------------------------------------
+
+napi_value RandomBytes(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "randomBytes: size required");
+  uint64_t size = 0;
+  if (!GetUint64(env, argv[0], &size))
+    return ThrowJsError(env, "randomBytes: size must be a non-negative number");
+  if (size > 0x7fffffff)
+    return ThrowJsError(env, "randomBytes: size must be <= 2^31 - 1");
+  std::vector<uint8_t> out(static_cast<size_t>(size));
+  if (size > 0 && RAND_bytes(out.data(), static_cast<int>(size)) != 1)
+    return ThrowOpenSSLError(env, "Failed to generate random bytes");
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+// ---------------------------------------------------------------------------
+// KDFs: PBKDF2 / scrypt / HKDF / Argon2
+// ---------------------------------------------------------------------------
+
+napi_value Pbkdf2Sync(napi_env env, napi_callback_info info) {
+  size_t argc = 5;
+  napi_value argv[5];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 5)
+    return ThrowJsError(env, "pbkdf2Sync: (password, salt, iterations, keylen, digest) required");
+  const uint8_t* pw = nullptr;
+  size_t pwLen = 0;
+  if (!GetData(env, argv[0], &pw, &pwLen))
+    return ThrowJsError(env, "pbkdf2Sync: password must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* salt = nullptr;
+  size_t saltLen = 0;
+  if (!GetData(env, argv[1], &salt, &saltLen))
+    return ThrowJsError(env, "pbkdf2Sync: salt must be a string, Buffer, or ArrayBuffer");
+  uint64_t iterations = 0, keylen = 0;
+  if (!GetUint64(env, argv[2], &iterations))
+    return ThrowJsError(env, "pbkdf2Sync: iterations must be a non-negative number");
+  if (!GetUint64(env, argv[3], &keylen) || keylen == 0)
+    return ThrowJsError(env, "pbkdf2Sync: keylen must be a positive number");
+  std::string digest;
+  if (!GetString(env, argv[4], &digest))
+    return ThrowJsError(env, "pbkdf2Sync: digest must be a string");
+  EVP_MD* md = FetchMdOrThrow(env, digest);
+  if (!md) return nullptr;
+  std::vector<uint8_t> out(static_cast<size_t>(keylen));
+  int ret = PKCS5_PBKDF2_HMAC(reinterpret_cast<const char*>(pwLen > 0 ? pw : reinterpret_cast<const uint8_t*>("")),
+                              static_cast<int>(pwLen),
+                              saltLen > 0 ? salt : reinterpret_cast<const uint8_t*>(""),
+                              static_cast<int>(saltLen),
+                              static_cast<int>(iterations), md, out.size(), out.data());
+  EVP_MD_free(md);
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to derive PBKDF2 key");
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+napi_value ScryptSync(napi_env env, napi_callback_info info) {
+  size_t argc = 7;
+  napi_value argv[7];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 6)
+    return ThrowJsError(env, "scryptSync: (password, salt, keylen, N, r, p[, maxmem]) required");
+  const uint8_t* pw = nullptr;
+  size_t pwLen = 0;
+  if (!GetData(env, argv[0], &pw, &pwLen))
+    return ThrowJsError(env, "scryptSync: password must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* salt = nullptr;
+  size_t saltLen = 0;
+  if (!GetData(env, argv[1], &salt, &saltLen))
+    return ThrowJsError(env, "scryptSync: salt must be a string, Buffer, or ArrayBuffer");
+  uint64_t keylen = 0, N = 0, r = 0, p = 0, maxmem = 0;
+  if (!GetUint64(env, argv[2], &keylen) || keylen == 0)
+    return ThrowJsError(env, "scryptSync: keylen must be a positive number");
+  if (!GetUint64(env, argv[3], &N) || N < 2 || (N & (N - 1)) != 0)
+    return ThrowJsError(env, "scryptSync: N must be a power of 2 greater than 1");
+  if (!GetUint64(env, argv[4], &r) || r == 0)
+    return ThrowJsError(env, "scryptSync: r must be a positive number");
+  if (!GetUint64(env, argv[5], &p) || p == 0)
+    return ThrowJsError(env, "scryptSync: p must be a positive number");
+  if (argc >= 7) {
+    if (!GetUint64(env, argv[6], &maxmem))
+      return ThrowJsError(env, "scryptSync: maxmem must be a non-negative number");
+  } else {
+    maxmem = 0;  // OpenSSL default
+  }
+  std::vector<uint8_t> out(static_cast<size_t>(keylen));
+  if (EVP_PBE_scrypt(reinterpret_cast<const char*>(pwLen > 0 ? pw : reinterpret_cast<const uint8_t*>("")),
+                     pwLen,
+                     saltLen > 0 ? salt : reinterpret_cast<const uint8_t*>(""),
+                     saltLen, N, r, p, maxmem, out.data(), out.size()) != 1)
+    return ThrowOpenSSLError(env, "Failed to derive scrypt key");
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+// HKDF extract+expand one-shot (mirrors lib hkdfSync flow).
+napi_value HkdfSync(napi_env env, napi_callback_info info) {
+  size_t argc = 5;
+  napi_value argv[5];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 5)
+    return ThrowJsError(env, "hkdfSync: (digest, ikm, salt, info, keylen) required");
+  std::string digest;
+  if (!GetString(env, argv[0], &digest))
+    return ThrowJsError(env, "hkdfSync: digest must be a string");
+  const uint8_t* ikm = nullptr;
+  size_t ikmLen = 0;
+  if (!GetData(env, argv[1], &ikm, &ikmLen))
+    return ThrowJsError(env, "hkdfSync: ikm must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* salt = nullptr;
+  size_t saltLen = 0;
+  if (!GetData(env, argv[2], &salt, &saltLen))
+    return ThrowJsError(env, "hkdfSync: salt must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* infoData = nullptr;
+  size_t infoLen = 0;
+  if (!GetData(env, argv[3], &infoData, &infoLen))
+    return ThrowJsError(env, "hkdfSync: info must be a string, Buffer, or ArrayBuffer");
+  uint64_t keylen = 0;
+  if (!GetUint64(env, argv[4], &keylen) || keylen == 0)
+    return ThrowJsError(env, "hkdfSync: keylen must be a positive number");
+
+  EVP_KDF* kdf = EVP_KDF_fetch(nullptr, "HKDF", nullptr);
+  if (!kdf) return ThrowOpenSSLError(env, "Failed to fetch HKDF");
+  EVP_KDF_CTX* kctx = EVP_KDF_CTX_new(kdf);
+  EVP_KDF_free(kdf);
+  if (!kctx) return ThrowOpenSSLError(env, "Failed to create HKDF context");
+
+  std::string mode = "EXTRACT_AND_EXPAND";
+  std::string mdName = digest;
+  OSSL_PARAM params[6] = {
+      OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, &mdName[0], 0),
+      OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, &mode[0], 0),
+      OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
+                                        const_cast<uint8_t*>(ikmLen > 0 ? ikm : reinterpret_cast<const uint8_t*>("")),
+                                        ikmLen),
+      OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
+                                        const_cast<uint8_t*>(saltLen > 0 ? salt : reinterpret_cast<const uint8_t*>("")),
+                                        saltLen),
+      OSSL_PARAM_construct_octet_string("info",
+                                        const_cast<uint8_t*>(infoLen > 0 ? infoData : reinterpret_cast<const uint8_t*>("")),
+                                        infoLen),
+      OSSL_PARAM_construct_end()};
+  std::vector<uint8_t> out(static_cast<size_t>(keylen));
+  int ret = EVP_KDF_derive(kctx, out.data(), out.size(), params);
+  EVP_KDF_CTX_free(kctx);
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to derive HKDF key");
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+// Argon2 via OpenSSL 3.2+ ARGON2* KDF (mirrors deps/ncrypto/src/ncrypto.cpp argon2()).
+napi_value Argon2Sync(napi_env env, napi_callback_info info) {
+  size_t argc = 10;
+  napi_value argv[10];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 8)
+    return ThrowJsError(env, "argon2Sync: (algorithm, message, nonce, parallelism, tagLength, memory, passes, version[, secret][, ad]) required");
+  std::string alg;
+  if (!GetString(env, argv[0], &alg))
+    return ThrowJsError(env, "argon2Sync: algorithm must be a string");
+  std::string kdfName;
+  if (alg == "argon2d") kdfName = "ARGON2D";
+  else if (alg == "argon2i") kdfName = "ARGON2I";
+  else if (alg == "argon2id") kdfName = "ARGON2ID";
+  else return ThrowJsError(env, "Unknown argon2 algorithm: " + alg);
+
+  const uint8_t* msg = nullptr;
+  size_t msgLen = 0;
+  if (!GetData(env, argv[1], &msg, &msgLen))
+    return ThrowJsError(env, "argon2Sync: message must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* nonce = nullptr;
+  size_t nonceLen = 0;
+  if (!GetData(env, argv[2], &nonce, &nonceLen))
+    return ThrowJsError(env, "argon2Sync: nonce must be a string, Buffer, or ArrayBuffer");
+  uint64_t parallelism = 0, tagLength = 0, memory = 0, passes = 0, version = 0;
+  if (!GetUint64(env, argv[3], &parallelism) || parallelism == 0)
+    return ThrowJsError(env, "argon2Sync: parallelism must be >= 1");
+  if (!GetUint64(env, argv[4], &tagLength) || tagLength < 4)
+    return ThrowJsError(env, "argon2Sync: tagLength must be >= 4");
+  if (!GetUint64(env, argv[5], &memory) || memory == 0)
+    return ThrowJsError(env, "argon2Sync: memory (KiB) must be >= 1");
+  if (!GetUint64(env, argv[6], &passes) || passes == 0)
+    return ThrowJsError(env, "argon2Sync: passes must be >= 1");
+  if (!GetUint64(env, argv[7], &version))
+    return ThrowJsError(env, "argon2Sync: version must be a number");
+
+  const uint8_t* secret = nullptr;
+  size_t secretLen = 0;
+  if (argc >= 9) {
+    napi_valuetype t;
+    napi_typeof(env, argv[8], &t);
+    if (t != napi_undefined && t != napi_null) GetData(env, argv[8], &secret, &secretLen);
+  }
+  const uint8_t* ad = nullptr;
+  size_t adLen = 0;
+  if (argc >= 10) {
+    napi_valuetype t;
+    napi_typeof(env, argv[9], &t);
+    if (t != napi_undefined && t != napi_null) GetData(env, argv[9], &ad, &adLen);
+  }
+
+  EVP_KDF* kdf = EVP_KDF_fetch(nullptr, kdfName.c_str(), nullptr);
+  if (!kdf) return ThrowOpenSSLError(env, "Failed to fetch " + kdfName);
+  EVP_KDF_CTX* kctx = EVP_KDF_CTX_new(kdf);
+  EVP_KDF_free(kdf);
+  if (!kctx) return ThrowOpenSSLError(env, "Failed to create ARGON2 KDF context");
+
+  uint32_t lanes = static_cast<uint32_t>(parallelism);
+  uint32_t memcost = static_cast<uint32_t>(memory);
+  uint32_t iter = static_cast<uint32_t>(passes);
+  uint32_t ver = static_cast<uint32_t>(version);
+
+  std::vector<OSSL_PARAM> params;
+  params.reserve(9);
+  params.push_back(OSSL_PARAM_construct_octet_string(
+      OSSL_KDF_PARAM_PASSWORD,
+      const_cast<uint8_t*>(msgLen > 0 ? msg : reinterpret_cast<const uint8_t*>("")), msgLen));
+  params.push_back(OSSL_PARAM_construct_octet_string(
+      OSSL_KDF_PARAM_SALT,
+      const_cast<uint8_t*>(nonceLen > 0 ? nonce : reinterpret_cast<const uint8_t*>("")), nonceLen));
+  params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES, &lanes));
+  // NOTE: OSSL_KDF_PARAM_THREADS intentionally omitted — it is an
+  // implementation-parallelism hint (requires a thread pool) and does not
+  // affect the derived key; ARGON2_LANES is the algorithmic parameter.
+  params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST, &memcost));
+  params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ITER, &iter));
+  params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_VERSION, &ver));
+  if (adLen != 0) {
+    params.push_back(OSSL_PARAM_construct_octet_string(
+        OSSL_KDF_PARAM_ARGON2_AD, const_cast<uint8_t*>(ad), adLen));
+  }
+  if (secretLen != 0) {
+    params.push_back(OSSL_PARAM_construct_octet_string(
+        OSSL_KDF_PARAM_SECRET, const_cast<uint8_t*>(secret), secretLen));
+  }
+  params.push_back(OSSL_PARAM_construct_end());
+
+  std::vector<uint8_t> out(static_cast<size_t>(tagLength));
+  int ret = EVP_KDF_derive(kctx, out.data(), out.size(), params.data());
+  EVP_KDF_CTX_free(kctx);
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to derive Argon2 key");
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+// ---------------------------------------------------------------------------
+// timingSafeEqual (mirrors cpp/utils/HybridUtils.cpp)
+// ---------------------------------------------------------------------------
+
+napi_value TimingSafeEqual(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "timingSafeEqual: (a, b) required");
+  const uint8_t* a = nullptr;
+  size_t aLen = 0;
+  const uint8_t* b = nullptr;
+  size_t bLen = 0;
+  if (!GetData(env, argv[0], &a, &aLen))
+    return ThrowJsError(env, "timingSafeEqual: first argument must be a string, Buffer, or ArrayBuffer");
+  if (!GetData(env, argv[1], &b, &bLen))
+    return ThrowJsError(env, "timingSafeEqual: second argument must be a string, Buffer, or ArrayBuffer");
+  if (aLen != bLen)
+    return ThrowJsError(env, "timingSafeEqual: input buffers must have the same byte length");
+  bool equal = aLen == 0 || CRYPTO_memcmp(a, b, aLen) == 0;
+  napi_value result;
+  napi_get_boolean(env, equal, &result);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Cipher (mirrors cpp/cipher/HybridCipher.cpp)
+// ---------------------------------------------------------------------------
+
+struct CipherContext {
+  EVP_CIPHER_CTX* ctx = nullptr;
+  bool encrypt = false;
+  bool authMode = false;
+  bool autoPad = true;
+  bool finalized = false;
+  size_t tagLen = 16;
+  ~CipherContext() {
+    if (ctx) EVP_CIPHER_CTX_free(ctx);
+  }
+};
+
+bool IsAuthMode(const std::string& algLower, int mode) {
+  (void)mode;
+  return algLower.find("gcm") != std::string::npos ||
+         algLower.find("ccm") != std::string::npos ||
+         algLower.find("ocb") != std::string::npos ||
+         algLower.find("siv") != std::string::npos ||
+         algLower.find("poly1305") != std::string::npos;
+}
+
+napi_value CipherCreate(napi_env env, napi_callback_info info) {
+  size_t argc = 4;
+  napi_value argv[4];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 3)
+    return ThrowJsError(env, "cipherCreate: (algorithm, key, iv, encrypt) required");
+  std::string alg;
+  if (!GetString(env, argv[0], &alg))
+    return ThrowJsError(env, "cipherCreate: algorithm must be a string");
+  const uint8_t* key = nullptr;
+  size_t keyLen = 0;
+  if (!GetData(env, argv[1], &key, &keyLen))
+    return ThrowJsError(env, "cipherCreate: key must be a string, Buffer, or ArrayBuffer");
+  const uint8_t* iv = nullptr;
+  size_t ivLen = 0;
+  bool hasIv = false;
+  {
+    napi_valuetype t;
+    napi_typeof(env, argv[2], &t);
+    if (t != napi_undefined && t != napi_null) {
+      hasIv = true;
+      if (!GetData(env, argv[2], &iv, &ivLen))
+        return ThrowJsError(env, "cipherCreate: iv must be a string, Buffer, or ArrayBuffer");
+    }
+  }
+  bool encrypt = false;
+  if (!GetBool(env, argv[3], &encrypt))
+    return ThrowJsError(env, "cipherCreate: encrypt must be a boolean");
+
+  EVP_CIPHER* cipher = EVP_CIPHER_fetch(nullptr, alg.c_str(), nullptr);
+  if (!cipher) {
+    std::string err = GetOpenSSLError();
+    return ThrowJsError(env, "Unknown cipher algorithm: " + alg +
+                                 (err.empty() ? "" : " (" + err + ")"));
+  }
+  std::string algLower = alg;
+  for (auto& c : algLower) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+  bool authMode = IsAuthMode(algLower, EVP_CIPHER_get_mode(cipher));
+
+  CipherContext* c = new CipherContext();
+  c->encrypt = encrypt;
+  c->authMode = authMode;
+  c->ctx = EVP_CIPHER_CTX_new();
+  if (!c->ctx) {
+    EVP_CIPHER_free(cipher);
+    delete c;
+    return ThrowOpenSSLError(env, "Failed to create cipher context");
+  }
+  int enc = encrypt ? 1 : 0;
+
+  // Validate / allow variable key length (like Node's checkCipherParameters).
+  int klen = EVP_CIPHER_get_key_length(cipher);
+  if (keyLen != static_cast<size_t>(klen)) {
+    if (EVP_CIPHER_CTX_set_key_length(c->ctx, static_cast<int>(keyLen)) != 1) {
+      std::string msg = "Invalid key length: got " + std::to_string(keyLen) +
+                        ", expected " + std::to_string(klen) + " for " + alg;
+      EVP_CIPHER_CTX_free(c->ctx);
+      EVP_CIPHER_free(cipher);
+      delete c;
+      return ThrowJsError(env, msg);
+    }
+  }
+
+  // For AEAD modes, set the IV length explicitly before key/iv init so that
+  // non-default IV sizes work (same as HybridCipher).
+  if (authMode && hasIv && ivLen > 0) {
+    if (EVP_CipherInit_ex2(c->ctx, cipher, nullptr, nullptr, enc, nullptr) != 1) {
+      std::string err = GetOpenSSLError();
+      EVP_CIPHER_CTX_free(c->ctx);
+      EVP_CIPHER_free(cipher);
+      delete c;
+      return ThrowJsError(env, "Failed to initialize cipher: " + err);
+    }
+    size_t ivLenParam = ivLen;
+    OSSL_PARAM ivParams[2] = {
+        OSSL_PARAM_construct_size_t(OSSL_CIPHER_PARAM_AEAD_IVLEN, &ivLenParam),
+        OSSL_PARAM_construct_end()};
+    if (EVP_CIPHER_CTX_set_params(c->ctx, ivParams) != 1) {
+      ERR_clear_error();  // non-fatal: fall back to default IV length
+    }
+    if (EVP_CipherInit_ex2(c->ctx, nullptr, key, iv, enc, nullptr) != 1) {
+      std::string err = GetOpenSSLError();
+      EVP_CIPHER_CTX_free(c->ctx);
+      EVP_CIPHER_free(cipher);
+      delete c;
+      return ThrowJsError(env, "Failed to initialize cipher: " + err);
+    }
+  } else {
+    if (EVP_CipherInit_ex2(c->ctx, cipher, key,
+                           hasIv && ivLen > 0 ? iv : nullptr, enc, nullptr) != 1) {
+      std::string err = GetOpenSSLError();
+      EVP_CIPHER_CTX_free(c->ctx);
+      EVP_CIPHER_free(cipher);
+      delete c;
+      return ThrowJsError(env, "Failed to initialize cipher: " + err);
+    }
+  }
+  EVP_CIPHER_free(cipher);
+  return MakeExternal(env, c);
+}
+
+napi_value CipherUpdate(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "cipherUpdate: (cipher, data) required");
+  CipherContext* c = GetExternal<CipherContext>(env, argv[0]);
+  if (!c || !c->ctx) return ThrowJsError(env, "Cipher context not initialized");
+  if (c->finalized) return ThrowJsError(env, "_CIPHER_FINALIZED");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &data, &len))
+    return ThrowJsError(env, "cipherUpdate: data must be a string, Buffer, or ArrayBuffer");
+  int blockSize = EVP_CIPHER_CTX_get_block_size(c->ctx);
+  if (blockSize <= 0) blockSize = 16;
+  std::vector<uint8_t> out(len + static_cast<size_t>(blockSize) + 16);
+  int outl = 0;
+  int ret = c->encrypt
+                ? EVP_EncryptUpdate(c->ctx, out.data(), &outl, len > 0 ? data : out.data(),
+                                    static_cast<int>(len))
+                : EVP_DecryptUpdate(c->ctx, out.data(), &outl, len > 0 ? data : out.data(),
+                                    static_cast<int>(len));
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to update cipher");
+  return MakeArrayBuffer(env, out.data(), static_cast<size_t>(outl > 0 ? outl : 0));
+}
+
+napi_value CipherSetAAD(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "cipherSetAAD: (cipher, data) required");
+  CipherContext* c = GetExternal<CipherContext>(env, argv[0]);
+  if (!c || !c->ctx) return ThrowJsError(env, "Cipher context not initialized");
+  if (!c->authMode) return ThrowJsError(env, "cipherSetAAD is only supported for AEAD ciphers");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &data, &len))
+    return ThrowJsError(env, "cipherSetAAD: data must be a string, Buffer, or ArrayBuffer");
+  int outl = 0;
+  int ret = c->encrypt
+                ? EVP_EncryptUpdate(c->ctx, nullptr, &outl, len > 0 ? data : reinterpret_cast<const uint8_t*>(""),
+                                    static_cast<int>(len))
+                : EVP_DecryptUpdate(c->ctx, nullptr, &outl, len > 0 ? data : reinterpret_cast<const uint8_t*>(""),
+                                    static_cast<int>(len));
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to set AAD");
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+napi_value CipherSetAutoPadding(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2)
+    return ThrowJsError(env, "cipherSetAutoPadding: (cipher, autoPadding) required");
+  CipherContext* c = GetExternal<CipherContext>(env, argv[0]);
+  if (!c || !c->ctx) return ThrowJsError(env, "Cipher context not initialized");
+  bool pad = true;
+  GetBool(env, argv[1], &pad);
+  if (EVP_CIPHER_CTX_set_padding(c->ctx, pad ? 1 : 0) != 1)
+    return ThrowOpenSSLError(env, "Failed to set auto padding");
+  c->autoPad = pad;
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+napi_value CipherFinal(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "cipherFinal: cipher external required");
+  CipherContext* c = GetExternal<CipherContext>(env, argv[0]);
+  if (!c || !c->ctx) return ThrowJsError(env, "Cipher context not initialized");
+  if (c->finalized) return ThrowJsError(env, "_CIPHER_FINALIZED");
+  int blockSize = EVP_CIPHER_CTX_get_block_size(c->ctx);
+  if (blockSize <= 0) blockSize = 16;
+  std::vector<uint8_t> out(static_cast<size_t>(blockSize) + 16);
+  int outl = 0;
+  int ret = c->encrypt ? EVP_EncryptFinal_ex(c->ctx, out.data(), &outl)
+                       : EVP_DecryptFinal_ex(c->ctx, out.data(), &outl);
+  c->finalized = true;
+  if (ret != 1) return ThrowOpenSSLError(env, "Failed to finalize cipher");
+  return MakeArrayBuffer(env, out.data(), static_cast<size_t>(outl > 0 ? outl : 0));
+}
+
+napi_value CipherGetAuthTag(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "cipherGetAuthTag: cipher external required");
+  CipherContext* c = GetExternal<CipherContext>(env, argv[0]);
+  if (!c || !c->ctx) return ThrowJsError(env, "Cipher context not initialized");
+  if (!c->encrypt)
+    return ThrowJsError(env, "getAuthTag is only supported on encryption");
+  size_t tagLen = c->tagLen;
+  if (argc >= 2) {
+    napi_valuetype t;
+    napi_typeof(env, argv[1], &t);
+    if (t == napi_number) {
+      uint64_t v = 0;
+      if (!GetUint64(env, argv[1], &v) || v == 0 || v > 1024)
+        return ThrowJsError(env, "Invalid auth tag length");
+      tagLen = static_cast<size_t>(v);
+    }
+  }
+  std::vector<uint8_t> out(tagLen);
+  if (EVP_CIPHER_CTX_ctrl(c->ctx, EVP_CTRL_AEAD_GET_TAG, static_cast<int>(tagLen),
+                          out.data()) != 1)
+    return ThrowOpenSSLError(env, "Failed to get auth tag");
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+napi_value CipherSetAuthTag(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "cipherSetAuthTag: (cipher, tag) required");
+  CipherContext* c = GetExternal<CipherContext>(env, argv[0]);
+  if (!c || !c->ctx) return ThrowJsError(env, "Cipher context not initialized");
+  if (c->encrypt)
+    return ThrowJsError(env, "setAuthTag is only supported on decryption");
+  const uint8_t* tag = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &tag, &len) || len == 0 || len > 1024)
+    return ThrowJsError(env, "Invalid auth tag");
+  if (EVP_CIPHER_CTX_ctrl(c->ctx, EVP_CTRL_AEAD_SET_TAG, static_cast<int>(len),
+                          const_cast<uint8_t*>(tag)) != 1)
+    return ThrowOpenSSLError(env, "Failed to set auth tag");
+  c->tagLen = len;
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+// ---------------------------------------------------------------------------
+// Blake3 (vendored deps/blake3/c, mirrors cpp/blake3/HybridBlake3.cpp)
+// ---------------------------------------------------------------------------
+
+struct Blake3Context {
+  blake3_hasher hasher = {};
+  int mode = 0;  // 0=hash, 1=keyed, 2=deriveKey
+  uint8_t key[BLAKE3_KEY_LEN] = {0};
+  std::string context;
+};
+
+napi_value Blake3InitHash(napi_env env, napi_callback_info) {
+  Blake3Context* b = new Blake3Context();
+  blake3_hasher_init(&b->hasher);
+  b->mode = 0;
+  return MakeExternal(env, b);
+}
+
+napi_value Blake3InitKeyed(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "blake3InitKeyed: key required");
+  const uint8_t* key = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[0], &key, &len) || len != BLAKE3_KEY_LEN)
+    return ThrowJsError(env, "BLAKE3: key must be exactly 32 bytes");
+  Blake3Context* b = new Blake3Context();
+  blake3_hasher_init_keyed(&b->hasher, key);
+  memcpy(b->key, key, BLAKE3_KEY_LEN);
+  b->mode = 1;
+  return MakeExternal(env, b);
+}
+
+napi_value Blake3InitDeriveKey(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "blake3InitDeriveKey: context required");
+  std::string context;
+  if (!GetString(env, argv[0], &context) || context.empty())
+    return ThrowJsError(env, "BLAKE3: context must be a non-empty string");
+  Blake3Context* b = new Blake3Context();
+  blake3_hasher_init_derive_key(&b->hasher, context.c_str());
+  b->mode = 2;
+  b->context = context;
+  return MakeExternal(env, b);
+}
+
+napi_value Blake3Update(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 2) return ThrowJsError(env, "blake3Update: (state, data) required");
+  Blake3Context* b = GetExternal<Blake3Context>(env, argv[0]);
+  if (!b) return ThrowJsError(env, "Blake3 state not initialized");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[1], &data, &len))
+    return ThrowJsError(env, "blake3Update: data must be a string, Buffer, or ArrayBuffer");
+  if (len > 0) blake3_hasher_update(&b->hasher, data, len);
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+napi_value Blake3Digest(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "blake3Digest: state required");
+  Blake3Context* b = GetExternal<Blake3Context>(env, argv[0]);
+  if (!b) return ThrowJsError(env, "Blake3 state not initialized");
+  uint64_t outLen = BLAKE3_OUT_LEN;
+  if (argc >= 2) {
+    napi_valuetype t;
+    napi_typeof(env, argv[1], &t);
+    if (t == napi_number && !GetUint64(env, argv[1], &outLen))
+      return ThrowJsError(env, "Invalid BLAKE3 output length");
+  }
+  if (outLen == 0 || outLen > 0x7fffffff)
+    return ThrowJsError(env, "Invalid BLAKE3 output length");
+  // work on a copy so state stays usable (Node/Blake3 parity)
+  Blake3Context copy = *b;
+  std::vector<uint8_t> out(static_cast<size_t>(outLen));
+  blake3_hasher_finalize(&copy.hasher, out.data(), out.size());
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+napi_value Blake3Copy(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "blake3Copy: state required");
+  Blake3Context* b = GetExternal<Blake3Context>(env, argv[0]);
+  if (!b) return ThrowJsError(env, "Blake3 state not initialized");
+  Blake3Context* copy = new Blake3Context(*b);
+  return MakeExternal(env, copy);
+}
+
+napi_value Blake3Reset(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "blake3Reset: state required");
+  Blake3Context* b = GetExternal<Blake3Context>(env, argv[0]);
+  if (!b) return ThrowJsError(env, "Blake3 state not initialized");
+  if (b->mode == 1)
+    blake3_hasher_init_keyed(&b->hasher, b->key);
+  else if (b->mode == 2) blake3_hasher_init_derive_key(&b->hasher, b->context.c_str());
+  else blake3_hasher_init(&b->hasher);
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+napi_value Blake3OneShot(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+  if (argc < 1) return ThrowJsError(env, "blake3: data required");
+  const uint8_t* data = nullptr;
+  size_t len = 0;
+  if (!GetData(env, argv[0], &data, &len))
+    return ThrowJsError(env, "blake3: data must be a string, Buffer, or ArrayBuffer");
+  uint64_t outLen = BLAKE3_OUT_LEN;
+  if (argc >= 2) GetUint64(env, argv[1], &outLen);
+  if (outLen == 0 || outLen > 0x7fffffff)
+    return ThrowJsError(env, "Invalid BLAKE3 output length");
+  blake3_hasher hasher;
+  blake3_hasher_init(&hasher);
+  if (len > 0) blake3_hasher_update(&hasher, data, len);
+  std::vector<uint8_t> out(static_cast<size_t>(outLen));
+  blake3_hasher_finalize(&hasher, out.data(), out.size());
+  return MakeArrayBuffer(env, out.data(), out.size());
+}
+
+napi_value Blake3GetVersion(napi_env env, napi_callback_info) {
+  return MakeArrayBuffer(env, reinterpret_cast<const uint8_t*>(BLAKE3_VERSION_STRING),
+                         strlen(BLAKE3_VERSION_STRING));
+}
+
+// ---------------------------------------------------------------------------
+// Algorithm listings (mirrors getSupportedHashAlgorithms etc.)
+// ---------------------------------------------------------------------------
+
+napi_value GetHashes(napi_env env, napi_callback_info) {
+  std::vector<std::string> names;
+  EVP_MD_do_all(
+                [](const EVP_MD* md, const char* from, const char* to, void* arg) {
+                  (void)md; (void)to;
+                  auto* names = static_cast<std::vector<std::string>*>(arg);
+                  if (from && strchr(from, ':') == nullptr && strchr(from, '/') == nullptr &&
+                      std::find(names->begin(), names->end(), from) == names->end())
+                    names->push_back(from);
+                },
+                &names);
+  napi_value arr;
+  napi_create_array_with_length(env, names.size(), &arr);
+  for (size_t i = 0; i < names.size(); i++) {
+    napi_value s;
+    napi_create_string_utf8(env, names[i].c_str(), names[i].size(), &s);
+    napi_set_element(env, arr, static_cast<uint32_t>(i), s);
+  }
+  return arr;
+}
+
+napi_value GetCiphers(napi_env env, napi_callback_info) {
+  std::vector<std::string> names;
+  EVP_CIPHER_do_all(
+                    [](const EVP_CIPHER* cipher, const char* from, const char* to, void* arg) {
+                      (void)cipher; (void)to;
+                      auto* names = static_cast<std::vector<std::string>*>(arg);
+                      if (from && strchr(from, ':') == nullptr && strchr(from, '/') == nullptr &&
+                          std::find(names->begin(), names->end(), from) == names->end())
+                        names->push_back(from);
+                    },
+                    &names);
+  napi_value arr;
+  napi_create_array_with_length(env, names.size(), &arr);
+  for (size_t i = 0; i < names.size(); i++) {
+    napi_value s;
+    napi_create_string_utf8(env, names[i].c_str(), names[i].size(), &s);
+    napi_set_element(env, arr, static_cast<uint32_t>(i), s);
+  }
+  return arr;
+}
+
+// ---------------------------------------------------------------------------
+// module registration
+// ---------------------------------------------------------------------------
+
+struct Property {
+  const char* name;
+  napi_callback fn;
+};
+
+napi_value Init(napi_env env, napi_value exports) {
+  const Property props[] = {
+      {"hashCreate", HashCreate},
+      {"hashUpdate", HashUpdate},
+      {"hashDigest", HashDigest},
+      {"hashCopy", HashCopy},
+      {"hash", HashOneShot},
+      {"hmacCreate", HmacCreate},
+      {"hmacUpdate", HmacUpdate},
+      {"hmacDigest", HmacDigest},
+      {"hmac", HmacOneShot},
+      {"randomBytes", RandomBytes},
+      {"pbkdf2Sync", Pbkdf2Sync},
+      {"scryptSync", ScryptSync},
+      {"hkdfSync", HkdfSync},
+      {"argon2Sync", Argon2Sync},
+      {"timingSafeEqual", TimingSafeEqual},
+      {"cipherCreate", CipherCreate},
+      {"cipherUpdate", CipherUpdate},
+      {"cipherSetAAD", CipherSetAAD},
+      {"cipherSetAutoPadding", CipherSetAutoPadding},
+      {"cipherFinal", CipherFinal},
+      {"cipherGetAuthTag", CipherGetAuthTag},
+      {"cipherSetAuthTag", CipherSetAuthTag},
+      {"blake3InitHash", Blake3InitHash},
+      {"blake3InitKeyed", Blake3InitKeyed},
+      {"blake3InitDeriveKey", Blake3InitDeriveKey},
+      {"blake3Update", Blake3Update},
+      {"blake3Digest", Blake3Digest},
+      {"blake3Copy", Blake3Copy},
+      {"blake3Reset", Blake3Reset},
+      {"blake3", Blake3OneShot},
+      {"blake3GetVersion", Blake3GetVersion},
+      {"getHashes", GetHashes},
+      {"getCiphers", GetCiphers},
+  };
+  for (const auto& p : props) {
+    napi_value fn;
+    if (napi_create_function(env, p.name, NAPI_AUTO_LENGTH, p.fn, nullptr, &fn) != napi_ok)
+      return nullptr;
+    if (napi_set_named_property(env, exports, p.name, fn) != napi_ok) return nullptr;
+  }
+  return exports;
+}
+
+}  // namespace
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)