AUTH-6793: per-stack redirect guidance in skill - #41
Conversation
The skill instructed agents to use a /callback redirect URI regardless of stack. That is a Next.js convention — for SPAs the React SDK handles the OAuth redirect internally and no callback path should be specified at all, which made SPA integrations worse (redirect to a non-existent route). Make redirect guidance SDK-aware instead of one global instruction: - authkit-react (SPA): redirect URI is the app origin with NO path (e.g. http://localhost:5173, not .../callback); no callback route; register the origin on the Dashboard Redirects page and in allowed origins on the Authentication page. Added a verification check that fails if the redirect URI contains a callback path. - authkit-base: task table, decision tree, env table, checklists, and critical rules now branch on client-side vs server-side SDK instead of assuming every stack creates a callback route. - authkit-vanilla-js: added matching no-callback-path redirect guidance. - workos-management: noted the CLI `redirect add` example value is stack-dependent. Server-side stacks (Next.js, React Router framework mode, TanStack Start, SvelteKit, Node/Express, backend SDKs) keep their existing callback-route conventions, verified against the official SDK READMEs. Refs: AUTH-6793
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| # 3. Check redirect URI has no callback path (SDK handles redirect internally) | ||
| grep -E "WORKOS_REDIRECT_URI=.*/(callback|auth)" .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path" |
There was a problem hiding this comment.
🟡 Verification step wrongly fails apps hosted on an auth-prefixed domain
The new redirect-URI check flags any configured URL that merely contains the text "/auth" (grep -E "WORKOS_REDIRECT_URI=.*/(callback|auth)" at plugins/workos/skills/workos/references/workos-authkit-react.md:70), so a correctly configured app hosted at a domain beginning with "auth" is reported as broken.
Impact: Users following the checklist are told their correct setup has failed and may change a working configuration.
Why the pattern over-matches origins like https://auth.example.com
The regex .*/(callback|auth) matches the substring /auth anywhere in the value. For WORKOS_REDIRECT_URI=https://auth.example.com, the double slash in https://auth... supplies a / immediately followed by auth, so the check prints FAIL: redirect URI must be the app origin, no path even though the value is a bare origin with no path. Anchoring the path portion (e.g. requiring a / after the host/port) avoids the false positive.
| # 3. Check redirect URI has no callback path (SDK handles redirect internally) | |
| grep -E "WORKOS_REDIRECT_URI=.*/(callback|auth)" .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path" | |
| # 3. Check redirect URI has no callback path (SDK handles redirect internally) | |
| grep -E "WORKOS_REDIRECT_URI=https?://[^/]+/." .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path" |
Was this helpful? React with 👍 or 👎 to provide feedback.
| Server-side SDK (Next.js, Node/Express, React Router framework mode, | ||
| SvelteKit, TanStack Start, backend SDKs)? | ||
| → Redirect URI = callback URL with path (e.g., http://localhost:3000/callback) | ||
| → Extract path from WORKOS_REDIRECT_URI → create route at that exact path |
There was a problem hiding this comment.
🔍 Base skill classifies React Router as server-only, which may misroute SPA-mode projects
The new decision tree puts "React Router framework mode" under server-side SDKs, which is accurate for framework mode, but a React Router SPA/library-mode project (no server) would need the client-SDK branch. The tree gives no signal for distinguishing the two, so an agent seeing "react-router" in package.json may create a callback route for an app with no server — the exact failure mode this PR aims to eliminate. Note plugins/workos/skills/workos/references/workos-authkit-react.md:73 also warns on "react-router" in package.json as a "server framework detected", reinforcing the ambiguity.
Was this helpful? React with 👍 or 👎 to provide feedback.
| In the WorkOS Dashboard: | ||
|
|
||
| - Add the redirect URI (app origin, no path) on the **Redirects** page | ||
| - Add the app origin to the **allowed origins** list on the **Authentication** page (required for client-side token exchange) |
There was a problem hiding this comment.
🔍 Dashboard page names introduced despite router guardrail against click-paths
The router skill (plugins/workos/skills/workos/SKILL.md) instructs agents to never state Dashboard click-paths unless verified against fetched docs, and to describe destinations conceptually. The added lines name specific Dashboard surfaces ("Redirects" page, "allowed origins" on the "Authentication" page). This reads as conceptual rather than a full click-path, but if the CORS/allowed-origins control lives elsewhere in the Dashboard, this text becomes exactly the kind of stale guidance the guardrail targets; a docs URL citation would make it durable.
Was this helpful? React with 👍 or 👎 to provide feedback.
Greptile SummaryThe PR updates AuthKit guidance so client-side SDKs use the application origin while server stacks retain callback routes.
Confidence Score: 4/5The PR is not yet safe to merge because the React verification command can approve redirect configuration that differs from the Dashboard by a trailing slash. The new path-detection regex requires a character after the host’s slash, so a trailing-slash-only redirect bypasses validation even though the surrounding guidance requires an exact bare-origin match. Files Needing Attention: plugins/workos/skills/workos/references/workos-authkit-react.md Important Files Changed
Prompt To Fix All With AI### Issue 1
plugins/workos/skills/workos/references/workos-authkit-react.md:70
**Trailing slash bypasses redirect check**
When `WORKOS_REDIRECT_URI` ends with a trailing slash, the regex requires another character after that slash and emits no failure, so verification approves a value that can differ from the Dashboard’s documented bare origin and leave sign-in or token exchange failing at runtime.
```suggestion
grep -E "WORKOS_REDIRECT_URI=https?://[^/]+/" .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path"
```
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (2): Last reviewed commit: "fix: tighten SPA redirect URI verificati..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| # 3. Check no server framework present (wrong skill if found) | ||
| # 3. Check redirect URI has no path (SDK handles redirect internally) | ||
| grep -E "WORKOS_REDIRECT_URI=https?://[^/]+/." .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path" |
There was a problem hiding this comment.
When WORKOS_REDIRECT_URI ends with a trailing slash, the regex requires another character after that slash and emits no failure, so verification approves a value that can differ from the Dashboard’s documented bare origin and leave sign-in or token exchange failing at runtime.
| grep -E "WORKOS_REDIRECT_URI=https?://[^/]+/." .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path" | |
| grep -E "WORKOS_REDIRECT_URI=https?://[^/]+/" .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path" |
Prompt To Fix With AI
This is a comment left during a code review.
Path: plugins/workos/skills/workos/references/workos-authkit-react.md
Line: 70
Comment:
**Trailing slash bypasses redirect check**
When `WORKOS_REDIRECT_URI` ends with a trailing slash, the regex requires another character after that slash and emits no failure, so verification approves a value that can differ from the Dashboard’s documented bare origin and leave sign-in or token exchange failing at runtime.
```suggestion
grep -E "WORKOS_REDIRECT_URI=https?://[^/]+/" .env .env.local 2>/dev/null && echo "FAIL: redirect URI must be the app origin, no path"
```
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.1 participant
bosun task: AUTH-6793: per-stack redirect guidance in skill
Task id: task-msh08fr9-wgg9
Shape: ship
Project: workos/skills