Grove Auth Integration

Add Heartwood authentication to a Grove property — from client registration through production deployment.

When to Activate

• User says "add auth to this project" or "wire up Heartwood"
• User is building a new Grove property that needs login
• User needs to register a new OAuth client with Heartwood
• User explicitly calls /grove-auth-integration
• User mentions needing sign-in, protected routes, or session validation
• User says "integrate GroveAuth" or "add login"

---

Key URLs

Service	URL	Purpose
Login UI	https://heartwood.grove.place	Where users authenticate
API	https://auth-api.grove.place	Token exchange, verify, sessions
D1 Database	groveauth (via wrangler)	Client registration

---

The Pipeline

Identify → Register Client → Configure Secrets → Write Code → Wire Wrangler → Test

Error Handling in Auth Flows: Auth errors MUST use the AUTH_ERRORS Signpost catalog — never bare redirect with ad-hoc error strings.

import {
    AUTH_ERRORS,
    getAuthError,
    logAuthError,
    buildErrorParams,
} from "@autumnsgrove/lattice/heartwood";

// In callback — map OAuth error to structured code
if (errorParam) {
    const authError = getAuthError(errorParam);
    logAuthError(authError, { path: "/auth/callback" });
    redirect(302, `/login?${buildErrorParams(authError)}`);
}

See AgentUsage/error_handling.md for the full Signpost reference.

Type-Safe Error Handling in Catch Blocks: Always use Rootwork type guards in catch blocks instead of manual property checks. Import isRedirect() and isHttpError() from @autumnsgrove/lattice/server:

import { isRedirect, isHttpError } from "@autumnsgrove/lattice/server";

try {
    // ... auth flow code
} catch (err) {
    if (isRedirect(err)) throw err; // Re-throw SvelteKit redirects
    if (isHttpError(err)) {
        // Handle HTTP errors with proper status and message
    }
    redirect(302, "/?error=auth_failed");
}

---

Step 1: Identify the Integration

Ask the user (or determine from context):

1. Project name — The Cloudflare Pages/Workers project name
2. Client ID — A simple slug (e.g., grove-plant, grove-domains, arbor-admin)
3. Site URL — Production URL (e.g., https://plant.grove.place)
4. Callback path — Usually /auth/callback
5. Project type — SvelteKit Pages (most common), Workers, or other
6. Session approach — OAuth tokens (standard) or SessionDO (faster, same-account only)

---

Step 2: Register the OAuth Client

2a. Generate client secret

CLIENT_SECRET=$(openssl rand -base64 32)
echo "Client Secret: $CLIENT_SECRET"

Save this value — you'll need it for both the client secrets AND the database hash.

2b. Generate base64url hash

CRITICAL: Heartwood uses base64url encoding — dashes (-), underscores (_), NO padding (=).

CLIENT_SECRET_HASH=$(echo -n "$CLIENT_SECRET" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')
echo "Secret Hash: $CLIENT_SECRET_HASH"

Format	Example	Correct?
base64url	Sdgtaokie8-H7GKw-tn0S_6XNSh1rdv	YES
base64	Sdgtaokie8+H7GKw+tn0S/6XNSh1rdv=	NO
hex	49d82d6a89227bcf87ec62b0...	NO

2c. Insert into Heartwood database

wrangler d1 execute groveauth --remote --command="
INSERT INTO clients (id, name, client_id, client_secret_hash, redirect_uris, allowed_origins)
VALUES (
  '$(uuidgen | tr '[:upper:]' '[:lower:]')',
  'DISPLAY_NAME',
  'CLIENT_ID',
  'BASE64URL_HASH',
  '[\"https://SITE_URL/auth/callback\", \"http://localhost:5173/auth/callback\"]',
  '[\"https://SITE_URL\", \"http://localhost:5173\"]'
)
ON CONFLICT(client_id) DO UPDATE SET
  client_secret_hash = excluded.client_secret_hash,
  redirect_uris = excluded.redirect_uris,
  allowed_origins = excluded.allowed_origins;
"

Always include localhost in redirect_uris and allowed_origins for development.

---

Step 3: Configure Secrets on the Client

For Pages projects (SvelteKit):

echo "CLIENT_ID" | wrangler pages secret put GROVEAUTH_CLIENT_ID --project PROJECT_NAME
echo "CLIENT_SECRET" | wrangler pages secret put GROVEAUTH_CLIENT_SECRET --project PROJECT_NAME
echo "https://SITE_URL/auth/callback" | wrangler pages secret put GROVEAUTH_REDIRECT_URI --project PROJECT_NAME
echo "https://auth-api.grove.place" | wrangler pages secret put GROVEAUTH_URL --project PROJECT_NAME

For Workers projects:

cd worker-directory
echo "CLIENT_ID" | wrangler secret put GROVEAUTH_CLIENT_ID
echo "CLIENT_SECRET" | wrangler secret put GROVEAUTH_CLIENT_SECRET

---

Step 4: Write the Auth Code (SvelteKit)

Create these files in the SvelteKit project:

4a. Login initiation route: src/routes/auth/+server.ts

/**
 * OAuth Initiation - Start Heartwood OAuth flow
 * Redirects to GroveAuth with PKCE parameters.
 */
import { redirect } from "@sveltejs/kit";
import type { RequestHandler } from "./$types";

function generateRandomString(length: number): string {
    const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
    const randomValues = crypto.getRandomValues(new Uint8Array(length));
    return Array.from(randomValues, (v) => charset[v % charset.length]).join("");
}

async function generatePKCE(): Promise<{
    verifier: string;
    challenge: string;
}> {
    const verifier = generateRandomString(64);
    const encoder = new TextEncoder();
    const data = encoder.encode(verifier);
    const hash = await crypto.subtle.digest("SHA-256", data);
    const challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
        .replace(/\+/g, "-")
        .replace(/\//g, "_")
        .replace(/=/g, "");
    return { verifier, challenge };
}

export const GET: RequestHandler = async ({ url, cookies, platform }) => {
    const env = platform?.env as Record<string, string> | undefined;
    const authBaseUrl = env?.GROVEAUTH_URL || "https://auth-api.grove.place";
    const clientId = env?.GROVEAUTH_CLIENT_ID || "YOUR_CLIENT_ID";
    const appBaseUrl = env?.PUBLIC_APP_URL || "https://YOUR_SITE_URL";
    const redirectUri = `${appBaseUrl}/auth/callback`;

    const { verifier, challenge } = await generatePKCE();
    const state = generateRandomString(32);

    const isProduction = url.hostname !== "localhost" && url.hostname !== "127.0.0.1";
    const cookieOptions = {
        path: "/",
        httpOnly: true,
        secure: isProduction,
        sameSite: "lax" as const,
        maxAge: 60 * 10, // 10 minutes
    };

    cookies.set("auth_state", state, cookieOptions);
    cookies.set("auth_code_verifier", verifier, cookieOptions);

    const authUrl = new URL(`${authBaseUrl}/login`);
    authUrl.searchParams.set("client_id", clientId);
    authUrl.searchParams.set("redirect_uri", redirectUri);
    authUrl.searchParams.set("response_type", "code");
    authUrl.searchParams.set("scope", "openid profile email");
    authUrl.searchParams.set("state", state);
    authUrl.searchParams.set("code_challenge", challenge);
    authUrl.searchParams.set("code_challenge_method", "S256");

    redirect(302, authUrl.toString());
};

4b. Callback handler: src/routes/auth/callback/+server.ts

/**
 * OAuth Callback - Handle Heartwood OAuth response
 * Exchanges authorization code for tokens and creates session.
 */
import { redirect } from "@sveltejs/kit";
import { isRedirect } from "@autumnsgrove/lattice/server";
import type { RequestHandler } from "./$types";

export const GET: RequestHandler = async ({ url, cookies, platform }) => {
    const code = url.searchParams.get("code");
    const state = url.searchParams.get("state");
    const errorParam = url.searchParams.get("error");

    if (errorParam) {
        redirect(302, `/?error=${encodeURIComponent(errorParam)}`);
    }

    // Validate state (CSRF protection)
    const savedState = cookies.get("auth_state");
    if (!state || state !== savedState) {
        redirect(302, "/?error=invalid_state");
    }

    // Get PKCE verifier
    const codeVerifier = cookies.get("auth_code_verifier");
    if (!codeVerifier || !code) {
        redirect(302, "/?error=missing_credentials");
    }

    // Clear auth cookies immediately
    cookies.delete("auth_state", { path: "/" });
    cookies.delete("auth_code_verifier", { path: "/" });

    const env = platform?.env as Record<string, string> | undefined;
    const authBaseUrl = env?.GROVEAUTH_URL || "https://auth-api.grove.place";
    const clientId = env?.GROVEAUTH_CLIENT_ID || "YOUR_CLIENT_ID";
    const clientSecret = env?.GROVEAUTH_CLIENT_SECRET || "";
    const appBaseUrl = env?.PUBLIC_APP_URL || "https://YOUR_SITE_URL";
    const redirectUri = `${appBaseUrl}/auth/callback`;

    try {
        // Exchange code for tokens
        const tokenResponse = await fetch(`${authBaseUrl}/token`, {
            method: "POST",
            headers: { "Content-Type": "application/x-www-form-urlencoded" },
            body: new URLSearchParams({
                grant_type: "authorization_code",
                code,
                redirect_uri: redirectUri,
                client_id: clientId,
                client_secret: clientSecret,
                code_verifier: codeVerifier,
            }),
        });

        if (!tokenResponse.ok) {
            redirect(302, "/?error=token_exchange_failed");
        }

        const tokens = (await tokenResponse.json()) as {
            access_token: string;
            refresh_token?: string;
            expires_in?: number;
        };

        // Fetch user info
        const userinfoResponse = await fetch(`${authBaseUrl}/userinfo`, {
            headers: { Authorization: `Bearer ${tokens.access_token}` },
        });

        if (!userinfoResponse.ok) {
            redirect(302, "/?error=userinfo_failed");
        }

        const userinfo = (await userinfoResponse.json()) as {
            sub?: string;
            id?: string;
            email: string;
            name?: string;
            email_verified?: boolean;
        };

        const userId = userinfo.sub || userinfo.id;
        const email = userinfo.email;

        if (!userId || !email) {
            redirect(302, "/?error=incomplete_profile");
        }

        // Set session cookies
        const isProduction = url.hostname !== "localhost" && url.hostname !== "127.0.0.1";
        const cookieOptions = {
            path: "/",
            httpOnly: true,
            secure: isProduction,
            sameSite: "lax" as const,
            maxAge: 60 * 60 * 24 * 7, // 7 days
        };

        cookies.set("access_token", tokens.access_token, {
            ...cookieOptions,
            maxAge: tokens.expires_in || 3600,
        });

        if (tokens.refresh_token) {
            cookies.set("refresh_token", tokens.refresh_token, {
                ...cookieOptions,
                maxAge: 60 * 60 * 24 * 30, // 30 days
            });
        }

        // TODO: Create local session or onboarding record as needed
        // This varies by property — adapt to your app's needs

        redirect(302, "/dashboard"); // Or wherever authenticated users go
    } catch (err) {
        // Type-safe error handling with Rootwork type guards
        if (isRedirect(err)) throw err; // Re-throw SvelteKit redirects
        redirect(302, "/?error=auth_failed");
    }
};

4c. Session validation hook: src/hooks.server.ts

Choose ONE approach:

Option A: Token verification (works cross-account)

import type { Handle } from "@sveltejs/kit";

export const handle: Handle = async ({ event, resolve }) => {
    const accessToken = event.cookies.get("access_token");

    if (accessToken) {
        try {
            const env = event.platform?.env as Record<string, string> | undefined;
            const authBaseUrl = env?.GROVEAUTH_URL || "https://auth-api.grove.place";

            const response = await fetch(`${authBaseUrl}/verify`, {
                headers: { Authorization: `Bearer ${accessToken}` },
            });

            if (response.ok) {
                const result = await response.json();
                if (result.active) {
                    event.locals.user = {
                        id: result.sub,
                        email: result.email,
                        name: result.name,
                    };
                }
            }
        } catch {
            // Token invalid or expired — user remains unauthenticated
        }
    }

    return resolve(event);
};

Option B: SessionDO validation (faster, same Cloudflare account only)

Requires a service binding in wrangler.toml (see Step 5).

import type { Handle } from "@sveltejs/kit";

export const handle: Handle = async ({ event, resolve }) => {
    const cookieHeader = event.request.headers.get("Cookie") || "";

    // Only validate if grove_session or access_token cookie exists
    if (cookieHeader.includes("grove_session") || cookieHeader.includes("access_token")) {
        try {
            const env = event.platform?.env as any;

            // Use service binding for sub-100ms validation
            const response = await env.AUTH.fetch("https://auth-api.grove.place/session/validate", {
                method: "POST",
                headers: { Cookie: cookieHeader },
            });

            if (response.ok) {
                const { valid, user } = await response.json();
                if (valid && user) {
                    event.locals.user = {
                        id: user.id,
                        email: user.email,
                        name: user.name,
                    };
                }
            }
        } catch {
            // Session invalid — user remains unauthenticated
        }
    }

    return resolve(event);
};

4d. Type definitions: src/app.d.ts

declare global {
    namespace App {
        interface Locals {
            user?: {
                id: string;
                email: string;
                name?: string | null;
            };
        }
        interface Platform {
            env?: {
                GROVEAUTH_URL?: string;
                GROVEAUTH_CLIENT_ID?: string;
                GROVEAUTH_CLIENT_SECRET?: string;
                PUBLIC_APP_URL?: string;
                AUTH?: Fetcher; // Service binding (Option B only)
                DB?: D1Database;
                [key: string]: unknown;
            };
        }
    }
}

export {};

4e. Protected route layout: 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) {
        redirect(302, "/auth");
    }
    return { user: locals.user };
};

4f. Logout route: src/routes/auth/logout/+server.ts

import { redirect } from "@sveltejs/kit";
import type { RequestHandler } from "./$types";

export const POST: RequestHandler = async ({ cookies, platform }) => {
    const accessToken = cookies.get("access_token");

    if (accessToken) {
        const env = platform?.env as Record<string, string> | undefined;
        const authBaseUrl = env?.GROVEAUTH_URL || "https://auth-api.grove.place";

        // Revoke token at Heartwood
        await fetch(`${authBaseUrl}/logout`, {
            method: "POST",
            headers: { Authorization: `Bearer ${accessToken}` },
        }).catch(() => {}); // Best-effort
    }

    // Clear all auth cookies
    cookies.delete("access_token", { path: "/" });
    cookies.delete("refresh_token", { path: "/" });

    redirect(302, "/");
};

---

Step 5: Wire Up wrangler.toml

Add these to the project's wrangler.toml:

# Heartwood (GroveAuth) - Service Binding for fast session validation
# Only works for projects in the same Cloudflare account
[[services]]
binding = "AUTH"
service = "groveauth"

# Secrets (configured via wrangler pages secret / Cloudflare Dashboard):
# - GROVEAUTH_URL = https://auth-api.grove.place
# - GROVEAUTH_CLIENT_ID = your-client-id
# - GROVEAUTH_CLIENT_SECRET = (generated in Step 2)
# - GROVEAUTH_REDIRECT_URI = https://yoursite.com/auth/callback
# - PUBLIC_APP_URL = https://yoursite.com

---

Step 6: Test the Flow

1. Deploy the project (or run locally with pnpm dev)
2. Navigate to /auth — should redirect to Heartwood login
3. Authenticate with Google (or other configured provider)
4. Should redirect back to /auth/callback
5. Should set cookies and redirect to protected area
6. Visit /admin (protected) — should show authenticated content
7. Logout via POST to /auth/logout — should clear session

---

Token Lifecycle

Token	Lifetime	Storage	Refresh
Access Token	1 hour	httpOnly cookie	Via refresh token
Refresh Token	30 days	httpOnly cookie	Re-login required
PKCE Verifier	10 minutes	httpOnly cookie	Single-use
State	10 minutes	httpOnly cookie	Single-use

---

Session Validation Approaches

Approach	Speed	Requirement	Use When
Token Verify (/verify)	~50-150ms	Network call	Cross-account, external services
SessionDO (/session/validate)	~5-20ms	Service binding	Same Cloudflare account (recommended)
Cookie SSO (.grove.place)	~0ms (local)	Same domain	All *.grove.place properties

For Grove properties on .grove.place subdomains, the grove_session cookie is shared automatically across all subdomains.

---

Checklist

Before going live, verify:

• Client registered in Heartwood D1 (clients table)
• Secret hash uses base64url encoding (dashes, underscores, no padding)
• redirect_uris includes BOTH production AND localhost
• allowed_origins includes BOTH production AND localhost
• Secrets set via wrangler pages secret put (NOT in wrangler.toml!)
• PKCE flow generates fresh verifier per login attempt
• State parameter validated in callback (CSRF protection)
• Auth cookies cleared immediately after code exchange
• Protected routes check locals.user and redirect if missing
• Logout revokes token at Heartwood AND clears local cookies
• Cookie secure flag is true in production, false in localhost

---

Troubleshooting

"Invalid client credentials" (401)

Almost always a hash format mismatch. Regenerate with the exact base64url command in Step 2b.

"Invalid redirect_uri"

The callback URL must EXACTLY match what's in the redirect_uris JSON array in the database. Check trailing slashes, protocol, and port.

"Invalid state" on callback

The state cookie expired (10min TTL) or was lost. Check:

• Cookie domain matches the callback domain
• No redirect loops between domains consuming the cookie early

"Code verifier required"

The PKCE verifier cookie wasn't sent with the callback request. Ensure:

• Cookie path is / (not /auth)
• Cookie domain matches callback domain
• No third-party cookie blocking

Session validation returns 401

• Token may have expired (1hr lifetime) — implement refresh logic
• Service binding may not be configured — check wrangler.toml
• Cookie domain mismatch — .grove.place cookies only work on subdomains

"CORS error" on auth API calls

Add your domain to allowed_origins in the Heartwood clients table.

---

Anti-Patterns

Don't do these:

• Don't store client_secret in wrangler.toml or source code
• Don't skip PKCE — it's required, not optional
• Don't reuse state or verifier values across login attempts
• Don't store tokens in localStorage (XSS-vulnerable)
• Don't skip state validation in the callback (enables CSRF)
• Don't hard-code auth-api.grove.place — use the env var for flexibility
• Don't forget localhost in redirect_uris (you'll need it for dev)

---

Authentication should be invisible until it's needed. Let Heartwood handle the complexity.