modular-body

Lightweight and extendable body-parser for express style web frameworks

Installation

npm install modular-body

Basic usage:

import express from 'express';
import {bodyParser} from 'modular-body';

const app = express();
app.use(bodyParser()); // createse parsers for 'application/json', 'text/plain',
                       // 'application/octet-stream' and 'application/x-www-form-urlencoded'
app.listen(3000, () => console.log('Server running on port 3000'));

Please be aware that the prevention of prototype poisoning is only implemented for the first level of an object converted from JSON. If it is necessary also for nested objects, the implementation is shown further down in this readme.

import express from 'express';
import {bodyParser} from 'modular-body';

const app = express();
app.use(bodyParser.json()); // create parser only for 'application/json'
app.listen(3000, () => console.log('Server running on port 3000'));

Extended usage:

import express from 'express';
import {
  bodyParser,
  ParserConfigurations,
} from 'modular-body';
import {Buffer} from 'buffer';
import {MediaType} from './mediaTypes';

const parserConfigurations: ParserConfigurations = [
  'text/plain', // use default configuration
  { // change default configuration, not specified fields will be used from options entries
    // or from default configuration of parser
    inflate: ['identity', 'gzip', 'br'],
    limit: '20Mb', // use custom limit
    defaultEncoding: 'ucs-2', // this encoding will be used when charset is not specified
    encodings: ['latin1'], // add additional encodings which should be used for this parser
    matcher: 'application/json',
    parser: (payload: string) => JSON.stringify(payload, null, 2),
  }, {
    inflate: true, // allow 'identity', 'inflate', 'gzip' and 'br'
    matcher: 'application/octet-stream',
  }, { // create individual parser configuration
    inflate: 'identity', // allow no compression
    limit: 1000000,
    matcher: [
      'image/jpeg',
      'image/png',
      'mpeg/*',
      (mediaType: MediaType) => mediaType[0] === 'image' && mediaType[1].match(/+xml$/),
    ],
    parser: (payload: Buffer) => 'Creating image...',
  },
];

const app = express();
app.use(bodyParser({defaultLimit: '100kb', inflate: ['identity', 'br']}, parserConfigurations));

app.listen(3000, () => console.log('Server running on port 3000'));

Extending for special requirements

For extending equivalent to the npm package body-parser see the tests in rawBodyParser.test.ts, textBodyParser.test.ts, jsonBodyParser.test.ts and urlencodedBodyParser.test.ts.

import express from 'express';
import {
  bodyParser,
  BufferEncodings,
  ParserConfigurations
} from 'modular-body';
import base62str from 'base62str';
import LZWDecoder from 'lzw-stream/decoder';
import {Buffer} from 'buffer';

const bufferEncodings = [
  {
    encodings: ['base62', 'base-62'],
    transform: (buffer: Buffer) => base62str.decodeStr(buffer.toString()),
  }
];

const decompressors = {
  'lzw': () => new LZWDecoder,
};

const app = express();

app.use(bodyParser({inflate: true}, undefined, bufferEncodings, decompressors));

app.listen(3000, () => console.log('Server running on port 3000'));

Preventing prototype poisoning on nested parsed JSON objects

This is an example code to prevent prototype poisoning. The default implementation checks only the existence of a "proto" key only for the keys in the first object level because of speed considerations. If the usage of the "proto" key should be prevented for all nested objects then this parser configuration could be used.

import express from 'express';
import {
  bodyParser,
  ParserConfigurations,
} from 'modular-body';

type JSONValue =
    | string
    | number
    | boolean
    | { [x: string]: JSONValue }
    | Array<JSONValue>;

/**
 * Adapted from https://stackoverflow.com/questions/8085004/iterate-through-nested-javascript-objects
 * @param jsonValue The object from the parsed JSON string
 * @param key The key which should be found in the object
 */
function keyExistsInNestedObject(jsonValue: JSONValue, key: string) {
  const allLists: (null | JSONValue[])[] = [];
  const allArray: (null | JSONValue[])[] = [];
  if (typeof jsonValue !== 'object' || jsonValue === null) {
    return false;
  }
  if (Array.isArray(jsonValue)) {
    allArray.push(jsonValue);
  } else {
    if (Object.keys(jsonValue).includes(key)) {
      return true;
    }
    allLists.push(Object.values(jsonValue));
  }
  let allListsSize = allLists.length;
  let allArraySize = allArray.length;
  let indexLists = 0;
  let indexArray = 0;

  do {
    for (; indexArray < allArraySize; indexArray = indexArray + 1) {
      const currentArray = allArray[indexArray];
      const currentLength = (<JSONValue []>currentArray).length;
      for (let i = 0; i < currentLength; i += 1) {
        const arrayItemInner = (<JSONValue []>currentArray)[i];
        if (typeof arrayItemInner === 'object' && arrayItemInner !== null) {
          if (Array.isArray(arrayItemInner)) {
            allArraySize = allArray.push(arrayItemInner);
          } else {
            if (Object.keys(arrayItemInner).includes(key)) {
              return true;
            }
            allListsSize = allLists.push(Object.values(arrayItemInner));
          }
        }
      }
      allArray[indexArray] = null;
    }
    for (; indexLists < allListsSize; indexLists = indexLists + 1) {
      const currentList = allLists[indexLists];
      const currentLength = (<JSONValue []>currentList).length;
      for (let i = 0; i < currentLength; i += 1) {
        const listItemInner = (<JSONValue []>currentList)[i];
        if (typeof listItemInner === 'object' && listItemInner !== null) {
          if (Array.isArray(listItemInner)) {
            allArraySize = allArray.push(listItemInner);
          } else {
            if (Object.keys(listItemInner).includes(key)) {
              return true;
            }
            allListsSize = allLists.push(Object.values(listItemInner));
          }
        }
      }
      allLists[indexLists] = null;
    }
  } while (indexLists < allListsSize || indexArray < allArraySize);
  return false;
}

const parserConfiguration = <ParserConfigurations<string, JSONValue>>{
  matcher: 'application/json',
  parser: (payload: string) => {
    const jsonObject: JSONValue = JSON.parse(payload);
    if (
      typeof jsonObject === 'object'
      && payload.includes('"__proto__":')
      && keyExistsInNestedObject(jsonObject, '__proto__')
    ) {
      throw new Error('Using "__proto__" as JSON key is not allowed.');
    }
    return jsonObject;
  },
  defaultEncoding: 'utf-8',
  emptyResponse: {},
};

const app = express();
app.use(bodyParser({defaultLimit: '100kb', inflate: ['identity', 'br']}, parserConfiguration));

app.listen(3000, () => console.log('Server running on port 3000'));

Type DefaultOptions

Properties

Name	Type	Details
defaultLimit	number | string	The default limit which should be set on the parser configurations, default is '20kb'.
inflate	true | string | string[]	When true allows all available decompressors, otherwise only specified decompressors. Default is 'identity'.
requireContentLength	boolean	Set if the 'Content-Length' header has to be set, default is false.
defaultContentType	string	When 'Content-Type' header is missing, then use this as default. Default is not set which will throw when header is missing.

Type ParserConfiguration<U, V>

Properties

Name	Type	Details
inflate	true | string | string[]	Add the allowed decompressors(s) as string or array, allow all decompressors with true
limit	string | number	Specify the maximum allowed body size as a number in bytes or as a byte string
requireContentLength	boolean	Specify if the header 'Content-Length' has to be set on the request
parser	((payload: Buffer | U) => V) | null	A function to parse the payload from the buffer or after encoding
matcher	MediaTypeIdentifier | MediaTypeIdentifier[]	The matchers for the allowed mime types as a matching function or mime type where '*' is allowed on either side of the slash to matches all.
encodings	string | string[] | boolean | null	Allow the specified encoding(s), allow all with true, remove/prevent with false or null from default config, no encoding with undefined
defaultEncoding	string	The encoding which should be used when 'charset' is not set on the 'Content-Type' header
verify	(req: Request<U, V>, res: Response, buffer: Buffer | U | V, body?: Body<U, V>, encoding: string | false) => void	Function to verify the body, it should throw when verify fails

For more details please consult the type documentation in the doc folder after building with npm run docs.

Type BufferEncoder<T, U> = ChunkedBufferEncoder<T, U> | UnchunkedBufferEncoder<U>;

Type ChunkedBufferEncoder<T, U>

Properties

Name	Type	Details
onData	(buffer: Buffer) => T	Transform function for the chunk from the 'onData' event
onEnd	() => T	Transform function for the 'onEnd' event
reduce	(array: T[]) => U	Reduce function to join the array with the transformed chunks
encodings	string[]	Array with charset names for which this encoder should be used

Type UnchunkedBufferEncoder<U>;

Properties

Name	Type	Details
transform	(buffer: Buffer) => U	The transform function to encode the joined buffer.
encodings	string[]	Array with charset names for which this encoder should be used

Type Decompressors = Record<string, () => Transform>;

Keys are the names for the decompressors, values are functions resolving to stream transformers.

Function bodyParser<T, U, V>

Parameters

Name	Type	Details
options	DefaultOptions	Default options for the parserConfiguration
parserConfigurations	ParserConfigurations<U, V>	An array of objects of type ParserConfiguration and/or DefaultMediaType or a single of these
bufferEncodings	BufferEncoder<T, U>[]	An object where we can add/replace buffer encodings
decompressors	Decompressors	An object where we can add/replace stream decompressors

Function bodyParser.json

Parameters

Name	Type	Details
options	DefaultOptions	Default options for the parserConfiguration
bufferEncodings	BufferEncoder<string, string>[]	An object where we can add/replace buffer encodings
decompressors	Decompressors	An object where we can add/replace stream decompressors

Function bodyParser.raw

Parameters

Name	Type	Details
options	DefaultOptions	Default options for the parserConfiguration
decompressors	Decompressors	An object where we can add/replace stream decompressors

Function bodyParser.urlencoded

Parameters

Name	Type	Details
options	DefaultOptions	Default options for the parserConfiguration
bufferEncodings	BufferEncoder<string, string>[]	An object where we can add/replace buffer encodings
decompressors	Decompressors	An object where we can add/replace stream decompressors

Function bodyParser.text

Parameters

Name	Type	Details
options	DefaultOptions	Default options for the parserConfiguration
bufferEncodings	BufferEncoder<string, string>[]	An object where we can add/replace buffer encodings
decompressors	Decompressors	An object where we can add/replace stream decompressors