User and guest session tokens

Usage no npm install needed!

<script type="module">
  import charmanderSession from 'https://cdn.skypack.dev/@charmander/session';


Build status


Session tokens are secret strings consisting of 32 ASCII characters in the range a through p.

CSRF tokens are secret strings constisting of 30 ASCII characters in the range a through p.

Storage keys are 16-byte Buffer values that don’t need to be treated as secret.

User ids are non-null/undefined values otherwise free to be defined by the user of the SessionBox.

  • new SessionBox(storage)

  • SessionBox#get(token, callback)

    Gets a session based on a token. The session token can change after this operation, indicated by a non-null newToken property. Pass null if no token was provided.

  • SessionBox#update(session, newUserId, callback)

    Updates a session obtained from SessionBox#get with a new user id. The session token will always change after this operation, and the old session will be invalidated. Pass null to update to a guest session.


Sessions have the following public properties:

  • newToken

    A new session token to return to the client, or null if the existing session token remains valid.

  • userId

    The user id associated with the session. null represents a guest session.

  • csrf

    The CSRF token associated with the session.


A storage implementation should provide these methods:

  • get(key, callback)

    Retrieves a user id based on a key. The callback has two parameters: error, userId.

    If the key does not exist, the retrieved value should be null (but undefined is also accepted).

  • set(key, userId, callback)

    Associates a user id with a key. The callback has one parameter: error.

    The key will not already exist.

  • delete(key, userId, callback)

    Disassociates a user id from a key. The id is provided in case the storage maintains a set of keys for each user (e.g. for the purposes of invalidating all of a user’s sessions). The callback has one parameter: error.

    If the key does not exist, no error should be produced.