ICCery-CPU/.grok/skills/auth/references/prewired-and-env.md

What's pre-wired, and the env vars

src/lib/auth/

File	Use it for
client.ts	Browser client. signIn(providerId), signOut(), authEnabled, GROK_PROVIDERS.
server.ts	The Better Auth instance (server-only). Do not edit or rewrite. Import only from /api/auth/$.
email-password.ts	Only place to enable local email/password (emailAndPasswordEnabled = true).
popup.server.ts	Live-preview popup handler (server-only). Already wired by the Vite plugin — do not create a route for it.
providers.ts	GROK_PROVIDERS — the fixed broker upstream list (Google and X only; don't add others).
use-current-user.ts	useCurrentUser() / useCurrentUserState() React hooks.
gates.tsx	SignedIn, SignedOut, RedirectToSignIn, UserButton.
middleware.ts	authMiddleware for server functions → verified context.userId.
verify.server.ts	requireUserId() / getSessionUser() (server-only) for manual wiring.

How each mode gets its credentials

• Live preview (*.grok-sandbox.com): the app is an embedded iframe, so sign-in opens a popup (a top-level redirect to the broker can't work inside the iframe) and federates via a baked shared preview client (src/lib/auth/preview.ts). The handler 302s straight to the broker/upstream login; on return the popup posts the session bearer back in a tiny HTML page. Sessions (and email/password users) persist in the app's embedded PGLite DB — the SAME DB as app data — and, since the iframe's cookies are partitioned, ride that bearer token; all of it lives in src/lib/auth. Restarting the preview resets the DB.
• Deployed: the deployer injects a per-app client + DATABASE_URL, so sign-in persists identities in Postgres.

Env vars — do not create a .env file

Never write a .env / .env.local / .env.example for auth (or anything else) in this sandbox. Live preview sign-in works out of the box with zero env configuration: the server falls back to the baked preview client in src/lib/auth/preview.ts, derives the *.grok-sandbox.com origin per-request, mints a process-stable session secret, and persists sessions in embedded PGLite. Deployed apps get GROK_AUTH_* / BETTER_AUTH_* / DATABASE_URL injected by the platform — still not something you write into a file.

Optional process-env knobs (platform / rare overrides only — do not put these in a file you create):

Var	Where	Purpose
VITE_AUTH_ENABLED	client	"false" in the shipped .grok/app-env.json (dev user); drop the key to turn sign-in ON. Only client-visible auth flag
BETTER_AUTH_URL	server	app's own public origin; unset in preview (origin is derived per-request)
BETTER_AUTH_SECRET	server	signs this app's own sessions (process-stable fallback in preview; survives HMR)
GROK_AUTH_ISSUER	server	the shared broker (defaults to https://auth.grok.me)
GROK_AUTH_CLIENT_ID / GROK_AUTH_CLIENT_SECRET	server	per-app client (falls back to the preview client)
DATABASE_URL	server	when deployed, Better Auth persists here (preview persists to the embedded PGLite — same DB as app data)

Never expose a non-VITE_ var to the client. The preview client id/secret live server-only in src/lib/auth/preview.ts.