Add support for access tokens for isolated environments

To run tc-logview without gcloud auth available or permanent service
account key, one could issue OAuth2 access token with gcloud and
impersonate some limited service account

`TC_LOGVIEW_ACCESS_TOKEN` would be used if present

Author: lotas

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v1.3.0 - 2026-05-28
+
+### Added
+
+- Pre-issued OAuth2 access tokens via the `TC_LOGVIEW_ACCESS_TOKEN` env var. Intended for containers/agents that should run without access to the host's `gcloud` session or a long-lived service account key. The host mints a short-lived, SA-scoped token (e.g. `gcloud auth print-access-token --impersonate-service-account=<SA>`) and injects only the token; tc-logview itself does not impersonate or refresh.
+- Auth precedence is now `TC_LOGVIEW_ACCESS_TOKEN` > `key_path` > ADC; the active mode is logged under `-v` as `token`, `key_file`, or `ADC`. Client-create and query errors are tagged with the active mode for diagnosability.
+- Expired/invalid token errors append a one-line hint pointing at the re-mint command.
+
+### Changed
+
+- `config init` template's authentication comment block now documents all three modes and the priority order.
+- README Setup section gains Option C describing the host-mints-token / container-consumes-token flow.
+
 ## v1.2.0 - 2026-05-28
 
 ### Added

README.md

@@ -68,7 +68,7 @@ environments:
 
 ### 2. Authenticate to GCP
 
-Choose one of the two options below per environment. In the example config above, `fx-ci`, `community-tc`, and `staging` use service account keys (Option B); `dev` uses ADC (Option A).
+Choose one of the three options below. Options A and B are configured per environment in `config.yaml`; Option C is selected at runtime via the `TC_LOGVIEW_ACCESS_TOKEN` env var and overrides whatever the config says. In the example above, `fx-ci`, `community-tc`, and `staging` use service account keys (Option B); `dev` uses ADC (Option A).
 
 #### Option A — Application Default Credentials (recommended for local use)
 
@@ -86,6 +86,26 @@ Place your service account JSON key in `~/.config/tc-logview/keys/` and set `key
 
 This mode is what you want inside an untrusted/containerized environment where you do not want to share your personal `gcloud` session.
 
+#### Option C — Injected access token (recommended for containers / agents)
+
+For containers running untrusted code (agents, CI jobs, ephemeral sandboxes), prefer a pre-issued short-lived bearer token over a long-lived service account key. The host impersonates a low-privilege service account once and passes only the resulting access token into the container.
+
+```bash
+# On the host (requires roles/iam.serviceAccountTokenCreator on the SA):
+TOKEN=$(gcloud auth print-access-token \
+  --impersonate-service-account=tc-log-reader@<PROJECT>.iam.gserviceaccount.com)
+
+# Run tc-logview with the token in the container's env:
+docker run --rm \
+  -e TC_LOGVIEW_ACCESS_TOKEN="$TOKEN" \
+  -e TASKCLUSTER_ROOT_URL=https://firefox-ci-tc.services.mozilla.com \
+  tc-logview-image query --type worker-stopped --limit 5
+```
+
+When `TC_LOGVIEW_ACCESS_TOKEN` is set it takes priority over `key_path` and ADC. The container never sees the host's `gcloud` session, never calls the IAM Credentials API, and cannot mint or refresh tokens. Worst-case leakage is one access token, valid only for its TTL (~1h).
+
+Re-mint and re-inject the token before it expires for long-running containers. An expired token surfaces as a `401` from the query path with a hint pointing back at the re-mint command.
+
 ### 3. Sync references
 
 ```bash

cmd/config_init.go

@@ -5,8 +5,8 @@ import (
 	"os"
 	"path/filepath"
 
-	"github.com/taskcluster/tc-logview/internal/config"
 	"github.com/spf13/cobra"
+	"github.com/taskcluster/tc-logview/internal/config"
 )
 
 var forceInit bool
@@ -36,9 +36,12 @@ var configInitCmd = &cobra.Command{
 
 		example := `# tc-logview configuration
 #
-# Authentication:
+# Authentication (priority: TC_LOGVIEW_ACCESS_TOKEN > key_path > ADC):
+#   - Export ` + "`TC_LOGVIEW_ACCESS_TOKEN`" + ` to use a pre-issued OAuth2 bearer
+#     token (short-lived; ideal for containers/agents — host mints via
+#     ` + "`gcloud auth print-access-token --impersonate-service-account=<SA>`" + `).
 #   - Set ` + "`key_path`" + ` to use a service account JSON key
-#     (intended for untrusted/containerized environments).
+#     (long-lived; intended for environments that cannot refresh tokens).
 #   - Omit ` + "`key_path`" + ` to use Application Default Credentials
 #     (run ` + "`gcloud auth application-default login`" + ` once on your machine).
 #

cmd/query.go

@@ -157,10 +157,11 @@ func runQuery(cmd *cobra.Command, args []string) error {
 			if skipCluster {
 				projectID = env.CloudSQLProject()
 			}
-			logInfo("%s", authModeMessage(projectID, env.KeyPath))
-			client, err := gcp.NewClient(ctx, projectID, env.KeyPath)
+			auth := resolveAuth(env)
+			logInfo("%s", authModeMessage(projectID, auth))
+			client, err := gcp.NewClient(ctx, projectID, auth)
 			if err != nil {
-				if hint := adcHintIfMissing(err, env.KeyPath); hint != "" {
+				if hint := authHint(err, auth); hint != "" {
 					return fmt.Errorf("creating GCP client: %w\n%s", err, hint)
 				}
 				return fmt.Errorf("creating GCP client: %w", err)
@@ -170,7 +171,11 @@ func runQuery(cmd *cobra.Command, args []string) error {
 			logInfo("Querying GCP Cloud Logging...")
 			result, err := client.Query(ctx, filterStr, queryLimit+queryOffset)
 			if err != nil {
-				return fmt.Errorf("querying logs: %w", err)
+				wrapped := fmt.Errorf("querying logs (auth=%s): %w", gcp.AuthModeLabel(auth), err)
+				if hint := authHint(err, auth); hint != "" {
+					return fmt.Errorf("%w\n%s", wrapped, hint)
+				}
+				return wrapped
 			}
 
 			rawEntries = result.Entries
@@ -304,10 +309,11 @@ func runQuery(cmd *cobra.Command, args []string) error {
 	// Query GCP if not cached
 	if rawEntries == nil {
 		ctx := context.Background()
-		logInfo("%s", authModeMessage(env.ProjectID, env.KeyPath))
-		client, err := gcp.NewClient(ctx, env.ProjectID, env.KeyPath)
+		auth := resolveAuth(env)
+		logInfo("%s", authModeMessage(env.ProjectID, auth))
+		client, err := gcp.NewClient(ctx, env.ProjectID, auth)
 		if err != nil {
-			if hint := adcHintIfMissing(err, env.KeyPath); hint != "" {
+			if hint := authHint(err, auth); hint != "" {
 				return fmt.Errorf("creating GCP client: %w\n%s", err, hint)
 			}
 			return fmt.Errorf("creating GCP client: %w", err)
@@ -317,7 +323,11 @@ func runQuery(cmd *cobra.Command, args []string) error {
 		logInfo("Querying GCP Cloud Logging...")
 		result, err := client.Query(ctx, filterStr, queryLimit+queryOffset)
 		if err != nil {
-			return fmt.Errorf("querying logs: %w", err)
+			wrapped := fmt.Errorf("querying logs (auth=%s): %w", gcp.AuthModeLabel(auth), err)
+			if hint := authHint(err, auth); hint != "" {
+				return fmt.Errorf("%w\n%s", wrapped, hint)
+			}
+			return wrapped
 		}
 
 		rawEntries = result.Entries
@@ -374,7 +384,7 @@ func runQuery(cmd *cobra.Command, args []string) error {
 	}
 
 	// Add message field when --filter is used or there are just two columns (ts, service)
-	if (queryFilter != "" || len(types) == 0 ) && !slices.Contains(fieldNames, "message") {
+	if (queryFilter != "" || len(types) == 0) && !slices.Contains(fieldNames, "message") {
 		fieldNames = append(fieldNames, "message")
 	}
 

cmd/root.go

@@ -5,10 +5,18 @@ import (
 	"os"
 	"strings"
 
-	"github.com/taskcluster/tc-logview/internal/config"
 	"github.com/spf13/cobra"
+	"github.com/taskcluster/tc-logview/internal/config"
+	"github.com/taskcluster/tc-logview/internal/gcp"
 )
 
+// accessTokenEnv is the env var that injects a pre-issued OAuth2 bearer
+// token into tc-logview. Set by host orchestration (e.g. a wrapper script
+// running `gcloud auth print-access-token --impersonate-service-account=...`)
+// to give a container short-lived, SA-scoped credentials without mounting
+// the host's gcloud session.
+const accessTokenEnv = "TC_LOGVIEW_ACCESS_TOKEN"
+
 var (
 	envFlag string
 	verbose bool
@@ -54,33 +62,52 @@ func logInfo(format string, args ...any) {
 	}
 }
 
+// resolveAuth assembles the AuthConfig for the current invocation by combining
+// the env-var token (if present) with the per-env key_path from config.
+func resolveAuth(env *config.Environment) gcp.AuthConfig {
+	return gcp.AuthConfig{
+		KeyPath:     env.KeyPath,
+		AccessToken: os.Getenv(accessTokenEnv),
+	}
+}
+
 // authModeMessage returns a human-readable description of which auth mode
 // the gcp client will use for the given project. Intended for stderr
 // diagnostics under -v.
-func authModeMessage(projectID, keyPath string) string {
-	if keyPath == "" {
+func authModeMessage(projectID string, auth gcp.AuthConfig) string {
+	switch {
+	case auth.AccessToken != "":
+		return fmt.Sprintf(
+			"auth: using injected access token from %s (project=%s)",
+			accessTokenEnv, projectID,
+		)
+	case auth.KeyPath != "":
+		return fmt.Sprintf(
+			"auth: using service account key file (project=%s, path=%s)",
+			projectID, auth.KeyPath,
+		)
+	default:
 		return fmt.Sprintf(
 			"auth: no key_path configured, using application default credentials (project=%s)",
 			projectID,
 		)
 	}
-	return fmt.Sprintf(
-		"auth: using service account key file (project=%s, path=%s)",
-		projectID, keyPath,
-	)
 }
 
-// adcHintIfMissing returns a one-line hint when a GCP client-create error
-// indicates that Application Default Credentials are not configured AND
-// the user has no key_path set. Empty string in any other case.
-func adcHintIfMissing(err error, keyPath string) string {
-	if err == nil || keyPath != "" {
+// authHint returns a one-line, mode-specific hint when a GCP error suggests
+// a fixable auth misconfiguration. Empty string when no hint applies.
+func authHint(err error, auth gcp.AuthConfig) string {
+	if err == nil {
 		return ""
 	}
-	if !strings.Contains(err.Error(), "could not find default credentials") {
-		return ""
+	msg := err.Error()
+	switch {
+	case auth.AccessToken != "" && (strings.Contains(msg, "invalid") || strings.Contains(msg, "expired") || strings.Contains(msg, "401")):
+		return fmt.Sprintf("hint: %s may be expired (~1h TTL).\n      Re-mint: gcloud auth print-access-token --impersonate-service-account=<SA>", accessTokenEnv)
+	case auth.AccessToken == "" && auth.KeyPath == "" && strings.Contains(msg, "could not find default credentials"):
+		return "hint: run `gcloud auth application-default login`, or set `key_path` in ~/.config/tc-logview/config.yaml"
 	}
-	return "hint: run `gcloud auth application-default login`, or set `key_path` in ~/.config/tc-logview/config.yaml"
+	return ""
 }
 
 func Execute() error {

cmd/root_test.go

@@ -4,69 +4,110 @@ import (
 	"errors"
 	"strings"
 	"testing"
+
+	"github.com/taskcluster/tc-logview/internal/gcp"
 )
 
 func TestAuthModeMessage(t *testing.T) {
 	tests := []struct {
 		name      string
 		projectID string
-		keyPath   string
+		auth      gcp.AuthConfig
 		contains  []string
 	}{
 		{
-			name:      "empty key_path mentions ADC and project",
+			name:      "empty auth mentions ADC and project",
 			projectID: "moz-fx-foo",
-			keyPath:   "",
+			auth:      gcp.AuthConfig{},
 			contains:  []string{"no key_path", "application default credentials", "moz-fx-foo"},
 		},
 		{
 			name:      "set key_path mentions key file and path",
 			projectID: "moz-fx-bar",
-			keyPath:   "/etc/keys/x.json",
+			auth:      gcp.AuthConfig{KeyPath: "/etc/keys/x.json"},
 			contains:  []string{"service account key file", "moz-fx-bar", "/etc/keys/x.json"},
 		},
+		{
+			name:      "access token mentions injected token and env var name",
+			projectID: "moz-fx-baz",
+			auth:      gcp.AuthConfig{AccessToken: "ya29.fake"},
+			contains:  []string{"injected access token", accessTokenEnv, "moz-fx-baz"},
+		},
+		{
+			name:      "token wins over key_path",
+			projectID: "moz-fx-qux",
+			auth:      gcp.AuthConfig{KeyPath: "/etc/keys/x.json", AccessToken: "ya29.fake"},
+			contains:  []string{"injected access token", "moz-fx-qux"},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := authModeMessage(tt.projectID, tt.keyPath)
+			got := authModeMessage(tt.projectID, tt.auth)
 			for _, sub := range tt.contains {
 				if !strings.Contains(got, sub) {
-					t.Errorf("authModeMessage(%q,%q) = %q; missing %q",
-						tt.projectID, tt.keyPath, got, sub)
+					t.Errorf("authModeMessage(%q,%+v) = %q; missing %q",
+						tt.projectID, tt.auth, got, sub)
 				}
 			}
 		})
 	}
 }
 
-func TestAdcHintIfMissing(t *testing.T) {
-	hint := "gcloud auth application-default login"
+func TestAuthHint(t *testing.T) {
+	adcHintFragment := "gcloud auth application-default login"
+	tokenHintFragment := "may be expired"
 
-	t.Run("ADC mode + matching error -> hint", func(t *testing.T) {
+	t.Run("ADC mode + missing-creds error -> ADC hint", func(t *testing.T) {
 		err := errors.New("google: could not find default credentials. See ...")
-		got := adcHintIfMissing(err, "")
-		if !strings.Contains(got, hint) {
-			t.Errorf("expected hint containing %q, got %q", hint, got)
+		got := authHint(err, gcp.AuthConfig{})
+		if !strings.Contains(got, adcHintFragment) {
+			t.Errorf("expected ADC hint containing %q, got %q", adcHintFragment, got)
 		}
 	})
 
 	t.Run("ADC mode + unrelated error -> empty", func(t *testing.T) {
 		err := errors.New("some other failure")
-		if got := adcHintIfMissing(err, ""); got != "" {
+		if got := authHint(err, gcp.AuthConfig{}); got != "" {
 			t.Errorf("expected empty hint, got %q", got)
 		}
 	})
 
-	t.Run("key_file mode + matching error -> empty (not user's problem)", func(t *testing.T) {
+	t.Run("key_file mode + missing-creds error -> empty (not user's problem)", func(t *testing.T) {
 		err := errors.New("google: could not find default credentials")
-		if got := adcHintIfMissing(err, "/etc/keys/x.json"); got != "" {
+		if got := authHint(err, gcp.AuthConfig{KeyPath: "/etc/keys/x.json"}); got != "" {
 			t.Errorf("expected empty hint when key_path is set, got %q", got)
 		}
 	})
 
 	t.Run("nil error -> empty", func(t *testing.T) {
-		if got := adcHintIfMissing(nil, ""); got != "" {
+		if got := authHint(nil, gcp.AuthConfig{}); got != "" {
 			t.Errorf("expected empty hint for nil error, got %q", got)
 		}
 	})
+
+	t.Run("token mode + 401 -> token re-mint hint", func(t *testing.T) {
+		err := errors.New("rpc error: code = Unauthenticated desc = Request had invalid authentication credentials. Status 401")
+		got := authHint(err, gcp.AuthConfig{AccessToken: "ya29.fake"})
+		if !strings.Contains(got, tokenHintFragment) {
+			t.Errorf("expected token hint containing %q, got %q", tokenHintFragment, got)
+		}
+		if !strings.Contains(got, accessTokenEnv) {
+			t.Errorf("expected token hint to mention %q, got %q", accessTokenEnv, got)
+		}
+	})
+
+	t.Run("token mode + expired wording -> token hint", func(t *testing.T) {
+		err := errors.New("oauth2: token expired and refresh token is not set")
+		got := authHint(err, gcp.AuthConfig{AccessToken: "ya29.fake"})
+		if !strings.Contains(got, tokenHintFragment) {
+			t.Errorf("expected token hint containing %q, got %q", tokenHintFragment, got)
+		}
+	})
+
+	t.Run("token mode + unrelated error -> empty", func(t *testing.T) {
+		err := errors.New("network unreachable")
+		if got := authHint(err, gcp.AuthConfig{AccessToken: "ya29.fake"}); got != "" {
+			t.Errorf("expected empty hint for unrelated error, got %q", got)
+		}
+	})
 }

cmd/version.go

@@ -9,7 +9,7 @@ import (
 )
 
 // version is bumped manually with each release. Keep in sync with CHANGELOG.md.
-const version = "v1.2.0"
+const version = "v1.3.0"
 
 var versionCmd = &cobra.Command{
 	Use:   "version",

go.mod

@@ -6,7 +6,10 @@ require (
 	cloud.google.com/go/logging v1.13.2
 	github.com/spf13/cobra v1.10.2
 	github.com/tidwall/gjson v1.18.0
+	golang.org/x/oauth2 v0.35.0
 	google.golang.org/api v0.269.0
+	google.golang.org/genproto/googleapis/api v0.0.0-20260128011058-8636f8732409
+	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -36,14 +39,11 @@ require (
 	go.opentelemetry.io/otel/trace v1.39.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
 	golang.org/x/net v0.50.0 // indirect
-	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/text v0.34.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/genproto v0.0.0-20260128011058-8636f8732409 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20260128011058-8636f8732409 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260217215200-42d3e9bedb6d // indirect
 	google.golang.org/grpc v1.79.1 // indirect
-	google.golang.org/protobuf v1.36.11 // indirect
 )