`microdot.auth` --- مصادقة HTTP¶

مزخرفات (decorators) تحمي المسارات خلف مصادقة HTTP. بنكهتين: BasicAuth لمخطط Authorization: Basic <base64> الذي تطالب به المتصفحات أصلاً، و TokenAuth لمخطط Authorization: Bearer <token> الذي تستخدمه واجهات API.

يشتق كلا الصنفين من قاعدة مشتركة BaseAuth؛ يبني التطبيق كائن المصادقة، ويسجل دالة رد نداء للمصادقة عبر authenticate()، ثم يزخرف المسارات المحمية بنسخة المصادقة.

class BasicAuth¶

class microdot.auth.BasicAuth(realm: str = 'Please login', charset: str = 'UTF-8', scheme: str = 'Basic', error_status: int = 401)¶

مصادقة HTTP الأساسية. ينبثق المتصفح بمربع حوار لاسم المستخدم / كلمة المرور عندما يصل طلب غير مُصادق عليه إلى مسار محمي، ويرسل Authorization: Basic <base64(user:pass)> في الطلبات اللاحقة.

realm: سلسلة المجال (realm) التي يعرضها المتصفح بجوار المطالبة.
charset: مجموعة المحارف المُعلَن عنها في تحدي WWW-Authenticate.
scheme: اسم مخطط المصادقة. الافتراضي 'Basic'.
error_status: حالة HTTP المُرجعة عند فشل المصادقة. الافتراضي 401.

authenticate(f)¶

مزخرف يسجل التحقق من بيانات الاعتماد. يأخذ f (request, username, password) ويُرجع كائن المستخدم المُصادق عليه (أو None عند بيانات اعتماد خاطئة). يُخزَّن الكائن المُرجَع في request.g.current_user.

basic = BasicAuth(realm='Camera')

@basic.authenticate
async def check(request, username, password):
    user = users.get(username)
    if user and user.check_password(password):
        return user

__call__(f)¶

زخرفة مسار بنسخة BasicAuth تحميه:

@app.route('/admin')
@basic
def admin(request):
    return 'hello ' + request.g.current_user.name

optional(f)¶: مثل __call__()، لكنه لا يرفض الطلبات التي تفتقر إلى بيانات الاعتماد -- يظل المعالج يعمل، مع تعيين request.g.current_user إما إلى المستخدم المُصادق عليه أو إلى None.

class TokenAuth¶

class microdot.auth.TokenAuth(header: str = 'Authorization', scheme: str = 'Bearer', error_status: int = 401)¶

مصادقة برمز Bearer. يرسل العملاء رمزاً في ترويسة Authorization؛ ويتحقق التطبيق منه مقابل أي مخزن داعم يفضله.

header: اسم الترويسة الحاملة للرمز. يتوقع الافتراضي 'Authorization' القيمة Bearer <token>؛ بينما تحمل ترويسة مخصصة قيمة الرمز مباشرة.
scheme: مخطط المصادقة لترويسة Authorization. الافتراضي 'Bearer'.
error_status: حالة HTTP عند فشل المصادقة. الافتراضي 401.

authenticate(f)¶

مزخرف يسجل التحقق من الرمز. يأخذ f (request, token) ويُرجع كائن مستخدم أو None

import jwt

tokens = TokenAuth()

@tokens.authenticate
async def check(request, token):
    try:
        claims = jwt.decode(token, SECRET)
    except jwt.exceptions.PyJWTError:
        return None
    return claims['sub']

errorhandler(f)¶: مزخرف يتجاوز استجابة 401 الافتراضية. يأخذ f كائن الطلب ويُرجع استجابة (أو يُجهض).

__call__(f: Callable) → Callable¶

زخرفة مسار بنسخة TokenAuth تحميه. تُرفض الطلبات التي لا تحمل رمزاً صالحاً (401 افتراضياً، أو أياً كان ما أرجعه errorhandler()). عند النجاح يكون المستخدم المُصادق عليه على request.g.current_user

@app.get('/api/me')
@tokens
async def me(request):
    return {'user': request.g.current_user}

يُرجع المعالج المُغلَّف.

optional(f: Callable) → Callable¶

مثل __call__()، لكنه لا يرفض الطلبات التي تفتقر إلى رمز -- يظل المعالج يعمل، مع تعيين request.g.current_user إما إلى المستخدم المُصادق عليه أو إلى None. مفيد للمسارات التي تغير مخرجاتها بناءً على ما إذا كان المستدعي مُصادقاً عليه دون اشتراط ذلك:

@app.get('/api/feed')
@tokens.optional
async def feed(request):
    if request.g.current_user:
        return personalized_feed(request.g.current_user)
    return public_feed()

يُرجع المعالج المُغلَّف.

class BaseAuth¶

class microdot.auth.BaseAuth¶

قاعدة مشتركة لـ BasicAuth و TokenAuth. يمكن لمخططات المصادقة المخصصة أن تشتق منها.

auth_callback: Callable | None¶: دالة رد النداء المسجلة عبر authenticate. تكون None حتى يسجل التطبيق دالة رد النداء (زخرفة دالة بـ @auth.authenticate هي ما يضبطها).

error_callback: Callable¶: كائن قابل للاستدعاء غير متزامن يُرجع الاستجابة المُرسلة عند فشل المصادقة. يضبطه المُنشئ على افتراضي يُرجع استجابة 401؛ استبدله عبر errorhandler على TokenAuth، أو مباشرة على صنف فرعي مخصص من BaseAuth.

تحصل المسارات المزخرفة على request.g.current_user معبأ بالقيمة المُرجعة من دالة رد نداء المصادقة. داخل المسار، افحص تلك السمة لتحديد هوية المستدعي.

microdot.auth --- مصادقة HTTP¶

class BasicAuth¶

class TokenAuth¶

class BaseAuth¶

`microdot.auth` --- مصادقة HTTP¶