@sap/eslint-plugin-cds 3.0.5 → 3.1.1

package/lib/rules/auth-valid-restrict-grant.js

@@ -1,7 +1,17 @@
-const { findFuzzy, isEmptyString, isEmptyObject, isStringInArray } = require('../utils/rules')
+'use strict'
 
-const REPLACE_AS_WRITE_EVENTS = ['READ', 'CREATE', 'UPDATE', 'DELETE']
-const VALID_EVENTS = REPLACE_AS_WRITE_EVENTS.concat(['INSERT', 'UPSERT', 'WRITE', '*'])
+const { findFuzzy } = require('../utils/rules')
+
+// See https://cap.cloud.sap/docs/guides/security/authorization#restrict-annotation
+// The combination of these events is equivalent to the virtual 'WRITE' event.
+const SAME_AS_WRITE_EVENT = [ 'CREATE', 'DELETE', 'UPDATE', 'UPSERT' ]
+// Note that 'INSERT' is not meant to be used by users. They should use 'CREATE' instead.
+const VALID_EVENTS = [ ...SAME_AS_WRITE_EVENT, 'READ', 'INSERT', '*', 'WRITE']
+
+const TYPICAL_ISSUES = {
+  __proto__: null,
+  any: '*'
+}
 
 module.exports = {
   meta: {
@@ -9,99 +19,145 @@ module.exports = {
     docs: {
       description: '`@restrict.grant` must have valid values.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-grant',
     },
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      invalidType: 'Invalid type for grant value. Must either be string or array of strings.',
+      invalidSingleType: 'Grant value must be a string.',
+      misspelledItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
+      unknownItem: `Invalid item '{{invalid}}'. Valid: [ {{candidates}} ].`,
+      replaceBy: `Replace grant values '{{values}}' with '{{name}}'.`,
+      missingEventOrAction: "Missing event/action on '{{name}}' for `@restrict.grant`.",
+      star: 'Grant value \'*\' overrides all other grants. Replace by \'*\' only.'
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     return {
-      entity: checkRestrictGrant
+      any: checkRestrictGrant
     }
 
-    function checkRestrictGrant (e) {
+    function checkRestrictGrant(e) {
+      if (!Array.isArray(e?.['@restrict']))
+        return
+
       const node = context.getNode(e)
       const file = e.$location.file
-      if (e['@restrict']) {
-        const actions = e.actions
-        const actionNames = actions ? Object.keys(actions).map((s) => actions[s].name) : []
-        const validEventsAndActions = VALID_EVENTS.concat(actionNames)
-
-        for (const entry of e['@restrict']) {
-          if (Object.keys(entry).includes('grant')) {
-            const grantValue = entry.grant
-            switch (typeof grantValue) {
-              case 'string': {
-                if (isEmptyString(grantValue)) {
-                  context.report({
-                    message: `Missing event/action on ${e.name} for \`@restrict.grant\`.`,
-                    node,
-                    file
-                  })
-                } else {
-                  if (!isStringInArray(grantValue, validEventsAndActions, true)) {
-                    const candidates = findFuzzy(grantValue, validEventsAndActions.sort())
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: grantValue, candidates },
-                      node,
-                      file
-                    })
-                  }
-                }
-                break
-              }
-
-              case 'object':
-                if (isEmptyObject(grantValue)) {
-                  context.report({
-                    message: `Missing event/action on ${e.name} for \`@restrict.grant\`.`,
-                    node,
-                    file
-                  })
-                } else {
-                  const valuesForWrite = grantValue.filter(function (item) {
-                    return item !== 'READ' && item !== 'WRITE' && item !== '*'
-                  })
-                  for (const value of grantValue) {
-                    if (!validEventsAndActions.includes(value)) {
-                      const candidates = findFuzzy(value, validEventsAndActions.sort())
-                      context.report({
-                        messageId: 'InvalidItem',
-                        data: { invalid: value, candidates },
-                        node,
-                        file
-                      })
-                    }
-                  }
-                  // If values do not contain 'READ, WRITE, *', 'WRITE' only is enough
-                  const allValuesIncluded = grantValue.every((v) => valuesForWrite.includes(v))
-                  if (allValuesIncluded) {
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: [`[${grantValue}]`], candidates: ['["WRITE"]'] },
-                      node,
-                      file
-                    })
-                  }
-                  // If values contain '*', '*' only is enough
-                  if (grantValue.length > 1 && grantValue.includes('*')) {
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: `[${grantValue}]`, candidates: ['["*"]'] },
-                      node,
-                      file
-                    })
-                  }
-                }
-                break
-            }
+      const actionNames = e.actions ? Object.keys(e.actions) : []
+      const validEventsAndActions = [ ...VALID_EVENTS, ...actionNames ]
+
+      for (const entry of e['@restrict']) {
+        if (entry?.grant !== undefined) {
+          if (!checkRestrictEntry(entry)) {
+            // max. one message per annotation, to avoid spamming the user
+            break
+          }
+        }
+      }
+
+      /**
+       * Check an entry of the `@restrict` array.
+       * Returns `true` if the value is valid, `false` otherwise.
+       *
+       * @param {object} entry
+       * @returns {boolean}
+       */
+      function checkRestrictEntry( entry ) {
+        if (typeof entry.grant === 'string') {
+          return checkSingleGrantValue(entry.grant)
+
+        } else if (!Array.isArray(entry.grant)) {
+          // neither string nor array: report invalid type
+          context.report({ messageId: 'invalidType', node, file })
+          return false
+
+        } else {
+          if (entry.grant.length === 0) {
+            context.report({
+              messageId: 'missingEventOrAction',
+              data: { name: e.name }, node, file
+            })
+            return false
+          }
+
+          for (const value of entry.grant) {
+            if (!checkSingleGrantValue(value))
+              return false
+          }
+
+          // If grant values contain '*', '*' only is enough. It overrides everything.
+          if (entry.grant.length > 1 && entry.grant.includes('*')) {
+            context.report({ messageId: 'star',  node, file })
+            return false
+          }
+
+          // If the given values include all of SAME_AS_WRITE_EVENT, the user can
+          // replace them with 'WRITE'.
+          const includesWrite = SAME_AS_WRITE_EVENT.every(value => entry.grant.includes(value))
+          if (includesWrite) {
+            context.report({
+              messageId: 'replaceBy',
+              data: { values: SAME_AS_WRITE_EVENT.join(', '), name: 'WRITE' },
+              node, file
+            })
+            return false
+          }
+          return true
+        }
+      }
+
+      /**
+       * Returns `true` if the value is valid, `false` otherwise.
+       *
+       * @param grant
+       * @returns {boolean}
+       */
+      function checkSingleGrantValue(grant) {
+        if (typeof grant !== 'string') {
+          // single grant values must be strings
+          context.report({ messageId: 'invalidSingleType', node, file })
+          return false
+        }
+        if (grant.trim() === '') {
+          context.report({
+            messageId: 'missingEventOrAction',
+            data: { name: e.name }, node, file,
+          })
+          return false
+        }
+
+        if (!validEventsAndActions.includes(grant)) {
+          const candidates = TYPICAL_ISSUES[grant]
+            ? [ TYPICAL_ISSUES[grant] ]
+            : findFuzzy(grant, validEventsAndActions.sort(), null, false, 2)
+
+          if (candidates.length === 0) {
+            context.report({
+              messageId: 'unknownItem',
+              data: { invalid: grant, candidates: validEventsAndActions.join(', ') }, node, file,
+            })
+          } else {
+            context.report({
+              messageId: 'misspelledItem',
+              data: { invalid: grant, candidates: candidates.join(', ') }, node, file,
+            })
           }
+          return false
         }
+
+        if (grant === 'INSERT') {
+          // special case: 'INSERT' is an internal event name. Users should use 'CREATE' instead.
+          context.report({
+            messageId: 'replaceBy',
+            data: { values: 'INSERT', name: 'CREATE' },
+            node, file
+          })
+          return false
+        }
+
+        return true
       }
     }
   }

package/lib/rules/auth-valid-restrict-keys.js

@@ -1,40 +1,56 @@
+'use strict'
+
 const { isEmptyObject, findFuzzy } = require('../utils/rules')
 
-const VALID_RESTRICT_KEYS = ['grant', 'to', 'where']
+// These are the only valid properties inside `@restrict` annotations.
+// They are described in <https://cap.cloud.sap/docs/guides/security/authorization#restrict-annotation>
+const VALID_RESTRICT_PROPERTIES = ['grant', 'to', 'where']
 
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
-      description: '`@restrict` must have properly spelled `to`, `grant`, and `where` keys.',
+      description: '`@restrict` must not have properties besides `to`, `grant`, and `where`.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-keys',
     },
     messages: {
-      InvalidItem: "Misspelled key '{{invalid}}'. Did you mean '{{candidates}}'?"
+      misspelledProperty: "Misspelled or unknown property '{{invalid}}'. Did you mean '{{candidates}}'?",
+      unknownProperty: "Unknown property '{{invalid}}'. Possible: ['to', 'grant', 'where']",
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     return {
-      entity: checkRestrictKeys
+      any: checkRestrictKeys,
     }
 
     function checkRestrictKeys (e) {
-      if (e['@restrict']) {
-        for (const entry of e['@restrict']) {
-          if (typeof entry === 'object' && !isEmptyObject(entry)) {
-            for (const key of Object.keys(entry)) {
-              if (!VALID_RESTRICT_KEYS.includes(key)) {
-                const candidates = findFuzzy(key, VALID_RESTRICT_KEYS.sort())
-                context.report({
-                  messageId: 'InvalidItem',
-                  data: { invalid: key, candidates },
-                  node: context.getNode(e),
-                  file: e.$location.file
-                })
-              }
+      if (!Array.isArray(e?.['@restrict']))
+        return
+
+      for (const entry of e['@restrict']) {
+        if (entry && typeof entry === 'object' && !isEmptyObject(entry)) {
+          for (const key of Object.keys(entry)) {
+            if (VALID_RESTRICT_PROPERTIES.includes(key))
+              continue
+            const candidates = findFuzzy(key, VALID_RESTRICT_PROPERTIES.sort(), null, false, 2)
+            if (candidates.length === 0) {
+              context.report({
+                messageId: 'unknownProperty',
+                data: { invalid: key },
+                node: context.getNode(e),
+                file: e.$location.file
+              })
+            } else {
+              context.report({
+                messageId: 'misspelledProperty',
+                data: { invalid: key, candidates },
+                node: context.getNode(e),
+                file: e.$location.file
+              })
             }
           }
         }

package/lib/rules/auth-valid-restrict-to.js

@@ -1,6 +1,6 @@
-const { isEmptyString, isStringInArray, findFuzzy, isEmptyObject } = require('../utils/rules')
+'use strict'
 
-const VALID_PSEUDO_ROLES = ['authenticated-user', 'system-user', 'any']
+const VALID_PSEUDO_ROLES = new Set(['authenticated-user', 'system-user', 'internal-user', 'any'])
 
 module.exports = {
   meta: {
@@ -8,125 +8,76 @@ module.exports = {
     docs: {
       description: '`@restrict.to` must have valid values.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-to',
     },
-    hasSuggestions: true,
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      invalidType: 'Invalid type for value of `@restrict.to`. Must either be string or array of strings.',
+      pseudoRoleTypo: "Did you mean pseudo-role '{{valid}}' instead of '{{role}}'?",
+      any: 'Role \'any\' overrides all other roles. Replace by \'any\' only.'
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     return {
-      entity: checkRestrictTo
+      entity: checkRestrictTo,
+      service: checkRestrictTo,
+      action: checkRestrictTo,
+      function: checkRestrictTo,
     }
 
-    function checkRestrictTo (e) {
-      const USER_ROLES = []
-      const model = context.getModel()
+    function checkRestrictTo(def) {
+      // TODO: This check also applies to `@requires`. Test that.
+      if (!Array.isArray(def?.['@restrict']))
+        return
 
-      model.foreach('entity', (e) => {
-        if (e['@restrict']) {
-          e['@restrict'].forEach((p) => {
-            if (p.to) {
-              switch (typeof p.to) {
-                case 'string':
-                  if (p.to !== p.to.toLowerCase() && !USER_ROLES.includes(p.to)) {
-                    USER_ROLES.push(p.to)
-                  }
-                  break
-                case 'object':
-                  for (const r in p.to) {
-                    if (r !== r.toLowerCase() && !USER_ROLES.includes(r)) {
-                      USER_ROLES.push(r)
-                    }
-                  }
-              }
-            }
-          })
-        }
-      })
-      const ROLES = USER_ROLES.concat(VALID_PSEUDO_ROLES)
-
-      if (e['@restrict']) {
-        const node = context.getNode(e)
-        const file = e.$location.file
-
-        // TODO: For hierachies, check whether service restriction exists
-        // const { prefix } = splitDefName(e)
-        // const prefixSplit = prefix.split('.')
-        // const serviceName = prefixSplit[prefixSplit.length - 1]
-        // const services = model.services
-        // let grantAllTo;
-        // Object.values(services).map((s) => {
-        //   if (s.name === serviceName && s['@requires']) {
-        //     grantAllTo = s['@requires'];
-        //   }
-        // })
+      const node = context.getNode(def)
+      const file = def.$location.file
+      def['@restrict'].forEach(checkRestrictEntry)
 
-        for (const entry of e['@restrict']) {
-          if (Object.keys(entry).includes('to')) {
-            const toValue = entry.to
+      function checkRestrictEntry(entry) {
+        if (entry?.to !== undefined) {
+          const roles = getUserRoles(entry)
+          if (roles.every(checkRole)) {
+            // all roles are valid
+            if (roles.length > 1 && roles.includes('any'))
+              context.report({ messageId: 'any', node, file })
+          }
+        }
+      }
 
-            switch (typeof toValue) {
-              case 'string': {
-                if (isEmptyString(toValue)) {
-                  context.report({
-                    message: `Missing role on ${e.name} for \`@restrict.to\`.`,
-                    node,
-                    file
-                  })
-                } else {
-                  const isPseudoRole = entry.to && entry.to === entry.to.toLowerCase()
-                  if (!isStringInArray(toValue, ROLES, isPseudoRole)) {
-                    const candidates = findFuzzy(toValue, ROLES.sort())
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: toValue, candidates },
-                      node,
-                      file
-                    })
-                  }
-                }
-                break
-              }
+      function getUserRoles(entry) {
+        if (typeof entry.to === 'string') {
+          return [ entry.to ]
+        }
+        else if (Array.isArray(entry.to)) {
+          return entry.to
+        }
+        else {
+          // neither string nor array: report invalid type
+          context.report({ messageId: 'invalidType', node, file })
+          return []
+        }
+      }
 
-              case 'object':
-                if (isEmptyObject(toValue)) {
-                  context.report({
-                    message: `Missing roles on ${e.name} for \`@restrict.to\`.`,
-                    node,
-                    file
-                  })
-                } else {
-                  // If values contain 'any', 'any' only is enough
-                  if (toValue.length > 1 && toValue.includes('any')) {
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: `[${toValue}]`, candidates: ['["any"]'] },
-                      node,
-                      file
-                    })
-                  }
-                  toValue.forEach((value) => {
-                    if (!ROLES.includes(value)) {
-                      const candidates = findFuzzy(value, ROLES.sort(), undefined, false, 2)
-                      if (candidates.length > 0) {
-                        context.report({
-                          messageId: 'InvalidItem',
-                          data: { invalid: value, candidates },
-                          node,
-                          file
-                        })
-                      }
-                    }
-                  })
-                }
-                break
-            }
+      function checkRole(role) {
+        if (typeof role !== 'string') {
+          context.report({ messageId: 'invalidType', node, file })
+          return false
+        }
+        else if (role !== '') {
+          // empty roles handled by auth-no-empty-restrictions
+          const roleLowercase = role.toLowerCase()
+          if (roleLowercase !== role && VALID_PSEUDO_ROLES.has(roleLowercase)) {
+            context.report({
+              messageId: 'pseudoRoleTypo',
+              data: { role, valid: roleLowercase },
+              node, file,
+            })
+            return false
           }
+          return true
         }
       }
     }

package/lib/rules/auth-valid-restrict-where.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const cds = require('@sap/cds')
 
 module.exports = {
@@ -6,65 +8,64 @@ module.exports = {
     docs: {
       description: '`@restrict.where` must have valid values.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-where',
     },
     severity: 'error',
-    hasSuggestions: true,
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      compilationFailed: 'Invalid `where` expression, CDS compilation failed.',
+      invalidType: 'Invalid `where` type. Must be a string or expression.',
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     const model = context.getModel()
+    if (!model)
+      return
 
-    return {
-      entity: checkRestrictGrant
+    return function checkRestrictWhere() {
+      model.foreach('entity', checkEntityRestrict)
     }
 
-    function checkRestrictGrant (e) {
-      const USER_ROLES = []
+    function checkEntityRestrict (def) {
+      if (!Array.isArray(def['@restrict']))
+        return
+
+      for (const entry of def['@restrict']) {
+        if (entry?.where !== undefined) {
+          // TODO: Check return value (where xpr)
+          checkAndCompileWhereExpression(entry.where)
+        }
+      }
 
-      model.foreach('entity', (e) => {
-        if (e['@restrict']) {
-          e['@restrict'].forEach((p) => {
-            if (p.to) {
-              switch (typeof p.to) {
-                case 'string':
-                  if (p.to !== p.to.toLowerCase() && !USER_ROLES.includes(p.to)) {
-                    USER_ROLES.push(p.to)
-                  }
-                  break
-                case 'object':
-                  for (const r in p.to) {
-                    if (r !== r.toLowerCase() && !USER_ROLES.includes(r)) {
-                      USER_ROLES.push(r)
-                    }
-                  }
-              }
-            }
+      function checkAndCompileWhereExpression(where) {
+        if (where === null || Array.isArray(where) ||
+           (typeof where !== 'object' && typeof where !== 'string')) {
+          context.report({
+            messageId: 'invalidType',
+            node: context.getNode(def),
+            file: def.$location.file,
           })
+          return null
         }
-      })
 
-      if (e['@restrict']) {
-        const node = context.getNode(e)
-        const file = e.$location.file
-        for (const entry of e['@restrict']) {
-          const whereValues = entry.where
-          if (whereValues && typeof whereValues === 'string') {
-            try {
-              cds.parse.expr(entry.where)
-            } catch (_err) {
-              context.report({
-                message: 'Invalid `where` expression, CDS compilation failed.',
-                node,
-                file
-              })
-            }
-          }
+        try {
+          const compileOptions = {}
+          return typeof where === 'string'
+            ? cds.parse.expr(where, compileOptions)
+            : where
+
+        } catch(e) {
+          if (e.code !== 'ERR_CDS_COMPILATION_FAILURE')
+            throw e
+
+          context.report({
+            messageId: 'compilationFailed',
+            node: context.getNode(def),
+            file: def.$location.file,
+          })
+          return null
         }
       }
     }