docs(auth): add OAuth PKCE callback flow documentation

[tonychang04]

Summary

let agent to optmizae the experience for auth

• sdk-integration.md: Add two redirect URLs table (provider callback vs redirectTo), SPA vs SSR guidance, SDK methods reference for signInWithOAuth and exchangeOAuthCode
• ssr-integration.md: Replace vague bullet-point best practices with full Next.js App Router implementation — server action, /api/auth/callback route handler, login page component, trailing-slash-safe URL construction

Problem

Users were setting redirectTo to the InsForge backend URL (NEXT_PUBLIC_INSFORGE_URL) instead of their app URL (NEXT_PUBLIC_APP_URL), causing Cannot GET /auth/callback. The skill docs didn't explain the distinction or show the full SSR callback flow.

Testing

• RED baseline: subagent with current skill had to guess ~80% of the OAuth implementation
• GREEN: subagent with updated skill got ~75% correct (remaining gaps are SDK setup, which is already covered earlier in ssr-integration.md)
• 17 backend unit tests added in InsForge/InsForge for the PKCE service

Test plan

• Baseline test (subagent without skill) — documented failures
• Re-test (subagent with updated skill) — verified correct redirectTo, callback route, exchange flow
• Backend PKCE unit tests pass (17/17)

🤖 Generated with Claude Code

Note

Add OAuth PKCE callback flow documentation for SPA and SSR environments

• Adds a 'Two redirect URLs' section to sdk-integration.md clarifying the difference between the provider callback URL (InsForge backend) and redirectTo (app URL), with a common Cannot GET /auth/callback error callout.
• Documents automatic PKCE handling in SPAs via the SDK constructor, including insforge_code detection and URL cleanup.
• Replaces the prior OAuth section in ssr-integration.md with a three-step Next.js server-side flow: a server action using skipBrowserRedirect: true, an API route handler that exchanges the code and sets httpOnly cookies, and a client login component.
• Adds an SDK methods reference table covering when to use signInWithOAuth, skipBrowserRedirect, and exchangeOAuthCode.
• Expands the Common Mistakes table in the SSR guide with entries for correct redirectTo usage, codeVerifier storage, and server-side token handling.

^{Macroscope summarized 7dcfb4c.}

Summary by CodeRabbit

• Documentation
  • Enhanced OAuth authentication documentation with improved clarity on SPA versus SSR implementation flows
  • Expanded redirect URL configuration guidance with troubleshooting for common misconfigurations
  • Updated code examples for SDK integration and Next.js server-side authentication
  • Added SDK methods reference table for easier integration

[coderabbitai]

Walkthrough

Documentation updates for InsForge OAuth integration, clarifying PKCE support, redirect URL semantics, and SDK method usage. SPA examples updated to show client-side code auto-detection. SSR/Next.js guidance expanded with server action and API route examples for full server-side OAuth flow with secure cookie handling.

Changes

Cohort / File(s)	Summary
OAuth SDK and SPA Documentation skills/insforge/auth/sdk-integration.md	Updated OAuth section to document PKCE, clarify dual redirect URL semantics (provider callback vs. app landing), add SPA auto-detection behavior, and introduce new SDK methods reference table for signInWithOAuth and exchangeOAuthCode across SPA and SSR modes.
SSR/Next.js OAuth Server-Side Flow skills/insforge/auth/ssr-integration.md	Replaced prior OAuth best practices with complete server-side flow documentation: added server action example for initiateOAuth (PKCE verifier storage), API route handler for /app/api/auth/callback (code exchange and token cookies), client login page example, and updated common mistakes table to reflect correct server-side exchange patterns.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Update auth skills #15: Modifies the same SDK documentation file (sdk-integration.md) with overlapping references to OAuth methods (signInWithOAuth, exchangeOAuthCode) and session/user API changes.
• Add auth ssr skill #11: Directly related OAuth documentation expansion in both sdk-integration.md and ssr-integration.md, including PKCE and server-side exchange patterns.

Suggested reviewers

• Fermionic-Lyu
• jwfing

Poem

🐰 Hops through OAuth flows with glee,
PKCE and redirects, now clear as can be!
SPA and SSR paths both shown,
Server cookies safe, secrets in a zone,
Documentation blooms—authorization's bright home! 🌸

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: documentation updates to OAuth PKCE callback flow, which is the primary focus of both modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/oauth-callback-skill-update

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/insforge/auth/ssr-integration.md`:
- Around line 156-157: The redirect currently interpolates raw backend text via
exchangeError?.message into the query string in NextResponse.redirect; change it
to pass either a stable error code or a sanitized/URL-encoded message instead of
raw text—locate the redirect line that constructs new
URL(`/login?error=${exchangeError?.message ?? 'exchange_failed'}`, request.url)
and replace it with logic that maps exchangeError to a deterministic code (or
applies safe encoding like URL-encoding) and use that value in the query
parameter so URLs remain valid and internals are not exposed.
- Around line 110-120: Guard against a missing PKCE verifier instead of using a
non-null assertion: after validating error and data.url in the OAuth init block,
also explicitly check that data.codeVerifier exists (e.g., if
(!data.codeVerifier) throw new Error('Missing codeVerifier for PKCE')) before
calling cookies() and cookieStore.set('insforge_code_verifier', ...). Update the
check that currently throws for error || !data.url to also validate
data.codeVerifier and use that validated value when calling cookieStore.set to
avoid relying on the non-null assertion on data.codeVerifier.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4be52fe9-9ce7-4c27-9bfb-074f66f50697

📥 Commits

Reviewing files that changed from the base of the PR and between 5ee1335 and 7dcfb4c.

📒 Files selected for processing (2)

• skills/insforge/auth/sdk-integration.md
• skills/insforge/auth/ssr-integration.md

[tonychang04]

cc @Fermionic-Lyu can you check this for me? giving more guidance in skills to fix callback url incorrect issue

[Fermionic-Lyu]

LGTM in quick scan. Can fix wording later if doesn't work well

[Fermionic-Lyu]

This is technically correct but I am not sure if it is a good practice to include it in the skill