feat(database,rbac): add multiple environment API key foundations

Author: carderne

apps/webapp/app/utils/apiKeys.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vitest";
+import {
+  apiKeyPrefix,
+  generateAdditionalApiKey,
+  generateRootApiKey,
+  hashApiKey,
+  obfuscateApiKey,
+} from "./apiKeys";
+
+describe("API key utilities", () => {
+  test.each([
+    ["DEVELOPMENT", "tr_dev_"],
+    ["STAGING", "tr_stg_"],
+    ["PRODUCTION", "tr_prod_"],
+    ["PREVIEW", "tr_preview_"],
+  ] as const)("generates %s keys", (environmentType, prefix) => {
+    const root = generateRootApiKey(environmentType);
+    const additional = generateAdditionalApiKey(environmentType);
+
+    expect(root.apiKey).toMatch(new RegExp(`^${prefix}[A-Za-z0-9]{24}$`));
+    expect(root.keyHash).toBe(hashApiKey(root.apiKey));
+    expect(root.lastFour).toBe(root.apiKey.slice(-4));
+    expect(additional.apiKey).toMatch(new RegExp(`^${prefix}ak_[A-Za-z0-9]{24}$`));
+    expect(additional.keyHash).toBe(hashApiKey(additional.apiKey));
+    expect(additional.lastFour).toBe(additional.apiKey.slice(-4));
+    expect(apiKeyPrefix(environmentType)).toBe(prefix);
+    expect(obfuscateApiKey(environmentType, root.lastFour)).toBe(
+      `${prefix}••••••••${root.lastFour}`
+    );
+    expect(obfuscateApiKey(environmentType, additional.lastFour, "additional")).toBe(
+      `${prefix}ak_••••••••${additional.lastFour}`
+    );
+  });
+
+  test("generates unique keys", () => {
+    const keys = new Set(
+      Array.from({ length: 100 }, () => generateAdditionalApiKey("PRODUCTION").apiKey)
+    );
+
+    expect(keys.size).toBe(100);
+  });
+});

apps/webapp/app/utils/apiKeys.ts

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import type { RuntimeEnvironmentType } from "@trigger.dev/database";
+import { customAlphabet } from "nanoid";
+
+const apiKeyId = customAlphabet(
+  "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
+  24
+);
+
+export function hashApiKey(apiKey: string): string {
+  return createHash("sha256").update(apiKey, "utf8").digest("hex");
+}
+
+function generatedApiKey(apiKey: string) {
+  return {
+    apiKey,
+    keyHash: hashApiKey(apiKey),
+    lastFour: apiKey.slice(-4),
+  };
+}
+
+export function generateRootApiKey(environmentType: RuntimeEnvironmentType) {
+  // Root keys intentionally use the same 24-character entropy as additional keys.
+  return generatedApiKey(`${apiKeyPrefix(environmentType)}${apiKeyId()}`);
+}
+
+export function generateAdditionalApiKey(environmentType: RuntimeEnvironmentType) {
+  return generatedApiKey(`${apiKeyPrefix(environmentType)}ak_${apiKeyId()}`);
+}
+
+export function apiKeyPrefix(environmentType: RuntimeEnvironmentType): string {
+  switch (environmentType) {
+    case "DEVELOPMENT":
+      return "tr_dev_";
+    case "STAGING":
+      return "tr_stg_";
+    case "PRODUCTION":
+      return "tr_prod_";
+    case "PREVIEW":
+      return "tr_preview_";
+  }
+}
+
+export function obfuscateApiKey(
+  environmentType: RuntimeEnvironmentType,
+  lastFour: string,
+  kind: "root" | "additional" = "root"
+): string {
+  const discriminator = kind === "additional" ? "ak_" : "";
+  return `${apiKeyPrefix(environmentType)}${discriminator}••••••••${lastFour}`;
+}

internal-packages/database/prisma/migrations/20260723112558_add_environment_api_keys/migration.sql

@@ -0,0 +1,30 @@
+-- CreateTable
+CREATE TABLE "public"."api_keys" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "key_hash" TEXT NOT NULL,
+    "last_four" TEXT NOT NULL,
+    "runtime_environment_id" TEXT NOT NULL,
+    "created_by_user_id" TEXT,
+    "preset_id" TEXT,
+    "scopes" TEXT[] NOT NULL,
+    "last_used_at" TIMESTAMP(3),
+    "revoked_at" TIMESTAMP(3),
+    "expires_at" TIMESTAMP(3),
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "api_keys_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "api_keys_key_hash_key" ON "public"."api_keys"("key_hash");
+
+-- CreateIndex
+CREATE INDEX "api_keys_runtime_environment_id_revoked_at_created_at_idx" ON "public"."api_keys"("runtime_environment_id", "revoked_at", "created_at" DESC);
+
+-- AddForeignKey
+ALTER TABLE "public"."api_keys" ADD CONSTRAINT "api_keys_runtime_environment_id_fkey" FOREIGN KEY ("runtime_environment_id") REFERENCES "public"."RuntimeEnvironment"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."api_keys" ADD CONSTRAINT "api_keys_created_by_user_id_fkey" FOREIGN KEY ("created_by_user_id") REFERENCES "public"."User"("id") ON DELETE SET NULL ON UPDATE CASCADE;

internal-packages/database/prisma/schema.prisma

@@ -69,6 +69,7 @@ model User {
   invitationCode       InvitationCode?       @relation(fields: [invitationCodeId], references: [id])
   invitationCodeId     String?
   personalAccessTokens PersonalAccessToken[]
+  createdApiKeys       ApiKey[]
   deployments          WorkerDeployment[]
   backupCodes          MfaBackupCode[]
   bulkActions          BulkActionGroup[]
@@ -392,6 +393,7 @@ model RuntimeEnvironment {
   playgroundConversations PlaygroundConversation[]
   errorGroupStates        ErrorGroupState[]
   taskIdentifiers         TaskIdentifier[]
+  apiKeys                 ApiKey[]
   revokedApiKeys          RevokedApiKey[]
 
   // A partial unique index also enforces one STAGING/PREVIEW root per project and type.
@@ -403,6 +405,31 @@ model RuntimeEnvironment {
   @@index([organizationId])
 }
 
+model ApiKey {
+  id       String @id @default(cuid())
+  name     String
+  keyHash  String @unique @map("key_hash")
+  lastFour String @map("last_four")
+
+  runtimeEnvironment   RuntimeEnvironment @relation(fields: [runtimeEnvironmentId], references: [id], onDelete: Cascade, onUpdate: Cascade)
+  runtimeEnvironmentId String             @map("runtime_environment_id")
+
+  createdBy       User?   @relation(fields: [createdByUserId], references: [id], onDelete: SetNull, onUpdate: Cascade)
+  createdByUserId String? @map("created_by_user_id")
+
+  presetId String?  @map("preset_id")
+  scopes   String[]
+
+  lastUsedAt DateTime? @map("last_used_at")
+  revokedAt  DateTime? @map("revoked_at")
+  expiresAt  DateTime? @map("expires_at")
+  updatedAt  DateTime  @updatedAt @map("updated_at")
+  createdAt  DateTime  @default(now()) @map("created_at")
+
+  @@index([runtimeEnvironmentId, revokedAt, createdAt(sort: Desc)])
+  @@map("api_keys")
+}
+
 /// Records of previously-valid API keys that are still accepted for authentication
 /// during a grace window after rotation. Extend or end the grace period by updating `expiresAt`.
 model RevokedApiKey {

internal-packages/rbac/src/ability.test.ts

@@ -5,6 +5,7 @@ import {
   denyAbility,
   buildFallbackAbility,
   buildJwtAbility,
+  scopesWithinAbility,
 } from "./ability.js";
 
 describe("permissiveAbility", () => {
@@ -123,6 +124,43 @@ describe("buildJwtAbility", () => {
   });
 });
 
+describe("scopesWithinAbility", () => {
+  it("allows subsets and preserves ids containing colons", () => {
+    const result = scopesWithinAbility(
+      ["read:runs:run_abc", "read:tags:env:staging"],
+      buildJwtAbility(["read:runs", "read:tags:env:staging"])
+    );
+
+    expect(result).toEqual({ ok: true, deniedScopes: [] });
+  });
+
+  it("rejects scopes that broaden or exceed the ability", () => {
+    const result = scopesWithinAbility(
+      ["trigger:tasks:send-email", "trigger:tasks", "read:runs"],
+      buildJwtAbility(["trigger:tasks:send-email"])
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      deniedScopes: ["trigger:tasks", "read:runs"],
+    });
+  });
+
+  it("allows arbitrary valid scopes for a permissive ability", () => {
+    expect(scopesWithinAbility(["read:runs", "admin"], permissiveAbility)).toEqual({
+      ok: true,
+      deniedScopes: [],
+    });
+  });
+
+  it("rejects malformed scopes for restricted abilities", () => {
+    expect(scopesWithinAbility(["read"], buildJwtAbility(["read:all"]))).toEqual({
+      ok: false,
+      deniedScopes: ["read"],
+    });
+  });
+});
+
 describe("buildJwtAbility — array resources", () => {
   it("authorizes when any resource in the array passes a scope check", () => {
     const ability = buildJwtAbility(["read:batch:batch_abc"]);

internal-packages/rbac/src/ability.ts

@@ -4,7 +4,7 @@ import type { RbacAbility } from "@trigger.dev/plugins";
 // @trigger.dev/plugins so a public token decodes identically whoever
 // serves the request. Re-exported here so existing importers keep their
 // `./ability.js` import.
-export { buildJwtAbility } from "@trigger.dev/plugins";
+export { buildJwtAbility, scopesWithinAbility } from "@trigger.dev/plugins";
 
 /** Every authenticated non-admin subject: can do anything, cannot do super-user actions. */
 export const permissiveAbility: RbacAbility = {

internal-packages/rbac/src/fallback.ts

@@ -13,7 +13,11 @@ import type {
   RoleMutationResult,
   UserActorAuthResult,
 } from "@trigger.dev/plugins";
-import { isUserActorToken, verifyUserActorToken } from "@trigger.dev/plugins";
+import {
+  FULL_ACCESS_PRESET_ID,
+  isUserActorToken,
+  verifyUserActorToken,
+} from "@trigger.dev/plugins";
 import { createHash } from "node:crypto";
 import type { PrismaClient } from "@trigger.dev/database";
 import { validateJWT } from "@trigger.dev/core/v3/jwt";
@@ -374,6 +378,34 @@ class RoleBaseAccessFallbackController implements RoleBaseAccessController {
     return null;
   }
 
+  async apiKeyPresets(_organizationId: string) {
+    return null;
+  }
+
+  async prepareApiKeyPolicy(params: {
+    organizationId: string;
+    presetId: string;
+    taskIdentifiers?: string[];
+  }) {
+    // Without a plugin there is no preset catalogue, so full access is the only
+    // policy on offer, but the caller still has to ask for it by name. Any
+    // other preset, or any task selection, is a restricted key and unavailable.
+    if (params.presetId !== FULL_ACCESS_PRESET_ID || (params.taskIdentifiers?.length ?? 0) > 0) {
+      return { ok: false as const, error: "API key access presets are not available" };
+    }
+
+    // `presetId: null` because this install has no catalogue to reference. The
+    // persisted scopes remain the source of truth for authorization.
+    return {
+      ok: true as const,
+      policy: { presetId: null, scopes: ["admin"] },
+    };
+  }
+
+  async describeApiKeyPolicy() {
+    return {};
+  }
+
   async allPermissions(): Promise<Permission[]> {
     return [];
   }

internal-packages/rbac/src/index.ts

@@ -13,6 +13,8 @@ import type { PrismaClient } from "@trigger.dev/database";
 import { RoleBaseAccessFallback } from "./fallback.js";
 export type { RoleBaseAccessController, RbacAbility, RbacResource } from "@trigger.dev/plugins";
 export type { UserActorAuthResult, UserActorClaims } from "@trigger.dev/plugins";
+export { buildJwtAbility, scopesWithinAbility } from "./ability.js";
+export { FULL_ACCESS_PRESET_ID, scopesGrantFullAccess } from "@trigger.dev/plugins";
 // Re-export the user-actor token grammar so the webapp mints/checks tokens
 // through @trigger.dev/rbac (it doesn't import @trigger.dev/plugins directly).
 export {
@@ -213,6 +215,20 @@ class LazyController implements RoleBaseAccessController {
     return (await this.c()).systemRoles(...args);
   }
 
+  async apiKeyPresets(...args: Parameters<RoleBaseAccessController["apiKeyPresets"]>) {
+    return (await this.c()).apiKeyPresets(...args);
+  }
+
+  async prepareApiKeyPolicy(...args: Parameters<RoleBaseAccessController["prepareApiKeyPolicy"]>) {
+    return (await this.c()).prepareApiKeyPolicy(...args);
+  }
+
+  async describeApiKeyPolicy(
+    ...args: Parameters<RoleBaseAccessController["describeApiKeyPolicy"]>
+  ) {
+    return (await this.c()).describeApiKeyPolicy(...args);
+  }
+
   async allPermissions(
     ...args: Parameters<RoleBaseAccessController["allPermissions"]>
   ): Promise<Permission[]> {

packages/core/src/v3/jwt.ts

@@ -14,6 +14,40 @@ export const JWT_ALGORITHM = "HS256";
 export const JWT_ISSUER = "https://id.trigger.dev";
 export const JWT_AUDIENCE = "https://api.trigger.dev";
 
+function decodeJWTPayload(token: string): unknown {
+  const parts = token.split(".");
+  const encodedPayload = parts[1];
+  if (parts.length !== 3 || !encodedPayload) return;
+
+  try {
+    const base64 = encodedPayload
+      .replace(/-/g, "+")
+      .replace(/_/g, "/")
+      .padEnd(Math.ceil(encodedPayload.length / 4) * 4, "=");
+    const bytes = Uint8Array.from(atob(base64), (character) => character.charCodeAt(0));
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return;
+  }
+}
+
+export function isPublicJWT(token: string): boolean {
+  const payload = decodeJWTPayload(token);
+  return (
+    payload !== null && typeof payload === "object" && "pub" in payload && payload.pub === true
+  );
+}
+
+export function extractJWTSub(token: string): string | undefined {
+  const payload = decodeJWTPayload(token);
+  return payload !== null &&
+    typeof payload === "object" &&
+    "sub" in payload &&
+    typeof payload.sub === "string"
+    ? payload.sub
+    : undefined;
+}
+
 export async function generateJWT(options: GenerateJWTOptions): Promise<string> {
   const { SignJWT } = await import("jose");
 

packages/plugins/src/index.ts

@@ -18,10 +18,22 @@ export type {
   RbacPluginConfig,
   RbacDatabaseConfig,
   SystemRole,
+  ApiKeyPreset,
+  ApiKeyPolicy,
+  PrepareApiKeyPolicyResult,
+  ApiKeyPolicyDescription,
   AuthenticatedEnvironment,
+  RbacScopeAction,
+  RbacScopeResourceType,
 } from "./rbac.js";
 
-export { buildJwtAbility } from "./rbac.js";
+export {
+  buildJwtAbility,
+  buildScope,
+  FULL_ACCESS_PRESET_ID,
+  scopesGrantFullAccess,
+  scopesWithinAbility,
+} from "./rbac.js";
 export {
   isUserActorToken,
   signUserActorToken,