The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
[codex] Isolate run JWTs by control-plane instance (#9162)
Dotta57a7da81ee43
diff --git a/server/src/__tests__/agent-auth-jwt.test.ts b/server/src/__tests__/agent-auth-jwt.test.tsindex e084b45b21..c5fe3f8b95 100644--- a/server/src/__tests__/agent-auth-jwt.test.ts+++ b/server/src/__tests__/agent-auth-jwt.test.ts@@ -9,6 +9,7 @@ describe("agent local JWT", () => {const issuerEnv = "PAPERCLIP_AGENT_JWT_ISSUER";const audienceEnv = "PAPERCLIP_AGENT_JWT_AUDIENCE";const disableLegacyFallbackEnv = "PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK";+ const instanceIdEnv = "PAPERCLIP_INSTANCE_ID";const originalEnv = {secret: process.env[secretEnv],@@ -17,6 +18,7 @@ describe("agent local JWT", () => {issuer: process.env[issuerEnv],audience: process.env[audienceEnv],disableLegacyFallback: process.env[disableLegacyFallbackEnv],+ instanceId: process.env[instanceIdEnv],};beforeEach(() => {@@ -26,6 +28,7 @@ describe("agent local JWT", () => {delete process.env[issuerEnv];delete process.env[audienceEnv];delete process.env[disableLegacyFallbackEnv];+ delete process.env[instanceIdEnv];vi.useFakeTimers();});@@ -43,6 +46,8 @@ describe("agent local JWT", () => {else process.env[audienceEnv] = originalEnv.audience;if (originalEnv.disableLegacyFallback === undefined) delete process.env[disableLegacyFallbackEnv];else process.env[disableLegacyFallbackEnv] = originalEnv.disableLegacyFallback;+ if (originalEnv.instanceId === undefined) delete process.env[instanceIdEnv];+ else process.env[instanceIdEnv] = originalEnv.instanceId;});it("creates and verifies a token", () => {@@ -160,6 +165,82 @@ describe("agent local JWT", () => {});});+ // --- Instance isolation (PAP-12899) ---------------------------------------+ // A worktree/fork control-plane instance runs under a distinct+ // PAPERCLIP_INSTANCE_ID but deliberately shares PAPERCLIP_AGENT_JWT_SECRET+ // with its source instance (provisioning copies the secret). Before this+ // change, a fork-minted run JWT validated successfully against the live plane+ // (reads worked; writes then failed on missing heartbeat_runs FK rows). These+ // tests pin the boundary that keeps fork tokens out of the live plane.++ it("stamps the minting instance id into the token claims", () => {+ process.env[instanceIdEnv] = "default";+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ const token = createLocalAgentJwt("agent-1", "company-1", "claude_local", "run-1");+ const claims = verifyLocalAgentJwt(token!);+ expect(claims?.instance_id).toBe("default");+ });++ it("rejects a fork/worktree-minted token on the live control plane", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));++ // Mint on a worktree/fork instance (distinct instance id, SAME secret).+ process.env[instanceIdEnv] = "pap-12899-worktree";+ const forkToken = createLocalAgentJwt("agent-1", "company-1", "claude_local", "run-1");+ expect(forkToken).not.toBeNull();+ // Sanity: it verifies on the instance that minted it.+ expect(verifyLocalAgentJwt(forkToken!)?.company_id).toBe("company-1");++ // Now switch to the live control plane (same shared secret, "default"+ // instance) and confirm the fork token no longer authenticates — neither+ // its instance-scoped signature nor the legacy master-secret fallback+ // matches, so reads and writes are both refused.+ process.env[instanceIdEnv] = "default";+ expect(verifyLocalAgentJwt(forkToken!)).toBeNull();+ });++ it("keeps live-plane heartbeat tokens authenticating across mint/verify", () => {+ process.env[instanceIdEnv] = "default";+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ const token = createLocalAgentJwt("agent-1", "company-1", "claude_local", "run-1", "user-1");+ const claims = verifyLocalAgentJwt(token!);+ expect(claims).toMatchObject({+ sub: "agent-1",+ company_id: "company-1",+ run_id: "run-1",+ instance_id: "default",+ });+ });++ it("rejects a token whose instance_id claim is forged to match the live plane", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));++ // Mint a fork token, then tamper the instance_id claim to impersonate the+ // live "default" instance. The signature was bound to the fork instance's+ // derived key, so re-encoding the claim cannot make it validate on the+ // live plane — the claim check is defense-in-depth, the key is the boundary.+ process.env[instanceIdEnv] = "pap-12899-worktree";+ const forkToken = createLocalAgentJwt("agent-1", "company-1", "claude_local", "run-1");+ const [headerB64, claimsB64, signature] = forkToken!.split(".");+ const claims = JSON.parse(Buffer.from(claimsB64, "base64url").toString("utf8"));+ claims.instance_id = "default";+ const tamperedClaimsB64 = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");+ const tampered = `${headerB64}.${tamperedClaimsB64}.${signature}`;++ process.env[instanceIdEnv] = "default";+ expect(verifyLocalAgentJwt(tampered)).toBeNull();+ });++ it("still rejects the master-secret legacy fallback once it is disabled (full instance isolation)", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ process.env[disableLegacyFallbackEnv] = "true";+ process.env[instanceIdEnv] = "default";+ // The legacy fallback signs with the raw shared secret and is therefore+ // instance-agnostic; disabling it closes that residual cross-instance hole.+ const legacyToken = craftLegacyMasterSecretToken(process.env[secretEnv]!, "company-1");+ expect(verifyLocalAgentJwt(legacyToken)).toBeNull();+ });+it("defaults TTL to 1h when PAPERCLIP_AGENT_JWT_TTL_SECONDS is unset", () => {delete process.env[ttlEnv];vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));diff --git a/server/src/__tests__/agent-auth-middleware.test.ts b/server/src/__tests__/agent-auth-middleware.test.tsindex fa2763518e..54c4fe150b 100644--- a/server/src/__tests__/agent-auth-middleware.test.ts+++ b/server/src/__tests__/agent-auth-middleware.test.ts@@ -106,6 +106,14 @@ function createApp(db: any) {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;}@@ -132,7 +140,11 @@ function craftAgentJwtWithoutResponsibleClaim(input: {const headerB64 = Buffer.from(JSON.stringify(header), "utf8").toString("base64url");const claimsB64 = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");const signingInput = `${headerB64}.${claimsB64}`;- const signingKey = createHmac("sha256", input.secret).update(`jwt:${input.companyId}`).digest("hex");+ // 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}`;}@@ -140,10 +152,14 @@ function craftAgentJwtWithoutResponsibleClaim(input: {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(() => {@@ -151,6 +167,8 @@ describe("agent auth middleware", () => {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("uses the signed responsible_user_id claim and keeps the signed run id authoritative", async () => {@@ -239,6 +257,36 @@ describe("agent auth middleware", () => {});});+ 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();diff --git a/server/src/agent-auth-jwt.ts b/server/src/agent-auth-jwt.tsindex 7b38119435..4cb25e97ab 100644--- a/server/src/agent-auth-jwt.ts+++ b/server/src/agent-auth-jwt.ts@@ -1,4 +1,5 @@import { createHmac, timingSafeEqual } from "node:crypto";+import { resolvePaperclipInstanceId } from "./home-paths.js";interface JwtHeader {alg: string;@@ -15,6 +16,7 @@ export interface LocalAgentJwtClaims {exp: number;iss?: string;aud?: string;+ instance_id?: string;jti?: string;}@@ -41,24 +43,44 @@ function jwtConfig() {ttlSeconds: parseNumber(process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS, 60 * 60),issuer: process.env.PAPERCLIP_AGENT_JWT_ISSUER ?? "paperclip",audience: process.env.PAPERCLIP_AGENT_JWT_AUDIENCE ?? "paperclip-api",+ // The control-plane instance this process belongs to. The live plane runs as+ // "default"; every worktree/fork instance gets a distinct id (its worktree+ // name) even though it deliberately shares PAPERCLIP_AGENT_JWT_SECRET with+ // the source instance. Folding this into the signing-key derivation is what+ // prevents a fork-minted token from authenticating against the live plane.+ instanceId: resolvePaperclipInstanceId(),disableLegacyFallback: parseBooleanEnv(process.env.PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK),};}/**- * Derive a per-company signing key from the master JWT secret and a companyId.+ * Derive a per-instance, per-company signing key from the master JWT secret,+ * the control-plane instanceId, and a companyId.*- * In a multi-tenant deployment this ensures that a JWT signed for company A- * cannot be reused to authenticate as an agent in company B, even if the raw- * token leaks. The instance-wide master secret is never used to sign new- * tokens — it is retained only as a verification fallback so that tokens- * issued before this change continue to validate.+ * Two isolation properties fall out of this derivation:+ * - Per-company: a JWT signed for company A cannot be reused to authenticate+ * as an agent in company B, even if the raw token leaks.+ * - Per-instance: a JWT minted by a worktree/fork control-plane instance+ * cannot authenticate against the live plane, even though forks+ * deliberately share the same master secret (it is copied into worktree+ * envs by provisioning). The live plane derives its key from its own+ * instanceId ("default"), so a fork token — signed under the fork's+ * instanceId — never matches. See PAP-12896 for the incident this closes.+ *+ * The instance-wide master secret is never used to sign new tokens — it is+ * retained only as a verification fallback so that tokens issued before this+ * change continue to validate. NOTE: that legacy fallback is instance-agnostic+ * (it signs with the raw shared secret), so complete cryptographic instance+ * isolation additionally requires disabling it once outstanding legacy tokens+ * have expired (set PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK=true). Normal+ * fork-minted run tokens are already rejected without that step because they+ * are signed with the derived key, not the raw master secret.** The derivation domain-separates with the `jwt:` prefix so the same master* secret can safely be reused for other HMAC purposes without key reuse.*/-function deriveCompanySigningKey(masterSecret: string, companyId: string): string {- return createHmac("sha256", masterSecret).update(`jwt:${companyId}`).digest("hex");+function deriveCompanySigningKey(masterSecret: string, companyId: string, instanceId: string): string {+ return createHmac("sha256", masterSecret).update(`jwt:${instanceId}:${companyId}`).digest("hex");}function base64UrlEncode(value: string) {@@ -110,6 +132,7 @@ export function createLocalAgentJwt(exp: now + config.ttlSeconds,iss: config.issuer,aud: config.audience,+ instance_id: config.instanceId,};const header = {@@ -118,9 +141,10 @@ export function createLocalAgentJwt(};const signingInput = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(claims))}`;- // Sign with the per-company derived key so a leaked token cannot be reused- // across tenants.- const signingKey = deriveCompanySigningKey(config.secret, companyId);+ // Sign with the per-instance, per-company derived key so a leaked token+ // cannot be reused across tenants and a fork-minted token cannot authenticate+ // against a different control-plane instance.+ const signingKey = deriveCompanySigningKey(config.secret, companyId, config.instanceId);const signature = signPayload(signingKey, signingInput);return `${signingInput}.${signature}`;@@ -145,18 +169,24 @@ export function verifyLocalAgentJwt(token: string): LocalAgentJwtClaims | null {if (!claimedCompanyId) return null;const signingInput = `${headerB64}.${claimsB64}`;- // Try the per-company derived key first (current tokens). Fall back to the- // raw master secret so tokens issued before per-company derivation existed- // continue to verify — this preserves backward compatibility for any- // outstanding tokens (TTL bounds the legacy window naturally).+ // Try the per-instance, per-company derived key first (current tokens),+ // deriving under THIS control plane's own instanceId. A token minted by a+ // worktree/fork instance was signed under a different instanceId, so it will+ // not match here — that is the boundary that keeps fork tokens out of the+ // live plane (PAP-12896/PAP-12899). Fall back to the raw master secret so+ // tokens issued before per-company derivation existed continue to verify —+ // this preserves backward compatibility for any outstanding tokens (TTL+ // bounds the legacy window naturally).//// Operators should set `PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK=true`// approximately one JWT TTL (~1h by default, see PAPERCLIP_AGENT_JWT_TTL_SECONDS)// after deploying per-company signing. Once set, the master-secret fallback- // is disabled and only tokens validating under the per-company derived key- // are accepted — closing the window in which a leaked master secret could- // be used to forge tokens with arbitrary future `exp` values for any tenant.- const perCompanyKey = deriveCompanySigningKey(config.secret, claimedCompanyId);+ // is disabled and only tokens validating under the per-instance/per-company+ // derived key are accepted — closing the window in which a leaked master+ // secret could be used to forge tokens with arbitrary future `exp` values for+ // any tenant, and completing cryptographic isolation between control-plane+ // instances (the raw-secret fallback is instance-agnostic).+ const perCompanyKey = deriveCompanySigningKey(config.secret, claimedCompanyId, config.instanceId);const perCompanySig = signPayload(perCompanyKey, signingInput);let signatureOk = safeCompare(signature, perCompanySig);if (!signatureOk && !config.disableLegacyFallback) {@@ -186,6 +216,15 @@ export function verifyLocalAgentJwt(token: string): LocalAgentJwtClaims | null {if (issuer && issuer !== config.issuer) return null;if (audience && audience !== config.audience) return null;+ // Enforce the minting instance when the claim is present. The instance-scoped+ // signing key above is the real cryptographic boundary; this claim check is+ // defense-in-depth that yields a clean, cheap rejection (and, once legacy+ // tokens have aged out, guards the master-secret fallback path too). Legacy+ // tokens minted before this claim existed omit it and are still accepted, so+ // enforcement is conditional — matching how iss/aud are handled above.+ const instanceClaim = typeof claims.instance_id === "string" ? claims.instance_id : undefined;+ if (instanceClaim && instanceClaim !== config.instanceId) return null;+return {sub,company_id: companyId,@@ -196,6 +235,7 @@ export function verifyLocalAgentJwt(token: string): LocalAgentJwtClaims | null {exp,...(issuer ? { iss: issuer } : {}),...(audience ? { aud: audience } : {}),+ ...(instanceClaim ? { instance_id: instanceClaim } : {}),jti: typeof claims.jti === "string" ? claims.jti : undefined,};}