nexus/.planning/phases/31-puter.js-zero-config-cloud/31-04-PLAN.md

---
phase: 31-puter.js-zero-config-cloud
plan: "04"
type: execute
wave: 3
depends_on: ["31-03"]
files_modified:
  - server/src/routes/google-oauth.ts
autonomous: false
requirements: [CLOUD-01, CLOUD-02, CLOUD-03, CLOUD-04, CLOUD-05]

must_haves:
  truths:
    - "Complete onboarding flow works end-to-end with Puter provider path"
    - "Google OAuth risk warning is prominently visible before sign-in button enables"
    - "API key entry form accepts and stores keys for subscription providers"
    - "Skip for now creates a working workspace with detected adapter"
    - "All provider credentials are stored server-side, not in localStorage"
---

<objective>
Add the Google OAuth claim endpoint (needed to link OAuth tokens to a companyId after company creation) and perform a human verification of the complete provider selection flow.

Purpose: Final wiring for the Google OAuth flow and visual/functional verification of all CLOUD requirements.
Output: OAuth claim endpoint, human verification of full onboarding wizard
</objective>

<execution_context>
@/home/mikkel/.claude/get-shit-done/workflows/execute-plan.md
@/home/mikkel/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/31-puter.js-zero-config-cloud/31-01-SUMMARY.md
@.planning/phases/31-puter.js-zero-config-cloud/31-02-SUMMARY.md
@.planning/phases/31-puter.js-zero-config-cloud/31-03-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Google OAuth claim endpoint + integration wiring</name>
  <files>server/src/routes/google-oauth.ts</files>
  <read_first>
    server/src/routes/google-oauth.ts,
    server/src/services/google-oauth.ts,
    server/src/services/secrets.ts
  </read_first>
  <action>
    Add a `POST /oauth/google/claim` route to `googleOAuthRoutes`:

    The OAuth callback (from plan 02) stores tokens in a temporary in-memory Map keyed by `stateId`. This claim endpoint moves them to permanent secretService storage under a real companyId.

    1. `assertBoard(req)`.
    2. Extract `stateId` and `companyId` from `req.body`. Validate both are non-empty strings.
    3. `assertCompanyAccess(req, companyId)`.
    4. Look up temporary token storage by `stateId`. If not found, return `res.status(404).json({ error: "OAuth session expired or not found" })`.
    5. Call `googleOAuthService(db).storeTokens(companyId, tokens)`.
    6. Delete from temporary storage.
    7. Return `res.json({ ok: true })`.

    Also update the existing callback handler (GET /oauth/google/callback) to store tokens in the temporary Map (keyed by stateId from the `state` query param) instead of requiring a companyId at callback time. The callback should: exchange code for tokens, store tokens temporarily in a Map `pendingTokens.set(state, { accessToken, refreshToken, createdAt: Date.now() })`, then redirect to `/?google_oauth=success`.

    Add cleanup: in the claim handler, clean up entries older than 10 minutes from `pendingTokens`.
  </action>
  <verify>
    <automated>cd /opt/nexus && grep -c "oauth/google/claim\|pendingTokens" server/src/routes/google-oauth.ts</automated>
  </verify>
  <acceptance_criteria>
    - grep -q "oauth/google/claim" server/src/routes/google-oauth.ts
    - grep -q "pendingTokens" server/src/routes/google-oauth.ts
    - grep -q "storeTokens" server/src/routes/google-oauth.ts
    - grep -q "assertBoard" server/src/routes/google-oauth.ts
  </acceptance_criteria>
  <done>Google OAuth claim endpoint links temporary tokens to a real companyId via secretService; stale entries cleaned up after 10 minutes</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 2: Visual and functional verification of onboarding wizard</name>
  <what-built>
    Complete 4-step onboarding wizard with provider selection:
    - Step 1: Hardware detection (unchanged from Phase 30)
    - Step 2: Mode selection (unchanged from Phase 30)
    - Step 3: Provider selection (NEW) with Puter, Google, and API Key options
    - Step 4: Root directory (unchanged)
    Plus: server-side Puter proxy, Google OAuth, API key storage, cost tracking
  </what-built>
  <how-to-verify>
    1. Start Nexus dev server: `cd /opt/nexus && pnpm dev`
    2. Open browser to localhost:3100 in an incognito window (fresh state)
    3. The onboarding wizard should open automatically
    4. Verify step indicator shows "Step 1 of 4"
    5. Click Continue through Step 1 (hardware) and Step 2 (mode)
    6. On Step 3 ("Choose a provider"):
       a. Verify three provider cards are visible (Puter, Google, API Key)
       b. Verify "Skip for now" button is visible below cards
       c. Click the Puter card — verify it gets the selected border highlight
       d. Verify "Continue with Puter" button appears
       e. Click the Google card — verify policy risk warning appears with red/amber text
       f. Verify "Sign in with Google" button is disabled for ~3 seconds
       g. Click the API key card — verify inline form with provider dropdown and key input appears
       h. If any adapters are detected (Hermes, Claude Code), verify "detected" badges appear
       i. Click "Skip for now" to advance to Step 4
    7. On Step 4: verify root directory form appears, enter a path, click "Get Started"
    8. Verify workspace is created and you reach the dashboard
    9. (Optional) If you have a Puter.com account: repeat flow, select Puter, click "Continue with Puter", verify popup opens
  </how-to-verify>
  <resume-signal>Type "approved" or describe issues to fix</resume-signal>
</task>

</tasks>

<verification>
- Full onboarding wizard flow works end-to-end
- All 5 CLOUD requirements are addressed:
  - CLOUD-01: Puter zero-config path (popup -> token -> server proxy)
  - CLOUD-02: Server-proxied adapter with cost tracking
  - CLOUD-03: Google OAuth PKCE with risk warning
  - CLOUD-04: Auto-detected tools show badges
  - CLOUD-05: API key entry for subscription providers
</verification>

<success_criteria>
- Human approves the visual and functional verification
- 4-step wizard works with all provider paths
- No console errors in browser
- Server logs show no unhandled exceptions
</success_criteria>

<output>
After completion, create `.planning/phases/31-puter.js-zero-config-cloud/31-04-SUMMARY.md`
</output>