fix(billing): withhold the payer credit pool from v2 status readers

`GET /api/v2/billing/status` resolved the workspace's payer and projected
that payer's pooled allowances — credits used, credit limit, credits
remaining, and the payer entity's storage usage and quota — to any caller
holding only `read` on the workspace, including a personal API key. The
payer pool is shared across every workspace that payer funds, and the
platform already treats it as privileged: the workspace credit-availability
surface computes `canViewPayerPool` from `canManageWorkspaceBilling` and
substitutes member-scoped or null figures for everyone else. The new
versioned endpoint had no equivalent gate.

`credits` and `storage` are now projected only to a caller who may manage
the resolved payer's billing: the billed account holder of a personally
hosted workspace, an admin of the hosting organization, or a workspace API
key, which only a workspace admin can provision. The endpoint stays at
`read` so a plain member keeps the plan, period, and standing the workspace
UI already shows them, and an exceeded pooled limit still reports as
`limit_exceeded` without disclosing the numbers behind it. Both fields are
nullable on the wire and in the regenerated OpenAPI spec.

The decision lives in the application use case, resolved from canonical
workspace state, not in the route: billing authority is payer identity and
organization role, which the workspace permission ladder cannot express —
a plain workspace `admin` is deliberately not enough.

Author: waleedlatif1

apps/docs/openapi-v2-billing.json

@@ -36,7 +36,7 @@
       "get": {
         "operationId": "getBillingStatus",
         "summary": "Get Billing Status",
-        "description": "Return the current plan, billing standing, credit allowance, and storage quota. Billing history lives at `GET /api/v2/billing/logs`. Without a Stripe subscription — notably on the free plan — there is no real billing period: `period` is the open interval 1970-01-01 to 9999-12-31 and `credits.used` is lifetime consumption, not consumption since a period start.",
+        "description": "Return the current plan, billing standing, credit allowance, and storage quota. `credits` and `storage` report the payer's pooled allowances and are null unless the caller can manage that payer's billing. Billing history lives at `GET /api/v2/billing/logs`. Without a Stripe subscription — notably on the free plan — there is no real billing period: `period` is the open interval 1970-01-01 to 9999-12-31 and `credits.used` is lifetime consumption, not consumption since a period start.",
         "tags": ["Billing"],
         "parameters": [
           {
@@ -543,47 +543,61 @@
             "description": "Current billing standing."
           },
           "credits": {
-            "type": "object",
-            "properties": {
-              "used": {
-                "type": "number",
-                "description": "Credits consumed so far. The counter is reset by Stripe invoice webhooks, so on a paid plan it covers the current billing period; on the free plan nothing resets it and the value is lifetime consumption."
-              },
-              "limit": {
-                "type": "number",
-                "description": "Credit allowance for the reporting window — per billing period on a paid plan, lifetime on the free plan."
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "used": {
+                    "type": "number",
+                    "description": "Credits consumed so far. The counter is reset by Stripe invoice webhooks, so on a paid plan it covers the current billing period; on the free plan nothing resets it and the value is lifetime consumption."
+                  },
+                  "limit": {
+                    "type": "number",
+                    "description": "Credit allowance for the reporting window — per billing period on a paid plan, lifetime on the free plan."
+                  },
+                  "remaining": {
+                    "type": "number",
+                    "description": "Allowance minus consumption, over the same window."
+                  }
+                },
+                "required": ["used", "limit", "remaining"],
+                "additionalProperties": false
               },
-              "remaining": {
-                "type": "number",
-                "description": "Allowance minus consumption, over the same window."
+              {
+                "type": "null"
               }
-            },
-            "required": ["used", "limit", "remaining"],
-            "additionalProperties": false,
-            "description": "Credit usage and allowance. Periodic on a paid plan; lifetime on the free plan, where the counter never resets."
+            ],
+            "description": "The payer's credit usage and allowance — periodic on a paid plan, lifetime on the free plan, where the counter never resets. Null when the caller cannot manage that payer's billing."
           },
           "storage": {
-            "type": "object",
-            "properties": {
-              "usedBytes": {
-                "type": "number",
-                "minimum": 0,
-                "description": "Storage currently consumed, in bytes."
-              },
-              "limitBytes": {
-                "type": "number",
-                "minimum": 0,
-                "description": "Storage quota, in bytes."
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "usedBytes": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Storage currently consumed, in bytes."
+                  },
+                  "limitBytes": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Storage quota, in bytes."
+                  },
+                  "percentUsed": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Percentage of the storage quota consumed."
+                  }
+                },
+                "required": ["usedBytes", "limitBytes", "percentUsed"],
+                "additionalProperties": false
               },
-              "percentUsed": {
-                "type": "number",
-                "minimum": 0,
-                "description": "Percentage of the storage quota consumed."
+              {
+                "type": "null"
               }
-            },
-            "required": ["usedBytes", "limitBytes", "percentUsed"],
-            "additionalProperties": false,
-            "description": "Current storage consumption and quota."
+            ],
+            "description": "The payer's storage consumption and quota, or null when the caller cannot manage that payer's billing."
           }
         },
         "required": ["workspaceId", "period", "plan", "status", "credits", "storage"],

apps/sim/app/api/v2/billing/status/route.test.ts

@@ -69,6 +69,17 @@ describe('GET /api/v2/billing/status', () => {
     expect(response.headers.get('x-ratelimit-limit')).toBe('100')
   })
 
+  it('serializes a withheld payer pool as null without failing response validation', async () => {
+    mocks.execute.mockResolvedValueOnce({ ...result, credits: null, storage: null })
+
+    const response = await GET(
+      new NextRequest('http://localhost:3000/api/v2/billing/status?workspaceId=workspace-1')
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ data: { ...result, credits: null, storage: null } })
+  })
+
   it('projects typed workspace-policy errors', async () => {
     mocks.execute.mockRejectedValueOnce(
       new OrchestrationError('forbidden', 'API key is not authorized for this workspace')

apps/sim/lib/api/contracts/v2/billing.ts

@@ -35,6 +35,14 @@ export const v2BillingStatusQuerySchema = z.object({
 /**
  * Current billing standing, credit allowance, and storage quota. Ledger rows
  * and source analytics deliberately live outside this status resource.
+ *
+ * `credits` and `storage` report the resolved payer's pooled allowances, which
+ * are shared across every workspace that payer funds. They are populated only
+ * for a caller who may manage that payer's billing — the billed account
+ * holder, an admin of the hosting organization, or a workspace API key, which
+ * an admin of that workspace provisioned. Any other workspace member reads
+ * both as `null` while still seeing the plan, period, and standing that the
+ * workspace already surfaces to them.
  */
 export const v2BillingStatusDataSchema = z
   .object({
@@ -78,16 +86,20 @@ export const v2BillingStatusDataSchema = z
           ),
         remaining: z.number().describe('Allowance minus consumption, over the same window.'),
       })
+      .nullable()
       .describe(
-        'Credit usage and allowance. Periodic on a paid plan; lifetime on the free plan, where the counter never resets.'
+        "The payer's credit usage and allowance — periodic on a paid plan, lifetime on the free plan, where the counter never resets. Null when the caller cannot manage that payer's billing."
       ),
     storage: z
       .object({
         usedBytes: z.number().nonnegative().describe('Storage currently consumed, in bytes.'),
         limitBytes: z.number().nonnegative().describe('Storage quota, in bytes.'),
         percentUsed: z.number().nonnegative().describe('Percentage of the storage quota consumed.'),
       })
-      .describe('Current storage consumption and quota.'),
+      .nullable()
+      .describe(
+        "The payer's storage consumption and quota, or null when the caller cannot manage that payer's billing."
+      ),
   })
   .meta({
     id: 'V2BillingStatus',

apps/sim/lib/api/contracts/v2/openapi/billing.ts

@@ -80,7 +80,7 @@ const routes = [
       operationId: 'getBillingStatus',
       summary: 'Get Billing Status',
       description:
-        'Return the current plan, billing standing, credit allowance, and storage quota. Billing history lives at `GET /api/v2/billing/logs`. Without a Stripe subscription — notably on the free plan — there is no real billing period: `period` is the open interval 1970-01-01 to 9999-12-31 and `credits.used` is lifetime consumption, not consumption since a period start.',
+        "Return the current plan, billing standing, credit allowance, and storage quota. `credits` and `storage` report the payer's pooled allowances and are null unless the caller can manage that payer's billing. Billing history lives at `GET /api/v2/billing/logs`. Without a Stripe subscription — notably on the free plan — there is no real billing period: `period` is the open interval 1970-01-01 to 9999-12-31 and `credits.used` is lifetime consumption, not consumption since a period start.",
       errors: [...WORKSPACE_ERRORS, 'NotFound'],
       success: { description: 'The current billing and storage status.' },
     }),

apps/sim/lib/billing/application/billing-use-cases.test.ts

@@ -24,6 +24,11 @@ const mocks = vi.hoisted(() => ({
   getUsageLogs: vi.fn(),
   getWorkspaceUsageLogs: vi.fn(),
   recordAudit: vi.fn(),
+  canManageWorkspaceBilling: vi.fn(),
+}))
+
+vi.mock('@/lib/billing/core/workspace-billing-authority', () => ({
+  canUserManageWorkspaceBilling: mocks.canManageWorkspaceBilling,
 }))
 
 vi.mock('@/lib/workspaces/application/workspace-context', () => ({
@@ -94,6 +99,7 @@ describe('billing application use cases', () => {
     vi.clearAllMocks()
     mocks.loadWorkspace.mockResolvedValue(workspaceContext)
     mocks.resolvePermission.mockResolvedValue('read')
+    mocks.canManageWorkspaceBilling.mockResolvedValue(false)
     mocks.checkUsageStatus.mockResolvedValue({ currentUsage: 1, limit: 10, isExceeded: false })
     mocks.checkAttributedBlocks.mockResolvedValue({ blocked: false })
     mocks.toUsageLimitSubscription.mockReturnValue(null)
@@ -173,6 +179,88 @@ describe('billing application use cases', () => {
     expect(mocks.recordAudit).not.toHaveBeenCalled()
   })
 
+  it('withholds the payer pool from a workspace member who cannot manage billing', async () => {
+    mocks.resolvePermission.mockResolvedValue('read')
+    mocks.canManageWorkspaceBilling.mockResolvedValue(false)
+
+    const result = await getBillingStatus.execute({
+      principal: personalPrincipal,
+      input: { workspaceId: 'workspace-1' },
+    })
+
+    expect(result.credits).toBeNull()
+    expect(result.storage).toBeNull()
+    expect(result).toMatchObject({ workspaceId: 'workspace-1', plan: 'free', status: 'active' })
+    expect(mocks.canManageWorkspaceBilling).toHaveBeenCalledWith(workspaceContext, 'user-1')
+  })
+
+  it('withholds the payer pool from a workspace admin who cannot manage billing', async () => {
+    mocks.resolvePermission.mockResolvedValue('admin')
+    mocks.canManageWorkspaceBilling.mockResolvedValue(false)
+
+    const result = await getBillingStatus.execute({
+      principal: personalPrincipal,
+      input: { workspaceId: 'workspace-1' },
+    })
+
+    expect(result.credits).toBeNull()
+    expect(result.storage).toBeNull()
+  })
+
+  it('still reports an exceeded payer limit without disclosing the pool', async () => {
+    mocks.canManageWorkspaceBilling.mockResolvedValue(false)
+    mocks.checkUsageStatus.mockResolvedValue({ currentUsage: 40, limit: 10, isExceeded: true })
+
+    const result = await getBillingStatus.execute({
+      principal: personalPrincipal,
+      input: { workspaceId: 'workspace-1' },
+    })
+
+    expect(result.status).toBe('limit_exceeded')
+    expect(result.credits).toBeNull()
+  })
+
+  it('projects the payer pool to a member who can manage billing', async () => {
+    mocks.canManageWorkspaceBilling.mockResolvedValue(true)
+
+    const result = await getBillingStatus.execute({
+      principal: personalPrincipal,
+      input: { workspaceId: 'workspace-1' },
+    })
+
+    expect(result.credits).toEqual({ used: 200, limit: 2_000, remaining: 1_800 })
+    expect(result.storage).toEqual({
+      usedBytes: 5_242_880,
+      limitBytes: 1_073_741_824,
+      percentUsed: 0.48828125,
+    })
+  })
+
+  it('never consults human billing authority for a workspace key', async () => {
+    const result = await getBillingStatus.execute({ principal: workspacePrincipal, input: {} })
+
+    expect(result.credits).not.toBeNull()
+    expect(mocks.canManageWorkspaceBilling).not.toHaveBeenCalled()
+  })
+
+  it('always reports the account-scoped pool the caller owns', async () => {
+    mocks.canManageWorkspaceBilling.mockResolvedValue(false)
+    mocks.getSubscription.mockResolvedValue({ plan: 'pro' })
+    mocks.deriveBillingContext.mockReturnValue({
+      billingEntity: { type: 'user', id: 'user-1' },
+      billingPeriod: {
+        start: new Date('2026-01-01T00:00:00Z'),
+        end: new Date('2026-02-01T00:00:00Z'),
+      },
+    })
+    mocks.checkBillingBlocked.mockResolvedValue({ blocked: false })
+
+    const result = await getBillingStatus.execute({ principal: personalPrincipal, input: {} })
+
+    expect(result.credits).toEqual({ used: 200, limit: 2_000, remaining: 1_800 })
+    expect(result.storage).not.toBeNull()
+  })
+
   it('uses the personal principal as account authority', async () => {
     mocks.getSubscription.mockResolvedValue({ plan: 'pro' })
     mocks.deriveBillingContext.mockReturnValue({

apps/sim/lib/billing/application/get-billing-status.ts

@@ -13,6 +13,7 @@ import {
 } from '@/lib/billing/core/billing-attribution'
 import { getHighestPrioritySubscription } from '@/lib/billing/core/subscription'
 import { deriveBillingContext } from '@/lib/billing/core/usage-log'
+import { canUserManageWorkspaceBilling } from '@/lib/billing/core/workspace-billing-authority'
 import { dollarsToCredits } from '@/lib/billing/credits/conversion'
 import {
   getStorageLimitForBillingContext,
@@ -26,16 +27,35 @@ export interface GetBillingStatusInput {
   workspaceId?: string
 }
 
+export interface BillingCreditsStatus {
+  used: number
+  limit: number
+  remaining: number
+}
+
+export interface BillingStorageStatus {
+  usedBytes: number
+  limitBytes: number
+  percentUsed: number
+}
+
+/**
+ * `credits` and `storage` describe the resolved payer's pooled allowances, not
+ * the caller's own consumption, so they are only projected to a caller who may
+ * manage that payer's billing. Every other workspace member reads them as
+ * `null` while still seeing the plan and standing the workspace UI already
+ * shows them.
+ */
 export interface BillingStatusResult {
   workspaceId: string | null
   period: { start: string; end: string }
   plan: string
   status: 'active' | 'limit_exceeded' | 'billing_blocked'
-  credits: { used: number; limit: number; remaining: number }
-  storage: { usedBytes: number; limitBytes: number; percentUsed: number }
+  credits: BillingCreditsStatus | null
+  storage: BillingStorageStatus | null
 }
 
-function storageStatus(usedBytes: number, limitBytes: number): BillingStatusResult['storage'] {
+function storageStatus(usedBytes: number, limitBytes: number): BillingStorageStatus {
   return {
     usedBytes,
     limitBytes,
@@ -48,14 +68,17 @@ export const getBillingStatus = defineAuthorizedBillingReadUseCase({
   requestedWorkspaceId: (input: GetBillingStatusInput) => input.workspaceId,
   execute: async ({ principal, scope }): Promise<BillingStatusResult> => {
     if (scope.kind === 'workspace') {
-      const [attribution, storageContext] = await Promise.all([
+      const [attribution, storageContext, canViewPayerPool] = await Promise.all([
         principal.kind === 'personal_api_key'
           ? resolveBillingAttribution({
               actorUserId: principal.userId,
               workspaceId: scope.workspace.workspaceId,
             })
           : resolveSystemBillingAttribution(scope.workspace.workspaceId),
         resolveStorageBillingContext(scope.workspace.workspaceId),
+        principal.kind === 'personal_api_key'
+          ? canUserManageWorkspaceBilling(scope.workspace, principal.userId)
+          : Promise.resolve(true),
       ])
       const [usage, block, storageUsedBytes] = await Promise.all([
         checkUsageStatus(attribution.billedAccountUserId, toUsageLimitSubscription(attribution)),
@@ -68,12 +91,14 @@ export const getBillingStatus = defineAuthorizedBillingReadUseCase({
         period: attribution.billingPeriod,
         plan: attribution.payerSubscription?.plan ?? 'free',
         status: block.blocked ? 'billing_blocked' : usage.isExceeded ? 'limit_exceeded' : 'active',
-        credits: {
-          used: dollarsToCredits(usage.currentUsage),
-          limit: dollarsToCredits(usage.limit),
-          remaining: dollarsToCredits(usage.limit - usage.currentUsage),
-        },
-        storage: storageStatus(storageUsedBytes, storageLimitBytes),
+        credits: canViewPayerPool
+          ? {
+              used: dollarsToCredits(usage.currentUsage),
+              limit: dollarsToCredits(usage.limit),
+              remaining: dollarsToCredits(usage.limit - usage.currentUsage),
+            }
+          : null,
+        storage: canViewPayerPool ? storageStatus(storageUsedBytes, storageLimitBytes) : null,
       }
     }