fix(onboarding): redirect back to onboarding after GitHub app install

[jrf0110]

Summary

When a user clicks "Install GitHub App" during gastown onboarding, the GitHub callback always redirected them to /integrations/github?success=installed instead of back to the onboarding wizard. The user had to manually navigate back and start over.

This PR extends the state parameter with an optional |return=<path> suffix so the callback can redirect back to the originating page. Changes:

1. OnboardingStepRepo.tsx — Append return path to state, switch from window.open to window.location.href so the round-trip happens in the same tab. Added a toast + repo refetch on ?github_install=success.
2. callback/route.ts — Parse the |return= suffix via extracted parseStateReturn utility with an open-redirect guard (regex validates single-leading-slash internal paths, rejects //, /\, CR/LF). The returnTo-aware redirect applies to the success path only; error/pending paths unchanged for backwards compat.
3. OnboardingWizardClient.tsx — Read ?step= query param to seed the initial wizard step, so users land on the repo step after the GitHub round-trip.
4. validate-return-path.ts — Extracted validateReturnPath and parseStateReturn with unit tests covering open-redirect attack vectors.

Verification

Manually verified by tracing the code path: onboarding → GitHub install URL includes return= in state → callback parses and validates return path → redirects to /gastown/onboarding?step=repo&github_install=success → wizard seeds repo step → toast fires + repos refetch.

Visual Changes

N/A

Reviewer Notes

• The open-redirect guard regex /^\/(?![\/\\])[^\r\n]*$/ plus the // prefix check is the security-critical part — see validate-return-path.test.ts for attack vector coverage.
• Error/pending/approval paths in the callback intentionally do NOT use returnTo — we don't want to send users back to onboarding when the install failed or is pending approval.
• Old in-flight installs (no |return= suffix) continue to work via the fallback to /integrations/github.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (5 files)

• apps/web/src/app/(app)/gastown/onboarding/OnboardingStepRepo.tsx
• apps/web/src/app/(app)/gastown/onboarding/OnboardingWizardClient.tsx
• apps/web/src/app/api/integrations/github/callback/route.ts
• apps/web/src/lib/integrations/validate-return-path.ts
• apps/web/src/lib/integrations/validate-return-path.test.ts

---

_{Reviewed by gpt-5.5-20260423 · 237,154 tokens}