Files
PaperClipAI/server/src/__tests__/agent-auth-middleware.test.ts
T
DottaandClaude Opus 5.5 8adf0a463a perf(db): build the agent request authentication statements once per client (#21707)
## 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 <noreply@anthropic.com>
2026-11-14 20:43:39 -06:00

599 lines
22 KiB
TypeScript

import { createHash, createHmac, randomUUID } from "node:crypto";
import express from "express";
import request from "supertest";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
activityLog,
agentApiKeys,
agents,
boardApiKeys,
heartbeatRuns,
} from "@paperclipai/db";
import { actorMiddleware } from "../middleware/auth.js";
import { errorHandler } from "../middleware/error-handler.js";
import { createLocalAgentJwt } from "../agent-auth-jwt.js";
import { assertCompanyAccess } from "../routes/authz.js";
function hashToken(token: string) {
return createHash("sha256").update(token).digest("hex");
}
function createSelectChain(rowsForTable: (table: unknown) => unknown[]) {
return {
from(table: unknown) {
return {
where() {
return Object.assign(Promise.resolve(rowsForTable(table)), {
prepare: () => ({ execute: async () => rowsForTable(table) }),
});
},
};
},
};
}
function createDbState(input: {
agent: { id: string; companyId: string; status?: string; lifecycleHolds?: string[] };
agentKey?: { id: string; agentId: string; companyId: string; keyHash: string; responsibleUserId?: string | null };
run?: { id: string; companyId: string; agentId: string; responsibleUserId?: string | null;
status?: string; contextSnapshot?: Record<string, unknown>; resultJson?: Record<string, unknown> };
}) {
const activity: Array<Record<string, unknown>> = [];
const agentRow = {
id: input.agent.id,
companyId: input.agent.companyId,
status: input.agent.status ?? "active",
lifecycleHolds: input.agent.lifecycleHolds ?? [],
};
const keyRow = input.agentKey
? {
id: input.agentKey.id,
agentId: input.agentKey.agentId,
companyId: input.agentKey.companyId,
keyHash: input.agentKey.keyHash,
responsibleUserId: input.agentKey.responsibleUserId ?? null,
revokedAt: null,
scopeConfig: null,
}
: null;
const runRow = input.run
? {
id: input.run.id,
companyId: input.run.companyId,
agentId: input.run.agentId,
responsibleUserId: input.run.responsibleUserId ?? null,
status: input.run.status ?? "running",
contextSnapshot: input.run.contextSnapshot ?? {},
resultJson: input.run.resultJson ?? {},
}
: null;
const db = {
select: () =>
createSelectChain((table) => {
if (table === boardApiKeys) return [];
if (table === agentApiKeys) return keyRow ? [keyRow] : [];
if (table === agents) return [agentRow];
if (table === heartbeatRuns) return runRow ? [runRow] : [];
return [];
}),
update: () => ({
set() {
return {
where() {
return Promise.resolve([]);
},
};
},
}),
insert: (table: unknown) => ({
values(values: Record<string, unknown>) {
if (table === activityLog) activity.push(values);
return Promise.resolve([]);
},
}),
} as any;
return { db, activity };
}
function createApp(db: any, deploymentMode: "authenticated" | "local_trusted" = "authenticated") {
const app = express();
app.use(express.json());
app.use(
actorMiddleware(db, {
deploymentMode,
resolveSession: async () => null,
}),
);
app.get("/actor", (req, res) => {
res.json(req.actor);
});
app.post("/api/routine-triggers/public/:publicId/fire", (req, res) => {
res.json({ reachedWebhook: true, actorType: req.actor.type });
});
app.post("/mcp/gateways/:gatewayPublicId", (req, res) => {
res.json({ reachedGatewayProtocol: true, actorType: req.actor.type });
});
app.get("/companies/:companyId/protected", (req, res) => {
assertCompanyAccess(req, req.params.companyId);
res.json({ ok: true });
});
app.get("/companies/:companyId/issues/:issueId", (req, res) => {
assertCompanyAccess(req, req.params.companyId);
res.json({ id: req.params.issueId, readable: true });
});
app.patch("/companies/:companyId/issues/:issueId", (req, res) => {
assertCompanyAccess(req, req.params.companyId);
res.json({ id: req.params.issueId, writable: true });
});
app.use(errorHandler);
return app;
}
function craftAgentJwtWithoutResponsibleClaim(input: {
secret: string;
agentId: string;
companyId: string;
adapterType: string;
runId: string;
expiresInSeconds?: number;
}) {
const now = Math.floor(Date.now() / 1000);
const header = { alg: "HS256", typ: "JWT" };
const claims = {
sub: input.agentId,
company_id: input.companyId,
adapter_type: input.adapterType,
run_id: input.runId,
iat: now,
exp: now + (input.expiresInSeconds ?? 3600),
iss: "paperclip",
aud: "paperclip-api",
};
const headerB64 = Buffer.from(JSON.stringify(header), "utf8").toString("base64url");
const claimsB64 = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");
const signingInput = `${headerB64}.${claimsB64}`;
// Sign with the same per-instance, per-company key the server derives. The
// instance defaults to "default" (beforeEach clears PAPERCLIP_INSTANCE_ID),
// matching the live control plane this middleware test exercises. This helper
// only omits the responsible_user_id claim — it is not a cross-instance token.
const signingKey = createHmac("sha256", input.secret).update(`jwt:default:${input.companyId}`).digest("hex");
const signature = createHmac("sha256", signingKey).update(signingInput).digest("base64url");
return `${signingInput}.${signature}`;
}
describe("agent auth middleware", () => {
const originalSecret = process.env.PAPERCLIP_AGENT_JWT_SECRET;
const originalTtl = process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS;
const originalInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
beforeEach(() => {
process.env.PAPERCLIP_AGENT_JWT_SECRET = "auth-middleware-secret";
process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS = "3600";
// Pin the control-plane instance so mint/verify (and the hand-crafted
// legacy token helper) all derive keys under the "default" live instance.
delete process.env.PAPERCLIP_INSTANCE_ID;
});
afterEach(() => {
if (originalSecret === undefined) delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
else process.env.PAPERCLIP_AGENT_JWT_SECRET = originalSecret;
if (originalTtl === undefined) delete process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS;
else process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS = originalTtl;
if (originalInstanceId === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
else process.env.PAPERCLIP_INSTANCE_ID = originalInstanceId;
});
it.each([
{ status: "cancelled", conversationMode: false, requested: false },
{ status: "running", conversationMode: false, requested: true },
{ status: "cancelled", conversationMode: true, requested: false },
{ status: "running", conversationMode: true, requested: true },
])("revokes writes but preserves reads for a stopped run: %j", async ({ status, conversationMode, requested }) => {
const agentId = randomUUID();
const companyId = randomUUID();
const runId = randomUUID();
const { db } = createDbState({ agent: { id: agentId, companyId }, run: {
id: runId, companyId, agentId, status, contextSnapshot: { conversationMode },
resultJson: requested ? { executionCancellation: { state: "requested" } } : {},
} });
const token = createLocalAgentJwt(agentId, companyId, "grok_local", runId, null);
const client = createApp(db);
const endpoint = `/companies/${companyId}/issues/${randomUUID()}`;
const write = await request(client).patch(endpoint).set("Authorization", `Bearer ${token}`).send({ status: "done" });
expect(write.status).toBe(403);
expect(write.body.code).toBe(conversationMode ? "conversation_turn_cancelled" : "agent_run_cancelled");
const read = await request(client).get(endpoint).set("Authorization", `Bearer ${token}`);
expect(read.status).toBe(200);
expect(read.body.readable).toBe(true);
});
it("keeps header-less local requests as the implicit board actor with their run id", async () => {
const runId = randomUUID();
const { db } = createDbState({ agent: { id: randomUUID(), companyId: randomUUID() } });
const res = await request(createApp(db, "local_trusted"))
.get("/actor")
.set("X-Paperclip-Run-Id", runId);
expect(res.status).toBe(200);
expect(res.body).toMatchObject({ type: "board", userId: "local-board", runId });
});
it.each([
["empty bearer token", "Bearer ", "Empty bearer token"],
["unverified token", "Bearer not-a-token", "Agent token did not verify"],
])("rejects %s instead of retaining the implicit local-board actor", async (_label, authorization, error) => {
const { db } = createDbState({ agent: { id: randomUUID(), companyId: randomUUID() } });
let commentWrites = 0;
const app = createApp(db, "local_trusted");
app.post("/comments", (_req, res) => {
commentWrites += 1;
res.status(201).json({ ok: true });
});
const res = await request(app).post("/comments").set("Authorization", authorization).send({ body: "reply" });
expect(res.status).toBe(401);
expect(res.body.error).toContain(error);
expect(commentWrites).toBe(0);
});
it.each(["authenticated", "local_trusted"] as const)(
"leaves webhook authentication to the trigger in %s mode",
async (deploymentMode) => {
const { db } = createDbState({ agent: { id: randomUUID(), companyId: randomUUID() } });
const res = await request(createApp(db, deploymentMode))
.post(`/api/routine-triggers/public/${"a".repeat(24)}/fire`)
.set("Authorization", "Bearer routine-secret")
.send({ event: "created" });
expect(res.status).toBe(200);
expect(res.body).toEqual({ reachedWebhook: true, actorType: "none" });
},
);
it.each([
`/api/routine-triggers/public/${"a".repeat(24)}/rotate-secret`,
"/api/routine-triggers/public/not-a-public-id/fire",
`/api/routine-triggers/public/${"a".repeat(24)}/fire/extra`,
])("does not bypass actor authentication for %s", async (path) => {
const { db } = createDbState({ agent: { id: randomUUID(), companyId: randomUUID() } });
const res = await request(createApp(db)).post(path).set("Authorization", "Bearer routine-secret");
expect(res.status).toBe(401);
});
it("leaves public MCP gateway bearers for the gateway protocol to validate", async () => {
const { db } = createDbState({ agent: { id: randomUUID(), companyId: randomUUID() } });
const publicId = `gw_${"a".repeat(32)}`;
const res = await request(createApp(db, "local_trusted"))
.post(`/mcp/gateways/${publicId}`)
.set("Authorization", "Bearer pcgw_runtime_token")
.send({ jsonrpc: "2.0", id: 1, method: "initialize" });
expect(res.status).toBe(200);
expect(res.body).toMatchObject({ reachedGatewayProtocol: true });
});
it("does not bypass actor authentication for lookalike MCP gateway paths", async () => {
const { db } = createDbState({ agent: { id: randomUUID(), companyId: randomUUID() } });
const res = await request(createApp(db, "local_trusted"))
.post("/mcp/gateways/not-a-public-id")
.set("Authorization", "Bearer pcgw_runtime_token")
.send({ jsonrpc: "2.0", id: 1, method: "initialize" });
expect(res.status).toBe(401);
expect(res.body.error).toContain("Agent token did not verify");
});
it.each([
["terminated", "Agent is terminated"],
["pending_approval", "Agent is pending approval"],
])("rejects a %s agent JWT instead of retaining local-board", async (status, error) => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const { db } = createDbState({ agent: { id: agentId, companyId, status } });
const token = createLocalAgentJwt(agentId, companyId, "codex_local", runId, "user-1");
const res = await request(createApp(db, "local_trusted"))
.get("/actor")
.set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(401);
expect(res.body.error).toContain(error);
});
it.each(["key", "jwt"])("rejects unfinished setup authentication with a %s", async kind => {
const companyId = randomUUID();
const agentId = randomUUID();
const token = kind === "jwt" ? createLocalAgentJwt(agentId, companyId, "codex_local", randomUUID(), "user-1")! : "pcp_setup-test-token";
const { db } = createDbState({
agent: { id: agentId, companyId, status: "paused", lifecycleHolds: ["setup"] },
...(kind === "key" ? { agentKey: { id: randomUUID(), agentId, companyId, keyHash: hashToken(token), responsibleUserId: "user-1" } } : {}),
});
const res = await request(createApp(db, "local_trusted")).get("/actor").set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(401);
expect(res.body.error).toContain("setup is incomplete");
});
it("rejects an agent JWT when the agent record belongs to another company", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const { db } = createDbState({ agent: { id: agentId, companyId: randomUUID() } });
const token = createLocalAgentJwt(agentId, companyId, "codex_local", runId, "user-1");
const res = await request(createApp(db, "local_trusted"))
.get("/actor")
.set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(401);
expect(res.body.error).toContain("missing or belongs to another company");
});
it("reports an expired agent JWT specifically", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const { db } = createDbState({ agent: { id: agentId, companyId } });
const token = craftAgentJwtWithoutResponsibleClaim({
secret: process.env.PAPERCLIP_AGENT_JWT_SECRET!,
agentId,
companyId,
adapterType: "codex_local",
runId,
expiresInSeconds: -1,
});
const res = await request(createApp(db, "local_trusted"))
.get("/actor")
.set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(401);
expect(res.body.error).toContain("Expired agent token");
});
it("uses the signed responsible_user_id claim and keeps the signed run id authoritative", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const { db } = createDbState({
agent: { id: agentId, companyId },
run: { id: runId, companyId, agentId, responsibleUserId: "user-row" },
});
const token = createLocalAgentJwt(agentId, companyId, "codex_local", runId, "user-claim");
const res = await request(createApp(db))
.get("/actor")
.set("Authorization", `Bearer ${token}`)
.set("X-Paperclip-Run-Id", runId);
expect(res.status).toBe(200);
expect(res.body).toMatchObject({
type: "agent",
agentId,
companyId,
runId,
onBehalfOfUserId: "user-claim",
source: "agent_jwt",
});
});
it("preserves signed skill_test JWT scope on the request actor", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const issueId = randomUUID();
const { db } = createDbState({
agent: { id: agentId, companyId },
run: { id: runId, companyId, agentId, responsibleUserId: "user-claim" },
});
const token = createLocalAgentJwt(agentId, companyId, "codex_local", runId, "user-claim", {
kind: "skill_test",
issueId,
});
const res = await request(createApp(db))
.get("/actor")
.set("Authorization", `Bearer ${token}`)
.set("X-Paperclip-Run-Id", runId);
expect(res.status).toBe(200);
expect(res.body).toMatchObject({
type: "agent",
agentId,
companyId,
keyScope: { kind: "skill_test", issueId },
source: "agent_jwt",
});
});
it("rejects mismatched run headers for agent JWTs and audits the spoof attempt", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const spoofedRunId = randomUUID();
const { db, activity } = createDbState({
agent: { id: agentId, companyId },
run: { id: runId, companyId, agentId, responsibleUserId: "user-claim" },
});
const token = createLocalAgentJwt(agentId, companyId, "codex_local", runId, "user-claim");
const res = await request(createApp(db))
.get("/actor")
.set("Authorization", `Bearer ${token}`)
.set("X-Paperclip-Run-Id", spoofedRunId);
expect(res.status).toBe(422);
expect(res.body.code).toBe("agent_jwt_run_id_mismatch");
expect(activity).toHaveLength(1);
expect(activity[0]).toMatchObject({
companyId,
actorType: "agent",
actorId: agentId,
action: "auth.agent_jwt_run_header_mismatch",
entityType: "heartbeat_run",
entityId: runId,
runId,
details: { claimRunId: runId, headerRunId: spoofedRunId },
});
});
it("audits a run header mismatch even when the claimed run does not exist", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const claimedRunId = randomUUID();
const spoofedRunId = randomUUID();
const { db, activity } = createDbState({
agent: { id: agentId, companyId },
});
const token = createLocalAgentJwt(agentId, companyId, "codex_local", claimedRunId, "user-claim");
const res = await request(createApp(db))
.get("/actor")
.set("Authorization", `Bearer ${token}`)
.set("X-Paperclip-Run-Id", spoofedRunId);
expect(res.status).toBe(422);
expect(res.body.code).toBe("agent_jwt_run_id_mismatch");
expect(activity).toHaveLength(1);
expect(activity[0]).toMatchObject({
companyId,
actorType: "agent",
actorId: agentId,
action: "auth.agent_jwt_run_header_mismatch",
entityType: "heartbeat_run",
entityId: claimedRunId,
details: { claimRunId: claimedRunId, headerRunId: spoofedRunId },
});
// run_id carries a real FK to heartbeat_runs; a nonexistent claim must not
// be written into it or the whole audit row is lost to the FK violation.
expect(activity[0].runId).toBeUndefined();
});
it("falls back to the run row responsible user for legacy claim-less agent JWTs", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const { db } = createDbState({
agent: { id: agentId, companyId },
run: { id: runId, companyId, agentId, responsibleUserId: "user-legacy" },
});
const token = craftAgentJwtWithoutResponsibleClaim({
secret: process.env.PAPERCLIP_AGENT_JWT_SECRET!,
agentId,
companyId,
adapterType: "codex_local",
runId,
});
const res = await request(createApp(db))
.get("/actor")
.set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(200);
expect(res.body).toMatchObject({
type: "agent",
runId,
onBehalfOfUserId: "user-legacy",
source: "agent_jwt",
});
});
it("rejects fork-minted run JWTs before issue reads or writes reach live issue data", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const runId = randomUUID();
const issueId = randomUUID();
const { db } = createDbState({
agent: { id: agentId, companyId },
run: { id: runId, companyId, agentId, responsibleUserId: "user-claim" },
});
process.env.PAPERCLIP_INSTANCE_ID = "pap-12899-worktree";
const forkToken = createLocalAgentJwt(agentId, companyId, "codex_local", runId, "user-claim");
expect(forkToken).not.toBeNull();
process.env.PAPERCLIP_INSTANCE_ID = "default";
const app = createApp(db);
const readRes = await request(app)
.get(`/companies/${companyId}/issues/${issueId}`)
.set("Authorization", `Bearer ${forkToken}`)
.set("X-Paperclip-Run-Id", runId);
const writeRes = await request(app)
.patch(`/companies/${companyId}/issues/${issueId}`)
.set("Authorization", `Bearer ${forkToken}`)
.set("X-Paperclip-Run-Id", runId)
.send({ title: "should not write" });
expect(readRes.status).toBe(401);
expect(writeRes.status).toBe(401);
});
it("populates agent-key actors from the key responsible user binding", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const token = "pcp_test_agent_key";
const { db } = createDbState({
agent: { id: agentId, companyId },
agentKey: {
id: randomUUID(),
agentId,
companyId,
keyHash: hashToken(token),
responsibleUserId: "user-key",
},
});
const res = await request(createApp(db))
.get("/actor")
.set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(200);
expect(res.body).toMatchObject({
type: "agent",
agentId,
companyId,
onBehalfOfUserId: "user-key",
source: "agent_key",
});
});
it("rejects agent keys that lack a responsible user binding and audits the denial", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const keyId = randomUUID();
const token = "pcp_test_agent_key_without_user";
const { db, activity } = createDbState({
agent: { id: agentId, companyId },
agentKey: {
id: keyId,
agentId,
companyId,
keyHash: hashToken(token),
responsibleUserId: null,
},
});
const res = await request(createApp(db))
.get(`/companies/${companyId}/protected`)
.set("Authorization", `Bearer ${token}`);
expect(res.status).toBe(403);
expect(res.body.code).toBe("RESPONSIBLE_USER_UNAVAILABLE");
expect(activity).toHaveLength(1);
expect(activity[0]).toMatchObject({
companyId,
actorType: "agent",
actorId: agentId,
action: "auth.agent_key_missing_responsible_user",
entityType: "agent_api_key",
entityId: keyId,
details: { method: "GET", url: `/companies/${companyId}/protected` },
});
});
});