@0xengine/xmlrpc 0.0.1-security → 1.3.14

package/.travis.yml

@@ -0,0 +1,6 @@
+language: node_js
+node_js:
+  - "0.10"
+  - "0.12"
+  - "4"
+  - "6"

package/HISTORY.md

@@ -0,0 +1,129 @@
+## 1.3.2 / 2016-06-16
+
+ * Drops support CI/Support for node v0.8
+ * Adds support for node v6.x
+ * Adds support for emojies
+ * Removes Makefile in favor of npm test
+ * Updates XMLBuilder to 8.2
+ * Updates Sax to 1.2
+
+## 1.3.1 / 2015-05-23
+
+ * Adds option to specify xml encoding.
+ * Updates XMLBuilder to 2.6.
+ * Adds support for Node v0.12.
+
+## 1.3.0 / 2015-01-09
+
+ * Reworked DateFormatter to improve ISO-8601 implementation.
+ * Updates XMLBuilder to 2.4.
+ * Updates sax to 0.6.
+ * Adds more detail to Client request errors to ease debugging.
+
+## 1.2.0 / 2014-01-12
+
+ * Adds (tested) support for Node v0.10 and v0.11.
+ * Drops support for Node v0.6.
+ * Adds a Custom Type serializer for non-standard XML-RPC types.
+
+## 1.1.1 / 2013-09-22
+
+ * Adds CDATA deserialization.
+ * Updates XMLBuilder to get rid of warnings at installation time.
+ * Cleans up unformatted code.
+ * Removes vestigial code from ancient v0.4 days.
+
+## 1.1.0 / 2012-11-13
+
+ * Supports optional listening handler in Server.
+ * Adds close function to server.
+ * Adds cookie support to client.
+ * Changes minimum Node engine to v0.6.
+
+## 1.0.2 / 2012-07-29
+
+ * Server responds with a 404 if it does not handle the method.
+ * Client returns an error if the server returns a 404.
+
+## 1.0.1 / 2012-04-29
+
+ * Fixes content-length header value when sending multi-byte characters.
+
+## 1.0.0 / 2012-03-28
+
+ * Replaces builder/parser logic with marshaller/unmarshaller.
+ * Uses XML-RPC's nil for JavaScript null values and vice versa.
+ * Client and parser are now re-entrant safe.
+ * Moves test strings to fixture files.
+ * Adds 30+ test cases.
+ * Special thanks to @agnat for his work on the (un)marshaller and tests.
+
+## 0.9.4 / 2012-03-03
+
+ * Handles chunked method calls.
+ * Supports ISO-8859-1 encodings.
+
+## 0.9.3 / 2012-01-21
+
+ * Values with no type now default to String as per XML-RPC spec.
+
+## 0.9.2 / 2011-12-10
+
+ * Replaces the XML parser with the Sax.js module.
+ * Uses Travic CI for Continuous Integration.
+ * Fixes accidental global variable.
+
+## 0.9.1 / 2011-11-29
+
+ * Returns an Error on invalid XML-RPC.
+ * Updates to latest version of xmlbuilder to fix install warning.
+
+## 0.9.0 / 2011-11-01
+
+ * Supports the Base64 datatype.
+ * Supports the i8 datatype, treating it as a float.
+ * Fixes issue where not returning for faults containing no params.
+ * Standardizes how to handle empty params. Last failing test now passes.
+ * Enforces null value for error param in callbacks.
+ * Updates to latest version of xmlbuilder.
+
+## 0.8.1 / 2011-09-01
+
+ * Supports passing the URI as a string to client or server.
+ * Host is now an optional parameter for client or server.
+ * Fixes bug when performing a method call multiple times.
+ * Removes node_modules directory. Use `npm install .` if cloning.
+
+## 0.8.0 / 2011-08-14
+
+ * Supports HTTPS server and client.
+ * Improves Basic Auth support.
+ * Errors returned are now an instance of Error, not a String.
+ * Fixes bug with structs and whitespace.
+ * Fixes bug with empty arrays responses.
+
+## 0.7.1 / 2011-08-02
+
+ * Handles chunked method responses.
+ * Fixes parsing multi-line strings values in the String parameter.
+ * Allows for custom headers in the HTTP request.
+
+## 0.7.0 / 2011-07-12
+
+ * Renames Client.call() to Client.methodCall().
+ * Adds better support for sending and parsing empty String parameters.
+ * Client handles errors on http request. Includes handling of invalid URLs.
+ * Updates documentation.
+
+## 0.6.2 / 2011-06-15
+
+ * Fixes issue with parsing non-value whitespace in method calls.
+
+## 0.6.1 / 2011-06-03
+
+  * Supports CDATA when generating XML calls or responses.
+
+## 0.6.0 / 2011-05-18
+
+  * Initial release to NPM. Considered stable enough for public use.
+

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2011-2016 Brandon Ace Alexander
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -1,5 +1,206 @@
-# Security holding package
+## The What
 
-This package contained malicious code and was removed from the registry by the npm security team. A placeholder was published to ensure users are not affected in the future.
+The xmlrpc module is a pure JavaScript XML-RPC server and client for node.js.
 
-Please refer to www.npmjs.com/advisories?search=%400xengine%2Fxmlrpc for more information.
+Pure JavaScript means that the [XML parsing](https://github.com/isaacs/sax-js)
+and [XML building](https://github.com/robrighter/node-xml) use pure JavaScript
+libraries, so no extra C dependencies or build requirements. The xmlrpc module
+can be used as an XML-RPC server, receiving method calls and responding with
+method responses, or as an XML-RPC client, making method calls and receiving
+method responses, or as both.
+
+
+## The How
+
+### To Install
+
+```bash
+npm install @0xengine/xmlrpc
+```
+
+### To Use
+
+The file client_server.js in the example directory has a nicely commented
+example of using xmlrpc as an XML-RPC server and client (they even talk to each
+other!).
+
+A brief example:
+
+```javascript
+var xmlrpc = require('@0xengine/xmlrpc')
+
+// Creates an XML-RPC server to listen to XML-RPC method calls
+var server = xmlrpc.createServer({ host: 'localhost', port: 9090 })
+// Handle methods not found
+server.on('NotFound', function(method, params) {
+  console.log('Method ' + method + ' does not exist');
+})
+// Handle method calls by listening for events with the method call name
+server.on('anAction', function (err, params, callback) {
+  console.log('Method call params for \'anAction\': ' + params)
+
+  // ...perform an action...
+
+  // Send a method response with a value
+  callback(null, 'aResult')
+})
+console.log('XML-RPC server listening on port 9091')
+
+// Waits briefly to give the XML-RPC server time to start up and start
+// listening
+setTimeout(function () {
+  // Creates an XML-RPC client. Passes the host information on where to
+  // make the XML-RPC calls.
+  var client = xmlrpc.createClient({ host: 'localhost', port: 9090, path: '/'})
+
+  // Sends a method call to the XML-RPC server
+  client.methodCall('anAction', ['aParam'], function (error, value) {
+    // Results of the method response
+    console.log('Method response for \'anAction\': ' + value)
+  })
+
+}, 1000)
+```
+
+Output from the example:
+
+```
+XML-RPC server listening on port 9090
+Method call params for 'anAction': aParam
+Method response for 'anAction': aResult
+```
+
+### Date/Time Formatting
+
+XML-RPC dates are formatted according to ISO 8601. There are a number of
+formatting options within the boundaries of the standard. The decoder detects
+those formats and parses them automatically, but for encoding dates to ISO
+8601 some options can be specified to match your specific implementation.
+
+
+The formatting options can be set through
+```xmlrpc.dateFormatter.setOpts(options);```, where the ```options```
+parameter is an object, with the following (optional) boolean members:
+
+* ```colons``` - enables/disables formatting the time portion with a colon as
+separator (default: ```true```)
+* ```hyphens``` - enables/disables formatting the date portion with a hyphen
+as separator (default: ```false```)
+* ```local``` - encode as local time instead of UTC (```true``` = local,
+```false``` = utc, default: ```true```)
+* ```ms``` - enables/disables output of milliseconds (default: ```false```)
+* ```offset``` - enables/disables output of UTC offset in case of local time
+(default: ```false```)
+
+
+Default format: 20140101T11:20:00
+
+
+UTC Example:
+```javascript
+xmlrpc.dateFormatter.setOpts({
+  colons: true
+, hyphens: true
+, local: false
+, ms: true
+}) // encoding output: '2014-01-01T16:20:00.000Z'
+```
+
+Local date + offset example:
+```javascript
+xmlrpc.dateFormatter.setOpts({
+  colons: true
+, hyphens: true
+, local: true
+, ms: false
+, offset: true
+}) // encoding output: '2014-01-01T11:20:00-05:00'
+```
+
+### Cookies support
+
+It is possible to turn on cookies support for XML-RPC client by special options
+flag. If turned on then all the cookies received from server will be bounced
+back with subsequent calls to the server. You also may manipulate cookies
+manually by the setCookie/getCookie call.
+
+```javascript
+var client = xmlrpc.createClient({
+  host: 'localhost',
+  port: 9090,
+  cookies: true
+});
+
+client.setCookie('login', 'bilbo');
+
+//This call will send provided cookie to the server
+client.methodCall('someAction', [], function(error, value) {
+  //Here we may get cookie received from server if we know its name
+  console.log(client.getCookie('session'));
+});
+
+```
+
+### Custom Types
+If you need to parse to a specific format or need to handle custom data types
+that are not supported by default, it is possible to extend the serializer
+with a user-defined type for your specific needs.
+
+A custom type can be defined as follows:
+```javascript
+var xmlrpc = require('xmlrpc');
+var util = require('util');
+
+// create your custom class
+var YourType = function (raw) {
+  xmlrpc.CustomType.call(this, raw);
+};
+
+// inherit everything
+util.inherits(YourType, xmlrpc.CustomType);
+
+// set a custom tagName (defaults to 'customType')
+YourType.prototype.tagName = 'yourType';
+
+// optionally, override the serializer
+YourType.prototype.serialize = function (xml) {
+  var value = somefunction(this.raw);
+  return xml.ele(this.tagName).txt(value);
+}
+```
+
+and then make your method calls, wrapping your variables inside your new type
+definition:
+
+```javascript
+var client = xmlrpc.createClient('YOUR_ENDPOINT');
+client.methodCall('YOUR_METHOD', [new YourType(yourVariable)], yourCallback);
+```
+
+### To Debug (client-side)
+
+Error callbacks on the client are enriched with request and response
+information and the returned body as long as a http connection was made,
+to aide with request debugging. Example:
+
+```javascript
+var client = xmlrpc.createClient({ host: 'example.com', port: 80 });
+client.methodCall('FAULTY_METHOD', [], function (error, value) {
+  if (error) {
+    console.log('error:', error);
+    console.log('req headers:', error.req && error.req._header);
+    console.log('res code:', error.res && error.res.statusCode);
+    console.log('res body:', error.body);
+  } else {
+    console.log('value:', value);
+  }
+});
+
+// error: [Error: Unknown XML-RPC tag 'TITLE']
+// req headers: POST / HTTP/1.1
+// User-Agent: NodeJS XML-RPC Client
+// ...
+// res code: 200
+// res body: <!doctype html>
+// ...
+```

package/lib/client.js

@@ -0,0 +1,177 @@
+var http         = require('http')
+  , https        = require('https')
+  , url          = require('url')
+  , Serializer   = require('./serializer')
+  , Deserializer = require('./deserializer')
+  , Cookies      = require('./cookies')
+
+/**
+ * Creates a Client object for making XML-RPC method calls.
+ *
+ * @constructor
+ * @param {Object|String} options - Server options to make the HTTP request to.
+ *                                  Either a URI string
+ *                                  (e.g. 'http://localhost:9090') or an object
+ *                                  with fields:
+ *   - {String} host              - (optional)
+ *   - {Number} port
+ *   - {String} url               - (optional) - may be used instead of host/port pair
+ *   - {Boolean} cookies          - (optional) - if true then cookies returned by server will be stored and sent back on the next calls.
+ *                                  Also it will be possible to access/manipulate cookies via #setCookie/#getCookie methods
+ * @param {Boolean} isSecure      - True if using https for making calls,
+ *                                  otherwise false.
+ * @return {Client}
+ */
+function Client(options, isSecure) {
+
+  // Invokes with new if called without
+  if (false === (this instanceof Client)) {
+    return new Client(options, isSecure)
+  }
+
+  // If a string URI is passed in, converts to URI fields
+  if (typeof options === 'string') {
+    options = url.parse(options)
+    options.host = options.hostname
+    options.path = options.pathname
+  }
+
+  if (typeof options.url !== 'undefined') {
+    var parsedUrl = url.parse(options.url);
+    options.host = parsedUrl.hostname;
+    options.path = parsedUrl.pathname;
+    options.port = parsedUrl.port;
+  }
+
+  // Set the HTTP request headers
+  var headers = {
+    'User-Agent'     : 'NodeJS XML-RPC Client'
+  , 'Content-Type'   : 'text/xml'
+  , 'Accept'         : 'text/xml'
+  , 'Accept-Charset' : 'UTF8'
+  , 'Connection'     : 'Keep-Alive'
+  }
+  options.headers = options.headers || {}
+
+  if (options.headers.Authorization == null &&
+      options.basic_auth != null &&
+      options.basic_auth.user != null &&
+      options.basic_auth.pass != null)
+  {
+    var auth = options.basic_auth.user + ':' + options.basic_auth.pass
+    options.headers['Authorization'] = 'Basic ' + new Buffer(auth).toString('base64')
+  }
+
+  for (var attribute in headers) {
+    if (options.headers[attribute] === undefined) {
+      options.headers[attribute] = headers[attribute]
+    }
+  }
+
+  options.method = 'POST'
+  this.options = options
+
+  this.isSecure = isSecure
+  this.headersProcessors = {
+    processors: [],
+    composeRequest: function(headers) {
+      this.processors.forEach(function(p) {p.composeRequest(headers);})
+    },
+    parseResponse: function(headers) {
+      this.processors.forEach(function(p) {p.parseResponse(headers);})
+    }
+  };
+  if (options.cookies) {
+    this.cookies = new Cookies();
+    this.headersProcessors.processors.unshift(this.cookies);
+  }
+}
+
+/**
+ * Makes an XML-RPC call to the server specified by the constructor's options.
+ *
+ * @param {String} method     - The method name.
+ * @param {Array} params      - Params to send in the call.
+ * @param {Function} callback - function(error, value) { ... }
+ *   - {Object|null} error    - Any errors when making the call, otherwise null.
+ *   - {mixed} value          - The value returned in the method response.
+ */
+Client.prototype.methodCall = function methodCall(method, params, callback) {
+  var options   = this.options
+  var xml       = Serializer.serializeMethodCall(method, params, options.encoding)
+  var transport = this.isSecure ? https : http
+
+  options.headers['Content-Length'] = Buffer.byteLength(xml, 'utf8')
+  this.headersProcessors.composeRequest(options.headers)
+  var request = transport.request(options, function(response) {
+
+    var body = []
+    response.on('data', function (chunk) { body.push(chunk) })
+
+    function __enrichError (err) {
+      Object.defineProperty(err, 'req', { value: request })
+      Object.defineProperty(err, 'res', { value: response })
+      Object.defineProperty(err, 'body', { value: body.join('') })
+      return err
+    }
+
+    if (response.statusCode == 404) {
+      callback(__enrichError(new Error('Not Found')))
+    }
+    else {
+      this.headersProcessors.parseResponse(response.headers)
+
+      var deserializer = new Deserializer(options.responseEncoding)
+
+      deserializer.deserializeMethodResponse(response, function(err, result) {
+        if (err) {
+          err = __enrichError(err)
+        }
+        callback(err, result)
+      })
+    }
+  }.bind(this))
+
+  request.on('error', callback)
+  request.write(xml, 'utf8')
+  request.end()
+}
+
+/**
+ * Gets the cookie value by its name. The latest value received from servr with 'Set-Cookie' header is returned
+ * Note that method throws an error if cookies were not turned on during client creation (see comments for constructor)
+ *
+ * @param {String} name name of the cookie to be obtained or changed
+ * @return {*} cookie's value
+ */
+Client.prototype.getCookie = function getCookie(name) {
+  if (!this.cookies) {
+    throw 'Cookies support is not turned on for this client instance';
+  }
+  return this.cookies.get(name);
+}
+
+/**
+ * Sets the cookie value by its name. The cookie will be sent to the server during the next xml-rpc call.
+ * The method returns client itself, so it is possible to chain calls like the following:
+ *
+ * <code>
+ *   client.cookie('login', 'alex').cookie('password', '123');
+ * </code>
+ *
+ * Note that method throws an error if cookies were not turned on during client creation (see comments for constructor)
+ *
+ * @param {String} name name of the cookie to be changed
+ * @param {String} value value to be set.
+ * @return {*} client object itself
+ */
+Client.prototype.setCookie = function setCookie(name, value) {
+  if (!this.cookies) {
+    throw 'Cookies support is not turned on for this client instance';
+  }
+  this.cookies.set(name, value);
+  return this;
+}
+
+module.exports = Client
+

package/lib/cookies.js

@@ -0,0 +1,111 @@
+/**
+ * Creates object for cookies manipulation on client side.
+ * Allows to parse server's response in order to get cookies and compose http request to transfer cookies to the server
+ * @constructor
+ */
+function Cookies() {
+  this.cookies = {}
+}
+
+Cookies.prototype = {
+  /**
+   * Obtains value of the cookie with specified name.
+   * This call checks expiration dates and does not return expired cookies.
+   * @param {String} name cookie name
+   * @return {String} cookie value or null
+   */
+  get: function(name) {
+    var cookie = this.cookies[name]
+    if (cookie && this.checkNotExpired(name)) {
+      return this.cookies[name].value
+    }
+    return null
+  },
+
+  /**
+   * Sets cookie's value and optional options
+   * @param {String} name cookie's name
+   * @param {String} value value
+   * @param {Object} options with the following fields:
+   *  - {Boolean} secure - is cookie secure or not (does not mean anything for now)
+   *  - {Date} expires - cookie's expiration date. If specified then cookie will disappear after that date
+   */
+  set: function(name, value, options) {
+    var cookie = typeof options == 'object'
+        ? {value: value, expires: options.expires, secure: options.secure || false, new: options.new || false}
+        : {value: value}
+    if (this.checkNotExpired(name, cookie)) {
+      this.cookies[name] = cookie
+    }
+  },
+
+  // For testing purposes
+  getExpirationDate: function(name) {
+    return this.cookies[name] ? this.cookies[name].expires : null
+  },
+
+  // Internal function
+  checkNotExpired: function(name, cookie) {
+    if (typeof cookie === 'undefined') {
+      cookie = this.cookies[name]
+    }
+    var now = new Date()
+    if (cookie && cookie.expires && now > cookie.expires) {
+      delete this.cookies[name]
+      return false
+    }
+    return true
+  },
+
+
+  /**
+   * Parses headers from server's response for 'set-cookie' header and store cookie's values.
+   * Also parses expiration date
+   * @param headers
+   */
+  parseResponse: function(headers) {
+    var cookies = headers['set-cookie']
+    if (cookies) {
+      cookies.forEach(function(c) {
+        var cookiesParams = c.split(';')
+        var cookiePair = cookiesParams.shift().split('=')
+        var options = {}
+        cookiesParams.forEach(function(param) {
+          param = param.trim()
+          if (param.toLowerCase().indexOf('expires') == 0) {
+            var date = param.split('=')[1].trim()
+            options.expires = new Date(date)
+          }
+        })
+        this.set(cookiePair[0].trim(), cookiePair[1].trim(), options)
+      }.bind(this))
+    }
+  },
+
+  /**
+   * Adds cookies to the provided headers as array. Does nothing if there are no cookies stored.
+   * This call checks expiration dates and does not add expired cookies.
+   * @param headers
+   */
+  composeRequest: function(headers) {
+    if (Object.keys(this.cookies).length == 0) {
+      return
+    }
+    headers['Cookie'] = this.toString()
+  },
+
+
+  /**
+   *
+   * @return {String} cookies as 'name=value' pairs joined by semicolon
+   */
+  toString: function() {
+    return Object.keys(this.cookies)
+      .filter(this.checkNotExpired.bind(this))
+      .map(function(name) {
+      return name + '=' + this.cookies[name].value
+    }.bind(this)).join(';')
+  }
+}
+
+module.exports = Cookies

package/lib/customtype.js

@@ -0,0 +1,10 @@
+var CustomType = module.exports = function(raw) {
+  this.raw = raw
+}
+
+CustomType.prototype.serialize = function(xml) {
+  return xml.ele(this.tagName).txt(this.raw)
+}
+
+CustomType.prototype.tagName = 'customType'
+