@checkstack/backend 0.15.0 → 0.16.1

package/src/plugin-manager/app-principal-authz.test.ts

@@ -0,0 +1,178 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { z } from "zod";
+import { implement } from "@orpc/server";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { ContractRouterClient } from "@orpc/contract";
+import { access, proc } from "@checkstack/common";
+import {
+  coreServices,
+  createMockRpcContext,
+  autoAuthMiddleware,
+  correlationMiddleware,
+  type AuthService,
+  type AuthUser,
+  type EventBus,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import { ServiceRegistry } from "../services/service-registry";
+import { createApiRouteHandler, registerApiRoute } from "./api-router";
+
+/**
+ * Hardening test for the automation `runAs` SERVICE-ACCOUNT principal.
+ *
+ * The whole design rests on ONE invariant: an automation's app-principal token
+ * resolves to an `application` principal that is subject to the FULL access-rule
+ * enforcement - it must NEVER be treated as a trusted `service` (which
+ * short-circuits all checks = god mode). If a future change made the
+ * app-principal a `service`, a prompt-injected AI Action could mutate any
+ * team's data. This test pins the contrast over real HTTP (real dispatcher,
+ * real `autoAuthMiddleware`, real loopback), so that regression goes red.
+ *
+ * It does not exercise the JWT mint/verify plumbing (that is mechanical); it
+ * guards the security-relevant outcome: application => enforced, service =>
+ * bypassed.
+ */
+
+const manageRule = access("thing", "manage", "Manage things");
+
+const targetContract = {
+  // Gated by `thing.manage`. autoAuthMiddleware qualifies it to
+  // `target.thing.manage` for the "target" plugin.
+  manageThing: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [manageRule],
+  }).output(z.object({ ok: z.boolean(), kind: z.string() })),
+};
+
+type RootClient = ContractRouterClient<{ target: typeof targetContract }>;
+
+function buildTargetRouter() {
+  const os = implement(targetContract)
+    .$context<RpcContext>()
+    .use(correlationMiddleware)
+    .use(autoAuthMiddleware);
+  return os.router({
+    manageThing: os.manageThing.handler(async ({ context }) => ({
+      ok: true,
+      kind: context.user?.type ?? "anonymous",
+    })),
+  });
+}
+
+const noopEventBus: EventBus = {
+  subscribe: async () => async () => {},
+  emit: async () => {},
+  emitLocal: async () => {},
+  shutdown: async () => {},
+};
+
+/**
+ * Maps bearer tokens to the principal kinds we want to contrast:
+ * - `app-ok`   -> application HOLDING the qualified rule
+ * - `app-deny` -> application WITHOUT the rule (must be refused)
+ * - `svc`      -> trusted service (short-circuits all checks)
+ */
+const realAuth: AuthService = {
+  async authenticate(request) {
+    const header = request.headers.get("authorization");
+    if (header === "Bearer app-ok") {
+      return {
+        type: "application",
+        id: "app-ok",
+        name: "Bounded App",
+        accessRules: ["target.thing.manage"],
+      } satisfies AuthUser;
+    }
+    if (header === "Bearer app-deny") {
+      return {
+        type: "application",
+        id: "app-deny",
+        name: "Under-privileged App",
+        accessRules: [],
+      } satisfies AuthUser;
+    }
+    if (header === "Bearer svc") {
+      return { type: "service", pluginId: "automation" } satisfies AuthUser;
+    }
+    return undefined;
+  },
+  async getCredentials() {
+    return { headers: {} };
+  },
+  async getAnonymousAccessRules() {
+    return [];
+  },
+  async checkResourceTeamAccess() {
+    return { hasAccess: false };
+  },
+  async getAccessibleResourceIds({ resourceIds }) {
+    return resourceIds;
+  },
+};
+
+function buildRegistry(): ServiceRegistry {
+  const stub = createMockRpcContext();
+  const registry = new ServiceRegistry();
+  registry.register(coreServices.logger, stub.logger);
+  registry.register(coreServices.database, stub.db);
+  registry.register(coreServices.fetch, stub.fetch);
+  registry.register(coreServices.healthCheckRegistry, stub.healthCheckRegistry);
+  registry.register(coreServices.collectorRegistry, stub.collectorRegistry);
+  registry.register(coreServices.queuePluginRegistry, stub.queuePluginRegistry);
+  registry.register(coreServices.queueManager, stub.queueManager);
+  registry.register(coreServices.cachePluginRegistry, stub.cachePluginRegistry);
+  registry.register(coreServices.cacheManager, stub.cacheManager);
+  registry.register(coreServices.eventBus, noopEventBus);
+  registry.register(coreServices.auth, realAuth);
+  return registry;
+}
+
+const app = new Hono();
+const apiHandler = createApiRouteHandler({
+  registry: buildRegistry(),
+  pluginRpcRouters: new Map<string, unknown>([["target", buildTargetRouter()]]),
+  pluginHttpHandlers: new Map(),
+  pluginMetadataRegistry: new Map([["target", { pluginId: "target" }]]),
+});
+registerApiRoute(app, apiHandler);
+
+const listening = Bun.serve({ port: 0, fetch: app.fetch });
+const baseUrl = `http://localhost:${listening.port}`;
+
+afterAll(() => {
+  listening.stop(true);
+});
+
+function clientWith(headers: Record<string, string>): RootClient {
+  return createORPCClient<RootClient>(
+    new RPCLink({ url: `${baseUrl}/api`, headers }),
+  );
+}
+
+describe("app-principal authorization (real HTTP)", () => {
+  test("an application HOLDING the rule is allowed (enforced, not bypassed)", async () => {
+    const result = await clientWith({
+      authorization: "Bearer app-ok",
+    }).target.manageThing();
+    expect(result).toEqual({ ok: true, kind: "application" });
+  });
+
+  test("an application WITHOUT the rule is FORBIDDEN - the security crux", async () => {
+    // Proves the app-principal flows through full access-rule enforcement and is
+    // NOT short-circuited like a service. This is the guarantee that an
+    // automation can never exceed its service account's permissions.
+    await expect(
+      clientWith({ authorization: "Bearer app-deny" }).target.manageThing(),
+    ).rejects.toThrow(/Missing access|FORBIDDEN/i);
+  });
+
+  test("a trusted service bypasses the check (the contrast we must NOT grant apps)", async () => {
+    const result = await clientWith({
+      authorization: "Bearer svc",
+    }).target.manageThing();
+    expect(result).toEqual({ ok: true, kind: "service" });
+  });
+});

package/src/plugin-manager/auth-passthrough.test.ts

@@ -0,0 +1,259 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { z } from "zod";
+import { implement, ORPCError } from "@orpc/server";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { ContractRouterClient } from "@orpc/contract";
+import { proc } from "@checkstack/common";
+import {
+  coreServices,
+  createMockRpcContext,
+  autoAuthMiddleware,
+  correlationMiddleware,
+  type AuthService,
+  type AuthUser,
+  type EventBus,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import { ServiceRegistry } from "../services/service-registry";
+import { createApiRouteHandler, registerApiRoute } from "./api-router";
+
+/**
+ * REAL end-to-end auth-passthrough test for the `/api/:pluginId/*` dispatcher.
+ *
+ * This guards the regression where `createApiRouteHandler` built the per-request
+ * `RpcContext` WITHOUT `requestHeaders`, so a handler that re-enters the router
+ * as the originating user (an AI tool's user-scoped rpcClient via
+ * `proposeTool`/`applyTool`) forwarded NO auth and the loopback failed with
+ * "Authentication required". It exercises the actual wiring over real HTTP - a
+ * real `Bun.serve`, the real dispatcher, real `autoAuthMiddleware`, and a real
+ * loopback oRPC client - with NO fakes for the path under test. The only stubs
+ * are unrelated core-service collaborators (db, registries, queue, cache), which
+ * none of these handlers touch.
+ *
+ * `caller.run` mirrors exactly what `proposeTool`/`applyTool` do: read
+ * `context.requestHeaders`, forward the caller's own cookie/bearer, and call a
+ * gated procedure on another plugin AS THAT USER. With the bug present,
+ * `caller.run` would throw "Authentication required" instead of returning the
+ * caller's id - so this test goes red without the fix and green with it.
+ */
+
+// ─── Contracts (a "target" plugin gated by auth, a "caller" that loops back) ──
+
+const targetContract = {
+  // Requires an authenticated user; echoes WHO the router authenticated.
+  whoami: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [],
+  }).output(z.object({ id: z.string(), kind: z.string() })),
+};
+
+const callerContract = {
+  // PUBLIC so it is reachable without outer auth - that lets us prove the
+  // LOOPBACK itself enforces auth (an unauthenticated run still fails downstream).
+  run: proc({ operationType: "query", userType: "public", access: [] }).output(
+    z.object({ id: z.string(), kind: z.string() }),
+  ),
+  // Directly surfaces whether the dispatcher populated `context.requestHeaders`.
+  echo: proc({ operationType: "query", userType: "public", access: [] }).output(
+    z.object({ seenAuthHeader: z.string().nullable() }),
+  ),
+};
+
+const rootContract = { target: targetContract, caller: callerContract };
+type RootClient = ContractRouterClient<typeof rootContract>;
+
+// Set once the server is listening; the caller handler reads it at call time.
+const server = { baseUrl: "" };
+
+// ─── Routers ──────────────────────────────────────────────────────────────
+
+function buildTargetRouter() {
+  const os = implement(targetContract)
+    .$context<RpcContext>()
+    .use(correlationMiddleware)
+    .use(autoAuthMiddleware);
+  return os.router({
+    whoami: os.whoami.handler(async ({ context }) => {
+      // autoAuthMiddleware already rejected an unauthenticated caller; this guard
+      // also narrows the AuthUser union to the `user` variant (which carries id).
+      const user = context.user;
+      if (!user || user.type !== "user") {
+        throw new ORPCError("UNAUTHORIZED", {
+          message: "Authentication required",
+        });
+      }
+      return { id: user.id, kind: user.type };
+    }),
+  });
+}
+
+function buildCallerRouter() {
+  const os = implement(callerContract)
+    .$context<RpcContext>()
+    .use(correlationMiddleware)
+    .use(autoAuthMiddleware);
+  return os.router({
+    run: os.run.handler(async ({ context }) => {
+      // EXACTLY the proposeTool/applyTool pattern: forward the caller's own auth
+      // headers and re-enter the router as that user.
+      const forward: Record<string, string> = {};
+      const auth = context.requestHeaders?.get("authorization");
+      if (auth) forward.authorization = auth;
+      const cookie = context.requestHeaders?.get("cookie");
+      if (cookie) forward.cookie = cookie;
+      const link = new RPCLink({
+        url: `${server.baseUrl}/api`,
+        headers: forward,
+      });
+      const client = createORPCClient<RootClient>(link);
+      return client.target.whoami();
+    }),
+    echo: os.echo.handler(async ({ context }) => ({
+      seenAuthHeader: context.requestHeaders?.get("authorization") ?? null,
+    })),
+  });
+}
+
+// ─── Real auth: maps `Authorization: Bearer u-<id>` to a user principal ──────
+
+// A typed no-op event bus: these handlers never emit, so the bus only needs to
+// exist (the dispatcher requires it non-null). No fakes are needed for the path
+// under test.
+const noopEventBus: EventBus = {
+  subscribe: async () => async () => {},
+  emit: async () => {},
+  emitLocal: async () => {},
+  shutdown: async () => {},
+};
+
+const realAuth: AuthService = {
+  async authenticate(request) {
+    const header = request.headers.get("authorization");
+    const match = header?.match(/^Bearer u-(.+)$/);
+    if (!match) return undefined;
+    return {
+      type: "user",
+      id: match[1],
+      accessRules: ["*"],
+    } satisfies AuthUser;
+  },
+  async getCredentials() {
+    return { headers: {} };
+  },
+  async getAnonymousAccessRules() {
+    return [];
+  },
+  async checkResourceTeamAccess() {
+    return { hasAccess: false };
+  },
+  async getAccessibleResourceIds({ resourceIds }) {
+    return resourceIds;
+  },
+};
+
+// ─── Harness: real dispatcher on a real Bun.serve ────────────────────────────
+
+function buildRegistry(): ServiceRegistry {
+  // Reuse the canonical stub shapes for the collaborators none of these handlers
+  // touch; override auth with the real header-reading strategy and event bus.
+  const stub = createMockRpcContext();
+  const registry = new ServiceRegistry();
+  registry.register(coreServices.logger, stub.logger);
+  registry.register(coreServices.database, stub.db);
+  registry.register(coreServices.fetch, stub.fetch);
+  registry.register(coreServices.healthCheckRegistry, stub.healthCheckRegistry);
+  registry.register(coreServices.collectorRegistry, stub.collectorRegistry);
+  registry.register(coreServices.queuePluginRegistry, stub.queuePluginRegistry);
+  registry.register(coreServices.queueManager, stub.queueManager);
+  registry.register(coreServices.cachePluginRegistry, stub.cachePluginRegistry);
+  registry.register(coreServices.cacheManager, stub.cacheManager);
+  registry.register(coreServices.eventBus, noopEventBus);
+  registry.register(coreServices.auth, realAuth);
+  return registry;
+}
+
+const app = new Hono();
+const apiHandler = createApiRouteHandler({
+  registry: buildRegistry(),
+  pluginRpcRouters: new Map<string, unknown>([
+    ["target", buildTargetRouter()],
+    ["caller", buildCallerRouter()],
+  ]),
+  pluginHttpHandlers: new Map(),
+  pluginMetadataRegistry: new Map([
+    ["target", { pluginId: "target" }],
+    ["caller", { pluginId: "caller" }],
+  ]),
+});
+registerApiRoute(app, apiHandler);
+
+const listening = Bun.serve({ port: 0, fetch: app.fetch });
+server.baseUrl = `http://localhost:${listening.port}`;
+
+afterAll(() => {
+  listening.stop(true);
+});
+
+function clientWith(headers: Record<string, string>): RootClient {
+  return createORPCClient<RootClient>(
+    new RPCLink({ url: `${server.baseUrl}/api`, headers }),
+  );
+}
+
+describe("RPC dispatcher auth passthrough (real HTTP)", () => {
+  test("the dispatcher populates context.requestHeaders from the request", async () => {
+    const client = clientWith({ authorization: "Bearer u-alice" });
+    const echo = await client.caller.echo();
+    // The exact regression: without requestHeaders on the context this is null.
+    expect(echo.seenAuthHeader).toBe("Bearer u-alice");
+  });
+
+  test("a request for an UNKNOWN plugin id returns 404, not 500", async () => {
+    // No metadata is registered for 'nope', so the dispatcher must treat it as a
+    // not-found resource (client error), not an internal server error.
+    const res = await fetch(`${server.baseUrl}/api/nope/whatever`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}",
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test("a loopback call re-enters the router authenticated AS the originating user", async () => {
+    const client = clientWith({ authorization: "Bearer u-alice" });
+    const result = await client.caller.run();
+    // caller.run forwarded alice's bearer to target.whoami, which authenticated
+    // as alice. With the bug (requestHeaders undefined) this throws
+    // "Authentication required" instead.
+    expect(result).toEqual({ id: "alice", kind: "user" });
+  });
+
+  test("a different user's auth is forwarded as THAT user (no cross-user bleed)", async () => {
+    const result = await clientWith({ authorization: "Bearer u-bob" }).caller.run();
+    expect(result).toEqual({ id: "bob", kind: "user" });
+  });
+
+  test("an unauthenticated loopback is refused downstream (auth still enforced)", async () => {
+    // caller.run is public, so the OUTER call proceeds; the loopback forwards no
+    // auth, so target.whoami refuses - proving the loopback does NOT bypass authz.
+    await expect(clientWith({}).caller.run()).rejects.toThrow(
+      /Authentication required|UNAUTHORIZED/i,
+    );
+  });
+
+  test("calling the gated procedure directly with auth works (sanity)", async () => {
+    const result = await clientWith({
+      authorization: "Bearer u-carol",
+    }).target.whoami();
+    expect(result).toEqual({ id: "carol", kind: "user" });
+  });
+
+  test("calling the gated procedure directly WITHOUT auth is refused", async () => {
+    await expect(clientWith({}).target.whoami()).rejects.toThrow(
+      /Authentication required|UNAUTHORIZED/i,
+    );
+  });
+});

package/src/plugin-manager/core-services.ts

@@ -139,6 +139,38 @@ export function registerCoreServices({
               pluginId: payload.service as string,
             };
           }
+
+          // App-principal token: minted by `rpcClientAs` so an automation can
+          // run as its configured service account. Resolve the application's
+          // CURRENT rules/teams LIVE (never trust frozen claims) and return an
+          // `application` principal, so it flows through the full access-rule
+          // and team-scope enforcement - NOT the trusted service short-circuit.
+          if (payload && typeof payload.appPrincipal === "string") {
+            try {
+              const rpcClient = await registry.get(coreServices.rpcClient, {
+                pluginId: "core",
+              });
+              const authClient = rpcClient.forPlugin(AuthApi);
+              const enriched = await authClient.enrichApplicationPrincipal({
+                applicationId: payload.appPrincipal,
+              });
+              if (!enriched) return; // app no longer exists -> unauthenticated
+              return {
+                type: "application" as const,
+                id: enriched.id,
+                name: enriched.name,
+                roles: enriched.roles,
+                accessRules: enriched.accessRules,
+                teamIds: enriched.teamIds,
+              };
+            } catch (error) {
+              // SECURITY: Fail-Closed - never fall back to a broader principal.
+              rootLogger.error(
+                `[auth] app-principal enrichment failed for ${payload.appPrincipal}; denying. Error: ${error}`,
+              );
+              return;
+            }
+          }
         }
 
         // Strategy B: User Token (via registered strategy)
@@ -315,6 +347,52 @@ export function registerCoreServices({
     return rpcClient;
   });
 
+  // 5b. Application-scoped RPC Client Factory.
+  // Returns a builder that mints a short-lived app-principal token and returns
+  // a client re-entering the live router AS THAT APPLICATION. The receiving
+  // `authenticate` (Strategy A) resolves the token to an `application`
+  // principal, so the call runs through the full access-rule + team-scope
+  // enforcement - NOT the trusted service short-circuit. The automation
+  // dispatch engine uses this to run an automation as its `runAs` account.
+  registry.registerFactory(coreServices.rpcClientAs, () => {
+    const apiBaseUrl = process.env.INTERNAL_URL || "http://localhost:3000";
+    return async (applicationId: string): Promise<RpcClient> => {
+      // Mint a FRESH short-lived token PER REQUEST (not once at client
+      // construction). An automation run can stay live far longer than the
+      // token TTL within a single un-suspended stretch - a long AI agent loop
+      // making many tool calls, or many sequential actions - and a client that
+      // baked one token would start failing with 401s once it expired. Minting
+      // per request (mirroring the trusted client's `getCredentials`) means the
+      // TTL only has to outlive a single in-flight request. (Across a
+      // suspend/resume the engine rebuilds the client, so waits are unaffected
+      // either way.)
+      const authedFetch = async (
+        input: RequestInfo | URL,
+        init?: RequestInit,
+      ): Promise<Response> => {
+        const token = await jwtService.sign(
+          { appPrincipal: applicationId },
+          "5m",
+        );
+        const headers = new Headers(init?.headers);
+        headers.set("Authorization", `Bearer ${token}`);
+        return fetch(input, { ...init, headers });
+      };
+      const link = new RPCLink({
+        url: `${apiBaseUrl}/api`,
+        fetch: authedFetch,
+      });
+      const appClient = createORPCClient(link);
+      return {
+        forPlugin(def) {
+          return (appClient as Record<string, unknown>)[
+            def.pluginId
+          ] as never;
+        },
+      };
+    };
+  });
+
   // 6. Health Check Registry (Scoped Factory - auto-prefixes strategy IDs with pluginId)
   const globalHealthCheckRegistry = new CoreHealthCheckRegistry();
   registry.registerFactory(coreServices.healthCheckRegistry, (metadata) =>

package/src/plugin-manager/pg-http-errors.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { ORPCError } from "@orpc/server";
+import { mapPgErrorToHttp } from "./pg-http-errors";
+
+/**
+ * Guards the regression where a client-caused Postgres fault (bad uuid,
+ * out-of-range int, over-long string, FK/unique violation) surfaced as a 500
+ * instead of a 4xx. The fuzzing pass found that `where id = $1` with a non-uuid
+ * `$1` reaches the driver and throws `22P02`, which oRPC reported as 500.
+ */
+describe("mapPgErrorToHttp", () => {
+  test("maps invalid_text_representation (bad uuid/int) to 400", () => {
+    const mapped = mapPgErrorToHttp({ code: "22P02" });
+    expect(mapped).toBeInstanceOf(ORPCError);
+    expect(mapped?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps numeric_value_out_of_range to 400", () => {
+    expect(mapPgErrorToHttp({ code: "22003" })?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps string_data_right_truncation to 400", () => {
+    expect(mapPgErrorToHttp({ code: "22001" })?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps foreign_key_violation to 400", () => {
+    expect(mapPgErrorToHttp({ code: "23503" })?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps unique_violation to 409 CONFLICT", () => {
+    expect(mapPgErrorToHttp({ code: "23505" })?.code).toBe("CONFLICT");
+  });
+
+  test("unwraps a Drizzle-wrapped driver error via cause", () => {
+    const mapped = mapPgErrorToHttp({
+      message: "wrapped",
+      cause: { code: "22P02" },
+    });
+    expect(mapped?.code).toBe("BAD_REQUEST");
+  });
+
+  test("returns undefined for an unknown SQLSTATE (genuine 500 stays a 500)", () => {
+    // 40001 = serialization_failure: a real server fault, not client input.
+    expect(mapPgErrorToHttp({ code: "40001" })).toBeUndefined();
+  });
+
+  test("returns undefined for a non-Postgres error", () => {
+    expect(mapPgErrorToHttp(new Error("boom"))).toBeUndefined();
+    expect(mapPgErrorToHttp("nope")).toBeUndefined();
+    expect(mapPgErrorToHttp(undefined)).toBeUndefined();
+  });
+
+  test("passes an already-mapped ORPCError through untouched (no double-map)", () => {
+    const original = new ORPCError("CONFLICT", { message: "dup" });
+    expect(mapPgErrorToHttp(original)).toBeUndefined();
+  });
+
+  test("does not leak the raw driver message to the client", () => {
+    const mapped = mapPgErrorToHttp({
+      code: "22001",
+      message: 'value too long for column "secret_token"',
+    });
+    expect(mapped?.message).not.toContain("secret_token");
+  });
+});

package/src/plugin-manager/pg-http-errors.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { ORPCError } from "@orpc/server";
+
+/**
+ * Postgres SQLSTATE codes for the error classes a *client* can trigger with bad
+ * input. These must surface as 4xx, not 500 - a malformed uuid, an out-of-range
+ * integer, an over-long string, or a constraint violation is the caller's
+ * mistake, not an internal server error.
+ *
+ * Without this mapping a `where id = $1` with `$1 = "not-a-uuid"` reaches the
+ * driver and throws `22P02`, which oRPC reports as a 500 - making routine
+ * fuzzing/probing look like the server is broken and burying genuine 500s.
+ *
+ * @see https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+const PG_CLIENT_ERROR_CODES: Record<string, { code: "BAD_REQUEST" | "CONFLICT"; message: string }> = {
+  // Class 22 — data exception (the caller sent a value the type can't hold).
+  "22P02": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a value was malformed (e.g. not a valid id).",
+  },
+  "22003": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a numeric value is out of the allowed range.",
+  },
+  "22001": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a text value exceeds the allowed length.",
+  },
+  "22007": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a date/time value is malformed.",
+  },
+  // Class 23 — integrity-constraint violation.
+  "23502": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a required value is missing.",
+  },
+  "23503": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a referenced record does not exist.",
+  },
+  "23505": {
+    code: "CONFLICT",
+    message: "That record already exists.",
+  },
+  "23514": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a value failed a validation constraint.",
+  },
+};
+
+// A Postgres driver error carries a SQLSTATE string in `code`. Drizzle may
+// rethrow it wrapped, exposing the original on `cause`, so we check both shapes
+// (mirrors the catalog-backend `pg-errors` matcher).
+const pgErrorSchema = z.object({ code: z.string() });
+const wrappedPgErrorSchema = z.object({ cause: pgErrorSchema });
+
+function extractSqlState(error: unknown): string | undefined {
+  const direct = pgErrorSchema.safeParse(error);
+  if (direct.success) return direct.data.code;
+  const wrapped = wrappedPgErrorSchema.safeParse(error);
+  if (wrapped.success) return wrapped.data.cause.code;
+  return undefined;
+}
+
+/**
+ * Maps a caught Postgres driver error to an `ORPCError` with the right 4xx
+ * status when the SQLSTATE indicates a client-caused fault. Returns `undefined`
+ * for anything else (genuine 500s, application errors), so callers fall through
+ * to their existing error-logging + rethrow path.
+ *
+ * The original error is preserved as `cause` for diagnostics; the client-facing
+ * message is deliberately generic so we never leak column/constraint names.
+ */
+export function mapPgErrorToHttp(error: unknown): ORPCError<string, unknown> | undefined {
+  // An already-mapped oRPC error (e.g. a handler's own CONFLICT/NOT_FOUND) must
+  // pass through untouched.
+  if (error instanceof ORPCError) return undefined;
+  const sqlState = extractSqlState(error);
+  if (!sqlState) return undefined;
+  const mapping = PG_CLIENT_ERROR_CODES[sqlState];
+  if (!mapping) return undefined;
+  return new ORPCError(mapping.code, { message: mapping.message, cause: error });
+}