@checkstack/backend 0.0.2

package/src/services/event-bus.ts

@@ -0,0 +1,317 @@
+import type { Queue, QueueManager } from "@checkstack/queue-api";
+import type {
+  Hook,
+  HookSubscribeOptions,
+  HookUnsubscribe,
+  Logger,
+} from "@checkstack/backend-api";
+import type { EventBus as IEventBus } from "@checkstack/backend-api";
+
+export type HookListener<T> = (payload: T) => Promise<void>;
+
+interface ListenerRegistration {
+  id: string;
+  pluginId: string;
+  hookId: string;
+  consumerGroup: string;
+  listener: HookListener<unknown>;
+  mode: "broadcast" | "work-queue";
+}
+
+interface LocalListenerRegistration {
+  id: string;
+  pluginId: string;
+  hookId: string;
+  listener: HookListener<unknown>;
+}
+
+/**
+ * EventBus service for distributed event/hook system
+ *
+ * Leverages the Queue system to provide pub/sub patterns that work
+ * across multiple backend instances.
+ */
+export class EventBus implements IEventBus {
+  private queueChannels = new Map<string, Queue<unknown>>();
+  private listeners = new Map<string, ListenerRegistration[]>();
+  private localListeners = new Map<string, LocalListenerRegistration[]>();
+  private workerGroups = new Map<string, Set<string>>(); // pluginId -> Set<workerGroup>
+  private instanceId = crypto.randomUUID();
+
+  constructor(private queueManager: QueueManager, private logger: Logger) {}
+
+  /**
+   * Subscribe to a hook
+   */
+  async subscribe<T>(
+    pluginId: string,
+    hook: Hook<T>,
+    listener: HookListener<T>,
+    options: HookSubscribeOptions = {}
+  ): Promise<HookUnsubscribe> {
+    // Type narrowing for discriminated union
+    const mode = options.mode ?? "broadcast";
+    const workerGroup =
+      "workerGroup" in options ? options.workerGroup : undefined;
+    const maxRetries = "maxRetries" in options ? options.maxRetries ?? 3 : 3;
+
+    // Handle instance-local mode separately (no queue involvement)
+    if (mode === "instance-local") {
+      return this.subscribeLocal(pluginId, hook, listener);
+    }
+
+    // Validation: workerGroup required for work-queue mode
+    if (mode === "work-queue" && !workerGroup) {
+      throw new Error(
+        `workerGroup is required when mode is 'work-queue' for hook ${hook.id} in plugin ${pluginId}`
+      );
+    }
+
+    // Duplicate detection
+    if (mode === "work-queue" && workerGroup) {
+      const pluginWorkerGroups = this.workerGroups.get(pluginId) || new Set();
+
+      if (pluginWorkerGroups.has(workerGroup)) {
+        throw new Error(
+          `Duplicate workerGroup '${workerGroup}' detected in plugin ${pluginId} for hook ${hook.id}. ` +
+            `Each workerGroup must be unique within a plugin.`
+        );
+      }
+
+      pluginWorkerGroups.add(workerGroup);
+      this.workerGroups.set(pluginId, pluginWorkerGroups);
+    }
+
+    // Determine consumer group with plugin namespacing
+    const consumerGroup =
+      mode === "broadcast"
+        ? `${pluginId}.${hook.id}.broadcast.${this.instanceId}` // Unique per instance
+        : `${pluginId}.${workerGroup}`; // Shared across instances (namespaced)
+
+    const listenerId = crypto.randomUUID();
+
+    const registration: ListenerRegistration = {
+      id: listenerId,
+      pluginId,
+      hookId: hook.id,
+      consumerGroup,
+      listener: listener as HookListener<unknown>,
+      mode,
+    };
+
+    const listeners = this.listeners.get(hook.id) || [];
+    listeners.push(registration);
+    this.listeners.set(hook.id, listeners);
+
+    // Create queue channel if needed
+    if (!this.queueChannels.has(hook.id)) {
+      const channel = this.queueManager.getQueue<T>(hook.id);
+      this.queueChannels.set(hook.id, channel);
+
+      this.logger.debug(`Created event channel for hook: ${hook.id}`);
+    }
+
+    const channel = this.queueChannels.get(hook.id)!;
+
+    // Register consumer with appropriate group
+    await channel.consume(
+      async (job) => {
+        // Find listener by ID and invoke
+        const currentListeners = this.listeners.get(hook.id) || [];
+        const targetListener = currentListeners.find(
+          (l) => l.id === listenerId
+        );
+
+        if (targetListener) {
+          await this.invokeListener(targetListener, job.data);
+        }
+      },
+      {
+        consumerGroup,
+        maxRetries: mode === "work-queue" ? maxRetries : 0,
+      }
+    );
+
+    this.logger.debug(
+      `Subscribed to hook ${hook.id} (plugin: ${pluginId}, mode: ${mode}, group: ${consumerGroup})`
+    );
+
+    // Return unsubscribe function
+    return async () => {
+      await this.unsubscribe(pluginId, hook.id, listenerId, workerGroup);
+    };
+  }
+
+  /**
+   * Unsubscribe from a hook
+   */
+  private async unsubscribe(
+    pluginId: string,
+    hookId: string,
+    listenerId: string,
+    workerGroup?: string
+  ): Promise<void> {
+    // Remove listener registration
+    const listeners = this.listeners.get(hookId) || [];
+    const updatedListeners = listeners.filter((l) => l.id !== listenerId);
+
+    if (updatedListeners.length === 0) {
+      this.listeners.delete(hookId);
+
+      // Stop queue if no more listeners
+      const channel = this.queueChannels.get(hookId);
+      if (channel) {
+        await channel.stop();
+        this.queueChannels.delete(hookId);
+      }
+    } else {
+      this.listeners.set(hookId, updatedListeners);
+    }
+
+    // Remove from workerGroup tracking
+    if (workerGroup) {
+      const pluginWorkerGroups = this.workerGroups.get(pluginId);
+      if (pluginWorkerGroups) {
+        pluginWorkerGroups.delete(workerGroup);
+        if (pluginWorkerGroups.size === 0) {
+          this.workerGroups.delete(pluginId);
+        }
+      }
+    }
+
+    this.logger.debug(
+      `Unsubscribed listener ${listenerId} from hook ${hookId}`
+    );
+  }
+
+  /**
+   * Emit a hook
+   */
+  async emit<T>(hook: Hook<T>, payload: T): Promise<void> {
+    let channel = this.queueChannels.get(hook.id);
+
+    // Create channel lazily if not exists
+    if (!channel) {
+      channel = this.queueManager.getQueue<T>(hook.id);
+      this.queueChannels.set(hook.id, channel);
+    }
+
+    await channel.enqueue(payload);
+    this.logger.debug(`Emitted hook: ${hook.id}`);
+  }
+
+  /**
+   * Emit a hook locally only (not distributed).
+   * Use this for instance-local hooks like pluginDeregistering.
+   * Uses Promise.allSettled to ensure one listener error doesn't block others.
+   */
+  async emitLocal<T>(hook: Hook<T>, payload: T): Promise<void> {
+    const registrations = this.localListeners.get(hook.id) || [];
+
+    if (registrations.length === 0) {
+      this.logger.debug(`No local listeners for hook: ${hook.id}`);
+      return;
+    }
+
+    const results = await Promise.allSettled(
+      registrations.map(async (reg) => {
+        try {
+          await reg.listener(payload);
+          this.logger.debug(
+            `Local listener ${reg.id} (${reg.pluginId}) processed successfully`
+          );
+        } catch (error) {
+          this.logger.error(
+            `Local listener ${reg.id} (${reg.pluginId}) failed:`,
+            error
+          );
+          throw error;
+        }
+      })
+    );
+
+    const failures = results.filter((r) => r.status === "rejected");
+    if (failures.length > 0) {
+      this.logger.warn(
+        `${failures.length}/${registrations.length} local listeners failed for hook: ${hook.id}`
+      );
+    }
+
+    this.logger.debug(
+      `Emitted local hook: ${hook.id} (${registrations.length} listeners)`
+    );
+  }
+
+  /**
+   * Subscribe to a hook in instance-local mode (not distributed)
+   */
+  private async subscribeLocal<T>(
+    pluginId: string,
+    hook: Hook<T>,
+    listener: HookListener<T>
+  ): Promise<HookUnsubscribe> {
+    const listenerId = crypto.randomUUID();
+
+    const registration: LocalListenerRegistration = {
+      id: listenerId,
+      pluginId,
+      hookId: hook.id,
+      listener: listener as HookListener<unknown>,
+    };
+
+    const registrations = this.localListeners.get(hook.id) || [];
+    registrations.push(registration);
+    this.localListeners.set(hook.id, registrations);
+
+    this.logger.debug(
+      `Subscribed to local hook ${hook.id} (plugin: ${pluginId})`
+    );
+
+    // Return unsubscribe function
+    return async () => {
+      const current = this.localListeners.get(hook.id) || [];
+      const updated = current.filter((l) => l.id !== listenerId);
+
+      if (updated.length === 0) {
+        this.localListeners.delete(hook.id);
+      } else {
+        this.localListeners.set(hook.id, updated);
+      }
+
+      this.logger.debug(
+        `Unsubscribed local listener ${listenerId} from hook ${hook.id}`
+      );
+    };
+  }
+
+  /**
+   * Invoke a listener with error handling
+   */
+  private async invokeListener(
+    registration: ListenerRegistration,
+    payload: unknown
+  ): Promise<void> {
+    try {
+      await registration.listener(payload);
+      this.logger.debug(
+        `Listener ${registration.id} (${registration.consumerGroup}) processed successfully`
+      );
+    } catch (error) {
+      this.logger.error(
+        `Listener ${registration.id} (${registration.consumerGroup}) failed:`,
+        error
+      );
+      throw error; // Let queue handle retry
+    }
+  }
+
+  /**
+   * Shutdown the event bus
+   */
+  async shutdown(): Promise<void> {
+    await Promise.all(
+      [...this.queueChannels.values()].map((channel) => channel.stop())
+    );
+    this.logger.info("EventBus shut down");
+  }
+}

package/src/services/health-check-registry.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, mock } from "bun:test";
+import { CoreHealthCheckRegistry } from "./health-check-registry";
+import { HealthCheckStrategy, Versioned } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+import { z } from "zod";
+
+// Mock logger
+const mockLogger = createMockLogger();
+mock.module("../logger", () => ({
+  rootLogger: mockLogger,
+}));
+
+describe("CoreHealthCheckRegistry", () => {
+  let registry: CoreHealthCheckRegistry;
+
+  const mockStrategy1: HealthCheckStrategy = {
+    id: "test-strategy-1",
+    displayName: "Test Strategy 1",
+    description: "A test strategy",
+    config: new Versioned({
+      version: 1,
+      schema: z.object({}),
+    }),
+    aggregatedResult: new Versioned({
+      version: 1,
+      schema: z.record(z.string(), z.unknown()),
+    }),
+    execute: mock(() => Promise.resolve({ status: "healthy" as const })),
+    aggregateResult: mock(() => ({})),
+  };
+
+  const mockStrategy2: HealthCheckStrategy = {
+    id: "test-strategy-2",
+    displayName: "Test Strategy 2",
+    description: "Another test strategy",
+    config: new Versioned({
+      version: 1,
+      schema: z.object({}),
+    }),
+    aggregatedResult: new Versioned({
+      version: 1,
+      schema: z.record(z.string(), z.unknown()),
+    }),
+    execute: mock(() =>
+      Promise.resolve({ status: "unhealthy" as const, message: "Failed" })
+    ),
+    aggregateResult: mock(() => ({})),
+  };
+
+  beforeEach(() => {
+    registry = new CoreHealthCheckRegistry();
+  });
+
+  describe("register", () => {
+    it("should register a new health check strategy", () => {
+      registry.register(mockStrategy1);
+      expect(registry.getStrategy(mockStrategy1.id)).toBe(mockStrategy1);
+    });
+
+    it("should overwrite an existing strategy with the same ID", () => {
+      const overwritingStrategy: HealthCheckStrategy<any> = {
+        ...mockStrategy1,
+        displayName: "New Name",
+      };
+      registry.register(mockStrategy1);
+      registry.register(overwritingStrategy);
+
+      expect(registry.getStrategy(mockStrategy1.id)).toBe(overwritingStrategy);
+      expect(registry.getStrategy(mockStrategy1.id)?.displayName).toBe(
+        "New Name"
+      );
+    });
+  });
+
+  describe("getStrategySection", () => {
+    it("should return the strategy if it exists", () => {
+      registry.register(mockStrategy1);
+      expect(registry.getStrategy(mockStrategy1.id)).toBe(mockStrategy1);
+    });
+
+    it("should return undefined if the strategy does not exist", () => {
+      expect(registry.getStrategy("non-existent")).toBeUndefined();
+    });
+  });
+
+  describe("getStrategies", () => {
+    it("should return all registered strategies", () => {
+      registry.register(mockStrategy1);
+      registry.register(mockStrategy2);
+
+      const strategies = registry.getStrategies();
+      expect(strategies).toHaveLength(2);
+      expect(strategies).toContain(mockStrategy1);
+      expect(strategies).toContain(mockStrategy2);
+    });
+
+    it("should return an empty array if no strategies are registered", () => {
+      expect(registry.getStrategies()).toEqual([]);
+    });
+  });
+});

package/src/services/health-check-registry.ts

@@ -0,0 +1,27 @@
+import {
+  HealthCheckRegistry,
+  HealthCheckStrategy,
+} from "@checkstack/backend-api";
+import { rootLogger } from "../logger";
+
+export class CoreHealthCheckRegistry implements HealthCheckRegistry {
+  private strategies = new Map<string, HealthCheckStrategy>();
+
+  register(strategy: HealthCheckStrategy) {
+    if (this.strategies.has(strategy.id)) {
+      rootLogger.warn(
+        `HealthCheckStrategy '${strategy.id}' is already registered. Overwriting.`
+      );
+    }
+    this.strategies.set(strategy.id, strategy);
+    rootLogger.debug(`✅ Registered HealthCheckStrategy: ${strategy.id}`);
+  }
+
+  getStrategy(id: string) {
+    return this.strategies.get(id);
+  }
+
+  getStrategies() {
+    return [...this.strategies.values()];
+  }
+}

package/src/services/jwt.ts

@@ -0,0 +1,45 @@
+import { SignJWT, jwtVerify, importJWK, JWK } from "jose";
+import { keyStore } from "./keystore";
+
+export const jwtService = {
+  /**
+   * Signs a JWT payload for service-to-service communication
+   */
+  sign: async (payload: Record<string, unknown>, expiresIn = "1h") => {
+    const { kid, key } = await keyStore.getSigningKey();
+
+    return await new SignJWT(payload)
+      .setProtectedHeader({ alg: "RS256", kid })
+      .setIssuedAt()
+      .setExpirationTime(expiresIn)
+      .sign(key);
+  },
+
+  /**
+   * Verifies a JWT token using the KeyStore
+   */
+  verify: async (token: string) => {
+    try {
+      const { keys } = await keyStore.getPublicJWKS();
+
+      // Custom GetKey function for jose
+      const getKey = async (protectedHeader: { kid?: string }) => {
+        const kid = protectedHeader.kid;
+        if (!kid) throw new Error("Missing kid in header");
+
+        const jwk = keys.find((k: { kid?: string }) => k.kid === kid);
+        if (!jwk) {
+          throw new Error(`Key with kid ${kid} not found`);
+        }
+        return importJWK(jwk as JWK, "RS256");
+      };
+
+      const { payload } = await jwtVerify(token, getKey, {
+        algorithms: ["RS256"],
+      });
+      return payload;
+    } catch {
+      return;
+    }
+  },
+};

package/src/services/keystore.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { KeyStore } from "./keystore";
+
+// 1. Mock the DB module
+const mockDb = {
+  insert: mock(() => ({
+    values: mock(() => Promise.resolve()),
+  })),
+  select: mock(() => mockDb),
+  from: mock(() => mockDb),
+  where: mock(() => mockDb),
+  orderBy: mock(() => mockDb),
+  limit: mock(() => mockDb),
+};
+
+// Return empty list by default for selects
+// We will override implementation per test if needed
+// But since the chain returns `mockDb` (itself), the final await needs to return data.
+// Wait, `await db.select()...` means the object must be thenable or the last method returns a Promise.
+// Drizzle: .execute() or await directly.
+// In the code: `const validKeys = await db.select()...`
+// So the object returned by `limit()` must be thenable.
+
+const mockChain = () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const chain: any = {};
+  chain.insert = mock(() => chain);
+  chain.values = mock(() => Promise.resolve());
+  chain.update = mock(() => chain);
+  chain.set = mock(() => chain);
+  chain.delete = mock(() => chain);
+
+  chain.select = mock(() => chain);
+  chain.from = mock(() => chain);
+  chain.where = mock(() => chain);
+  chain.orderBy = mock(() => chain);
+  chain.limit = mock(() => chain); // limit is the last one called in getSigningKey
+
+  // Make it thenable to simulate 'await'
+  // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
+  chain.then = (resolve: any) => resolve([]); // Default empty array
+
+  return chain;
+};
+
+const dbMockInstance = mockChain();
+
+mock.module("../db", () => {
+  return {
+    db: dbMockInstance,
+  };
+});
+
+describe("KeyStore", () => {
+  let store: KeyStore;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let mockKeyForGeneration: any;
+
+  beforeEach(async () => {
+    store = new KeyStore();
+    // Reset mocks
+    dbMockInstance.select.mockClear();
+    dbMockInstance.insert.mockClear();
+    dbMockInstance.update.mockClear();
+    dbMockInstance.set.mockClear();
+    dbMockInstance.delete.mockClear();
+    dbMockInstance.where.mockClear();
+
+    // Reset default behavior
+    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
+    dbMockInstance.then = (resolve: any) => resolve([]);
+
+    // Pre-generate a valid key for mocking responses
+    const { generateKeyPair, exportJWK } = await import("jose");
+    const { publicKey, privateKey } = await generateKeyPair("RS256", {
+      extractable: true,
+    });
+    const publicJwk = await exportJWK(publicKey);
+    const privateJwk = await exportJWK(privateKey);
+
+    mockKeyForGeneration = {
+      id: "generated-kid",
+      publicKey: JSON.stringify(publicJwk),
+      privateKey: JSON.stringify(privateJwk),
+      algorithm: "RS256",
+      createdAt: new Date().toISOString(),
+      expiresAt: undefined,
+      revokedAt: undefined,
+    };
+  });
+
+  it("should generate a new key if no active key exists", async () => {
+    // Mock DB returning empty array for existing keys first, then the new key
+    let callCount = 0;
+    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
+    dbMockInstance.then = (resolve: any) => {
+      callCount++;
+      if (callCount === 1) {
+        return resolve([]); // First call: no active key
+      }
+      return resolve([mockKeyForGeneration]);
+    };
+
+    const result = await store.getSigningKey();
+
+    expect(result.kid).toBe("generated-kid"); // The mock key ID
+    expect(result.key).toBeTruthy();
+    expect(dbMockInstance.insert).toHaveBeenCalled();
+  });
+
+  it("should return the existing key if it is valid", async () => {
+    const { generateKeyPair, exportJWK } = await import("jose");
+    const { publicKey, privateKey } = await generateKeyPair("RS256", {
+      extractable: true,
+    });
+    const publicJwk = await exportJWK(publicKey);
+    const privateJwk = await exportJWK(privateKey);
+    const kid = "test-kid";
+
+    const mockKeyRow = {
+      id: kid,
+      publicKey: JSON.stringify(publicJwk),
+      privateKey: JSON.stringify(privateJwk),
+      algorithm: "RS256",
+      createdAt: new Date().toISOString(), // Fresh
+      expiresAt: undefined,
+      revokedAt: undefined,
+    };
+
+    // Mock DB return
+    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
+    dbMockInstance.then = (resolve: any) => resolve([mockKeyRow]);
+
+    const result = await store.getSigningKey();
+
+    expect(result.kid).toBe(kid);
+    // Should NOT have called insert (no rotation)
+    expect(dbMockInstance.insert).not.toHaveBeenCalled();
+  });
+
+  it("should rotate key if the existing one is too old", async () => {
+    // Generate a real key
+    const { generateKeyPair, exportJWK } = await import("jose");
+    const { publicKey, privateKey } = await generateKeyPair("RS256", {
+      extractable: true,
+    });
+    const publicJwk = await exportJWK(publicKey);
+    const privateJwk = await exportJWK(privateKey);
+    const kid = "old-kid";
+
+    // Create an OLD date > 1 hour ago
+    const oldDate = new Date(Date.now() - 1000 * 60 * 60 * 2).toISOString();
+
+    const mockKeyRow = {
+      id: kid,
+      publicKey: JSON.stringify(publicJwk),
+      privateKey: JSON.stringify(privateJwk),
+      algorithm: "RS256",
+      createdAt: oldDate,
+      expiresAt: undefined,
+      revokedAt: undefined,
+    };
+
+    let callCount = 0;
+    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
+    dbMockInstance.then = (resolve: any) => {
+      callCount++;
+      if (callCount === 1) {
+        return resolve([mockKeyRow]); // First call: check active
+      }
+      // Second call: fetch new key (in rotate logic)
+      // We need to return a valid new key so it doesn't crash
+      return resolve([
+        {
+          ...mockKeyRow,
+          id: "new-kid",
+          createdAt: new Date().toISOString(),
+        },
+      ]);
+    };
+
+    const result = await store.getSigningKey();
+
+    expect(result.kid).toBe("new-kid"); // Should return the NEW key
+    expect(dbMockInstance.insert).toHaveBeenCalled();
+    expect(dbMockInstance.update).toHaveBeenCalled(); // Should set expiresAt on old key
+    expect(dbMockInstance.set).toHaveBeenCalledWith(
+      expect.objectContaining({ expiresAt: expect.any(String) })
+    );
+  });
+
+  it("should delete expired keys in cleanupKeys", async () => {
+    await store.cleanupKeys();
+
+    expect(dbMockInstance.delete).toHaveBeenCalled();
+    expect(dbMockInstance.where).toHaveBeenCalled();
+  });
+});