@checkstack/backend-api 0.0.2

package/src/rpc.ts

@@ -0,0 +1,284 @@
+import { os as baseOs, ORPCError, Router } from "@orpc/server";
+import { AnyContractRouter } from "@orpc/contract";
+import { HealthCheckRegistry } from "./health-check";
+import {
+  QueuePluginRegistry,
+  QueueManager,
+} from "@checkstack/queue-api";
+import {
+  ProcedureMetadata,
+  qualifyPermissionId,
+} from "@checkstack/common";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  Logger,
+  Fetch,
+  AuthService,
+  AuthUser,
+  RealUser,
+  ServiceUser,
+} from "./types";
+import type { PluginMetadata } from "@checkstack/common";
+import type { Hook } from "./hooks";
+
+// =============================================================================
+// CONTEXT TYPES
+// =============================================================================
+
+/**
+ * Function type for emitting hooks from request handlers.
+ */
+export type EmitHookFn = <T>(hook: Hook<T>, payload: T) => Promise<void>;
+
+export interface RpcContext {
+  /**
+   * The plugin metadata for this request.
+   * Use this to access pluginId and other plugin configuration.
+   */
+  pluginMetadata: PluginMetadata;
+
+  db: NodePgDatabase<Record<string, unknown>>;
+  logger: Logger;
+  fetch: Fetch;
+  auth: AuthService;
+  user?: AuthUser;
+  healthCheckRegistry: HealthCheckRegistry;
+  queuePluginRegistry: QueuePluginRegistry;
+  queueManager: QueueManager;
+  /** Emit a hook event for cross-plugin communication */
+  emitHook: EmitHookFn;
+}
+
+/** Context with authenticated real user */
+export interface UserRpcContext extends RpcContext {
+  user: RealUser;
+}
+
+/** Context with authenticated service */
+export interface ServiceRpcContext extends RpcContext {
+  user: ServiceUser;
+}
+
+/**
+ * The core oRPC server instance for the entire backend.
+ * We use $context to define the required initial context for all procedures.
+ */
+export const os = baseOs.$context<RpcContext>();
+
+// Re-export ProcedureMetadata from common for convenience
+export type { ProcedureMetadata } from "@checkstack/common";
+
+// =============================================================================
+// UNIFIED AUTH MIDDLEWARE
+// =============================================================================
+
+/**
+ * Unified authentication and authorization middleware.
+ *
+ * Automatically enforces based on contract metadata:
+ * 1. User type (from meta.userType):
+ *    - "anonymous": No authentication required, no permission checks
+ *    - "public": Anyone can attempt, but permissions are checked (anonymous role for guests)
+ *    - "user": Only real users (frontend authenticated)
+ *    - "service": Only services (backend-to-backend)
+ *    - "authenticated": Either users or services, but must be authenticated (default)
+ * 2. Permissions (from meta.permissions, only for real users or public anonymous)
+ *
+ * Use this in backend routers: `implement(contract).$context<RpcContext>().use(autoAuthMiddleware)`
+ */
+export const autoAuthMiddleware = os.middleware(
+  async ({ next, context, procedure }) => {
+    const meta = procedure["~orpc"]?.meta as ProcedureMetadata | undefined;
+    const requiredUserType = meta?.userType || "authenticated";
+    const contractPermissions = meta?.permissions || [];
+
+    // Prefix contract permissions with pluginId to get fully-qualified permission IDs
+    // Contract defines: "catalog.read" -> Stored in DB as: "catalog.catalog.read"
+    const requiredPermissions = contractPermissions.map((p: string) =>
+      qualifyPermissionId(context.pluginMetadata, { id: p })
+    );
+
+    // Helper to wrap next() with error logging
+    const nextWithErrorLogging = async () => {
+      try {
+        return await next({});
+      } catch (error) {
+        // Log the full error before oRPC sanitizes it to a generic 500
+        if (error instanceof ORPCError) {
+          // ORPCError is intentional - log at debug level
+          context.logger.debug("RPC error response:", {
+            code: error.code,
+            message: error.message,
+            data: error.data,
+          });
+        } else {
+          // Unexpected error - log at error level with full stack trace
+          context.logger.error("Unexpected RPC error:", error);
+        }
+        throw error;
+      }
+    };
+
+    // 1. Handle anonymous endpoints - no auth required, no permission checks
+    if (requiredUserType === "anonymous") {
+      return nextWithErrorLogging();
+    }
+
+    // 2. Handle public endpoints - anyone can attempt, but permissions are checked
+    if (requiredUserType === "public") {
+      if (context.user) {
+        // Authenticated user or application - check their permissions
+        if (
+          (context.user.type === "user" ||
+            context.user.type === "application") &&
+          requiredPermissions.length > 0
+        ) {
+          const userPermissions = context.user.permissions || [];
+          const hasPermission = requiredPermissions.some(
+            (p: string) =>
+              userPermissions.includes("*") || userPermissions.includes(p)
+          );
+
+          if (!hasPermission) {
+            throw new ORPCError("FORBIDDEN", {
+              message: `Missing permission: ${requiredPermissions.join(
+                " or "
+              )}`,
+            });
+          }
+        }
+        // Services are trusted with all permissions
+      } else {
+        // Anonymous user - check anonymous role permissions
+        if (requiredPermissions.length > 0) {
+          const anonymousPermissions =
+            await context.auth.getAnonymousPermissions();
+          const hasPermission = requiredPermissions.some((p: string) =>
+            anonymousPermissions.includes(p)
+          );
+
+          if (!hasPermission) {
+            throw new ORPCError("FORBIDDEN", {
+              message: `Anonymous access not permitted for this resource`,
+            });
+          }
+        }
+      }
+      return nextWithErrorLogging();
+    }
+
+    // 3. Enforce authentication for user/service/authenticated types
+    if (!context.user) {
+      throw new ORPCError("UNAUTHORIZED", {
+        message: "Authentication required",
+      });
+    }
+
+    const user = context.user;
+
+    // 4. Enforce user type
+    if (requiredUserType === "user" && user.type !== "user") {
+      throw new ORPCError("FORBIDDEN", {
+        message: "This endpoint is for users only",
+      });
+    }
+    if (requiredUserType === "service" && user.type !== "service") {
+      throw new ORPCError("FORBIDDEN", {
+        message: "This endpoint is for services only",
+      });
+    }
+
+    // 5. Enforce permissions (for real users and applications)
+    if (
+      (user.type === "user" || user.type === "application") &&
+      requiredPermissions.length > 0
+    ) {
+      const userPermissions = user.permissions || [];
+      const hasPermission = requiredPermissions.some(
+        (p: string) =>
+          userPermissions.includes("*") || userPermissions.includes(p)
+      );
+
+      if (!hasPermission) {
+        throw new ORPCError("FORBIDDEN", {
+          message: `Missing permission: ${requiredPermissions.join(" or ")}`,
+        });
+      }
+    }
+
+    // Pass through - services are trusted with all permissions
+    return nextWithErrorLogging();
+  }
+);
+
+// =============================================================================
+// CONTRACT BUILDER
+// =============================================================================
+
+/**
+ * Base contract builder with automatic authentication and authorization.
+ *
+ * All plugin contracts should use this builder. It ensures that:
+ * 1. All procedures are authenticated by default
+ * 2. User type is enforced based on meta.userType
+ * 3. Permissions are enforced based on meta.permissions
+ *
+ * @example
+ * import { baseContractBuilder } from "@checkstack/backend-api";
+ * import { permissions } from "./permissions";
+ *
+ * const myContract = {
+ *   // User-only endpoint with specific permission
+ *   getItems: baseContractBuilder
+ *     .meta({ userType: "user", permissions: [permissions.myPluginRead.id] })
+ *     .output(z.array(ItemSchema)),
+ *
+ *   // Service-only endpoint (backend-to-backend)
+ *   internalSync: baseContractBuilder
+ *     .meta({ userType: "service" })
+ *     .input(z.object({ data: z.string() }))
+ *     .output(z.object({ success: z.boolean() })),
+ *
+ *   // Public authenticated endpoint (both users and services)
+ *   getPublicInfo: baseContractBuilder
+ *     .meta({ userType: "authenticated" })
+ *     .output(z.object({ info: z.string() })),
+ * };
+ */
+export const baseContractBuilder = os.use(autoAuthMiddleware).meta({});
+
+// =============================================================================
+// RPC SERVICE INTERFACE
+// =============================================================================
+
+/**
+ * Service interface for the RPC registry.
+ */
+export interface RpcService {
+  /**
+   * Registers an oRPC router and its contract for this plugin.
+   * Routes are automatically prefixed with /api/{pluginName}/
+   * The contract is used for OpenAPI generation.
+   * @param router - The oRPC router instance
+   * @param contract - The oRPC contract definition (from *-common package)
+   */
+  registerRouter<C extends AnyContractRouter>(
+    router: Router<C, RpcContext>,
+    contract: C
+  ): void;
+
+  /**
+   * Registers a raw HTTP handler for this plugin.
+   * Routes are automatically prefixed with /api/{pluginName}/
+   * This is useful for third-party libraries that provide their own handlers (e.g. Better Auth).
+   * @param handler - The HTTP request handler
+   * @param path - Optional path within plugin namespace (defaults to "/")
+   */
+  registerHttpHandler(
+    handler: (req: Request) => Promise<Response>,
+    path?: string
+  ): void;
+}
+
+export { z as zod } from "zod";
+export * from "./contract";

package/src/schema-utils.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { getConfigMeta } from "./zod-config";
+
+/**
+ * Adds x-secret, x-color, x-options-resolver, x-depends-on, x-searchable, and x-hidden
+ * metadata to JSON Schema based on registry metadata.
+ * This is used internally by toJsonSchema.
+ * Recursively processes nested objects and arrays.
+ */
+function addSchemaMetadata(
+  zodSchema: z.ZodTypeAny,
+  jsonSchema: Record<string, unknown>
+): void {
+  // Handle arrays - recurse into items
+  if (zodSchema instanceof z.ZodArray) {
+    const itemsSchema = (zodSchema as z.ZodArray<z.ZodTypeAny>).element;
+    const jsonItems = jsonSchema.items as Record<string, unknown> | undefined;
+    if (jsonItems) {
+      addSchemaMetadata(itemsSchema, jsonItems);
+    }
+    return;
+  }
+
+  // Handle optional - unwrap and recurse
+  if (zodSchema instanceof z.ZodOptional) {
+    const innerSchema = zodSchema.unwrap() as z.ZodTypeAny;
+    addSchemaMetadata(innerSchema, jsonSchema);
+    return;
+  }
+
+  // Type guard to check if this is an object schema
+  if (!("shape" in zodSchema)) return;
+
+  const objectSchema = zodSchema as z.ZodObject<z.ZodRawShape>;
+  const properties = jsonSchema.properties as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+
+  if (!properties) return;
+
+  for (const [key, fieldSchema] of Object.entries(objectSchema.shape)) {
+    const zodField = fieldSchema as z.ZodTypeAny;
+    const jsonField = properties[key];
+
+    if (!jsonField) continue;
+
+    // Get metadata from registry
+    const meta = getConfigMeta(zodField);
+    if (meta) {
+      if (meta["x-secret"]) jsonField["x-secret"] = true;
+      if (meta["x-color"]) jsonField["x-color"] = true;
+      if (meta["x-hidden"]) jsonField["x-hidden"] = true;
+      if (meta["x-options-resolver"]) {
+        jsonField["x-options-resolver"] = meta["x-options-resolver"];
+        if (meta["x-depends-on"])
+          jsonField["x-depends-on"] = meta["x-depends-on"];
+        if (meta["x-searchable"]) jsonField["x-searchable"] = true;
+      }
+    }
+
+    // Recurse into nested objects and arrays
+    addSchemaMetadata(zodField, jsonField);
+  }
+}
+
+/**
+ * Converts a Zod schema to JSON Schema with automatic registry metadata.
+ * Uses Zod v4's native toJSONSchema() method.
+ *
+ * The registry metadata enables DynamicForm to automatically render
+ * specialized input fields (password for secrets, color picker for colors,
+ * dropdowns for optionsResolver fields, hidden for auto-populated fields).
+ */
+export function toJsonSchema(zodSchema: z.ZodTypeAny): Record<string, unknown> {
+  // Use Zod's native JSON Schema conversion
+  const jsonSchema = zodSchema.toJSONSchema() as Record<string, unknown>;
+  addSchemaMetadata(zodSchema, jsonSchema);
+  return jsonSchema;
+}

package/src/service-ref.ts

@@ -0,0 +1,15 @@
+export type ServiceRef<T> = {
+  id: string;
+  T: T;
+  toString(): string;
+};
+
+export function createServiceRef<T>(id: string): ServiceRef<T> {
+  return {
+    id,
+    T: undefined as T,
+    toString() {
+      return `ServiceRef(${id})`;
+    },
+  };
+}

package/src/test-utils.ts

@@ -0,0 +1,65 @@
+import { mock } from "bun:test";
+import { RpcContext, EmitHookFn } from "./rpc";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { HealthCheckRegistry } from "./health-check";
+import {
+  QueuePluginRegistry,
+  QueueManager,
+} from "@checkstack/queue-api";
+
+/**
+ * Creates a mocked oRPC context for testing.
+ */
+export function createMockRpcContext(
+  overrides: Partial<RpcContext> = {}
+): RpcContext {
+  return {
+    pluginMetadata: { pluginId: "test-plugin" },
+    db: mock() as unknown as NodePgDatabase<Record<string, unknown>>,
+    logger: {
+      info: mock(),
+      error: mock(),
+      warn: mock(),
+      debug: mock(),
+    },
+    fetch: {
+      fetch: mock(),
+      forPlugin: mock().mockReturnValue({
+        fetch: mock(),
+        get: mock(),
+        post: mock(),
+        put: mock(),
+        patch: mock(),
+        delete: mock(),
+      }),
+    },
+    auth: {
+      authenticate: mock(),
+      getCredentials: mock().mockResolvedValue({ headers: {} }),
+      getAnonymousPermissions: mock().mockResolvedValue([]),
+    },
+    healthCheckRegistry: {
+      registerStrategy: mock(),
+      getStrategies: mock().mockReturnValue([]),
+      getStrategy: mock(),
+    } as unknown as HealthCheckRegistry,
+    queuePluginRegistry: {
+      register: mock(),
+      getPlugin: mock(),
+      getPlugins: mock().mockReturnValue([]),
+    } as unknown as QueuePluginRegistry,
+    queueManager: {
+      getQueue: mock(),
+      getActivePlugin: mock(),
+      getActiveConfig: mock(),
+      setActiveBackend: mock(),
+      getInFlightJobCount: mock(),
+      listAllRecurringJobs: mock(),
+      startPolling: mock(),
+      shutdown: mock(),
+    } as unknown as QueueManager,
+    user: undefined,
+    emitHook: mock() as unknown as EmitHookFn,
+    ...overrides,
+  };
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+import { ZodSchema } from "zod";
+import { ClientDefinition, InferClient } from "@checkstack/common";
+
+export interface Logger {
+  info(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+}
+
+export interface Fetch {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  forPlugin(pluginId: string): {
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    get(path: string, init?: RequestInit): Promise<Response>;
+    post(path: string, body?: unknown, init?: RequestInit): Promise<Response>;
+    put(path: string, body?: unknown, init?: RequestInit): Promise<Response>;
+    patch(path: string, body?: unknown, init?: RequestInit): Promise<Response>;
+    delete(path: string, init?: RequestInit): Promise<Response>;
+  };
+}
+
+/**
+ * Real user authenticated via session/token (human users).
+ * Has permissions and roles from the RBAC system.
+ */
+export interface RealUser {
+  type: "user";
+  id: string;
+  email?: string;
+  name?: string;
+  permissions?: string[];
+  roles?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Service user for backend-to-backend calls.
+ * Trusted implicitly - no permissions/roles needed.
+ */
+export interface ServiceUser {
+  type: "service";
+  pluginId: string;
+}
+
+/**
+ * External application authenticated via API key.
+ * Has permissions and roles from the RBAC system like RealUser.
+ */
+export interface ApplicationUser {
+  type: "application";
+  id: string;
+  name: string;
+  permissions?: string[];
+  roles?: string[];
+}
+
+/**
+ * Discriminated union of user types.
+ * Use `user.type` to discriminate between real users, services, and applications.
+ */
+export type AuthUser = RealUser | ServiceUser | ApplicationUser;
+
+export interface AuthService {
+  authenticate(request: Request): Promise<AuthUser | undefined>;
+  getCredentials(): Promise<{ headers: Record<string, string> }>;
+  /**
+   * Get permissions assigned to the anonymous role.
+   * Used by autoAuthMiddleware to check permissions for unauthenticated
+   * users on "public" userType endpoints.
+   */
+  getAnonymousPermissions(): Promise<string[]>;
+}
+
+/**
+ * Authentication strategy for validating user credentials.
+ * Returns RealUser for human users or ApplicationUser for API keys.
+ */
+export interface AuthenticationStrategy {
+  validate(request: Request): Promise<RealUser | ApplicationUser | undefined>;
+}
+
+export interface PluginInstaller {
+  install(packageName: string): Promise<{ name: string; path: string }>;
+}
+
+/**
+ * Options for declarative route definitions (Deprecated, will be replaced by oRPC procedures).
+ */
+export interface RouteOptions {
+  permission?: string | string[];
+  schema?: ZodSchema;
+}
+
+/**
+ * RPC Client for typed backend-to-backend communication.
+ * Similar to the frontend RpcApi but with service token authentication.
+ */
+export interface RpcClient {
+  /**
+   * Get a typed RPC client for a specific plugin.
+   * @param def - The client definition from the target plugin's common package
+   * @returns Typed client for the plugin's RPC endpoints
+   *
+   * @example
+   * import { AuthApi } from "@checkstack/auth-common";
+   * const authClient = rpcClient.forPlugin(AuthApi);
+   * const result = await authClient.getRegistrationStatus();
+   */
+  forPlugin<T extends ClientDefinition>(def: T): InferClient<T>;
+}

package/src/zod-config.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+
+// ============================================================================
+// CONFIG REGISTRY - Typed metadata for configuration schemas
+// ============================================================================
+
+/**
+ * Metadata type for configuration schemas.
+ * Provides autocompletion for `.meta()` calls on config fields.
+ */
+export interface ConfigMeta {
+  /** Mark as a secret field (password input, encrypted storage, redacted in UI) */
+  "x-secret"?: boolean;
+  /** Mark as a color field (color picker input) */
+  "x-color"?: boolean;
+  /** Mark as hidden (auto-populated, not shown in forms) */
+  "x-hidden"?: boolean;
+  /** Name of the resolver function for dynamic options dropdown */
+  "x-options-resolver"?: string;
+  /** Field names this field depends on (triggers refetch when they change) */
+  "x-depends-on"?: string[];
+  /** If true, renders a searchable/filterable dropdown */
+  "x-searchable"?: boolean;
+}
+
+/**
+ * Registry for config schema metadata.
+ * Used by schema-utils.ts and config-service.ts for field detection.
+ */
+export const configRegistry = z.registry<ConfigMeta>();
+
+// ============================================================================
+// SCHEMA UNWRAPPING - Handle Optional/Default/Nullable wrappers
+// ============================================================================
+
+/**
+ * Unwraps a Zod schema to get the inner schema, handling:
+ * - ZodOptional
+ * - ZodDefault
+ * - ZodNullable
+ */
+function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny {
+  let unwrapped = schema;
+
+  if (unwrapped instanceof z.ZodOptional) {
+    unwrapped = unwrapped.unwrap() as z.ZodTypeAny;
+  }
+
+  if (unwrapped instanceof z.ZodDefault) {
+    unwrapped = unwrapped.def.innerType as z.ZodTypeAny;
+  }
+
+  if (unwrapped instanceof z.ZodNullable) {
+    unwrapped = unwrapped.unwrap() as z.ZodTypeAny;
+  }
+
+  return unwrapped;
+}
+
+/**
+ * Get config metadata for a schema.
+ * Automatically unwraps Optional/Default/Nullable wrappers.
+ */
+export function getConfigMeta(schema: z.ZodTypeAny): ConfigMeta | undefined {
+  return configRegistry.get(unwrapSchema(schema));
+}
+
+/**
+ * Check if a schema has secret metadata.
+ */
+export function isSecretSchema(schema: z.ZodTypeAny): boolean {
+  return getConfigMeta(schema)?.["x-secret"] === true;
+}
+
+/**
+ * Check if a schema has color metadata.
+ */
+export function isColorSchema(schema: z.ZodTypeAny): boolean {
+  return getConfigMeta(schema)?.["x-color"] === true;
+}
+
+/**
+ * Check if a schema has hidden metadata.
+ */
+export function isHiddenSchema(schema: z.ZodTypeAny): boolean {
+  return getConfigMeta(schema)?.["x-hidden"] === true;
+}
+
+/**
+ * Get options resolver metadata for a schema.
+ */
+export function getOptionsResolverMetadata(
+  schema: z.ZodTypeAny
+):
+  | { resolver: string; dependsOn?: string[]; searchable?: boolean }
+  | undefined {
+  const meta = getConfigMeta(schema);
+  if (!meta?.["x-options-resolver"]) return undefined;
+  return {
+    resolver: meta["x-options-resolver"],
+    dependsOn: meta["x-depends-on"],
+    searchable: meta["x-searchable"],
+  };
+}
+
+// ============================================================================
+// TYPED ZOD CONFIG - Uses .register() directly instead of overriding .meta()
+// ============================================================================
+
+/**
+ * Create a config string field with typed metadata.
+ * Registers metadata in configRegistry for detection by schema-utils and config-service.
+ *
+ * @example
+ * ```typescript
+ * import { configString } from "@checkstack/backend-api";
+ *
+ * const schema = z.object({
+ *   apiToken: configString({ "x-secret": true }).describe("API Token"),
+ *   projectKey: configString({
+ *     "x-options-resolver": "projectOptions",
+ *     "x-depends-on": ["connectionId"],
+ *   }),
+ * });
+ * ```
+ */
+export function configString(meta: ConfigMeta) {
+  const schema = z.string();
+  schema.register(configRegistry, meta);
+  return schema;
+}
+
+/**
+ * Create a config number field with typed metadata.
+ */
+export function configNumber(meta: ConfigMeta) {
+  const schema = z.number();
+  schema.register(configRegistry, meta);
+  return schema;
+}
+
+/**
+ * Create a config boolean field with typed metadata.
+ */
+export function configBoolean(meta: ConfigMeta) {
+  const schema = z.boolean();
+  schema.register(configRegistry, meta);
+  return schema;
+}