feat(validation-kit): introduce HardenedHttpsValidationKit with enhanced documentation and examples

examples/axios.ts

@@ -12,19 +12,21 @@ async function main() {
     maxCachedSessions: 500,
   };
 
-  // Merge standard agent options with hardened defaultss
+  // Merge standard agent options with hardened defaults
   const agent = new HardenedHttpsAgent({
     ...httpsAgentOptions,
     ...defaultAgentOptions(),
+    enableLogging: true, // Enable logging to see the validation process (disabled with defaultAgentOptions())
   });
 
   const client = axios.create({ httpsAgent: agent, timeout: 15000 });
 
   try {
+    console.log('\n> Performing request...');
     await client.get('https://example.com');
-    console.log('\nCongrats! You have successfully performed a more secure request with hardened-https-agent.');
+    console.log('> Congrats! You have successfully performed a more secure request with hardened-https-agent.');
   } catch (error) {
-    console.error('\nAn error occurred while performing the request', error);
+    console.error('> An error occurred while performing the request', error);
   }
 }
 

examples/custom-options.ts

@@ -14,31 +14,35 @@ async function main() {
 
   // Merge standard agent options with hardened defaults and some custom policies
   // Here we use values from the default options, but you can customize them as you want
-  const agent = new HardenedHttpsAgent({
-    ...httpsAgentOptions,
-    ca: embeddedCfsslCaBundle, // or *your custom ca bundle* | useNodeDefaultCABundle()
-    ctPolicy: {
-      logList: embeddedUnifiedCtLogList, // or *your custom log list*
-      minEmbeddedScts: 2,
-      minDistinctOperators: 2,
+  const agent = new HardenedHttpsAgent(
+    {
+      ...httpsAgentOptions,
+      ca: embeddedCfsslCaBundle, // or *your custom ca bundle* | useNodeDefaultCABundle()
+      ctPolicy: {
+        logList: embeddedUnifiedCtLogList, // or *your custom log list*
+        minEmbeddedScts: 2,
+        minDistinctOperators: 2,
+      },
+      ocspPolicy: {
+        mode: 'mixed', // or 'stapling' | 'direct'
+        failHard: true,
+      },
+      crlSetPolicy: {
+        verifySignature: true,
+        updateStrategy: 'always', // or 'on-expiry'
+      },
+      enableLogging: true, // Enable logging to see the validation process (disabled with defaultAgentOptions())
     },
-    ocspPolicy: {
-      mode: 'mixed', // or 'stapling' | 'direct'
-      failHard: true,
-    },
-    crlSetPolicy: {
-      verifySignature: true,
-      updateStrategy: 'always', // or 'on-expiry'
-    },
-    enableLogging: true,
-  });
+    console, // or your own `LogSink` (default is `console`)
+  );
 
   const client = axios.create({ httpsAgent: agent, timeout: 15000 });
   try {
+    console.log('\n> Performing request...');
     await client.get('https://example.com');
-    console.log('\nCongrats! You have successfully performed a more secure request with hardened-https-agent.');
+    console.log('> Congrats! You have successfully performed a more secure request with hardened-https-agent.');
   } catch (error) {
-    console.error('\nAn error occurred while performing the request', error);
+    console.error('> An error occurred while performing the request', error);
   }
 }
 

examples/got.ts

@@ -1,4 +1,3 @@
-
 import got from 'got';
 import { HardenedHttpsAgent, defaultAgentOptions } from '../dist';
 import https from 'node:https';
@@ -17,6 +16,7 @@ async function main() {
   const agent = new HardenedHttpsAgent({
     ...httpsAgentOptions,
     ...defaultAgentOptions(),
+    enableLogging: true, // Enable logging to see the validation process (disabled with defaultAgentOptions())
   });
 
   const client = got.extend({
@@ -26,13 +26,12 @@ async function main() {
   });
 
   try {
+    console.log('\n> Performing request...');
     await client.get('https://example.com');
-    console.log('\nCongrats! You have successfully performed a more secure request with hardened-https-agent.');
+    console.log('> Congrats! You have successfully performed a more secure request with hardened-https-agent.');
   } catch (error) {
-    console.error('\nAn error occurred while performing the request', error);
+    console.error('> An error occurred while performing the request', error);
   }
 }
 
 main();
-
-

examples/https-native.ts

@@ -15,9 +15,11 @@ async function main() {
   const agent = new HardenedHttpsAgent({
     ...httpsAgentOptions,
     ...defaultAgentOptions(),
+    enableLogging: true, // Enable logging to see the validation process (disabled with defaultAgentOptions())
   });
 
   try {
+    console.log('\n> Performing request...');
     await new Promise<void>((resolve, reject) => {
       const req = https.request(
         'https://example.com',
@@ -35,10 +37,9 @@ async function main() {
       req.on('error', reject);
       req.end();
     });
-
-    console.log('\nCongrats! You have successfully performed a more secure request with hardened-https-agent.');
+    console.log('> Congrats! You have successfully performed a more secure request with hardened-https-agent.');
   } catch (error) {
-    console.error('\nAn error occurred while performing the request', error);
+    console.error('> An error occurred while performing the request', error);
   }
 }
 

examples/validation-kit.ts

@@ -0,0 +1,50 @@
+import * as http from 'http';
+import * as https from 'https';
+import { HttpsProxyAgent, HttpsProxyAgentOptions } from 'https-proxy-agent';
+import { HardenedHttpsValidationKit, defaultAgentOptions } from '../dist';
+
+async function main() {
+  // Create a validation kit with hardened defaults
+  const kit = new HardenedHttpsValidationKit({
+    ...defaultAgentOptions(),
+    enableLogging: true,
+  });
+
+  // Define your HTTPS proxy agent options as usual
+  const httpsProxyAgentOpts: HttpsProxyAgentOptions<'https'> = {
+    keepAlive: true,
+  };
+
+  // Create the proxy agent, applying validation kit to options before passing them
+  const agent = new HttpsProxyAgent('http://127.0.0.1:3128', kit.applyBeforeConnect(httpsProxyAgentOpts));
+
+  // Attach the validation kit to the agent
+  kit.attachToAgent(agent as http.Agent);
+
+  try {
+    console.log('\n> Performing request...');
+    await new Promise<void>((resolve, reject) => {
+      const req = https.request(
+        'https://example.com',
+        { method: 'GET', agent: agent as http.Agent, timeout: 15000 },
+        (res) => {
+          const status = res.statusCode ?? 0;
+          if (status >= 200 && status < 300) {
+            resolve();
+          } else {
+            reject(new Error(`Unexpected status ${status}`));
+          }
+          res.resume();
+        },
+      );
+      req.on('error', reject);
+      req.end();
+    });
+
+    console.log('> Congrats! You have successfully performed a more secure request with hardened-https-agent.');
+  } catch (error) {
+    console.error('> An error occurred while performing the request', error);
+  }
+}
+
+main();

package.json

@@ -28,7 +28,7 @@
   },
   "scripts": {
     "test": "jest",
-    "test:e2e": "jest --config jest.config.e2e.js",
+    "test:e2e": "jest --config jest.config.e2e.js --detectOpenHandles",
     "test:update-test-data": "npm run test:fetch-test-certs && npm run test:fetch-log-list && npm run test:fetch-ca-bundle",
     "test:fetch-test-certs": "tsx scripts/fetch-test-certs.ts",
     "test:fetch-log-list": "tsx scripts/fetch-log-list.ts --for-test",
@@ -43,7 +43,8 @@
     "example:axios": "npm run build && tsx examples/axios.ts",
     "example:got": "npm run build && tsx examples/got.ts",
     "example:https-native": "npm run build && tsx examples/https-native.ts",
-    "example:custom-options": "npm run build && tsx examples/custom-options.ts"
+    "example:custom-options": "npm run build && tsx examples/custom-options.ts",
+    "example:validation-kit": "npm run build && tsx examples/validation-kit.ts"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -53,9 +54,12 @@
     "ajv-formats": "^3.0.1",
     "axios": "^1.10.0",
     "got": "^14.4.4",
+    "https-proxy-agent": "^7.0.6",
     "jest": "^30.0.4",
     "json-schema-merge-allof": "^0.8.1",
     "json-schema-to-typescript": "^15.0.4",
+    "node-forge": "^1.3.1",
+    "selfsigned": "^3.0.1",
     "ts-jest": "^29.4.0",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3"