ssrf-agent-guard 0.1.1 → 0.1.2

package/dist/index.cjs.js

@@ -49,7 +49,7 @@ function isSafeHost(hostname, isValidDomainOptions) {
     // Case 2: Domain name
     return isValidDomain(hostname, {
         allowUnicode: false,
-        subdomain: false,
+        subdomain: true,
         ...isValidDomainOptions,
     });
 }
@@ -80,7 +80,7 @@ const CREATE_CONNECTION = Symbol('createConnection');
  * @param isValidDomainOptions Options for validating domain names.
  * @returns The patched CustomAgent instance.
  */
-function index (url, isValidDomainOptions) {
+const ssrfAgentGuard = function (url, isValidDomainOptions) {
     const finalAgent = getAgent(url);
     // Prevent patching the agent multiple times
     if (finalAgent[CREATE_CONNECTION]) {
@@ -111,7 +111,7 @@ function index (url, isValidDomainOptions) {
             }
             // 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 (!isSafeIp(ipToCheck)) {
+            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.`));
             }
@@ -119,6 +119,7 @@ function index (url, isValidDomainOptions) {
         return client;
     };
     return finalAgent;
-}
+};
+module.exports = ssrfAgentGuard;
 
-exports.default = index;
+exports.default = ssrfAgentGuard;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+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/index.esm.js

@@ -45,7 +45,7 @@ function isSafeHost(hostname, isValidDomainOptions) {
     // Case 2: Domain name
     return isValidDomain(hostname, {
         allowUnicode: false,
-        subdomain: false,
+        subdomain: true,
         ...isValidDomainOptions,
     });
 }
@@ -76,7 +76,7 @@ const CREATE_CONNECTION = Symbol('createConnection');
  * @param isValidDomainOptions Options for validating domain names.
  * @returns The patched CustomAgent instance.
  */
-function index (url, isValidDomainOptions) {
+const ssrfAgentGuard = function (url, isValidDomainOptions) {
     const finalAgent = getAgent(url);
     // Prevent patching the agent multiple times
     if (finalAgent[CREATE_CONNECTION]) {
@@ -107,7 +107,7 @@ function index (url, isValidDomainOptions) {
             }
             // 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 (!isSafeIp(ipToCheck)) {
+            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.`));
             }
@@ -115,6 +115,7 @@ function index (url, isValidDomainOptions) {
         return client;
     };
     return finalAgent;
-}
+};
+module.exports = ssrfAgentGuard;
 
-export { index as default };
+export { ssrfAgentGuard as default };

package/dist/lib/types.d.ts

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,9 @@
+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

@@ -38,7 +38,7 @@ const CREATE_CONNECTION = Symbol('createConnection');
  * @param isValidDomainOptions Options for validating domain names.
  * @returns The patched CustomAgent instance.
  */
-export default function (url: string, isValidDomainOptions?: IsValidDomainOptions): CustomAgent {
+const ssrfAgentGuard = function (url: string, isValidDomainOptions?: IsValidDomainOptions): CustomAgent {
     const finalAgent = getAgent(url);
 
     // Prevent patching the agent multiple times
@@ -79,7 +79,7 @@ export default function (url: string, isValidDomainOptions?: IsValidDomainOption
             // 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 (!isSafeIp(ipToCheck)) {
+            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.`));
             }
@@ -90,3 +90,6 @@ export default function (url: string, isValidDomainOptions?: IsValidDomainOption
 
     return finalAgent;
 }
+
+export default ssrfAgentGuard;
+module.exports = ssrfAgentGuard;

package/lib/utils.ts

@@ -40,7 +40,7 @@ export function isSafeHost(hostname: string, isValidDomainOptions?: IsValidDomai
     // Case 2: Domain name
     return isValidDomain(hostname, {
         allowUnicode: false,
-        subdomain: false,
+        subdomain: true,
         ...isValidDomainOptions,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssrf-agent-guard",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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/tsconfig.json

@@ -3,6 +3,8 @@
     "target": "ES2020",
     "module": "ESNext",
     "declaration": true,
+    "emitDeclarationOnly": false,
+    "declarationDir": "./dist",
     "outDir": "dist",
     "strict": true,
     "esModuleInterop": true,
@@ -10,7 +12,7 @@
     "skipLibCheck": true
   },
   "include": [
-      "lib/**/*",
+    "lib/**/*",
     "rollup.config.mjs"
   ]
 }