Skip to content

Commit 3e462f4

Browse files
authored
feat(cli): use dedicated HyperFrames OAuth clients (#6687)
* feat(cli): use dedicated HyperFrames OAuth clients * docs(cli): shorten credential store contract comment * fix(cli): respect Windows modes in OAuth media test * fix(cli): keep media workflows on HyperFrames OAuth * test(cli): scope billing status assertions to wallet rows * test(cli): align telemetry fixtures and CI auth inputs
1 parent 4e2a1c2 commit 3e462f4

49 files changed

Lines changed: 859 additions & 271 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ jobs:
238238
- "packages/cli/src/{background-removal,registry,telemetry}/**"
239239
- "packages/cli/src/capture/{captureCompositionFrame,captureTimeout,navigateForCapture,readBoundedResponse}.ts"
240240
- "packages/cli/src/media-use/lib/config-lock.mjs"
241-
- "packages/cli/src/auth/{paths,telemetryIdentity}.ts"
241+
- "packages/cli/src/auth/{config,errors,paths,telemetryIdentity}.ts"
242242
- "packages/cli/scripts/**"
243243
- "packages/core/stubs/**"
244244
- "packages/engine/src/**"

‎docs/guides/authentication.mdx‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ Signing in is the same OAuth step as creating an account — new users land on t
3737
</Step>
3838
</Steps>
3939

40-
The credential lives in `~/.heygen/credentials` (mode `0600`) — no per-repo `.env` to manage. Browser OAuth is a `hyperframes auth login` feature. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) (its own install — there's no `npx heygen`) is API-key-only, so `heygen auth login` just stores a key you paste. Both read the same `~/.heygen/credentials`, so signing in with one carries to the other.
40+
HyperFrames uses its own public OAuth client and stores credentials in `~/.hyperframes/credentials` (mode `0600`). Sign in again after upgrading from the shared HeyGen login. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) keeps its own login in `~/.heygen`; HyperFrames does not move or delete it. An expired HyperFrames OAuth session requires refresh or sign-in and never selects a saved API key instead. An explicit API-key login or environment key selects API-key billing.
41+
42+
`auth status` verifies identity. For a dedicated HyperFrames OAuth login it reports the billing product, but the HyperFrames balance is unavailable here: `/v3/users/me` returns generic HeyGen account billing fields. Those raw fields remain in JSON and are not presented as the HyperFrames balance. Host-injected or custom-client OAuth is reported as an unverified billing product.
4143

4244
<Tip>
4345
No account is needed to try HyperFrames locally. With no credential, voice can
@@ -54,12 +56,11 @@ sound retrieval. It resolves first-match-wins:
5456
2. `HEYGEN_ACCESS_TOKEN` — an OAuth token a host app injects
5557
3. `HEYGEN_API_KEY` — environment variable
5658
4. `HYPERFRAMES_API_KEY` — alias, for parity with other tools
57-
5. `~/.heygen/credentials` — written by `hyperframes auth login` (or `heygen auth login`)
59+
5. `~/.hyperframes/credentials` — written by `hyperframes auth login`
5860

5961
A nearby project `.env` can supply the keys, but never `HEYGEN_API_BASE`. Point at a different config directory
60-
with `HEYGEN_CONFIG_DIR`. The `hyperframes` CLI's own commands check the API keys before `HEYGEN_ACCESS_TOKEN`; see
61-
the [CLI reference](/packages/cli). `media-use resolve` searches through the separate `heygen` CLI, which resolves its
62-
own credential.
62+
with `HYPERFRAMES_CONFIG_DIR`. The `hyperframes` CLI's own commands check the API keys before `HEYGEN_ACCESS_TOKEN`; see
63+
the [CLI reference](/packages/cli). When `media-use` invokes the separate `heygen` executable, it supplies an isolated temporary credential containing the selected access token. That helper cannot refresh a HyperFrames grant or pick up another HeyGen login.
6364

6465
## Providers used by agent workflows
6566

@@ -70,7 +71,7 @@ vision key is available.
7071

7172
| Capability | Provider order | Key(s) — first match wins | Local dependency |
7273
|------------|----------------|---------------------------|------------------|
73-
| **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | `HEYGEN_API_KEY` → `HYPERFRAMES_API_KEY` → `~/.heygen` · then `ELEVENLABS_API_KEY` | Kokoro: `pip install kokoro-onnx soundfile` |
74+
| **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | `HEYGEN_API_KEY` → `HYPERFRAMES_API_KEY` → `~/.hyperframes` · then `ELEVENLABS_API_KEY` | Kokoro: `pip install kokoro-onnx soundfile` |
7475
| **Music (BGM)** | HeyGen library → Lyria → MusicGen | HeyGen credential (above) · then `GEMINI_API_KEY` → `GOOGLE_API_KEY` | MusicGen: `pip install transformers torch soundfile numpy` |
7576
| **Sound effects** | HeyGen library → bundled library | HeyGen credential (above) | bundled — no deps |
7677
| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | None; optional for [website capture](/guides/product-launch-video) |
@@ -145,7 +146,9 @@ to a shared space with `--space`.
145146
| `HEYGEN_ACCESS_TOKEN` | OAuth token a host app injects; never refreshed or saved. |
146147
| `HEYGEN_API_BASE` | A host app's gateway for media workflows; never read from a project `.env`. |
147148
| `HEYGEN_API_URL` | API base URL for `hyperframes` CLI commands (default `https://api.heygen.com`). |
148-
| `HEYGEN_CONFIG_DIR` | Credentials directory (default `~/.heygen`). |
149+
| `HYPERFRAMES_CONFIG_DIR` | HyperFrames credentials root (default `~/.hyperframes`). |
150+
| `HYPERFRAMES_ENV` | `prod` (default) or `dev`; switches OAuth and API defaults together. Dev credentials live under the root’s `dev/` directory. |
151+
| `HYPERFRAMES_OAUTH_CLIENT_ID` | Override the public client ID for a controlled OAuth environment. |
149152
| `ELEVENLABS_API_KEY` | ElevenLabs TTS, used when no HeyGen credential is present. |
150153
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Explicit Gemini TTS selection and Lyria music generation; capture descriptions use `GEMINI_API_KEY`. |
151154
| `GOOGLE_APPLICATION_CREDENTIALS` / `GCS_CREDS` | Gemini TTS service-account JSON file path / injected JSON. Used when neither API key is set. |

‎docs/packages/cli.mdx‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -687,10 +687,11 @@ and are copied to `~/.media/` so other projects can reuse them. Sound effects
687687
under CC BY get their credit written to `.media/audio/sfx/CREDITS.md`.
688688

689689
**What needs an account, and what can cost money.** The HeyGen sources run
690-
through the separate `heygen` CLI, signed in with `heygen auth login --oauth`.
691-
Searching the music, image, and icon catalogs is free. Text to speech and avatar
692-
video draw on a free allowance when you are signed in with OAuth, then on your
693-
HeyGen billing, so an agent should ask before generating them. When a
690+
through the separate `heygen` executable using the login selected by
691+
`hyperframes auth login`. It receives a temporary access-token credential and
692+
cannot read the separate HeyGen login or refresh a HyperFrames grant.
693+
The server decides feature eligibility and charges. An explicit API-key credential
694+
uses API-key billing. When a
694695
host app sets `HEYGEN_API_BASE` and `HEYGEN_API_KEY`, HeyGen calls go through that
695696
host instead and are charged to its key. The `codex` image fallback uses your
696697
ChatGPT subscription. Openverse, theSVG, GitHub, favicons, color grades, and the
@@ -2188,16 +2189,16 @@ it is anonymous until you sign in. Nothing calls it by hand.
21882189

21892190
## hyperframes auth
21902191

2191-
Sign in to HeyGen and manage credentials. They live in `~/.heygen/credentials`
2192-
(mode `0600`) and are **shared with the `heygen` CLI** — sign in with one and
2193-
the other picks up the session.
2192+
Sign into your HeyGen account through the dedicated HyperFrames OAuth client.
2193+
Credentials live in `~/.hyperframes/credentials` (mode `0600`), independently
2194+
of the `heygen` CLI. A previous shared login requires a fresh HyperFrames sign-in.
21942195

21952196
First match wins:
21962197

21972198
1. `HEYGEN_API_KEY`
21982199
2. `HYPERFRAMES_API_KEY` (a HyperFrames alias for the same thing)
21992200
3. `HEYGEN_ACCESS_TOKEN` (an OAuth token a host app injects; never refreshed or saved)
2200-
4. `~/.heygen/credentials`
2201+
4. `~/.hyperframes/credentials`
22012202

22022203
### `auth login`
22032204

@@ -2257,7 +2258,9 @@ hyperframes auth logout --yes # no prompt
22572258
| `HYPERFRAMES_API_KEY` | Alias for `HEYGEN_API_KEY`. |
22582259
| `HEYGEN_ACCESS_TOKEN` | OAuth token from a host app; never refreshed. |
22592260
| `HEYGEN_API_URL` | API base URL (default `https://api.heygen.com`). |
2260-
| `HEYGEN_CONFIG_DIR` | Credentials directory (default `~/.heygen`). |
2261+
| `HYPERFRAMES_CONFIG_DIR` | Credentials root (default `~/.hyperframes`). |
2262+
| `HYPERFRAMES_ENV` | `prod` (default) or `dev`; selects matching OAuth/API hosts and a separate dev credential directory. |
2263+
| `HYPERFRAMES_OAUTH_CLIENT_ID` | Override the selected public OAuth client. |
22612264

22622265
For the keys other capabilities use — ElevenLabs and Gemini for voice and music
22632266
fallback, OpenRouter and Gemini for capture — and how the skills prioritize

‎packages/cli/scripts/test-home.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ for (const name of [
1818
"CODEX_HOME",
1919
"CLAUDE_CONFIG_DIR",
2020
"HEYGEN_CONFIG_DIR",
21+
"HYPERFRAMES_CONFIG_DIR",
2122
"HYPERFRAMES_CATALOG_ARTIFACT_DIR",
2223
"HYPERFRAMES_MEDIA_HOME",
2324
"HF_HOME",

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,16 @@ const ENV_KEYS = [
1414
"HEYGEN_API_KEY",
1515
"HEYGEN_ACCESS_TOKEN",
1616
"HYPERFRAMES_API_KEY",
17+
"HYPERFRAMES_CONFIG_DIR",
1718
"HEYGEN_CONFIG_DIR",
19+
"HEYGEN_API_BASE",
1820
"HEYGEN_API_URL",
1921
"HYPERFRAMES_OAUTH_CLIENT_ID",
22+
"HYPERFRAMES_ENV",
23+
"HYPERFRAMES_OAUTH_TOKEN_URL",
24+
"HYPERFRAMES_OAUTH_AUTHORIZE_URL",
25+
"HYPERFRAMES_OAUTH_REVOKE_URL",
26+
"HYPERFRAMES_OAUTH_DEVICE_URL",
2027
] as const;
2128

2229
type EnvKey = (typeof ENV_KEYS)[number];
@@ -30,7 +37,7 @@ export interface EnvFixture {
3037

3138
/**
3239
* Take a snapshot of the auth-related env, clear them, make a tmp
33-
* `HEYGEN_CONFIG_DIR`, and return a `restore()` that undoes all of
40+
* `HYPERFRAMES_CONFIG_DIR`, and return a `restore()` that undoes all of
3441
* the above.
3542
*/
3643
export async function setupTempAuthEnv(prefix = "hf-auth-test-"): Promise<EnvFixture> {
@@ -40,7 +47,7 @@ export async function setupTempAuthEnv(prefix = "hf-auth-test-"): Promise<EnvFix
4047
saved[k] = process.env[k];
4148
delete process.env[k];
4249
}
43-
process.env["HEYGEN_CONFIG_DIR"] = dir;
50+
process.env["HYPERFRAMES_CONFIG_DIR"] = dir;
4451

4552
const restore = async (): Promise<void> => {
4653
for (const k of ENV_KEYS) {

‎packages/cli/src/auth/client.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ import { ErrApi, ErrUnauthenticated, isAuthError } from "./errors.js";
1919
import type { ResolvedCredential } from "./resolver.js";
2020
import { scrubCredentials } from "./scrub.js";
2121
import type { OAuthTokens } from "./store.js";
22+
import { oauthEnvironment } from "./config.js";
2223

23-
const DEFAULT_BASE_URL = "https://api.heygen.com";
2424
export const HEYGEN_CLI_SOURCE_HEADER = "X-HeyGen-Source";
2525
export const HEYGEN_CLI_SOURCE = "cli";
2626
// Tool-attribution header identifying this CLI as the request origin. Sent on
@@ -32,7 +32,9 @@ export const HEYGEN_CLIENT_SOURCE = "hyperframes";
3232

3333
export function apiBaseUrl(): string {
3434
const override = process.env["HEYGEN_API_URL"];
35-
return override && override.length > 0 ? override.replace(/\/+$/, "") : DEFAULT_BASE_URL;
35+
return override && override.length > 0
36+
? override.replace(/\/+$/, "")
37+
: `https://api.${oauthEnvironment() === "dev" ? "dev." : ""}heygen.com`;
3638
}
3739

3840
export type BillingType = "wallet" | "subscription" | "usage_based" | string;
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import { afterEach, beforeEach, describe, expect, it } from "vitest";
2+
import { setupTempAuthEnv } from "./_test-utils.js";
3+
import {
4+
assertOAuthIdentity,
5+
authorizeEndpoint,
6+
deviceAuthorizationEndpoint,
7+
oauthIdentity,
8+
resolveClientId,
9+
revokeEndpoint,
10+
tokenEndpoint,
11+
} from "./config.js";
12+
import { apiBaseUrl } from "./client.js";
13+
14+
describe("HyperFrames OAuth configuration", () => {
15+
let fixture: Awaited<ReturnType<typeof setupTempAuthEnv>>;
16+
beforeEach(async () => {
17+
fixture = await setupTempAuthEnv();
18+
});
19+
afterEach(async () => {
20+
await fixture.restore();
21+
});
22+
23+
it("uses the dedicated public production client", () => {
24+
expect(resolveClientId()).toBe("Zg3LF4FCLoeJoGs2YqMtZ17g");
25+
expect(authorizeEndpoint()).toBe("https://app.heygen.com/oauth/authorize");
26+
expect(tokenEndpoint()).toBe("https://api2.heygen.com/v1/oauth/token");
27+
expect(apiBaseUrl()).toBe("https://api.heygen.com");
28+
});
29+
30+
it("switches every default host together for development", () => {
31+
process.env["HYPERFRAMES_ENV"] = "dev";
32+
expect(resolveClientId()).toBe("9QoaiwCZov9O0cAkC4OZbR4p");
33+
expect(authorizeEndpoint()).toBe("https://api2.dev.heygen.com/v1/oauth/authorize");
34+
expect(tokenEndpoint()).toBe("https://api2.dev.heygen.com/v1/oauth/token");
35+
expect(revokeEndpoint()).toBe("https://api2.dev.heygen.com/v1/oauth/revoke");
36+
expect(deviceAuthorizationEndpoint()).toBe(
37+
"https://api2.dev.heygen.com/v1/oauth/device_authorization",
38+
);
39+
expect(apiBaseUrl()).toBe("https://api.dev.heygen.com");
40+
});
41+
42+
it("rejects a session after either its client or token server changes", () => {
43+
const identity = oauthIdentity();
44+
expect(() => assertOAuthIdentity(identity)).not.toThrow();
45+
process.env["HYPERFRAMES_OAUTH_CLIENT_ID"] = "another-client";
46+
expect(() => assertOAuthIdentity(identity)).toThrow("different OAuth client or environment");
47+
delete process.env["HYPERFRAMES_OAUTH_CLIENT_ID"];
48+
process.env["HYPERFRAMES_OAUTH_TOKEN_URL"] = "https://other.example/token";
49+
expect(() => assertOAuthIdentity(identity)).toThrow("different OAuth client or environment");
50+
});
51+
});

‎packages/cli/src/auth/config.ts‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
import { AuthError, ErrOAuthNotConfigured } from "./errors.js";
2+
3+
const PROD_CLIENT_ID = "Zg3LF4FCLoeJoGs2YqMtZ17g";
4+
5+
export function oauthEnvironment(): "prod" | "dev" {
6+
const value = process.env["HYPERFRAMES_ENV"] || "prod";
7+
if (value === "prod" || value === "dev") return value;
8+
throw new AuthError("OAUTH_NOT_CONFIGURED", "HYPERFRAMES_ENV must be prod or dev");
9+
}
10+
11+
export function defaultClientId(): string {
12+
return oauthEnvironment() === "prod" ? PROD_CLIENT_ID : "9QoaiwCZov9O0cAkC4OZbR4p";
13+
}
14+
15+
export function resolveClientId(): string {
16+
const id = process.env["HYPERFRAMES_OAUTH_CLIENT_ID"] || defaultClientId();
17+
if (!id) throw ErrOAuthNotConfigured();
18+
return id;
19+
}
20+
21+
export function tokenEndpoint(): string {
22+
return (
23+
process.env["HYPERFRAMES_OAUTH_TOKEN_URL"] ||
24+
`https://api2.${oauthEnvironment() === "dev" ? "dev." : ""}heygen.com/v1/oauth/token`
25+
);
26+
}
27+
28+
export function authorizeEndpoint(): string {
29+
return (
30+
process.env["HYPERFRAMES_OAUTH_AUTHORIZE_URL"] ||
31+
(oauthEnvironment() === "dev"
32+
? "https://api2.dev.heygen.com/v1/oauth/authorize"
33+
: "https://app.heygen.com/oauth/authorize")
34+
);
35+
}
36+
37+
export function revokeEndpoint(): string {
38+
return (
39+
process.env["HYPERFRAMES_OAUTH_REVOKE_URL"] ||
40+
`https://api2.${oauthEnvironment() === "dev" ? "dev." : ""}heygen.com/v1/oauth/revoke`
41+
);
42+
}
43+
44+
export function deviceAuthorizationEndpoint(): string {
45+
return (
46+
process.env["HYPERFRAMES_OAUTH_DEVICE_URL"] ||
47+
`https://api2.${oauthEnvironment() === "dev" ? "dev." : ""}heygen.com/v1/oauth/device_authorization`
48+
);
49+
}
50+
51+
export function oauthIdentity(): { client_id: string; token_endpoint: string } {
52+
return { client_id: resolveClientId(), token_endpoint: tokenEndpoint() };
53+
}
54+
55+
export function assertOAuthIdentity(tokens: { client_id?: string; token_endpoint?: string }): void {
56+
const identity = oauthIdentity();
57+
if (
58+
tokens.client_id !== identity.client_id ||
59+
tokens.token_endpoint !== identity.token_endpoint
60+
) {
61+
throw new AuthError(
62+
"LOGIN_EXPIRED",
63+
"This login belongs to a different OAuth client or environment",
64+
"Run `hyperframes auth login` to sign into the selected HyperFrames environment.",
65+
);
66+
}
67+
}

‎packages/cli/src/auth/errors.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ export const ErrInvalidStore = (detail: string) =>
3737
new AuthError(
3838
"INVALID_STORE",
3939
`Credential file is unreadable: ${detail}`,
40-
"Delete ~/.heygen/credentials and run `hyperframes auth login` to re-create it.",
40+
"Delete ~/.hyperframes/credentials and run `hyperframes auth login` to re-create it.",
4141
);
4242

4343
export const ErrUnauthenticated = (detail?: string) =>

0 commit comments

Comments
 (0)