fix(copilot): secure live platform context

Author: j15z

apps/sim/lib/api/contracts/organization.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import {
+  organizationRoleSchema,
   type PiiRedactionSettings,
   piiRedactionSettingsSchema,
   retentionOverridesSchema,
@@ -15,9 +16,6 @@ const numericResponseSchema = z.preprocess((value) => {
   return Number.isFinite(parsed) ? parsed : value
 }, z.number())
 
-export const organizationRoleSchema = z.enum(['owner', 'admin', 'member'], {
-  error: 'Invalid role',
-})
 export const organizationParamsSchema = z.object({
   id: z.string().min(1),
 })

apps/sim/lib/api/contracts/primitives.test.ts

@@ -6,6 +6,7 @@ import {
   customPatternSchema,
   isCanonicalBase64,
   organizationIdSchema,
+  organizationRoleSchema,
   piiStagePolicySchema,
   piiStagesSchema,
   privateSecretProvenanceBundleSchema,
@@ -16,6 +17,16 @@ import {
   workspaceIdSchema,
 } from '@/lib/api/contracts/primitives'
 
+describe('organizationRoleSchema', () => {
+  it.each(['owner', 'admin', 'member'] as const)('accepts canonical role %s', (role) => {
+    expect(organizationRoleSchema.parse(role)).toBe(role)
+  })
+
+  it.each(['billing-owner', 'viewer', '', null, undefined])('rejects invalid role %j', (role) => {
+    expect(organizationRoleSchema.safeParse(role).success).toBe(false)
+  })
+})
+
 describe('workspaceFileNameSchema', () => {
   it('trims and accepts one bounded file name', () => {
     expect(workspaceFileNameSchema.parse(' report.pdf ')).toBe('report.pdf')

apps/sim/lib/api/contracts/primitives.ts

@@ -231,6 +231,12 @@ export const workspaceFileNameSchema = z
 /** Non-empty `organizationId` field with a stable, human-readable message. */
 export const organizationIdSchema = requiredFieldSchema('Organization ID is required')
 
+/** Canonical organization membership role shared across API resource families. */
+export const organizationRoleSchema = z.enum(['owner', 'admin', 'member'], {
+  error: 'Invalid role',
+})
+export type OrganizationRole = z.output<typeof organizationRoleSchema>
+
 /** Non-empty `workflowId` field with a stable, human-readable message. */
 export const workflowIdSchema = requiredFieldSchema('Workflow ID is required')
 

apps/sim/lib/api/contracts/workspaces.test.ts

@@ -0,0 +1,32 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { workspaceHostContextSchema } from '@/lib/api/contracts/workspaces'
+
+const viewerSchema = workspaceHostContextSchema.shape.viewer
+const viewer = {
+  permission: 'read' as const,
+  isHostOrganizationMember: false,
+  isHostOrganizationAdmin: false,
+}
+
+describe('workspaceHostContextSchema organizationRole', () => {
+  it.each(['owner', 'admin', 'member'] as const)(
+    'accepts canonical role %s',
+    (organizationRole) => {
+      expect(viewerSchema.safeParse({ ...viewer, organizationRole }).success).toBe(true)
+    }
+  )
+
+  it('retains null and omission for rolling response compatibility', () => {
+    expect(viewerSchema.safeParse({ ...viewer, organizationRole: null }).success).toBe(true)
+    expect(viewerSchema.safeParse(viewer).success).toBe(true)
+  })
+
+  it('rejects non-canonical organization roles', () => {
+    expect(viewerSchema.safeParse({ ...viewer, organizationRole: 'billing-owner' }).success).toBe(
+      false
+    )
+  })
+})

apps/sim/lib/api/contracts/workspaces.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod'
-import { nonEmptyIdSchema, requiredFieldSchema } from '@/lib/api/contracts/primitives'
+import {
+  nonEmptyIdSchema,
+  organizationRoleSchema,
+  requiredFieldSchema,
+} from '@/lib/api/contracts/primitives'
 import { type ContractJsonResponse, defineRouteContract } from '@/lib/api/contracts/types'
 
 export const workspaceScopeSchema = z.enum(['active', 'archived', 'all'])
@@ -264,7 +268,7 @@ export const workspaceHostContextSchema = z.object({
     isHostOrganizationMember: z.boolean(),
     isHostOrganizationAdmin: z.boolean(),
     /** Optional for rolling compatibility with app versions that predate organization-role projection. */
-    organizationRole: z.string().nullable().optional(),
+    organizationRole: organizationRoleSchema.nullable().optional(),
   }),
 })
 

apps/sim/lib/billing/core/account-billing-snapshot.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  events: [] as string[],
+  getResolvedUserUsageData: vi.fn(),
+  getCreditBalanceForEntity: vi.fn(),
+  isOrgScopedSubscription: vi.fn(),
+}))
+
+vi.mock('@/lib/billing/core/usage', () => ({
+  getResolvedUserUsageData: mocks.getResolvedUserUsageData,
+}))
+
+vi.mock('@/lib/billing/credits/balance', () => ({
+  getCreditBalanceForEntity: mocks.getCreditBalanceForEntity,
+}))
+
+vi.mock('@/lib/billing/subscriptions/utils', () => ({
+  isOrgScopedSubscription: mocks.isOrgScopedSubscription,
+}))
+
+import { getAccountBillingSnapshot } from '@/lib/billing/core/account-billing-snapshot'
+
+const usage = {
+  currentUsage: 18.5,
+  limit: 40,
+  percentUsed: 46.25,
+  isWarning: false,
+  isExceeded: false,
+  billingPeriodStart: new Date('2026-08-01T00:00:00Z'),
+  billingPeriodEnd: new Date('2026-09-01T00:00:00Z'),
+  lastPeriodCost: 31,
+}
+
+describe('getAccountBillingSnapshot', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.events.length = 0
+  })
+
+  it('reuses one resolved subscription for org scope, usage, limits, and credits', async () => {
+    const subscription = {
+      plan: 'team',
+      referenceId: 'org-1',
+    }
+    mocks.getResolvedUserUsageData.mockImplementation(async () => {
+      mocks.events.push('usage-and-subscription')
+      return { usage, subscription, personalCreditBalance: 4 }
+    })
+    mocks.isOrgScopedSubscription.mockReturnValue(true)
+    mocks.getCreditBalanceForEntity.mockImplementation(async () => {
+      mocks.events.push('credits')
+      return 25
+    })
+
+    await expect(getAccountBillingSnapshot('user-1')).resolves.toEqual({
+      plan: 'team',
+      billingScope: 'organization',
+      organizationId: 'org-1',
+      usage: {
+        currentPeriodCost: 18.5,
+        limit: 40,
+        remaining: 21.5,
+        percentUsed: 46.25,
+        isExceeded: false,
+        billingPeriodEnd: new Date('2026-09-01T00:00:00Z'),
+      },
+      credits: { balance: 25, scope: 'organization' },
+    })
+    expect(mocks.getResolvedUserUsageData).toHaveBeenCalledOnce()
+    expect(mocks.getCreditBalanceForEntity).toHaveBeenCalledWith(
+      'organization',
+      'org-1',
+      expect.anything()
+    )
+    expect(mocks.events).toEqual(['usage-and-subscription', 'credits'])
+  })
+
+  it('preserves personal scope and clamps negative remaining usage to zero', async () => {
+    mocks.getResolvedUserUsageData.mockResolvedValue({
+      usage: { ...usage, currentUsage: 45, isExceeded: true },
+      subscription: { plan: 'pro', referenceId: 'user-1' },
+      personalCreditBalance: 0,
+    })
+    mocks.isOrgScopedSubscription.mockReturnValue(false)
+    mocks.getCreditBalanceForEntity.mockResolvedValue(0)
+
+    await expect(getAccountBillingSnapshot('user-1')).resolves.toMatchObject({
+      plan: 'pro',
+      billingScope: 'user',
+      organizationId: null,
+      usage: { remaining: 0, isExceeded: true },
+      credits: { balance: 0, scope: 'user' },
+    })
+    expect(mocks.getCreditBalanceForEntity).not.toHaveBeenCalled()
+  })
+})

apps/sim/lib/billing/core/account-billing-snapshot.ts

@@ -0,0 +1,58 @@
+import { db } from '@sim/db'
+import { getResolvedUserUsageData } from '@/lib/billing/core/usage'
+import { getCreditBalanceForEntity } from '@/lib/billing/credits/balance'
+import { isOrgScopedSubscription } from '@/lib/billing/subscriptions/utils'
+import type { DbClient } from '@/lib/db/types'
+
+export interface AccountBillingSnapshot {
+  plan: string
+  billingScope: 'user' | 'organization'
+  organizationId: string | null
+  usage: {
+    currentPeriodCost: number
+    limit: number
+    remaining: number
+    percentUsed: number
+    isExceeded: boolean
+    billingPeriodEnd: Date | null
+  }
+  credits: {
+    balance: number
+    scope: 'user' | 'organization'
+  }
+}
+
+/** Resolves one coherent subscription, usage, limit, and credit snapshot for an account. */
+export async function getAccountBillingSnapshot(
+  userId: string,
+  executor: DbClient = db
+): Promise<AccountBillingSnapshot> {
+  const { usage, subscription, personalCreditBalance } = await getResolvedUserUsageData(
+    userId,
+    executor
+  )
+  const organizationScoped = isOrgScopedSubscription(subscription, userId) && subscription !== null
+  const billingScope = organizationScoped ? 'organization' : 'user'
+  const billingEntityId = organizationScoped ? subscription.referenceId : userId
+  const creditBalance = organizationScoped
+    ? await getCreditBalanceForEntity('organization', billingEntityId, executor)
+    : personalCreditBalance
+
+  return {
+    plan: subscription?.plan || 'free',
+    billingScope,
+    organizationId: organizationScoped ? subscription.referenceId : null,
+    usage: {
+      currentPeriodCost: usage.currentUsage,
+      limit: usage.limit,
+      remaining: Math.max(0, usage.limit - usage.currentUsage),
+      percentUsed: usage.percentUsed,
+      isExceeded: usage.isExceeded,
+      billingPeriodEnd: usage.billingPeriodEnd,
+    },
+    credits: {
+      balance: creditBalance,
+      scope: billingScope,
+    },
+  }
+}

apps/sim/lib/billing/core/usage.ts

@@ -14,7 +14,10 @@ import {
 } from '@/components/emails'
 import { getEffectiveBillingStatus } from '@/lib/billing/core/access'
 import { defaultBillingPeriod } from '@/lib/billing/core/billing-period'
-import { getHighestPrioritySubscription } from '@/lib/billing/core/plan'
+import {
+  getHighestPrioritySubscription,
+  type HighestPrioritySubscription,
+} from '@/lib/billing/core/plan'
 import { getBillingPeriodUsageCost } from '@/lib/billing/core/usage-log'
 import {
   computeDailyRefreshConsumed,
@@ -190,13 +193,18 @@ export async function ensureUserStatsExists(userId: string): Promise<void> {
     .onConflictDoNothing({ target: userStats.userId })
 }
 
-/**
- * Get comprehensive usage data for a user
- */
-export async function getUserUsageData(
+export interface ResolvedUserUsageData {
+  usage: UsageData
+  subscription: HighestPrioritySubscription
+  /** The personal balance from the same user-stats row used to calculate usage. */
+  personalCreditBalance: number
+}
+
+/** Resolves comprehensive usage and the subscription that determined its billing scope. */
+export async function getResolvedUserUsageData(
   userId: string,
   executor: DbClient = db
-): Promise<UsageData> {
+): Promise<ResolvedUserUsageData> {
   try {
     // Write — always on the primary regardless of executor routing.
     await ensureUserStatsExists(userId)
@@ -332,21 +340,33 @@ export async function getUserUsageData(
     const isExceeded = effectiveUsage >= limit
 
     return {
-      currentUsage: effectiveUsage,
-      limit,
-      percentUsed,
-      isWarning,
-      isExceeded,
-      billingPeriodStart,
-      billingPeriodEnd,
-      lastPeriodCost,
+      usage: {
+        currentUsage: effectiveUsage,
+        limit,
+        percentUsed,
+        isWarning,
+        isExceeded,
+        billingPeriodStart,
+        billingPeriodEnd,
+        lastPeriodCost,
+      },
+      subscription,
+      personalCreditBalance: toNumber(toDecimal(stats.creditBalance)),
     }
   } catch (error) {
     logger.error('Failed to get user usage data', { userId, error })
     throw error
   }
 }
 
+/** Get comprehensive usage data for a user. */
+export async function getUserUsageData(
+  userId: string,
+  executor: DbClient = db
+): Promise<UsageData> {
+  return (await getResolvedUserUsageData(userId, executor)).usage
+}
+
 /**
  * Get usage limit information for a user
  */

apps/sim/lib/copilot/application/execute-platform-context-use-case.ts

@@ -0,0 +1,40 @@
+import { createCopilotApplicationAdapter } from '@/lib/copilot/application/application-adapter'
+import { messageForCopilotApplicationError } from '@/lib/copilot/application/error'
+import {
+  COPILOT_APPLICATION_DELEGATION_TTL_MS,
+  type CopilotExecutionContext,
+  InteractiveCopilotExecutionRequiredError,
+  requireInteractiveCopilotExecutionContext,
+} from '@/lib/copilot/auth/application-delegation'
+import type { OperationUseCase } from '@/lib/core/application'
+import { platformContextDelegationPolicy } from '@/lib/platform-context/application/authorization'
+import {
+  type PlatformContextOperation,
+  platformContextOperations,
+} from '@/lib/platform-context/application/operations'
+
+const executePlatformContextUseCase = createCopilotApplicationAdapter({
+  domain: 'platform context',
+  delegation: {
+    audience: platformContextDelegationPolicy.audience,
+    ttlMs: COPILOT_APPLICATION_DELEGATION_TTL_MS,
+    createDelegationId: (context) => `copilot-tool:${context.toolCallId}`,
+  },
+  operations: platformContextOperations,
+})
+
+/** Enters a live platform-context operation only from a trusted interactive Copilot lifecycle. */
+export function executeCopilotPlatformContextUseCase<O extends PlatformContextOperation, I, R>(
+  context: CopilotExecutionContext | undefined,
+  useCase: OperationUseCase<O, I, R>,
+  input: I
+): Promise<R> {
+  const trustedContext = requireInteractiveCopilotExecutionContext(context)
+  return executePlatformContextUseCase(trustedContext, useCase, input)
+}
+
+/** Projects only actionable authorization failures into live platform-context tool output. */
+export function messageForCopilotPlatformContextError(error: unknown): string {
+  if (error instanceof InteractiveCopilotExecutionRequiredError) return error.message
+  return messageForCopilotApplicationError(error)
+}