auth: add file-based credential storage (PRINFRA-123) (#17)

## Description

### What This Adds
This PR adds **persistent local authentication** to the CLI.

`heygen auth login` reads an API key from stdin (interactive prompt or pipe), stores it in the CLI config directory with **restrictive file permissions** (0600), and returns structured JSON. This gives the CLI a real local login flow instead of requiring users to export `HEYGEN_API_KEY` for every session.

### Login Flow
`auth login` **skips the global pre-run auth check** via Cobra annotations (`skipAuth: "true"`). Before this change, `PersistentPreRunE` tried to resolve credentials for every command, which blocked the login command itself when no API key existed yet.

### Credential Resolution Order
Credential lookup uses a chain resolver with priority order:

1. `HEYGEN_API_KEY` env var — for CI, Docker, and agent workflows
2. `~/.heygen/credentials` file — written by `heygen auth login`

### Error Handling
The auth layer distinguishes between:
- A credential source that is **absent** (`ErrNotConfigured`) — falls through to the next resolver
- A credential source that is **present but broken** (permission denied, empty file) — surfaces immediately with an actionable hint pointing to the actual credential path

### No `--key` flag
Industry standard (gh, AWS, Stripe, gcloud) is to never pass secrets as CLI flags — they leak into `ps` output and shell history. Instead:
- **Agents/CI**: `HEYGEN_API_KEY` env var (no login needed)
- **Humans (interactive)**: `heygen auth login` → prompt with hidden input
- **Humans (scripted)**: `echo "$KEY" | heygen auth login`

### Example Outputs

**Successful login:**
```
$ echo "$KEY" | heygen auth login
{
  "message": "API key saved to ~/.heygen/credentials"
}
```

**Empty input:**
```
$ echo "" | heygen auth login
{
  "error": {
    "code": "usage_error",
    "message": "no API key provided"
  }
}
```

**No credentials configured (on any API command):**
```
$ heygen video list
{
  "error": {
    "code": "auth_error",
    "message": "no API key found",
    "hint": "Set HEYGEN_API_KEY env var or run: heygen auth login"
  }
}
```

**Linear issue:** PRINFRA-123

## Testing

### Automated (16 tests)
- **Chain resolver** (4): first-wins, fallthrough on ErrNotConfigured, all-not-configured → auth error, broken-source → surfaces immediately
- **File resolver** (4): reads key, missing file → ErrNotConfigured, empty file → real error, whitespace trimming
- **File store** (4): save + read back, creates directory with 0700, file permissions 0600 (skipped on Windows), overwrite existing
- **Auth login command** (4): success via stdin pipe, empty input → exit 2, overwrite, skipAuth bypass (no HEYGEN_API_KEY needed)
- All existing M0 tests pass unchanged

### Manual smoke tests
- `echo "key" | ./bin/heygen auth login` — exit 0, credentials saved with 0600 perms
- `echo "" | ./bin/heygen auth login` — exit 2, `usage_error`
- Overwrite: second key wins
- Credential chain: `unset HEYGEN_API_KEY`, CLI resolves from credentials file
- `heygen auth login --help` — shows `HEYGEN_API_KEY` env var hint for agents

Author: somanshreddy

cmd/heygen/auth.go

@@ -0,0 +1,13 @@
+package main
+
+import "github.com/spf13/cobra"
+
+func newAuthCmd(ctx *cmdContext) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:         "auth",
+		Short:       "Manage authentication",
+		Annotations: map[string]string{"skipAuth": "true"},
+	}
+	cmd.AddCommand(newAuthLoginCmd(ctx))
+	return cmd
+}

cmd/heygen/auth_login.go

@@ -0,0 +1,80 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+
+	"github.com/heygen-com/heygen-cli/internal/auth"
+	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
+	"github.com/heygen-com/heygen-cli/internal/paths"
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+)
+
+func newAuthLoginCmd(ctx *cmdContext) *cobra.Command {
+	return &cobra.Command{
+		Use:   "login",
+		Short: "Store API key for CLI authentication",
+		Long: `Reads an API key from stdin and stores it for future CLI use.
+
+Interactive:
+  heygen auth login
+
+Piped:
+  echo "$KEY" | heygen auth login
+
+You can also set the HEYGEN_API_KEY environment variable.
+The env var takes priority over stored credentials.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			key, err := readAPIKey(cmd.InOrStdin(), cmd.ErrOrStderr())
+			if err != nil {
+				return err
+			}
+			if key == "" {
+				return clierrors.NewUsage("no API key provided")
+			}
+
+			store := &auth.FileCredentialStore{}
+			if err := store.Save(key); err != nil {
+				return clierrors.New(fmt.Sprintf("failed to save credentials: %v", err))
+			}
+
+			credPath := filepath.Join(paths.ConfigDir(), "credentials")
+			data, err := json.Marshal(map[string]string{
+				"message": "API key saved to " + credPath,
+			})
+			if err != nil {
+				return clierrors.New(fmt.Sprintf("failed to encode response: %v", err))
+			}
+
+			return ctx.formatter.Data(data)
+		},
+	}
+}
+
+func readAPIKey(in io.Reader, errOut io.Writer) (string, error) {
+	if file, ok := in.(interface{ Fd() uintptr }); ok && term.IsTerminal(int(file.Fd())) {
+		if _, err := fmt.Fprint(errOut, "Enter API key: "); err != nil {
+			return "", clierrors.New(fmt.Sprintf("failed to write prompt: %v", err))
+		}
+
+		raw, err := term.ReadPassword(int(file.Fd()))
+		if _, writeErr := fmt.Fprintln(errOut); writeErr != nil && err == nil {
+			err = writeErr
+		}
+		if err != nil {
+			return "", clierrors.New(fmt.Sprintf("failed to read input: %v", err))
+		}
+
+		return strings.TrimSpace(string(raw)), nil
+	}
+
+	data, err := io.ReadAll(in)
+	if err != nil {
+		return "", clierrors.New(fmt.Sprintf("failed to read stdin: %v", err))
+	}
+	return strings.TrimSpace(string(data)), nil
+}

cmd/heygen/auth_test.go

@@ -0,0 +1,80 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestAuthLogin_Success(t *testing.T) {
+	t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+
+	res := runCommandWithInput(t, "http://example.invalid", "", strings.NewReader("test-key-123\n"), "auth", "login")
+
+	if res.ExitCode != 0 {
+		t.Fatalf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+
+	var parsed map[string]string
+	if err := json.Unmarshal([]byte(res.Stdout), &parsed); err != nil {
+		t.Fatalf("stdout is not valid JSON: %v\nstdout: %s", err, res.Stdout)
+	}
+	if parsed["message"] == "" {
+		t.Fatalf("expected success message, got %v", parsed)
+	}
+
+	data, err := os.ReadFile(filepath.Join(os.Getenv("HEYGEN_CONFIG_DIR"), "credentials"))
+	if err != nil {
+		t.Fatalf("ReadFile: %v", err)
+	}
+	if string(data) != "test-key-123\n" {
+		t.Fatalf("credentials = %q, want %q", string(data), "test-key-123\n")
+	}
+}
+
+func TestAuthLogin_EmptyInput(t *testing.T) {
+	t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+
+	res := runCommandWithInput(t, "http://example.invalid", "", strings.NewReader("\n"), "auth", "login")
+
+	if res.ExitCode != 2 {
+		t.Fatalf("ExitCode = %d, want 2\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+}
+
+func TestAuthLogin_OverwriteExisting(t *testing.T) {
+	t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+
+	first := runCommandWithInput(t, "http://example.invalid", "", strings.NewReader("first-key\n"), "auth", "login")
+	if first.ExitCode != 0 {
+		t.Fatalf("first login failed: %#v", first)
+	}
+
+	second := runCommandWithInput(t, "http://example.invalid", "", strings.NewReader("second-key\n"), "auth", "login")
+	if second.ExitCode != 0 {
+		t.Fatalf("second login failed: %#v", second)
+	}
+
+	data, err := os.ReadFile(filepath.Join(os.Getenv("HEYGEN_CONFIG_DIR"), "credentials"))
+	if err != nil {
+		t.Fatalf("ReadFile: %v", err)
+	}
+	if string(data) != "second-key\n" {
+		t.Fatalf("credentials = %q, want %q", string(data), "second-key\n")
+	}
+}
+
+func TestAuthLogin_SkipsAuth(t *testing.T) {
+	t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+
+	res := runCommandWithInput(t, "http://example.invalid", "", strings.NewReader("test-key-123\n"), "auth", "login")
+
+	if res.ExitCode != 0 {
+		t.Fatalf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if res.Stderr != "" {
+		t.Fatalf("stderr = %q, want empty", res.Stderr)
+	}
+}

cmd/heygen/context.go

@@ -0,0 +1,58 @@
+package main
+
+import (
+	"github.com/heygen-com/heygen-cli/internal/auth"
+	"github.com/heygen-com/heygen-cli/internal/client"
+	"github.com/heygen-com/heygen-cli/internal/config"
+	"github.com/heygen-com/heygen-cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+// cmdContext holds shared dependencies created in PersistentPreRunE
+// and consumed by child commands via closures.
+type cmdContext struct {
+	client         *client.Client
+	formatter      output.Formatter
+	configProvider config.Provider
+}
+
+// skipAuth checks whether the command (or any parent) is annotated to
+// bypass credential resolution. Used by auth and config commands.
+func skipAuth(cmd *cobra.Command) bool {
+	for c := cmd; c != nil; c = c.Parent() {
+		if c.Annotations != nil && c.Annotations["skipAuth"] == "true" {
+			return true
+		}
+	}
+	return false
+}
+
+// initContext sets up the config provider and, for commands that require
+// auth, resolves credentials and creates the HTTP client.
+func initContext(cmd *cobra.Command, version string, ctx *cmdContext) error {
+	provider := &config.EnvProvider{}
+	ctx.configProvider = provider
+
+	if skipAuth(cmd) {
+		ctx.client = nil
+		return nil
+	}
+
+	resolver := &auth.ChainCredentialResolver{
+		Resolvers: []auth.CredentialResolver{
+			&auth.EnvCredentialResolver{},
+			&auth.FileCredentialResolver{},
+		},
+	}
+	apiKey, err := resolver.Resolve()
+	if err != nil {
+		return err
+	}
+
+	ctx.client = client.New(apiKey,
+		client.WithBaseURL(provider.BaseURL()),
+		client.WithUserAgent("heygen-cli/"+version),
+	)
+
+	return nil
+}

cmd/heygen/root.go

@@ -5,23 +5,12 @@ import (
 	"strings"
 
 	"github.com/heygen-com/heygen-cli/gen"
-	"github.com/heygen-com/heygen-cli/internal/auth"
-	"github.com/heygen-com/heygen-cli/internal/client"
 	"github.com/heygen-com/heygen-cli/internal/command"
-	"github.com/heygen-com/heygen-cli/internal/config"
 	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
 	"github.com/heygen-com/heygen-cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
-// cmdContext holds shared dependencies created in PersistentPreRunE
-// and consumed by child commands via closures.
-type cmdContext struct {
-	client         *client.Client
-	formatter      output.Formatter
-	configProvider config.Provider
-}
-
 func newRootCmd(version string, formatter output.Formatter) *cobra.Command {
 	ctx := &cmdContext{formatter: formatter}
 
@@ -32,24 +21,7 @@ func newRootCmd(version string, formatter output.Formatter) *cobra.Command {
 		SilenceUsage:  true, // we handle usage errors ourselves
 		SilenceErrors: true, // we handle error output ourselves
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
-			// 1. Create config provider (BaseURL only — auth is Resolver's job)
-			provider := &config.EnvProvider{}
-			ctx.configProvider = provider
-
-			// 2. Resolve credentials (env var today; file-based storage later)
-			resolver := &auth.EnvCredentialResolver{}
-			apiKey, err := resolver.Resolve()
-			if err != nil {
-				return err
-			}
-
-			// 3. Create client using config.Provider for BaseURL
-			ctx.client = client.New(apiKey,
-				client.WithBaseURL(provider.BaseURL()),
-				client.WithUserAgent("heygen-cli/"+version),
-			)
-
-			return nil
+			return initContext(cmd, version, ctx)
 		},
 	}
 
@@ -58,6 +30,7 @@ func newRootCmd(version string, formatter output.Formatter) *cobra.Command {
 		return clierrors.NewUsage(err.Error())
 	})
 
+	root.AddCommand(newAuthCmd(ctx))
 	registerGroups(root, ctx, gen.Groups)
 
 	return root
@@ -76,28 +49,15 @@ func newRootCmdWithSpecs(version string, formatter output.Formatter, groups map[
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
-			provider := &config.EnvProvider{}
-			ctx.configProvider = provider
-
-			resolver := &auth.EnvCredentialResolver{}
-			apiKey, err := resolver.Resolve()
-			if err != nil {
-				return err
-			}
-
-			ctx.client = client.New(apiKey,
-				client.WithBaseURL(provider.BaseURL()),
-				client.WithUserAgent("heygen-cli/"+version),
-			)
-
-			return nil
+			return initContext(cmd, version, ctx)
 		},
 	}
 
 	root.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
 		return clierrors.NewUsage(err.Error())
 	})
 
+	root.AddCommand(newAuthCmd(ctx))
 	registerGroups(root, ctx, groups)
 
 	return root

cmd/heygen/testutil_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"bytes"
 	"errors"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -60,18 +61,28 @@ func setupTestServer(t *testing.T, handlers map[string]testHandler) *httptest.Se
 // matches what production emits.
 func runCommand(t *testing.T, serverURL, apiKey string, args ...string) cmdResult {
 	t.Helper()
+	return runCommandWithInput(t, serverURL, apiKey, nil, args...)
+}
+
+func runCommandWithInput(t *testing.T, serverURL, apiKey string, stdin io.Reader, args ...string) cmdResult {
+	t.Helper()
 
 	var stdout, stderr bytes.Buffer
 	formatter := output.NewJSONFormatter(&stdout, &stderr)
 
 	// Set env vars for this test
-	t.Setenv("HEYGEN_API_KEY", apiKey)
+	if apiKey != "" {
+		t.Setenv("HEYGEN_API_KEY", apiKey)
+	}
 	t.Setenv("HEYGEN_API_BASE", serverURL)
 
 	cmd := newRootCmd("test", formatter)
 	cmd.SetOut(&stdout)
 	cmd.SetErr(&stderr)
 	cmd.SetArgs(args)
+	if stdin != nil {
+		cmd.SetIn(stdin)
+	}
 
 	err := cmd.Execute()
 

go.mod

@@ -10,6 +10,8 @@ require (
 	gopkg.in/yaml.v3 v3.0.1
 )
 
+require golang.org/x/term v0.30.0
+
 require (
 	github.com/go-openapi/jsonpointer v0.21.0 // indirect
 	github.com/go-openapi/swag v0.23.0 // indirect
@@ -22,4 +24,5 @@ require (
 	github.com/perimeterx/marshmallow v1.1.5 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
 	github.com/woodsbury/decimal128 v1.3.0 // indirect
+	golang.org/x/sys v0.31.0 // indirect
 )

go.sum

@@ -47,6 +47,10 @@ github.com/ugorji/go/codec v1.2.7/go.mod h1:WGN1fab3R1fzQlVQTkfxVtIBhWDRqOviHU95
 github.com/woodsbury/decimal128 v1.3.0 h1:8pffMNWIlC0O5vbyHWFZAt5yWvWcrHA+3ovIIjVWss0=
 github.com/woodsbury/decimal128 v1.3.0/go.mod h1:C5UTmyTjW3JftjUFzOVhC20BEQa2a4ZKOB5I6Zjb+ds=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
+golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/term v0.30.0 h1:PQ39fJZ+mfadBm0y5WlL4vlM7Sx1Hgf13sMIY2+QS9Y=
+golang.org/x/term v0.30.0/go.mod h1:NYYFdzHoI5wRh/h5tDMdMqCqPJZEuNqVR5xJLd/n67g=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=