Convex Auth

<overview> Implement Convex authentication and authorization patterns with OIDC providers (Clerk, Auth0, WorkOS) or the built-in Convex Auth library. </overview>

<reference>

• Auth overview: https://docs.convex.dev/auth
• Convex Auth (beta): https://docs.convex.dev/auth/convex-auth
• Auth methods: https://labs.convex.dev/auth
• Clerk Integration: https://docs.convex.dev/auth/clerk
• WorkOS Integration: https://docs.convex.dev/auth/authkit/

</reference>

<context name="Auth Concepts">

• Convex uses OpenID Connect JWTs.
• Integrations: Clerk, WorkOS AuthKit, Auth0; custom OIDC supported.
• Convex Auth (Beta): A built-in library (labs.convex.dev) supporting Magic Links, OTPs, OAuth, and Passwords without external services.
• Identity: Accessed via ctx.auth.getUserIdentity() in server functions.
• Authorization: Enforced per public function; sensitive logic MUST use internal functions.

</context>

<rules>

Auth Operations

• In functions: ctx.auth.getUserIdentity() returns tokenIdentifier, subject, issuer plus provider claims.
• Custom JWT auth MAY expose claims at identity["properties.email"] style paths.
• User storage patterns:
• Client mutation to store user from JWT, or webhook from provider to upsert users.
• Index lookups SHOULD use by_token / byExternalId.
• Webhooks: You MUST implement via HTTP actions and verify signatures with provider SDK; signing secrets MUST be stored in env vars.

Convex Auth (Beta) Specifics

• Supported Methods:

1. Magic Links & OTPs: Email-based links or codes. 2. OAuth: GitHub, Google, Apple, etc. 3. Passwords: Supports reset flows and optional email verification.

• Components: Does not provide UI components; You MUST build them in React using library hooks.
• Next.js: SSR/Middleware support is experimental/beta.

Server Function Patterns

• You MUST read identity via ctx.auth.getUserIdentity().
• You MUST enforce row-level authorization in every public function.
• You SHOULD NOT expose sensitive logic via public functions; prefer internal ones.

Service-to-service Access

• If no user JWT is available, You SHOULD use a shared secret pattern.
• You MUST store secrets in deployment env vars; MUST NOT hardcode.

Client Guidance

• You MUST follow provider quickstarts; MUST NOT invent flows.
• You SHOULD NOT rely on auth data in client-only code without server verification.

</rules>