@checkstack/incident-backend 1.10.0 → 1.12.0

package/src/index.ts

@@ -145,6 +145,7 @@ export default createBackendPlugin({
         rpc: coreServices.rpc,
         rpcClient: coreServices.rpcClient,
         signalService: coreServices.signalService,
+        eventBus: coreServices.eventBus,
         cacheManager: coreServices.cacheManager,
         advisoryLock: coreServices.advisoryLock,
         resourceResolverRegistry: coreServices.resourceResolverRegistry,
@@ -155,6 +156,7 @@ export default createBackendPlugin({
         rpc,
         rpcClient,
         signalService,
+        eventBus,
         cacheManager,
         advisoryLock,
         resourceResolverRegistry,
@@ -198,6 +200,7 @@ export default createBackendPlugin({
         const router = createRouter({
           service,
           signalService,
+          eventBus,
           catalogClient,
           notificationClient,
           authClient,
@@ -218,6 +221,7 @@ export default createBackendPlugin({
         for (const action of createIncidentActions({
           service,
           getIncidentEntity: () => incidentEntity,
+          eventBus,
         })) {
           automationActions.registerAction(action, pluginMetadata);
         }

package/src/notifications.test.ts

@@ -317,6 +317,187 @@ describe("notifyAffectedSystems", () => {
     });
   });
 
+  describe("update message in body", () => {
+    it("appends the escaped update message as a blockquote", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: "Rolled back the bad deploy, monitoring recovery.",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      expect(call?.body).toContain(
+        "\n\n> Rolled back the bad deploy, monitoring recovery",
+      );
+    });
+
+    it("escapes markdown control characters in the message", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: "See [here](http://evil) **now** `code`",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      // No unescaped link/bold/code syntax survives into the body.
+      expect(call?.body).not.toContain("[here](http://evil)");
+      expect(call?.body).not.toContain("**now**");
+      expect(call?.body).toContain("\\[here\\]");
+      expect(call?.body).toContain("\\*\\*now\\*\\*");
+    });
+
+    it("strips non-whitespace control characters (ESC/NUL/BEL/DEL)", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: "before\u001B\u0000\u0007\u007Fafter",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      const blockquoteLine = (call?.body ?? "").split("\n\n> ")[1] ?? "";
+      expect(blockquoteLine).toBe("beforeafter");
+      // No control characters survive into the excerpt.
+      expect(/[\u0000-\u001F\u007F-\u009F]/u.test(blockquoteLine)).toBe(
+        false,
+      );
+    });
+
+    it("escapes HTML-significant < and & so markup cannot be injected", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: "watch <img onerror=x> & <script>",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      const blockquoteLine = (call?.body ?? "").split("\n\n> ")[1] ?? "";
+      expect(blockquoteLine).not.toContain("<");
+      expect(blockquoteLine).toContain("&lt;img");
+      expect(blockquoteLine).toContain("&amp;");
+    });
+
+    it("collapses newlines so the message cannot break out of the blockquote", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: "line one\n\nline two\ninjected",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      const blockquoteLine = (call?.body ?? "").split("\n\n> ")[1] ?? "";
+      expect(blockquoteLine).not.toContain("\n");
+      expect(blockquoteLine).toBe("line one line two injected");
+    });
+
+    it("truncates an over-long message to a bounded length", async () => {
+      const longMessage = "a".repeat(1000);
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: longMessage,
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      const blockquoteLine = (call?.body ?? "").split("\n\n> ")[1] ?? "";
+      expect(blockquoteLine.endsWith("...")).toBe(true);
+      // 500 chars + the "..." indicator.
+      expect(blockquoteLine.length).toBeLessThanOrEqual(503);
+    });
+
+    it("omits the blockquote entirely for a blank/whitespace message", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "updated",
+        severity: "minor",
+        updateMessage: "   \n  ",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      expect(call?.body).not.toContain("\n\n>");
+    });
+
+    it("omits the blockquote when no message is provided", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "API Outage",
+        systemIds: ["sys-1"],
+        action: "created",
+        severity: "minor",
+      });
+
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [{ body?: string }]
+      )[0];
+      expect(call?.body).not.toContain("\n\n>");
+    });
+  });
+
   describe("error handling", () => {
     it("logs a warning but does not throw when the notify call fails", async () => {
       mockNotificationClient.notifyForSubscription.mockRejectedValue(

package/src/notifications.ts

@@ -7,6 +7,7 @@ import type { Logger } from "@checkstack/backend-api";
 import type { InferClient } from "@checkstack/common";
 import { resolveRoute } from "@checkstack/common";
 import type { NotificationApi } from "@checkstack/notification-common";
+import { buildUpdateMessageSuffix } from "@checkstack/notification-common";
 import {
   incidentRoutes,
   incidentCollapseKey,
@@ -29,6 +30,13 @@ export async function notifyAffectedSystems(props: {
   systemNames?: Map<string, string>;
   action: "created" | "updated" | "resolved" | "reopened";
   severity: string;
+  /**
+   * The latest incident update's free-text message. When present it is
+   * escaped, single-lined, truncated, and appended to the notification body as
+   * a blockquote so subscribers see WHAT changed, not just that something did.
+   * User-supplied, so it is always sanitized before it reaches a markdown body.
+   */
+  updateMessage?: string;
 }): Promise<void> {
   const {
     notificationClient,
@@ -39,6 +47,7 @@ export async function notifyAffectedSystems(props: {
     systemNames,
     action,
     severity,
+    updateMessage,
   } = props;
   void props.catalogClient;
 
@@ -64,12 +73,14 @@ export async function notifyAffectedSystems(props: {
     }),
   );
 
+  const messageSuffix = buildUpdateMessageSuffix({ message: updateMessage });
+
   try {
     await notificationClient.notifyForSubscription({
       specId: incidentSystemSubscription.specId,
       resourceKeys: uniqueSystemIds,
       title: `Incident ${actionText}: ${incidentTitle}`,
-      body: `Incident **"${incidentTitle}"** has been ${actionText}.`,
+      body: `Incident **"${incidentTitle}"** has been ${actionText}.${messageSuffix}`,
       importance,
       action: { label: "View Incident", url: incidentDetailPath },
       collapseKey: incidentCollapseKey(incidentId),

package/src/read-visibility.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from "bun:test";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { AuthService, RealUser, ServiceUser } from "@checkstack/backend-api";
+import {
+  incidentAccess,
+  pluginMetadata,
+  type IncidentVisibility,
+} from "@checkstack/incident-common";
+import {
+  isVisibleAtAudience,
+  filterByAudience,
+  scopeEditHistory,
+  resolveIncidentAudience,
+  type ReadAudience,
+} from "./read-visibility";
+
+const MANAGE_ID = qualifyAccessRuleId(
+  pluginMetadata,
+  incidentAccess.incident.manage,
+);
+
+/** Auth stub whose `check` returns a fixed verdict and records its calls. */
+function fakeAuth(hasAccess: boolean): Pick<AuthService, "check"> {
+  return {
+    check: async () => ({ hasAccess }),
+  };
+}
+
+describe("isVisibleAtAudience", () => {
+  const rows: Array<[IncidentVisibility, ReadAudience, boolean]> = [
+    ["public", "public", true],
+    ["logged_in", "public", false],
+    ["internal", "public", false],
+    ["public", "authenticated", true],
+    ["logged_in", "authenticated", true],
+    ["internal", "authenticated", false],
+    ["public", "manager", true],
+    ["logged_in", "manager", true],
+    ["internal", "manager", true],
+  ];
+  test.each(rows)("%s @ %s => %s", (visibility, audience, expected) => {
+    expect(isVisibleAtAudience(visibility, audience)).toBe(expected);
+  });
+});
+
+describe("filterByAudience", () => {
+  const items: Array<{ id: string; visibility: IncidentVisibility }> = [
+    { id: "p", visibility: "public" },
+    { id: "l", visibility: "logged_in" },
+    { id: "i", visibility: "internal" },
+  ];
+
+  test("anonymous sees only public", () => {
+    expect(filterByAudience(items, "public").map((i) => i.id)).toEqual(["p"]);
+  });
+  test("authenticated excludes internal", () => {
+    expect(filterByAudience(items, "authenticated").map((i) => i.id)).toEqual([
+      "p",
+      "l",
+    ]);
+  });
+  test("manager sees all", () => {
+    expect(filterByAudience(items, "manager").map((i) => i.id)).toEqual([
+      "p",
+      "l",
+      "i",
+    ]);
+  });
+});
+
+describe("scopeEditHistory", () => {
+  // A now-public update whose PRIOR version was internal: exposing the history
+  // to a non-manager would leak the prior internal content.
+  const updates = [
+    {
+      id: "u1",
+      visibility: "public" as IncidentVisibility,
+      editHistory: [
+        {
+          message: "secret internal note",
+          visibility: "internal",
+          createdAt: "2026-01-01T00:00:00.000Z",
+          editedAt: "2026-01-01T01:00:00.000Z",
+        },
+      ],
+    },
+  ];
+
+  test("manager keeps the edit history", () => {
+    const [u] = scopeEditHistory(updates, "manager");
+    expect(u.editHistory).toHaveLength(1);
+  });
+
+  test("authenticated non-manager gets history stripped", () => {
+    const [u] = scopeEditHistory(updates, "authenticated");
+    expect(u.editHistory).toBeUndefined();
+  });
+
+  test("public reader gets history stripped (no prior internal leak)", () => {
+    const [u] = scopeEditHistory(updates, "public");
+    expect(u.editHistory).toBeUndefined();
+  });
+});
+
+describe("resolveIncidentAudience", () => {
+  test("no user => public", async () => {
+    const audience = await resolveIncidentAudience({
+      context: { user: undefined, auth: fakeAuth(false) },
+      incidentId: "inc1",
+    });
+    expect(audience).toBe("public");
+  });
+
+  test("service user => manager (trusted)", async () => {
+    const user: ServiceUser = { type: "service", pluginId: "other" };
+    const audience = await resolveIncidentAudience({
+      context: { user, auth: fakeAuth(false) },
+      incidentId: "inc1",
+    });
+    expect(audience).toBe("manager");
+  });
+
+  test("global manage rule => manager", async () => {
+    const user: RealUser = { type: "user", id: "u1", accessRules: [MANAGE_ID] };
+    const audience = await resolveIncidentAudience({
+      context: { user, auth: fakeAuth(false) },
+      incidentId: "inc1",
+    });
+    expect(audience).toBe("manager");
+  });
+
+  test("wildcard rule => manager", async () => {
+    const user: RealUser = { type: "user", id: "u1", accessRules: ["*"] };
+    const audience = await resolveIncidentAudience({
+      context: { user, auth: fakeAuth(false) },
+      incidentId: "inc1",
+    });
+    expect(audience).toBe("manager");
+  });
+
+  test("team grant on this incident => manager", async () => {
+    const user: RealUser = { type: "user", id: "u1", accessRules: [] };
+    const audience = await resolveIncidentAudience({
+      context: { user, auth: fakeAuth(true) },
+      incidentId: "inc1",
+    });
+    expect(audience).toBe("manager");
+  });
+
+  test("authenticated non-manager => authenticated", async () => {
+    const user: RealUser = { type: "user", id: "u1", accessRules: [] };
+    const audience = await resolveIncidentAudience({
+      context: { user, auth: fakeAuth(false) },
+      incidentId: "inc1",
+    });
+    expect(audience).toBe("authenticated");
+  });
+});

package/src/read-visibility.ts

@@ -0,0 +1,99 @@
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcContext, AuthService } from "@checkstack/backend-api";
+import {
+  incidentAccess,
+  incidentResourceTypes,
+  pluginMetadata,
+  type IncidentVisibility,
+} from "@checkstack/incident-common";
+
+/**
+ * Read-path audience level for the caller. Drives which incident updates/links
+ * ship in a payload (Item 3/5): filtering is enforced SERVER-SIDE here, never
+ * via CSS - a hidden item is never serialized.
+ *
+ * - `public`: anonymous callers and the public status-page projection.
+ * - `authenticated`: a logged-in user who cannot manage this incident.
+ * - `manager`: a global incident manager, a team-scoped manager of THIS
+ *   incident, or a trusted service call.
+ */
+export type ReadAudience = "public" | "authenticated" | "manager";
+
+/** Whether an item of the given visibility is exposed at the caller's audience. */
+export function isVisibleAtAudience(
+  visibility: IncidentVisibility,
+  audience: ReadAudience,
+): boolean {
+  if (audience === "manager") return true;
+  if (audience === "authenticated") return visibility !== "internal";
+  return visibility === "public";
+}
+
+/** Filter a list of visibility-carrying items to what the audience may see. */
+export function filterByAudience<T extends { visibility: IncidentVisibility }>(
+  items: T[],
+  audience: ReadAudience,
+): T[] {
+  return items.filter((item) => isVisibleAtAudience(item.visibility, audience));
+}
+
+/**
+ * Strip the manager-only `editHistory` from updates for any non-manager
+ * audience. An update's CURRENT visibility gates the whole row, but a PRIOR
+ * version archived in `editHistory` could have been `internal` before being made
+ * `public` - so exposing history to a public / logged-in reader would leak prior
+ * internal content. The simplest safe rule (and the one applied here): edit
+ * history is manager-only. Managers get the array untouched; everyone else gets
+ * it removed from the payload.
+ */
+export function scopeEditHistory<T extends { editHistory?: unknown }>(
+  updates: T[],
+  audience: ReadAudience,
+): T[] {
+  if (audience === "manager") return updates;
+  return updates.map((u) => ({ ...u, editHistory: undefined }));
+}
+
+/**
+ * Resolve the caller's audience for a specific incident. A trusted service call
+ * is treated as `manager` (server-to-server reads are not the public surface -
+ * the public status page filters to `public` separately in its widget). An
+ * anonymous caller (no user) is `public`. Otherwise the caller is a `manager`
+ * when they hold the global manage rule OR a team grant to manage THIS incident.
+ */
+export async function resolveIncidentAudience({
+  context,
+  incidentId,
+}: {
+  // Only the caller + the auth `check` are needed; a narrow shape keeps this
+  // unit testable without constructing a full RpcContext / AuthService.
+  context: { user: RpcContext["user"]; auth: Pick<AuthService, "check"> };
+  incidentId: string;
+}): Promise<ReadAudience> {
+  const user = context.user;
+  if (!user) return "public";
+  if (user.type === "service") return "manager";
+
+  const manageRuleId = qualifyAccessRuleId(
+    pluginMetadata,
+    incidentAccess.incident.manage,
+  );
+  const rules = user.accessRules ?? [];
+  const hasGlobalManage =
+    rules.includes("*") || rules.includes(manageRuleId);
+  if (hasGlobalManage) return "manager";
+
+  if (user.type === "user" || user.type === "application") {
+    const { hasAccess } = await context.auth.check({
+      userId: user.id,
+      userType: user.type,
+      objectType: incidentResourceTypes.incident,
+      objectId: incidentId,
+      action: "manage",
+      hasGlobalAccess: false,
+    });
+    if (hasAccess) return "manager";
+  }
+
+  return "authenticated";
+}

package/src/router.test.ts

@@ -25,6 +25,7 @@ interface FakeIncident {
   status: string;
   severity: string;
   suppressNotifications: boolean;
+  healthOverride: string | null;
   systemIds: string[];
   createdAt: Date;
   updatedAt: Date;
@@ -39,6 +40,7 @@ function makeIncident(id: string, status = "investigating"): FakeIncident {
     status,
     severity: "major",
     suppressNotifications: false,
+    healthOverride: null,
     systemIds: ["sys-1"],
     createdAt: new Date("2026-01-01T00:00:00Z"),
     updatedAt: new Date("2026-01-01T00:00:00Z"),
@@ -63,15 +65,22 @@ function buildRouter() {
   const getIncident = mock(async (id: string) =>
     PRESENT.has(id) ? makeIncident(id) : undefined,
   );
+  // Echoes the patch back onto the incident so an override-only edit still
+  // resolves the affected systemIds for the lifecycle hook payload.
+  const updateIncident = mock(async (input: { id: string }) =>
+    PRESENT.has(input.id) ? makeIncident(input.id) : undefined,
+  );
 
   const service = {
     getIncident,
     deleteIncident,
     resolveIncident,
+    updateIncident,
   } as unknown as Parameters<typeof createRouter>[0]["service"];
 
   const invalidateForMutation = mock(async () => {});
   const broadcast = mock(async () => {});
+  const emit = mock(async () => {});
   const notifyForSubscription = mock(async () => {});
   const getSystem = mock(async () => undefined);
   const getUserById = mock(async () => undefined);
@@ -82,6 +91,9 @@ function buildRouter() {
     signalService: { broadcast } as unknown as Parameters<
       typeof createRouter
     >[0]["signalService"],
+    eventBus: { emit } as unknown as Parameters<
+      typeof createRouter
+    >[0]["eventBus"],
     catalogClient: { getSystem } as unknown as Parameters<
       typeof createRouter
     >[0]["catalogClient"],
@@ -97,7 +109,15 @@ function buildRouter() {
     >[0]["cache"],
   });
 
-  return { router, deleteIncident, resolveIncident, invalidateForMutation };
+  return {
+    router,
+    deleteIncident,
+    resolveIncident,
+    updateIncident,
+    emit,
+    invalidateForMutation,
+    notifyForSubscription,
+  };
 }
 
 /** Team-scoped context: no global rule; only `granted` ids are grant-covered. */
@@ -154,6 +174,54 @@ describe("incident router bulkDeleteIncidents", () => {
   });
 });
 
+describe("incident router resolveIncident notification", () => {
+  it("carries the resolution note into the subscriber notification body", async () => {
+    const { router, notifyForSubscription } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok"]);
+
+    await call(
+      router.resolveIncident,
+      { id: "inc-ok", message: "Root cause fixed and services restored" },
+      { context: ctx },
+    );
+
+    expect(notifyForSubscription).toHaveBeenCalledTimes(1);
+    const payload = (
+      notifyForSubscription.mock.calls[0] as unknown[] | undefined
+    )?.[0] as { body?: string } | undefined;
+    expect(payload?.body).toContain("has been resolved");
+    // The operator's resolution note must reach subscribers, not be dropped.
+    expect(payload?.body).toContain("Root cause fixed and services restored");
+  });
+});
+
+describe("incident lifecycle hook", () => {
+  it("fires incident.lifecycle.changed on an override-only update (with affected systemIds)", async () => {
+    // The reactive `incident` entity state is {status, severity, systemIds}, so
+    // clearing/adding a healthOverride with no other change emits no entity
+    // change. This hook MUST still fire so SLO can open/close incident-forced
+    // downtime — the whole reason it exists alongside INCIDENT_UPDATED.
+    const { router, emit } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok"]);
+
+    await call(
+      router.updateIncident,
+      { id: "inc-ok", healthOverride: null },
+      { context: ctx },
+    );
+
+    expect(emit).toHaveBeenCalledTimes(1);
+    const emitArgs = emit.mock.calls[0] as unknown[] | undefined;
+    const hook = emitArgs?.[0] as { id?: string } | undefined;
+    const payload = emitArgs?.[1] as
+      | { systemIds?: string[]; action?: string }
+      | undefined;
+    expect(hook?.id).toBe("incident.lifecycle.changed");
+    expect(payload?.action).toBe("updated");
+    expect(payload?.systemIds).toEqual(["sys-1"]);
+  });
+});
+
 describe("incident router bulkResolveIncidents", () => {
   it("resolves only authorized ids and reports forbidden/notFound/error per id", async () => {
     const { router, resolveIncident } = buildRouter();