@bicycle-codes/session-cookie

session cookie

Create signed cookies with an HMAC key, and verify them.

• works in Cloudflare
• works in Node

This will stringify a JSON object in a stable format, then use an HMAC key to create a signature. The final cookie value includes a token that is the signature concatenated with the JSON you passed in, all base64 encoded.

This conveniently includes a command to generate keys as well.

Parsing the cookie will return the cookie as a plain object, plus a "session token" -- the base64 encoded HMAC signature + session data.

Parsing a session token will return the object that you passed in when creating the token, useful for embedding an ID, or any data you want to be certain has not been changed.

Verify the signature with verifySessionString.

Contents

• install
• Example
  • Create a cookie
  • Create headers
  • Parse a cookie
  • Parse a session token
  • Verify a session token
  • Delete a cookie
• Module Format
  • ESM
  • Common JS
• Generate a secret key
• Environment
• See also

install

npm i -S @bicycle-codes/session-cookie

Example

These functions should all be run in a server.

Create a cookie

Create a string suitable for use as a cookie. Sign the given data with a secret key, and stringify the signature + JSON data as a base64 string.

[!NOTE]
This will add default values for additional cookie attributes.

session=123; Max-Age=604800; Path=/; HttpOnly; Secure; SameSite=Lax

These environment variables can be used to set the cookie attributes:

SESSION_COOKIE_HTTPONLY
SESSION_COOKIE_SECURE
SESSION_COOKIE_SAMESITE
SESSION_COOKIE_MAX_AGE_SPAN
SESSION_COOKIE_DOMAIN
SESSION_COOKIE_PATH

import { createCookie } from '@bicycle-codes/session-cookie'

const cookie = createCookie({ hello: 'world' }, SECRET_KEY)
console.log(cookie)
// => session=vTAHUs4nBS65UPy4AdnIMVdh-5MeyJoZWxsbyI6IndvcmxkIn0; Max-Age=604800; Path=/; HttpOnly; Secure; SameSite=Lax

createCookie (sessionData, secretKey, name?, env?)

async function createCookie (
    sessionData:Record<string, string>,
    secretKey:string,
    name?:string,
    env?:CookieEnv,
):Promise<string>

Create headers

Create or patch a Headers instance.

import { setCookie } from '@bicycle-codes/session-cookie'

const headers = setCookie(cookie)

setCookie(cookie, headers?:Headers)

function setCookie (
    cookie:string,
    _headers?:Headers,
):Headers

Parse a cookie

Parse a cookie string into a plain object.

import { parseCookie } from '@bicycle-codes/session-cookie'

const parsed = parseCookie('session=vTAHUs4nBS65UPy4AdnIMVdh-5MeyJoZWxsbyI6IndvcmxkIn0; Max-Age=604800; Path=/; HttpOnly; Secure; SameSite=Lax')

// =>
//   {
//      session: 'vTAHUs4nBS65UPy4AdnIMVdh-5MeyJoZWxsbyI6IndvcmxkIn0',
//      'Max-Age': '604800',
//      Path: '/',
//      HttpOnly: true,
//      Secure: true,
//      SameSite: 'Lax'
//   }

Parse a session token

Parse a session token. This will return whatever data was used to create the token.

import { parseSession } from '@bicycle-codes/session-cookie'

const session = parseSession(parsed.session as string)
// => { hello: 'world' }

Verify a session token

Verify the given session token. This checks that an embedded signature is correct for the associated data.

import {
    verifySessionString,
    parseCookie
} from '@bicycle-codes/session-cookie'

// ... get headers somehow ...

const cookies = headers.getSetCookie()
const cookie = parseCookie(cookies[0])
const isOk = await verifySessionString(cookie.session, SECRET_KEY)
// => true

verifySessionString(session, key)

async function verifySessionString (
    session:string,
    key:string
):Promise<boolean>

Delete a cookie

Do this serverside. Patch the given headers, removing the cookie.

function rmCookie (headers:Headers, name?:string):void

---

Module Format

This exposes ESM and common JS via package.json exports field.

ESM

import '@bicycle-codes/session-cookie'

Common JS

require('@bicycle-codes/session-cookie')

Generate a secret key

Session cookies are signed using HMAC SHA256, which requires using a secret key of at least 32 bytes of length.

This package conveniently includes a command line tool to generate keys, exposed as cookiekey. After installing this as a dependency, use it like this:

$ npx cookiekey
BGSzELbpBuESqmKyhtw/9zD7sHIy2hf/kSK0y0U0L60=

Environment

Save the secret key as part of your server environment. This depends on always using the same secret key.

This works anywhere that supports the Web Crypto API. Has been verified to work in Cloudflare and Node.

See also

• The docs generated from typescript