@checkstack/catalog-backend 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @checkstack/catalog-backend
 
+## 0.5.0
+
+### Minor Changes
+
+- 80cbc51: Enforce GitOps provenance lock on backend API endpoints to prevent manual configuration drift for synchronized resources.
+
 ## 0.4.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-backend",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {

package/src/index.ts

@@ -18,7 +18,7 @@ import { resolveRoute, type InferClient, extractErrorMessage} from "@checkstack/
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { EntityService } from "./services/entity-service";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
-import { CHECKSTACK_API_VERSION, entityRefSchema } from "@checkstack/gitops-common";
+import { CHECKSTACK_API_VERSION, entityRefSchema, GitOpsApi } from "@checkstack/gitops-common";
 import { z } from "zod";
 
 // Database schema is still needed for types in creating the router
@@ -193,12 +193,14 @@ export default createBackendPlugin({
         // Get notification client for group management and sending notifications
         const notificationClient = rpcClient.forPlugin(NotificationApi);
         const authClient = rpcClient.forPlugin(AuthApi);
+        const gitOpsClient = rpcClient.forPlugin(GitOpsApi);
 
         // Register oRPC router with notification client and auth client
         const catalogRouter = createCatalogRouter({
           database: typedDb,
           notificationClient,
           authClient,
+          gitOpsClient,
           pluginId: pluginMetadata.pluginId,
         });
         rpc.registerRouter(catalogRouter, catalogContract);

package/src/router.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, mock } from "bun:test";
+import { createCatalogRouter } from "./router";
+import { createMockRpcContext } from "@checkstack/backend-api";
+import { call } from "@orpc/server";
+
+describe("Catalog Router - GitOps Provenance Enforcement", () => {
+  const mockUser = {
+    type: "user" as const,
+    id: "test-user",
+    accessRules: ["*"],
+    roles: ["admin"],
+  };
+
+  const mockDb = {
+    select: mock(() => ({
+      from: mock(() => ({
+        where: mock(() => Promise.resolve([])),
+      })),
+    })),
+  } as unknown;
+
+  const mockNotificationClient = {
+    createGroup: mock(() => Promise.resolve()),
+    deleteGroup: mock(() => Promise.resolve()),
+    notifyGroups: mock(() => Promise.resolve({ notifiedCount: 0 })),
+  };
+
+  const mockAuthClient = {
+    getUserById: mock(() => Promise.resolve(null)),
+  };
+
+  const mockGitOpsClient = {
+    getProvenance: mock<any>(() => Promise.resolve(null)),
+  };
+
+  const router = createCatalogRouter({
+    database: mockDb as never,
+    notificationClient: mockNotificationClient as never,
+    authClient: mockAuthClient as never,
+    gitOpsClient: mockGitOpsClient as never,
+    pluginId: "test-catalog",
+  });
+
+  it("allows deleteSystem when GitOps lock is not present", async () => {
+    mockGitOpsClient.getProvenance.mockResolvedValueOnce(null);
+    const context = createMockRpcContext({ user: mockUser, emitHook: mock(() => Promise.resolve()) });
+
+    try {
+      await call(router.deleteSystem, "sys-1", { context });
+    } catch (e: any) {
+      expect(e.code).not.toBe("FORBIDDEN");
+    }
+
+    expect(mockGitOpsClient.getProvenance).toHaveBeenCalledWith({
+      kind: "System",
+      entityId: "sys-1",
+    });
+  });
+
+  it("throws FORBIDDEN when deleting a GitOps locked system", async () => {
+    mockGitOpsClient.getProvenance.mockResolvedValueOnce({
+      id: "prov-1", kind: "System", entityId: "sys-1",
+      providerId: "prov", entityName: "sys1", status: "synced",
+      lastSyncedAt: new Date(), createdAt: new Date(), updatedAt: new Date(),
+      repository: "", filePath: "", fileSha: ""
+    });
+    const context = createMockRpcContext({ user: mockUser });
+
+    let error;
+    try {
+      await call(router.deleteSystem, "sys-1", { context });
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect((error as any).code).toBe("FORBIDDEN");
+    expect((error as any).message).toContain("managed by GitOps");
+  });
+
+  it("throws FORBIDDEN when updating a GitOps locked group", async () => {
+    mockGitOpsClient.getProvenance.mockResolvedValueOnce({
+      id: "prov-1", kind: "Group", entityId: "grp-1",
+      providerId: "prov", entityName: "grp1", status: "synced",
+      lastSyncedAt: new Date(), createdAt: new Date(), updatedAt: new Date(),
+      repository: "", filePath: "", fileSha: ""
+    });
+    const context = createMockRpcContext({ user: mockUser });
+
+    let error;
+    try {
+      await call(router.updateGroup, { id: "grp-1", data: { name: "New Name" } }, { context });
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect((error as any).code).toBe("FORBIDDEN");
+  });
+
+  it("throws FORBIDDEN when adding a locked system to a group", async () => {
+    mockGitOpsClient.getProvenance.mockResolvedValueOnce({
+      id: "prov-1", kind: "System", entityId: "sys-1",
+      providerId: "prov", entityName: "sys1", status: "synced",
+      lastSyncedAt: new Date(), createdAt: new Date(), updatedAt: new Date(),
+      repository: "", filePath: "", fileSha: ""
+    }); 
+    
+    const context = createMockRpcContext({ user: mockUser });
+
+    let error;
+    try {
+      await call(router.addSystemToGroup, { systemId: "sys-1", groupId: "grp-1" }, { context });
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect((error as any).code).toBe("FORBIDDEN");
+  });
+
+  it("allows adding an unlocked system to a group, even if the group is locked", async () => {
+    mockGitOpsClient.getProvenance.mockResolvedValueOnce(null);
+    
+    const context = createMockRpcContext({ user: mockUser });
+
+    try {
+      await call(router.addSystemToGroup, { systemId: "sys-1", groupId: "grp-1" }, { context });
+    } catch (e: any) {
+      expect(e.code).not.toBe("FORBIDDEN");
+    }
+  });
+});

package/src/router.ts

@@ -12,6 +12,7 @@ import { AuthApi } from "@checkstack/auth-common";
 import type { InferClient } from "@checkstack/common";
 import { catalogHooks } from "./hooks";
 import { eq } from "drizzle-orm";
+import { GitOpsApi } from "@checkstack/gitops-common";
 
 /**
  * Creates the catalog router using contract-based implementation.
@@ -27,6 +28,7 @@ export interface CatalogRouterDeps {
   database: SafeDatabase<typeof schema>;
   notificationClient: InferClient<typeof NotificationApi>;
   authClient: InferClient<typeof AuthApi>;
+  gitOpsClient: InferClient<typeof GitOpsApi>;
   pluginId: string;
 }
 
@@ -34,10 +36,23 @@ export const createCatalogRouter = ({
   database,
   notificationClient,
   authClient,
+  gitOpsClient,
   pluginId,
 }: CatalogRouterDeps) => {
   const entityService = new EntityService(database);
 
+  const enforceNotGitOpsLocked = async (kind: string, entityId: string) => {
+    const provenance = await gitOpsClient.getProvenance({
+      kind,
+      entityId,
+    });
+    if (provenance) {
+      throw new ORPCError("FORBIDDEN", {
+        message: `${kind} is managed by GitOps and cannot be modified manually.`,
+      });
+    }
+  };
+
   // Helper to create notification group for an entity
   const createNotificationGroup = async (
     type: "system" | "group",
@@ -136,6 +151,7 @@ export const createCatalogRouter = ({
   });
 
   const updateSystem = os.updateSystem.handler(async ({ input }) => {
+    await enforceNotGitOpsLocked("System", input.id);
     // Convert null to undefined and filter out fields
     const cleanData: Partial<{
       name: string;
@@ -160,6 +176,7 @@ export const createCatalogRouter = ({
   });
 
   const deleteSystem = os.deleteSystem.handler(async ({ input, context }) => {
+    await enforceNotGitOpsLocked("System", input);
     await entityService.deleteSystem(input);
 
     // Delete the notification group for this system
@@ -189,6 +206,7 @@ export const createCatalogRouter = ({
   });
 
   const updateGroup = os.updateGroup.handler(async ({ input }) => {
+    await enforceNotGitOpsLocked("Group", input.id);
     // Convert null to undefined for optional fields
     const cleanData = {
       ...input.data,
@@ -214,6 +232,7 @@ export const createCatalogRouter = ({
   });
 
   const deleteGroup = os.deleteGroup.handler(async ({ input, context }) => {
+    await enforceNotGitOpsLocked("Group", input);
     await entityService.deleteGroup(input);
 
     // Delete the notification group for this catalog group
@@ -226,12 +245,20 @@ export const createCatalogRouter = ({
   });
 
   const addSystemToGroup = os.addSystemToGroup.handler(async ({ input }) => {
+    // Note: We only enforce the lock on the System, not the Group.
+    // This is because system-group associations are reconciled as a kindExtension
+    // of the System kind. The Group reconciler does not touch associations.
+    // Thus, it is perfectly safe (and intended) to manually add an unlocked System 
+    // to a GitOps-managed Group.
+    await enforceNotGitOpsLocked("System", input.systemId);
     await entityService.addSystemToGroup(input);
     return { success: true };
   });
 
   const removeSystemFromGroup = os.removeSystemFromGroup.handler(
     async ({ input }) => {
+      // See addSystemToGroup for why we only check the System provenance lock.
+      await enforceNotGitOpsLocked("System", input.systemId);
       await entityService.removeSystemFromGroup(input);
       return { success: true };
     },
@@ -286,6 +313,7 @@ export const createCatalogRouter = ({
   });
 
   const addSystemContact = os.addSystemContact.handler(async ({ input }) => {
+    await enforceNotGitOpsLocked("System", input.systemId);
     // Validate input based on type
     if (input.type === "user" && !input.userId) {
       throw new ORPCError("BAD_REQUEST", {
@@ -333,6 +361,10 @@ export const createCatalogRouter = ({
 
   const removeSystemContact = os.removeSystemContact.handler(
     async ({ input }) => {
+      const contacts = await database.select().from(schema.systemContacts).where(eq(schema.systemContacts.id, input));
+      if (contacts[0]) {
+        await enforceNotGitOpsLocked("System", contacts[0].systemId);
+      }
       await entityService.removeContact(input);
       return { success: true };
     },