feat: wire convex data foundations
This commit is contained in:
147
.agents/skills/convex-setup-auth/references/workos-authkit.md
Normal file
147
.agents/skills/convex-setup-auth/references/workos-authkit.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# WorkOS AuthKit
|
||||
|
||||
Official docs:
|
||||
|
||||
- https://docs.convex.dev/auth/authkit/
|
||||
- https://docs.convex.dev/auth/authkit/add-to-app
|
||||
- https://docs.convex.dev/auth/authkit/auto-provision
|
||||
|
||||
Use this when the app already uses WorkOS or the user wants AuthKit
|
||||
specifically.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Confirm the user wants WorkOS AuthKit
|
||||
2. Determine whether they want:
|
||||
- a Convex-managed WorkOS team
|
||||
- an existing WorkOS team
|
||||
3. Ask whether the user wants local-only setup or production-ready setup now
|
||||
4. Read the official Convex and WorkOS AuthKit guide
|
||||
5. Create or update `convex.json` for the app's framework and real local port
|
||||
6. Follow the correct branch of the setup flow based on that choice
|
||||
7. Configure the required WorkOS environment variables
|
||||
8. Configure `convex/auth.config.ts` for WorkOS-issued JWTs
|
||||
9. Wire the client provider and callback flow
|
||||
10. Verify authenticated requests reach Convex
|
||||
11. If the user wants production-ready setup, make sure the production WorkOS
|
||||
configuration is covered too
|
||||
12. Only add `storeUser` or a `users` table if the app needs first-class user
|
||||
rows inside Convex
|
||||
|
||||
## What To Do
|
||||
|
||||
- Read the official Convex and WorkOS AuthKit guide before writing setup code
|
||||
- Determine whether the user wants a Convex-managed WorkOS team or an existing
|
||||
WorkOS team
|
||||
- Treat `convex.json` as a first-class part of the AuthKit setup, not an
|
||||
optional extra
|
||||
- Follow the current setup flow from the docs instead of relying on older
|
||||
examples
|
||||
|
||||
## Key Setup Areas
|
||||
|
||||
- package installation for the app's framework
|
||||
- `convex.json` with the `authKit` section for dev, and preview or prod if
|
||||
needed
|
||||
- environment variables such as `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, and
|
||||
redirect configuration
|
||||
- `convex/auth.config.ts` wiring for WorkOS-issued JWTs
|
||||
- client provider setup and token flow into Convex
|
||||
- login callback and redirect configuration
|
||||
|
||||
## Files and Env Vars To Expect
|
||||
|
||||
- `convex.json`
|
||||
- `convex/auth.config.ts`
|
||||
- frontend auth provider wiring
|
||||
- callback or redirect route setup where the framework requires it
|
||||
- WorkOS environment variables commonly include:
|
||||
- `WORKOS_CLIENT_ID`
|
||||
- `WORKOS_API_KEY`
|
||||
- `WORKOS_COOKIE_PASSWORD`
|
||||
- `VITE_WORKOS_CLIENT_ID`
|
||||
- `VITE_WORKOS_REDIRECT_URI`
|
||||
- `NEXT_PUBLIC_WORKOS_REDIRECT_URI`
|
||||
|
||||
For a managed WorkOS team, `convex dev` can provision the AuthKit environment
|
||||
and write local env vars such as `VITE_WORKOS_CLIENT_ID` and
|
||||
`VITE_WORKOS_REDIRECT_URI` into `.env.local` for Vite apps.
|
||||
|
||||
## Concrete Steps
|
||||
|
||||
1. Choose Convex-managed or existing WorkOS team
|
||||
2. Create or update `convex.json` with the `authKit` section for the framework
|
||||
in use
|
||||
3. Make sure the dev `redirectUris`, `appHomepageUrl`, `corsOrigins`, and local
|
||||
redirect env vars match the app's actual local port
|
||||
4. For a managed WorkOS team, run `npx convex dev` and follow the interactive
|
||||
onboarding flow
|
||||
5. For an existing WorkOS team, get `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` from
|
||||
the WorkOS dashboard and set them with `npx convex env set`
|
||||
6. Create or update `convex/auth.config.ts` for WorkOS JWT validation
|
||||
7. Run the normal Convex dev or deploy flow so backend config is synced
|
||||
8. Wire the WorkOS client provider in the app
|
||||
9. Configure callback and redirect handling
|
||||
10. Verify the user can sign in and return to the app
|
||||
11. Verify Convex sees the authenticated user after login
|
||||
12. If the user wants production-ready setup, configure the production client
|
||||
ID, API key, redirect URI, and deployment settings too
|
||||
|
||||
## Gotchas
|
||||
|
||||
- The docs split setup between Convex-managed and existing WorkOS teams, so ask
|
||||
which path the user wants if it is not obvious
|
||||
- Keep dev and prod WorkOS configuration separate where the docs call for
|
||||
different client IDs or API keys
|
||||
- Only add `storeUser` or a `users` table if the app needs first-class user rows
|
||||
inside Convex
|
||||
- Do not mix dev and prod WorkOS credentials or redirect URIs
|
||||
- If the repo already contains WorkOS setup, preserve the current tenant model
|
||||
unless the user wants to change it
|
||||
- For managed WorkOS setup, `convex dev` is interactive the first time. In
|
||||
non-interactive terminals, stop and ask the user to complete the onboarding
|
||||
prompts.
|
||||
- `convex.json` is not optional for the managed AuthKit flow. It drives redirect
|
||||
URI, homepage URL, CORS configuration, and local env var generation.
|
||||
- If the frontend starts on a different port than the one in `convex.json`, the
|
||||
hosted WorkOS sign-in flow will point to the wrong callback URL. Update
|
||||
`convex.json`, update the local redirect env var, and run `npx convex dev`
|
||||
again.
|
||||
- Vite can fall off `5173` if other apps are already running. Do not assume the
|
||||
default port still matches the generated AuthKit config.
|
||||
- A successful WorkOS sign-in should redirect back to the local callback route
|
||||
and then reach a Convex-authenticated state. Do not stop at "the hosted WorkOS
|
||||
page loaded."
|
||||
|
||||
## Production
|
||||
|
||||
- Ask whether the user wants dev-only setup or production-ready setup
|
||||
- If the answer is production-ready, make sure the production WorkOS client ID,
|
||||
API key, redirect URI, and Convex deployment config are all covered
|
||||
- Verify the production redirect and callback settings before calling the task
|
||||
complete
|
||||
- Do not silently write a notes file into the repo by default. If the user wants
|
||||
rollout or handoff docs, create one explicitly.
|
||||
|
||||
## Validation
|
||||
|
||||
- Verify the user can complete the login flow and return to the app
|
||||
- Verify the callback URL matches the real frontend port in local dev
|
||||
- Verify Convex receives authenticated requests after login
|
||||
- Verify `convex.json` matches the framework and chosen WorkOS setup path
|
||||
- Verify `convex/auth.config.ts` matches the chosen WorkOS setup path
|
||||
- Verify environment variables differ correctly between local and production
|
||||
where needed
|
||||
- If production-ready setup was requested, verify the production WorkOS
|
||||
configuration is also covered
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Confirm the user wants WorkOS AuthKit
|
||||
- [ ] Ask whether the user wants local-only setup or production-ready setup
|
||||
- [ ] Choose Convex-managed or existing WorkOS team
|
||||
- [ ] Create or update `convex.json`
|
||||
- [ ] Configure WorkOS environment variables
|
||||
- [ ] Configure `convex/auth.config.ts`
|
||||
- [ ] Verify authenticated requests reach Convex after login
|
||||
- [ ] If requested, configure the production deployment too
|
||||
Reference in New Issue
Block a user