fix(billing): deny the payer pool to actor-less workspace API keys

The first pass gated `credits` and `storage` on billing authority for
personal API keys but let a `workspace_api_key` principal through
unconditionally, which left the excluded role a way back in. Any workspace
`admin` may mint a workspace API key, and a workspace `admin` is
deliberately not a billing manager, so an admin who reads `null` as
themselves could mint a key and read the full pool with it. On an
organization-hosted workspace that pool is the organization's, spanning
workspaces the admin has no standing in.

Billing authority is payer identity or an organization admin role — a
property of a person. A workspace API key is deliberately actor-less, so it
can never satisfy it and now reads both fields as `null`. Attributing the
key to its creator was rejected: it would launder the same workspace-admin
role, it breaks when the creator's authority is revoked while the key lives
on, and substituting a key's owner for the acting principal is what the
application operation boundary forbids. The reasoning sits in TSDoc at the
decision point.

The key keeps the plan, period, and standing it needs to monitor a
workspace, including `limit_exceeded` and `billing_blocked`. No in-repo
caller reads `credits` or `storage` from this endpoint. The payer storage
pool is now read only once disclosure is authorized, so a caller who may
not see it no longer triggers the query at all.

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. `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.",
+        "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; they are always null for a workspace API key. 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": [
           {
@@ -567,7 +567,7 @@
                 "type": "null"
               }
             ],
-            "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."
+            "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. Always null for a workspace API key."
           },
           "storage": {
             "anyOf": [
@@ -597,7 +597,7 @@
                 "type": "null"
               }
             ],
-            "description": "The payer's storage consumption and quota, or null when the caller cannot manage that payer's billing."
+            "description": "The payer's storage consumption and quota, or null when the caller cannot manage that payer's billing. Always null for a workspace API key."
           }
         },
         "required": ["workspaceId", "period", "plan", "status", "credits", "storage"],

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

@@ -38,11 +38,12 @@ export const v2BillingStatusQuerySchema = z.object({
  *
  * `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.
+ * for a caller who may manage that payer's billing: the billed account holder,
+ * or an admin of the hosting organization. Billing authority is a property of
+ * a person, so an actor-less workspace API key never qualifies. Every other
+ * caller reads both as `null` while still seeing the plan, period, and
+ * standing that the workspace already surfaces to them — enough to monitor for
+ * `limit_exceeded` and `billing_blocked`.
  */
 export const v2BillingStatusDataSchema = z
   .object({
@@ -88,7 +89,7 @@ export const v2BillingStatusDataSchema = z
       })
       .nullable()
       .describe(
-        "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."
+        "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. Always null for a workspace API key."
       ),
     storage: z
       .object({
@@ -98,7 +99,7 @@ export const v2BillingStatusDataSchema = z
       })
       .nullable()
       .describe(
-        "The payer's storage consumption and quota, or null when the caller cannot manage that payer's billing."
+        "The payer's storage consumption and quota, or null when the caller cannot manage that payer's billing. Always null for a workspace API key."
       ),
   })
   .meta({

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. `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.",
+        "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; they are always null for a workspace API key. 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

@@ -167,18 +167,53 @@ describe('billing application use cases', () => {
     })
 
     expect(result.workspaceId).toBe('workspace-1')
-    expect(result.storage).toEqual({
-      usedBytes: 5_242_880,
-      limitBytes: 1_073_741_824,
-      percentUsed: 0.48828125,
-    })
+    expect(result).toMatchObject({ plan: 'free', status: 'active' })
     expect(mocks.resolveSystemAttribution).toHaveBeenCalledWith('workspace-1')
-    expect(mocks.resolveStorageContext).toHaveBeenCalledWith('workspace-1')
     expect(mocks.resolvePermission).not.toHaveBeenCalled()
     expect(mocks.resolveAttribution).not.toHaveBeenCalled()
     expect(mocks.recordAudit).not.toHaveBeenCalled()
   })
 
+  /**
+   * A workspace API key is actor-less, and any workspace `admin` may mint one,
+   * so granting it the pool would launder the exact role the projection
+   * excludes — across the whole organization on an organization-hosted
+   * workspace.
+   */
+  it('withholds the payer pool from an actor-less workspace key', async () => {
+    const result = await getBillingStatus.execute({
+      principal: workspacePrincipal,
+      input: {},
+    })
+
+    expect(result.credits).toBeNull()
+    expect(result.storage).toBeNull()
+    expect(mocks.canManageWorkspaceBilling).not.toHaveBeenCalled()
+  })
+
+  it('never reads the payer storage pool it may not disclose', async () => {
+    await getBillingStatus.execute({ principal: workspacePrincipal, input: {} })
+    await getBillingStatus.execute({
+      principal: personalPrincipal,
+      input: { workspaceId: 'workspace-1' },
+    })
+
+    expect(mocks.resolveStorageContext).not.toHaveBeenCalled()
+    expect(mocks.getStorageUsageForContext).not.toHaveBeenCalled()
+  })
+
+  it('still reports a workspace key an exceeded pooled limit it cannot read', async () => {
+    mocks.checkAttributedBlocks.mockResolvedValue({ blocked: true })
+
+    const result = await getBillingStatus.execute({
+      principal: workspacePrincipal,
+      input: {},
+    })
+
+    expect(result.status).toBe('billing_blocked')
+    expect(result.credits).toBeNull()
+  })
+
   it('withholds the payer pool from a workspace member who cannot manage billing', async () => {
     mocks.resolvePermission.mockResolvedValue('read')
     mocks.canManageWorkspaceBilling.mockResolvedValue(false)
@@ -236,13 +271,6 @@ describe('billing application use cases', () => {
     })
   })
 
-  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' })

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

@@ -1,5 +1,5 @@
 import { defineAuthorizedBillingReadUseCase } from '@/lib/billing/application/authorized-billing-read-use-case'
-import { billingOperations } from '@/lib/billing/application/operations'
+import { type BillingReadPrincipal, billingOperations } from '@/lib/billing/application/operations'
 import {
   checkBillingBlocked,
   checkBillingEntityBlocked,
@@ -13,7 +13,10 @@ 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 {
+  canUserManageWorkspaceBilling,
+  type WorkspaceBillingAuthorityContext,
+} from '@/lib/billing/core/workspace-billing-authority'
 import { dollarsToCredits } from '@/lib/billing/credits/conversion'
 import {
   getStorageLimitForBillingContext,
@@ -42,9 +45,9 @@ export interface BillingStorageStatus {
 /**
  * `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.
+ * manage that payer's billing — see {@link canReadPayerPool}. Every other
+ * caller reads them as `null` while still seeing the plan and standing the
+ * workspace UI already shows them.
  */
 export interface BillingStatusResult {
   workspaceId: string | null
@@ -63,29 +66,63 @@ function storageStatus(usedBytes: number, limitBytes: number): BillingStorageSta
   }
 }
 
+/**
+ * Resolves whether a caller may read the resolved payer's pooled allowances.
+ *
+ * Only a human principal can hold billing authority: it is payer identity, or
+ * an admin role in the hosting organization, and never a workspace role. A
+ * workspace API key is deliberately actor-less — `WorkspaceApiKeyPrincipal`
+ * carries a key and a workspace but no user — so there is no identity to
+ * evaluate that authority against, and it is therefore never a billing
+ * manager.
+ *
+ * Attributing the key to whoever created it would close the gap on paper and
+ * open a worse one. Any workspace `admin` may mint a workspace key, and a
+ * workspace `admin` is not a billing manager, so the key would launder exactly
+ * the role this projection excludes. The pool is the payer's, not the
+ * workspace's — organization-wide on an organization-hosted workspace — so it
+ * spans workspaces that admin has no standing in at all. Substituting a key's
+ * owner for the acting principal is also what the application operation
+ * boundary forbids outright, and the creator's authority can be revoked while
+ * the key keeps working.
+ *
+ * A workspace key still reads the plan, period, and standing it needs to
+ * monitor the workspace, including `limit_exceeded` and `billing_blocked`.
+ */
+function canReadPayerPool(
+  principal: BillingReadPrincipal,
+  workspace: WorkspaceBillingAuthorityContext
+): Promise<boolean> {
+  if (principal.kind !== 'personal_api_key') return Promise.resolve(false)
+  return canUserManageWorkspaceBilling(workspace, principal.userId)
+}
+
+/** Reads the payer's storage pool. Only called once disclosure is authorized. */
+async function resolvePayerStorage(workspaceId: string): Promise<BillingStorageStatus> {
+  const storageContext = await resolveStorageBillingContext(workspaceId)
+  const usedBytes = await getStorageUsageForBillingContext(storageContext)
+  return storageStatus(usedBytes, getStorageLimitForBillingContext(storageContext))
+}
+
 export const getBillingStatus = defineAuthorizedBillingReadUseCase({
   operation: billingOperations.readStatus,
   requestedWorkspaceId: (input: GetBillingStatusInput) => input.workspaceId,
   execute: async ({ principal, scope }): Promise<BillingStatusResult> => {
     if (scope.kind === 'workspace') {
-      const [attribution, storageContext, canViewPayerPool] = await Promise.all([
+      const [attribution, 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),
+        canReadPayerPool(principal, scope.workspace),
       ])
-      const [usage, block, storageUsedBytes] = await Promise.all([
+      const [usage, block, storage] = await Promise.all([
         checkUsageStatus(attribution.billedAccountUserId, toUsageLimitSubscription(attribution)),
         checkAttributedBillingBlocks(attribution),
-        getStorageUsageForBillingContext(storageContext),
+        canViewPayerPool ? resolvePayerStorage(scope.workspace.workspaceId) : null,
       ])
-      const storageLimitBytes = getStorageLimitForBillingContext(storageContext)
       return {
         workspaceId: scope.workspace.workspaceId,
         period: attribution.billingPeriod,
@@ -98,7 +135,7 @@ export const getBillingStatus = defineAuthorizedBillingReadUseCase({
               remaining: dollarsToCredits(usage.limit - usage.currentUsage),
             }
           : null,
-        storage: canViewPayerPool ? storageStatus(storageUsedBytes, storageLimitBytes) : null,
+        storage,
       }
     }