@checkstack/backend-api 0.21.3 → 0.21.5

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @checkstack/backend-api
 
+## 0.21.5
+
+### Patch Changes
+
+- 0626782: Guard the role editor against granting inert (and misleading) permissions to the
+  anonymous role.
+
+  RPC procedures carry two independent axes: `userType` (the hard authentication
+  gate) and `access` rules (authorization). An admin can grant the anonymous role
+  any access rule, but if the procedures needing that rule are `userType:
+"authenticated"`/`"user"`, the grant does nothing - the auth middleware rejects
+  unauthenticated callers BEFORE access rules are checked (so there is no security
+  hole; the grant is simply inert). After anonymous users started seeing
+  permission-gated UI, such a grant would surface as visible-but-broken controls.
+
+  - The backend now computes, from contract metadata, the access rules an anonymous
+    caller can actually use (a rule is "usable" iff at least one `public` procedure
+    requires it) via `pluginManager.getAnonymousUsableAccessRuleIds()`, exposed to
+    plugins through the plugin environment.
+  - `auth.getAccessRules` annotates each rule with `anonymousUsable`.
+  - `auth.updateRole` REFUSES to ADD a non-usable rule to the anonymous role
+    (existing grants are untouched, so no configuration can be wedged). This is a
+    guardrail, not an enforcement change - RPC authorization is unchanged.
+  - The role editor disables non-usable rules (with an explanation) when editing
+    the anonymous role.
+
+  Verified live: `getAccessRules` reports 11 anonymous-usable vs 58 not; granting
+  `incident.incident.manage` to the anonymous role returns HTTP 400 with a clear
+  message.
+
+- Updated dependencies [56e7c75]
+  - @checkstack/common@0.15.0
+  - @checkstack/healthcheck-common@1.5.4
+  - @checkstack/cache-api@0.3.12
+  - @checkstack/queue-api@0.3.12
+  - @checkstack/signal-common@0.2.9
+  - @checkstack/template-engine@0.4.3
+
+## 0.21.4
+
+### Patch Changes
+
+- b50916d: Fix "Date cannot be represented in JSON Schema" crashing the AI chat. Zod v4's
+  `toJSONSchema()` throws on `z.date()` (and even `z.coerce.date()`) by default,
+  and the chat hit this in TWO places:
+
+  - **`@checkstack/backend-api`** `toJsonSchema()` (the OpenAPI generator and AI
+    tool-introspection / MCP substrate) called it with no options.
+  - **`@checkstack/ai-backend`** the agent loop hands the Vercel AI SDK the raw
+    Zod tool input, and the SDK runs its OWN `toJSONSchema()` (throwing) to build
+    the model-facing tool schema - so a single date field in any tool input
+    crashed every chat turn (the whole tool list is projected before the model is
+    called).
+
+  Both now render dates as `{ type: "string", format: "date-time" }` (their wire
+  shape) and degrade other unrepresentable types to `{}` instead of throwing.
+
+  For the model boundary, a single `dateSafeModelSchema()` helper hands the SDK a
+  ready-made date-safe schema plus a validator that COERCES the ISO strings the
+  model emits back into real `Date`s before parsing with the original schema
+  (refinements and the downstream RPC client, which expects `Date`s, keep
+  working). A single `toModelSchema()` entry point applies this at EVERY point a
+  schema is handed to the model - chat tool inputs, the headless agent runner's
+  tool inputs (the automation "AI Action"), and `generateObject` structured
+  output - gated so non-date schemas are untouched, so individual tool / agent
+  definitions never special-case dates. Regression tests cover the converter, the
+  AI tool serializer, and the model-schema generation + coercion helper, including
+  the full inbound round-trip with the exact ISO shape a live model emits
+  (`...T22:00:00Z`, no milliseconds).
+
+  **Timezone correctness.** Because the model produces dates as text, the chat now
+  enforces an unambiguous wire contract: a date-time tool argument MUST be RFC 3339
+  with an explicit timezone offset. Zone-less (`2026-07-01T22:00:00`) and date-only
+  (`2026-07-01`) values are rejected with a model-readable error (the model
+  self-repairs), instead of being silently interpreted in the pod's local zone -
+  which would resolve the same string to different instants across pods. To resolve
+  an operator's bare "22:00", the browser's IANA timezone is sent with every chat
+  turn and folded into the system prompt, so each operator's times are interpreted
+  in their own zone by default. When no browser zone is available (a headless
+  automation AI Action), the reference zone falls back to the host/container
+  timezone (`TZ`), not UTC. A format-matrix test covers every common shape a model
+  might emit. The chat UI shows the operator which timezone is in use, and the
+  `TZ` override is documented for operators.
+
+  **Current time in context.** The model has no clock, so the system prompt now
+  includes the current instant (UTC plus the reference-zone wall clock), letting it
+  resolve relative dates like "today at 10:00" without asking. Applied to both the
+  chat and the headless agent runner, computed per turn/run so it is never stale.
+
+  **Less-strict topic classifier.** The chat's off-topic pre-classifier was
+  refusing legitimate requests like "create a maintenance" because maintenances
+  (and several other domains) were not listed. The classifier now enumerates the
+  full domain set and treats any create/list/update/delete action on a platform
+  resource as on-topic by default.
+
 ## 0.21.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.21.3",
+  "version": "0.21.5",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,12 +10,12 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/cache-api": "0.3.11",
-    "@checkstack/common": "0.14.1",
-    "@checkstack/healthcheck-common": "1.5.3",
-    "@checkstack/queue-api": "0.3.11",
-    "@checkstack/signal-common": "0.2.8",
-    "@checkstack/template-engine": "0.4.2",
+    "@checkstack/cache-api": "0.3.12",
+    "@checkstack/common": "0.15.0",
+    "@checkstack/healthcheck-common": "1.5.4",
+    "@checkstack/queue-api": "0.3.12",
+    "@checkstack/signal-common": "0.2.9",
+    "@checkstack/template-engine": "0.4.3",
     "@orpc/client": "^1.14.4",
     "@orpc/contract": "^1.14.4",
     "@orpc/openapi": "^1.14.4",
@@ -27,7 +27,7 @@
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.6.0",
+    "@checkstack/scripts": "0.6.1",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "latest",
     "@types/pg": "^8.20.0",

package/src/plugin-system.ts

@@ -139,6 +139,12 @@ export type BackendPluginRegistry = {
   ) => void;
   pluginManager: {
     getAllAccessRules: () => { id: string; description?: string }[];
+    /**
+     * Qualified ids of access rules an anonymous caller can actually use (rules
+     * required by at least one `public` procedure). Used to guard the role
+     * editor against granting inert permissions to the anonymous role.
+     */
+    getAnonymousUsableAccessRuleIds: () => string[];
   };
 };
 

package/src/rpc.test.ts

@@ -25,7 +25,7 @@ const testContracts = {
   publicGlobalEndpoint: proc({
     userType: "public",
     operationType: "query",
-    access: [access("resource", "read", "Test access")],
+    access: [access("resource", "read", "Test access", { pluginId: "test" })],
   }).output(z.object({ message: z.string() })),
 
   // Public endpoint with list filtering
@@ -39,7 +39,7 @@ const testContracts = {
           read: { description: "View systems", isPublic: true },
           manage: { description: "Manage systems" },
         },
-        { listKey: "systems" },
+        { listKey: "systems", pluginId: "test" },
       ).read,
     ],
   }).output(
@@ -80,7 +80,7 @@ const testContracts = {
           read: { description: "View systems", isPublic: true },
           manage: { description: "Manage systems" },
         },
-        { idParam: "systemId" },
+        { idParam: "systemId", pluginId: "test" },
       ).read,
     ],
   })
@@ -95,6 +95,7 @@ const testContracts = {
       access("bulk", "read", "Bulk read", {
         recordKey: "statuses",
         isPublic: true,
+        pluginId: "test",
       }),
     ],
   })
@@ -129,7 +130,7 @@ const testContracts = {
           read: { description: "View systems", isPublic: true },
           manage: { description: "Manage systems" },
         },
-        { idParam: "systemId" },
+        { idParam: "systemId", pluginId: "test" },
       ).read,
     ],
     instanceAccess: { recordKey: "statuses" },

package/src/schema-utils.test.ts

@@ -42,3 +42,36 @@ describe("toJsonSchema x-* metadata", () => {
     expect(json.properties.secretEnv?.["x-secret-env"]).toBe(true);
   });
 });
+
+describe("toJsonSchema unrepresentable types", () => {
+  // Regression: Zod v4 throws "Date cannot be represented in JSON Schema" for
+  // `z.date()` by default. This converter feeds the OpenAPI generator AND the
+  // AI tool projection, so a single date field (timestamps are everywhere)
+  // would crash the whole AI chat. Dates must serialize as date-time strings.
+  test("represents z.date() as a date-time string instead of throwing", () => {
+    const schema = z.object({
+      createdAt: z.date(),
+      note: z.string(),
+    });
+
+    const json = toJsonSchema(schema) as {
+      properties: Record<string, Record<string, unknown>>;
+    };
+
+    expect(json.properties.createdAt?.type).toBe("string");
+    expect(json.properties.createdAt?.format).toBe("date-time");
+    expect(json.properties.note?.type).toBe("string");
+  });
+
+  test("handles a top-level / optional / array date without throwing", () => {
+    expect(() => toJsonSchema(z.date())).not.toThrow();
+    const json = toJsonSchema(
+      z.object({ seen: z.array(z.date()), at: z.date().optional() }),
+    ) as { properties: Record<string, Record<string, unknown>> };
+    expect(
+      (json.properties.seen?.items as Record<string, unknown> | undefined)
+        ?.format,
+    ).toBe("date-time");
+    expect(json.properties.at?.format).toBe("date-time");
+  });
+});

package/src/schema-utils.ts

@@ -101,8 +101,25 @@ function addSchemaMetadata(
  * dropdowns for optionsResolver fields, hidden for auto-populated fields).
  */
 export function toJsonSchema(zodSchema: z.ZodTypeAny): Record<string, unknown> {
-  // Use Zod's native JSON Schema conversion
-  const jsonSchema = zodSchema.toJSONSchema() as Record<string, unknown>;
+  // Use Zod's native JSON Schema conversion.
+  //
+  // Zod v4 throws "Date cannot be represented in JSON Schema" for `z.date()`
+  // by default (`unrepresentable: "throw"`). Many platform contracts carry
+  // date fields (timestamps), and this converter is the substrate for the
+  // OpenAPI generator AND the AI tool projection - so a single date field
+  // would crash the whole AI chat (every turn projects the full tool list)
+  // and break OpenAPI. Dates serialize as ISO strings over the wire, so we
+  // represent them as `{ type: "string", format: "date-time" }` and let any
+  // other unrepresentable type degrade to `{}` (any) rather than throw.
+  const jsonSchema = z.toJSONSchema(zodSchema, {
+    unrepresentable: "any",
+    override: (ctx) => {
+      if (ctx.zodSchema instanceof z.ZodDate) {
+        ctx.jsonSchema.type = "string";
+        ctx.jsonSchema.format = "date-time";
+      }
+    },
+  }) as Record<string, unknown>;
   addSchemaMetadata(zodSchema, jsonSchema);
   return jsonSchema;
 }