The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 22:00 UTC
feat(server): analytics records a stable install id and who owns each install (#21506)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 20, 2026 at 00:14 UTC
e2875821820e34047bc70bc786b8b39ef3fc35eb
23 files changed
+722
-298
apps/mobile/src/connection/platform.ts
+4
@@ -196,6 +196,10 @@ const layerCapabilities = Layer.effectContext(
196
bearerToken: Effect.succeed(Option.none()),
197
}),
198
),
199
+ // The relay device id already persists in secure storage; analytics only sends its hash.
200
+ Context.add(ClientCapabilities.AnalyticsDevice, {
201
+ id: storage.loadOrCreateAgentAwarenessDeviceId.pipe(Effect.option),
202
+ }),
203
Context.add(
204
ClientCapabilities.RelayDeviceIdentity,
205
ClientCapabilities.RelayDeviceIdentity.of({
apps/server/src/mcp/toolkits/core.test.ts
+1
@@ -483,6 +483,7 @@ it.effect("records the calling agent and the agent a tool acted on", () => {
483
properties: properties ?? {},
484
}).pipe(Effect.asVoid),
485
flush: Effect.void,
486
+ recordOwners: () => Effect.void,
487
}),
488
),
489
),
apps/server/src/provider/CodexChatGptAuth.test.ts
+1
@@ -220,6 +220,7 @@ const makeHarnessFor = Effect.fnUntraced(function* (
220
analyticsEvents.push({ event, properties });
221
}),
222
flush: Effect.void,
223
+ recordOwners: () => Effect.void,
224
});
225
const auth = yield* makeCodexChatGptAuth({
226
instanceId,
apps/server/src/provider/CodexChatGptAuth.ts
+14
@@ -9,9 +9,11 @@ import {
9
type ProviderInstanceId,
10
} from "@t3tools/contracts";
11
import { codexCallbackUrl } from "@t3tools/shared/codexAuthHandoff";
12
+import { hashTelemetryId } from "@t3tools/shared/telemetryId";
13
import * as Clock from "effect/Clock";
14
import * as Cause from "effect/Cause";
15
import * as AnalyticsService from "../telemetry/AnalyticsService.ts";
16
+import { openAiUserId } from "../telemetry/Identify.ts";
17
import * as Crypto from "effect/Crypto";
18
import * as Exit from "effect/Exit";
19
import { codexAuthCallbackPage, codexAuthReturnUrl } from "./CodexAuthCallbackPage.ts";
@@ -221,6 +223,18 @@ export const makeCodexChatGptAuth = Effect.fn("makeCodexChatGptAuth")(function*
223
saved.sessions.find((session) => session.clientId === saved.activeClientId),
224
),
225
),
226
+ // The OpenAI account is the person, so it marks who owns this install.
227
+ Effect.tap((credentials) => {
228
+ const userId = Option.flatMap(credentials, (saved) =>
229
+ Option.flatMap(Option.fromUndefinedOr(saved.idToken), openAiUserId),
230
+ );
231
+ return Option.isSome(userId) && Option.isSome(analytics)
232
+ ? analytics.value.recordOwners(
233
+ [{ source: "openai", ownerId: hashTelemetryId(userId.value) }],
234
+ "server",
235
+ )
236
+ : Effect.void;
237
+ }),
238
);
239
const writeSessions = (saved: typeof Sessions.Type) =>
240
encodeSessions(saved).pipe(
apps/server/src/serverRuntimeStartup.autoPull.test.ts
+5
@@ -5,6 +5,7 @@ import { DEFAULT_SIGNAL_EXPORT } from "@t3tools/shared/observability";
5
import * as OtelEnvironment from "@t3tools/shared/otelEnvironment";
6
import * as Deferred from "effect/Deferred";
7
import * as Effect from "effect/Effect";
8
+import * as FileSystem from "effect/FileSystem";
9
import * as Layer from "effect/Layer";
10
import * as Path from "effect/Path";
11
import { HttpServer } from "effect/http";
@@ -30,6 +31,7 @@ import { ServerActivation } from "./serverActivation.ts";
31
import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";
32
import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";
33
import * as ServerSettings from "./serverSettings.ts";
34
+import * as ServerSecretStore from "./auth/ServerSecretStore.ts";
35
import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
36
import * as GitVcsDriver from "./vcs/GitVcsDriver.ts";
37
@@ -163,6 +165,9 @@ it.effect("parks automatic pull until activation without delaying command readin
165
),
166
}),
167
Layer.mock(AnalyticsService.AnalyticsService)({ record: () => Effect.void }),
168
+ // No provider logins or Connect link, so startup records no owners.
169
+ FileSystem.layerNoop({}),
170
+ Layer.mock(ServerSecretStore.ServerSecretStore)({ get: () => Effect.succeedNone }),
171
NodeCrypto.layer,
172
Layer.mock(EnvironmentAuth.EnvironmentAuth)({}),
173
Layer.mock(ExternalLauncher.ExternalLauncher)({}),
apps/server/src/serverRuntimeStartup.test.ts
+5
@@ -16,6 +16,7 @@ import { HttpServer } from "effect/http";
16
import * as NetAddress from "effect/net/NetAddress";
17
import * as Deferred from "effect/Deferred";
18
import * as Effect from "effect/Effect";
19
+import * as FileSystem from "effect/FileSystem";
20
import * as Exit from "effect/Exit";
21
import * as Fiber from "effect/Fiber";
22
import * as Ref from "effect/Ref";
@@ -44,6 +45,7 @@ import * as AgentAwarenessRelay from "./relay/AgentAwarenessRelay.ts";
45
import { ServerActivation } from "./serverActivation.ts";
46
import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";
47
import * as ServerSettings from "./serverSettings.ts";
48
+import * as ServerSecretStore from "./auth/ServerSecretStore.ts";
49
import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
50
51
it("uses the canonical Codex model for auto-bootstrap", () => {
@@ -216,6 +218,9 @@ it.effect.each([
218
}),
219
Layer.mock(GitVcsDriver.GitVcsDriver)({}),
220
Layer.mock(AnalyticsService.AnalyticsService)({}),
221
+ // No provider logins or Connect link, so startup records no owners.
222
+ FileSystem.layerNoop({}),
223
+ Layer.mock(ServerSecretStore.ServerSecretStore)({ get: () => Effect.succeedNone }),
224
Layer.mock(EnvironmentAuth.EnvironmentAuth)({}),
225
Layer.mock(ExternalLauncher.ExternalLauncher)({}),
226
Layer.mock(HttpServer.HttpServer)({
apps/server/src/serverRuntimeStartup.ts
+2
@@ -45,6 +45,7 @@ import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";
45
import * as ServerSettings from "./serverSettings.ts";
46
import { forkParked, forkParkedFiber } from "./serverActivation.ts";
47
import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
48
+import { getServerOwners } from "./telemetry/Identify.ts";
49
import * as ServerEnvironment from "./environment/ServerEnvironment.ts";
50
import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";
51
import {
@@ -174,6 +175,7 @@ const recordStartupHeartbeat = Effect.gen(function* () {
175
threadCount,
176
projectCount,
177
});
178
+ yield* analytics.recordOwners(yield* getServerOwners, "server");
179
});
180
181
export const getAutoBootstrapThreadModelSelection = (): ModelSelection => ({
apps/server/src/telemetry/AnalyticsService.test.ts
+95
-11
@@ -16,7 +16,7 @@ import * as HttpServerResponse from "effect/http/HttpServerResponse";
16
import * as HostProcess from "@t3tools/shared/HostProcess";
17
18
import * as ServerConfig from "../config.ts";
19
-import { getTelemetryIdentifier } from "./Identify.ts";
19
+import { getTelemetryIdentity } from "./Identify.ts";
20
import * as AnalyticsService from "./AnalyticsService.ts";
21
22
interface RecordedBatchRequest {
@@ -57,7 +57,14 @@ const SentBatch = Schema.fromJsonString(
57
batch: Schema.Array(
58
Schema.Struct({
59
uuid: Schema.String,
60
- properties: Schema.Struct({ telemetryChannel: Schema.String }),
60
+ event: Schema.String,
61
+ distinct_id: Schema.String,
62
+ properties: Schema.Struct({
63
+ telemetryChannel: Schema.String,
64
+ installId: Schema.optionalKey(Schema.String),
65
+ ownerSource: Schema.optionalKey(Schema.String),
66
+ observedBy: Schema.optionalKey(Schema.String),
67
+ }),
68
}),
69
),
70
}),
@@ -81,11 +88,26 @@ const respondWithStatus =
88
(request) =>
89
Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status })));
90
91
+const recordTwentyEvents = Effect.gen(function* () {
92
+ const analytics = yield* AnalyticsService.AnalyticsService;
93
+ for (let index = 0; index < 20; index += 1) {
94
+ yield* analytics.record("test.retry", { index });
95
+ }
96
+});
97
+
98
/**
85
- * Records 20 events, then lets ten minutes of background flushes run against
86
- * a client that answers every send with `respond`. Returns the sent batches.
99
+ * Runs `record` (20 events by default), then lets ten minutes of background
100
+ * flushes run against a client that answers every send with `respond`.
101
+ * Returns the sent batches.
102
*/
88
-const sendForTenMinutes = (respond: Respond) =>
103
+const sendForTenMinutes = (
104
+ respond: Respond,
105
+ record: Effect.Effect<
106
+ void,
107
+ never,
108
+ AnalyticsService.AnalyticsService | Effect.Services<typeof getTelemetryIdentity>
109
+ > = recordTwentyEvents,
110
+) =>
111
Effect.gen(function* () {
112
const batches: Array<ReadonlyArray<SentEvent>> = [];
113
const client = HttpClient.make((request) =>
@@ -122,10 +144,7 @@ const sendForTenMinutes = (respond: Respond) =>
144
);
145
146
yield* Effect.gen(function* () {
125
- const analytics = yield* AnalyticsService.AnalyticsService;
126
- for (let index = 0; index < 20; index += 1) {
127
- yield* analytics.record("test.retry", { index });
128
- }
147
+ yield* record;
148
for (let second = 0; second < 600; second += 1) {
149
yield* TestClock.adjust("1 second");
150
}
@@ -181,6 +200,71 @@ it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
200
}).pipe(Effect.ensuring(Effect.sync(() => vi.unstubAllGlobals()))),
201
);
202
203
+ it.effect("each owner is sent once per process, and every event carries the install id", () =>
204
+ Effect.gen(function* () {
205
+ let identity: Effect.Success<typeof getTelemetryIdentity> | null = null;
206
+ const batches = yield* sendForTenMinutes(
207
+ respondWithStatus(204),
208
+ Effect.gen(function* () {
209
+ identity = yield* getTelemetryIdentity;
210
+ const analytics = yield* AnalyticsService.AnalyticsService;
211
+ const connect = { source: "connect", ownerId: "a".repeat(64) } as const;
212
+ yield* analytics.recordOwners([connect, connect], "server");
213
+ yield* analytics.recordOwners(
214
+ [connect, { source: "device", ownerId: "b".repeat(64) }],
215
+ "client",
216
+ );
217
+ }),
218
+ );
219
+ const events = batches.flat();
220
+
221
+ assert.deepEqual(
222
+ events.map((event) => [
223
+ event.event,
224
+ event.properties.ownerSource,
225
+ event.properties.observedBy,
226
+ ]),
227
+ [
228
+ ["install.owner_observed", "connect", "server"],
229
+ ["install.owner_observed", "connect", "client"],
230
+ ["install.owner_observed", "device", "client"],
231
+ ],
232
+ );
233
+ const { distinctId, installId } = identity!;
234
+ assert.isString(installId);
235
+ assert.isTrue(
236
+ events.every(
237
+ (event) => event.distinct_id === distinctId && event.properties.installId === installId,
238
+ ),
239
+ );
240
+ }),
241
+ );
242
+
243
+ it.effect("client owner reports cannot use up the server's owner cap", () =>
244
+ Effect.gen(function* () {
245
+ const batches = yield* sendForTenMinutes(
246
+ respondWithStatus(204),
247
+ Effect.gen(function* () {
248
+ const analytics = yield* AnalyticsService.AnalyticsService;
249
+ yield* analytics.recordOwners(
250
+ Array.from({ length: 1_001 }, (_, index) => ({
251
+ source: "device" as const,
252
+ ownerId: index.toString(16).padStart(64, "0"),
253
+ })),
254
+ "client",
255
+ );
256
+ // The event buffer also holds 1,000, so send the client events first.
257
+ yield* analytics.flush;
258
+ yield* analytics.recordOwners([{ source: "connect", ownerId: "a".repeat(64) }], "server");
259
+ }),
260
+ );
261
+ const owners = batches.flat().map((event) => event.properties.observedBy);
262
+
263
+ assert.equal(owners.filter((observedBy) => observedBy === "client").length, 1_000);
264
+ assert.equal(owners.filter((observedBy) => observedBy === "server").length, 1);
265
+ }),
266
+ );
267
+
268
it.effect("flush drains all buffered events across multiple batches", () =>
269
Effect.gen(function* () {
270
const capturedRequests: Array<RecordedBatchRequest> = [];
@@ -227,8 +311,8 @@ it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
311
312
yield* Effect.gen(function* () {
313
yield* Layer.launch(layerBatchServer).pipe(Effect.forkScoped);
230
- const telemetryIdentifier = yield* getTelemetryIdentifier;
231
- assert.equal(telemetryIdentifier !== null, true);
314
+ const { distinctId } = yield* getTelemetryIdentity;
315
+ assert.equal(distinctId !== null, true);
316
const analytics = yield* AnalyticsService.AnalyticsService;
317
318
for (let index = 0; index < 45; index += 1) {
apps/server/src/telemetry/AnalyticsService.ts
+48
-6
@@ -24,7 +24,7 @@ import * as HttpClientResponse from "effect/http/HttpClientResponse";
24
25
import packageJson from "../../package.json" with { type: "json" };
26
import * as ServerConfig from "../config.ts";
27
-import { getTelemetryIdentifier } from "./Identify.ts";
27
+import { getTelemetryIdentity, type TelemetryOwner } from "./Identify.ts";
28
29
interface BufferedAnalyticsEvent {
30
readonly uuid: string;
@@ -47,6 +47,10 @@ const FLUSH_INTERVAL_MS = 10_000;
47
const SEND_TIMEOUT = "10 seconds";
48
const MAX_BATCH_ATTEMPTS = 5;
49
const RETRY_BASE_DELAY_MS = 2_000;
50
+// Clients can report any number of owner ids; past this many per observer, new ones
51
+// are not sent. Each observer has its own cap, so client reports never crowd out the
52
+// server's own.
53
+const MAX_RECORDED_OWNERS = 1_000;
54
const RETRY_MAX_DELAY_MS = 300_000;
55
// The endpoint answers these when the batch itself is wrong (bad body, wrong
56
// api_key, too large), so sending it again cannot help. 408 and 429 are not
@@ -91,6 +95,16 @@ export class AnalyticsService extends Context.Service<
95
) => Effect.Effect<void>;
96
97
readonly flush: Effect.Effect<void>;
98
+
99
+ /**
100
+ * Records `install.owner_observed` for each owner of this install that the
101
+ * server read itself or a connecting client reported. Each owner is sent once
102
+ * per server process, so reconnects and repeated reads are free.
103
+ */
104
+ readonly recordOwners: (
105
+ owners: ReadonlyArray<TelemetryOwner>,
106
+ observedBy: "server" | "client",
107
+ ) => Effect.Effect<void>;
108
}
109
>()("t3/telemetry/AnalyticsService") {
110
static readonly layerTest = Layer.succeed(
@@ -98,6 +112,7 @@ export class AnalyticsService extends Context.Service<
112
AnalyticsService.of({
113
record: () => Effect.void,
114
flush: Effect.void,
115
+ recordOwners: () => Effect.void,
116
}),
117
);
118
}
@@ -123,7 +138,7 @@ export const make = Effect.gen(function* () {
138
const telemetryConfig = yield* TelemetryEnvConfig;
139
const httpClient = yield* HttpClient.HttpClient;
140
const serverConfig = yield* ServerConfig.ServerConfig;
126
- const identifier = yield* getTelemetryIdentifier;
141
+ const { distinctId, installId } = yield* getTelemetryIdentity;
142
const crypto = yield* Crypto.Crypto;
143
const bufferRef = yield* Ref.make<ReadonlyArray<BufferedAnalyticsEvent>>([]);
144
const deliveryRef = yield* Ref.make<DeliveryState>({
@@ -132,6 +147,9 @@ export const make = Effect.gen(function* () {
147
failures: 0,
148
retryAt: 0,
149
});
150
+ const recordedOwnersRef = yield* Ref.make<
151
+ Readonly<Record<"server" | "client", ReadonlySet<string>>>
152
+ >({ server: new Set(), client: new Set() });
153
// The background flush and the shutdown flush must not send the same batch at once.
154
const flushLock = yield* Semaphore.make(1);
155
const clientType = serverConfig.mode === "desktop" ? "desktop-app" : "cli-web-client";
@@ -175,16 +193,17 @@ export const make = Effect.gen(function* () {
193
const sendBatch = Effect.fn("AnalyticsService.sendBatch")(function* (
194
events: ReadonlyArray<BufferedAnalyticsEvent>,
195
) {
178
- if (!telemetryConfig.enabled || !identifier) return;
196
+ if (!telemetryConfig.enabled || !distinctId) return;
197
198
const payload = {
199
api_key: telemetryConfig.posthogKey,
200
batch: events.map((event) => ({
201
uuid: event.uuid,
202
event: event.event,
185
- distinct_id: identifier,
203
+ distinct_id: distinctId,
204
properties: {
205
...event.properties,
206
+ ...(installId === null ? {} : { installId }),
207
$process_person_profile: false,
208
platform: hostPlatform,
209
wsl: Option.getOrUndefined(telemetryConfig.wslDistroName),
@@ -267,7 +286,7 @@ export const make = Effect.gen(function* () {
286
287
const record: AnalyticsService["Service"]["record"] = Effect.fn("AnalyticsService.record")(
288
function* (event, properties) {
270
- if (!telemetryConfig.enabled || !identifier) return;
289
+ if (!telemetryConfig.enabled || !distinctId) return;
290
291
// Telemetry is best effort: an event without a uuid is not sent. The
292
// Node implementation throws (a defect) rather than failing, so catch both.
@@ -284,13 +303,36 @@ export const make = Effect.gen(function* () {
303
},
304
);
305
306
+ const recordOwners: AnalyticsService["Service"]["recordOwners"] = Effect.fn(
307
+ "AnalyticsService.recordOwners",
308
+ )((owners, observedBy) =>
309
+ Effect.forEach(
310
+ owners,
311
+ ({ source, ownerId }) =>
312
+ Ref.modify(recordedOwnersRef, (recorded) => {
313
+ const key = `${source}:${ownerId}`;
314
+ const seen = recorded[observedBy];
315
+ return seen.has(key) || seen.size >= MAX_RECORDED_OWNERS
316
+ ? [false, recorded]
317
+ : [true, { ...recorded, [observedBy]: new Set(seen).add(key) }];
318
+ }).pipe(
319
+ Effect.flatMap((isNew) =>
320
+ isNew
321
+ ? record("install.owner_observed", { ownerSource: source, ownerId, observedBy })
322
+ : Effect.void,
323
+ ),
324
+ ),
325
+ { discard: true },
326
+ ),
327
+ );
328
+
329
yield* Effect.forever(Effect.sleep(FLUSH_INTERVAL_MS).pipe(Effect.flatMap(() => flushWhenDue)), {
330
disableYield: true,
331
}).pipe(Effect.forkScoped);
332
333
yield* Effect.addFinalizer(() => flush);
334
293
- return AnalyticsService.of({ record, flush });
335
+ return AnalyticsService.of({ record, flush, recordOwners });
336
});
337
338
export const layer = Layer.effect(AnalyticsService, make);
apps/server/src/telemetry/DelegatedTaskAnalytics.test.ts
+1
@@ -92,6 +92,7 @@ it.effect("records each delegated task's final outcome once, without ids or prom
92
record: (event, properties) =>
93
Effect.sync(() => void recorded.push({ event, properties })),
94
flush: Effect.void,
95
+ recordOwners: () => Effect.void,
96
}),
97
),
98
),
apps/server/src/telemetry/Identify.test.ts
+180
-147
@@ -10,6 +10,8 @@ import * as Path from "effect/Path";
10
import * as PlatformError from "effect/PlatformError";
11
import * as References from "effect/References";
12
13
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
14
+import { CLOUD_LINKED_USER_ID } from "../cloud/config.ts";
15
import * as ServerConfig from "../config.ts";
16
import * as Identify from "./Identify.ts";
17
@@ -39,28 +41,76 @@ const findIdentityLog = (
41
errorTag: string,
42
) => logs.find((log) => log.annotations.source === source && log.annotations.errorTag === errorTag);
43
44
+const unsignedJwt = (claims: Readonly<Record<string, unknown>>) =>
45
+ ["e30", Buffer.from(JSON.stringify(claims)).toString("base64url"), "signature"].join(".");
46
+
47
+const layerIdentity = (prefix: string, logs?: CapturedLog[]) =>
48
+ Layer.provideMerge(
49
+ ServerSecretStore.layer,
50
+ ServerConfig.layerTest(process.cwd(), { prefix }),
51
+ ).pipe(
52
+ Layer.merge(
53
+ logs === undefined
54
+ ? Layer.empty
55
+ : Logger.layer([makeCaptureLogger(logs)], { mergeWithExisting: false }),
56
+ ),
57
+ );
58
+
59
+const writeHomeFile = Effect.fn("test.writeHomeFile")(function* (
60
+ homeDirectory: string,
61
+ relativePath: string,
62
+ contents: string,
63
+) {
64
+ const fileSystem = yield* FileSystem.FileSystem;
65
+ const path = yield* Path.Path;
66
+ const filePath = path.join(homeDirectory, relativePath);
67
+ yield* fileSystem.makeDirectory(path.dirname(filePath), { recursive: true });
68
+ yield* fileSystem.writeFileString(filePath, contents);
69
+ return filePath;
70
+});
71
+
72
it.layer(NodeServices.layer)("telemetry identity", (it) => {
43
- it.effect("uses the persisted anonymous id when provider identities are absent", () =>
73
+ it.effect("keeps the old distinct_id rule and a fixed install id as logins change", () =>
74
Effect.gen(function* () {
75
const config = yield* ServerConfig.ServerConfig;
76
const fileSystem = yield* FileSystem.FileSystem;
77
const path = yield* Path.Path;
78
+ const homeDirectory = path.join(config.baseDir, "home");
79
const anonymousId = "persisted-anonymous-id";
49
-
80
yield* fileSystem.writeFileString(config.anonymousIdPath, anonymousId);
81
+ const installId = yield* sha256(anonymousId);
82
+ const identity = () => Identify.getTelemetryIdentityForHome(homeDirectory);
83
52
- const identifier = yield* Identify.getTelemetryIdentifierForHome(
53
- path.join(config.baseDir, "home"),
54
- );
84
+ assert.deepEqual(yield* identity(), { distinctId: installId, installId });
85
56
- assert.equal(identifier, yield* sha256(anonymousId));
57
- }).pipe(
58
- Effect.provide(
59
- ServerConfig.layerTest(process.cwd(), {
60
- prefix: "t3-telemetry-identify-anonymous-",
61
- }),
62
- ),
63
- ),
86
+ yield* writeHomeFile(homeDirectory, ".claude.json", `{"userID":"claude-machine"}`);
87
+ assert.deepEqual(yield* identity(), {
88
+ distinctId: yield* sha256("claude-machine"),
89
+ installId,
90
+ });
91
+
92
+ yield* writeHomeFile(homeDirectory, ".codex/auth.json", `{"auth_mode":"apikey"}`);
93
+ assert.equal((yield* identity()).distinctId, yield* sha256("claude-machine"));
94
+
95
+ yield* writeHomeFile(homeDirectory, ".codex/auth.json", `{"tokens":{"account_id":"ws-1"}}`);
96
+ assert.deepEqual(yield* identity(), { distinctId: yield* sha256("ws-1"), installId });
97
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-install-"))),
98
+ );
99
+
100
+ it.effect("keeps a provider distinct_id when the install id cannot be saved", () =>
101
+ Effect.gen(function* () {
102
+ const config = yield* ServerConfig.ServerConfig;
103
+ const fileSystem = yield* FileSystem.FileSystem;
104
+ const path = yield* Path.Path;
105
+ const homeDirectory = path.join(config.baseDir, "home");
106
+ yield* fileSystem.makeDirectory(config.anonymousIdPath);
107
+ yield* writeHomeFile(homeDirectory, ".claude.json", `{"userID":"claude-machine"}`);
108
+
109
+ assert.deepEqual(yield* Identify.getTelemetryIdentityForHome(homeDirectory), {
110
+ distinctId: yield* sha256("claude-machine"),
111
+ installId: null,
112
+ });
113
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-noinstall-"))),
114
);
115
116
it.effect("leaves no torn anonymous id behind when its write fails midway", () =>
@@ -87,19 +137,77 @@ it.layer(NodeServices.layer)("telemetry identity", (it) => {
137
),
138
});
139
90
- const identifier = yield* Identify.getTelemetryIdentifierForHome(
140
+ const identity = yield* Identify.getTelemetryIdentityForHome(
141
path.join(config.baseDir, "home"),
142
).pipe(Effect.provideService(FileSystem.FileSystem, tornWrites));
143
94
- assert.isNull(identifier);
144
+ assert.deepEqual(identity, { distinctId: null, installId: null });
145
assert.isFalse(yield* fileSystem.exists(config.anonymousIdPath));
96
- }).pipe(
97
- Effect.provide(
98
- ServerConfig.layerTest(process.cwd(), {
99
- prefix: "t3-telemetry-identify-torn-",
146
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-torn-"))),
147
+ );
148
+
149
+ it.effect("does not overwrite the anonymous id path after a non-NotFound read failure", () => {
150
+ const logs: CapturedLog[] = [];
151
+
152
+ return Effect.gen(function* () {
153
+ const config = yield* ServerConfig.ServerConfig;
154
+ const fileSystem = yield* FileSystem.FileSystem;
155
+ const path = yield* Path.Path;
156
+ yield* fileSystem.makeDirectory(config.anonymousIdPath);
157
+
158
+ const identity = yield* Identify.getTelemetryIdentityForHome(
159
+ path.join(config.baseDir, "home"),
160
+ );
161
+ assert.deepEqual(identity, { distinctId: null, installId: null });
162
+ assert.deepEqual(yield* fileSystem.readDirectory(config.anonymousIdPath), []);
163
+
164
+ const readLog = findIdentityLog(logs, "anonymous", "TelemetryIdentityReadError");
165
+ assert.equal(readLog?.annotations.filePath, config.anonymousIdPath);
166
+ assert.notEqual(readLog?.annotations.platformReason, "NotFound");
167
+ assert.notProperty(readLog?.annotations ?? {}, "cause");
168
+ assert.isUndefined(
169
+ findIdentityLog(logs, "anonymous", "TelemetryAnonymousIdPersistenceError"),
170
+ );
171
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-read-", logs)));
172
+ });
173
+
174
+ it.effect("reads the Connect account and each provider account as owners", () =>
175
+ Effect.gen(function* () {
176
+ const config = yield* ServerConfig.ServerConfig;
177
+ const secrets = yield* ServerSecretStore.ServerSecretStore;
178
+ const path = yield* Path.Path;
179
+ const homeDirectory = path.join(config.baseDir, "home");
180
+ yield* secrets.set(CLOUD_LINKED_USER_ID, new TextEncoder().encode("user_connect"));
181
+ yield* writeHomeFile(
182
+ homeDirectory,
183
+ ".codex/auth.json",
184
+ JSON.stringify({
185
+ tokens: {
186
+ account_id: "team-workspace",
187
+ id_token: unsignedJwt({
188
+ sub: "google-oauth2|login-method",
189
+ "https://api.openai.com/auth": { user_id: "user-openai-person" },
190
+ }),
191
+ },
192
}),
101
- ),
102
- ),
193
+ );
194
+ yield* writeHomeFile(
195
+ homeDirectory,
196
+ ".claude.json",
197
+ JSON.stringify({
198
+ userID: "claude-machine",
199
+ oauthAccount: { accountUuid: "claude-person" },
200
+ }),
201
+ );
202
+
203
+ const owners = yield* Identify.getServerOwnersForHome(homeDirectory);
204
+
205
+ assert.deepEqual(owners, [
206
+ { source: "connect", ownerId: yield* sha256("user_connect") },
207
+ { source: "openai", ownerId: yield* sha256("user-openai-person") },
208
+ { source: "claude", ownerId: yield* sha256("claude-person") },
209
+ ]);
210
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-owners-"))),
211
);
212
213
it.effect.each([
@@ -119,135 +227,60 @@ it.layer(NodeServices.layer)("telemetry identity", (it) => {
227
secret: "private-personal-access-token",
228
authJson: (secret: string) => `{"OPENAI_API_KEY":null,"personal_access_token":"${secret}"}`,
229
},
122
- ])("falls back quietly when Codex authenticates with $login", ({ secret, authJson }) => {
123
- const logs: CapturedLog[] = [];
124
- const logger = makeCaptureLogger(logs);
125
-
126
- return Effect.gen(function* () {
127
- const config = yield* ServerConfig.ServerConfig;
128
- const fileSystem = yield* FileSystem.FileSystem;
129
- const path = yield* Path.Path;
130
- const homeDirectory = path.join(config.baseDir, "home");
131
- const codexAuthPath = path.join(homeDirectory, ".codex", "auth.json");
132
- const anonymousId = "tokenless-codex-anonymous-id";
230
+ ])(
231
+ "adds no owner and logs nothing when Codex authenticates with $login",
232
+ ({ secret, authJson }) => {
233
+ const logs: CapturedLog[] = [];
234
134
- yield* fileSystem.makeDirectory(path.dirname(codexAuthPath), { recursive: true });
135
- yield* fileSystem.writeFileString(codexAuthPath, authJson(secret));
136
- yield* fileSystem.writeFileString(config.anonymousIdPath, anonymousId);
235
+ return Effect.gen(function* () {
236
+ const config = yield* ServerConfig.ServerConfig;
237
+ const path = yield* Path.Path;
238
+ const homeDirectory = path.join(config.baseDir, "home");
239
+ yield* writeHomeFile(homeDirectory, ".codex/auth.json", authJson(secret));
240
138
- const identifier = yield* Identify.getTelemetryIdentifierForHome(homeDirectory);
139
-
140
- assert.equal(identifier, yield* sha256(anonymousId));
141
- assert.isUndefined(findIdentityLog(logs, "codex", "TelemetryIdentityDecodeError"));
142
- assert.isUndefined(findIdentityLog(logs, "codex", "TelemetryIdentityReadError"));
143
- const allLogs = logs
144
- .map((log) =>
145
- [String(log.message), ...Object.values(log.annotations).map(String)].join("\n"),
146
- )
147
- .join("\n");
148
- assert.notInclude(allLogs, secret);
149
- }).pipe(
150
- Effect.provide(
151
- Layer.merge(
152
- ServerConfig.layerTest(process.cwd(), {
153
- prefix: "t3-telemetry-identify-tokenless-",
154
- }),
155
- Logger.layer([logger], { mergeWithExisting: false }),
156
- ),
157
- ),
158
- );
159
- });
160
-
161
- it.effect("logs structured decode context and falls back from malformed Codex auth", () => {
162
- const logs: CapturedLog[] = [];
163
- const logger = makeCaptureLogger(logs);
164
-
165
- return Effect.gen(function* () {
166
- const config = yield* ServerConfig.ServerConfig;
167
- const fileSystem = yield* FileSystem.FileSystem;
168
- const path = yield* Path.Path;
169
- const homeDirectory = path.join(config.baseDir, "home");
170
- const codexAuthPath = path.join(homeDirectory, ".codex", "auth.json");
171
- const anonymousId = "decode-fallback-anonymous-id";
172
- const privateAccessToken = "private-codex-access-token";
173
-
174
- yield* fileSystem.makeDirectory(path.dirname(codexAuthPath), { recursive: true });
175
- yield* fileSystem.writeFileString(
176
- codexAuthPath,
177
- `{"tokens":{"access_token":"${privateAccessToken}"}}`,
178
- );
179
- yield* fileSystem.writeFileString(config.anonymousIdPath, anonymousId);
180
-
181
- const identifier = yield* Identify.getTelemetryIdentifierForHome(homeDirectory);
182
-
183
- assert.equal(identifier, yield* sha256(anonymousId));
184
- const decodeLog = findIdentityLog(logs, "codex", "TelemetryIdentityDecodeError");
185
- assert.isDefined(decodeLog);
186
- assert.equal(
187
- decodeLog?.message,
188
- `Failed to decode codex telemetry identity at '${codexAuthPath}'.`,
189
- );
190
-
191
- assert.equal(decodeLog?.annotations.filePath, codexAuthPath);
192
- assert.equal(decodeLog?.annotations.causeKind, "schema");
193
- assert.notProperty(decodeLog?.annotations ?? {}, "cause");
194
- const errorStack = decodeLog?.annotations.errorStack;
195
- assert.isString(errorStack);
196
- assert.include(errorStack, "Failed to decode codex telemetry identity");
197
- const annotations = Object.values(decodeLog?.annotations ?? {})
198
- .map(String)
199
- .join("\n");
200
- assert.notInclude(annotations, privateAccessToken);
201
- }).pipe(
202
- Effect.provide(
203
- Layer.merge(
204
- ServerConfig.layerTest(process.cwd(), {
205
- prefix: "t3-telemetry-identify-decode-",
206
- }),
207
- Logger.layer([logger], { mergeWithExisting: false }),
208
- ),
209
- ),
210
- );
211
- });
212
-
213
- it.effect("does not overwrite the anonymous id path after a non-NotFound read failure", () => {
214
- const logs: CapturedLog[] = [];
215
- const logger = makeCaptureLogger(logs);
216
-
217
- return Effect.gen(function* () {
218
- const config = yield* ServerConfig.ServerConfig;
219
- const fileSystem = yield* FileSystem.FileSystem;
220
- const path = yield* Path.Path;
221
- const homeDirectory = path.join(config.baseDir, "home");
222
-
223
- yield* fileSystem.makeDirectory(config.anonymousIdPath);
241
+ assert.deepEqual(yield* Identify.getServerOwnersForHome(homeDirectory), []);
242
+ assert.deepEqual(logs, []);
243
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-tokenless-", logs)));
244
+ },
245
+ );
246
225
- const identifier = yield* Identify.getTelemetryIdentifierForHome(homeDirectory);
247
+ it.effect(
248
+ "warns about malformed Codex auth without its tokens and keeps the other owners",
249
+ () => {
250
+ const logs: CapturedLog[] = [];
251
227
- assert.isNull(identifier);
228
- assert.deepEqual(yield* fileSystem.readDirectory(config.anonymousIdPath), []);
252
+ return Effect.gen(function* () {
253
+ const config = yield* ServerConfig.ServerConfig;
254
+ const path = yield* Path.Path;
255
+ const homeDirectory = path.join(config.baseDir, "home");
256
+ const privateAccessToken = "private-codex-access-token";
257
+ const codexAuthPath = yield* writeHomeFile(
258
+ homeDirectory,
259
+ ".codex/auth.json",
260
+ `{"tokens":{"access_token":"${privateAccessToken}"}}`,
261
+ );
262
+ yield* writeHomeFile(
263
+ homeDirectory,
264
+ ".claude.json",
265
+ `{"oauthAccount":{"accountUuid":"claude-person"}}`,
266
+ );
267
230
- const readLog = findIdentityLog(logs, "anonymous", "TelemetryIdentityReadError");
231
- assert.isDefined(readLog);
232
- assert.equal(readLog?.annotations.filePath, config.anonymousIdPath);
233
- assert.equal(readLog?.annotations.causeKind, "platform");
234
- assert.notEqual(readLog?.annotations.platformReason, "NotFound");
235
- assert.notProperty(readLog?.annotations ?? {}, "cause");
236
- const errorStack = readLog?.annotations.errorStack;
237
- assert.isString(errorStack);
238
- assert.include(errorStack, "Failed to read anonymous telemetry identity");
239
- assert.isUndefined(
240
- findIdentityLog(logs, "anonymous", "TelemetryAnonymousIdPersistenceError"),
241
- );
242
- }).pipe(
243
- Effect.provide(
244
- Layer.merge(
245
- ServerConfig.layerTest(process.cwd(), {
246
- prefix: "t3-telemetry-identify-read-",
247
- }),
248
- Logger.layer([logger], { mergeWithExisting: false }),
249
- ),
250
- ),
251
- );
252
- });
268
+ assert.deepEqual(yield* Identify.getServerOwnersForHome(homeDirectory), [
269
+ { source: "claude", ownerId: yield* sha256("claude-person") },
270
+ ]);
271
+ const decodeLog = findIdentityLog(logs, "codex", "TelemetryIdentityDecodeError");
272
+ assert.equal(
273
+ decodeLog?.message,
274
+ `Failed to decode codex telemetry identity at '${codexAuthPath}'.`,
275
+ );
276
+ assert.equal(decodeLog?.annotations.causeKind, "schema");
277
+ assert.notInclude(
278
+ Object.values(decodeLog?.annotations ?? {})
279
+ .map(String)
280
+ .join("\n"),
281
+ privateAccessToken,
282
+ );
283
+ }).pipe(Effect.provide(layerIdentity("t3-telemetry-identify-decode-", logs)));
284
+ },
285
+ );
286
});
apps/server/src/telemetry/Identify.ts
+160
-122
@@ -1,33 +1,66 @@
1
import * as Crypto from "effect/Crypto";
2
import * as Effect from "effect/Effect";
3
-import * as Hex from "effect/encoding/Hex";
3
+import * as Base64Url from "effect/encoding/Base64Url";
4
import * as FileSystem from "effect/FileSystem";
5
import * as Option from "effect/Option";
6
import * as Path from "effect/Path";
7
import * as PlatformError from "effect/PlatformError";
8
+import * as Result from "effect/Result";
9
import * as Schema from "effect/Schema";
10
11
import { writeFileStringAtomically } from "@t3tools/shared/atomicWrite";
11
-import * as ServerConfig from "../config.ts";
12
import * as HostProcess from "@t3tools/shared/HostProcess";
13
+import { hashTelemetryId } from "@t3tools/shared/telemetryId";
14
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
15
+import { CLOUD_LINKED_USER_ID } from "../cloud/config.ts";
16
+import * as ServerConfig from "../config.ts";
17
18
/**
19
* Codex writes `tokens` only for ChatGPT logins and omits the key for API-key,
20
* agent-identity, and personal-access-token logins, so its absence is a
17
- * supported install and not a malformed file.
21
+ * supported install and not a malformed file. `account_id` is the ChatGPT
22
+ * workspace, which a whole Team shares; the `id_token` names the person.
23
*/
24
const CodexAuthJsonSchema = Schema.Struct({
25
tokens: Schema.optionalKey(
26
Schema.Struct({
27
account_id: Schema.String,
28
+ id_token: Schema.optionalKey(Schema.String),
29
}),
30
),
31
});
32
33
+/** `userID` is random per machine. `oauthAccount` is present only while Claude Code is logged in. */
34
const ClaudeJsonSchema = Schema.Struct({
28
- userID: Schema.String,
35
+ userID: Schema.optionalKey(Schema.String),
36
+ oauthAccount: Schema.optionalKey(
37
+ Schema.Struct({
38
+ accountUuid: Schema.optionalKey(Schema.String),
39
+ }),
40
+ ),
41
});
42
43
+// `sub` names the login method (`google-oauth2|…`), so one person can have several.
44
+// `user_id` (`user-…`) is the OpenAI account and is the same for every login.
45
+const IdTokenClaims = Schema.Struct({
46
+ "https://api.openai.com/auth": Schema.Struct({ user_id: Schema.NonEmptyString }),
47
+});
48
+const decodeIdTokenClaims = Schema.decodeUnknownOption(Schema.fromJsonString(IdTokenClaims));
49
+
50
+/**
51
+ * Who an install belongs to, from strongest to weakest. `connect` is the T3
52
+ * Connect account. `openai` and `claude` are provider accounts. `device` is a
53
+ * client device that connected.
54
+ */
55
+export const TelemetryOwnerSource = Schema.Literals(["connect", "openai", "claude", "device"]);
56
+export type TelemetryOwnerSource = typeof TelemetryOwnerSource.Type;
57
+
58
+export interface TelemetryOwner {
59
+ readonly source: TelemetryOwnerSource;
60
+ /** `hashTelemetryId` of the source's raw id. */
61
+ readonly ownerId: string;
62
+}
63
+
64
export const TelemetryIdentitySource = Schema.Literals(["codex", "claude", "anonymous"]);
65
export type TelemetryIdentitySource = typeof TelemetryIdentitySource.Type;
66
@@ -83,25 +116,11 @@ export class TelemetryAnonymousIdPersistenceError extends Schema.TaggedError<Tel
116
}
117
}
118
86
-export class TelemetryIdentityHashError extends Schema.TaggedError<TelemetryIdentityHashError>()(
87
- "TelemetryIdentityHashError",
88
- {
89
- source: TelemetryIdentitySource,
90
- algorithm: Schema.Literal("SHA-256"),
91
- cause: Schema.Defect(),
92
- },
93
-) {
94
- override get message(): string {
95
- return `Failed to hash ${this.source} telemetry identity with ${this.algorithm}.`;
96
- }
97
-}
98
-
119
type TelemetryIdentityError =
120
| TelemetryIdentityReadError
121
| TelemetryIdentityDecodeError
122
| TelemetryAnonymousIdGenerationError
103
- | TelemetryAnonymousIdPersistenceError
104
- | TelemetryIdentityHashError;
123
+ | TelemetryAnonymousIdPersistenceError;
124
125
const decodeCodexAuthJson = Schema.decodeEffect(Schema.fromJsonString(CodexAuthJsonSchema));
126
const decodeClaudeJson = Schema.decodeEffect(Schema.fromJsonString(ClaudeJsonSchema));
@@ -155,72 +174,48 @@ const readIdentityFile = (
174
}),
175
);
176
158
-const hash = (source: TelemetryIdentitySource, value: string) =>
159
- Crypto.Crypto.pipe(
160
- Effect.flatMap((crypto) => crypto.digest("SHA-256", new TextEncoder().encode(value))),
161
- Effect.map(Hex.encode),
162
- Effect.mapError(
163
- (cause) =>
164
- new TelemetryIdentityHashError({
165
- source,
166
- algorithm: "SHA-256",
167
- cause,
168
- }),
169
- ),
170
- );
177
+/**
178
+ * The OpenAI account id in a ChatGPT id_token, read without verifying it:
179
+ * analytics needs only a stable id. Codex CLI and T3's own sign-in both use it.
180
+ */
181
+export const openAiUserId = (idToken: string) => {
182
+ const payload = Base64Url.decodeString(idToken.split(".")[1] ?? "");
183
+ return Result.isSuccess(payload)
184
+ ? Option.map(
185
+ decodeIdTokenClaims(payload.success),
186
+ (claims) => claims["https://api.openai.com/auth"].user_id,
187
+ )
188
+ : Option.none<string>();
189
+};
190
172
-const getCodexAccountId = Effect.fn("TelemetryIdentity.getCodexAccountId")(function* (
173
- homeDirectory: string,
191
+const readJsonIdentityFile = Effect.fn("TelemetryIdentity.readJsonIdentityFile")(function* <A>(
192
+ source: "codex" | "claude",
193
+ filePath: string,
194
+ decode: (encoded: string) => Effect.Effect<A, Schema.SchemaError>,
195
) {
196
const fileSystem = yield* FileSystem.FileSystem;
176
- const path = yield* Path.Path;
177
-
178
- const authJsonPath = path.join(homeDirectory, ".codex", "auth.json");
179
- const encoded = yield* readIdentityFile(fileSystem, "codex", authJsonPath);
197
+ const encoded = yield* readIdentityFile(fileSystem, source, filePath);
198
if (Option.isNone(encoded)) {
181
- return Option.none<string>();
199
+ return Option.none<A>();
200
}
183
- const authJson = yield* decodeCodexAuthJson(encoded.value).pipe(
184
- Effect.mapError(
185
- (cause) =>
186
- new TelemetryIdentityDecodeError({
187
- source: "codex",
188
- filePath: authJsonPath,
189
- cause,
190
- }),
191
- ),
201
+ return yield* decode(encoded.value).pipe(
202
+ Effect.asSome,
203
+ Effect.mapError((cause) => new TelemetryIdentityDecodeError({ source, filePath, cause })),
204
);
193
-
194
- return authJson.tokens === undefined
195
- ? Option.none<string>()
196
- : Option.some(authJson.tokens.account_id);
205
});
206
199
-const getClaudeUserId = Effect.fn("TelemetryIdentity.getClaudeUserId")(function* (
200
- homeDirectory: string,
201
-) {
202
- const fileSystem = yield* FileSystem.FileSystem;
203
- const path = yield* Path.Path;
204
-
205
- const claudeJsonPath = path.join(homeDirectory, ".claude.json");
206
- const encoded = yield* readIdentityFile(fileSystem, "claude", claudeJsonPath);
207
- if (Option.isNone(encoded)) {
208
- return Option.none<string>();
209
- }
210
- const claudeJson = yield* decodeClaudeJson(encoded.value).pipe(
211
- Effect.mapError(
212
- (cause) =>
213
- new TelemetryIdentityDecodeError({
214
- source: "claude",
215
- filePath: claudeJsonPath,
216
- cause,
217
- }),
218
- ),
207
+// A missing or unreadable file only removes that owner; it never blocks the others.
208
+const skipOnError = <A, R>(
209
+ effect: Effect.Effect<
210
+ Option.Option<A>,
211
+ TelemetryIdentityReadError | TelemetryIdentityDecodeError,
212
+ R
213
+ >,
214
+) =>
215
+ effect.pipe(
216
+ Effect.catch((error) => logTelemetryIdentityError(error).pipe(Effect.as(Option.none<A>()))),
217
);
218
221
- return Option.some(claudeJson.userID);
222
-});
223
-
219
const upsertAnonymousId = Effect.gen(function* () {
220
const fileSystem = yield* FileSystem.FileSystem;
221
const { anonymousIdPath } = yield* ServerConfig.ServerConfig;
@@ -255,54 +250,97 @@ const upsertAnonymousId = Effect.gen(function* () {
250
return anonymousId;
251
});
252
258
-export const getTelemetryIdentifierForHome = Effect.fn("getTelemetryIdentifierForHome")(
259
- function* (homeDirectory: string) {
260
- const codexAccountId = yield* getCodexAccountId(homeDirectory).pipe(
261
- Effect.catchTags({
262
- TelemetryIdentityReadError: (error) =>
263
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
264
- TelemetryIdentityDecodeError: (error) =>
265
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
266
- }),
267
- );
268
- if (Option.isSome(codexAccountId)) {
269
- return yield* hash("codex", codexAccountId.value);
270
- }
271
-
272
- const claudeUserId = yield* getClaudeUserId(homeDirectory).pipe(
273
- Effect.catchTags({
274
- TelemetryIdentityReadError: (error) =>
275
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
276
- TelemetryIdentityDecodeError: (error) =>
277
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
278
- }),
279
- );
280
- if (Option.isSome(claudeUserId)) {
281
- return yield* hash("claude", claudeUserId.value);
282
- }
283
-
284
- const anonymousId = yield* upsertAnonymousId.pipe(
285
- Effect.asSome,
286
- Effect.catchTags({
287
- TelemetryIdentityReadError: (error) =>
288
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
289
- TelemetryAnonymousIdGenerationError: (error) =>
290
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
291
- TelemetryAnonymousIdPersistenceError: (error) =>
292
- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),
293
- }),
294
- );
295
- if (Option.isSome(anonymousId)) {
296
- return yield* hash("anonymous", anonymousId.value);
297
- }
253
+const readProviderLogins = Effect.fn("TelemetryIdentity.readProviderLogins")(function* (
254
+ homeDirectory: string,
255
+) {
256
+ const path = yield* Path.Path;
257
+ const codexTokens = yield* readJsonIdentityFile(
258
+ "codex",
259
+ path.join(homeDirectory, ".codex", "auth.json"),
260
+ decodeCodexAuthJson,
261
+ ).pipe(
262
+ skipOnError,
263
+ Effect.map(Option.flatMap((authJson) => Option.fromUndefinedOr(authJson.tokens))),
264
+ );
265
+ const claudeJson = yield* readJsonIdentityFile(
266
+ "claude",
267
+ path.join(homeDirectory, ".claude.json"),
268
+ decodeClaudeJson,
269
+ ).pipe(skipOnError);
270
+ return { codexTokens, claudeJson };
271
+});
272
299
- return null;
300
- },
301
- Effect.tapError(logTelemetryIdentityError),
302
- Effect.orElseSucceed(() => null),
303
-);
273
+/**
274
+ * `distinctId` keeps the rule every earlier build used, so analytics stay
275
+ * continuous: the hashed Codex `account_id`, else the Claude machine `userID`,
276
+ * else the install's anonymous id. It can change when someone logs in, and a
277
+ * Codex Team shares one. `installId` is the hashed anonymous id, which never
278
+ * changes for an install; count installs and people with it.
279
+ *
280
+ * A null `distinctId` turns telemetry off. A missing file falls through quietly,
281
+ * and so does an API-key-only Codex auth.json. Only unreadable or malformed
282
+ * files warn.
283
+ */
284
+export const getTelemetryIdentityForHome = Effect.fn("getTelemetryIdentityForHome")(function* (
285
+ homeDirectory: string,
286
+) {
287
+ const { codexTokens, claudeJson } = yield* readProviderLogins(homeDirectory);
288
+ const installId = yield* upsertAnonymousId.pipe(
289
+ Effect.map(hashTelemetryId),
290
+ Effect.catch((error) => logTelemetryIdentityError(error).pipe(Effect.as(null))),
291
+ );
292
+ const providerId = Option.orElse(
293
+ Option.map(codexTokens, (tokens) => tokens.account_id),
294
+ () => Option.flatMap(claudeJson, (json) => Option.fromUndefinedOr(json.userID)),
295
+ );
296
+ return {
297
+ distinctId: Option.isSome(providerId) ? hashTelemetryId(providerId.value) : installId,
298
+ installId,
299
+ };
300
+});
301
305
-export const getTelemetryIdentifier = Effect.flatMap(
302
+export const getTelemetryIdentity = Effect.flatMap(
303
HostProcess.HomeDirectory,
307
- getTelemetryIdentifierForHome,
304
+ getTelemetryIdentityForHome,
305
);
306
+
307
+/**
308
+ * Owners the server can read without a client: the linked T3 Connect account
309
+ * and the provider logins under `homeDirectory`. Clients add `connect` and
310
+ * `device` owners when they connect.
311
+ */
312
+export const getServerOwnersForHome = Effect.fn("getServerOwnersForHome")(function* (
313
+ homeDirectory: string,
314
+) {
315
+ const secrets = yield* ServerSecretStore.ServerSecretStore;
316
+ const connectUser = yield* secrets.get(CLOUD_LINKED_USER_ID).pipe(
317
+ Effect.map(Option.map((bytes) => new TextDecoder().decode(bytes))),
318
+ Effect.catch((cause) =>
319
+ Effect.logWarning("Failed to read the linked T3 Connect account for telemetry", {
320
+ errorTag: cause._tag,
321
+ }).pipe(Effect.as(Option.none<string>())),
322
+ ),
323
+ );
324
+ const { codexTokens, claudeJson } = yield* readProviderLogins(homeDirectory);
325
+
326
+ const raw: ReadonlyArray<readonly [TelemetryOwnerSource, Option.Option<string>]> = [
327
+ ["connect", connectUser],
328
+ [
329
+ "openai",
330
+ Option.flatMap(codexTokens, (tokens) =>
331
+ Option.flatMap(Option.fromUndefinedOr(tokens.id_token), openAiUserId),
332
+ ),
333
+ ],
334
+ [
335
+ "claude",
336
+ Option.flatMap(claudeJson, (json) => Option.fromUndefinedOr(json.oauthAccount?.accountUuid)),
337
+ ],
338
+ ];
339
+ return raw.flatMap(([source, value]): ReadonlyArray<TelemetryOwner> =>
340
+ Option.isSome(value) && value.value.trim() !== ""
341
+ ? [{ source, ownerId: hashTelemetryId(value.value) }]
342
+ : [],
343
+ );
344
+});
345
+
346
+export const getServerOwners = Effect.flatMap(HostProcess.HomeDirectory, getServerOwnersForHome);
apps/server/src/ws.ts
+25
@@ -224,6 +224,7 @@ import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";
224
import * as HostResources from "./resourceTelemetry/HostResources.ts";
225
import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
226
import { featureUsage } from "./telemetry/FeatureUsage.ts";
227
+import type { TelemetryOwner } from "./telemetry/Identify.ts";
228
import * as UsageService from "./usage/UsageService.ts";
229
import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
230
import * as PullRequestService from "./pullRequest/PullRequestService.ts";
@@ -244,6 +245,7 @@ import * as PairingGrantStore from "./auth/PairingGrantStore.ts";
245
import * as SessionStore from "./auth/SessionStore.ts";
246
import { failEnvironmentAuthInvalid, failEnvironmentInternal } from "./auth/http.ts";
247
import * as RelayClient from "@t3tools/shared/relayClient";
248
+import { isTelemetryIdHash } from "@t3tools/shared/telemetryId";
249
import {
250
sameUsageLimitCommandCoverage,
251
withUsageLimitsCommands,
@@ -674,6 +676,28 @@ function readClientAnalyticsProps(request: HttpServerRequest.HttpServerRequest)
676
};
677
}
678
679
+/**
680
+ * Owners a connecting client reports: its hashed T3 Connect account and its
681
+ * hashed device id. Only hashes are accepted, so a raw id never reaches analytics.
682
+ */
683
+function readClientOwners(
684
+ request: HttpServerRequest.HttpServerRequest,
685
+): ReadonlyArray<TelemetryOwner> {
686
+ const url = HttpServerRequest.toURL(request);
687
+ if (Option.isNone(url)) {
688
+ return [];
689
+ }
690
+ const params = url.value.searchParams;
691
+ return (
692
+ [
693
+ ["connect", params.get("clientOwner")],
694
+ ["device", params.get("clientDevice")],
695
+ ] as const
696
+ ).flatMap(([source, ownerId]) =>
697
+ ownerId !== null && isTelemetryIdHash(ownerId) ? [{ source, ownerId }] : [],
698
+ );
699
+}
700
+
701
const canReplayPersistedRange = Effect.fnUntraced(function* (
702
afterSequence: number,
703
headSequence: number,
@@ -3124,6 +3148,7 @@ export const layer = Layer.unwrap(
3148
const clientAnalyticsProps = readClientAnalyticsProps(request);
3149
yield* sessions.recordClientConnection(session.sessionId, clientOrigin);
3150
yield* analytics.record("client.connected", clientAnalyticsProps);
3151
+ yield* analytics.recordOwners(readClientOwners(request), "client");
3152
const rpcWebSocketHttpEffect = yield* Effect.gen(function* () {
3153
const { protocol, httpEffect } = yield* RpcServer.makeProtocolWithHttpEffectWebsocket;
3154
yield* RpcServer.make(ServerWsRpcGroup, WS_RPC_SERVER_OPTIONS).pipe(
apps/web/src/connection/platform.ts
+15
@@ -52,6 +52,7 @@ import {
52
import { clearComposerDraftsEnvironment } from "../composerDraftStore";
53
import { isHostedStaticApp } from "../hostedPairing";
54
import { isLocalEnvironmentDisabled } from "../localEnvironment";
55
+import { randomUUID } from "../lib/utils";
56
import { appAtomRegistry } from "../rpc/atomRegistry";
57
import { acknowledgeRpcRequest, trackRpcRequestSent } from "../rpc/requestLatencyState";
58
import {
@@ -302,6 +303,19 @@ export const prepareDesktopSshEnvironment = Effect.fn("web.connectionPlatform.ss
303
},
304
);
305
306
+const ANALYTICS_DEVICE_ID_KEY = "t3code:analytics-device-id";
307
+
308
+// Lives as long as this browser profile's site data. Storage can be blocked, which only drops the id.
309
+const analyticsDevice = {
310
+ id: Effect.try(() => {
311
+ const existing = window.localStorage.getItem(ANALYTICS_DEVICE_ID_KEY);
312
+ if (existing) return existing;
313
+ const created = randomUUID();
314
+ window.localStorage.setItem(ANALYTICS_DEVICE_ID_KEY, created);
315
+ return created;
316
+ }).pipe(Effect.option),
317
+};
318
+
319
const layerCapabilities = Layer.effectContext(
320
Effect.sync(() => {
321
const presentation = ClientCapabilities.ClientPresentation.of({
@@ -391,6 +405,7 @@ const layerCapabilities = Layer.effectContext(
405
});
406
407
return Context.make(ClientCapabilities.CloudSession, cloudSession).pipe(
408
+ Context.add(ClientCapabilities.AnalyticsDevice, analyticsDevice),
409
Context.add(ClientCapabilities.PrimaryEnvironmentAuth, primaryAuth),
410
Context.add(ClientCapabilities.RelayDeviceIdentity, identity),
411
Context.add(ClientCapabilities.ClientPresentation, presentation),
docs/internals/product-analytics.md
+30
-5
@@ -1,11 +1,36 @@
1
# Product analytics
2
3
The server owns analytics delivery, opt-out, and identity for every connected client.
4
-[Identity selection](../../apps/server/src/telemetry/Identify.ts) hashes an available
5
-provider account ID, falling back to an installation-scoped ID. This identity can
6
-span several clients; it does not identify a browser session. Clients do not load
7
-the PostHog browser SDK. Client-use events require an authenticated connection, so
8
-visiting the hosted app without connecting does not count as product use.
4
+Clients do not load the PostHog browser SDK. Client-use events require an
5
+authenticated connection, so visiting the hosted app without connecting does not
6
+count as product use.
7
+
8
+## Installs and owners
9
+
10
+`distinct_id` keeps the rule every build has used: the hashed Codex workspace,
11
+else the Claude machine id, else the install's anonymous id. It can change when
12
+someone logs in, and a Codex Team shares one, but keeping it means PostHog charts
13
+and history never break. Do not change it; add a field instead.
14
+
15
+Every event also carries `installId` when the server can save its state: the hash
16
+of a random id in the state directory, which never changes for the install. If
17
+that file cannot be written, events still go out under `distinct_id`, as before. Count installs
18
+with it. Who an install belongs to is a separate fact, sent as
19
+`install.owner_observed`. Owners are resolved at query time in our own store, so
20
+a rule can change and apply to all history.
21
+
22
+[Owner sources](../../apps/server/src/telemetry/Identify.ts), strongest first:
23
+T3 Connect, then the OpenAI and Claude person ids, then the client device. The
24
+server reports what it can read itself: the linked Connect account and provider
25
+logins. A connecting client reports its signed-in Connect account and its device,
26
+which links every environment opened from one phone, browser, or desktop. Use the
27
+OpenAI `user_id` claim, not the Codex `account_id` (the ChatGPT workspace, which a
28
+whole Team shares) or the token `sub` (one per login method). Two Connect accounts are never the same person, whatever
29
+weaker ids they share.
30
+
31
+Every id is SHA-256 hashed with [one helper](../../packages/shared/src/telemetryId.ts)
32
+on both sides, so a Connect account hashes the same on the client and the server.
33
+The server accepts only hashes from clients.
34
35
## Attribution boundaries
36
docs/user/telemetry.md
+3
-1
@@ -1,7 +1,9 @@
1
# Product usage data
2
3
The T3 Code server sends product usage events to T3 Code's own endpoint at `ingest.t3.codes`,
4
-associated with a hashed account or installation identifier. The endpoint keeps a copy of each
4
+associated with a hashed account or installation identifier. To count how many installations one person
5
+uses, the server also sends hashed account identifiers: your T3 Connect account, your OpenAI and
6
+Claude accounts when you are signed in, and a random identifier for each device that connects. The endpoint keeps a copy of each
7
event and forwards events to PostHog. Events include the provider, model, reasoning effort,
8
permission mode, turn result, duration, release channel, and main-agent token totals when
9
available.
packages/client-runtime/src/authorization/remote.test.ts
+36
@@ -2,10 +2,12 @@ import { describe, expect, it } from "@effect/vitest";
2
import * as Duration from "effect/Duration";
3
import * as Effect from "effect/Effect";
4
import * as Fiber from "effect/Fiber";
5
+import * as Option from "effect/Option";
6
import * as Schema from "effect/Schema";
7
import * as TestClock from "effect/testing/TestClock";
8
9
import { EnvironmentAuthInvalidError } from "@t3tools/contracts";
10
+import { hashTelemetryId } from "@t3tools/shared/telemetryId";
11
import {
12
appendClientConnectionParams,
13
bootstrapRemoteBearerSession,
@@ -18,6 +20,7 @@ import {
20
resolveRemoteWebSocketConnectionUrl,
21
} from "./remote.ts";
22
import { fetchRemoteEnvironmentDescriptor } from "../environment/descriptor.ts";
23
+import * as ClientCapabilities from "../platform/capabilities.ts";
24
import * as RpcHttp from "../rpc/http.ts";
25
26
const isEnvironmentAuthInvalidError = Schema.is(EnvironmentAuthInvalidError);
@@ -486,4 +489,37 @@ describe("remote environment authorization", () => {
489
);
490
}),
491
);
492
+
493
+ it.effect("names the signed-in Connect account and this device by hash only", () =>
494
+ Effect.gen(function* () {
495
+ const fetch = recordedFetch(
496
+ Response.json({ ticket: "ws-ticket", expiresAt: "2026-05-01T12:05:00.000Z" }),
497
+ );
498
+
499
+ const url = new URL(
500
+ yield* resolveRemoteWebSocketConnectionUrl({
501
+ wsBaseUrl: "wss://remote.example.com/",
502
+ httpBaseUrl: "https://remote.example.com/",
503
+ bearerToken: "bearer-token",
504
+ }).pipe(
505
+ provideRemoteHttp(fetch.fetchFn),
506
+ Effect.provideService(
507
+ ClientCapabilities.CloudSession,
508
+ ClientCapabilities.CloudSession.of({
509
+ identity: Effect.succeed(Option.some({ accountId: "user_connect" })),
510
+ clerkToken: Effect.succeed("clerk-token"),
511
+ }),
512
+ ),
513
+ Effect.provideService(ClientCapabilities.AnalyticsDevice, {
514
+ id: Effect.succeed(Option.some("device-1")),
515
+ }),
516
+ ),
517
+ );
518
+
519
+ expect(url.searchParams.get("clientOwner")).toBe(hashTelemetryId("user_connect"));
520
+ expect(url.searchParams.get("clientDevice")).toBe(hashTelemetryId("device-1"));
521
+ expect(url.toString()).not.toContain("user_connect");
522
+ expect(url.toString()).not.toContain("device-1");
523
+ }),
524
+ );
525
});
packages/client-runtime/src/authorization/remote.ts
+42
-2
@@ -7,8 +7,11 @@ import {
7
type AuthEnvironmentScope,
8
} from "@t3tools/contracts";
9
import { encodeOAuthScope } from "@t3tools/shared/oauthScope";
10
+import { hashTelemetryId } from "@t3tools/shared/telemetryId";
11
import * as Effect from "effect/Effect";
12
+import * as Option from "effect/Option";
13
import { environmentEndpointUrl } from "../environment/endpoint.ts";
14
+import * as ClientCapabilities from "../platform/capabilities.ts";
15
import {
16
executeEnvironmentHttpRequest,
17
makeEnvironmentHttpApiGroupClient,
@@ -37,10 +40,31 @@ const clientMetadataTokenExchangeFields = (
40
};
41
};
42
43
+/** Hashes of who is connecting. Only hashes leave the client. */
44
+export interface ClientOwnerParams {
45
+ readonly connect?: string;
46
+ readonly device?: string;
47
+}
48
+
49
+/**
50
+ * Tells the environment, for analytics, which T3 Connect account and device
51
+ * are connecting, so it can count the environment as theirs.
52
+ */
53
+export const readClientOwnerParams = Effect.gen(function* () {
54
+ const session = yield* Effect.serviceOption(ClientCapabilities.CloudSession);
55
+ const account = Option.isSome(session) ? yield* session.value.identity : Option.none();
56
+ const device = yield* (yield* ClientCapabilities.AnalyticsDevice).id;
57
+ return {
58
+ ...(Option.isSome(account) ? { connect: hashTelemetryId(account.value.accountId) } : {}),
59
+ ...(Option.isSome(device) ? { device: hashTelemetryId(device.value) } : {}),
60
+ } satisfies ClientOwnerParams;
61
+});
62
+
63
export const appendClientConnectionParams = (
64
url: URL,
65
clientMetadata: AuthClientPresentationMetadata | undefined,
66
connectionMethod?: ClientConnectionMethod,
67
+ owners?: ClientOwnerParams,
68
): void => {
69
if (clientMetadata?.surface) {
70
url.searchParams.set("clientSurface", clientMetadata.surface);
@@ -79,6 +103,12 @@ export const appendClientConnectionParams = (
103
if (connectionMethod) {
104
url.searchParams.set("connectionMethod", connectionMethod);
105
}
106
+ if (owners?.connect) {
107
+ url.searchParams.set("clientOwner", owners.connect);
108
+ }
109
+ if (owners?.device) {
110
+ url.searchParams.set("clientDevice", owners.device);
111
+ }
112
};
113
114
export const exchangeRemoteDpopAccessToken = Effect.fn(
@@ -217,7 +247,12 @@ export const resolveRemoteWebSocketConnectionUrl = Effect.fn(
247
url.pathname = "/ws";
248
}
249
url.searchParams.set("wsTicket", issued.ticket);
220
- appendClientConnectionParams(url, input.clientMetadata, input.connectionMethod);
250
+ appendClientConnectionParams(
251
+ url,
252
+ input.clientMetadata,
253
+ input.connectionMethod,
254
+ yield* readClientOwnerParams,
255
+ );
256
return url.toString();
257
});
258
@@ -243,6 +278,11 @@ export const resolveRemoteDpopWebSocketConnectionUrl = Effect.fn(
278
url.pathname = "/ws";
279
}
280
url.searchParams.set("wsTicket", issued.ticket);
246
- appendClientConnectionParams(url, input.clientMetadata, input.connectionMethod);
281
+ appendClientConnectionParams(
282
+ url,
283
+ input.clientMetadata,
284
+ input.connectionMethod,
285
+ yield* readClientOwnerParams,
286
+ );
287
return url.toString();
288
});
packages/client-runtime/src/connection/resolver.ts
+8
-3
@@ -10,7 +10,11 @@ import * as Option from "effect/Option";
10
import * as Schema from "effect/Schema";
11
import * as HttpClient from "effect/http/HttpClient";
12
13
-import { appendClientConnectionParams } from "../authorization/remote.ts";
13
+import {
14
+ appendClientConnectionParams,
15
+ type ClientOwnerParams,
16
+ readClientOwnerParams,
17
+} from "../authorization/remote.ts";
18
import * as RemoteEnvironmentAuthorization from "../authorization/service.ts";
19
import * as ClientCapabilities from "../platform/capabilities.ts";
20
import {
@@ -74,12 +78,13 @@ const isBearerCredential = Schema.is(BearerConnectionCredential);
78
function primarySocketUrl(
79
target: PrimaryConnectionTarget,
80
clientMetadata: AuthClientPresentationMetadata | undefined,
81
+ owners: ClientOwnerParams,
82
): string {
83
const url = new URL(target.wsBaseUrl);
84
if (url.pathname === "" || url.pathname === "/") {
85
url.pathname = "/ws";
86
}
82
- appendClientConnectionParams(url, clientMetadata, "direct");
87
+ appendClientConnectionParams(url, clientMetadata, "direct", owners);
88
return url.toString();
89
}
90
@@ -97,7 +102,7 @@ const makePrimaryBroker = Effect.fn("clientRuntime.connection.broker.makePrimary
102
environmentId: target.environmentId,
103
label: target.label,
104
httpBaseUrl: target.httpBaseUrl,
100
- socketUrl: primarySocketUrl(target, presentation.metadata),
105
+ socketUrl: primarySocketUrl(target, presentation.metadata, yield* readClientOwnerParams),
106
httpAuthorization: null,
107
target,
108
} satisfies PreparedConnection;
packages/client-runtime/src/platform/capabilities.ts
+12
-1
@@ -5,7 +5,7 @@ import {
5
EnvironmentId,
6
} from "@t3tools/contracts";
7
import * as Context from "effect/Context";
8
-import type * as Effect from "effect/Effect";
8
+import * as Effect from "effect/Effect";
9
import type * as Option from "effect/Option";
10
11
import type { ConnectionAttemptError } from "../connection/model.ts";
@@ -40,6 +40,17 @@ export class RelayDeviceIdentity extends Context.Service<
40
}
41
>()("@t3tools/client-runtime/platform/capabilities/RelayDeviceIdentity") {}
42
43
+/**
44
+ * A random id this client keeps across launches. Environments it connects to
45
+ * record its hash, so two environments opened from one device share an owner
46
+ * in analytics even when nobody is signed in.
47
+ */
48
+export class AnalyticsDevice extends Context.Reference<{
49
+ readonly id: Effect.Effect<Option.Option<string>>;
50
+}>("@t3tools/client-runtime/platform/capabilities/AnalyticsDevice", {
51
+ defaultValue: () => ({ id: Effect.succeedNone }),
52
+}) {}
53
+
54
export class ClientPresentation extends Context.Service<
55
ClientPresentation,
56
{
packages/shared/package.json
+4
@@ -183,6 +183,10 @@
183
"types": "./src/dpopCommon.ts",
184
"import": "./src/dpopCommon.ts"
185
},
186
+ "./telemetryId": {
187
+ "types": "./src/telemetryId.ts",
188
+ "import": "./src/telemetryId.ts"
189
+ },
190
"./relayAuth": {
191
"types": "./src/relayAuth.ts",
192
"import": "./src/relayAuth.ts"
packages/shared/src/telemetryId.test.ts
new
+19
@@ -0,0 +1,19 @@
1
+import { describe, expect, it } from "vite-plus/test";
2
+
3
+import { hashTelemetryId, isTelemetryIdHash } from "./telemetryId.ts";
4
+
5
+describe("telemetry ids", () => {
6
+ // The server hashes the linked Connect account and clients hash the signed-in
7
+ // one. Both must give plain SHA-256 hex, or the two never match.
8
+ it("is the SHA-256 hex digest of the id", () => {
9
+ expect(hashTelemetryId("user_connect")).toBe(
10
+ "7938265611170ce1ba814a67f5a51bcff2b9b46c5597da465e6f098f2217717a",
11
+ );
12
+ });
13
+
14
+ it("accepts only hashes, never a raw id", () => {
15
+ expect(isTelemetryIdHash(hashTelemetryId("user_connect"))).toBe(true);
16
+ expect(isTelemetryIdHash("user_connect")).toBe(false);
17
+ expect(isTelemetryIdHash(hashTelemetryId("x").toUpperCase())).toBe(false);
18
+ });
19
+});
packages/shared/src/telemetryId.ts
new
+12
@@ -0,0 +1,12 @@
1
+import { sha256 } from "@noble/hashes/sha2";
2
+import * as Hex from "effect/encoding/Hex";
3
+
4
+/**
5
+ * Hashes an identifier before it reaches analytics. Clients and the server both
6
+ * use it, so one Connect account gives the same owner id on every surface.
7
+ */
8
+export const hashTelemetryId = (value: string): string =>
9
+ Hex.encode(sha256(new TextEncoder().encode(value)));
10
+
11
+/** True for a `hashTelemetryId` result. The server accepts only this shape from clients. */
12
+export const isTelemetryIdHash = (value: string): boolean => /^[0-9a-f]{64}$/u.test(value);