Skip to content

The Open Standard for Generative UI

8.5 KB
Raw Blame
/**
 * Installation telemetry disclosure
 *
 * Sent during package postinstall unless telemetry is disabled:
 * - A random installation ID and a salted SHA-256 project ID
 * - Lang Core, Node.js, OS, architecture, and package-manager versions
 * - CI provider category, Docker status, project-ID source category, and schema version
 *
 * The JSON payload contains no direct PII or application-user data. It never includes
 * names, email addresses, usernames, raw Git origins, repository or project names,
 * filesystem paths, branches, commits, credentials, environment values, source code,
 * prompts, messages, generated output, component or tool definitions, errors, logs,
 * stack traces, routes, or UI interactions. As with any HTTP request, the telemetry
 * proxy and PostHog can observe the source IP as transport metadata; the script does
 * not read it or add it to the payload.
 */
import { id as ciInfoId, isCI as ciInfoIsCI } from "ci-info";
import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { release } from "node:os";
import path from "node:path";
import {
  createTelemetryStateIO,
  loadTelemetryState,
  saveTelemetryState,
  type TelemetryStateIO,
} from "../../../../shared/telemetry/telemetry-state.cjs";
import {
  getPostHogConfig,
  isTelemetryDisabled,
  isTruthyEnv,
  normalizeProjectIdentity,
  PROJECT_ID_SALT,
  TELEMETRY_REQUEST_TIMEOUT_MS,
  TELEMETRY_SCHEMA_VERSION,
} from "./shared";

export { isTelemetryDisabled, isTruthyEnv, normalizeProjectIdentity };

export const INSTALL_EVENT = "openui_lang_core_installed";

export type ProjectIdSource = "git_origin" | "repository_url" | "install_root";
export type PackageManagerName = "npm" | "pnpm" | "yarn" | "bun" | "unknown";

export interface InstallTelemetryProperties extends Record<string, unknown> {
  telemetry_schema_version: number;
  project_id: string;
  project_id_source: ProjectIdSource;
  lang_core_version: string;
  node_version: string;
  system_platform: string;
  system_release: string;
  system_architecture: string;
  package_manager: PackageManagerName;
  package_manager_version?: string;
  ci: boolean;
  ci_name?: string;
  is_docker: boolean;
}

export interface InstallTelemetryPayload {
  distinctId: string;
  event: typeof INSTALL_EVENT;
  properties: InstallTelemetryProperties;
}

export interface InstallTelemetryIO extends TelemetryStateIO {
  cwd(): string;
  getGitOrigin(projectRoot: string): string | undefined;
  platform: string;
  architecture: string;
  release(): string;
  isDocker(): boolean;
  stdout(message: string): void;
  stderr(message: string): void;
}

export type InstallTelemetrySender = (
  payload: InstallTelemetryPayload,
  env: NodeJS.ProcessEnv,
) => Promise<void>;

export interface RunInstallTelemetryOptions {
  env?: NodeJS.ProcessEnv;
  io?: Partial<InstallTelemetryIO>;
  send?: InstallTelemetrySender;
}

export type RunInstallTelemetryResult =
  | { status: "disabled" }
  | { status: "debug"; payload: InstallTelemetryPayload }
  | { status: "sent"; payload: InstallTelemetryPayload }
  | { status: "failed"; payload?: InstallTelemetryPayload };

interface ProjectIdentity {
  value: string;
  source: ProjectIdSource;
}

const INSTALL_NOTICE =
  "\n◆ OpenUI Lang Core sends pseudonymous installation telemetry to PostHog.\n" +
  "  It includes a salted project ID, OpenUI/Node/OS/package-manager metadata, and the network IP observed by PostHog.\n" +
  "  It does not send repository URLs, paths, source code, prompts, errors, or application data.\n" +
  "  Disable it with OPENUI_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.\n\n";

export function hashProjectIdentity(salt: string, projectIdentity: string): string {
  return createHash("sha256").update(salt).update("\0").update(projectIdentity).digest("hex");
}

export function detectPackageManager(env: NodeJS.ProcessEnv): {
  name: PackageManagerName;
  version?: string;
} {
  const userAgent = env["npm_config_user_agent"]?.trim() ?? "";
  const match = userAgent.match(/^(npm|pnpm|yarn|bun)\/([^\s]+)/i);
  if (!match) return { name: "unknown" };

  const name = match[1]!.toLowerCase() as Exclude<PackageManagerName, "unknown">;
  const version = match[2]!.slice(0, 64);
  return version ? { name, version } : { name };
}

export async function runInstallTelemetry(
  options: RunInstallTelemetryOptions = {},
): Promise<RunInstallTelemetryResult> {
  const env = options.env ?? process.env;
  if (isTelemetryDisabled(env)) return { status: "disabled" };

  let payload: InstallTelemetryPayload | undefined;
  try {
    const io = createInstallTelemetryIO(options.io);
    let telemetryState = loadTelemetryState({ env, io });
    let { state, changed } = telemetryState;
    if (state["langCorePostinstallNoticeShown"] !== true) {
      io.stderr(INSTALL_NOTICE);
      state = { ...state, langCorePostinstallNoticeShown: true };
      changed = true;
    }
    if (changed) {
      telemetryState = saveTelemetryState(telemetryState, state, io);
      state = telemetryState.state;
    }

    const projectRoot = path.resolve(env["INIT_CWD"] || io.cwd());
    const projectIdentity = resolveProjectIdentity(projectRoot, env, io);
    const packageManager = detectPackageManager(env);

    payload = {
      distinctId: state.distinctId,
      event: INSTALL_EVENT,
      properties: {
        telemetry_schema_version: TELEMETRY_SCHEMA_VERSION,
        project_id: hashProjectIdentity(PROJECT_ID_SALT, projectIdentity.value),
        project_id_source: projectIdentity.source,
        lang_core_version:
          env["OPENUI_LANG_CORE_PACKAGE_VERSION"] || env["npm_package_version"] || "unknown",
        node_version: process.version,
        system_platform: io.platform,
        system_release: io.release(),
        system_architecture: io.architecture,
        package_manager: packageManager.name,
        ...(packageManager.version ? { package_manager_version: packageManager.version } : {}),
        ci: ciInfoIsCI,
        ...(ciInfoId ? { ci_name: ciInfoId } : {}),
        is_docker: io.isDocker(),
      },
    };

    if (isTruthyEnv(env["OPENUI_TELEMETRY_DEBUG"])) {
      io.stdout(`[OpenUI telemetry debug]\n${JSON.stringify(payload, null, 2)}\n`);
      return { status: "debug", payload };
    }

    await (options.send ?? sendToPostHog)(payload, env);
    return { status: "sent", payload };
  } catch {
    return { status: "failed", ...(payload ? { payload } : {}) };
  }
}

function createInstallTelemetryIO(overrides: Partial<InstallTelemetryIO> = {}): InstallTelemetryIO {
  return {
    ...createTelemetryStateIO(),
    cwd: () => process.cwd(),
    getGitOrigin: defaultGetGitOrigin,
    platform: process.platform,
    architecture: process.arch,
    release,
    isDocker: defaultIsDocker,
    stdout: (message) => process.stdout.write(message),
    stderr: (message) => process.stderr.write(message),
    ...overrides,
  };
}

function resolveProjectIdentity(
  projectRoot: string,
  env: NodeJS.ProcessEnv,
  io: InstallTelemetryIO,
): ProjectIdentity {
  const gitOrigin = io.getGitOrigin(projectRoot)?.trim();
  if (gitOrigin) {
    return { value: normalizeProjectIdentity(gitOrigin), source: "git_origin" };
  }

  const repositoryUrl = env["REPOSITORY_URL"]?.trim();
  if (repositoryUrl) {
    return {
      value: normalizeProjectIdentity(repositoryUrl),
      source: "repository_url",
    };
  }

  return { value: projectRoot, source: "install_root" };
}

function defaultGetGitOrigin(projectRoot: string): string | undefined {
  try {
    return execFileSync("git", ["-C", projectRoot, "config", "--get", "remote.origin.url"], {
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
      timeout: 1000,
    }).trim();
  } catch {
    return undefined;
  }
}

function defaultIsDocker(): boolean {
  if (existsSync("/.dockerenv")) return true;
  try {
    return /docker|containerd|kubepods/i.test(readFileSync("/proc/self/cgroup", "utf8"));
  } catch {
    return false;
  }
}

async function sendToPostHog(
  payload: InstallTelemetryPayload,
  env: NodeJS.ProcessEnv,
): Promise<void> {
  const postHog = getPostHogConfig(env);
  const response = await fetch(postHog.captureUrl, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      api_key: postHog.apiKey,
      event: payload.event,
      properties: {
        distinct_id: payload.distinctId,
        ...payload.properties,
      },
    }),
    signal: AbortSignal.timeout(TELEMETRY_REQUEST_TIMEOUT_MS),
  });

  if (!response.ok) throw new Error(`PostHog capture failed: ${response.status}`);
}