@kazzle/app 0.1.926 → 0.1.929

package/dist/auth-react.d.ts

@@ -0,0 +1,20 @@
+import type { AppUser } from './auth-schema';
+export type { AppUser } from './auth-schema';
+/** Login methods the Kazzle broker supports. Email arrives with the email primitive. */
+export type KazzleLoginMethod = 'google';
+/**
+ * Start sign-in. Redirects the browser through the Kazzle broker to the named
+ * method's login, then back to `callbackURL` (default: the page root).
+ */
+export declare function signInWithKazzle(_method?: KazzleLoginMethod, opts?: {
+    callbackURL?: string;
+}): Promise<unknown>;
+/** Sign the current user out of this app. */
+export declare function signOutOfApp(): Promise<unknown>;
+/**
+ * The signed-in end user, or null. Reactive: re-renders on sign-in/out.
+ * While the session is still loading, returns null (render logged-out UI).
+ */
+export declare function useAppUser(): AppUser | null;
+/** Session loading state, for UIs that want a spinner instead of a flash of logged-out. */
+export declare function useAppUserPending(): boolean;

package/dist/auth-react.js

@@ -0,0 +1,52 @@
+// @kazzle/app/auth/react — app login, browser half.
+//
+// All the agent touches: `useAppUser()` for who's signed in, and
+// `signInWithKazzle()` / `signOutOfApp()` on buttons. The client talks to the
+// app's own /api/auth/* routes (same origin — the UI dev server proxies them
+// to the process; in prod both share one host), so there is no base URL to
+// configure and no auth code to write.
+import { createAuthClient } from 'better-auth/react';
+import { genericOAuthClient } from 'better-auth/client/plugins';
+// Module-private: Better Auth's inferred client type is not portable across
+// d.ts emit. The SDK contract is the functions below, not the raw client.
+const authClient = createAuthClient({
+    plugins: [genericOAuthClient()],
+});
+/**
+ * Start sign-in. Redirects the browser through the Kazzle broker to the named
+ * method's login, then back to `callbackURL` (default: the page root).
+ */
+export function signInWithKazzle(_method = 'google', opts) {
+    // The method is fixed server-side today (authorizationUrlParams). The
+    // parameter exists so login buttons already state their intent — when the
+    // broker gains methods, this maps per-call without app code changing shape.
+    return authClient.signIn.oauth2({
+        providerId: 'kazzle',
+        callbackURL: opts?.callbackURL ?? '/',
+    });
+}
+/** Sign the current user out of this app. */
+export function signOutOfApp() {
+    return authClient.signOut();
+}
+/**
+ * The signed-in end user, or null. Reactive: re-renders on sign-in/out.
+ * While the session is still loading, returns null (render logged-out UI).
+ */
+export function useAppUser() {
+    const { data } = authClient.useSession();
+    const user = data?.user;
+    if (!user)
+        return null;
+    return {
+        id: user.id,
+        email: user.email,
+        emailVerified: user.emailVerified,
+        name: user.name ?? null,
+        image: user.image ?? null,
+    };
+}
+/** Session loading state, for UIs that want a spinner instead of a flash of logged-out. */
+export function useAppUserPending() {
+    return authClient.useSession().isPending;
+}

package/dist/auth-schema.d.ts

@@ -0,0 +1,12 @@
+/** Identity claims the app sees for a signed-in end user. */
+export interface AppUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+}
+/** Postgres schema the auth tables live in. */
+export declare const AUTH_PG_SCHEMA = "auth";
+/** Idempotent DDL for the auth tables. Run against the app's own database. */
+export declare const AUTH_SCHEMA_SQL = "\nCREATE SCHEMA IF NOT EXISTS auth;\n\nCREATE TABLE IF NOT EXISTS auth.\"user\" (\n  id text PRIMARY KEY,\n  name text,\n  email text NOT NULL UNIQUE,\n  \"emailVerified\" boolean NOT NULL DEFAULT false,\n  image text,\n  \"createdAt\" timestamptz NOT NULL DEFAULT now(),\n  \"updatedAt\" timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE TABLE IF NOT EXISTS auth.\"session\" (\n  id text PRIMARY KEY,\n  \"expiresAt\" timestamptz NOT NULL,\n  token text NOT NULL UNIQUE,\n  \"ipAddress\" text,\n  \"userAgent\" text,\n  \"userId\" text NOT NULL REFERENCES auth.\"user\"(id) ON DELETE CASCADE,\n  \"createdAt\" timestamptz NOT NULL DEFAULT now(),\n  \"updatedAt\" timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS session_user_id_idx ON auth.\"session\"(\"userId\");\n\nCREATE TABLE IF NOT EXISTS auth.\"account\" (\n  id text PRIMARY KEY,\n  \"accountId\" text NOT NULL,\n  \"providerId\" text NOT NULL,\n  \"userId\" text NOT NULL REFERENCES auth.\"user\"(id) ON DELETE CASCADE,\n  \"accessToken\" text,\n  \"refreshToken\" text,\n  \"idToken\" text,\n  \"accessTokenExpiresAt\" timestamptz,\n  \"refreshTokenExpiresAt\" timestamptz,\n  scope text,\n  password text,\n  \"createdAt\" timestamptz NOT NULL DEFAULT now(),\n  \"updatedAt\" timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS account_user_id_idx ON auth.\"account\"(\"userId\");\n\nCREATE TABLE IF NOT EXISTS auth.\"verification\" (\n  id text PRIMARY KEY,\n  identifier text NOT NULL,\n  value text NOT NULL,\n  \"expiresAt\" timestamptz NOT NULL,\n  \"createdAt\" timestamptz NOT NULL DEFAULT now(),\n  \"updatedAt\" timestamptz NOT NULL DEFAULT now()\n);\n";

package/dist/auth-schema.js

@@ -0,0 +1,66 @@
+// @kazzle/app/auth/schema — the app-login auth tables, as SQL.
+//
+// Dependency-free on purpose: the server's login template hook runs this SQL
+// at checkout (and the agent runs it when adding `appLogin` to an existing
+// app) without pulling better-auth/pg into the importer.
+//
+// The tables live in a dedicated `auth` Postgres schema inside the app's own
+// database — Supabase convention: app code never modifies these tables, it
+// extends by referencing `auth."user"(id)` from its own tables in the public
+// schema. Shapes match Better Auth core (user/session/account/verification,
+// camelCase quoted columns); `@kazzle/app/auth` connects with
+// `search_path=auth` so Better Auth's unqualified table names resolve here.
+/** Postgres schema the auth tables live in. */
+export const AUTH_PG_SCHEMA = 'auth';
+/** Idempotent DDL for the auth tables. Run against the app's own database. */
+export const AUTH_SCHEMA_SQL = `
+CREATE SCHEMA IF NOT EXISTS auth;
+
+CREATE TABLE IF NOT EXISTS auth."user" (
+  id text PRIMARY KEY,
+  name text,
+  email text NOT NULL UNIQUE,
+  "emailVerified" boolean NOT NULL DEFAULT false,
+  image text,
+  "createdAt" timestamptz NOT NULL DEFAULT now(),
+  "updatedAt" timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS auth."session" (
+  id text PRIMARY KEY,
+  "expiresAt" timestamptz NOT NULL,
+  token text NOT NULL UNIQUE,
+  "ipAddress" text,
+  "userAgent" text,
+  "userId" text NOT NULL REFERENCES auth."user"(id) ON DELETE CASCADE,
+  "createdAt" timestamptz NOT NULL DEFAULT now(),
+  "updatedAt" timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS session_user_id_idx ON auth."session"("userId");
+
+CREATE TABLE IF NOT EXISTS auth."account" (
+  id text PRIMARY KEY,
+  "accountId" text NOT NULL,
+  "providerId" text NOT NULL,
+  "userId" text NOT NULL REFERENCES auth."user"(id) ON DELETE CASCADE,
+  "accessToken" text,
+  "refreshToken" text,
+  "idToken" text,
+  "accessTokenExpiresAt" timestamptz,
+  "refreshTokenExpiresAt" timestamptz,
+  scope text,
+  password text,
+  "createdAt" timestamptz NOT NULL DEFAULT now(),
+  "updatedAt" timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS account_user_id_idx ON auth."account"("userId");
+
+CREATE TABLE IF NOT EXISTS auth."verification" (
+  id text PRIMARY KEY,
+  identifier text NOT NULL,
+  value text NOT NULL,
+  "expiresAt" timestamptz NOT NULL,
+  "createdAt" timestamptz NOT NULL DEFAULT now(),
+  "updatedAt" timestamptz NOT NULL DEFAULT now()
+);
+`;

package/dist/auth.d.ts

@@ -0,0 +1,50 @@
+import { type AppUser } from './auth-schema';
+export type { AppUser } from './auth-schema';
+export { AUTH_SCHEMA_SQL, AUTH_PG_SCHEMA } from './auth-schema';
+/**
+ * Minimal structural view of the Better Auth instance. Kept narrow on purpose:
+ * Better Auth's inferred generics are not portable across d.ts emit, and the
+ * SDK contract is the helpers, not the raw instance.
+ */
+interface AuthInstance {
+    handler(request: Request): Promise<Response>;
+    api: {
+        getSession(opts: {
+            headers: Headers;
+        }): Promise<{
+            user: {
+                id: string;
+                email: string;
+                emailVerified: boolean;
+                name?: string | null;
+                image?: string | null;
+            };
+        } | null>;
+    };
+}
+export interface KazzleAuth {
+    /** The underlying Better Auth instance (escape hatch; prefer the helpers). */
+    auth: AuthInstance;
+    /** Request handler for /api/auth/* — see mountKazzleAuth. */
+    handler(request: Request): Promise<Response>;
+    /** Resolve the signed-in end user from a request's cookies, or null. */
+    getAppUser(request: Request): Promise<AppUser | null>;
+}
+/**
+ * Create the app's login runtime. Reads platform-injected env; no options in
+ * the common case. `databaseUrl` override exists for tests only.
+ */
+export declare function createKazzleAuth(options?: {
+    databaseUrl?: string;
+}): KazzleAuth;
+/**
+ * Mount /api/auth/* on a Hono app. Structural typing on purpose so this
+ * module doesn't depend on hono.
+ */
+export declare function mountKazzleAuth(app: {
+    on(methods: string[], path: string, handler: (c: {
+        req: {
+            raw: Request;
+        };
+    }) => Promise<Response>): unknown;
+}, kazzleAuth: KazzleAuth): void;

package/dist/auth.js

@@ -0,0 +1,87 @@
+// @kazzle/app/auth — app login, server half.
+//
+// One provider, `kazzle`: the app's Better Auth does standard OIDC against
+// Kazzle's app-login broker, which runs Google (and later other methods)
+// behind it. App code never touches Google — no secrets, no callbacks, no
+// consent config. The platform injects everything this module reads:
+//
+//   DATABASE_URL           the app's own Postgres (users live HERE, not at Kazzle)
+//   KAZZLE_LOGIN_ID        the app's broker client id (= its app id)
+//   KAZZLE_LOGIN_SECRET    the app's broker client secret (server-only)
+//   KAZZLE_APP_PUBLIC_URL  the app's browser-facing origin (preview tunnel or prod host)
+//   KAZZLE_API_URL         Kazzle platform API base (the broker lives under /app-login)
+//
+// Auth rides the app's UI origin: the browser only ever calls relative
+// /api/auth/* paths (the UI dev server proxies them to this process; in prod
+// both surfaces share one host), so cookies are plain same-origin.
+//
+// The auth tables live in the `auth` Postgres schema (see ./auth-schema.ts);
+// this module connects with search_path=auth so Better Auth's unqualified
+// table names resolve there. App tables in the public schema reference
+// auth."user"(id) — never add columns to the auth tables themselves.
+import { betterAuth } from 'better-auth';
+import { genericOAuth } from 'better-auth/plugins';
+import { Pool } from 'pg';
+import { AUTH_PG_SCHEMA } from './auth-schema';
+export { AUTH_SCHEMA_SQL, AUTH_PG_SCHEMA } from './auth-schema';
+function requiredEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`${name} is not set — app login requires the platform-injected env (is appLogin enabled for this app?)`);
+    }
+    return value;
+}
+/**
+ * Create the app's login runtime. Reads platform-injected env; no options in
+ * the common case. `databaseUrl` override exists for tests only.
+ */
+export function createKazzleAuth(options) {
+    const databaseUrl = options?.databaseUrl ?? requiredEnv('DATABASE_URL');
+    const publicUrl = requiredEnv('KAZZLE_APP_PUBLIC_URL');
+    const apiUrl = requiredEnv('KAZZLE_API_URL');
+    const clientId = requiredEnv('KAZZLE_LOGIN_ID');
+    const clientSecret = requiredEnv('KAZZLE_LOGIN_SECRET');
+    const pool = new Pool({
+        connectionString: databaseUrl,
+        options: `-c search_path=${AUTH_PG_SCHEMA}`,
+    });
+    const auth = betterAuth({
+        database: pool,
+        secret: clientSecret,
+        baseURL: publicUrl,
+        basePath: '/api/auth',
+        trustedOrigins: [publicUrl],
+        plugins: [
+            genericOAuth({
+                config: [{
+                        providerId: 'kazzle',
+                        clientId,
+                        clientSecret,
+                        discoveryUrl: `${apiUrl}/app-login/.well-known/openid-configuration`,
+                        scopes: ['openid', 'email', 'profile'],
+                        pkce: true,
+                        // The app states the method; the broker executes it. Today: google.
+                        authorizationUrlParams: { method: 'google' },
+                    }],
+            }),
+        ],
+    });
+    return {
+        auth,
+        handler: (request) => auth.handler(request),
+        getAppUser: async (request) => {
+            const session = await auth.api.getSession({ headers: request.headers });
+            if (!session?.user)
+                return null;
+            const { id, email, emailVerified, name, image } = session.user;
+            return { id, email, emailVerified, name: name ?? null, image: image ?? null };
+        },
+    };
+}
+/**
+ * Mount /api/auth/* on a Hono app. Structural typing on purpose so this
+ * module doesn't depend on hono.
+ */
+export function mountKazzleAuth(app, kazzleAuth) {
+    app.on(['GET', 'POST'], '/api/auth/*', (c) => kazzleAuth.handler(c.req.raw));
+}

package/dist/connections.d.ts

@@ -0,0 +1,11 @@
+export declare class ConnectionNotConnectedError extends Error {
+    readonly connectionId: string;
+    constructor(connectionId: string, message?: string);
+}
+/**
+ * A fresh vendor access token for a connection, e.g.
+ * `new Stripe(await getConnectionToken('8f2a…'))`.
+ */
+export declare function getConnectionToken(connectionId: string): Promise<string>;
+/** Forget cached tokens (tests, or after a reconnect). */
+export declare function clearConnectionTokenCache(): void;

package/dist/connections.js

@@ -0,0 +1,56 @@
+// @kazzle/app/connections — use the accounts a person connected in Kazzle
+// (Stripe, Gmail, Slack, …) from app code.
+//
+// Kazzle keeps the OAuth tokens; this asks Kazzle for a fresh one and caches it
+// until it expires. Identify the connection by its vault secret id (the AI that
+// built the app has it from the vault). Requires KAZZLE_API_KEY and
+// KAZZLE_API_URL, both injected into every component at deploy and `kazzle run`.
+//
+// Dependency-free on purpose (uses global fetch). Do not add zod/vite here.
+import { kazzleApiUrl } from './client';
+export class ConnectionNotConnectedError extends Error {
+    connectionId;
+    constructor(connectionId, message) {
+        super(message ?? `Connection ${connectionId} is not connected. Connect it on the Integrations page in Kazzle.`);
+        this.connectionId = connectionId;
+        this.name = 'ConnectionNotConnectedError';
+    }
+}
+const DEFAULT_TTL_MS = 60 * 60_000;
+const REFRESH_MARGIN_MS = 60_000;
+const cache = new Map();
+function apiKey() {
+    const key = process.env['KAZZLE_API_KEY'];
+    if (!key) {
+        throw new Error('KAZZLE_API_KEY is not set — connection tokens are only available to deployed Kazzle app components.');
+    }
+    return key;
+}
+/**
+ * A fresh vendor access token for a connection, e.g.
+ * `new Stripe(await getConnectionToken('8f2a…'))`.
+ */
+export async function getConnectionToken(connectionId) {
+    const hit = cache.get(connectionId);
+    if (hit && hit.expiresAt - Date.now() > REFRESH_MARGIN_MS)
+        return hit.token;
+    const res = await fetch(`${kazzleApiUrl()}/connections/${encodeURIComponent(connectionId)}/token`, {
+        headers: { authorization: `Bearer ${apiKey()}` },
+    });
+    if (res.status === 404 || res.status === 409) {
+        const body = await res.json().catch(() => ({}));
+        cache.delete(connectionId);
+        throw new ConnectionNotConnectedError(connectionId, body.message);
+    }
+    if (!res.ok) {
+        throw new Error(`Kazzle connection token request failed: HTTP ${res.status}`);
+    }
+    const body = await res.json();
+    const expiresAt = body.expiresAt ? Date.parse(body.expiresAt) : Date.now() + DEFAULT_TTL_MS;
+    cache.set(connectionId, { token: body.token, expiresAt: Number.isFinite(expiresAt) ? expiresAt : Date.now() + DEFAULT_TTL_MS });
+    return body.token;
+}
+/** Forget cached tokens (tests, or after a reconnect). */
+export function clearConnectionTokenCache() {
+    cache.clear();
+}

package/dist/index.d.ts

@@ -89,6 +89,13 @@ export interface KazzleConfig {
     target?: 'local' | 'remote';
     /** Path to the app icon file (png, jpg, svg, webp, ico) */
     icon?: string;
+    /**
+     * End-user login for this app (via @kazzle/app/auth — Google today).
+     * Distinct from `kazzleAuth`, which gates the launch surface by Kazzle
+     * account; appLogin is the app's OWN users, stored in its own database.
+     * Requires a process + database.
+     */
+    appLogin?: boolean;
     /** Executable components — UI frontends or background processes */
     components?: KazzleComponent[];
     /** AI skill definitions — markdown files the AI reads for domain knowledge */

package/dist/sdk.d.ts

@@ -0,0 +1 @@
+export * from 'kazzle';

package/dist/sdk.js

@@ -0,0 +1,10 @@
+// @kazzle/app/sdk — the Kazzle REST API client, re-exported for app code.
+//
+// Deployed app components get KAZZLE_API_KEY and KAZZLE_API_URL injected
+// (server/apps/apps.runtime-env.ts), so `new Kazzle()` needs no arguments
+// there: the key scopes every call to the app's space.
+//
+// The implementation lives in the `kazzle` package (packages/kazzle-sdk) — an
+// optional peer dependency, so apps that do not drive computers or browsers do
+// not install it.
+export * from 'kazzle';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kazzle/app",
-  "version": "0.1.926",
+  "version": "0.1.929",
   "description": "Contracts, tool helpers, Vite helper, and templates for building Kazzle apps.",
   "license": "UNLICENSED",
   "repository": {
@@ -24,6 +24,22 @@
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
     },
+    "./connections": {
+      "types": "./dist/connections.d.ts",
+      "import": "./dist/connections.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js"
+    },
+    "./auth/schema": {
+      "types": "./dist/auth-schema.d.ts",
+      "import": "./dist/auth-schema.js"
+    },
+    "./auth/react": {
+      "types": "./dist/auth-react.d.ts",
+      "import": "./dist/auth-react.js"
+    },
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
@@ -32,6 +48,10 @@
       "types": "./dist/pwa.d.ts",
       "import": "./dist/pwa.js"
     },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    },
     "./templates": {
       "types": "./dist/templates.d.ts",
       "import": "./dist/templates.js"
@@ -61,10 +81,26 @@
     "workbox-window": "^7.4.1"
   },
   "peerDependencies": {
+    "kazzle": "^0.1.0",
+    "better-auth": ">=1.6.0 <1.7.0",
+    "pg": "^8.11.0",
+    "react": ">=18",
     "vite": ">=5",
     "zod": "^3 || ^4"
   },
   "peerDependenciesMeta": {
+    "kazzle": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     },
@@ -73,7 +109,13 @@
     }
   },
   "devDependencies": {
+    "kazzle": "workspace:*",
     "@types/node": "^25.1.0",
+    "@types/pg": "^8.11.0",
+    "@types/react": "^19.0.0",
+    "better-auth": ">=1.6.0 <1.7.0",
+    "pg": "^8.11.0",
+    "react": "^19.0.0",
     "typescript": "7.0.2",
     "vite": "^6.3.5",
     "zod": "^4.3.6"

package/templates/login-app/KAZZLE.md

@@ -0,0 +1,18 @@
+# Kazzle template context
+
+This app was created from the `login` template. It already includes end-user
+login (Google via Kazzle), a React UI, a Hono process API, and Postgres wiring.
+
+Template-owned setup:
+- `kazzle.config.ts` declares the UI and server components and `appLogin: true`. Database env vars are injected by `app.create`.
+- `components/server/index.ts` mounts the login flow (`createKazzleAuth` + `mountKazzleAuth` from `@kazzle/app/auth`) and owns the per-user notes API.
+- `components/ui/src/App.tsx` renders login state via `useAppUser()` / `signInWithKazzle()` / `signOutOfApp()` from `@kazzle/app/auth/react`.
+- The database schema (auth tables + notes) is bootstrapped by template setup before the app is handed back.
+
+Login rules — these keep sign-in working:
+- Auth is SDK code. Never write session/cookie/callback logic, never call the Kazzle broker or Google directly, never edit `/api/auth` handling beyond `mountKazzleAuth`.
+- The `auth` Postgres schema (`auth."user"`, `auth."session"`, `auth."account"`, `auth."verification"`) is owned by the SDK. Never ALTER those tables. Per-user data goes in your own public-schema tables with `user_id TEXT REFERENCES auth."user"(id) ON DELETE CASCADE` — see `notes`.
+- Server routes that touch user data start with `await kazzleAuth.getAppUser(c.req.raw)`; null → return 401.
+- New backend routes the browser calls must be added to `proxyPaths` in `components/ui/vite.config.ts`. `/api/auth` must stay in that list.
+
+Do not rerun `db.connect`, rewrite manifest env refs, recreate server boilerplate, or reinstall dependencies as setup repair after `app.create` reports template setup complete. Change these files only when the user asks for behavior beyond this template.

package/templates/login-app/components/server/index.ts

@@ -0,0 +1,93 @@
+/**
+ * {{APP_NAME}} — server component for the login template.
+ *
+ * End-user login via Kazzle (Google today) plus a per-user notes API that
+ * shows the pattern for user-owned data:
+ *
+ *   - Auth is SDK code: `createKazzleAuth()` + `mountKazzleAuth()` wire the
+ *     whole login flow. Do NOT write auth logic (sessions, cookies, callbacks)
+ *     by hand — extend around it.
+ *   - Users live in this app's own database, in the `auth` Postgres schema
+ *     (auth."user", auth."session", …). NEVER modify those tables. Per-user
+ *     app data goes in your own public-schema tables with a
+ *     `user_id TEXT REFERENCES auth."user"(id)` column — like `notes` below.
+ *   - Every route that touches user data starts with `getAppUser(request)`;
+ *     null means logged out → 401. The browser sends the session cookie
+ *     automatically (same-origin /api/auth + API paths via the UI proxy).
+ */
+
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import postgres from 'postgres';
+import { createKazzleAuth, mountKazzleAuth } from '@kazzle/app/auth';
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error('DATABASE_URL is required');
+
+const sql = postgres(databaseUrl);
+const kazzleAuth = createKazzleAuth();
+const app = new Hono();
+
+app.use('*', cors());
+app.get('/health', (c) => c.json({ ok: true }));
+
+// All of /api/auth/* — sign-in, callback, session, sign-out. SDK-owned.
+mountKazzleAuth(app, kazzleAuth);
+
+// ── Who am I ─────────────────────────────────────────────────────────────
+
+app.get('/me', async (c) => {
+  const user = await kazzleAuth.getAppUser(c.req.raw);
+  if (!user) return c.json({ error: 'Not signed in' }, 401);
+  return c.json(user);
+});
+
+// ── Notes (per-user data pattern) ────────────────────────────────────────
+
+app.get('/notes', async (c) => {
+  const user = await kazzleAuth.getAppUser(c.req.raw);
+  if (!user) return c.json({ error: 'Not signed in' }, 401);
+  const rows = await sql`
+    SELECT id, body, created_at
+    FROM notes
+    WHERE user_id = ${user.id}
+    ORDER BY created_at DESC
+  `;
+  return c.json(rows);
+});
+
+app.post('/notes', async (c) => {
+  const user = await kazzleAuth.getAppUser(c.req.raw);
+  if (!user) return c.json({ error: 'Not signed in' }, 401);
+  const { body } = await c.req.json<{ body?: string }>();
+  const text = body?.trim();
+  if (!text) return c.json({ error: 'Note text is required' }, 400);
+  const [note] = await sql`
+    INSERT INTO notes (user_id, body)
+    VALUES (${user.id}, ${text})
+    RETURNING id, body, created_at
+  `;
+  return c.json(note, 201);
+});
+
+app.delete('/notes/:id', async (c) => {
+  const user = await kazzleAuth.getAppUser(c.req.raw);
+  if (!user) return c.json({ error: 'Not signed in' }, 401);
+  const id = Number(c.req.param('id'));
+  if (!Number.isFinite(id)) return c.json({ error: 'Invalid note id' }, 400);
+  // WHERE user_id keeps one user from deleting another's note by guessing ids.
+  await sql`DELETE FROM notes WHERE id = ${id} AND user_id = ${user.id}`;
+  return c.json({ ok: true });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+//  DO NOT CHANGE THE NEXT 4 LINES.  DO NOT ADD FALLBACKS.  DO NOT HARDCODE.
+//  PORT and HOST are injected by `kazzle run`. Missing values must throw.
+// ─────────────────────────────────────────────────────────────────────────
+if (!process.env.PORT || !process.env.HOST) {
+  throw new Error('PORT and HOST must be set by "kazzle run" — never hardcode them.');
+}
+const port = Number(process.env.PORT);
+const hostname = process.env.HOST;
+serve({ fetch: app.fetch, port, hostname });

package/templates/login-app/components/server/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{APP_SLUG}}-server",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun run index.ts",
+    "dev": "kazzle run -- bun --watch index.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
+    "check": "bun run typecheck"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}",
+    "better-auth": ">=1.6.0 <1.7.0",
+    "hono": "^4.12.16",
+    "pg": "^8.11.0",
+    "postgres": "^3.4.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "@types/pg": "^8.11.0",
+    "typescript": "7.0.2"
+  }
+}

package/templates/login-app/components/server/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["*.ts"]
+}

package/templates/login-app/components/ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/login-app/components/ui/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "{{APP_SLUG}}",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "kazzle run -- vite",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build",
+    "preview": "kazzle run -- vite preview",
+    "check": "bun run typecheck && bun run build"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}",
+    "@vitejs/plugin-react": "^4.5.2",
+    "better-auth": ">=1.6.0 <1.7.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "vite": "^6.3.5"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.0",
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "tailwindcss": "^4.1.0",
+    "typescript": "7.0.2"
+  }
+}

package/templates/login-app/components/ui/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="64" height="64" rx="18" fill="#6366F1"/>
+  <path d="M19 33.5L28 42L46 22" stroke="white" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/templates/login-app/components/ui/src/App.tsx

@@ -0,0 +1,107 @@
+/**
+ * {{APP_NAME}} — login template UI.
+ *
+ * Two states, driven entirely by `useAppUser()` from @kazzle/app/auth/react:
+ *   logged out → a login card with one "Continue with Google" button
+ *   logged in  → the app (per-user notes), user chip, sign out
+ *
+ * All auth is SDK code: `signInWithKazzle()` starts the flow,
+ * `signOutOfApp()` ends the session, `useAppUser()` is reactive. There is no
+ * auth logic to write in this file — build the app around the user object.
+ */
+
+import { useEffect, useState, type FormEvent } from 'react';
+import { signInWithKazzle, signOutOfApp, useAppUser, useAppUserPending } from '@kazzle/app/auth/react';
+import { createNote, deleteNote, getNotes, type Note } from './api';
+
+export function App() {
+  const user = useAppUser();
+  const pending = useAppUserPending();
+
+  if (pending) return <div className="page" />;
+  if (!user) return <LoginScreen />;
+  return <NotesScreen name={user.name ?? user.email} image={user.image} />;
+}
+
+function LoginScreen() {
+  return (
+    <div className="page items-center justify-center">
+      <div className="card stack max-w-sm w-full items-center text-center">
+        <h1 className="text-2xl font-semibold">{'{{APP_NAME}}'}</h1>
+        <p className="text-muted">Sign in to keep your notes in one place.</p>
+        <button className="btn w-full" onClick={() => void signInWithKazzle('google')}>
+          Continue with Google
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function NotesScreen({ name, image }: { name: string; image: string | null }) {
+  const [notes, setNotes] = useState<Note[]>([]);
+  const [draft, setDraft] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    getNotes().then(setNotes).catch((err: Error) => setError(err.message));
+  }, []);
+
+  async function addNote(event: FormEvent) {
+    event.preventDefault();
+    const body = draft.trim();
+    if (!body) return;
+    try {
+      const note = await createNote(body);
+      setNotes((current) => [note, ...current]);
+      setDraft('');
+    } catch (err) {
+      setError((err as Error).message);
+    }
+  }
+
+  async function removeNote(id: number) {
+    try {
+      await deleteNote(id);
+      setNotes((current) => current.filter((note) => note.id !== id));
+    } catch (err) {
+      setError((err as Error).message);
+    }
+  }
+
+  return (
+    <div className="page">
+      <header className="row justify-between">
+        <h1 className="text-xl font-semibold">{'{{APP_NAME}}'}</h1>
+        <div className="row">
+          {image && <img src={image} alt="" className="size-8 rounded-full" referrerPolicy="no-referrer" />}
+          <span className="text-muted">{name}</span>
+          <button className="btn" onClick={() => void signOutOfApp().then(() => window.location.reload())}>
+            Sign out
+          </button>
+        </div>
+      </header>
+
+      <form className="row" onSubmit={addNote}>
+        <input
+          className="input flex-1"
+          placeholder="Write a note…"
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+        />
+        <button className="btn" type="submit">Add</button>
+      </form>
+
+      {error && <p className="text-red-400">{error}</p>}
+
+      <div className="stack">
+        {notes.map((note) => (
+          <div key={note.id} className="card row justify-between">
+            <span>{note.body}</span>
+            <button className="btn" onClick={() => void removeNote(note.id)}>Delete</button>
+          </div>
+        ))}
+        {notes.length === 0 && !error && <p className="text-muted">No notes yet — your notes are only visible to you.</p>}
+      </div>
+    </div>
+  );
+}

package/templates/login-app/components/ui/src/api.ts

@@ -0,0 +1,37 @@
+/**
+ * Thin wrappers over the server's REST API. The browser sends the session
+ * cookie automatically — no auth headers to add. A 401 means logged out; the
+ * App component treats that as "show the login screen".
+ */
+
+export interface Note {
+  id: number;
+  body: string;
+  created_at: string;
+}
+
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(path, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      ...init?.headers,
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`Request failed: ${res.status} ${await res.text()}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+export function getNotes(): Promise<Note[]> {
+  return request<Note[]>('/notes');
+}
+
+export function createNote(body: string): Promise<Note> {
+  return request<Note>('/notes', { method: 'POST', body: JSON.stringify({ body }) });
+}
+
+export function deleteNote(id: number): Promise<{ ok: boolean }> {
+  return request<{ ok: boolean }>(`/notes/${id}`, { method: 'DELETE' });
+}

package/templates/login-app/components/ui/src/main.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { registerAppSW } from '@kazzle/app/pwa';
+import { App } from './App';
+import './styles/theme.css';
+
+registerAppSW();
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/templates/login-app/components/ui/src/styles/theme.css

@@ -0,0 +1,181 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ *  Kazzle app theme — the ONE styling entry point for this app.
+ *
+ *  This file is the design system. It is imported once (in `main.tsx`) and
+ *  gives you three things, in order:
+ *
+ *    1. Tailwind v4            — every utility class (`flex`, `gap-4`,
+ *                                `rounded-xl`, `text-zinc-500`, …) works in
+ *                                your JSX. No config file, no PostCSS setup.
+ *    2. Design tokens (@theme) — colors, radius, fonts as CSS variables. Edit
+ *                                these to re-skin the whole app at once.
+ *    3. Primitives (@layer)    — a few ready-made classes (`.btn`, `.card`,
+ *                                `.input`, `.field`, `.page`, `.stack`,
+ *                                `.row`) so common UI looks good with zero
+ *                                effort.
+ *
+ *  HOW TO STYLE — pick whichever is easier, mix freely:
+ *    • Tailwind utilities in `className` for one-off layout/spacing.
+ *    • A primitive class (`.btn`, `.card`) for the common building blocks.
+ *
+ *  WHY IT'S BUILT THIS WAY: styles live in the markup (utilities) or in named
+ *  primitives here — never in a separate per-screen stylesheet keyed to class
+ *  names you have to keep in sync. Rewriting a component can't silently strip
+ *  its styling, because the styling travels with the elements.
+ *
+ *  TO EXTEND: add new design tokens under `@theme`, and add new reusable
+ *  building blocks under `@layer components`. Keep app-specific one-offs as
+ *  inline Tailwind utilities in the component instead of adding a class here.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+@import "tailwindcss";
+
+/* ── Design tokens ──────────────────────────────────────────────────────────
+ * Exposed to Tailwind as `bg-surface`, `text-fg`, `text-muted`,
+ * `bg-accent`, `rounded-app`, etc. Change a value here and every utility and
+ * primitive that references it updates at once. */
+@theme {
+  --color-bg: #0b0f1a;
+  --color-surface: #131a2a;
+  --color-surface-raised: #1b2438;
+  --color-fg: #e8edf7;
+  --color-muted: #94a3b8;
+  --color-border: rgba(148, 163, 184, 0.18);
+  --color-accent: #6366f1;
+  --color-accent-hover: #4f46e5;
+  --color-accent-fg: #ffffff;
+  --color-danger: #f87171;
+
+  --radius-app: 0.875rem;
+
+  --font-sans: "Inter", ui-sans-serif, system-ui, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+
+/* ── Base ────────────────────────────────────────────────────────────────────
+ * Sensible document defaults so even unstyled markup reads well. */
+@layer base {
+  html,
+  body,
+  #root {
+    min-height: 100%;
+  }
+
+  body {
+    margin: 0;
+    background: var(--color-bg);
+    color: var(--color-fg);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  h1 {
+    font-size: 1.875rem;
+    font-weight: 700;
+    letter-spacing: -0.02em;
+    margin: 0;
+  }
+
+  h2 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin: 0;
+  }
+}
+
+/* ── Primitives ──────────────────────────────────────────────────────────────
+ * Reusable building blocks. Use them directly (`<button class="btn btn-primary">`)
+ * or layer Tailwind utilities on top. Add new ones here when a pattern repeats. */
+@layer components {
+  /* Page wrapper — centers content with comfortable gutters. */
+  .page {
+    width: min(100% - 2rem, 48rem);
+    margin-inline: auto;
+    padding-block: 3rem;
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+  }
+
+  /* Vertical / horizontal stacks. */
+  .stack {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+  .row {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+  }
+
+  /* Card surface. */
+  .card {
+    background: var(--color-surface);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-app);
+    padding: 1.25rem;
+  }
+
+  /* Buttons. `.btn` is the neutral base; add `.btn-primary` for the accent. */
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    padding: 0.625rem 1rem;
+    border-radius: var(--radius-app);
+    border: 1px solid var(--color-border);
+    background: var(--color-surface-raised);
+    color: var(--color-fg);
+    font: inherit;
+    font-weight: 500;
+    cursor: pointer;
+    transition: background 0.15s, border-color 0.15s, opacity 0.15s;
+  }
+  .btn:hover {
+    background: color-mix(in srgb, var(--color-surface-raised) 80%, white);
+  }
+  .btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .btn-primary {
+    background: var(--color-accent);
+    border-color: transparent;
+    color: var(--color-accent-fg);
+  }
+  .btn-primary:hover {
+    background: var(--color-accent-hover);
+  }
+
+  /* Text input / select. */
+  .input {
+    width: 100%;
+    min-width: 0;
+    padding: 0.625rem 0.875rem;
+    border-radius: var(--radius-app);
+    border: 1px solid var(--color-border);
+    background: var(--color-surface-raised);
+    color: var(--color-fg);
+    font: inherit;
+    outline: none;
+  }
+  .input:focus {
+    border-color: var(--color-accent);
+  }
+
+  /* Labelled field: <label class="field"><span>Label</span><input class="input"/></label> */
+  .field {
+    display: flex;
+    flex-direction: column;
+    gap: 0.375rem;
+    font-size: 0.875rem;
+    color: var(--color-muted);
+  }
+
+  /* Muted helper / secondary text. */
+  .muted {
+    color: var(--color-muted);
+  }
+}

package/templates/login-app/components/ui/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/login-app/components/ui/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": []
+}

package/templates/login-app/components/ui/vite.config.ts

@@ -0,0 +1,19 @@
+/**
+ * Vite config for the UI component.
+ *
+ * Kazzle owns HOST/PORT (`kazzleAppVite`) and production PWA (`kazzleAppPwa`)
+ * in `@kazzle/app/vite`. This template declares a backend `server` component;
+ * we pass its name plus the relative routes the browser calls. `/api/auth` is
+ * the login flow — it MUST stay proxied so auth cookies are same-origin. Add
+ * new backend routes to `proxyPaths`.
+ */
+
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
+
+export default defineConfig(({ command }) => ({
+  plugins: [react(), tailwindcss(), ...kazzleAppPwa()],
+  ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/api/auth', '/me', '/notes'] }),
+}));

package/templates/login-app/kazzle.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from '@kazzle/app';
+
+export default defineConfig({
+  /** One-line catalog tagline. Required to publish. */
+  subtitle: '{{APP_NAME}}',
+  icon: 'components/ui/public/favicon.svg',
+  /** End-user login (Google via Kazzle). Users live in this app's own database. */
+  appLogin: true,
+  components: [
+    { name: 'ui', type: 'ui', path: './components/ui' },
+    { name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
+  ],
+});

package/templates/login-app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "components/*"
+  ],
+  "scripts": {
+    "dev": "bun run --cwd components/ui dev",
+    "start": "bun run --cwd components/server start",
+    "check": "bun run --filter='./components/*' check"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}"
+  }
+}

package/templates/manifest.json

@@ -4,6 +4,7 @@
     { "id": "ui", "label": "UI", "description": "React + Vite UI component with the Kazzle preview Vite helper.", "tags": ["ui", "frontend"] },
     { "id": "process", "label": "Process", "description": "Background/triggered process component plus AI tool skill.", "tags": ["process", "tools"] },
     { "id": "ui-db", "label": "UI + Postgres", "description": "React UI plus Hono API backed by a plain Postgres database.", "tags": ["ui", "database"] },
+    { "id": "login", "label": "Login", "description": "React UI with end-user Google login (via Kazzle) and per-user data in Postgres.", "tags": ["ui", "database", "login"] },
     { "id": "realtime", "label": "Realtime", "description": "Offline-first UI with PowerSync sync over a Postgres backend.", "tags": ["ui", "database", "sync"] },
     { "id": "ai", "label": "AI", "description": "React UI plus Hono server exposing Kazzle AI (chat, image, speech, extract).", "tags": ["ui", "ai"] }
   ]

package/templates/ui-db-app/components/ui/tsconfig.json

@@ -10,7 +10,7 @@
     "strict": true,
     "forceConsistentCasingInFileNames": true,
     "module": "ESNext",
-    "moduleResolution": "Node",
+    "moduleResolution": "Bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
     "noEmit": true,