@checkstack/backend-api 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,228 @@
+# @checkstack/backend-api
+
+## 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/common@0.0.2
+  - @checkstack/queue-api@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 1.1.0
+
+### Minor Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+### Patch Changes
+
+- b4eb432: Fixed TypeScript generic contravariance issue in notification strategy registration.
+
+  The `register` and `addStrategy` methods now use generic type parameters instead of `unknown`, allowing notification strategy plugins with typed OAuth configurations to be registered without compiler errors. This fixes contravariance issues where function parameters in `StrategyOAuthConfig<TConfig>` could not be assigned when `TConfig` was a specific type.
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+  - @checkstack/queue-api@1.0.1
+  - @checkstack/signal-common@0.1.1
+
+## 1.0.0
+
+### Major Changes
+
+- 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);
+  ```
+
+### 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
+
+- 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
+
+- 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
+  });
+  ```
+
+- b354ab3: # Strategy Instructions Support & Telegram Notification Plugin
+
+  ## Strategy Instructions Interface
+
+  Added `adminInstructions` and `userInstructions` optional fields to the `NotificationStrategy` interface. These allow strategies to export markdown-formatted setup guides that are displayed in the configuration UI:
+
+  - **`adminInstructions`**: Shown when admins configure platform-wide strategy settings (e.g., how to create API keys)
+  - **`userInstructions`**: Shown when users configure their personal settings (e.g., how to link their account)
+
+  ### Updated Components
+
+  - `StrategyConfigCard` now accepts an `instructions` prop and renders it before config sections
+  - `StrategyCard` passes `adminInstructions` to `StrategyConfigCard`
+  - `UserChannelCard` renders `userInstructions` when users need to connect
+
+  ## New Telegram Notification Plugin
+
+  Added `@checkstack/notification-telegram-backend` plugin for sending notifications via Telegram:
+
+  - Uses [grammY](https://grammy.dev/) framework for Telegram Bot API integration
+  - Sends messages with MarkdownV2 formatting and inline keyboard buttons for actions
+  - Includes comprehensive admin instructions for bot setup via @BotFather
+  - Includes user instructions for account linking
+
+  ### Configuration
+
+  Admins need to configure a Telegram Bot Token obtained from @BotFather.
+
+  ### User Linking
+
+  The strategy uses `contactResolution: { type: "custom" }` for Telegram Login Widget integration. Full frontend integration for the Login Widget is pending future work.
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [e4d83fc]
+- Updated dependencies [b55fae6]
+- Updated dependencies [8e889b4]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/queue-api@1.0.0
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@checkstack/backend-api",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@checkstack/queue-api": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@orpc/client": "^1.13.2",
+    "@orpc/openapi": "^1.13.2",
+    "@orpc/server": "^1.13.2",
+    "@orpc/zod": "^1.13.2",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.0.0",
+    "marked": "^17.0.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0",
+    "drizzle-orm": "^0.45.1"
+  }
+}

package/src/assertions.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it } from "bun:test";
+import {
+  evaluateAssertion,
+  evaluateAssertions,
+  evaluateJsonPathAssertions,
+  numericField,
+  timeThresholdField,
+  stringField,
+  booleanField,
+  enumField,
+  jsonPathField,
+} from "./assertions";
+import { z } from "zod";
+
+describe("Assertion Schema Factories", () => {
+  describe("numericField", () => {
+    it("creates a schema with numeric operators", () => {
+      const schema = numericField("packetLoss", { min: 0, max: 100 });
+
+      const valid = schema.safeParse({
+        field: "packetLoss",
+        operator: "lessThan",
+        value: 50,
+      });
+      expect(valid.success).toBe(true);
+
+      const invalid = schema.safeParse({
+        field: "packetLoss",
+        operator: "lessThan",
+        value: 150,
+      });
+      expect(invalid.success).toBe(false);
+    });
+  });
+
+  describe("timeThresholdField", () => {
+    it("only allows lessThan and lessThanOrEqual operators", () => {
+      const schema = timeThresholdField("latency");
+
+      const valid = schema.safeParse({
+        field: "latency",
+        operator: "lessThan",
+        value: 100,
+      });
+      expect(valid.success).toBe(true);
+
+      const invalid = schema.safeParse({
+        field: "latency",
+        operator: "greaterThan",
+        value: 100,
+      });
+      expect(invalid.success).toBe(false);
+    });
+  });
+
+  describe("stringField", () => {
+    it("creates a schema with string operators", () => {
+      const schema = stringField("banner");
+
+      const valid = schema.safeParse({
+        field: "banner",
+        operator: "contains",
+        value: "SSH",
+      });
+      expect(valid.success).toBe(true);
+    });
+  });
+
+  describe("booleanField", () => {
+    it("creates a schema with isTrue/isFalse operators", () => {
+      const schema = booleanField("isExpired");
+
+      const isTrue = schema.safeParse({
+        field: "isExpired",
+        operator: "isTrue",
+      });
+      expect(isTrue.success).toBe(true);
+
+      const isFalse = schema.safeParse({
+        field: "isExpired",
+        operator: "isFalse",
+      });
+      expect(isFalse.success).toBe(true);
+    });
+  });
+
+  describe("enumField", () => {
+    it("creates a schema for enum values", () => {
+      const schema = enumField("status", ["SERVING", "NOT_SERVING"] as const);
+
+      const valid = schema.safeParse({
+        field: "status",
+        operator: "equals",
+        value: "SERVING",
+      });
+      expect(valid.success).toBe(true);
+
+      const invalid = schema.safeParse({
+        field: "status",
+        operator: "equals",
+        value: "INVALID",
+      });
+      expect(invalid.success).toBe(false);
+    });
+
+    it("generates JSON Schema with enum values for select rendering", () => {
+      const schema = enumField("status", [
+        "SERVING",
+        "NOT_SERVING",
+        "UNKNOWN",
+      ] as const);
+      const jsonSchema = schema.toJSONSchema() as Record<string, unknown>;
+      const properties = jsonSchema.properties as Record<
+        string,
+        Record<string, unknown>
+      >;
+
+      // Field should have const for discriminator
+      expect(properties.field.const).toBe("status");
+
+      // Operator should have const "equals"
+      expect(properties.operator.const).toBe("equals");
+
+      // Value should have enum array for select rendering
+      expect(properties.value.enum).toEqual([
+        "SERVING",
+        "NOT_SERVING",
+        "UNKNOWN",
+      ]);
+    });
+  });
+
+  describe("jsonPathField", () => {
+    it("creates a schema with dynamic operators", () => {
+      const schema = jsonPathField();
+
+      const valid = schema.safeParse({
+        path: "$.status",
+        operator: "equals",
+        value: "ok",
+      });
+      expect(valid.success).toBe(true);
+
+      const exists = schema.safeParse({ path: "$.data", operator: "exists" });
+      expect(exists.success).toBe(true);
+    });
+  });
+});
+
+describe("evaluateAssertion", () => {
+  describe("numeric operators", () => {
+    it("evaluates equals correctly", () => {
+      const result = evaluateAssertion(
+        { field: "count", operator: "equals", value: 5 },
+        { count: 5 }
+      );
+      expect(result.passed).toBe(true);
+    });
+
+    it("evaluates lessThan correctly", () => {
+      const result = evaluateAssertion(
+        { field: "latency", operator: "lessThan", value: 100 },
+        { latency: 50 }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "latency", operator: "lessThan", value: 100 },
+        { latency: 150 }
+      );
+      expect(failed.passed).toBe(false);
+      expect(failed.message).toContain("less than");
+    });
+
+    it("evaluates greaterThanOrEqual correctly", () => {
+      const result = evaluateAssertion(
+        { field: "uptime", operator: "greaterThanOrEqual", value: 99 },
+        { uptime: 99 }
+      );
+      expect(result.passed).toBe(true);
+    });
+  });
+
+  describe("string operators", () => {
+    it("evaluates contains correctly", () => {
+      const result = evaluateAssertion(
+        { field: "stdout", operator: "contains", value: "OK" },
+        { stdout: "Status: OK" }
+      );
+      expect(result.passed).toBe(true);
+    });
+
+    it("evaluates startsWith correctly", () => {
+      const result = evaluateAssertion(
+        { field: "banner", operator: "startsWith", value: "SSH-2.0" },
+        { banner: "SSH-2.0-OpenSSH" }
+      );
+      expect(result.passed).toBe(true);
+    });
+
+    it("evaluates matches correctly", () => {
+      const result = evaluateAssertion(
+        { field: "version", operator: "matches", value: "v\\d+\\.\\d+" },
+        { version: "v1.2.3" }
+      );
+      expect(result.passed).toBe(true);
+    });
+
+    it("evaluates isEmpty correctly", () => {
+      const result = evaluateAssertion(
+        { field: "stderr", operator: "isEmpty" },
+        { stderr: "" }
+      );
+      expect(result.passed).toBe(true);
+    });
+  });
+
+  describe("boolean operators", () => {
+    it("evaluates isTrue correctly", () => {
+      const result = evaluateAssertion(
+        { field: "connected", operator: "isTrue" },
+        { connected: true }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "connected", operator: "isTrue" },
+        { connected: false }
+      );
+      expect(failed.passed).toBe(false);
+    });
+
+    it("evaluates isFalse correctly", () => {
+      const result = evaluateAssertion(
+        { field: "isExpired", operator: "isFalse" },
+        { isExpired: false }
+      );
+      expect(result.passed).toBe(true);
+    });
+  });
+
+  describe("existence operators", () => {
+    it("evaluates exists correctly", () => {
+      const result = evaluateAssertion(
+        { field: "data", operator: "exists" },
+        { data: { foo: "bar" } }
+      );
+      expect(result.passed).toBe(true);
+
+      const notExists = evaluateAssertion(
+        { field: "data", operator: "exists" },
+        { data: null }
+      );
+      expect(notExists.passed).toBe(false);
+    });
+
+    it("evaluates notExists correctly", () => {
+      const result = evaluateAssertion(
+        { field: "error", operator: "notExists" },
+        { error: undefined }
+      );
+      expect(result.passed).toBe(true);
+    });
+  });
+});
+
+describe("evaluateAssertions", () => {
+  it("returns null when all assertions pass", () => {
+    const assertions = [
+      { field: "status", operator: "equals", value: 200 },
+      { field: "latency", operator: "lessThan", value: 100 },
+    ];
+    const result = evaluateAssertions(assertions, { status: 200, latency: 50 });
+    expect(result).toBe(null);
+  });
+
+  it("returns the first failed assertion", () => {
+    const assertions = [
+      { field: "status", operator: "equals", value: 200 },
+      { field: "latency", operator: "lessThan", value: 100 },
+    ];
+    const result = evaluateAssertions(assertions, {
+      status: 200,
+      latency: 150,
+    });
+    expect(result).toEqual({
+      field: "latency",
+      operator: "lessThan",
+      value: 100,
+    });
+  });
+
+  it("returns null for empty or undefined assertions", () => {
+    expect(evaluateAssertions([], {})).toBe(null);
+    expect(evaluateAssertions(undefined, {})).toBe(null);
+  });
+});
+
+describe("evaluateJsonPathAssertions", () => {
+  const extractPath = (path: string, json: unknown) => {
+    // Simple mock extractor for testing
+    if (path === "$.status") return (json as Record<string, unknown>)?.status;
+    if (path === "$.count") return (json as Record<string, unknown>)?.count;
+    return undefined;
+  };
+
+  it("evaluates JSONPath assertions with string coercion", () => {
+    const assertions = [{ path: "$.status", operator: "equals", value: "ok" }];
+    const result = evaluateJsonPathAssertions(
+      assertions,
+      { status: "ok" },
+      extractPath
+    );
+    expect(result).toBe(null);
+  });
+
+  it("evaluates JSONPath assertions with numeric coercion", () => {
+    const assertions = [
+      { path: "$.count", operator: "greaterThan", value: "5" },
+    ];
+    const result = evaluateJsonPathAssertions(
+      assertions,
+      { count: 10 },
+      extractPath
+    );
+    expect(result).toBe(null);
+
+    const failed = evaluateJsonPathAssertions(
+      assertions,
+      { count: 3 },
+      extractPath
+    );
+    expect(failed).toEqual(assertions[0]);
+  });
+
+  it("evaluates existence checks", () => {
+    const assertions = [{ path: "$.status", operator: "exists" }];
+    const result = evaluateJsonPathAssertions(
+      assertions,
+      { status: "ok" },
+      extractPath
+    );
+    expect(result).toBe(null);
+  });
+});