Skip to content
heartwood-auth logo

Heartwood Auth Integration Skill

heartwood-auth

Integrate Heartwood (GroveAuth) authentication into Grove applications. Use when adding sign-in, protecting routes, or validating sessions in any Grove property.

SKILL.md

Full skill instructions

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.

DomainPurpose
heartwood.grove.placeFrontend (login UI)
auth-api.grove.placeBackend 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 or expired
    }
  }

  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

VariableDescription
HEARTWOOD_CLIENT_IDYour registered client ID
HEARTWOOD_CLIENT_SECRETYour client secret (never commit!)

API Endpoints Reference

Better Auth Endpoints (Recommended)

MethodEndpointPurpose
POST/​api/​auth/​sign-in/​socialOAuth sign-in
POST/​api/​auth/​sign-in/​magic-linkMagic link sign-in
POST/​api/​auth/​sign-in/​passkeyPasskey sign-in
GET/​api/​auth/​sessionGet current session
POST/​api/​auth/​sign-outSign out

Legacy Endpoints

MethodEndpointPurpose
GET/​loginLogin page
POST/​tokenExchange code for tokens
GET/​verifyValidate access token
GET/​userinfoGet 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

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View