feat(core): branded DCR OAuth providers (WorkOS, Auth0, Clerk, Stytch, Descope)

[harijoe]

Summary

• Add branded DCR OAuth providers in packages/core.
• workosProvider, auth0Provider, clerkProvider, stytchProvider, descopeProvider.
• Each is a thin wrapper over the generic customProvider (feat(core): customProvider (SKY-446) #878).
• customProvider discovers the IdP's OAuth metadata and verifies JWTs via JWKS.
• Wire an example app per provider under examples/auth-*; all five verified end to end on Alpic.

Architecture Notes

• audience is now optional in customProvider/verify — when omitted, the aud check is skipped.
• Needed for Clerk, whose tokens carry no aud claim; clerkProvider has no audience option.
• Binding providers (workos/auth0/stytch/descope) re-require audience so it can't be silently dropped.

Relationship to #848 (community Descope example)

This supersedes #848 (@mrunankpawar) — please close #848 in favor of the branded descopeProvider here, crediting the contributor.

Carried over / improved vs #848:

• Same demo app — coffee-data.ts, the view, and helpers.ts are byte-identical; the README is fuller (122 vs 85 lines).
• Added Descope MCP Server auth #848's manual src/auth.ts (hardcoded JWKS URL, aud = ${SERVER_URL}/mcp) is replaced by the discovery-based branded descopeProvider.
• Audience corrected: Descope binds the token aud to [DCR client id, project id], so the audience must be the Project ID (verified working). Added Descope MCP Server auth #848's ${SERVER_URL}/mcp does not match current Descope tokens.

Validation (Alpic + playground)

Beyond the unit tests, every example was deployed to Alpic and driven through the complete OAuth flow in the playground — DCR, IdP sign-in/consent, token verification, and a successful authenticated tool call:

• WorkOS — example-workos-1210dbbd.alpic.live ✅
• Auth0 — example-auth0-00afc280.alpic.live ✅
• Clerk — example-clerk-2480a040.alpic.live ✅
• Stytch — example-stytch-3c5fa3cc.alpic.live ✅
• Descope — example-descope-8cb43574.alpic.live ✅

Each verified end to end: build-time metadata capture → /.well-known/oauth-protected-resource 200 → 401 + WWW-Authenticate on an unauthenticated /mcp → IdP sign-in/consent → token aud/issuer verified by the provider → tool call succeeds. Per-IdP setup was validated too (DCR enabled; resource/audience configured; Stytch's self-hosted consent pages + SDK domain allowlist; Descope MCP Server).

Greptile Summary

This PR introduces five branded DCR OAuth providers (workosProvider, auth0Provider, clerkProvider, stytchProvider, descopeProvider) as thin wrappers over an expanded customProvider, and refactors the corresponding example apps to use them. It also makes audience optional in customProvider/verify to accommodate Clerk tokens, which carry no aud claim.

• Provider layer: Each branded provider delegates to customProvider after normalising the issuer URL; clerkProvider explicitly omits audience to skip the aud check; descopeProvider derives the Descope Project ID from the MCP Server URL as the default audience.
• Discovery update: discoverAuthorizationServer now continues past a valid OIDC document that lacks registration_endpoint, preferring the document that advertises DCR (handles Clerk's split metadata shape).
• Example refactor: All five example apps drop their hand-rolled auth boilerplate (manual metadata routers, SDK-specific verify functions, CORS proxies) in favour of the new one-liner oauth: await <provider>(…) constructor option.

Confidence Score: 4/5

Safe to merge after fixing the Clerk README's phantom CLERK_AUDIENCE env variable; all five providers have been end-to-end validated and the core token verification logic is sound.

The Clerk README instructs users to set CLERK_AUDIENCE in their .env file, but env.ts never reads it and clerkProvider accepts no audience parameter. A user who follows the setup guide sets the variable, sees no errors (it is silently ignored), and is left debugging why audience-based access control has no effect.

examples/auth-clerk/README.md — the .env block includes CLERK_AUDIENCE which is not consumed anywhere in the example code.

_{Reviews (21): Last reviewed commit: "feat(examples): wire auth examples for t..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
skybridge-staging	🟢 Ready	View Preview	Jun 18, 2026, 1:51 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.