[connectors] dcr-oauth2 — discovery + dynamic client registration + PKCE for user-named endpoints

[serge-ivo]

Design: docs/connector-auth.md.

The gap

The connector auth model (api-key | oauth2 | app | none) assumes the operator knows the remote system at build time. oauth2 requires secretRef resolved from operator env — a pre-registered, confidential client.

That breaks for the first connector where a subscriber names the endpoint at runtime (outbound MCP, mcp_url as a per-instance setting). The operator cannot pre-register with a server they have never heard of, so secretRef is unfillable: there is no value that could go in it.

Consequence: the mcp connector shipped auth:"token" — a vault bearer the user pastes in — which the first real target (FreeWebStore) explicitly documents as "a compatibility fallback" alongside "do not ask users to paste access tokens."

This also blocks #143 Phase 3 (creator-supplied manifests): a creator cannot add a client secret to the operator env, so any creator connector needing OAuth requires an operator deploy — exactly what #143 exists to abolish.

The fix

Add auth.type: "dcr-oauth2". The connector declares nothing about the remote server; the resource URL is the input.

Step	Spec	Removes
Discover auth server from resource	RFC 9728 protected-resource metadata	hardcoded authUrl/tokenUrl
Discover endpoints	RFC 8414 AS metadata	manifest endpoint config
Register the client at runtime	RFC 7591 dynamic client registration	secretRef, pre-registration
Authorize without a secret	PKCE S256, public client	the client secret entirely

This is the stack MCP mandates. Verified live against FreeWebStore:

POST https://agent.freewebstore.online/register
 -> 201 {"client_id":"6bda1761-...","redirect_uris":["https://api.proagentstore.online/v1/connectors/mcp/oauth/callback"]}

PAGS registered itself, for its own callback, with no operator involvement and no secret.

Scope

• Discovery chain: resource URL -> RFC 9728 -> RFC 8414, through safeFetch (SSRF-guarded, https-only).
• DCR client registration cached per (user, resource origin) — one registration per server per user, reused across instances; envelope-encrypted like every other credential.
• PKCE S256 authorize + callback, reusing the HMAC-signed state in lib/connector-oauth.ts.
• Grant storage keyed by resource origin, not connector id alone (a user may connect several MCP servers).
• connectorClient dispatch for the new type; mcp connector switches to it when discovery finds an auth server, falling back to vault bearer only when it does not.

Acceptance

• A subscriber can connect an arbitrary OAuth-protected MCP server with no operator action and no pasted token.
• Registration is performed once per (user, origin) and reused.
• A server offering no auth metadata still works via the existing vault-bearer path.
• Discovery cannot be pointed at internal addresses (SSRF guard covers the metadata fetches).
• Tests cover: discovery, DCR, PKCE round-trip, cached registration reuse, and the no-metadata fallback.

Notes

Getting connected is necessary but not sufficient for unattended chains — see the companion issue on credential survivability.

[serge-ivo]

Partly delivered in 5f28af8; the DCR+PKCE half is deliberately deferred and this issue stays open.

Shipped: lib/connectors/discovery.ts — the RFC 9728 → RFC 8414 metadata chain through safeFetch. The MCP connector's 401/403 path now names the authorization server and the specific missing capability instead of guessing.

Not shipped — and discovery is itself the evidence for stopping. Probing the only live target (FreeWebStore) returns:

code_challenge_methods_supported:      ["S256"]
token_endpoint_auth_methods_supported: ["none"]
grant_types_supported:                 ["authorization_code"]   ← no refresh_token

So a completed DCR+PKCE flow against it yields an interactive-only credential that expires every 24h and needs a human at a browser — unusable for the cron-driven pipelines this connector exists to serve. Building it would have cost a registration cache, a migration, new routes and per-origin grant keying to buy precisely the thing #181 was just merged to warn against wiring.

Blocked on: freewebstore-online/platform#114 (refresh grant). Revisit when an authorization server in scope advertises refresh_token.

docs/connector-auth.md moved from "proposal" to "partly implemented" with that split stated. Acceptance criteria on this issue are NOT met — leaving open rather than closing on the discovery half.