@checkstack/healthcheck-http-backend 0.5.4 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @checkstack/healthcheck-http-backend
 
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies [e819276]
+  - @checkstack/backend-api@0.28.0
+
+## 0.6.0
+
+### Minor Changes
+
+- b4e0832: Add optional authentication to the HTTP health check strategy. A new
+  **Authentication** picker (`none` / `basic` / `token`) on the strategy config
+  sets the outbound `Authorization` header: `basic` sends
+  `Basic <base64(username:password)>`, `token` sends `Bearer <token>`. Passwords
+  and tokens are secret fields (encrypted at rest, redacted in the UI). A
+  collector that sets its own `Authorization` header still takes precedence.
+  Existing configs are unaffected (`authType` defaults to `none`; no
+  schema-version bump required).
+
 ## 0.5.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-http-backend",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,7 +14,7 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.27.1",
+    "@checkstack/backend-api": "0.28.0",
     "@checkstack/healthcheck-common": "1.11.0",
     "jsonpath-plus": "^10.3.0",
     "@checkstack/common": "0.19.0"

package/src/strategy.test.ts

@@ -7,7 +7,11 @@ import {
 } from "bun:test";
 import * as http from "node:http";
 import { AddressInfo } from "node:net";
-import { HttpHealthCheckStrategy } from "./strategy";
+import {
+  buildAuthorizationHeader,
+  HttpHealthCheckStrategy,
+  httpHealthCheckConfigSchema,
+} from "./strategy";
 
 describe("HttpHealthCheckStrategy", () => {
   // Inject a deterministic DNS resolver so the in-process SSRF guard does not
@@ -88,8 +92,9 @@ describe("HttpHealthCheckStrategy", () => {
         headers: [{ name: "Accept", value: "application/json" }],
         body: "payload",
       });
-      // v1->v2 fabricates the default timeout, v2->v3 strips the moved fields.
-      expect(migrated).toEqual({ timeout: 30_000 });
+      // v1->v2 fabricates the default timeout, v2->v3 strips the moved fields;
+      // the final validation fills the defaulted authType.
+      expect(migrated).toEqual({ timeout: 30_000, authType: "none" });
     });
 
     it("carries a v1 timeout through both migration steps", async () => {
@@ -98,12 +103,12 @@ describe("HttpHealthCheckStrategy", () => {
         method: "POST",
         timeout: 12_345,
       });
-      expect(migrated).toEqual({ timeout: 12_345 });
+      expect(migrated).toEqual({ timeout: 12_345, authType: "none" });
     });
 
     it("is idempotent: an already-current {timeout} blob is unchanged", async () => {
       const migrated = await strategy.config.parseAssumingV1({ timeout: 5000 });
-      expect(migrated).toEqual({ timeout: 5000 });
+      expect(migrated).toEqual({ timeout: 5000, authType: "none" });
     });
 
     it("has a complete v1->version migration chain", () => {
@@ -301,6 +306,120 @@ describe("HttpHealthCheckStrategy", () => {
     });
   });
 
+  describe("authentication", () => {
+    it("sends no Authorization header by default (authType none)", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
+        method: "GET",
+        timeout: 5000,
+      });
+
+      const parsed = JSON.parse(result.body) as { auth: string | null };
+      expect(parsed.auth).toBeNull();
+
+      connectedClient.close();
+    });
+
+    it("sends Authorization: Basic with base64(username:password)", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+        authType: "basic",
+        authUsername: "alice",
+        authPassword: "s3cret",
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
+        method: "GET",
+        timeout: 5000,
+      });
+
+      const parsed = JSON.parse(result.body) as { auth: string | null };
+      const expected = Buffer.from("alice:s3cret", "utf8").toString("base64");
+      expect(parsed.auth).toBe(`Basic ${expected}`);
+
+      connectedClient.close();
+    });
+
+    it("sends Authorization: Bearer with the configured token", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+        authType: "token",
+        authToken: "my-api-token",
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
+        method: "GET",
+        timeout: 5000,
+      });
+
+      const parsed = JSON.parse(result.body) as { auth: string | null };
+      expect(parsed.auth).toBe("Bearer my-api-token");
+
+      connectedClient.close();
+    });
+
+    it("lets an explicit request Authorization header win over the config", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+        authType: "token",
+        authToken: "config-token",
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
+        method: "GET",
+        // Lower-case on purpose: precedence must be case-insensitive.
+        headers: { authorization: "Bearer request-token" },
+        timeout: 5000,
+      });
+
+      const parsed = JSON.parse(result.body) as { auth: string | null };
+      expect(parsed.auth).toBe("Bearer request-token");
+
+      connectedClient.close();
+    });
+
+    it("builds no header for authType none", () => {
+      expect(
+        buildAuthorizationHeader({ config: { authType: "none" } }),
+      ).toBeUndefined();
+    });
+
+    it("rejects basic auth without username or password", () => {
+      const missingPassword = httpHealthCheckConfigSchema.safeParse({
+        timeout: 5000,
+        authType: "basic",
+        authUsername: "alice",
+      });
+      expect(missingPassword.success).toBe(false);
+
+      const missingUsername = httpHealthCheckConfigSchema.safeParse({
+        timeout: 5000,
+        authType: "basic",
+        authPassword: "s3cret",
+      });
+      expect(missingUsername.success).toBe(false);
+    });
+
+    it("rejects token auth without a token", () => {
+      const result = httpHealthCheckConfigSchema.safeParse({
+        timeout: 5000,
+        authType: "token",
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it("accepts a config without auth fields (existing stored configs)", () => {
+      const result = httpHealthCheckConfigSchema.safeParse({ timeout: 5000 });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.authType).toBe("none");
+      }
+    });
+  });
+
   describe("SSRF guard (in-process egress)", () => {
     it("refuses a request whose host resolves to the cloud-metadata IP", async () => {
       const metadataStrategy = new HttpHealthCheckStrategy(async () => [

package/src/strategy.ts

@@ -6,6 +6,7 @@ import {
   aggregatedCounter,
   mergeCounter,
   z,
+  configString,
   type InferAggregatedResult,
   type ConnectedClient,
   type TransportTimings,
@@ -29,6 +30,14 @@ import type {
 // SCHEMAS
 // ============================================================================
 
+/**
+ * Supported authentication schemes for outbound HTTP health-check requests.
+ * - none: no Authorization header is set (default)
+ * - basic: `Authorization: Basic base64(<username>:<password>)`
+ * - token: `Authorization: Bearer <token>`
+ */
+export const HTTP_AUTH_TYPES = ["none", "basic", "token"] as const;
+
 /**
  * HTTP health check configuration schema.
  * Global defaults only - action params moved to RequestCollector.
@@ -40,19 +49,124 @@ import type {
  * the metadata/link-local block. Leaving it unset keeps the secure default.
  * RFC1918 / internal probing stays allowed by default (a monitoring tool's job).
  *
- * Optional + additive: existing stored configs (which lack this field) remain
- * valid, so no schema-version bump / migration is required.
+ * The auth fields hide behind the `authType` picker via `x-hidden-when`; the
+ * `""` entry covers configs stored before the field existed (no value in the
+ * form until the default is applied). Their conditional requiredness lives in
+ * the superRefine below, mirroring the Jira connection config pattern.
+ *
+ * Optional + additive: existing stored configs (which lack these fields)
+ * remain valid, so no schema-version bump / migration is required.
  */
-export const httpHealthCheckConfigSchema = baseStrategyConfigSchema.extend({
-  egressDenyCidrs: z
-    .array(z.string())
-    .optional()
-    .describe(
-      "Extra CIDR ranges to deny for outbound requests (added on top of the always-on cloud-metadata/link-local block).",
-    ),
-});
+export const httpHealthCheckConfigSchema = baseStrategyConfigSchema
+  .extend({
+    egressDenyCidrs: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Extra CIDR ranges to deny for outbound requests (added on top of the always-on cloud-metadata/link-local block).",
+      ),
+    authType: z
+      .enum(HTTP_AUTH_TYPES)
+      .default("none")
+      .describe("Authentication for outbound requests"),
+    authUsername: configString({
+      "x-hidden-when": { authType: ["none", "token", ""] },
+    })
+      .optional()
+      .describe("Username for Basic authentication"),
+    authPassword: configString({
+      "x-secret": true,
+      "x-hidden-when": { authType: ["none", "token", ""] },
+    })
+      .optional()
+      .describe("Password for Basic authentication"),
+    authToken: configString({
+      "x-secret": true,
+      "x-hidden-when": { authType: ["none", "basic", ""] },
+    })
+      .optional()
+      .describe("Bearer token for Token authentication"),
+  })
+  .superRefine((data, ctx) => {
+    if (data.authType === "basic") {
+      if (!data.authUsername) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Username is required for Basic authentication",
+          path: ["authUsername"],
+        });
+      }
+      if (!data.authPassword) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Password is required for Basic authentication",
+          path: ["authPassword"],
+        });
+      }
+    }
+    if (data.authType === "token" && !data.authToken) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Token is required for Token authentication",
+        path: ["authToken"],
+      });
+    }
+  });
 
 export type HttpHealthCheckConfig = z.infer<typeof httpHealthCheckConfigSchema>;
+export type HttpHealthCheckConfigInput = z.input<
+  typeof httpHealthCheckConfigSchema
+>;
+
+/**
+ * Build the `Authorization` header value for the configured auth scheme, or
+ * `undefined` when the check runs unauthenticated. Basic credentials are
+ * base64-encoded as `<username>:<password>` per RFC 7617.
+ */
+export function buildAuthorizationHeader({
+  config,
+}: {
+  config: Pick<
+    HttpHealthCheckConfig,
+    "authType" | "authUsername" | "authPassword" | "authToken"
+  >;
+}): string | undefined {
+  switch (config.authType) {
+    case "basic": {
+      const credentials = Buffer.from(
+        `${config.authUsername ?? ""}:${config.authPassword ?? ""}`,
+        "utf8",
+      ).toString("base64");
+      return `Basic ${credentials}`;
+    }
+    case "token": {
+      return `Bearer ${config.authToken ?? ""}`;
+    }
+    default: {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * Merge the strategy-level auth header into a request's headers. A collector
+ * that explicitly sets its own `Authorization` header (any casing) wins over
+ * the strategy config - the more specific setting takes precedence.
+ */
+function mergeAuthHeader({
+  headers,
+  authHeader,
+}: {
+  headers: Record<string, string> | undefined;
+  authHeader: string | undefined;
+}): Record<string, string> | undefined {
+  if (!authHeader) return headers;
+  const hasExplicitAuth = Object.keys(headers ?? {}).some(
+    (name) => name.toLowerCase() === "authorization",
+  );
+  if (hasExplicitAuth) return headers;
+  return { ...headers, Authorization: authHeader };
+}
 
 // The migrate input is `unknown` per the versioning chain, so narrowing is
 // done with `typeof`/`in` guards (no casts).
@@ -206,10 +320,14 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
    * All request parameters come from the collector (RequestCollector).
    */
   async createClient(
-    config: HttpHealthCheckConfig,
+    config: HttpHealthCheckConfigInput,
   ): Promise<ConnectedClient<HttpTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
+    // Strategy-level auth: computed once from the validated config; merged
+    // into every request unless the collector sets its own Authorization.
+    const authHeader = buildAuthorizationHeader({ config: validatedConfig });
+
     // SSRF secure default: deny cloud-metadata + link-local always, plus any
     // operator-configured extra ranges. This collector runs IN-PROCESS on the
     // trusted core, so without this guard a healthcheck author could point a
@@ -279,7 +397,7 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
           const fetchStart = performance.now();
           const response = await fetch(request.url, {
             method: request.method,
-            headers: request.headers,
+            headers: mergeAuthHeader({ headers: request.headers, authHeader }),
             body: request.body,
             signal: controller.signal,
           });