1 | # cookie-parser
|
2 |
|
3 | [![NPM Version][npm-version-image]][npm-url]
|
4 | [![NPM Downloads][npm-downloads-image]][npm-url]
|
5 | [![Build Status][ci-image]][ci-url]
|
6 | [![Test Coverage][coveralls-image]][coveralls-url]
|
7 |
|
8 | Parse `Cookie` header and populate `req.cookies` with an object keyed by the
|
9 | cookie names. Optionally you may enable signed cookie support by passing a
|
10 | `secret` string, which assigns `req.secret` so it may be used by other
|
11 | middleware.
|
12 |
|
13 | ## Installation
|
14 |
|
15 | ```sh
|
16 | $ npm install cookie-parser
|
17 | ```
|
18 |
|
19 | ## API
|
20 |
|
21 | ```js
|
22 | var cookieParser = require('cookie-parser')
|
23 | ```
|
24 |
|
25 | ### cookieParser(secret, options)
|
26 |
|
27 | Create a new cookie parser middleware function using the given `secret` and
|
28 | `options`.
|
29 |
|
30 | - `secret` a string or array used for signing cookies. This is optional and if
|
31 | not specified, will not parse signed cookies. If a string is provided, this
|
32 | is used as the secret. If an array is provided, an attempt will be made to
|
33 | unsign the cookie with each secret in order.
|
34 | - `options` an object that is passed to `cookie.parse` as the second option. See
|
35 | [cookie](https://www.npmjs.org/package/cookie) for more information.
|
36 | - `decode` a function to decode the value of the cookie
|
37 |
|
38 | The middleware will parse the `Cookie` header on the request and expose the
|
39 | cookie data as the property `req.cookies` and, if a `secret` was provided, as
|
40 | the property `req.signedCookies`. These properties are name value pairs of the
|
41 | cookie name to cookie value.
|
42 |
|
43 | When `secret` is provided, this module will unsign and validate any signed cookie
|
44 | values and move those name value pairs from `req.cookies` into `req.signedCookies`.
|
45 | A signed cookie is a cookie that has a value prefixed with `s:`. Signed cookies
|
46 | that fail signature validation will have the value `false` instead of the tampered
|
47 | value.
|
48 |
|
49 | In addition, this module supports special "JSON cookies". These are cookie where
|
50 | the value is prefixed with `j:`. When these values are encountered, the value will
|
51 | be exposed as the result of `JSON.parse`. If parsing fails, the original value will
|
52 | remain.
|
53 |
|
54 | ### cookieParser.JSONCookie(str)
|
55 |
|
56 | Parse a cookie value as a JSON cookie. This will return the parsed JSON value
|
57 | if it was a JSON cookie, otherwise, it will return the passed value.
|
58 |
|
59 | ### cookieParser.JSONCookies(cookies)
|
60 |
|
61 | Given an object, this will iterate over the keys and call `JSONCookie` on each
|
62 | value, replacing the original value with the parsed value. This returns the
|
63 | same object that was passed in.
|
64 |
|
65 | ### cookieParser.signedCookie(str, secret)
|
66 |
|
67 | Parse a cookie value as a signed cookie. This will return the parsed unsigned
|
68 | value if it was a signed cookie and the signature was valid. If the value was
|
69 | not signed, the original value is returned. If the value was signed but the
|
70 | signature could not be validated, `false` is returned.
|
71 |
|
72 | The `secret` argument can be an array or string. If a string is provided, this
|
73 | is used as the secret. If an array is provided, an attempt will be made to
|
74 | unsign the cookie with each secret in order.
|
75 |
|
76 | ### cookieParser.signedCookies(cookies, secret)
|
77 |
|
78 | Given an object, this will iterate over the keys and check if any value is a
|
79 | signed cookie. If it is a signed cookie and the signature is valid, the key
|
80 | will be deleted from the object and added to the new object that is returned.
|
81 |
|
82 | The `secret` argument can be an array or string. If a string is provided, this
|
83 | is used as the secret. If an array is provided, an attempt will be made to
|
84 | unsign the cookie with each secret in order.
|
85 |
|
86 | ## Example
|
87 |
|
88 | ```js
|
89 | var express = require('express')
|
90 | var cookieParser = require('cookie-parser')
|
91 |
|
92 | var app = express()
|
93 | app.use(cookieParser())
|
94 |
|
95 | app.get('/', function (req, res) {
|
96 | // Cookies that have not been signed
|
97 | console.log('Cookies: ', req.cookies)
|
98 |
|
99 | // Cookies that have been signed
|
100 | console.log('Signed Cookies: ', req.signedCookies)
|
101 | })
|
102 |
|
103 | app.listen(8080)
|
104 |
|
105 | // curl command that sends an HTTP request with two cookies
|
106 | // curl http://127.0.0.1:8080 --cookie "Cho=Kim;Greet=Hello"
|
107 | ```
|
108 |
|
109 | ## License
|
110 |
|
111 | [MIT](LICENSE)
|
112 |
|
113 | [ci-image]: https://badgen.net/github/checks/expressjs/cookie-parser/master?label=ci
|
114 | [ci-url]: https://github.com/expressjs/cookie-parser/actions?query=workflow%3Aci
|
115 | [coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/cookie-parser/master
|
116 | [coveralls-url]: https://coveralls.io/r/expressjs/cookie-parser?branch=master
|
117 | [npm-downloads-image]: https://badgen.net/npm/dm/cookie-parser
|
118 | [npm-url]: https://npmjs.org/package/cookie-parser
|
119 | [npm-version-image]: https://badgen.net/npm/v/cookie-parser
|