@checkstack/backend-api 0.20.0 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,174 @@
 # @checkstack/backend-api
 
+## 0.21.1
+
+### Patch Changes
+
+- 13373ce: Break the publish-time dependency cycle between `@checkstack/backend-api` and `@checkstack/cache-api` / `@checkstack/queue-api`.
+
+  `cache-api` and `queue-api` only ever used `Logger` and `Migration` from `backend-api` as `import type`, yet declared `@checkstack/backend-api` as a runtime dependency. In the monorepo this is harmless (everything resolves via `workspace:*`), but once published, `bun publish` freezes each `workspace:*` into a concrete pin of the _other_ package's then-current version. Because the dependency is mutual, a consumer installing these packages from the registry must resolve `backend-api -> cache-api -> backend-api -> ...` backward through release history until it reaches ancient versions that shipped raw `workspace:*` ranges and a long-removed `@checkstack/cache-api@0.1.0` pin - which fail to resolve. This surfaced as `bun install` errors (and a missing `checkstack-dev` binary) in freshly scaffolded standalone plugins.
+
+  `Logger` and `Migration` now live in `@checkstack/common` (a dependency-free leaf package). `@checkstack/backend-api` re-exports both for backward compatibility, so existing `import type { Logger, Migration } from "@checkstack/backend-api"` call sites are unchanged. `cache-api` and `queue-api` now depend on `@checkstack/common` instead of `@checkstack/backend-api`, removing the cycle.
+
+- Updated dependencies [13373ce]
+  - @checkstack/common@0.14.0
+  - @checkstack/cache-api@0.3.10
+  - @checkstack/queue-api@0.3.10
+  - @checkstack/healthcheck-common@1.5.1
+  - @checkstack/signal-common@0.2.7
+  - @checkstack/template-engine@0.4.1
+
+## 0.21.0
+
+### Minor Changes
+
+- 9dcc848: Add the AI platform: a transport-agnostic tool spine, an OAuth Authorization Server + read-only MCP server, a propose/apply flow with audit log, a streaming in-app chat agent, per-conversation permission modes, per-integration spend caps, and user-scoped tool authorization.
+
+  Two new packages, `@checkstack/ai-common` (the `AiTool` contract, `read`/`mutate`/`destructive` effect classification, the `ai.*` access rules, the OpenAI-compatible connection shape, and the wire contracts) and `@checkstack/ai-backend` (the tool registry, extension points, principal-to-tool resolver, shared zod-to-JSON-Schema serializer, and all transports). The OpenAI-compatible integration provider registers through the existing integration provider extension point, so its API key is stored in the Secrets Vault and configured in the generic Connections UI.
+
+  What ships:
+
+  - Tool spine and extension points: `aiToolExtensionPoint.registerTool` (hand-authored composite tools) and `aiToolProjectionExtensionPoint.expose` (opt-in projections of existing oRPC procedures). Authorization mirrors `autoAuthMiddleware` exactly - a tool is surfaced only when every `requiredAccessRules` entry is satisfied, so a scope-narrowed principal can only ever see fewer tools.
+  - OAuth + MCP: Checkstack can act as its own OAuth 2.1 Authorization Server (authorization code + PKCE, consent screen, Dynamic Client Registration) and expose a read-only MCP server over Streamable HTTP at `/api/ai/mcp`. Off by default, enabled by the admin `ai.mcp-oauth` setting. A Bearer OAuth-token branch is added to the auth strategy; token scopes are intersected live with the bound user's access rules on every call. A shared-Postgres rate limiter throttles the DCR endpoint per client IP. `getMcpOAuthSettings` / `setMcpOAuthSettings` contracts added to `@checkstack/auth-common`. A minimal OAuth consent page (`/auth/oauth-consent`) renders the requesting client and scopes.
+  - Propose/apply + audit: a transport-agnostic two-step service - `propose` re-checks authz, runs the tool's `dryRun` without mutating, and returns a single-use proposal token (the `proposed` audit row IS the token store, 10-minute TTL, atomic single-use); `apply` re-parses the server-stored payload, re-checks authz, and atomically commits. The `ai_tool_calls` audit table records every call across both transports with a SHA-256 args hash (never raw arguments) and stamps who proposed and who applied. An `ai.toolCalled` event carries metadata only.
+  - In-app chat: a server-side, provider-agnostic Vercel AI SDK agent loop (OpenAI, Azure, OpenRouter, Ollama, vLLM, LM Studio, ...). The model provider is built on the backend from the integration credentials, so the API key never leaves the backend. The loop offers only resolver-allowed tools, auto-runs read tools (re-entering the live router as the logged-in user) and routes mutating / destructive tools through propose/apply. Durable conversation persistence (`ai_conversations`, `ai_messages`, owner-scoped RPCs) plus a streaming chat UI with a confirm-card component and per-integration model picker.
+  - Per-conversation permission mode (Claude-Code-style approve/auto), a durable `permission_mode` column on `ai_conversations` (default `approve`). `read` always auto-runs in both modes; `mutate` inherits the mode (auto-applies server-side in `auto`, confirm-carded in `approve`); `destructive` ALWAYS requires the human `applyTool` in both modes. Security invariant (structural + tested): the mode is consulted only on the `mutate` branch, so no `(effect, mode)` pair routes a destructive tool to auto-apply.
+  - Per-integration LLM spend cap (optional `spendCap` = `tokenBudget` + `windowMinutes`, default OFF). Spend is tracked in a shared-Postgres `ai_spend` ledger; enforcement is a rolling-window SUM run before each turn (HTTP 429 over budget). Per-principal tool rate-limit budgets are a rolling COUNT over `ai_tool_calls`, enforced on both transports. An absent / empty / incomplete `spendCap` is treated as "no cap" rather than rejected.
+  - Full tool-call replay: `ai_messages.model_messages` (jsonb) persists the canonical AI-SDK `ResponseMessage[]` per turn and replays them verbatim on the next turn; legacy rows fall back to text-only replay.
+  - Enforced no-secret-leak scrubbing: `appendMessage` runs `scrubContent` on every write, redacting credential-shaped keys and high-confidence credential values; a canary regression test asserts injected secrets are stripped. A hardening test suite asserts no secret appears in any AI-surface DTO and that handler-side authz holds when the model misbehaves.
+  - Provider correctness: the chat provider uses `@ai-sdk/openai-compatible`'s `chatModel` (plain `/chat/completions`), so OpenAI-compatible gateways (OpenRouter, DeepSeek, Ollama, vLLM) no longer reject turns with `invalid_prompt`; `@ai-sdk/openai` is removed.
+
+  BREAKING CHANGES:
+
+  - The `AiTool` contract (`@checkstack/ai-common`) gained a `TRpc` type parameter, and both `dryRun` and `execute` now receive a USER-SCOPED `rpcClient` arg bound to the originating user. Every plugin procedure a tool calls re-enters the live router AS THAT USER, so handler-side authorization (access rules AND per-resource/team scope) is enforced exactly as a direct UI/RPC call - closing a prior privilege-escalation where tools captured a trusted service client at construction. A hand-authored tool MUST resolve its plugin client from this per-call arg and MUST NOT capture a trusted service client at factory scope. Tool factories that previously took `{ rpcClient }` should drop that parameter.
+  - `AiToolProjectionExtensionPoint.expose` no longer takes a second `pluginMetadata` argument; the owning metadata lives on `input.sourcePluginMetadata`. Callers must drop the second argument.
+
+  State and scale: conversations, messages, the audit log, proposal tokens, the rate-limit counter, and the spend ledger all live in shared Postgres, so every pod answers identically and the agent loop is resumable on any pod. The only pod-local state is the live MCP connection registry (bookkeeping, never a source of truth). Cross-pod conversation readback, the spend cap, and the tool budget are verified by env-gated two-pod integration tests.
+
+  This is a beta minor.
+
+- 9dcc848: Automations now run as a configured service account, removing implicit god-mode from the dispatch path.
+
+  BREAKING: every automation must declare a `runAs` application (service account). Previously every automation action ran as the trusted service client, bypassing all access-rule, per-resource, and team-scope checks - so an automation could touch any team's data. Now each automation runs as a bounded `application` principal, and every data-access call an action makes is authorized exactly as that identity. An automation with no `runAs` fails to run with a clear error rather than falling back to the trusted client; legacy automations must be assigned a service account before they run again.
+
+  What changed:
+
+  - New top-level field `runAs` on automations (a `run_as_application_id` column + create/update inputs; `AutomationSchema.runAs`). Required on create; GitOps sets it via the `run-as` metadata label.
+  - A new `coreServices.rpcClientAs(applicationId)` mints a short-lived, backend-signed app-principal token; the auth service resolves it LIVE to an `application` principal (reusing `enrichApplicationPrincipal`), so it flows through full `autoAuthMiddleware` enforcement. The dispatch engine threads this client into every action's `execute` as the required `context.rpcClient`.
+  - Bind authority (anti-escalation): a user may only bind an application whose access rules are a subset of their own (`isApplicationBindable`); `getBindableApplications` lists only bindable apps, and the create/update handlers enforce the check.
+  - `notification.sendTransactional` moves from service-only to access-gated (`notification.send`, a new access rule), so an automation's `runAs` can call the built-in `notify_user` / `notification.send` actions; trusted services still bypass via short-circuit.
+  - A "Run as (Service Account)" picker in the automation editor, populated from `getBindableApplications` (server-side filtered to bindable apps), seeding from the loaded `runAs` on edit and passing it into create + update. First-class teaching UX: an inline info banner, a blocked Save with an inline hint until one is chosen, and an empty state linking to the Applications admin + docs when none are bindable.
+
+  State and scale: `runAs` resolution is a pure read over shared tables; the app-principal token is self-contained and verified statelessly, so the per-run client is correct under horizontal scale.
+
+  This is a beta minor.
+
+- 9dcc848: Harden config-versioning so stored configs always migrate-then-validate and broken migration chains fail fast at boot.
+
+  - `@checkstack/backend-api` `Versioned<T>` gains `parseAssumingV1` (migrate-from-v1 then validate leniently, runtime path), `parseStrictAssumingV1` (migrate then validate strictly, editor path), and `validateMigrationChainFromV1()`. A standalone pure helper `assertMigrationChainFromV1({ version, migrations })` is the single shared implementation behind the constructor guard and `validateMigrationChainFromV1`.
+  - `Versioned` now validates its own v1 -> `version` chain in the constructor, which runs at module import / plugin registration. A new `no-restricted-syntax` ESLint rule bans calling `parse` / `safeParse` / `parseAsync` / `strict` directly on a `Versioned`'s `.schema` member.
+  - Auth strategy migration chains are validated at the `betterAuthExtensionPoint.addStrategy` chokepoint (`@checkstack/auth-backend`).
+  - Automation action AND trigger configs migrate-then-validate (lenient at dispatch, strict in the editor validator, recursing into `choose`/`parallel`/`repeat`/`sequence` blocks). The `run_script` / `run_shell` action configs bump to `version: 2` dropping the removed `sandbox` key, fixing the editor's `Unrecognized key: sandbox` error.
+  - Anomaly read path now validates: `getAnomalyConfig` / `getAnomalyAssignmentConfig` run stored records through `Versioned.parseRecord`; `PartialAnomalySettingsSchema` moved to `@checkstack/anomaly-common`. Notification ConfigService reads thread the migrations argument, and per-strategy `userConfig` is migrate-then-validated before `send()`.
+  - gitops-apply migrate-then-validates authored health-check config; integration connection validation routes through `safeValidate`. The latent HTTP health-check `result` schema (at `version: 3` with no migrations) now ships a pass-through v1 -> v2 -> v3 chain.
+
+  BREAKING CHANGES (fail-fast at boot, intended):
+
+  - Any `Versioned` config with `version > 1` and an incomplete or non-contiguous migration chain now throws at construction (boot) instead of failing lazily on first read. This covers every `Versioned` instance repo-wide, including future plugin types. Out-of-tree plugins shipping such a config must add the missing migration step(s); all in-repo strategies already have complete chains.
+  - An auth strategy declaring `configVersion > 1` without a complete chain throws at registration.
+  - A trigger's per-automation config is now a versioned `config: Versioned<TConfig>` instead of a bare `configSchema?`. Plugins registering triggers with `configSchema:` must wrap it: `config: new Versioned({ version: 1, schema })`. The underlying schema stays reachable via `config.schema`; triggers without per-automation config are unaffected.
+
+  State and scale: all affected reads resolve from shared Postgres / in-process registries, so every pod sees the same migrated answer. No new framework-owned current-state store.
+
+  This is a beta minor.
+
+- 9dcc848: Add environments as a first-class catalog primitive, with per-environment health-check fan-out, config templating, per-environment reactive health, and script run-context exposure.
+
+  - Catalog primitive: an environment is a sibling of groups - a named, instance-global record carrying free-form custom fields (baseUrl, region, tier, ...) that any system can belong to many-to-many. New `environments` + `systems_environments` tables, `EnvironmentSchema` + create/update schemas, `EntityService` environment CRUD and membership joins, RPC endpoints gated by a new `catalogAccess.environment` access rule, a GitOps `Environment` kind + `System.environments` extension, and frontend management (an `EnvironmentEditor`, an Environments management panel, and a per-system environment picker). The Environments card's Add/Edit/Delete affordances are gated on `catalogAccess.environment.manage`.
+  - Per-environment fan-out: run identity becomes `(systemId, configurationId, environmentId)`. Runs, aggregates, and state transitions gain a nullable `environmentId`. The health-check assignment gains an `environmentIds` selector with three modes (All / Specific / None; `null` and `[]` are distinct). The queue executor resolves the effective environment set via the catalog `resolveSystemEnvironments` read and executes one isolated run per environment.
+  - Config templating: a new `x-templatable` config-field marker renders a string field through the template engine at execute time, against `{ environment, check, system }`. A shared `renderTemplatableConfig` and a `renderTemplatePreview` helper (re-exported from `@checkstack/template-engine`) keep editor previews identical to the run-time render. The HTTP collector's `url`, `headers[].value`, and `body` are templatable, rendered per environment (the strategy client build moves inside the per-env loop); the `url`'s `.url()` validation moves post-render. Secrets resolve before templating; a field marked both secret and `x-templatable` is rejected at plugin load. `DynamicForm` shows a live "Preview" line, and the catalog `EnvironmentPreviewPicker` ("Preview as: <environment>") drives it in the collector editor (only when the schema has a templatable field).
+  - Script run-context: `CollectorRunContext` gains an optional `environment` field (`{ id, name, fields }`, metadata only). Shell collectors receive `CHECKSTACK_ENV_ID` / `_NAME` / `CHECKSTACK_ENV_<FIELD>` vars; inline TS collectors read `globalThis.context.environment`; the editor test panel mirrors both. The env-less path is unchanged.
+  - Per-environment reactive health (see BREAKING below), env-keyed read/write paths, env-qualified serialization locks, an optional `trigger.payload.environmentId`, per-environment isolation, and an `ENVIRONMENT_RESOLUTION_FAILED` signal when catalog resolution degrades to a single env-less run.
+
+  BREAKING CHANGES: the reactive `health` entity's id-shape and cardinality change. It now encodes two views: per-environment (id `"<systemId>::<environmentId>"`) and a system rollup (id `"<systemId>"`, the worst status across environments + env-less runs). The rollup PRESERVES the pre-existing system-level contract - dashboards, status badges, and automations referencing health by `systemId` keep working without re-authoring - but the entity's contract surface changed (new id-shape, higher cardinality, new payload field), so it is flagged breaking. `getBulkHealthState` parses env-qualified ids and keys results by the original id.
+
+  State and scale: membership and custom fields live only in catalog Postgres and are re-read every tick via the cross-plugin RPC; env-keyed health reads from shared `health_check_runs` / aggregates / transitions (compute-on-read). Every pod resolves the same effective set and the same per-environment health. No pod-local environment state.
+
+  Also: `unwrapSchema` in `zod-config.ts` loops instead of single-pass-stripping so multi-layer wrappers (`.optional().default()`) still resolve `x-templatable` meta. The env-less `{{ environment.* }}` run notice logs at `debug` (a legitimate recurring configuration), while the post-render HTTP `.url()` check still fails a genuinely-broken empty render with a clear "Rendered URL is invalid" error.
+
+  This is a beta minor.
+
+- 9dcc848: Cut initial-load JS: lazy plugin contributions, a hardened lazy-by-default contribution contract, on-demand Monaco, and a lighter icon/chart load.
+
+  - Lazy plugin route pages: each plugin's route `element` references a `React.lazy`-wrapped page rendered inside a shared `<Suspense>` boundary. Plugins still register synchronously, so nav, slots, commands, API factories, and `foreignSignals` are available on first paint. This moves ~37 route-page chunks (~600 KB) out of the entry; the entry chunk drops from ~2.4 MB to ~190 KB. Auth flow pages stay eager. The `@checkstack/scripts` scaffold template generates lazy route pages too.
+  - Hardened contribution contract (BREAKING, frontend plugin contract): plugins declare contributions lazily and let the framework own code-splitting, Suspense, and per-plugin error isolation. Routes use `load: () => import("./Page").then((m) => ({ default: m.Page }))` instead of `element: <Page />` (`element` is still accepted for the rare page that must paint without a chunk fetch; provide exactly one). Slot extensions accept either an eager `component` or a lazy `load`; new `getLazyContribution` + `ExtensionComponent` exports from `@checkstack/frontend-api` render either kind. This also fixes runtime-installed plugins: `ExtensionSlot` subscribes to the plugin registry, and the API registry rebuilds when the plugin set changes (`getPlugins()` returns an immutable snapshot via `useSyncExternalStore`). A per-plugin error boundary contains a bad contribution.
+  - On-demand Monaco: the `@checkstack/ui` barrel no longer pulls the `@codingame/*` / `monaco-languageclient` stack into the initial load. `CodeEditor` lazy-loads its Monaco-backed editor behind `React.lazy` + Suspense, `validateTypeScriptSources` imports the editor API via in-body `await import(...)`, and the "vscode services ready" signal moved to a Monaco-free module. The ~10 MB editor body loads only when a `CodeEditor` mounts. A `react-vendor` `manualChunks` split was added for stable vendor caching.
+  - lucide-react 1.x + lighter icons/charts (BREAKING for icon consumers): lucide-react unified from three drifting ranges to `^1.17.0`. lucide v1 removed brand icons, so the GitHub/GitLab marks are vendored in `@checkstack/ui` (`GithubIcon`, `GitlabIcon`, `brandIcons`); a new `IconName` type (`LucideIconName | BrandIconName`) in `@checkstack/common` is canonical, accepted by `AuthStrategy.icon` and the card components, so data-driven brand names keep working. `DynamicIcon` no longer eagerly imports lucide's ~1600-icon map (~1 MB) - it lives in a `React.lazy` `iconRegistry` chunk fetched on first data-driven render, while statically named-imported icons tree-shake normally. The recharts-backed health-check charts (~300 KB) and the `HealthCheckSystemOverview` drawer leave the initial load.
+
+  BREAKING CHANGES:
+
+  - Frontend plugin contract: routes/slot contributions are lazy-by-default (`load` instead of `element`/eager elements) as described above.
+  - Any external consumer importing a brand icon from `lucide-react` (e.g. `import { Github } from "lucide-react"`) must switch to the vendored `@checkstack/ui` brand icons or a custom SVG.
+
+  This is a beta minor.
+
+- 9dcc848: Layered OS-level script sandbox, secure and fail-closed by default (epic #247).
+
+  Script and shell health checks and the `run_shell` / `run_script` automation actions now run inside a layered OS-level sandbox by default. The sandbox lives in `core/backend-api/src/script-sandbox/` (the single source of truth) and is enforced inside the shared runners, so it applies wherever a job runs.
+
+  Layers:
+
+  - Resource caps (CPU / memory / PID / FD / file-size, via `prlimit` on capable Linux; ESM JS-heap cap via `--max-old-space-size`; portable wall-clock timeout) and an OOM-safe streaming output cap.
+  - Privilege drop via a NON-ROOT supervisor model: the shipped images run the supervisor as non-root uid `65532`, so every sandboxed script inherits non-root and can never be host-root; filesystem + network confinement is delivered by ROOTLESS `bwrap`/`nsjail` via unprivileged user namespaces. `enforced.privilege` is truthful (true only when the child cannot run as host-root). Runners no longer pass `uid`/`gid` to `Bun.spawn` (a silent no-op and a forward-compat hazard).
+  - Filesystem isolation (`scratch-only` / `scratch-plus-ro`) confining the child to its per-run scratch dir over a read-only base; the interpreter path is RO-bound so the runtime execs, and `TMPDIR` is pinned to the in-namespace tmpfs.
+  - Network egress control: `deny` (routeless loopback-only netns), `allowlist` (real plumbed egress via macvlan OR rootless slirp4netns + an in-kernel nftables filter), and an always-on metadata / link-local block (`169.254.0.0/16`, `fe80::/10`, `fc00::/7`). No-blackhole invariant: `enforced.network` is never true when egress is actually severed or unfiltered; unpluggable egress degrades to surfaced host net.
+  - Per-run fork-bomb containment via RLIMIT*NPROC inside the fresh per-run user+PID namespace; a centralized forbidden-env denylist (`LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD*_`, `NODE*OPTIONS`, `BUN*_`, caller `PATH` overrides).
+  - A validated tuned seccomp profile (`deploy/seccomp/checkstack-userns.json`) and a live `clone(CLONE_NEWUSER|CLONE_NEWNET)` capability probe (not the static sysctl), shipped by default in both Dockerfiles, `docker-compose.yml`, and `deploy/k8s/checkstack-sandbox.yaml`.
+
+  Global policy and operator surface:
+
+  - The global sandbox policy lives in ONE durable row owned by `script-packages` (its `ConfigService` row in shared `plugin_configs`). A single process-wide provider serves every runner; the two script plugins no longer register competing providers. A dedicated admin-only `script-sandbox.manage` permission gates both reading and writing the policy. New `getSandboxPolicy` / `setSandboxPolicy` endpoints and a Settings -> Script Sandbox admin UI (`enabled`, `onUnavailable`, network/filesystem/privilege modes, allow list, metadata block, resource caps). The startup capability/readiness log is emitted in-process by `script-packages-backend` (no fragile init-order RPC self-loop), and on a host that cannot enforce a layer a one-time startup warning explains the two local-dev paths (Docker, or set the global policy to `degrade`).
+  - Satellite relay: the WS protocol carries the resolved policy in the `authenticated` message and a `sandbox_policy` push-on-change; a satellite caches the last relayed policy and resolves every run through it.
+
+  BREAKING CHANGES (platform in BETA, shipped as minor):
+
+  - Scripts run sandboxed by default. The shipped global default is FAIL-CLOSED (`onUnavailable: "fail"`): when a requested layer cannot be enforced the run is REFUSED (clean `exitCode: -1`, never an unsandboxed spawn) rather than silently degrading. Deployments on hosts that cannot enforce a layer (no bubblewrap, user namespaces blocked, no `/proc` unmask) must run the official images with the documented runtime flags (the bundled seccomp profile + `systempaths=unconfined`, or k8s `procMount: Unmasked`), or set the global policy to `degrade`. On macOS / restricted containers the strong layers degrade to the portable subset and are surfaced per run.
+  - Default network posture is deny-egress (`allowlist` with an empty allow list, which resolves to the routeless `deny` path). Scripts calling external endpoints fail until those destinations are allowlisted in the global default. The always-on metadata / link-local block applies even under looser modes.
+  - The per-action / per-check `sandbox` config override and the transport `ScriptRequest.sandbox` field are removed; policy is global-only, so an automation/check author can no longer weaken the sandbox on their own item. Stored configs carrying a stray `sandbox` key are tolerated (stripped on parse).
+  - The shared runners' `run()` no longer accepts a `sandbox` option; callers rely on the global policy provider.
+  - A satellite fails closed (most restrictive profile) until it receives the first relayed policy; a relay-read failure or an older core keeps it fail-closed. A relay failure can never loosen a satellite's sandbox.
+
+  State and scale: the global policy is a single durable Postgres row read identically on every pod. Capability detection is per-process, deterministic from the host kernel, and surfaced per run via the `EffectiveSandbox` report (a Linux pod and a macOS satellite may legitimately differ). `CHECKSTACK_SANDBOX_UID/GID` and macvlan addressing are genuinely per-host infrastructure, surfaced per run, not the queryable policy. The satellite's policy cache is satellite-local transport state. No new pod-local current-state.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/healthcheck-common@1.5.0
+  - @checkstack/common@0.13.0
+  - @checkstack/template-engine@0.4.0
+  - @checkstack/cache-api@0.3.9
+  - @checkstack/queue-api@0.3.9
+  - @checkstack/signal-common@0.2.6
+
 ## 0.20.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,30 +10,31 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.12.0",
-    "@checkstack/healthcheck-common": "1.3.0",
-    "@checkstack/cache-api": "0.3.6",
-    "@checkstack/queue-api": "0.3.6",
-    "@checkstack/signal-common": "0.2.5",
-    "@orpc/client": "^1.13.14",
-    "@orpc/contract": "^1.13.14",
-    "@orpc/openapi": "^1.13.2",
-    "@orpc/server": "^1.13.2",
-    "@orpc/zod": "^1.13.2",
+    "@checkstack/cache-api": "0.3.9",
+    "@checkstack/common": "0.13.0",
+    "@checkstack/healthcheck-common": "1.5.0",
+    "@checkstack/queue-api": "0.3.9",
+    "@checkstack/signal-common": "0.2.6",
+    "@checkstack/template-engine": "0.4.0",
+    "@orpc/client": "^1.14.4",
+    "@orpc/contract": "^1.14.4",
+    "@orpc/openapi": "^1.14.4",
+    "@orpc/server": "^1.14.4",
+    "@orpc/zod": "^1.14.4",
     "drizzle-orm": "^0.45.0",
-    "hono": "^4.12.14",
+    "hono": "^4.12.23",
     "marked": "^17.0.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.3.4",
+    "@checkstack/scripts": "0.4.0",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "latest",
     "@types/pg": "^8.20.0",
     "pg": "^8.21.0"
   },
   "peerDependencies": {
-    "hono": "^4.12.14",
+    "hono": "^4.12.23",
     "drizzle-orm": "^0.45.0"
   },
   "checkstack": {

package/src/auth-strategy.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { Migration } from "./config-versioning";
-import type { LucideIconName } from "@checkstack/common";
+import type { IconName } from "@checkstack/common";
 
 /**
  * Migration chain for auth strategy configurations.
@@ -21,8 +21,11 @@ export interface AuthStrategy<Config = unknown> {
   /** Optional description of the strategy */
   description?: string;
 
-  /** Lucide icon name in PascalCase (e.g., 'Github', 'Chrome', 'Mail') */
-  icon?: LucideIconName;
+  /**
+   * Icon name in PascalCase. A lucide icon (e.g. 'Mail') or a vendored brand
+   * icon (e.g. 'Github') - see `IconName` / `DynamicIcon`.
+   */
+  icon?: IconName;
 
   /** Current version of the configuration schema */
   configVersion: number;

package/src/bearer-token.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared opaque-bearer extraction used by the OAuth resource-server validate
+ * path (auth-backend) and the MCP transport (ai-backend) so the two never
+ * drift. A `ck_` API key is NOT an opaque OAuth bearer token (it has its own
+ * dedicated auth branch), so it is explicitly excluded here.
+ */
+export function opaqueBearerToken(request: Request): string | undefined {
+  const header = request.headers.get("authorization");
+  if (!header?.startsWith("Bearer ") || header.startsWith("Bearer ck_")) {
+    return undefined;
+  }
+  return header.slice("Bearer ".length);
+}

package/src/collector-strategy.ts

@@ -24,6 +24,15 @@ export interface CollectorResult<TResult> {
 export interface CollectorRunContext {
   check: { id: string; name: string; intervalSeconds: number };
   system: { id: string; name: string };
+  /**
+   * The resolved environment for THIS run, when the check fanned out into
+   * one. Absent when the assignment opts out or the system has no
+   * environments (the env-less run). `fields` is the environment's
+   * free-form custom metadata (verbatim values) - metadata only, never
+   * secrets. Exposed to scripts as `globalThis.context.environment` (inline)
+   * and the `CHECKSTACK_ENV_*` shell vars.
+   */
+  environment?: { id: string; name: string; fields: Record<string, unknown> };
 }
 
 /**

package/src/config-versioning.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Tests for the `Versioned<T>` config helper, focused on the
+ * assume-v1-on-read parse paths used by configs that are stored
+ * UNVERSIONED (raw, nested in a larger JSON blob).
+ */
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import {
+  Versioned,
+  assertMigrationChainFromV1,
+  type Migration,
+} from "./config-versioning";
+
+// A v1 config: a single object schema, no migrations.
+const v1Schema = z.object({
+  url: z.string(),
+  method: z.enum(["GET", "POST"]).default("GET"),
+});
+
+const v1Config = new Versioned({ version: 1, schema: v1Schema });
+
+// A v1 -> v2 config that DROPS a removed `sandbox` key, mirroring the
+// real run_script/run_shell migration.
+const v2Schema = z.object({
+  script: z.string(),
+});
+
+const dropSandboxMigration: Migration<Record<string, unknown>, unknown> = {
+  fromVersion: 1,
+  toVersion: 2,
+  description: "Drop removed `sandbox` key",
+  migrate: ({ sandbox: _sandbox, ...rest }) => rest,
+};
+
+const v2Config = new Versioned({
+  version: 2,
+  schema: v2Schema,
+  migrations: [dropSandboxMigration],
+});
+
+describe("parseAssumingV1", () => {
+  it("validates a v1-no-migration config (just validate)", async () => {
+    const result = await v1Config.parseAssumingV1({ url: "https://x.test" });
+    expect(result).toEqual({ url: "https://x.test", method: "GET" });
+  });
+
+  it("runs the migration chain for a v>1 config and drops a removed key", async () => {
+    const result = await v2Config.parseAssumingV1({
+      script: "echo hi",
+      sandbox: "off",
+    });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("is idempotent: a fresh config without the removed key is unchanged", async () => {
+    const result = await v2Config.parseAssumingV1({ script: "echo hi" });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("strips unknown keys leniently (does NOT reject typos)", async () => {
+    const result = await v1Config.parseAssumingV1({
+      url: "https://x.test",
+      methodd: "GET",
+    });
+    expect(result).toEqual({ url: "https://x.test", method: "GET" });
+    expect(result).not.toHaveProperty("methodd");
+  });
+
+  it("rejects a genuine validation error (missing required field)", async () => {
+    await expect(
+      v1Config.parseAssumingV1({ method: "GET" }),
+    ).rejects.toThrow();
+  });
+});
+
+describe("parseStrictAssumingV1", () => {
+  it("validates a clean v1-no-migration config", async () => {
+    const result = await v1Config.parseStrictAssumingV1({
+      url: "https://x.test",
+    });
+    expect(result).toEqual({ url: "https://x.test", method: "GET" });
+  });
+
+  it("migrates a removed key away, then strict-validates cleanly", async () => {
+    const result = await v2Config.parseStrictAssumingV1({
+      script: "echo hi",
+      sandbox: "off",
+    });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("is idempotent for a fresh config without the removed key", async () => {
+    const result = await v2Config.parseStrictAssumingV1({ script: "echo hi" });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("rejects a genuine unknown-key typo the migration does NOT account for", async () => {
+    await expect(
+      v1Config.parseStrictAssumingV1({
+        url: "https://x.test",
+        methodd: "GET",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an unknown key on the migrated (v2) shape", async () => {
+    await expect(
+      v2Config.parseStrictAssumingV1({ script: "echo hi", typo: 1 }),
+    ).rejects.toThrow();
+  });
+
+  it("falls back to a normal parse for non-object schemas", async () => {
+    const unionConfig = new Versioned({
+      version: 1,
+      schema: z.union([z.object({ a: z.string() }), z.object({ b: z.number() })]),
+    });
+    const result = await unionConfig.parseStrictAssumingV1({ a: "x" });
+    expect(result).toEqual({ a: "x" });
+  });
+});
+
+describe("construction-time migration-chain guard", () => {
+  it("throws for a version>1 config with no migrations", () => {
+    expect(
+      () => new Versioned({ version: 2, schema: v2Schema, migrations: [] }),
+    ).toThrow();
+  });
+
+  it("constructs fine for a version 2 config with a complete v1->v2 chain", () => {
+    expect(
+      () =>
+        new Versioned({
+          version: 2,
+          schema: v2Schema,
+          migrations: [dropSandboxMigration],
+        }),
+    ).not.toThrow();
+  });
+
+  it("constructs fine for a version 1 config with no migrations", () => {
+    expect(() => new Versioned({ version: 1, schema: v1Schema })).not.toThrow();
+  });
+
+  it("throws for a broken chain (gap / non-+1 step)", () => {
+    expect(
+      () =>
+        new Versioned({
+          version: 4,
+          schema: v2Schema,
+          migrations: [
+            { fromVersion: 1, toVersion: 2, description: "a", migrate: (d) => d },
+            { fromVersion: 3, toVersion: 4, description: "c", migrate: (d) => d },
+          ],
+        }),
+    ).toThrow();
+  });
+});
+
+describe("validateMigrationChainFromV1", () => {
+  it("passes for a v1 config with no migrations", () => {
+    expect(v1Config.validateMigrationChainFromV1()).toBeUndefined();
+  });
+
+  it("passes for a v2 config with a complete 1->2 chain", () => {
+    expect(v2Config.validateMigrationChainFromV1()).toBeUndefined();
+  });
+
+  // NOTE: the "missing covering migration" and "gapped chain" cases now
+  // throw at CONSTRUCTION (see the construction-time guard above), so they
+  // can no longer be exercised via a constructed instance. The pure
+  // structural method itself is covered transitively by the guard tests
+  // and by the passing cases below.
+});
+
+describe("assertMigrationChainFromV1", () => {
+  const step = (fromVersion: number, toVersion: number): Migration => ({
+    fromVersion,
+    toVersion,
+    description: `${fromVersion}->${toVersion}`,
+    migrate: (d) => d,
+  });
+
+  it("passes for a v1 config with no migrations", () => {
+    expect(() =>
+      assertMigrationChainFromV1({ version: 1, migrations: [] }),
+    ).not.toThrow();
+  });
+
+  it("passes for a complete contiguous chain (1->2->3)", () => {
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: 3,
+        migrations: [step(2, 3), step(1, 2)],
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws for a version>1 config with no migrations", () => {
+    expect(() =>
+      assertMigrationChainFromV1({ version: 2, migrations: [] }),
+    ).toThrow(/incomplete/);
+  });
+
+  it("throws for a chain that does not reach the target version", () => {
+    expect(() =>
+      assertMigrationChainFromV1({ version: 3, migrations: [step(1, 2)] }),
+    ).toThrow(/incomplete: reaches version 2/);
+  });
+
+  it("throws for a gap in the chain", () => {
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: 4,
+        migrations: [step(1, 2), step(3, 4)],
+      }),
+    ).toThrow(/chain broken: expected migration from version 2/);
+  });
+
+  it("throws for a non-+1 step", () => {
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: 3,
+        migrations: [step(1, 3)],
+      }),
+    ).toThrow(/increment version by 1/);
+  });
+});