fix(billing): withhold the payer credit and storage pools from callers who cannot manage billing

[waleedlatif1]

Stacked on #6565 → #6560. Review only this PR's own commits; merge after its parents.

GET /api/v2/billing/status returned the resolved payer's pooled credits (used/limit/remaining) and storage to any caller holding only read on the workspace.

On an org-hosted workspace resolveStorageBillingContext resolves the payer entity, so storage is organization-wide across every workspace that org funds — not workspace-scoped.

Baseline note

v2 billing does not exist on origin/main, so "main gated this route" is literally false. But main's analogous surface deliberately gated the same data: workspaces/[id]/credit-availability passes canViewPayerPool: canManageWorkspaceBilling(...) into getWorkspaceCreditAvailability, which substitutes a member-scoped or null figure otherwise. No route on main ever returned a payer's pool to a non-billing-manager.

plan, period, status, and workspaceId were not newly exposed — workspaces/[id]/host-context already surfaces the payer's rolled-up plan to every workspace viewer. Those stay.

Why concealment rather than a role gate

Billing authority is not a workspace role: it is billedAccountUserId === userId, or org admin. defineWorkspaceOperation caps workspace API keys at write, and a workspace admin is deliberately not a billing manager, so no minimumRole expresses the policy. The endpoint stays at read; the use case projects the two pool objects only to an authorized caller. The route is untouched — no role check moved into the adapter.

Workspace API keys are excluded

An actor-less workspace_api_key has no user to evaluate, and POST /api/workspaces/[id]/api-keys requires only workspace admin — a freely grantable collaborator permission. Treating such keys as billing managers would let a non-billing-manager admin mint a key and read the org-wide pool. Attributing the key to its creator is ruled out by CLAUDE.md: "Never substitute a billing owner, uploader, creator, or API-key owner for the acting principal" — and is independently unsound, since the creator's authority can be revoked while the key keeps working.

Keys keep plan, period, status, workspaceId, which covers limit_exceeded / billing_blocked alerting. No in-repo consumer reads credits/storage (checked packages/ts-sdk, all of apps, docs).

Also

The org-wide storage query now runs only after disclosure is authorized; previously it executed for every caller and the result was discarded.

credits and storage are now .nullable() in the contract with descriptions stating why; OpenAPI regenerated. One existing test asserted the old leak and was corrected.

Reverting the guard turns 6 tests red across both the human and workspace-key paths. type-check · biome · 553 tests · check:api-validation · check:openapi — all pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 11, 2026 11:31pm

[cursor]

PR Summary

High Risk
Changes authorization for billing pool disclosure — previously leaked organization-wide credit and storage allowances to any workspace reader or API key. Correctness of the new gate is security-critical.

Overview
Closes a billing data leak on GET /api/v2/billing/status: credits and storage now return only for callers who can manage the resolved payer's billing. Everyone else — including all workspace API keys — gets null, while still receiving plan, period, and status for limit monitoring.

Adds server-side canUserManageWorkspaceBilling (org admin/owner, or billed account holder on personal workspaces). Workspace roles alone are not enough. Storage pool queries now run only after disclosure is authorized.

Makes credits and storage nullable in the v2 contract and OpenAPI docs.

^{Reviewed by Cursor Bugbot for commit 79a3486. Configure here.}

[greptile-apps]

Greptile Summary

This PR prevents callers without billing-management authority from receiving payer-level pooled credit and storage data while preserving workspace billing standing.

• Adds a canonical server-side billing-authority predicate for personal and organization-hosted workspaces.
• Returns nullable credits and storage fields and avoids resolving storage usage when disclosure is unauthorized.
• Updates tests, schemas, generated OpenAPI documentation, and generator assertions for the revised contract.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/billing/application/get-billing-status.ts	Gates payer-pool projection by acting-principal billing authority and defers storage-pool resolution until disclosure is authorized.
apps/sim/lib/billing/core/workspace-billing-authority.ts	Implements the existing billing-management policy using canonical workspace payer and organization membership data.
apps/sim/lib/api/contracts/v2/billing.ts	Makes payer credit and storage fields nullable and documents their authorization semantics.
apps/docs/openapi-v2-billing.json	Regenerates the public billing-status schema to represent withheld payer pools as null.
apps/sim/lib/billing/application/billing-use-cases.test.ts	Covers authorized and unauthorized human callers, actor-less workspace keys, standing visibility, and deferred storage queries.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[GET billing status] --> B{Principal type}
  B -->|Workspace API key| C[Resolve workspace billing status]
  C --> D[Return plan, period, and standing]
  D --> E[credits = null<br/>storage = null]
  B -->|Personal API key| F{Requested workspace?}
  F -->|No| G[Resolve caller's account scope]
  G --> H[Return account credits and storage]
  F -->|Yes| I[Resolve workspace and payer]
  I --> J{Can manage payer billing?}
  J -->|No| D
  J -->|Yes| K[Resolve payer storage pool]
  K --> L[Return pooled credits and storage]

Loading

_{Reviews (2): Last reviewed commit: "chore(billing): tidy payer-pool concealm..." | Re-trigger Greptile}

[waleedlatif1]

@greptile-apps

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 79a3486. Configure here.}