Heartwood Auth Integration Skill Skill

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

Agent Skills: Heartwood Auth Integration Skill

Install this agent skill to your local

Skill Files