@checkstack/common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# @checkstack/common
+
+## 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.
+
+## 0.2.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`
+
+## 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

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@checkstack/common",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@orpc/contract": "^1.5.0",
+    "lucide-react": "0.562.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/client-definition.ts

@@ -0,0 +1,71 @@
+import type { ContractRouterClient, AnyContractRouter } from "@orpc/contract";
+import type { PluginMetadata } from "./plugin-metadata";
+
+/**
+ * A client definition that bundles an RPC contract type with its plugin metadata.
+ * Used for type-safe plugin RPC consumption.
+ *
+ * @example
+ * ```typescript
+ * // Define in auth-common
+ * export const AuthApi = createClientDefinition(authContract, pluginMetadata);
+ *
+ * // Use in frontend/backend
+ * const authClient = rpcApi.forPlugin(AuthApi);  // Fully typed!
+ * ```
+ */
+export interface ClientDefinition<
+  TContract extends AnyContractRouter = AnyContractRouter
+> {
+  readonly pluginId: string;
+  /**
+   * Phantom type for contract type inference.
+   * This property doesn't exist at runtime - it's only used by TypeScript
+   * to carry the contract type information for type inference.
+   */
+  readonly __contractType?: TContract;
+}
+
+/**
+ * Type helper to extract the client type from a ClientDefinition.
+ *
+ * @example
+ * ```typescript
+ * type AuthClient = InferClient<typeof AuthApi>;
+ * // Equivalent to: ContractRouterClient<typeof authContract>
+ * ```
+ */
+export type InferClient<T extends ClientDefinition> =
+  T extends ClientDefinition<infer C> ? ContractRouterClient<C> : never;
+
+/**
+ * Create a typed client definition for a plugin's RPC contract.
+ *
+ * This bundles the contract type with the plugin metadata, enabling type-safe
+ * forPlugin() calls without manual type annotations.
+ *
+ * @param _contract - The RPC contract object (used only for type inference)
+ * @param metadata - The plugin metadata from the plugin's plugin-metadata.ts
+ * @returns A ClientDefinition object that can be passed to forPlugin()
+ *
+ * @example
+ * ```typescript
+ * // In @checkstack/auth-common
+ * import { authContract } from "./rpc-contract";
+ * import { pluginMetadata } from "./plugin-metadata";
+ *
+ * export const AuthApi = createClientDefinition(authContract, pluginMetadata);
+ *
+ * // In consumer (frontend or backend)
+ * const authClient = rpcApi.forPlugin(AuthApi);
+ * await authClient.getUsers(); // Fully typed!
+ * ```
+ */
+export function createClientDefinition<TContract extends AnyContractRouter>(
+  _contract: TContract,
+  metadata: PluginMetadata
+): ClientDefinition<TContract> {
+  return {
+    pluginId: metadata.pluginId,
+  } as ClientDefinition<TContract>;
+}

package/src/icons.ts

@@ -0,0 +1,26 @@
+/**
+ * Lucide icon name type and Zod schema.
+ * This type is derived from the 'lucide-react' package icons export.
+ * Uses type-only import to avoid React runtime dependency on the backend.
+ *
+ * Icon names are PascalCase (e.g., 'CircleAlert', 'HeartPulse', 'Users')
+ */
+import type { icons } from "lucide-react";
+import { z } from "zod";
+
+/**
+ * Valid Lucide icon names (PascalCase).
+ * @example "CircleAlert", "Settings", "Users"
+ */
+export type LucideIconName = keyof typeof icons;
+
+/**
+ * Zod schema for LucideIconName.
+ * Uses string at runtime but infers LucideIconName type for compile-time safety.
+ * Use this in RPC contracts to get proper type inference.
+ *
+ * @example
+ * const schema = z.object({ icon: lucideIconSchema.optional() });
+ * // Infers: { icon?: LucideIconName }
+ */
+export const lucideIconSchema = z.string() as z.ZodType<LucideIconName>;

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./pagination";
+export * from "./routes";
+export * from "./plugin-metadata";
+export * from "./client-definition";
+export * from "./permission-utils";
+export * from "./icons";

package/src/pagination.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "bun:test";
+import { PaginationInputSchema, paginatedOutput } from "./pagination";
+import { z } from "zod";
+
+describe("PaginationInputSchema", () => {
+  it("should accept valid pagination input", () => {
+    const result = PaginationInputSchema.parse({
+      limit: 20,
+      offset: 40,
+    });
+
+    expect(result.limit).toBe(20);
+    expect(result.offset).toBe(40);
+  });
+
+  it("should use default values when not provided", () => {
+    const result = PaginationInputSchema.parse({});
+
+    expect(result.limit).toBe(10);
+    expect(result.offset).toBe(0);
+  });
+
+  it("should reject limit below 1", () => {
+    expect(() => PaginationInputSchema.parse({ limit: 0 })).toThrow();
+  });
+
+  it("should reject limit above 100", () => {
+    expect(() => PaginationInputSchema.parse({ limit: 101 })).toThrow();
+  });
+
+  it("should reject negative offset", () => {
+    expect(() => PaginationInputSchema.parse({ offset: -1 })).toThrow();
+  });
+});
+
+describe("paginatedOutput", () => {
+  const ItemSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+  });
+
+  it("should create correct output schema structure", () => {
+    const outputSchema = paginatedOutput(ItemSchema);
+
+    const result = outputSchema.parse({
+      items: [
+        { id: "1", name: "Item 1" },
+        { id: "2", name: "Item 2" },
+      ],
+      total: 100,
+    });
+
+    expect(result.items).toHaveLength(2);
+    expect(result.total).toBe(100);
+  });
+
+  it("should reject invalid items", () => {
+    const outputSchema = paginatedOutput(ItemSchema);
+
+    expect(() =>
+      outputSchema.parse({
+        items: [{ id: "1" }], // Missing 'name'
+        total: 1,
+      })
+    ).toThrow();
+  });
+
+  it("should reject missing total", () => {
+    const outputSchema = paginatedOutput(ItemSchema);
+
+    expect(() =>
+      outputSchema.parse({
+        items: [{ id: "1", name: "Item 1" }],
+      })
+    ).toThrow();
+  });
+
+  it("should accept empty items array", () => {
+    const outputSchema = paginatedOutput(ItemSchema);
+
+    const result = outputSchema.parse({
+      items: [],
+      total: 0,
+    });
+
+    expect(result.items).toEqual([]);
+    expect(result.total).toBe(0);
+  });
+});

package/src/pagination.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+
+/**
+ * Standard pagination input schema for RPC procedures.
+ * Use with paginatedOutput() for consistent pagination patterns.
+ *
+ * @example
+ * ```typescript
+ * // In your contract:
+ * import { PaginationInputSchema, paginatedOutput } from "@checkstack/common";
+ *
+ * const contract = {
+ *   getItems: _base
+ *     .input(PaginationInputSchema.extend({ search: z.string().optional() }))
+ *     .output(paginatedOutput(ItemSchema)),
+ * };
+ * ```
+ */
+export const PaginationInputSchema = z.object({
+  /** Number of items per page (1-100) */
+  limit: z.number().min(1).max(100).default(10),
+  /** Number of items to skip */
+  offset: z.number().min(0).default(0),
+});
+
+export type PaginationInput = z.infer<typeof PaginationInputSchema>;
+
+/**
+ * Creates a paginated output schema wrapper.
+ * Returns { items: T[], total: number } structure that works with usePagination hook.
+ *
+ * @example
+ * ```typescript
+ * // Contract definition:
+ * getUsers: _base
+ *   .input(PaginationInputSchema)
+ *   .output(paginatedOutput(UserSchema)),
+ *
+ * // Returns: { items: User[], total: number }
+ * ```
+ */
+export function paginatedOutput<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    items: z.array(itemSchema),
+    total: z.number(),
+  });
+}
+
+/**
+ * Type helper for paginated responses
+ */
+export type PaginatedResponse<T> = {
+  items: T[];
+  total: number;
+};

package/src/permission-utils.ts

@@ -0,0 +1,81 @@
+import type { PluginMetadata } from "./plugin-metadata";
+
+/**
+ * Supported actions for permissions.
+ */
+export type PermissionAction = "read" | "manage";
+
+/**
+ * Represents a permission that can be assigned to roles.
+ */
+export interface Permission {
+  /** Permission identifier (e.g., "catalog.read") */
+  id: string;
+  /** Human-readable description of what this permission allows */
+  description?: string;
+  /** Whether this permission is assigned to the default "users" role (authenticated users) */
+  isAuthenticatedDefault?: boolean;
+  /** Whether this permission is assigned to the "anonymous" role (public access) */
+  isPublicDefault?: boolean;
+}
+
+/**
+ * Represents a permission tied to a specific resource and action.
+ */
+export interface ResourcePermission extends Permission {
+  /** The resource this permission applies to */
+  resource: string;
+  /** The action allowed on the resource */
+  action: PermissionAction;
+}
+
+/**
+ * Helper to create a standardized resource permission.
+ *
+ * @param resource The resource name (e.g., "catalog", "healthcheck")
+ * @param action The action (e.g., "read", "manage")
+ * @param description Optional human-readable description
+ * @param options Additional options like isAuthenticatedDefault and isPublicDefault
+ */
+export function createPermission(
+  resource: string,
+  action: PermissionAction,
+  description?: string,
+  options?: { isAuthenticatedDefault?: boolean; isPublicDefault?: boolean }
+): ResourcePermission {
+  return {
+    id: `${resource}.${action}`,
+    resource,
+    action,
+    description,
+    isAuthenticatedDefault: options?.isAuthenticatedDefault,
+    isPublicDefault: options?.isPublicDefault,
+  };
+}
+
+/**
+ * Creates a fully-qualified permission ID by prefixing the permission's ID with the plugin ID.
+ *
+ * This is the canonical way to construct namespaced permission IDs for authorization checks.
+ * The function ensures consistent formatting across all permission-related operations.
+ *
+ * @param pluginMetadata - The plugin metadata containing the pluginId
+ * @param permission - The permission object containing the local permission ID
+ * @returns The fully-qualified permission ID (e.g., "catalog.catalog.read")
+ *
+ * @example
+ * ```typescript
+ * import { qualifyPermissionId } from "@checkstack/common";
+ * import { pluginMetadata } from "./plugin-metadata";
+ * import { permissions } from "./permissions";
+ *
+ * const qualifiedId = qualifyPermissionId(pluginMetadata, permissions.catalogRead);
+ * // Returns: "catalog.catalog.read"
+ * ```
+ */
+export function qualifyPermissionId(
+  pluginMetadata: Pick<PluginMetadata, "pluginId">,
+  permission: Pick<Permission, "id">
+): string {
+  return `${pluginMetadata.pluginId}.${permission.id}`;
+}

package/src/plugin-metadata.ts

@@ -0,0 +1,28 @@
+/**
+ * Plugin metadata interface for backend plugins.
+ *
+ * Each backend plugin should export a `pluginMetadata` object from `plugin-metadata.ts`
+ * that implements this interface. This provides a single source of truth for:
+ * - The pluginId (used by createBackendPlugin and drizzle schema generation)
+ * - Other plugin metadata that may be needed at build time
+ */
+export interface PluginMetadata {
+  /** The unique identifier for this plugin */
+  pluginId: string;
+
+  /**
+   * Previous plugin IDs that this plugin was known by.
+   * Used during schema migrations to rename old schemas to the new name.
+   * Only needed when renaming a plugin that has already been deployed.
+   */
+  previousPluginIds?: string[];
+}
+
+/**
+ * Helper function to create typed plugin metadata.
+ * @param metadata The plugin metadata object
+ * @returns The same object with proper typing
+ */
+export function definePluginMetadata<T extends PluginMetadata>(metadata: T): T {
+  return metadata;
+}

package/src/routes.ts

@@ -0,0 +1,139 @@
+/**
+ * Route definition with path and extracted parameters.
+ */
+export interface RouteDefinition<TParams extends string = string> {
+  /** Unique route identifier (pluginId.routeName) */
+  id: string;
+  /** Plugin identifier */
+  pluginId: string;
+  /** Relative path with optional :param placeholders */
+  path: string;
+  /** Parameter names extracted from path */
+  params: TParams[];
+}
+
+/**
+ * Plugin routes configuration object.
+ */
+export interface PluginRoutes<
+  T extends Record<string, RouteDefinition<string>> = Record<
+    string,
+    RouteDefinition<string>
+  >
+> {
+  pluginId: string;
+  routes: T;
+}
+
+/**
+ * Extract parameter names from a path string.
+ * E.g., "/detail/:id" -> ["id"]
+ */
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<Rest>
+    : T extends `${string}:${infer Param}`
+    ? Param
+    : never;
+
+/**
+ * Creates a typed plugin routes configuration.
+ * Routes are relative paths that will be prefixed with /{pluginId} at runtime.
+ *
+ * @param pluginId - Plugin identifier (without -frontend/-backend suffix)
+ * @param routes - Object mapping route names to paths
+ * @returns Typed routes object for use in frontend plugins and route resolution
+ *
+ * @example
+ * ```typescript
+ * // In maintenance-common/src/routes.ts
+ * export const maintenanceRoutes = createRoutes("maintenance", {
+ *   config: "/config",
+ *   detail: "/detail/:id",
+ * });
+ *
+ * // Usage in frontend:
+ * routes: [
+ *   { route: maintenanceRoutes.routes.config, element: <ConfigPage /> },
+ * ]
+ *
+ * // Resolution:
+ * resolveRoute(maintenanceRoutes.routes.config)           // "/maintenance/config"
+ * resolveRoute(maintenanceRoutes.routes.detail, { id: "123" }) // "/maintenance/detail/123"
+ * ```
+ */
+export function createRoutes<T extends Record<string, string>>(
+  pluginId: string,
+  routes: T
+): PluginRoutes<{
+  [K in keyof T]: RouteDefinition<ExtractParams<T[K]>>;
+}> {
+  const routeDefinitions: Record<string, RouteDefinition<string>> = {};
+
+  for (const [name, path] of Object.entries(routes)) {
+    // Extract params from path (e.g., ":id" -> "id")
+    const params: string[] = [];
+    const paramMatches = path.matchAll(/:([^/]+)/g);
+    for (const match of paramMatches) {
+      params.push(match[1]);
+    }
+
+    routeDefinitions[name] = {
+      id: `${pluginId}.${name}`,
+      pluginId,
+      path,
+      params,
+    };
+  }
+
+  return {
+    pluginId,
+    routes: routeDefinitions,
+  } as PluginRoutes<{
+    [K in keyof T]: RouteDefinition<ExtractParams<T[K]>>;
+  }>;
+}
+
+/**
+ * Resolves a route definition to a full path with the plugin prefix.
+ *
+ * @param route - Route definition from a plugin routes object
+ * @param params - Path parameters to substitute (required if route has params)
+ * @returns The full path with plugin prefix and substituted parameters
+ *
+ * @example
+ * ```typescript
+ * resolveRoute(maintenanceRoutes.routes.config)
+ * // Returns: "/maintenance/config"
+ *
+ * resolveRoute(maintenanceRoutes.routes.detail, { id: "123" })
+ * // Returns: "/maintenance/detail/123"
+ * ```
+ */
+// Overload: no params needed for routes without path parameters
+export function resolveRoute(route: RouteDefinition<never>): string;
+// Overload: params required for routes with path parameters
+export function resolveRoute<TParams extends string>(
+  route: RouteDefinition<TParams>,
+  params: Record<TParams, string>
+): string;
+// Implementation
+export function resolveRoute<TParams extends string>(
+  route: RouteDefinition<TParams>,
+  params?: Record<string, string>
+): string {
+  const basePath = `/${route.pluginId}${
+    route.path.startsWith("/") ? route.path : `/${route.path}`
+  }`;
+
+  if (!params || route.params.length === 0) {
+    return basePath;
+  }
+
+  // Substitute path parameters (e.g., :id -> actual value)
+  let result = basePath;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(`:${key}`, value);
+  }
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+// =============================================================================
+// RPC PROCEDURE METADATA
+// =============================================================================
+
+/**
+ * Metadata interface for RPC procedures.
+ * Used by contracts to define auth requirements and by backend middleware to enforce them.
+ *
+ * @example
+ * const contract = {
+ *   getItems: baseContractBuilder
+ *     .meta({
+ *       userType: "user",
+ *       permissions: [permissions.myPluginRead.id]
+ *     })
+ *     .output(z.array(ItemSchema)),
+ * };
+ */
+export interface ProcedureMetadata {
+  /**
+   * Which type of caller can access this endpoint.
+   * - "anonymous": No authentication required, no permission checks (fully public)
+   * - "public": Anyone can attempt, but permissions are checked (uses 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)
+   */
+  userType?: "anonymous" | "public" | "user" | "service" | "authenticated";
+
+  /**
+   * Permissions required to access this endpoint.
+   * Only enforced for real users - services are trusted.
+   * For "public" userType, permissions are checked against the anonymous role if not authenticated.
+   * User must have at least one of the listed permissions, or "*" (wildcard).
+   */
+  permissions?: string[];
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}