ssrf-agent-guard 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssrf-agent-guard",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A TypeScript SSRF protection library for Node.js (express/axios) with advanced policies, DNS rebinding detection and cloud metadata protection.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/.eslintrc.js

@@ -1,27 +0,0 @@
-module.exports = {
-  root: true,
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaVersion: 2020,
-    sourceType: 'module',
-  },
-  env: {
-    node: true,
-    es2020: true,
-    jest: true,
-  },
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended', // TypeScript rules
-    'plugin:prettier/recommended'           // Integrate Prettier
-  ],
-  plugins: ['@typescript-eslint', 'prettier'],
-  rules: {
-    'prettier/prettier': 'error',          // Show prettier errors as ESLint errors
-    '@typescript-eslint/explicit-function-return-type': 'off',
-    '@typescript-eslint/no-explicit-any': 'off',
-    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-    'no-console': 'warn',
-    'prefer-const': 'error',
-  },
-};

package/.prettierrc

@@ -1,8 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "all",
-  "printWidth": 100,
-  "tabWidth": 4,
-  "endOfLine": "lf"
-}

package/dist/index.d.ts

@@ -1,14 +0,0 @@
-import { Agent as HttpAgent } from 'http';
-import { Agent as HttpsAgent } from 'https';
-import { IsValidDomainOptions } from './lib/types';
-type CustomAgent = HttpAgent | HttpsAgent;
-/**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
- *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
- * @returns The patched CustomAgent instance.
- */
-declare const ssrfAgentGuard: (url: string, isValidDomainOptions?: IsValidDomainOptions) => CustomAgent;
-export default ssrfAgentGuard;

package/dist/lib/types.d.ts

@@ -1,27 +0,0 @@
-export interface Options {
-    protocal?: string;
-    metadataHosts?: string[];
-    mode?: 'block' | 'report' | 'allow';
-    policy?: PolicyOptions;
-    blockCloudMetadata?: boolean;
-    detectDnsRebinding?: boolean;
-    logger?: (level: 'info' | 'warn' | 'error', msg: string, meta?: any) => void;
-}
-export interface PolicyOptions {
-    allowDomains?: string[];
-    denyDomains?: string[];
-    denyTLD?: string[];
-}
-export interface BlockEvent {
-    url: string;
-    reason: string;
-    ip?: string;
-    timestamp: number;
-}
-export interface IsValidDomainOptions {
-    subdomain?: boolean;
-    wildcard?: boolean;
-    allowUnicode?: boolean;
-    topLevel?: boolean;
-}
-export declare const CLOUD_METADATA_HOSTS: string[];

package/dist/lib/utils.d.ts

@@ -1,9 +0,0 @@
-import { IsValidDomainOptions } from './types';
-/**
- * Validates whether a domain is syntactically valid.
- */
-export declare function isSafeIp(hostname: string): boolean;
-/**
- * High-level validation for hostnames (domains + public IPs).
- */
-export declare function isSafeHost(hostname: string, isValidDomainOptions?: IsValidDomainOptions): boolean;

package/index.ts

@@ -1,95 +0,0 @@
-import { Agent as HttpAgent, AgentOptions as HttpAgentOptions } from 'http';
-import { Agent as HttpsAgent, AgentOptions as HttpsAgentOptions } from 'https';
-import { Duplex } from 'stream';
-
-import { isSafeHost, isSafeIp } from './lib/utils';
-import { IsValidDomainOptions } from './lib/types';
-
-// Define the type for the Agent that this module will modify and return.
-// It can be either an HttpAgent or an HttpsAgent.
-type CustomAgent = HttpAgent | HttpsAgent;
-
-// Instantiate the default agents
-const httpAgent = new HttpAgent();
-const httpsAgent = new HttpsAgent();
-
-/**
- * Determines the correct Agent instance based on the input.
- * @param url The URL or another input to determine the agent type.
- * @returns The appropriate HttpAgent or HttpsAgent instance.
- */
-const getAgent = (url: string): CustomAgent => {
-    // If it's a string, check if it implies HTTPS
-    if (typeof url === 'string' && url.startsWith('https')) {
-        return httpsAgent;
-    }
-    // Default to HTTP agent
-    return httpAgent;
-};
-
-// Define a Symbol for a unique property to prevent double-patching the agent.
-const CREATE_CONNECTION = Symbol('createConnection');
-
-/**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
- *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
- * @returns The patched CustomAgent instance.
- */
-const ssrfAgentGuard = function (url: string, isValidDomainOptions?: IsValidDomainOptions): CustomAgent {
-    const finalAgent = getAgent(url);
-
-    // Prevent patching the agent multiple times
-    if ((finalAgent as any)[CREATE_CONNECTION]) {
-        return finalAgent;
-    }
-    (finalAgent as any)[CREATE_CONNECTION] = true;
-
-    // The original createConnection function from the Agent
-    const createConnection = finalAgent.createConnection;
-
-    // Patch the createConnection method on the agent
-    finalAgent.createConnection =  (
-        options: HttpAgentOptions | HttpsAgentOptions,
-        fn?: (err: Error | null, stream: Duplex) => void,
-    ) => {
-        const { host: address } = options;
-        // --- 1. Pre-DNS Check (Host/Address Check) ---
-        // If the 'host' option is an IP address, check it immediately.
-        // If it's a hostname, this check will usually pass (via defaultIpChecker).
-        if (address && !isSafeHost(address, isValidDomainOptions)) {
-            throw new Error(`DNS lookup ${address} is not allowed.`);
-        }
-
-        // Call the original createConnection
-        // @ts-expect-error 'this' is not assignable to type 'HttpAgent | HttpsAgent'
-        const client = createConnection.call(this, options, fn);
-
-        // --- 2. Post-DNS Check (Lookup Event Check) ---
-        // The 'lookup' event fires after the DNS lookup is complete
-        // and provides the resolved IP address.
-        client?.on('lookup', (err: Error | null, resolvedAddress: string | string[]) => {
-            // If there was an error in lookup, or if the resolved IP is allowed, do nothing.
-            if (err) {
-                return;
-            }
-
-            // Ensure resolvedAddress is a string for the check (it's typically a string for simple lookups)
-            const ipToCheck = Array.isArray(resolvedAddress) ? resolvedAddress[0] : resolvedAddress;
-
-            if (!isSafeHost(ipToCheck)) {
-                // If the resolved IP is NOT allowed (e.g., a private IP), destroy the connection.
-                return client?.destroy(new Error(`DNS lookup ${ipToCheck} is not allowed.`));
-            }
-        });
-
-        return client;
-    };
-
-    return finalAgent;
-}
-
-export default ssrfAgentGuard;
-module.exports = ssrfAgentGuard;

package/lib/types.ts

@@ -1,37 +0,0 @@
-// lib/types.ts
-export interface Options {
-    protocal?: string;
-    metadataHosts?: string[];
-    mode?: 'block' | 'report' | 'allow';
-    policy?: PolicyOptions;
-    blockCloudMetadata?: boolean;
-    detectDnsRebinding?: boolean;
-    logger?: (level: 'info' | 'warn' | 'error', msg: string, meta?: any) => void;
-}
-
-export interface PolicyOptions {
-    allowDomains?: string[];
-    denyDomains?: string[];
-    denyTLD?: string[];
-}
-
-export interface BlockEvent {
-    url: string;
-    reason: string;
-    ip?: string;
-    timestamp: number;
-}
-
-export interface IsValidDomainOptions {
-    subdomain?: boolean;
-    wildcard?: boolean;
-    allowUnicode?: boolean;
-    topLevel?: boolean;
-}
-
-export const CLOUD_METADATA_HOSTS: string[] = [
-    '169.254.169.254',
-    '169.254.169.253',
-    'metadata.google.internal',
-    '169.254.170.2',
-];

package/lib/utils.ts

@@ -1,46 +0,0 @@
-// lib/utils.ts
-import isValidDomain from 'is-valid-domain';
-import ipaddr from 'ipaddr.js';
-import { IsValidDomainOptions, CLOUD_METADATA_HOSTS } from './types';
-
-/**
- * Checks if the input is an IP address (v4/v6).
- */
-function isIp(input: string): boolean {
-    return ipaddr.isValid(input);
-}
-
-/**
- * Returns true for valid public unicast IP addresses.
- */
-function isPublicIp(ip: string): boolean {
-    return ipaddr.parse(ip).range() === 'unicast';
-}
-
-/**
- * Validates whether a domain is syntactically valid.
- */
-export function isSafeIp(hostname: string): boolean {
-    // Case 1: IP address
-    if (isIp(hostname)) {
-        return isPublicIp(hostname); // only allow public IPs
-    }
-    return true;
-}
-
-/**
- * High-level validation for hostnames (domains + public IPs).
- */
-export function isSafeHost(hostname: string, isValidDomainOptions?: IsValidDomainOptions): boolean {
-    // Block cloud metadata IP/domains
-    if (CLOUD_METADATA_HOSTS.indexOf(hostname)) return false;
-
-    if (!isSafeIp(hostname)) return false;
-
-    // Case 2: Domain name
-    return isValidDomain(hostname, {
-        allowUnicode: false,
-        subdomain: true,
-        ...isValidDomainOptions,
-    });
-}

package/rollup.config.mjs

@@ -1,10 +0,0 @@
-import typescript from 'rollup-plugin-typescript2';
-
-export default {
-    input: 'index.ts',
-    output: [
-        { file: 'dist/index.esm.js', format: 'es' },
-        { file: 'dist/index.cjs.js', format: 'cjs', exports: 'named' },
-    ],
-    plugins: [typescript({ useTsconfigDeclarationDir: true })],
-};

package/test/index.test.ts

@@ -1,63 +0,0 @@
-describe('SSRF Agent Guard', () => {
-    describe('Agent Selection', () => {
-        it('should return HttpsAgent for HTTPS URLs', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should return HttpAgent for HTTP URLs', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should return HttpAgent by default for non-HTTPS URLs', () => {
-            expect(true).toBe(true);
-        });
-    });
-
-    describe('Pre-DNS Validation', () => {
-        it('should throw error if host is not safe', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should not throw if host is safe', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should pass options to isSafeHost', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should handle missing host option', () => {
-            expect(true).toBe(true);
-        });
-    });
-
-    describe('Post-DNS Validation', () => {
-        it('should destroy connection if resolved IP is not safe', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should not destroy connection if resolved IP is safe', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should handle array of resolved addresses', () => {
-            expect(true).toBe(true);
-        });
-
-        it('should ignore lookup errors', () => {
-            expect(true).toBe(true);
-        });
-    });
-
-    describe('Patch Prevention', () => {
-        it('should not patch agent multiple times', () => {
-            expect(true).toBe(true);
-        });
-    });
-
-    describe('Callback Handling', () => {
-        it('should call provided callback with client', () => {
-            expect(true).toBe(true);
-        });
-    });
-});

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "declaration": true,
-    "emitDeclarationOnly": false,
-    "declarationDir": "./dist",
-    "outDir": "dist",
-    "strict": true,
-    "esModuleInterop": true,
-    "moduleResolution": "node",
-    "skipLibCheck": true
-  },
-  "include": [
-    "lib/**/*",
-    "rollup.config.mjs"
-  ]
-}