feat(auth): read the token from a file descriptor and print grant error codes - #479

Tracking

• Stacked on feat(databases): apply migrations through migration runs under a grant #478 (K3), feat(functions): invoke with a delegated grant, not a service key #477 (K2), feat(auth): treat pg- delegated grants as project-bound #476 (K1)
• Related: Kong/volcano-builder#523 (Builder-side asks), Kong/volcano-builder#518
• Related: Kong/volcano-hosting#3311, Kong/volcano-hosting#3312, Kong/volcano-hosting#3313

Why

• The CLI parses the code in Hosting's error bodies but never prints it, so a Builder worker has to match message text to tell grant_budget_exhausted, grant_reserved_variable, grant_permission_missing, grant_route_not_allowed, rate_limit_exceeded and delegated_grant_required apart.
• R11: any process the model left running in the VM can read the CLI's environment, so a grant in VOLCANO_TOKEN is exposed while the CLI runs, and every process the CLI starts inherits it.

Summary

• error codes, grant only: when the command ran with a delegated grant and the API error has a code, the CLI prints one more line after the error, Error code: <code>. Nothing else is reworded, and every other credential sees errors exactly as before. I chose this over appending (<code>) to every error, which would change the text for all users
• add VOLCANO_TOKEN_FD=<n> (internal/config/token_source.go). At startup, before anything reads the configuration, main reads the token from that descriptor up to the first newline (16 KiB cap), so a writer that keeps its end open does not hold the CLI up, and unsets the variable. A descriptor of 3 or more is opened and closed after the read. 0 reads stdin through os.Stdin and leaves it open, so the number can't pass to the next file the CLI opens; 1 and 2 are refused. This one option also covers "token on stdin". I chose it over --token-stdin because the CLI takes its credential from env vars, and several commands already read stdin for their own input
• a grant in VOLCANO_TOKEN is moved into memory and removed from the CLI's environment at startup, so processes the CLI starts (the telemetry flush, git, docker, the updater) don't inherit it. Other tokens stay in VOLCANO_TOKEN, because the telemetry flush reads an account token from there
• refused at startup with exit 2, without echoing what was read: setting both VOLCANO_TOKEN_FD and VOLCANO_TOKEN, a bad descriptor number, or an empty or oversized read
• local mode ignores the adopted token, as it ignores VOLCANO_TOKEN
• limit, for the worker: on Linux, unsetting a variable does not change /proc/<pid>/environ, which still shows the CLI's starting environment to same-user processes. Only VOLCANO_TOKEN_FD keeps the grant out of the CLI's environment entirely, so the worker should use it
• a run on a token taken into memory (any token from VOLCANO_TOKEN_FD, or a grant from VOLCANO_TOKEN) sends no telemetry event. The flush process can't see that token, and would otherwise send the saved login's token with the event
• docs: docs/authentication.md describes VOLCANO_TOKEN_FD and the code line
• changed in review: an earlier version of this PR appended the code to every API error for every credential. It now prints the code line under a grant only

Verification

• go build ./...
• make check (openapi-generated-check, release-workflow-check, lint with 0 issues, test)
• TestGrantErrorPrintsTheAPICode (the code line follows the unchanged error under a grant) and TestNonGrantErrorPrintsNoCodeLine
• TestAdoptTokenReadsTheDescriptorAndClosesIt, TestAdoptTokenTakesAGrantOutOfTheEnvironment (both run env as a child process and check the token is absent), TestAdoptTokenLeavesOtherTokensInTheEnvironment, TestAdoptTokenRefusals (including descriptors 1 and 2)
• TestAdoptTokenStopsAtTheFirstNewline (the writer stays open after pg-…\n; fails on a 5 s timeout) and TestAdoptTokenReadsStdinAndLeavesItOpen (stdin still reads what follows the token's line)
• TestRecord_AdoptedTokenSendsNothing and the adopted-grant case of TestConnectRefusesALoginThatVolcanoTokenWouldOverride
• built the binary with VOLCANO_API_URL on a closed port: VOLCANO_TOKEN_FD=2 prints the refusal (exit 2), and 3< <(echo pg-x; sleep 5) returns at once
• the descriptor tests live in _unix_test.go files and pass a dup'd descriptor that no *os.File owns. Passing a pipe's own Fd() made two owners of one descriptor, and the second close hit an HTTP socket that reused the number (seen once in make check). Ran go test -count=5 ./internal/config ./cmd/volcano after the fix, and GOOS=windows go vet on both packages
• TestGrantFromATokenDescriptor runs cloud functions list through the real command tree with the grant on a pipe and VOLCANO_TOKEN unset, and checks the request carried it
• built the binary and ran VOLCANO_TOKEN_FD=3 volcano cloud functions list 3<<<"pg-…" (a fake grant), with VOLCANO_TOKEN unset, against a local recording server: exit 0, and the request carried Bearer pg-…

Decisions for Ted

• the code is printed as its own line (Error code: <code>), not inside the error line, so no existing text changes. If the worker would rather parse Error (<code>): …, that is a one-line change