#בקרת הרשאות ACL

ACL (Access Control List) משמש לבקרת הרשאות פעולות על משאבים. ניתן להעניק הרשאות לתפקידים, או לעקוף הגבלות תפקידים ולהגביל הרשאות באופן ישיר. מערכת ה-ACL מספקת מנגנון גמיש לניהול הרשאות, התומך בקטעי הרשאה (snippets), תוכנות ביניים (middleware), בדיקות תנאי ועוד.

#רישום קטעי הרשאה (Snippets)

קטעי הרשאה (Snippets) מאפשרים לרשום צירופי הרשאות נפוצים כיחידות הרשאה הניתנות לשימוש חוזר. לאחר שתפקיד מקושר ל-snippet, הוא מקבל את סט ההרשאות המתאים, מה שמפחית כפילויות בהגדרות ומשפר את יעילות ניהול ההרשאות.

acl.registerSnippet({
  name: 'ui.customRequests', // הקידומת ui.* מציינת הרשאות שניתן להגדיר בממשק המשתמש
  actions: ['customRequests:*'], // פעולות משאב מתאימות, תומך בתווים כלליים (wildcards)
});

#הרשאות העוקפות הגבלות תפקידים (allow)

acl.allow() משמשת כדי לאפשר לפעולות מסוימות לעקוף הגבלות תפקידים. היא מתאימה לממשקי API ציבוריים, לתרחישים הדורשים הערכת הרשאות דינמית, או למקרים שבהם יש צורך לבסס את בדיקת ההרשאות על הקשר הבקשה.

// גישה ציבורית, אין צורך בהתחברות
acl.allow('app', 'getLang', 'public');

// נגיש למשתמשים מחוברים בלבד
acl.allow('app', 'getInfo', 'loggedIn');

// מבוסס על תנאי מותאם אישית
acl.allow('orders', ['create', 'update'], (ctx) => {
  return ctx.auth.user?.isAdmin ?? false;
});

תיאור פרמטר condition:

• 'public': כל משתמש (כולל משתמשים שאינם מחוברים) יכול לגשת, ללא צורך באימות כלשהו.
• 'loggedIn': רק משתמשים מחוברים יכולים לגשת, דורש זהות משתמש תקפה.
• (ctx) => Promise<boolean> או (ctx) => boolean: פונקציה מותאמת אישית הקובעת באופן דינמי אם הגישה מותרת בהתבסס על הקשר הבקשה; יכולה ליישם לוגיקת הרשאות מורכבת.

#רישום תוכנת ביניים להרשאות (use)

acl.use() משמשת לרישום תוכנת ביניים (middleware) מותאמת אישית להרשאות, המאפשרת להוסיף לוגיקה מותאמת אישית לתהליך בדיקת ההרשאות. בדרך כלל היא משמשת בשילוב עם ctx.permission להגדרת כללי הרשאה מותאמים אישית. מתאימה לתרחישים הדורשים בקרת הרשאות לא שגרתית, כגון טפסים ציבוריים הדורשים אימות סיסמה מותאם אישית, בדיקות הרשאות דינמיות המבוססות על פרמטרי בקשה ועוד.

תרחישי יישום אופייניים:

• תרחישי טפסים ציבוריים: ללא משתמש וללא תפקיד, אך יש צורך להגביל הרשאות באמצעות סיסמה מותאמת אישית.
• בקרת הרשאות המבוססת על פרמטרי בקשה, כתובות IP ותנאים אחרים.
• כללי הרשאה מותאמים אישית, עקיפה או שינוי של תהליך בדיקת ההרשאות המוגדר כברירת מחדל.

בקרת הרשאות באמצעות ctx.permission:

acl.use(async (ctx, next) => {
  const { resourceName, actionName } = ctx.action;
  
  // דוגמה: טופס ציבורי דורש אימות סיסמה כדי לעקוף את בדיקת ההרשאות
  if (resourceName === 'publicForms' && actionName === 'submit') {
    const password = ctx.request.body?.password;
    if (password === 'your-secret-password') {
      // האימות עבר בהצלחה, עוקפים את בדיקת ההרשאות
      ctx.permission = {
        skip: true,
      };
    } else {
      ctx.throw(403, 'Invalid password');
    }
  }
  
  // מבצעים בדיקת הרשאות (ממשיכים את תהליך ה-ACL)
  await next();
});

ctx.permission תיאור מאפיינים:

• skip: true: עוקף את בדיקות ההרשאה הבאות של ACL ומאפשר גישה ישירה.
• ניתן להגדיר באופן דינמי בתוכנת הביניים (middleware) בהתבסס על לוגיקה מותאמת אישית כדי להשיג בקרת הרשאות גמישה.

#הוספת אילוצי נתונים קבועים לפעולות ספציפיות (addFixedParams)

addFixedParams יכולה להוסיף אילוצי טווח נתונים קבועים (filter) לפעולות מסוימות על משאבים. אילוצים אלה עוקפים הגבלות תפקידים ומיושמים ישירות, ובדרך כלל משמשים להגנה על נתוני מערכת קריטיים.

acl.addFixedParams('roles', 'destroy', () => {
  return {
    filter: {
      $and: [
        { 'name.$ne': 'root' },
        { 'name.$ne': 'admin' },
        { 'name.$ne': 'member' },
      ],
    },
  };
});

// גם אם למשתמש יש הרשאה למחוק תפקידים, הוא לא יוכל למחוק תפקידי מערכת כמו root, admin, member

טיפ: addFixedParams יכולה לשמש למניעת מחיקה או שינוי בשוגג של נתונים רגישים, כגון תפקידי מערכת מובנים, חשבונות מנהל מערכת וכדומה. אילוצים אלה פועלים בשילוב עם הרשאות התפקידים, ומבטיחים שגם עם הרשאות לא ניתן לתפעל נתונים מוגנים.

#בדיקת הרשאות (can)

acl.can() משמשת לבדיקה האם לתפקיד מסוים יש הרשאה לבצע פעולה מוגדרת, ומחזירה אובייקט תוצאת הרשאה או null. היא נפוצה בשימוש לבדיקת הרשאות באופן דינמי בלוגיקה עסקית, למשל בתוכנות ביניים (middleware) או ב-Handler של פעולה, כדי לקבוע אם מותר לבצע פעולות מסוימות בהתבסס על תפקידים.

const result = acl.can({
  roles: ['admin', 'manager'], // ניתן להעביר תפקיד יחיד או מערך של תפקידים
  resource: 'orders',
  action: 'delete',
});

if (result) {
  console.log(`לתפקיד ${result.role} יש הרשאה לבצע את הפעולה ${result.action}`);
  // result.params מכיל פרמטרים קבועים שהוגדרו באמצעות addFixedParams
  console.log('פרמטרים קבועים:', result.params);
} else {
  console.log('אין הרשאה לבצע פעולה זו');
}

טיפ: אם מועברים מספר תפקידים, כל תפקיד ייבדק ברצף, ותוחזר התוצאה של התפקיד הראשון שיש לו הרשאה.

הגדרות סוג:

interface CanArgs {
  role?: string;      // תפקיד יחיד
  roles?: string[];   // מספר תפקידים (נבדקים ברצף, מחזיר את התפקיד הראשון עם הרשאה)
  resource: string;   // שם המשאב
  action: string;    // שם הפעולה
}

interface CanResult {
  role: string;       // התפקיד עם ההרשאה
  resource: string;   // שם המשאב
  action: string;    // שם הפעולה
  params?: any;       // מידע על פרמטרים קבועים (אם הוגדרו באמצעות addFixedParams)
}

#רישום פעולות הניתנות להגדרה (setAvailableAction)

אם ברצונכם שפעולות מותאמות אישית יהיו ניתנות להגדרה בממשק המשתמש (לדוגמה, שיופיעו בדף ניהול התפקידים), עליכם להשתמש ב-setAvailableAction כדי לרשום אותן. פעולות רשומות יופיעו בממשק הגדרת ההרשאות, ושם מנהלי מערכת יוכלו להגדיר הרשאות פעולה עבור תפקידים שונים.

acl.setAvailableAction('importXlsx', {
  displayName: '{{t("Import")}}', // שם תצוגה בממשק המשתמש, תומך בלוקליזציה (internationalization)
  type: 'new-data',               // סוג הפעולה
  onNewRecord: true,              // האם להיכנס לתוקף בעת יצירת רשומות חדשות
});

תיאור פרמטרים:

• displayName: השם המוצג בממשק הגדרת ההרשאות, תומך בלוקליזציה (באמצעות פורמט {{t("key")}}).
• type: סוג הפעולה, קובע את סיווג הפעולה בהגדרת ההרשאות.
  • 'new-data': פעולות היוצרות נתונים חדשים (כמו ייבוא, הוספה וכדומה).
  • 'existing-data': פעולות המשנות נתונים קיימים (כמו עדכון, מחיקה וכדומה).
• onNewRecord: האם להיכנס לתוקף בעת יצירת רשומות חדשות, תקף רק עבור סוג 'new-data'.

לאחר הרישום, פעולה זו תופיע בממשק הגדרת ההרשאות, ושם מנהלי מערכת יוכלו להגדיר את הרשאות הפעולה בדף ניהול התפקידים.