ac-sanitizer 6.0.7 → 6.1.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# [6.1.0](https://github.com/mmpro/ac-sanitizer/compare/v6.0.7..v6.1.0) (2026-04-28 11:20:30)
+
+
+### Feature
+
+
+* **App:** Added iamPermission to limit access to field | MP | [dce29ae609119fcaced0e966792157b2b3747631](https://github.com/mmpro/ac-sanitizer/commit/dce29ae609119fcaced0e966792157b2b3747631)    
+Added iamPermission to limit access to field  
+Related issues:
+### Bug Fix
+
+
+* **App:** Prefer IAM permissions | MP | [c8fa1271c179e93c175bdf43ce0aaad43ea8ec23](https://github.com/mmpro/ac-sanitizer/commit/c8fa1271c179e93c175bdf43ce0aaad43ea8ec23)    
+If IAM permissions are set and send, ignore adminLevel  
+Related issues:
+* **App:** Minor adjustments after CoPilot review | MP | [2847150158b7ac325a648c5fcea5a8ba3d805462](https://github.com/mmpro/ac-sanitizer/commit/2847150158b7ac325a648c5fcea5a8ba3d805462)    
+iamPermissions must be an array. Added test for deeply nested objects  
+Related issues:
 ## [6.0.7](https://github.com/mmpro/ac-sanitizer/compare/v6.0.6..v6.0.7) (2026-04-24 19:06:20)
 
 

package/README.md

@@ -25,6 +25,29 @@ let fieldsToCheck = {
 let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
 ```
 
+```
+// IAM PERMISSIONS EXAMPLE
+// Fields can be protected by IAM permissions. The user must have at least one of the
+// listed permissions (OR logic). If userPermissions is not provided, the check is skipped.
+
+const sanitizer = require('ac-sanitizer')
+
+let fieldsToCheck = {
+  params: {
+    title: 'My Media',
+    internalNote: 'confidential'
+  },
+  fields: [
+    { field: 'title', type: 'string' },
+    { field: 'internalNote', type: 'string', iamPermissions: ['media.admin', 'media.write'] }  // array, at least one must match
+  ],
+  userPermissions: ['media.read'],  // user does not have media.admin or media.write
+  omitFields: true                  // omit instead of returning an error
+}
+let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
+// result: { params: { title: 'My Media' } }  -> internalNote is silently removed
+```
+
 ```
 // COMPLEX EXAMPLE WITH NESTED PROPERTIES AND CONDITIONAL REQUIREMENTS
 
@@ -55,7 +78,8 @@ type | string | Type of the field to sanitize, see below for available values
 required | [boolean OR string] | Set to true if required or set a path[^1] to a param (if that param is set, this value is required)
 enum | [array OR string] | Optional list of allowed values. You can a string placeholder for certain standard lists (see below)
 adminLevel | [integer] | Optional adminLevel required for this field
-omitFields | [boolean] | If adminLevel is set and you do not have the proper adminLevel the sanitizer will just omit the field (and not return an error) if omitFields is true
+iamPermissions | [array] | Optional list of IAM permissions required to access this field. At least one permission must match (OR logic). If `userPermissions` is not provided to `checkAndSanitizeValues`, the check is skipped.
+omitFields | [boolean] | If adminLevel/iamPermissions is set and the user does not have sufficient access, the sanitizer will just omit the field (and not return an error) if omitFields is true
 convert | [boolean OR string] | Some types can be automatically converted (e.g. base64 to string)
 valueType | [string] | Use it to sanitize values of an array by defining the allowed type here
 strict | [boolean] | For objects only - if true and payload contains a property not defined, an error will be returned.

package/index.js

@@ -49,7 +49,7 @@ const sanitizer = function() {
    *
    * @param params.params OBJECT params object (e.g. from body paylod) to sanitize (example { id: 1, user: 'tom' })
    * @param params.fields ARRAY array of field definitions
-   * @param params.adminLevel INT level of the requesting user, will be compared against field's adminLevel
+   * @param params.adminLevel INT DEPRECATED level of the requesting user, will be compared against field's adminLevel
    *
    * @param return.error OBJECT returned error message (if there is an error)
    * @param return.params OBJECT returned sanitized object (invalid keys are removed)
@@ -61,7 +61,8 @@ const sanitizer = function() {
     let fields = params.fields
     if (!_.isArray(fields) || !_.size(fields)) { return { error: { message: 'fields_required' } } }
 
-    const adminLevel = _.get(params, 'adminLevel')
+    const adminLevel = _.get(params, 'adminLevel') // DEPRECATED, use iamPermissions instead
+    const userPermissions = _.compact(_.get(params, 'userPermissions', []))
     const omitFields = _.get(params, 'omitFields')
 
     let error
@@ -201,7 +202,8 @@ const sanitizer = function() {
           })
         }
       }
-      else if (_.get(field, 'adminLevel') && adminLevel < _.get(field, 'adminLevel')) {
+      else if (_.get(field, 'adminLevel') && !(_.get(field, 'iamPermissions') && _.size(userPermissions)) && adminLevel < _.get(field, 'adminLevel')) {
+        console.warn('SANITIZER - adminLevel is deprecated for field %s, please migrate to iamPermissions', fieldName)
         if (omitFields) {
           fields = _.filter(fields, item => {
             if (item.field !== fieldName) { return item }
@@ -211,6 +213,17 @@ const sanitizer = function() {
           error = { message: `${fieldName}_adminLevelNotSufficient`, additionalInfo: { adminLevel, required: _.get(field, 'adminLevel') } }
         }
       }
+      else if (_.get(field, 'iamPermissions') && _.size(userPermissions) && !_.size(_.intersection(userPermissions, field.iamPermissions))) {
+        if (!_.isArray(field.iamPermissions)) {
+          console.error('SANITIZER - iamPermissions must be an array, field %s', fieldName)
+        }
+        if (omitFields) {
+          fields = _.filter(fields, item => item.field !== fieldName)
+        }
+        else {
+          error = { message: `${fieldName}_iamPermissionNotSufficient`, additionalInfo: { required: field.iamPermissions } }
+        }
+      }
       else if (_.indexOf(['number', 'integer', 'long', 'short', 'float'], field.type) > -1) {
         if (typeof value !== 'number' || isNaN(value)) { error = { message: fieldName + '_' + getTypeMapping('integer', 'errorMessage') } }
         else {
@@ -294,11 +307,14 @@ const sanitizer = function() {
 
             const fieldsToCheck = {
               params: {},
-              fields: [{ 
-                field: fieldName, 
-                type: valueType, 
+              fields: [{
+                field: fieldName,
+                type: valueType,
                 ...fieldProps
-              }]
+              }],
+              adminLevel,
+              omitFields,
+              userPermissions
             }
             _.set(fieldsToCheck, `params.${fieldName}`, v)
             const check = checkAndSanitizeValues(fieldsToCheck)
@@ -345,7 +361,8 @@ const sanitizer = function() {
             fields: _.get(field, 'properties'),
             prefix: fieldName,
             adminLevel: _.get(field, 'adminLevel', adminLevel),
-            omitFields: _.get(field, 'omitFields', omitFields)
+            omitFields: _.get(field, 'omitFields', omitFields),
+            userPermissions
           }
           const check = checkAndSanitizeValues(fieldsToCheck)
           if (_.get(check, 'error')) { error = _.get(check, 'error') }

package/package.json

@@ -4,7 +4,7 @@
   "author": "Mark Poepping (https://www.admiralcloud.com)",
   "license": "MIT",
   "repository": "admiralcloud/ac-sanitizer",
-  "version": "6.0.7",
+  "version": "6.1.0",
   "homepage": "https://www.admiralcloud.com",
   "dependencies": {
     "ac-countrylist": "^1.0.19",

package/test/suites/default.js

@@ -12,6 +12,11 @@ module.exports = {
       tests.error.test()
     })
 
+    describe('IAM PERMISSIONS', function() {
+      this.timeout(timeOut)
+      tests.iamPermissions.test()
+    })
+
     describe('ANY', function() {
       this.timeout(timeOut)
       tests.any.test()

package/test/tests/iamPermissions.js

@@ -0,0 +1,212 @@
+const sanitizer = require('../../index')
+
+module.exports = {
+  test: () => {
+    it('Field with iamPermissions - user has matching permission -> field is included', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello' },
+        fields: [{ field: 'title', type: 'string', iamPermissions: ['media.read'] }],
+        userPermissions: ['media.read', 'media.write']
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.title).to.equal('Hello')
+      return done()
+    })
+
+    it('Field with iamPermissions as array - user has one of the required permissions (OR logic) -> field is included', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello' },
+        fields: [{ field: 'title', type: 'string', iamPermissions: ['media.admin', 'media.read'] }],
+        userPermissions: ['media.read']
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.title).to.equal('Hello')
+      return done()
+    })
+
+    it('Field with iamPermissions - user has none of the required permissions -> error', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello' },
+        fields: [{ field: 'title', type: 'string', iamPermissions: ['media.admin', 'media.write'] }],
+        userPermissions: ['media.read']
+      })
+      expect(r.error.message).to.equal('title_iamPermissionNotSufficient')
+      expect(r.error.additionalInfo.required).to.eql(['media.admin', 'media.write'])
+      return done()
+    })
+
+    it('Field with iamPermissions - user has none of the required permissions and omitFields is true -> field is omitted silently', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello', id: 1 },
+        fields: [
+          { field: 'title', type: 'string', iamPermissions: ['media.admin'] },
+          { field: 'id', type: 'integer' }
+        ],
+        userPermissions: ['media.read'],
+        omitFields: true
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.title).to.be.undefined
+      expect(r.params.id).to.equal(1)
+      return done()
+    })
+
+    it('Field with both adminLevel and iamPermissions - userPermissions available -> iamPermissions wins, adminLevel is ignored', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello' },
+        fields: [{ field: 'title', type: 'string', adminLevel: 100, iamPermissions: ['media.read'] }],
+        adminLevel: 0,  // would fail adminLevel check
+        userPermissions: ['media.read']
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.title).to.equal('Hello')
+      return done()
+    })
+
+    it('Field with both adminLevel and iamPermissions - no userPermissions -> falls back to adminLevel', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello' },
+        fields: [{ field: 'title', type: 'string', adminLevel: 100, iamPermissions: ['media.read'] }],
+        adminLevel: 0  // no userPermissions -> adminLevel check applies
+      })
+      expect(r.error.message).to.equal('title_adminLevelNotSufficient')
+      return done()
+    })
+
+    it('Field with iamPermissions - no userPermissions provided -> check is skipped, field is included', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { title: 'Hello' },
+        fields: [{ field: 'title', type: 'string', iamPermissions: ['media.admin'] }]
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.title).to.equal('Hello')
+      return done()
+    })
+
+    it('Nested object field with iamPermissions - user has permission -> nested field is included', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { settings: { level: 5, secret: 'topsecret' } },
+        fields: [{
+          field: 'settings',
+          type: 'object',
+          properties: [
+            { field: 'level', type: 'integer' },
+            { field: 'secret', type: 'string', iamPermissions: ['settings.admin'] }
+          ]
+        }],
+        userPermissions: ['settings.admin']
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.settings.secret).to.equal('topsecret')
+      return done()
+    })
+
+    it('Nested object field with iamPermissions - user lacks permission and omitFields true -> nested field is omitted', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { settings: { level: 5, secret: 'topsecret' } },
+        fields: [{
+          field: 'settings',
+          type: 'object',
+          properties: [
+            { field: 'level', type: 'integer' },
+            { field: 'secret', type: 'string', iamPermissions: ['settings.admin'] }
+          ]
+        }],
+        userPermissions: ['media.read'],
+        omitFields: true
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.settings.level).to.equal(5)
+      expect(r.params.settings.secret).to.be.undefined
+      return done()
+    })
+    it('Deeply nested object field with iamPermissions - user has permission -> field is included', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { settings: { nested: { level: 5, secret: 'topsecret' } } },
+        fields: [{
+          field: 'settings',
+          type: 'object',
+          properties: [{
+            field: 'nested',
+            type: 'object',
+            properties: [
+              { field: 'level', type: 'integer' },
+              { field: 'secret', type: 'string', iamPermissions: ['settings.admin'] }
+            ]
+          }]
+        }],
+        userPermissions: ['settings.admin']
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.settings.nested.secret).to.equal('topsecret')
+      return done()
+    })
+
+    it('Deeply nested object field with iamPermissions - user lacks permission and omitFields true -> field is omitted', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { settings: { nested: { level: 5, secret: 'topsecret' } } },
+        fields: [{
+          field: 'settings',
+          type: 'object',
+          properties: [{
+            field: 'nested',
+            type: 'object',
+            properties: [
+              { field: 'level', type: 'integer' },
+              { field: 'secret', type: 'string', iamPermissions: ['settings.admin'] }
+            ]
+          }]
+        }],
+        userPermissions: ['media.read'],
+        omitFields: true
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.settings.nested.level).to.equal(5)
+      expect(r.params.settings.nested.secret).to.be.undefined
+      return done()
+    })
+
+    it('Array of objects with iamPermissions - user has permission -> field is included in all items', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { items: [{ name: 'foo', secret: 'a' }, { name: 'bar', secret: 'b' }] },
+        fields: [{
+          field: 'items',
+          type: 'array',
+          valueType: 'object',
+          properties: [
+            { field: 'name', type: 'string' },
+            { field: 'secret', type: 'string', iamPermissions: ['media.admin'] }
+          ]
+        }],
+        userPermissions: ['media.admin']
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.items[0].secret).to.equal('a')
+      expect(r.params.items[1].secret).to.equal('b')
+      return done()
+    })
+
+    it('Array of objects with iamPermissions - user lacks permission and omitFields true -> field is omitted from all items', (done) => {
+      const r = sanitizer.checkAndSanitizeValues({
+        params: { items: [{ name: 'foo', secret: 'a' }, { name: 'bar', secret: 'b' }] },
+        fields: [{
+          field: 'items',
+          type: 'array',
+          valueType: 'object',
+          properties: [
+            { field: 'name', type: 'string' },
+            { field: 'secret', type: 'string', iamPermissions: ['media.admin'] }
+          ]
+        }],
+        userPermissions: ['media.read'],
+        omitFields: true
+      })
+      expect(r.error).to.be.undefined
+      expect(r.params.items[0].name).to.equal('foo')
+      expect(r.params.items[0].secret).to.be.undefined
+      expect(r.params.items[1].name).to.equal('bar')
+      expect(r.params.items[1].secret).to.be.undefined
+      return done()
+    })
+  }
+}

package/test/tests/index.js

@@ -1,5 +1,6 @@
 module.exports = {
   any: require('./any'),
+  iamPermissions: require('./iamPermissions'),
   array: require('./array'),
   base64: require('./base64'),
   bool: require('./bool'),