@checkstack/ai-backend 0.2.0 → 0.3.0

package/src/system-signals-contributor.test.ts

@@ -0,0 +1,162 @@
+import { describe, test, expect, mock } from "bun:test";
+import { access } from "@checkstack/common";
+import type { AuthUser } from "@checkstack/backend-api";
+import type { SystemSignal, SystemSignalsMap } from "@checkstack/catalog-common";
+import {
+  createGatedSystemSignalsContributor,
+  type SystemAccessResolver,
+} from "./system-signals-contributor";
+
+// A read rule for a fictional "demo" plugin: id "thing.read", qualified
+// "demo.thing.read", qualified resource type "demo.thing".
+const rule = access("thing", "read", "View things", { pluginId: "demo" });
+
+const signal = (source: string): SystemSignal => ({
+  source,
+  tone: "error",
+  label: "Problem",
+});
+
+const globalSignals: SystemSignalsMap = {
+  sysA: [signal("demo")],
+  sysB: [signal("demo")],
+};
+
+/** A resolver that returns a fixed accessible subset and records its args. */
+function stubResolver(accessible: string[]): {
+  resolver: SystemAccessResolver;
+  calls: Array<Parameters<SystemAccessResolver["accessibleSystemIds"]>[0]>;
+} {
+  const calls: Array<
+    Parameters<SystemAccessResolver["accessibleSystemIds"]>[0]
+  > = [];
+  return {
+    calls,
+    resolver: {
+      accessibleSystemIds: async (args) => {
+        calls.push(args);
+        return accessible.filter((id) => args.systemIds.includes(id));
+      },
+    },
+  };
+}
+
+const userWith = (accessRules: string[]): AuthUser => ({
+  type: "user",
+  id: "u1",
+  accessRules,
+});
+
+describe("createGatedSystemSignalsContributor", () => {
+  test("global-rule principal sees every system; resolver is not consulted", async () => {
+    const read = mock(async () => globalSignals);
+    const { resolver, calls } = stubResolver([]);
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: read,
+    });
+
+    const result = await contributor.read({
+      principal: userWith(["demo.thing.read"]),
+    });
+
+    expect(result.accessible).toBe(true);
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+    expect(read).toHaveBeenCalledTimes(1);
+    expect(calls).toHaveLength(0); // global access skips the team resolver
+  });
+
+  test("wildcard grant is treated as global", async () => {
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver: stubResolver([]).resolver,
+      readSignals: async () => globalSignals,
+    });
+    const result = await contributor.read({ principal: userWith(["*"]) });
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("service principals are trusted (treated as global)", async () => {
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver: stubResolver([]).resolver,
+      readSignals: async () => globalSignals,
+    });
+    const principal: AuthUser = { type: "service", pluginId: "svc" };
+    const result = await contributor.read({ principal });
+    expect(result.accessible).toBe(true);
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("a manage grant satisfies the read rule (escalation) and sees all", async () => {
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver: stubResolver([]).resolver,
+      readSignals: async () => globalSignals,
+    });
+    const result = await contributor.read({
+      principal: userWith(["demo.thing.manage"]),
+    });
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("non-global user is filtered to team-granted systems (correct resourceType)", async () => {
+    const read = mock(async () => globalSignals);
+    const { resolver, calls } = stubResolver(["sysB"]);
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: read,
+    });
+
+    const result = await contributor.read({ principal: userWith([]) });
+
+    expect(result.accessible).toBe(true);
+    expect(Object.keys(result.signals)).toEqual(["sysB"]); // sysA filtered out
+    expect(read).toHaveBeenCalledTimes(1);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      userId: "u1",
+      userType: "user",
+      resourceType: "demo.thing", // qualifyResourceType(pluginId, resource)
+      action: "read",
+      hasGlobalAccess: false,
+    });
+    expect(calls[0].systemIds.sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("non-global user with no team grants is reported inaccessible", async () => {
+    const { resolver } = stubResolver([]); // grants nothing
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: async () => globalSignals,
+    });
+
+    const result = await contributor.read({ principal: userWith([]) });
+
+    expect(result).toEqual({ accessible: false, signals: {} });
+  });
+
+  test("globally-clear source: accessible with no signals, resolver not called", async () => {
+    const { resolver, calls } = stubResolver([]);
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: async () => ({}),
+    });
+
+    const result = await contributor.read({ principal: userWith([]) });
+
+    expect(result).toEqual({ accessible: true, signals: {} });
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/system-signals-contributor.ts

@@ -0,0 +1,129 @@
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import type { AccessRule } from "@checkstack/common";
+import { isAccessRuleSatisfied, qualifyResourceType } from "@checkstack/common";
+import { AuthApi } from "@checkstack/auth-common";
+import type { SystemSignalsMap } from "@checkstack/catalog-common";
+import {
+  principalGrantedRuleIds,
+  type SystemSignalsContributor,
+} from "./extension-points";
+
+/**
+ * Resolves the subset of `systemIds` a non-global principal may see for a
+ * resource type, applying the SAME team/instance grants the RPC middleware
+ * enforces for list/record endpoints (via auth's `getAccessibleResourceIds`).
+ */
+export interface SystemAccessResolver {
+  accessibleSystemIds(args: {
+    userId: string;
+    userType: "user" | "application";
+    resourceType: string;
+    systemIds: string[];
+    action: "read" | "manage";
+    hasGlobalAccess: boolean;
+  }): Promise<string[]>;
+}
+
+/**
+ * Build a {@link SystemAccessResolver} backed by the auth plugin's
+ * `getAccessibleResourceIds` S2S query - the exact primitive the RPC middleware
+ * uses to filter list/record endpoints by team grants. A plugin gets its
+ * `rpcClient` from `coreServices.rpcClient` in `init`.
+ */
+export function createSystemAccessResolver(
+  rpcClient: RpcClient,
+): SystemAccessResolver {
+  const authClient = rpcClient.forPlugin(AuthApi);
+  return {
+    accessibleSystemIds: ({
+      userId,
+      userType,
+      resourceType,
+      systemIds,
+      action,
+      hasGlobalAccess,
+    }) =>
+      authClient.getAccessibleResourceIds({
+        userId,
+        userType,
+        resourceType,
+        resourceIds: systemIds,
+        action,
+        hasGlobalAccess,
+      }),
+  };
+}
+
+/**
+ * Build a {@link SystemSignalsContributor} from a GLOBAL signal reader, applying
+ * the per-source access gate centrally so every source enforces it identically
+ * (and the same way the matching bulk RPC does):
+ *
+ * - A principal holding the global rule - including trusted service principals,
+ *   which {@link principalGrantedRuleIds} maps to the wildcard - sees every
+ *   system the source reports.
+ * - A real user / application WITHOUT the global rule sees only the systems its
+ *   TEAM grants allow, via {@link SystemAccessResolver} (the same instance/team
+ *   filtering the bulk RPC applies), so `system.issues` neither under- nor
+ *   over-reports relative to the per-domain UI.
+ * - Any other principal without the global rule (anonymous, or a service lacking
+ *   the wildcard) sees nothing.
+ *
+ * `readSignals` MUST return problem signals for ALL systems globally; the gate
+ * filters them. It is not called for a principal that can see nothing, so a
+ * no-access principal triggers no query.
+ */
+export function createGatedSystemSignalsContributor({
+  sourceId,
+  accessRule,
+  resolver,
+  readSignals,
+}: {
+  sourceId: string;
+  accessRule: AccessRule;
+  resolver: SystemAccessResolver;
+  readSignals: () => Promise<SystemSignalsMap>;
+}): SystemSignalsContributor {
+  const resourceType = qualifyResourceType(
+    accessRule.pluginId,
+    accessRule.resource,
+  );
+  return {
+    sourceId,
+    read: async ({ principal }: { principal: AuthUser }) => {
+      const hasGlobalAccess = isAccessRuleSatisfied(
+        principalGrantedRuleIds(principal),
+        accessRule,
+      );
+      if (hasGlobalAccess) {
+        return { accessible: true, signals: await readSignals() };
+      }
+      // Only real users / applications can carry per-team instance grants.
+      if (principal.type !== "user" && principal.type !== "application") {
+        return { accessible: false, signals: {} };
+      }
+      const signals = await readSignals();
+      const systemIds = Object.keys(signals);
+      if (systemIds.length === 0) {
+        // Source is globally clear: nothing to report and nothing to hide.
+        return { accessible: true, signals: {} };
+      }
+      const accessibleIds = new Set(
+        await resolver.accessibleSystemIds({
+          userId: principal.id,
+          userType: principal.type,
+          resourceType,
+          systemIds,
+          action: "read",
+          hasGlobalAccess: false,
+        }),
+      );
+      const filtered: SystemSignalsMap = {};
+      for (const [systemId, sigs] of Object.entries(signals)) {
+        if (accessibleIds.has(systemId)) filtered[systemId] = sigs;
+      }
+      // Accessible iff the principal may see at least one affected system.
+      return { accessible: accessibleIds.size > 0, signals: filtered };
+    },
+  };
+}

package/src/tools/system-issues.test.ts

@@ -0,0 +1,236 @@
+import { describe, test, expect } from "bun:test";
+import type { AuthUser } from "@checkstack/backend-api";
+import type { SystemSignal, SystemSignalsMap } from "@checkstack/catalog-common";
+import type {
+  SystemSignalsContributor,
+  SystemSignalsContribution,
+} from "../extension-points";
+import {
+  mergeSystemSignalsMaps,
+  collectSystemSignals,
+  toSystemIssuesOutput,
+  type SystemSignalsCollection,
+} from "./system-issues";
+
+const signal = (over: Partial<SystemSignal> = {}): SystemSignal => ({
+  source: "incident",
+  tone: "error",
+  label: "Critical incident",
+  ...over,
+});
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.read"],
+};
+
+/** A contributor that is accessible and returns `signals`. */
+const ok = (
+  sourceId: string,
+  signals: SystemSignalsMap,
+): SystemSignalsContributor => ({
+  sourceId,
+  read: async (): Promise<SystemSignalsContribution> => ({
+    accessible: true,
+    signals,
+  }),
+});
+
+/** A contributor the principal cannot access. */
+const denied = (sourceId: string): SystemSignalsContributor => ({
+  sourceId,
+  read: async (): Promise<SystemSignalsContribution> => ({
+    accessible: false,
+    signals: {},
+  }),
+});
+
+/** A contributor that throws while reading. */
+const throwing = (sourceId: string): SystemSignalsContributor => ({
+  sourceId,
+  read: async (): Promise<SystemSignalsContribution> => {
+    throw new Error(`${sourceId} exploded`);
+  },
+});
+
+const emptyCollection = (
+  merged: SystemSignalsMap,
+): SystemSignalsCollection => ({
+  merged,
+  checkedSources: [],
+  inaccessibleSources: [],
+  failedSources: [],
+});
+
+describe("mergeSystemSignalsMaps", () => {
+  test("merges two maps by systemId, concatenating signal arrays", () => {
+    const a: SystemSignalsMap = {
+      sysA: [signal({ source: "incident", label: "Incident" })],
+      sysB: [signal({ source: "incident", label: "B incident" })],
+    };
+    const b: SystemSignalsMap = {
+      sysA: [signal({ source: "slo", tone: "warn", label: "SLO at risk" })],
+      sysC: [signal({ source: "anomaly", tone: "warn", label: "Anomaly" })],
+    };
+
+    const merged = mergeSystemSignalsMaps([a, b]);
+
+    expect(Object.keys(merged).sort()).toEqual(["sysA", "sysB", "sysC"]);
+    // sysA gets both sources concatenated.
+    expect(merged.sysA).toHaveLength(2);
+    expect(merged.sysA.map((s) => s.source)).toEqual(["incident", "slo"]);
+    expect(merged.sysB).toHaveLength(1);
+    expect(merged.sysC).toHaveLength(1);
+  });
+
+  test("does not mutate the input maps", () => {
+    const a: SystemSignalsMap = { sysA: [signal()] };
+    const b: SystemSignalsMap = { sysA: [signal({ source: "slo" })] };
+
+    mergeSystemSignalsMaps([a, b]);
+
+    expect(a.sysA).toHaveLength(1);
+    expect(b.sysA).toHaveLength(1);
+  });
+
+  test("skips empty signal arrays", () => {
+    const merged = mergeSystemSignalsMaps([{ sysA: [] }, { sysB: [signal()] }]);
+    expect(Object.keys(merged)).toEqual(["sysB"]);
+  });
+});
+
+describe("collectSystemSignals", () => {
+  test("merges signals from accessible contributors and lists them as checked", async () => {
+    const contributors = [
+      ok("incident", { sysA: [signal({ source: "incident" })] }),
+      ok("slo", {
+        sysA: [signal({ source: "slo", tone: "warn", label: "SLO" })],
+        sysB: [signal({ source: "slo", tone: "warn", label: "SLO B" })],
+      }),
+    ];
+
+    const result = await collectSystemSignals({ contributors, principal });
+
+    expect(result.merged.sysA.map((s) => s.source)).toEqual([
+      "incident",
+      "slo",
+    ]);
+    expect(result.merged.sysB).toHaveLength(1);
+    expect(result.checkedSources.sort()).toEqual(["incident", "slo"]);
+    expect(result.inaccessibleSources).toEqual([]);
+    expect(result.failedSources).toEqual([]);
+  });
+
+  test("reports an inaccessible source distinctly (not as empty/clear)", async () => {
+    const contributors = [
+      denied("incident"),
+      ok("slo", { sysA: [signal({ source: "slo" })] }),
+    ];
+
+    const result = await collectSystemSignals({ contributors, principal });
+
+    // The denied source contributes no signals but IS surfaced so the model
+    // can say "could not check incidents" instead of "no incidents".
+    expect(Object.keys(result.merged)).toEqual(["sysA"]);
+    expect(result.inaccessibleSources).toEqual(["incident"]);
+    expect(result.checkedSources).toEqual(["slo"]);
+    expect(result.failedSources).toEqual([]);
+  });
+
+  test("reports a throwing contributor as failed without breaking the call", async () => {
+    const contributors = [
+      throwing("boom"),
+      ok("incident", { sysA: [signal({ source: "incident" })] }),
+    ];
+
+    const result = await collectSystemSignals({ contributors, principal });
+
+    expect(Object.keys(result.merged)).toEqual(["sysA"]);
+    expect(result.failedSources).toEqual(["boom"]);
+    expect(result.checkedSources).toEqual(["incident"]);
+  });
+
+  test("no contributors produces no entries and empty coverage", async () => {
+    const result = await collectSystemSignals({ contributors: [], principal });
+    expect(result.merged).toEqual({});
+    expect(result.checkedSources).toEqual([]);
+    expect(result.inaccessibleSources).toEqual([]);
+    expect(result.failedSources).toEqual([]);
+  });
+});
+
+describe("toSystemIssuesOutput", () => {
+  test("groups signals by system and counts totals", () => {
+    const out = toSystemIssuesOutput({
+      collection: emptyCollection({
+        sysA: [signal({ source: "incident" }), signal({ source: "slo" })],
+        sysB: [signal({ source: "anomaly" })],
+      }),
+    });
+
+    expect(out.totalSystems).toBe(2);
+    expect(out.totalSignals).toBe(3);
+    const sysA = out.systems.find((s) => s.systemId === "sysA");
+    expect(sysA?.signals.map((s) => s.source)).toEqual(["incident", "slo"]);
+  });
+
+  test("passes per-source coverage through to the output", () => {
+    const out = toSystemIssuesOutput({
+      collection: {
+        merged: { sysA: [signal()] },
+        checkedSources: ["incident", "slo"],
+        inaccessibleSources: ["healthcheck"],
+        failedSources: ["dependency"],
+      },
+    });
+
+    expect(out.checkedSources).toEqual(["incident", "slo"]);
+    expect(out.inaccessibleSources).toEqual(["healthcheck"]);
+    expect(out.failedSources).toEqual(["dependency"]);
+  });
+
+  test("narrows to the requested systemIds", () => {
+    const out = toSystemIssuesOutput({
+      collection: emptyCollection({
+        sysA: [signal()],
+        sysB: [signal()],
+      }),
+      systemIds: ["sysB"],
+    });
+
+    expect(out.systems.map((s) => s.systemId)).toEqual(["sysB"]);
+    expect(out.totalSystems).toBe(1);
+  });
+
+  test("drops href/accessRule/iconName, keeps source/tone/label/detail/since", () => {
+    const out = toSystemIssuesOutput({
+      collection: emptyCollection({
+        sysA: [
+          signal({
+            detail: "2 of 3 checks failing",
+            since: "2026-06-07T00:00:00Z",
+            href: "/checkstack/x",
+            accessRule: {
+              id: "x",
+              resource: "x",
+              level: "read",
+              pluginId: "p",
+              description: "view x",
+            },
+            iconName: "TriangleAlert",
+          }),
+        ],
+      }),
+    });
+
+    const s = out.systems[0].signals[0];
+    expect(s).toEqual({
+      source: "incident",
+      tone: "error",
+      label: "Critical incident",
+      detail: "2 of 3 checks failing",
+      since: "2026-06-07T00:00:00Z",
+    });
+  });
+});