@checkstack/common 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @checkstack/common
 
+## 0.2.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
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/common",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/access-utils.ts

@@ -0,0 +1,228 @@
+import type { PluginMetadata } from "./plugin-metadata";
+
+// =============================================================================
+// UNIFIED ACCESS CONTROL
+// =============================================================================
+
+/**
+ * The two fundamental access levels.
+ */
+export type AccessLevel = "read" | "manage";
+
+/**
+ * Configuration for instance-level (team-based) access control.
+ * Specifies how to extract resource IDs from requests or responses.
+ */
+export interface InstanceAccessConfig {
+  /**
+   * For single-resource endpoints: parameter path in request input to extract resource ID.
+   * Uses dot notation for nested params (e.g., "params.systemId").
+   */
+  idParam?: string;
+
+  /**
+   * For list endpoints: key in response object containing the array to filter.
+   * When set, post-filters results based on team grants.
+   * Example: "systems" for response { systems: [...] }
+   */
+  listKey?: string;
+}
+
+/**
+ * An Access Rule defines WHO can do WHAT to WHICH resources.
+ * This is the fundamental building block of the unified access control system.
+ *
+ * @example
+ * ```typescript
+ * // Simple access rule (no instance-level checks)
+ * const teamsRead = access("teams", "read", "View teams");
+ *
+ * // With instance-level access (single resource)
+ * const systemRead = access("system", "read", "View systems", {
+ *   idParam: "systemId",
+ * });
+ *
+ * // With instance-level access (list filtering)
+ * const systemListRead = access("system", "read", "View systems", {
+ *   listKey: "systems",
+ * });
+ * ```
+ */
+export interface AccessRule {
+  /**
+   * Unique identifier for this rule (e.g., "system.read").
+   * Auto-generated from resource + level.
+   * This is used as the access rule ID when checking user access rules.
+   */
+  readonly id: string;
+
+  /**
+   * The resource domain (e.g., "system", "healthcheck", "incident").
+   * Combined with pluginId to create fully-qualified type for team access checks.
+   */
+  readonly resource: string;
+
+  /**
+   * The access level this rule grants: "read" or "manage".
+   * Directly maps to canRead/canManage in team grants.
+   */
+  readonly level: AccessLevel;
+
+  /**
+   * Human-readable description of what this rule allows.
+   */
+  readonly description: string;
+
+  /**
+   * Whether this rule is granted by default to authenticated users ("users" role).
+   */
+  readonly isDefault?: boolean;
+
+  /**
+   * Whether this rule is granted to anonymous/public users ("anonymous" role).
+   */
+  readonly isPublic?: boolean;
+
+  /**
+   * Instance-level (team-based) access configuration.
+   * If defined, the middleware will check team grants for specific resource instances.
+   * If undefined, only global access is checked.
+   */
+  readonly instanceAccess?: InstanceAccessConfig;
+}
+
+/**
+ * Creates a fully-qualified access rule ID by prefixing the rule's ID with the plugin ID.
+ *
+ * This is the canonical way to construct namespaced access rule IDs for authorization checks.
+ * The function ensures consistent formatting across all access-related operations.
+ *
+ * @param pluginMetadata - The plugin metadata containing the pluginId
+ * @param rule - The access rule object containing the local access rule ID
+ * @returns The fully-qualified access rule ID (e.g., "catalog.system.read")
+ *
+ * @example
+ * ```typescript
+ * import { qualifyAccessRuleId } from "@checkstack/common";
+ * import { pluginMetadata } from "./plugin-metadata";
+ * import { catalogAccess } from "./access";
+ *
+ * const qualifiedId = qualifyAccessRuleId(pluginMetadata, catalogAccess.systems.read);
+ * // Returns: "catalog.system.read"
+ * ```
+ */
+export function qualifyAccessRuleId(
+  pluginMetadata: Pick<PluginMetadata, "pluginId">,
+  rule: Pick<AccessRule, "id">
+): string {
+  return `${pluginMetadata.pluginId}.${rule.id}`;
+}
+
+/**
+ * Creates an access rule for a resource.
+ *
+ * @param resource - The resource name (e.g., "system", "incident")
+ * @param level - The access level ("read" or "manage")
+ * @param description - Human-readable description
+ * @param options - Optional configuration for defaults and instance-level access
+ * @returns An AccessRule object
+ *
+ * @example
+ * ```typescript
+ * // Simple access rule
+ * const teamsRead = access("teams", "read", "View teams");
+ *
+ * // With defaults for public access
+ * const statusRead = access("status", "read", "View status", {
+ *   isDefault: true,
+ *   isPublic: true,
+ * });
+ *
+ * // With instance-level access
+ * const systemRead = access("system", "read", "View systems", {
+ *   idParam: "systemId",
+ *   listKey: "systems",
+ *   isDefault: true,
+ *   isPublic: true,
+ * });
+ * ```
+ */
+export function access(
+  resource: string,
+  level: AccessLevel,
+  description: string,
+  options?: {
+    idParam?: string;
+    listKey?: string;
+    isDefault?: boolean;
+    isPublic?: boolean;
+  }
+): AccessRule {
+  const hasInstanceAccess = options?.idParam || options?.listKey;
+
+  return {
+    id: `${resource}.${level}`,
+    resource,
+    level,
+    description,
+    isDefault: options?.isDefault,
+    isPublic: options?.isPublic,
+    instanceAccess: hasInstanceAccess
+      ? {
+          idParam: options?.idParam,
+          listKey: options?.listKey,
+        }
+      : undefined,
+  };
+}
+
+/**
+ * Creates a read/manage pair for a resource.
+ * Most resources need both access levels, so this reduces boilerplate.
+ *
+ * @param resource - The resource name (e.g., "system", "incident")
+ * @param descriptions - Descriptions for read and manage levels
+ * @param options - Optional configuration for defaults and instance-level access
+ * @returns An object with `read` and `manage` AccessRule properties
+ *
+ * @example
+ * ```typescript
+ * const systemAccess = accessPair("system", {
+ *   read: "View systems",
+ *   manage: "Create, update, and delete systems",
+ * }, {
+ *   idParam: "systemId",
+ *   listKey: "systems",
+ *   readIsDefault: true,
+ *   readIsPublic: true,
+ * });
+ *
+ * // Usage in contract:
+ * getSystem: _base.meta({ access: [systemAccess.read] }),
+ * updateSystem: _base.meta({ access: [systemAccess.manage] }),
+ * ```
+ */
+export function accessPair(
+  resource: string,
+  descriptions: { read: string; manage: string },
+  options?: {
+    idParam?: string;
+    listKey?: string;
+    readIsDefault?: boolean;
+    readIsPublic?: boolean;
+  }
+): { read: AccessRule; manage: AccessRule } {
+  return {
+    read: access(resource, "read", descriptions.read, {
+      idParam: options?.idParam,
+      listKey: options?.listKey,
+      isDefault: options?.readIsDefault,
+      isPublic: options?.readIsPublic,
+    }),
+    manage: access(resource, "manage", descriptions.manage, {
+      idParam: options?.idParam,
+      // Note: manage doesn't typically use listKey (you don't "manage" a list in bulk)
+      // but we include idParam for single-resource manage checks
+    }),
+  };
+}

package/src/chart-types.ts

@@ -0,0 +1,38 @@
+/**
+ * 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)
+ * - 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
+ */
+export type ChartType =
+  | "line"
+  | "bar"
+  | "pie"
+  | "counter"
+  | "gauge"
+  | "boolean"
+  | "text"
+  | "status";
+
+/**
+ * Metadata type for health check result schemas.
+ * Provides autocompletion for chart-related metadata on result fields.
+ */
+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;
+}

package/src/index.ts

@@ -3,7 +3,8 @@ export * from "./pagination";
 export * from "./routes";
 export * from "./plugin-metadata";
 export * from "./client-definition";
-export * from "./permission-utils";
+export * from "./access-utils";
 export * from "./icons";
 export * from "./transport-client";
 export * from "./json-schema";
+export * from "./chart-types";

package/src/types.ts

@@ -2,64 +2,7 @@
 // RPC PROCEDURE METADATA
 // =============================================================================
 
-/**
- * Configuration for resource-level access control.
- * Used to enforce fine-grained permissions based on team grants.
- */
-export interface ResourceAccessConfig {
-  /**
-   * The resource type identifier (e.g., "system", "healthcheck").
-   * Will be auto-prefixed with pluginId in middleware (e.g., "catalog.system").
-   */
-  resourceType: string;
-
-  /**
-   * Parameter name in request input to extract resource ID from.
-   * Uses dot notation for nested params (e.g., "params.id").
-   * Required for single-resource access checks.
-   */
-  idParam?: string;
-
-  /**
-   * Filter mode for list endpoints.
-   * - "single": Check access to a single resource (default)
-   * - "list": Post-filter result array based on team access
-   */
-  filterMode?: "single" | "list";
-
-  /**
-   * Key in response object containing the array to filter.
-   * Required when filterMode is "list".
-   * Example: "systems" for response { systems: [...] }
-   */
-  outputKey?: string;
-}
-
-/**
- * Creates a ResourceAccessConfig for single-resource access checks.
- *
- * @param resourceType - The resource type (auto-prefixed with pluginId)
- * @param idParam - Parameter path in input to extract resource ID from
- */
-export function createResourceAccess(
-  resourceType: string,
-  idParam: string
-): ResourceAccessConfig {
-  return { resourceType, idParam, filterMode: "single" };
-}
-
-/**
- * Creates a ResourceAccessConfig for list filtering.
- *
- * @param resourceType - The resource type (auto-prefixed with pluginId)
- * @param outputKey - Key in response object containing the array to filter
- */
-export function createResourceAccessList(
-  resourceType: string,
-  outputKey: string
-): ResourceAccessConfig {
-  return { resourceType, filterMode: "list", outputKey };
-}
+import type { AccessRule } from "./access-utils";
 
 /**
  * Qualifies a resource type with the plugin namespace.
@@ -85,7 +28,7 @@ export function qualifyResourceType(
  *   getItems: baseContractBuilder
  *     .meta({
  *       userType: "user",
- *       permissions: [permissions.myPluginRead.id]
+ *       access: [myPluginAccess.items.read]
  *     })
  *     .output(z.array(ItemSchema)),
  * };
@@ -93,8 +36,8 @@ export function qualifyResourceType(
 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)
+   * - "anonymous": No authentication required, no access checks (fully public)
+   * - "public": Anyone can attempt, but access rules 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)
@@ -102,16 +45,17 @@ export interface ProcedureMetadata {
   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[];
-
-  /**
-   * Resource-level access control configurations.
-   * When specified, middleware checks team-based grants for the resources.
+   * Unified access rules combining access rules and resource-level access control.
+   * Each rule specifies the access rule ID, access level, and optional instance-level checks.
+   *
+   * User must satisfy ALL rules (AND logic).
+   *
+   * @example
+   * ```typescript
+   * access: [catalogAccess.systems.read]
+   * access: [catalogAccess.systems.manage]
+   * access: [catalogAccess.groups.manage, catalogAccess.systems.manage] // Both required
+   * ```
    */
-  resourceAccess?: ResourceAccessConfig[];
+  access?: AccessRule[];
 }

package/src/permission-utils.ts

@@ -1,81 +0,0 @@
-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}`;
-}