kit-jwt

ترميز وفك ترميز JSON Web Token (JWT) لـ Kit

[TOC]

الملفات

التبعيات

• تبعية حزمة Kit: crypto
• وحدة Kit القياسية: Encoding.Base64
• مكتبة أصلية: OpenSSL libcrypto للمساعدات RS256 و RS384 و RS512
• الإمكانية المطلوبة: ffi

تم تعريف الحزمة كـ ffi-zig لأن التوقيع والتحقق من RSA يستخدمان zig/jwt_rsa.zig. يستخدم HS256 crypto.hmac-sha256.

التثبيت

kit add gitlab.com/kit-lang/packages/kit-jwt.git

الاستخدام

import Kit.Jwt as JWT

main = fn =>
  secret = "my-super-secret-key-at-least-32-chars"
  claims = "{\"sub\":\"user123\",\"name\":\"John Doe\",\"admin\":true,\"iat\":1700000000}"

  match JWT.encode claims secret
    | Err e ->
      println "Failed to create token:"
      println e
    | Ok token ->
      println "JWT:"
      println token

      if JWT.verify? token secret then
        println "Token is valid"
      else
        println "Token is invalid"

      match JWT.decode token secret
        | Ok decoded ->
          println "Header:"
          println decoded.header
          println "Payload:"
          println decoded.payload
        | Err e ->
          println "Decode failed:"
          println e

main

المساعدات المدعومة للتوقيع والتحقق:

المساعدات غير الآمنة للفحص متاحة أيضًا لتصحيح أخطاء الرموز دون التحقق من التوقيعات:

• decode-unsafe
• get-claims-unsafe
• get-header-unsafe

لا تستخدم المساعدات غير الآمنة لقرارات التفويض.

التطوير

تشغيل الأمثلة

شغّل المثال الأساسي باستخدام المفسر:

kit run examples/basic.kit --allow=ffi

قم بتجميع المثال إلى ملف ثنائي أصلي:

kit build examples/basic.kit --allow=ffi && ./basic

تشغيل الاختبارات

شغّل مجموعة الاختبارات النشطة:

kit test --allow=ffi

شغّل مجموعة الاختبارات النشطة مع تغطية:

kit test --coverage --allow=ffi

شغّل ملفات اختبار RSA الاختيارية مباشرة:

kit test tests/rs256.kit.disabled --allow=ffi
kit test tests/rs384.kit.disabled --allow=ffi
kit test tests/rs512.kit.disabled --allow=ffi

تشغيل kit dev

شغّل سير عمل التطوير القياسي (تنسيق، فحص، اختبار):

kit dev

سيقوم هذا بما يلي:

1. فحص تنسيق ملفات المصدر والأمثلة الخاصة بـ Kit
2. فحص الأنواع في المصدر والأمثلة
3. تشغيل الاختبارات النشطة مع تغطية

تشغيل فحص التطابق (Parity)

شغّل فحوصات التطابق بين المفسر والمترجم للأمثلة:

kit parity --failures-only

تتحقق فحوصات التطابق من أن الأمثلة تُشغّل عبر المفسر، وتُجمّع بنجاح، وتُنفّذ بنجاح، وتُنتج مخرجات متطابقة.

إنشاء التوثيق

أنشئ توثيق واجهة برمجة التطبيقات من تعليقات التوثيق:

kit doc src/jwt.kit

ملاحظة: ملفات Kit المصدرية التي تحتوي على تعليقات توثيق (##) تُنشئ توثيق HTML.

تنظيف ملفات البناء

أزل الملفات المُنشأة والذاكرة المؤقتة وملفات البناء:

kit task clean

ملاحظة: مُعرّفة في kit.toml.

التثبيت المحلي

لتثبيت هذه الحزمة محليًا للتطوير:

kit install

يقوم هذا بتثبيت الحزمة إلى ~/.kit/packages/@kit/jwt/، مما يجعلها متاحة للاستيراد كـ Kit.Jwt في المشاريع الأخرى.

ملاحظات أمنية

• استخدم مفاتيح HS256 عشوائية وقوية. يُوصى بحد أدنى 256 بت.
• لا تُرسل أبدًا مفاتيح خاصة أو مفاتيح JWT خاصة بالإنتاج.
• تحقق من مطالبات التطبيق مثل exp و nbf و iat و iss و aud بعد فك الترميز.
• يُفضّل استخدام الرموز قصيرة العمر وتدوير المفاتيح وفقًا لنموذج التهديد الخاص بتطبيقك.
• استخدم HTTPS عند نقل JWTs عبر الشبكة.

الترخيص

تم إصدار هذه الحزمة بموجب ترخيص MIT - راجع LICENSE للتفاصيل.