Files
hyperframes/packages/cli/src/auth/store.ts
T
James RussoandClaude Opus 4.8 b9b5780396 feat(cli): persist + show friendly user identity; preserve unknown credential fields (#1741)
* feat(cli): persist + show friendly user identity; preserve unknown credential fields

The `~/.heygen/credentials` file is SHARED with the Go `heygen` CLI. This
is the hyperframes-side mirror of heygen-cli#197, which adds an optional
`user` block to that file. Two CLIs writing one file must round-trip each
other's data without loss.

Load-bearing change: the credentials reader/writer now PRESERVES unknown
fields on round-trip. Previously readStore/writeStore stripped any key
this CLI didn't model, so writing the file back would silently drop the
`user` block heygen-cli wrote (and any future key). Unrecognized top-level
keys, and unknown keys inside `oauth` / `user`, are captured on a hidden
symbol slot and re-emitted verbatim. Known fields stay strictly validated.

Also mirrors heygen-cli#197's friendly-display feature:
- New optional `user` block schema (email/first_name/last_name/username),
  all omitempty; legacy files without it parse fine.
- After login (OAuth + api-key paths) probe /v3/users/me, persist the
  block, and show a friendly name (email > "first last" > username).
  Probe failure is non-fatal (login still succeeds); a stale block is
  cleared on probe failure so a wrong account can't surface.
- `auth status` surfaces the persisted block (persisted_user in JSON,
  a cached Account row in human output) for file-sourced credentials;
  env-sourced credentials skip it (the on-disk block may belong to a
  different key).
- Fixed the OAuth write path to carry the user block + unknown keys
  across a fresh login / refresh (it previously rebuilt a minimal record).

Tests: preserve-unknown-fields round-trip (top-level, oauth, user), the
exact cross-CLI `user`-block scenario, schema round-trip + omitempty,
backwards-compat with legacy files, login persistence + graceful probe
failure + stale-clear, and the `auth status` surface. Full CLI suite
(1009 tests) green; oxlint + oxfmt + tsc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(cli): preserve unknown credential data in cleanup/rollback paths

Addresses Magi's REQUEST_CHANGES on #1741. The credentials reader/writer
already round-trips unknown/foreign keys (the cross-CLI forward-compat
contract), but three destructive paths still deleted the whole file when
no known api_key/oauth survived — even when the hidden Symbol-keyed
unknown-field bag held a future credential another CLI owns. That clobbers
exactly the data this PR preserves.

- Add `hasPreservedUnknownData(record)` to store.ts (checks the top-level
  unknown bag + the oauth/user sub-object bags) and export it via the
  barrel.
- `clearOAuth`, `clearUserInfo`, and the failed `auth login --api-key`
  rollback now write the credential-less remnant (carrying the unknown
  bag) instead of deleting the file when unknown/foreign data survives.
  They still delete when nothing worth preserving remains.
- Regression tests: rollback path + both cleanup paths (clearOAuth,
  clearUserInfo) preserve a foreign top-level key; `hasPreservedUnknownData`
  unit tests at all three levels.

Also addresses the review's minor items:
- Add a refresh-path round-trip test (`refreshTokens`) proving an unknown
  key inside the oauth sub-object survives a no-rotation refresh — the
  most-frequent write path, previously only implicitly covered.
- Clarify the `userDisplayName` / `combineName` docstrings: precedence is
  `email > "first last" > first-only > last-only > username`.
- Replace the stale `expires_at` example date in store.ts with
  `<ISO-8601 UTC>`.

Full CLI suite green (1020 tests); tsc, oxlint, oxfmt --check all clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 10:16:23 -07:00

465 lines
17 KiB
TypeScript

/**
* Read/write the shared `~/.heygen/credentials` file (JSON contents,
* no `.json` extension — the path matches heygen-cli).
*
* Current format:
* {
* "api_key": "hg_...",
* "oauth": {
* "access_token": "...",
* "refresh_token": "...",
* "expires_at": "<ISO-8601 UTC>",
* "scope": "openid profile",
* "token_type": "Bearer"
* },
* "user": {
* "email": "...",
* "first_name": "...",
* "last_name": "...",
* "username": "..."
* }
* }
*
* Legacy: a single-line plaintext API key (the format heygen-cli has
* written historically). If `JSON.parse` rejects the file, we treat the
* trimmed contents as an API key; the next write upgrades to JSON.
*
* Writes go to a temp file + rename, 0600 mode, parent dir 0700.
*
* Cross-CLI forward compatibility: this file is SHARED with the Go
* `heygen` CLI (and any future tool). Either CLI may write keys this
* version doesn't model yet. To avoid one CLI silently clobbering the
* other's data on round-trip, the reader stashes every unrecognized
* top-level key (and every unrecognized key inside the `oauth` / `user`
* sub-objects) into a hidden passthrough bag, and the writer re-emits
* them verbatim. Known fields are still strictly validated; the
* passthrough is purely additive and never feeds an HTTP header.
*
* The same contract binds the destructive paths (`clearOAuth`,
* `clearUserInfo`, and the failed `auth login --api-key` rollback): when
* removing a credential would leave the file with no known credential but
* a surviving unknown/foreign top-level (or user-block) key, they write
* the credential-less remnant rather than deleting the file — see
* `hasPreservedUnknownData`. Deleting there would clobber exactly the
* cross-CLI data this machinery exists to preserve.
*/
import { promises as fs } from "node:fs";
import { dirname } from "node:path";
import { credentialPath } from "./paths.js";
import { ErrInvalidStore } from "./errors.js";
const FILE_MODE = 0o600;
const DIR_MODE = 0o700;
/**
* Symbol-keyed slot holding the raw JSON of any keys this CLI version
* doesn't model, captured at read time and re-emitted verbatim at write
* time. A symbol (rather than a string key) keeps it off the typed
* surface so callers can't accidentally read/write it, and `Object.keys`
* / `JSON.stringify` skip it. See the module header for the rationale.
*/
const UNKNOWN = Symbol("hf.credentials.unknownFields");
/** Keys this CLI version models at the top level of the credentials file. */
const KNOWN_ROOT_KEYS = new Set(["api_key", "oauth", "user"]);
/** Keys this CLI version models inside the `oauth` sub-object. */
const KNOWN_OAUTH_KEYS = new Set([
"access_token",
"refresh_token",
"expires_at",
"scope",
"token_type",
]);
/** Keys this CLI version models inside the `user` sub-object. */
const KNOWN_USER_KEYS = new Set(["email", "first_name", "last_name", "username"]);
export interface OAuthTokens {
access_token: string;
refresh_token?: string;
/** ISO-8601 UTC. */
expires_at?: string;
scope?: string;
token_type?: string;
/** Unknown/future keys captured for cross-CLI round-trip. */
[UNKNOWN]?: Record<string, unknown>;
}
/**
* Friendly-display metadata captured at login time from `/v3/users/me`.
* NOT a credential — additive identity info persisted alongside the
* credential so `auth status` can show "Logged in as ..." without
* re-hitting the API. All fields optional; a file with no `user` block
* (a pre-this-change login) is fully backwards-compatible. Mirrors the
* `user` block heygen-cli writes — see `internal/auth/user_store.go`.
*/
export interface StoredUserInfo {
email?: string;
first_name?: string;
last_name?: string;
username?: string;
/** Unknown/future keys captured for cross-CLI round-trip. */
[UNKNOWN]?: Record<string, unknown>;
}
export interface Credentials {
api_key?: string;
oauth?: OAuthTokens;
user?: StoredUserInfo;
/** Unknown/future top-level keys captured for cross-CLI round-trip. */
[UNKNOWN]?: Record<string, unknown>;
}
export type StoreSource = "file_json" | "file_legacy" | "absent";
export interface ReadResult {
credentials: Credentials;
source: StoreSource;
}
export async function readStore(path = credentialPath()): Promise<ReadResult> {
let raw: string;
try {
raw = await fs.readFile(path, "utf8");
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") {
return { credentials: {}, source: "absent" };
}
throw ErrInvalidStore(`unable to read ${path}: ${(err as Error).message}`);
}
const trimmed = raw.trim();
if (trimmed.length === 0) return { credentials: {}, source: "absent" };
if (trimmed.startsWith("{")) {
return { credentials: parseJsonStore(trimmed), source: "file_json" };
}
if (looksLikeApiKey(trimmed)) {
return { credentials: { api_key: trimmed }, source: "file_legacy" };
}
throw ErrInvalidStore("file is not JSON and does not look like a plain API key");
}
export async function writeStore(credentials: Credentials, path = credentialPath()): Promise<void> {
await ensureDir(dirname(path));
const body = JSON.stringify(serializeCredentials(credentials), null, 2);
const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
await fs.writeFile(tmp, `${body}\n`, { mode: FILE_MODE, encoding: "utf8" });
// `mode` on `writeFile` is masked by umask and only applies on file
// creation — explicit chmod is the only reliable way to land on 0600.
// `rename` moves the (already-0600) tmp inode over the destination,
// so the final file carries the tmp's mode; no post-rename chmod
// needed even when overwriting a looser-permissioned file.
await fs.chmod(tmp, FILE_MODE);
await fs.rename(tmp, path);
}
export async function deleteStore(path = credentialPath()): Promise<void> {
try {
await fs.unlink(path);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
throw err;
}
}
/**
* True when `credentials` carries any unrecognized/foreign data captured
* on a hidden passthrough slot — either a top-level unknown key, or an
* unknown key inside the `oauth` / `user` sub-objects.
*
* The cleanup / rollback paths (`clearOAuth`, `clearUserInfo`, the failed
* `auth login --api-key` rollback) use this to decide between deleting the
* file and writing a credential-less remnant. When no known credential
* survives BUT foreign data does, that data may be a future credential or
* metadata key another CLI owns — deleting the file would clobber exactly
* what the cross-CLI forward-compatibility contract promises to preserve.
* So those paths write the remaining record (carrying the unknown bag)
* instead of deleting. Only when nothing worth preserving remains do they
* delete.
*/
export function hasPreservedUnknownData(credentials: Credentials): boolean {
if (hasUnknownBag(credentials[UNKNOWN])) return true;
if (hasUnknownBag(credentials.oauth?.[UNKNOWN])) return true;
if (hasUnknownBag(credentials.user?.[UNKNOWN])) return true;
return false;
}
function hasUnknownBag(bag: Record<string, unknown> | undefined): boolean {
return bag !== undefined && Object.keys(bag).length > 0;
}
/** Remove only the `oauth` block. Used by `auth logout --keep-api-key`. */
export async function clearOAuth(path = credentialPath()): Promise<void> {
const { credentials, source } = await readStore(path);
if (source === "absent" || !credentials.oauth) return;
// Drop oauth, keep everything else (api_key, the friendly-display
// user block, and any unknown/foreign keys) so a logout that only
// clears the OAuth session doesn't silently wipe co-located data.
const next: Credentials = { ...credentials };
delete next.oauth;
if (!next.api_key && !hasPreservedUnknownData(next)) {
// Nothing worth preserving survives. The leftover user block had no
// friendly fields and there's no foreign/unknown data to round-trip,
// so this is orphaned metadata with no credential to attach to — drop
// the file. (A surviving top-level / user-block unknown key, by
// contrast, may be a future credential another CLI owns, so we keep
// the file in that case.)
await deleteStore(path);
return;
}
await writeStore(next, path);
}
async function ensureDir(dir: string): Promise<void> {
try {
const stat = await fs.stat(dir);
if (!stat.isDirectory()) {
throw ErrInvalidStore(`${dir} exists and is not a directory`);
}
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
await fs.mkdir(dir, { recursive: true, mode: DIR_MODE });
}
try {
await fs.chmod(dir, DIR_MODE);
} catch {
/* perm-less filesystems are fine */
}
}
function parseJsonStore(text: string): Credentials {
const obj = parseJsonObject(text, "credential file root");
const out: Credentials = {};
const apiKey = pickRequiredStringOrAbsent(obj, "api_key", "api_key");
if (apiKey !== undefined) {
if (!isHeaderSafe(apiKey)) {
throw ErrInvalidStore("api_key must not contain control characters");
}
out.api_key = apiKey;
}
if (obj["oauth"] !== undefined && obj["oauth"] !== null) {
out.oauth = parseOAuth(obj["oauth"]);
}
if (obj["user"] !== undefined && obj["user"] !== null) {
out.user = parseUser(obj["user"]);
}
// Capture any top-level keys this CLI version doesn't model so the
// next write round-trips them instead of dropping another CLI's data.
const unknownRoot = collectUnknown(obj, KNOWN_ROOT_KEYS);
if (unknownRoot) out[UNKNOWN] = unknownRoot;
return out;
}
/** Optional-field picker variants used by the data-driven parsers. */
type FieldPicker = "header_safe" | "non_empty";
const PICKERS: Record<
FieldPicker,
(obj: Record<string, unknown>, key: string) => string | undefined
> = {
header_safe: pickHeaderSafeString,
non_empty: pickNonEmptyString,
};
/**
* Copy each `[field, picker]` from `obj` onto `out` when the picker
* yields a value. Data-driven so the optional-field handling stays a
* single loop instead of a long if-chain per parser. `out` is written
* through an index cast — the `spec` field names are the contract that
* keeps the assignments type-correct at the call site.
*/
function assignOptionalStrings(
out: object,
obj: Record<string, unknown>,
spec: readonly [string, FieldPicker][],
): void {
const target = out as Record<string, unknown>;
for (const [field, picker] of spec) {
const v = PICKERS[picker](obj, field);
if (v) target[field] = v;
}
}
const OAUTH_OPTIONAL: readonly [string, FieldPicker][] = [
["refresh_token", "header_safe"],
["expires_at", "non_empty"],
["scope", "non_empty"],
["token_type", "non_empty"],
];
function parseOAuth(raw: unknown): OAuthTokens {
const obj = asJsonObject(raw, "oauth");
const accessToken = pickHeaderSafeString(obj, "access_token");
if (!accessToken) {
throw ErrInvalidStore("oauth.access_token must be a non-empty string with no control chars");
}
const out: OAuthTokens = { access_token: accessToken };
assignOptionalStrings(out, obj, OAUTH_OPTIONAL);
const unknownOAuth = collectUnknown(obj, KNOWN_OAUTH_KEYS);
if (unknownOAuth) out[UNKNOWN] = unknownOAuth;
return out;
}
const USER_OPTIONAL: readonly [string, FieldPicker][] = [
["email", "non_empty"],
["first_name", "non_empty"],
["last_name", "non_empty"],
["username", "non_empty"],
];
/**
* Parse the friendly-display `user` block. Every field is optional and
* lenient — a wrong-typed or empty value is simply skipped rather than
* rejected, because this is additive METADATA, not a credential, and a
* malformed sub-field must never block resolving a perfectly good
* api_key / oauth token. (Contrast with `parseOAuth`, where a missing
* access_token is a hard error.) Unknown keys round-trip.
*/
function parseUser(raw: unknown): StoredUserInfo {
const obj = asJsonObject(raw, "user");
const out: StoredUserInfo = {};
assignOptionalStrings(out, obj, USER_OPTIONAL);
const unknownUser = collectUnknown(obj, KNOWN_USER_KEYS);
if (unknownUser) out[UNKNOWN] = unknownUser;
return out;
}
/** Narrow `raw` to a plain JSON object or throw a labelled error. */
function asJsonObject(raw: unknown, label: string): Record<string, unknown> {
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
throw ErrInvalidStore(`${label} must be a JSON object`);
}
return raw as Record<string, unknown>;
}
/**
* Return a shallow copy of every entry in `obj` whose key is not in
* `known`, or `undefined` when there are none. Used to capture
* unrecognized JSON for verbatim re-emission on the next write.
*/
function collectUnknown(
obj: Record<string, unknown>,
known: Set<string>,
): Record<string, unknown> | undefined {
let bag: Record<string, unknown> | undefined;
for (const key of Object.keys(obj)) {
if (known.has(key)) continue;
(bag ??= {})[key] = obj[key];
}
return bag;
}
function parseJsonObject(text: string, label: string): Record<string, unknown> {
let raw: unknown;
try {
raw = JSON.parse(text);
} catch (err) {
throw ErrInvalidStore(`invalid JSON: ${(err as Error).message}`);
}
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
throw ErrInvalidStore(`${label} must be a JSON object`);
}
return raw as Record<string, unknown>;
}
function pickNonEmptyString(obj: Record<string, unknown>, key: string): string | undefined {
const v = obj[key];
return typeof v === "string" && v.length > 0 ? v : undefined;
}
/** Like `pickNonEmptyString` but rejects values containing control chars. */
function pickHeaderSafeString(obj: Record<string, unknown>, key: string): string | undefined {
const v = pickNonEmptyString(obj, key);
return v !== undefined && isHeaderSafe(v) ? v : undefined;
}
/**
* Header-safety check for credential strings: reject any string with
* CR, LF, NUL, or other C0 control characters. Without this, a
* malicious credentials.json could smuggle extra request headers via
* `Authorization` / `x-api-key` (RFC 7230 header injection).
*/
export function isHeaderSafe(s: string): boolean {
// Reject U+0000-U+001F (C0 controls) and U+007F (DEL) — bytes that
// aren't allowed in HTTP header values. Using charCodeAt avoids
// embedding control characters in regex source (lint requirement).
for (let i = 0; i < s.length; i++) {
const c = s.charCodeAt(i);
if (c < 0x20 || c === 0x7f) return false;
}
return true;
}
/**
* Strict variant: returns the string when present and non-empty,
* `undefined` when the key is absent or null, and throws when the
* field is present-but-invalid (wrong type or empty string).
*/
function pickRequiredStringOrAbsent(
obj: Record<string, unknown>,
key: string,
errorLabel: string,
): string | undefined {
const v = obj[key];
if (v === undefined || v === null) return undefined;
if (typeof v !== "string" || v.length === 0) {
throw ErrInvalidStore(`${errorLabel} must be a non-empty string`);
}
return v;
}
function serializeCredentials(c: Credentials): Record<string, unknown> {
// Re-emit unrecognized top-level keys first so the known fields below
// are authoritative (collectUnknown already excludes known keys, so
// there's no real collision — this is belt-and-suspenders).
const out: Record<string, unknown> = { ...(c[UNKNOWN] ?? {}) };
if (c.api_key) out["api_key"] = c.api_key;
if (c.oauth) out["oauth"] = serializeOAuth(c.oauth);
if (c.user) {
const user = serializeUser(c.user);
// Omit an all-empty user block entirely (no empty `"user": {}` litter).
if (Object.keys(user).length > 0) out["user"] = user;
}
return out;
}
function serializeOAuth(o: OAuthTokens): Record<string, unknown> {
const oauth: Record<string, unknown> = { ...(o[UNKNOWN] ?? {}) };
oauth["access_token"] = o.access_token;
if (o.refresh_token) oauth["refresh_token"] = o.refresh_token;
if (o.expires_at) oauth["expires_at"] = o.expires_at;
if (o.scope) oauth["scope"] = o.scope;
if (o.token_type) oauth["token_type"] = o.token_type;
return oauth;
}
function serializeUser(u: StoredUserInfo): Record<string, unknown> {
const user: Record<string, unknown> = { ...(u[UNKNOWN] ?? {}) };
if (u.email) user["email"] = u.email;
if (u.first_name) user["first_name"] = u.first_name;
if (u.last_name) user["last_name"] = u.last_name;
if (u.username) user["username"] = u.username;
return user;
}
/**
* Legacy-plaintext heuristic. HeyGen API keys come in multiple formats
* (`sk_V2_…`, historic `hg_…`, partner keys, etc.) and the CLI should
* NOT shape-check them — the backend's `/v3/users/me` is the source of
* truth and the existing `auth login` rollback handles bad keys cleanly.
* We only require: a single line, printable, of reasonable length, and
* header-safe (no CR/LF). JSON files are detected separately by the
* leading `{`, so this path can't swallow a JSON fragment.
*/
function looksLikeApiKey(s: string): boolean {
if (s.length < 8) return false;
if (!isHeaderSafe(s)) return false;
// Single line of printable ASCII (excluding space, since real keys
// don't contain spaces — a space-bearing blob is almost certainly
// not a credential).
return /^[!-~]+$/.test(s);
}