feat(cli,webapp): allow deploys with environment API keys

Author: carderne

.changeset/deploy-api-keys.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Allow `trigger deploy` to authenticate with an environment API key from `TRIGGER_SECRET_KEY`, including deploy-only keys and Preview deployments.

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.apikeys/route.tsx

@@ -872,7 +872,7 @@ const API_KEY_EXPIRATIONS = [
   { value: "never", label: "Never" },
 ];
 
-type CapId = "tasks" | "runs" | "batches" | "queues" | "deployments" | "envvars";
+type CapId = "tasks" | "runs" | "batches" | "queues" | "deployments" | "branches" | "envvars";
 
 // Capability rows shown in the scope pane, in a fixed order so two presets read
 // as a diff of the same list rather than a reshuffled one.
@@ -882,6 +882,7 @@ const SCOPE_CAPABILITIES: [CapId, string][] = [
   ["batches", "Batches"],
   ["queues", "Queues"],
   ["deployments", "Deployments"],
+  ["branches", "Preview branches"],
   ["envvars", "Environment variables"],
 ];
 
@@ -918,6 +919,7 @@ const SCOPE_CAPABILITY_BY_SCOPE: Record<string, [CapId, number]> = {
   "write:queues": ["queues", 2],
   "read:deployments": ["deployments", 1],
   "write:deployments": ["deployments", 2],
+  "write:branches": ["branches", 3],
   "read:envvars": ["envvars", 1],
   "write:envvars": ["envvars", 2],
 };

apps/webapp/app/routes/api.v1.projects.$projectRef.$env.ts

@@ -8,9 +8,9 @@ import {
 } from "~/services/apiAuth.server";
 import { logger } from "~/services/logger.server";
 import {
-  authenticateEnvironmentScopedApiRequest,
+  apiKeyForProjectEnvironmentBootstrap,
+  authenticateEnvironmentBootstrapRequest,
   authorizePatEnvironmentAccess,
-  presentedApiKeyFromAuthentication,
 } from "~/services/environmentVariableApiAccess.server";
 
 const ParamsSchema = z.object({
@@ -30,9 +30,9 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
   const { projectRef, env } = parsedParams.data;
 
   try {
-    // PAT/OAT authenticate on the legacy path; machine API keys go through
-    // the RBAC controller so additional keys (and their grants) are enforced.
-    const authResult = await authenticateEnvironmentScopedApiRequest(request, "read", "apiKeys");
+    // PAT/OAT authenticate on the legacy path; machine API keys only need to
+    // prove they are valid because bootstrap echoes the same key back.
+    const authResult = await authenticateEnvironmentBootstrapRequest(request);
     if (!authResult.ok) {
       return json({ error: authResult.error }, { status: authResult.status });
     }
@@ -46,29 +46,22 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
     );
 
     // User tokens bootstrap the environment's secret key, so gate them on
-    // env-tier read:apiKeys. Machine credentials are checked against the same
-    // permission before their presented key is returned below.
-    const denied = await authorizePatEnvironmentAccess({
-      request,
-      authType: authenticationResult.type,
-      ability:
-        authenticationResult.type === "apiKey" && authenticationResult.result.ok
-          ? authenticationResult.result.ability
-          : undefined,
-      organizationId: environment.organizationId,
-      projectId: environment.project.id,
-      envType: environment.type,
-      resource: "apiKeys",
-      action: "read",
-    });
-    if (denied) return denied;
-
-    // API-key callers already possess a valid environment credential. Reuse
-    // exactly what they presented instead of exchanging it for the root key.
-    const presentedApiKey = presentedApiKeyFromAuthentication(authenticationResult);
+    // env-tier read:apiKeys. A machine credential never receives that root key.
+    if (authenticationResult.type !== "apiKey") {
+      const denied = await authorizePatEnvironmentAccess({
+        request,
+        authType: authenticationResult.type,
+        organizationId: environment.organizationId,
+        projectId: environment.project.id,
+        envType: environment.type,
+        resource: "apiKeys",
+        action: "read",
+      });
+      if (denied) return denied;
+    }
 
     const result: GetProjectEnvResponse = {
-      apiKey: presentedApiKey ?? environment.apiKey,
+      apiKey: apiKeyForProjectEnvironmentBootstrap(authenticationResult, environment.apiKey),
       name: environment.project.name,
       apiUrl: processEnv.API_ORIGIN ?? processEnv.APP_ORIGIN,
       projectId: environment.project.id,

apps/webapp/app/routes/api.v1.projects.$projectRef.branches.ts

@@ -3,7 +3,11 @@ import { tryCatch, UpsertBranchRequestBody } from "@trigger.dev/core/v3";
 import { DEFAULT_DEV_BRANCH, isDefaultDevBranch } from "@trigger.dev/core/v3/utils/gitBranch";
 import { z } from "zod";
 import { prisma } from "~/db.server";
-import { authenticateRequest } from "~/services/apiAuth.server";
+import {
+  authenticateApiKeyWithScope,
+  authenticateRequest,
+  type AuthenticationResult,
+} from "~/services/apiAuth.server";
 import { logger } from "~/services/logger.server";
 import { authenticateApiRequestWithPersonalAccessToken } from "~/services/personalAccessToken.server";
 import { UpsertBranchService } from "~/services/upsertBranch.server";
@@ -21,15 +25,35 @@ export async function action({ request, params }: ActionFunctionArgs) {
 
   logger.info("project upsert branch", { url: request.url });
 
-  const authenticationResult = await authenticateRequest(request, {
+  const userOrOrganizationAuthentication = await authenticateRequest(request, {
     personalAccessToken: true,
     organizationAccessToken: true,
     apiKey: false,
   });
-  if (!authenticationResult) {
-    return json({ error: "Invalid or Missing Access Token" }, { status: 401 });
+
+  let authenticationResult: AuthenticationResult;
+  if (userOrOrganizationAuthentication) {
+    authenticationResult = userOrOrganizationAuthentication;
+  } else {
+    const apiKeyAuthentication = await authenticateApiKeyWithScope(request, {
+      action: "write",
+      resource: { type: "branches" },
+      allowPreviewParent: true,
+    });
+    if (!apiKeyAuthentication.ok) {
+      return json({ error: apiKeyAuthentication.error }, { status: apiKeyAuthentication.status });
+    }
+    authenticationResult = {
+      type: "apiKey",
+      result: apiKeyAuthentication.authentication,
+    };
   }
 
+  const apiKeyEnvironment =
+    authenticationResult.type === "apiKey" && authenticationResult.result.ok
+      ? authenticationResult.result.environment
+      : undefined;
+
   const parsedParams = ParamsSchema.safeParse(params);
 
   if (!parsedParams.success) {
@@ -38,24 +62,32 @@ export async function action({ request, params }: ActionFunctionArgs) {
 
   const { projectRef } = parsedParams.data;
 
-  const project = await prisma.project.findFirst({
-    select: {
-      id: true,
-    },
-    where: {
-      externalRef: projectRef,
-      organization:
-        authenticationResult.type === "organizationAccessToken"
-          ? { id: authenticationResult.result.organizationId }
-          : {
-              members: {
-                some: {
-                  userId: authenticationResult.result.userId,
+  let project: { id: string } | null | undefined;
+  if (authenticationResult.type === "apiKey") {
+    project =
+      apiKeyEnvironment?.project.externalRef === projectRef
+        ? { id: apiKeyEnvironment.project.id }
+        : undefined;
+  } else {
+    project = await prisma.project.findFirst({
+      select: {
+        id: true,
+      },
+      where: {
+        externalRef: projectRef,
+        organization:
+          authenticationResult.type === "organizationAccessToken"
+            ? { id: authenticationResult.result.organizationId }
+            : {
+                members: {
+                  some: {
+                    userId: authenticationResult.result.userId,
+                  },
                 },
               },
-            },
-    },
-  });
+      },
+    });
+  }
   if (!project) {
     return json({ error: "Project not found" }, { status: 404 });
   }
@@ -72,38 +104,64 @@ export async function action({ request, params }: ActionFunctionArgs) {
 
   const { branch, env, git } = parsed.data;
 
-  if (env === "development" && authenticationResult.type === "organizationAccessToken") {
+  if (env === "development" && authenticationResult.type !== "personalAccessToken") {
     return json(
-      { error: "Cannot create dev branches with organization access tokens." },
+      {
+        error:
+          authenticationResult.type === "apiKey"
+            ? "API keys can only create Preview branches."
+            : "Cannot create dev branches with organization access tokens.",
+      },
       { status: 400 }
     );
   }
 
+  if (
+    authenticationResult.type === "apiKey" &&
+    (!apiKeyEnvironment ||
+      apiKeyEnvironment.type !== "PREVIEW" ||
+      apiKeyEnvironment.parentEnvironmentId !== null)
+  ) {
+    return json(
+      { error: "API keys must belong to the parent Preview environment." },
+      { status: 403 }
+    );
+  }
+
   if (env === "development" && isDefaultDevBranch(branch)) {
     return json(
       { error: `Cannot create dev branch with name '${DEFAULT_DEV_BRANCH}'.` },
       { status: 400 }
     );
   }
 
-  const service = new UpsertBranchService();
-  const result = await service.call(
-    authenticationResult.type === "organizationAccessToken"
-      ? { type: "orgId", organizationId: authenticationResult.result.organizationId }
-      : { type: "userMembership", userId: authenticationResult.result.userId },
-    {
-      env,
-      branchName: branch,
-      projectId: project.id,
-      git,
+  let orgFilter:
+    | { type: "userMembership"; userId: string }
+    | { type: "orgId"; organizationId: string };
+  if (authenticationResult.type === "personalAccessToken") {
+    orgFilter = { type: "userMembership", userId: authenticationResult.result.userId };
+  } else if (authenticationResult.type === "organizationAccessToken") {
+    orgFilter = { type: "orgId", organizationId: authenticationResult.result.organizationId };
+  } else {
+    if (!apiKeyEnvironment) {
+      return json({ error: "Invalid API key" }, { status: 401 });
     }
-  );
+    orgFilter = { type: "orgId", organizationId: apiKeyEnvironment.organizationId };
+  }
+
+  const service = new UpsertBranchService();
+  const result = await service.call(orgFilter, {
+    env,
+    branchName: branch,
+    projectId: project.id,
+    git,
+  });
 
   if (!result.success) {
     return json({ error: result.error }, { status: 400 });
   }
 
-  return json(result.branch);
+  return json({ id: result.branch.id });
 }
 
 export async function loader({ request, params }: LoaderFunctionArgs) {