Add comprehensive skill documentation for Grove ecosystem

.claude/skills/heartwood-auth/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: heartwood-auth
+description: Integrate Heartwood (GroveAuth) authentication into Grove applications. Use when adding sign-in, protecting routes, or validating sessions in any Grove property.
+---
+
+# 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`