@checkstack/incident-common 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # @checkstack/incident-common
 
+## 1.6.0
+
+### Minor Changes
+
+- d2077bd: Platform-wide team-scoped access control on a unified relation-tuple store.
+
+  Admins can scope any resource to teams, and the **platform** (not each plugin)
+  enforces it. A plugin opts in declaratively by adding `instanceAccess` to a
+  procedure's contract; the auth middleware does the rest, so enforcement is
+  consistent across catalog, health checks, incidents, maintenances, SLOs,
+  automations, and the dependency map, and any third-party plugin gets it for free.
+
+  Core model:
+
+  - **Teams are optional.** A resource with no team grants behaves exactly as
+    before.
+  - **Team grants are additive and restrict who can CHANGE a resource, not who can
+    SEE it.** Granting a team `Manage` lets its members view and change the
+    resource; `Read-only` lets them view it. Either level grants access to team
+    members **even when they lack the global permission**, and granting never
+    removes read from anyone who already had it (e.g. a public status page stays
+    readable). Privacy is a separate, explicit opt-in via the **Private** toggle,
+    which removes the global read path so only the resource's teams can see it.
+  - **Ownership at creation.** Create forms expose an **Owning team** picker. A
+    non-admin can create a resource for a team they belong to that holds a
+    create-capability grant for that type; the new resource is auto-granted to that
+    team. Incidents and maintenances are **parent-gated**: anyone who can manage a
+    system may open incidents/maintenances for it, no separate grant needed.
+  - **Meaningful authorization errors.** A caller with neither the global rule nor
+    any team grant for a resource type gets a `403` with a structured body instead
+    of a silently-empty `200`. Anonymous callers on public endpoints are never
+    `403`'d, so status pages keep rendering.
+
+  Unified relation-tuple store:
+
+  - The previously separate access primitives (`resource_team_access.canRead` /
+    `.canManage`, ownership, `resource_access_settings.teamOnly`, and
+    `resource_create_grant`) are collapsed onto ONE
+    `relation_tuple(object, relation, subject)` store: "a team has
+    `viewer`/`editor`/`owner` on an object, or `creator` on a type". Privacy is an
+    explicit **`private` marker** tuple — its **presence** closes the global read
+    path (team grants only), its **absence** is the readable-by-default state, so a
+    private resource with zero grants is correctly inaccessible to everyone rather
+    than silently globalized. The access decision is a pure, unit-tested function.
+  - The auth API is generic: `writeRelation` / `removeRelation` / `setObjectPublic`
+    / `listObjectRelations` / `listSubjectRelations` / `setCreateGrant` /
+    `listTeamCreateGrants` (user-facing) and `check` / `listAccessibleObjectIds` /
+    `hasAnyTypeGrant` / `authorizeCreate` / `setOwner` / `deleteObjectRelations`
+    (service-to-service). Migration `0008` backfills tuples from the legacy tables
+    and drops them.
+
+  Explicit per-procedure scoping:
+
+  - Access rules (`access()` / `accessPair()`) define only the rule (id, level,
+    defaults); every procedure declares its own `instanceAccess`. This removes a
+    "loaded gun" default that silently applied a shared `idParam` to any procedure
+    which forgot its own override.
+  - Modes: `idParam` (single-resource pre-check, fails **closed** if the id does
+    not resolve), `listKey` / `recordKey` (post-filter a list/record to the
+    accessible subset), `create` (authorize creation + write the owning-team
+    grant), `parentScope` (scope by read/manage access to a PARENT type,
+    cross-plugin single-hop: "you may see incidents/maintenances/SLOs/health for
+    system S iff you may see S"), and `global: true` (the honest "intentionally not
+    team-scoped" opt-out). A boot-time validator **rejects** any procedure gated on
+    a team-scopable resource type that declares no `instanceAccess`, turning the
+    previous fail-open into a boot error.
+
+  Teams administration:
+
+  - **Team managers** manage their own team's members and managers without the
+    global `auth.teams.manage` rule; creating, deleting, and granting a team access
+    remain admin-only.
+  - A **standalone Teams page** (gated on `auth.teams.read`) lets managers reach
+    team administration without the admin Auth Settings page; members are added via
+    a debounced directory picker.
+  - A **cross-plugin `ResourceResolverRegistry`** lets owning plugins register a
+    name/search resolver for their resource types, so the Teams page lists a team's
+    grants **by name** (grouped by type) and offers a resource picker — an admin can
+    change a grant's level, revoke it, or add one, without auth depending on every
+    plugin. Resolvers shipped for catalog systems, health-check configurations,
+    incidents, maintenances, SLO objectives, and automations.
+
+  Frontend:
+
+  - The resource-side editor is **"Who can change this"** (one Manage checkbox per
+    team; unticked = read-only), with an always-visible **Private** toggle
+    (disabled until a team that can Manage exists, so a resource can't be stranded).
+  - `TeamOwnershipPicker` explains _why_ there's nothing to pick (not a member of
+    any team, or none of your teams manage the selected parent) instead of a bare
+    "global resource" line.
+  - Read-only **"who can change this"** indicators on resource detail pages expand
+    to the actual people by name; bulk + per-row **Scope to team** actions in the
+    catalog systems list; and the team-access copy spells out that grants are
+    additive and that Read-only grants view (not change) even without the global
+    permission.
+
+  Security hardening:
+
+  - Child deletes in catalog (`removeSystemContact` / `removeSystemLink`) are scoped
+    to both the child id and its parent `systemId`, closing a cross-system IDOR for
+    team-scoped managers.
+  - `searchUsers` is restricted to team administrators, closing a directory/email
+    enumeration path opened by the default `auth.teams.read` rule.
+  - Grant setters reject unregistered resource types.
+
+  BREAKING CHANGES (beta; shipped as minor bumps):
+
+  - `access()` and `accessPair()` no longer accept `idParam` / `listKey` /
+    `recordKey`; move instance config to the procedure's `instanceAccess`.
+  - Boot fails if a procedure gated on a team-scopable resource type omits
+    `instanceAccess`. Declare a scoping mode or `instanceAccess: { global: true }`.
+  - The `AuthService` interface is reshaped: `check`, `listAccessibleObjectIds`,
+    `hasAnyTypeGrant`, `authorizeCreate` (returns `isPrivate`), `setOwner`
+    (`isPrivate`), and `deleteObjectRelations`. Custom `AuthService` implementations
+    and mocks must update.
+  - The auth RPC contract's per-concept resource-access endpoints are replaced by
+    the generic tuple API above; external callers of the old
+    `getResourceTeamAccess` / `setResourceTeamAccess` / `setResourceAccessSettings`
+    / `grantResourceCreate` / etc. must move to the new procedures.
+  - Several contract inputs changed from a bare `string` to an object so the
+    middleware can resolve the resource id: catalog `deleteSystem` (`{ id }`),
+    `removeSystemContact` / `removeSystemLink` (`{ id, systemId }`); health-check
+    `deleteConfiguration` / `pauseConfiguration` / `resumeConfiguration` (`{ id }`).
+    All in-tree callers are updated.
+  - List/record endpoints that relied on returning an empty `200` to signal "no
+    access" now return a `403` for categorically-unauthorized principals.
+  - The mis-keyed bulk endpoints `getBulkIncidentsForSystems`,
+    `getBulkMaintenancesForSystems`, and `getBulkObjectivesForSystems` no longer
+    post-filter their (systemId-keyed) result; access is already gated by
+    `catalog.system` upstream.
+  - Team membership/manager mutations (`addUserToTeam`, `removeUserFromTeam`,
+    `addTeamManager`, `removeTeamManager`) now require `auth.teams.read` instead of
+    `auth.teams.manage` at the contract level (broadened to per-team managers).
+  - The `resource_team_access`, `resource_access_settings`, and
+    `resource_create_grant` tables are dropped (data backfilled into
+    `relation_tuple` by migration `0008`). A previously inconsistent "team-only with
+    zero grants" resource is now correctly inaccessible to global-access holders.
+
+### Patch Changes
+
+- Updated dependencies [d2077bd]
+- Updated dependencies [9ab73c5]
+- Updated dependencies [5c6393f]
+  - @checkstack/common@0.16.0
+  - @checkstack/catalog-common@2.4.0
+  - @checkstack/frontend-api@0.10.0
+  - @checkstack/notification-common@1.3.4
+  - @checkstack/signal-common@0.2.10
+
 ## 1.5.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-common",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,18 +9,18 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.15.0",
-    "@checkstack/catalog-common": "2.3.6",
-    "@checkstack/frontend-api": "0.9.0",
-    "@checkstack/notification-common": "1.3.3",
-    "@checkstack/signal-common": "0.2.9",
+    "@checkstack/common": "0.16.0",
+    "@checkstack/catalog-common": "2.4.0",
+    "@checkstack/frontend-api": "0.10.0",
+    "@checkstack/notification-common": "1.3.4",
+    "@checkstack/signal-common": "0.2.10",
     "@orpc/contract": "^1.14.4",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.6.1"
+    "@checkstack/scripts": "0.6.2"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/access.ts

@@ -26,7 +26,6 @@ export const incidentAccess = {
       },
     },
     {
-      idParam: "systemId",
       pluginId: pluginMetadata.pluginId,
     },
   ),

package/src/rpc-contract.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { incidentContract } from "./rpc-contract";
+
+/**
+ * Team-scoping regression guards (G9 mis-keying).
+ *
+ * Grants for this plugin are keyed by INCIDENT id: the frontend
+ * `TeamAccessEditor` writes `resourceType="incident.incident"`,
+ * `resourceId={incident.id}`. The shared `incident` access rule, however,
+ * declares `idParam: "systemId"`. Without a per-proc override, the
+ * `autoAuthMiddleware` would look for `input.systemId` on object-scoped procs
+ * like `updateIncident({ id })`, find nothing, and SKIP the instance check —
+ * so any holder of `incident.manage` could edit any incident.
+ *
+ * These tests assert each proc carries the expected `instanceAccess` override
+ * resolving to the INCIDENT's own id (or the correct list/record key), and that
+ * the deliberately-unscoped procs carry NO override.
+ *
+ * `~orpc.meta` is the contract-procedure internals (the same accessor the
+ * catalog contract test uses); `meta.instanceAccess` is the per-proc override
+ * the middleware reads.
+ */
+interface InstanceAccessCreate {
+  teamIdParam?: string;
+  idField?: string;
+}
+
+interface InstanceAccessParentScope {
+  resourceType?: string;
+  action?: "read" | "manage";
+  idParam?: string;
+  recordKey?: string;
+}
+
+interface InstanceAccess {
+  global?: boolean;
+  idParam?: string;
+  listKey?: string;
+  recordKey?: string;
+  create?: InstanceAccessCreate;
+  parentScope?: InstanceAccessParentScope;
+}
+
+function instanceAccessFor(
+  procName: keyof typeof incidentContract,
+): InstanceAccess | undefined {
+  const proc = incidentContract[procName] as unknown as Record<string, unknown>;
+  const orpc = proc["~orpc"] as {
+    meta?: { instanceAccess?: InstanceAccess };
+  };
+  return orpc.meta?.instanceAccess;
+}
+
+describe("incident contract object-scoped procs gate on the incident's own id", () => {
+  const idProcs: Array<{
+    proc: keyof typeof incidentContract;
+    idParam: string;
+  }> = [
+    { proc: "getIncident", idParam: "id" },
+    { proc: "updateIncident", idParam: "id" },
+    { proc: "resolveIncident", idParam: "id" },
+    { proc: "deleteIncident", idParam: "id" },
+    { proc: "addUpdate", idParam: "incidentId" },
+    { proc: "addLink", idParam: "incidentId" },
+  ];
+
+  for (const { proc, idParam } of idProcs) {
+    test(`${proc} carries instanceAccess idParam=${idParam} (not systemId)`, () => {
+      const access = instanceAccessFor(proc);
+      expect(access).toBeDefined();
+      expect(access?.idParam).toBe(idParam);
+      // G9 regression: must NOT inherit the rule's mis-keyed systemId.
+      expect(access?.idParam).not.toBe("systemId");
+      expect(access?.listKey).toBeUndefined();
+      expect(access?.recordKey).toBeUndefined();
+    });
+  }
+});
+
+describe("incident contract listIncidents post-filters by incident id", () => {
+  test("listIncidents carries instanceAccess listKey=incidents", () => {
+    const access = instanceAccessFor("listIncidents");
+    expect(access).toBeDefined();
+    expect(access?.listKey).toBe("incidents");
+    expect(access?.idParam).toBeUndefined();
+    expect(access?.recordKey).toBeUndefined();
+  });
+});
+
+describe("incident contract system-scoped / unresolvable procs", () => {
+  // SYSTEM-scoped reads now gate on catalog.system via parentScope (cross-plugin,
+  // single-hop): "you may see incidents for system S iff you may see S".
+  test("getIncidentsForSystem parent-scopes on catalog.system (read, idParam)", () => {
+    const ps = instanceAccessFor("getIncidentsForSystem")?.parentScope;
+    expect(ps?.resourceType).toBe("catalog.system");
+    expect(ps?.action).toBe("read");
+    expect(ps?.idParam).toBe("systemId");
+  });
+
+  test("getBulkIncidentsForSystems parent-scopes on catalog.system (read, recordKey)", () => {
+    const ps = instanceAccessFor("getBulkIncidentsForSystems")?.parentScope;
+    expect(ps?.resourceType).toBe("catalog.system");
+    expect(ps?.action).toBe("read");
+    expect(ps?.recordKey).toBe("incidents");
+  });
+
+  // removeLink's input `id` is the LINK id (not the incident or system id), so
+  // no middleware pre-check can resolve a grant; it is explicitly global (the
+  // incident.manage rule still gates it).
+  test("removeLink is explicitly global (link id is not a scopable resource id)", () => {
+    expect(instanceAccessFor("removeLink")?.global).toBe(true);
+  });
+});
+
+describe("incident contract createIncident carries create-mode team ownership", () => {
+  /**
+   * Regression guard for create-mode wiring. The autoAuthMiddleware reads
+   * `instanceAccess.create` on a mutation proc to:
+   *   1. (pre-handler)  resolve + authorise the owning team from `input[teamIdParam]`.
+   *   2. (post-handler) write a team-scoped grant keyed by `response[idField]`
+   *      via `setResourceOwner`.
+   *
+   * Grants for this plugin are keyed `incident.incident / {incident.id}`, which
+   * matches the `TeamAccessEditor` usage in `IncidentEditor` (resourceType =
+   * "incident.incident", resourceId = incident.id). Hence `idField: "id"` and
+   * `teamIdParam: "teamId"` are the correct values.
+   *
+   * `createAutoIncident` is intentionally excluded: it is `userType: "service"`
+   * (system-generated incidents have no interactive team owner) and must NOT
+   * carry create-mode.
+   */
+  test("createIncident carries instanceAccess.create with teamIdParam=teamId and idField=id", () => {
+    const access = instanceAccessFor("createIncident");
+    expect(access).toBeDefined();
+    expect(access?.create).toBeDefined();
+    expect(access?.create?.teamIdParam).toBe("teamId");
+    expect(access?.create?.idField).toBe("id");
+    // Must not carry object-scope fields — create-mode is distinct from read/update gating.
+    expect(access?.idParam).toBeUndefined();
+    expect(access?.listKey).toBeUndefined();
+    expect(access?.recordKey).toBeUndefined();
+  });
+
+  test("createAutoIncident does NOT carry instanceAccess.create (service userType)", () => {
+    const access = instanceAccessFor("createAutoIncident");
+    expect(access?.create).toBeUndefined();
+  });
+});

package/src/rpc-contract.ts

@@ -20,6 +20,11 @@ export const incidentContract = {
     operationType: "query",
     userType: "public",
     access: [incidentAccess.incident.read],
+    // Grants are keyed by INCIDENT id (frontend `TeamAccessEditor` writes
+    // `resourceType="incident.incident"`, `resourceId={incident.id}`). Each
+    // returned item is an `IncidentWithSystems` whose `.id` is the incident id,
+    // so the list post-filter matches grants correctly.
+    instanceAccess: { listKey: "incidents" },
   })
     .input(
       z
@@ -37,6 +42,11 @@ export const incidentContract = {
     operationType: "query",
     userType: "public",
     access: [incidentAccess.incident.read],
+    // Object-scoped: gate on the incident's OWN grant. The shared `incident`
+    // access rule declares `idParam: "systemId"`, but grants are keyed by
+    // incident id and this input carries `id` (no `systemId`), so without this
+    // override the middleware would find no id and SKIP the check (G9 bug).
+    instanceAccess: { idParam: "id" },
   })
     .input(z.object({ id: z.string() }))
     .output(IncidentDetailSchema.nullable()),
@@ -46,6 +56,12 @@ export const incidentContract = {
     operationType: "query",
     userType: "public",
     access: [incidentAccess.incident.read],
+    // SYSTEM-scoped read: input carries `systemId` and this endpoint returns
+    // incidents FOR that system. Access follows "can you read that system"
+    // (catalog.system / read), not incident-level grants.
+    instanceAccess: {
+      parentScope: { resourceType: "catalog.system", action: "read", idParam: "systemId" },
+    },
   })
     .input(z.object({ systemId: z.string() }))
     .output(z.array(IncidentWithSystemsSchema)),
@@ -57,7 +73,13 @@ export const incidentContract = {
     operationType: "query",
     userType: "public",
     access: [incidentAccess.incident.read],
-    instanceAccess: { recordKey: "incidents" },
+    // SYSTEM-scoped bulk read: output is `{ incidents: Record<systemId, ...> }`.
+    // The record is keyed by system id, so access follows per-system catalog
+    // visibility — the validator post-filters the record to only the system ids
+    // the caller can read.
+    instanceAccess: {
+      parentScope: { resourceType: "catalog.system", action: "read", recordKey: "incidents" },
+    },
   })
     .route({ method: "POST" })
     .input(z.object({ systemIds: z.array(z.string()) }))
@@ -72,6 +94,22 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // CREATE-mode team ownership: the autoAuthMiddleware reads `input.teamId`
+    // (optional) to resolve the owning team and, post-handler, writes a
+    // team-scoped grant keyed `incident.incident / {incident.id}` via
+    // `setResourceOwner`. The `idField: "id"` tells the middleware which field
+    // of the response carries the new resource's id. Grants are keyed by
+    // incident id, matching the `TeamAccessEditor` usage in IncidentEditor.
+    instanceAccess: {
+      create: {
+        teamIdParam: "teamId",
+        idField: "id",
+        // Anyone who can MANAGE a referenced system may create one for it; the
+        // result stays globally readable. Falls back to a per-type
+        // create-capability grant when no parent gate matches.
+        parent: { resourceType: "catalog.system", idParam: "systemIds" },
+      },
+    },
   })
     .input(CreateIncidentInputSchema)
     .output(IncidentWithSystemsSchema),
@@ -81,6 +119,9 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // Object-scoped: gate on the incident's OWN grant via the `id` input.
+    // Overrides the rule's `idParam: "systemId"` (G9 bug — no `systemId` here).
+    instanceAccess: { idParam: "id" },
   })
     .route({ method: "PATCH" })
     .input(UpdateIncidentInputSchema)
@@ -91,6 +132,10 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // Object-scoped: gate on the incident's OWN grant. This input carries the
+    // incident id as `incidentId` (not `id`). Overrides the rule's
+    // `idParam: "systemId"` (G9 bug — no `systemId` here).
+    instanceAccess: { idParam: "incidentId" },
   })
     .input(AddIncidentUpdateInputSchema)
     .output(IncidentUpdateSchema),
@@ -100,6 +145,9 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // Object-scoped: gate on the incident's OWN grant via the `id` input.
+    // Overrides the rule's `idParam: "systemId"` (G9 bug — no `systemId` here).
+    instanceAccess: { idParam: "id" },
   })
     .input(z.object({ id: z.string(), message: z.string().optional() }))
     .output(IncidentWithSystemsSchema),
@@ -109,6 +157,9 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // Object-scoped: gate on the incident's OWN grant via the `incidentId`
+    // input. Overrides the rule's `idParam: "systemId"` (G9 bug).
+    instanceAccess: { idParam: "incidentId" },
   })
     .input(AddIncidentLinkInputSchema)
     .output(IncidentLinkSchema),
@@ -118,6 +169,12 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // global:true — input carries only a LINK id (`incidentLinks.id`), not an
+    // incident id or system id. The owning incident id is only resolvable
+    // server-side after the lookup, so no pre-check can scope this to a resource.
+    // `idParam: "id"` would compare a link id against incident grants and always
+    // 403. The `incident.manage` access rule still gates this endpoint globally.
+    instanceAccess: { global: true },
   })
     .route({ method: "DELETE" })
     .input(z.object({ id: z.string() }))
@@ -128,6 +185,9 @@ export const incidentContract = {
     operationType: "mutation",
     userType: "authenticated",
     access: [incidentAccess.incident.manage],
+    // Object-scoped: gate on the incident's OWN grant via the `id` input.
+    // Overrides the rule's `idParam: "systemId"` (G9 bug — no `systemId` here).
+    instanceAccess: { idParam: "id" },
   })
     .route({ method: "DELETE" })
     .input(z.object({ id: z.string() }))

package/src/schemas.ts

@@ -96,6 +96,15 @@ export const CreateIncidentInputSchema = z.object({
     .string()
     .optional()
     .describe("Optional initial status update message"),
+  /**
+   * Optional owning-team id. When supplied by an authenticated team member, the
+   * autoAuthMiddleware create-mode writes a team-scoped ownership grant for the
+   * newly created incident. Omitting it (or calling with global-manage) creates
+   * the incident without team scoping, exactly as before. Never written to the
+   * incident row — the router handler ignores this field before delegating to
+   * the service.
+   */
+  teamId: z.string().optional(),
 });
 export type CreateIncidentInput = z.infer<typeof CreateIncidentInputSchema>;