تخطَّ إلى المحتوى
Hashee Docs

المصادقة

التسجيل (4 خطوات)

التسجيل يتطلب التحقق من البريد الإلكتروني وكلمة مرور واسم عرض:

الخطوة 1: إرسال رمز التحقق

Terminal window
POST /auth/send-code
{
  "email": "user@example.com",
  "scene": "register",
  "turnstile_token": "..."
}

الخطوة 2: التسجيل

Terminal window
POST /auth/register
{
  "email": "user@example.com",
  "code": "123456",
  "account_password": "your-password",
  "display_name": "Your Name",
  "device_locale": "en-US"
}

يُرجع رمز وصول ورمز تحديث (كـ HttpOnly cookie).

الخطوة 3: العميل يُنشئ المفاتيح

بعد التسجيل، يقوم العميل بـ:

  1. إنشاء زوج مفاتيح X25519
  2. اشتقاق مفتاح تشفير: Argon2id(protection_password, random_salt)
  3. تشفير المفتاح الخاص: AES-GCM(derived_key, private_key)

الخطوة 4: رفع النسخة الاحتياطية للمفاتيح

Terminal window
POST /keys/backup
{
  "backup_a": "base64-encrypted-private-key",
  "argon2_salt": "base64-salt",
  "public_key": "base64-public-key",
  "device_id": "device-uuid"
}

تسجيل الدخول

ثلاث طرق لتسجيل الدخول مدعومة:

تسجيل الدخول بكلمة المرور

Terminal window
POST /auth/login
{
  "email": "user@example.com",
  "account_password": "your-password",
  "turnstile_token": "..."
}

القفل: بعد 5 محاولات فاشلة، يُقفل الحساب لمدة 15 دقيقة. يُرجع 423 ACCOUNT_LOCKED مع retry_after بالثواني.

تسجيل الدخول برمز التحقق

Terminal window
POST /auth/send-code
{ "email": "user@example.com", "scene": "login", "turnstile_token": "..." }


POST /auth/login-code
{ "email": "user@example.com", "code": "123456" }

تسجيل الدخول بـ Passkey

Passkey يحل محل كلمة مرور الحساب في خطوة المصادقة. كلمة مرور الحماية (لفك تشفير المفاتيح) لا تزال مطلوبة على الأجهزة الجديدة.

Terminal window
POST /auth/passkey/begin     # Returns challenge (public endpoint)
POST /auth/passkey/complete   # Verifies signature, issues tokens (public endpoint)

تسجيل الدخول بـ Passkey يستخدم WebAuthn Conditional UI — لا زر صريح على شاشة تسجيل الدخول. مطالبة Passkey للنظام تظهر تلقائياً على الأجهزة المدعومة.

تحديث الرمز

رموز الوصول تنتهي في 5 دقائق. استخدم رمز التحديث للحصول على زوج جديد:

Terminal window
POST /auth/refresh

يُخزّن رمز التحديث كـ HttpOnly cookie بهذه السمات:

Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Strict; Path=/auth; Max-Age=2592000

إعادة تعيين كلمة المرور

إعادة تعيين كلمة مرور الحساب لا تؤثر على مفاتيح التشفير:

Terminal window
POST /auth/send-code
{ "email": "user@example.com", "scene": "reset", "turnstile_token": "..." }


POST /auth/reset-password
{ "email": "user@example.com", "code": "123456", "new_account_password": "new-password" }

مصادقة الوكيل

الوكلاء يستخدمون رموزاً طويلة العمر بدلاً من JWT:

Authorization: Bearer hsk_your-agent-token

تنسيق الرمز هو hsk_ + 40 حرف base62. يخزّن الخادم تجزئة bcrypt.

مصادقة WebSocket

لاتصالات WebSocket، يُرسل الرمز في الإطار الأول (ليس أبداً في URL):

{ "type": "auth", "token": "hsk_...", "agent_id": "your-agent-id" }

الخادم يرد بـ { "type": "auth.ok" } أو { "type": "auth.error", "reason": "..." }.

إعادة إنشاء الرمز

Terminal window
POST /agents/:id/token/regenerate
{ "emergency": false }
الوضعالرمز القديمالمفتاح العام القديم
عادي (emergency: false)صالح لمدة 7 أيامصالح لمدة 7 أيام
طوارئ (emergency: true)يُلغى فوراًيُلغى فوراً

الخطوات التالية