API Reference

/**
 * URLSheriff class for validating URLs and preventing SSRF attacks
 */
class URLSheriff {
  /**
   * Creates a new URLSheriff instance
   * @param config - Optional configuration object
   */
  constructor(config?: URLSheriffConfig);

  /**
   * Validates if a URL is safe to use
   * @param url - URL string or URL object to validate
   * @returns Promise resolving to true if URL is safe
   * @throws Error if URL is invalid, uses disallowed scheme, or resolves to private IP
   */
  isSafeURL(url: string | URL): Promise<boolean>;

  /**
   * Checks if an IP address is private or internal
   * @param ipAddress - IP address string (IPv4 or IPv6)
   * @returns true if IP address is private, false if public
   */
  isPrivateIPAddress(ipAddress: string): boolean;

  /**
   * Performs DNS lookup using system resolver
   * @param hostname - Hostname to resolve
   * @returns Promise resolving to array of IP addresses (both IPv4 and IPv6)
   * @throws Error if DNS lookup fails
   */
  hostnameLookup(hostname: string): Promise<string[]>;

  /**
   * Performs DNS lookup using custom resolvers configured in constructor
   * @param hostname - Hostname to resolve
   * @returns Promise resolving to array of IPv4 addresses only
   * @throws Error if custom resolver not configured or DNS lookup fails
   */
  resolveHostnameViaServers(hostname: string): Promise<string[]>;

  /**
   * Adds entries to the allow-list at runtime
   * @param entries - Array of string literals or RegExp patterns to add
   * @returns void
   */
  addToAllowList(entries: Array<string | RegExp>): void;

  /**
   * Removes entries from the allow-list at runtime
   * @param entries - Array of string literals or RegExp patterns to remove
   * @returns void
   * @note Removing non-existent entries is safe and silently ignored
   */
  removeFromAllowList(entries: Array<string | RegExp>): void;

  /**
   * Gets the current allow-list entries
   * @returns Copy of current allow-list array
   */
  getAllowList(): Array<string | RegExp>;

  /**
   * Sets allowed URL schemes/protocols
   * @param schemes - Array of allowed scheme strings (e.g., ['http', 'https'])
   * @returns Normalized schemes array or null if empty array provided (which clears restrictions)
   */
  setAllowedSchemes(schemes: string[]): string[] | null;

  /**
   * Gets current allowed URL schemes
   * @returns Copy of allowed schemes array or null if no restrictions
   */
  getAllowedSchemes(): string[] | null;

  /**
   * Removes all scheme restrictions, allowing any protocol
   * @returns void
   */
  clearSchemeRestrictions(): void;
}

const sheriff = new URLSheriff();
const sheriffWithConfig = new URLSheriff({
  allowedSchemes: ['https'],
  allowList: ['localhost']
});

try {
  await sheriff.isSafeURL('https://example.com'); // Returns true
} catch (error) {
  console.error('Unsafe URL:', error.message);
}

sheriff.isPrivateIPAddress('192.168.1.1'); // true
sheriff.isPrivateIPAddress('8.8.8.8');     // false

const ips = await sheriff.hostnameLookup('example.com');
// ['93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946']

const sheriff = new URLSheriff({
  dnsResolvers: ['1.1.1.1']
});
const ips = await sheriff.resolveHostnameViaServers('example.com');
// ['93.184.216.34']

sheriff.addToAllowList(['localhost', /^.*\.internal\.com$/]);

sheriff.removeFromAllowList(['localhost']);

const allowList = sheriff.getAllowList();
console.log(allowList); // ['localhost', /^.*\.internal\.com$/]

sheriff.setAllowedSchemes(['https', 'http']);
// Returns ['https', 'http']

sheriff.setAllowedSchemes([]);
// Returns null, clears restrictions

const schemes = sheriff.getAllowedSchemes();
// ['https', 'http'] or null

sheriff.clearSchemeRestrictions();
// Now all schemes are allowed