feat(providers): expose actionable OAuth refresh failures

[mrunalp]

Summary

Expose structured, provider-neutral recovery guidance for OAuth refresh failures so consumers can distinguish transient retries, operator configuration problems, and user reauthorization without parsing provider error text. Preserve safe diagnostics, stop rapid retries for terminal grants, and keep the existing credential-driver storage boundary unchanged.

Related Issue

Closes #2886

Changes

• Parse bounded OAuth error responses and persist stable recovery actions, failure codes, safe provider subtypes, and failure timestamps.
• Park refresh grants that require user reauthorization, retry configuration failures hourly, and retain short retries for transient failures and rotated-token persistence recovery.
• Surface actionable refresh status through the CLI and curated Go SDK, including correct handling of the parked-refresh next-time sentinel.
• Add unit coverage for classification, persistence, cleared success state, scheduling, response bounds, provider gates, and post-mint failures.
• Add a rootless Podman + Keycloak E2E lane that uses the default database credential store and verifies refresh, revocation, and reauthorization status.
• Document the recovery contract in provider docs, gateway architecture, protobuf comments, and the OpenShell CLI skill.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)
• cargo test -p openshell-server --lib (1,430 passed, 8 ignored)
• mise run go:ci
• mise run e2e:provider-refresh-keycloak

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[johntmyers]

gator-agent

PR Review Status

This PR is project-valid through accepted issue #2886. The initial review found one blocking OAuth error-classification defect; the provider docs and CLI skill updates otherwise cover the direct UX contract.

Action required: @mrunalp, preserve recognized top-level OAuth classifications when an optional subtype has an unexpected JSON type, and add the malformed-subtype regression case.

Blocking findings:

• GATOR-88e83828-01: a non-string optional subtype discards a recognized invalid_grant classification

Carried findings:

• None

Non-blocking suggestions:

• None

Gator metadata

• Validation: Implements accepted issue #2886 across the existing provider-refresh boundary
• Docs: Fern provider docs, gateway architecture, protobuf comments, and CLI skill updated
• Checks: DCO and vouch are green; required branch and E2E workflows are not dispatched for this head yet
• E2E: test:e2e required for provider credential flow; dispatch deferred until blocking review feedback is resolved
• Head SHA: 88e8382897a857893f1a9dbba824e3a486819960
• Base SHA: 2f7fb65591ee5746217ace154afc0aa6bf1afc6d
• Merge base SHA: 2f7fb65591ee5746217ace154afc0aa6bf1afc6d
• Patch ID: 9f514aa29504caf111a75d371d6c06023ccbea9d
• Gator payload: 6
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[github-actions]

Label test:e2e applied, but pull-request/2887 does not exist yet. A maintainer needs to comment /ok to test ad9591ef2f78c121db2e950dd1f6fbc65077568e to mirror this PR. Once the mirror exists, re-apply the label or re-run Branch E2E Checks from the Actions tab.

[mrunalp]

/ok to test ad9591e

[johntmyers]

/ok to test ad9591e

[johntmyers]

gator-agent

PR Review Status

Thanks @mrunalp. I checked your fix for the malformed OAuth subtype case: the top-level invalid_grant classification now survives an object-valued optional subtype, and the exact regression case verifies reauthorize with a parked retry schedule. The prior finding is resolved, and the bounded follow-up review found no new blocking issues.

Blocking findings:

• No blocking findings remain

Carried findings:

• None; GATOR-88e83828-01 is resolved

Gator metadata

• Validation: Implements accepted issue #2886 across the existing provider-refresh boundary
• Docs: Fern provider docs, gateway architecture, protobuf comments, and CLI skill are updated
• Checks: Current-head Branch Checks and Helm Lint are running
• E2E: test:e2e is applied; /ok to test ad9591ef2f78c121db2e950dd1f6fbc65077568e created the current mirror and Branch E2E Checks run 32764400518 is running
• Head SHA: ad9591ef2f78c121db2e950dd1f6fbc65077568e
• Base SHA: 905e99aa2a960c17d5672b11cf64f10ff7d18b41
• Merge base SHA: 905e99aa2a960c17d5672b11cf64f10ff7d18b41
• Patch ID: df8405233cd23b57f75f0729f664d0b43b0dda81
• Gator payload: 7
• Review mode: follow_up
• Previous reviewed SHA: 88e8382897a857893f1a9dbba824e3a486819960
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[github-actions]

Label test:e2e applied for ad9591e. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.