CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-cookie-signature

Sign and unsign cookies using HMAC-SHA256 for secure cookie authentication

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Cookie Signature

Cookie Signature is a secure cookie signing and verification library for Node.js applications. It uses HMAC-SHA256 to generate cryptographic signatures that can be appended to cookie values, ensuring cookie integrity and preventing tampering. The library provides timing-safe signature verification to prevent timing attacks.

Package Information

  • Package Name: cookie-signature
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cookie-signature

Core Imports

const cookie = require('cookie-signature');

Basic Usage

const cookie = require('cookie-signature');

// Sign a cookie value
const signedValue = cookie.sign('hello', 'secret-key');
// Result: 'hello.DGDUkGlIkCzPz+C0B064FNgHdEjox7ch8tOBGslZ5QI'

// Verify and unsign a cookie
const originalValue = cookie.unsign(signedValue, 'secret-key');
// Result: 'hello'

// Invalid signatures return false
const invalid = cookie.unsign(signedValue, 'wrong-key');
// Result: false

Capabilities

Cookie Signing

Signs a cookie value with a secret key using HMAC-SHA256 cryptographic hashing.

/**
 * Sign the given value with secret key
 * @param {string} val - The value to be signed
 * @param {string|NodeJS.ArrayBufferView|crypto.KeyObject} secret - Secret key for signing
 * @returns {string} The signed value in format "value.signature"
 * @throws {TypeError} If val is not a string or secret is null/undefined
 */
function sign(val, secret);

Usage Examples:

const cookie = require('cookie-signature');

// Basic string signing
const signed = cookie.sign('user123', 'my-secret-key');

// Works with Buffer secrets for enhanced security
const keyBuffer = Buffer.from('A0ABBC0C', 'hex');
const signedWithBuffer = cookie.sign('sessiondata', keyBuffer);

// Works with Uint8Array secrets
const keyArray = new Uint8Array([0xA0, 0xAB, 0xBC, 0x0C]);
const signedWithArray = cookie.sign('tokendata', keyArray);

Cookie Verification

Verifies and unsigns a signed cookie value, returning the original value or false if the signature is invalid. Uses timing-safe comparison to prevent timing attacks.

/**
 * Unsign and decode the given input with secret, returning false if signature is invalid
 * @param {string} input - The signed cookie string to verify
 * @param {string|NodeJS.ArrayBufferView|crypto.KeyObject} secret - Secret key for verification
 * @returns {string|boolean} Original value if valid, false if invalid signature
 * @throws {TypeError} If input is not a string or secret is null/undefined
 */
function unsign(input, secret);

Usage Examples:

const cookie = require('cookie-signature');

// Verify a signed cookie
const signed = 'hello.DGDUkGlIkCzPz+C0B064FNgHdEjox7ch8tOBGslZ5QI';
const original = cookie.unsign(signed, 'tobiiscool');
// Result: 'hello'

// Invalid signatures return false
const tampered = 'hello.invalid-signature';
const result = cookie.unsign(tampered, 'tobiiscool');
// Result: false

// Wrong secret key returns false
const wrongKey = cookie.unsign(signed, 'wrong-secret');
// Result: false

// Works with non-string secrets
const keyBuffer = Buffer.from('A0ABBC0C', 'hex');
const verifiedWithBuffer = cookie.unsign('hello.hIvljrKw5oOZtHHSq5u+MlL27cgnPKX77y7F+x5r1to', keyBuffer);
// Result: 'hello'

Security Features

  • HMAC-SHA256: Uses cryptographically secure hashing algorithm
  • Timing-Safe Comparison: Prevents timing attacks during signature verification
  • Type Validation: Validates input types to prevent common security errors
  • Secret Key Flexibility: Supports string, Buffer, Uint8Array, and KeyObject secret types
  • Base64 Encoding: Uses base64 encoding for compact signature representation (with padding removed)

Error Handling

Both functions throw TypeError exceptions for invalid inputs:

  • sign() throws if val is not a string or secret is null/undefined
  • unsign() throws if input is not a string or secret is null/undefined

Example Error Handling:

const cookie = require('cookie-signature');

try {
  // This will throw TypeError
  cookie.sign(123, 'secret');
} catch (error) {
  console.error(error.message); // "Cookie value must be provided as a string."
}

try {
  // This will throw TypeError
  cookie.sign('value', null);
} catch (error) {
  console.error(error.message); // "Secret key must be provided."
}

try {
  // This will throw TypeError
  cookie.unsign(123, 'secret');
} catch (error) {
  console.error(error.message); // "Signed cookie string must be provided."
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cookie-signature@1.2.x
Publish Source
CLI
Badge
tessl/npm-cookie-signature badge