fix: reject multiple values for singleton response headers (#2012)

## Summary
- reject empty or multiple-value arrays; normalize one-item arrays.
[edited by @yowainwright]
- apply the validation consistently to both `ctx.set(name, value)` and
`ctx.set(headers)`
- add regression coverage for both call forms

## Test plan
- `npm test`
- `npm run lint`
- `git diff --check`

Related to #1973

## Summary by Sourcery

Enforce single-value response headers consistently while retaining valid
multi-valued header support.

Bug Fixes:
- Reject multiple or empty values for singleton response headers while
preserving support for multi-valued headers such as Set-Cookie.
- Apply singleton-header validation consistently when setting individual
headers and header maps, including error responses.

Enhancements:
- Normalize single-element Content-Type and Content-Length arrays to
scalar header values and validate header maps before making assignments.

Tests:
- Add regression coverage for singleton-header validation,
normalization, atomic header assignment, single-read field access, and
error-response headers.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Setting multiple values for `Content-Type` or `Content-Length` now
throws an error, whether headers are set individually or together. Error
messages preserve the supplied header-name casing.
* When setting headers together, an invalid value prevents earlier
headers in the same assignment from being set.
* Single-value arrays are accepted for these headers, and each
object-form header value is read once.
* Error responses continue to apply other supplied headers, including
cookies, while ignoring supplied `Content-Type` and `Content-Length`
values.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: shuaiyafei <16618929+shuaiyafei@users.noreply.github.com>
Co-authored-by: Jeff Wainwright <1074042+yowainwright@users.noreply.github.com>

Author: shuaiyafei

__tests__/context/onerror.test.js

@@ -56,19 +56,25 @@ describe('ctx.onerror(err)', () => {
         status: 418,
         expose: true,
         headers: {
+          'Content-Length': ['1', '2'],
+          'cOnTeNt-TyPe': ['text/plain', 'application/json'],
+          'Set-Cookie': ['first=1', 'second=2'],
           'X-New-Header': 'Value'
         }
       })
     })
 
     const res = await request(app.callback())
       .get('/')
-      .expect(418)
+      .timeout({ deadline: 1000 })
+      .expect(418, 'boom')
       .expect('Content-Type', 'text/plain; charset=utf-8')
+      .expect('Content-Length', '4')
       .expect('X-New-Header', 'Value')
 
     assert.strictEqual(Object.prototype.hasOwnProperty.call(res.headers, 'vary'), false)
     assert.strictEqual(Object.prototype.hasOwnProperty.call(res.headers, 'x-csrf-token'), false)
+    assert.deepStrictEqual(res.headers['set-cookie'], ['first=1', 'second=2'])
   })
 
   it('should ignore error after headerSent', async () => {

__tests__/response/set.test.js

@@ -42,4 +42,73 @@ describe('ctx.set(object)', () => {
     assert.strictEqual(ctx.response.header.foo, '1')
     assert.strictEqual(ctx.response.header.bar, '2')
   })
+
+  it('should not assign multiple values to singleton headers', () => {
+    const ctx = context()
+
+    assert.throws(() => {
+      ctx.set('content-length', ['1', '2'])
+    }, /content-length must contain exactly one value/)
+
+    assert.throws(() => {
+      ctx.set({ 'Content-Length': ['1', '2'] })
+    }, /Content-Length must contain exactly one value/)
+
+    assert.throws(() => {
+      ctx.set({ 'cOnTeNt-TyPe': ['text/plain', 'application/json'] })
+    }, /cOnTeNt-TyPe must contain exactly one value/)
+  })
+
+  it('should normalize singleton header arrays', () => {
+    const ctx = context()
+
+    ctx.set('Content-Length', ['1'])
+    assert.strictEqual(ctx.response.get('Content-Length'), '1')
+
+    ctx.set({ 'Content-Type': ['application/json'] })
+    ctx.body = { ok: true }
+    assert.strictEqual(ctx.response.get('Content-Type'), 'application/json')
+
+    ctx.set('Content-Type', ['application/json'])
+    ctx.body = { ok: true }
+    assert.strictEqual(ctx.response.get('Content-Type'), 'application/json')
+  })
+
+  it('should reject empty arrays for singleton headers', () => {
+    const ctx = context()
+
+    assert.throws(() => ctx.set('Content-Type', []), /must contain exactly one value/)
+    assert.throws(() => ctx.set('Content-Length', []), /must contain exactly one value/)
+    assert.throws(() => ctx.set({ 'Content-Type': [] }), /must contain exactly one value/)
+    assert.throws(() => ctx.set({ 'Content-Length': [] }), /must contain exactly one value/)
+  })
+
+  it('should validate every field before assigning any values', () => {
+    const ctx = context()
+
+    assert.throws(() => {
+      ctx.set({
+        'X-Foo': 'bar',
+        'Content-Length': ['1', '2']
+      })
+    }, /Content-Length must contain exactly one value/)
+
+    assert.strictEqual(ctx.response.header['x-foo'], undefined)
+  })
+
+  it('should read each field value once', () => {
+    const ctx = context()
+    let reads = 0
+    const fields = {
+      get 'Content-Length' () {
+        reads++
+        return reads === 1 ? '1' : ['1', '2']
+      }
+    }
+
+    ctx.set(fields)
+
+    assert.strictEqual(reads, 1)
+    assert.strictEqual(ctx.response.header['content-length'], '1')
+  })
 })

lib/context.js

@@ -143,7 +143,13 @@ const proto = module.exports = {
     }
 
     // then set those specified
-    this.set(err.headers)
+    const headers = err.headers || {}
+    Object.keys(headers).forEach(name => {
+      const lowerName = name.toLowerCase()
+      const generatedHeader = lowerName === 'content-type' || lowerName === 'content-length'
+      if (generatedHeader) return
+      this.set(name, headers[name])
+    })
 
     // force text/plain
     this.type = 'text'

lib/response.js

@@ -21,6 +21,19 @@ const getType = require('mime-types').contentType
 const isStream = require('./is-stream.js')
 const only = require('./only.js')
 
+function isSingleValueHeader (field) {
+  const name = field.toLowerCase()
+  return name === 'content-type' || name === 'content-length'
+}
+
+function normalizeHeader (field, value) {
+  const singletonArray = isSingleValueHeader(field) && Array.isArray(value)
+  if (!singletonArray) return [field, value]
+
+  assert(value.length === 1, `${field} must contain exactly one value`)
+  return [field, value[0]]
+}
+
 /**
  * Prototype.
  */
@@ -537,14 +550,12 @@ module.exports = {
   set (field, val) {
     if (this.headerSent || !field) return
 
-    if (typeof field === 'string') {
-      if (field.toLowerCase() === 'content-type') {
-        assert(!Array.isArray(val), 'Assign multiple Content-Type for response header is not allowed')
-      }
-      this.res.setHeader(field, val)
-    } else {
-      Object.keys(field).forEach(header => this.res.setHeader(header, field[header]))
-    }
+    const entries = typeof field === 'string' ? [[field, val]] : Object.entries(field)
+    const headers = entries.map(([name, value]) => normalizeHeader(name, value))
+
+    headers.forEach(([name, value]) => {
+      this.res.setHeader(name, value)
+    })
   },
 
   /**