@checkstack/healthcheck-common 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @checkstack/healthcheck-common
 
+## 1.5.0
+
+### Minor Changes
+
+- 9dcc848: Plugin-owned AI tools: every domain plugin contributes its own AI tools (chat assistant + automation AI action), and `ai-backend` is platform-only.
+
+  Every plugin-specific AI tool is owned by the plugin whose domain it acts on, registered via that plugin's own `aiToolExtensionPoint` / `aiToolProjectionExtensionPoint` from its init - the same path an external plugin author uses. `ai-backend` no longer imports or depends on any capability plugin's `*-common`; the dependency direction is strictly plugin -> ai-platform. Pure helpers (`computeFieldDiff`, capability-summary, `ScriptContextKind`) live in `@checkstack/ai-common`.
+
+  Tools shipped:
+
+  - Health checks and automations: full CRUD - `healthcheck.propose` / `automation.propose` and `*.update` (`mutate`, deep-validated) and `*.delete` (`destructive`, always confirm-gated). `healthcheck.propose`'s dry-run calls the new deep `validateConfiguration` so propose-time validation matches apply-time. Assertions are validated against the collector's result schema and the canonical operator vocabulary. Capability-catalog tools (`ai.listCapabilities`, `ai.getCapabilitySchema`), script context tools (`ai.getScriptContext`, `ai.testScript`), and notify-subscriber tools (`healthcheck.notifySystemSubscribers` / `...GroupSubscribers`).
+  - Catalog: `catalog.createSystem` / `updateSystem` / `createGroup` / `updateGroup` (`mutate`), `catalog.deleteSystem` / `deleteGroup` (`destructive`), membership tools (`mutate`), plus `catalog.listSystems` / `listGroups` read projections.
+  - Incident: `incident.create` / `update` / `addUpdate` / `resolve` / `addLink` (`mutate`), `incident.delete` / `removeLink` (`destructive`), and `incident.get` / `incident.list` read projections.
+  - Maintenance: `maintenance.create` / `update` / `addUpdate` / `close` / `addLink` (`mutate`), `maintenance.delete` / `removeLink` (`destructive`), and `maintenance.list` / `get` read projections.
+  - Read projections for SLO (`slo.listObjectives`), dependency (`dependency.list`), incident (`incident.list`), healthcheck (`healthcheck.status`), and anomaly (`anomaly.explain`), each gated by the source procedure's own access rule and routed as the principal.
+  - Documentation grounding: `ai.searchDocs` / `ai.getDoc` over a build-time bundled docs index (BM25-ish ranking), so the assistant grounds how-to answers in Checkstack's own docs offline.
+  - URL introspection: `ai.probeUrl`, an SSRF-guarded read tool the assistant uses to inspect a real endpoint before drafting a health check. Update tools compute a before -> after field diff rendered on the confirm card (approve mode) or an "Applied" card (auto mode), so a change is never silent.
+
+  `ai_analyze` automation action (automation-backend, with an editor connection picker + audited tool calls): runs a bounded AI agent on the run context as the automation's `runAs` service account, so it can never exceed that identity's permissions; destructive tools are never offered; mutating tools auto-apply through the service account's client. Produces an `automation.analysis` artifact downstream actions can branch on. The agent loop is exposed as a headless `aiAgentRunnerRef` service so automation-backend can drive it without depending on ai-backend.
+
+  `notification.notifyForSubscription` is now callable by user / application principals holding `notification.send` (previously service-only). Every tool routes through the user-scoped client, so handler-side authorization is enforced exactly as a direct UI/RPC action; the resolver gate plus the propose/apply re-check at propose AND apply are the additional authority. A systemic authz regression test asserts every registered tool falls into exactly one safe authorization category.
+
+  A new `ai_transport` enum value `automation` records the AI action's tool calls in the `ai_tool_calls` audit log. No new durable state beyond that; each tool is a thin, deterministic wrapper over an existing RPC, so every pod behaves identically.
+
+  This is a beta minor.
+
+- 9dcc848: Add environments as a first-class catalog primitive, with per-environment health-check fan-out, config templating, per-environment reactive health, and script run-context exposure.
+
+  - Catalog primitive: an environment is a sibling of groups - a named, instance-global record carrying free-form custom fields (baseUrl, region, tier, ...) that any system can belong to many-to-many. New `environments` + `systems_environments` tables, `EnvironmentSchema` + create/update schemas, `EntityService` environment CRUD and membership joins, RPC endpoints gated by a new `catalogAccess.environment` access rule, a GitOps `Environment` kind + `System.environments` extension, and frontend management (an `EnvironmentEditor`, an Environments management panel, and a per-system environment picker). The Environments card's Add/Edit/Delete affordances are gated on `catalogAccess.environment.manage`.
+  - Per-environment fan-out: run identity becomes `(systemId, configurationId, environmentId)`. Runs, aggregates, and state transitions gain a nullable `environmentId`. The health-check assignment gains an `environmentIds` selector with three modes (All / Specific / None; `null` and `[]` are distinct). The queue executor resolves the effective environment set via the catalog `resolveSystemEnvironments` read and executes one isolated run per environment.
+  - Config templating: a new `x-templatable` config-field marker renders a string field through the template engine at execute time, against `{ environment, check, system }`. A shared `renderTemplatableConfig` and a `renderTemplatePreview` helper (re-exported from `@checkstack/template-engine`) keep editor previews identical to the run-time render. The HTTP collector's `url`, `headers[].value`, and `body` are templatable, rendered per environment (the strategy client build moves inside the per-env loop); the `url`'s `.url()` validation moves post-render. Secrets resolve before templating; a field marked both secret and `x-templatable` is rejected at plugin load. `DynamicForm` shows a live "Preview" line, and the catalog `EnvironmentPreviewPicker` ("Preview as: <environment>") drives it in the collector editor (only when the schema has a templatable field).
+  - Script run-context: `CollectorRunContext` gains an optional `environment` field (`{ id, name, fields }`, metadata only). Shell collectors receive `CHECKSTACK_ENV_ID` / `_NAME` / `CHECKSTACK_ENV_<FIELD>` vars; inline TS collectors read `globalThis.context.environment`; the editor test panel mirrors both. The env-less path is unchanged.
+  - Per-environment reactive health (see BREAKING below), env-keyed read/write paths, env-qualified serialization locks, an optional `trigger.payload.environmentId`, per-environment isolation, and an `ENVIRONMENT_RESOLUTION_FAILED` signal when catalog resolution degrades to a single env-less run.
+
+  BREAKING CHANGES: the reactive `health` entity's id-shape and cardinality change. It now encodes two views: per-environment (id `"<systemId>::<environmentId>"`) and a system rollup (id `"<systemId>"`, the worst status across environments + env-less runs). The rollup PRESERVES the pre-existing system-level contract - dashboards, status badges, and automations referencing health by `systemId` keep working without re-authoring - but the entity's contract surface changed (new id-shape, higher cardinality, new payload field), so it is flagged breaking. `getBulkHealthState` parses env-qualified ids and keys results by the original id.
+
+  State and scale: membership and custom fields live only in catalog Postgres and are re-read every tick via the cross-plugin RPC; env-keyed health reads from shared `health_check_runs` / aggregates / transitions (compute-on-read). Every pod resolves the same effective set and the same per-environment health. No pod-local environment state.
+
+  Also: `unwrapSchema` in `zod-config.ts` loops instead of single-pass-stripping so multi-layer wrappers (`.optional().default()`) still resolve `x-templatable` meta. The env-less `{{ environment.* }}` run notice logs at `debug` (a legitimate recurring configuration), while the post-render HTTP `.url()` check still fails a genuinely-broken empty render with a clear "Rendered URL is invalid" error.
+
+  This is a beta minor.
+
+- 9dcc848: Add a deep `validateConfiguration` RPC to the health-check plugin so propose-time validation matches apply-time validation.
+
+  - `validateConfiguration` (`@checkstack/healthcheck-common`): a new mutation procedure gated by `healthcheck.healthcheck.manage`, taking a proposed configuration (reusing the create skeleton) and returning `{ valid, errors: [{ path, message }] }`, mirroring automation's `validateDefinition`. It persists nothing.
+  - Shared deep validation (`@checkstack/healthcheck-backend`): `collectConfigurationIssues` resolves strategy + collectors by fully-qualified id then migrate-then-validate-strict each config via `parseStrictAssumingV1`. The GitOps reconcile path is refactored to call the same `validateVersionedConfigStrict`, so create / gitops-apply / the new RPC share one implementation.
+  - `healthcheck.propose`'s dry-run (`@checkstack/ai-backend`) now calls `validateConfiguration` as its validation authority, so a wrong config type or a typo'd key surfaces at propose time, bringing it to the same deep-validate level `automation.propose` already has.
+
+  State and scale: no durable state; `validateConfiguration` is a pure read against the in-process registries plus zod validation, identical on every pod.
+
+  This is a beta minor.
+
+### Patch Changes
+
+- 9dcc848: Input-validation and error-mapping hardening found by a fuzzing pass against the built container.
+
+  - backend: a Postgres driver error caused by bad client input no longer surfaces as a `500`. The `/api` and `/rest` dispatchers now map the relevant SQLSTATE classes to the correct status - `22P02`/`22003`/`22001`/`22007` (malformed/out-of-range/over-long/bad-date value), `23502`/`23503`/`23514` (missing/dangling/check-failed) to `400`, and `23505` (unique violation) to `409` - and log them at `warn` (client mistake), not `error`. The client-facing message is generic so column/constraint names are never leaked; genuine unknown faults still log at `error` and 500. Previously a `where id = $1` with a non-uuid `$1` (or an over-long string, or a foreign-key miss in `addSystemToGroup`) reached the driver and 500'd, making routine probing look like a server outage and burying real 500s.
+  - slo-common: **fixes a stored cluster-wide DoS.** `windowDays` was accepted up to `2^53`, but the SLO engine derives window boundaries with `Date(now - windowDays * 86_400_000)` - a large value overflows past the max representable `Date` and yields `Invalid Date`. That objective committed fine, then every subsequent read of the system's objectives threw `RangeError: Invalid time value` during serialization (a 500 readable by anyone with SLO read access, on any pod). `windowDays` is now bounded to 1..3650 days at the contract, the GitOps `kind: SLO` spec, and the update path via a single shared `SloWindowDaysSchema`, so the poison row can never be created.
+  - slo-common + healthcheck-common: SLO `getDailySnapshots` and the healthcheck history endpoints (`getHistory`, `getDetailedHistory`, `getAggregatedHistory`, `getDetailedAggregatedHistory`, `getRunsForAnalysis`) declared their `startDate`/`endDate` params as `z.date()`, which a `/rest/...` string param can never satisfy - so those endpoints 400'd on the entire REST surface. They now use `z.coerce.date()`, accepting both the REST string shape and the native RPC `Date`.
+  - healthcheck-common: `intervalSeconds` was `z.number().min(1)` with no `.int()` and no upper bound, so a fractional or out-of-range value reached the DB and failed at insert (the column is a 32-bit int). It is now `.int().min(1).max(2_592_000)` (1 second .. 30 days), applied to both create and update (the update schema is the create partial).
+  - catalog-common: system/group/environment names were bare `z.string()` (environment was `.min(1)` only), so empty, whitespace-only, and 100KB+ names reached the DB - the huge ones surfaced as 500s when parameter binding blew up. Names are now `trim().min(1).max(200)` via a shared schema.
+
+    **BREAKING:** `getSystemContacts` is now `userType: "authenticated"` (was `"public"`). System contacts carry PII (user id, name, email); the public read leaked them to anonymous status-page visitors. Anonymous callers now receive `401` for this one endpoint; the system detail page already renders "No contacts assigned" for anonymous viewers, so the UI degrades gracefully. All other catalog reads remain public.
+
+  - catalog-frontend: the system detail page skips the `getSystemContacts` request entirely for anonymous viewers (it would now `401`) and falls back to the empty state.
+
+  This is a beta release: the breaking contact-visibility change ships as a minor bump per the beta versioning policy, not a major.
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/notification-common@1.3.0
+  - @checkstack/catalog-common@2.3.0
+  - @checkstack/common@0.13.0
+  - @checkstack/signal-common@0.2.6
+
 ## 1.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {

package/src/index.ts

@@ -84,3 +84,24 @@ export const SYSTEM_STATUS_CHANGED = createSignal({
     newStatus: z.enum(["healthy", "degraded", "unhealthy"]),
   }),
 });
+
+/**
+ * Broadcast when the executor FAILED to resolve a system's environments from
+ * the catalog at run time and DEGRADED to a single env-less run (fail-open).
+ *
+ * This is the durable-misconfig / catalog-outage observability signal: a
+ * `logger.warn` alone is easy to miss, so this counter-style signal makes the
+ * degradation observable (dashboards / alerts can count it). The check still
+ * runs (env-less) — this signals that per-environment fan-out was skipped for
+ * this tick, NOT that the check failed.
+ */
+export const ENVIRONMENT_RESOLUTION_FAILED = createSignal({
+  pluginMetadata,
+  event: "environment.resolution_failed",
+  payloadSchema: z.object({
+    systemId: z.string(),
+    configurationId: z.string(),
+    /** The error message that caused the fall-back to an env-less run. */
+    error: z.string(),
+  }),
+});

package/src/rpc-contract.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import type { ZodType } from "zod";
+import { healthCheckContract } from "./rpc-contract";
+
+/**
+ * Guards the REST-compatibility fix: history date params were `z.date()`, which
+ * a `/rest/...` string param can never satisfy, so every REST history call
+ * 400'd. `z.coerce.date()` accepts both the REST string shape and the native RPC
+ * Date shape.
+ */
+function inputSchemaFor(procName: keyof typeof healthCheckContract): ZodType {
+  const proc = healthCheckContract[procName] as unknown as Record<
+    string,
+    unknown
+  >;
+  const orpc = proc["~orpc"] as { inputSchema?: ZodType };
+  if (!orpc.inputSchema) throw new Error(`${String(procName)} has no input`);
+  return orpc.inputSchema;
+}
+
+describe("history endpoints coerce string date params (REST compatibility)", () => {
+  test("getAggregatedHistory accepts ISO date strings", () => {
+    const parsed = inputSchemaFor("getAggregatedHistory").safeParse({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+      startDate: "2026-01-01T00:00:00.000Z",
+      endDate: "2026-02-01T00:00:00.000Z",
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      const data = parsed.data as { startDate: Date };
+      expect(data.startDate).toBeInstanceOf(Date);
+    }
+  });
+
+  test("getHistory accepts ISO date strings on its optional date params", () => {
+    const parsed = inputSchemaFor("getHistory").safeParse({
+      systemId: "sys-1",
+      startDate: "2026-01-01T00:00:00.000Z",
+      sortOrder: "desc",
+    });
+    expect(parsed.success).toBe(true);
+  });
+});

package/src/rpc-contract.ts

@@ -8,6 +8,8 @@ import {
   HealthCheckConfigurationSchema,
   CreateHealthCheckConfigurationSchema,
   UpdateHealthCheckConfigurationSchema,
+  ValidateConfigurationInputSchema,
+  ValidateConfigurationResultSchema,
   AssociateHealthCheckSchema,
   HealthCheckRunSchema,
   HealthCheckRunPublicSchema,
@@ -182,6 +184,21 @@ export const healthCheckContract = {
     .input(CreateHealthCheckConfigurationSchema)
     .output(HealthCheckConfigurationSchema),
 
+  /**
+   * Deep-validate a proposed health-check configuration WITHOUT persisting it.
+   * Runs the SAME strategy/collector resolution + migrate-then-validate-strict
+   * logic the create / gitops-apply path uses, so propose-time errors match
+   * apply-time errors. Gated by `configuration.manage` (the privilege the
+   * create form requires); the mirror of automation's `validateDefinition`.
+   */
+  validateConfiguration: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [healthCheckAccess.configuration.manage],
+  })
+    .input(ValidateConfigurationInputSchema)
+    .output(ValidateConfigurationResultSchema),
+
   updateConfiguration: proc({
     operationType: "mutation",
     userType: "authenticated",
@@ -248,6 +265,11 @@ export const healthCheckContract = {
           stateThresholds: StateThresholdsSchema.optional(),
           /** IDs of satellites assigned to execute this health check */
           satelliteIds: z.array(z.string()).optional(),
+          /**
+           * Per-assignment environment selector. null = all current
+           * environments; [] = opt out (env-less); non-empty = those ids.
+           */
+          environmentIds: z.array(z.string()).nullable().optional(),
           /** Whether to also run this check locally on the core (default: true) */
           includeLocal: z.boolean(),
           /** Per-association notification policy (omitted = platform defaults) */
@@ -356,8 +378,8 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string().optional(),
         configurationId: z.string().optional(),
-        startDate: z.date().optional(),
-        endDate: z.date().optional(),
+        startDate: z.coerce.date().optional(),
+        endDate: z.coerce.date().optional(),
         /** Filter by source: "local" = core only, satellite UUID = specific satellite, undefined = all */
         sourceFilter: z.string().optional(),
         /** Restrict runs to the listed statuses. Omitted/empty = no filter. */
@@ -383,8 +405,8 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string().optional(),
         configurationId: z.string().optional(),
-        startDate: z.date().optional(),
-        endDate: z.date().optional(),
+        startDate: z.coerce.date().optional(),
+        endDate: z.coerce.date().optional(),
         /** Filter by source: "local" = core only, satellite UUID = specific satellite, undefined = all */
         sourceFilter: z.string().optional(),
         /** Restrict runs to the listed statuses. Omitted/empty = no filter. */
@@ -422,8 +444,8 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string(),
         configurationId: z.string(),
-        startDate: z.date(),
-        endDate: z.date(),
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
         /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
         targetPoints: z.number().min(10).max(2000).default(500),
       }),
@@ -445,8 +467,8 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string(),
         configurationId: z.string(),
-        startDate: z.date(),
-        endDate: z.date(),
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
         /** Filter by source: "local" = core only, satellite UUID = specific satellite, undefined = all */
         sourceFilter: z.string().optional(),
         /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
@@ -623,7 +645,7 @@ export const healthCheckContract = {
   })
     .input(
       z.object({
-        startDate: z.date(),
+        startDate: z.coerce.date(),
         limitPerAssignment: z.number().optional().default(200),
       }),
     )

package/src/schemas.ts

@@ -97,7 +97,9 @@ export const CreateHealthCheckConfigurationSchema = z.object({
   name: z.string().min(1),
   strategyId: z.string().min(1),
   config: z.record(z.string(), z.unknown()),
-  intervalSeconds: z.number().min(1),
+  // Bounded: a non-integer or out-of-range value previously reached the DB and
+  // failed at insert (the column is a 32-bit int). 1 second .. 30 days.
+  intervalSeconds: z.number().int().min(1).max(2_592_000),
   /** Optional collector configurations */
   collectors: z.array(CollectorConfigEntrySchema).optional(),
 });
@@ -106,6 +108,39 @@ export type CreateHealthCheckConfiguration = z.infer<
   typeof CreateHealthCheckConfigurationSchema
 >;
 
+/**
+ * Input for the `validateConfiguration` RPC: a proposed (not-yet-persisted)
+ * health-check configuration. Reuses the create skeleton so the same
+ * name/strategyId/config/intervalSeconds/collectors shape is validated at
+ * propose time as is at apply time.
+ */
+export const ValidateConfigurationInputSchema =
+  CreateHealthCheckConfigurationSchema;
+
+export type ValidateConfigurationInput = z.infer<
+  typeof ValidateConfigurationInputSchema
+>;
+
+/**
+ * Result of `validateConfiguration`: `valid` plus a flat list of structured
+ * issues. `path`s are dot-joinable for display, e.g. `config.url` or
+ * `collectors.0.config.path`. Mirrors automation's `validateDefinition`
+ * result so consumers (the AI propose tool, the UI) handle both identically.
+ */
+export const ValidateConfigurationResultSchema = z.object({
+  valid: z.boolean(),
+  errors: z.array(
+    z.object({
+      path: z.array(z.union([z.string(), z.number()])),
+      message: z.string(),
+    }),
+  ),
+});
+
+export type ValidateConfigurationResult = z.infer<
+  typeof ValidateConfigurationResultSchema
+>;
+
 export const UpdateHealthCheckConfigurationSchema =
   CreateHealthCheckConfigurationSchema.partial();
 
@@ -245,6 +280,14 @@ export const AssociateHealthCheckSchema = z.object({
   stateThresholds: StateThresholdsSchema.optional(),
   /** IDs of satellites assigned to execute this health check */
   satelliteIds: z.array(z.string()).optional(),
+  /**
+   * Per-assignment environment selector for per-environment fan-out.
+   * `null`/omitted = all environments the system currently belongs to;
+   * non-empty array = exactly those (intersected with current membership);
+   * empty array `[]` = opt out (run once with no environment). `null` and
+   * `[]` are semantically distinct.
+   */
+  environmentIds: z.array(z.string()).nullable().optional(),
   /** Whether to also run this check locally on the core instance (default: true) */
   includeLocal: z.boolean().default(true),
   /** Per-association notification policy. Defaults applied when omitted. */
@@ -267,6 +310,11 @@ export const HealthCheckRunSchema = z.object({
   result: z.record(z.string(), z.unknown()),
   timestamp: z.date(),
   latencyMs: z.number().optional(),
+  /**
+   * Environment this run executed for (per-environment fan-out). undefined =
+   * env-less run (the opt-out / no-membership case).
+   */
+  environmentId: z.string().optional(),
   /** Source ID for result attribution (null = local core, UUID = satellite) */
   sourceId: z.string().optional(),
   /** Human-readable source label (e.g. "Local" or "EU West (eu-west-1)") */
@@ -307,6 +355,11 @@ export const HealthCheckRunPublicSchema = z.object({
   status: HealthCheckStatusSchema,
   timestamp: z.date(),
   latencyMs: z.number().optional(),
+  /**
+   * Environment this run executed for (per-environment fan-out). undefined =
+   * env-less run (the opt-out / no-membership case).
+   */
+  environmentId: z.string().optional(),
   /** Source ID for result attribution (null = local core, UUID = satellite) */
   sourceId: z.string().optional(),
   /** Human-readable source label (e.g. "Local" or "EU West (eu-west-1)") */