# Electron Clerk Auth

> Use when working on HyperCoder's Clerk-based authentication across Electron, the marketing auth page, and Convex. Covers packaged Electron auth, custom protocol and localhost callback flows, Clerk sign-in tokens, production Clerk domain and env wiring, GitHub social token access, and debugging prod-only auth failures.

- Skill: `hypersocialinc/electron-clerk-auth` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hypersocialinc/electron-clerk-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hypersocialinc/electron-clerk-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: hypersocialinc (https://skillmd.com/u/hypersocialinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hypersocialinc/electron-clerk-auth

---


# Electron Clerk Auth

Use this skill for any auth work that touches:
- `apps/electron` Clerk session setup or GitHub connect UI
- `apps/marketing/app/auth/electron` sign-in token issuance
- `convex` auth provider or GitHub token access
- packaged Electron auth failures that do not reproduce on localhost
- Clerk production configuration questions for `clerk.hypercoder.app`

## Workflow

1. Identify the failing layer before editing anything.
   Electron UI entrypoints, Electron main process, marketing auth page, Convex backend, or Clerk dashboard/config.
2. Read the right reference file.
   `references/architecture.md` for end-to-end flow and file ownership.
   `references/production-setup.md` for env vars, Clerk dashboard requirements, and cross-service invariants.
   `references/debugging.md` for symptom-based diagnosis and validation steps.
3. Preserve the current architecture unless you have a strong reason to change it.
   Packaged Electron auth is not standard web Clerk auth. It relies on a localhost callback server, a sign-in token minted on the marketing app, renderer ticket consumption, and a main-process HTTPS fetch proxy for Clerk FAPI requests.
4. Validate at the right level.
   For code-only changes, run Electron typecheck and targeted tests first.
   For transport or auth-init changes, also run `pnpm --filter @hypersurge/electron build:ci`.
   For production-only fixes, prefer a real packaged auth smoke test before declaring success.

## Non-Negotiable Invariants

- Electron does not start GitHub OAuth with `authenticateWithRedirect` inside the renderer.
  It opens the system browser to the marketing auth page.
- The marketing auth page is responsible for the normal web Clerk login and for minting the Clerk `sign_in_token`.
- Electron consumes that token with `signIn.create({ strategy: "ticket", ticket })`.
- Packaged Electron Clerk HTTPS requests are proxied through Electron main to avoid renderer CORS failures.
- Convex must trust the same Clerk issuer domain that the marketing app and Electron build are using.
- Treat Clerk `__unstable__` hooks in Electron as pinned implementation details. Re-verify them on Clerk upgrades.

## Key Files

- `apps/electron/src/main.tsx`
- `apps/electron/src/lib/auth.ts`
- `apps/electron/src/lib/clerkElectron.ts`
- `apps/electron/src/lib/clerkElectronFetch.ts`
- `apps/electron/src/hooks/useAuthDeepLink.ts`
- `apps/electron/electron/main.ts`
- `apps/electron/electron/preload.ts`
- `apps/marketing/app/auth/electron/page.tsx`
- `apps/marketing/app/auth/electron/actions.ts`
- `convex/auth.config.ts`
- `convex/github.ts`

## Validation Commands

For Electron-only changes:
```bash
pnpm --filter @hypersurge/electron typecheck
pnpm --filter @hypersurge/electron exec vitest run src/__tests__/lib/clerkElectronFetch.test.ts
pnpm --filter @hypersurge/electron build:ci
```

For marketing auth page changes:
```bash
pnpm --filter @hypersurge/marketing build
# Then test the full browser -> Electron sign-in flow
```

For Convex auth config changes:
```bash
npx convex deploy  # or convex dev for local
# Verify Clerk issuer domain and secret key match production
```

If the touched layer is outside Electron (marketing or Convex), validate cross-service by running the full packaged sign-in flow — Electron typecheck alone won't catch mismatched keys or issuer domains.

If the issue is production-only, do not stop at unit/build validation. Run a packaged Electron sign-in smoke test.