heartwood-auth

# Heartwood Auth Integration Skill ## When to Activate Activate this skill when: - Adding authentication to a Grove application - Protecting admin routes - Validating user sessions - Setting up OAuth sign-in - Integrating with Heartwood (GroveAuth) ## Overview **Heartwood** is Grove's centralized authentication service powered by Better Auth. | Domain | Purpose | |--------|---------| | `heartwood.grove.place` | Frontend (login UI) | | `auth-api.grove.place` | Backend API | ### Key Features - **OAuth Providers**: Google - **Magic Links**: Click-to-login emails via Resend - **Passkeys**: WebAuthn passwordless authentication - **KV-Cached Sessions**: Sub-100ms validation - **Cross-Subdomain SSO**: Single session across all .grove.place ## Integration Approaches ### Option A: Better Auth Client (Recommended) For new integrations, use Better Auth's client library: ```typescript // src/lib/auth/client.ts import { createAuthClient } from 'better-auth/client'; export const auth = createAuthClient({ baseURL: 'https://auth-api.grove.place' }); // Sign in with Google await auth.signIn.social({ provider: 'google' }); // Get current session const session = await auth.getSession(); // Sign out await auth.signOut(); ``` ### Option B: Cookie-Based SSO (*.grove.place apps) For apps on `.grove.place` subdomains, sessions work automatically via cookies: ```typescript // src/hooks.server.ts import type { Handle } from '@sveltejs/kit'; export const handle: Handle = async ({ event, resolve }) => { // Check session via Heartwood API const sessionCookie = event.cookies.get('better-auth.session_token'); if (sessionCookie) { try { const response = await fetch('https://auth-api.grove.place/api/auth/session', { headers: { Cookie: `better-auth.session_token=${sessionCookie}` } }); if (response.ok) { const data = await response.json(); event.locals.user = data.user; event.locals.session = data.session; } } catch { // Session invalid or expired } } return resolve(event); }; ``` ### Option C: Legacy Token Flow (Backwards Compatible) For existing integrations using the legacy OAuth flow: ```typescript // 1. Redirect to Heartwood login const params = new URLSearchParams({ client_id: 'your-client-id', redirect_uri: 'https://yourapp.grove.place/auth/callback', state: crypto.randomUUID(), code_challenge: await generateCodeChallenge(verifier), code_challenge_method: 'S256' }); redirect(302, `https://auth-api.grove.place/login?${params}`); // 2. Exchange code for tokens (in callback route) const tokens = await fetch('https://auth-api.grove.place/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', code: code, redirect_uri: 'https://yourapp.grove.place/auth/callback', client_id: 'your-client-id', client_secret: env.HEARTWOOD_CLIENT_SECRET, code_verifier: verifier }) }).then(r => r.json()); // 3. Verify token on protected routes const user = await fetch('https://auth-api.grove.place/verify', { headers: { Authorization: `Bearer ${tokens.access_token}` } }).then(r => r.json()); ``` ## Protected Routes Pattern ### SvelteKit Layout Protection ```typescript // src/routes/admin/+layout.server.ts import { redirect } from '@sveltejs/kit'; import type { LayoutServerLoad } from './$types'; export const load: LayoutServerLoad = async ({ locals }) => { if (!locals.user) { throw redirect(302, '/auth/login'); } return { user: locals.user }; }; ``` ### API Route Protection ```typescript // src/routes/api/protected/+server.ts import { json, error } from '@sveltejs/kit'; import type { RequestHandler } from './$types'; export const GET: RequestHandler = async ({ locals }) => { if (!locals.user) { throw error(401, 'Unauthorized'); } return json({ message: 'Protected data', user: locals.user }); }; ``` ## Session Validation ### Via Better Auth Session Endpoint ```typescript async function validateSession(sessionToken: string) { const response = await fetch('https://auth-api.grove.place/api/auth/session', { headers: { Cookie: `better-auth.session_token=${sessionToken}` } }); if (!response.ok) return null; const data = await response.json(); return data.session ? data : null; } ``` ### Via Legacy Verify Endpoint ```typescript async function validateToken(accessToken: string) { const response = await fetch('https://auth-api.grove.place/verify', { headers: { Authorization: `Bearer ${accessToken}` } }); const data = await response.json(); return data.active ? data : null; } ``` ## Client Registration To integrate a new app with Heartwood, you need to register it as a client. ### 1. Generate Client Credentials ```bash # Generate a secure client secret openssl rand -base64 32 # Example: YKzJChC3RPjZvd1f/OD5zUGAvcouOTXG7maQP1ernCg= # Hash it for storage (base64url encoding) echo -n "YOUR_SECRET" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=' ``` ### 2. Register in Heartwood Database ```sql INSERT INTO clients (id, name, client_id, client_secret_hash, redirect_uris, allowed_origins) VALUES ( lower(hex(randomblob(16))), 'Your App Name', 'your-app-id', 'BASE64URL_HASHED_SECRET', '["https://yourapp.grove.place/auth/callback"]', '["https://yourapp.grove.place"]' ); ``` ### 3. Set Secrets on Your App ```bash # Set the client secret on your app wrangler secret put HEARTWOOD_CLIENT_SECRET # Paste: YKzJChC3RPjZvd1f/OD5zUGAvcouOTXG7maQP1ernCg= ``` ## Environment Variables | Variable | Description | |----------|-------------| | `HEARTWOOD_CLIENT_ID` | Your registered client ID | | `HEARTWOOD_CLIENT_SECRET` | Your client secret (never commit!) | ## API Endpoints Reference ### Better Auth Endpoints (Recommended) | Method | Endpoint | Purpose | |--------|----------|---------| | POST | `/api/auth/sign-in/social` | OAuth sign-in | | POST | `/api/auth/sign-in/magic-link` | Magic link sign-in | | POST | `/api/auth/sign-in/passkey` | Passkey sign-in | | GET | `/api/auth/session` | Get current session | | POST | `/api/auth/sign-out` | Sign out | ### Legacy Endpoints | Method | Endpoint | Purpose | |--------|----------|---------| | GET | `/login` | Login page | | POST | `/token` | Exchange code for tokens | | GET | `/verify` | Validate access token | | GET | `/userinfo` | Get user info | ## Best Practices ### DO - Use Better Auth client for new integrations - Validate sessions on every protected request - Use `httpOnly` cookies for token storage - Implement proper error handling for auth failures - Log out users gracefully when sessions expire ### DON'T - Store tokens in localStorage (XSS vulnerable) - Skip session validation on API routes - Hardcode client secrets - Ignore token expiration ## Cross-Subdomain SSO All `.grove.place` apps share the same session cookie automatically: ``` better-auth.session_token (domain=.grove.place) ``` Once a user signs in on any Grove property, they're signed in everywhere. ## Troubleshooting ### "Session not found" errors - Check cookie domain is `.grove.place` - Verify SESSION_KV namespace is accessible - Check session hasn't expired ### OAuth callback errors - Verify redirect_uri matches registered client - Check client_id is correct - Ensure client_secret_hash uses base64url encoding ### Slow authentication - Ensure KV caching is enabled (SESSION_KV binding) - Check for cold start issues (Workers may sleep) ## Related Resources - **Heartwood Spec**: `/Users/autumn/Documents/Projects/GroveAuth/GROVEAUTH_SPEC.md` - **Better Auth Docs**: https://better-auth.com - **Client Setup Guide**: `/Users/autumn/Documents/Projects/GroveAuth/docs/OAUTH_CLIENT_SETUP.md`