@checkstack/healthcheck-backend 1.11.1 → 1.13.0

package/src/history-access.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthService, AuthUser } from "@checkstack/backend-api";
+import {
+  canReadRunScope,
+  hasGlobalHistoryAccess,
+  listManageableSystemIds,
+  listTeamManageableConfigurationIds,
+  resolveHistoryScope,
+} from "./history-access";
+
+/**
+ * Regression guard for the run-history authorization: global
+ * `configuration.manage` (or wildcard/service) yields unrestricted access, a
+ * team-scoped caller is restricted to runs of their granted CONFIGURATIONS
+ * plus all runs of the SYSTEMS they manage (a system's owning team sees every
+ * run of that system, whoever owns the configuration), anyone else is
+ * forbidden, and any auth (S2S) failure fails CLOSED.
+ */
+
+const QUALIFIED_MANAGE = "healthcheck.healthcheck.manage";
+const QUALIFIED_SYSTEM_MANAGE = "catalog.system.manage";
+
+const realUser = (accessRules: string[]): AuthUser => ({
+  type: "user",
+  id: "u1",
+  accessRules,
+});
+
+// Cast is unavoidable for a partial mock: the helpers only touch
+// `listAccessibleObjectIds` / `check`, and implementing the full AuthService
+// here would just be noise.
+const authWith = (impl: Partial<AuthService>): AuthService =>
+  impl as unknown as AuthService;
+
+describe("hasGlobalHistoryAccess", () => {
+  test("true for global manage, wildcard, and services; false otherwise", () => {
+    expect(hasGlobalHistoryAccess(realUser([QUALIFIED_MANAGE]))).toBe(true);
+    expect(hasGlobalHistoryAccess(realUser(["*"]))).toBe(true);
+    expect(hasGlobalHistoryAccess({ type: "service", pluginId: "slo" })).toBe(
+      true,
+    );
+    expect(hasGlobalHistoryAccess(realUser(["healthcheck.healthcheck.read"]))).toBe(
+      false,
+    );
+    expect(hasGlobalHistoryAccess(undefined)).toBe(false);
+  });
+});
+
+describe("resolveHistoryScope", () => {
+  test("global manage rule yields the unfiltered feed", () => {
+    expect(
+      resolveHistoryScope({
+        user: realUser([QUALIFIED_MANAGE]),
+        accessibleConfigurationIds: [],
+        accessibleSystemIds: [],
+      }),
+    ).toEqual({ kind: "all" });
+  });
+
+  test("configuration grants scope the feed", () => {
+    expect(
+      resolveHistoryScope({
+        user: realUser([]),
+        accessibleConfigurationIds: ["cfg-1"],
+        accessibleSystemIds: [],
+      }),
+    ).toEqual({ kind: "scoped", configurationIds: ["cfg-1"], systemIds: [] });
+  });
+
+  test("system manage alone scopes the feed (owning team sees its runs)", () => {
+    expect(
+      resolveHistoryScope({
+        user: realUser([]),
+        accessibleConfigurationIds: [],
+        accessibleSystemIds: ["sys-1"],
+      }),
+    ).toEqual({ kind: "scoped", configurationIds: [], systemIds: ["sys-1"] });
+  });
+
+  test("no global rule and no grant of either kind is forbidden", () => {
+    expect(
+      resolveHistoryScope({
+        user: realUser(["healthcheck.healthcheck.read"]),
+        accessibleConfigurationIds: [],
+        accessibleSystemIds: [],
+      }),
+    ).toEqual({ kind: "forbidden" });
+  });
+
+  test("missing user is forbidden", () => {
+    expect(
+      resolveHistoryScope({
+        user: undefined,
+        accessibleConfigurationIds: [],
+        accessibleSystemIds: [],
+      }),
+    ).toEqual({ kind: "forbidden" });
+  });
+
+  test("a manage rule from ANOTHER plugin does not unlock the feed", () => {
+    expect(
+      resolveHistoryScope({
+        user: realUser(["incident.incident.manage"]),
+        accessibleConfigurationIds: [],
+        accessibleSystemIds: [],
+      }),
+    ).toEqual({ kind: "forbidden" });
+  });
+});
+
+describe("listTeamManageableConfigurationIds", () => {
+  test("resolves the manage-granted subset via the auth S2S", async () => {
+    const auth = authWith({
+      listAccessibleObjectIds: async ({ objectType, action, objectIds }) => {
+        expect(objectType).toBe("healthcheck.healthcheck");
+        expect(action).toBe("manage");
+        return objectIds.filter((id) => id === "cfg-2");
+      },
+    });
+
+    await expect(
+      listTeamManageableConfigurationIds({
+        auth,
+        user: realUser([]),
+        allConfigurationIds: ["cfg-1", "cfg-2"],
+      }),
+    ).resolves.toEqual(["cfg-2"]);
+  });
+
+  test("fails CLOSED when the auth S2S errors", async () => {
+    const auth = authWith({
+      listAccessibleObjectIds: async () => {
+        throw new Error("auth down");
+      },
+    });
+
+    await expect(
+      listTeamManageableConfigurationIds({
+        auth,
+        user: realUser([]),
+        allConfigurationIds: ["cfg-1"],
+      }),
+    ).resolves.toEqual([]);
+  });
+});
+
+describe("listManageableSystemIds", () => {
+  test("resolves the team-granted subset keyed on catalog.system manage", async () => {
+    const auth = authWith({
+      listAccessibleObjectIds: async ({ objectType, action, objectIds }) => {
+        expect(objectType).toBe("catalog.system");
+        expect(action).toBe("manage");
+        return objectIds.filter((id) => id === "sys-1");
+      },
+    });
+
+    await expect(
+      listManageableSystemIds({
+        auth,
+        user: realUser([]),
+        allSystemIds: ["sys-1", "sys-2"],
+      }),
+    ).resolves.toEqual(["sys-1"]);
+  });
+
+  test("the global catalog.system.manage rule grants every system (parentScope convention)", async () => {
+    const auth = authWith({
+      listAccessibleObjectIds: async () => {
+        throw new Error("must not be called");
+      },
+    });
+
+    await expect(
+      listManageableSystemIds({
+        auth,
+        user: realUser([QUALIFIED_SYSTEM_MANAGE]),
+        allSystemIds: ["sys-1", "sys-2"],
+      }),
+    ).resolves.toEqual(["sys-1", "sys-2"]);
+  });
+
+  test("fails CLOSED when the auth S2S errors", async () => {
+    const auth = authWith({
+      listAccessibleObjectIds: async () => {
+        throw new Error("auth down");
+      },
+    });
+
+    await expect(
+      listManageableSystemIds({
+        auth,
+        user: realUser([]),
+        allSystemIds: ["sys-1"],
+      }),
+    ).resolves.toEqual([]);
+  });
+});
+
+describe("canReadRunScope", () => {
+  const scope = { configurationId: "cfg-1", systemId: "sys-1" };
+
+  test("global healthcheck manage allows without any S2S call", async () => {
+    const auth = authWith({
+      check: async () => {
+        throw new Error("must not be called");
+      },
+    });
+
+    await expect(
+      canReadRunScope({ auth, user: realUser([QUALIFIED_MANAGE]), ...scope }),
+    ).resolves.toBe(true);
+  });
+
+  test("a team grant on the CONFIGURATION allows", async () => {
+    const auth = authWith({
+      check: async ({ objectType, objectId }) => ({
+        hasAccess:
+          objectType === "healthcheck.healthcheck" && objectId === "cfg-1",
+      }),
+    });
+
+    await expect(
+      canReadRunScope({ auth, user: realUser([]), ...scope }),
+    ).resolves.toBe(true);
+  });
+
+  test("a team grant on the SYSTEM allows even without a configuration grant", async () => {
+    const auth = authWith({
+      check: async ({ objectType, objectId }) => ({
+        hasAccess: objectType === "catalog.system" && objectId === "sys-1",
+      }),
+    });
+
+    await expect(
+      canReadRunScope({ auth, user: realUser([]), ...scope }),
+    ).resolves.toBe(true);
+  });
+
+  test("the global catalog.system.manage rule allows (parentScope convention)", async () => {
+    const auth = authWith({
+      check: async () => {
+        throw new Error("must not be called");
+      },
+    });
+
+    await expect(
+      canReadRunScope({
+        auth,
+        user: realUser([QUALIFIED_SYSTEM_MANAGE]),
+        ...scope,
+      }),
+    ).resolves.toBe(true);
+  });
+
+  test("no grant of either kind denies", async () => {
+    const auth = authWith({
+      check: async () => ({ hasAccess: false }),
+    });
+
+    await expect(
+      canReadRunScope({ auth, user: realUser([]), ...scope }),
+    ).resolves.toBe(false);
+  });
+
+  test("missing user denies", async () => {
+    const auth = authWith({});
+    await expect(
+      canReadRunScope({ auth, user: undefined, ...scope }),
+    ).resolves.toBe(false);
+  });
+
+  test("fails CLOSED when the auth S2S errors", async () => {
+    const auth = authWith({
+      check: async () => {
+        throw new Error("auth down");
+      },
+    });
+
+    await expect(
+      canReadRunScope({ auth, user: realUser([]), ...scope }),
+    ).resolves.toBe(false);
+  });
+});

package/src/history-access.ts

@@ -0,0 +1,203 @@
+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";
+
+/**
+ * The qualified global rule that unlocks the UNFILTERED run-history feed.
+ * Kept in lock-step with the history procs' contract docs: their `access` is
+ * deliberately empty (the OR below is not expressible declaratively), so THIS
+ * module is the authorization for them.
+ */
+const QUALIFIED_MANAGE_RULE = qualifyAccessRuleId(
+  pluginMetadata,
+  healthCheckAccess.configuration.manage,
+);
+
+/**
+ * The parent (catalog.system) global manage rule. Follows the middleware's
+ * parentScope convention: authorizing via a parent consults the parent's own
+ * grants AND its global `{resourceType}.{action}` rule.
+ */
+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 run-history access? True for wildcard
+ * admins, global `healthcheck.healthcheck.manage` holders, and trusted
+ * services (same stance as the middleware).
+ */
+export function hasGlobalHistoryAccess(user: AuthUser | undefined): boolean {
+  if (!user) return false;
+  if (user.type === "service") return true;
+  const rules = user.accessRules ?? [];
+  return rules.includes("*") || rules.includes(QUALIFIED_MANAGE_RULE);
+}
+
+/** The outcome of authorizing the run-history FEED for the current caller. */
+export type HistoryScope =
+  /** Global manage (or wildcard/service): the caller sees every run. */
+  | { kind: "all" }
+  /**
+   * Team-scoped caller: restrict rows to runs of these configurations OR runs
+   * belonging to these systems (a system's owning team sees ALL of its runs,
+   * regardless of who owns the configuration).
+   */
+  | { kind: "scoped"; configurationIds: string[]; systemIds: string[] }
+  /** No global rule and no team grant of either kind: the read is forbidden. */
+  | { kind: "forbidden" };
+
+/**
+ * Pure decision half of the feed authorization: given the caller and their
+ * team-accessible configuration/system ids, decide the feed scope. Split from
+ * the S2S lookups so the branching is unit-testable without an auth service.
+ */
+export function resolveHistoryScope({
+  user,
+  accessibleConfigurationIds,
+  accessibleSystemIds,
+}: {
+  user: AuthUser | undefined;
+  accessibleConfigurationIds: string[];
+  accessibleSystemIds: string[];
+}): HistoryScope {
+  if (!user) return { kind: "forbidden" };
+  if (hasGlobalHistoryAccess(user)) return { kind: "all" };
+
+  if (
+    accessibleConfigurationIds.length === 0 &&
+    accessibleSystemIds.length === 0
+  ) {
+    return { kind: "forbidden" };
+  }
+  return {
+    kind: "scoped",
+    configurationIds: accessibleConfigurationIds,
+    systemIds: accessibleSystemIds,
+  };
+}
+
+/**
+ * Resolve which of `allConfigurationIds` the caller may MANAGE via team
+ * grants on the CONFIGURATION itself. FAILS CLOSED: an S2S error yields an
+ * empty set, i.e. narrower access, never wider.
+ */
+export async function listTeamManageableConfigurationIds({
+  auth,
+  user,
+  allConfigurationIds,
+}: {
+  auth: AuthService;
+  user: AuthUser;
+  allConfigurationIds: string[];
+}): Promise<string[]> {
+  if (!isGrantHolder(user)) return [];
+  if (allConfigurationIds.length === 0) return [];
+  try {
+    return await auth.listAccessibleObjectIds({
+      userId: user.id,
+      userType: user.type,
+      objectType: healthCheckResourceTypes.configuration,
+      objectIds: allConfigurationIds,
+      action: "manage",
+      hasGlobalAccess: false,
+    });
+  } catch {
+    // SECURITY: fail closed - an auth outage must not widen the feed.
+    return [];
+  }
+}
+
+/**
+ * Resolve which of `allSystemIds` the caller may MANAGE - via a team grant on
+ * the system, or via the global `catalog.system.manage` rule (the parentScope
+ * convention). A system's owning team sees every run of that system, even for
+ * configurations owned elsewhere. FAILS CLOSED on S2S errors.
+ */
+export async function listManageableSystemIds({
+  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_MANAGE_RULE)) return allSystemIds;
+  try {
+    return await auth.listAccessibleObjectIds({
+      userId: user.id,
+      userType: user.type,
+      objectType: catalogResourceTypes.system,
+      objectIds: allSystemIds,
+      action: "manage",
+      hasGlobalAccess: false,
+    });
+  } catch {
+    // SECURITY: fail closed - an auth outage must not widen the feed.
+    return [];
+  }
+}
+
+/**
+ * Per-object check for the single-configuration history surfaces
+ * (`getRunById`, `getDetailedAggregatedHistory`): the caller may read runs of
+ * (`configurationId`, `systemId`) iff they hold global history access, a team
+ * manage grant on the CONFIGURATION, or manage access to the SYSTEM (team
+ * grant or global catalog rule). FAILS CLOSED on S2S errors.
+ */
+export async function canReadRunScope({
+  auth,
+  user,
+  configurationId,
+  systemId,
+}: {
+  auth: AuthService;
+  user: AuthUser | undefined;
+  configurationId: string;
+  systemId: string;
+}): Promise<boolean> {
+  if (!user) return false;
+  if (hasGlobalHistoryAccess(user)) return true;
+  if (!isGrantHolder(user)) return false;
+
+  const rules = user.accessRules ?? [];
+  if (rules.includes(QUALIFIED_SYSTEM_MANAGE_RULE)) return true;
+
+  try {
+    const configCheck = await auth.check({
+      userId: user.id,
+      userType: user.type,
+      objectType: healthCheckResourceTypes.configuration,
+      objectId: configurationId,
+      action: "manage",
+      hasGlobalAccess: false,
+    });
+    if (configCheck.hasAccess) return true;
+
+    const systemCheck = await auth.check({
+      userId: user.id,
+      userType: user.type,
+      objectType: catalogResourceTypes.system,
+      objectId: systemId,
+      action: "manage",
+      hasGlobalAccess: false,
+    });
+    return systemCheck.hasAccess;
+  } catch {
+    // SECURITY: fail closed - an auth outage must not widen access.
+    return false;
+  }
+}

package/src/hooks.ts

@@ -46,6 +46,12 @@ export const healthCheckHooks = {
     latencyMs: number | undefined;
     result: Record<string, unknown> | undefined;
     timestamp: string;
+    /**
+     * Environment the run was executed for. null = the env-less slice (no
+     * environment membership). Forwarded by the anomaly plugin so its inline
+     * detector resolves the per-env baseline rather than a cross-env one.
+     */
+    environmentId: string | null;
   }>("healthcheck.check.completed"),
 
   /**
@@ -64,5 +70,6 @@ export const healthCheckHooks = {
     latencyMs: number | undefined;
     result: Record<string, unknown> | undefined;
     timestamp: string;
+    environmentId: string | null;
   }>("healthcheck.check.failed"),
 } as const;

package/src/index.ts

@@ -1,12 +1,14 @@
 import {
   setupHealthCheckWorker,
   bootstrapHealthChecks,
+  recomputeSystemRollupHealth,
 } from "./queue-executor";
 import { setupRetentionJob } from "./retention-job";
 import * as schema from "./schema";
 import {
   healthCheckAccessRules,
   healthCheckAccess,
+  healthCheckResourceTypes,
   pluginMetadata,
   healthCheckContract,
   healthcheckRoutes,
@@ -242,10 +244,14 @@ export default createBackendPlugin({
         const typedDb = database as SafeDatabase<typeof schema>;
 
         // Resolve/search health-check configurations by name for the Teams admin
-        // UI (team grants are stored as opaque healthcheck.configuration:<id>
-        // rows). Lets the auth backend render grants by name and power the grant
-        // picker without depending on healthcheck internals.
-        resourceResolverRegistry.register("healthcheck.configuration", {
+        // UI (team grants are stored as opaque `<type>:<configId>` rows, where
+        // <type> is `healthCheckResourceTypes.configuration` — i.e.
+        // `healthcheck.healthcheck`, the key the RPC middleware derives from the
+        // configuration access rule's resource). This MUST match that grant key,
+        // or grant names never resolve. Lets the auth backend render grants by
+        // name and power the grant picker without depending on healthcheck
+        // internals.
+        resourceResolverRegistry.register(healthCheckResourceTypes.configuration, {
           resolveNames: async (ids) => {
             if (ids.length === 0) return new Map();
             const rows = await typedDb
@@ -480,6 +486,17 @@ export default createBackendPlugin({
           maintenanceClient,
           logger,
           signalService,
+          recomputeSystemRollupHealth: (systemId) =>
+            recomputeSystemRollupHealth({
+              systemId,
+              // Reuse the COMPUTE-ON-READ service instance bound to the
+              // `health` entity read accessor — it's the same db/registry
+              // the rollup write inside `executeHealthCheckJob` uses.
+              service,
+              getHealthEntity: () => healthEntity,
+              advisoryLock,
+              logger,
+            }),
         });
         rpc.registerRouter(healthCheckRouter, healthCheckContract);