OAuth2

دع الناس يسجلون الدخول إلى موقعك بحساب زرزور. يستخدم تثبيت البوت الشاشة نفسها.

ما تحتاج إليه

تطبيق، وموقع أو برنامج يستطيع استقبال إعادة توجيه.

ما يستطيعه وما لا يستطيعه

يقرأ رمز الوصول هوية الشخص وسيرفراته. يعمل على /oauth2/@me... فقط، ولا يتصرف أبدًا باسم الشخص في بقية الواجهة.

النطاق	يمنح
`identify`	`GET /oauth2/@me`
`servers.read`	`GET /oauth2/@me/servers`
`applications.commands`	يبيّن أن أوامرك قد تُضاف
`bot.install`	يثبّت البوت في سيرفر يختاره الشخص

الخطوات

افتح تطبيقك، تبويب OAuth2. أضف عناوين إعادة التوجيه، عنوانًا في كل سطر، حتى 10: عناوين https://، أو http://localhost في أثناء التطوير. يجب أن تطابق تمامًا.
أنشئ سر عميل إذا كان برنامجك يعمل على سيرفر. دونه يكون التطبيق عميلًا عامًا. يظهر مرة واحدة.
لكل تسجيل دخول، أنشئ state عشوائيًا وcode_verifier عشوائيًا. أرسل الشخص إلى:

/oauth2/authorize
  ?client_id=YOUR_BOT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &response_type=code
  &scope=identify%20servers.read
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_OF_SHA256_OF_VERIFIER
  &code_challenge_method=S256

هذا المسار في تطبيق زرزور. ويبني مولّد الروابط في تبويب OAuth2 هذا العنوان. PKCE (code_challenge) مطلوب دائمًا، حتى مع سر العميل.

يوافق الشخص. يعود المتصفح إلى عنوان إعادة التوجيه مع code وstate. تحقق من أن state لك.
استبدل الرمز خلال 10 دقائق. يصلح مرة واحدة.

curl -X POST "https://api.zrzur.com/oauth2/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_BOT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d redirect_uri=https://example.com/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "identify servers.read"
}

استدع الواجهة به:

curl "https://api.zrzur.com/oauth2/@me" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

أنشئ قيم PKCE

code_verifier نص عشوائي من 43 إلى 128 حرفًا. وcode_challenge هو SHA-256 لذلك النص بترميز base64url دون حشو. احتفظ بالقيمة الأولى حتى الخطوة 5، ولا ترسل في العنوان إلا code_challenge.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");

التحديث والإلغاء

تدوم رموز الوصول ساعة، ورموز التحديث 30 يومًا. يصلح كل رمز تحديث مرة واحدة ويعود جديدًا. واستخدام رمز قديم ينهي السلسلة كلها، لأن ذلك يشبه السرقة.

curl -X POST "https://api.zrzur.com/oauth2/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_BOT_ID \
  -d refresh_token=YOUR_REFRESH_TOKEN

curl -X POST "https://api.zrzur.com/oauth2/revoke" \
  -d client_id=YOUR_BOT_ID \
  -d token=YOUR_REFRESH_TOKEN

يأخذ المساران نموذجًا لا JSON، وهما ليسا في مستند OpenAPI. يستطيع الشخص أيضًا سحب تطبيقك من إعداداته.

الأخطاء الشائعة

تجيب هذه المسارات بصيغة { "error": "...", "error_description": "..." }.

`error`	السبب	الحل
`invalid_request`	حقل مفقود، مثل `code_verifier`	أرسل كل الحقول
`invalid_grant`	الرمز مجهول أو مستخدم أو منتهٍ، أو PKCE خاطئ	ابدأ تسجيل الدخول مجددًا
`invalid_client`	معرّف العميل أو سره خاطئ (الحالة `401`)	تحقق منهما
`invalid_scope`	نطاق أوسع من الموافقة الأولى	اطلب أقل
`unsupported_grant_type`	نوع منح آخر	استخدم النوعين أعلاه