cookie-parser

Postconditions — what we check

• cookieParser · malformed-cookie-silent

  info
  WhenA cookie value is malformed or cannot be parsed
  ReturnsMalformed cookies are silently skipped; req.cookies will not contain the unparseable entry. No error is thrown.
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• cookieParser · signed-cookie-invalid-signature

  warning
  WhenA signed cookie fails HMAC signature validation
  Returnsreq.signedCookies[name] is set to false (boolean) instead of the cookie value
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• cookieParser · signed-cookie-no-secret

  warning
  WhenSigned cookies are present in the request but no secret was passed to cookieParser()
  ReturnsSigned cookies are not validated and are not placed in req.signedCookies. They remain in req.cookies with their raw s:... value.
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• cookieParser · parse-error-propagated

  error
  WhenAn unexpected internal parse error occurs
  ThrowsError propagated to Express error handler via next(err)
  Required handlingCaller MUST have an Express error handler middleware (4-argument handler) registered after the router to catch parse errors. Without an error handler, Express will send a 500 response or crash.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• cookieParser · success

  info
  WhenCookie header is present and parseable
  Returnsreq.cookies populated with parsed cookie key-value pairs; req.signedCookies populated with verified signed cookies
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• signedCookie · signed-cookie-tampered-false

  warning
  WhenThe cookie value starts with 's:' but the HMAC signature does not match any of the provided secrets. The cookie has been tampered with or the wrong secret is being used.
  ReturnsReturns boolean false. Does NOT throw an error. Callers that check truthiness (e.g. `if (result)`) will silently treat a tampered cookie as "not present" rather than as a security violation.
  Required handlingCallers MUST explicitly check `result === false` (strict equality) rather than truthiness. A falsy check conflates "invalid signature" (false) with "not a signed cookie" (original string). Use the result to reject the request or invalidate the session when false.
  costhighin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[2][3]
• signedCookie · signed-cookie-non-string-undefined

  warning
  WhenThe `str` argument is not a string (e.g. undefined, null, number, or object). This happens when the cookie value is missing or when the caller passes req.cookies[name] without checking existence first.
  ReturnsReturns undefined. No error is thrown. Callers that do not check for undefined will pass undefined downstream silently.
  Required handlingCallers MUST check that the input is a defined string before calling signedCookie(). Alternatively, check the return value for undefined before using it.
  costmediumin prodsilent failureusers seeauthentication failurevisibilitysilent
  Sources[2]
• signedCookies · signed-cookies-mutates-input

  warning
  WhenThe function is called with a cookies object containing any signed cookies (values starting with 's:'). All signed cookie keys are deleted from the input object as a side effect.
  ReturnsThe input `cookies` object is mutated — signed cookies are deleted from it. A new separate object is returned containing the signed cookies mapped to their validated values (string) or false (invalid signature). Callers who pass `req.cookies` directly will find those keys removed from req.cookies.
  Required handlingCallers MUST be aware that the input object is mutated. If the original cookies object is needed after calling signedCookies(), clone it first with Object.assign({}, cookies) or spread { ...cookies }.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[2]
• signedCookies · signed-cookies-false-on-tamper

  warning
  WhenOne or more signed cookies in the input have invalid HMAC signatures.
  ReturnsThe returned object contains the cookie name mapped to false (boolean) for each tampered cookie. Callers that iterate over the result without checking for false values will silently pass tampered data downstream.
  Required handlingAfter calling signedCookies(), callers MUST check each value with strict equality (`val === false`) before trusting it. Do not use truthiness check as false (tampered) is falsy.
  costhighin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[2]
• JSONCookie · json-cookie-undefined-for-non-json

  warning
  WhenThe cookie value does not start with 'j:' (not a JSON cookie), or the value after 'j:' is not valid JSON, or the input is not a string.
  ReturnsReturns undefined. Does NOT return the original string value. Callers who expect the original string to be returned when parsing fails will get undefined instead — a common source of bugs when using JSONCookie() as a general-purpose parse-or-passthrough function.
  Required handlingCallers MUST check the return value for undefined before using it. JSONCookie() is NOT a safe fallback parser — it returns undefined for non-JSON cookies. Use it only when the cookie is expected to be a JSON cookie, and handle undefined as "not a JSON cookie."
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[2][4]
• JSONCookies · json-cookies-mutates-input

  info
  WhenThe cookies object contains any values starting with 'j:' that parse successfully as JSON.
  ReturnsThe input cookies object is mutated in-place — JSON cookie string values are replaced with parsed object values. The same object reference is returned. Callers who retain a reference to the original object will see the mutated values.
  Required handlingCallers MUST be aware that the input is mutated. If the original string values are needed after calling JSONCookies(), clone the object first. The returned value and the input argument point to the same object.
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[2]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/expressjs/cookie-parserhttps://github.com/expressjs/cookie-parser/blob/master/README.md
2. [2]github.com/expressjs/cookie-parserhttps://github.com/expressjs/cookie-parser/blob/master/index.js
3. [3]github.com/tj/node-cookie-signaturehttps://github.com/tj/node-cookie-signature/blob/master/index.js
4. [4]raw.githubusercontent.com/expressjs/cookie-parserhttps://raw.githubusercontent.com/expressjs/cookie-parser/master/README.md