@checkstack/healthcheck-backend 1.14.0 → 1.15.0

package/src/config-secrets.ts

@@ -0,0 +1,361 @@
+import { z } from "zod";
+import { type AdvisoryLockService } from "@checkstack/backend-api";
+import {
+  type InternalSecretsService,
+  type SecretResolverService,
+  type ConfigSecretChannel,
+  extractScopeSecrets,
+  inflateScopeSecrets,
+  collectScopeSecretValues,
+  deleteScopeSecrets,
+  pruneScopeSecrets,
+  mergeSecretFields,
+} from "@checkstack/secrets-backend";
+import {
+  HEALTHCHECK_SECRET_MARKER_PREFIX,
+  type CollectorConfigEntry,
+} from "@checkstack/healthcheck-common";
+
+// Re-export the marker vocabulary (defined in healthcheck-common so the
+// satellite runtime shares it) and the schema-only channel helpers (defined in
+// secrets-backend, the ONE extraction channel) for this package + its tests.
+export {
+  healthcheckSecretMarker,
+  isHealthcheckSecretMarker,
+} from "@checkstack/healthcheck-common";
+// `mergeSecretFields` is also imported above for local use in this module;
+// this re-export surfaces the channel helpers for the package + its tests.
+export {
+  redactSecretFields,
+  mergeSecretFields,
+  listPopulatedSecretKeys,
+} from "@checkstack/secrets-backend";
+
+/**
+ * Health-check config credentials ride the platform's ONE config-secret
+ * extraction channel ({@link ConfigSecretChannel} in `@checkstack/secrets-backend`,
+ * shared with integration connections). This module only binds that channel to a
+ * health-check scope (strategy config, or one collector entry) and orchestrates
+ * the strategy + collectors of a whole configuration. Fields are declared with
+ * `configSecret({ id })`; the internal secret is keyed by the stable id.
+ */
+
+/**
+ * Scope of a secret within a configuration: the strategy config itself, or one
+ * collector entry's config (keyed by the entry's stable UUID, which survives
+ * collector re-ordering).
+ */
+export type SecretScope =
+  | { kind: "strategy" }
+  | { kind: "collector"; entryId: string };
+
+/** Internal-secret name parts for a health-check config credential field. */
+export function healthcheckSecretParts({
+  configurationId,
+  scope,
+  secretId,
+}: {
+  configurationId: string;
+  scope: SecretScope;
+  secretId: string;
+}): string[] {
+  return scope.kind === "strategy"
+    ? ["healthcheck", configurationId, "strategy", secretId]
+    : ["healthcheck", configurationId, "collector", scope.entryId, secretId];
+}
+
+/** The extraction channel bound to one health-check scope. */
+function scopeChannel(
+  configurationId: string,
+  scope: SecretScope,
+): ConfigSecretChannel {
+  return {
+    markerPrefix: HEALTHCHECK_SECRET_MARKER_PREFIX,
+    keyParts: (secretId) =>
+      healthcheckSecretParts({ configurationId, scope, secretId }),
+  };
+}
+
+export interface HealthCheckSecretsDeps {
+  internalSecrets: InternalSecretsService;
+  /** Only the per-run resolution surface is needed (narrows test fakes). */
+  secretResolver: Pick<SecretResolverService, "resolveForRun">;
+  /**
+   * Optional cluster-wide mutex. When present, `updateConfiguration` and
+   * `deleteConfiguration` serialize their read-modify-write-prune for a given
+   * config id under a per-id advisory lock, so a concurrent writer to the SAME
+   * id cannot have its just-written secret deleted by another writer's stale
+   * orphan-prune (which would leave a dangling marker).
+   */
+  advisoryLock?: AdvisoryLockService;
+}
+
+/** Advisory-lock key serializing writes to ONE health-check configuration. */
+export function healthcheckConfigLockKey(configurationId: string): string {
+  return `healthcheck:config:${configurationId}`;
+}
+
+/** Resolve a collector entry's config schema, or undefined when unknown. */
+export type GetCollectorSchema = (
+  collectorId: string,
+) => z.ZodTypeAny | undefined;
+
+// ============================================================================
+// EXTRACT (write path)
+// ============================================================================
+
+/**
+ * Extract inline secrets from a configuration's strategy config AND every
+ * collector entry's config into internal secrets, replacing each with a marker.
+ * An UNREGISTERED strategy has no schema, so its config passes through unchanged
+ * while REGISTERED collectors still extract their own secrets.
+ */
+export async function extractConfigurationSecrets({
+  configurationId,
+  strategySchema,
+  config,
+  collectors,
+  getCollectorSchema,
+  internalSecrets,
+}: {
+  strategySchema: z.ZodTypeAny | undefined;
+  configurationId: string;
+  config: Record<string, unknown>;
+  collectors: CollectorConfigEntry[] | undefined;
+  getCollectorSchema: GetCollectorSchema;
+  internalSecrets: InternalSecretsService;
+}): Promise<{
+  config: Record<string, unknown>;
+  collectors: CollectorConfigEntry[] | undefined;
+  extracted: number;
+}> {
+  let extracted = 0;
+
+  let strategyConfig = config;
+  if (strategySchema) {
+    const result = await extractScopeSecrets({
+      channel: scopeChannel(configurationId, { kind: "strategy" }),
+      schema: strategySchema,
+      config,
+      internalSecrets,
+    });
+    strategyConfig = result.config;
+    extracted += result.extracted;
+  }
+
+  let rewrittenCollectors = collectors;
+  if (collectors?.length) {
+    rewrittenCollectors = await Promise.all(
+      collectors.map(async (entry) => {
+        const schema = getCollectorSchema(entry.collectorId);
+        if (!schema) return entry;
+        const result = await extractScopeSecrets({
+          channel: scopeChannel(configurationId, {
+            kind: "collector",
+            entryId: entry.id,
+          }),
+          schema,
+          config: entry.config,
+          internalSecrets,
+        });
+        extracted += result.extracted;
+        return { ...entry, config: result.config };
+      }),
+    );
+  }
+
+  return { config: strategyConfig, collectors: rewrittenCollectors, extracted };
+}
+
+// ============================================================================
+// INFLATE / COLLECT (run path)
+// ============================================================================
+
+/** Inflate ONE stored config's secret fields to real values (in memory). */
+export async function inflateConfigSecrets({
+  configurationId,
+  scope,
+  schema,
+  config,
+  deps,
+}: {
+  configurationId: string;
+  scope: SecretScope;
+  schema: z.ZodTypeAny;
+  config: Record<string, unknown>;
+  deps: HealthCheckSecretsDeps;
+}): Promise<{ config: Record<string, unknown>; values: string[] }> {
+  return inflateScopeSecrets({
+    channel: scopeChannel(configurationId, scope),
+    schema,
+    config,
+    internalSecrets: deps.internalSecrets,
+    secretResolver: deps.secretResolver,
+  });
+}
+
+/** Resolve a config's secret fields to a `path -> value` map (satellite JIT). */
+export async function collectConfigSecretValues({
+  configurationId,
+  scope,
+  schema,
+  config,
+  deps,
+}: {
+  configurationId: string;
+  scope: SecretScope;
+  schema: z.ZodTypeAny;
+  config: Record<string, unknown>;
+  deps: HealthCheckSecretsDeps;
+}): Promise<Record<string, string>> {
+  return collectScopeSecretValues({
+    channel: scopeChannel(configurationId, scope),
+    schema,
+    config,
+    internalSecrets: deps.internalSecrets,
+    secretResolver: deps.secretResolver,
+  });
+}
+
+// ============================================================================
+// MERGE (update path)
+// ============================================================================
+
+/**
+ * Merge stored secrets into an incoming configuration update: the strategy
+ * config plus each collector entry (paired with the stored entry of the SAME
+ * id - a brand-new entry has nothing to restore). An unregistered strategy has
+ * no schema, so its config passes through unchanged.
+ */
+export function mergeConfigurationSecrets({
+  strategySchema,
+  incomingConfig,
+  storedConfig,
+  incomingCollectors,
+  storedCollectors,
+  getCollectorSchema,
+}: {
+  strategySchema: z.ZodTypeAny | undefined;
+  incomingConfig: Record<string, unknown>;
+  storedConfig: Record<string, unknown> | undefined;
+  incomingCollectors: CollectorConfigEntry[] | undefined;
+  storedCollectors: CollectorConfigEntry[] | undefined;
+  getCollectorSchema: GetCollectorSchema;
+}): {
+  config: Record<string, unknown>;
+  collectors: CollectorConfigEntry[] | undefined;
+} {
+  // Imported lazily-free: mergeSecretFields is re-exported above.
+  const config = strategySchema
+    ? mergeSecretFields({
+        schema: strategySchema,
+        incoming: incomingConfig,
+        stored: storedConfig,
+      })
+    : incomingConfig;
+
+  const storedById = new Map(
+    (storedCollectors ?? []).map((entry) => [entry.id, entry]),
+  );
+  const collectors = incomingCollectors?.map((entry) => {
+    const schema = getCollectorSchema(entry.collectorId);
+    const stored = storedById.get(entry.id);
+    if (!schema) return entry;
+    return {
+      ...entry,
+      config: mergeSecretFields({
+        schema,
+        incoming: entry.config,
+        stored: stored?.config,
+      }),
+    };
+  });
+
+  return { config, collectors };
+}
+
+// ============================================================================
+// CLEANUP (schema-free delete + orphan prune)
+// ============================================================================
+
+/** Collector scopes present across an old + new collector list, deduped. */
+function collectorScopes(
+  ...lists: (CollectorConfigEntry[] | undefined)[]
+): { kind: "collector"; entryId: string }[] {
+  const ids = new Set<string>();
+  for (const list of lists) for (const entry of list ?? []) ids.add(entry.id);
+  return [...ids].map((entryId) => ({ kind: "collector", entryId }));
+}
+
+/**
+ * Delete every internal secret a stored configuration's markers point at (the
+ * strategy config plus every collector entry). Schema-free, so it cleans up even
+ * when the strategy/collector plugin is uninstalled - a deleted check never
+ * orphans its secrets.
+ */
+export async function deleteConfigurationSecrets({
+  configurationId,
+  config,
+  collectors,
+  internalSecrets,
+}: {
+  configurationId: string;
+  config: Record<string, unknown>;
+  collectors: CollectorConfigEntry[] | undefined;
+  internalSecrets: InternalSecretsService;
+}): Promise<void> {
+  await deleteScopeSecrets({
+    channel: scopeChannel(configurationId, { kind: "strategy" }),
+    config,
+    internalSecrets,
+  });
+  const byId = new Map((collectors ?? []).map((e) => [e.id, e]));
+  for (const scope of collectorScopes(collectors)) {
+    await deleteScopeSecrets({
+      channel: scopeChannel(configurationId, scope),
+      config: byId.get(scope.entryId)?.config ?? {},
+      internalSecrets,
+    });
+  }
+}
+
+/**
+ * Delete internal secrets ORPHANED by an update: a cleared/removed field, an
+ * inline secret swapped for a reference, or a removed collector. Prunes the
+ * strategy scope and every collector scope (old ∪ new), comparing markers by
+ * exact internal-secret coordinates. Returns the number deleted.
+ */
+export async function pruneOrphanedConfigurationSecrets({
+  configurationId,
+  oldConfig,
+  newConfig,
+  oldCollectors,
+  newCollectors,
+  internalSecrets,
+}: {
+  configurationId: string;
+  oldConfig: Record<string, unknown>;
+  newConfig: Record<string, unknown>;
+  oldCollectors: CollectorConfigEntry[] | undefined;
+  newCollectors: CollectorConfigEntry[] | undefined;
+  internalSecrets: InternalSecretsService;
+}): Promise<number> {
+  let deleted = await pruneScopeSecrets({
+    channel: scopeChannel(configurationId, { kind: "strategy" }),
+    oldConfig,
+    newConfig: newConfig ?? {},
+    internalSecrets,
+  });
+
+  const oldById = new Map((oldCollectors ?? []).map((e) => [e.id, e]));
+  const newById = new Map((newCollectors ?? []).map((e) => [e.id, e]));
+  for (const scope of collectorScopes(oldCollectors, newCollectors)) {
+    deleted += await pruneScopeSecrets({
+      channel: scopeChannel(configurationId, scope),
+      oldConfig: oldById.get(scope.entryId)?.config ?? {},
+      newConfig: newById.get(scope.entryId)?.config ?? {},
+      internalSecrets,
+    });
+  }
+  return deleted;
+}

package/src/healthcheck-gitops-kinds.ts

@@ -146,14 +146,16 @@ export function buildHealthcheckKind(
       
       const strategy = matchStrategy.strategy;
 
-      // 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,
-        },
-      );
+      // Resolvability check ONLY: resolving `${{ secrets.* }}` references in
+      // `x-secret` fields surfaces a missing/undeclared secret as a clear
+      // apply-time error. The RESOLVED VALUES ARE DISCARDED - the ORIGINAL
+      // spec (references intact) is what gets validated and persisted, so a
+      // resolved secret never lands in the stored row. The executor resolves
+      // references just-in-time at run.
+      await context.resolveSecretsBySchema({
+        value: spec.config,
+        schema: strategy.config.schema,
+      });
 
       // Migrate-then-validate-strict: authored gitops YAML may be in an OLD
       // config shape, so run the migration chain (assume-v1-on-read) before
@@ -162,10 +164,11 @@ export function buildHealthcheckKind(
       // exact strict-validate path the `validateConfiguration` RPC uses, so the
       // two agree on what counts as valid. A strategy config is always a plain
       // object validated by the strategy's own schema, so narrowing the
-      // `unknown` result to the stored `Record` shape is safe.
+      // `unknown` result to the stored `Record` shape is safe. Secret fields
+      // hold reference strings here, which validate as ordinary strings.
       const strategyResult = await validateVersionedConfigStrict({
         config: strategy.config,
-        value: resolvedConfig,
+        value: spec.config,
         basePath: ["config"],
       });
       if (!strategyResult.ok) {
@@ -176,7 +179,7 @@ export function buildHealthcheckKind(
       const migratedConfig = strategyResult.value as Record<string, unknown>;
 
       // Resolve and validate collector configs using their registry schemas
-      const resolvedCollectors = spec.collectors
+      const validatedCollectors = spec.collectors
         ? await Promise.all(
             spec.collectors.map(async (c) => {
               // Look up collector using strictly the fully qualified ID
@@ -196,12 +199,13 @@ export function buildHealthcheckKind(
               }
               const registered = matchCollector;
 
-              // Resolve secrets using the collector's typed schema
-              const { resolved: resolvedCollectorConfig } =
-                await context.resolveSecretsBySchema({
-                  value: c.config,
-                  schema: registered.collector.config.schema,
-                });
+              // Resolvability check ONLY (see the strategy-config note): the
+              // resolved values are discarded and the ORIGINAL config (with
+              // references intact) is validated and persisted.
+              await context.resolveSecretsBySchema({
+                value: c.config,
+                schema: registered.collector.config.schema,
+              });
 
               // Migrate-then-validate-strict: authored gitops YAML may use an
               // OLD collector config shape. Run the migration chain before
@@ -213,7 +217,7 @@ export function buildHealthcheckKind(
               // `Record` shape is safe.
               const collectorResult = await validateVersionedConfigStrict({
                 config: registered.collector.config,
-                value: resolvedCollectorConfig,
+                value: c.config,
                 basePath: ["config"],
               });
               if (!collectorResult.ok) {
@@ -235,18 +239,25 @@ export function buildHealthcheckKind(
       const displayName = entity.metadata.title ?? entity.metadata.name;
 
       if (existingEntityId && !existingEntityId.startsWith("pending-")) {
-        await service.updateConfiguration(existingEntityId, {
-          name: displayName,
-          strategyId: spec.strategy,
-          config: migratedConfig,
-          intervalSeconds: spec.intervalSeconds,
-          collectors: resolvedCollectors?.map((c) => ({
-            id: c.collectorId,
-            collectorId: c.collectorId,
-            config: c.config,
-            assertions: c.assertions,
-          })),
-        });
+        await service.updateConfiguration(
+          existingEntityId,
+          {
+            name: displayName,
+            strategyId: spec.strategy,
+            config: migratedConfig,
+            intervalSeconds: spec.intervalSeconds,
+            collectors: validatedCollectors?.map((c) => ({
+              id: c.collectorId,
+              collectorId: c.collectorId,
+              config: c.config,
+              assertions: c.assertions,
+            })),
+          },
+          // GitOps is declarative: the authored YAML is the whole truth, so an
+          // omitted secret field means "not set" and must be removed, not
+          // silently restored from the stored row (keep-existing is UI-only).
+          { mergeSecrets: false },
+        );
         context.logger.info(
           `GitOps: updated Healthcheck "${displayName}" (id: ${existingEntityId})`,
         );
@@ -258,7 +269,7 @@ export function buildHealthcheckKind(
         strategyId: spec.strategy,
         config: migratedConfig,
         intervalSeconds: spec.intervalSeconds,
-        collectors: resolvedCollectors?.map((c) => ({
+        collectors: validatedCollectors?.map((c) => ({
           id: c.collectorId,
           collectorId: c.collectorId,
           config: c.config,

package/src/index.ts

@@ -56,7 +56,9 @@ import {
   type HealthEntityState,
 } from "./health-entity";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
-import { secretResolverRef } from "@checkstack/secrets-backend";
+import { secretResolverRef, internalSecretsRef } from "@checkstack/secrets-backend";
+import type { HealthCheckSecretsDeps } from "./config-secrets";
+import { backfillConfigSecrets } from "./config-secrets-backfill";
 import { createHealthCheckRouter } from "./router";
 import { HealthCheckService } from "./service";
 import {
@@ -171,6 +173,7 @@ export default createBackendPlugin({
     let gitopsHealthCheckRegistry: HealthCheckRegistry | undefined;
     let gitopsCollectorRegistry: CollectorRegistry | undefined;
     let gitopsQueueManager: QueueManager | undefined;
+    let gitopsConfigSecrets: HealthCheckSecretsDeps | undefined;
     let healthCheckCache:
       | ReturnType<typeof createHealthCheckCache>
       | undefined;
@@ -188,6 +191,9 @@ export default createBackendPlugin({
           gitopsDb,
           gitopsHealthCheckRegistry,
           gitopsCollectorRegistry,
+          undefined,
+          undefined,
+          gitopsConfigSecrets,
         );
       },
       getHealthCheckRegistry: () => {
@@ -220,6 +226,7 @@ export default createBackendPlugin({
         cacheManager: coreServices.cacheManager,
         config: coreServices.config,
         secretResolver: secretResolverRef,
+        internalSecrets: internalSecretsRef,
         advisoryLock: coreServices.advisoryLock,
         resourceResolverRegistry: coreServices.resourceResolverRegistry,
       },
@@ -236,6 +243,7 @@ export default createBackendPlugin({
         cacheManager,
         config,
         secretResolver,
+        internalSecrets,
         advisoryLock,
         resourceResolverRegistry,
       }) => {
@@ -243,6 +251,34 @@ export default createBackendPlugin({
 
         const typedDb = database as SafeDatabase<typeof schema>;
 
+        // Secrets channel for config credentials: extract-on-write /
+        // redact-on-read / inflate-at-run. Shared by the router, the gitops
+        // reconcile service, the executor, and the boot backfill.
+        const configSecrets: HealthCheckSecretsDeps = {
+          internalSecrets,
+          secretResolver,
+          // Serializes concurrent updateConfiguration writes to the SAME config
+          // id so one writer's orphan-prune cannot delete a secret a concurrent
+          // writer just set (which would leave a dangling marker).
+          advisoryLock,
+        };
+        gitopsConfigSecrets = configSecrets;
+
+        // Move any pre-channel inline secrets out of stored rows (idempotent,
+        // advisory-locked, fail-open: a backfill failure must not block boot).
+        try {
+          await backfillConfigSecrets({
+            db: typedDb,
+            registry: healthCheckRegistry,
+            collectorRegistry,
+            internalSecrets,
+            advisoryLock,
+            logger,
+          });
+        } catch (error) {
+          logger.warn("Config-secrets backfill failed; continuing boot", error);
+        }
+
         // Resolve/search health-check configurations by name for the Teams admin
         // UI (team grants are stored as opaque `<type>:<configId>` rows, where
         // <type> is `healthCheckResourceTypes.configuration` — i.e.
@@ -458,6 +494,7 @@ export default createBackendPlugin({
           getHealthEntity: () => healthEntity,
           cache,
           secretResolver,
+          internalSecrets,
         });
 
         // Setup retention job for tiered storage (daily aggregation)
@@ -486,6 +523,7 @@ export default createBackendPlugin({
           maintenanceClient,
           logger,
           signalService,
+          configSecrets,
           recomputeSystemRollupHealth: (systemId) =>
             recomputeSystemRollupHealth({
               systemId,
@@ -629,6 +667,14 @@ export default createBackendPlugin({
 // Re-export hooks for other plugins to use
 export { healthCheckHooks } from "./hooks";
 
+// Re-export the config-secrets channel so satellite-backend can resolve a
+// satellite's assignment config secrets just-in-time (the same walk +
+// marker/reference semantics the core executor uses).
+export {
+  collectConfigSecretValues,
+  type HealthCheckSecretsDeps,
+} from "./config-secrets";
+
 // Re-export the reactive `health` entity surface so cross-plugin consumers
 // (slo, dependency) can subscribe via onEntityChanged + classify changes
 // without duplicating the kind id / transition predicate (§10.3).