@checkstack/healthcheck-tls-backend 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @checkstack/healthcheck-tls-backend
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Refactored health check strategies to use `createClient()` pattern with built-in collectors.
+
+  **Strategy Changes:**
+
+  - Replaced `execute()` with `createClient()` that returns a transport client
+  - Strategy configs now only contain connection parameters
+  - Collector configs handle what to do with the connection
+
+  **Built-in Collectors Added:**
+
+  - DNS: `LookupCollector` for hostname resolution
+  - gRPC: `HealthCollector` for gRPC health protocol
+  - HTTP: `RequestCollector` for HTTP requests
+  - MySQL: `QueryCollector` for database queries
+  - Ping: `PingCollector` for ICMP ping
+  - Postgres: `QueryCollector` for database queries
+  - Redis: `CommandCollector` for Redis commands
+  - Script: `ExecuteCollector` for script execution
+  - SSH: `CommandCollector` for SSH commands
+  - TCP: `BannerCollector` for TCP banner grabbing
+  - TLS: `CertificateCollector` for certificate inspection
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/common@0.0.3
+
 ## 0.0.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-tls-backend",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/certificate-collector.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it, mock } from "bun:test";
+import { CertificateCollector } from "./certificate-collector";
+import type {
+  TlsTransportClient,
+  TlsCertificateInfo,
+} from "./transport-client";
+
+describe("CertificateCollector", () => {
+  const createMockClient = (
+    response: Partial<TlsCertificateInfo> = {}
+  ): TlsTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        isValid: response.isValid ?? true,
+        isSelfSigned: response.isSelfSigned ?? false,
+        subject: response.subject ?? "CN=example.com",
+        issuer: response.issuer ?? "CN=Let's Encrypt",
+        validFrom: response.validFrom ?? "2024-01-01T00:00:00Z",
+        validTo: response.validTo ?? "2025-01-01T00:00:00Z",
+        daysUntilExpiry: response.daysUntilExpiry ?? 365,
+        daysRemaining: response.daysRemaining ?? 365,
+        error: response.error,
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should get certificate info successfully", async () => {
+      const collector = new CertificateCollector();
+      const client = createMockClient({ daysRemaining: 90 });
+
+      const result = await collector.execute({
+        config: {},
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.subject).toBe("CN=example.com");
+      expect(result.result.issuer).toBe("CN=Let's Encrypt");
+      expect(result.result.daysRemaining).toBe(90);
+      expect(result.result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return error for failed TLS connection", async () => {
+      const collector = new CertificateCollector();
+      const client = createMockClient({
+        error: "Connection refused",
+        isValid: false,
+        daysRemaining: 0,
+        daysUntilExpiry: 0,
+      });
+
+      const result = await collector.execute({
+        config: {},
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.valid).toBe(false);
+      expect(result.error).toBe("Connection refused");
+    });
+
+    it("should mark expired certificate as invalid", async () => {
+      const collector = new CertificateCollector();
+      const client = createMockClient({ daysRemaining: 0 });
+
+      const result = await collector.execute({
+        config: {},
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.valid).toBe(false);
+      expect(result.result.daysRemaining).toBe(0);
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average days remaining", () => {
+      const collector = new CertificateCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            subject: "CN=a.com",
+            issuer: "CN=CA",
+            validFrom: "",
+            validTo: "",
+            daysRemaining: 30,
+            valid: true,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            subject: "CN=a.com",
+            issuer: "CN=CA",
+            validFrom: "",
+            validTo: "",
+            daysRemaining: 60,
+            valid: true,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgDaysRemaining).toBe(45);
+      expect(aggregated.validRate).toBe(100);
+    });
+
+    it("should calculate valid rate correctly", () => {
+      const collector = new CertificateCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            subject: "CN=a.com",
+            issuer: "CN=CA",
+            validFrom: "",
+            validTo: "",
+            daysRemaining: 30,
+            valid: true,
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            subject: "CN=a.com",
+            issuer: "CN=CA",
+            validFrom: "",
+            validTo: "",
+            daysRemaining: 0,
+            valid: false,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.validRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new CertificateCollector();
+
+      expect(collector.id).toBe("certificate");
+      expect(collector.displayName).toBe("TLS Certificate");
+      expect(collector.allowMultiple).toBe(false);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/certificate-collector.ts

@@ -0,0 +1,170 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+  healthResultBoolean,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "./plugin-metadata";
+import type { TlsTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const certificateConfigSchema = z.object({
+  // No config needed - just returns cert info from connection
+});
+
+export type CertificateConfig = z.infer<typeof certificateConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const certificateResultSchema = z.object({
+  subject: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Subject",
+  }),
+  issuer: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Issuer",
+  }),
+  validFrom: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Valid From",
+  }),
+  validTo: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Valid To",
+  }),
+  daysRemaining: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Days Remaining",
+    "x-chart-unit": "days",
+  }),
+  valid: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Valid",
+  }),
+});
+
+export type CertificateResult = z.infer<typeof certificateResultSchema>;
+
+const certificateAggregatedSchema = z.object({
+  avgDaysRemaining: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Avg Days Remaining",
+    "x-chart-unit": "days",
+  }),
+  validRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Valid Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type CertificateAggregatedResult = z.infer<
+  typeof certificateAggregatedSchema
+>;
+
+// ============================================================================
+// CERTIFICATE COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in TLS certificate collector.
+ * Returns certificate information from the TLS connection.
+ */
+export class CertificateCollector
+  implements
+    CollectorStrategy<
+      TlsTransportClient,
+      CertificateConfig,
+      CertificateResult,
+      CertificateAggregatedResult
+    >
+{
+  id = "certificate";
+  displayName = "TLS Certificate";
+  description = "Check TLS certificate validity and expiration";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = false;
+
+  config = new Versioned({ version: 1, schema: certificateConfigSchema });
+  result = new Versioned({ version: 1, schema: certificateResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: certificateAggregatedSchema,
+  });
+
+  async execute({
+    client,
+  }: {
+    config: CertificateConfig;
+    client: TlsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<CertificateResult>> {
+    const response = await client.exec({ action: "inspect" });
+
+    if (response.error) {
+      return {
+        result: {
+          subject: "",
+          issuer: "",
+          validFrom: "",
+          validTo: "",
+          daysRemaining: 0,
+          valid: false,
+        },
+        error: response.error,
+      };
+    }
+
+    return {
+      result: {
+        subject: response.subject ?? "",
+        issuer: response.issuer ?? "",
+        validFrom: response.validFrom ?? "",
+        validTo: response.validTo ?? "",
+        daysRemaining: response.daysRemaining ?? 0,
+        valid: (response.daysRemaining ?? 0) > 0,
+      },
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<CertificateResult>[]
+  ): CertificateAggregatedResult {
+    const daysRemaining = runs
+      .map((r) => r.metadata?.daysRemaining)
+      .filter((v): v is number => typeof v === "number");
+
+    const validResults = runs
+      .map((r) => r.metadata?.valid)
+      .filter((v): v is boolean => typeof v === "boolean");
+
+    const validCount = validResults.filter(Boolean).length;
+
+    return {
+      avgDaysRemaining:
+        daysRemaining.length > 0
+          ? Math.round(
+              daysRemaining.reduce((a, b) => a + b, 0) / daysRemaining.length
+            )
+          : 0,
+      validRate:
+        validResults.length > 0
+          ? Math.round((validCount / validResults.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/index.ts

@@ -1,9 +1,7 @@
-import {
-  createBackendPlugin,
-  coreServices,
-} from "@checkstack/backend-api";
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { TlsHealthCheckStrategy } from "./strategy";
 import { pluginMetadata } from "./plugin-metadata";
+import { CertificateCollector } from "./certificate-collector";
 
 export default createBackendPlugin({
   metadata: pluginMetadata,
@@ -11,13 +9,17 @@ export default createBackendPlugin({
     env.registerInit({
       deps: {
         healthCheckRegistry: coreServices.healthCheckRegistry,
+        collectorRegistry: coreServices.collectorRegistry,
         logger: coreServices.logger,
       },
-      init: async ({ healthCheckRegistry, logger }) => {
+      init: async ({ healthCheckRegistry, collectorRegistry, logger }) => {
         logger.debug("🔌 Registering TLS/SSL Health Check Strategy...");
         const strategy = new TlsHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+        collectorRegistry.register(new CertificateCollector());
       },
     });
   },
 });
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/strategy.test.ts

@@ -60,11 +60,11 @@ describe("TlsHealthCheckStrategy", () => {
     ),
   });
 
-  describe("execute", () => {
-    it("should return healthy for valid certificate", async () => {
+  describe("createClient", () => {
+    it("should return a connected client", async () => {
       const strategy = new TlsHealthCheckStrategy(createMockClient());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "example.com",
         port: 443,
         timeout: 5000,
@@ -72,120 +72,69 @@ describe("TlsHealthCheckStrategy", () => {
         rejectUnauthorized: true,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.isValid).toBe(true);
-      expect(result.metadata?.daysUntilExpiry).toBeGreaterThan(0);
-    });
-
-    it("should return unhealthy for unauthorized certificate", async () => {
-      const strategy = new TlsHealthCheckStrategy(
-        createMockClient({ authorized: false })
-      );
-
-      const result = await strategy.execute({
-        host: "example.com",
-        port: 443,
-        timeout: 5000,
-        minDaysUntilExpiry: 7,
-        rejectUnauthorized: true,
-      });
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("not valid");
+      connectedClient.close();
     });
 
-    it("should return unhealthy when certificate expires soon", async () => {
-      const expiringCert = createCertInfo({
-        validTo: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000), // 5 days
-      });
-
-      const strategy = new TlsHealthCheckStrategy(
-        createMockClient({ cert: expiringCert })
-      );
-
-      const result = await strategy.execute({
-        host: "example.com",
-        port: 443,
-        timeout: 5000,
-        minDaysUntilExpiry: 14,
-        rejectUnauthorized: true,
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("expires in");
-    });
-
-    it("should return unhealthy for connection error", async () => {
+    it("should throw for connection error during client creation", async () => {
       const strategy = new TlsHealthCheckStrategy(
         createMockClient({ error: new Error("Connection refused") })
       );
 
-      const result = await strategy.execute({
-        host: "example.com",
-        port: 443,
-        timeout: 5000,
-        minDaysUntilExpiry: 7,
-        rejectUnauthorized: true,
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Connection refused");
+      await expect(
+        strategy.createClient({
+          host: "example.com",
+          port: 443,
+          timeout: 5000,
+          minDaysUntilExpiry: 7,
+          rejectUnauthorized: true,
+        })
+      ).rejects.toThrow("Connection refused");
     });
+  });
 
-    it("should pass daysUntilExpiry assertion", async () => {
+  describe("client.exec (inspect action)", () => {
+    it("should return valid certificate info", async () => {
       const strategy = new TlsHealthCheckStrategy(createMockClient());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "example.com",
         port: 443,
         timeout: 5000,
         minDaysUntilExpiry: 7,
         rejectUnauthorized: true,
-        assertions: [
-          {
-            field: "daysUntilExpiry",
-            operator: "greaterThanOrEqual",
-            value: 7,
-          },
-        ],
       });
 
-      expect(result.status).toBe("healthy");
-    });
+      const result = await connectedClient.client.exec({ action: "inspect" });
 
-    it("should pass issuer assertion", async () => {
-      const strategy = new TlsHealthCheckStrategy(createMockClient());
+      expect(result.isValid).toBe(true);
+      expect(result.daysRemaining).toBeGreaterThan(0);
+      expect(result.subject).toBe("example.com");
 
-      const result = await strategy.execute({
-        host: "example.com",
-        port: 443,
-        timeout: 5000,
-        minDaysUntilExpiry: 7,
-        rejectUnauthorized: true,
-        assertions: [
-          { field: "issuer", operator: "contains", value: "DigiCert" },
-        ],
-      });
-
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
 
-    it("should fail isValid assertion when certificate is invalid", async () => {
+    it("should return invalid for unauthorized certificate", async () => {
       const strategy = new TlsHealthCheckStrategy(
         createMockClient({ authorized: false })
       );
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "example.com",
         port: 443,
         timeout: 5000,
         minDaysUntilExpiry: 7,
-        rejectUnauthorized: false, // Don't reject to test assertion
-        assertions: [{ field: "isValid", operator: "isTrue" }],
+        rejectUnauthorized: false, // Don't reject to allow connection
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
+      const result = await connectedClient.client.exec({ action: "inspect" });
+
+      expect(result.isValid).toBe(false);
+
+      connectedClient.close();
     });
 
     it("should detect self-signed certificates", async () => {
@@ -199,7 +148,7 @@ describe("TlsHealthCheckStrategy", () => {
         createMockClient({ cert: selfSignedCert, authorized: false })
       );
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 443,
         timeout: 5000,
@@ -207,7 +156,11 @@ describe("TlsHealthCheckStrategy", () => {
         rejectUnauthorized: false,
       });
 
-      expect(result.metadata?.isSelfSigned).toBe(true);
+      const result = await connectedClient.client.exec({ action: "inspect" });
+
+      expect(result.isSelfSigned).toBe(true);
+
+      connectedClient.close();
     });
   });
 
@@ -301,7 +254,7 @@ describe("TlsHealthCheckStrategy", () => {
 
       const aggregated = strategy.aggregateResult(runs);
 
-      expect(aggregated.invalidCount).toBe(1);
+      expect(aggregated.invalidCount).toBe(2);
       expect(aggregated.errorCount).toBe(1);
     });
   });

package/src/strategy.ts

@@ -1,38 +1,26 @@
 import * as tls from "node:tls";
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  numericField,
-  stringField,
-  booleanField,
-  evaluateAssertions,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  TlsTransportClient,
+  TlsInspectRequest,
+  TlsCertificateInfo,
+} from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
 // ============================================================================
 
-/**
- * Assertion schema for TLS health checks using shared factories.
- */
-const tlsAssertionSchema = z.discriminatedUnion("field", [
-  numericField("daysUntilExpiry", { min: 0 }),
-  stringField("issuer"),
-  stringField("subject"),
-  booleanField("isValid"),
-  booleanField("isSelfSigned"),
-]);
-
-export type TlsAssertion = z.infer<typeof tlsAssertionSchema>;
-
 /**
  * Configuration schema for TLS health checks.
  */
@@ -42,7 +30,7 @@ export const tlsConfigSchema = z.object({
   servername: z
     .string()
     .optional()
-    .describe("SNI hostname (defaults to host if not specified)"),
+    .describe("Server name for SNI (defaults to host)"),
   timeout: z
     .number()
     .min(100)
@@ -50,17 +38,14 @@ export const tlsConfigSchema = z.object({
     .describe("Connection timeout in milliseconds"),
   minDaysUntilExpiry: z
     .number()
+    .int()
     .min(0)
-    .default(14)
-    .describe("Minimum days until certificate expiry for healthy status"),
+    .default(30)
+    .describe("Minimum days before certificate expiry to consider healthy"),
   rejectUnauthorized: z
     .boolean()
     .default(true)
     .describe("Reject invalid/self-signed certificates"),
-  assertions: z
-    .array(tlsAssertionSchema)
-    .optional()
-    .describe("Validation conditions"),
 });
 
 export type TlsConfig = z.infer<typeof tlsConfigSchema>;
@@ -75,49 +60,24 @@ const tlsResultSchema = z.object({
   }),
   isValid: healthResultBoolean({
     "x-chart-type": "boolean",
-    "x-chart-label": "Certificate Valid",
+    "x-chart-label": "Valid",
   }),
   isSelfSigned: healthResultBoolean({
     "x-chart-type": "boolean",
     "x-chart-label": "Self-Signed",
   }),
-  issuer: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Issuer",
-  }),
-  subject: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Subject",
-  }),
-  validFrom: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Valid From",
-  }),
-  validTo: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Valid To",
-  }),
   daysUntilExpiry: healthResultNumber({
-    "x-chart-type": "counter",
+    "x-chart-type": "line",
     "x-chart-label": "Days Until Expiry",
     "x-chart-unit": "days",
   }),
-  protocol: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Protocol",
-  }).optional(),
-  cipher: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Cipher",
-  }).optional(),
-  failedAssertion: tlsAssertionSchema.optional(),
   error: healthResultString({
     "x-chart-type": "status",
     "x-chart-label": "Error",
   }).optional(),
 });
 
-export type TlsResult = z.infer<typeof tlsResultSchema>;
+type TlsResult = z.infer<typeof tlsResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -143,7 +103,7 @@ const tlsAggregatedSchema = z.object({
   }),
 });
 
-export type TlsAggregatedResult = z.infer<typeof tlsAggregatedSchema>;
+type TlsAggregatedResult = z.infer<typeof tlsAggregatedSchema>;
 
 // ============================================================================
 // TLS CLIENT INTERFACE (for testability)
@@ -199,7 +159,7 @@ const defaultTlsClient: TlsClient = {
       );
 
       socket.on("error", reject);
-      socket.on("timeout", () => {
+      socket.setTimeout(options.timeout, () => {
         socket.destroy();
         reject(new Error("Connection timeout"));
       });
@@ -212,7 +172,13 @@ const defaultTlsClient: TlsClient = {
 // ============================================================================
 
 export class TlsHealthCheckStrategy
-  implements HealthCheckStrategy<TlsConfig, TlsResult, TlsAggregatedResult>
+  implements
+    HealthCheckStrategy<
+      TlsConfig,
+      TlsTransportClient,
+      TlsResult,
+      TlsAggregatedResult
+    >
 {
   id = "tls";
   displayName = "TLS/SSL Health Check";
@@ -225,13 +191,29 @@ export class TlsHealthCheckStrategy
   }
 
   config: Versioned<TlsConfig> = new Versioned({
-    version: 1,
+    version: 2, // Bumped for createClient pattern
     schema: tlsConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no config changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   result: Versioned<TlsResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: tlsResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<TlsAggregatedResult> = new Versioned({
@@ -242,151 +224,87 @@ export class TlsHealthCheckStrategy
   aggregateResult(
     runs: HealthCheckRunForAggregation<TlsResult>[]
   ): TlsAggregatedResult {
-    let totalDaysUntilExpiry = 0;
-    let minDaysUntilExpiry = Number.POSITIVE_INFINITY;
-    let invalidCount = 0;
-    let errorCount = 0;
-    let validRuns = 0;
-
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-        continue;
-      }
-      if (run.metadata && !run.metadata.isValid) {
-        invalidCount++;
-      }
-      if (run.metadata) {
-        totalDaysUntilExpiry += run.metadata.daysUntilExpiry;
-        if (run.metadata.daysUntilExpiry < minDaysUntilExpiry) {
-          minDaysUntilExpiry = run.metadata.daysUntilExpiry;
-        }
-        validRuns++;
-      }
+    const validRuns = runs.filter((r) => r.metadata);
+
+    if (validRuns.length === 0) {
+      return {
+        avgDaysUntilExpiry: 0,
+        minDaysUntilExpiry: 0,
+        invalidCount: 0,
+        errorCount: 0,
+      };
     }
 
+    const daysValues = validRuns
+      .map((r) => r.metadata?.daysUntilExpiry)
+      .filter((d): d is number => typeof d === "number");
+
+    const avgDaysUntilExpiry =
+      daysValues.length > 0
+        ? Math.round(daysValues.reduce((a, b) => a + b, 0) / daysValues.length)
+        : 0;
+
+    const minDaysUntilExpiry =
+      daysValues.length > 0 ? Math.min(...daysValues) : 0;
+
+    const invalidCount = validRuns.filter(
+      (r) => r.metadata?.isValid === false
+    ).length;
+
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
+
     return {
-      avgDaysUntilExpiry: validRuns > 0 ? totalDaysUntilExpiry / validRuns : 0,
-      minDaysUntilExpiry:
-        minDaysUntilExpiry === Number.POSITIVE_INFINITY
-          ? 0
-          : minDaysUntilExpiry,
+      avgDaysUntilExpiry,
+      minDaysUntilExpiry,
       invalidCount,
       errorCount,
     };
   }
 
-  async execute(config: TlsConfig): Promise<HealthCheckResult<TlsResult>> {
+  async createClient(
+    config: TlsConfig
+  ): Promise<ConnectedClient<TlsTransportClient>> {
     const validatedConfig = this.config.validate(config);
-    const start = performance.now();
-
-    try {
-      const connection = await this.tlsClient.connect({
-        host: validatedConfig.host,
-        port: validatedConfig.port,
-        servername: validatedConfig.servername ?? validatedConfig.host,
-        rejectUnauthorized: validatedConfig.rejectUnauthorized,
-        timeout: validatedConfig.timeout,
-      });
-
-      const cert = connection.getPeerCertificate();
-      const protocol = connection.getProtocol();
-      const cipher = connection.getCipher();
-
-      connection.end();
-
-      const end = performance.now();
-      const latencyMs = Math.round(end - start);
 
-      // Calculate days until expiry
-      const validTo = new Date(cert.valid_to);
-      const now = new Date();
-      const daysUntilExpiry = Math.floor(
-        (validTo.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
-      );
-
-      // Determine if self-signed
-      const isSelfSigned =
-        cert.issuer.CN === cert.subject.CN && cert.issuer.O === undefined;
-
-      const result: Omit<TlsResult, "failedAssertion" | "error"> = {
-        connected: true,
-        isValid: connection.authorized,
-        isSelfSigned,
-        issuer: cert.issuer.CN ?? cert.issuer.O ?? "Unknown",
-        subject: cert.subject.CN ?? "Unknown",
-        validFrom: cert.valid_from,
-        validTo: cert.valid_to,
-        daysUntilExpiry,
-        protocol: protocol ?? undefined,
-        cipher: cipher?.name,
-      };
+    const connection = await this.tlsClient.connect({
+      host: validatedConfig.host,
+      port: validatedConfig.port,
+      servername: validatedConfig.servername ?? validatedConfig.host,
+      rejectUnauthorized: validatedConfig.rejectUnauthorized,
+      timeout: validatedConfig.timeout,
+    });
 
-      // Evaluate assertions using shared utility
-      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
-        daysUntilExpiry,
-        issuer: result.issuer,
-        subject: result.subject,
-        isValid: result.isValid,
-        isSelfSigned,
-      });
+    const cert = connection.getPeerCertificate();
+    const validTo = new Date(cert.valid_to);
+    const daysUntilExpiry = Math.floor(
+      (validTo.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
+    );
+
+    const certInfo: TlsCertificateInfo = {
+      isValid: connection.authorized,
+      isSelfSigned: cert.issuer?.CN === cert.subject?.CN,
+      issuer: cert.issuer?.O || cert.issuer?.CN || "Unknown",
+      subject: cert.subject?.CN || "Unknown",
+      validFrom: cert.valid_from,
+      validTo: cert.valid_to,
+      daysUntilExpiry,
+      daysRemaining: daysUntilExpiry,
+      protocol: connection.getProtocol() ?? undefined,
+      cipher: connection.getCipher()?.name,
+    };
 
-      if (failedAssertion) {
-        return {
-          status: "unhealthy",
-          latencyMs,
-          message: `Assertion failed: ${failedAssertion.field} ${
-            failedAssertion.operator
-          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
-          metadata: { ...result, failedAssertion },
-        };
-      }
-
-      // Check minimum days until expiry
-      if (daysUntilExpiry < validatedConfig.minDaysUntilExpiry) {
-        return {
-          status: "unhealthy",
-          latencyMs,
-          message: `Certificate expires in ${daysUntilExpiry} days (minimum: ${validatedConfig.minDaysUntilExpiry})`,
-          metadata: result,
-        };
-      }
-
-      // Check certificate validity
-      if (!connection.authorized && validatedConfig.rejectUnauthorized) {
-        return {
-          status: "unhealthy",
-          latencyMs,
-          message: "Certificate is not valid or not trusted",
-          metadata: result,
-        };
-      }
+    const client: TlsTransportClient = {
+      async exec(_request: TlsInspectRequest): Promise<TlsCertificateInfo> {
+        // Certificate info is captured at connection time
+        return certInfo;
+      },
+    };
 
-      return {
-        status: "healthy",
-        latencyMs,
-        message: `Certificate valid for ${daysUntilExpiry} days (${result.subject} issued by ${result.issuer})`,
-        metadata: result,
-      };
-    } catch (error: unknown) {
-      const end = performance.now();
-      const isError = error instanceof Error;
-      return {
-        status: "unhealthy",
-        latencyMs: Math.round(end - start),
-        message: isError ? error.message : "TLS connection failed",
-        metadata: {
-          connected: false,
-          isValid: false,
-          isSelfSigned: false,
-          issuer: "",
-          subject: "",
-          validFrom: "",
-          validTo: "",
-          daysUntilExpiry: 0,
-          error: isError ? error.name : "UnknownError",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => connection.end(),
+    };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,34 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * TLS inspection request.
+ */
+export interface TlsInspectRequest {
+  /** Action to perform (inspect is the default and only action for now) */
+  action?: "inspect";
+}
+
+/**
+ * TLS certificate information.
+ */
+export interface TlsCertificateInfo {
+  isValid: boolean;
+  isSelfSigned: boolean;
+  issuer: string;
+  subject: string;
+  validFrom: string;
+  validTo: string;
+  daysUntilExpiry: number;
+  daysRemaining: number; // Alias for daysUntilExpiry
+  protocol?: string;
+  cipher?: string;
+  error?: string;
+}
+
+/**
+ * TLS transport client for certificate inspection.
+ */
+export type TlsTransportClient = TransportClient<
+  TlsInspectRequest,
+  TlsCertificateInfo
+>;