Support provider-owned custom request authentication

[chubes4]

Problem

ProviderRegistry currently derives provider authentication from ProviderMetadata::getAuthenticationMethod(), and RequestAuthenticationMethod only maps to ApiKeyRequestAuthentication.

That works for API-key providers, but it makes provider-owned OAuth or token-refresh authentication awkward. A provider that needs to add dynamic bearer tokens or provider-specific headers has to pretend to be API-key based, e.g. by subclassing ApiKeyRequestAuthentication, even when the credential is not an API key.

Concrete case

I tested a local WordPress proof for ChatGPT/Codex-backed OpenAI access via wp-ai-client:

• registered a provider through AiClient::defaultRegistry()
• refreshed a ChatGPT/Codex OAuth access token
• sent a request to the Codex Responses backend
• normalized the response into GenerativeAiResult

The live WordPress proof succeeded and returned the expected model text.

The runtime did not need WordPress Core Connectors to execute. The awkward part was only the auth shape: the provider had to expose RequestAuthenticationMethod::apiKey() so the registry would accept the request auth object, even though the auth object was actually OAuth/token-refresh backed and added provider-specific headers.

Why this belongs in php-ai-client

php-ai-client is the runtime layer that knows how providers are registered, how models receive request auth, and how request auth objects are validated. WordPress Connectors can later own configuration, credential UI, and storage, but providers need a clean runtime primitive first.

Suggested direction

Add a provider-owned/custom request authentication path that allows providers to supply a RequestAuthenticationInterface implementation without requiring it to be one of the hard-coded enum-backed auth implementations.

Possible shapes:

• Add a custom authentication method whose implementation class is supplied by provider metadata.
• Allow providers to create/default their own RequestAuthenticationInterface instance through a static factory or provider contract.
• Relax ProviderRegistry::setRequestAuthenticationForProvider() so provider metadata can explicitly declare a custom request auth class.

The key requirement is that a provider can say: "this provider authenticates requests with this request-auth object", without misrepresenting OAuth/device-flow/session credentials as an API key.

Non-goals

• This is not asking WordPress Core Connectors to support OAuth UI/storage yet.
• This is not asking php-ai-client to support true streaming over WordPress HTTP. WordPress Core HTTP is buffered; providers that must send stream=true can still parse a fully buffered text/event-stream response in their own model implementation.
• This is not asking for OpenAI/Codex-specific code in php-ai-client.

Related

• Add support for streaming #100 tracks broader streaming support. This issue is specifically about request authentication extensibility.

[chubes4]

Adding the downstream integration stack this now unblocks:

• Add ChatGPT Codex OAuth provider ai-provider-for-openai#30 — Codex OAuth provider using provider-supplied request auth.
• Harden generic OpenAI-compatible gateway CLI, token, and model routing Automattic/wp-ai-gateway#1 — OpenAI-compatible WordPress gateway that can route to Codex without raw API-key auth.
• Optionally install and configure WP AI Gateway for OpenCode runtimes Extra-Chill/wp-coding-agents#173 — optional OpenCode setup path that installs/configures the gateway and provider stack.
• Support generic runtime secret/env projection for fan-out sessions Extra-Chill/data-machine-code#488 — pass only gateway credentials to Lab/WP Codebox fan-out sessions.
• Guard against recursive WP AI Gateway routing loops chubes4/ai-provider-for-opencode#4 — guard against recursive gateway/provider routing loops.

Existing tested local branch for this issue:

• /Users/chubes/Developer/php-ai-client@custom-provider-auth
• Branch: custom-provider-auth
• Commit: 3624d24 Add provider-supplied request authentication

For this stack, the acceptance shape is specifically: providers can supply their own RequestAuthenticationInterface, the registry binds it to model instances, explicit externally supplied provider auth still works, and API-key providers keep existing behavior.

[felixarntz]

@chubes4 I'm not sure about this one. First, for sure the PHP AI Client should support other authentication methods than API key - but what you're proposing here (and implementing in #238) feels more of a workaround for other authentication methods not existing.

The reason we don't yet support other authentication methods is that properly implementing them tends to be more effort, especially OAuth. The implementation would need to cover (at the minimum) to refresh the access token when (or shortly before) it expires.

As far as I can tell, your practical concern that the issue and PR are addressing is purely that sending a Bearer token under an authentication method called API key sounds confusing. I get that, though technically either is simply just a single specific header with a string value.

While getting proper support for OAuth request authentication would be ideal, I acknowledge this isn't something to just build out tomorrow. So how about instead we actually add a new class for just the bearer token part, as an actual first-class citizen of the PHP AI Client? In other words a new BearerTokenRequestAuthentication class, including new enum value and related handling. I think that would be a cleaner implementation.

[chubes4]

@felixarntz Yes, this is a bit of a hacked together approach. I was trying to get Codex auth running headlessly in WordPress and succeeded at that.

I agree that WordPress should support native OAuth flows. The primary concern was API key only auth. It feels like the Connectors page should be the home of all OAuth in WordPress, from social media to AI providers.

I know this PR isn't the above, it's just where my head is at. I'll come back with something cleaner.

Thank you again for the feedback sir!