The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Record where an account came from (utm_* and rid at sign-up) (#785)
0xken1577507a9f6f71
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prismaindex edb548fb4..cd3f2bbdb 100644--- a/backend/prisma/schema.prisma+++ b/backend/prisma/schema.prisma@@ -39,6 +39,13 @@ model User {// Null on rows that predate it or when the request did not come through Cloudflare.lastCountryCode String?lastCountryAt DateTime?+ // The `utm_*` and `rid` a sign-in arrived with (lib/signInAttribution.ts), recorded by /api/auth/exchange.+ // `signUpAttribution` is the tags the account was created with — how it was acquired — written once,+ // by the sign-in that created the row (or claimed a device's provisional row). Unset for an account+ // created untagged or elsewhere, so a later tagged sign-in never claims the acquisition.+ // `lastAttribution` is the latest tagged sign-in.+ signUpAttribution SignInAttribution?+ lastAttribution SignInAttribution?createdAt DateTime @default(now())updatedAt DateTime @updatedAt@@ -46,6 +53,16 @@ model User {@@map("users")}+type SignInAttribution {+ source String?+ medium String?+ campaign String?+ term String?+ content String?+ rid String? // Autonomous referral id+ recordedAt DateTime+}+/// A machine: the unit that groups N agents and the thing a user creates, names, pays for and/// attaches a device to. Maps a user to their provisioned machine (agent-node) + the per-machine/// api-key the backend generated for it. The backend injects this key when reverse-proxying thediff --git a/backend/src/lib/signInAttribution.test.ts b/backend/src/lib/signInAttribution.test.tsnew file mode 100644index 000000000..7bf30c233--- /dev/null+++ b/backend/src/lib/signInAttribution.test.ts@@ -0,0 +1,44 @@+import { describe, expect, it } from 'vitest'+import { normalizeSignInAttribution } from './signInAttribution.js'++/**+ * `/api/auth/exchange` takes this from whoever holds a fresh code, and what passes is stored on the+ * user and reported on — so only the `utm_*` keys and `rid` survive, trimmed and capped.+ */+describe('sign-in attribution', () => {+ it('maps the five utm keys to their fields', () => {+ expect(normalizeSignInAttribution({+ utm_source: 'app',+ utm_medium: 'web',+ utm_campaign: 'launch',+ utm_term: 'agents',+ utm_content: 'hero',+ })).toEqual({ source: 'app', medium: 'web', campaign: 'launch', term: 'agents', content: 'hero' })+ })++ it('keeps the Autonomous referral id', () => {+ expect(normalizeSignInAttribution({ rid: 'r-123', utm_source: 'app' })).toEqual({ rid: 'r-123', source: 'app' })+ })++ it('keeps only the keys that were sent', () => {+ expect(normalizeSignInAttribution({ utm_source: 'app' })).toEqual({ source: 'app' })+ })++ it('drops unknown keys and non-string values', () => {+ expect(normalizeSignInAttribution({ utm_source: 'app', role: 'admin', utm_medium: 42 })).toEqual({ source: 'app' })+ })++ it('trims and caps each value', () => {+ expect(normalizeSignInAttribution({ utm_source: ' app ' })).toEqual({ source: 'app' })+ expect(normalizeSignInAttribution({ utm_source: 'a'.repeat(500) })?.source).toHaveLength(128)+ })++ it('is absent rather than empty when nothing usable was sent', () => {+ expect(normalizeSignInAttribution(undefined)).toBeUndefined()+ expect(normalizeSignInAttribution(null)).toBeUndefined()+ expect(normalizeSignInAttribution('utm_source=app')).toBeUndefined()+ expect(normalizeSignInAttribution(['app'])).toBeUndefined()+ expect(normalizeSignInAttribution({})).toBeUndefined()+ expect(normalizeSignInAttribution({ utm_source: ' ' })).toBeUndefined()+ })+})diff --git a/backend/src/lib/signInAttribution.ts b/backend/src/lib/signInAttribution.tsnew file mode 100644index 000000000..db8a91b48--- /dev/null+++ b/backend/src/lib/signInAttribution.ts@@ -0,0 +1,48 @@+/**+ * Where a sign-in came from, as the marketing site tagged it. auth.autonomous.ai carries the+ * `utm_*` and `rid` it was reached with back onto our redirect_uri; the web callback page lifts+ * them off the URL and sends them with `/api/auth/exchange`, which records them on the user: as+ * `signUpAttribution` when that sign-in creates the account, and as `lastAttribution` every time.+ *+ * `/api/auth/exchange` is reachable by anyone holding a fresh code, so only the keys below are+ * read, each trimmed and capped — whatever passes here becomes a stored, reported value.+ */+export interface SignInAttribution {+ source?: string+ medium?: string+ campaign?: string+ term?: string+ content?: string+ /** Autonomous's own referral id, beside the utm tags on its links. */+ rid?: string+}++/** Wire key → stored field. The wire keys are the URL's own, so the client forwards them untouched. */+const ATTRIBUTION_FIELDS = {+ utm_source: 'source',+ utm_medium: 'medium',+ utm_campaign: 'campaign',+ utm_term: 'term',+ utm_content: 'content',+ rid: 'rid',+} as const satisfies Record<string, keyof SignInAttribution>++const MAX_VALUE_LENGTH = 128++function attributionValue(raw: unknown): string | undefined {+ if (typeof raw !== 'string') return undefined+ const value = raw.trim().slice(0, MAX_VALUE_LENGTH)+ return value || undefined+}++/** The recognised keys of [raw], or nothing when it carries none — never an empty record. */+export function normalizeSignInAttribution(raw: unknown): SignInAttribution | undefined {+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return undefined+ const input = raw as Record<string, unknown>+ const attribution: SignInAttribution = {}+ for (const [wireKey, field] of Object.entries(ATTRIBUTION_FIELDS)) {+ const value = attributionValue(input[wireKey])+ if (value) attribution[field] = value+ }+ return Object.keys(attribution).length ? attribution : undefined+}diff --git a/backend/src/lib/ssoAuth.test.ts b/backend/src/lib/ssoAuth.test.tsindex 43e4076a2..30ccb3501 100644--- a/backend/src/lib/ssoAuth.test.ts+++ b/backend/src/lib/ssoAuth.test.ts@@ -186,6 +186,20 @@ describe('authenticated user resolution', () => {expect(findByExternal).not.toHaveBeenCalled()})+ it('hands the sign-in tags to the user mirror, which keeps them only on a new account', async () => {+ profileFetch('prod-sub-1', '[email protected]')+ findByEmail.mockResolvedValue(null)+ findByExternal.mockResolvedValue(null)+ upsertFromSso.mockResolvedValue({ id: 'u-new', email: '[email protected]', role: 'user' })++ await authenticateAccessToken('a.e30.c', 'prod', { signUpAttribution: { source: 'app', rid: 'r-123' } })++ expect(upsertFromSso).toHaveBeenCalledWith(expect.objectContaining({+ email: '[email protected]',+ signUpAttribution: { source: 'app', rid: 'r-123' },+ }))+ })+it('claims a prod provisional row by User.externalId', async () => {profileFetch('prod-sub-1', '[email protected]')findByEmail.mockResolvedValue(null)diff --git a/backend/src/lib/ssoAuth.ts b/backend/src/lib/ssoAuth.tsindex 4d7df8607..1f13399ac 100644--- a/backend/src/lib/ssoAuth.ts+++ b/backend/src/lib/ssoAuth.ts@@ -11,6 +11,7 @@ import {} from './autonomousEnvironment.js'import { createSsoProfileCache, type SharedProfileStore } from './ssoProfileCache.js'import { isHarnessAccessToken } from './harnessTokenFormat.js'+import type { SignInAttribution } from './signInAttribution.js'/** Internal identity attached to authenticated backend requests and user WebSockets. */export interface AuthUser {@@ -188,7 +189,16 @@ function accessTokenMetadata(token: string): { name?: string; roles?: string[] }export async function authenticateAccessToken(token: string,autonomousEnv: AutonomousEnvironment = 'prod',- { enforceEnv = true, allowHarnessSession = true }: { enforceEnv?: boolean; allowHarnessSession?: boolean | 'computer' } = {},+ {+ enforceEnv = true,+ allowHarnessSession = true,+ signUpAttribution,+ }: {+ enforceEnv?: boolean+ allowHarnessSession?: boolean | 'computer'+ /** The sign-in's tags (lib/signInAttribution.ts), kept on the account only if this creates it. */+ signUpAttribution?: SignInAttribution+ } = {},): Promise<AuthUser> {// A sign-in Harness issued itself — a phone signed in by scanning a computer's QR. It names its// user outright, so there is no account plane to choose and nothing to ask the account service.@@ -230,6 +240,7 @@ export async function authenticateAccessToken(email,autonomousEnv,...metadata,+ ...(signUpAttribution ? { signUpAttribution } : {}),})return { sub: user.id, email: user.email, role: user.role, autonomousEnv }}diff --git a/backend/src/routes/auth.ts b/backend/src/routes/auth.tsindex 86202e1f8..33d2003a2 100644--- a/backend/src/routes/auth.ts+++ b/backend/src/routes/auth.ts@@ -25,6 +25,16 @@ import {import { parseAutonomousEnvironment, type AutonomousEnvironment } from '../lib/autonomousEnvironment.js'import { isHarnessRefreshToken } from '../lib/harnessTokenFormat.js'import { redeemHandoff, refreshHarnessSession, revokeHarnessSession, startHandoff } from '../lib/harnessSession.js'+import { normalizeSignInAttribution, type SignInAttribution } from '../lib/signInAttribution.js'++/** Reporting only: a sign-in whose attribution cannot be stored still signs in. */+async function recordAttribution(userId: string, attribution: SignInAttribution): Promise<void> {+ try {+ await userService.recordSignInAttribution(userId, attribution)+ } catch (e) {+ logger.error('sign-in attribution not recorded', e, { userId })+ }+}export async function authRoutes(app: FastifyInstance): Promise<void> {// 1) Start login (web-driven). The web fetches this (XHR, so the API URL never hits the address@@ -56,10 +66,12 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {// ?code&state + the `tx` it stashed, and POSTs them here (XHR). The BACKEND exchanges the code// then validates the access token through the profile service, mirrors the user and returns that// SAME access token in the body. No backend-owned session JWT is minted.- app.post<{ Body: { code?: string; state?: string; tx?: string } }>(+ // `attribution` is the `utm_*` + `rid` auth-service carried back onto the callback URL (lib/signInAttribution.ts).+ app.post<{ Body: { code?: string; state?: string; tx?: string; attribution?: unknown } }>('/api/auth/exchange',async (req, reply) => {const { code, state, tx: txRaw } = req.body ?? {}+ const attribution = normalizeSignInAttribution(req.body?.attribution)let tx: SsoTx | null = nulltry {tx = txRaw ? await consumeTx(txRaw) : null@@ -73,14 +85,21 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {const tokens = await exchangeCode(code, tx.verifier, tx.redirectUri, tx.autonomousEnv, tx.clientId)const token = tokens.access_tokenif (!token) throw new Error('sso response had no access_token')- const user = await authenticateAccessToken(token, tx.autonomousEnv)+ // A sign-in that creates the account keeps its tags as the acquisition (`signUpAttribution`).+ const user = await authenticateAccessToken(+ token,+ tx.autonomousEnv,+ attribution ? { signUpAttribution: attribution } : {},+ )logger.info('sso login', {userId: user.sub,email: user.email || '(empty)',autonomousEnv: user.autonomousEnv,hasRefreshToken: !!tokens.refresh_token,expiresIn: tokens.expires_in,+ ...(attribution ? { attribution } : {}),})+ if (attribution) await recordAttribution(user.sub, attribution)return sendSuccess(reply, {token,next: tx.next,diff --git a/backend/src/services/UserService.test.ts b/backend/src/services/UserService.test.tsindex f8aa1089b..dd91e8144 100644--- a/backend/src/services/UserService.test.ts+++ b/backend/src/services/UserService.test.ts@@ -164,6 +164,88 @@ describe('SSO user identity', () => {})})+describe('sign-in attribution', () => {+ const tags = { source: 'newsletter', campaign: 'oct', rid: 'r-123' }++ it('keeps the tags of the sign-in that creates the account as its acquisition', async () => {+ findUnique.mockResolvedValue(null)++ await userService.upsertFromSso({+ externalId: 'prod-sub-new',+ email: '[email protected]',+ autonomousEnv: 'prod',+ signUpAttribution: tags,+ })++ expect(create).toHaveBeenCalledWith({+ data: expect.objectContaining({+ signUpAttribution: { ...tags, recordedAt: expect.any(Date) },+ }),+ })+ })++ it('creates an untagged account with no acquisition', async () => {+ findUnique.mockResolvedValue(null)++ await userService.upsertFromSso({ externalId: 'prod-sub-new', email: '[email protected]', autonomousEnv: 'prod' })++ expect(create.mock.calls[0][0].data).not.toHaveProperty('signUpAttribution')+ })++ it('never gives an existing account an acquisition from a later tagged sign-in', async () => {+ findUnique.mockResolvedValue(row())++ await userService.upsertFromSso({+ externalId: 'prod-sub-1',+ email: '[email protected]',+ autonomousEnv: 'prod',+ name: 'Renamed',+ signUpAttribution: tags,+ })++ expect(update).toHaveBeenCalledWith({ where: { id: 'u1' }, data: { name: 'Renamed' } })+ })++ it('stays off the write path for a current account even when the sign-in is tagged', async () => {+ findUnique.mockResolvedValue(row())++ await userService.upsertFromSso({+ externalId: 'prod-sub-1',+ email: '[email protected]',+ autonomousEnv: 'prod',+ signUpAttribution: tags,+ })++ expect(update).not.toHaveBeenCalled()+ })++ it("keeps the tags of the owner's first sign-in when it claims a device's provisional row", async () => {+ findUnique.mockResolvedValueOnce(null).mockResolvedValueOnce(row({ email: provisionalEmailForExternalId('prod-sub-1') }))++ await userService.upsertFromSso({+ externalId: 'prod-sub-1',+ email: '[email protected]',+ autonomousEnv: 'prod',+ signUpAttribution: tags,+ })++ expect(update).toHaveBeenCalledWith({+ where: { id: 'u1' },+ data: { email: '[email protected]', signUpAttribution: { ...tags, recordedAt: expect.any(Date) } },+ })+ })++ it('records a tagged sign-in only as the latest', async () => {+ await userService.recordSignInAttribution('u1', tags)++ expect(update).toHaveBeenCalledOnce()+ expect(update).toHaveBeenCalledWith({+ where: { id: 'u1' },+ data: { lastAttribution: { ...tags, recordedAt: expect.any(Date) } },+ })+ })+})+describe('provisional identity helpers', () => {it('builds a deterministic non-deliverable email', () => {expect(provisionalEmailForExternalId('ABC123')).toBe('[email protected]')diff --git a/backend/src/services/UserService.ts b/backend/src/services/UserService.tsindex d0c166cec..4bc6175f5 100644--- a/backend/src/services/UserService.ts+++ b/backend/src/services/UserService.ts@@ -5,6 +5,7 @@ import { ADMIN_EMAILS } from '../config/env.js'import { hashPassword } from '../lib/password.js'import { ConflictError, NotFoundError } from '../errors/index.js'import type { AutonomousEnvironment } from '../lib/autonomousEnvironment.js'+import type { SignInAttribution } from '../lib/signInAttribution.js'export type PublicUser = Omit<User, 'passwordHash'>@@ -37,6 +38,8 @@ interface SsoUserInput {autonomousEnv: AutonomousEnvironmentname?: stringroles?: string[]+ /** The tags this sign-in arrived with; stored only if it creates the account (or claims a provisional row). */+ signUpAttribution?: SignInAttribution}async function mergeProdProvisionalUser(provisional: User, user: User): Promise<void> {@@ -75,6 +78,9 @@ export const userService = {const externalId = input.externalId.trim()const em = normalizeUserEmail(input.email)if (!externalId || !em) throw new Error('SSO profile is missing its subject or email')+ const signUpAttribution = input.signUpAttribution+ ? { signUpAttribution: { ...input.signUpAttribution, recordedAt: new Date() } }+ : {}const wantAdmin = input.roles?.includes('admin') || ADMIN_EMAILS.has(em)let existing = await prisma.user.findUnique({ where: { email: em } })@@ -91,7 +97,10 @@ export const userService = {}}const role = existing.role === 'admin' || wantAdmin ? 'admin' : 'user'+ // Claiming a device's provisional row is this owner's first sign-in: the account starts here.+ const claimsProvisional = isProvisionalUserEmail(existing.email)const data = {+ ...(claimsProvisional ? signUpAttribution : {}),...(existing.email !== em ? { email: em } : {}),...(input.name && existing.name !== input.name ? { name: input.name } : {}),...(existing.role !== role ? { role } : {}),@@ -116,6 +125,7 @@ export const userService = {name: input.name,role: wantAdmin ? 'admin' : 'user',autonomousEnv: input.autonomousEnv,+ ...signUpAttribution,}try {return await prisma.user.create({ data })@@ -171,6 +181,17 @@ export const userService = {}},+ /**+ * Stamp a tagged sign-in as the latest. The acquisition (`signUpAttribution`) is written by+ * `upsertFromSso` when the sign-in creates the account, never here.+ */+ async recordSignInAttribution(userId: string, attribution: SignInAttribution): Promise<void> {+ await prisma.user.update({+ where: { id: userId },+ data: { lastAttribution: { ...attribution, recordedAt: new Date() } },+ })+ },+get(id: string): Promise<User | null> {return prisma.user.findUnique({ where: { id } })},diff --git a/desktop/lib/viewer/browser_login.dart b/desktop/lib/viewer/browser_login.dartindex 70ea338e9..33101e064 100644--- a/desktop/lib/viewer/browser_login.dart+++ b/desktop/lib/viewer/browser_login.dart@@ -9,6 +9,7 @@ import '../core/browser_label.dart';import 'direct_auth.dart';import 'qr_sign_in.dart';import 'direct_auth_api.dart';+import 'sign_in_attribution.dart';import '../sharing/shared_agent_location.dart';import 'viewer_location.dart';@@ -95,6 +96,7 @@ class BrowserLogin implements SignInClient, PhoneSignInClient {code: code,state: saved['state'] as String,tx: saved['tx'] as String,+ attribution: signInAttribution(uri),);_requireCurrent(revision);await auth.signIn(tokens, stillCurrent: () => revision == _revision);diff --git a/desktop/lib/viewer/direct_auth_api.dart b/desktop/lib/viewer/direct_auth_api.dartindex ef38c343c..494e6074a 100644--- a/desktop/lib/viewer/direct_auth_api.dart+++ b/desktop/lib/viewer/direct_auth_api.dart@@ -146,15 +146,22 @@ class DirectAuthApi {.toString();}+ /// [attribution] is the callback's `utm_*` and `rid` (`sign_in_attribution.dart`), recorded on the account.Future<IssuedTokens> exchange({required String code,required String state,required String tx,+ Map<String, String> attribution = const {},}) async {final data = unwrapApiResponse(await _dio.post('/api/auth/exchange',- data: {'code': code, 'state': state, 'tx': tx},+ data: {+ 'code': code,+ 'state': state,+ 'tx': tx,+ if (attribution.isNotEmpty) 'attribution': attribution,+ },),);return IssuedTokens.fromData(data) ??diff --git a/desktop/lib/viewer/sign_in_attribution.dart b/desktop/lib/viewer/sign_in_attribution.dartnew file mode 100644index 000000000..8f56258d0--- /dev/null+++ b/desktop/lib/viewer/sign_in_attribution.dart@@ -0,0 +1,18 @@+/// The keys auth-service carries back onto the sign-in callback: the `utm_*` tags and+/// Autonomous's referral id `rid`.+const _attributionKeys = {+ 'utm_source',+ 'utm_medium',+ 'utm_campaign',+ 'utm_term',+ 'utm_content',+ 'rid',+};++/// Where this sign-in came from, as the marketing site tagged it: the [_attributionKeys] of [callback],+/// under their URL keys, for `/api/auth/exchange` to record on the account (backend+/// lib/signInAttribution.ts). Empty when the sign-in carried none.+Map<String, String> signInAttribution(Uri callback) => {+ for (final MapEntry(:key, :value) in callback.queryParameters.entries)+ if (_attributionKeys.contains(key) && value.trim().isNotEmpty) key: value,+};diff --git a/desktop/test/browser_login_test.dart b/desktop/test/browser_login_test.dartindex 5d5bfe24a..b8f847dfa 100644--- a/desktop/test/browser_login_test.dart+++ b/desktop/test/browser_login_test.dart@@ -35,6 +35,7 @@ class _Api extends DirectAuthApi {final authorization = Completer<({String authorizeUrl, String tx})>();final exchanged = Completer<IssuedTokens>();final requests = <({String code, String state, String tx})>[];+ final attributions = <Map<String, String>>[];String? origin;String? nativeRedirect;SignInProvider? provider;@@ -63,8 +64,10 @@ class _Api extends DirectAuthApi {required String code,required String state,required String tx,+ Map<String, String> attribution = const {},}) {requests.add((code: code, state: state, tx: tx));+ attributions.add(attribution);return exchanged.future;}}@@ -332,6 +335,36 @@ void main() {);}+ test('forwards the callback\'s utm tags and rid with the exchange, and nothing else', () async {+ callback();+ browser.uri = browser.uri.replace(+ queryParameters: {+ ...browser.uri.queryParameters,+ 'utm_source': 'app',+ 'utm_campaign': 'launch',+ 'rid': 'r-123',+ 'utm_medium': ' ',+ 'ref': 'other',+ },+ );+ final status = login.checkStatus();+ expect(api.attributions.single, {+ 'utm_source': 'app',+ 'utm_campaign': 'launch',+ 'rid': 'r-123',+ });+ api.exchanged.complete(const IssuedTokens(token: 'fixture-token'));+ expect((await status).loggedIn, isTrue);+ });++ test('an untagged callback exchanges with no attribution', () async {+ callback();+ final status = login.checkStatus();+ expect(api.attributions.single, isEmpty);+ api.exchanged.complete(const IssuedTokens(token: 'fixture-token'));+ await status;+ });+test('rejects unsolicited, expired and mismatched callbacks without an exchange',() async {diff --git a/desktop/test/viewer_auth_lifecycle_test.dart b/desktop/test/viewer_auth_lifecycle_test.dartindex 2ba366c4d..d32823cd3 100644--- a/desktop/test/viewer_auth_lifecycle_test.dart+++ b/desktop/test/viewer_auth_lifecycle_test.dart@@ -66,6 +66,7 @@ class _Api extends DirectAuthApi {required String code,required String state,required String tx,+ Map<String, String> attribution = const {},}) {expect(code, 'fixture-code');expect(state, 'fixture-state');