@checkstack/healthcheck-tls-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/healthcheck-tls-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/healthcheck-common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/healthcheck-common@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [0babb9c]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/healthcheck-common@0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/healthcheck-tls-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

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

package/src/plugin-metadata.ts

@@ -0,0 +1,8 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the TLS/SSL Health Check backend.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-tls",
+});

package/src/strategy.test.ts

@@ -0,0 +1,308 @@
+import { describe, expect, it, mock } from "bun:test";
+import {
+  TlsHealthCheckStrategy,
+  TlsClient,
+  TlsConnection,
+  CertificateInfo,
+} from "./strategy";
+
+describe("TlsHealthCheckStrategy", () => {
+  // Create a valid certificate info (30 days until expiry)
+  const createCertInfo = (
+    overrides: Partial<{
+      subject: string;
+      issuer: string;
+      issuerOrg: string | undefined;
+      validFrom: Date;
+      validTo: Date;
+    }> = {}
+  ): CertificateInfo => {
+    const validFrom =
+      overrides.validFrom ?? new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    const validTo =
+      overrides.validTo ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+
+    // Check if issuerOrg was explicitly set (even to undefined)
+    const hasIssuerOrg = "issuerOrg" in overrides;
+    const issuerOrg = hasIssuerOrg ? overrides.issuerOrg : "DigiCert Inc";
+
+    return {
+      subject: { CN: overrides.subject ?? "example.com" },
+      issuer: {
+        CN: overrides.issuer ?? "DigiCert",
+        O: issuerOrg,
+      },
+      valid_from: validFrom.toISOString(),
+      valid_to: validTo.toISOString(),
+    };
+  };
+
+  // Helper to create mock TLS client
+  const createMockClient = (
+    config: {
+      authorized?: boolean;
+      cert?: CertificateInfo;
+      protocol?: string;
+      cipher?: string;
+      error?: Error;
+    } = {}
+  ): TlsClient => ({
+    connect: mock(() =>
+      config.error
+        ? Promise.reject(config.error)
+        : Promise.resolve({
+            authorized: config.authorized ?? true,
+            getPeerCertificate: () => config.cert ?? createCertInfo(),
+            getProtocol: () => config.protocol ?? "TLSv1.3",
+            getCipher: () => (config.cipher ? { name: config.cipher } : null),
+            end: mock(() => {}),
+          } as TlsConnection)
+    ),
+  });
+
+  describe("execute", () => {
+    it("should return healthy for valid certificate", async () => {
+      const strategy = new TlsHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "example.com",
+        port: 443,
+        timeout: 5000,
+        minDaysUntilExpiry: 7,
+        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(result.status).toBe("unhealthy");
+      expect(result.message).toContain("not valid");
+    });
+
+    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 () => {
+      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");
+    });
+
+    it("should pass daysUntilExpiry assertion", async () => {
+      const strategy = new TlsHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "example.com",
+        port: 443,
+        timeout: 5000,
+        minDaysUntilExpiry: 7,
+        rejectUnauthorized: true,
+        assertions: [
+          {
+            field: "daysUntilExpiry",
+            operator: "greaterThanOrEqual",
+            value: 7,
+          },
+        ],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should pass issuer assertion", async () => {
+      const strategy = new TlsHealthCheckStrategy(createMockClient());
+
+      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");
+    });
+
+    it("should fail isValid assertion when certificate is invalid", async () => {
+      const strategy = new TlsHealthCheckStrategy(
+        createMockClient({ authorized: false })
+      );
+
+      const result = await strategy.execute({
+        host: "example.com",
+        port: 443,
+        timeout: 5000,
+        minDaysUntilExpiry: 7,
+        rejectUnauthorized: false, // Don't reject to test assertion
+        assertions: [{ field: "isValid", operator: "isTrue" }],
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Assertion failed");
+    });
+
+    it("should detect self-signed certificates", async () => {
+      const selfSignedCert = createCertInfo({
+        subject: "localhost",
+        issuer: "localhost",
+        issuerOrg: undefined,
+      });
+
+      const strategy = new TlsHealthCheckStrategy(
+        createMockClient({ cert: selfSignedCert, authorized: false })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 443,
+        timeout: 5000,
+        minDaysUntilExpiry: 0,
+        rejectUnauthorized: false,
+      });
+
+      expect(result.metadata?.isSelfSigned).toBe(true);
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate averages correctly", () => {
+      const strategy = new TlsHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            isValid: true,
+            isSelfSigned: false,
+            issuer: "DigiCert",
+            subject: "example.com",
+            validFrom: "2024-01-01",
+            validTo: "2025-01-01",
+            daysUntilExpiry: 30,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            isValid: true,
+            isSelfSigned: false,
+            issuer: "DigiCert",
+            subject: "example.com",
+            validFrom: "2024-01-01",
+            validTo: "2025-01-01",
+            daysUntilExpiry: 20,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.avgDaysUntilExpiry).toBe(25);
+      expect(aggregated.minDaysUntilExpiry).toBe(20);
+      expect(aggregated.invalidCount).toBe(0);
+      expect(aggregated.errorCount).toBe(0);
+    });
+
+    it("should count invalid and errors", () => {
+      const strategy = new TlsHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "unhealthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            isValid: false,
+            isSelfSigned: false,
+            issuer: "",
+            subject: "",
+            validFrom: "",
+            validTo: "",
+            daysUntilExpiry: 0,
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 0,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: false,
+            isValid: false,
+            isSelfSigned: false,
+            issuer: "",
+            subject: "",
+            validFrom: "",
+            validTo: "",
+            daysUntilExpiry: 0,
+            error: "Connection refused",
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.invalidCount).toBe(1);
+      expect(aggregated.errorCount).toBe(1);
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,392 @@
+import * as tls from "node:tls";
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  numericField,
+  stringField,
+  booleanField,
+  evaluateAssertions,
+} from "@checkstack/backend-api";
+import {
+  healthResultBoolean,
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// 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.
+ */
+export const tlsConfigSchema = z.object({
+  host: z.string().describe("Hostname to connect to"),
+  port: z.number().int().min(1).max(65_535).default(443).describe("TLS port"),
+  servername: z
+    .string()
+    .optional()
+    .describe("SNI hostname (defaults to host if not specified)"),
+  timeout: z
+    .number()
+    .min(100)
+    .default(10_000)
+    .describe("Connection timeout in milliseconds"),
+  minDaysUntilExpiry: z
+    .number()
+    .min(0)
+    .default(14)
+    .describe("Minimum days until certificate expiry for healthy status"),
+  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>;
+
+/**
+ * Per-run result metadata.
+ */
+const tlsResultSchema = z.object({
+  connected: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Connected",
+  }),
+  isValid: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Certificate 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-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>;
+
+/**
+ * Aggregated metadata for buckets.
+ */
+const tlsAggregatedSchema = z.object({
+  avgDaysUntilExpiry: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Days Until Expiry",
+    "x-chart-unit": "days",
+  }),
+  minDaysUntilExpiry: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Min Days Until Expiry",
+    "x-chart-unit": "days",
+  }),
+  invalidCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Invalid Certificates",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+});
+
+export type TlsAggregatedResult = z.infer<typeof tlsAggregatedSchema>;
+
+// ============================================================================
+// TLS CLIENT INTERFACE (for testability)
+// ============================================================================
+
+export interface CertificateInfo {
+  subject: { CN?: string };
+  issuer: { CN?: string; O?: string };
+  valid_from: string;
+  valid_to: string;
+}
+
+export interface TlsConnection {
+  authorized: boolean;
+  getPeerCertificate(): CertificateInfo;
+  getProtocol(): string | null;
+  getCipher(): { name: string } | null;
+  end(): void;
+}
+
+export interface TlsClient {
+  connect(options: {
+    host: string;
+    port: number;
+    servername: string;
+    rejectUnauthorized: boolean;
+    timeout: number;
+  }): Promise<TlsConnection>;
+}
+
+// Default client using Node.js tls module
+const defaultTlsClient: TlsClient = {
+  connect(options): Promise<TlsConnection> {
+    return new Promise((resolve, reject) => {
+      const socket = tls.connect(
+        {
+          host: options.host,
+          port: options.port,
+          servername: options.servername,
+          rejectUnauthorized: options.rejectUnauthorized,
+          timeout: options.timeout,
+        },
+        () => {
+          resolve({
+            authorized: socket.authorized,
+            getPeerCertificate: () =>
+              socket.getPeerCertificate() as unknown as CertificateInfo,
+            getProtocol: () => socket.getProtocol(),
+            getCipher: () => socket.getCipher(),
+            end: () => socket.end(),
+          });
+        }
+      );
+
+      socket.on("error", reject);
+      socket.on("timeout", () => {
+        socket.destroy();
+        reject(new Error("Connection timeout"));
+      });
+    });
+  },
+};
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class TlsHealthCheckStrategy
+  implements HealthCheckStrategy<TlsConfig, TlsResult, TlsAggregatedResult>
+{
+  id = "tls";
+  displayName = "TLS/SSL Health Check";
+  description = "SSL/TLS certificate validation and expiry monitoring";
+
+  private tlsClient: TlsClient;
+
+  constructor(tlsClient: TlsClient = defaultTlsClient) {
+    this.tlsClient = tlsClient;
+  }
+
+  config: Versioned<TlsConfig> = new Versioned({
+    version: 1,
+    schema: tlsConfigSchema,
+  });
+
+  result: Versioned<TlsResult> = new Versioned({
+    version: 1,
+    schema: tlsResultSchema,
+  });
+
+  aggregatedResult: Versioned<TlsAggregatedResult> = new Versioned({
+    version: 1,
+    schema: tlsAggregatedSchema,
+  });
+
+  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++;
+      }
+    }
+
+    return {
+      avgDaysUntilExpiry: validRuns > 0 ? totalDaysUntilExpiry / validRuns : 0,
+      minDaysUntilExpiry:
+        minDaysUntilExpiry === Number.POSITIVE_INFINITY
+          ? 0
+          : minDaysUntilExpiry,
+      invalidCount,
+      errorCount,
+    };
+  }
+
+  async execute(config: TlsConfig): Promise<HealthCheckResult<TlsResult>> {
+    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,
+      };
+
+      // Evaluate assertions using shared utility
+      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
+        daysUntilExpiry,
+        issuer: result.issuer,
+        subject: result.subject,
+        isValid: result.isValid,
+        isSelfSigned,
+      });
+
+      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,
+        };
+      }
+
+      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",
+        },
+      };
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}