improvement(analytics): attribute every request, credential, and queued run

apps/docs/content/docs/cli/usage-data.mdx

@@ -20,7 +20,7 @@ One event per command, after the command finishes:
 | Duration | `1432` ms | From process start to completion |
 | CLI, Node, OS, CPU | `2.1.2`, `22.14.0`, `darwin`, `arm64` | |
 | Terminal and CI | `is_tty`, `is_ci` | Whether stdout is a terminal, whether a CI variable is set |
-| Coding agent | `claude-code` | When the CLI runs inside an AI coding agent's shell |
+| Coding agent | `claude-code`, or `none` | The AI coding agent whose shell the CLI runs in, if any |
 | Deployment kind | `hosted` or `self_hosted` | Never the address |
 | Device and session ids | random UUIDs | See below |
 

apps/sim/app/api/v1/auth.ts

@@ -1,9 +1,5 @@
-import {
-  describePrincipalAuth,
-  type PersonalApiKeyPrincipal,
-  type WorkspaceApiKeyPrincipal,
-} from '@sim/auth/principal'
-import { createLogger, setRequestAuth } from '@sim/logger'
+import type { PersonalApiKeyPrincipal, WorkspaceApiKeyPrincipal } from '@sim/auth/principal'
+import { createLogger } from '@sim/logger'
 import type { NextRequest } from 'next/server'
 import { authenticateApiKeyFromHeader, updateApiKeyLastUsed } from '@/lib/api-key/service'
 import { ANONYMOUS_USER_ID } from '@/lib/auth/constants'
@@ -76,7 +72,6 @@ export async function authenticateV1Request(request: NextRequest): Promise<AuthR
     }
 
     await updateApiKeyLastUsed(result.keyId)
-    setRequestAuth(describePrincipalAuth(principal))
 
     return {
       authenticated: true,

apps/sim/background/schedule-execution.ts

@@ -6,7 +6,7 @@ import {
   workflowExecutionLogs,
   workflowSchedule,
 } from '@sim/db'
-import { createLogger, runWithRequestContext } from '@sim/logger'
+import { createLogger, type RequestContext, runWithRequestContext } from '@sim/logger'
 import { describeError, toError } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { task, timeout } from '@trigger.dev/sdk'
@@ -822,7 +822,12 @@ export async function executeScheduleJob(
   const scheduledFor = payload.scheduledFor ? new Date(payload.scheduledFor) : null
 
   try {
-    return await runWithRequestContext({ requestId }, async () => {
+    /** A trigger, not a client, started this run. */
+    const requestContext: RequestContext = {
+      requestId,
+      client: { surface: 'schedule', source: 'trigger' },
+    }
+    return await runWithRequestContext(requestContext, async () => {
       logger.info(`[${requestId}] Starting schedule execution`, {
         scheduleId: payload.scheduleId,
         workflowId: payload.workflowId,

apps/sim/background/webhook-execution.ts

@@ -6,7 +6,7 @@ import {
 } from '@sim/auth/principal'
 import { db } from '@sim/db'
 import { account, webhook } from '@sim/db/schema'
-import { createLogger, runWithRequestContext } from '@sim/logger'
+import { createLogger, type RequestContext, runWithRequestContext } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
 import { interruptibleSleep } from '@sim/utils/helpers'
 import { generateId } from '@sim/utils/id'
@@ -556,7 +556,12 @@ export async function executeWebhookJob(
       })
     }
 
-    return await runWithRequestContext({ requestId }, async () => {
+    /** A trigger, not a client, started this run. */
+    const requestContext: RequestContext = {
+      requestId,
+      client: { surface: 'webhook', source: 'trigger' },
+    }
+    return await runWithRequestContext(requestContext, async () => {
       logger.info(`[${requestId}] Starting webhook execution`, {
         webhookId: authenticatedPayload.webhookId,
         workflowId: authenticatedPayload.workflowId,

apps/sim/background/workflow-execution.ts

@@ -25,6 +25,7 @@ import {
   getTimeoutErrorMessage,
   RESERVATION_TTL_BUFFER_MS,
 } from '@/lib/core/execution-limits'
+import type { RequestAttribution } from '@/lib/core/utils/request-attribution'
 import { preprocessExecution } from '@/lib/execution/preprocessing'
 import { LoggingSession } from '@/lib/logs/execution/logging-session'
 import { buildTraceSpans } from '@/lib/logs/execution/trace-spans/trace-spans'
@@ -76,6 +77,8 @@ export type WorkflowExecutionPayload = {
   correlation?: AsyncExecutionCorrelation
   metadata?: Record<string, any>
   callChain?: string[]
+  /** Who queued the run, restored into the job's context so its events stay attributed. */
+  attribution?: RequestAttribution
   executionMode?: 'sync' | 'stream' | 'async'
   /** Upstream preprocessing already consumed rate-limit quota and owns the usage reservation. */
   admissionCompleted?: boolean
@@ -177,7 +180,7 @@ export async function executeWorkflowJob(
       }
     }
 
-    return await runWithRequestContext({ requestId }, async () => {
+    return await runWithRequestContext({ requestId, ...payload.attribution }, async () => {
       logger.info(`[${requestId}] Starting workflow execution job: ${workflowId}`, {
         userId: payload.userId,
         triggerType: payload.triggerType,

apps/sim/lib/api-key/service.test.ts

@@ -7,6 +7,7 @@
  *
  * @vitest-environment node
  */
+import { setRequestAuth } from '@sim/logger'
 import { dbChainMockFns } from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -95,6 +96,27 @@ describe('authenticateApiKeyFromHeader', () => {
     expect(dbChainMockFns.where).toHaveBeenCalledTimes(1)
   })
 
+  it('records the key kind on the request without replacing a more specific principal', async () => {
+    dbChainMockFns.where.mockResolvedValueOnce([
+      personalKeyRecord({ type: 'workspace', workspaceId: 'workspace-1' }),
+    ])
+
+    await authenticateApiKeyFromHeader('sk-sim-plain-key')
+
+    expect(vi.mocked(setRequestAuth)).toHaveBeenCalledWith(
+      { kind: 'workspace_api_key' },
+      { preserveExisting: true }
+    )
+  })
+
+  it('records nothing for a key that fails its checks', async () => {
+    dbChainMockFns.where.mockResolvedValueOnce([personalKeyRecord({ userId: 'other-user' })])
+
+    await authenticateApiKeyFromHeader('sk-sim-plain-key', { userId: 'user-1' })
+
+    expect(vi.mocked(setRequestAuth)).not.toHaveBeenCalled()
+  })
+
   it('returns invalid when the hash lookup finds a row that fails scope checks', async () => {
     const record = personalKeyRecord({ userId: 'other-user' })
     dbChainMockFns.where.mockResolvedValueOnce([record])

apps/sim/lib/api-key/service.ts

@@ -1,6 +1,6 @@
 import { db } from '@sim/db'
 import { apiKey as apiKeyTable, user as userTable } from '@sim/db/schema'
-import { createLogger } from '@sim/logger'
+import { createLogger, setRequestAuth } from '@sim/logger'
 import { and, eq, isNull, lt, or } from 'drizzle-orm'
 import { hashApiKey } from '@/lib/api-key/crypto'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
@@ -132,6 +132,10 @@ export async function authenticateApiKeyFromHeader(
     }
 
     logger.debug('API key matched via hash lookup', { keyId: record.id, keyType })
+    setRequestAuth(
+      { kind: keyType === 'personal' ? 'personal_api_key' : 'workspace_api_key' },
+      { preserveExisting: true }
+    )
 
     return {
       success: true,

apps/sim/lib/auth/auth.ts

@@ -4,7 +4,7 @@ import { sso } from '@better-auth/sso'
 import { stripe } from '@better-auth/stripe'
 import { db } from '@sim/db'
 import * as schema from '@sim/db/schema'
-import { createLogger } from '@sim/logger'
+import { createLogger, setRequestAuth } from '@sim/logger'
 import { getErrorMessage, toError } from '@sim/utils/errors'
 import { type BetterAuthOptions, betterAuth, type User } from 'better-auth'
 import {
@@ -1758,13 +1758,25 @@ export const auth = betterAuth({
 async function getSessionImpl() {
   if (isAuthDisabled) {
     await ensureAnonymousUserExists()
-    return createAnonymousSession()
+    return recordSessionAuth(createAnonymousSession())
   }
 
   const hdrs = await headers()
-  return await auth.api.getSession({
-    headers: hdrs,
-  })
+  return recordSessionAuth(
+    await auth.api.getSession({
+      headers: hdrs,
+    })
+  )
+}
+
+/**
+ * Records a resolved session as the request's auth kind. Stamped here, where
+ * every session is resolved, so the many routes that authenticate by calling
+ * `getSession` directly are attributed without each one remembering to.
+ */
+function recordSessionAuth<T extends { user?: { id?: string } } | null>(session: T): T {
+  if (session?.user?.id) setRequestAuth({ kind: 'session' }, { preserveExisting: true })
+  return session
 }
 
 export const getSession = cache(getSessionImpl)

apps/sim/lib/auth/hybrid.ts

@@ -1,5 +1,5 @@
-import { describePrincipalAuth, type WorkflowExecutionPrincipal } from '@sim/auth/principal'
-import { createLogger, setRequestAuth } from '@sim/logger'
+import type { WorkflowExecutionPrincipal } from '@sim/auth/principal'
+import { createLogger } from '@sim/logger'
 import type { NextRequest } from 'next/server'
 import { API_KEY_HEADER, BEARER_PREFIX } from '@/lib/api/server/credential-headers'
 import { authenticateApiKeyFromHeader, updateApiKeyLastUsed } from '@/lib/api-key/service'
@@ -83,7 +83,7 @@ function resolveUserFromJwt(
  * @param options - Optional configuration
  * @param options.requireWorkflowId - Whether workflowId/userId is required (default: true)
  */
-async function resolveInternalAuth(
+export async function checkInternalAuth(
   request: NextRequest,
   options: { requireWorkflowId?: boolean } = {}
 ): Promise<AuthResult> {
@@ -131,7 +131,7 @@ async function resolveInternalAuth(
  * @param options - Optional configuration
  * @param options.requireWorkflowId - Whether workflowId/userId is required for JWT (default: true)
  */
-async function resolveSessionOrInternalAuth(
+export async function checkSessionOrInternalAuth(
   request: NextRequest,
   options: { requireWorkflowId?: boolean } = {}
 ): Promise<AuthResult> {
@@ -195,7 +195,7 @@ async function resolveSessionOrInternalAuth(
  *
  * For internal JWT calls, requires workflowId to determine user context
  */
-async function resolveHybridAuth(
+export async function checkHybridAuth(
   request: NextRequest,
   options: { requireWorkflowId?: boolean } = {}
 ): Promise<AuthResult> {
@@ -277,36 +277,3 @@ async function resolveHybridAuth(
     }
   }
 }
-
-type AuthCheck = (
-  request: NextRequest,
-  options?: { requireWorkflowId?: boolean }
-) => Promise<AuthResult>
-
-/**
- * Records how a request authenticated on the request context, so the logs and
- * analytics of a route that authenticates through these helpers rather than a
- * route builder carry the same `auth` attribution. A principal describes
- * itself; an internal JWT that produced none is recorded by its auth type.
- */
-function recordingAuth(resolve: AuthCheck): AuthCheck {
-  return async (request, options) => {
-    const result = await resolve(request, options)
-    if (!result.success) return result
-    if (result.principal) {
-      setRequestAuth(describePrincipalAuth(result.principal))
-    } else if (result.authType) {
-      setRequestAuth({ kind: result.authType })
-    }
-    return result
-  }
-}
-
-/** Internal JWT authentication only. See {@link resolveInternalAuth}. */
-export const checkInternalAuth = recordingAuth(resolveInternalAuth)
-
-/** Session or internal JWT authentication, never an API key. See {@link resolveSessionOrInternalAuth}. */
-export const checkSessionOrInternalAuth = recordingAuth(resolveSessionOrInternalAuth)
-
-/** Any of the three supported credentials. See {@link resolveHybridAuth}. */
-export const checkHybridAuth = recordingAuth(resolveHybridAuth)

apps/sim/lib/auth/internal.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { serializePrincipal } from '@sim/auth/principal'
+import { setRequestAuth } from '@sim/logger'
 import { resetEnvMock } from '@sim/testing'
 import { decodeJwt, SignJWT } from 'jose'
 import { afterAll, describe, expect, it, vi } from 'vitest'
@@ -40,6 +41,19 @@ describe('internal JWT claims', () => {
     })
   })
 
+  it('records a verified internal token as the request auth kind, and a refused one not at all', async () => {
+    vi.mocked(setRequestAuth).mockClear()
+
+    await verifyInternalToken('not-a-jwt')
+    expect(vi.mocked(setRequestAuth)).not.toHaveBeenCalled()
+
+    await verifyInternalToken(await generateInternalToken('user-1'))
+    expect(vi.mocked(setRequestAuth)).toHaveBeenCalledWith(
+      { kind: 'internal_jwt' },
+      { preserveExisting: true }
+    )
+  })
+
   it('rejects unknown sandbox profiles instead of falling back to another image', async () => {
     const token = await generateInternalToken('user-1', {
       sandboxProfile: 'unknown-profile' as never,

apps/sim/lib/auth/internal.ts

@@ -5,7 +5,7 @@ import {
   type WorkflowExecutionAuthority,
   type WorkflowExecutionPrincipal,
 } from '@sim/auth/principal'
-import { createLogger } from '@sim/logger'
+import { createLogger, setRequestAuth } from '@sim/logger'
 import { safeCompare } from '@sim/security/compare'
 import { generateId } from '@sim/utils/id'
 import { type JWTPayload, jwtVerify, SignJWT } from 'jose'
@@ -295,6 +295,7 @@ export async function verifyInternalToken(
       if (payload.sandboxProfile !== undefined && payload.sandboxProfile !== 'mothership') {
         return { valid: false }
       }
+      setRequestAuth({ kind: 'internal_jwt' }, { preserveExisting: true })
       return {
         valid: true,
         userId: typeof payload.userId === 'string' ? payload.userId : undefined,

apps/sim/lib/auth/oauth-access-token.test.ts

@@ -1,6 +1,7 @@
 /**
  * @vitest-environment node
  */
+import { setRequestAuth } from '@sim/logger'
 import { dbChainMockFns, queueTableRows, resetDbChainMock, schemaMock } from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -85,12 +86,17 @@ describe('verifyOAuthAccessToken', () => {
     })
     expect(dbChainMockFns.where).toHaveBeenCalledOnce()
     expect(JSON.stringify(dbChainMockFns.where.mock.calls[0])).toContain('hash:secret')
+    expect(vi.mocked(setRequestAuth)).toHaveBeenCalledWith(
+      { kind: 'oauth_access_token', clientId: 'sim-cli' },
+      { preserveExisting: true }
+    )
   })
 
   it('refuses a credential that is not one of ours without a database read', async () => {
     expect(await reason('sim_abc')).toBe('malformed')
     expect(await reason('sim_oat_')).toBe('malformed')
     expect(dbChainMockFns.where).not.toHaveBeenCalled()
+    expect(vi.mocked(setRequestAuth)).not.toHaveBeenCalled()
   })
 
   it('refuses an unknown, expired, disabled-client, orphaned, or banned token', async () => {

apps/sim/lib/auth/oauth-access-token.ts

@@ -1,7 +1,7 @@
 import type { OAuthAccessTokenPrincipal } from '@sim/auth/principal'
 import { db } from '@sim/db'
 import { oauthAccessToken, oauthClient, user } from '@sim/db/schema'
-import { createLogger } from '@sim/logger'
+import { createLogger, setRequestAuth } from '@sim/logger'
 import { sha256Hex } from '@sim/security/hash'
 import { eq } from 'drizzle-orm'
 import { isAccountBlocked } from '@/lib/auth/ban'
@@ -137,6 +137,7 @@ export async function verifyOAuthAccessToken(
   }
 
   logger.debug('Authenticated OAuth access token', { tokenId: row.id, clientId: row.clientId })
+  setRequestAuth({ kind: 'oauth_access_token', clientId: row.clientId }, { preserveExisting: true })
   return {
     kind: 'oauth_access_token',
     userId: row.userId,

apps/sim/lib/core/utils/request-attribution.test.ts

@@ -0,0 +1,43 @@
+/**
+ * @vitest-environment node
+ */
+import { loggerMock } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { captureRequestAttribution } from '@/lib/core/utils/request-attribution'
+
+describe('captureRequestAttribution', () => {
+  beforeEach(() => {
+    vi.mocked(loggerMock.getRequestContext).mockReset()
+  })
+
+  it('carries the client and auth of the request that queues the work', () => {
+    vi.mocked(loggerMock.getRequestContext).mockReturnValue({
+      requestId: 'req-1',
+      path: '/api/workflows/wf-1/execute',
+      client: { surface: 'cli', version: '2.1.2', agent: 'none', source: 'header' },
+      auth: { kind: 'oauth_access_token', clientId: 'sim-cli' },
+    })
+
+    expect(captureRequestAttribution()).toEqual({
+      client: { surface: 'cli', version: '2.1.2', agent: 'none', source: 'header' },
+      auth: { kind: 'oauth_access_token', clientId: 'sim-cli' },
+    })
+  })
+
+  it('omits what the request did not establish', () => {
+    vi.mocked(loggerMock.getRequestContext).mockReturnValue({
+      requestId: 'req-1',
+      client: { surface: 'api', source: 'credential' },
+    })
+
+    expect(captureRequestAttribution()).toEqual({
+      client: { surface: 'api', source: 'credential' },
+    })
+  })
+
+  it('carries nothing outside a request', () => {
+    vi.mocked(loggerMock.getRequestContext).mockReturnValue(undefined)
+
+    expect(captureRequestAttribution()).toBeUndefined()
+  })
+})