feat: pivot xai-proxy → openab-auth-proxy (generic OAuth sidecar)

[chaodu-agent]

Summary

Pivots the xAI-specific xai-proxy sidecar into openab-auth-proxy — a generic OAuth proxy that works with any OIDC provider. Also recommends OpenCode's native xAI OAuth as the primary approach for OpenCode deployments.

Motivation

• OpenCode ≥1.15.0 now has built-in xAI OAuth (browser + device-code), making the sidecar unnecessary for OpenCode
• The proxy pattern is still valuable for non-OpenCode agents and corporate OIDC gateways
• Generalizing it makes it reusable across providers

Changes

Code

• Rename xai-proxy/ → openab-auth-proxy/
• Config-driven — provider settings loaded from TOML; defaults to xAI preset
• New env var AUTH_PROXY_TOKEN_PATH (legacy XAI_PROXY_TOKEN_PATH still works)
• Token path → ~/.openab-auth-proxy/<provider>/tokens.json
• CI — ci-xai-proxy.yml → ci-auth-proxy.yml

Docs

• docs/refarch/sidecar-proxy.md — reference architecture for the generic OAuth sidecar pattern
• docs/xai-proxy.md — rewritten to recommend native OAuth; links to refarch for sidecar approach

Example: custom provider config

[provider]
name = "my-corp-llm"
discovery_url = "https://auth.corp.com/.well-known/openid-configuration"
client_id = "my-client-id"
scopes = "openid offline_access api:access"
upstream_base_url = "https://llm.corp.com"

Breaking changes

• Binary: xai-proxy → openab-auth-proxy
• Default token path changed (legacy env var still supported)
• Cargo.lock removed (CI regenerates)

Closes

Supersedes #884

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: feat: pivot xai-proxy → openab-auth-proxy (generic OAuth sidecar)
• Source: feat: pivot xai-proxy → openab-auth-proxy (generic OAuth sidecar) #891
• Status: moved to PR-Screening
• Generated at: 2026-05-22T00:03:10.955Z
• Discord thread: not available

Screening report

done.

GitHub comment: #891 (comment)
Project action: moved PVTI_lADOEFbZWM4BUUALzgtdYQA from Incoming to PR-Screening in https://github.com/orgs/openabdev/projects/1

Intent

PR #891 pivots the xAI-specific xai-proxy sidecar into openab-auth-proxy, a provider-configurable OAuth/OIDC sidecar. The operator-visible problem is that OpenCode now has native xAI OAuth, so the old xAI-only proxy is too narrow, but the sidecar pattern is still useful for non-OpenCode agents and corporate OIDC gateways.

Feat

Feature work with docs and CI cleanup. It renames the proxy package and CI workflow, adds TOML-driven provider configuration, preserves a legacy token-path env var, moves default token storage under ~/.openab-auth-proxy/<provider>/tokens.json, and rewrites the xAI docs to prefer native OpenCode OAuth while keeping a generic sidecar reference architecture.

Who It Serves

Primary beneficiaries are deployers and agent runtime operators who need OAuth in environments where the agent cannot or should not own the provider-specific auth flow. Maintainers also benefit if this removes the need to carry xAI-only proxy logic as a special case.

Rewritten Prompt

Rename xai-proxy to openab-auth-proxy and generalize it into a small OAuth/OIDC sidecar. Load provider settings from TOML, with an xAI preset for backward compatibility. Support AUTH_PROXY_TOKEN_PATH while continuing to honor XAI_PROXY_TOKEN_PATH as a legacy alias. Store default tokens at ~/.openab-auth-proxy/<provider>/tokens.json. Update Docker, CI, README, and docs so OpenCode deployments prefer native xAI OAuth, while non-OpenCode or corporate OIDC deployments use the generic sidecar path. Include migration notes, focused tests for config/env precedence and token-path behavior, and keep lockfile handling consistent with the repo's Rust policy.

Merge Pitch

This should move forward if the proxy remains useful outside OpenCode. The direction is sound: generic OIDC sidecar beats keeping an xAI-specific artifact after OpenCode gained native xAI OAuth. Risk is moderate because it includes a binary rename, default token-path change, lockfile deletion, and provider generalization in one PR. The likely reviewer concern is compatibility: existing xAI proxy users need clear migration behavior, and CI must prove the renamed crate builds reproducibly.

Best-Practice Comparison

OpenClaw's scheduling and durable execution model does not directly apply; this PR is auth sidecar infrastructure, not job dispatch. The relevant OpenClaw comparison is explicit delivery/routing boundaries: the sidecar should keep auth/token ownership clear and make upstream routing explicit per provider.

Hermes Agent's daemon tick model and scheduled prompt persistence do not apply. The relevant Hermes lesson is self-contained execution state: token storage, config, and runtime logs should be deterministic enough for operators to debug refresh and upstream failures without reading agent internals.

Implementation Options

Conservative: keep xai-proxy compatibility as the primary surface, add openab-auth-proxy as an alias, and only document the generic provider config. This lowers breakage but prolongs duplicate naming.

Balanced: accept the rename to openab-auth-proxy, keep legacy env compatibility, add explicit migration docs, restore or justify lockfile policy, and add focused tests for provider config, token path resolution, and xAI preset behavior. This is the best near-term merge shape.

Ambitious: split generic auth proxy into a reusable sidecar framework with provider presets, health/debug endpoints, structured run logs, token refresh metrics, and Helm/chart integration. This is valuable later but too broad for this PR unless the current proxy is already production-critical.

Comparison Table

Option	Speed	Complexity	Reliability	Maintainability	User Impact	Fit for OpenAB now
Conservative	Fast	Low	Medium	Medium-low	Lowest migration friction	Good if compatibility risk dominates
Balanced	Medium	Medium	High	High	Clear migration with useful generalization	Best fit
Ambitious	Slow	High	Potentially high	Medium until stabilized	Highest long-term operator value	Better as follow-up

Recommendation

Take the balanced path. Advance this to PR-Screening for Masami/Pahud follow-up, with review focused on migration safety, lockfile policy, CI coverage after the rename, and whether token/config errors are observable enough for operators. Split richer sidecar operations work into follow-up PRs after the generic rename lands cleanly.