From 8adf0a463a1ed87039fb7badd864003d06cda9c9 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:43:39 -0600 Subject: [PATCH] perf(db): build the agent request authentication statements once per client (#21707) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - One Node process controls every run of a workspace. At 1,000 concurrent agents, main-thread CPU for each database statement is the scarce resource. > - A CPU profile of the hosted server shows the cost is per statement: building SQL text in Drizzle costs about as much as parsing the result in postgres.js. > - Every authenticated agent API request (about 0.3 per agent per second, plus tool calls) runs three fixed statements in `actorMiddleware`: the agent row, the run authentication projection, and the responsible user's company memberships. The server built the SQL text of all three again for every request. > - A local micro-benchmark shows that building the text is 15 to 40 µs of CPU per statement for these shapes, and that a reused prepared query costs the same as a raw driver call. Drizzle's `tracing.ts` wrapper is a no-op (0.1 µs). > - This pull request prepares the three statements once per database client with placeholders, and executes them with the request's values. The driver receives the same SQL text and parameters as before. > - The benefit is about 40% less main-thread CPU for each authenticated agent request in a local benchmark. ## Linked Issues or Issue Description **What existing behavior does this improve?** The CPU cost of agent JWT and agent key authentication on every agent API request. **Subsystem affected** Server request authentication (`server/src/middleware/auth.ts`, `server/src/middleware/agent-run-authentication.ts`). **Current behavior** For every agent request, `actorMiddleware` builds three Drizzle queries from scratch: `agents` by id, the `heartbeat_runs` authentication projection (with `jsonb_build_object` and two `run_identity_contexts` subqueries), and the `company_memberships` read with an `exists` on `auth_users`. Building and preparing them costs 14, 38 and 40 µs of CPU (median of 7 passes of 5,000 builds). **Proposed behavior** Build each statement one time for each database client, with `sql.placeholder` values. Execute the prepared query with the request's values. The SQL text, the parameters, and the returned rows stay the same. **Reason and benefit** At 1,000 agents, agent API traffic is several hundred authenticated requests per second on one main thread. Measured CPU per authenticated request (local, embedded PostgreSQL, `process.cpuUsage()`, 2,000 requests per pass): | Run (interleaved) | Before: median (min–max) µs | After: median (min–max) µs | Load average | | --- | --- | --- | --- | | 1 | 436 (363–599) | 200 (183–224) | 10.8 / 10.1 | | 2 | 489 (430–535) | 312 (212–392) | 11.6 / 13.4 | | 3 | 461 (442–562) | 281 (247–409) | 13.1 / 12.9 | | separate | 383 (322–810), 301 (268–476) | 169 (156–439), 193 (174–215) | 9.5 / 9.0 | The machine is shared (18 cores), so the spread is wide. Every pair shows the after run lower. The drop is larger than the build cost alone, because the request also allocates less (fewer builder objects to collect). **Breaking changes** None. The statements, their parameters and the result shapes do not change. **Additional context** Per-statement cost attribution from the new `packages/db/scripts/benchmark-statement-cpu.ts` (CPU µs per statement, median of 5 passes of 2,000, two runs, concurrency 1, load average 20–26): | Statement | Drizzle builder | Build only (`toSQL`) | Drizzle `.prepare()` reused | `unsafe(text, params)` | `unsafe(..., {prepare: true})` | | --- | --- | --- | --- | --- | --- | | `issues` parent by id | 105 / 122 | 17 / 18 | 59 / 75 | 57 / 63 | 30 / 33 | | `issues` full row by id | 277 / 326 | 136 / 153 | 96 / 81 | 97 / 77 | 48 / 33 | | `company_memberships` by principal | 128 / 103 | 35 / 33 | 71 / 66 | 80 / 63 | 37 / 32 | | join with an in-list of 10 | 169 / 173 | 57 / 57 | 83 / 88 | 109 / 80 | 42 / 40 | | update by id | 110 / 106 | 25 / 26 | 75 / 80 | 76 / 73 | 39 / 40 | | insert `activity_log` | 116 / 125 | 34 / 35 | 65 / 57 | 64 / 55 | 41 / 30 | Drizzle's no-op tracer (`startActiveSpan`) measured 0.1 µs per call. ## What Changed - `server/src/services/prepared-statements.ts`: add `preparedStatement(prepare)`, the single-statement form of the existing `preparedStatements` helper (one prepared query for each `Db`, held in a `WeakMap`). - `server/src/middleware/agent-run-authentication.ts`: split the query into `agentRunAuthenticationQuery(db, binding)`; `loadAgentRunAuthentication` executes the query prepared once with placeholders. - `server/src/middleware/auth.ts`: add `agentAuthenticationQuery` and `responsibleUserMembershipsQuery`; the JWT path, the agent key path and `loadResponsibleUserMemberships` execute their prepared forms. - `server/src/__tests__/agent-auth-prepared-statements.test.ts` (new): proves that each prepared statement sends the same SQL text and parameters and returns strictly equal rows, and that repeated agent requests do not build the statements again. - `server/src/__tests__/agent-auth-middleware.test.ts`: the test double's select chain now supports `.prepare().execute()`. - `server/src/__tests__/prepared-statements.test.ts`: covers `preparedStatement`. - `packages/db/scripts/benchmark-statement-cpu.ts` (new): CPU per statement for the builder, build only, a reused prepared query, `unsafe` with and without `prepare: true`, and the no-op tracer. Run with `cd packages/db && ITERATIONS=2000 PASSES=5 node --import tsx scripts/benchmark-statement-cpu.ts` (`CONCURRENCY`, `ONLY`, `VARIANTS` are optional). - `scripts/benchmark-agent-request-auth-cpu.ts` (new): CPU per authenticated agent JWT request through `actorMiddleware`. Run with `pnpm --filter @paperclipai/server exec tsx ../scripts/benchmark-agent-request-auth-cpu.ts`. Both benchmarks start their own embedded PostgreSQL in a temporary directory. ## Verification - Red/green: the "builds the request authentication statements once per database client" test failed on `origin/master` (`select` called 12 times in 3 requests) and passes with this change. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/agent-auth-prepared-statements.test.ts src/__tests__/prepared-statements.test.ts src/__tests__/agent-auth-middleware.test.ts src/__tests__/agent-run-authentication.test.ts src/__tests__/agent-jwt-request-authentication.test.ts src/__tests__/auth-session-route.test.ts src/middleware/cloud-tenant-actor.test.ts src/__tests__/local-agent-process-boundary.test.ts src/__tests__/liveness.test.ts src/__tests__/inbox-mine-routes.test.ts src/__tests__/board-bootstrap-routes.test.ts src/__tests__/agent-auth-identity-transfer.test.ts src/__tests__/prepared-statements-driver.test.ts src/services/fresh-continuation-fallback.test.ts`: all pass. - CPU before and after: the tables above. ## Risks - Low risk. The prepared query uses Drizzle's own `PgPreparedQuery`, the same execute path that the builder uses. The test pins the SQL text, the parameters and the rows against the builder. - Drizzle's `.prepare(name)` on postgres.js does not send a statement name to the database (see #21201). With `DATABASE_PREPARED_STATEMENTS` unset, the driver sends the same unnamed statement as before, so connection poolers see no change. - A test double for `Db` must now support `.prepare().execute()` on these selects. One test double changed. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use (shell, file edits, local test and benchmark runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- .../db/scripts/benchmark-statement-cpu.ts | 151 ++++++++++++++++++ scripts/benchmark-agent-authentication.ts | 4 +- scripts/benchmark-agent-request-auth-cpu.ts | 47 ++++++ .../__tests__/agent-auth-middleware.test.ts | 4 +- .../agent-auth-prepared-statements.test.ts | 93 +++++++++++ .../src/__tests__/prepared-statements.test.ts | 13 +- .../middleware/agent-run-authentication.ts | 26 ++- server/src/middleware/auth.ts | 47 ++++-- server/src/services/prepared-statements.ts | 9 ++ 9 files changed, 368 insertions(+), 26 deletions(-) create mode 100644 packages/db/scripts/benchmark-statement-cpu.ts create mode 100644 scripts/benchmark-agent-request-auth-cpu.ts create mode 100644 server/src/__tests__/agent-auth-prepared-statements.test.ts diff --git a/packages/db/scripts/benchmark-statement-cpu.ts b/packages/db/scripts/benchmark-statement-cpu.ts new file mode 100644 index 00000000000..d114efd9922 --- /dev/null +++ b/packages/db/scripts/benchmark-statement-cpu.ts @@ -0,0 +1,151 @@ +import { randomUUID } from "node:crypto"; +import { cpus, loadavg } from "node:os"; +import { and, eq, inArray, mapResultRow, sql } from "drizzle-orm"; +import { tracer } from "drizzle-orm/tracing"; +import { drizzle } from "drizzle-orm/postgres-js"; +import postgres from "postgres"; +import { createDb } from "../src/client.js"; +import * as schema from "../src/schema/index.js"; +import { activityLog, agents, companies, companyMemberships, issues } from "../src/schema/index.js"; +import { startEmbeddedPostgresTestDatabase } from "../src/test-embedded-postgres.js"; + +const iterations = Number(process.env.ITERATIONS ?? 2000); +const passes = Number(process.env.PASSES ?? 5); +const concurrency = Number(process.env.CONCURRENCY ?? 1); +const only = process.env.ONLY?.split(",").filter(Boolean); +const variants = process.env.VARIANTS?.split("|").filter(Boolean); +const median = (values: number[]) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)]!; + +async function pass(action: () => Promise | unknown) { + const cpu = process.cpuUsage(), startedAt = performance.now(); + let next = 0; + await Promise.all(Array.from({ length: concurrency }, async () => { + while (next < iterations) { next += 1; await action(); } + })); + const used = process.cpuUsage(cpu); + return { cpu: (used.user + used.system) / iterations, wall: (performance.now() - startedAt) * 1000 / iterations }; +} + +const results: Record> = {}; +async function measure(statement: string, variant: string, action: () => Promise | unknown) { + if (only && !only.includes(statement)) return; + if (variants && !variants.some(name => variant.startsWith(name))) return; + for (let index = 0; index < Math.min(500, iterations); index += 1) await action(); + const samples = []; + for (let index = 0; index < passes; index += 1) samples.push(await pass(action)); + const cpu = samples.map(sample => sample.cpu); + (results[statement] ??= {})[variant] = { median: Number(median(cpu).toFixed(1)), min: Number(Math.min(...cpu).toFixed(1)), + max: Number(Math.max(...cpu).toFixed(1)) }; + console.log(JSON.stringify({ statement, variant, cpuMicros: results[statement][variant], + wallMicros: Number(median(samples.map(sample => sample.wall)).toFixed(1)) })); +} + +type Query = { toSQL(): { sql: string; params: unknown[] }; _: { selectedFields?: unknown } }; +type Case = { + name: string; + build: (db: ReturnType) => Query & PromiseLike; + prepare: (db: ReturnType) => { execute(values: Record): Promise }; + values: Record; + fields?: (query: Query) => unknown; +}; + +const database = await startEmbeddedPostgresTestDatabase("paperclip-statement-cpu-"); +const db = createDb(database.connectionString, { maxConnections: 4 }); +const plainSql = postgres(database.connectionString, { max: 4, onnotice: () => {} }); +const plain = drizzle(plainSql, { schema }); +try { + const [company] = await db.insert(companies).values({ name: "Bench", issuePrefix: "BEN" }).returning({ id: companies.id }); + const companyId = company!.id; + const [agent] = await db.insert(agents).values({ companyId, name: "Agent" }).returning({ id: agents.id }); + const issueIds: string[] = []; + for (let index = 0; index < 20; index += 1) { + const [issue] = await db.insert(issues).values({ companyId, title: `Issue ${index}`, assigneeAgentId: agent!.id, + description: "x".repeat(400) }).returning({ id: issues.id }); + issueIds.push(issue!.id); + } + const userId = "user-1"; + await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: userId, status: "active", + membershipRole: "owner" }); + const listIds = issueIds.slice(0, 10); + + const cases: Case[] = [ + { + name: "issue parent by id", + build: d => d.select({ parentId: issues.parentId }).from(issues).where(eq(issues.id, issueIds[0]!)), + prepare: d => d.select({ parentId: issues.parentId }).from(issues).where(eq(issues.id, sql.placeholder("id"))).prepare("p1"), + values: { id: issueIds[0] }, + }, + { + name: "issue row by id", + build: d => d.select().from(issues).where(eq(issues.id, issueIds[1]!)), + prepare: d => d.select().from(issues).where(eq(issues.id, sql.placeholder("id"))).prepare("p2"), + values: { id: issueIds[1] }, + }, + { + name: "membership by principal", + build: d => d.select({ companyId: companyMemberships.companyId, membershipRole: companyMemberships.membershipRole, + status: companyMemberships.status }).from(companyMemberships).where(and(eq(companyMemberships.companyId, companyId), + eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, userId), + eq(companyMemberships.status, "active"))), + prepare: d => d.select({ companyId: companyMemberships.companyId, membershipRole: companyMemberships.membershipRole, + status: companyMemberships.status }).from(companyMemberships).where(and( + eq(companyMemberships.companyId, sql.placeholder("companyId")), eq(companyMemberships.principalType, "user"), + eq(companyMemberships.principalId, sql.placeholder("userId")), eq(companyMemberships.status, "active"))).prepare("p3"), + values: { companyId, userId }, + }, + { + name: "join with in-list of 10", + build: d => d.select({ id: issues.id, title: issues.title, status: issues.status, agentName: agents.name }) + .from(issues).leftJoin(agents, eq(issues.assigneeAgentId, agents.id)) + .where(and(eq(issues.companyId, companyId), inArray(issues.id, listIds))), + prepare: d => d.select({ id: issues.id, title: issues.title, status: issues.status, agentName: agents.name }) + .from(issues).leftJoin(agents, eq(issues.assigneeAgentId, agents.id)) + .where(and(eq(issues.companyId, sql.placeholder("companyId")), sql`${issues.id} = any(${sql.placeholder("ids")}::uuid[])`)).prepare("p4"), + values: { companyId, ids: listIds }, + }, + { + name: "update by id", + build: d => d.update(issues).set({ updatedAt: new Date(), checkoutRunId: null }).where(eq(issues.id, issueIds[2]!)) as never, + prepare: d => d.update(issues).set({ updatedAt: sql.placeholder("now") as never, checkoutRunId: null }) + .where(eq(issues.id, sql.placeholder("id"))).prepare("p5"), + values: { id: issueIds[2], now: new Date() }, + }, + { + name: "insert activity", + build: d => d.insert(activityLog).values({ companyId, actorType: "agent", actorId: agent!.id, action: "issue.updated", + entityType: "issue", entityId: issueIds[3]!, agentId: agent!.id, details: { field: "status", from: "todo", to: "done" } }) as never, + prepare: d => d.insert(activityLog).values({ companyId: sql.placeholder("companyId"), actorType: "agent", + actorId: sql.placeholder("actorId"), action: "issue.updated", entityType: "issue", entityId: sql.placeholder("entityId"), + agentId: sql.placeholder("actorId"), details: sql.placeholder("details") }).prepare("p6"), + values: { companyId, actorId: agent!.id, entityId: issueIds[3], details: { field: "status", from: "todo", to: "done" } }, + }, + ]; + + await measure("tracer", "no-op startActiveSpan (async callback)", () => tracer.startActiveSpan("x", async () => 1)); + for (const item of cases) { + const sample = item.build(db); + const { sql: text, params } = sample.toSQL(); + const ordered = (sample as unknown as { _prepare(): { fields?: unknown; joinsNotNullableMap?: unknown } })._prepare(); + const mapFields = ordered.fields as Parameters[0] | undefined; + const joins = ordered.joinsNotNullableMap as Parameters[2]; + await measure(item.name, "build only (toSQL)", () => item.build(db).toSQL()); + await measure(item.name, "drizzle builder, createDb", () => item.build(db)); + await measure(item.name, "drizzle builder, plain drizzle()", () => item.build(plain as never)); + const prepared = item.prepare(db); + await measure(item.name, "drizzle .prepare() reused", () => prepared.execute(item.values)); + if (mapFields) { + await measure(item.name, "unsafe .values() + mapResultRow", async () => { + const rows = await db.$client.unsafe(text, params as never[]).values(); + return rows.map(row => mapResultRow(mapFields, row as unknown[], joins)); + }); + } + await measure(item.name, "unsafe(text, params)", () => db.$client.unsafe(text, params as never[])); + await measure(item.name, "unsafe(text, params, {prepare:true})", () => db.$client.unsafe(text, params as never[], { prepare: true })); + } + console.log(JSON.stringify({ kind: "summary", node: process.version, cpus: cpus().length, loadavg: loadavg(), iterations, + passes, concurrency, results })); +} finally { + await plainSql.end({ timeout: 1 }); + await db.$client.end({ timeout: 1 }); + await database.cleanup(); +} diff --git a/scripts/benchmark-agent-authentication.ts b/scripts/benchmark-agent-authentication.ts index b50bae740e7..90d152dcbb1 100644 --- a/scripts/benchmark-agent-authentication.ts +++ b/scripts/benchmark-agent-authentication.ts @@ -6,7 +6,7 @@ import { createRequire } from "node:module"; const { and, eq } = createRequire(new URL("../server/package.json", import.meta.url))("drizzle-orm"); import { agents, companies, createDb, heartbeatRuns, startEmbeddedPostgresTestDatabase, type Db } from "../packages/db/src/index.js"; import { agentRunWritesRevoked } from "../server/src/agent-run-cancellation.js"; -import { loadAgentRunAuthentication } from "../server/src/middleware/agent-run-authentication.js"; +import { agentRunAuthenticationQuery } from "../server/src/middleware/agent-run-authentication.js"; type Query = { sql: string; params: unknown[] }; const baselineRef = process.argv.find(arg => arg.startsWith("--baseline-ref="))?.slice(15); @@ -32,7 +32,7 @@ try { const baseline = new Function("db", "heartbeatRuns", "and", "eq", "claims", `return ${expression}`)( db, heartbeatRuns, and, eq, { sub: agentId, company_id: companyId, run_id: runId }, ).toSQL() as Query; - const treatment = loadAgentRunAuthentication(db, { companyId, agentId, runId }).toSQL(); + const treatment = agentRunAuthenticationQuery(db, { companyId, agentId, runId }).toSQL(); function contract(rows: unknown[][]) { return rows.map(([activeIdentityContextId, responsibleUserId, status, resultJson, contextSnapshot]) => ({ diff --git a/scripts/benchmark-agent-request-auth-cpu.ts b/scripts/benchmark-agent-request-auth-cpu.ts new file mode 100644 index 00000000000..82453ab5655 --- /dev/null +++ b/scripts/benchmark-agent-request-auth-cpu.ts @@ -0,0 +1,47 @@ +import { randomBytes, randomUUID } from "node:crypto"; +import { loadavg } from "node:os"; +process.env.PAPERCLIP_SECRETS_MASTER_KEY ??= randomBytes(32).toString("base64"); +process.env.PAPERCLIP_AGENT_JWT_SECRET ??= randomBytes(32).toString("base64"); +const { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns, startEmbeddedPostgresTestDatabase } = + await import("../packages/db/src/index.js"); +const { createLocalAgentJwt } = await import("../server/src/agent-auth-jwt.js"); +const { actorMiddleware } = await import("../server/src/middleware/auth.js"); + +const N = Number(process.env.N ?? 2000), PASSES = Number(process.env.PASSES ?? 7); +const temporary = await startEmbeddedPostgresTestDatabase("auth-request-cpu-"); +const db = createDb(temporary.connectionString); +try { + const [company] = await db.insert(companies).values({ name: "Auth", issuePrefix: "AUT" }).returning(); + const [agent] = await db.insert(agents).values({ companyId: company!.id, name: "A", adapterType: "process" }).returning(); + const userId = "user-1", runId = randomUUID(); + await db.insert(authUsers).values({ id: userId, name: "U", email: "u@example.test", createdAt: new Date(), updatedAt: new Date() }); + await db.insert(companyMemberships).values({ companyId: company!.id, principalType: "user", principalId: userId, status: "active", membershipRole: "owner" }); + await db.insert(heartbeatRuns).values({ id: runId, companyId: company!.id, agentId: agent!.id, status: "running", responsibleUserId: userId }); + const token = createLocalAgentJwt(agent!.id, company!.id, "process", runId, userId)!; + const middleware = actorMiddleware(db, { deploymentMode: "authenticated", resolveSession: async () => null }); + const headers: Record = { authorization: `Bearer ${token}`, "x-paperclip-run-id": runId }; + const once = () => new Promise((resolve, reject) => { + const req: any = { method: "GET", url: "/api/x", originalUrl: "/api/x", path: "/api/x", headers, + header: (name: string) => headers[name.toLowerCase()], get: (name: string) => headers[name.toLowerCase()] }; + const res: any = { once() {}, on() {}, status() { return res; }, json(body: unknown) { reject(new Error(JSON.stringify(body))); }, statusCode: 200 }; + middleware(req, res, (error?: unknown) => { + if (error) return reject(error); + if (req.actor?.type !== "agent" || req.actor.onBehalfOfMemberships?.length !== 1) return reject(new Error(`bad actor ${JSON.stringify(req.actor)}`)); + resolve(); + }); + }); + for (let i = 0; i < 500; i++) await once(); + const samples: number[] = []; + for (let p = 0; p < PASSES; p++) { + const c = process.cpuUsage(); + for (let i = 0; i < N; i++) await once(); + const u = process.cpuUsage(c); + samples.push((u.user + u.system) / N); + } + samples.sort((a, b) => a - b); + console.log(JSON.stringify({ cpuMicrosPerRequest: { median: +samples[Math.floor(PASSES / 2)]!.toFixed(1), min: +samples[0]!.toFixed(1), + max: +samples[PASSES - 1]!.toFixed(1), all: samples.map(s => +s.toFixed(1)) }, loadavg: loadavg().map(v => +v.toFixed(1)) })); +} finally { + await db.$client.end({ timeout: 1 }); + await temporary.cleanup(); +} diff --git a/server/src/__tests__/agent-auth-middleware.test.ts b/server/src/__tests__/agent-auth-middleware.test.ts index 91e7d966652..b94c6f82e5b 100644 --- a/server/src/__tests__/agent-auth-middleware.test.ts +++ b/server/src/__tests__/agent-auth-middleware.test.ts @@ -23,7 +23,9 @@ function createSelectChain(rowsForTable: (table: unknown) => unknown[]) { from(table: unknown) { return { where() { - return Promise.resolve(rowsForTable(table)); + return Object.assign(Promise.resolve(rowsForTable(table)), { + prepare: () => ({ execute: async () => rowsForTable(table) }), + }); }, }; }, diff --git a/server/src/__tests__/agent-auth-prepared-statements.test.ts b/server/src/__tests__/agent-auth-prepared-statements.test.ts new file mode 100644 index 00000000000..d1a9f5937f4 --- /dev/null +++ b/server/src/__tests__/agent-auth-prepared-statements.test.ts @@ -0,0 +1,93 @@ +import { randomUUID } from "node:crypto"; +import express from "express"; +import request from "supertest"; +import { fillPlaceholders, sql } from "drizzle-orm"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; +import { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns } from "@paperclipai/db"; +import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; +import { createLocalAgentJwt } from "../agent-auth-jwt.js"; +import { agentAuthenticationQuery, actorMiddleware, responsibleUserMembershipsQuery } from "../middleware/auth.js"; +import { agentRunAuthenticationQuery } from "../middleware/agent-run-authentication.js"; + +const support = await getEmbeddedPostgresTestSupport(); + +(support.supported ? describe : describe.skip)("agent request authentication statements", () => { + let database: Awaited>; + let db: ReturnType; + const companyId = randomUUID(), agentId = randomUUID(), runId = randomUUID(), userId = `user-${randomUUID()}`; + + beforeAll(async () => { + vi.stubEnv("PAPERCLIP_AGENT_JWT_SECRET", "agent-auth-prepared-statements-secret"); + database = await startEmbeddedPostgresTestDatabase("paperclip-agent-auth-prepared-"); + db = createDb(database.connectionString); + await db.insert(companies).values({ id: companyId, name: "Prepared authentication", issuePrefix: "PREP" }); + await db.insert(authUsers).values({ id: userId, name: "Owner", email: "owner@example.test", emailVerified: true, + createdAt: new Date(), updatedAt: new Date() }); + await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: userId, + status: "active", membershipRole: "owner" }); + await db.insert(agents).values({ id: agentId, companyId, name: "Worker", adapterType: "process", lifecycleHolds: [] }); + await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, status: "running", responsibleUserId: userId, + resultJson: { executionCancellation: { state: "none" }, freshContinuationSupersededAt: null }, + contextSnapshot: { conversationMode: true, issueId: randomUUID() } }); + }, 30_000); + + afterAll(async () => { + vi.unstubAllEnvs(); + await db?.$client.end({ timeout: 5 }); + await database?.cleanup(); + }, 60_000); + + const cases = () => [ + { + bound: agentAuthenticationQuery(db, agentId), + prepared: agentAuthenticationQuery(db, sql.placeholder("agentId")), + values: { agentId }, + }, + { + bound: agentRunAuthenticationQuery(db, { runId, companyId, agentId }), + prepared: agentRunAuthenticationQuery(db, { runId: sql.placeholder("runId"), companyId: sql.placeholder("companyId"), + agentId: sql.placeholder("agentId") }), + values: { runId, companyId, agentId }, + }, + { + bound: responsibleUserMembershipsQuery(db, { companyId, userId }), + prepared: responsibleUserMembershipsQuery(db, { companyId: sql.placeholder("companyId"), userId: sql.placeholder("userId") }), + values: { companyId, userId }, + }, + ]; + + it("sends the same statement and returns the same rows as the query builder", async () => { + for (const { bound, prepared, values } of cases()) { + const statement = prepared.prepare("fixture"); + const built = bound.toSQL(), placeholders = prepared.toSQL(); + expect(placeholders.sql).toBe(built.sql); + expect(fillPlaceholders(statement.getQuery().params, values)).toEqual(built.params); + const rows = await bound; + expect(rows).toHaveLength(1); + expect(await statement.execute(values)).toStrictEqual(rows); + } + }); + + it("builds the request authentication statements once per database client", async () => { + const app = express(); + app.use(actorMiddleware(db, { deploymentMode: "authenticated", resolveSession: async () => null })); + app.get("/actor", (req, res) => { res.json(req.actor); }); + const token = createLocalAgentJwt(agentId, companyId, "process", runId, userId)!; + const call = () => request(app).get("/actor").set("authorization", `Bearer ${token}`).set("x-paperclip-run-id", runId); + + const select = vi.spyOn(db, "select"); + const first = await call(); + expect(first.status).toBe(200); + expect(first.body).toMatchObject({ type: "agent", agentId, companyId, runId, onBehalfOfUserId: userId, + onBehalfOfMemberships: [{ companyId, membershipRole: "owner", status: "active" }] }); + select.mockClear(); + + for (let index = 0; index < 3; index += 1) { + const next = await call(); + expect(next.status).toBe(200); + expect(next.body).toEqual(first.body); + } + expect(select).not.toHaveBeenCalled(); + select.mockRestore(); + }); +}); diff --git a/server/src/__tests__/prepared-statements.test.ts b/server/src/__tests__/prepared-statements.test.ts index 688d8cd328f..4555b10e1dc 100644 --- a/server/src/__tests__/prepared-statements.test.ts +++ b/server/src/__tests__/prepared-statements.test.ts @@ -2,7 +2,7 @@ import { eq, fillPlaceholders, sql } from "drizzle-orm"; import { PgDialect, pgTable, timestamp, uuid } from "drizzle-orm/pg-core"; import { describe, expect, it, vi } from "vitest"; import type { Db } from "@paperclipai/db"; -import { columnPlaceholder, preparedStatements } from "../services/prepared-statements.js"; +import { columnPlaceholder, preparedStatement, preparedStatements } from "../services/prepared-statements.js"; describe("prepared statements", () => { it("prepares a shape one time for a client, and again for another client or shape", () => { @@ -18,6 +18,17 @@ describe("prepared statements", () => { expect(prepare.mock.calls).toEqual([[root, "first"], [root, "after"], [transaction, "first"]]); }); + it("prepares a single statement one time for each client", () => { + const prepare = vi.fn((db: Db) => ({ db })); + const statement = preparedStatement(prepare); + const root = {} as Db, other = {} as Db; + const first = statement(root); + expect(statement(root)).toBe(first); + expect(statement(other)).toEqual({ db: other }); + expect(statement(other)).not.toBe(first); + expect(prepare.mock.calls).toEqual([[root], [other]]); + }); + it("encodes a placeholder value with the column, as the query builder encodes a bound value", () => { const table = pgTable("prepared_statement_fixture", { id: uuid("id"), at: timestamp("at", { withTimezone: true }) }); const at = new Date("2026-11-12T10:00:00.123Z"); diff --git a/server/src/middleware/agent-run-authentication.ts b/server/src/middleware/agent-run-authentication.ts index 74eb4c7f42a..e0b312374b1 100644 --- a/server/src/middleware/agent-run-authentication.ts +++ b/server/src/middleware/agent-run-authentication.ts @@ -1,12 +1,12 @@ -import { and, eq, sql } from "drizzle-orm"; +import { and, eq, sql, type Placeholder } from "drizzle-orm"; import { heartbeatRuns, type Db } from "@paperclipai/db"; import { requestRunIdentityFields } from "../services/run-identity.js"; +import { preparedStatement } from "../services/prepared-statements.js"; -export function loadAgentRunAuthentication(db: Db, input: { - runId: string; - companyId: string; - agentId: string; -}) { +type Bound = Value | Placeholder; +export type AgentRunAuthenticationBinding = { runId: Bound; companyId: Bound; agentId: Bound }; + +export function agentRunAuthenticationQuery(db: Db, input: AgentRunAuthenticationBinding) { return db.select({ activeIdentityContextId: heartbeatRuns.activeIdentityContextId, responsibleUserId: heartbeatRuns.responsibleUserId, @@ -27,3 +27,17 @@ export function loadAgentRunAuthentication(db: Db, input: { eq(heartbeatRuns.agentId, input.agentId), )); } + +const agentRunAuthenticationStatement = preparedStatement(db => agentRunAuthenticationQuery(db, { + runId: sql.placeholder("runId"), + companyId: sql.placeholder("companyId"), + agentId: sql.placeholder("agentId"), +}).prepare("agent_run_authentication")); + +export function loadAgentRunAuthentication(db: Db, input: { + runId: string; + companyId: string; + agentId: string; +}) { + return agentRunAuthenticationStatement(db).execute(input); +} diff --git a/server/src/middleware/auth.ts b/server/src/middleware/auth.ts index 0d1c2725ae3..122188c49f7 100644 --- a/server/src/middleware/auth.ts +++ b/server/src/middleware/auth.ts @@ -2,7 +2,7 @@ import { notifyMuseContactVerification } from "../modules/external-agents/index. import { idleApiActivity } from "../services/idle-api-activity.js"; import { createHash, timingSafeEqual } from "node:crypto"; import type { Request, RequestHandler } from "express"; -import { and, eq, exists, isNull, sql } from "drizzle-orm"; +import { and, eq, exists, isNull, sql, type Placeholder } from "drizzle-orm"; import type { Db } from "@paperclipai/db"; import { activityLog, @@ -31,6 +31,7 @@ import { logger } from "./logger.js"; import { localAgentProcessBoundary, type LocalAgentProcessBoundary } from "./local-agent-process-boundary.js"; import { resolveRequestRunIdentity } from "../services/run-identity.js"; import { boardAuthService } from "../services/board-auth.js"; +import { preparedStatement } from "../services/prepared-statements.js"; import { retryIdempotentDatabaseOperation } from "../database-retry.js"; import { beginIdleTrackedWork } from "../services/task-admission.js"; import { notifyChatCompanyAuthorityChange } from "../services/chat-run-milestone-notifications.js"; @@ -76,11 +77,20 @@ const agentAuthenticationFields = { lifecycleHolds: agents.lifecycleHolds, }; -async function loadResponsibleUserMemberships( - db: Db, - input: { companyId: string; userId: string | null }, -) { - if (!input.userId) return []; +type Bound = Value | Placeholder; + +export function agentAuthenticationQuery(db: Db, agentId: Bound) { + return db.select(agentAuthenticationFields).from(agents).where(eq(agents.id, agentId)); +} + +const agentAuthenticationStatement = preparedStatement(db => + agentAuthenticationQuery(db, sql.placeholder("agentId")).prepare("agent_authentication")); + +function loadAgentAuthentication(db: Db, agentId: string) { + return agentAuthenticationStatement(db).execute({ agentId }).then((rows) => rows[0] ?? null); +} + +export function responsibleUserMembershipsQuery(db: Db, input: { companyId: Bound; userId: Bound }) { return db .select({ companyId: companyMemberships.companyId, @@ -99,6 +109,19 @@ async function loadResponsibleUserMemberships( ); } +const responsibleUserMembershipsStatement = preparedStatement(db => responsibleUserMembershipsQuery(db, { + companyId: sql.placeholder("companyId"), + userId: sql.placeholder("userId"), +}).prepare("responsible_user_memberships")); + +async function loadResponsibleUserMemberships( + db: Db, + input: { companyId: string; userId: string | null }, +) { + if (!input.userId) return []; + return responsibleUserMembershipsStatement(db).execute({ companyId: input.companyId, userId: input.userId }); +} + /** * The user's own active company memberships — the exact company scope a * locally authenticated session actor carries. Shared by the session path @@ -357,11 +380,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHa return; } - const agentRecord = await db - .select(agentAuthenticationFields) - .from(agents) - .where(eq(agents.id, claims.sub)) - .then((rows) => rows[0] ?? null); + const agentRecord = await loadAgentAuthentication(db, claims.sub); if (!agentRecord || agentRecord.companyId !== claims.company_id) { next(unauthorized("Agent record is missing or belongs to another company; obtain fresh credentials and retry")); @@ -478,11 +497,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHa .set({ lastUsedAt: new Date() }) .where(eq(agentApiKeys.id, key.id)); - const agentRecord = await db - .select(agentAuthenticationFields) - .from(agents) - .where(eq(agents.id, key.agentId)) - .then((rows) => rows[0] ?? null); + const agentRecord = await loadAgentAuthentication(db, key.agentId); if (!agentRecord || agentRecord.companyId !== key.companyId) { next(unauthorized("Agent record is missing or belongs to another company; obtain fresh credentials and retry")); diff --git a/server/src/services/prepared-statements.ts b/server/src/services/prepared-statements.ts index 19c8efc3117..1d6a2418d93 100644 --- a/server/src/services/prepared-statements.ts +++ b/server/src/services/prepared-statements.ts @@ -12,6 +12,15 @@ export function preparedStatements(prepare: (db }; } +export function preparedStatement(prepare: (db: Db) => Statement) { + const statements = new WeakMap(); + return (db: Db): Statement => { + let statement = statements.get(db); + if (!statement) statements.set(db, statement = prepare(db)); + return statement; + }; +} + export function columnPlaceholder(name: string, column: DriverValueEncoder): Param { return new Param(sql.placeholder(name), column); }