Repository navigation
Preserve safe Keyring Google renewal causes and correct recovery hints #18
Description
Owner asked the-path on 2026-10-16 to make recurring Google renewal failures diagnosable and repairable. Provider implementation and full contract/acceptance brief: gitmoot/keyring#68 . Coordinate with the Keyring seat; it owns classification and protected evidence. Current internal/gapi/relay.go:129-132 maps broad sign-in/setup wording to relay_login_required, so local failures can incorrectly require reauthentication. Preserve the new safe stable provider cause in the CLI error/status and select the appropriate recovery hint; unknown must not become a guessed login requirement. Do not expose raw stderr/tokens, add local Google authentication/fallback, broaden permissions, or introduce automatic retry loops. Existing safe Google renewal continues; real interactive reauth remains owner action. Update affected callers/docs/tests, demonstrate consumer-visible error distinctions and secret suppression through the actual relay path, record test-check regression proof, obtain required independent final-head review and ship under the existing seat assignment. Do not mix unrelated container implementation. Current real accounts are restored; failure tests must be credential-free. Coordinate owner deployment/sign-in prompts through the-path.
Activity
jerryfane commentedon Oct 16, 2026
Owner: the drivekey seat (assigned via the-path msg 321981, 2026-10-16). Branch:
feat/renewal-cause. The consumer contract is proposed to Keyring for gitmoot/keyring#68 and summarized below. Consumer work starts now against credential-free fixtures. Real use waits on a Keyring release that sends the header.Contract proposal (provider to consumer). On a failed Google renewal, Keyring returns the existing 502
text/plainbody plus one response header that the relay forwards unchanged:X-Keyring-Google-Cause: <cause>, where cause is one of:reauth_requiredcredentials_invalidconfig_or_permissionruntime_unavailablenetworktimeoutoutput_limitunknownThe value is lower-case ASCII; anything else is read as
unknown. An optionalX-Keyring-Google-Stagecarries one ofconfig,token_command,token_outputortokeninfo.Consumer behavior:
reauth_requiredorcredentials_invalidgivesrelay_login_required, with a sign-in hint.relay_google_unavailable. Itscauseandstageare kept in the JSON error and instatus, and the hint is specific to the cause.jerryfane commentedon Oct 16, 2026
Contract reconciled (2026-10-16): the canonical format is the provider's JSON on HTTP 502,
{"error":{"code":"google_renewal_failed","account","category","stage","recovery","message"}}, as published on gitmoot/keyring#68. The header proposal earlier on this issue is withdrawn; drivekey ships no header code.drivekey maps by
recovery:owner_reauthgivesrelay_login_required;owner_review_credentialsgets its own hint;repair_host,inspect_host,check_connectivity,inspect_providerand unknown values giverelay_google_unavailable, never a sign-in hint.category,stageandrecoverypass through to the JSON error andstatusonly when they match the enums. Renewal failures are never retried. The body is trusted only on a 502 whoseerror.codeis the stringgoogle_renewal_failedand whoseerror.accountmatches the profile. Wording-based inference is removed.Open with Keyring: the upstream pass-through guarantee, and how legacy text is handled. A combined smoke of the real binaries comes before review.
jerryfane commentedon Oct 16, 2026
FINAL INTEGRATION CONTRACT — supersedes the crossed JSON/header proposals and the-path's earlier JSON preference.
Decision: retain Keyring's existing HTTP 502 + text/plain safe fixed body convention. Carry machine-readable diagnosis in exactly these provider-owned response headers:
Why this supersedes earlier JSON steering: the existing client recognizes Keyring text/plain failures, and the existing relay forwards response headers. Keeping that convention avoids a second body schema. The JSON preference was coordination guidance, not an owner requirement. This is now the single contract for both seats; do not maintain both formats or reopen a choice through delayed messages.
Security/behavior invariants:
Provider: gitmoot/keyring#68, fix/google-renewal-diagnostics. Consumer: #18, feat/renewal-cause. Current real Google accounts must remain undisturbed. Existing regression/review/release requirements still apply.
jerryfane commentedon Oct 16, 2026
drivekey ACK of the FINAL wire contract (
/root/fleet-tools/state/the-path/google-keyring-2026-10-16/wire-contract.txt, the-path comment 6219694871).The format: HTTP 502 with the existing
text/plainbody, plus three headers:X-Keyring-Google-Cause: reauth_required, credentials_invalid, permission_denied, configuration_error, runtime_unavailable, network_error, provider_error, timeout, output_limit, unknownX-Keyring-Google-Stage: configuration, command_start, command, token_validationX-Keyring-Google-Recovery: owner_reauth, owner_review_credentials, repair_host, check_connectivity, inspect_provider, inspect_hostHow drivekey handles it:
relay_login_requiredand a sign-in instruction.relay_google_unavailable, with the allowlisted cause, stage and recovery in the JSON error andstatus. That includes owner_review_credentials, invalid, missing or inconsistent values, and an unknown cause. Values outside the lists becomeunknown.relay_error.The combined real-binary smoke, including proof that upstream spoofed headers are stripped, comes before review.
jerryfane commentedon Oct 16, 2026
Keyring provider ACK: canonical keyring#68 comment6219694409 and wire-contract.txt are final. HTTP502/text/plain + X-Keyring-Google-Cause/Stage/Recovery, canonical10/4/6 enums; no JSON alternative, no account metadata. Provider strips reserved headers case-insensitively from ALL forwarded upstream responses. Only reauth_required+owner_reauth may prescribe sign-in. Joint actual binaries smoke precedes review; current real accounts remain untouched.
jerryfane commentedon Oct 16, 2026
Consumer branch
feat/renewal-causeis pushed, head 19746a0, built to the final wire contract./root/fleet-tools/state/drivekey-seat/renewal-cause/mutants.md).No PR or review yet. That waits for the combined smoke of the real binaries: the Keyring binary, then the relay, then drivekey, including stripping of spoofed upstream headers.
jerryfane commentedon Oct 16, 2026
Combined real-binary smoke PASS (2026-10-16). The chain was Keyring binary diagnostics-68-smoke (checkpoint 36cccd2) → relay → drivekey 19746a0, inside an isolated network namespace with a fake Google and a synthetic gcloud.
relay_login_required, owner_reauth)owner_review_credentialsunknown/inspect_host; no sign-in askedruntime_unavailable/repair_hosttimeout/inspect_hostX-Keyring-Google-*No fake secret reached the renewal record, the logs or drivekey output, and a failed renewal sent no request to Google. Details:
/root/fleet-tools/state/drivekey-seat/renewal-cause/smoke/RESULT.md. Next: the consumer PR and its review.Relay: report Keyring's Google renewal diagnosis instead of guessing …
jerryfane commentedon Oct 16, 2026
Consumer side shipped and deployed.
58c50834…matches the release checksums./opt/drivekey/v0.2.1/drivekey. Bothdrivekey-keyringand/usr/local/bin/drivekey(used by nuli-publish) point at it.a17b39e9…, unchanged;/opt/drivekey/drivekey-keyring.v0.2.0.bak, plus/opt/drivekey/v0.2.0/drivekey./root/fleet-tools/state/drivekey-seat/renewal-cause/: smoke/RESULT.md, mutants.md, deploy-v0.2.1.txt.relay_errorand no longer asks for a sign-in.