Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@37b5fbd48e0b3f90e6b4e1088a02041d9f169a4a

Author: github-actions[bot]

bun.lock

@@ -24,6 +24,102 @@ const createTrackEventMock = () =>
   mock((_event: AnalyticsEvent, _properties?: Record<string, any>) => {})
 
 describe('login-flow analytics instrumentation', () => {
+  test('plain and TUI callers carry one explicit CLI UUID without changing authentication', async () => {
+    const cliFlowId = 'a0000000-0000-4000-8000-000000000001'
+    for (const via of ['modal', 'plain_command'] as const) {
+      const data = {
+        loginUrl: 'https://freebuff.test/login?auth_code=opaque-auth-code',
+        fingerprintHash: 'private-hash',
+        expiresAt: '2030-01-01T00:00:00Z',
+      }
+      const loginCode = mock(async () => ({
+        ok: true as const,
+        status: 200,
+        data,
+      }))
+      const result = await generateLoginUrl(
+        {
+          logger: createMockLogger(),
+          apiClient: createMockApiClient({ loginCode }),
+        },
+        {
+          baseUrl: 'https://freebuff.test',
+          fingerprintId: 'private-fingerprint',
+          via,
+          cliFlowId,
+        },
+      )
+      const browserUrl = new URL(result.loginUrl)
+      expect(browserUrl.searchParams.get('cli_flow')).toBe(cliFlowId)
+      expect(browserUrl.searchParams.getAll('cli_flow')).toEqual([cliFlowId])
+      expect(browserUrl.searchParams.get('auth_code')).toBe('opaque-auth-code')
+      expect(result.fingerprintHash).toBe(data.fingerprintHash)
+      expect(result.expiresAt).toBe(data.expiresAt)
+      expect(loginCode).toHaveBeenCalledWith({
+        fingerprintId: 'private-fingerprint',
+      })
+      expect(data.loginUrl).not.toContain('cli_flow')
+    }
+  })
+
+  test('auth codes and invalid correlation values never imply CLI origin', async () => {
+    const data = {
+      loginUrl:
+        'https://freebuff.test/login?auth_code=opaque-auth-code&native_apple=1',
+      fingerprintHash: 'private-hash',
+      expiresAt: '2030-01-01T00:00:00Z',
+    }
+    const loginCode = mock(async () => ({
+      ok: true as const,
+      status: 200,
+      data,
+    }))
+    const apiClient = createMockApiClient({ loginCode })
+    for (const cliFlowId of [
+      undefined,
+      'private-fingerprint',
+      'opaque-auth-code',
+    ]) {
+      const result = await generateLoginUrl(
+        { logger: createMockLogger(), apiClient },
+        {
+          baseUrl: 'https://freebuff.test',
+          fingerprintId: 'private-fingerprint',
+          cliFlowId,
+        },
+      )
+      expect(result).toEqual(data)
+    }
+  })
+
+  test('optional correlation never rejects an unusable or non-web URL', async () => {
+    for (const loginUrl of ['not a URL', 'freebuff://login?auth_code=opaque']) {
+      const data = {
+        loginUrl,
+        fingerprintHash: 'hash',
+        expiresAt: '2030-01-01T00:00:00Z',
+      }
+      const loginCode = mock(async () => ({
+        ok: true as const,
+        status: 200,
+        data,
+      }))
+      expect(
+        await generateLoginUrl(
+          {
+            logger: createMockLogger(),
+            apiClient: createMockApiClient({ loginCode }),
+          },
+          {
+            baseUrl: 'https://freebuff.test',
+            fingerprintId: 'fingerprint',
+            cliFlowId: 'a0000000-0000-4000-8000-000000000001',
+          },
+        ),
+      ).toEqual(data)
+    }
+  })
+
   test('generateLoginUrl emits LOGIN_STARTED on entry and nothing else on success', async () => {
     const trackEvent = createTrackEventMock()
     const loginCode = mock(async () => ({
@@ -84,13 +180,20 @@ describe('login-flow analytics instrumentation', () => {
   test('pollLoginStatus emits LOGIN_TIMEOUT with attempts + via', async () => {
     const trackEvent = createTrackEventMock()
     const loginStatus = mock(
-      async () => ({ ok: false, status: 401 }) as ApiResponse<{ user?: unknown }>,
+      async () =>
+        ({ ok: false, status: 401 }) as ApiResponse<{ user?: unknown }>,
     )
     const apiClient = createMockApiClient({ loginStatus })
     const clock = createClock()
 
     const result = await pollLoginStatus(
-      { sleep: clock.sleep, logger: createMockLogger(), now: clock.now, apiClient, trackEvent },
+      {
+        sleep: clock.sleep,
+        logger: createMockLogger(),
+        now: clock.now,
+        apiClient,
+        trackEvent,
+      },
       {
         baseUrl: 'https://cli.test',
         fingerprintId: 'finger-1',
@@ -115,7 +218,13 @@ describe('login-flow analytics instrumentation', () => {
     const clock = createClock()
 
     const result = await pollLoginStatus(
-      { sleep: clock.sleep, logger: createMockLogger(), now: clock.now, apiClient, trackEvent },
+      {
+        sleep: clock.sleep,
+        logger: createMockLogger(),
+        now: clock.now,
+        apiClient,
+        trackEvent,
+      },
       {
         baseUrl: 'https://cli.test',
         fingerprintId: 'finger-1',

cli/src/__tests__/integration/login-flow-instrumentation.test.ts

@@ -1,10 +1,12 @@
 import { useMutation } from '@tanstack/react-query'
+import { randomUUID } from 'node:crypto'
 import { safeOpen } from '../utils/open-url'
 
 import { LOGIN_WEBSITE_URL } from '../login/constants'
 import { generateLoginUrl } from '../login/login-flow'
 import { trackEvent } from '../utils/analytics'
 import { logger } from '../utils/logger'
+import { IS_FREEBUFF } from '../utils/constants'
 
 interface UseFetchLoginUrlParams {
   setLoginUrl: (url: string | null) => void
@@ -37,6 +39,7 @@ export function useFetchLoginUrl({
           baseUrl: LOGIN_WEBSITE_URL,
           fingerprintId,
           via: 'modal',
+          cliFlowId: IS_FREEBUFF ? randomUUID() : undefined,
         },
       )
     },

cli/src/hooks/use-fetch-login-url.ts

@@ -32,6 +32,24 @@ export interface GenerateLoginUrlOptions {
   baseUrl: string
   fingerprintId: string
   via?: LoginVia
+  /** Explicit Freebuff CLI origin. Never use a fingerprint or auth token here. */
+  cliFlowId?: string
+}
+
+const CLI_FLOW_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/** Attribution is optional and cannot make a usable sign-in URL fail. */
+function withCliLoginFlow(loginUrl: string, flowId?: string): string {
+  if (!flowId || !CLI_FLOW_ID.test(flowId)) return loginUrl
+  try {
+    const url = new URL(loginUrl)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return loginUrl
+    url.searchParams.set('cli_flow', flowId)
+    return url.toString()
+  } catch {
+    return loginUrl
+  }
 }
 
 export async function generateLoginUrl(
@@ -82,7 +100,10 @@ export async function generateLoginUrl(
     throw new Error('Failed to get login URL')
   }
 
-  return response.data
+  const loginUrl = withCliLoginFlow(response.data.loginUrl, options.cliFlowId)
+  return loginUrl === response.data.loginUrl
+    ? response.data
+    : { ...response.data, loginUrl }
 }
 
 interface PollLoginStatusDeps {

cli/src/login/login-flow.ts

@@ -1,4 +1,5 @@
 import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
+import { randomUUID } from 'node:crypto'
 import { cyan, green, red, yellow, bold } from 'picocolors'
 
 import { LOGIN_WEBSITE_URL } from './constants'
@@ -7,11 +8,7 @@ import {
   FREEBUFF_DISCORD_INVITE_URL,
 } from './discord-invite'
 import { generateLoginUrl, pollLoginStatus } from './login-flow'
-import {
-  flushAnalytics,
-  identifyUser,
-  trackEvent,
-} from '../utils/analytics'
+import { flushAnalytics, identifyUser, trackEvent } from '../utils/analytics'
 import { saveUserCredentials } from '../utils/auth'
 import { IS_FREEBUFF } from '../utils/constants'
 import { getFingerprintId } from '../utils/fingerprint'
@@ -39,7 +36,12 @@ export async function runPlainLogin(): Promise<void> {
   try {
     loginData = await generateLoginUrl(
       { logger, trackEvent },
-      { baseUrl: LOGIN_WEBSITE_URL, fingerprintId, via: 'plain_command' },
+      {
+        baseUrl: LOGIN_WEBSITE_URL,
+        fingerprintId,
+        via: 'plain_command',
+        cliFlowId: IS_FREEBUFF ? randomUUID() : undefined,
+      },
     )
   } catch (error) {
     console.error(
@@ -97,11 +99,13 @@ export async function runPlainLogin(): Promise<void> {
     }
 
     console.log()
-    console.log(green(
+    console.log(
+      green(
         user.name
           ? `✓ Logged in as ${user.name} (${user.email})`
           : `✓ Logged in as ${user.email}`,
-      ))
+      ),
+    )
     console.log()
     const cliName = IS_FREEBUFF ? 'freebuff' : 'codebuff'
     console.log('You can now run ' + cyan(cliName) + ' to start.')

cli/src/login/plain-login.ts

@@ -324,6 +324,7 @@ export enum AnalyticsEvent {
   FREEBUFF_GET_STARTED_SIGN_IN_CLICKED = 'freebuff.get_started_sign_in_clicked',
   FREEBUFF_GET_STARTED_SIGNED_IN = 'freebuff.get_started_signed_in',
   FREEBUFF_EMAIL_AUTH = 'freebuff.email_auth',
+  FREEBUFF_AUTH_STEP = 'freebuff.auth_step',
   FREEBUFF_GET_STARTED_ELIGIBILITY_RESOLVED = 'freebuff.get_started_eligibility_resolved',
   FREEBUFF_GET_STARTED_CONNECT_GITHUB_CLICKED = 'freebuff.get_started_connect_github_clicked',
   FREEBUFF_GET_STARTED_INSTALL_COMMAND_COPIED = 'freebuff.get_started_install_command_copied',

common/src/constants/analytics-events.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod'
+
+export const FREEBUFF_AUTH_EVENT = 'freebuff.auth_step'
+export const authOriginSchema = z.enum(['web', 'desktop', 'cli', 'unknown'])
+export const authProviderSchema = z.enum([
+  'email',
+  'google',
+  'github',
+  'apple',
+  'existing',
+])
+export const authContextSchema = z
+  .object({
+    flow_id: z.string().uuid(),
+    attempt_id: z.string().uuid(),
+    origin: authOriginSchema,
+    provider: authProviderSchema.optional(),
+    started_at: z.number().int().positive(),
+  })
+  .strict()
+export const authEventSchema = authContextSchema
+  .omit({ started_at: true })
+  .extend({
+    event_version: z.literal(1),
+    step: z.enum(['login', 'provider', 'auth', 'connect']),
+    outcome: z.enum([
+      'shown',
+      'selected',
+      'submitted',
+      'succeeded',
+      'failed',
+      'cancelled',
+      'reused',
+    ]),
+    reason: z
+      .enum([
+        'oauth',
+        'blocked',
+        'configuration',
+        'invalid',
+        'expired',
+        'error',
+        'phone_required',
+        'already_connected',
+        'invalid_credentials',
+        'invalid_link',
+        'rate_limited',
+        'unavailable',
+        'challenge_incomplete',
+        'network',
+        'request_failed',
+        'invalid_password',
+        'password_mismatch',
+      ])
+      .optional(),
+    is_new_user: z.boolean().optional(),
+  })
+  .strict()
+export type AuthContext = z.infer<typeof authContextSchema>
+export type AuthEvent = z.infer<typeof authEventSchema>
+export type AuthProvider = z.infer<typeof authProviderSchema>
+
+/** All external payloads are closed: never spread a callback, user or error. */
+export function authEventProperties(
+  context: AuthContext | null | undefined,
+  step: AuthEvent['step'],
+  outcome: AuthEvent['outcome'],
+  details: Pick<AuthEvent, 'provider' | 'reason' | 'is_new_user'> = {},
+): AuthEvent | null {
+  const parsed = authContextSchema.safeParse(context)
+  if (!parsed.success) return null
+  const { started_at: _, ...fields } = parsed.data
+  const result = authEventSchema.safeParse({
+    ...fields,
+    ...details,
+    step,
+    outcome,
+    event_version: 1,
+  })
+  return result.success ? result.data : null
+}
+
+export function authInsertId(event: AuthEvent): string {
+  return `auth:${event.flow_id}:${event.attempt_id}:${event.step}:${event.outcome}:${event.reason ?? ''}`
+}
+
+/** Session-local analytics identity, deliberately unrelated to an account. */
+export function authDistinctId(flow: string): string {
+  return `freebuff-auth:${flow}`
+}

common/src/constants/freebuff-auth-funnel.ts

@@ -41,6 +41,7 @@ const ALWAYS_TRACK_EVENTS = new Set<AnalyticsEvent>([
   AnalyticsEvent.DESKTOP_PROJECT_CREATED,
   AnalyticsEvent.DESKTOP_TURN_COMPLETED,
   AnalyticsEvent.DESKTOP_FUNNEL_STEP,
+  AnalyticsEvent.FREEBUFF_AUTH_STEP,
   // Low-volume recovery funnel. Sampling any stage independently would make
   // creation-to-success and repeated-failure rates impossible to measure.
   AnalyticsEvent.DESKTOP_FAILED_TURN_RECOVERY,