@medley/cookie v0.3.0

@medley/cookie

Medley plugin for parsing and setting cookies.

Installation

npm install @medley/cookie --save
# or
yarn add @medley/cookie

Usage

const medley = require('@medley/medley');
const app = medley();

app.register(require('@medley/cookie'));

app.get('/', (req, res) => {
  if (req.cookies.foo === undefined) {
    res.setCookie('foo', 'bar');
    res.send('cookie set');
  } else {
    res.send(`cookie: foo = ${req.cookies.foo}`);
  }
});

Plugin Options

secret

Type: string

Used for signing/unsigning cookies.

app.register(require('@medley/cookie'), {
  secret: 'to everybody', // `secret` should be a long, random string
});

app.get('/', (req, res) => {
  if (req.cookies.foo === undefined) {
    const fooCookie = res.signCookie('foo-value')
    res.setCookie('foo', foo);
    res.send('cookie set');
  } else {
    const fooCookie = req.unsignCookie(req.cookies.foo);
    res.send(`foo = ${fooCookie}`);
  }
});

decode

Type: function Default: decodeURIComponent

A function that will be used to decode each cookies' value.

app.register(require('@medley/cookie'), {
  decode: require('safe-decode-uri-component'),
});

API

• req.cookies
• req.unsignCookie(value)
• res.signCookie(value)
• res.setCookie(name, value[, options])
  • Options
• res.clearCookie(name[, options])

req.cookies

An object of parsed cookies.

app.get('/', (req, res) => {
  req.cookies // { cookieName: 'cookieValue', foo: 'bar' }
});

req.unsignCookie(value)

• value (string) - A cookie value.
• Returns (string | false) - The original cookie value (before signing) or false if the cookie was tampered with.

Unsigns a cookie value.

const fooCookie = req.unsignCookie(req.cookies.foo);
console.log(fooCookie); // 'bar'

const tamperedFooCookie = req.unsignCookie(req.cookies.foo + 'str');
console.log(tamperedFooCookie); // false

res.signCookie(value)

• value (string) - A cookie value.
• Returns (string) - The signed cookie value.

Signs a cookie value.

const signedValue = res.signCookie('hello');
console.log(signedValue); // 'hello.DGDUkGlIkCzPz+C0B064FNgHdEjox7ch8tOBGslZ5QI'

res.setCookie('greeting', signedValue);

The signed value will be different depending on the secret option used when registering the plugin.

res.setCookie(name, value[, options])

• name (string) - The name of the cookie.
• value (string) - The cookie value.
• options (object) - See the options below.
• chainable

Sets a cookie with name to value.

res.setCookie('foo', 'bar');

// Sets a cookie that expires in 1 hour
res.setCookie('rememberme', 'true', { maxAge: 3600, httpOnly: true, secure: true });

// Default encode option
res.setCookie('cross_domain_cookie', 'value!', {
  domain: 'example.com'
});
// Result: 'cross_domain_cookie=value!; Domain=example.com; Path=/'

// Custom encode option
res.setCookie('cross_domain_cookie', 'value!', {
  domain: 'example.com',
  encode: require('strict-uri-encode') // https://www.npmjs.com/package/strict-uri-encode
});
// Result: 'cross_domain_cookie=value%21; Domain=example.com; Path=/;'

Options

res.clearCookie(name[, options])

• name (string) - The name of a cookie.
• options (object) - See the options above.
• chainable

Clears a previously set cookie with name.

Note that for the cookie to be cleared, the domain, httpOnly, path, sameSite, and secure options must be the same as when the cookie was originally set.

res.clearCookie('foo');
res.clearCookie('rememberme', { httpOnly: true, secure: true });