request-csrf

A simple CSRF protection wrapper for the request library.

Installation

npm install request-csrf

Features

• Automatically adds CSRF tokens to requests
• Validates CSRF tokens in responses
• Supports both callback and promise-based APIs
• Compatible with all request library options

How It Works

This package provides a simple anti-CSRF security measure by:

1. Generating a random CSRF token for each request
2. Adding the token to the request headers
3. Validating that the server returns the same token in the response headers
4. Failing the request if the token is missing or invalid (for non-GET requests)

Usage

Basic Usage

const { csrfRequest } = require('request-csrf');

// Make a request with CSRF protection
csrfRequest({
  uri: 'https://api.example.com/data',
  method: 'POST',
  json: { name: 'John' }
}, (error, response) => {
  if (error) {
    console.error('Request failed:', error);
    return;
  }
  
  console.log('Response:', response.body);
  console.log('CSRF Token:', response.csrfToken);
});

Promise-based API

const { csrfRequestPromise } = require('request-csrf');

async function makeRequest() {
  try {
    const response = await csrfRequestPromise({
      uri: 'https://api.example.com/data',
      method: 'POST',
      json: { name: 'John' }
    });
    
    console.log('Response:', response.body);
    console.log('CSRF Token:', response.csrfToken);
  } catch (error) {
    console.error('Request failed:', error);
  }
}

makeRequest();

Convenience Methods

const { post, get } = require('request-csrf');

// GET request
get('https://api.example.com/data', (error, response) => {
  // Handle response
});

// POST request
post('https://api.example.com/data', 
  { json: { name: 'John' } },
  (error, response) => {
    // Handle response
  }
);

Custom CSRF Options

const { csrfRequest } = require('request-csrf');

csrfRequest({
  uri: 'https://api.example.com/data',
  method: 'POST',
  json: { name: 'John' },
  // Custom CSRF options
  csrfToken: 'my-existing-token', // Use an existing token
  csrfHeaderName: 'X-Custom-CSRF-Token', // Custom header name
  validateCsrf: false // Skip validation
}, (error, response) => {
  // Handle response
});

API Reference

csrfRequest(options, callback)

Makes a request with CSRF protection.

• options: All standard request options plus:
  • csrfToken: Optional existing token to use
  • csrfHeaderName: Custom header name (default: 'X-CSRF-Token')
  • csrfCookieName: Custom cookie name (default: 'csrf_token')
  • validateCsrf: Whether to validate the token (default: true for non-GET)
• callback: Function called with (error, response)
  • response.response: Original HTTP response
  • response.body: Response body
  • response.csrfToken: CSRF token used

csrfRequestPromise(options)

Promise-based version of csrfRequest.

HTTP Method Helpers

• get(uri, options, callback)
• post(uri, options, callback)
• put(uri, options, callback)
• patch(uri, options, callback)
• del(uri, options, callback)

generateCsrfToken()

Generates a random CSRF token.

License

GNU General Public License v3.0 (GPL-3.0)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This means that any software that uses this package must also be released under the GPL-3.0 license, ensuring that derivative works remain open source.