AC Sanitizer
Sanitizes payloads with given field definitions
Version 4 - Breaking changes
Version 4 requires Node 16.
Usage
const sanitizer = require('ac-sanitizer')
let fieldsToCheck = {
params: {
stringVar: 'This is a string'
},
fields: [
{ field: 'stringVar', type: 'string', required: true },
{ field: 'forceJob', type: 'boolean', adminLevel: 64 }
],
adminLevel: 32 // optional adminLevel of the user - must be at least the one defined in fields
}
let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
// COMPLEX EXAMPLE WITH NESTED PROPERTIES AND CONDITIONAL REQUIREMENTS
const sanitizer = require('ac-sanitizer')
let fieldsToCheck = {
params: {
obj: {
f1: true
},
fields: [
{ field: 'obj', type: 'object', properties: [
{ field: 'f1', type: 'boolean' },
{ field: 'f2', type: 'boolean', required: 'f1' } // if f1 is true, then f2 is required
]}
]
}
let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
Field definition
Parameter | Type | Remarks |
---|---|---|
field | string | Name of the field |
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 path1 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 |
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. |
nullAllowed | [boolean] | If true, sending NULL is allowed. |
ENUM lists
The following enum lists are available using a string placeholder
Placeholder | Items | Remarks |
---|---|---|
iso-639-1 | ISO 639-1 entries | e.g. de, en, fr, es... |
iso-639-2 | ISO 639-2 entries | e.g. deu, eng, fra ... |
countrylist | list of country names | e.g. Laos, Brazil, Norway... |
Convert
Some types allow automatic conversion:
Type | Example | Remarks |
---|---|---|
integer | 60.1 -> 60 | Convert incoming number to integer - this way you can make your check more lenient |
string | Hello Developer -> Hello (with maxLength = 5) | Reduce string to max length |
base64 | SGVsbG8= -> Hello | Convert base64 encoded string to UTF-8 string |
iso-639 | { iso-639-2: 'tlh', translations: [] } -> tlh (with convert=iso-639-2) | Returns only the select property for the ISO-639 object |
Available types
Type | Options | Remarks |
---|---|---|
any | Any can be string, integer, boolean, object or array - it will be automatically detected. | |
base64 | Checks if a string is base64 encoded, optional with field option "convert" (to string) | |
boolean | ||
cidr | Check CIDR, see example | |
integer | boolean | Value can be an integer OR a boolean | |
date | dateFormat | Date or date time, support various date formats (e.g. DD.MM.YYYY, DD/MM/YYYY, YYYY-MM-DD, etc) as well as a custom format defined in dateFormat. |
fqdn | wildcardAllowed (bool) | Fully qualified domain names, optional with wildcard subdomain (e.g. *.admiralcloud.com) |
a@b.c | ||
float | 0 - 2^31 | |
fileExtension | ||
gps | Can be a string of "LAT,LNG" or one including a distance as 3rd parameter like "LAT,LNG,DISTANCE". | |
hashids | HashIds - https://hashids.org | |
hexColor | Check valid hexadecimal color like #ff99cc | |
integer | 0 - 2^31 | |
integer | string | Value can be an integer OR a string | |
iso-639-1 | convert | With convert = nativeName you can retrieve the native name of the given ISO string |
iso-639-2 | convert | With convert = nativeName you can retrieve the native name of the given ISO string |
ip | version | version can be "4" or "6", defaults to "4" |
long | 0 - 2^63 | |
object | properties | Use properties to define object structure, properties is equal to fields array |
number | Should no be used - use integer, long, short, floag | |
ratio | x:y | |
rgb | Check for valid RGB value (r,g,b) or (r%,g%, b%) | |
short | 0 - 2^15 | |
string | minLength (int), maxLength (int) | |
url | protocols, require_tld, require_protocol | Default values: protocols ['http', 'https'], required_tld true, require_protocol true |
Examples
CIDR
// CIDR Example
const sanitizer = require('ac-sanitizer')
let fieldsToCheck = {
params: {
cidr: [{ cidr: '8.8.8.8/32' }]
},
fields: [
{ field: 'cidr', type: 'cidr' }
]
}
let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
// multiple mixed CIDR
let fieldsToCheck = {
params: {
cidr: [
{ cidr: '8.8.8.8/32' },
{ cidr: '::ffff:127.0.0.1', type: 'ipv6' }
]
},
fields: [
{ field: 'cidr', type: 'cidr' }
]
}
let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
Objects
By default properties which are not defined will be ignored and removed from payload.
Objects with strict mode activate
In strict mode, only defined properties are allowed.
let fieldsToCheck = {
params: {
settings: {
allowed: true,
notAllowed: true
}
},
fields: [
{ field: 'settings', type: 'object', strict: true, properties: [
{ field: 'allowed', type: 'boolean' }
] }
]
}
let test = sanitizer.checkAndSanitizeValues(fieldsToCheck)
// error: object_settings_containsInvalidProperties
Links
License
MIT License Copyright © 2009-present, AdmiralCloud AG, Mark Poepping
-
The path must be set with the parent propery as root, e.g. the actual field is settings.video.width, in property video the condition is then just "width" not the full path. ↩