@checkstack/backend-api 0.0.2

package/src/encryption.ts

@@ -0,0 +1,95 @@
+import crypto from "node:crypto";
+
+/**
+ * Master encryption key from environment variable.
+ * Should be 32 bytes (64 hex characters) for AES-256.
+ */
+const getMasterKey = (): Buffer => {
+  const key = process.env.ENCRYPTION_MASTER_KEY;
+  if (!key) {
+    throw new Error(
+      "ENCRYPTION_MASTER_KEY environment variable is required for secret encryption"
+    );
+  }
+
+  // Convert hex string to buffer
+  const keyBuffer = Buffer.from(key, "hex");
+  if (keyBuffer.length !== 32) {
+    throw new Error(
+      "ENCRYPTION_MASTER_KEY must be 32 bytes (64 hex characters)"
+    );
+  }
+
+  return keyBuffer;
+};
+
+/**
+ * Encrypts a plaintext string using AES-256-GCM.
+ * Returns base64-encoded string in format: iv:authTag:ciphertext
+ */
+export const encrypt = (plaintext: string): string => {
+  const key = getMasterKey();
+
+  // Generate random IV (12 bytes for GCM)
+  const iv = crypto.randomBytes(12);
+
+  // Create cipher
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+
+  // Encrypt
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final(),
+  ]);
+
+  // Get auth tag
+  const authTag = cipher.getAuthTag();
+
+  // Return base64-encoded iv:authTag:ciphertext
+  return `${iv.toString("base64")}:${authTag.toString(
+    "base64"
+  )}:${encrypted.toString("base64")}`;
+};
+
+/**
+ * Decrypts an encrypted string.
+ * Expects base64-encoded format: iv:authTag:ciphertext
+ */
+export const decrypt = (encrypted: string): string => {
+  const key = getMasterKey();
+
+  // Parse the encrypted string
+  const parts = encrypted.split(":");
+  if (parts.length !== 3) {
+    throw new Error("Invalid encrypted format");
+  }
+
+  const iv = Buffer.from(parts[0], "base64");
+  const authTag = Buffer.from(parts[1], "base64");
+  const ciphertext = Buffer.from(parts[2], "base64");
+
+  // Create decipher
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(authTag);
+
+  // Decrypt
+  const decrypted = Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final(),
+  ]);
+
+  return decrypted.toString("utf8");
+};
+
+/**
+ * Checks if a value appears to be encrypted.
+ * Encrypted values follow the format: base64:base64:base64
+ */
+export const isEncrypted = (value: string): boolean => {
+  const parts = value.split(":");
+  if (parts.length !== 3) return false;
+
+  // Check if all parts are valid base64
+  const base64Regex = /^[A-Za-z0-9+/]+=*$/;
+  return parts.every((part) => base64Regex.test(part));
+};

package/src/event-bus-types.ts

@@ -0,0 +1,28 @@
+import type { Hook, HookSubscribeOptions, HookUnsubscribe } from "./hooks";
+
+/**
+ * EventBus interface for dependency injection
+ */
+export interface EventBus {
+  subscribe<T>(
+    pluginId: string,
+    hook: Hook<T>,
+    listener: (payload: T) => Promise<void>,
+    options?: HookSubscribeOptions
+  ): Promise<HookUnsubscribe>;
+
+  /**
+   * Emit a hook through the distributed queue system.
+   * All instances receive broadcast hooks; one instance handles work-queue hooks.
+   */
+  emit<T>(hook: Hook<T>, payload: T): Promise<void>;
+
+  /**
+   * Emit a hook locally only (not distributed).
+   * Use for instance-local hooks that should only run on THIS instance.
+   * Uses Promise.allSettled to ensure one listener error doesn't block others.
+   */
+  emitLocal<T>(hook: Hook<T>, payload: T): Promise<void>;
+
+  shutdown(): Promise<void>;
+}

package/src/extension-point.ts

@@ -0,0 +1,11 @@
+export interface ExtensionPoint<T> {
+  id: string;
+  T: T; // phantom type for type safety
+}
+
+/**
+ * Creates a reference to an extension point.
+ */
+export function createExtensionPoint<T>(id: string): ExtensionPoint<T> {
+  return { id } as ExtensionPoint<T>;
+}

package/src/health-check.ts

@@ -0,0 +1,68 @@
+import { Versioned } from "./config-versioning";
+
+/**
+ * Health check result with typed metadata.
+ * TMetadata is defined by each strategy's resultMetadata schema.
+ */
+export interface HealthCheckResult<TMetadata = Record<string, unknown>> {
+  status: "healthy" | "unhealthy" | "degraded";
+  latencyMs?: number;
+  message?: string;
+  metadata?: TMetadata;
+}
+
+/**
+ * Raw run data for aggregation (passed to aggregateMetadata function).
+ */
+export interface HealthCheckRunForAggregation<
+  TResultMetadata = Record<string, unknown>
+> {
+  status: "healthy" | "unhealthy" | "degraded";
+  latencyMs?: number;
+  metadata?: TResultMetadata;
+}
+
+/**
+ * Health check strategy definition with typed config and result.
+ * @template TConfig - Configuration type for this strategy
+ * @template TResult - Per-run result type
+ * @template TAggregatedResult - Aggregated result type for buckets
+ */
+export interface HealthCheckStrategy<
+  TConfig = unknown,
+  TResult = Record<string, unknown>,
+  TAggregatedResult = Record<string, unknown>
+> {
+  id: string;
+  displayName: string;
+  description?: string;
+
+  /** Configuration schema with versioning and migrations */
+  config: Versioned<TConfig>;
+
+  /** Optional result schema with versioning and migrations */
+  result?: Versioned<TResult>;
+
+  /** Aggregated result schema for long-term bucket storage */
+  aggregatedResult: Versioned<TAggregatedResult>;
+
+  execute(config: TConfig): Promise<HealthCheckResult<TResult>>;
+
+  /**
+   * Aggregate results from multiple runs into a summary for bucket storage.
+   * Called during retention processing when raw data is aggregated.
+   * Core metrics (counts, latency) are auto-calculated by platform.
+   * This function only handles strategy-specific result aggregation.
+   */
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<TResult>[]
+  ): TAggregatedResult;
+}
+
+export interface HealthCheckRegistry {
+  register(strategy: HealthCheckStrategy<unknown, unknown, unknown>): void;
+  getStrategy(
+    id: string
+  ): HealthCheckStrategy<unknown, unknown, unknown> | undefined;
+  getStrategies(): HealthCheckStrategy<unknown, unknown, unknown>[];
+}

package/src/hooks.ts

@@ -0,0 +1,182 @@
+import type { Permission } from "@checkstack/common";
+
+/**
+ * Hook definition for type-safe event emission and subscription
+ */
+export interface Hook<T = unknown> {
+  id: string;
+  _type?: T; // Phantom type for TypeScript inference
+}
+
+/**
+ * Create a typed hook
+ */
+export function createHook<T>(id: string): Hook<T> {
+  return { id } as Hook<T>;
+}
+
+/**
+ * Core platform hooks
+ */
+export const coreHooks = {
+  /**
+   * Emitted when a plugin registers permissions
+   */
+  permissionsRegistered: createHook<{
+    pluginId: string;
+    permissions: Permission[];
+  }>("core.permissions.registered"),
+
+  /**
+   * Emitted when plugin configuration is updated
+   */
+  configUpdated: createHook<{
+    pluginId: string;
+    key: string;
+    value: unknown;
+  }>("core.config.updated"),
+
+  /**
+   * Emitted when a plugin completes initialization (Phase 2)
+   */
+  pluginInitialized: createHook<{
+    pluginId: string;
+  }>("core.plugin.initialized"),
+
+  /**
+   * Distributed request to deregister a plugin.
+   * All instances receive this and should perform local cleanup.
+   * Emitted via broadcast mode.
+   */
+  pluginDeregistrationRequested: createHook<{
+    pluginId: string;
+    deleteSchema: boolean;
+  }>("core.plugin.deregistration-requested"),
+
+  /**
+   * INSTANCE-LOCAL: Emitted BEFORE a plugin begins shutdown on THIS instance.
+   * Use emitLocal() to emit this hook - it does NOT go through the Queue.
+   * Listeners should perform cleanup that depends on cross-plugin services.
+   */
+  pluginDeregistering: createHook<{
+    pluginId: string;
+    reason: "uninstall" | "disable" | "shutdown";
+  }>("core.plugin.deregistering"),
+
+  /**
+   * Emitted AFTER a plugin has been fully removed.
+   * Use this for orphan cleanup (e.g., removing permissions from DB).
+   * Should be emitted with work-queue mode for DB operations.
+   */
+  pluginDeregistered: createHook<{
+    pluginId: string;
+  }>("core.plugin.deregistered"),
+
+  /**
+   * Emitted when the platform is shutting down.
+   * Gives plugins time to gracefully cleanup resources.
+   */
+  platformShutdown: createHook<{
+    reason: "signal" | "error" | "manual";
+  }>("core.platform.shutdown"),
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Plugin Installation (Multi-Instance Coordination)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Distributed request to install/enable a plugin.
+   * All instances receive this and should load the plugin into memory.
+   * Emitted via broadcast mode.
+   */
+  pluginInstallationRequested: createHook<{
+    pluginId: string;
+    pluginPath: string;
+  }>("core.plugin.installation-requested"),
+
+  /**
+   * INSTANCE-LOCAL: Emitted when a plugin is being loaded on THIS instance.
+   * Use emitLocal() to emit this hook - it does NOT go through the Queue.
+   */
+  pluginInstalling: createHook<{
+    pluginId: string;
+  }>("core.plugin.installing"),
+
+  /**
+   * Emitted AFTER a plugin has been fully installed and loaded.
+   * Use this for post-installation tasks (e.g., syncing to DB).
+   * Should be emitted with work-queue mode for DB operations.
+   */
+  pluginInstalled: createHook<{
+    pluginId: string;
+  }>("core.plugin.installed"),
+} as const;
+
+/**
+ * Hook subscription options using discriminated union for type safety.
+ *
+ * When mode is 'work-queue', workerGroup is REQUIRED at compile-time.
+ * When mode is 'broadcast', workerGroup is not allowed.
+ */
+export type HookSubscribeOptions =
+  | {
+      /**
+       * Broadcast mode: All instances receive and process the hook
+       */
+      mode?: "broadcast";
+      /**
+       * Not allowed in broadcast mode
+       */
+      workerGroup?: never;
+      /**
+       * Maximum retry attempts (not used in broadcast mode)
+       */
+      maxRetries?: number;
+    }
+  | {
+      /**
+       * Work-queue mode: Only one instance processes (load-balanced with retry)
+       */
+      mode: "work-queue";
+      /**
+       * Worker group identifier. REQUIRED for work-queue mode.
+       *
+       * Workers with the same group name compete (only one processes the message).
+       * Workers with different group names both process the message.
+       *
+       * Automatically namespaced by plugin ID to prevent conflicts.
+       *
+       * Examples:
+       * - 'db-sync' → becomes 'my-plugin.db-sync'
+       * - 'email-sender' → becomes 'my-plugin.email-sender'
+       */
+      workerGroup: string;
+      /**
+       * Maximum retry attempts for work-queue mode
+       * @default 3
+       */
+      maxRetries?: number;
+    }
+  | {
+      /**
+       * Instance-local mode: Events bypass the Queue and run in-memory only.
+       * Use for cleanup hooks that should NOT be distributed across instances.
+       * Emitted via emitLocal() instead of emit().
+       */
+      mode: "instance-local";
+      /**
+       * Not allowed in instance-local mode
+       */
+      workerGroup?: never;
+      /**
+       * Not applicable in instance-local mode
+       */
+      maxRetries?: never;
+    };
+
+/**
+ * Handle for unsubscribing from a hook
+ */
+export interface HookUnsubscribe {
+  (): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export * from "./service-ref";
+export * from "./extension-point";
+export * from "./core-services";
+export * from "./plugin-system";
+export * from "./health-check";
+export * from "./auth-strategy";
+export * from "./zod-config";
+export * from "./encryption";
+export * from "./schema-utils";
+export * from "./config-service";
+export * from "zod";
+export * from "./config-versioning";
+export * from "./rpc";
+export * from "./test-utils";
+export * from "./hooks";
+export * from "./event-bus-types";
+export * from "./plugin-admin-contract";
+export * from "./notification-strategy";
+export * from "./oauth-handler";
+export * from "./markdown";
+export * from "./email-layout";
+export * from "./assertions";
+export * from "./chart-metadata";

package/src/markdown.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+import {
+  markdownToHtml,
+  markdownToPlainText,
+  markdownToSlackMrkdwn,
+} from "./markdown";
+
+describe("markdownToHtml", () => {
+  it("converts bold text", () => {
+    const result = markdownToHtml("**bold**");
+    expect(result).toContain("<strong>bold</strong>");
+  });
+
+  it("converts italic text", () => {
+    const result = markdownToHtml("*italic*");
+    expect(result).toContain("<em>italic</em>");
+  });
+
+  it("converts links", () => {
+    const result = markdownToHtml("[link](https://example.com)");
+    expect(result).toContain('<a href="https://example.com">link</a>');
+  });
+
+  it("converts headers", () => {
+    const result = markdownToHtml("# Header");
+    expect(result).toContain("<h1");
+    expect(result).toContain("Header");
+  });
+
+  it("converts unordered lists", () => {
+    const result = markdownToHtml("- item 1\n- item 2");
+    expect(result).toContain("<ul>");
+    expect(result).toContain("<li>item 1</li>");
+    expect(result).toContain("<li>item 2</li>");
+  });
+
+  it("converts code blocks", () => {
+    const result = markdownToHtml("```\ncode\n```");
+    expect(result).toContain("<code>");
+  });
+
+  it("converts inline code", () => {
+    const result = markdownToHtml("use `code` here");
+    expect(result).toContain("<code>code</code>");
+  });
+});
+
+describe("markdownToPlainText", () => {
+  it("strips bold formatting", () => {
+    const result = markdownToPlainText("**bold** text");
+    expect(result).toBe("bold text");
+  });
+
+  it("strips italic formatting", () => {
+    const result = markdownToPlainText("*italic* text");
+    expect(result).toBe("italic text");
+  });
+
+  it("strips links but keeps text", () => {
+    const result = markdownToPlainText("[link](https://example.com)");
+    expect(result).toBe("link");
+  });
+
+  it("strips headers", () => {
+    const result = markdownToPlainText("# Header");
+    expect(result).toBe("Header");
+  });
+
+  it("preserves line breaks between paragraphs", () => {
+    const result = markdownToPlainText("First paragraph.\n\nSecond paragraph.");
+    expect(result).toContain("First paragraph.");
+    expect(result).toContain("Second paragraph.");
+  });
+
+  it("decodes HTML entities", () => {
+    const result = markdownToPlainText("A &amp; B");
+    expect(result).toBe("A & B");
+  });
+});
+
+describe("markdownToSlackMrkdwn", () => {
+  it("converts bold to Slack format", () => {
+    const result = markdownToSlackMrkdwn("**bold**");
+    expect(result).toBe("*bold*");
+  });
+
+  it("converts double underscore to Slack bold", () => {
+    const result = markdownToSlackMrkdwn("__bold__");
+    expect(result).toBe("*bold*");
+  });
+
+  it("converts links to Slack format", () => {
+    const result = markdownToSlackMrkdwn("[link](https://example.com)");
+    expect(result).toBe("<https://example.com|link>");
+  });
+
+  it("converts strikethrough", () => {
+    const result = markdownToSlackMrkdwn("~~strikethrough~~");
+    expect(result).toBe("~strikethrough~");
+  });
+
+  it("preserves inline code", () => {
+    const result = markdownToSlackMrkdwn("`code`");
+    expect(result).toBe("`code`");
+  });
+});

package/src/markdown.ts

@@ -0,0 +1,104 @@
+/**
+ * Markdown conversion utilities for notification strategies.
+ *
+ * These utilities allow strategies to convert markdown content to their
+ * native format (HTML for email, plain text for SMS, etc.).
+ *
+ * @module
+ */
+
+import { marked } from "marked";
+
+// Configure marked for email-safe HTML
+marked.setOptions({
+  gfm: true, // GitHub Flavored Markdown
+  breaks: true, // Convert \n to <br>
+});
+
+/**
+ * Convert markdown to HTML (safe for email rendering).
+ *
+ * Uses GitHub Flavored Markdown with line break support.
+ *
+ * @example
+ * ```typescript
+ * const html = markdownToHtml("**Bold** and *italic*");
+ * // Returns: "<p><strong>Bold</strong> and <em>italic</em></p>"
+ * ```
+ */
+export function markdownToHtml(markdown: string): string {
+  // marked.parse can return string | Promise<string>, but with sync config it's always string
+  return marked.parse(markdown) as string;
+}
+
+/**
+ * Strip markdown to plain text.
+ *
+ * Removes all formatting while preserving the content.
+ * Useful for strategies that don't support rich formatting (SMS, push).
+ *
+ * @example
+ * ```typescript
+ * const text = markdownToPlainText("**Bold** and [link](https://example.com)");
+ * // Returns: "Bold and link"
+ * ```
+ */
+export function markdownToPlainText(markdown: string): string {
+  // Convert to HTML first, then strip tags
+  const html = markdownToHtml(markdown);
+
+  // Strip HTML tags
+  let text = html.replaceAll(/<[^>]*>/g, "");
+
+  // Decode common HTML entities
+  text = text
+    .replaceAll("&amp;", "&")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&#39;", "'")
+    .replaceAll("&nbsp;", " ");
+
+  // Collapse multiple whitespace/newlines
+  text = text.replaceAll(/\n\s*\n/g, "\n").trim();
+
+  return text;
+}
+
+/**
+ * Convert markdown to Slack mrkdwn format.
+ *
+ * Slack uses a different markdown flavor with ~strikethrough~ syntax
+ * and different link formatting.
+ *
+ * @example
+ * ```typescript
+ * const mrkdwn = markdownToSlackMrkdwn("**Bold** and [link](https://example.com)");
+ * // Returns: "*Bold* and <https://example.com|link>"
+ * ```
+ */
+export function markdownToSlackMrkdwn(markdown: string): string {
+  let result = markdown;
+
+  // Convert strikethrough first: ~~text~~ -> ~text~
+  result = result.replaceAll(/~~(.+?)~~/g, "~$1~");
+
+  // Convert links: [text](url) -> <url|text>
+  result = result.replaceAll(/\[([^\]]+)\]\(([^)]+)\)/g, "<$2|$1>");
+
+  // Convert italic (single underscore only): _text_ -> _text_
+  // Note: We skip *italic* conversion because Slack uses * for bold
+  // and it would conflict with the **bold** -> *bold* conversion
+
+  // Convert bold: **text** or __text__ -> *text*
+  result = result.replaceAll(/\*\*(.+?)\*\*/g, "*$1*");
+  result = result.replaceAll(/__(.+?)__/g, "*$1*");
+
+  // Convert inline code: `code` -> `code` (same in Slack)
+  // No change needed
+
+  // Convert code blocks: ```code``` -> ```code``` (same in Slack)
+  // No change needed
+
+  return result;
+}