feat(cli): persist + show friendly user identity; preserve unknown credential fields

packages/cli/src/auth/index.ts

@@ -5,8 +5,23 @@
 
 export { isAuthError } from "./errors.js";
 
-export { clearOAuth, deleteStore, isHeaderSafe, readStore, writeStore } from "./store.js";
-export type { Credentials } from "./store.js";
+export {
+  clearOAuth,
+  deleteStore,
+  hasPreservedUnknownData,
+  isHeaderSafe,
+  readStore,
+  writeStore,
+} from "./store.js";
+export type { Credentials, StoredUserInfo } from "./store.js";
+
+export {
+  clearUserInfo,
+  isUserInfoEmpty,
+  loadUserInfo,
+  saveUserInfo,
+  userDisplayName,
+} from "./user.js";
 
 export { configDir, credentialPath } from "./paths.js";
 

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

@@ -1,3 +1,4 @@
+import { promises as fs } from "node:fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { setupTempAuthEnv } from "./_test-utils.js";
 import { isAuthError } from "./errors.js";
@@ -182,6 +183,38 @@ describe("auth/oauth", () => {
       expect(credentials.oauth?.access_token).toBe("new_at");
     });
 
+    it("preserves an unknown key INSIDE the oauth sub-object across a refresh", async () => {
+      // The refresh path is `persistOAuth(preserveMissing: true)`, i.e.
+      // `{ ...existing.oauth, ...tokens }` — object spread carries the
+      // hidden Symbol-keyed unknown bag from `existing.oauth`, so a key
+      // another CLI wrote inside `oauth` (e.g. an `id_token`) must survive
+      // the no-rotation refresh. Refresh is the most-frequent write path,
+      // so a silent regression here would be the worst case.
+      const path = (await import("./paths.js")).credentialPath();
+      await fs.writeFile(
+        path,
+        JSON.stringify({
+          oauth: {
+            access_token: "old_at",
+            refresh_token: "keep_me_rt",
+            id_token: "future_id_token_value",
+          },
+        }),
+        { mode: 0o600 },
+      );
+      const fetchImpl = (async () =>
+        new Response(JSON.stringify({ access_token: "new_at", expires_in: 3600 }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        })) as unknown as typeof fetch;
+      await refreshTokens("keep_me_rt", { fetchImpl });
+
+      const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+      expect(onDisk.oauth.access_token).toBe("new_at");
+      // The unknown oauth sub-key rode through on the hidden slot.
+      expect(onDisk.oauth.id_token).toBe("future_id_token_value");
+    });
+
     it("throws REFRESH_FAILED on 400/401", async () => {
       const fetchImpl = (async () =>
         new Response("invalid_grant", { status: 400 })) as unknown as typeof fetch;
@@ -296,5 +329,31 @@ describe("auth/oauth", () => {
       expect(credentials.oauth?.access_token).toBe("new_at");
       expect(credentials.oauth?.refresh_token).toBe("new_rt");
     });
+
+    it("preserves the user block AND unknown/foreign keys across fresh login", async () => {
+      // The OAuth write path must not drop co-located data the other CLI
+      // (or a prior login) wrote. Seed a user block plus a future key,
+      // then log in fresh — both must survive the OAuth-block overwrite.
+      const path = (await import("./paths.js")).credentialPath();
+      await fs.writeFile(
+        path,
+        JSON.stringify({
+          oauth: { access_token: "old_at" },
+          user: { email: "jane@example.com", username: "jdoe" },
+          future_field: { keep: true },
+        }),
+        { mode: 0o600 },
+      );
+      const fetchImpl = tokenFetch({ access_token: "new_at", expires_in: 3600 });
+      await startAuthorizationCodeFlow({ fetchImpl });
+
+      const { credentials } = await readStore();
+      expect(credentials.oauth?.access_token).toBe("new_at");
+      expect(credentials.user).toEqual({ email: "jane@example.com", username: "jdoe" });
+
+      // The unknown key is on a hidden slot — assert via the raw file.
+      const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+      expect(onDisk.future_field).toEqual({ keep: true });
+    });
   });
 });

packages/cli/src/auth/oauth.ts

@@ -414,8 +414,11 @@ async function persistOAuth(
   const oauth: OAuthTokens = opts.preserveMissing
     ? { ...existing.oauth, ...tokens }
     : { ...tokens };
-  // Keep co-located API key in both modes.
-  await writeStore({ ...(existing.api_key ? { api_key: existing.api_key } : {}), oauth });
+  // Start from the existing record so co-located data survives: the
+  // api_key, the friendly-display `user` block, AND any unknown/foreign
+  // keys another CLI wrote (carried on a hidden symbol slot by spread).
+  // Only the `oauth` block is overwritten here.
+  await writeStore({ ...existing, oauth });
 }
 
 async function readJsonOrThrow(res: Response): Promise<unknown> {

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

@@ -3,7 +3,14 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { isAuthError } from "./errors.js";
-import { clearOAuth, deleteStore, readStore, writeStore, type Credentials } from "./store.js";
+import {
+  clearOAuth,
+  deleteStore,
+  hasPreservedUnknownData,
+  readStore,
+  writeStore,
+  type Credentials,
+} from "./store.js";
 
 async function makeTmpDir(): Promise<string> {
   return fs.mkdtemp(join(tmpdir(), "hf-auth-store-"));
@@ -173,12 +180,143 @@ describe("auth/store", () => {
     await expect(readStore(path)).rejects.toSatisfy((err) => isAuthError(err));
   });
 
-  it("drops unknown top-level keys", async () => {
+  it("exposes only the typed surface for known keys (unknown keys hidden from callers)", async () => {
+    // The typed `credentials` view shows only the modelled keys —
+    // unknown/foreign keys are captured in a hidden (symbol-keyed)
+    // passthrough slot, not the enumerable surface, so callers can't
+    // accidentally read them. Round-trip preservation is covered below.
     await fs.writeFile(path, JSON.stringify({ api_key: "hg_x", future_field: { stuff: 1 } }), {
       mode: 0o600,
     });
     const result = await readStore(path);
-    expect(result.credentials).toEqual({ api_key: "hg_x" });
+    expect(Object.keys(result.credentials)).toEqual(["api_key"]);
+    expect(result.credentials.api_key).toBe("hg_x");
+  });
+
+  // --- Cross-CLI forward compatibility: unknown-field preservation. ---
+  // The credentials file is SHARED with the Go `heygen` CLI. If this CLI
+  // strips keys it doesn't model when it writes the file back, it
+  // silently destroys the other CLI's data (and vice versa). The writer
+  // MUST round-trip unknown fields untouched.
+
+  it("preserves an unknown TOP-LEVEL key across a read → write round-trip", async () => {
+    // Simulate a file another CLI version wrote with a future key.
+    await fs.writeFile(
+      path,
+      JSON.stringify({ api_key: "hg_x", future_field: { nested: [1, 2], flag: true } }),
+      { mode: 0o600 },
+    );
+    // Read it, then write back a typed update (here: just the api_key it
+    // surfaced). The unknown key must survive.
+    const { credentials } = await readStore(path);
+    await writeStore(credentials, path);
+
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.api_key).toBe("hg_x");
+    expect(onDisk.future_field).toEqual({ nested: [1, 2], flag: true });
+  });
+
+  it("preserves the heygen-cli `user` block when this CLI rewrites only the credential", async () => {
+    // The exact cross-CLI data-loss scenario: heygen-cli wrote a `user`
+    // block; hyperframes-cli updates the api_key and must not drop it.
+    await fs.writeFile(
+      path,
+      JSON.stringify({
+        api_key: "hg_old",
+        user: { email: "jane@example.com", first_name: "Jane", last_name: "Doe", username: "jdoe" },
+      }),
+      { mode: 0o600 },
+    );
+    const { credentials } = await readStore(path);
+    credentials.api_key = "hg_new";
+    await writeStore(credentials, path);
+
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.api_key).toBe("hg_new");
+    expect(onDisk.user).toEqual({
+      email: "jane@example.com",
+      first_name: "Jane",
+      last_name: "Doe",
+      username: "jdoe",
+    });
+  });
+
+  it("preserves an unknown key INSIDE the oauth sub-object", async () => {
+    await fs.writeFile(
+      path,
+      JSON.stringify({
+        oauth: { access_token: "at_1", id_token: "future_id_token_value" },
+      }),
+      { mode: 0o600 },
+    );
+    const { credentials } = await readStore(path);
+    await writeStore(credentials, path);
+
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.oauth.access_token).toBe("at_1");
+    expect(onDisk.oauth.id_token).toBe("future_id_token_value");
+  });
+
+  it("preserves an unknown key INSIDE the user sub-object", async () => {
+    await fs.writeFile(
+      path,
+      JSON.stringify({
+        api_key: "hg_x",
+        user: { email: "u@example.com", avatar_url: "https://cdn/x.png" },
+      }),
+      { mode: 0o600 },
+    );
+    const { credentials } = await readStore(path);
+    await writeStore(credentials, path);
+
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.user.email).toBe("u@example.com");
+    expect(onDisk.user.avatar_url).toBe("https://cdn/x.png");
+  });
+
+  it("round-trips the user block (schema + omitempty: empty fields are not written)", async () => {
+    const creds: Credentials = {
+      api_key: "hg_x",
+      user: { email: "u@example.com", username: "u" },
+    };
+    await writeStore(creds, path);
+    const result = await readStore(path);
+    expect(result.credentials.user).toEqual({ email: "u@example.com", username: "u" });
+
+    // omitempty: only the populated fields appear on disk — no empty
+    // first_name / last_name strings littering the file.
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.user).toEqual({ email: "u@example.com", username: "u" });
+    expect(Object.keys(onDisk.user)).toEqual(["email", "username"]);
+  });
+
+  it('omits an all-empty user block entirely (no `"user": {}` litter)', async () => {
+    await writeStore({ api_key: "hg_x", user: {} }, path);
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.user).toBeUndefined();
+    expect(onDisk.api_key).toBe("hg_x");
+  });
+
+  it("backwards-compat: a legacy file WITHOUT a user block parses with user undefined", async () => {
+    await fs.writeFile(path, JSON.stringify({ api_key: "hg_legacy" }), { mode: 0o600 });
+    const result = await readStore(path);
+    expect(result.source).toBe("file_json");
+    expect(result.credentials.api_key).toBe("hg_legacy");
+    expect(result.credentials.user).toBeUndefined();
+  });
+
+  it("ignores a malformed user sub-field rather than rejecting the whole file", async () => {
+    // The user block is additive metadata — a junk sub-field must never
+    // block resolving a perfectly good api_key. Non-string fields are
+    // dropped; the credential survives.
+    await fs.writeFile(
+      path,
+      JSON.stringify({ api_key: "hg_x", user: { email: "u@example.com", first_name: 12345 } }),
+      { mode: 0o600 },
+    );
+    const result = await readStore(path);
+    expect(result.credentials.api_key).toBe("hg_x");
+    expect(result.credentials.user).toEqual({ email: "u@example.com" });
   });
 
   it("deleteStore is idempotent", async () => {
@@ -202,8 +340,119 @@ describe("auth/store", () => {
     await expect(fs.access(path)).rejects.toThrow();
   });
 
+  it("clearOAuth keeps the user block (and unknown keys) when an api_key survives", async () => {
+    await fs.writeFile(
+      path,
+      JSON.stringify({
+        api_key: "hg_keep",
+        oauth: { access_token: "drop_me" },
+        user: { email: "u@example.com" },
+        future_field: 1,
+      }),
+      { mode: 0o600 },
+    );
+    await clearOAuth(path);
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.oauth).toBeUndefined();
+    expect(onDisk.api_key).toBe("hg_keep");
+    expect(onDisk.user).toEqual({ email: "u@example.com" });
+    expect(onDisk.future_field).toBe(1);
+  });
+
   it("clearOAuth is a no-op when file is absent", async () => {
     await clearOAuth(path);
     await expect(fs.access(path)).rejects.toThrow();
   });
+
+  // --- Destructive paths must not clobber preserved unknown data. ---
+  // When clearing the only known credential would otherwise delete the
+  // file, a surviving unknown/foreign top-level key (a future credential
+  // another CLI owns) must keep the file alive — deleting would clobber
+  // exactly the cross-CLI data this machinery exists to preserve.
+
+  it("clearOAuth keeps the file (writing the unknown bag) when no api_key but a foreign top-level key survives", async () => {
+    await fs.writeFile(
+      path,
+      JSON.stringify({
+        oauth: { access_token: "drop_me" },
+        future_credential: { token: "owned_by_other_cli" },
+      }),
+      { mode: 0o600 },
+    );
+    await clearOAuth(path);
+    // File must still exist and carry the foreign key.
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.oauth).toBeUndefined();
+    expect(onDisk.future_credential).toEqual({ token: "owned_by_other_cli" });
+  });
+
+  it("clearOAuth keeps the file when no api_key but a foreign key survives inside the user block", async () => {
+    // The user block has no known friendly fields, only a foreign sub-key
+    // — the block itself survives the oauth clear, so its unknown data
+    // must too.
+    await fs.writeFile(
+      path,
+      JSON.stringify({
+        oauth: { access_token: "drop_me" },
+        user: { external_org_id: "org_123" },
+      }),
+      { mode: 0o600 },
+    );
+    await clearOAuth(path);
+    const onDisk = JSON.parse(await fs.readFile(path, "utf8"));
+    expect(onDisk.oauth).toBeUndefined();
+    expect(onDisk.user).toEqual({ external_org_id: "org_123" });
+  });
+
+  it("clearOAuth still deletes the file when only a known (empty-after-clear) surface remains", async () => {
+    // No api_key, no foreign data — just the oauth block being cleared.
+    // Nothing worth preserving, so the file goes.
+    await writeStore({ oauth: { access_token: "only" } }, path);
+    await clearOAuth(path);
+    await expect(fs.access(path)).rejects.toThrow();
+  });
+
+  describe("hasPreservedUnknownData", () => {
+    it("false for an empty record", () => {
+      expect(hasPreservedUnknownData({})).toBe(false);
+    });
+
+    it("false for a record with only known fields", () => {
+      expect(
+        hasPreservedUnknownData({
+          api_key: "hg_x",
+          oauth: { access_token: "at" },
+          user: { email: "u@example.com" },
+        }),
+      ).toBe(false);
+    });
+
+    it("true when a top-level unknown key was captured at read time", async () => {
+      await fs.writeFile(path, JSON.stringify({ api_key: "hg_x", future_field: 1 }), {
+        mode: 0o600,
+      });
+      const { credentials } = await readStore(path);
+      expect(hasPreservedUnknownData(credentials)).toBe(true);
+    });
+
+    it("true when an unknown key was captured inside the oauth sub-object", async () => {
+      await fs.writeFile(
+        path,
+        JSON.stringify({ oauth: { access_token: "at", id_token: "future" } }),
+        { mode: 0o600 },
+      );
+      const { credentials } = await readStore(path);
+      expect(hasPreservedUnknownData(credentials)).toBe(true);
+    });
+
+    it("true when an unknown key was captured inside the user sub-object", async () => {
+      await fs.writeFile(
+        path,
+        JSON.stringify({ api_key: "hg_x", user: { email: "u@example.com", avatar_url: "x" } }),
+        { mode: 0o600 },
+      );
+      const { credentials } = await readStore(path);
+      expect(hasPreservedUnknownData(credentials)).toBe(true);
+    });
+  });
 });