@checkstack/backend 0.14.0 → 0.16.0

package/src/plugin-manager/api-router.ts

@@ -24,6 +24,7 @@ import type { EventBus } from "@checkstack/backend-api";
 import type { PluginMetadata } from "@checkstack/common";
 import { rootLogger } from "../logger";
 import { extractErrorMessage } from "@checkstack/common";
+import { mapPgErrorToHttp } from "./pg-http-errors";
 
 interface RouteHandlerDeps {
   registry: ServiceRegistry;
@@ -139,14 +140,20 @@ async function resolveRequestContext({
     deps.pluginMetadataRegistry.get(pluginId);
 
   if (!pluginMetadata) {
-    (logger as Logger).error(
+    // No metadata for this pluginId. The common cause is a client requesting an
+    // unknown plugin (typo / probing) - a 404, not a 500. A genuine
+    // misconfiguration (a core router that forgot
+    // pluginManager.registerCorePluginMetadata()) surfaces the same way, so we
+    // log it for diagnosis, but at warn level since the dominant case is a
+    // client error and erroring on every bad path would be noise.
+    (logger as Logger).warn(
       `${pathname}: no plugin metadata registered for pluginId='${pluginId}'. ` +
-        `Regular plugins populate this during register(); core routers must call ` +
-        `pluginManager.registerCorePluginMetadata().`,
+        `Either the plugin id is unknown (client typo / probe), or a core ` +
+        `router did not call pluginManager.registerCorePluginMetadata().`,
     );
     return {
       ok: false,
-      response: c.json({ error: "Plugin metadata not found in registry" }, 500),
+      response: c.json({ error: "Not Found" }, 404),
     };
   }
 
@@ -163,6 +170,11 @@ async function resolveRequestContext({
     cachePluginRegistry: cachePluginRegistry as CachePluginRegistry,
     cacheManager: cacheManager as CacheManager,
     user,
+    // The incoming request's headers, so a handler can forward the caller's OWN
+    // auth (session cookie / bearer) when it re-enters the router as the same
+    // user - e.g. an AI tool's user-scoped rpcClient (proposeTool/applyTool).
+    // Also read by correlationMiddleware for the inbound correlation id.
+    requestHeaders: c.req.raw.headers,
     emitHook,
   };
 
@@ -203,6 +215,35 @@ function logHandlerError({
   }
 }
 
+/**
+ * Shared interceptor catch path for both the RPC and REST handlers. A Postgres
+ * driver error caused by bad client input (bad uuid, out-of-range int, over-long
+ * string, constraint violation) is mapped to the correct 4xx `ORPCError` and
+ * logged at warn (it is a client mistake, not a server fault). Everything else
+ * keeps the existing error-level logging + rethrow so genuine 500s stay loud.
+ */
+function rethrowAsHttpError({
+  error,
+  pathname,
+  logger,
+  protocolLabel,
+}: {
+  error: unknown;
+  pathname: string;
+  logger: Logger | undefined;
+  protocolLabel: string;
+}): never {
+  const mapped = mapPgErrorToHttp(error);
+  if (mapped) {
+    (logger ?? rootLogger).warn(
+      `${protocolLabel} ${pathname}: ${mapped.code} (${extractErrorMessage(error)})`,
+    );
+    throw mapped;
+  }
+  logHandlerError({ error, pathname, logger, protocolLabel });
+  throw error;
+}
+
 /**
  * Creates the API route handler for Hono.
  * Serves oRPC's native RPC wire protocol at /api/:pluginId/*.
@@ -242,13 +283,12 @@ export function createApiRouteHandler({
             try {
               return await next(rest);
             } catch (error) {
-              logHandlerError({
+              rethrowAsHttpError({
                 error,
                 pathname,
                 logger,
                 protocolLabel: "RPC",
               });
-              throw error;
             }
           },
         ],
@@ -321,13 +361,12 @@ export function createRestRouteHandler({
             try {
               return await next(rest);
             } catch (error) {
-              logHandlerError({
+              rethrowAsHttpError({
                 error,
                 pathname,
                 logger,
                 protocolLabel: "REST",
               });
-              throw error;
             }
           },
         ],

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

@@ -14,7 +14,7 @@ import {
 import { AuthApi } from "@checkstack/auth-common";
 import type { ServiceRegistry } from "../services/service-registry";
 import { rootLogger } from "../logger";
-import { db } from "../db";
+import { db, lockPool } from "../db";
 import { jwtService } from "../services/jwt";
 import {
   CoreHealthCheckRegistry,
@@ -98,11 +98,14 @@ export function registerCoreServices({
     return createScopedDb(db, assignedSchema);
   });
 
-  // 1b. Advisory Lock Factory (server-global, backed by the shared admin
-  // pool). Session locks need connection affinity, so the service checks
-  // out a dedicated client per acquired lock and releases on the SAME
-  // client — the scoped per-query DB proxy can't provide that.
-  const advisoryLockService = createAdvisoryLockService(adminPool);
+  // 1b. Advisory Lock Factory (server-global, backed by the DEDICATED
+  // `lockPool`, NOT `adminPool`). Both session locks (`tryAcquire`) and the
+  // transaction-scoped `withXactLock` HOLD a connection for the lock's whole
+  // lifetime while the locked work runs on `adminPool`. Drawing the lock
+  // connection from a separate pool keeps the acquire graph acyclic
+  // (lockPool -> adminPool, never back), so a held lock can never starve the
+  // work pool into the `idle in transaction` deadlock. See `db.ts`.
+  const advisoryLockService = createAdvisoryLockService(lockPool);
   registry.registerFactory(
     coreServices.advisoryLock,
     () => advisoryLockService,
@@ -136,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)
@@ -312,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) =>