Add opt-in ADC reauth preflight (--reauth=off|auto)

README.md

@@ -84,6 +84,10 @@ Flags:
       --enable-partitioned-dml     Execute DML statement using Partitioned DML
       --timeout=10m                Maximum time to wait for the SQL query to
                                    complete
+      --reauth="off"               When auto, run gcloud application-default
+                                   login once if local user ADC needs
+                                   reauthentication; off only prints a hint
+                                   ($EXECSPANSQL_REAUTH).
       --try-partition-query        (Experimental) Check whether the query can be
                                    executed as partition query or not
 
@@ -398,6 +402,32 @@ Note: `--log-grpc=payload` can log request and response payloads (including boun
 
 Use `--priority=high`, `--priority=medium`, `--priority=low`, or `--priority=unspecified` to set the Spanner execute-SQL request priority. Omitting the flag keeps the unspecified priority. The setting applies to JSON/YAML output (including eager and lazy jq input), CSV, ordinary DML, and Partitioned DML; it does not change read-write transaction commit priority.
 
+### Reauthentication
+
+Google Workspace session policies can invalidate a user Application Default Credentials refresh token (`invalid_grant` with `error_subtype` `invalid_rapt` or `rapt_required`). execspansql never replays SQL after a Spanner RPC has started.
+
+`--reauth=off` (default, also `EXECSPANSQL_REAUTH`) leaves client construction unchanged. If a classified reauth error or a gRPC `Unauthenticated` message containing `invalid_rapt` / `rapt_required` is reported, the process exits non-zero with:
+
+```
+Reauthentication is needed. Please run 'gcloud auth application-default login' to reauthenticate.
+```
+
+`--reauth=auto` is explicit consent for one interactive `gcloud auth application-default login` **before** the Spanner client is created. `auto` means continue as whoever completes that login; the principal is not compared with the previous ADC identity. The login budget is exactly one attempt per process. After a successful login the well-known ADC file is re-read, must still be `authorized_user`, and a token is fetched again. A quota project change is reported on stderr and does not fail the command.
+
+Automatic login runs only when all of the following hold:
+
+* `SPANNER_EMULATOR_HOST` is unset (the emulator does not use these credentials)
+* `GOOGLE_APPLICATION_CREDENTIALS` is unset (gcloud writes the well-known file, not that path)
+* `CLOUDSDK_CONFIG` is unset (gcloud honors it; the Go auth library does not, so the login result would not be picked up)
+* the well-known ADC file exists, is writable, and has `"type": "authorized_user"`
+* stdin and stderr are terminals (stdout may be a pipe)
+* `gcloud` is on `PATH`
+* no test/emulator client options that bypass ADC were injected
+
+`--timeout` applies only to query execution, not to the login. A reauth failure during a long-running statement (after the preflight) is reported with the hint rather than retried. DML is never replayed.
+
+The Go client always reads `$HOME/.config/gcloud/application_default_credentials.json` (`%APPDATA%\gcloud\...` on Windows). If `CLOUDSDK_CONFIG` is set, automatic login is skipped and the hint names that variable.
+
 ### (Experimental) `--try-partition-query`
 
 Check whether the query can be executed as partition query or not.

go.mod

@@ -3,6 +3,7 @@ module github.com/apstndb/execspansql
 go 1.25.0
 
 require (
+	cloud.google.com/go/auth v0.20.0
 	cloud.google.com/go/spanner v1.90.0
 	github.com/alecthomas/kong v1.15.0
 	github.com/apstndb/gsqlutils v0.0.0-20260502161854-d7d6011a36e0
@@ -21,6 +22,8 @@ require (
 	go.opentelemetry.io/otel v1.44.0
 	go.opentelemetry.io/otel/sdk v1.44.0
 	go.uber.org/zap v1.27.0
+	golang.org/x/oauth2 v0.36.0
+	golang.org/x/term v0.43.0
 	google.golang.org/api v0.280.0
 	google.golang.org/grpc v1.81.1
 	google.golang.org/protobuf v1.36.11
@@ -29,7 +32,6 @@ require (
 require (
 	cel.dev/expr v0.25.1 // indirect
 	cloud.google.com/go v0.123.0 // indirect
-	cloud.google.com/go/auth v0.20.0 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	cloud.google.com/go/iam v1.11.0 // indirect
@@ -133,7 +135,6 @@ require (
 	golang.org/x/crypto v0.51.0 // indirect
 	golang.org/x/image v0.43.0 // indirect
 	golang.org/x/net v0.55.0 // indirect
-	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.21.0 // indirect
 	golang.org/x/sys v0.45.0 // indirect
 	golang.org/x/text v0.38.0 // indirect

main.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"os/signal"
 
 	"encoding/json"
 
@@ -76,6 +77,7 @@ type opts struct {
 	TraceOTLPEndpoint    string        `name:"experimental-trace-otlp-endpoint" default:"localhost:4317" help:"OTLP/gRPC endpoint used with --experimental-trace-otlp."`
 	EnablePartitionedDML bool          `name:"enable-partitioned-dml" help:"Execute DML statement using Partitioned DML"`
 	Timeout              time.Duration `name:"timeout" default:"10m" help:"Maximum time to wait for the SQL query to complete"`
+	Reauth               string        `name:"reauth" enum:"off,auto" default:"off" env:"EXECSPANSQL_REAUTH" help:"When auto, run gcloud application-default login once if local user ADC needs reauthentication; off only prints a hint."`
 	TryPartitionQuery    bool          `name:"try-partition-query" help:"(Experimental) Check whether the query can be executed as partition query or not"`
 	TimestampBound       struct {
 		Strong        bool   `name:"strong" xor:"timestamp" help:"Perform a strong query."`
@@ -413,14 +415,24 @@ func _main() error {
 }
 
 // runCLI accepts client options so transport tests can inspect outgoing RPCs.
-func runCLI(clientOptions ...option.ClientOption) error {
+// Non-empty clientOptions skip the ADC reauth preflight (tests inject insecure
+// dial options that bypass application-default credentials).
+func runCLI(clientOptions ...option.ClientOption) (err error) {
 	o, err := processFlags()
 	if err != nil {
 		os.Exit(1)
 	}
+	defer func() { err = wrapWithHint(err) }()
 
-	ctx, cancel := context.WithTimeout(context.Background(), o.Timeout)
-	defer cancel()
+	// The first interrupt cancels ctx so an in-progress gcloud login or query
+	// unwinds cleanly; stop() then restores default signal handling so a
+	// second interrupt still terminates the process if shutdown hangs.
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer stop()
+	go func() {
+		<-ctx.Done()
+		stop()
+	}()
 
 	jqMode, err := jqresult.ParseInputMode(o.JqInputMode)
 	if err != nil {
@@ -469,12 +481,34 @@ func runCLI(clientOptions ...option.ClientOption) error {
 		return err
 	}
 
+	// Freeze the statement (SQL and parameters) before any interactive step so
+	// a parameter file edited during a browser login cannot change what runs.
+	paramStrMap, err := o.mergedParams()
+	if err != nil {
+		return err
+	}
+	paramMap, err := params.GenerateParams(paramStrMap, mode == sppb.ExecuteSqlRequest_PLAN)
+	if err != nil {
+		return err
+	}
+	stmt := spanner.Statement{SQL: query, Params: paramMap}
+
 	sinks, err := newOutputSinks(o)
 	if err != nil {
 		return err
 	}
 	defer sinks.Abort()
 
+	authOpts, err := maybeAuthPreflight(ctx, o, clientOptions, newReauthHooks())
+	if err != nil {
+		return err
+	}
+
+	// Query execution timeout starts after authentication. Login is
+	// human-paced and must not consume --timeout.
+	ctx, cancel := context.WithTimeout(ctx, o.Timeout)
+	defer cancel()
+
 	ctx, tp, err := enableTracing(ctx, o)
 	if err != nil {
 		return err
@@ -487,23 +521,12 @@ func runCLI(clientOptions ...option.ClientOption) error {
 		}()
 	}
 
-	client, err := newClient(ctx, o.Project, o.Instance, o.Database, o.DatabaseRole, string(o.LogGrpc), tracingEnabled(o), clientOptions...)
+	client, err := newClient(ctx, o.Project, o.Instance, o.Database, o.DatabaseRole, string(o.LogGrpc), tracingEnabled(o), append(clientOptions, authOpts...)...)
 	if err != nil {
 		return err
 	}
 	defer client.Close()
 
-	paramStrMap, err := o.mergedParams()
-	if err != nil {
-		return err
-	}
-	paramMap, err := params.GenerateParams(paramStrMap, mode == sppb.ExecuteSqlRequest_PLAN)
-	if err != nil {
-		return err
-	}
-
-	stmt := spanner.Statement{SQL: query, Params: paramMap}
-
 	if o.TryPartitionQuery {
 		bt, err := client.BatchReadOnlyTransaction(ctx, tb)
 		if err != nil {