@checkstack/incident-backend 1.13.6 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @checkstack/incident-backend
 
+## 1.14.0
+
+### Minor Changes
+
+- 88f4333: Resolve `#` mentions on public status pages, and check viewability in the admin UI
+
+  Cross-entity mentions previously resolved only in the admin UI, and did so
+  without asking whether the reader could actually open the target. Public
+  surfaces resolved nothing at all. Three changes, one per delivery context.
+
+  **The admin UI now checks viewability.** `useMentionResolution({ documents })`
+  collects the references a page is about to render and asks each owning plugin -
+  in ONE batched request - which of them this viewer may read. A mention to a
+  deleted or unreadable record now renders as plain text instead of a link to a
+  not-found page or an access gate. Backed by new `resolveIncidentRefs` /
+  `resolveMaintenanceRefs` procedures, which return ids only (so an unreadable
+  record is indistinguishable from a deleted one) and carry the same `listKey`
+  read post-filter as their list procedures. They are deliberately not a filter
+  over the authoring search list, which hides resolved incidents and would
+  silently downgrade valid references.
+
+  **Public status pages now resolve mentions.** A reference becomes a link to the
+  target's public detail page when - and only when - the same page publishes that
+  target, which is exactly the anti-enumeration gate the detail pages already
+  apply. So an operator writing "caused by #Database upgrade" in a public update
+  gets a working link, while a mention of an internal-only incident stays plain
+  text rather than becoming a link that confirms it exists. Widgets opt in by
+  declaring a `mentionType`, so the status-page packages take no dependency on any
+  domain plugin.
+
+  **BREAKING CHANGE (behavioural, no API change):** the in-app public status page
+  at `/statuspage/view/<slug>` now builds detail-page hrefs. Previously it passed
+  none, so incident and maintenance titles rendered as plain text there while the
+  same page on a custom domain linked them. Both now behave identically.
+
+  **Notification bodies no longer leak the internal scheme.** `checkstack:` is
+  meaningless outside a Checkstack renderer, and channels leaked it differently:
+  the email sanitiser stripped the href and left a dead anchor, while Slack's
+  mrkdwn emitted `<checkstack:maintenance/9f1c-abc|Database upgrade>` straight to
+  the recipient (Discord, Telegram and Teams render markdown natively and would
+  have passed it through too). `sanitizeUpdateMessage` now flattens every mention
+  to its label before the body reaches any channel, so no channel has to know the
+  scheme exists. Flattening also happens before the length bound, so the excerpt
+  budget is spent on visible text rather than on an internal URI.
+
+### Patch Changes
+
+- 88f4333: Show command-palette actions to team-scoped users
+
+  The palette filtered commands against the caller's GLOBAL access rules only, so a
+  user whose team holds a create-capability grant - but who holds no global
+  `incident.incident.manage` / `maintenance.maintenance.manage` rule - never saw
+  "Create Incident" or "Create Maintenance", nor their keyboard shortcuts. The
+  palette hid the actions from exactly the people authorized to run them.
+
+  Commands can now declare a `manageCapability` (mirroring the gate routes and nav
+  already use). `filterByAccessRules` shows an item when the caller holds the
+  global rules OR can create/manage the declared type through a team grant, and the
+  command backend resolves that per request via `hasAnyTypeGrant` (with
+  `includeCreator`, so a team member who may CREATE the type qualifies before
+  owning an instance). It fails closed: an auth error leaves pure global gating.
+  The incident and maintenance commands declare their types.
+
+  `useGlobalShortcuts` no longer takes `userAccessRules` and no longer re-checks
+  access: the server-filtered list is authoritative. That re-check tested the
+  global rules only and would have dropped team-scoped users' shortcuts - both call
+  sites already defeated it by passing `["*"]`.
+
+- Updated dependencies [88f4333]
+- Updated dependencies [1deaac5]
+- Updated dependencies [88f4333]
+- Updated dependencies [88f4333]
+- Updated dependencies [88f4333]
+- Updated dependencies [88f4333]
+- Updated dependencies [1deaac5]
+- Updated dependencies [56e5375]
+  - @checkstack/common@0.24.0
+  - @checkstack/auth-common@0.17.0
+  - @checkstack/status-page-common@0.7.0
+  - @checkstack/incident-common@1.11.0
+  - @checkstack/automation-common@0.10.3
+  - @checkstack/command-backend@0.3.0
+  - @checkstack/status-page-backend@0.7.0
+  - @checkstack/notification-common@1.9.0
+  - @checkstack/ai-backend@0.11.5
+  - @checkstack/backend-api@0.35.0
+  - @checkstack/automation-backend@0.11.9
+  - @checkstack/ai-common@0.6.8
+  - @checkstack/cache-api@0.3.21
+  - @checkstack/catalog-backend@1.10.2
+  - @checkstack/catalog-common@2.8.2
+  - @checkstack/integration-backend@0.7.10
+  - @checkstack/integration-common@0.9.11
+  - @checkstack/signal-common@0.3.2
+  - @checkstack/cache-utils@0.3.2
+
 ## 1.13.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-backend",
-  "version": "1.13.6",
+  "version": "1.14.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,25 +14,25 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/ai-backend": "0.11.4",
-    "@checkstack/ai-common": "0.6.7",
-    "@checkstack/backend-api": "0.34.1",
-    "@checkstack/cache-api": "0.3.20",
-    "@checkstack/cache-utils": "0.3.1",
-    "@checkstack/incident-common": "1.10.5",
-    "@checkstack/catalog-common": "2.8.1",
-    "@checkstack/catalog-backend": "1.10.1",
-    "@checkstack/notification-common": "1.8.0",
-    "@checkstack/auth-common": "0.16.0",
-    "@checkstack/command-backend": "0.2.27",
-    "@checkstack/signal-common": "0.3.1",
-    "@checkstack/status-page-backend": "0.6.6",
-    "@checkstack/status-page-common": "0.6.5",
-    "@checkstack/integration-backend": "0.7.9",
-    "@checkstack/integration-common": "0.9.10",
-    "@checkstack/automation-backend": "0.11.8",
-    "@checkstack/automation-common": "0.10.2",
-    "@checkstack/common": "0.23.0",
+    "@checkstack/ai-backend": "0.11.5",
+    "@checkstack/ai-common": "0.6.8",
+    "@checkstack/backend-api": "0.35.0",
+    "@checkstack/cache-api": "0.3.21",
+    "@checkstack/cache-utils": "0.3.2",
+    "@checkstack/incident-common": "1.11.0",
+    "@checkstack/catalog-common": "2.8.2",
+    "@checkstack/catalog-backend": "1.10.2",
+    "@checkstack/notification-common": "1.9.0",
+    "@checkstack/auth-common": "0.17.0",
+    "@checkstack/command-backend": "0.3.0",
+    "@checkstack/signal-common": "0.3.2",
+    "@checkstack/status-page-backend": "0.7.0",
+    "@checkstack/status-page-common": "0.7.0",
+    "@checkstack/integration-backend": "0.7.10",
+    "@checkstack/integration-common": "0.9.11",
+    "@checkstack/automation-backend": "0.11.9",
+    "@checkstack/automation-common": "0.10.3",
+    "@checkstack/common": "0.24.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/contract": "^1.14.4",
@@ -40,8 +40,8 @@
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/scripts": "0.7.6",
-    "@checkstack/test-utils-backend": "0.1.61",
+    "@checkstack/scripts": "0.7.7",
+    "@checkstack/test-utils-backend": "0.1.62",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "@types/pg": "^8.20.0",

package/src/index.ts

@@ -11,6 +11,7 @@ import {
 import {
   incidentAccessRules,
   incidentAccess,
+  incidentResourceTypes,
   pluginMetadata,
   incidentContract,
   incidentRoutes,
@@ -289,6 +290,9 @@ export default createBackendPlugin({
               route:
                 resolveRoute(incidentRoutes.routes.config) + "?action=create",
               requiredAccessRules: [incidentAccess.incident.manage],
+              // Team-scoped: a team that may create/manage incidents sees this
+              // even without the global rule (see command-common filterByAccessRules).
+              manageCapability: { objectType: incidentResourceTypes.incident },
             },
             {
               id: "manage",
@@ -298,6 +302,9 @@ export default createBackendPlugin({
               shortcuts: ["meta+shift+i", "ctrl+shift+i"],
               route: resolveRoute(incidentRoutes.routes.config),
               requiredAccessRules: [incidentAccess.incident.manage],
+              // Team-scoped: a team that may create/manage incidents sees this
+              // even without the global rule (see command-common filterByAccessRules).
+              manageCapability: { objectType: incidentResourceTypes.incident },
             },
           ],
         });

package/src/notifications.test.ts

@@ -467,3 +467,64 @@ describe("notifyAffectedSystems", () => {
     });
   });
 });
+
+/**
+ * The REAL notification body build, not just the converter.
+ *
+ * `update-message.test.ts` proves the sanitizer strips the mention scheme and
+ * `mention-leak.test.ts` proves each channel converter is faithful. Neither
+ * proves that THIS function actually routes the update message through the
+ * sanitizer - a caller that interpolated `updateMessage` directly would pass
+ * both of those suites and still ship the internal URI to every subscriber.
+ */
+describe("notifyAffectedSystems does not leak the mention scheme", () => {
+  const bodyOf = (client: ReturnType<typeof createMockNotificationClient>) => {
+    const payload = (
+      client.notifyForSubscription.mock.calls[0] as unknown[] | undefined
+    )?.[0] as { body?: string } | undefined;
+    return payload?.body ?? "";
+  };
+
+  it("flattens a mention in the update message to its label", async () => {
+    const mockCatalog = createMockCatalogClient();
+    const mockNotify = createMockNotificationClient();
+    const logger = createMockLogger();
+
+    await notifyAffectedSystems({
+      catalogClient: mockCatalog as never,
+      notificationClient: mockNotify as never,
+      logger: logger as never,
+      incidentId: "inc-1",
+      incidentTitle: "Checkout errors",
+      systemIds: ["sys-1"],
+      action: "updated",
+      severity: "major",
+      updateMessage:
+        "Rolled back. See [Database upgrade](checkstack:maintenance/9f1c-abc).",
+    });
+
+    const body = bodyOf(mockNotify);
+    expect(body).not.toContain("checkstack:");
+    expect(body).toContain("Database upgrade");
+  });
+
+  it("keeps an ordinary link in the update message intact", async () => {
+    const mockCatalog = createMockCatalogClient();
+    const mockNotify = createMockNotificationClient();
+    const logger = createMockLogger();
+
+    await notifyAffectedSystems({
+      catalogClient: mockCatalog as never,
+      notificationClient: mockNotify as never,
+      logger: logger as never,
+      incidentId: "inc-1",
+      incidentTitle: "Checkout errors",
+      systemIds: ["sys-1"],
+      action: "updated",
+      severity: "major",
+      updateMessage: "See [the runbook](https://example.com/rb).",
+    });
+
+    expect(bodyOf(mockNotify)).toContain("https://example.com/rb");
+  });
+});

package/src/router.test.ts

@@ -71,11 +71,18 @@ function buildRouter() {
     PRESENT.has(input.id) ? makeIncident(input.id) : undefined,
   );
 
+  // Existence only - the READ post-filter is the platform middleware's job,
+  // which is exactly what the resolveIncidentRefs tests below prove.
+  const findExistingIncidentIds = mock(async (ids: string[]) =>
+    ids.filter((id) => PRESENT.has(id)),
+  );
+
   const service = {
     getIncident,
     deleteIncident,
     resolveIncident,
     updateIncident,
+    findExistingIncidentIds,
   } as unknown as Parameters<typeof createRouter>[0]["service"];
 
   const invalidateForMutation = mock(async () => {});
@@ -114,6 +121,7 @@ function buildRouter() {
     deleteIncident,
     resolveIncident,
     updateIncident,
+    findExistingIncidentIds,
     emit,
     invalidateForMutation,
     notifyForSubscription,
@@ -247,3 +255,104 @@ describe("incident router bulkResolveIncidents", () => {
     expect(resolvedIds).toContain("inc-ok");
   });
 });
+
+/**
+ * `resolveIncidentRefs` backs viewability-aware mention rendering: a `#`
+ * reference becomes a link only when the reader may actually open the target.
+ *
+ * These drive the REAL procedure through `call`, so the contract's
+ * `listKey: "incidents"` post-filter runs. That matters more than the handler
+ * body - the handler only establishes existence, and it is the middleware that
+ * turns "exists" into "and you may read it". A regression that dropped the
+ * `listKey` declaration would leave the handler passing and silently link every
+ * incident in the estate to a team-scoped reader.
+ */
+describe("incident router resolveIncidentRefs", () => {
+  it("returns only ids the team-scoped caller may READ", async () => {
+    const { router } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok"]);
+
+    const { incidents } = await call(
+      router.resolveIncidentRefs,
+      { ids: ["inc-ok", "inc-throw"] },
+      { context: ctx },
+    );
+
+    // Both exist; only "inc-ok" is granted.
+    expect(incidents).toEqual([{ id: "inc-ok" }]);
+  });
+
+  it("omits an id that does not exist, even when granted", async () => {
+    // A reference to a DELETED incident must not become a link either.
+    const { router } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok", "inc-missing"]);
+
+    const { incidents } = await call(
+      router.resolveIncidentRefs,
+      { ids: ["inc-ok", "inc-missing"] },
+      { context: ctx },
+    );
+
+    expect(incidents).toEqual([{ id: "inc-ok" }]);
+  });
+
+  it("makes an unreadable incident indistinguishable from a missing one", async () => {
+    // Both come back as simple absence - no error, no title, nothing that
+    // confirms the unreadable incident exists.
+    const { router } = buildRouter();
+    const ctx = teamScopedContext([]);
+
+    const { incidents } = await call(
+      router.resolveIncidentRefs,
+      { ids: ["inc-ok", "inc-missing"] },
+      { context: ctx },
+    );
+
+    expect(incidents).toEqual([]);
+  });
+
+  it("discloses nothing beyond the id", async () => {
+    // The label already lives in the authored markdown, so the response has no
+    // reason to carry titles - and must not, since it is reached by anyone who
+    // can read ANY incident.
+    const { router } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok"]);
+
+    const { incidents } = await call(
+      router.resolveIncidentRefs,
+      { ids: ["inc-ok"] },
+      { context: ctx },
+    );
+
+    expect(Object.keys(incidents[0] ?? {})).toEqual(["id"]);
+  });
+
+  it("accepts an empty id list without querying", async () => {
+    const { router, findExistingIncidentIds } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok"]);
+
+    const { incidents } = await call(
+      router.resolveIncidentRefs,
+      { ids: [] },
+      { context: ctx },
+    );
+
+    expect(incidents).toEqual([]);
+    expect(findExistingIncidentIds).toHaveBeenCalledWith([]);
+  });
+
+  it("rejects an id list beyond the contract's bound", async () => {
+    // The input is reachable by any reader, so the batch size is capped rather
+    // than letting one request probe the whole estate.
+    const { router } = buildRouter();
+    const ctx = teamScopedContext(["inc-ok"]);
+
+    await expect(
+      call(
+        router.resolveIncidentRefs,
+        { ids: Array.from({ length: 201 }, (_, i) => `inc-${i}`) },
+        { context: ctx },
+      ),
+    ).rejects.toThrow();
+  });
+});

package/src/router.ts

@@ -249,6 +249,15 @@ export function createRouter({
       };
     }),
 
+    resolveIncidentRefs: os.resolveIncidentRefs.handler(async ({ input }) => {
+      // Existence is checked here; READ permission is applied by the
+      // contract's `listKey: "incidents"` post-filter on the way out. An id
+      // that fails either test is simply absent from the response, so a
+      // deleted incident and an unreadable one look identical to the caller.
+      const ids = await service.findExistingIncidentIds(input.ids);
+      return { incidents: ids.map((id) => ({ id })) };
+    }),
+
     getIncident: os.getIncident.handler(async ({ input, context }) => {
       const result = await cache.wrapIncident(input.id, () =>
         service.getIncident(input.id),

package/src/service-reads.it.test.ts

@@ -349,5 +349,83 @@ describe.skipIf(!process.env.CHECKSTACK_IT)(
         forA.find((i) => i.id === "inc-1")?.systemIds.toSorted(),
       ).toEqual(["sys-a", "sys-b"]);
     });
+
+    /**
+     * `findExistingIncidentIds` backs viewability-aware mention rendering. It
+     * is a real set-based `inArray` read, so the SQL is worth proving against
+     * a database - the mocked-db unit tests only cover the router around it.
+     */
+    describe("findExistingIncidentIds", () => {
+      it("returns only the ids that exist", async () => {
+        await insertIncident({
+          id: "inc-1",
+          status: "investigating",
+          systemIds: ["sys-a"],
+        });
+
+        const found = await service.findExistingIncidentIds([
+          "inc-1",
+          "inc-deleted",
+        ]);
+
+        expect(found).toEqual(["inc-1"]);
+      });
+
+      it("returns nothing for an empty input WITHOUT hitting the database", async () => {
+        // `inArray(col, [])` is invalid SQL in Postgres, so the empty case has
+        // to short-circuit rather than build a query.
+        expect(await service.findExistingIncidentIds([])).toEqual([]);
+      });
+
+      it("returns nothing when no id exists", async () => {
+        expect(
+          await service.findExistingIncidentIds(["nope-1", "nope-2"]),
+        ).toEqual([]);
+      });
+
+      it("de-duplicates a repeated id", async () => {
+        await insertIncident({
+          id: "inc-1",
+          status: "investigating",
+          systemIds: ["sys-a"],
+        });
+
+        expect(
+          await service.findExistingIncidentIds(["inc-1", "inc-1", "inc-1"]),
+        ).toEqual(["inc-1"]);
+      });
+
+      it("finds a RESOLVED incident, which the browse list hides", async () => {
+        // The whole reason this is not a filter over `listIncidents`: that list
+        // excludes resolved incidents by default, so deriving viewability from
+        // it would silently downgrade a valid reference to plain text.
+        await insertIncident({
+          id: "inc-resolved",
+          status: "resolved",
+          systemIds: ["sys-a"],
+        });
+
+        expect(
+          await service.findExistingIncidentIds(["inc-resolved"]),
+        ).toEqual(["inc-resolved"]);
+      });
+
+      it("handles a large batch in one round trip", async () => {
+        for (let i = 0; i < 50; i++) {
+          await insertIncident({
+            id: `bulk-${i}`,
+            status: "investigating",
+            systemIds: ["sys-a"],
+          });
+        }
+
+        const asked = Array.from({ length: 200 }, (_, i) => `bulk-${i}`);
+        const found = await service.findExistingIncidentIds(asked);
+
+        expect(found.toSorted()).toEqual(
+          Array.from({ length: 50 }, (_, i) => `bulk-${i}`).toSorted(),
+        );
+      });
+    });
   },
 );

package/src/service.ts

@@ -155,6 +155,30 @@ export class IncidentService {
     return byIncident;
   }
 
+  /**
+   * Which of these incident ids EXIST?
+   *
+   * The read-permission half of the answer is applied by the contract's
+   * `listKey` post-filter, so this only has to establish existence - a
+   * reference to a deleted incident must not become a link either.
+   *
+   * Selects the id column alone: the caller (viewability-aware mention
+   * rendering) needs nothing else, and fetching titles here would put the
+   * titles of not-yet-filtered incidents into memory for no reason.
+   */
+  async findExistingIncidentIds(ids: string[]): Promise<string[]> {
+    if (ids.length === 0) return [];
+
+    const rows = await withScopedTransaction(this.db, (tx) =>
+      tx
+        .select({ id: incidents.id })
+        .from(incidents)
+        .where(inArray(incidents.id, [...new Set(ids)])),
+    );
+
+    return rows.map((row) => row.id);
+  }
+
   /**
    * Get single incident with full details
    */

package/src/status-page-widget.ts

@@ -1,5 +1,8 @@
 import { CatalogApi, assertCatalogResourcesReadable } from "@checkstack/catalog-common";
-import { IncidentApi } from "@checkstack/incident-common";
+import {
+  IncidentApi,
+  INCIDENT_MENTION_TYPE,
+} from "@checkstack/incident-common";
 import {
   pluginMetadata as statusPagePluginMetadata,
   IncidentsConfigSchema,
@@ -127,6 +130,10 @@ async function labelsFor(
 const incidents: WidgetTypeDefinition = {
   id: "incidents",
   displayName: "Incidents",
+  // Lets a public page turn a `#` reference to an incident into a link to its
+  // public detail page - but only for an incident THIS page surfaces, which is
+  // the same gate `resolveDetail` below enforces.
+  mentionType: INCIDENT_MENTION_TYPE,
   description: "Recent unresolved incidents with their update timeline.",
   category: "Events",
   binding: "systems",