refactor(rbac): make API key policy methods optional on the controller

The API-key policy methods are capability extensions, so declare them
optional on RoleBaseAccessController and normalize the surface in
LazyController rather than requiring every implementation to carry them.

An authorization extension is compiled against whichever core commit its
base image ships, so a required additive method forces both sides to move
together and turns rolling an extension back into a build failure instead
of a graceful degradation.

Absence fails closed: no preset catalogue, and prepareApiKeyPolicy refuses
outright rather than defaulting to full access, so an extension below this
contract cannot mint a credential. Keys already issued are unaffected —
they authorize from the scopes persisted on their row.

loader.create() now returns HostRbacController, the total surface, so host
callers neither guard nor invent their own absent-extension default.

Author: carderne

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

@@ -0,0 +1,58 @@
+import type { PrismaClient } from "@trigger.dev/database";
+import { describe, expect, it, vi } from "vitest";
+
+// The API-key policy methods are OPTIONAL on RoleBaseAccessController so a
+// plugin compiled against an older OSS commit still satisfies the contract
+// (the plugin is built against whichever OSS source its base image carries).
+// LazyController is what turns that partial surface into a total one, and these
+// tests pin the defaults it substitutes — in particular that a missing
+// prepareApiKeyPolicy fails CLOSED rather than resolving to full access.
+//
+// A stand-in for the cloud plugin, which isn't installed in this repo. The
+// factory supplies the specifier, so no real module has to resolve.
+vi.mock("@triggerdotdev/plugins/rbac", () => ({
+  default: {
+    create: () => ({
+      // Deliberately omits apiKeyPresets / prepareApiKeyPolicy /
+      // describeApiKeyPolicy — this is a pre-contract plugin.
+      isUsingPlugin: async () => true,
+    }),
+  },
+}));
+
+const prismaPlaceholder = {} as unknown as PrismaClient;
+
+describe("LazyController API-key policy defaults (plugin predates the contract)", () => {
+  async function controller() {
+    const loader = (await import("./index.js")).default;
+    const instance = loader.create(prismaPlaceholder);
+    // Guard against a silent fallback: if the mock didn't take, these
+    // assertions would be checking the fallback's real implementations.
+    await expect(instance.isUsingPlugin()).resolves.toBe(true);
+    return instance;
+  }
+
+  it("reports no preset catalogue rather than throwing", async () => {
+    await expect((await controller()).apiKeyPresets("org_123")).resolves.toBeNull();
+  });
+
+  it("refuses to prepare a policy — including FULL_ACCESS", async () => {
+    const result = await (
+      await controller()
+    ).prepareApiKeyPolicy({
+      organizationId: "org_123",
+      presetId: "FULL_ACCESS",
+    });
+
+    // The critical assertion: absence must never resolve to `{ ok: true }` with
+    // an admin scope. A plugin below the contract cannot mint any credential.
+    expect(result.ok).toBe(false);
+    expect(result).not.toHaveProperty("policy");
+  });
+
+  it("describes a policy as having nothing extra to show", async () => {
+    await expect(
+      (await controller()).describeApiKeyPolicy({ presetId: "TRIGGER_ONLY", scopes: ["read:runs"] })
+    ).resolves.toEqual({});
+  });
+});

internal-packages/rbac/src/index.ts

@@ -1,5 +1,8 @@
 import type {
+  ApiKeyPolicyDescription,
+  ApiKeyPreset,
   Permission,
+  PrepareApiKeyPolicyResult,
   RbacAbility,
   RbacDatabaseConfig,
   Role,
@@ -12,6 +15,18 @@ import type {
 import type { PrismaClient } from "@trigger.dev/database";
 import { RoleBaseAccessFallback } from "./fallback.js";
 export type { RoleBaseAccessController, RbacAbility, RbacResource } from "@trigger.dev/plugins";
+
+/**
+ * The controller surface as the HOST sees it, after LazyController has filled in
+ * defaults for the optional capability methods a plugin may not implement.
+ *
+ * `RoleBaseAccessController` is the *plugin-facing* contract, where capability
+ * extensions are optional so an older plugin still satisfies it. Host code
+ * always talks to the LazyController singleton (`rbac`), which never omits a
+ * method — so host consumers should depend on this type, not on the plugin
+ * contract, and get a total surface without writing their own guards.
+ */
+export type HostRbacController = Required<RoleBaseAccessController>;
 export type { UserActorAuthResult, UserActorClaims } from "@trigger.dev/plugins";
 export { buildJwtAbility, scopesWithinAbility } from "./ability.js";
 export { FULL_ACCESS_PRESET_ID, scopesGrantFullAccess } from "@trigger.dev/plugins";
@@ -215,18 +230,39 @@ class LazyController implements RoleBaseAccessController {
     return (await this.c()).systemRoles(...args);
   }
 
-  async apiKeyPresets(...args: Parameters<RoleBaseAccessController["apiKeyPresets"]>) {
-    return (await this.c()).apiKeyPresets(...args);
+  // The API-key policy methods are optional on the controller contract (see the
+  // note on RoleBaseAccessController) so a plugin compiled against an older OSS
+  // commit still satisfies it. LazyController is where that optional surface is
+  // normalized into a total one: every host caller goes through `rbac`, so the
+  // absent-plugin default lives here once instead of at each call site.
+  async apiKeyPresets(
+    ...args: Parameters<NonNullable<RoleBaseAccessController["apiKeyPresets"]>>
+  ): Promise<ApiKeyPreset[] | null> {
+    const controller = await this.c();
+    // Same meaning as the no-plugin fallback: no catalogue to offer.
+    return controller.apiKeyPresets ? controller.apiKeyPresets(...args) : null;
   }
 
-  async prepareApiKeyPolicy(...args: Parameters<RoleBaseAccessController["prepareApiKeyPolicy"]>) {
-    return (await this.c()).prepareApiKeyPolicy(...args);
+  async prepareApiKeyPolicy(
+    ...args: Parameters<NonNullable<RoleBaseAccessController["prepareApiKeyPolicy"]>>
+  ): Promise<PrepareApiKeyPolicyResult> {
+    const controller = await this.c();
+    if (!controller.prepareApiKeyPolicy) {
+      // Fail closed. A plugin that predates this contract must not be able to
+      // mint a credential — least of all a full-access one — so creation stops
+      // outright. Keys already issued are unaffected: they authorize from the
+      // scopes persisted on their row, compiled by the host bearer resolver.
+      return { ok: false, error: "API key access presets are not available" };
+    }
+    return controller.prepareApiKeyPolicy(...args);
   }
 
   async describeApiKeyPolicy(
-    ...args: Parameters<RoleBaseAccessController["describeApiKeyPolicy"]>
-  ) {
-    return (await this.c()).describeApiKeyPolicy(...args);
+    ...args: Parameters<NonNullable<RoleBaseAccessController["describeApiKeyPolicy"]>>
+  ): Promise<ApiKeyPolicyDescription> {
+    const controller = await this.c();
+    // Presentation only — an undescribed policy renders from its stored scopes.
+    return controller.describeApiKeyPolicy ? controller.describeApiKeyPolicy(...args) : {};
   }
 
   async allPermissions(
@@ -309,7 +345,13 @@ class LazyController implements RoleBaseAccessController {
 class RoleBaseAccess {
   // Synchronous — returns a lazy controller that resolves any installed
   // plugin on first call.
-  create(prisma: RbacPrismaInput, options?: RbacCreateOptions): RoleBaseAccessController {
+  //
+  // Returns HostRbacController, not RoleBaseAccessController: the latter is the
+  // plugin-facing contract whose capability methods are optional, and
+  // LazyController has already substituted defaults for any the installed plugin
+  // omits. Handing back the total surface is what keeps host callers from having
+  // to guard (or, worse, from inventing their own absent-plugin default).
+  create(prisma: RbacPrismaInput, options?: RbacCreateOptions): HostRbacController {
     return new LazyController(prisma, options);
   }
 }

packages/plugins/src/rbac.ts

@@ -470,17 +470,37 @@ export interface RoleBaseAccessController {
   // Plugin-owned API-key policy catalogue and policy generation. A null
   // catalogue means no plugin is installed. The host owns credentials and
   // persists the effective policy returned by prepareApiKeyPolicy().
-  apiKeyPresets(organizationId: string): Promise<ApiKeyPreset[] | null>;
+  //
+  // These three are OPTIONAL, and are the first optional members of this
+  // interface — the distinction is deliberate. Methods the host cannot serve a
+  // request without (authenticateBearer, authenticatePat, authenticateSession)
+  // stay required. Capability extensions the host can degrade past are
+  // optional, so a plugin built against an older contract still satisfies this
+  // interface. That matters because the plugin is compiled against whichever
+  // OSS commit its base image carries: making an additive capability required
+  // turns every such addition into a lockstep two-repo merge, and turns a
+  // plugin rollback into an image build failure instead of a graceful
+  // degradation.
+  //
+  // Absence must fail CLOSED, and each default is chosen so it does:
+  //   - apiKeyPresets       -> null (identical to "no plugin installed")
+  //   - prepareApiKeyPolicy -> { ok: false } — NEVER a full-access default;
+  //                            key creation stops, while already-issued keys
+  //                            keep authorizing from their persisted scopes
+  //   - describeApiKeyPolicy -> {} (presentation only)
+  // LazyController applies these defaults, so host callers going through
+  // `rbac` see a total surface and cannot forget the guard.
+  apiKeyPresets?(organizationId: string): Promise<ApiKeyPreset[] | null>;
   // `presetId` is deliberately required: an authorization function must not
   // have an implicit default, least of all a full-access one. A caller that
   // omits the field should fail to compile rather than silently mint an admin
   // credential. Installs with no preset catalogue pass "FULL_ACCESS".
-  prepareApiKeyPolicy(params: {
+  prepareApiKeyPolicy?(params: {
     organizationId: string;
     presetId: string;
     taskIdentifiers?: string[];
   }): Promise<PrepareApiKeyPolicyResult>;
-  describeApiKeyPolicy(policy: ApiKeyPolicy): Promise<ApiKeyPolicyDescription>;
+  describeApiKeyPolicy?(policy: ApiKeyPolicy): Promise<ApiKeyPolicyDescription>;
 
   // Role introspection. The fallback returns []; a plugin may return
   // its own role catalogue.