Skip to content

Write HTML. Render video. Built for agents.

17.1 KB
Raw Blame
import { failCommand, failUsage } from "../../utils/commandResult.js";
import { envFlagEnabled, isAttendedTerminal } from "../../utils/attendedTerminal.js";
/**
 * `hyperframes auth login` — sign in to HeyGen.
 *
 * Default: OAuth 2.0 + PKCE via a loopback callback. The CLI opens
 * the user's browser, captures the authorization code on an
 * ephemeral 127.0.0.1 port, exchanges it for tokens, and persists
 * them to `~/.heygen/credentials`.
 *
 * `--api-key`: opts into the legacy long-lived API-key path.
 *
 * Write semantics:
 *   - Snapshot existing credentials first; merge so a new OAuth session
 *     preserves an existing API key (and vice versa).
 *   - Sanity-check that the input is non-empty and header-safe (no
 *     CR/LF) before touching disk. The backend's `/v3/users/me` is the
 *     source of truth for whether the key is actually valid — we do
 *     NOT shape-check the prefix (real keys come in multiple formats:
 *     `sk_V2_…`, `hg_…`, partner keys, etc.).
 *   - Verify via `GET /v3/users/me`. On 401, roll back to the previous
 *     state. Network/5xx errors keep the new credential in place per
 *     the transient-blip rationale.
 */

import { defineCommand } from "citty";
import { stdin as input } from "node:process";
import {
  AuthClient,
  assertOAuthConfiguredOrExit,
  clearUserInfo,
  deleteStore,
  hasPreservedUnknownData,
  isAuthError,
  isHeaderSafe,
  isUserInfoEmpty,
  readStore,
  refreshTokens,
  revokeTokens,
  saveUserInfo,
  persistVerifiedOAuthSession,
  startAuthorizationCodeFlow,
  startDeviceAuthorizationFlow,
  userDisplayName,
  writeStore,
  type Credentials,
  type StoredUserInfo,
  type UserInfo,
} from "../../auth/index.js";
import { c } from "../../ui/colors.js";

const STDIN_TIMEOUT_MS = 30_000;
// Smallest plausible length for a real API key. We don't validate the
// prefix or character set — the backend's /v3/users/me is the source
// of truth and rolls back on rejection. The only must-check is
// header-safety (CR/LF), which `isHeaderSafe` covers.
const MIN_KEY_LENGTH = 8;

export default defineCommand({
  meta: {
    name: "login",
    description: "Sign in to HeyGen (OAuth by default; --api-key for long-lived keys)",
  },
  args: {
    "api-key": {
      type: "string",
      description: "API key value, or pass `--api-key` with no value to read from stdin / prompt.",
    },
    device: {
      type: "boolean",
      description: "Use an attended device code (for SSH/headless terminals; never for CI).",
    },
  },
  // fallow-ignore-next-line complexity
  async run({ args }) {
    const inlineKey = args["api-key"];
    if (inlineKey !== undefined && args.device) {
      console.error(c.error("Choose either --device or --api-key, not both."));
      failUsage();
    }
    if (inlineKey !== undefined) {
      await runApiKeyLogin(inlineKey);
      return;
    }
    if (args.device) {
      await runDeviceLogin();
      return;
    }
    if (isRemoteOrHeadless()) {
      console.error(
        c.error(
          "Browser callback login is unavailable in this remote/headless terminal. Run `hyperframes auth login --device`.",
        ),
      );
      failUsage();
    }
    await runOAuthLogin();
  },
});

function isRemoteOrHeadless(): boolean {
  const remoteEnvironment = [
    "CODESPACES",
    "GITHUB_CODESPACES",
    "REMOTE_CONTAINERS",
    "GITPOD_WORKSPACE_ID",
    "container",
  ].some(envFlagEnabled);
  return Boolean(
    process.env["SSH_CONNECTION"] ||
    process.env["SSH_CLIENT"] ||
    process.env["SSH_TTY"] ||
    process.env["BROWSER"] === "none" ||
    process.env["HF_NO_BROWSER"] === "1" ||
    remoteEnvironment ||
    process.stdout.isTTY !== true,
  );
}

function assertAttendedDeviceFlow(): void {
  if (!isAttendedTerminal()) {
    console.error(
      c.error(
        "`--device` requires an attended terminal and is disabled in CI. Use an API key or workload credential for automation.",
      ),
    );
    failUsage();
  }
}

async function runDeviceLogin(): Promise<void> {
  assertAttendedDeviceFlow();
  assertOAuthConfiguredOrExit();
  const { trackAuthLoginStarted, trackAuthLoginCompleted, trackAuthLoginFailed, identifyUser } =
    await import("../../telemetry/index.js");
  trackAuthLoginStarted("device");

  let tokens;
  try {
    tokens = await startDeviceAuthorizationFlow({
      onChallenge: ({ verificationUri, verificationUriComplete, userCode }) => {
        console.log(`Open ${c.accent(verificationUriComplete ?? verificationUri)} in a browser.`);
        if (!verificationUriComplete) console.log(`Enter code ${c.bold(userCode)}.`);
        console.log(c.dim("Waiting for approval…"));
      },
    });
  } catch (err) {
    const message = (err as Error).message || "Device authorization failed.";
    trackAuthLoginFailed("device", /expired/i.test(message) ? "flow_timeout" : "flow_error");
    console.error(c.error(message));
    failCommand();
  }

  let user: UserInfo;
  try {
    user = await new AuthClient().getCurrentUser(issuedCredential(tokens));
  } catch (err) {
    await revokeDeviceTokens(tokens);
    trackAuthLoginFailed("device", "rejected");
    console.error(
      c.error(
        `HeyGen could not verify the approved device session; no credential was saved. ${(err as Error).message}`,
      ),
    );
    failCommand();
  }

  try {
    await persistVerifiedOAuthSession(tokens, toStoredUserInfo(user));
  } catch (err) {
    await revokeDeviceTokens(tokens);
    trackAuthLoginFailed("device", "flow_error");
    console.error(
      c.error(
        `Could not save the verified device session; it was revoked. ${(err as Error).message}`,
      ),
    );
    failCommand();
  }

  const id = identityKey(user);
  if (id) identifyUser(id);
  trackAuthLoginCompleted("device", id);
  const identity = userDisplayName(toStoredUserInfo(user)) ?? "(unknown user)";
  console.log(c.success(`✓ Signed in as ${identity}.`));
}

// The tokens this login just issued, never a resolved credential: an env credential would outrank them.
function issuedCredential(tokens: { access_token: string; refresh_token?: string }) {
  return {
    type: "oauth" as const,
    access_token: tokens.access_token,
    ...(tokens.refresh_token ? { refresh_token: tokens.refresh_token } : {}),
    source: "file_json" as const,
    refreshable: false,
  };
}

async function revokeDeviceTokens(tokens: {
  access_token: string;
  refresh_token?: string;
}): Promise<void> {
  await revokeTokens(tokens.access_token, { token_type_hint: "access_token" });
  if (tokens.refresh_token) {
    await revokeTokens(tokens.refresh_token, {
      token_type_hint: "refresh_token",
    });
  }
}

// fallow-ignore-next-line complexity
async function runOAuthLogin(): Promise<void> {
  assertOAuthConfiguredOrExit();

  const { trackAuthLoginStarted, trackAuthLoginFailed } = await import("../../telemetry/index.js");
  trackAuthLoginStarted("oauth");

  let tokens;
  try {
    ({ tokens } = await startAuthorizationCodeFlow());
  } catch (err) {
    const message = (err as Error).message ?? "";
    // The loopback server rejects with "OAuth callback timed out after …" when
    // the user never completes the browser step (closed the tab / walked away).
    // That is the dominant non-error dropout, so split it from real failures
    // (IdP misconfig, network) instead of lumping everything as flow_error.
    trackAuthLoginFailed("oauth", /timed out/i.test(message) ? "flow_timeout" : "flow_error");
    console.error(c.error(`Sign-in failed: ${message}`));
    failCommand();
  }

  await reportIdentity(issuedCredential(tokens));
}

async function reportIdentity(credential: ReturnType<typeof issuedCredential>): Promise<void> {
  const { trackAuthLoginCompleted, identifyUser } = await import("../../telemetry/index.js");
  // Wire the refresh hook here too — a freshly-minted token shouldn't
  // need it, but a fast IdP-side rotation (or a misconfigured short
  // TTL) shouldn't punish the user with a hard failure when the
  // refresh_token would have transparently fixed it.
  const client = new AuthClient({
    onUnauthenticatedRefresh: async (rt) => await refreshTokens(rt),
  });
  try {
    const user = await client.getCurrentUser(credential);
    // Persist the friendly-display block alongside the OAuth tokens so
    // `auth status` can show "Logged in as ..." without re-hitting
    // /v3/users/me. Best-effort — a persist failure never fails the login.
    await persistUserInfo(user);
    // Attribute this install to the signed-in account (and stitch its prior
    // anonymous usage) before recording completion, so the completed event
    // carries the identity. Both no-op under the telemetry opt-out.
    const id = identityKey(user);
    if (id) identifyUser(id);
    trackAuthLoginCompleted("oauth", id);
    const identity = userDisplayName(toStoredUserInfo(user)) ?? "(unknown user)";
    console.log(c.success(`✓ Signed in as ${identity}.`));
  } catch (err) {
    // Don't roll back — the OAuth tokens are valid on disk; this is a
    // transient verify-side issue. The credential is persisted and usable, so
    // the sign-in still COMPLETED; we just have no resolved identity to
    // attribute it to. The stale user block from a prior login (possibly a
    // DIFFERENT account) is cleared so `auth status` can't surface it.
    await clearUserInfoBestEffort();
    trackAuthLoginCompleted("oauth");
    console.error(
      c.warn(`Signed in. Identity check failed (transient): ${(err as Error).message}`),
    );
  }
}

/**
 * The stable key we associate this install with in telemetry after sign-in.
 * `/v3/users/me` exposes no opaque user_id, so we key on the HeyGen account
 * EMAIL — the canonical account identifier and the reliable join key back to
 * billing — falling back to username only when the account exposes no email.
 * (Username is NOT a privacy win — HeyGen usernames are frequently email-shaped
 * — it is purely a fallback so an emailless account is still attributable.)
 * The privacy notice (showTelemetryNotice) and docs/packages/cli.mdx disclose
 * both, so keep them in sync with whatever this returns.
 */
function identityKey(user: UserInfo): string | undefined {
  return user.email ?? user.username;
}

/** Project the API `/v3/users/me` view onto the on-disk identity block. */
function toStoredUserInfo(user: UserInfo): StoredUserInfo {
  const out: StoredUserInfo = {};
  if (user.email) out.email = user.email;
  if (user.first_name) out.first_name = user.first_name;
  if (user.last_name) out.last_name = user.last_name;
  if (user.username) out.username = user.username;
  return out;
}

/**
 * Persist the friendly-display block (best-effort). A non-empty block is
 * saved; an empty one (the API returned no identity fields) clears any
 * stale block so a wrong account can't surface in `auth status`. A
 * persist/clear failure is warned, never fatal — the credential is valid
 * on disk and that's what matters.
 */
async function persistUserInfo(user: UserInfo): Promise<void> {
  const stored = toStoredUserInfo(user);
  try {
    if (isUserInfoEmpty(stored)) {
      await clearUserInfo();
    } else {
      await saveUserInfo(stored);
    }
  } catch (err) {
    console.error(c.dim(`(warning: could not persist user info: ${(err as Error).message})`));
  }
}

/** Drop any stale user block; best-effort, never fatal. */
async function clearUserInfoBestEffort(): Promise<void> {
  try {
    await clearUserInfo();
  } catch (err) {
    console.error(c.dim(`(warning: could not clear stale user info: ${(err as Error).message})`));
  }
}

// fallow-ignore-next-line complexity
async function runApiKeyLogin(inlineKey: string): Promise<void> {
  const { trackAuthLoginStarted, trackAuthLoginCompleted, trackAuthLoginFailed, identifyUser } =
    await import("../../telemetry/index.js");
  trackAuthLoginStarted("api_key");

  // collectApiKey throws when the user cancels the interactive prompt (Ctrl-C)
  // or when no key arrives on stdin before the timeout — both are "user walked
  // away", the abandonment signal we most want. Record it before the error
  // propagates so `started` still reconciles to `completed + failed`.
  let key: string;
  try {
    key = await collectApiKey(inlineKey);
  } catch (err) {
    trackAuthLoginFailed("api_key", "aborted");
    console.error(c.error((err as Error).message || "Sign-in aborted."));
    failCommand();
  }
  if (!key) {
    trackAuthLoginFailed("api_key", "invalid_input");
    console.error(c.error("No API key provided."));
    failCommand();
  }
  if (!isHeaderSafe(key)) {
    // CR/LF in the value would smuggle headers when the key is sent
    // via `x-api-key`. The backend handles "wrong key" itself, but
    // header-injection has to be caught here.
    trackAuthLoginFailed("api_key", "invalid_input");
    console.error(c.error("API key must not contain newline or control characters."));
    failCommand();
  }
  if (key.length < MIN_KEY_LENGTH) {
    trackAuthLoginFailed("api_key", "invalid_input");
    console.error(c.error(`API key looks too short (got ${key.length} chars).`));
    failCommand();
  }

  const previous = await snapshotStore();
  const next: Credentials = { ...previous, api_key: key };
  await writeStore(next);

  const user = await verifyAndReport(key);
  if (!user) {
    trackAuthLoginFailed("api_key", "rejected");
    await rollback(previous);
    failCommand();
  }
  const id = identityKey(user);
  if (id) identifyUser(id);
  trackAuthLoginCompleted("api_key", id);
}

async function snapshotStore(): Promise<Credentials> {
  try {
    const { credentials } = await readStore();
    return { ...credentials };
  } catch {
    return {};
  }
}

async function rollback(previous: Credentials): Promise<void> {
  try {
    if (previous.api_key || previous.oauth || hasPreservedUnknownData(previous)) {
      // Restore the prior state. This branch also covers the case where
      // the only prior content was an unknown/foreign top-level key (a
      // future credential another CLI owns): writing `previous` back
      // re-emits that key, so the rollback doesn't clobber cross-CLI data
      // the file had before this login attempt.
      await writeStore(previous);
      console.error(c.dim("Rolled back to the previous credential."));
    } else {
      // No prior credential and nothing worth preserving — restore true
      // absence. Leaving the rejected key on disk would make the next
      // `auth status` / command silently resolve a known-bad key.
      await deleteStore();
      console.error(c.dim("Removed the rejected credential."));
    }
  } catch (err) {
    console.error(c.error(`Failed to roll back: ${(err as Error).message}`));
  }
}

// Returns the verified user on success (so the caller can attribute the
// completed sign-in to that identity), or null when the backend rejects the
// key. Other errors propagate.
// fallow-ignore-next-line complexity
async function verifyAndReport(key: string): Promise<UserInfo | null> {
  const client = new AuthClient();
  try {
    const user = await client.getCurrentUser({
      type: "api_key",
      key,
      source: "file_json",
    });
    // Persist the friendly-display block next to the now-verified api_key
    // so `auth status` can show a recognizable identity. Best-effort.
    await persistUserInfo(user);
    const identity = userDisplayName(toStoredUserInfo(user)) ?? "(unknown user)";
    console.log(c.success(`✓ API key saved. Authenticated as ${identity}.`));
    return user;
  } catch (err) {
    if (isAuthError(err) && err.code === "UNAUTHENTICATED") {
      console.error(
        `${c.warn("HeyGen rejected the API key.")}\n` +
          `  ${c.dim(err.message)}\n` +
          `Run ${c.accent("hyperframes auth login --api-key")} again with a valid key.`,
      );
      return null;
    }
    throw err;
  }
}

async function collectApiKey(inline: string): Promise<string> {
  if (inline.length > 0) return inline.trim();
  if (!input.isTTY) {
    return (await readAllWithTimeout(input, STDIN_TIMEOUT_MS)).trim();
  }
  return await promptForKey();
}

async function readAllWithTimeout(
  stream: NodeJS.ReadableStream,
  timeoutMs: number,
): Promise<string> {
  return await new Promise<string>((resolve, reject) => {
    const chunks: Buffer[] = [];
    const timer = setTimeout(() => {
      reject(new Error(`Timed out waiting for stdin (${timeoutMs}ms). Pipe the key explicitly.`));
    }, timeoutMs);
    stream.on("data", (chunk: Buffer | string) => {
      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
    });
    stream.on("end", () => {
      clearTimeout(timer);
      resolve(Buffer.concat(chunks).toString("utf8"));
    });
    stream.on("error", (err) => {
      clearTimeout(timer);
      reject(err);
    });
  });
}

async function promptForKey(): Promise<string> {
  const clack = await import("@clack/prompts");
  const value = await clack.password({
    message: "Enter HeyGen API key",
    validate: (v) => {
      if (!v || v.length < MIN_KEY_LENGTH) return "API key looks too short";
      if (!isHeaderSafe(v)) return "API key must not contain newline or control characters";
      return undefined;
    },
  });
  if (clack.isCancel(value)) {
    // Throw rather than exit here so the single catch in runApiKeyLogin records
    // the abandonment (auth_login_failed: aborted) and then exits.
    throw new Error("Aborted.");
  }
  return value.trim();
}