@checkstack/auth-common 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @checkstack/auth-common
 
+## 0.8.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: 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]
+  - @checkstack/common@0.13.0
+
+## 0.7.2
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+  - @checkstack/common@0.12.0
+
 ## 0.7.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/auth-common",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -10,14 +10,14 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.10.0",
-    "@orpc/contract": "^1.13.14",
+    "@checkstack/common": "0.12.0",
+    "@orpc/contract": "^1.14.4",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "@checkstack/tsconfig": "0.0.7",
     "typescript": "^5.7.2",
-    "@checkstack/scripts": "0.3.2"
+    "@checkstack/scripts": "0.3.4"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/bind-authority.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { isApplicationBindable } from "./bind-authority";
+
+describe("isApplicationBindable", () => {
+  test("admin caller (*) may bind any application", () => {
+    expect(
+      isApplicationBindable({
+        appAccessRules: ["incident.incident.manage", "notification.send"],
+        callerAccessRules: ["*"],
+      }),
+    ).toBe(true);
+    // even an app that itself holds `*`
+    expect(
+      isApplicationBindable({
+        appAccessRules: ["*"],
+        callerAccessRules: ["*"],
+      }),
+    ).toBe(true);
+  });
+
+  test("non-admin caller cannot bind an app holding * (escalation)", () => {
+    expect(
+      isApplicationBindable({
+        appAccessRules: ["*"],
+        callerAccessRules: ["incident.incident.manage"],
+      }),
+    ).toBe(false);
+  });
+
+  test("bindable when the app's rules are a subset of the caller's", () => {
+    expect(
+      isApplicationBindable({
+        appAccessRules: ["notification.send"],
+        callerAccessRules: ["notification.send", "incident.incident.manage"],
+      }),
+    ).toBe(true);
+  });
+
+  test("not bindable when the app holds a rule the caller lacks (escalation)", () => {
+    expect(
+      isApplicationBindable({
+        appAccessRules: ["notification.send", "catalog.system.manage"],
+        callerAccessRules: ["notification.send"],
+      }),
+    ).toBe(false);
+  });
+
+  test("an app with no rules is bindable by anyone", () => {
+    expect(
+      isApplicationBindable({ appAccessRules: [], callerAccessRules: [] }),
+    ).toBe(true);
+  });
+});

package/src/bind-authority.ts

@@ -0,0 +1,30 @@
+/**
+ * Bind-authority predicate for automation service accounts.
+ *
+ * An automation runs as a referenced application (service account). To prevent
+ * privilege escalation, a user may only bind an application whose effective
+ * access rules are a SUBSET of their own - a user can never grant an automation
+ * more authority than they themselves hold.
+ *
+ * Rules:
+ * - A caller holding `*` (admin) may bind any application.
+ * - An application holding `*` may only be bound by a `*`-holding caller.
+ * - Otherwise every one of the application's access rules must be present in
+ *   the caller's access rules.
+ *
+ * This is the single source of truth for the check, used both by the auth
+ * backend's `getBindableApplications` (the picker) and by the automation
+ * backend's create/update handler (the enforced gate at save time).
+ */
+export function isApplicationBindable({
+  appAccessRules,
+  callerAccessRules,
+}: {
+  appAccessRules: readonly string[];
+  callerAccessRules: readonly string[];
+}): boolean {
+  if (callerAccessRules.includes("*")) return true;
+  if (appAccessRules.includes("*")) return false;
+  const caller = new Set(callerAccessRules);
+  return appAccessRules.every((rule) => caller.has(rule));
+}

package/src/index.ts

@@ -2,4 +2,5 @@ export * from "./access";
 export * from "./rpc-contract";
 export * from "./plugin-metadata";
 export * from "./schemas";
+export * from "./bind-authority";
 export { authRoutes } from "./routes";

package/src/routes.ts

@@ -13,4 +13,12 @@ export const authRoutes = createRoutes("auth", {
   changePassword: "/change-password",
   profile: "/profile",
   onboarding: "/onboarding",
+  /**
+   * OAuth 2.1 consent screen for the AI platform's Authorization Server.
+   * better-auth's `oidcProvider` redirects the interactive authorization-code
+   * flow here (`consentPage: "/auth/oauth-consent"`) with `consent_code`,
+   * `client_id`, and `scope` query params; the page POSTs the decision to
+   * `/api/auth/oauth2/consent` and follows the returned `redirectURI`.
+   */
+  oauthConsent: "/oauth-consent",
 });

package/src/rpc-contract.ts

@@ -73,6 +73,14 @@ const RegistrationStatusSchema = z.object({
   allowRegistration: z.boolean(),
 });
 
+/** AI platform OAuth AS + MCP server settings (admin-managed). */
+const McpOAuthSettingsSchema = z.object({
+  enabled: z.boolean(),
+  allowDynamicClientRegistration: z.boolean(),
+  dcrRateLimitMax: z.number().int().positive(),
+  dcrRateLimitWindowSeconds: z.number().int().positive(),
+});
+
 // Service-to-service schemas
 const FindUserByEmailInputSchema = z.object({
   email: z.string().email(),
@@ -342,6 +350,26 @@ export const authContract = {
     .input(RegistrationStatusSchema)
     .output(z.object({ success: z.boolean() })),
 
+  // ==========================================================================
+  // AI PLATFORM: OAuth AS + MCP server settings (admin-gated)
+  // ==========================================================================
+
+  /** Current OAuth-AS / MCP server settings (enable, DCR toggle, rate-limit). */
+  getMcpOAuthSettings: proc({
+    operationType: "query",
+    userType: "user",
+    access: [authAccess.strategies],
+  }).output(McpOAuthSettingsSchema),
+
+  /** Update the OAuth-AS / MCP server settings; reloads better-auth to apply. */
+  setMcpOAuthSettings: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [authAccess.strategies],
+  })
+    .input(McpOAuthSettingsSchema)
+    .output(z.object({ success: z.boolean() })),
+
   // ==========================================================================
   // INTERNAL SERVICE ENDPOINTS (userType: "service")
   // ==========================================================================
@@ -486,6 +514,52 @@ export const authContract = {
     .input(z.string())
     .output(z.object({ secret: z.string() })),
 
+  /**
+   * S2S: resolve an application's CURRENT roles, access rules, and team
+   * memberships. Used by the core auth service to build an `application`
+   * principal from an app-principal token (automation `runAs` service
+   * accounts) - resolved live on every call, never frozen into the token.
+   * Returns `null` when the application no longer exists.
+   */
+  enrichApplicationPrincipal: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  })
+    .input(z.object({ applicationId: z.string() }))
+    .output(
+      z
+        .object({
+          id: z.string(),
+          name: z.string(),
+          roles: z.array(z.string()),
+          accessRules: z.array(z.string()),
+          teamIds: z.array(z.string()),
+        })
+        .nullable(),
+    ),
+
+  /**
+   * List the applications the calling user may BIND as an automation's
+   * service account. An application is bindable only when its resolved
+   * access rules are a subset of the caller's (a user can never grant an
+   * automation more authority than they hold); `*`-holders may bind any
+   * application. Drives the "Run as" picker in the automation editor.
+   */
+  getBindableApplications: proc({
+    operationType: "query",
+    userType: "user",
+    access: [],
+  }).output(
+    z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        description: z.string().nullable().optional(),
+      }),
+    ),
+  ),
+
   // ==========================================================================
   // TEAM MANAGEMENT (userType: "authenticated" with access)
   // ==========================================================================