tessl/npm-superagent

Elegant & feature rich browser / node HTTP with a fluent API

—

Pending

Overview

Eval results

Files

Authentication & Security

Name: tessl/npm-superagent
Author: tessl

Authentication methods and TLS/SSL certificate configuration for secure communications, including basic authentication, bearer tokens, and client certificate handling.

Capabilities

Authentication

Methods for setting various authentication schemes.

/**
 * Set authentication credentials
 * @param {string} user - Username or token
 * @param {string} [password] - Password (optional for bearer auth)
 * @param {object} [options] - Authentication options
 * @param {string} [options.type] - Authentication type: 'basic' or 'bearer'
 * @returns {Request} Request instance for chaining
 */
Request.prototype.auth(user, password?, options?): Request;

Usage Examples:

const superagent = require('superagent');

// Basic authentication
superagent
  .get('https://api.example.com/protected')
  .auth('username', 'password');

// Basic auth with colon syntax
superagent
  .get('https://api.example.com/protected')
  .auth('username:password');

// Bearer token authentication
superagent
  .get('https://api.example.com/protected')
  .auth('token123', { type: 'bearer' });

// Equivalent bearer token using header
superagent
  .get('https://api.example.com/protected')
  .set('Authorization', 'Bearer token123');

// Basic auth with only username (empty password)
superagent
  .get('https://api.example.com/protected')
  .auth('username');

TLS/SSL Certificate Configuration

Methods for configuring client certificates and certificate authorities.

/**
 * Set certificate authority (CA) certificate
 * @param {Buffer|Buffer[]|string} cert - CA certificate(s)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.ca(cert): Request;

/**
 * Set client private key
 * @param {Buffer|string} key - Private key
 * @returns {Request} Request instance for chaining
 */
Request.prototype.key(key): Request;

/**
 * Set client certificate
 * @param {Buffer|string} cert - Client certificate
 * @returns {Request} Request instance for chaining
 */
Request.prototype.cert(cert): Request;

/**
 * Set PFX or PKCS12 certificate
 * @param {Buffer|string|object} pfx - PFX certificate or options object
 * @param {Buffer|string} [pfx.pfx] - PFX certificate data
 * @param {string} [pfx.passphrase] - Certificate passphrase
 * @returns {Request} Request instance for chaining
 */
Request.prototype.pfx(pfx): Request;

/**
 * Disable TLS certificate validation (insecure)
 * @returns {Request} Request instance for chaining
 */
Request.prototype.disableTLSCerts(): Request;

Usage Examples:

const fs = require('fs');

// Set CA certificate
const caCert = fs.readFileSync('ca-cert.pem');
superagent
  .get('https://secure.example.com/api')
  .ca(caCert);

// Multiple CA certificates
const caCerts = [
  fs.readFileSync('ca-cert1.pem'),
  fs.readFileSync('ca-cert2.pem')
];
superagent
  .get('https://secure.example.com/api')
  .ca(caCerts);

// Client certificate authentication
const clientKey = fs.readFileSync('client-key.pem');
const clientCert = fs.readFileSync('client-cert.pem');
superagent
  .get('https://secure.example.com/api')
  .key(clientKey)
  .cert(clientCert);

// PFX certificate with passphrase
const pfxData = fs.readFileSync('certificate.p12');
superagent
  .get('https://secure.example.com/api')
  .pfx({
    pfx: pfxData,
    passphrase: 'secret123'
  });

// PFX certificate without passphrase
superagent
  .get('https://secure.example.com/api')
  .pfx(pfxData);

// Disable certificate validation (NOT recommended for production)
superagent
  .get('https://self-signed.example.com/api')
  .disableTLSCerts();

Connection Security

Additional security-related connection options.

/**
 * Enable or disable HTTP/2 for the request (Node.js only)
 * @param {boolean} [enabled=true] - Whether to use HTTP/2
 * @returns {Request} Request instance for chaining
 */
Request.prototype.http2(enabled?): Request;

/**
 * Trust localhost certificates (Node.js only)
 * @param {boolean} [enabled=true] - Whether to trust localhost certificates
 * @returns {Request} Request instance for chaining
 */
Request.prototype.trustLocalhost(enabled?): Request;

/**
 * Override DNS resolution for specific hostnames
 * @param {string|object} override - IP address or hostname mapping object
 * @returns {Request} Request instance for chaining
 */
Request.prototype.connect(override): Request;

Usage Examples:

// Enable HTTP/2 for request
superagent
  .get('https://api.example.com/data')
  .http2();

// Explicitly disable HTTP/2
superagent
  .get('https://api.example.com/data')
  .http2(false);

// Trust localhost certificates for development
superagent
  .get('https://localhost:3000/api')
  .trustLocalhost();

// Don't trust localhost certificates
superagent
  .get('https://localhost:3000/api')
  .trustLocalhost(false);

// Override DNS for specific hostname
superagent
  .get('https://api.example.com/data')
  .connect('127.0.0.1'); // Connect to localhost instead

// Override multiple hostnames
superagent
  .get('https://api.example.com/data')
  .connect({
    'api.example.com': '192.168.1.100',
    'cdn.example.com': '192.168.1.101'
  });

// Wildcard override (all hostnames)
superagent
  .get('https://any-hostname.com/api')
  .connect({ '*': '127.0.0.1' });

Agent Configuration

HTTP agent configuration for connection pooling and security settings.

/**
 * Set HTTP agent for connection pooling
 * @param {http.Agent|https.Agent|boolean} agent - HTTP agent or false to disable
 * @returns {Request} Request instance for chaining
 */
Request.prototype.agent(agent): Request;

/**
 * Set custom DNS lookup function
 * @param {function} lookup - Custom DNS lookup function
 * @returns {Request} Request instance for chaining
 */
Request.prototype.lookup(lookup): Request;

Usage Examples:

const https = require('https');

// Custom HTTPS agent with specific options
const httpsAgent = new https.Agent({
  keepAlive: true,
  maxSockets: 10,
  ca: fs.readFileSync('ca-cert.pem')
});

superagent
  .get('https://api.example.com/data')
  .agent(httpsAgent);

// Disable agent (no connection pooling)
superagent
  .get('https://api.example.com/data')
  .agent(false);

// Custom DNS lookup
const dns = require('dns');
superagent
  .get('https://api.example.com/data')
  .lookup((hostname, options, callback) => {
    // Custom DNS resolution logic
    dns.lookup(hostname, options, callback);
  });

Security Best Practices

Certificate Validation

Always validate certificates in production:

// ✅ Good - validates certificates
superagent.get('https://api.example.com/data');

// ❌ Bad - disables certificate validation
superagent.get('https://api.example.com/data').disableTLSCerts();

Authentication Token Storage

Store authentication tokens securely:

// ✅ Good - using environment variables
const token = process.env.API_TOKEN;
superagent
  .get('https://api.example.com/data')
  .auth(token, { type: 'bearer' });

// ❌ Bad - hardcoded token
superagent
  .get('https://api.example.com/data')
  .auth('hardcoded-token-123', { type: 'bearer' });

HTTPS Usage

Always use HTTPS for sensitive data:

// ✅ Good - HTTPS
superagent.post('https://api.example.com/login').send(credentials);

// ❌ Bad - HTTP for sensitive data
superagent.post('http://api.example.com/login').send(credentials);

Install with Tessl CLI