or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

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."
}