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

[dhensby]

Summary

new Response({ status: 404 }) produces a response whose status is 200. This PR originally changed the constructor to honour status, but review showed why it shouldn't. Response isn't a general model of an HTTP response. It is the library's output: the handlers fill it in and the adapter copies it onto the real HTTP response. The handlers set the status themselves:

• 200 for a token;
• the error's code on failure;
• 302 through redirect().

So a status passed in by the caller has no legitimate use. @jankapunkt showed it would leak into a successful token response, against RFC 6749 §5.1.

The status has started at 200 since 2015, and that doesn't change here. This PR now documents that behaviour and pins it with tests, and makes no change to how the library behaves:

• JSDoc: the Response constructor says the status always starts as 200 and is set by the handlers, so it can't be passed in. The otherOptions description now says it never overwrites properties the response already has, such as status or its methods; it also said "request" where it meant "response". A separate commit removes a method param, which the constructor never accepted. docs/api/response.md is regenerated.
• Tests: a constructor test checks that status: 404 is ignored. @jankapunkt's compliance test checks that a successful token response is 200 even when the Response was created with status: 404.

index.d.ts is unchanged.

Linked issue(s)

None. Found while reviewing other open PRs.

Involved parts of the project

• lib/response.js: constructor JSDoc only
• docs/api/response.md: regenerated from JSDoc
• test/integration/response_test.js, test/compliance/client-credential-workflow_test.js

Added tests?

Yes, as above. Both pass on master and fail if the constructor honours status. I checked that against the earlier version of this PR. biome check . is clean and the full mocha suite passes (466).

OAuth2 standard

No change in behaviour. The new compliance test pins RFC 6749 §5.1's 200 (OK) for a successful token response.

Reproduction

const { Response } = require('@node-oauth/oauth2-server');
new Response({ status: 404 }).status; // 200, by design

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The constructor typings reject previously accepted array-valued headers.

0 open findings

What changed in this PR

Fixes Response construction to honour integer status values while retaining the default 200 for other values.

Changes:

• Handles explicit status values and adds regression tests.
• Expands constructor typings.
• Updates constructor documentation and removes the incorrect method parameter.

File	Description
test/​integration/​response_test.js	Tests explicit status and function-valued status fallback.
lib/​response.js	Accepts integer status values and updates JSDoc.
index.d.ts	Declares constructor options explicitly.
docs/​api/​response.md	Updates generated constructor documentation.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The focused change matches the intended behaviour, includes regression coverage, and has no identified blocking issues.

0 open findings

🧠 Review effort: Balanced

[jankapunkt]

While this fixes the immediate visible issue, there is one indirect consequence of this: "OAuth2 Standard not affected" is a little too broad. If someone passes status 404, a successful token response will now keep that status, even though OAuth2 expects 200. The usual behavior stays the same when no status is passed.

Consider the following test case in client-credential-workflow_test.js:

    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);
    });

In its current state it will fail because TokenHandler.updateSuccessResponse still implies the previous behavior and does not set any 200 response.

[dhensby]

Thanks; that's a good point and something I had thought about. Initially I was thinking Request would be a fully abstract implementation of a HTTP response, but really it's an internal representation and there's no reason for a consumer to be constructing it with a status that needs persisting. I've reworked the PR just to improve the docs.