@checkmate-monitor/catalog-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @checkmate-monitor/catalog-common
+
+## 0.1.0
+
+### Minor Changes
+
+- ffc28f6: ### Anonymous Role and Public Access
+
+  Introduces a configurable "anonymous" role for managing permissions available to unauthenticated users.
+
+  **Core Changes:**
+
+  - Added `userType: "public"` - endpoints accessible by both authenticated users (with their permissions) and anonymous users (with anonymous role permissions)
+  - Renamed `userType: "both"` to `"authenticated"` for clarity
+  - Renamed `isDefault` to `isAuthenticatedDefault` on Permission interface
+  - Added `isPublicDefault` flag for permissions that should be granted to the anonymous role by default
+
+  **Backend Infrastructure:**
+
+  - New `anonymous` system role created during auth-backend initialization
+  - New `disabled_public_default_permission` table tracks admin-disabled public defaults
+  - `autoAuthMiddleware` now checks anonymous role permissions for unauthenticated public endpoint access
+  - `AuthService.getAnonymousPermissions()` with 1-minute caching for performance
+  - Anonymous role filtered from `getRoles` endpoint (not assignable to users)
+  - Validation prevents assigning anonymous role to users
+
+  **Catalog Integration:**
+
+  - `catalog.read` permission now has both `isAuthenticatedDefault` and `isPublicDefault`
+  - Read endpoints (`getSystems`, `getGroups`, `getEntities`) now use `userType: "public"`
+
+  **UI:**
+
+  - New `PermissionGate` component for conditionally rendering content based on permissions
+
+- 4dd644d: Enable external application (API key) access to management endpoints
+
+  Changed `userType: "user"` to `userType: "authenticated"` for 52 endpoints across 5 packages, allowing external applications (service accounts with API keys) to call these endpoints programmatically while maintaining RBAC permission checks:
+
+  - **incident-common**: createIncident, updateIncident, addUpdate, resolveIncident, deleteIncident
+  - **maintenance-common**: createMaintenance, updateMaintenance, addUpdate, closeMaintenance, deleteMaintenance
+  - **catalog-common**: System CRUD, Group CRUD, addSystemToGroup, removeSystemFromGroup
+  - **healthcheck-common**: Configuration management, system associations, retention config, detailed history
+  - **integration-common**: Subscription management, connection management, event discovery, delivery logs
+
+  This enables automation use cases such as:
+
+  - Creating incidents from external monitoring systems (Prometheus, Grafana)
+  - Scheduling maintenances from CI/CD pipelines
+  - Managing catalog systems from infrastructure-as-code tools
+  - Configuring health checks from deployment scripts
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+  - @checkmate-monitor/common@0.1.0
+  - @checkmate-monitor/frontend-api@0.0.2

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@checkmate-monitor/catalog-common",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkmate-monitor/common": "workspace:*",
+    "@checkmate-monitor/frontend-api": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkmate-monitor/tsconfig": "workspace:*",
+    "@checkmate-monitor/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { permissions, permissionList } from "./permissions";
+export * from "./rpc-contract";
+export * from "./types";
+export * from "./slots";
+export * from "./plugin-metadata";
+export { catalogRoutes } from "./routes";

package/src/permissions.ts

@@ -0,0 +1,17 @@
+import { createPermission } from "@checkmate-monitor/common";
+
+export const permissions = {
+  catalogRead: createPermission(
+    "catalog",
+    "read",
+    "Read Catalog (Systems and Groups)",
+    { isAuthenticatedDefault: true, isPublicDefault: true }
+  ),
+  catalogManage: createPermission(
+    "catalog",
+    "manage",
+    "Full management of Catalog (Systems and Groups)"
+  ),
+};
+
+export const permissionList = Object.values(permissions);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkmate-monitor/common";
+
+/**
+ * Plugin metadata for the catalog plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "catalog",
+});

package/src/routes.ts

@@ -0,0 +1,10 @@
+import { createRoutes } from "@checkmate-monitor/common";
+
+/**
+ * Route definitions for the catalog plugin.
+ */
+export const catalogRoutes = createRoutes("catalog", {
+  home: "/",
+  config: "/config",
+  systemDetail: "/system/:systemId",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,228 @@
+import { oc } from "@orpc/contract";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkmate-monitor/common";
+import { pluginMetadata } from "./plugin-metadata";
+import { z } from "zod";
+import { SystemSchema, GroupSchema, ViewSchema } from "./types";
+import { permissions } from "./permissions";
+
+// Base builder with full metadata support
+const _base = oc.$meta<ProcedureMetadata>({});
+
+// Input schemas that match the service layer expectations
+const CreateSystemInputSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  owner: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+const UpdateSystemInputSchema = z.object({
+  id: z.string(),
+  data: z.object({
+    name: z.string().optional(),
+    description: z.string().nullable().optional(), // Allow nullable for updates
+    owner: z.string().nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).nullable().optional(), // Allow nullable
+  }),
+});
+
+const CreateGroupInputSchema = z.object({
+  name: z.string(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+const UpdateGroupInputSchema = z.object({
+  id: z.string(),
+  data: z.object({
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).nullable().optional(), // Allow nullable
+  }),
+});
+
+const CreateViewInputSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  configuration: z.unknown(),
+});
+
+// Catalog RPC Contract using oRPC's contract-first pattern
+export const catalogContract = {
+  // ==========================================================================
+  // ENTITY READ ENDPOINTS (userType: "public" - accessible by anyone with permission)
+  // ==========================================================================
+
+  getEntities: _base
+    .meta({ userType: "public", permissions: [permissions.catalogRead.id] })
+    .output(
+      z.object({
+        systems: z.array(SystemSchema),
+        groups: z.array(GroupSchema),
+      })
+    ),
+
+  getSystems: _base
+    .meta({ userType: "public", permissions: [permissions.catalogRead.id] })
+    .output(z.array(SystemSchema)),
+
+  getSystem: _base
+    .meta({ userType: "public", permissions: [permissions.catalogRead.id] })
+    .input(z.object({ systemId: z.string() }))
+    .output(SystemSchema.nullable()),
+
+  getGroups: _base
+    .meta({ userType: "public", permissions: [permissions.catalogRead.id] })
+    .output(z.array(GroupSchema)),
+
+  // ==========================================================================
+  // SYSTEM MANAGEMENT (userType: "authenticated" with manage permission)
+  // ==========================================================================
+
+  createSystem: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(CreateSystemInputSchema)
+    .output(SystemSchema),
+
+  updateSystem: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(UpdateSystemInputSchema)
+    .output(SystemSchema),
+
+  deleteSystem: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(z.string())
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // GROUP MANAGEMENT (userType: "authenticated" with manage permission)
+  // ==========================================================================
+
+  createGroup: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(CreateGroupInputSchema)
+    .output(GroupSchema),
+
+  updateGroup: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(UpdateGroupInputSchema)
+    .output(GroupSchema),
+
+  deleteGroup: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(z.string())
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // SYSTEM-GROUP RELATIONSHIPS (userType: "authenticated" with manage permission)
+  // ==========================================================================
+
+  addSystemToGroup: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(
+      z.object({
+        groupId: z.string(),
+        systemId: z.string(),
+      })
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  removeSystemFromGroup: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.catalogManage.id],
+    })
+    .input(
+      z.object({
+        groupId: z.string(),
+        systemId: z.string(),
+      })
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // VIEW MANAGEMENT (userType: "user")
+  // ==========================================================================
+
+  getViews: _base
+    .meta({ userType: "user", permissions: [permissions.catalogRead.id] })
+    .output(z.array(ViewSchema)),
+
+  createView: _base
+    .meta({ userType: "user", permissions: [permissions.catalogManage.id] })
+    .input(CreateViewInputSchema)
+    .output(ViewSchema),
+
+  // ==========================================================================
+  // SERVICE INTERFACE (userType: "service" - backend-to-backend only)
+  // ==========================================================================
+
+  /**
+   * Notify all users subscribed to a system (and optionally its groups).
+   * This is used by other plugins (e.g., maintenance) to send notifications
+   * to system subscribers without needing direct access to the notification service.
+   *
+   * Deduplication: If includeGroupSubscribers is true, subscribers are
+   * deduplicated so users subscribed to both the system AND its groups
+   * receive only one notification.
+   */
+  notifySystemSubscribers: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        systemId: z
+          .string()
+          .describe("The system ID to notify subscribers for"),
+        title: z.string().describe("Notification title"),
+        /** Notification body in markdown format */
+        body: z.string().describe("Notification body (supports markdown)"),
+        importance: z.enum(["info", "warning", "critical"]).optional(),
+        /** Primary action button */
+        action: z
+          .object({
+            label: z.string(),
+            url: z.string(),
+          })
+          .optional(),
+        includeGroupSubscribers: z
+          .boolean()
+          .optional()
+          .describe(
+            "If true, also notify subscribers of groups that contain this system"
+          ),
+      })
+    )
+    .output(z.object({ notifiedCount: z.number() })),
+};
+
+// Export contract type
+export type CatalogContract = typeof catalogContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(CatalogApi);
+export const CatalogApi = createClientDefinition(
+  catalogContract,
+  pluginMetadata
+);

package/src/slots.ts

@@ -0,0 +1,74 @@
+import { createSlot } from "@checkmate-monitor/frontend-api";
+import type { System } from "./types";
+
+/**
+ * Slot for extending the top of the System Details page.
+ * Use for important alerts like active maintenances that should be shown prominently.
+ * Extensions receive the full system object.
+ *
+ * @example
+ * extensions: [{
+ *   id: "my-plugin.system-details-top",
+ *   slotId: SystemDetailsTopSlot.id,
+ *   component: ({ system }) => <MaintenanceAlert system={system} />,
+ * }]
+ */
+export const SystemDetailsTopSlot = createSlot<{ system: System }>(
+  "plugin.catalog.system-details-top"
+);
+
+/**
+ * Slot for extending the System Details page with additional content.
+ * Extensions receive the full system object.
+ *
+ * @example
+ * // In your plugin
+ * import { SystemDetailsSlot } from "@checkmate-monitor/catalog-common";
+ *
+ * extensions: [{
+ *   id: "my-plugin.system-details",
+ *   slotId: SystemDetailsSlot.id,
+ *   component: ({ system }) => <MyComponent system={system} />,
+ * }]
+ */
+export const SystemDetailsSlot = createSlot<{ system: System }>(
+  "plugin.catalog.system-details"
+);
+
+/**
+ * Slot for adding actions to the catalog system configuration page.
+ * Extensions receive the system ID and name.
+ *
+ * @example
+ * // In your plugin
+ * import { CatalogSystemActionsSlot } from "@checkmate-monitor/catalog-common";
+ *
+ * extensions: [{
+ *   id: "my-plugin.system-actions",
+ *   slotId: CatalogSystemActionsSlot.id,
+ *   component: ({ systemId, systemName }) => <MyAction systemId={systemId} />,
+ * }]
+ */
+export const CatalogSystemActionsSlot = createSlot<{
+  systemId: string;
+  systemName: string;
+}>("plugin.catalog.system-actions");
+
+/**
+ * Slot for displaying system state badges.
+ * Plugins use this to contribute state indicators (e.g., health status, maintenance status).
+ * Extensions receive the system and should render badge components.
+ *
+ * @example
+ * // In your plugin
+ * import { SystemStateBadgesSlot } from "@checkmate-monitor/catalog-common";
+ *
+ * extensions: [{
+ *   id: "my-plugin.system-state-badge",
+ *   slotId: SystemStateBadgesSlot.id,
+ *   component: ({ system }) => <MyStatusBadge systemId={system.id} />,
+ * }]
+ */
+export const SystemStateBadgesSlot = createSlot<{ system: System }>(
+  "plugin.catalog.system-state-badges"
+);

package/src/types.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+// Domain type schemas for catalog entities
+// These match the database output types exactly
+// JSON serialization will handle Date -> ISO string conversion automatically
+
+export const SystemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  owner: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type System = z.infer<typeof SystemSchema>;
+
+export const GroupSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  systemIds: z.array(z.string()), // Required field from the service layer
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type Group = z.infer<typeof GroupSchema>;
+
+export const ViewSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  configuration: z.unknown(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type View = z.infer<typeof ViewSchema>;

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkmate-monitor/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}