@checkstack/backend 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @checkstack/backend
 
+## 0.18.0
+
+### Minor Changes
+
+- 0626782: Guard the role editor against granting inert (and misleading) permissions to the
+  anonymous role.
+
+  RPC procedures carry two independent axes: `userType` (the hard authentication
+  gate) and `access` rules (authorization). An admin can grant the anonymous role
+  any access rule, but if the procedures needing that rule are `userType:
+"authenticated"`/`"user"`, the grant does nothing - the auth middleware rejects
+  unauthenticated callers BEFORE access rules are checked (so there is no security
+  hole; the grant is simply inert). After anonymous users started seeing
+  permission-gated UI, such a grant would surface as visible-but-broken controls.
+
+  - The backend now computes, from contract metadata, the access rules an anonymous
+    caller can actually use (a rule is "usable" iff at least one `public` procedure
+    requires it) via `pluginManager.getAnonymousUsableAccessRuleIds()`, exposed to
+    plugins through the plugin environment.
+  - `auth.getAccessRules` annotates each rule with `anonymousUsable`.
+  - `auth.updateRole` REFUSES to ADD a non-usable rule to the anonymous role
+    (existing grants are untouched, so no configuration can be wedged). This is a
+    guardrail, not an enforcement change - RPC authorization is unchanged.
+  - The role editor disables non-usable rules (with an explanation) when editing
+    the anonymous role.
+
+  Verified live: `getAccessRules` reports 11 anonymous-usable vs 58 not; granting
+  `incident.incident.manage` to the anonymous role returns HTTP 400 with a clear
+  message.
+
+### Patch Changes
+
+- 56e7c75: Fix frontend access checks to use FULLY-QUALIFIED access-rule ids, and resolve
+  the anonymous role on the frontend.
+
+  Granted access-rule ids are stored fully-qualified as `{pluginId}.{ruleId}` (e.g.
+  `incident.incident.read`) so two plugins defining the same short rule id never
+  collide. The frontend, however, was checking the UNqualified id (`incident.read`)
+  via `isAccessRuleSatisfied`, so every check failed for any user without the `*`
+  (admin) grant - masked in development because dev-auth grants `*`. This silently
+  broke ALL non-admin frontend gating (route guards, sidebar entries, and
+  `useAccess`-based button/link gating).
+
+  - **`@checkstack/common`**: `AccessRule` now carries a REQUIRED owning `pluginId`;
+    `access()` / `accessPair()` require and stamp it; `isAccessRuleSatisfied`
+    qualifies the rule (`{pluginId}.{id}`, plus the manage->read escalation) and
+    matches ONLY the qualified form. There is intentionally NO unqualified fallback
+    - matching a bare id would let one plugin's grant satisfy another plugin's
+      identically-named rule (a cross-plugin privilege-escalation flaw). Every plugin
+      that defines access rules now passes its own `pluginId`.
+  - **`@checkstack/backend`**: `pluginManager.getAllAccessRules()` no longer strips
+    the `pluginId` field (the rule `id` is already fully-qualified for the DB sync).
+  - **Route guard** (`@checkstack/frontend` / `@checkstack/frontend-api`) now
+    checks the FULL rule object (so it qualifies and escalates), not a bare id.
+  - **Anonymous role on the frontend**: the `accessRules` procedure is now
+    `public`, returning the configurable anonymous role's grants to unauthenticated
+    callers; `useAccessRules` fetches them for guests instead of returning an empty
+    set. So anonymous UI now reflects exactly what the anonymous role is allowed -
+    which an admin can change (`isPublic` is only the seeded default).
+  - Incident / maintenance / SLO detail routes are now read-gated (their read rule
+    is an `isPublic` default, so the anonymous role holds it unless an admin
+    revokes it); their dashboard status signals carry that rule and render as a
+    link only when the viewer may open it.
+
+  **BREAKING (`@checkstack/common`):** `AccessRule.pluginId` is now REQUIRED, and
+  `access()` / `accessPair()` require a `pluginId` option. `isAccessRuleSatisfied`
+  matches ONLY the fully-qualified `{pluginId}.{ruleId}` form - the previous
+  unqualified fallback is removed, because it was a cross-plugin
+  privilege-escalation flaw. Any code constructing an `AccessRule` or calling
+  `access()`/`accessPair()` must supply the owning `pluginId`.
+
+  Verified live against an anonymous caller: read pages resolve (qualified match),
+  manage actions are denied, manage->read escalation and `*` still work.
+
+- Updated dependencies [0626782]
+- Updated dependencies [56e7c75]
+  - @checkstack/backend-api@0.21.5
+  - @checkstack/auth-common@0.8.3
+  - @checkstack/common@0.15.0
+  - @checkstack/api-docs-common@0.1.19
+  - @checkstack/pluginmanager-common@0.2.8
+  - @checkstack/signal-backend@0.3.5
+  - @checkstack/cache-api@0.3.12
+  - @checkstack/queue-api@0.3.12
+  - @checkstack/signal-common@0.2.9
+
+## 0.17.2
+
+### Patch Changes
+
+- Updated dependencies [b50916d]
+  - @checkstack/backend-api@0.21.4
+  - @checkstack/signal-backend@0.3.4
+
 ## 0.17.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -14,16 +14,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.18",
-    "@checkstack/auth-common": "0.8.2",
-    "@checkstack/backend-api": "0.21.3",
-    "@checkstack/common": "0.14.1",
+    "@checkstack/api-docs-common": "0.1.19",
+    "@checkstack/auth-common": "0.8.3",
+    "@checkstack/backend-api": "0.21.5",
+    "@checkstack/common": "0.15.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.3.11",
-    "@checkstack/queue-api": "0.3.11",
-    "@checkstack/signal-backend": "0.3.3",
-    "@checkstack/signal-common": "0.2.8",
-    "@checkstack/pluginmanager-common": "0.2.7",
+    "@checkstack/cache-api": "0.3.12",
+    "@checkstack/queue-api": "0.3.12",
+    "@checkstack/signal-backend": "0.3.5",
+    "@checkstack/signal-common": "0.2.9",
+    "@checkstack/pluginmanager-common": "0.2.8",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.14.4",
     "@orpc/contract": "^1.14.4",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.6.0",
-    "@checkstack/test-utils-backend": "0.1.37",
+    "@checkstack/scripts": "0.6.1",
+    "@checkstack/test-utils-backend": "0.1.39",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/plugin-manager/app-principal-authz.test.ts

@@ -35,7 +35,9 @@ import { createApiRouteHandler, registerApiRoute } from "./api-router";
  * bypassed.
  */
 
-const manageRule = access("thing", "manage", "Manage things");
+const manageRule = access("thing", "manage", "Manage things", {
+  pluginId: "target",
+});
 
 const targetContract = {
   // Gated by `thing.manage`. autoAuthMiddleware qualifies it to

package/src/plugin-manager/plugin-loader.getservice.test.ts

@@ -32,6 +32,7 @@ function makeDeps(registry: ServiceRegistry): PluginLoaderDeps {
     extensionPointManager: createExtensionPointManager(),
     registeredAccessRules: [] as (AccessRule & { pluginId: string })[],
     getAllAccessRules: () => [],
+    getAnonymousUsableAccessRuleIds: () => [],
     db: {} as PluginLoaderDeps["db"],
     pluginMetadataRegistry: new Map<string, PluginMetadata>(),
     cleanupHandlers: new Map<string, Array<() => Promise<void>>>(),

package/src/plugin-manager/plugin-loader.skip-naming.test.ts

@@ -32,6 +32,7 @@ function makeDeps(registry: ServiceRegistry): PluginLoaderDeps {
     extensionPointManager: createExtensionPointManager(),
     registeredAccessRules: [] as (AccessRule & { pluginId: string })[],
     getAllAccessRules: () => [],
+    getAnonymousUsableAccessRuleIds: () => [],
     db: {} as PluginLoaderDeps["db"],
     pluginMetadataRegistry: new Map<string, PluginMetadata>(),
     cleanupHandlers: new Map<string, Array<() => Promise<void>>>(),

package/src/plugin-manager/plugin-loader.ts

@@ -48,6 +48,7 @@ export interface PluginLoaderDeps {
   extensionPointManager: ExtensionPointManager;
   registeredAccessRules: (AccessRule & { pluginId: string })[];
   getAllAccessRules: () => AccessRule[];
+  getAnonymousUsableAccessRuleIds: () => string[];
   db: SafeDatabase<Record<string, unknown>>;
   /**
    * Map of pluginId -> PluginMetadata for request-time context injection.
@@ -236,6 +237,8 @@ export function registerPlugin({
     },
     pluginManager: {
       getAllAccessRules: () => deps.getAllAccessRules(),
+      getAnonymousUsableAccessRuleIds: () =>
+        deps.getAnonymousUsableAccessRuleIds(),
     },
   });
 }
@@ -639,7 +642,10 @@ export async function loadPlugins({
   // Emit access rule registration hooks at start of Phase 3
   // (EventBus already retrieved above, all plugins can receive notifications)
   const accessRulesByPlugin = new Map<string, AccessRule[]>();
-  for (const { pluginId, ...rule } of deps.registeredAccessRules) {
+  for (const rule of deps.registeredAccessRules) {
+    // Keep `pluginId` on the rule (required AccessRule field); use it only to
+    // group. The rule's `id` is already fully-qualified.
+    const { pluginId } = rule;
     if (!accessRulesByPlugin.has(pluginId)) {
       accessRulesByPlugin.set(pluginId, []);
     }

package/src/plugin-manager.anon-rules.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { access } from "@checkstack/common";
+import { collectAnonymousUsableRuleIds } from "./plugin-manager";
+
+// A fake contract is just a record of procedures; each procedure carries its
+// metadata under `~orpc.meta`, exactly like a real oRPC contract procedure.
+const proc = (userType: string, access_: ReturnType<typeof access>[]) => ({
+  ["~orpc"]: { meta: { userType, access: access_ } },
+});
+
+const incidentRead = access("incident", "read", "", { pluginId: "incident" });
+const incidentManage = access("incident", "manage", "", {
+  pluginId: "incident",
+});
+const catalogRead = access("system", "read", "", { pluginId: "catalog" });
+
+describe("collectAnonymousUsableRuleIds", () => {
+  test("includes rules required by a public procedure (qualified id)", () => {
+    const contracts = [
+      { getIncidents: proc("public", [incidentRead]) },
+      { getSystems: proc("public", [catalogRead]) },
+    ];
+    expect(collectAnonymousUsableRuleIds(contracts).sort()).toEqual([
+      "catalog.system.read",
+      "incident.incident.read",
+    ]);
+  });
+
+  test("excludes rules required only by authenticated/user procedures", () => {
+    const contracts = [
+      {
+        createIncident: proc("authenticated", [incidentManage]),
+        deleteIncident: proc("user", [incidentManage]),
+      },
+    ];
+    expect(collectAnonymousUsableRuleIds(contracts)).toEqual([]);
+  });
+
+  test("a rule on BOTH a public and an authenticated procedure is usable", () => {
+    const contracts = [
+      {
+        getIncidents: proc("public", [incidentRead]),
+        createIncident: proc("authenticated", [incidentManage]),
+      },
+    ];
+    // read is usable (public); manage is not (only authenticated).
+    expect(collectAnonymousUsableRuleIds(contracts)).toEqual([
+      "incident.incident.read",
+    ]);
+  });
+
+  test("ignores procedures without metadata and anonymous-userType ones", () => {
+    const contracts = [
+      { notAProc: {} as unknown },
+      // anonymous userType skips access checks entirely, so its rules are not
+      // 'usable via grant' - they would never be consulted.
+      { ping: proc("anonymous", [incidentRead]) },
+    ];
+    expect(collectAnonymousUsableRuleIds(contracts)).toEqual([]);
+  });
+});

package/src/plugin-manager.ts

@@ -15,7 +15,11 @@ import {
   HookUnsubscribe,
 } from "@checkstack/backend-api";
 import type { AnyContractRouter } from "@orpc/contract";
-import type { AccessRule, PluginMetadata } from "@checkstack/common";
+import type {
+  AccessRule,
+  PluginMetadata,
+  ProcedureMetadata,
+} from "@checkstack/common";
 import { extractErrorMessage } from "@checkstack/common";
 
 // Extracted modules
@@ -30,6 +34,32 @@ import { stripPublicSchemaFromMigrations } from "./utils/strip-public-schema";
 import { runPluginMigrations } from "./utils/run-plugin-migrations";
 import { createScopedDb } from "./utils/scoped-db";
 
+/**
+ * Collect the qualified ids (`{pluginId}.{ruleId}`) of access rules an ANONYMOUS
+ * caller can actually use: a rule is included iff at least one procedure that
+ * requires it has `userType: "public"` (the only userType where the anonymous
+ * role's rules are consulted). Pure + exported for unit testing.
+ */
+export function collectAnonymousUsableRuleIds(
+  contracts: Iterable<unknown>,
+): string[] {
+  const usable = new Set<string>();
+  for (const contract of contracts) {
+    for (const procedure of Object.values(
+      contract as Record<string, unknown>,
+    )) {
+      const meta = (
+        procedure as { ["~orpc"]?: { meta?: ProcedureMetadata } } | undefined
+      )?.["~orpc"]?.meta;
+      if (meta?.userType !== "public") continue;
+      for (const rule of meta.access ?? []) {
+        usable.add(`${rule.pluginId}.${rule.id}`);
+      }
+    }
+  }
+  return [...usable];
+}
+
 export interface DeregisterOptions {
   deleteSchema: boolean;
 }
@@ -194,9 +224,10 @@ export class PluginManager {
   }
 
   getAllAccessRules(): AccessRule[] {
-    return this.registeredAccessRules.map(
-      ({ pluginId: _pluginId, ...rule }) => rule
-    );
+    // Return rules WITH their `pluginId` (it is a required AccessRule field now).
+    // Their `id` is already fully-qualified (`{pluginId}.{id}`, see the registration
+    // above), which is what gets synced to the DB and granted to roles.
+    return [...this.registeredAccessRules];
   }
 
   /**
@@ -207,6 +238,22 @@ export class PluginManager {
     return new Map(this.pluginContractRegistry);
   }
 
+  /**
+   * Qualified ids (`{pluginId}.{ruleId}`) of access rules an ANONYMOUS caller can
+   * actually USE: a rule is included iff at least one registered procedure that
+   * requires it has `userType: "public"` - the only userType where the anonymous
+   * role's granted rules are consulted. Rules used solely by
+   * authenticated/user/service procedures are excluded: granting them to the
+   * anonymous role is inert (the auth middleware rejects unauthenticated callers
+   * before access rules are checked), so the role editor uses this to avoid
+   * misleading "granted but unusable" anonymous permissions.
+   */
+  getAnonymousUsableAccessRuleIds(): string[] {
+    return collectAnonymousUsableRuleIds(
+      this.pluginContractRegistry.values(),
+    );
+  }
+
   async loadPlugins(
     rootRouter: Hono,
     manualPlugins: BackendPlugin[] = [],
@@ -227,6 +274,8 @@ export class PluginManager {
         extensionPointManager: this.extensionPointManager,
         registeredAccessRules: this.registeredAccessRules,
         getAllAccessRules: () => this.getAllAccessRules(),
+        getAnonymousUsableAccessRuleIds: () =>
+          this.getAnonymousUsableAccessRuleIds(),
         db,
         pluginMetadataRegistry: this.pluginMetadataRegistry,
         cleanupHandlers: this.cleanupHandlers,
@@ -771,6 +820,8 @@ export class PluginManager {
         },
         pluginManager: {
           getAllAccessRules: () => this.getAllAccessRules(),
+          getAnonymousUsableAccessRuleIds: () =>
+            this.getAnonymousUsableAccessRuleIds(),
         },
       });