soap 0.27.1 → 0.31.0

package/History.md

@@ -1,3 +1,51 @@
+0.31.0 / 2020-02-21
+===================
+
+* [DOC] Update Readme.md (#1105)
+* [ENHANCEMENT] Client.*method*Async can have options as the second argument (#1104)
+* [FIX] Add WSDL xmlns header attribute (#1093)
+* [FIX] Catch errors when parsing WSDL (#1102)
+* [FIX] Fix min/maxOccurs parsing and handling (#1100)
+* [FIX] Fixes bug when envelopeKey is changed and WSSecurityCert is set (#1106)
+* [FIX] fix for circular descriptions (#1101)
+
+
+0.30.0 / 2019-10-16
+===================
+
+* [ENHANCEMENT] Allow a fixed file path for local includes (#1089)
+* [ENHANCEMENT] New XML Signing Options, extra tags to sign and small bug fix (#1091)
+* [ENHANCEMENT] added forceMTOM option and updated the Readme (#1086)
+* [FIX] Added undefined check in WSDL.processAttributes (#1090)
+* [FIX] Fixes bug where methodName would not be included in the response event (#1087)
+* [FIX] fixed MTOM removing soap12header (#1084)
+
+0.29.0 / 2019-07-26
+===================
+
+* [ENHANCEMENT] Added Options object for signer.computeSignature (#1066)
+* [FIX] Prototype pollution in lodash versions <=4.17.11. Hence, updating lodash version to ^4.17.15 in package.json and package-lock.json (#1085)
+* [FIX] Fix known vulnerabilities found by  `npm audit` (#1083)
+* [FIX] Adjusts URL detection to be case insensitive (#1082)
+* [FIX] Fixed issue causing error message, "TypeError: Cannot read property &apos;output&apos; of undefined" (#1081)
+
+0.28.0 / 2019-06-20
+===================
+
+* [ENHANCEMENT] Added support for parsing of doubles and floats. (#1065)
+* [ENHANCEMENT] Adds promise server authentication (#1069)
+* [ENHANCEMENT] Expose the WSDL class (#1071)
+* [ENHANCEMENT] Now supporting XSI namespace overrides (#1079)
+* [ENHANCEMENT] added possibility to add action to content-type header (#1073)
+* [ENHANCEMENT] client.addSoapHeader() dynamic SOAP header (#1062)
+* [ENHANCEMENT] emit response events allowing user override on response XML (#1070)
+* [FIX] Fix description for recursive wsdl with extended element (#1078)
+* [FIX] Fixes issue with unknown ReadableStream type (#1076)
+* [FIX] Update types to make `options` optional for createClientAsync (#1068)
+* [FIX] fix for soap 1.2 content-type header, missing action key (#1075)
+* [FIX] types: move forceSoap12Headers to IWsdlBaseOptions (#1063)
+* [MAINTENANCE] Updated read me to reflect changes in soap.listen (#1060)
+
 0.27.1 / 2019-04-19
 ===================
 

package/Readme.md

@@ -16,7 +16,7 @@ This module lets you connect to web services using SOAP.  It also provides a ser
 - [Module](#module)
   - [soap.createClient(url[, options], callback) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.](#soapcreateclienturl-options-callback---create-a-new-soap-client-from-a-wsdl-url-also-supports-a-local-filesystem-path)
   - [soap.createClientAsync(url[, options]) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.](#soapcreateclientasyncurl-options---create-a-new-soap-client-from-a-wsdl-url-also-supports-a-local-filesystem-path)
-  - [soap.listen(*server*, *path*, *services*, *wsdl*) - create a new SOAP server that listens on *path* and provides *services*.](#soaplistenserver-path-services-wsdl---create-a-new-soap-server-that-listens-on-path-and-provides-services)
+  - [soap.listen(*server*, *path*, *services*, *wsdl*, *callback*) - create a new SOAP server that listens on *path* and provides *services*.](#soaplistenserver-path-services-wsdl-callback---create-a-new-soap-server-that-listens-on-path-and-provides-services)
   - [Options](#options)
   - [Server Logging](#server-logging)
   - [Server Events](#server-events)
@@ -145,9 +145,10 @@ The `options` argument allows you to customize the client with the following pro
 
 Note: for versions of node >0.10.X, you may need to specify `{connection: 'keep-alive'}` in SOAP headers to avoid truncation of longer chunked responses.
 
-### soap.listen(*server*, *path*, *services*, *wsdl*) - create a new SOAP server that listens on *path* and provides *services*.
+### soap.listen(*server*, *path*, *services*, *wsdl*, *callback*) - create a new SOAP server that listens on *path* and provides *services*.
 *server* can be a [http](https://nodejs.org/api/http.html) Server or [express](http://expressjs.com/) framework based server
 *wsdl* is an xml string that defines the service.
+*callback* a function to run after the server has been initialized.
 
 ``` javascript
   var myService = {
@@ -203,7 +204,9 @@ Note: for versions of node >0.10.X, you may need to specify `{connection: 'keep-
   });
 
   server.listen(8000);
-  soap.listen(server, '/wsdl', myService, xml);
+  soap.listen(server, '/wsdl', myService, xml, function(){
+    console.log('server initialized');
+  });
 
   //express server example
   var app = express();
@@ -212,7 +215,9 @@ Note: for versions of node >0.10.X, you may need to specify `{connection: 'keep-
   app.listen(8001, function(){
       //Note: /wsdl route will be handled by soap module
       //and all other routes & middleware will continue to work
-      soap.listen(app, '/wsdl', myService, xml);
+      soap.listen(app, '/wsdl', myService, xml, function(){
+        console.log('server initialized');
+      });
   });
 
 ```
@@ -265,6 +270,8 @@ Server instances emit the following events:
 
 * request - Emitted for every received messages.
   The signature of the callback is `function(request, methodName)`.
+* response - Emitted before sending SOAP response.
+  The signature of the callback is `function(response, methodName)`.
 * headers - Emitted when the SOAP Headers are not empty.
   The signature of the callback is `function(headers, methodName)`.
 
@@ -493,8 +500,21 @@ The `options` object is optional and is passed to the `request`-module.
 Interesting properties might be:
 * `timeout`: Timeout in milliseconds
 * `forever`: Enables keep-alive connections and pools them
-
-### Client.*method*Async(args) - call *method* on the SOAP service.
+* `attachments`: array of attachment objects. This converts the request into MTOM: _headers['Content-Type']='multipart/related; type="application/xop+xml"; start= ... '_
+  ```
+  [{
+        mimetype: content mimetype,
+        contentId: part id,
+        name: file name,
+        body: binary data
+   },
+    ...
+  ]
+  ```
+* `forceMTOM`: set to True if you want to send the request as MTOM even if you don't have attachments
+    
+
+### Client.*method*Async(args, options) - call *method* on the SOAP service.
 
 ``` javascript
   client.MyFunctionAsync({name: 'value'}).then((result) => {
@@ -508,6 +528,23 @@ Interesting properties might be:
 
 The `args` argument allows you to supply arguments that generate an XML document inside of the SOAP Body section.
 
+The `options` object is optional and is passed to the `request`-module.
+Interesting properties might be:
+* `timeout`: Timeout in milliseconds
+* `forever`: Enables keep-alive connections and pools them
+* `attachments`: array of attachment objects. This converts the request into MTOM: _headers['Content-Type']='multipart/related; type="application/xop+xml"; start= ... '_
+  ```
+  [{
+        mimetype: content mimetype,
+        contentId: part id,
+        name: file name,
+        body: binary data
+   },
+    ...
+  ]
+  ```
+* `forceMTOM`: set to True if you want to send the request as MTOM even if you don't have attachments
+
 ##### Example with JSON for the `args`
 The example above uses `{name: 'value'}` as the args. This may generate a SOAP messages such as:
 
@@ -663,6 +700,87 @@ Example :
   }, {exchangeId: myExchangeId})
 ```
 
+## WSDL
+
+A WSDL instance can also be instantiated directly when you want to (un)marshal
+messages without doing SOAP calls. This can be used when a WSDL does not contain
+bindings for services (e.g. some Windows Communication Foundation SOAP web
+services).
+
+## WSDL.constructor(wsdl, baseURL, options):
+
+Construct a WSDL instance from either the WSDL content or the URL to the WSDL.
+#### Parameters
+
+  - wsdl: A string wSDL or an URL to the WSDL
+  - baseURL: base URL for the SOAP API
+  - options: options (see source for details), use `{}` as default.
+
+### wsdl.xmlToObject(xml):
+
+Unmarshal XML to object.
+
+#### Parameters:
+  - xml: SOAP response (XML) to unmarshal
+
+#### Returns:
+
+Object containing the object types from the xml as keys.
+
+### wsdl.objectToXML(object, typeName, namespacePrefix, namespaceURI, ...):
+
+Marshal an object to XML
+
+#### Parameters:
+  - object: Object to marshal
+  - typeName: type (as per the wsdl) of the object
+  - namespacePrefix: namespace prefix
+  - namespaceURI: URI of the namespace
+
+#### Returns:
+
+XML representation of object.
+
+#### Example:
+```typescript
+// Abstracted from a real use case
+import { AxiosInstance } from 'axios';
+import { WSDL } from 'soap';
+import { IProspectType } from './types';
+
+// A WSDL in a string.
+const WSDL_CONTENT = "...";
+
+const httpClient: AxiosInstance = /* ... instantiate ... */;
+const url = 'http://example.org/SoapService.svc';
+
+const wsdl = new WSDL(WSDL_CONTENT, baseURL, {});
+
+async function sampleGetCall(): IProspectType | undefined {
+    const res = await httpClient.get(`${baseURL}/GetProspect`);
+
+    const object = wsdl.xmlToObject(res.data);
+
+    if (!object.ProspectType) {
+      // Response did not contain the expected type
+      return undefined;
+    }
+    // Optionally, unwrap and set defaults for some fields
+    // Ensure that the object meets the expected prototype
+    // Finally cast and return the result.
+    return object.ProspectType as IProspectType;
+}
+
+async function samplePostCall(prospect: IProspectType) {
+  // objectToXML(object, typeName, namespacePrefix, namespaceURI, ...)
+  const objectBody = wsdl.objectToXML(obj, 'ProspectType', '', '');
+  const data = `<?xml version="1.0" ?>${body}`;
+
+  const res = await httpClient.post(`${baseURL}/ProcessProspect`, data);
+  // Optionally, deserialize request and return response status.
+}
+```
+
 
 ## Security
 
@@ -763,10 +881,163 @@ WS-Security X509 Certificate support.
   var privateKey = fs.readFileSync(privateKeyPath);
   var publicKey = fs.readFileSync(publicKeyPath);
   var password = ''; // optional password
-  var wsSecurity = new soap.WSSecurityCert(privateKey, publicKey, password);
+  var options = {
+    hasTimeStamp: true,
+    additionalReferences: [
+        'wsa:Action',
+        'wsa:ReplyTo',
+        'wsa:To',
+    ],
+    signerOptions: {
+        prefix: 'ds',
+        attrs: { Id: 'Signature' },
+        existingPrefixes: {
+            wsse: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd',
+        }
+  }
+  var wsSecurity = new soap.WSSecurityCert(privateKey, publicKey, password, options);
   client.setSecurity(wsSecurity);
 ```
 
+The `options` object is optional and can contain the following properties:
+* `hasTimeStamp`: Includes Timestamp tags (default: `true`)
+* `signatureTransformations`: sets the Reference Transforms Algorithm (default ['http://www.w3.org/2000/09/xmldsig#enveloped-signature', 'http://www.w3.org/2001/10/xml-exc-c14n#']). Type is a string array
+* `signatureAlgorithm`: set to `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` to use sha256
+* `additionalReferences` : (optional) Array of Soap headers that need to be signed.  This need to be added using `client.addSoapHeader('header')`
+* `signerOptions`: (optional) passes options to the XML Signer package - from (https://github.com/yaronn/xml-crypto) 
+  * `existingPrefixes`: (optional) A hash of prefixes and namespaces prefix: namespace that shouldn't be in the signature because they already exist in the xml (default: `{ 'wsse': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' }`)
+  * `prefix`: (optional) Adds this value as a prefix for the generated signature tags.
+  * `attrs`: (optional) A hash of attributes and values attrName: value to add to the signature root node 
+  
+#### Option examples
+
+`hasTimeStamp:true` 
+  
+``` xml
+<soap:Header>
+    <wsse:Security soap:mustUnderstand="1">
+        <wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
+        <!-- The Timestamp group of tags are added and signed --> 
+        <Timestamp xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" Id="Timestamp">
+            <Created>2019-10-01T08:17:50Z</Created>
+            <Expires>2019-10-01T08:27:50Z</Expires>
+        </Timestamp>
+        <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
+            <SignedInfo>
+                ...
+                <Reference URI="#Timestamp">
+                    <Transforms>
+                        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+                        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+                    </Transforms>
+                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
+                    <DigestValue>XyZ=</DigestValue>
+                </Reference>
+            </SignedInfo>
+        </Signature>
+    </wsse:Security>
+</soap:Header>
+```
+
+`additionalReferences: ['To']`
+``` XML
+<soap:Header>
+    <To Id="To">localhost.com</To>
+    <wsse:Security soap:mustUnderstand="1">
+        <wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
+        <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
+            <SignedInfo>
+                <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+                <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
+                <!-- The "To" tag is signed and added as a reference --> 
+                <Reference URI="#To">
+                    <Transforms>
+                        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+                        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+                    </Transforms>
+                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
+                    <DigestValue>XYZ</DigestValue>
+                </Reference>
+            </SignedInfo>
+            <SignatureValue>
+                Rf6M4F4puQuQHJIPtJz1CZIVvF3qOdpEEcuAiooWkX5ecnAHSf3RW3sOIzFUWW7VOOncJcts/3xr8DuN4+8Wm9hx1MoOcWJ6kyRIdVNbQWLseIcAhxYCntRY57T2TBXzpb0UPA56pry1+TEcnIQXhdIzG5YT+tTVTp+SZHHcnlP5Y+yqnIOH9wzgRvAovbydTYPCODF7Ana9K/7CSGDe7vpVT85CUYUcJE4DfTxaRa9gKkKrBdPN9vFVi0WfxtMF4kv23cZRCZzS5+CoLfPlx3mq65gVXsqH01RLbktNJq9VaQKcZUgapmUCMzrYhqyzUQJ8HrSHqe+ya2GsjlB0VQ==
+            </SignatureValue>
+            <KeyInfo>
+                <wsse:SecurityTokenReference
+                        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
+                    <wsse:Reference URI="#x509-c5c0d213676f4a6ba5e6fa58074eb57a"
+                                    ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
+                </wsse:SecurityTokenReference>
+            </KeyInfo>
+        </Signature>
+    </wsse:Security>
+</soap:Header>
+```
+
+`signerOptions.prefix:'ds'` 
+
+``` XML
+<soap:Header>
+    <To Id="To">localhost.com</To>
+    <wsse:Security soap:mustUnderstand="1">
+        <wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
+        <!-- Signature and children tags are given the prefix defined. -->
+        <ds:Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
+            <ds:SignedInfo>
+                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+                <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
+                <ds:Reference URI="#To">
+                    <ds:Transforms>
+                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+                    </ds:Transforms>
+                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
+                    <ds:DigestValue>XYZ</DigestValue>
+                </ds:Reference>
+            </ds:SignedInfo>
+            <ds:SignatureValue>
+                Rf6M4F4puQuQHJIPtJz1CZIVvF3qOdpEEcuAiooWkX5ecnAHSf3RW3sOIzFUWW7VOOncJcts/3xr8DuN4+8Wm9hx1MoOcWJ6kyRIdVNbQWLseIcAhxYCntRY57T2TBXzpb0UPA56pry1+TEcnIQXhdIzG5YT+tTVTp+SZHHcnlP5Y+yqnIOH9wzgRvAovbydTYPCODF7Ana9K/7CSGDe7vpVT85CUYUcJE4DfTxaRa9gKkKrBdPN9vFVi0WfxtMF4kv23cZRCZzS5+CoLfPlx3mq65gVXsqH01RLbktNJq9VaQKcZUgapmUCMzrYhqyzUQJ8HrSHqe+ya2GsjlB0VQ==
+            </ds:SignatureValue>
+            <ds:KeyInfo>
+                <wsse:SecurityTokenReference
+                        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
+                    <wsse:Reference URI="#x509-c5c0d213676f4a6ba5e6fa58074eb57a"
+                                    ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
+                </wsse:SecurityTokenReference>
+            </ds:KeyInfo>
+        </ds:Signature>
+    </wsse:Security>
+</soap:Header>
+```
+
+`signerOptions.attrs:{ Id: 'signature-100', foo:'bar'}` 
+  
+``` xml
+<soap:Header>
+    <wsse:Security soap:mustUnderstand="1">
+        <wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
+        <!-- The Timestamp group of tags are added and signed --> 
+        <Timestamp xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" Id="Timestamp">
+            <Created>2019-10-01T08:17:50Z</Created>
+            <Expires>2019-10-01T08:27:50Z</Expires>
+        </Timestamp>
+        <Signature Id="signature-100" foo="bar" xmlns="http://www.w3.org/2000/09/xmldsig#">
+            <SignedInfo>
+                ...
+                <Reference URI="#Timestamp">
+                    <Transforms>
+                        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+                        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+                    </Transforms>
+                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
+                    <DigestValue>XyZ=</DigestValue>
+                </Reference>
+            </SignedInfo>
+        </Signature>
+    </wsse:Security>
+</soap:Header>
+```
+
 ### NTLMSecurity
 
 Parameter invocation:
@@ -903,6 +1174,23 @@ soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, funct
   });
 });
 ```
+
+### Overriding imports relative paths
+
+By default, WSDL and schema files import other schemas and types using relative paths.
+
+However in some systems (i.e. NetSuite) when the wsdl is downloaded for offline caching, all files are flattened under a single directory and all the imports fail.
+Passing this option allows `node-soap` to correctly load all files.  
+
+```javascript
+var options ={
+    wsdl_options = { fixedPath: true }
+};
+soap.createClient(__dirname+'/wsdl/fixedPath/netsuite.wsdl', options, function(err, client) {
+    // your code  
+});
+```
+
 ### Specifying the exact namespace definition of the root element
 In rare cases, you may want to precisely control the namespace definition that is included in the root element.
 

package/lib/client.d.ts

@@ -44,8 +44,8 @@ export declare class Client extends EventEmitter {
     private normalizeNames;
     constructor(wsdl: WSDL, endpoint?: string, options?: IOptions);
     /** add soapHeader to soap:Header node */
-    addSoapHeader(soapHeader: any, name?: string, namespace?: string, xmlns?: string): number;
-    changeSoapHeader(index: number, soapHeader: any, name?: string, namespace?: string, xmlns?: string): void;
+    addSoapHeader(soapHeader: any, name?: string, namespace?: any, xmlns?: string): number;
+    changeSoapHeader(index: any, soapHeader: any, name?: any, namespace?: any, xmlns?: any): void;
     /** return all defined headers */
     getSoapHeaders(): string[];
     /** remove all defined headers */
@@ -68,5 +68,6 @@ export declare class Client extends EventEmitter {
     private _defineService;
     private _definePort;
     private _defineMethod;
+    private _processSoapHeader;
     private _invoke;
 }