Skip to content

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.

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.prisma
index 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 the
diff --git a/backend/src/lib/signInAttribution.test.ts b/backend/src/lib/signInAttribution.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 = null
try {
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_token
if (!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.ts
index 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.ts
index 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: AutonomousEnvironment
name?: string
roles?: 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.dart
index 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.dart
index 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.dart
new file mode 100644
index 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.dart
index 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.dart
index 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');