Add project-level environment variables

Co-Authored-By: Paperclip <noreply@paperclip.ing>

server/src/__tests__/heartbeat-project-env.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveExecutionRunAdapterConfig } from "../services/heartbeat.ts";
+
+describe("resolveExecutionRunAdapterConfig", () => {
+  it("overlays project env on top of agent env and unions secret keys", async () => {
+    const resolveAdapterConfigForRuntime = vi.fn().mockResolvedValue({
+      config: {
+        env: {
+          SHARED_KEY: "agent",
+          AGENT_ONLY: "agent-only",
+        },
+        other: "value",
+      },
+      secretKeys: new Set(["AGENT_SECRET"]),
+    });
+    const resolveEnvBindings = vi.fn().mockResolvedValue({
+      env: {
+        SHARED_KEY: "project",
+        PROJECT_ONLY: "project-only",
+      },
+      secretKeys: new Set(["PROJECT_SECRET"]),
+    });
+
+    const result = await resolveExecutionRunAdapterConfig({
+      companyId: "company-1",
+      executionRunConfig: { env: { SHARED_KEY: "agent" } },
+      projectEnv: { SHARED_KEY: "project" },
+      secretsSvc: {
+        resolveAdapterConfigForRuntime,
+        resolveEnvBindings,
+      } as any,
+    });
+
+    expect(result.resolvedConfig).toMatchObject({
+      other: "value",
+      env: {
+        SHARED_KEY: "project",
+        AGENT_ONLY: "agent-only",
+        PROJECT_ONLY: "project-only",
+      },
+    });
+    expect(Array.from(result.secretKeys).sort()).toEqual(["AGENT_SECRET", "PROJECT_SECRET"]);
+  });
+
+  it("skips project env resolution when the project has no bindings", async () => {
+    const resolveAdapterConfigForRuntime = vi.fn().mockResolvedValue({
+      config: { env: { AGENT_ONLY: "agent-only" } },
+      secretKeys: new Set<string>(),
+    });
+    const resolveEnvBindings = vi.fn();
+
+    const result = await resolveExecutionRunAdapterConfig({
+      companyId: "company-1",
+      executionRunConfig: { env: { AGENT_ONLY: "agent-only" } },
+      projectEnv: null,
+      secretsSvc: {
+        resolveAdapterConfigForRuntime,
+        resolveEnvBindings,
+      } as any,
+    });
+
+    expect(result.resolvedConfig.env).toEqual({ AGENT_ONLY: "agent-only" });
+    expect(resolveEnvBindings).not.toHaveBeenCalled();
+  });
+});

server/src/__tests__/project-goal-telemetry-routes.test.ts

@@ -22,6 +22,9 @@ const mockGoalService = vi.hoisted(() => ({
 }));
 
 const mockWorkspaceOperationService = vi.hoisted(() => ({}));
+const mockSecretService = vi.hoisted(() => ({
+  normalizeEnvBindingsForPersistence: vi.fn(),
+}));
 const mockLogActivity = vi.hoisted(() => vi.fn());
 const mockTrackProjectCreated = vi.hoisted(() => vi.fn());
 const mockTrackGoalCreated = vi.hoisted(() => vi.fn());
@@ -46,6 +49,7 @@ vi.mock("../services/index.js", () => ({
   goalService: () => mockGoalService,
   logActivity: mockLogActivity,
   projectService: () => mockProjectService,
+  secretService: () => mockSecretService,
   workspaceOperationService: () => mockWorkspaceOperationService,
 }));
 
@@ -77,6 +81,7 @@ describe("project and goal telemetry routes", () => {
     vi.clearAllMocks();
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockProjectService.resolveByReference.mockResolvedValue({ ambiguous: false, project: null });
+    mockSecretService.normalizeEnvBindingsForPersistence.mockImplementation(async (_companyId, env) => env);
     mockProjectService.create.mockResolvedValue({
       id: "project-1",
       companyId: "company-1",

server/src/__tests__/project-routes-env.test.ts

@@ -0,0 +1,188 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockProjectService = vi.hoisted(() => ({
+  list: vi.fn(),
+  getById: vi.fn(),
+  create: vi.fn(),
+  update: vi.fn(),
+  createWorkspace: vi.fn(),
+  listWorkspaces: vi.fn(),
+  updateWorkspace: vi.fn(),
+  removeWorkspace: vi.fn(),
+  remove: vi.fn(),
+  resolveByReference: vi.fn(),
+}));
+const mockSecretService = vi.hoisted(() => ({
+  normalizeEnvBindingsForPersistence: vi.fn(),
+}));
+const mockWorkspaceOperationService = vi.hoisted(() => ({}));
+const mockLogActivity = vi.hoisted(() => vi.fn());
+const mockTrackProjectCreated = vi.hoisted(() => vi.fn());
+const mockGetTelemetryClient = vi.hoisted(() => vi.fn());
+
+vi.mock("@paperclipai/shared/telemetry", async () => {
+  const actual = await vi.importActual<typeof import("@paperclipai/shared/telemetry")>(
+    "@paperclipai/shared/telemetry",
+  );
+  return {
+    ...actual,
+    trackProjectCreated: mockTrackProjectCreated,
+  };
+});
+
+vi.mock("../telemetry.js", () => ({
+  getTelemetryClient: mockGetTelemetryClient,
+}));
+
+vi.mock("../services/index.js", () => ({
+  logActivity: mockLogActivity,
+  projectService: () => mockProjectService,
+  secretService: () => mockSecretService,
+  workspaceOperationService: () => mockWorkspaceOperationService,
+}));
+
+vi.mock("../services/workspace-runtime.js", () => ({
+  startRuntimeServicesForWorkspaceControl: vi.fn(),
+  stopRuntimeServicesForProjectWorkspace: vi.fn(),
+}));
+
+async function createApp() {
+  const { projectRoutes } = await import("../routes/projects.js");
+  const { errorHandler } = await import("../middleware/index.js");
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = {
+      type: "board",
+      userId: "board-user",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    };
+    next();
+  });
+  app.use("/api", projectRoutes({} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+function buildProject(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "project-1",
+    companyId: "company-1",
+    urlKey: "project-1",
+    goalId: null,
+    goalIds: [],
+    goals: [],
+    name: "Project",
+    description: null,
+    status: "backlog",
+    leadAgentId: null,
+    targetDate: null,
+    color: null,
+    env: null,
+    pauseReason: null,
+    pausedAt: null,
+    executionWorkspacePolicy: null,
+    codebase: {
+      workspaceId: null,
+      repoUrl: null,
+      repoRef: null,
+      defaultRef: null,
+      repoName: null,
+      localFolder: null,
+      managedFolder: "/tmp/project",
+      effectiveLocalFolder: "/tmp/project",
+      origin: "managed_checkout",
+    },
+    workspaces: [],
+    primaryWorkspace: null,
+    archivedAt: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe("project env routes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
+    mockProjectService.resolveByReference.mockResolvedValue({ ambiguous: false, project: null });
+    mockProjectService.createWorkspace.mockResolvedValue(null);
+    mockProjectService.listWorkspaces.mockResolvedValue([]);
+    mockSecretService.normalizeEnvBindingsForPersistence.mockImplementation(async (_companyId, env) => env);
+  });
+
+  it("normalizes env bindings on create and logs only env keys", async () => {
+    const normalizedEnv = {
+      API_KEY: {
+        type: "secret_ref",
+        secretId: "11111111-1111-4111-8111-111111111111",
+        version: "latest",
+      },
+    };
+    mockSecretService.normalizeEnvBindingsForPersistence.mockResolvedValue(normalizedEnv);
+    mockProjectService.create.mockResolvedValue(buildProject({ env: normalizedEnv }));
+
+    const app = await createApp();
+    const res = await request(app)
+      .post("/api/companies/company-1/projects")
+      .send({
+        name: "Project",
+        env: normalizedEnv,
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockSecretService.normalizeEnvBindingsForPersistence).toHaveBeenCalledWith(
+      "company-1",
+      normalizedEnv,
+      expect.objectContaining({ fieldPath: "env" }),
+    );
+    expect(mockProjectService.create).toHaveBeenCalledWith(
+      "company-1",
+      expect.objectContaining({ env: normalizedEnv }),
+    );
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        details: expect.objectContaining({
+          envKeys: ["API_KEY"],
+        }),
+      }),
+    );
+  });
+
+  it("normalizes env bindings on update and avoids logging raw values", async () => {
+    const normalizedEnv = {
+      PLAIN_KEY: { type: "plain", value: "top-secret" },
+    };
+    mockSecretService.normalizeEnvBindingsForPersistence.mockResolvedValue(normalizedEnv);
+    mockProjectService.getById.mockResolvedValue(buildProject());
+    mockProjectService.update.mockResolvedValue(buildProject({ env: normalizedEnv }));
+
+    const app = await createApp();
+    const res = await request(app)
+      .patch("/api/projects/project-1")
+      .send({
+        env: normalizedEnv,
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockProjectService.update).toHaveBeenCalledWith(
+      "project-1",
+      expect.objectContaining({ env: normalizedEnv }),
+    );
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        details: {
+          changedKeys: ["env"],
+          envKeys: ["PLAIN_KEY"],
+        },
+      }),
+    );
+  });
+});

server/src/routes/projects.ts

@@ -9,7 +9,7 @@ import {
 } from "@paperclipai/shared";
 import { trackProjectCreated } from "@paperclipai/shared/telemetry";
 import { validate } from "../middleware/validate.js";
-import { projectService, logActivity, workspaceOperationService } from "../services/index.js";
+import { projectService, logActivity, secretService, workspaceOperationService } from "../services/index.js";
 import { conflict } from "../errors.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
 import { startRuntimeServicesForWorkspaceControl, stopRuntimeServicesForProjectWorkspace } from "../services/workspace-runtime.js";
@@ -18,7 +18,9 @@ import { getTelemetryClient } from "../telemetry.js";
 export function projectRoutes(db: Db) {
   const router = Router();
   const svc = projectService(db);
+  const secretsSvc = secretService(db);
   const workspaceOperations = workspaceOperationService(db);
+  const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";
 
   async function resolveCompanyIdForProjectReference(req: Request) {
     const companyIdQuery = req.query.companyId;
@@ -82,6 +84,13 @@ export function projectRoutes(db: Db) {
     };
 
     const { workspace, ...projectData } = req.body as CreateProjectPayload;
+    if (projectData.env !== undefined) {
+      projectData.env = await secretsSvc.normalizeEnvBindingsForPersistence(
+        companyId,
+        projectData.env,
+        { strictMode: strictSecretsMode, fieldPath: "env" },
+      );
+    }
     const project = await svc.create(companyId, projectData);
     let createdWorkspaceId: string | null = null;
     if (workspace) {
@@ -107,6 +116,7 @@ export function projectRoutes(db: Db) {
       details: {
         name: project.name,
         workspaceId: createdWorkspaceId,
+        envKeys: project.env ? Object.keys(project.env).sort() : [],
       },
     });
     const telemetryClient = getTelemetryClient();
@@ -128,6 +138,12 @@ export function projectRoutes(db: Db) {
     if (typeof body.archivedAt === "string") {
       body.archivedAt = new Date(body.archivedAt);
     }
+    if (body.env !== undefined) {
+      body.env = await secretsSvc.normalizeEnvBindingsForPersistence(existing.companyId, body.env, {
+        strictMode: strictSecretsMode,
+        fieldPath: "env",
+      });
+    }
     const project = await svc.update(id, body);
     if (!project) {
       res.status(404).json({ error: "Project not found" });
@@ -143,7 +159,13 @@ export function projectRoutes(db: Db) {
       action: "project.updated",
       entityType: "project",
       entityId: project.id,
-      details: req.body,
+      details: {
+        changedKeys: Object.keys(req.body).sort(),
+        envKeys:
+          body.env && typeof body.env === "object" && !Array.isArray(body.env)
+            ? Object.keys(body.env as Record<string, unknown>).sort()
+            : undefined,
+      },
     });
 
     res.json(project);

server/src/services/company-portability.ts

@@ -27,6 +27,7 @@ import type {
   CompanyPortabilitySidebarOrder,
   CompanyPortabilitySkillManifestEntry,
   CompanySkill,
+  AgentEnvConfig,
   RoutineVariable,
 } from "@paperclipai/shared";
 import {
@@ -39,6 +40,7 @@ import {
   ROUTINE_TRIGGER_KINDS,
   ROUTINE_TRIGGER_SIGNING_MODES,
   deriveProjectUrlKey,
+  envConfigSchema,
   normalizeAgentUrlKey,
 } from "@paperclipai/shared";
 import {
@@ -387,6 +389,11 @@ function isSensitiveEnvKey(key: string) {
   );
 }
 
+function normalizePortableProjectEnv(value: unknown): AgentEnvConfig | null {
+  const parsed = envConfigSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
 type ResolvedSource = {
   manifest: CompanyPortabilityManifest;
   files: Record<string, CompanyPortabilityFileEntry>;
@@ -419,6 +426,7 @@ type ProjectLike = {
   targetDate: string | null;
   color: string | null;
   status: string;
+  env: Record<string, unknown> | null;
   executionWorkspacePolicy: Record<string, unknown> | null;
   workspaces?: Array<{
     id: string;
@@ -2531,6 +2539,7 @@ function buildManifestFromPackageFiles(
       targetDate: asString(extension.targetDate),
       color: asString(extension.color),
       status: asString(extension.status),
+      env: normalizePortableProjectEnv(extension.env),
       executionWorkspacePolicy: isPlainRecord(extension.executionWorkspacePolicy)
         ? extension.executionWorkspacePolicy
         : null,
@@ -3159,6 +3168,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
         targetDate: project.targetDate ?? null,
         color: project.color ?? null,
         status: project.status,
+        env: normalizePortableProjectEnv(project.env) ?? undefined,
         executionWorkspacePolicy: exportPortableProjectExecutionWorkspacePolicy(
           slug,
           project.executionWorkspacePolicy,
@@ -4095,6 +4105,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
           status: manifestProject.status && PROJECT_STATUSES.includes(manifestProject.status as any)
             ? manifestProject.status as typeof PROJECT_STATUSES[number]
             : "backlog",
+          env: manifestProject.env,
           executionWorkspacePolicy: stripPortableProjectExecutionWorkspaceRefs(manifestProject.executionWorkspacePolicy),
         };
 

server/src/services/heartbeat.ts

@@ -86,6 +86,36 @@ const SESSIONED_LOCAL_ADAPTERS = new Set([
   "pi_local",
 ]);
 
+type RuntimeConfigSecretResolver = Pick<
+  ReturnType<typeof secretService>,
+  "resolveAdapterConfigForRuntime" | "resolveEnvBindings"
+>;
+
+export async function resolveExecutionRunAdapterConfig(input: {
+  companyId: string;
+  executionRunConfig: Record<string, unknown>;
+  projectEnv: unknown;
+  secretsSvc: RuntimeConfigSecretResolver;
+}) {
+  const { config: resolvedConfig, secretKeys } = await input.secretsSvc.resolveAdapterConfigForRuntime(
+    input.companyId,
+    input.executionRunConfig,
+  );
+  const projectEnvResolution = input.projectEnv
+    ? await input.secretsSvc.resolveEnvBindings(input.companyId, input.projectEnv)
+    : { env: {}, secretKeys: new Set<string>() };
+  if (Object.keys(projectEnvResolution.env).length > 0) {
+    resolvedConfig.env = {
+      ...parseObject(resolvedConfig.env),
+      ...projectEnvResolution.env,
+    };
+    for (const key of projectEnvResolution.secretKeys) {
+      secretKeys.add(key);
+    }
+  }
+  return { resolvedConfig, secretKeys };
+}
+
 export function applyPersistedExecutionWorkspaceConfig(input: {
   config: Record<string, unknown>;
   workspaceConfig: ExecutionWorkspaceConfig | null;
@@ -2309,17 +2339,20 @@ export function heartbeatService(db: Db) {
       : null;
     const contextProjectId = readNonEmptyString(context.projectId);
     const executionProjectId = issueContext?.projectId ?? contextProjectId;
-    const projectExecutionWorkspacePolicy = executionProjectId
+    const projectContext = executionProjectId
       ? await db
-          .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+          .select({
+            executionWorkspacePolicy: projects.executionWorkspacePolicy,
+            env: projects.env,
+          })
           .from(projects)
           .where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
-          .then((rows) =>
-            gateProjectExecutionWorkspacePolicy(
-              parseProjectExecutionWorkspacePolicy(rows[0]?.executionWorkspacePolicy),
-              isolatedWorkspacesEnabled,
-            ))
+          .then((rows) => rows[0] ?? null)
       : null;
+    const projectExecutionWorkspacePolicy = gateProjectExecutionWorkspacePolicy(
+      parseProjectExecutionWorkspacePolicy(projectContext?.executionWorkspacePolicy),
+      isolatedWorkspacesEnabled,
+    );
     const taskSession = taskKey
       ? await getTaskSession(agent.companyId, agent.id, agent.adapterType, taskKey)
       : null;
@@ -2416,10 +2449,12 @@ export function heartbeatService(db: Db) {
       : persistedWorkspaceManagedConfig;
     const configSnapshot = buildExecutionWorkspaceConfigSnapshot(mergedConfig);
     const executionRunConfig = stripWorkspaceRuntimeFromExecutionRunConfig(mergedConfig);
-    const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(
-      agent.companyId,
+    const { resolvedConfig, secretKeys } = await resolveExecutionRunAdapterConfig({
+      companyId: agent.companyId,
       executionRunConfig,
-    );
+      projectEnv: projectContext?.env ?? null,
+      secretsSvc,
+    });
     const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
     const runtimeConfig = {
       ...resolvedConfig,

server/src/services/secrets.ts

@@ -39,6 +39,11 @@ function canonicalizeBinding(binding: EnvBinding): CanonicalEnvBinding {
 }
 
 export function secretService(db: Db) {
+  type NormalizeEnvOptions = {
+    strictMode?: boolean;
+    fieldPath?: string;
+  };
+
   async function getById(id: string) {
     return db
       .select()
@@ -94,10 +99,10 @@ export function secretService(db: Db) {
   async function normalizeEnvConfig(
     companyId: string,
     envValue: unknown,
-    opts?: { strictMode?: boolean },
+    opts?: NormalizeEnvOptions,
   ): Promise<AgentEnvConfig> {
     const record = asRecord(envValue);
-    if (!record) throw unprocessable("adapterConfig.env must be an object");
+    if (!record) throw unprocessable(`${opts?.fieldPath ?? "env"} must be an object`);
 
     const normalized: AgentEnvConfig = {};
     for (const [key, rawBinding] of Object.entries(record)) {
@@ -292,6 +297,12 @@ export function secretService(db: Db) {
       opts?: { strictMode?: boolean },
     ) => normalizeAdapterConfigForPersistenceInternal(companyId, adapterConfig, opts),
 
+    normalizeEnvBindingsForPersistence: async (
+      companyId: string,
+      envValue: unknown,
+      opts?: NormalizeEnvOptions,
+    ) => normalizeEnvConfig(companyId, envValue, opts),
+
     normalizeHireApprovalPayloadForPersistence: async (
       companyId: string,
       payload: Record<string, unknown>,