@checkstack/healthcheck-backend 0.14.3 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @checkstack/healthcheck-backend
 
+## 0.15.0
+
+### Minor Changes
+
+- 8ef367a: Added `registerSpecSchemaDocumentation` to EntityKindRegistry to allow plugins to provide detailed JSON Schemas for specific configurations. The frontend now displays these registered schemas as dropdown alternatives, improving the developer experience when authoring GitOps configurations.
+
+### Patch Changes
+
+- cb65e9d: ### Schema-driven secret resolution, rotation invalidation, and security hardening
+
+  **Breaking**: Replaced `{ secretRef: "..." }` object syntax with `${{ secrets.NAME }}` template interpolation. The `secretField()`, `secretRefSchema`, `isSecretRef`, `SecretRef`, and `ResolvedSecretField` exports have been removed from `@checkstack/gitops-common`.
+
+  **Breaking**: `ReconcileContext.resolveSecretsBySchema()` now returns `{ resolved: T; warnings: string[] }` instead of `T` directly. Plugins must destructure the result. Warnings contain messages for `${{ secrets.NAME }}` templates found in non-secret fields (fields without `x-secret` annotation).
+
+  **New features**:
+
+  - Secrets can be referenced in **any string field** using `${{ secrets.NAME }}` syntax
+  - Inline interpolation is supported: `"postgres://user:${{ secrets.DB_PASS }}@host/db"`
+  - Resolution is **schema-driven** — reuses the existing `configString({ "x-secret": true })` pattern from DynamicForm
+  - Secret rotation now automatically invalidates affected entities, triggering re-reconciliation on the next sync cycle
+  - New `getSecretUsage` RPC endpoint to look up which entities reference a given secret
+  - Secrets UI now shows an expandable usage panel per secret showing referencing entities
+  - Reconciliation warnings: templates in non-secret fields are detected and surfaced in the provenance UI
+  - New `secretNameSchema` and `SECRET_NAME_REGEX` exports for validating secret names
+
+  **Security**:
+
+  - Secret names are validated at creation: must start with a letter, contain only `[a-zA-Z0-9_-]`, max 63 chars
+  - Secrets are validated to exist at sync time but **not pre-resolved** into the spec
+  - Templates in `metadata` fields are **rejected** to prevent secret leaks via display fields
+  - Only fields with `x-secret` schema annotations get resolved — no escape hatch
+  - Templates in non-secret fields emit warnings (stored in provenance, visible in UI) instead of silently passing
+
+  **Migration**: Update YAML descriptors to use `${{ secrets.NAME }}` instead of `secretRef: name`. Remove `secretField()` imports from plugin schemas — use `configString({ "x-secret": true })` to annotate secret fields. Destructure `const { resolved } = await context.resolveSecretsBySchema({ value, schema })` (return type changed from `T` to `{ resolved: T; warnings: string[] }`).
+
+- Updated dependencies [8ef367a]
+- Updated dependencies [cb65e9d]
+  - @checkstack/gitops-common@0.2.0
+  - @checkstack/gitops-backend@0.2.0
+  - @checkstack/catalog-backend@0.4.3
+  - @checkstack/satellite-backend@0.2.6
+
 ## 0.14.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,18 +14,18 @@
   },
   "dependencies": {
     "@checkstack/backend-api": "0.12.0",
-    "@checkstack/catalog-backend": "0.4.0",
+    "@checkstack/catalog-backend": "0.4.2",
     "@checkstack/catalog-common": "1.3.1",
     "@checkstack/command-backend": "0.1.19",
     "@checkstack/common": "0.6.5",
-    "@checkstack/gitops-backend": "0.1.0",
-    "@checkstack/gitops-common": "0.1.0",
+    "@checkstack/gitops-backend": "0.1.2",
+    "@checkstack/gitops-common": "0.1.1",
     "@checkstack/healthcheck-common": "0.11.0",
     "@checkstack/incident-common": "0.4.7",
     "@checkstack/integration-backend": "0.1.19",
     "@checkstack/maintenance-common": "0.4.9",
     "@checkstack/queue-api": "0.2.13",
-    "@checkstack/satellite-backend": "0.2.3",
+    "@checkstack/satellite-backend": "0.2.5",
     "@checkstack/signal-common": "0.1.9",
     "@hono/zod-validator": "^0.7.6",
     "drizzle-orm": "^0.45.0",

package/src/healthcheck-gitops-kinds.test.ts

@@ -191,6 +191,8 @@ const mockContext: ReconcileContext = {
     error: () => {},
   },
   resolveEntityRef: async () => undefined,
+  resolveSecretsBySchema: async <T>(params: { value: T }): Promise<{ resolved: T; warnings: string[] }> =>
+    ({ resolved: params.value, warnings: [] }),
 };
 
 // ─── Tests: kind: Healthcheck ──────────────────────────────────────────────
@@ -594,3 +596,111 @@ describe("Healthcheck GitOps Kind: System Extension", () => {
     expect(mockService.associateSystem).not.toHaveBeenCalled();
   });
 });
+
+// ─── Tests: Secret template resolution in healthcheck configs ──────────────
+
+describe("Healthcheck GitOps: Secret template resolution", () => {
+  it("collectSecretNames extracts secrets from healthcheck config", async () => {
+    const { collectSecretNames } = await import("@checkstack/gitops-common");
+
+    const spec = {
+      strategy: "postgres",
+      intervalSeconds: 30,
+      config: {
+        host: "db.internal",
+        port: 5432,
+        database: "payments",
+        user: "monitor",
+        password: "${{ secrets.DB_PASS }}",
+      },
+    };
+
+    const names = collectSecretNames({ value: spec });
+    expect(names).toEqual(["DB_PASS"]);
+  });
+
+  it("collectSecretNames extracts multiple secrets from config", async () => {
+    const { collectSecretNames } = await import("@checkstack/gitops-common");
+
+    const spec = {
+      strategy: "postgres",
+      intervalSeconds: 30,
+      config: {
+        host: "db.internal",
+        user: "${{ secrets.DB_USER }}",
+        password: "${{ secrets.DB_PASS }}",
+      },
+    };
+
+    const names = collectSecretNames({ value: spec });
+    expect(names).toContain("DB_USER");
+    expect(names).toContain("DB_PASS");
+    expect(names).toHaveLength(2);
+  });
+
+  it("collectSecretNames handles inline interpolation in config values", async () => {
+    const { collectSecretNames } = await import("@checkstack/gitops-common");
+
+    const spec = {
+      strategy: "postgres",
+      intervalSeconds: 30,
+      config: {
+        connectionString:
+          "postgres://${{ secrets.DB_USER }}:${{ secrets.DB_PASS }}@host/db",
+      },
+    };
+
+    const names = collectSecretNames({ value: spec });
+    expect(names).toContain("DB_USER");
+    expect(names).toContain("DB_PASS");
+  });
+
+  it("SECRET_TEMPLATE_REGEX correctly identifies templates in healthcheck config values", async () => {
+    const { SECRET_TEMPLATE_REGEX } = await import("@checkstack/gitops-common");
+
+    const configValues = [
+      { input: "${{ secrets.DB_PASS }}", expectedSecrets: ["DB_PASS"] },
+      { input: "db-${{ secrets.ENV }}.internal", expectedSecrets: ["ENV"] },
+      {
+        input:
+          "postgres://${{ secrets.DB_USER }}:${{ secrets.DB_PASS }}@host/db",
+        expectedSecrets: ["DB_USER", "DB_PASS"],
+      },
+      { input: "plain-value", expectedSecrets: [] },
+    ];
+
+    for (const { input, expectedSecrets } of configValues) {
+      const found: string[] = [];
+      SECRET_TEMPLATE_REGEX.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = SECRET_TEMPLATE_REGEX.exec(input)) !== null) {
+        found.push(match[1]);
+      }
+      expect(found).toEqual(expectedSecrets);
+    }
+  });
+
+  it("template replacement produces expected resolved config", () => {
+    // Simulates what the reconciler does: replace ${{ secrets.X }} with values
+    const secrets: Record<string, string> = {
+      DB_PASS: "production-password-123",
+      ENV: "production",
+    };
+
+    const rawConfig: Record<string, string> = {
+      host: "db-${{ secrets.ENV }}.internal",
+      password: "${{ secrets.DB_PASS }}",
+    };
+
+    const resolvedConfig: Record<string, string> = {};
+    for (const [key, value] of Object.entries(rawConfig)) {
+      resolvedConfig[key] = value.replaceAll(
+        /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g,
+        (_match, secretName: string) => secrets[secretName] ?? _match,
+      );
+    }
+
+    expect(resolvedConfig.host).toBe("db-production.internal");
+    expect(resolvedConfig.password).toBe("production-password-123");
+  });
+});

package/src/healthcheck-gitops-kinds.ts

@@ -5,13 +5,23 @@ import type {
   EntityKindRegistry,
   ReconcileContext,
 } from "@checkstack/gitops-common";
-import { CHECKSTACK_API_VERSION, secretField, entityRefSchema } from "@checkstack/gitops-common";
+import {
+  CHECKSTACK_API_VERSION,
+  entityRefSchema,
+} from "@checkstack/gitops-common";
 import type {
   HealthCheckRegistry,
   CollectorRegistry,
 } from "@checkstack/backend-api";
 import { HealthCheckService } from "./service";
-
+import {
+  DynamicOperators,
+  numericField,
+  stringField,
+  booleanField,
+  arrayField,
+  enumField,
+} from "@checkstack/backend-api";
 
 /**
  * Lazy accessor functions — populated during init(), consumed during reconcile.
@@ -29,13 +39,13 @@ interface HealthcheckGitOpsKindsDeps {
 /**
  * GitOps spec schema for kind: Healthcheck.
  *
- * Strategy `config` fields use `secretField()` for sensitive values
- * (passwords, tokens) that are resolved by the reconciliation engine.
+ * Strategy `config` values may contain `${{ secrets.NAME }}` templates
+ * which are automatically resolved by the reconciliation engine.
  */
 const healthcheckSpecSchema = z.object({
   strategy: z.string().min(1),
   intervalSeconds: z.number().int().min(1),
-  config: z.record(z.string(), z.union([z.unknown(), secretField()])),
+  config: z.record(z.string(), z.unknown()),
   collectors: z
     .array(
       z.object({
@@ -97,53 +107,83 @@ export function buildHealthcheckKind(
       existingEntityId,
       context,
     }: {
-      entity: { metadata: { name: string; title?: string; description?: string }; spec: HealthcheckSpec };
+      entity: {
+        metadata: { name: string; title?: string; description?: string };
+        spec: HealthcheckSpec;
+      };
       existingEntityId?: string;
       context: ReconcileContext;
     }) => {
       const service = deps.createService();
       const spec = entity.spec;
 
-      // Validate strategy exists in registry
+      // Look up strategy first — we need its typed schema for secret resolution
       const healthCheckRegistry = deps.getHealthCheckRegistry();
       const strategy = healthCheckRegistry.getStrategy(spec.strategy);
       if (!strategy) {
         throw new Error(
           `Unknown health check strategy "${spec.strategy}". ` +
-            `Available: ${healthCheckRegistry.getStrategies().map((s) => s.id).join(", ")}`,
+            `Available: ${healthCheckRegistry
+              .getStrategies()
+              .map((s) => s.id)
+              .join(", ")}`,
         );
       }
 
-      // Validate config against strategy's Zod schema
-      const configValidation = strategy.config.schema.safeParse(spec.config);
+      // Resolve secrets using the strategy's typed schema.
+      // Only fields marked with configString({ "x-secret": true }) get resolved.
+      const { resolved: resolvedConfig } = await context.resolveSecretsBySchema(
+        {
+          value: spec.config,
+          schema: strategy.config.schema,
+        },
+      );
+
+      // Validate resolved config against strategy's Zod schema
+      const configValidation = strategy.config.schema.safeParse(resolvedConfig);
       if (!configValidation.success) {
         throw new Error(
           `Strategy "${spec.strategy}" config validation failed: ${configValidation.error.message}`,
         );
       }
 
-      // Validate collector configs against their registry schemas
-      if (spec.collectors) {
-        for (const collector of spec.collectors) {
-          const collectorReg = deps.getCollectorRegistry();
-          const registered = collectorReg.getCollector(
-            collector.collectorId,
-          );
-          if (!registered) {
-            throw new Error(
-              `Unknown collector "${collector.collectorId}". ` +
-                `Available: ${collectorReg.getCollectors().map((c) => c.qualifiedId).join(", ")}`,
-            );
-          }
-          const collectorConfigValidation =
-            registered.collector.config.schema.safeParse(collector.config);
-          if (!collectorConfigValidation.success) {
-            throw new Error(
-              `Collector "${collector.collectorId}" config validation failed: ${collectorConfigValidation.error.message}`,
-            );
-          }
-        }
-      }
+      // Resolve and validate collector configs using their registry schemas
+      const resolvedCollectors = spec.collectors
+        ? await Promise.all(
+            spec.collectors.map(async (c) => {
+              const collectorReg = deps.getCollectorRegistry();
+              const registered = collectorReg.getCollector(c.collectorId);
+              if (!registered) {
+                throw new Error(
+                  `Unknown collector "${c.collectorId}". ` +
+                    `Available: ${collectorReg
+                      .getCollectors()
+                      .map((col) => col.qualifiedId)
+                      .join(", ")}`,
+                );
+              }
+
+              // Resolve secrets using the collector's typed schema
+              const { resolved: resolvedCollectorConfig } =
+                await context.resolveSecretsBySchema({
+                  value: c.config,
+                  schema: registered.collector.config.schema,
+                });
+
+              const collectorConfigValidation =
+                registered.collector.config.schema.safeParse(
+                  resolvedCollectorConfig,
+                );
+              if (!collectorConfigValidation.success) {
+                throw new Error(
+                  `Collector "${c.collectorId}" config validation failed: ${collectorConfigValidation.error.message}`,
+                );
+              }
+
+              return { ...c, config: resolvedCollectorConfig };
+            }),
+          )
+        : undefined;
 
       // Create or update configuration
       const displayName = entity.metadata.title ?? entity.metadata.name;
@@ -152,9 +192,9 @@ export function buildHealthcheckKind(
         await service.updateConfiguration(existingEntityId, {
           name: displayName,
           strategyId: spec.strategy,
-          config: spec.config,
+          config: resolvedConfig,
           intervalSeconds: spec.intervalSeconds,
-          collectors: spec.collectors?.map((c) => ({
+          collectors: resolvedCollectors?.map((c) => ({
             id: c.collectorId,
             collectorId: c.collectorId,
             config: c.config,
@@ -170,9 +210,9 @@ export function buildHealthcheckKind(
       const config = await service.createConfiguration({
         name: displayName,
         strategyId: spec.strategy,
-        config: spec.config,
+        config: resolvedConfig,
         intervalSeconds: spec.intervalSeconds,
-        collectors: spec.collectors?.map((c) => ({
+        collectors: resolvedCollectors?.map((c) => ({
           id: c.collectorId,
           collectorId: c.collectorId,
           config: c.config,
@@ -254,7 +294,7 @@ export function buildSystemHealthcheckExtension(
         // Build state thresholds from the shorthand
         const stateThresholds =
           entry.degradedThreshold || entry.unhealthyThreshold
-            ? ({
+            ? {
                 mode: "consecutive" as const,
                 healthy: { minSuccessCount: 1 },
                 degraded: {
@@ -263,7 +303,7 @@ export function buildSystemHealthcheckExtension(
                 unhealthy: {
                   minFailureCount: entry.unhealthyThreshold ?? 5,
                 },
-              })
+              }
             : undefined;
 
         await service.associateSystem({
@@ -310,3 +350,138 @@ export function registerHealthcheckGitOpsKinds({
   kindRegistry.registerKind(buildHealthcheckKind(deps));
   kindRegistry.registerKindExtension(buildSystemHealthcheckExtension(deps));
 }
+
+/**
+ * Register spec schema documentation for the Healthcheck kind.
+ * Called from healthcheck-backend's `afterPluginsReady` phase once registries are populated.
+ */
+export function registerHealthcheckGitOpsDocumentation({
+  kindRegistry,
+  healthCheckRegistry,
+  collectorRegistry,
+}: {
+  kindRegistry: EntityKindRegistry;
+  healthCheckRegistry: HealthCheckRegistry;
+  collectorRegistry: CollectorRegistry;
+}): void {
+  // 1. Register documentation for strategy configs (fieldPath: "config")
+  for (const registered of healthCheckRegistry.getStrategiesWithMeta()) {
+    kindRegistry.registerSpecSchemaDocumentation({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Healthcheck",
+      fieldPath: "config",
+      variantId: registered.ownerPluginId,
+      label: registered.strategy.displayName,
+      description: `ID: ${registered.ownerPluginId}\n\n${registered.strategy.description}`,
+      schema: registered.strategy.config.schema,
+    });
+  }
+
+  // 2. Register documentation for collector configs (fieldPath: "collectors[].config")
+  for (const registered of collectorRegistry.getCollectors()) {
+    kindRegistry.registerSpecSchemaDocumentation({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Healthcheck",
+      fieldPath: "collectors[].config",
+      variantId: registered.qualifiedId,
+      label: registered.collector.displayName,
+      description: `ID: ${registered.qualifiedId}\n\n${registered.collector.description}`,
+      schema: registered.collector.config.schema,
+      conditions: [
+        {
+          fieldPath: "config",
+          variantIds: registered.collector.supportedPlugins.map(
+            (p) => p.pluginId,
+          ),
+        },
+      ],
+    });
+
+    // 3. Register documentation for collector assertions (fieldPath: "collectors[].assertions")
+    const unwrapped = unwrapZodType(registered.collector.result.schema);
+    
+    if (unwrapped instanceof z.ZodObject) {
+      const shape = unwrapped.shape;
+      
+      for (const [key, prop] of Object.entries(shape)) {
+        const propUnwrapped = unwrapZodType(prop as z.ZodTypeAny);
+
+        let fieldSchema: z.ZodTypeAny;
+
+        if (propUnwrapped instanceof z.ZodNumber) {
+          fieldSchema = numericField(key);
+        } else if (propUnwrapped instanceof z.ZodString) {
+          fieldSchema = stringField(key);
+        } else if (propUnwrapped instanceof z.ZodBoolean) {
+          fieldSchema = booleanField(key);
+        } else if (propUnwrapped instanceof z.ZodArray) {
+          fieldSchema = arrayField(key);
+        } else if (propUnwrapped instanceof z.ZodEnum) {
+          const enumValues = propUnwrapped.options;
+          const stringValues = enumValues.filter((v: unknown) => typeof v === "string") as string[];
+          fieldSchema = stringValues.length > 0 ? enumField(key, stringValues) : stringField(key);
+        } else {
+          fieldSchema = stringField(key);
+        }
+
+        kindRegistry.registerSpecSchemaDocumentation({
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Healthcheck",
+          fieldPath: "collectors[].assertions",
+          variantId: `${registered.qualifiedId}.assert.${key}`,
+          label: `Assert: ${key}`,
+          description: `Assertion documentation for the '${key}' field of ${registered.collector.displayName}.`,
+          schema: z.array(fieldSchema).describe(`Assertions array`),
+          conditions: [
+            {
+              fieldPath: "collectors[].config",
+              variantIds: [registered.qualifiedId],
+            },
+          ],
+        });
+      }
+    } else {
+      // Fallback if result schema is not an object
+      kindRegistry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        fieldPath: "collectors[].assertions",
+        variantId: `${registered.qualifiedId}.assert.generic`,
+        label: `${registered.collector.displayName} Assertions`,
+        description: `Define assertions against the result of this collector.`,
+        schema: z.array(
+          z.object({
+            field: z.string(),
+            operator: DynamicOperators,
+            value: z.unknown().optional(),
+          })
+        ).describe(`Assertions array`),
+        conditions: [
+          {
+            fieldPath: "collectors[].config",
+            variantIds: [registered.qualifiedId],
+          },
+        ],
+      });
+    }
+  }
+}
+
+function unwrapZodType(type: z.ZodTypeAny): z.ZodTypeAny {
+  let current = type;
+  while (current) {
+    if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+      current = current.unwrap() as z.ZodTypeAny;
+    } else if (current instanceof z.ZodDefault) {
+      current = current._def.innerType as z.ZodTypeAny;
+    } else if ("innerType" in current && typeof current.innerType === "function") {
+      // Handles ZodEffects/ZodBranded generically without relying on removed types
+      current = current.innerType() as z.ZodTypeAny;
+    } else {
+      break;
+    }
+  }
+  return current;
+}
+
+

package/src/index.ts

@@ -24,7 +24,7 @@ import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { z } from "zod";
 import { createHealthCheckRouter } from "./router";
 import { HealthCheckService } from "./service";
-import { registerHealthcheckGitOpsKinds } from "./healthcheck-gitops-kinds";
+import { registerHealthcheckGitOpsKinds, registerHealthcheckGitOpsDocumentation } from "./healthcheck-gitops-kinds";
 import { catalogHooks } from "@checkstack/catalog-backend";
 import { satelliteHooks } from "@checkstack/satellite-backend";
 import { CatalogApi } from "@checkstack/catalog-common";
@@ -239,6 +239,13 @@ export default createBackendPlugin({
           logger,
         });
 
+        // Register GitOps documentation now that registries are populated
+        registerHealthcheckGitOpsDocumentation({
+          kindRegistry,
+          healthCheckRegistry,
+          collectorRegistry,
+        });
+
         // Subscribe to catalog system deletion to clean up associations
         const service = new HealthCheckService(
           database,