Part of epic #3306.

Problem

Agents that hit a protected endpoint on api.worldmonitor.app get a 401 or similar but have no standard way to learn (a) which authorization server issues tokens for this resource, (b) what scopes they must request, or (c) what resource identifier to put in the token aud claim. RFC 9728 defines /.well-known/oauth-protected-resource for exactly this.

We already use Clerk for auth, and Clerk exposes a standards-compliant OIDC discovery document — so we have the upstream pieces; we just need to publish the resource-side metadata.

Fix

Serve /.well-known/oauth-protected-resource at the origin root with at minimum:

{
  "resource": "https://api.worldmonitor.app/",
  "authorization_servers": [
    "https://clerk.worldmonitor.app"
  ],
  "scopes_supported": [
    "read:public",
    "read:pro"
  ],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://worldmonitor.app/docs/api/auth"
}

Exact values to confirm during implementation:

• The Clerk OIDC issuer for our prod instance (check Clerk dashboard).
• The actual scope namespace we want to advertise. Today our gate logic uses isCallerPremium (Clerk org:pro role OR Convex tier>=1) rather than OAuth scopes — so we either (a) advertise a pro scope and teach the gate to also honour it, or (b) advertise only read:public and keep premium out of this surface for now.

Implementation

• Static JSON at public/.well-known/oauth-protected-resource OR edge function at api/.well-known/oauth-protected-resource.ts if we want to interpolate env-based values (prefer static if values are stable).
• Response MUST use Content-Type: application/json.
• Add to Link headers (feat(agent-readiness): add Link response headers for agent discovery (RFC 8288) #3308) with rel http://openid.net/specs/connect/1.0/protected-resource-metadata (or the RFC 9728 reserved rel).
• Add to API catalog (feat(agent-readiness): publish API catalog at /.well-known/api-catalog (RFC 9727) #3309) linkset.
• Sanity-check that middleware.ts PUBLIC_API_PATHS allows this .well-known path (see memory: middleware short-UA guard).

Acceptance criteria

• curl -s https://worldmonitor.app/.well-known/oauth-protected-resource returns valid JSON conforming to RFC 9728.
• resource field matches the actual API origin (https://api.worldmonitor.app/).
• authorization_servers[0]/.well-known/openid-configuration resolves (smoke check).
• Advertised scopes match reality — no scopes we don't honour.
• isitagentready.com "OAuth Protected Resource Metadata" check passes.

References

• RFC 9728 — OAuth 2.0 Protected Resource Metadata
• Clerk OIDC docs
• Skill: https://isitagentready.com/.well-known/agent-skills/oauth-protected-resource/SKILL.md