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.

feat: record where a sign-in came from (utm_* and rid) on the user

Dev jacob2af09cbd6d26
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma
index edb548fb4..6f83c8356 100644
--- a/backend/prisma/schema.prisma
+++ b/backend/prisma/schema.prisma
@@ -39,6 +39,11 @@ 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.
+ // `firstAttribution` is the first tagged sign-in and is never rewritten — how the account was
+ // acquired; `lastAttribution` is the latest tagged one. Unset when no sign-in ever carried any.
+ firstAttribution SignInAttribution?
+ lastAttribution SignInAttribution?
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@ -46,6 +51,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..aa69b908c
--- /dev/null
+++ b/backend/src/lib/signInAttribution.ts
@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * `/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/routes/auth.ts b/backend/src/routes/auth.ts
index 86202e1f8..08cfe0c8d 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
@@ -80,7 +92,9 @@ export async function authRoutes(app: FastifyInstance): Promise<void> {
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.ts b/backend/src/services/UserService.ts
index d0c166cec..4f987555c 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'>
@@ -171,6 +172,16 @@ export const userService = {
}
},
+ /** Stamp a tagged sign-in: always the latest, and the first only while the user has none. */
+ async recordSignInAttribution(userId: string, attribution: SignInAttribution): Promise<void> {
+ const recorded = { ...attribution, recordedAt: new Date() }
+ await prisma.user.update({ where: { id: userId }, data: { lastAttribution: recorded } })
+ await prisma.user.updateMany({
+ where: { id: userId, firstAttribution: { isSet: false } },
+ data: { firstAttribution: recorded },
+ })
+ },
+
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');