{
"name": "cookies",
"version": "0.1.6",
"description": "Cookies, optionally signed using Keygrip.",
"main": "./index",
"engines": [
"node"
],
"directories": {
"lib": "./lib"
},
"files": [
""
],
"readme": "Cookies\n=======\n\nCookies is a [node.js](http://nodejs.org/) module for getting and setting HTTP(S) cookies. Cookies can be signed to prevent tampering, using [Keygrip](https://github.com/jed/keygrip).\n\n## Requirements\n\n* [node.js](http://nodejs.org/), tested with 0.4.1\n\n## Install\n\n $ npm install cookies\n \n## Features\n\nThis is the next version of the now deprecated [cookie-node](https://github.com/jed/cookie-node) library, with the following improvements:\n\n* **Lazy**: Since cookie verification against multiple keys could be expensive, cookies are only verified lazily when accessed, not eagerly on each request.\n\n* **Unobtrusive**: Signed cookies are stored the same way as unsigned cookies, instead of in an obfuscated signing format. An additional signature cookie is stored for each signed cookie, using a standard naming convention (_cookie-name_`.sig`). This allows other libraries to access the original cookies without having to know the signing mechanism.\n\n* **Agnostic**: This library is optimized for use with [Keygrip](https://github.com/jed/keygrip), but does not require it; you can implement your own signing scheme instead if you like and use this library only to read/write cookies. Factoring the signing into a separate library encourages code reuse and allows you to use the same signing library for other areas where signing is needed, such as in URLs.\n\n* **Up-to-date**: Whereas the last library was built starting with an v0.1.* version of node without crypto or buffers, this one was built starting with v0.4.1. This means that it's a lot cleaner than the previous version, which was getting crufty after a year of API changes.\n\n## API\n\n### cookies = new Cookies( request, response, [ Object keygrip ] )\n\nThis creates a cookie jar corresponding to the current _request_ and _response_. A [Keygrip](https://github.com/jed/keygrip) object can optionally be passed as the third argument _keygrip_ to enable cryptographic signing based on SHA1 HMAC, using rotated credentials.\n\nNote that since this only saves parameters without any other processing, it is very lightweight. Cookies are only parsed on demand when they are accessed.\n\n### cookies.get( name, [ options ] )\n\nThis extracts the cookie with the given name from the `Cookie` header in the request. If such a cookie exists, its value is returned. Otherwise, nothing is returned.\n\n`{ signed: true }` can optionally be passed as the second parameter _options_. In this case, a signature cookie (a cookie of same name ending with the `.sig` suffix appended) is fetched. If no such cookie exists, nothing is returned.\n\nIf the signature cookie _does_ exist, the provided [Keygrip](https://github.com/jed/keygrip) object is used to check whether the hash of _<cookie-name>_ + `=` + _<cookie-value>_ matches that of any registered key:\n\n* If the signature cookie hash matches the first key, the original cookie value is returned.\n* If the signature cookie hash matches any other key, the original cookie value is returned AND an outbound header is set to update the signature cookie's value to the hash of the first key. This enables automatic freshening of signature cookies that have become stale due to key rotation.\n* If the signature cookie hash does not match any key, nothing is returned, and an outbound header with an expired date is used to delete the cookie.\n\n### cookies.set( name, [ value ], [ options ] )\n\nThis sets the given cookie in the response and returns the current context to allow chaining.\n\nIf the _name_ is omitted, an outbound header with an expired date is used to delete the cookie.\n\nIf the _options_ object is provided, it will be used to generate the outbound cookie header as follows:\n\n* `expires`: a `Date` object indicating the cookie's expiration date (expires at the end of session by default).\n* `path`: a string indicating the path of the cookie (`/` by default).\n* `domain`: a string indicating the domain of the cookie (no default).\n* `secure`: a boolean indicating whether the cookie is only to be sent over HTTPS (`false` by default).\n* `httpOnly`: a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (`false` by default).\n* `signed`: a boolean indicating whether the cookie is to be signed (`false` by default). If this is true, another cookie of the same name with the `.sig` suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of _<cookie-name>_ + `=` + _<cookie-value>_ against the first [Keygrip](https://github.com/jed/keygrip) key. This signature key is used to detect tampering the next time a cookie is received.\n\n## Example\n\n // from ./test.js\n var assert = require( \"assert\" )\n , http = require( \"http\" )\n , keys = require( \"keygrip\" )()\n , Cookies = require( \"cookies\" )\n \n http.createServer( function( req, res ) {\n var cookies = new Cookies( req, res, keys )\n , insecure, secure, tampered\n \n if ( req.url == \"/set\" ) {\n cookies\n // set a regular cookie\n .set( \"insecure\", \"foo\" )\n \n // set a signed cookie\n .set( \"secure\", \"bar\", { signed: true } )\n \n // mimic a signed cookie, but with a bogus signature\n .set( \"tampered\", \"baz\" )\n .set( \"tampered.sig\", \"bogus\" )\n \n res.writeHead( 302, { \"Location\": \"/\" } )\n return res.end( \"Now let's check.\" )\n }\n \n insecure = cookies.get( \"insecure\" )\n secure = cookies.get( \"secure\", { signed: true } )\n tampered = cookies.get( \"tampered\", { signed: true } )\n \n assert.equal( insecure, \"foo\" )\n assert.equal( secure, \"bar\" )\n assert.notEqual( tampered, \"baz\" )\n assert.equal( tampered, undefined )\n \n res.writeHead( 200, { \"Content-Type\": \"text/plain\" } )\n res.end(\n \"insecure expected: foo\\n\\n\" +\n \"insecure actual: \" + insecure + \"\\n\\n\" +\n \"secure expected: bar\\n\\n\" +\n \"secure actual: \" + secure + \"\\n\\n\" +\n \"tampered expected: undefined\\n\\n\"+\n \"tampered: \" + tampered + \"\\n\\n\"\n )\n }).listen( 8000 )\n\n## TODO\n\n* Look for existing outbound cookies to prevent duplicates\n\nCopyright\n---------\n\nCopyright (c) 2011 Jed Schmidt. See LICENSE.txt for details.\n\nSend any questions or comments [here](http://twitter.com/jedschmidt).",
"readmeFilename": "README.md",
"_id": "cookies@0.1.6",
"dist": {
"shasum": "1d02447078aa5872414a31eff45c9c52e85e138b"
},
"_from": "cookies@0.1.x"
}
|
Download
