.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.3 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "FLASK-PARANOID" "1" "Dec 15, 2025" "" "Flask-Paranoid"
.SH "نام (NAME)"
python\-flask\-paranoid \- افزونه محافظت از نشست‌های کاربر در برابر سرقت کوکی در فلسک
.sp
افزونهٔ
.B Flask\-Paranoid
یک افزونه ساده برای ریزچارچوب Flask است که از برنامه در برابر حملاتی که در آن‌ها کوکی نشست کاربر ربوده شده و توسط مهاجم استفاده می‌شود، محافظت می‌کند.
.sp
هنگامی که یک کلاینت برای نخستین بار به برنامه متصل می‌شود، توکنی تولید و ذخیره می‌گردد که نمایانگر ویژگی‌های مشخصی از آن کلاینت است. در درخواست‌های بعدی ارسال‌شده از سوی این کلاینت، این توکن مجدداً تولید شده و با توکن ذخیره‌شده مقایسه می‌شود. اگر توکن‌ها متفاوت باشند، فرض بر این گذاشته می‌شود که کلاینت درخواست‌ها را از محیطی متفاوت از محیطی که نشست در آن ایجاد شده بود ارسال می‌کند؛ بنابراین در این حالت نشست نابود شده و درخواست به عنوان اقدامی پیشگیرانه رد می‌شود.
.sp
به‌طور پیش‌فرض، توکن بر اساس آدرس IP و رشتهٔ عامل کاربر (User Agent) کلاینت تولید می‌شود. این بدان معناست که اگر کوکی نشست کاربری ربوده شود و سپس از مکانی دیگر یا مرورگری متفاوت استفاده شود، توکن تولیدشده تغییر خواهد کرد و آن درخواست «متفاوت» مسدود خواهد شد.
.sp
ایدهٔ این ابزار مبتنی بر قابلیت محافظت قدرتمند از نشست (strong session protection) در
.B Flask\-Login
است، اما به صورت تعمیم‌یافته پیاده‌سازی شده تا بتوان آن را خارج از بستر Flask\-Login نیز استفاده کرد. فرآیند تولید و ذخیره‌سازی توکن را می‌توان متناسب با انواع برنامه‌ها سفارشی‌سازی کرد.
.sp
در زیر یک برنامهٔ ساده آورده شده است که از Flask\-Paranoid برای محافظت از نشست کاربر استفاده می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from flask import Flask
from flask_paranoid import Paranoid

app = Flask(__name__)
app.config[\(aqSECRET_KEY\(aq] = \(aqtop\-secret!\(aq

paranoid = Paranoid(app)
paranoid.redirect_view = \(aq/\(aq

@app.route(\(aq/\(aq)
def index():
    return render_template(\(aqindex.html\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
در این مثال، توکن Paranoid محاسبه‌شده در نخستین درخواست کلاینت، درون نشست کاربر ذخیره می‌شود. اگر در درخواستی بعدی توکن متفاوتی تولید شود، نشست پاکسازی شده و سپس هدایت (redirect) به نشانی ریشه انجام می‌گیرد که مهاجم احتمالی را وادار به ورود مجدد به سیستم می‌کند.
.sp
تنها پیکربندی لازم، تعیین اقدامی است که پس از پاکسازی نشست و هنگام شناسایی یک نشست نامعتبر انجام می‌شود. رفتار پیش‌فرض بازگرداندن خطای 401 به کلاینت است.
.sp
برای هدایت به یک نشانی وب مشخص، مقدار \fBparanoid.redirect_view\fP را روی مقصد مورد نظر تنظیم کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
paranoid.redirect_view = \(aq/login\(aq
.EE
.UNINDENT
.UNINDENT
.sp
نشانی‌های وب مطلق (Absolute URLs) نیز پشتیبانی می‌شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
paranoid.redirect_view = \(aqhttps://www.google.com\(aq
.EE
.UNINDENT
.UNINDENT
.sp
برای هدایت به یک مسیر ثبت‌شده در Flask، مقدار \fBparanoid.redirect_view\fP را برابر نام اندپوینت مورد نظر قرار دهید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
paranoid.redirect_view = \(aqindex\(aq
.EE
.UNINDENT
.UNINDENT
.sp
جهت هدایت به مسیری در داخل یک بلوپرینت (Blueprint)، از همان ساختار نگارشی تابع \fBurl_for()\fP استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
paranoid.redirect_view = \(aqauth.login\(aq
.EE
.UNINDENT
.UNINDENT
.sp
برای اینکه این افزونه یک تابع بازخوانی (Callback) را برای تولید پاسخ فراخوانی کند، از دکوراتور \fBparanoid.on_invalid_session\fP استفاده کنید. این تابع باید یک شیء پاسخ معتبر Flask را بازگرداند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@paranoid.on_invalid_session
def invalid_session():
    return \(aqplease login\(aq, 401
.EE
.UNINDENT
.UNINDENT
.sp
از آنجا که این افزونه قابلیت مشابه موجود در Flask\-Login را بازنویسی (override) می‌کند، توصیه می‌شود در صورت استفاده هم‌زمان از هر دو افزونه در یک برنامه، محافظت از نشست در Flask\-Login غیرفعال شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
login_manager.session_protection = None
.EE
.UNINDENT
.UNINDENT
.sp
افزونهٔ Flask\-Paranoid استفاده از Flask\-Login را تشخیص می‌دهد و در این صورت، با شناسایی یک نشست نامعتبر، علاوه بر نشست کاربر، کوکی «مرا به خاطر بسپار» (\(dqremember me\(dq) آن را نیز پاکسازی می‌کند.
.sp
افزونهٔ Flask\-Paranoid به برنامه‌ها اجازه می‌دهد تا از طریق زیرکلاس‌ها (subclasses)، عملکردهای درونی آن را سفارشی‌سازی کنند.
.SH "تغییر الگوریتم تولید توکن (CHANGING THE TOKEN GENERATION ALGORITHM)"
.sp
پیاده‌سازی پیش‌فرض، یک هش SHA256 از آدرس IP و عامل کاربر (User Agent) کلاینت ایجاد می‌کند.
.sp
برای استفاده از الگوریتمی متفاوت جهت تولید توکن، متد \fBcreate_token\fP را بازنویسی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class MyParanoid(Paranoid):
    def create_token(self):
        pass
.EE
.UNINDENT
.UNINDENT
.sp
این متد در بستر درخواست (Request Context) فراخوانی می‌شود، بنابراین می‌تواند برای دریافت اطلاعات درباره کلاینت به شیء \fBrequest\fP دسترسی داشته باشد.
.SH "تغییر محل ذخیره‌سازی توکن (CHANGING WHERE THE TOKEN IS STORED)"
.sp
پیاده‌سازی پیش‌فرض، توکن Paranoid را در \fBsession[\(aq_paranoid_token\(aq]\fP\& می‌نویسد.
.sp
در صورتی که سازوکار ذخیره‌سازی متفاوتی مد نظر باشد، متدهای \fBwrite_token_to_session()\fP و \fBget_token_from_session()\fP را بازنویسی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class MyParanoid(Paranoid):
    def write_token_to_session(self, token):
        pass

    def get_token_from_session(self):
        pass
.EE
.UNINDENT
.UNINDENT
.sp
یک حالت استفادهٔ خاص و پیچیده‌تر زمانی است که این افزونه همراه با یک پروژهٔ API استفاده می‌شود که از نشست کاربر استفاده نکرده و در عوض توکن‌های احراز هویت را در اختیار کلاینت‌ها قرار می‌دهد. در چنین حالتی، می‌توان تابع تولید توکن برنامه را ارتقا داد تا توکن Paranoid را نیز شامل شود. برای نمونه:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def get_token(username, password):
    if validate_user(username, password):
        return encode_jwt(claims={\(aqusername\(aq: username,
                                  \(aqparanoid_token\(aq: paranoid.create_token()})
.EE
.UNINDENT
.UNINDENT
.sp
سپس می‌توان متدهای ذخیره‌سازی توکن را به شکل زیر بازنویسی کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class MyParanoid(Paranoid):
    def write_token_to_session(self, token):
        # nothing to do here, the paranoid token is inserted in the JWT
        # by the application
        pass

    def get_token_from_session(self):
        claims = decode_jwt(request.headers[\(aqX\-API\-TOKEN\(aq])
        if \(aqparanoid_token\(aq not in claims:
            abort(401)
        return claims[\(aqparanoid_token\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
در این مثال، \fBencode_jwt\fP و \fBdecode_jwt\fP توابع برنامه هستند که با توکن‌های JWT کار می‌کنند. کلاینت با ارسال توکن JWT در هدر \fBX\-API\-TOKEN\fP احراز هویت می‌شود.
.SH "استفاده از سازوکار پاکسازی متفاوت برای نشست (USING A DIFFERENT SESSION CLEANUP MECHANISM)"
.sp
به‌طور پیش‌فرض، این افزونه محتویات نشست کاربر را خالی می‌کند، و در صورتی که Flask\-Login استفاده شده باشد، کوکی «مرا به خاطر بسپار» (\(dqremember me\(dq) آن را نیز حذف می‌نماید.
.sp
برای تغییر یا جایگزینی الگوریتم پاکسازی نشست، متد \fBclear_session()\fP را بازنویسی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class MyParanoid(Paranoid):
    def clear_session(self, response):
        pass
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان \fBresponse\fP که به این متد پاس داده می‌شود، شیء پاسخی است که پس از پاکسازی نشست به کلاینت بازگردانده خواهد شد. هر کوکی که نیاز به حذف یا تغییر داشته باشد باید در این شیء پاسخ گنجانده شود.
.SH "نویسنده (AUTHOR)"
Miguel Grinberg
.SH "حق نشر (COPYRIGHT)"
2017, Miguel Grinberg
.\" End of generated man page.