הפעלות ואבטחה

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

מה שמכילה הפעלת מסמך

כל OpenDocumentAsync מוצלח יוצר הפעלה אחת ב‑IMemoryCache:

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

משך החיים

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

// סשן קצר לתצוגה מקדימה חד-פעמית
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."). הגדרו אפשרויות אלה דרך ASP.NET Core DI לפני בניית האפליקציה. אם מצב ההפעלה אינו זמין, תיווך האבטחה נכשל סגור עם 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 (ברירת המחדל) — מתג גלובלי זה הוא מה שקושר אסימונים להפעלות.
• רשמו את AddDistributedMemoryCache() (אפליקציות MVC ו‑Razor Pages כבר כוללות אותו) ואת AddSession(), וקראו app.UseSession() לפני ענף תיווך Doconut.
• ודאו שמדיניות קוביית הסשן שלכם מאפשרת לבקשות הווידג'ט לשאת את הקובייה SameSite, HTTPS.
• השתמשו ב‑CloseDocument כאשר המשתמש עוזב את המסמך — זיכרון ואבטחה משופרים.
• לעולם אל תתעדו או תשתפו אסימונים; התייחסו אליהם כאל אישורים קצרים טווח.