feat(webapp): add permission-gating primitives

Add checkPermissions(ability, checks) which maps a set of action/resource
checks to a boolean record using the injected ability, so loaders can
compute display-only permission flags server-side and pass them to the
client. Add PermissionButton and PermissionLink wrappers that disable the
underlying control and show an explanatory tooltip when a server-computed
hasPermission flag is false. No permission logic ships to the client; the
route builder authorization block remains the security boundary.

Author: matt-aitken

apps/webapp/app/components/primitives/PermissionButton.tsx

@@ -0,0 +1,36 @@
+import { forwardRef, type ReactNode } from "react";
+import { Button } from "./Buttons";
+
+export const DEFAULT_NO_PERMISSION_TOOLTIP = "You don't have permission to do this";
+
+type PermissionButtonProps = React.ComponentProps<typeof Button> & {
+  /** Server-computed flag (see `checkPermissions`). When false the button is disabled with a tooltip. */
+  hasPermission: boolean;
+  noPermissionTooltip?: ReactNode;
+};
+
+/**
+ * A `Button` that disables itself and shows an explanatory tooltip when the
+ * user lacks permission. Display only — the server route builder's
+ * `authorization` block is the real gate. `Button` already renders its
+ * `tooltip` while disabled (it wraps the disabled button in a hoverable span),
+ * so we reuse that path.
+ */
+export const PermissionButton = forwardRef<HTMLButtonElement, PermissionButtonProps>(
+  ({ hasPermission, noPermissionTooltip, disabled, tooltip, ...props }, ref) => {
+    if (hasPermission) {
+      return <Button ref={ref} disabled={disabled} tooltip={tooltip} {...props} />;
+    }
+
+    return (
+      <Button
+        ref={ref}
+        {...props}
+        disabled
+        tooltip={noPermissionTooltip ?? DEFAULT_NO_PERMISSION_TOOLTIP}
+      />
+    );
+  }
+);
+
+PermissionButton.displayName = "PermissionButton";

apps/webapp/app/components/primitives/PermissionLink.tsx

@@ -0,0 +1,43 @@
+import { type ReactNode } from "react";
+import { cn } from "~/utils/cn";
+import { ButtonContent, type ButtonContentPropsType, LinkButton } from "./Buttons";
+import { SimpleTooltip } from "./Tooltip";
+import { DEFAULT_NO_PERMISSION_TOOLTIP } from "./PermissionButton";
+
+type PermissionLinkProps = React.ComponentProps<typeof LinkButton> & {
+  /** Server-computed flag (see `checkPermissions`). When false the link is disabled with a tooltip. */
+  hasPermission: boolean;
+  noPermissionTooltip?: ReactNode;
+};
+
+/**
+ * A `LinkButton` that disables itself and shows an explanatory tooltip when the
+ * user lacks permission. Display only — the server route builder's
+ * `authorization` block is the real gate. Unlike `Button`, `LinkButton` has no
+ * tooltip support and renders a `pointer-events-none` element when disabled
+ * (which can't be hovered), so the denied state renders a `SimpleTooltip`
+ * around a non-interactive `ButtonContent` instead — the same pattern the team
+ * settings page uses for its gated controls.
+ */
+export function PermissionLink({
+  hasPermission,
+  noPermissionTooltip,
+  ...props
+}: PermissionLinkProps) {
+  if (hasPermission) {
+    return <LinkButton {...props} />;
+  }
+
+  return (
+    <SimpleTooltip
+      button={
+        <ButtonContent
+          {...(props as ButtonContentPropsType)}
+          className={cn(props.className, "cursor-not-allowed opacity-50")}
+        />
+      }
+      content={noPermissionTooltip ?? DEFAULT_NO_PERMISSION_TOOLTIP}
+      disableHoverableContent
+    />
+  );
+}

apps/webapp/app/services/routeBuilders/permissions.server.ts

@@ -0,0 +1,33 @@
+import type { RbacAbility, RbacResource } from "@trigger.dev/rbac";
+
+/**
+ * A single permission check, mirroring the `authorization` option the
+ * dashboard/api route builders accept: either a super-user check or an
+ * action + resource(s) pair.
+ */
+export type PermissionCheck =
+  | { requireSuper: true }
+  | { action: string; resource: RbacResource | RbacResource[] };
+
+/**
+ * Evaluate a set of permission checks against an already-resolved `ability`
+ * and return a plain boolean map for the client to gate UI on.
+ *
+ * The matching lives entirely in the injected ability — permissive by
+ * default, and fully enforced when an RBAC plugin is installed — so this only
+ * calls `can`/`canSuper` and no permission-model logic lives here. The
+ * returned booleans are display-only: the route builder's `authorization`
+ * block is the real security boundary.
+ */
+export function checkPermissions<K extends string>(
+  ability: RbacAbility,
+  checks: Record<K, PermissionCheck>
+): Record<K, boolean> {
+  const result = {} as Record<K, boolean>;
+  for (const key in checks) {
+    const check = checks[key];
+    result[key] =
+      "requireSuper" in check ? ability.canSuper() : ability.can(check.action, check.resource);
+  }
+  return result;
+}

apps/webapp/test/checkPermissions.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import type { RbacAbility } from "@trigger.dev/rbac";
+import { checkPermissions } from "~/services/routeBuilders/permissions.server";
+
+const permissive: RbacAbility = { can: () => true, canSuper: () => false };
+const denyAll: RbacAbility = { can: () => false, canSuper: () => false };
+
+describe("checkPermissions", () => {
+  it("returns true for every check under a permissive ability (OSS path)", () => {
+    const result = checkPermissions(permissive, {
+      canCancelRun: { action: "write", resource: { type: "runs" } },
+      canManageMembers: { action: "manage", resource: { type: "members" } },
+    });
+
+    expect(result).toEqual({ canCancelRun: true, canManageMembers: true });
+  });
+
+  it("returns false for every check under a deny-all ability", () => {
+    const result = checkPermissions(denyAll, {
+      canCancelRun: { action: "write", resource: { type: "runs" } },
+    });
+
+    expect(result).toEqual({ canCancelRun: false });
+  });
+
+  it("evaluates each check independently against can()", () => {
+    const ability: RbacAbility = {
+      can: (action, resource) => {
+        const r = Array.isArray(resource) ? resource[0] : resource;
+        return action === "read" || r.type === "tasks";
+      },
+      canSuper: () => false,
+    };
+
+    const result = checkPermissions(ability, {
+      readRuns: { action: "read", resource: { type: "runs" } },
+      writeRuns: { action: "write", resource: { type: "runs" } },
+      writeTasks: { action: "write", resource: { type: "tasks" } },
+    });
+
+    expect(result).toEqual({ readRuns: true, writeRuns: false, writeTasks: true });
+  });
+
+  it("supports requireSuper checks via canSuper()", () => {
+    const admin: RbacAbility = { can: () => false, canSuper: () => true };
+
+    expect(checkPermissions(admin, { adminOnly: { requireSuper: true } })).toEqual({
+      adminOnly: true,
+    });
+    expect(checkPermissions(denyAll, { adminOnly: { requireSuper: true } })).toEqual({
+      adminOnly: false,
+    });
+  });
+
+  it("passes resource arrays straight through to can()", () => {
+    const seen: unknown[] = [];
+    const ability: RbacAbility = {
+      can: (_action, resource) => {
+        seen.push(resource);
+        return true;
+      },
+      canSuper: () => false,
+    };
+
+    checkPermissions(ability, {
+      x: { action: "read", resource: [{ type: "runs" }, { type: "tasks" }] },
+    });
+
+    expect(seen[0]).toEqual([{ type: "runs" }, { type: "tasks" }]);
+  });
+});