@checkstack/healthcheck-backend 1.20.0 → 1.21.0

package/src/assignment-access.ts

@@ -0,0 +1,205 @@
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { AuthUser, AuthService } from "@checkstack/backend-api";
+import {
+  healthCheckAccess,
+  healthCheckResourceTypes,
+  pluginMetadata,
+} from "@checkstack/healthcheck-common";
+import { catalogResourceTypes } from "@checkstack/catalog-common";
+
+/**
+ * Authorization for the configuration-centric assignment reads
+ * (`getConfigurationAssignments`, and the relaxed `getConfiguration`). Their
+ * contract `access` is deliberately empty - the rule is an OR across TWO grant
+ * planes (a team grant on the CONFIGURATION, or read access to an assigned
+ * SYSTEM) that the middleware's instanceAccess modes cannot express - so THIS
+ * module is the authorization for them. Sibling of `history-access.ts`, which
+ * does the same for the run-history procs at manage level.
+ */
+
+const QUALIFIED_READ_RULE = qualifyAccessRuleId(
+  pluginMetadata,
+  healthCheckAccess.configuration.read,
+);
+const QUALIFIED_MANAGE_RULE = qualifyAccessRuleId(
+  pluginMetadata,
+  healthCheckAccess.configuration.manage,
+);
+
+/**
+ * The parent (catalog.system) global rules. Follows the middleware's
+ * parentScope convention: authorizing via a parent consults the parent's own
+ * grants AND its global `{resourceType}.{action}` rule. Manage implies read.
+ */
+const QUALIFIED_SYSTEM_READ_RULE = `${catalogResourceTypes.system}.read`;
+const QUALIFIED_SYSTEM_MANAGE_RULE = `${catalogResourceTypes.system}.manage`;
+
+/** A user/application principal (the only kinds that can hold team grants). */
+type GrantHolder = AuthUser & { type: "user" | "application" };
+
+const isGrantHolder = (user: AuthUser): user is GrantHolder =>
+  user.type === "user" || user.type === "application";
+
+/**
+ * Does the caller hold UNRESTRICTED configuration read access? True for
+ * wildcard admins, global `configuration.read` OR `configuration.manage`
+ * holders (manage implies read), and trusted services (same stance as the
+ * middleware).
+ */
+export function hasGlobalConfigurationRead(
+  user: AuthUser | undefined,
+): boolean {
+  if (!user) return false;
+  if (user.type === "service") return true;
+  const rules = user.accessRules ?? [];
+  return (
+    rules.includes("*") ||
+    rules.includes(QUALIFIED_READ_RULE) ||
+    rules.includes(QUALIFIED_MANAGE_RULE)
+  );
+}
+
+/** The outcome of authorizing the assignment-row read for the caller. */
+export type AssignmentRowScope =
+  /** Global read (or wildcard/service/config grant): every row is visible. */
+  | { kind: "all" }
+  /**
+   * System-scoped caller: restrict rows to the systems their teams may READ
+   * (a system's team sees which checks run on their system).
+   */
+  | { kind: "scoped"; systemIds: string[] }
+  /** No global rule and no grant of either kind: the read is forbidden. */
+  | { kind: "forbidden" };
+
+/**
+ * Pure decision half of the row authorization: given the caller, whether they
+ * hold a team grant on the configuration, and the system ids their teams may
+ * read, decide the row scope. Split from the S2S lookups so the branching is
+ * unit-testable without an auth service.
+ */
+export function resolveAssignmentRowScope({
+  user,
+  hasConfigurationGrant,
+  readableSystemIds,
+}: {
+  user: AuthUser | undefined;
+  hasConfigurationGrant: boolean;
+  readableSystemIds: string[];
+}): AssignmentRowScope {
+  if (!user) return { kind: "forbidden" };
+  if (hasGlobalConfigurationRead(user)) return { kind: "all" };
+  if (hasConfigurationGrant) return { kind: "all" };
+  if (readableSystemIds.length === 0) return { kind: "forbidden" };
+  return { kind: "scoped", systemIds: readableSystemIds };
+}
+
+/**
+ * Does the caller's team hold a READ grant on the configuration itself?
+ * FAILS CLOSED: an S2S error yields `false`, i.e. narrower access, never
+ * wider.
+ */
+export async function hasConfigurationReadGrant({
+  auth,
+  user,
+  configurationId,
+}: {
+  auth: AuthService;
+  user: AuthUser;
+  configurationId: string;
+}): Promise<boolean> {
+  if (!isGrantHolder(user)) return false;
+  try {
+    const result = await auth.check({
+      userId: user.id,
+      userType: user.type,
+      objectType: healthCheckResourceTypes.configuration,
+      objectId: configurationId,
+      action: "read",
+      hasGlobalAccess: false,
+    });
+    return result.hasAccess;
+  } catch {
+    // SECURITY: fail closed - an auth outage must not widen access.
+    return false;
+  }
+}
+
+/**
+ * Resolve which of `allSystemIds` the caller may READ - via a team grant on
+ * the system, or via the global `catalog.system.read`/`.manage` rule (the
+ * parentScope convention). FAILS CLOSED on S2S errors.
+ */
+export async function listReadableSystemIds({
+  auth,
+  user,
+  allSystemIds,
+}: {
+  auth: AuthService;
+  user: AuthUser;
+  allSystemIds: string[];
+}): Promise<string[]> {
+  if (!isGrantHolder(user)) return [];
+  if (allSystemIds.length === 0) return [];
+  const rules = user.accessRules ?? [];
+  if (
+    rules.includes(QUALIFIED_SYSTEM_READ_RULE) ||
+    rules.includes(QUALIFIED_SYSTEM_MANAGE_RULE)
+  ) {
+    return allSystemIds;
+  }
+  try {
+    return await auth.listAccessibleObjectIds({
+      userId: user.id,
+      userType: user.type,
+      objectType: catalogResourceTypes.system,
+      objectIds: allSystemIds,
+      action: "read",
+      hasGlobalAccess: false,
+    });
+  } catch {
+    // SECURITY: fail closed - an auth outage must not widen access.
+    return [];
+  }
+}
+
+/**
+ * Per-object check for the relaxed single-configuration read: the caller may
+ * read the configuration iff they hold global configuration read, a team READ
+ * grant on the configuration, or READ access to at least one system the
+ * configuration is assigned to (a system's team may inspect the checks that
+ * run on their system - the same exposure `getSystemConfigurations` already
+ * allows). `getAssignedSystemIds` is lazy so the assignment lookup only runs
+ * when the cheaper checks did not already decide. FAILS CLOSED on S2S errors.
+ */
+export async function canReadConfigurationScope({
+  auth,
+  user,
+  configurationId,
+  getAssignedSystemIds,
+}: {
+  auth: AuthService;
+  user: AuthUser | undefined;
+  configurationId: string;
+  getAssignedSystemIds: () => Promise<string[]>;
+}): Promise<boolean> {
+  if (!user) return false;
+  if (hasGlobalConfigurationRead(user)) return true;
+  if (!isGrantHolder(user)) return false;
+
+  if (await hasConfigurationReadGrant({ auth, user, configurationId })) {
+    return true;
+  }
+
+  try {
+    const assignedSystemIds = await getAssignedSystemIds();
+    const readable = await listReadableSystemIds({
+      auth,
+      user,
+      allSystemIds: assignedSystemIds,
+    });
+    return readable.length > 0;
+  } catch {
+    // SECURITY: fail closed - an auth outage must not widen access.
+    return false;
+  }
+}

package/src/collector-script-test.test.ts

@@ -83,6 +83,29 @@ describe("buildShellRunContextEnv", () => {
     });
     expect(env.CHECKSTACK_ENV_BASE_URL).toBe("first");
   });
+
+  test("emits CHECKSTACK_SYSTEM_<FIELD> vars for the system's custom fields", () => {
+    const env = buildShellRunContextEnv({
+      system: {
+        id: "s1",
+        name: "web-1",
+        metadata: { baseUrl: "https://sys.example.com", tier: "1" },
+      },
+    });
+    expect(env).toEqual({
+      CHECKSTACK_SYSTEM_ID: "s1",
+      CHECKSTACK_SYSTEM_NAME: "web-1",
+      CHECKSTACK_SYSTEM_BASE_URL: "https://sys.example.com",
+      CHECKSTACK_SYSTEM_TIER: "1",
+    });
+  });
+
+  test("a system field named id/name cannot clobber the structural var", () => {
+    const env = buildShellRunContextEnv({
+      system: { id: "s1", name: "web-1", metadata: { name: "nope" } },
+    });
+    expect(env.CHECKSTACK_SYSTEM_NAME).toBe("web-1");
+  });
 });
 
 describe("buildCollectorContext", () => {
@@ -126,6 +149,20 @@ describe("buildCollectorContext", () => {
       },
     });
   });
+
+  test("passes the system's metadata through to context.system", () => {
+    const ctx = buildCollectorContext({
+      config: {},
+      runContext: {
+        system: { id: "s1", name: "web-1", metadata: { baseUrl: "https://s" } },
+      },
+    });
+    expect(ctx.system).toEqual({
+      id: "s1",
+      name: "web-1",
+      metadata: { baseUrl: "https://s" },
+    });
+  });
 });
 
 describe("runCollectorScriptTest — typescript", () => {

package/src/collector-script-test.ts

@@ -32,7 +32,13 @@ export type CollectorScriptTestKind = "typescript" | "shell";
 /** Curated check/system/environment metadata a collector script can read. */
 export interface CollectorTestRunContext {
   check?: { id: string; name: string; intervalSeconds: number };
-  system?: { id: string; name: string };
+  /**
+   * The system being checked. `metadata` is its free-form custom fields,
+   * mirroring the runtime `CollectorRunContext.system` so the test panel
+   * previews the `CHECKSTACK_SYSTEM_*` / `context.system.metadata` surface the
+   * real run exposes.
+   */
+  system?: { id: string; name: string; metadata?: Record<string, unknown> };
   /**
    * The resolved environment for the previewed run. `fields` is the
    * environment's free-form custom metadata. Mirrors the runtime
@@ -85,22 +91,49 @@ export interface CollectorScriptTestDeps {
 }
 
 const CHECKSTACK_ENV_PREFIX = "CHECKSTACK_ENV_";
+const CHECKSTACK_SYSTEM_PREFIX = "CHECKSTACK_SYSTEM_";
 
 /**
- * Derive the `CHECKSTACK_ENV_<KEY>` shell var name for a custom field key.
- * Mirrors `toEnvFieldShellKey` in `@checkstack/healthcheck-script-backend`
- * (kept local - we don't import across plugins) so the test panel and the
- * real run produce identical var names. Splits camelCase, uppercases,
- * collapses non-alphanumeric runs to `_`, trims leading/trailing `_` using a
- * ReDoS-safe negative look-behind.
+ * Derive the `<prefix><KEY>` shell var name for a custom field key. Mirrors
+ * `toFieldShellKey` in `@checkstack/healthcheck-script-backend` (kept local -
+ * we don't import across plugins) so the test panel and the real run produce
+ * identical var names. Splits camelCase, uppercases, collapses non-alphanumeric
+ * runs to `_`, trims leading/trailing `_` using a ReDoS-safe negative
+ * look-behind.
  */
-function toEnvFieldShellKey(key: string): string {
+function toFieldShellKey(key: string, prefix: string): string {
   const normalized = key
     .replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2")
     .toUpperCase()
     .replaceAll(/[^A-Z0-9]+/g, "_")
     .replaceAll(/^_+|(?<!_)_+$/g, "");
-  return `${CHECKSTACK_ENV_PREFIX}${normalized}`;
+  return `${prefix}${normalized}`;
+}
+
+/**
+ * Expand a set of custom fields into `<prefix><KEY>` shell vars, mirroring
+ * `buildFieldShellEnv` in the script plugin: skip empty-normalized names, skip
+ * the reserved structural id/name vars, first-key-wins on collisions.
+ */
+function addFieldShellVars({
+  env,
+  fields,
+  prefix,
+}: {
+  env: Record<string, string>;
+  fields: Record<string, unknown>;
+  prefix: string;
+}): void {
+  const reserved = new Set([`${prefix}ID`, `${prefix}NAME`]);
+  const claimed = new Set<string>();
+  for (const [key, value] of Object.entries(fields)) {
+    const shellKey = toFieldShellKey(key, prefix);
+    if (shellKey === prefix || reserved.has(shellKey) || claimed.has(shellKey)) {
+      continue;
+    }
+    env[shellKey] = stringifyFieldValue(value);
+    claimed.add(shellKey);
+  }
 }
 
 /** Stringify a custom-field value for a shell env var. */
@@ -135,17 +168,22 @@ export function buildShellRunContextEnv(
   if (runContext?.system) {
     env.CHECKSTACK_SYSTEM_ID = runContext.system.id;
     env.CHECKSTACK_SYSTEM_NAME = runContext.system.name;
+    if (runContext.system.metadata) {
+      addFieldShellVars({
+        env,
+        fields: runContext.system.metadata,
+        prefix: CHECKSTACK_SYSTEM_PREFIX,
+      });
+    }
   }
   if (runContext?.environment) {
     env.CHECKSTACK_ENV_ID = runContext.environment.id;
     env.CHECKSTACK_ENV_NAME = runContext.environment.name;
-    const claimed = new Set<string>();
-    for (const [key, value] of Object.entries(runContext.environment.fields)) {
-      const shellKey = toEnvFieldShellKey(key);
-      if (shellKey === CHECKSTACK_ENV_PREFIX || claimed.has(shellKey)) continue;
-      env[shellKey] = stringifyFieldValue(value);
-      claimed.add(shellKey);
-    }
+    addFieldShellVars({
+      env,
+      fields: runContext.environment.fields,
+      prefix: CHECKSTACK_ENV_PREFIX,
+    });
   }
   return env;
 }

package/src/queue-executor.test.ts

@@ -347,10 +347,11 @@ describe("Queue-Based Health Check Executor", () => {
       const mockIncidentClient = createMockIncidentClient();
       const mockSignalService = createMockSignalService();
 
-      // Catalog resolves the system name.
+      // Catalog resolves the system name + free-form metadata.
       (mockCatalogClient.getSystem as any) = mock(async () => ({
         id: "system-1",
         name: "web-01",
+        metadata: { baseUrl: "https://web-01.example.com" },
       }));
 
       // configName is null -> run-context check.name must fall back to id.
@@ -470,7 +471,11 @@ describe("Queue-Based Health Check Executor", () => {
       expect(collectorExecute).toHaveBeenCalled();
       expect(capturedRunContext).toEqual({
         check: { id: "config-1", name: "config-1", intervalSeconds: 45 },
-        system: { id: "system-1", name: "web-01" },
+        system: {
+          id: "system-1",
+          name: "web-01",
+          metadata: { baseUrl: "https://web-01.example.com" },
+        },
       });
     });
 
@@ -694,6 +699,7 @@ describe("Queue-Based Health Check Executor", () => {
       collectorConfig = {},
       collectorConfigSchema = z.object({}),
       failCatalogResolution = false,
+      systemMetadata = {},
     }: {
       /** The env this job runs (`null` = an env-less job). */
       payloadEnvironmentId: string | null;
@@ -710,9 +716,11 @@ describe("Queue-Based Health Check Executor", () => {
       collectorConfigSchema?: z.ZodType<unknown>;
       /** When true, the catalog membership read REJECTS (fail-open path). */
       failCatalogResolution?: boolean;
+      /** The system's free-form catalog metadata (`{{ system.metadata.* }}`). */
+      systemMetadata?: Record<string, unknown>;
     }): Promise<{
       /** Run-context captured for the single run (empty when skipped). */
-      runs: Array<{ environment?: unknown; config?: unknown }>;
+      runs: Array<{ environment?: unknown; system?: unknown; config?: unknown }>;
       /** Payloads broadcast on `healthcheck.run.completed`, in order. */
       runCompletedPayloads: Array<Record<string, unknown>>;
     }> {
@@ -728,6 +736,7 @@ describe("Queue-Based Health Check Executor", () => {
       (mockCatalogClient.getSystem as any) = mock(async () => ({
         id: "system-1",
         name: "web-01",
+        metadata: systemMetadata,
       }));
       (mockCatalogClient as any).resolveSystemEnvironments = mock(async () => {
         if (failCatalogResolution) throw new Error("catalog unavailable");
@@ -972,6 +981,51 @@ describe("Queue-Based Health Check Executor", () => {
       expect((captured[0]?.config as { url: string }).url).toBe("/healthz");
     });
 
+    it("renders {{ system.metadata.<key> }} from the system's catalog custom fields", async () => {
+      const { runs: captured } = await runSingleEnv({
+        payloadEnvironmentId: null,
+        environmentIds: [],
+        membership: [{ id: "prod", name: "Production", metadata: {} }],
+        systemMetadata: { baseUrl: "https://sys.example.com" },
+        collectorConfig: { url: "{{ system.metadata.baseUrl }}/healthz" },
+        collectorConfigSchema: z.object({
+          url: configString({ "x-templatable": true }),
+        }),
+      });
+
+      expect(captured).toHaveLength(1);
+      expect((captured[0]?.config as { url: string }).url).toBe(
+        "https://sys.example.com/healthz",
+      );
+    });
+
+    it("namespaces metadata under .metadata so a custom field cannot shadow system.name", async () => {
+      // A metadata key literally named `name` must NOT override the structural
+      // `{{ system.name }}`; it is only reachable at `{{ system.metadata.name }}`.
+      const { runs: captured } = await runSingleEnv({
+        payloadEnvironmentId: null,
+        environmentIds: [],
+        membership: [{ id: "prod", name: "Production", metadata: {} }],
+        systemMetadata: { name: "shadow-attempt" },
+        collectorConfig: {
+          structural: "{{ system.name }}",
+          custom: "{{ system.metadata.name }}",
+        },
+        collectorConfigSchema: z.object({
+          structural: configString({ "x-templatable": true }),
+          custom: configString({ "x-templatable": true }),
+        }),
+      });
+
+      expect(captured).toHaveLength(1);
+      const config = captured[0]?.config as {
+        structural: string;
+        custom: string;
+      };
+      expect(config.structural).toBe("web-01");
+      expect(config.custom).toBe("shadow-attempt");
+    });
+
     it("runs the explicit-subset environment the payload targets", async () => {
       const { runs: captured } = await runSingleEnv({
         payloadEnvironmentId: "staging",

package/src/queue-executor.ts

@@ -767,12 +767,16 @@ async function executeHealthCheckJob(props: {
       return;
     }
 
-    // Fetch system name for signal payload
+    // Fetch system name + metadata for signal payload and run-context. The
+    // metadata is the system's free-form catalog custom fields, surfaced to
+    // config templating as `{{ system.metadata.<key> }}`.
     let systemName = systemId;
+    let systemMetadata: Record<string, unknown> = {};
     try {
       const system = await catalogClient.getSystem({ systemId });
       if (system) {
         systemName = system.name;
+        systemMetadata = system.metadata ?? {};
       }
     } catch {
       // Fall back to systemId if catalog lookup fails
@@ -980,7 +984,7 @@ async function executeHealthCheckJob(props: {
           name: configRow.configName || configId,
           intervalSeconds: configRow.interval,
         },
-        system: { id: systemId, name: systemName },
+        system: { id: systemId, name: systemName, metadata: systemMetadata },
         ...(environment
           ? {
               environment: {