@checkstack/backend-api 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # @checkstack/backend-api
 
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [9a27800]
+  - @checkstack/queue-api@0.0.6
+
+## 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,
+  ```
+
+- 827b286: Add array assertion operators for string array fields
+
+  New operators for asserting on array fields (e.g., playerNames in RCON collectors):
+
+  - **includes** - Check if array contains a specific value
+  - **notIncludes** - Check if array does NOT contain a specific value
+  - **lengthEquals** - Check if array length equals a value
+  - **lengthGreaterThan** - Check if array length is greater than a value
+  - **lengthLessThan** - Check if array length is less than a value
+  - **isEmpty** - Check if array is empty
+  - **isNotEmpty** - Check if array has at least one element
+
+  Also exports a new `arrayField()` schema factory for creating array assertion schemas.
+
+### Patch Changes
+
+- 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
+
+- aa4a8ab: Fix anonymous users not seeing public list endpoints
+
+  Anonymous users with global access rules (e.g., `catalog.system.read` assigned to the "anonymous" role) were incorrectly getting empty results from list endpoints with `instanceAccess.listKey`. The middleware now properly checks if anonymous users have global access before filtering.
+
+  Added comprehensive test suite for `autoAuthMiddleware` covering:
+
+  - Anonymous endpoints (userType: "anonymous")
+  - Public endpoints with global and instance-level access rules
+  - Authenticated, user-only, and service-only endpoints
+  - Single resource access with team-based filtering
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.0
+  - @checkstack/queue-api@0.0.5
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {

package/src/assertions.test.ts

@@ -9,6 +9,7 @@ import {
   booleanField,
   enumField,
   jsonPathField,
+  arrayField,
 } from "./assertions";
 import { z } from "zod";
 
@@ -130,6 +131,32 @@ describe("Assertion Schema Factories", () => {
     });
   });
 
+  describe("arrayField", () => {
+    it("creates a schema with array operators", () => {
+      const schema = arrayField("playerNames");
+
+      const includes = schema.safeParse({
+        field: "playerNames",
+        operator: "includes",
+        value: "Steve",
+      });
+      expect(includes.success).toBe(true);
+
+      const lengthEquals = schema.safeParse({
+        field: "playerNames",
+        operator: "lengthEquals",
+        value: 5,
+      });
+      expect(lengthEquals.success).toBe(true);
+
+      const isEmpty = schema.safeParse({
+        field: "playerNames",
+        operator: "isEmpty",
+      });
+      expect(isEmpty.success).toBe(true);
+    });
+  });
+
   describe("jsonPathField", () => {
     it("creates a schema with dynamic operators", () => {
       const schema = jsonPathField();
@@ -239,6 +266,107 @@ describe("evaluateAssertion", () => {
     });
   });
 
+  describe("array operators", () => {
+    it("evaluates includes correctly", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "includes", value: "Steve" },
+        { playerNames: ["Steve", "Alex", "Notch"] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "includes", value: "Herobrine" },
+        { playerNames: ["Steve", "Alex", "Notch"] }
+      );
+      expect(failed.passed).toBe(false);
+      expect(failed.message).toContain("to include");
+    });
+
+    it("evaluates notIncludes correctly", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "notIncludes", value: "Herobrine" },
+        { playerNames: ["Steve", "Alex"] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "notIncludes", value: "Steve" },
+        { playerNames: ["Steve", "Alex"] }
+      );
+      expect(failed.passed).toBe(false);
+    });
+
+    it("evaluates lengthEquals correctly", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "lengthEquals", value: 3 },
+        { playerNames: ["Steve", "Alex", "Notch"] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "lengthEquals", value: 5 },
+        { playerNames: ["Steve", "Alex", "Notch"] }
+      );
+      expect(failed.passed).toBe(false);
+    });
+
+    it("evaluates lengthGreaterThan correctly", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "lengthGreaterThan", value: 2 },
+        { playerNames: ["Steve", "Alex", "Notch"] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "lengthGreaterThan", value: 5 },
+        { playerNames: ["Steve", "Alex"] }
+      );
+      expect(failed.passed).toBe(false);
+    });
+
+    it("evaluates lengthLessThan correctly", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "lengthLessThan", value: 5 },
+        { playerNames: ["Steve", "Alex"] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "lengthLessThan", value: 2 },
+        { playerNames: ["Steve", "Alex", "Notch"] }
+      );
+      expect(failed.passed).toBe(false);
+    });
+
+    it("evaluates isEmpty correctly for arrays", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "isEmpty" },
+        { playerNames: [] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "isEmpty" },
+        { playerNames: ["Steve"] }
+      );
+      expect(failed.passed).toBe(false);
+    });
+
+    it("evaluates isNotEmpty correctly for arrays", () => {
+      const result = evaluateAssertion(
+        { field: "playerNames", operator: "isNotEmpty" },
+        { playerNames: ["Steve", "Alex"] }
+      );
+      expect(result.passed).toBe(true);
+
+      const failed = evaluateAssertion(
+        { field: "playerNames", operator: "isNotEmpty" },
+        { playerNames: [] }
+      );
+      expect(failed.passed).toBe(false);
+    });
+  });
+
   describe("existence operators", () => {
     it("evaluates exists correctly", () => {
       const result = evaluateAssertion(

package/src/assertions.ts

@@ -40,6 +40,21 @@ export const StringOperators = z.enum([
  */
 export const BooleanOperators = z.enum(["isTrue", "isFalse"]);
 
+/**
+ * Operators for array fields.
+ */
+export const ArrayOperators = z.enum([
+  "includes",
+  "notIncludes",
+  "lengthEquals",
+  "lengthGreaterThan",
+  "lengthLessThan",
+  "isEmpty",
+  "isNotEmpty",
+  "exists",
+  "notExists",
+]);
+
 /**
  * Universal operators for dynamic/unknown types (JSONPath values).
  * Works via runtime type coercion.
@@ -118,6 +133,23 @@ export function booleanField(name: string) {
   });
 }
 
+/**
+ * Creates an assertion schema for array fields.
+ * Supports checking array contents and length.
+ */
+export function arrayField(name: string) {
+  return z.object({
+    field: z.literal(name),
+    operator: ArrayOperators,
+    value: z
+      .union([z.string(), z.number()])
+      .optional()
+      .describe(
+        "Value to check (string for includes, number for length operators)"
+      ),
+  });
+}
+
 /**
  * Creates an assertion schema for enum fields (e.g., status codes).
  */
@@ -258,8 +290,38 @@ function evaluateOperator(
   if (op === "isTrue") return actual === true;
   if (op === "isFalse") return actual === false;
 
-  // Empty check
+  // Array operators
+  if (Array.isArray(actual)) {
+    switch (op) {
+      case "includes": {
+        const strExpected = String(expected ?? "");
+        return actual.some((item) => String(item) === strExpected);
+      }
+      case "notIncludes": {
+        const strExpected = String(expected ?? "");
+        return !actual.some((item) => String(item) === strExpected);
+      }
+      case "lengthEquals": {
+        return actual.length === Number(expected);
+      }
+      case "lengthGreaterThan": {
+        return actual.length > Number(expected);
+      }
+      case "lengthLessThan": {
+        return actual.length < Number(expected);
+      }
+      case "isEmpty": {
+        return actual.length === 0;
+      }
+      case "isNotEmpty": {
+        return actual.length > 0;
+      }
+    }
+  }
+
+  // Empty check (for strings)
   if (op === "isEmpty") return !actual || String(actual).trim() === "";
+  if (op === "isNotEmpty") return !!actual && String(actual).trim() !== "";
 
   // For numeric operators, try to coerce to numbers
   if (
@@ -350,17 +412,30 @@ function formatFailureMessage(
     endsWith: "to end with",
     matches: "to match pattern",
     isEmpty: "to be empty",
+    isNotEmpty: "to not be empty",
     exists: "to exist",
     notExists: "not to exist",
     isTrue: "to be true",
     isFalse: "to be false",
+    includes: "to include",
+    notIncludes: "to not include",
+    lengthEquals: "to have length equal to",
+    lengthGreaterThan: "to have length greater than",
+    lengthLessThan: "to have length less than",
   };
 
   const opLabel = opLabels[operator] || operator;
 
   // For operators without expected values
   if (
-    ["isEmpty", "exists", "notExists", "isTrue", "isFalse"].includes(operator)
+    [
+      "isEmpty",
+      "isNotEmpty",
+      "exists",
+      "notExists",
+      "isTrue",
+      "isFalse",
+    ].includes(operator)
   ) {
     return `${field}: expected ${opLabel}, got ${JSON.stringify(actual)}`;
   }

package/src/chart-metadata.ts

@@ -26,30 +26,7 @@
  * ```
  */
 
-/**
- * Available chart types for auto-generated 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
- *
- * Note: Fields without chart annotations simply won't render - no "hidden" type needed.
- */
-export type ChartType =
-  | "line"
-  | "bar"
-  | "counter"
-  | "gauge"
-  | "boolean"
-  | "text"
-  | "status";
+import type { ChartType } from "@checkstack/common";
 
 /**
  * Chart metadata to attach to Zod schema fields via .meta().

package/src/hooks.ts

@@ -1,4 +1,4 @@
-import type { Permission } from "@checkstack/common";
+import type { AccessRule } from "@checkstack/common";
 
 /**
  * Hook definition for type-safe event emission and subscription
@@ -20,12 +20,12 @@ export function createHook<T>(id: string): Hook<T> {
  */
 export const coreHooks = {
   /**
-   * Emitted when a plugin registers permissions
+   * Emitted when a plugin registers access rules
    */
-  permissionsRegistered: createHook<{
+  accessRulesRegistered: createHook<{
     pluginId: string;
-    permissions: Permission[];
-  }>("core.permissions.registered"),
+    accessRules: AccessRule[];
+  }>("core.accessRules.registered"),
 
   /**
    * Emitted when plugin configuration is updated
@@ -65,7 +65,7 @@ export const coreHooks = {
 
   /**
    * Emitted AFTER a plugin has been fully removed.
-   * Use this for orphan cleanup (e.g., removing permissions from DB).
+   * Use this for orphan cleanup (e.g., removing access rules from DB).
    * Should be emitted with work-queue mode for DB operations.
    */
   pluginDeregistered: createHook<{

package/src/notification-strategy.ts

@@ -366,10 +366,10 @@ export interface RegisteredNotificationStrategy<
   /** Plugin that registered this strategy */
   ownerPluginId: string;
   /**
-   * Dynamically generated permission ID for this strategy.
+   * Dynamically generated access rule ID for this strategy.
    * Format: `{ownerPluginId}.strategy.{id}.use`
    */
-  permissionId: string;
+  accessRuleId: string;
 }
 
 /**
@@ -404,12 +404,12 @@ export interface NotificationStrategyRegistry {
   getStrategies(): RegisteredNotificationStrategy<unknown, unknown, unknown>[];
 
   /**
-   * Get all strategies that a user has permission to use.
+   * Get all strategies that a user has access to use.
    *
-   * @param userPermissions - Set of permission IDs the user has
+   * @param userAccessRules - Set of access rule IDs the user has
    */
   getStrategiesForUser(
-    userPermissions: Set<string>
+    userAccessRules: Set<string>
   ): RegisteredNotificationStrategy<unknown, unknown, unknown>[];
 }
 

package/src/plugin-admin-contract.ts

@@ -1,22 +1,20 @@
 import { z } from "zod";
 import { oc } from "@orpc/contract";
-import type { ProcedureMetadata } from "@checkstack/common";
-import type { Permission } from "@checkstack/common";
+import { access, type ProcedureMetadata } from "@checkstack/common";
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Permissions
+// Access Rules
 // ─────────────────────────────────────────────────────────────────────────────
 
-export const pluginAdminPermissions = {
-  install: {
-    id: "plugin.install",
-    description: "Install new plugins from npm",
-  },
-  deregister: {
-    id: "plugin.deregister",
-    description: "Deregister (uninstall) plugins",
-  },
-} as const satisfies Record<string, Permission>;
+export const pluginAdminAccess = {
+  install: access("plugin", "manage", "Install new plugins from npm"),
+  deregister: access("plugin", "manage", "Deregister (uninstall) plugins"),
+};
+
+export const pluginAdminAccessRules = [
+  pluginAdminAccess.install,
+  pluginAdminAccess.deregister,
+];
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Contract
@@ -31,7 +29,7 @@ export const pluginAdminContract = {
   install: _base
     .meta({
       userType: "user",
-      permissions: [pluginAdminPermissions.install.id],
+      access: [pluginAdminAccess.install],
     })
     .input(
       z.object({
@@ -52,7 +50,7 @@ export const pluginAdminContract = {
   deregister: _base
     .meta({
       userType: "user",
-      permissions: [pluginAdminPermissions.deregister.id],
+      access: [pluginAdminAccess.deregister],
     })
     .input(
       z.object({

package/src/plugin-system.ts

@@ -1,7 +1,7 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { ServiceRef } from "./service-ref";
 import { ExtensionPoint } from "./extension-point";
-import type { Permission, PluginMetadata } from "@checkstack/common";
+import type { AccessRule, PluginMetadata } from "@checkstack/common";
 import type { Hook, HookSubscribeOptions, HookUnsubscribe } from "./hooks";
 import { Router } from "@orpc/server";
 import { RpcContext } from "./rpc";
@@ -70,7 +70,10 @@ export type BackendPluginRegistry = {
   registerService: <S>(ref: ServiceRef<S>, impl: S) => void;
   registerExtensionPoint: <T>(ref: ExtensionPoint<T>, impl: T) => void;
   getExtensionPoint: <T>(ref: ExtensionPoint<T>) => T;
-  registerPermissions: (permissions: Permission[]) => void;
+  /**
+   * Register access rules for this plugin.
+   */
+  registerAccessRules: (accessRules: AccessRule[]) => void;
   /**
    * Registers an oRPC router and its contract for this plugin.
    * The contract is used for OpenAPI generation.
@@ -85,7 +88,7 @@ export type BackendPluginRegistry = {
    */
   registerCleanup: (cleanup: () => Promise<void>) => void;
   pluginManager: {
-    getAllPermissions: () => { id: string; description?: string }[];
+    getAllAccessRules: () => { id: string; description?: string }[];
   };
 };