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

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