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

אסימון 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 עם בקשות הדף. הגדרות cross‑origin שמסירות עוגיות (או לקוח 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 כאשר המשתמש עוזב את המסמך — זיכרון ואבטחה משופרים.
• אל תתעדו או תשתפו אסימונים; התייחסו אליהם כאל אישורים קצרים טווח.