feat(webapp): gate billing limits on a dedicated permission (#4073)

## Summary

The billing limits page and the usage-limit banners now require a
dedicated `manage:billing-limits` permission instead of the broader
billing permission. This lets a role be granted control over billing
limits independently of subscription and payment management.

## Details

Both the loader and action of the billing limits settings page check
`manage:billing-limits`. The "Configure billing limit" and "Resolve"
actions in the limit banners (the no-limit-configured, grace, and
rejected states) gate on the same permission. The subscription and
billing pages keep using the existing billing permission.

Author: matt-aitken

apps/webapp/app/components/billing/OrgBanner.tsx

@@ -9,7 +9,7 @@ import {
   useOptionalOrganization,
   useOrganization,
   useBillingLimit,
-  useCanManageBilling,
+  useCanManageBillingLimits,
 } from "~/hooks/useOrganizations";
 import { useOptionalProject, useProject } from "~/hooks/useProject";
 import { useShowSelfServe } from "~/hooks/useShowSelfServe";
@@ -80,8 +80,8 @@ export function OrgBanner() {
 function LimitRejectedBanner() {
   const organization = useOrganization();
   const showSelfServe = useShowSelfServe();
-  const canManageBilling = useCanManageBilling();
-  const canResolve = showSelfServe && canManageBilling;
+  const canManageBillingLimits = useCanManageBillingLimits();
+  const canResolve = showSelfServe && canManageBillingLimits;
 
   return (
     <AnimatedOrgBannerBar
@@ -110,8 +110,8 @@ function LimitGraceBanner() {
   const organization = useOrganization();
   const billingLimit = useBillingLimit();
   const showSelfServe = useShowSelfServe();
-  const canManageBilling = useCanManageBilling();
-  const canResolve = showSelfServe && canManageBilling;
+  const canManageBillingLimits = useCanManageBillingLimits();
+  const canResolve = showSelfServe && canManageBillingLimits;
 
   const graceEndsAt =
     billingLimit?.isConfigured && billingLimit.limitState.status === "grace"
@@ -143,21 +143,21 @@ function LimitGraceBanner() {
 
 function NoLimitConfiguredBanner() {
   const organization = useOrganization();
-  const canManageBilling = useCanManageBilling();
+  const canManageBillingLimits = useCanManageBillingLimits();
 
   return (
     <AnimatedOrgBannerBar
       show
       variant="warning"
       action={
-        canManageBilling ? (
+        canManageBillingLimits ? (
           <LinkButton variant="tertiary/small" to={v3BillingLimitsPath(organization)}>
             Configure billing limit
           </LinkButton>
         ) : undefined
       }
     >
-      {canManageBilling
+      {canManageBillingLimits
         ? "Protect your organization from unexpected usage spikes."
         : "Billing limits are not configured for this organization. Contact an organization administrator to configure them."}
     </AnimatedOrgBannerBar>

apps/webapp/app/hooks/useOrganizations.ts

@@ -96,10 +96,10 @@ export function useBillingLimit(matches?: UIMatch[]) {
   return data?.billingLimit;
 }
 
-export function useCanManageBilling(matches?: UIMatch[]) {
+export function useCanManageBillingLimits(matches?: UIMatch[]) {
   const data = useTypedMatchesData<typeof orgLoader>({
     id: "routes/_app.orgs.$organizationSlug",
     matches,
   });
-  return data?.canManageBilling === true;
+  return data?.canManageBillingLimits === true;
 }

apps/webapp/app/routes/_app.orgs.$organizationSlug.settings.billing-limits/route.tsx

@@ -77,7 +77,7 @@ import {
 
 const billingLimitsAuthorization = {
   action: "manage" as const,
-  resource: { type: "billing" as const },
+  resource: { type: "billing-limits" as const },
 };
 
 export const meta: MetaFunction = () => {

apps/webapp/app/routes/_app.orgs.$organizationSlug/route.tsx

@@ -11,7 +11,7 @@ import { RegionsPresenter, type Region } from "~/presenters/v3/RegionsPresenter.
 import { getImpersonationId } from "~/services/impersonation.server";
 import { getCachedUsage, getBillingLimit, getCurrentPlan } from "~/services/platform.v3.server";
 import { rbac } from "~/services/rbac.server";
-import { canManageBilling } from "~/services/routeBuilders/permissions.server";
+import { canManageBillingLimits } from "~/services/routeBuilders/permissions.server";
 import { requireUser } from "~/services/session.server";
 import { telemetry } from "~/services/telemetry.server";
 import { organizationPath } from "~/utils/pathBuilder";
@@ -124,7 +124,9 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
           .catch(() => [] as Region[])
       : Promise.resolve([] as Region[]),
   ]);
-  const userCanManageBilling = sessionAuth.ok ? canManageBilling(sessionAuth.ability) : false;
+  const userCanManageBillingLimits = sessionAuth.ok
+    ? canManageBillingLimits(sessionAuth.ability)
+    : false;
 
   let hasExceededFreeTier = false;
   let usagePercentage = 0;
@@ -181,7 +183,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
       limit: dashboardLimit,
     },
     widgetLimitPerDashboard,
-    canManageBilling: userCanManageBilling,
+    canManageBillingLimits: userCanManageBillingLimits,
   });
 };
 

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

@@ -19,8 +19,8 @@ export type PermissionCheck =
  * returned booleans are display-only: the route builder's `authorization`
  * block is the real security boundary.
  */
-export function canManageBilling(ability: RbacAbility): boolean {
-  return ability.can("manage", { type: "billing" });
+export function canManageBillingLimits(ability: RbacAbility): boolean {
+  return ability.can("manage", { type: "billing-limits" });
 }
 
 export function checkPermissions<K extends string>(