מושבים ואבטחה

אסימון Doconut הוא חזק: כל מי שמציגו יכול לבקש כל דף של המסמך אם הוא לא קשור למושב הפתיחה. דף זה מסביר מה מכיל מושב, כמה זמן הוא נשאר, והבדיקות ש‑UseDoconut() מאפשרת כברירת מחדל.

מה מכיל מושב מסמך

כל קריאה מוצלחת ל‑OpenDocumentAsync יוצרת מושב אחד ב‑IMemoryCache:

• המציג פורמט טעון (מופע מנוע המסמך המחזיק את המסמך המעובד),
• מצב לכל דף — סיבוב, הפיכות, ונתוני הערות שהמשתמש מוסיף בווידג'ט,
• האינדקס חיפוש האופציונלי, נבנה באופן עצלני בחיפוש הראשון (או נטען מקובץ .srh מוכן מראש בתרחישי חוות אינטרנט),
• הסימן מים של המושב מ‑DocOptions.Watermark.

משך החיים

מושבים פוגעים ב‑חלון זחילה: DocOptions.TimeOut דקות (ברירת מחדל 60), מתאפסים בכל בקשה שמציגה את האסימון. כאשר מושב נשלל — עקב פקיעה או על‑ידי CloseDocument(token) — קריאת ההחזרה שלו משחררת את מנוע המסמך ומשחררת את הזיכרון המשויך מיד.

// A short-lived session for a one-shot preview
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

בקשה עם אסימון שפג מקבלת תמונת שגיאה עם הטקסט Document session not found. Please re-open document. — הלקוח חייב לפתוח מחדש כדי לקבל אסימון חדש.

קשירת אסימון מובנית

עם UnsafeMode = false (ברירת המחדל), OpenDocumentAsync קושר את האסימון החדש למושב ASP.NET של בקשת ה‑HTTP שפתחה אותו, על‑ידי כתיבת סימון secure-{token} במושב זה. תוכנת האמצע של Doconut מסרבת אז לשרת דפים לכל מושב דפדפן אחר:

• דפדפן/מושב שונה המציג אסימון גנוב → תמונת שגיאה You Are Not Authorized To View This Page.
• תוכנת האמצע של המושב לא נרשמה → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

זוהי הסיבה שמדריך ההתחלה המהירה דורש AddSession() + app.UseSession() לפני סניף ה‑Doconut. שני השלכות מעשיות:

• הלקוח חייב לשלוח את עוגיית המושב של ASP.NET עם בקשות הדף. הגדרות חוצות‑מקור שמסירות עוגיות (או לקוח API ללא מחזיק עוגיות) יכשלו בבדיקה — זהו תפקוד תקין, לא באג.
• options.UnsafeMode = true משבית את הקשירה לחלוטין. היא קיימת לתרחישים מבוקרים (למשל רינדור שרת‑ל‑שרת); השאירו אותה false בייצור.

קשירת האסימון נשלטת רק על‑ידי המתג הגלובלי UnsafeMode — הוא פעיל כברירת מחדל (UnsafeMode = false) וחול על כל מושב. אין אפשרות לבטל לכל מסמך בנפרד; הגדרת UnsafeMode = true משביתת את הקשירה גלובלית.

הרשאות גישה ומשתמשים מאומתים

כאשר UnsafeMode הוא false, UseDoconut() מוסיפה את DocumentAccessMiddleware אוטומטית לפני תוכנת האמצע של הדף. אל תירשמו אותה פעמיים. כאשר בקשה נושאת אסימון, היא מחפשת את הרשאת הגישה שנרשמה כאשר המסמך נפתח ומאשרת רק אם כל התנאים הבאים מתקיימים:

1. קיימת הרשאה עבור האסימון,
2. היא לא פגה (משך החיים של ההרשאה = TimeOut של המסמך),
3. מזהה מושב ASP.NET של הבקשה תואם לזה שפתח את המסמך,
4. אם הפותח היה מאומת, תביעת NameIdentifier של המשתמש המבקש תואמת גם היא.

כשלונות מחזירים 403 — כתמונת PNG לשגיאה עבור בקשות דף/תמונה ממוזערת, וטקסט פשוט אחרת. ההודעה ומפתח השאילתה של האסימון מגיעים מ‑DocumentSecurityOptions (TokenQueryKey, ברירת מחדל "token"; UnauthorizedMessage, ברירת מחדל "You Are Not Authorized To View This Page."). הגדרו אפשרויות אלה דרך DI של ASP.NET Core לפני בניית האפליקציה. אם מצב המושב אינו זמין, תוכנת האמצע נכשלת סגורה עם HTTP 500: ASP.NET Session is required for Doconut document security.

builder.Services.Configure<Doconut.Security.DocumentSecurityOptions>(options =>
{
    options.TokenQueryKey = "token";
    options.UnauthorizedMessage = "You Are Not Authorized To View This Page.";
});

תוכנת האמצע של הדף המרכזית אז מאמתת את סימון המושב secure-{token} לפני שהיא מגישה את המסמך. עם UnsafeMode = true, UseDoconut() מדלגת על תוכנת האמצע של הגישה ובדיקה של הסימון המרכזי גם היא מושבתת.

ביטול

CloseDocument(token) לא רק משחררת זיכרון — היא גם מסירה את סימון secure-{token} ומבטלת את הרשאת הגישה, ולכן אסימון סגור מת בטלות בשתי שכבות האבטחה מיד.

רשימת בדיקה לייצור

• השאירו UnsafeMode = false (ברירת המחדל) — מתג גלובלי זה הוא זה שקושר אסימונים למושבים.
• רשמו AddSession() וקראו app.UseSession() לפני סניף תוכנת האמצע של Doconut.
• ודאו שמדיניות עוגיית המושב שלכם מאפשרת לבקשות הווידג'ט לשאת את העוגייה (SameSite, HTTPS).
• השתמשו ב‑CloseDocument כאשר המשתמש עוזב את המסמך — זיכרון ואבטחה משופרים.
• אל תתעדו או תשתפו אסימונים; התייחסו אליהם כאל אישורים קצרים טווח.