@checkstack/backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,225 @@
+# @checkstack/backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/api-docs-common@0.0.2
+  - @checkstack/auth-common@0.0.2
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/drizzle-helper@0.0.2
+  - @checkstack/queue-api@0.0.2
+  - @checkstack/signal-backend@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.4
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/auth-common@0.2.1
+  - @checkstack/queue-api@1.0.1
+  - @checkstack/signal-backend@0.1.1
+  - @checkstack/api-docs-common@0.0.3
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [e26c08e]
+  - @checkstack/auth-common@0.2.0
+
+## 0.1.2
+
+### Patch Changes
+
+- 0f8cc7d: Add runtime configuration API for Docker deployments
+
+  - Backend: Add `/api/config` endpoint serving `BASE_URL` at runtime
+  - Backend: Update CORS to use `BASE_URL` and auto-allow Vite dev server
+  - Backend: `INTERNAL_URL` now defaults to `localhost:3000` (no BASE_URL fallback)
+  - Frontend API: Add `RuntimeConfigProvider` context for runtime config
+  - Frontend: Use `RuntimeConfigProvider` from `frontend-api`
+  - Auth Frontend: Add `useAuthClient()` hook using runtime config
+
+## 0.1.1
+
+### Patch Changes
+
+- f0bdec2: Fixed CI test failures by implementing proper module mocking infrastructure:
+  - Added test-preload.ts with comprehensive mocks for db, logger, and core-services
+  - Added skipDiscovery option to loadPlugins() for test isolation
+  - Configured bunfig.toml preload for workspace-wide test setup
+
+## 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
+
+- 71275dd: fix: Anonymous and non-admin user authorization
+
+  - Fixed permission metadata preservation in `plugin-manager.ts` - changed from outdated `isDefault` field to `isAuthenticatedDefault` and `isPublicDefault`
+  - Added `pluginId` to `RpcContext` to enable proper permission ID matching
+  - Updated `autoAuthMiddleware` to prefix contract permission IDs with the pluginId from context, ensuring that contract permissions (e.g., `catalog.read`) correctly match database permissions (e.g., `catalog-backend.catalog.read`)
+  - Route now uses `/api/:pluginId/*` pattern with Hono path parameters for clean pluginId extraction
+
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+
+  ## New Packages
+
+  - **@checkstack/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkstack/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkstack/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+
+  ## Changes
+
+  - **@checkstack/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkstack/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+
+  ## Usage
+
+  Backend plugins can emit signals:
+
+  ```typescript
+  import { coreServices } from "@checkstack/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+
+  Frontend components subscribe to signals:
+
+  ```tsx
+  import { useSignal } from "@checkstack/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  useSignal(NOTIFICATION_RECEIVED, (payload) => {
+    // Handle realtime notification
+  });
+  ```
+
+### Patch Changes
+
+- ae19ff6: Add configurable state thresholds for health check evaluation
+
+  **@checkstack/backend-api:**
+
+  - Added `VersionedData<T>` generic interface as base for all versioned data structures
+  - `VersionedConfig<T>` now extends `VersionedData<T>` and adds `pluginId`
+  - Added `migrateVersionedData()` utility function for running migrations on any `VersionedData` subtype
+
+  **@checkstack/backend:**
+
+  - Refactored `ConfigMigrationRunner` to use the new `migrateVersionedData` utility
+
+  **@checkstack/healthcheck-common:**
+
+  - Added state threshold schemas with two evaluation modes (consecutive, window)
+  - Added `stateThresholds` field to `AssociateHealthCheckSchema`
+  - Added `getSystemHealthStatus` RPC endpoint contract
+
+  **@checkstack/healthcheck-backend:**
+
+  - Added `stateThresholds` column to `system_health_checks` table
+  - Added `state-evaluator.ts` with health status evaluation logic
+  - Added `state-thresholds-migrations.ts` with migration infrastructure
+  - Added `getSystemHealthStatus` RPC handler
+
+  **@checkstack/healthcheck-frontend:**
+
+  - Updated `SystemHealthBadge` to use new backend endpoint
+
+- 81f3f85: ## Breaking: Unified Versioned<T> Architecture
+
+  Refactored the versioning system to use a unified `Versioned<T>` class instead of separate `VersionedSchema`, `VersionedData`, and `VersionedConfig` types.
+
+  ### Breaking Changes
+
+  - **`VersionedSchema<T>`** is replaced by `Versioned<T>` class
+  - **`VersionedData<T>`** is replaced by `VersionedRecord<T>` interface
+  - **`VersionedConfig<T>`** is replaced by `VersionedPluginRecord<T>` interface
+  - **`ConfigMigration<F, T>`** is replaced by `Migration<F, T>` interface
+  - **`MigrationChain<T>`** is removed (use `Migration<unknown, unknown>[]`)
+  - **`migrateVersionedData()`** is removed (use `versioned.parse()`)
+  - **`ConfigMigrationRunner`** is removed (migrations are internal to Versioned)
+
+  ### Migration Guide
+
+  Before:
+
+  ```typescript
+  const strategy: HealthCheckStrategy = {
+    config: {
+      version: 1,
+      schema: mySchema,
+      migrations: [],
+    },
+  };
+  const data = await migrateVersionedData(stored, 1, migrations);
+  ```
+
+  After:
+
+  ```typescript
+  const strategy: HealthCheckStrategy = {
+    config: new Versioned({
+      version: 1,
+      schema: mySchema,
+      migrations: [],
+    }),
+  };
+  const data = await strategy.config.parse(stored);
+  ```
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [e4d83fc]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [32f2535]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [8e889b4]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/auth-common@0.1.0
+  - @checkstack/queue-api@1.0.0
+  - @checkstack/signal-common@0.1.0
+  - @checkstack/signal-backend@0.1.0
+  - @checkstack/api-docs-common@0.0.2

package/drizzle/0000_loose_yellow_claw.sql

@@ -0,0 +1,28 @@
+CREATE TABLE "jwt_keys" (
+	"id" text PRIMARY KEY NOT NULL,
+	"public_key" text NOT NULL,
+	"private_key" text NOT NULL,
+	"algorithm" text NOT NULL,
+	"created_at" text NOT NULL,
+	"expires_at" text,
+	"revoked_at" text
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_configs" (
+	"plugin_id" text NOT NULL,
+	"config_id" text NOT NULL,
+	"data" jsonb NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "plugin_configs_plugin_id_config_id_pk" PRIMARY KEY("plugin_id","config_id")
+);
+--> statement-breakpoint
+CREATE TABLE "plugins" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"path" text NOT NULL,
+	"is_uninstallable" boolean DEFAULT false NOT NULL,
+	"config" json DEFAULT '{}'::json,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"type" text DEFAULT 'backend' NOT NULL,
+	CONSTRAINT "plugins_name_unique" UNIQUE("name")
+);

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,187 @@
+{
+  "id": "0f04d1ab-b47d-4057-b267-4b904deebd99",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.jwt_keys": {
+      "name": "jwt_keys",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "public_key": {
+          "name": "public_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "private_key": {
+          "name": "private_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "algorithm": {
+          "name": "algorithm",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.plugin_configs": {
+      "name": "plugin_configs",
+      "schema": "",
+      "columns": {
+        "plugin_id": {
+          "name": "plugin_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "config_id": {
+          "name": "config_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "plugin_configs_plugin_id_config_id_pk": {
+          "name": "plugin_configs_plugin_id_config_id_pk",
+          "columns": [
+            "plugin_id",
+            "config_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.plugins": {
+      "name": "plugins",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path": {
+          "name": "path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_uninstallable": {
+          "name": "is_uninstallable",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "config": {
+          "name": "config",
+          "type": "json",
+          "primaryKey": false,
+          "notNull": false,
+          "default": "'{}'::json"
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'backend'"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "plugins_name_unique": {
+          "name": "plugins_name_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "name"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1767314744846,
+      "tag": "0000_loose_yellow_claw",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@checkstack/backend",
+  "version": "0.0.2",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --env-file=../../.env --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "generate": "bun --env-file=../../.env run drizzle-kit generate",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/api-docs-common": "workspace:*",
+    "@checkstack/auth-common": "workspace:*",
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/drizzle-helper": "workspace:*",
+    "@checkstack/queue-api": "workspace:*",
+    "@checkstack/signal-backend": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@hono/zod-validator": "^0.7.6",
+    "@orpc/client": "^1.13.2",
+    "@orpc/openapi": "^1.13.2",
+    "@orpc/server": "^1.13.2",
+    "@orpc/zod": "^1.13.2",
+    "better-auth": "^1.4.7",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.0.0",
+    "jose": "^6.1.3",
+    "pg": "^8.11.0",
+    "winston": "^3.19.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.8",
+    "@types/pg": "^8.11.0",
+    "@types/bun": "latest",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/test-utils-backend": "workspace:*"
+  }
+}

package/src/db.ts

@@ -0,0 +1,20 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import * as schema from "./schema";
+
+// Basic connection string sometimes fails with Bun + pg + docker SASL
+// parsing manually or relying on pg to pick up ENV variables if we don't pass anything
+// But we passed connectionString.
+
+// Explicitly parse config or fallback to individual env vars to avoid SASL string errors
+const connectionString = process.env.DATABASE_URL;
+
+if (!connectionString) {
+  throw new Error("DATABASE_URL is not defined");
+}
+
+export const adminPool = new Pool({
+  connectionString,
+});
+
+export const db = drizzle(adminPool, { schema });

package/src/health-check-plugin-integration.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import {
+  coreServices,
+  createBackendPlugin,
+  HealthCheckStrategy,
+  Versioned,
+} from "@checkstack/backend-api";
+import {
+  createMockQueueManager,
+  createMockLogger,
+} from "@checkstack/test-utils-backend";
+import { z } from "zod";
+
+// Note: ./db and ./logger are mocked via test-preload.ts (bunfig.toml preload)
+// This ensures mocks are in place BEFORE any module imports them
+
+import { PluginManager } from "./plugin-manager";
+
+describe("HealthCheck Plugin Integration", () => {
+  let pluginManager: PluginManager;
+
+  beforeEach(() => {
+    pluginManager = new PluginManager();
+  });
+
+  it("should allow a plugin to register a health check strategy", async () => {
+    const mockRouter = {
+      route: mock(),
+      all: mock(),
+      newResponse: mock(),
+    } as never;
+
+    // Define a mock execute function for the strategy
+    const mockExecute = mock(async () => ({ status: "healthy" as const }));
+
+    // 1. Define a mock strategy
+    const mockStrategy: HealthCheckStrategy = {
+      id: "test-strategy",
+      displayName: "Test Strategy",
+      description: "A test strategy for integration testing",
+      config: new Versioned({
+        version: 1,
+        schema: z.object({}),
+      }),
+      aggregatedResult: new Versioned({
+        version: 1,
+        schema: z.record(z.string(), z.unknown()),
+      }),
+      execute: mockExecute,
+      aggregateResult: mock(() => ({})),
+    };
+
+    // 2. Define a mock plugin that registers this strategy
+    const testPlugin = createBackendPlugin({
+      metadata: { pluginId: "test-plugin" },
+      register(env) {
+        env.registerInit({
+          deps: {
+            healthCheckRegistry: coreServices.healthCheckRegistry,
+          },
+          init: async ({ healthCheckRegistry }) => {
+            healthCheckRegistry.register(mockStrategy);
+          },
+        });
+      },
+    });
+
+    // Register mock services since core-services is mocked as no-op
+    pluginManager.registerService(
+      coreServices.queueManager,
+      createMockQueueManager()
+    );
+    pluginManager.registerService(coreServices.logger, createMockLogger());
+    pluginManager.registerService(coreServices.database, {} as never); // Mock database
+
+    // 4. Load plugins using the PluginManager with manual injection
+    await pluginManager.loadPlugins(mockRouter, [testPlugin], {
+      skipDiscovery: true,
+    });
+
+    // 5. Verify the strategy is registered in the registry managed by PluginManager
+    const registry = await pluginManager.getService(
+      coreServices.healthCheckRegistry
+    );
+    expect(registry).toBeDefined();
+
+    const retrieved = registry?.getStrategy(mockStrategy.id);
+    expect(retrieved).toBe(mockStrategy);
+    expect(retrieved?.displayName).toBe("Test Strategy");
+    expect(retrieved?.id).toBe("test-strategy");
+    expect(retrieved?.execute).toBe(mockExecute);
+  });
+});