@mbtest/mountebank 2.9.2-beta.9050

package/src/views/docs/protocols/https.ejs

@@ -0,0 +1,246 @@
+<%
+title = 'https'
+description = 'The HTTPS protocol support provided by mountebank'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>https</h1>
+
+<p>The https is very similar to the http protocol, except for the fact that it uses
+a certificate key pair.  If you use the built-in self-signed certificate, you may have to
+configure your code to disable certificate validation (e.g. use the <code>-k</code>
+switch in <code>curl</code>).  Alternatively, you may pass in the key pair yourself.</p>
+
+<h2>Imposter Creation Parameters</h2>
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Options</th>
+    <th>Required?</th>
+    <th>Default</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>protocol</code></td>
+    <td><code>https</code></td>
+    <td>Yes</td>
+    <td>N/A</td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><code>port</code></td>
+    <td>Any valid port number</td>
+    <td>No</td>
+    <td>A randomly assigned port.  mountebank will return the actual value
+    in the <code>POST</code> response.</td>
+    <td>The port to run the imposter on.</td>
+  </tr>
+  <tr>
+    <td><code>key</code></td>
+    <td>A PEM-formatted string</td>
+    <td>No</td>
+    <td>A built in private key</td>
+    <td>The SSL server private key</td>
+  </tr>
+  <tr>
+    <td><code>cert</code></td>
+    <td>A PEM-formatted string</td>
+    <td>No</td>
+    <td>A built in self-signed certificate</td>
+    <td>The SSL server certificate</td>
+  </tr>
+  <tr>
+    <td><code>mutualAuth</code></td>
+    <td><code>true</code> or <code>false</code></td>
+    <td>No</td>
+    <td><code>false</code></td>
+    <td>If <code>true</code>, the server will request a client certificate.
+    Since the goal is simply to virtualize a server requiring mutual auth,
+    invalid certificates will not be rejected.</td>
+  </tr>
+  <tr>
+    <td><code>ciphers</code></td>
+    <td><a href='https://nodejs.org/dist/latest-v14.x/docs/api/tls.html#tls_modifying_the_default_tls_cipher_suite'>See here</a></td>
+    <td>No</td>
+    <td><a href='https://nodejs.org/dist/latest-v14.x/docs/api/tls.html#tls_tls_getciphers'>Here</a></td>
+    <td>For older (and insecure) https servers, this field allows you to override the cipher used to communicate</td>
+  </tr>
+  <tr>
+    <td><code>name</code></td>
+    <td>Any string</td>
+    <td>No</td>
+    <td>empty string</td>
+    <td>Included in the logs, useful when multiple imposters are set up.</td>
+  </tr>
+  <tr>
+    <td><code>recordRequests</code></td>
+    <td><code>true</code> or <code>false</code></td>
+    <td>No</td>
+    <td>false</td>
+    <td>Adds <a href='/docs/api/mocks'>mock verification</a> support by remembering the requests
+        made to this imposter.  Note that this represents a memory leak for any long running
+        <code>mb</code> process, as requests are never forgotten.</td>
+  </tr>
+  <tr>
+    <td><code>stubs</code></td>
+    <td>Valid stubs</td>
+    <td>No</td>
+    <td>An empty array</td>
+    <td>The list of stubs responsible for matching a request and returning a response</td>
+  </tr>
+  <tr>
+    <td><code>defaultResponse</code></td>
+    <td>A valid response, see the <a href='/docs/protocols/http'>http</a> page for response fields</td>
+    <td>No</td>
+    <td><pre><code>
+{
+  "statusCode": 200,
+  "headers": {
+    "connection": "close"
+   },
+  "body": ""
+}
+    </code></pre></td>
+    <td>The default response to send if no predicate matches. Also represents the default values
+        that get merged into a response that doesn't specify every field</td>
+  </tr>
+  <tr>
+    <td><code>allowCORS</code></td>
+    <td>boolean</td>
+    <td>No</td>
+    <td>false</td>
+    <td>If true, mountebank will allow all CORS preflight requests on the imposter.</td>
+  </tr>
+  <tr>
+    <td><code>rejectUnauthorized</code></td>
+    <td>boolean</td>
+    <td>No</td>
+    <td>false</td>
+    <td>If true, mountebank will validate the certificate against the list of supplied CAs.</td>
+  </tr>
+  <tr>
+    <td><code>ca</code></td>
+    <td>Array of PEM-formatted certificates</td>
+    <td>No</td>
+    <td>null</td>
+    <td>Use when setting <code>rejectUnauthorized</code> to true to provide a list of certificates to validate against.
+        When <code>rejectUnauthorized</code> is true and <code>mutualAuth</code> is true, mountebank will request a client certificate.</td>
+  </tr>
+</table>
+
+<p>See the <a href='/docs/protocols/http'>http</a> page for examples.  Just be sure
+  to change the <code>protocol</code> parameter to <code>https</code> during imposter
+  creation!</p>
+
+<h2>Handling trust</h2>
+
+<p>By default, mountebank will use an internal self-signed certificate.  While this allows you
+to explore the API in a simple zero-config manner, it also means that you need to configure
+your system under test to ignore trust errors. This is A Very Bad Idea. It puts you at risk
+of accidentally leaving that configuration in production, exposing your network to unnecessary risk.</p>
+
+<p>There are at least three solutions that are safe for testing and remove the possibility
+of your test strategy causing trust violations in production:</p>
+
+<ul class='bullet-list'>
+    <li>Test against an http imposter, and trust that the SSL/TLS libraries your system under
+    test is using just work.</li>
+    <li>Create your own self-signed certificate for testing <i>and add it to your local trust store only.</i>
+    Have a look at <a href='https://github.com/FiloSottile/mkcert'>mkcert</a> for a simple way
+    of doing this.</li>
+    <li>Use a real trusted certificate for testing. If you can't have your organization create
+    one for you, <a href='https://letsencrypt.org/'>Let's Encrypt</a> offers a free service
+    to create trusted certificates.</li>
+</ul>
+
+<p>The mutual authentication example below shows including them in your imposter setup.</p>
+
+<h2>Mutual Authentication</h2>
+
+<p>mountebank supports mutual authentication involving client certificates both for the
+server itself and through proxies.  The following example demonstrates this capability,
+as well as setting up your own certificate for the server.  First we'll set up a server
+that expects client certificates by using the <code>mutualAuth</code> field:</p>
+
+<testScenario name='https-mutual-auth'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 4545,
+  "protocol": "https",
+  "name": "origin server",
+  <strong class='highlight2'>"mutualAuth": true</strong>,
+  "key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXAIBAAKBgQCrvse04YkxtVGagyvGJCsvv7LTfLK5uR/ZIJKDYCnuF+BqBzM4\nlko8O39vx+Lz9FfF11Xl+CN1aY37YurLYOle3dC/qslSbQDe2TJN7lcVHVssePvc\nO5IExpvNFV5LYtmyCMKJHxpnIprv/trUso5obqzzXhFVPV9SQbFH/snInwIDAQAB\nAoGARywlqLD6YO4qJiULw+4DM6N2oSwBCPRN3XYhIW59kdy1NFtNf7rQgsuJUTJ9\nu+lbYnKNd2LwltyqaS4h7Sx5KRhpFNmMpyVsBf5J2q3fbfmrsXt+emY7XhVTc1NV\nizUWYyxCoTTeMWvN/6NYpPV0lSxq7jMTFVZrWQUMqJclxpECQQDTlGwALtAX1Y8u\nGKsEHPkoq9bhHA5N9WAboQ4LQCZVC8eBf/XH//2iosYTXRNgII2JLmHmmxJHo5iN\nJPFMbnoHAkEAz81osJf+yHm7PBBJP4zEWZCV25c+iJiPDpj5UoUXEbq47qVfy1mV\nDqy2zoDynAWitU7PeHyZ8ozfyribPoR2qQJAVmvMhXKZmvKnLivzRpXTC9LMzVwZ\nV6x/Wim5w8yrG5fZIMM0kEG2xwR3pZch/+SsCzl/0aLLn6lp+VT6nr6NZwJBAMxs\nHrvymoLvNeDtiJFK0nHliXafP7YyljDfDg4+vSYE0R57c1RhSQBJqgBV29TeumSw\nJes6cFuqeBE+MAJ9XxkCQDdUdhnA8HHQRNetqK7lygUep7EcHHCB6u/0FypoLw7o\nEUVo5KSEFq93UeMr3B7DDPIz3LOrFXlm7clCh1HFZhQ=\n-----END RSA PRIVATE KEY-----",
+  "cert": "-----BEGIN CERTIFICATE-----\nMIIB6TCCAVICCQCZgxbBD0CG4zANBgkqhkiG9w0BAQUFADA5MQswCQYDVQQGEwJV\nUzETMBEGA1UECBMKU29tZS1TdGF0ZTEVMBMGA1UEChMMVGhvdWdodFdvcmtzMB4X\nDTEzMTIyOTE2NDAzN1oXDTE0MDEyODE2NDAzN1owOTELMAkGA1UEBhMCVVMxEzAR\nBgNVBAgTClNvbWUtU3RhdGUxFTATBgNVBAoTDFRob3VnaHRXb3JrczCBnzANBgkq\nhkiG9w0BAQEFAAOBjQAwgYkCgYEAq77HtOGJMbVRmoMrxiQrL7+y03yyubkf2SCS\ng2Ap7hfgagczOJZKPDt/b8fi8/RXxddV5fgjdWmN+2Lqy2DpXt3Qv6rJUm0A3tky\nTe5XFR1bLHj73DuSBMabzRVeS2LZsgjCiR8aZyKa7/7a1LKOaG6s814RVT1fUkGx\nR/7JyJ8CAwEAATANBgkqhkiG9w0BAQUFAAOBgQCPhixeKxIy+ftrfPikwjYo1uxp\ngQ18FdVN1pbI//IIx1o8kJuX8yZzO95PsCOU0GbIRCkFMhBlqHiD9H0/W/GvWzjf\n7WFW15lL61y/kH1J0wqEgoaMrUDjHZvKVr0HrN+vSxHlNQcSNFJ2KdvZ5a9dhpGf\nXOdprCdUUXzSoJWCCg==\n-----END CERTIFICATE-----",
+  "stubs": [{
+    "responses": [<strong class='highlight1'>{ "is": { "body": "It worked!" } }</strong>]
+  }]
+}
+</code></pre>
+    </step>
+
+<p>If we try and connect to this server without providing a client certificate, it will immediately terminate the connection.
+Let's create an imposter that will proxy to it, providing the necessary credentials:</p>
+
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 5555,
+  "protocol": "http",
+  "name": "proxy",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "proxy": {
+            "to": "https://localhost:4545",
+            <strong class='highlight2'>"key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXAIBAAKBgQCrvse04YkxtVGagyvGJCsvv7LTfLK5uR/ZIJKDYCnuF+BqBzM4\nlko8O39vx+Lz9FfF11Xl+CN1aY37YurLYOle3dC/qslSbQDe2TJN7lcVHVssePvc\nO5IExpvNFV5LYtmyCMKJHxpnIprv/trUso5obqzzXhFVPV9SQbFH/snInwIDAQAB\nAoGARywlqLD6YO4qJiULw+4DM6N2oSwBCPRN3XYhIW59kdy1NFtNf7rQgsuJUTJ9\nu+lbYnKNd2LwltyqaS4h7Sx5KRhpFNmMpyVsBf5J2q3fbfmrsXt+emY7XhVTc1NV\nizUWYyxCoTTeMWvN/6NYpPV0lSxq7jMTFVZrWQUMqJclxpECQQDTlGwALtAX1Y8u\nGKsEHPkoq9bhHA5N9WAboQ4LQCZVC8eBf/XH//2iosYTXRNgII2JLmHmmxJHo5iN\nJPFMbnoHAkEAz81osJf+yHm7PBBJP4zEWZCV25c+iJiPDpj5UoUXEbq47qVfy1mV\nDqy2zoDynAWitU7PeHyZ8ozfyribPoR2qQJAVmvMhXKZmvKnLivzRpXTC9LMzVwZ\nV6x/Wim5w8yrG5fZIMM0kEG2xwR3pZch/+SsCzl/0aLLn6lp+VT6nr6NZwJBAMxs\nHrvymoLvNeDtiJFK0nHliXafP7YyljDfDg4+vSYE0R57c1RhSQBJqgBV29TeumSw\nJes6cFuqeBE+MAJ9XxkCQDdUdhnA8HHQRNetqK7lygUep7EcHHCB6u/0FypoLw7o\nEUVo5KSEFq93UeMr3B7DDPIz3LOrFXlm7clCh1HFZhQ=\n-----END RSA PRIVATE KEY-----",
+            "cert": "-----BEGIN CERTIFICATE-----\nMIIB6TCCAVICCQCZgxbBD0CG4zANBgkqhkiG9w0BAQUFADA5MQswCQYDVQQGEwJV\nUzETMBEGA1UECBMKU29tZS1TdGF0ZTEVMBMGA1UEChMMVGhvdWdodFdvcmtzMB4X\nDTEzMTIyOTE2NDAzN1oXDTE0MDEyODE2NDAzN1owOTELMAkGA1UEBhMCVVMxEzAR\nBgNVBAgTClNvbWUtU3RhdGUxFTATBgNVBAoTDFRob3VnaHRXb3JrczCBnzANBgkq\nhkiG9w0BAQEFAAOBjQAwgYkCgYEAq77HtOGJMbVRmoMrxiQrL7+y03yyubkf2SCS\ng2Ap7hfgagczOJZKPDt/b8fi8/RXxddV5fgjdWmN+2Lqy2DpXt3Qv6rJUm0A3tky\nTe5XFR1bLHj73DuSBMabzRVeS2LZsgjCiR8aZyKa7/7a1LKOaG6s814RVT1fUkGx\nR/7JyJ8CAwEAATANBgkqhkiG9w0BAQUFAAOBgQCPhixeKxIy+ftrfPikwjYo1uxp\ngQ18FdVN1pbI//IIx1o8kJuX8yZzO95PsCOU0GbIRCkFMhBlqHiD9H0/W/GvWzjf\n7WFW15lL61y/kH1J0wqEgoaMrUDjHZvKVr0HrN+vSxHlNQcSNFJ2KdvZ5a9dhpGf\nXOdprCdUUXzSoJWCCg==\n-----END CERTIFICATE-----"</strong>
+          }
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>With the client certificate specified, we should now be able to successfully proxy:</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:5555</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+<strong class='highlight1'>It worked!</strong></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/5555 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+</testScenario>
+
+<%- include('../../_footer') -%>

package/src/views/docs/protocols/smtp.ejs

@@ -0,0 +1,142 @@
+<%
+title = 'smtp'
+description = 'The SMTP protocol support provided by mountebank'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>smtp</h1>
+
+<p>At the moment, the smtp imposters only support <a href='/docs/api/mocks'>mock verification</a>.
+Stubbing support will come as soon as someone describes it as being worth the time to develop.
+mountebank expects stub responses will be acceptance or rejection of the message.</p>
+
+<h2>Imposter Creation Parameters</h2>
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Options</th>
+    <th>Required?</th>
+    <th>Default</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>protocol</code></td>
+    <td><code>smtp</code></td>
+    <td>Yes</td>
+    <td>N/A</td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><code>port</code></td>
+    <td>Any valid port number</td>
+    <td>No</td>
+    <td>A randomly assigned port.  mountebank will return the actual value
+    in the <code>POST</code> response.</td>
+    <td>The port to run the imposter on.</td>
+  </tr>
+  <tr>
+    <td><code>name</code></td>
+    <td>Any string</td>
+    <td>No</td>
+    <td>empty string</td>
+    <td>Included in the logs, useful when multiple imposters are set up.</td>
+  </tr>
+  <tr>
+    <td><code>recordRequests</code></td>
+    <td><code>true</code> or <code>false</code></td>
+    <td>No</td>
+    <td>false</td>
+    <td>Adds <a href='/docs/api/mocks'>mock verification</a> support by remembering the requests
+        made to this imposter.  Note that this represents a memory leak for any long running
+        <code>mb</code> process, as requests are never forgotten.</td>
+  </tr>
+</table>
+
+<h2>SMTP Requests</h2>
+
+<table>
+  <tr>
+      <th>Field</th>
+      <th>Description</th>
+      <th>Type</th>
+  </tr>
+  <tr>
+    <td><code>requestFrom</code></td>
+    <td>The client socket, primarily used for logging and debugging.  mountebank
+    currently is unable to get the client port, but may fix that in the near future.</td>
+    <td>string</td>
+  </tr>
+  <tr>
+      <td><code>envelopeFrom</code></td>
+      <td>The from address sent in the <code>MAIL</code> command, used as the return
+      address for bounces.  Many client SMTP APIs do not expose this field, and keep it the
+      same as the <code>from</code> field.</td>
+      <td>string</td>
+  </tr>
+  <tr>
+      <td><code>envelopeTo</code></td>
+      <td>The address sent using the <code>RCPT</code> command.  Many client SMTP APIs
+      hide this field, deriving it from the <code>to</code>, <code>cc</code>, and
+      <code>bcc</code> fields.</td>
+      <td>string</td>
+  </tr>
+  <tr>
+      <td><code>from</code></td>
+      <td>The sender of the message (sent in the <code>DATA</code> command).</td>
+      <td>string</td>
+  </tr>
+  <tr>
+      <td><code>to</code></td>
+      <td>The recipients of the message (sent in the <code>DATA</code> command).</td>
+      <td>array</td>
+  </tr>
+  <tr>
+      <td><code>cc</code></td>
+      <td>The CC recipients of the message</td>
+      <td>array</td>
+  </tr>
+  <tr>
+    <td><code>bcc</code></td>
+    <td>The BCC recipients of the message</td>
+    <td>array</td>
+  </tr>
+  <tr>
+    <td><code>subject</code></td>
+    <td>The subject of the message</td>
+    <td>array</td>
+  </tr>
+  <tr>
+    <td><code>priority</code></td>
+    <td>The priority of the message</td>
+    <td>string</td>
+  </tr>
+  <tr>
+    <td><code>references</code></td>
+    <td>The references of the message</td>
+    <td>array</td>
+  </tr>
+  <tr>
+    <td><code>inReplyTo</code></td>
+    <td>The in reply to of the message</td>
+    <td>array</td>
+  </tr>
+  <tr>
+    <td><code>text</code></td>
+    <td>The text-only message</td>
+    <td>string</td>
+  </tr>
+  <tr>
+    <td><code>html</code></td>
+    <td>The html message</td>
+    <td>string</td>
+  </tr>
+  <tr>
+    <td><code>attachments</code></td>
+    <td>The message attachments</td>
+    <td>array</td>
+  </tr>
+</table>
+
+<%- include('../../_footer') -%>