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: // 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: // 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, expired, or network error — silently continue } } return resolve ( event ) ; } ; Option C: Legacy Token Flow (Backwards Compatible) For existing integrations using the legacy OAuth flow: // 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 // 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 // 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 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 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

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 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

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 Type-Safe Error Handling Use Rootwork type guards in catch blocks instead of manual error type narrowing. Import from @autumnsgrove/lattice/server : import { isRedirect , isHttpError } from "@autumnsgrove/lattice/server" ; try { // ... auth flow } catch ( err ) { if ( isRedirect ( err ) ) throw err ; // Re-throw SvelteKit redirects if ( isHttpError ( err ) ) { // Handle HTTP errors with proper status code console . error ( Auth failed: ${ err . status } ${ err . body } ) ; } // Fallback error handling } Reading session data from KV/cache: Use safeJsonParse() for type-safe deserialization: import { safeJsonParse } from "@autumnsgrove/lattice/server" ; import { z } from "zod" ; const sessionSchema = z . object ( { userId : z . string ( ) , email : z . string ( ) . email ( ) , } ) ; const rawSession = await kv . get ( "session:123" ) ; const session = safeJsonParse ( rawSession , sessionSchema ) ; if ( session ) { event . locals . user = { id : session . userId , email : session . email } ; } 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) Error Codes (HW-AUTH Catalog) Heartwood has its own Signpost error catalog with 16 codes: import { AUTH_ERRORS , getAuthError , logAuthError , buildErrorParams , } from "@autumnsgrove/lattice/heartwood" ; Key error codes: Code Key When HW-AUTH-001 ACCESS_DENIED User lacks permission HW-AUTH-002 PROVIDER_ERROR OAuth provider failed HW-AUTH-004 REDIRECT_URI_MISMATCH Callback URL doesn't match registered client HW-AUTH-020 NO_SESSION No session cookie found HW-AUTH-021 SESSION_EXPIRED Session timed out HW-AUTH-022 INVALID_TOKEN Token verification failed HW-AUTH-023 TOKEN_EXCHANGE_FAILED Code-for-token exchange failed Mapping OAuth errors to Signpost codes: // In callback handler — map OAuth error param to structured error const authError = getAuthError ( errorParam ) ; // e.g. "access_denied" → AUTH_ERRORS.ACCESS_DENIED logAuthError ( authError , { path : "/auth/callback" , ip } ) ; redirect ( 302 , /login? ${ buildErrorParams ( authError ) } ) ; Number ranges: 001-019 infrastructure, 020-039 session/token, 040+ reserved. See AgentUsage/error_handling.md for the full Signpost reference. 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