@checkstack/common 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @checkstack/common
 
+## 0.1.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.
+
+## 0.0.3
+
+### Patch Changes
+
+- f5b1f49: Added generic `TransportClient` interface for health check strategy transport abstraction.
+
 ## 0.0.2
 
 ### Patch Changes

package/package.json

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

package/src/index.ts

@@ -5,3 +5,5 @@ export * from "./plugin-metadata";
 export * from "./client-definition";
 export * from "./permission-utils";
 export * from "./icons";
+export * from "./transport-client";
+export * from "./json-schema";

package/src/json-schema.ts

@@ -0,0 +1,35 @@
+/**
+ * Generic base JSON Schema property type.
+ * Uses a generic Self parameter for recursive properties to allow proper extension.
+ */
+export interface JsonSchemaPropertyCore<
+  Self = JsonSchemaPropertyCore<unknown>
+> {
+  type?: string;
+  description?: string;
+  enum?: string[];
+  const?: string | number | boolean;
+  properties?: Record<string, Self>;
+  items?: Self;
+  required?: string[];
+  additionalProperties?: boolean | Self;
+  format?: string;
+  default?: unknown;
+  oneOf?: Self[];
+  anyOf?: Self[];
+}
+
+/**
+ * Concrete base JSON Schema property type without extensions.
+ */
+export type JsonSchemaPropertyBase =
+  JsonSchemaPropertyCore<JsonSchemaPropertyBase>;
+
+/**
+ * Base JSON Schema type for object schemas.
+ */
+export interface JsonSchemaBase<TProp = JsonSchemaPropertyBase> {
+  type?: string;
+  properties?: Record<string, TProp>;
+  required?: string[];
+}

package/src/transport-client.ts

@@ -0,0 +1,16 @@
+/**
+ * Generic transport client interface for remote command execution.
+ *
+ * Transport strategies (SSH, SNMP, WinRM) implement this interface to provide
+ * a consistent abstraction for collectors.
+ *
+ * @template TCommand - Command type (e.g., string for SSH, OidRequest for SNMP)
+ * @template TResult - Result type (e.g., { stdout, stderr, exitCode } for SSH)
+ */
+export interface TransportClient<TCommand, TResult> {
+  /**
+   * Execute a command on the remote host.
+   * The command and result types are defined by the transport implementation.
+   */
+  exec(command: TCommand): Promise<TResult>;
+}

package/src/types.ts

@@ -2,6 +2,80 @@
 // 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 };
+}
+
+/**
+ * Qualifies a resource type with the plugin namespace.
+ * @param pluginId - The plugin identifier
+ * @param resourceType - The unqualified resource type
+ * @returns Qualified resource type (e.g., "catalog.system")
+ */
+export function qualifyResourceType(
+  pluginId: string,
+  resourceType: string
+): string {
+  // If already qualified (contains a dot), return as-is
+  if (resourceType.includes(".")) return resourceType;
+  return `${pluginId}.${resourceType}`;
+}
+
 /**
  * Metadata interface for RPC procedures.
  * Used by contracts to define auth requirements and by backend middleware to enforce them.
@@ -34,4 +108,10 @@ export interface ProcedureMetadata {
    * 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.
+   */
+  resourceAccess?: ResourceAccessConfig[];
 }