@checkstack/healthcheck-common 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,176 @@
 # @checkstack/healthcheck-common
 
+## 0.3.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+- f533141: Enforce health result factory function usage via branded types
+
+  - Added `healthResultSchema()` builder that enforces the use of factory functions at compile-time
+  - Added `healthResultArray()` factory for array fields (e.g., DNS resolved values)
+  - Added branded `HealthResultField<T>` type to mark schemas created by factory functions
+  - Consolidated `ChartType` and `HealthResultMeta` into `@checkstack/common` as single source of truth
+  - Updated all 12 health check strategies and 11 collectors to use `healthResultSchema()`
+  - Using raw `z.number()` etc. inside `healthResultSchema()` now causes a TypeScript error
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 8e43507: # Teams and Resource-Level Access Control
+
+  This release introduces a comprehensive Teams system for organizing users and controlling access to resources at a granular level.
+
+  ## Features
+
+  ### Team Management
+
+  - Create, update, and delete teams with name and description
+  - Add/remove users from teams
+  - Designate team managers with elevated privileges
+  - View team membership and manager status
+
+  ### Resource-Level Access Control
+
+  - Grant teams access to specific resources (systems, health checks, incidents, maintenances)
+  - Configure read-only or manage permissions per team
+  - Resource-level "Team Only" mode that restricts access exclusively to team members
+  - Separate `resourceAccessSettings` table for resource-level settings (not per-grant)
+  - Automatic cleanup of grants when teams are deleted (database cascade)
+
+  ### Middleware Integration
+
+  - Extended `autoAuthMiddleware` to support resource access checks
+  - Single-resource pre-handler validation for detail endpoints
+  - Automatic list filtering for collection endpoints
+  - S2S endpoints for access verification
+
+  ### Frontend Components
+
+  - `TeamsTab` component for managing teams in Auth Settings
+  - `TeamAccessEditor` component for assigning team access to resources
+  - Resource-level "Team Only" toggle in `TeamAccessEditor`
+  - Integration into System, Health Check, Incident, and Maintenance editors
+
+  ## Breaking Changes
+
+  ### API Response Format Changes
+
+  List endpoints now return objects with named keys instead of arrays directly:
+
+  ```typescript
+  // Before
+  const systems = await catalogApi.getSystems();
+
+  // After
+  const { systems } = await catalogApi.getSystems();
+  ```
+
+  Affected endpoints:
+
+  - `catalog.getSystems` → `{ systems: [...] }`
+  - `healthcheck.getConfigurations` → `{ configurations: [...] }`
+  - `incident.listIncidents` → `{ incidents: [...] }`
+  - `maintenance.listMaintenances` → `{ maintenances: [...] }`
+
+  ### User Identity Enrichment
+
+  `RealUser` and `ApplicationUser` types now include `teamIds: string[]` field with team memberships.
+
+  ## Documentation
+
+  See `docs/backend/teams.md` for complete API reference and integration guide.
+
+- 97c5a6b: Add UUID-based collector identification for better multiple collector support
+
+  **Breaking Change**: Existing health check configurations with collectors need to be recreated.
+
+  - Each collector instance now has a unique UUID assigned on creation
+  - Collector results are stored under the UUID key with `_collectorId` and `_assertionFailed` metadata
+  - Auto-charts correctly display separate charts for each collector instance
+  - Charts are now grouped by collector instance with clear headings
+  - Assertion status card shows pass/fail for each collector
+  - Renamed "Success" to "HTTP Success" to clarify it's about HTTP request success
+  - Fixed deletion of collectors not persisting to database
+  - Fixed duplicate React key warnings in auto-chart grid
+
+### Patch Changes
+
+- Updated dependencies [8e43507]
+  - @checkstack/common@0.1.0
+  - @checkstack/signal-common@0.0.4
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {

package/src/access.ts

@@ -0,0 +1,43 @@
+import { access, accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Health Check plugin.
+ */
+export const healthCheckAccess = {
+  /**
+   * Status-only access for viewing health check status.
+   * Enabled by default for anonymous and authenticated users.
+   */
+  status: access("healthcheck.status", "read", "View Health Check Status", {
+    isDefault: true,
+    isPublic: true,
+  }),
+
+  /**
+   * Configuration access for viewing and managing health check configurations.
+   */
+  configuration: accessPair("healthcheck", {
+    read: "Read Health Check Configurations",
+    manage: "Full management of Health Check Configurations",
+  }),
+
+  /**
+   * Access for viewing detailed health check run data including metadata.
+   * Allows access to extended visualizations without full management access.
+   */
+  details: access(
+    "healthcheck.details",
+    "read",
+    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)"
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const healthCheckAccessRules = [
+  healthCheckAccess.status,
+  healthCheckAccess.configuration.read,
+  healthCheckAccess.configuration.manage,
+  healthCheckAccess.details,
+];

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from "./permissions";
+export * from "./access";
 export * from "./schemas";
 export * from "./zod-health-result";
 

package/src/rpc-contract.ts

@@ -5,7 +5,7 @@ import {
 } from "@checkstack/common";
 import { pluginMetadata } from "./plugin-metadata";
 import { z } from "zod";
-import { permissions } from "./permissions";
+import { healthCheckAccess } from "./access";
 import {
   HealthCheckStrategyDtoSchema,
   CollectorDtoSchema,
@@ -44,13 +44,13 @@ const SystemHealthStatusResponseSchema = z.object({
 // Health Check RPC Contract using oRPC's contract-first pattern
 export const healthCheckContract = {
   // ==========================================================================
-  // STRATEGY MANAGEMENT (userType: "authenticated" with read permission)
+  // STRATEGY MANAGEMENT (userType: "authenticated" with read access)
   // ==========================================================================
 
   getStrategies: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .output(z.array(HealthCheckStrategyDtoSchema)),
 
@@ -61,7 +61,7 @@ export const healthCheckContract = {
   getCollectors: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(z.object({ strategyId: z.string() }))
     .output(z.array(CollectorDtoSchema)),
@@ -73,14 +73,16 @@ export const healthCheckContract = {
   getConfigurations: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
-    .output(z.array(HealthCheckConfigurationSchema)),
+    .output(
+      z.object({ configurations: z.array(HealthCheckConfigurationSchema) })
+    ),
 
   createConfiguration: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(CreateHealthCheckConfigurationSchema)
     .output(HealthCheckConfigurationSchema),
@@ -88,7 +90,7 @@ export const healthCheckContract = {
   updateConfiguration: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -101,7 +103,7 @@ export const healthCheckContract = {
   deleteConfiguration: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(z.string())
     .output(z.void()),
@@ -113,7 +115,7 @@ export const healthCheckContract = {
   getSystemConfigurations: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(z.string())
     .output(z.array(HealthCheckConfigurationSchema)),
@@ -125,7 +127,7 @@ export const healthCheckContract = {
   getSystemAssociations: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(z.object({ systemId: z.string() }))
     .output(
@@ -142,7 +144,7 @@ export const healthCheckContract = {
   associateSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -155,7 +157,7 @@ export const healthCheckContract = {
   disassociateSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -166,13 +168,13 @@ export const healthCheckContract = {
     .output(z.void()),
 
   // ==========================================================================
-  // RETENTION CONFIGURATION (userType: "authenticated" with manage permission)
+  // RETENTION CONFIGURATION (userType: "authenticated" with manage access)
   // ==========================================================================
 
   getRetentionConfig: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(
       z.object({
@@ -189,7 +191,7 @@ export const healthCheckContract = {
   updateRetentionConfig: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -201,13 +203,13 @@ export const healthCheckContract = {
     .output(z.void()),
 
   // ==========================================================================
-  // HISTORY & STATUS (userType: "user" with read permission)
+  // HISTORY & STATUS (userType: "user" with read access)
   // ==========================================================================
 
   getHistory: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(
       z.object({
@@ -228,12 +230,12 @@ export const healthCheckContract = {
 
   /**
    * Get detailed health check run history with full result data.
-   * Requires permission to view detailed run data including metadata.
+   * Requires access to view detailed run data including metadata.
    */
   getDetailedHistory: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckDetailsRead.id],
+      access: [healthCheckAccess.details],
     })
     .input(
       z.object({
@@ -260,7 +262,7 @@ export const healthCheckContract = {
   getAggregatedHistory: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(
       z.object({
@@ -280,12 +282,12 @@ export const healthCheckContract = {
   /**
    * Get detailed aggregated health check history including strategy-specific data.
    * Returns buckets with core metrics AND aggregatedResult from strategy.
-   * Requires healthCheckDetailsRead permission.
+   * Requires healthCheckDetailsRead access rule.
    */
   getDetailedAggregatedHistory: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckDetailsRead.id],
+      access: [healthCheckAccess.details],
     })
     .input(
       z.object({
@@ -309,7 +311,7 @@ export const healthCheckContract = {
   getSystemHealthStatus: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(z.object({ systemId: z.string() }))
     .output(SystemHealthStatusResponseSchema),
@@ -321,7 +323,7 @@ export const healthCheckContract = {
   getSystemHealthOverview: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(z.object({ systemId: z.string() }))
     .output(

package/src/schemas.ts

@@ -56,9 +56,11 @@ export type CollectorAssertion = z.infer<typeof CollectorAssertionSchema>;
 
 /**
  * A collector configuration entry within a health check.
- * Each entry includes the collector ID, its config, and per-collector assertions.
+ * Each entry includes a unique ID, the collector type ID, its config, and per-collector assertions.
  */
 export const CollectorConfigEntrySchema = z.object({
+  /** Unique ID for this collector instance (UUID) */
+  id: z.string(),
   /** Fully-qualified collector ID (e.g., collector-hardware.cpu) */
   collectorId: z.string(),
   /** Collector-specific configuration */
@@ -270,7 +272,7 @@ export const DEFAULT_RETENTION_CONFIG: RetentionConfig = {
 /**
  * Base schema for aggregated health check data buckets.
  * Contains core metrics only (no strategy-specific data).
- * Used by getAggregatedHistory endpoint (healthCheckStatusRead permission).
+ * Used by getAggregatedHistory endpoint (healthCheckStatusRead access).
  */
 export const AggregatedBucketBaseSchema = z.object({
   bucketStart: z.date(),
@@ -290,7 +292,7 @@ export type AggregatedBucketBase = z.infer<typeof AggregatedBucketBaseSchema>;
 
 /**
  * Extended schema with strategy-specific aggregated result.
- * Used by getDetailedAggregatedHistory endpoint (healthCheckDetailsRead permission).
+ * Used by getDetailedAggregatedHistory endpoint (healthCheckDetailsRead access).
  */
 export const AggregatedBucketSchema = AggregatedBucketBaseSchema.extend({
   aggregatedResult: z.record(z.string(), z.unknown()).optional(),

package/src/zod-health-result.ts

@@ -1,54 +1,95 @@
 import { z } from "zod";
+import type { HealthResultMeta } from "@checkstack/common";
 
 // ============================================================================
 // HEALTH RESULT REGISTRY - Typed metadata for chart annotations
 // ============================================================================
 
 /**
- * Chart types for auto-generated health check visualizations.
- *
- * Numeric types:
- * - line: Time series line chart for numeric metrics over time
- * - bar: Bar chart for distributions (record of string to number)
- * - pie: Pie chart for category distributions (record of string to number)
- * - counter: Simple count display with trend indicator
- * - gauge: Percentage gauge for rates/percentages (0-100)
- *
- * Non-numeric types:
- * - boolean: Boolean indicator (success/failure, connected/disconnected)
- * - text: Text display for string values
- * - status: Status badge for error/warning states
+ * Registry for health result schema metadata.
+ * Used by auto-chart components for visualization inference.
  */
-export type ChartType =
-  | "line"
-  | "bar"
-  | "pie"
-  | "counter"
-  | "gauge"
-  | "boolean"
-  | "text"
-  | "status";
+export const healthResultRegistry = z.registry<HealthResultMeta>();
+
+// ============================================================================
+// BRANDED TYPES FOR COMPILE-TIME ENFORCEMENT
+// ============================================================================
 
 /**
- * Metadata type for health check result schemas.
- * Provides autocompletion for `.meta()` calls on result fields.
+ * Unique symbol for branding health result fields.
+ * This enables compile-time enforcement that developers use factory functions.
  */
-export interface HealthResultMeta {
-  /** The type of chart to render for this field */
-  "x-chart-type"?: ChartType;
-  /** Human-readable label for the chart (defaults to field name) */
-  "x-chart-label"?: string;
-  /** Unit suffix for values (e.g., 'ms', '%', 'req/s') */
-  "x-chart-unit"?: string;
-  /** Whether this field supports JSONPath assertions */
-  "x-jsonpath"?: boolean;
-}
+declare const HealthResultBrand: unique symbol;
 
 /**
- * Registry for health result schema metadata.
- * Used by auto-chart components for visualization inference.
+ * A branded Zod schema type that marks it as a health result field.
+ * Only schemas created via factory functions (healthResultNumber, healthResultString, etc.)
+ * carry this brand.
  */
-export const healthResultRegistry = z.registry<HealthResultMeta>();
+export type HealthResultField<T extends z.ZodTypeAny> = T & {
+  [HealthResultBrand]: true;
+};
+
+/**
+ * Allowed field types in a health result schema.
+ * Supports direct fields, optional fields, and fields with defaults.
+ */
+export type HealthResultFieldType =
+  | HealthResultField<z.ZodTypeAny>
+  | z.ZodOptional<HealthResultField<z.ZodTypeAny>>
+  | z.ZodDefault<HealthResultField<z.ZodTypeAny>>
+  | z.ZodNullable<HealthResultField<z.ZodTypeAny>>;
+
+/**
+ * Constraint for health result schema shapes.
+ * All fields must use factory functions (healthResultNumber, healthResultString, etc.)
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid - uses factory functions
+ * const validSchema = z.object({
+ *   value: healthResultNumber({ "x-chart-type": "line" }),
+ *   error: healthResultString({ "x-chart-type": "status" }).optional(),
+ * });
+ *
+ * // ❌ Invalid - uses raw z.number()
+ * const invalidSchema = z.object({
+ *   value: z.number(), // Type error!
+ * });
+ * ```
+ */
+export type HealthResultShape = Record<string, HealthResultFieldType>;
+
+// ============================================================================
+// HEALTH RESULT SCHEMA BUILDER
+// ============================================================================
+
+/**
+ * Create a health result schema that enforces the use of factory functions.
+ *
+ * This builder ensures all fields use healthResultNumber(), healthResultString(),
+ * healthResultBoolean(), or healthResultJSONPath() - raw Zod schemas like z.number()
+ * will cause a compile-time error.
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid - all fields use factory functions
+ * const schema = healthResultSchema({
+ *   responseTime: healthResultNumber({ "x-chart-type": "line", "x-chart-label": "Response Time" }),
+ *   error: healthResultString({ "x-chart-type": "status" }).optional(),
+ * });
+ *
+ * // ❌ Invalid - raw z.number() causes type error
+ * const schema = healthResultSchema({
+ *   value: z.number(), // Type error: not assignable to HealthResultFieldType
+ * });
+ * ```
+ */
+export function healthResultSchema<T extends HealthResultShape>(
+  shape: T
+): z.ZodObject<T> {
+  return z.object(shape);
+}
 
 // ============================================================================
 // TYPED HEALTH RESULT FACTORIES
@@ -69,28 +110,53 @@ type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
  * });
  * ```
  */
-export function healthResultString(meta: ChartMeta) {
+export function healthResultString(
+  meta: ChartMeta
+): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, meta);
-  return schema;
+  return schema as HealthResultField<z.ZodString>;
 }
 
 /**
  * Create a health result number field with typed chart metadata.
  */
-export function healthResultNumber(meta: ChartMeta) {
+export function healthResultNumber(
+  meta: ChartMeta
+): HealthResultField<z.ZodNumber> {
   const schema = z.number();
   schema.register(healthResultRegistry, meta);
-  return schema;
+  return schema as HealthResultField<z.ZodNumber>;
 }
 
 /**
  * Create a health result boolean field with typed chart metadata.
  */
-export function healthResultBoolean(meta: ChartMeta) {
+export function healthResultBoolean(
+  meta: ChartMeta
+): HealthResultField<z.ZodBoolean> {
   const schema = z.boolean();
   schema.register(healthResultRegistry, meta);
-  return schema;
+  return schema as HealthResultField<z.ZodBoolean>;
+}
+
+/**
+ * Create a health result array field with typed chart metadata.
+ * For arrays of strings (e.g., DNS resolved values, list of hosts).
+ *
+ * @example
+ * ```typescript
+ * const resultSchema = healthResultSchema({
+ *   resolvedValues: healthResultArray({ "x-chart-type": "text", "x-chart-label": "Values" }),
+ * });
+ * ```
+ */
+export function healthResultArray(
+  meta: ChartMeta
+): HealthResultField<z.ZodArray<z.ZodString>> {
+  const schema = z.array(z.string());
+  schema.register(healthResultRegistry, meta);
+  return schema as HealthResultField<z.ZodArray<z.ZodString>>;
 }
 
 /**
@@ -106,10 +172,12 @@ export function healthResultBoolean(meta: ChartMeta) {
  * });
  * ```
  */
-export function healthResultJSONPath(meta: ChartMeta) {
+export function healthResultJSONPath(
+  meta: ChartMeta
+): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, { ...meta, "x-jsonpath": true });
-  return schema;
+  return schema as HealthResultField<z.ZodString>;
 }
 
 // ============================================================================

package/src/permissions.ts

@@ -1,39 +0,0 @@
-import { createPermission } from "@checkstack/common";
-
-export const permissions = {
-  /**
-   * Status-only permission for viewing health check status.
-   * Enabled by default for anonymous and authenticated users.
-   */
-  healthCheckStatusRead: createPermission(
-    "healthcheck.status",
-    "read",
-    "View Health Check Status",
-    { isAuthenticatedDefault: true, isPublicDefault: true }
-  ),
-  /**
-   * Configuration read permission for viewing health check configurations.
-   * Restricted to users with explicit grant.
-   */
-  healthCheckRead: createPermission(
-    "healthcheck",
-    "read",
-    "Read Health Check Configurations"
-  ),
-  /**
-   * Permission for viewing detailed health check run data including metadata.
-   * Allows access to extended visualizations without full management access.
-   */
-  healthCheckDetailsRead: createPermission(
-    "healthcheck.details",
-    "read",
-    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)"
-  ),
-  healthCheckManage: createPermission(
-    "healthcheck",
-    "manage",
-    "Full management of Health Check Configurations"
-  ),
-};
-
-export const permissionList = Object.values(permissions);