Document stateless BYOK provider auth for derived-account adapters

[bokelley]

Clarified ask

This is a documentation/pattern ask, not a request for new OAuth runtime functionality.

The SDK already has the primitives we need for OAuth/BYOK provider auth:

• bearer/introspection/custom authentication can populate request authInfo
• authInfo carries the token and stable credential/client identity
• createDerivedAccountStore can require auth and derive the per-request account from ctx.authInfo
• missing auth already maps to SDK AUTH_REQUIRED

We need docs/examples that show how to combine these pieces for Storefront-backed provider adapters.

Storefront model

Storefront is the buyer-facing seller/platform boundary. Inside that boundary, some backing adapters are provider-auth adapters: the client owns the provider credential lifecycle, passes the current provider bearer/API/OAuth token to the MCP session or tool call, and the Storefront adapter derives the per-request account/auth context from that credential.

Other Storefront flows that register or acknowledge buyer accounts can continue to use sync_accounts / implicit-account patterns. This issue is not asking to replace those shapes.

Desired docs/example

Show createDerivedAccountStore as the canonical pattern for provider-auth adapters behind a Storefront boundary:

const accounts = createDerivedAccountStore<MyAdapterMeta>({
  toAccount: (ctx) => ({
    id: 'audiostack',
    name: 'AudioStack',
    status: 'active',
    authInfo: ctx?.authInfo,
    ctx_metadata: {},
  }),
})

The important properties:

• platform handlers can read the provider token from the resolved account/request auth context, e.g. ctx.account.authInfo.token or the current equivalent field
• handlers can use a stable non-secret identity such as ctx.account.authInfo.clientId / credential id for idempotency and cache scoping
• the host app does not persist provider credentials
• no refresh token store, provider token store, or OAuth callback route is required when the client owns OAuth
• AUTH_REQUIRED from createDerivedAccountStore is the standard signal clients can use to prompt for provider credentials

Per-tool / per-specialism guidance

Please document the expected pattern when only some Storefront-backed adapter tools require provider auth:

• AudioStack creative tools require AudioStack bearer/OAuth auth.
• get_adcp_capabilities should not require provider auth.
• Some sales adapters may require auth for list_accounts, get_products, etc.

If account-resolution-level auth via createDerivedAccountStore is the intended mechanism, document that. If a tool/specialism should instead gate inside the handler using ctx.account.authInfo, show that pattern.

Non-goal

This is not asking the SDK to store provider credentials or implement OAuth on behalf of the Storefront host. For client-owned OAuth, the SDK already has the needed auth primitives; we just need the derived-account BYOK/provider-adapter recipe documented clearly.

[bokelley]

Triage

Classification: Feature request
Bucket(s): library
Status: ready-for-human

What the experts said:

• security-reviewer: Sound to build; two hard blockers — provider token must travel on a separate named channel (not Authorization), and BYOK ingress must not silently void credentialPolicy: 'authInfo-only'; design risks around log leakage, principal-hash namespace collisions, per-tool gate typo detection, and scope confusion.
• code-reviewer: AuthPrincipal is declared with incompatible shapes in auth.ts vs account.ts — must resolve before new fields land; ctx.account.authInfo.token already holds the buyer bearer, so provider credentials need a dedicated field (Account.providerCredential?); changeset is minor unless dual-export cleanup is breaking.
• dx-expert: authInfo.token conflates two auth planes and will misdirect adopters and LLM agents alike; recommends ctx.authInfo.extra.<provider_key> or a typed providerCredentials? field; a requireProviderAuth(toolNames[]) export is needed for per-tool-gate discoverability.

My take: All three experts converge on the same architectural blocker: provider credentials (outbound, per-request) and buyer credentials (inbound, per-session) must be distinct at the API surface before any code lands. This is security-sensitive; flagging for @bokelley to decide the ingress channel and field placement.

Decisions needed before implementation:

• Ingress: dedicated x-adcp-provider-token header vs. verifyApiKey.extra derivation at auth time vs. MCP session _meta
• Field: Account.providerCredential? vs. typed AuthPrincipal.providerTokens? vs. ctx.authInfo.extra.<key>
• Whether validateCredentialPolicy construction-time check extends to the per-tool provider-auth gate (silent misconfiguration risk)
• Whether dual-AuthPrincipal cleanup (auth.ts vs account.ts) is breaking → major bump

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01Vg1RtQyg1ok7PsARgdv3Ft

---

Generated by Claude Code

[bokelley]

Decision: keep baseline BYOK single-plane.

For API-key/Bearer BYOK, the caller presents the provider credential as the AdCP request credential:

Authorization: Bearer <provider_api_key_or_access_token>

The SDK should treat that as request auth, expose the request-local token to platform handlers, and expose a stable non-secret principal/credential id for cache/idempotency scoping. No token store, refresh store, callback route, or separate provider-auth channel is required for this baseline path.

This covers the common seller-agent wrapper shape: a caller invokes an AdCP seller agent that wraps an upstream provider API, using the tenant/provider credential as Bearer request auth.

A separate provider-auth channel is only needed for deployments that require two credentials on the same request: one credential to authorize the caller to the seller agent, and another to authorize the upstream provider tenant. That is an optional/proxy-specific extension, not the default BYOK model.

So this issue should remain docs-focused: document the stateless BYOK pattern using existing request auth + account resolution, then close when the docs PR merges.