fix(auth): accept host-managed HeyGen access tokens

Author: miguel-heygen

packages/cli/src/auth/_test-utils.ts

@@ -12,6 +12,7 @@ import { join } from "node:path";
 
 const ENV_KEYS = [
   "HEYGEN_API_KEY",
+  "HEYGEN_ACCESS_TOKEN",
   "HYPERFRAMES_API_KEY",
   "HEYGEN_CONFIG_DIR",
   "HEYGEN_API_URL",

packages/cli/src/auth/resolver.test.ts

@@ -20,6 +20,7 @@ describe("auth/resolver", () => {
   });
 
   it("prefers HEYGEN_API_KEY over everything else", async () => {
+    process.env["HEYGEN_ACCESS_TOKEN"] = "host-token";
     process.env["HEYGEN_API_KEY"] = "env-key";
     process.env["HYPERFRAMES_API_KEY"] = "alias-key";
     await writeStore({ api_key: "file-key" });
@@ -28,12 +29,35 @@ describe("auth/resolver", () => {
   });
 
   it("falls through to HYPERFRAMES_API_KEY", async () => {
+    process.env["HEYGEN_ACCESS_TOKEN"] = "host-token";
     process.env["HYPERFRAMES_API_KEY"] = "alias-key";
     await writeStore({ api_key: "file-key" });
     const r = await resolveCredential();
     expect(r).toEqual({ type: "api_key", key: "alias-key", source: "env_alias" });
   });
 
+  it("accepts host-managed OAuth without a credential file or a refresh token", async () => {
+    process.env["HEYGEN_ACCESS_TOKEN"] = "host-token";
+    expect(await resolveCredential()).toEqual({
+      type: "oauth",
+      access_token: "host-token",
+      source: "env_oauth",
+      refreshable: false,
+    });
+    expect(await fs.readdir(dir)).toEqual([]);
+  });
+
+  it("rejects an unsafe host token without exposing it", async () => {
+    process.env["HEYGEN_ACCESS_TOKEN"] = "secret\r\nInjected: value";
+    await expect(resolveCredential()).rejects.toMatchObject({ code: "INVALID_STORE" });
+    await expect(resolveCredential()).rejects.not.toThrow("secret");
+  });
+
+  it("treats an empty host token as absent", async () => {
+    process.env["HEYGEN_ACCESS_TOKEN"] = "";
+    expect(await tryResolveCredential()).toBeNull();
+  });
+
   it("returns file api_key when no env is set", async () => {
     await writeStore({ api_key: "file-key" });
     const r = await resolveCredential();

packages/cli/src/auth/resolver.ts

@@ -4,7 +4,8 @@
  * Priority — first non-empty wins:
  *   1. `HEYGEN_API_KEY` env (matches heygen-cli)
  *   2. `HYPERFRAMES_API_KEY` env (alias for parity with other tools)
- *   3. `~/.heygen/credentials` (JSON) — unexpired OAuth, else api_key
+ *   3. `HEYGEN_ACCESS_TOKEN` env (host-managed OAuth)
+ *   4. `~/.heygen/credentials` (JSON) — unexpired OAuth, else api_key
  *
  * Absent sources fall through. A broken file (parse error, bad shape)
  * surfaces immediately as `ErrInvalidStore` — silently falling back
@@ -19,7 +20,7 @@
 import { isHeaderSafe, readStore } from "./store.js";
 import { ErrInvalidStore, ErrLoginExpired, ErrNotConfigured, isAuthError } from "./errors.js";
 
-type CredentialSource = "env" | "env_alias" | "file_json" | "file_legacy";
+type CredentialSource = "env" | "env_alias" | "env_oauth" | "file_json" | "file_legacy";
 
 interface ApiKeyCredential {
   type: "api_key";
@@ -65,6 +66,14 @@ export async function resolveCredential(opts: ResolveOptions = {}): Promise<Reso
     return { type: "api_key", key: hfEnv, source: "env_alias" };
   }
 
+  const accessToken = process.env["HEYGEN_ACCESS_TOKEN"];
+  if (accessToken) {
+    if (!isHeaderSafe(accessToken)) {
+      throw ErrInvalidStore("HEYGEN_ACCESS_TOKEN contains control characters");
+    }
+    return { type: "oauth", access_token: accessToken, source: "env_oauth", refreshable: false };
+  }
+
   const { credentials, source } = await readStore();
   if (source === "absent") throw ErrNotConfigured();
 

packages/cli/src/commands/auth/status-user.test.ts

@@ -64,6 +64,17 @@ describe("auth status — persisted user block surface", () => {
     return JSON.parse(stdout[stdout.length - 1] ?? "{}");
   }
 
+  it("reports host-managed OAuth without showing its token or a stored identity", async () => {
+    process.env["HEYGEN_ACCESS_TOKEN"] = "fixture-host-secret";
+    await writeStore({ user: { email: "stored@example.com" } });
+    expect(await runStatus(true)).toBe(0);
+    expect(lastJson()).toMatchObject({ source: "env_oauth", persisted_user: null });
+    expect(await runStatus(false)).toBe(0);
+    expect(stdout.join("\n")).toContain("env (HEYGEN_ACCESS_TOKEN)");
+    expect(stdout.join("\n")).not.toContain("fixture-host-secret");
+    expect(stdout.join("\n")).not.toContain("stored@example.com");
+  });
+
   it("surfaces the persisted user block (with resolved display_name) for a file credential", async () => {
     await writeStore({
       api_key: "hg_x",

packages/cli/src/commands/auth/status.ts

@@ -260,6 +260,7 @@ function identityRows(user: UserInfo): [string, string][] {
 const SOURCE_LABELS: Record<ResolvedCredential["source"], string> = {
   env: "env (HEYGEN_API_KEY)",
   env_alias: "env (HYPERFRAMES_API_KEY)",
+  env_oauth: "env (HEYGEN_ACCESS_TOKEN)",
   file_legacy: "file (~/.heygen/credentials — legacy plaintext)",
   file_json: "file (~/.heygen/credentials)",
 };

skills/media-use/audio/scripts/lib/heygen.mjs

@@ -1,6 +1,6 @@
 import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
 // heygen.mjs — vendored HeyGen REST helpers (auth + transport) for the audio
-// pipeline. The credential resolver matches the hyperframes CLI auth: first
+// pipeline. The credential resolver uses the shared HeyGen store: first
 // usable source wins — a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
 // $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
 // credentials (oauth → Bearer, else api_key → X-Api-Key; $HEYGEN_CONFIG_DIR
@@ -10,7 +10,8 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
-export const HEYGEN_BASE = "https://api.heygen.com/v3";
+const apiHost = process.env.HEYGEN_API_URL || "https://api.heygen.com";
+export const HEYGEN_BASE = `${apiHost.replace(/\/+$/, "")}/v3`;
 export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
 // Tool-attribution sent on EVERY media-use HeyGen call regardless of auth type, so
 // the backend can isolate media-use consumption from other free TTS / avatar video.

skills/media-use/audio/scripts/lib/heygen.test.mjs

@@ -1,3 +1,5 @@
+import { createServer } from "node:http";
+import { once } from "node:events";
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
@@ -183,3 +185,49 @@ test("heygenAuthHeaders says to fix an unreadable credentials path, and to log i
     }
   });
 });
+
+test("host-managed OAuth reaches its paired API host in both distributed helpers", async () => {
+  const originalFetch = globalThis.fetch;
+  const previousHost = process.env.HEYGEN_API_URL;
+  const previousToken = process.env.HEYGEN_ACCESS_TOKEN;
+  const calls = [];
+  const server = createServer((request, response) => {
+    calls.push({ path: request.url, authorization: request.headers.authorization });
+    response.setHeader("content-type", "application/json");
+    response.end(JSON.stringify({ ok: true }));
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  try {
+    process.env.HEYGEN_API_URL = `http://127.0.0.1:${server.address().port}///`;
+    process.env.HEYGEN_ACCESS_TOKEN = "fixture-token";
+    const origin = new URL(process.env.HEYGEN_API_URL).origin;
+    globalThis.fetch = (url, options) => {
+      assert.equal(new URL(url).origin, origin, "this test must never reach the internet");
+      return originalFetch(url, options);
+    };
+    for (const file of [
+      "./heygen.mjs?paired-host",
+      "../../../../../packages/cli/src/audio/scripts/lib/heygen.mjs?paired-host",
+    ]) {
+      const helper = await import(new URL(file, import.meta.url));
+      assert.deepEqual(
+        await helper.heygenJSON("/voices", { headers: helper.heygenAuthHeaders() }),
+        {
+          ok: true,
+        },
+      );
+    }
+    assert.deepEqual(calls, [
+      { path: "/v3/voices", authorization: "Bearer fixture-token" },
+      { path: "/v3/voices", authorization: "Bearer fixture-token" },
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+    if (previousHost === undefined) delete process.env.HEYGEN_API_URL;
+    else process.env.HEYGEN_API_URL = previousHost;
+    if (previousToken === undefined) delete process.env.HEYGEN_ACCESS_TOKEN;
+    else process.env.HEYGEN_ACCESS_TOKEN = previousToken;
+    await new Promise((resolve) => server.close(resolve));
+  }
+});