SKILL.md
<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()returnstokenIdentifier,subject,issuerplus 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>