kit-oauth

مكتبة عميل OAuth 2.0 لتطبيقات Kit

[TOC]

الملفات

التبعيات

لا تبعيات لحزم Kit.

تستخدم هذه الحزمة الوحدات المضمنة في Kit HTTP و Time. يجب أن يطلب ملف تعريف الحزمة إمكانية net لأن تبادل الرموز ومساعدات الطلبات الموثقة تقوم باستدعاءات HTTP.

التثبيت

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

الاستخدام

import Kit.Oauth as OAuth

main = fn =>
  config = OAuth.github "client-id" "client-secret" "http://localhost:3000/callback" ["read:user", "user:email"]

  state = OAuth.generate-state
  auth-url = OAuth.authorize-url config state

  println "Open this authorization URL:"
  println auth-url

main

رمز التفويض

بعد أن يقوم المزود بإعادة التوجيه إلى رابط الاستدعاء الخاص بك، تحقق من أن state المُعاد يتطابق مع الحالة التي أنشأتها، ثم قم بتبادل رمز التفويض للحصول على الرموز:

match OAuth.exchange-code http-auth config code
  | Ok tokens ->
    println "Token type: ${tokens.token-type}"
    println "Expires in: ${Int.to-string tokens.expires-in} seconds"
  | Err err ->
    println "OAuth error: ${err}"

رمز التفويض مع PKCE

استخدم PKCE للعملاء العموميين مثل تطبيقات سطح المكتب والتطبيقات الجوالة والتدفقات المستندة إلى المتصفح:

verifier = "abcdefghijklmnopqrstuvwxyz0123456789-._~abc"
state = OAuth.generate-state
auth-url = OAuth.authorize-url-pkce config state verifier

match OAuth.exchange-code-pkce http-auth config code verifier
  | Ok tokens -> println "Access token received"
  | Err err -> println "OAuth error: ${err}"

يستخدم مساعد PKCE الحالي طريقة التحدي plain. وهو مُنظم بحيث يمكن نقله إلى S256 بمجرد توفر مساعد SHA256 للنصوص.

بيانات اعتماد العميل

استخدم بيانات اعتماد العميل للمصادقة من آلة إلى آلة:

config = OAuth.custom "client-id" "client-secret" "https://auth.example.com/oauth/authorize" "https://auth.example.com/oauth/token" "https://app.example.com/oauth/callback" ["api:read", "api:write"]

match OAuth.client-credentials http-auth config
  | Ok tokens ->
    println "Access token received"
  | Err err ->
    println "OAuth error: ${err}"

رموز التحديث

match OAuth.refresh-token http-auth config refresh-token
  | Ok tokens -> println "Refreshed access token"
  | Err err -> println "Refresh failed: ${err}"

الطلبات الموثقة

match OAuth.get http-auth "https://api.example.com/user" tokens.access-token
  | Ok response ->
    println "Status: ${Int.to-string response.status}"
    println response.body
  | Error err ->
    println "API error: ${err}"

json-body = "{\"name\":\"Kit\"}"

match OAuth.post http-auth "https://api.example.com/resources" json-body tokens.access-token
  | Ok response -> println "Created: ${Int.to-string response.status}"
  | Error err -> println "API error: ${err}"

الإعدادات المسبقة للمزودين

ترجع مساعدات المزودين المضمنة OAuthConfig مع نقاط نهاية التفويض والرمز الخاصة بالمزود:

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

• تحقق دائمًا من قيمة state في الاستدعاء قبل تبادل رمز التفويض.
• استخدم روابط إعادة توجيه HTTPS في الإنتاج.
• لا تقم بتسجيل رموز الوصول أو رموز التحديث أو رموز التفويض أو أسرار العميل.
• قم بتخزين رموز التحديث في تخزين آمن مناسب لتطبيقك.
• استخدم متغيرات البيئة أو مدير الأسرار لأسرار العميل.
• تعامل مع الأمثلة المرفوعة كمثال تجريبي فقط. تم تصميمها لتكون آمنة من التطابق ولا تتصل بمزودي OAuth المباشرين.

التطوير

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

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

kit run examples/github.kit
kit run examples/client-credentials.kit

ترجمة مثال إلى ملف ثنائي أصلي:

kit build examples/github.kit && ./github

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

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

kit test

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

kit test --coverage

تشغيل kit dev

تشغيل سير العمل التطويري القياسي:

kit dev

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

1. التحقق من التنسيق
2. فحص الأنواع في ملفات المصدر في src/
3. فحص الأنواع في الأمثلة في examples/
4. تشغيل الاختبارات في tests/ مع التغطية

تشغيل التطابق

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

kit parity --failures-only

تستخدم الأمثلة مخرجات حتمية وتتجنب استدعاءات الشبكة المباشرة بحيث يمكن للتطابق مقارنة مخرجات المفسر والملف التنفيذي المترجم بشكل موثوق.

توليد الوثائق

توليد وثائق API من تعليقات التوثيق:

kit doc

ملاحظة: مصادر Kit التي تحتوي على تعليقات توثيق (##) ستقوم بتوليد مستندات HTML في docs/*.html.

تنظيف نتائج البناء

إزالة الملفات المولدة وذاكرة التخزين المؤقت ونتائج التطابق والوثائق وملفات القفل ونتائج البناء الأصلي:

kit task clean

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

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

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

kit install

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

الترخيص

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