Introduce curated Provider presets and managed authentication #71

Objective

Introduce a small, CodexHub-maintained catalog of Provider presets so users can select a known Provider, enter an API key, run discovery/probing, and complete configuration in one guided flow. Add Provider-scoped OAuth later for subscription-backed services such as xAI, after CodexHub has a secure credential abstraction.

This is a tracking issue. The implementation must be split into the child workstreams listed below rather than delivered as one change.

Product direction

• Maintain approximately 6–10 tested Provider presets instead of mirroring OpenCode's full catalog.
• Keep Official OpenAI / ChatGPT subscription as its existing first-class source; do not turn it into a normal API-key preset.
• Preserve the existing fully custom Provider path.
• A preset supplies reviewed defaults and onboarding metadata, never credentials.
• Users may customize an instantiated Provider without later preset updates silently overwriting their URL, protocol, enabled models, or ordering.
• Start with API-key onboarding. Add OAuth only per Provider and only after its client registration, scopes, subscription terms, and token lifecycle are verified.

Scope assessment

Overall scope is XL, but it contains two independently deliverable phases:

Phase 1: Curated presets and API-key onboarding — M

1. Add a versioned, localizable CodexHub preset manifest containing:
   • stable preset ID and display name;
   • base URL and supported upstream formats;
   • tool protocol and conservative capability overrides;
   • supported authentication methods and environment-variable names;
   • documentation URL and model metadata source;
   • tested version/date and upstream provenance.
2. Convert the currently bundled Provider definitions into presets.
3. Select a small initial catalog from Providers that can be exercised by the existing Gateway and automated probes. Candidates include Ollama Cloud, Volcengine, MiniMax, Xunfei, DeepSeek, OpenRouter, Anthropic, and xAI API key; the maintainer must approve the final 6–10.
4. Change “Add Provider” to offer:
   • curated presets;
   • search/filter;
   • a custom Provider option.
5. Guided API-key flow:
   • prefill reviewed endpoint/protocol defaults;
   • accept an API key or environment-variable reference;
   • run model discovery and protocol probe;
   • preview discovered models and compatibility warnings;
   • atomically save, regenerate the catalog, and sync enabled clients;
   • handle existing IDs with update / save-as-new / cancel instead of overwrite.

Phase 2: Secure credentials and Provider-scoped OAuth — L

1. Replace secret-bearing Provider fields with an auth_kind plus opaque credential_ref.
2. Store API keys, access tokens, and refresh tokens in an OS credential vault; the frontend receives only masked status.
3. Provide migration and rollback for existing plaintext keys or environment references.
4. Add a Provider auth-driver contract supporting:
   • API key;
   • authorization-code + PKCE/state/nonce;
   • loopback callback;
   • RFC 8628 device-code flow;
   • token expiry, single-flight refresh, and rotating refresh tokens;
   • logout/revoke/re-auth;
   • request-time backend-only credential injection.
5. Use xAI as the first OAuth pilot only after xAI approves or documents a CodexHub client ID, redirect URI, scopes, and subscription API entitlement.

OpenCode reuse decision

Use OpenCode as a design and source reference, but do not import its Provider runtime as a Git submodule, npm dependency, or second runtime:

• OpenCode Provider behavior is composed from Models.dev data, its internal Bun/Effect runtime, AI SDK adapters, and built-in auth plugins; it is not a standalone stable Provider module.
• The main OpenCode package is private and tightly coupled to workspace packages and OpenCode-specific request semantics.
• @opencode-ai/plugin exposes a plugin contract but does not supply the built-in Provider catalog/runtime or xAI OAuth implementation.

Recommended reuse boundary:

• consume Models.dev only in a maintenance/build workflow;
• allowlist the selected Providers;
• validate the schema and generate a pinned repository snapshot;
• use it only for non-secret model metadata such as IDs, limits, modalities, and pricing;
• keep base URLs, protocol, auth, capability claims, and product inclusion under CodexHub review;
• generate an upstream diff for review instead of mutating user runtime configuration automatically;
• retain a reviewed offline snapshot and rollback path.

Provider-specific MIT code may be selectively reimplemented or ported with attribution, but an upstream OAuth client identity is not reusable merely because the source license is MIT.

Security requirements

• Presets and snapshots contain no secrets.
• Raw keys/tokens are never returned to the frontend after storage.
• Logs, telemetry, diagnostics, exports, fixtures, and errors redact every credential form.
• OAuth callback state and PKCE are mandatory.
• Refresh-token rotation is atomic and cross-process safe.
• Provider credentials cannot weaken the existing local Gateway authentication boundary.
• Upstream catalog changes cannot auto-enable new Providers, change routes, or override user configuration.
• xAI must not reuse OpenCode's or Grok CLI's allowlisted public client ID without explicit authorization.

Proposed child issues

• Provider preset manifest and curated initial catalog.
• One-click API-key Provider onboarding.
• Selective Models.dev sync and upstream-diff workflow.
• Secure credential references and secret-store migration.
• Provider-scoped OAuth framework.
• xAI subscription OAuth pilot.

Dependency order:

preset manifest
  -> API-key onboarding
  -> selective metadata sync

secure credential store
  -> OAuth framework
  -> xAI OAuth pilot + xAI client approval

Tracking acceptance criteria

• The initial curated Provider list and ownership/update policy are approved.
• Each proposed child issue is created with explicit dependencies and validation.
• API-key onboarding ships independently of OAuth.
• Every preset has schema validation, snapshot/provenance coverage, probe mocks, and Gateway routing tests.
• Preset updates never silently overwrite user-owned Provider settings.
• Offline behavior uses the last reviewed bundled snapshot.
• Credential migration and OAuth remain blocked until secret storage and redaction are proven.
• xAI OAuth remains disabled until CodexHub-specific client authorization is confirmed.
• English and Chinese UI/documentation cover setup, failure recovery, credential removal, and source provenance.

Non-goals

• Mirroring every OpenCode or Models.dev Provider.
• Running arbitrary OpenCode Provider plugins inside CodexHub.
• Sharing or importing secrets from OpenCode.
• Letting Models.dev become the runtime authority for routes, authentication, or verified tool compatibility.
• Shipping a generic OAuth framework and xAI subscription support inside the API-key MVP.

Research and source evidence

• docs/research/2026-07-12-opencode-provider-presets-scope.md
• OpenCode baseline: https://github.com/anomalyco/opencode/tree/34e58090595d44e3e7cc37498f16753a98627456
• OpenCode Models.dev loader: https://github.com/anomalyco/opencode/blob/34e58090595d44e3e7cc37498f16753a98627456/packages/core/src/models-dev.ts
• OpenCode Provider runtime: https://github.com/anomalyco/opencode/blob/34e58090595d44e3e7cc37498f16753a98627456/packages/opencode/src/provider/provider.ts
• OpenCode Provider auth service: https://github.com/anomalyco/opencode/blob/34e58090595d44e3e7cc37498f16753a98627456/packages/opencode/src/provider/auth.ts
• OpenCode xAI auth plugin: https://github.com/anomalyco/opencode/blob/34e58090595d44e3e7cc37498f16753a98627456/packages/opencode/src/plugin/xai.ts
• Models.dev API: https://models.dev/api.json
• xAI OIDC discovery: https://auth.x.ai/.well-known/openid-configuration

Related

• Make config and catalog writes atomic and locked across Rust and Python #23
• Harden local Gateway auth so codex-app context is not spoofable #24
• Spike complete Codex model capability exposure on third-party providers #57
• 0.1.8 Beta2: Define tool-type compatibility rules for custom Responses endpoints #65
• Support secure imagegen output rendering for third-party Codex providers #68
• config/providers.toml
• frontend/src/pages/ProvidersPage.tsx
• src-tauri/src/config.rs
• src-python/provider_registry.py