docs: document that the Response status is set by the handlers

docs/api/response.md

@@ -8,23 +8,25 @@ response signature.
 **Kind**: global class  
 
 * [Response](#Response)
-    * [new Response(headers, method, [body], ...otherOptions)](#new_Response_new)
+    * [new Response(headers, [body], ...otherOptions)](#new_Response_new)
     * [.get(field)](#Response+get) ⇒ <code>string</code> \| <code>undefined</code>
     * [.redirect(url)](#Response+redirect)
     * [.set(field, value)](#Response+set)
 
 <a name="new_Response_new"></a>
 
-### new Response(headers, method, [body], ...otherOptions)
+### new Response(headers, [body], ...otherOptions)
 Create a new Response instance.
 
+The `status` always starts as `200` and is set by the handlers (for example
+`302` for a redirect, or the error's code), so it cannot be passed in.
+
 
 | Param | Type | Description |
 | --- | --- | --- |
 | headers | <code>object</code> | key-value object of headers |
-| method | <code>string</code> | the HTTP method |
 | [body] | <code>object</code> | optional key-value object of body parameters |
-| ...otherOptions | <code>object</code> | any other properties that should be assigned to the request by your webserver |
+| ...otherOptions | <code>object</code> | any other properties that should be assigned to the response by your webserver; properties the response already has (such as `status` or its methods) are not overwritten |
 
 **Example**  
 ```js

lib/response.js

@@ -14,11 +14,13 @@
 class Response {
   /**
    * Create a new Response instance.
+   *
+   * The `status` always starts as `200` and is set by the handlers (for example
+   * `302` for a redirect, or the error's code), so it cannot be passed in.
    * @constructor
    * @param headers {object} key-value object of headers
-   * @param method {string} the HTTP method
    * @param body {object=} optional key-value object of body parameters
-   * @param otherOptions {...object} any other properties that should be assigned to the request by your webserver
+   * @param otherOptions {...object} any other properties that should be assigned to the response by your webserver; properties the response already has (such as `status` or its methods) are not overwritten
    */
   constructor({ headers = {}, body = {}, ...otherOptions } = {}) {
     this.status = 200;

test/compliance/client-credential-workflow_test.js

@@ -106,6 +106,38 @@ describe('ClientCredentials Workflow Compliance (4.4)', function () {
       db.refreshTokens.has(token.refreshToken).should.equal(false);
     });
 
+    /**
+     * 5.1.  Successful Response
+     *
+     *    The authorization server issues an access token and optional
+     *    refresh token, and constructs the response by adding the following
+     *    parameters to the entity-body of the HTTP response with a 200 (OK)
+     *    status code
+     */
+    it('returns status 200 for a successful token response even if the initial status is 404', async function () {
+      const response = new Response({ status: 404 });
+      const request = createRequest({
+        body: {
+          grant_type: 'client_credentials',
+          scope: enabledScope,
+        },
+        headers: {
+          authorization: 'Basic ' + Buffer.from(clientDoc.id + ':' + clientDoc.secret).toString('base64'),
+          'content-type': 'application/x-www-form-urlencoded',
+        },
+        method: 'POST',
+      });
+
+      const token = await oAuth2Server.token(request, response);
+
+      response.body.access_token.should.equal(token.accessToken);
+      response.body.token_type.should.equal('Bearer');
+      db.accessTokens.has(token.accessToken).should.equal(true);
+
+      // RFC 6749 section 5.1 specifies status 200 for a successful token response.
+      response.status.should.equal(200);
+    });
+
     /**
      * 7.  Accessing Protected Resources
      *

test/integration/response_test.js

@@ -32,6 +32,12 @@ describe('Response integration', function () {
 
       response.status.should.equal(200);
     });
+
+    it('should not set the `status` from the options', function () {
+      const response = new Response({ body: {}, headers: {}, status: 404 });
+
+      response.status.should.equal(200);
+    });
   });
 
   describe('get()', function () {