AgentSkillsCN

convex-auth

利用 OIDC 提供商或 Convex Auth，实施 Convex 的认证与授权模式。 在设置认证提供商会用到此技能；在 ctx.auth 的使用场景中，可借助该技能处理用户身份；同时，它还能帮助你设计具备认证意识的 Schema 模式。 当用户提及认证、JWT、Clerk/Auth0/WorkOS，或 Convex Auth 时，应主动运用此技能。 示例： - 用户：“为 Convex 添加认证功能” → 选择合适的认证提供商并规划部署流程 - 用户：“获取当前用户信息” → 使用 ctx.auth.getUserIdentity 方法进行身份验证与检查 - 用户：“实现服务间访问” → 采用共享密钥模式

SKILL.md
--- frontmatter
name: convex-auth
description: |-
  Implement Convex authentication and authorization patterns with OIDC providers or Convex Auth.
  Use for auth provider setup, ctx.auth usage, user identity handling, and auth-aware schema patterns.
  Use proactively when users mention auth, JWT, Clerk/Auth0/WorkOS, or Convex Auth.
  
  Examples:
  - user: "Add auth to Convex" → choose provider and outline setup
  - user: "Get current user" → use ctx.auth.getUserIdentity and checks
  - user: "Service-to-service access" → use shared secret pattern
<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>