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
feat(security): per-company JWT signing keys for multi-tenant isolation (#5864)
Jannes Stubbemann70357b961fcd
diff --git a/server/src/__tests__/agent-auth-jwt.test.ts b/server/src/__tests__/agent-auth-jwt.test.tsindex c2505b29c3..5744be362c 100644--- a/server/src/__tests__/agent-auth-jwt.test.ts+++ b/server/src/__tests__/agent-auth-jwt.test.ts@@ -1,3 +1,4 @@+import { createHmac } from "node:crypto";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { createLocalAgentJwt, verifyLocalAgentJwt } from "../agent-auth-jwt.js";@@ -7,6 +8,7 @@ describe("agent local JWT", () => {const ttlEnv = "PAPERCLIP_AGENT_JWT_TTL_SECONDS";const issuerEnv = "PAPERCLIP_AGENT_JWT_ISSUER";const audienceEnv = "PAPERCLIP_AGENT_JWT_AUDIENCE";+ const disableLegacyFallbackEnv = "PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK";const originalEnv = {secret: process.env[secretEnv],@@ -14,6 +16,7 @@ describe("agent local JWT", () => {ttl: process.env[ttlEnv],issuer: process.env[issuerEnv],audience: process.env[audienceEnv],+ disableLegacyFallback: process.env[disableLegacyFallbackEnv],};beforeEach(() => {@@ -22,6 +25,7 @@ describe("agent local JWT", () => {process.env[ttlEnv] = "3600";delete process.env[issuerEnv];delete process.env[audienceEnv];+ delete process.env[disableLegacyFallbackEnv];vi.useFakeTimers();});@@ -37,6 +41,8 @@ describe("agent local JWT", () => {else process.env[issuerEnv] = originalEnv.issuer;if (originalEnv.audience === undefined) delete process.env[audienceEnv];else process.env[audienceEnv] = originalEnv.audience;+ if (originalEnv.disableLegacyFallback === undefined) delete process.env[disableLegacyFallbackEnv];+ else process.env[disableLegacyFallbackEnv] = originalEnv.disableLegacyFallback;});it("creates and verifies a token", () => {@@ -97,4 +103,119 @@ describe("agent local JWT", () => {process.env[audienceEnv] = "paperclip-api";expect(verifyLocalAgentJwt(token!)).toBeNull();});++ it("does not verify a token across companies (per-company isolation)", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ const tokenA = createLocalAgentJwt("agent-1", "company-A", "claude_local", "run-1");+ expect(tokenA).not.toBeNull();++ // A token whose body claims company-A must verify successfully under its+ // own company-A derived key.+ expect(verifyLocalAgentJwt(tokenA!)?.company_id).toBe("company-A");++ // Tamper: forge a token by copying tokenA's header+signature and swapping+ // the claim's company_id to company-B. The signature was bound to the+ // company-A derived key over the original claims; once we re-encode with a+ // different company_id (or rebind to company-B's key) verification must+ // fail because the signature is over the original signing input.+ const [headerB64, claimsB64, signature] = tokenA!.split(".");+ const claims = JSON.parse(Buffer.from(claimsB64, "base64url").toString("utf8"));+ claims.company_id = "company-B";+ const tamperedClaimsB64 = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");+ const tampered = `${headerB64}.${tamperedClaimsB64}.${signature}`;+ expect(verifyLocalAgentJwt(tampered)).toBeNull();+ });++ it("accepts legacy tokens signed with the master secret (backward compat)", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ const masterSecret = process.env[secretEnv]!;++ // Hand-craft a token signed directly with the master secret, simulating a+ // JWT issued before per-company derivation existed.+ const now = Math.floor(Date.now() / 1000);+ const header = { alg: "HS256", typ: "JWT" };+ const claims = {+ sub: "agent-legacy",+ company_id: "company-legacy",+ adapter_type: "claude_local",+ run_id: "run-legacy",+ iat: now,+ exp: now + 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}`;+ const legacySig = createHmac("sha256", masterSecret).update(signingInput).digest("base64url");+ const legacyToken = `${signingInput}.${legacySig}`;++ const verified = verifyLocalAgentJwt(legacyToken);+ expect(verified).toMatchObject({+ sub: "agent-legacy",+ company_id: "company-legacy",+ adapter_type: "claude_local",+ run_id: "run-legacy",+ });+ });++ 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"));+ const token = createLocalAgentJwt("agent-1", "company-1", "claude_local", "run-1");+ const claims = verifyLocalAgentJwt(token!);+ expect(claims).not.toBeNull();+ expect(claims!.exp - claims!.iat).toBe(60 * 60);+ });++ // Helper: hand-craft a token signed with the raw master secret (legacy path).+ function craftLegacyMasterSecretToken(masterSecret: string, companyId: string) {+ const now = Math.floor(Date.now() / 1000);+ const header = { alg: "HS256", typ: "JWT" };+ const claims = {+ sub: "agent-legacy",+ company_id: companyId,+ adapter_type: "claude_local",+ run_id: "run-legacy",+ iat: now,+ exp: now + 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}`;+ const legacySig = createHmac("sha256", masterSecret).update(signingInput).digest("base64url");+ return `${signingInput}.${legacySig}`;+ }++ it("accepts master-secret-signed tokens when PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK is unset", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ delete process.env[disableLegacyFallbackEnv];+ const legacyToken = craftLegacyMasterSecretToken(process.env[secretEnv]!, "company-legacy");+ const verified = verifyLocalAgentJwt(legacyToken);+ expect(verified).not.toBeNull();+ expect(verified!.company_id).toBe("company-legacy");+ });++ it("rejects master-secret-signed tokens when PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK is enabled", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ process.env[disableLegacyFallbackEnv] = "true";+ const legacyToken = craftLegacyMasterSecretToken(process.env[secretEnv]!, "company-legacy");+ expect(verifyLocalAgentJwt(legacyToken)).toBeNull();+ });++ it("still verifies per-company-signed tokens when PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK is enabled", () => {+ vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));+ process.env[disableLegacyFallbackEnv] = "true";+ const token = createLocalAgentJwt("agent-1", "company-1", "claude_local", "run-1");+ expect(token).not.toBeNull();+ const verified = verifyLocalAgentJwt(token!);+ expect(verified).toMatchObject({+ sub: "agent-1",+ company_id: "company-1",+ adapter_type: "claude_local",+ run_id: "run-1",+ });+ });});diff --git a/server/src/agent-auth-jwt.ts b/server/src/agent-auth-jwt.tsindex 728461b090..6ffae2d9d3 100644--- a/server/src/agent-auth-jwt.ts+++ b/server/src/agent-auth-jwt.ts@@ -25,18 +25,41 @@ function parseNumber(value: string | undefined, fallback: number) {return Math.floor(parsed);}+function parseBooleanEnv(value: string | undefined): boolean {+ if (!value) return false;+ const normalized = value.trim().toLowerCase();+ return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";+}+function jwtConfig() {const secret = process.env.PAPERCLIP_AGENT_JWT_SECRET?.trim() || process.env.BETTER_AUTH_SECRET?.trim();if (!secret) return null;return {secret,- ttlSeconds: parseNumber(process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS, 60 * 60 * 48),+ 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",+ disableLegacyFallback: parseBooleanEnv(process.env.PAPERCLIP_AGENT_JWT_DISABLE_LEGACY_FALLBACK),};}+/**+ * Derive a per-company signing key from the master JWT secret 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.+ *+ * 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 base64UrlEncode(value: string) {return Buffer.from(value, "utf8").toString("base64url");}@@ -87,7 +110,10 @@ export function createLocalAgentJwt(agentId: string, companyId: string, adapterT};const signingInput = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(claims))}`;- const signature = signPayload(config.secret, signingInput);+ // Sign with the per-company derived key so a leaked token cannot be reused+ // across tenants.+ const signingKey = deriveCompanySigningKey(config.secret, companyId);+ const signature = signPayload(signingKey, signingInput);return `${signingInput}.${signature}`;}@@ -104,20 +130,40 @@ export function verifyLocalAgentJwt(token: string): LocalAgentJwtClaims | null {const header = parseJson(base64UrlDecode(headerB64));if (!header || header.alg !== JWT_ALGORITHM) return null;- const signingInput = `${headerB64}.${claimsB64}`;- const expectedSig = signPayload(config.secret, signingInput);- if (!safeCompare(signature, expectedSig)) return null;-const claims = parseJson(base64UrlDecode(claimsB64));if (!claims) return null;+ const claimedCompanyId = typeof claims.company_id === "string" ? claims.company_id : 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).+ //+ // 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);+ const perCompanySig = signPayload(perCompanyKey, signingInput);+ let signatureOk = safeCompare(signature, perCompanySig);+ if (!signatureOk && !config.disableLegacyFallback) {+ const legacySig = signPayload(config.secret, signingInput);+ signatureOk = safeCompare(signature, legacySig);+ }+ if (!signatureOk) return null;+const sub = typeof claims.sub === "string" ? claims.sub : null;- const companyId = typeof claims.company_id === "string" ? claims.company_id : null;const adapterType = typeof claims.adapter_type === "string" ? claims.adapter_type : null;const runId = typeof claims.run_id === "string" ? claims.run_id : null;const iat = typeof claims.iat === "number" ? claims.iat : null;const exp = typeof claims.exp === "number" ? claims.exp : null;- if (!sub || !companyId || !adapterType || !runId || !iat || !exp) return null;+ if (!sub || !adapterType || !runId || !iat || !exp) return null;+ const companyId = claimedCompanyId;const now = Math.floor(Date.now() / 1000);if (exp < now) return null;