NOTE

يُنفذ Bun دالتي `createHash` و `createHmac` من [`node:crypto`](https://nodejs.org/api/crypto.html) بالإضافة إلى واجهات برمجة التطبيقات الأصلية لـ Bun الموثقة أدناه.

---

Bun.password

Bun.password هي مجموعة من دوال التجزئة والتحقق من كلمات المرور بخوارزميات آمنة مشفرة متنوعة.

const password = "super-secure-pa$$word";

const hash = await Bun.password.hash(password);
// => $argon2id$v=19$m=65536,t=2,p=1$tFq+9AVr1bfPxQdh6E8DQRhEXg/M/SqYCNu6gVdRRNs$GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4

const isMatch = await Bun.password.verify(password, hash);
// => true

تقبل الوسيطة الثانية لـ Bun.password.hash كائن معلمات يسمح لك باختيار وتكوين خوارزمية التجزئة.

const password = "super-secure-pa$$word";

// استخدام argon2 (الافتراضي)
const argonHash = await Bun.password.hash(password, {
  algorithm: "argon2id", // "argon2id" | "argon2i" | "argon2d"
  memoryCost: 4, // استخدام الذاكرة بالكيلوبايت
  timeCost: 3, // عدد التكرارات
});

// استخدام bcrypt
const bcryptHash = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 4, // رقم بين 4-31
});

تُخزن الخوارزمية المستخدمة لإنشاء التجزئة في التجزئة نفسها. عند استخدام bcrypt، يتم ترميز التجزئة المُرجعة بتنسيق Modular Crypt Format للتوافق مع معظم تطبيقات bcrypt الموجودة؛ ومع argon2 يتم ترميز النتيجة بتنسيق PHC الأحدث.

تكتشف دالة verify تلقائيًا الخوارزمية بناءً على التجزئة المُدخلة وتستخدم طريقة التحقق الصحيحة. يمكنها استنتاج الخوارزمية بشكل صحيح من التجزئات المشفرة بتنسيق PHC أو MCF.

const password = "super-secure-pa$$word";

const hash = await Bun.password.hash(password, {
  /* config */
});

const isMatch = await Bun.password.verify(password, hash);
// => true

الإصدارات المتزامنة من جميع الدوال متاحة أيضًا. ضع في اعتبارك أن هذه الدوال مكلفة حسابيًا، لذا قد يؤدي استخدام واجهة برمجة تطبيقات محظورة إلى تدهور أداء التطبيق.

const password = "super-secure-pa$$word";

const hash = Bun.password.hashSync(password, {
  /* config */
});

const isMatch = Bun.password.verifySync(password, hash);
// => true

Salt

عند استخدام Bun.password.hash، يتم إنشاء salt تلقائيًا وتضمينه في التجزئة.

bcrypt - تنسيق Modular Crypt

في تجزئة Modular Crypt Format التالية (المستخدمة بواسطة bcrypt):

الإدخال:

await Bun.password.hash("hello", {
  algorithm: "bcrypt",
});

الإخراج:

$2b$10$Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi;

يتكون التنسيق من:

• bcrypt: $2b
• rounds: $10 - الجولات (log10 من العدد الفعلي للجولات)
• salt: $Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi
• hash: $GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4

بشكل افتراضي، تقوم مكتبة bcrypt بقطع كلمات المرور الأطول من 72 بايت. في Bun، إذا مررت لـ Bun.password.hash كلمة مرور أطول من 72 بايت واستخدمت خوارزمية bcrypt، سيتم تجزئة كلمة المرور عبر SHA-512 قبل تمريرها إلى bcrypt.

await Bun.password.hash("hello".repeat(100), {
  algorithm: "bcrypt",
});

لذا بدلاً من إرسال كلمة مرور بطول 500 بايت إلى bcrypt يتم قطعها بصمت إلى 72 بايت، سيقوم Bun بتجزئة كلمة المرور باستخدام SHA-512 وإرسال كلمة المرور المجزأة إلى bcrypt (فقط إذا تجاوزت 72 بايت). هذا سلوك افتراضي أكثر أمانًا.

argon2 - تنسيق PHC

في تجزئة تنسيق PHC التالية (المستخدمة بواسطة argon2):

الإدخال:

await Bun.password.hash("hello", {
  algorithm: "argon2id",
});

الإخراج:

$argon2id$v=19$m=65536,t=2,p=1$xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs$2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI

يتكون التنسيق من:

• algorithm: $argon2id
• version: $v=19
• memory cost: 65536
• iterations: t=2
• parallelism: p=1
• salt: $xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs
• hash: $2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI

---

Bun.hash

Bun.hash هي مجموعة من الأدوات للتجزئة غير المشفرة. خوارزميات التجزئة غير المشفرة محسنة لسرعة الحساب على مقاومة التصادم أو الأمان.

تستخدم دالة Bun.hash القياسية Wyhash لإنشاء تجزئة 64 بت من إدخال بحجم تعسفي.

Bun.hash("some data here");
// 11562320457524636935n

يمكن أن يكون الإدخال سلسلة أو TypedArray أو DataView أو ArrayBuffer أو SharedArrayBuffer.

const arr = new Uint8Array([1, 2, 3, 4]);

Bun.hash("some data here");
Bun.hash(arr);
Bun.hash(arr.buffer);
Bun.hash(new DataView(arr.buffer));

اختياريًا، يمكن تحديد seed كعدد صحيح كوسيطة ثانية. للتجزئات 64 بت، يجب تقديم seeds فوق Number.MAX_SAFE_INTEGER كـ BigInt لتجنب فقدان الدقة.

Bun.hash("some data here", 1234);
// 15724820720172937558n

خوارزميات تجزئة إضافية متاحة كخصائص على Bun.hash. واجهة برمجة التطبيقات هي نفسها لكل منها، مع تغيير نوع الإرجاع فقط من number للتجزئات 32 بت إلى bigint للتجزئات 64 بت.

Bun.hash.wyhash("data", 1234); // يعادل Bun.hash()
Bun.hash.crc32("data", 1234);
Bun.hash.adler32("data", 1234);
Bun.hash.cityHash32("data", 1234);
Bun.hash.cityHash64("data", 1234);
Bun.hash.xxHash32("data", 1234);
Bun.hash.xxHash64("data", 1234);
Bun.hash.xxHash3("data", 1234);
Bun.hash.murmur32v3("data", 1234);
Bun.hash.murmur32v2("data", 1234);
Bun.hash.murmur64v2("data", 1234);
Bun.hash.rapidhash("data", 1234);

---

Bun.CryptoHasher

Bun.CryptoHasher هي فئة أدوات عامة الغرض تتيح لك حساب تجزئة البيانات الثنائية أو السلاسل بشكل تدريجي باستخدام مجموعة من خوارزميات التجزئة المشفرة. الخوارزميات التالية مدعومة:

• "blake2b256"
• "blake2b512"
• "md4"
• "md5"
• "ripemd160"
• "sha1"
• "sha224"
• "sha256"
• "sha384"
• "sha512"
• "sha512-224"
• "sha512-256"
• "sha3-224"
• "sha3-256"
• "sha3-384"
• "sha3-512"
• "shake128"
• "shake256"

const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello world");
hasher.digest();
// Uint8Array(32) [ <byte>, <byte>, ... ]

بمجرد التهيئة، يمكن تغذية البيانات بشكل تدريجي إلى hasher باستخدام .update(). تقبل هذه الدالة string و TypedArray و ArrayBuffer.

const hasher = new Bun.CryptoHasher("sha256");

hasher.update("hello world");
hasher.update(new Uint8Array([1, 2, 3]));
hasher.update(new ArrayBuffer(10));

إذا تم تمرير string، يمكن استخدام وسيطة ثانية اختيارية لتحديد الترميز (الافتراضي 'utf-8'). الترميزات التالية مدعومة:

الفئة	الترميزات
الترميزات الثنائية	"base64" "base64url" "hex" "binary"
ترميزات الأحرف	"utf8" "utf-8" "utf16le" "latin1"
ترميزات الأحرف القديمة	"ascii" "binary" "ucs2" "ucs-2"

hasher.update("hello world"); // الافتراضي utf8
hasher.update("hello world", "hex");
hasher.update("hello world", "base64");
hasher.update("hello world", "latin1");

بعد تغذية البيانات إلى hasher، يمكن حساب تجزئة نهائية باستخدام .digest(). بشكل افتراضي، ترجع هذه الدالة Uint8Array تحتوي على التجزئة.

const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello world");

hasher.digest();
// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]

يمكن لطريقة .digest() إرجاع التجزئة كسلسلة اختيارًا. للقيام بذلك، حدد ترميزًا:

hasher.digest("base64");
// => "uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek="

hasher.digest("hex");
// => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

بدلاً من ذلك، يمكن للطريقة كتابة التجزئة في مثيل TypedArray موجود مسبقًا. قد يكون هذا مرغوبًا في بعض التطبيقات الحساسة للأداء.

const arr = new Uint8Array(32);

hasher.digest(arr);

console.log(arr);
// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]

HMAC في Bun.CryptoHasher

يمكن استخدام Bun.CryptoHasher لحساب تجزئات HMAC. للقيام بذلك، مرر المفتاح إلى المنشئ.

const hasher = new Bun.CryptoHasher("sha256", "secret-key");
hasher.update("hello world");
console.log(hasher.digest("hex"));
// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"

عند استخدام HMAC، مجموعة محدودة من الخوارزميات مدعومة:

• "blake2b512"
• "md5"
• "sha1"
• "sha224"
• "sha256"
• "sha384"
• "sha512-224"
• "sha512-256"
• "sha512"

على عكس Bun.CryptoHasher غير HMAC، لا يتم إعادة تعيين مثيل Bun.CryptoHasher لـ HMAC بعد استدعاء .digest()، ومحاولة استخدام نفس المثيل مرة أخرى ستطرح خطأ.

الطرق الأخرى مثل .copy() و .update() مدعومة (طالما أنها قبل .digest())، لكن الطرق مثل .digest() التي تنهي hasher غير مدعومة.

const hasher = new Bun.CryptoHasher("sha256", "secret-key");
hasher.update("hello world");

const copy = hasher.copy();
copy.update("!");
console.log(copy.digest("hex"));
// => "3840176c3d8923f59ac402b7550404b28ab11cb0ef1fa199130a5c37864b5497"

console.log(hasher.digest("hex"));
// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"