@devries-cameron20 / t3code Mirror · read-only / commits / e287582182
Fork 0

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);