feat: Implement passkey and social authentication (#2107)

Author: koistya

.claude/commands/validate-auth-schema.md

@@ -0,0 +1,41 @@
+# Validate Auth Schema
+
+Validate that the Drizzle ORM schema in `db/schema/` matches the Better Auth requirements.
+
+## Steps
+
+1. **Generate Better Auth schema reference**:
+
+   ```bash
+   bun run db/scripts/generate-auth-schema.ts
+   ```
+
+2. **Compare with current Drizzle schema**:
+   - Review all files in `db/schema/` (user.ts, organization.ts, etc.)
+   - Check that each Better Auth table has corresponding Drizzle table
+   - Verify field types, constraints, and relationships match
+   - Ensure table names and field names align with Better Auth expectations
+
+3. **Key validation points**:
+   - **Table mapping**: Better Auth `account` → Drizzle `identity`
+   - **Required fields**: All Better Auth required fields are present and correctly typed
+   - **Relationships**: Foreign key references match (userId, organizationId, etc.)
+   - **Constraints**: Unique fields, required fields, default values
+   - **Field types**: string/text, boolean, date/timestamp, number types
+
+4. **Report findings**:
+   - List any missing tables or fields
+   - Identify type mismatches
+   - Note incorrect constraints or relationships
+   - Suggest specific fixes needed
+
+## Context
+
+Better Auth requires specific database schema structure. The generated JSON serves as the source of truth for what Better Auth expects, while the Drizzle schema in `db/schema/` is our actual implementation that must match.
+
+## Success Criteria
+
+- All Better Auth required tables exist in Drizzle schema
+- Field types and constraints match Better Auth requirements
+- Foreign key relationships are correctly implemented
+- Custom schema additions (like organizations) don't conflict with Better Auth expectations

.gemini/settings.json

@@ -1,4 +1,4 @@
 {
   "preferredEditor": "vscode",
-  "contextFileName": "CLAUDE.md"
+  "contextFileName": ["CLAUDE.md", "CLAUDE.local.md"]
 }

apps/api/dev.ts

@@ -1,78 +1,89 @@
 /**
- * Local development server for the API with Neon database support via Hyperdrive.
+ * Local development server that emulates Cloudflare Workers runtime with Neon database.
  *
- * @remarks
- * This file bootstraps a local Cloudflare Workers environment using Wrangler's
- * getPlatformProxy, allowing you to develop against a Neon database instance
- * locally with Hyperdrive bindings.
- *
- * Features:
- * - Emulates Cloudflare Workers runtime environment
- * - Provides access to Hyperdrive bindings for Neon PostgreSQL
- * - Connection pooling via Hyperdrive
- * - Hot reloading support for rapid development
+ * WARNING: This file uses getPlatformProxy which requires wrangler.jsonc configuration.
+ * Hyperdrive bindings must be configured for both HYPERDRIVE_CACHED and HYPERDRIVE_DIRECT.
  *
  * @example
- * Start the development server:
  * ```bash
  * bun --filter @repo/api dev
+ * bun --filter @repo/api dev --env=staging  # Use staging environment config
  * ```
  *
  * SPDX-FileCopyrightText: 2014-present Kriasoft
  * SPDX-License-Identifier: MIT
  */
 
 import { Hono } from "hono";
+import { parseArgs } from "node:util";
 import { getPlatformProxy } from "wrangler";
 import api from "./index.js";
 import { createAuth } from "./lib/auth.js";
 import type { AppContext } from "./lib/context.js";
 import { createDb } from "./lib/db.js";
 import type { Env } from "./lib/env.js";
 
+const { values: args } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    env: { type: "string" },
+  },
+});
+
 type CloudflareEnv = {
   HYPERDRIVE_CACHED: Hyperdrive;
   HYPERDRIVE_DIRECT: Hyperdrive;
 } & Env;
 
-/**
- * Initialize the local development server with Cloudflare bindings.
- */
+// [INITIALIZATION]
 const app = new Hono<AppContext>();
 
-/**
- * Create a local Cloudflare environment proxy.
- *
- * @remarks
- * - Reads configuration from wrangler.jsonc in the parent directory
- * - Enables persistence to maintain D1 database state across restarts
- * - Provides access to all Cloudflare bindings defined in wrangler.jsonc
- */
+// NOTE: persist:true maintains D1 state across restarts (.wrangler directory)
+// Environment defaults to 'dev' unless --env flag is provided
 const cf = await getPlatformProxy<CloudflareEnv>({
   configPath: "./wrangler.jsonc",
+  environment: args.env ?? "dev",
   persist: true,
 });
 
-/**
- * Middleware to inject database binding into request context.
- *
- * @remarks
- * Uses Neon PostgreSQL via Hyperdrive for both local development
- * and production deployment with connection pooling and caching.
- */
+// [CONTEXT INJECTION]
+// Creates two database connections per request:
+// - db: Uses Hyperdrive caching (read-heavy queries)
+// - dbDirect: Bypasses cache (write operations, transactions)
 app.use("*", async (c, next) => {
   const db = createDb(cf.env.HYPERDRIVE_CACHED);
   const dbDirect = createDb(cf.env.HYPERDRIVE_DIRECT);
+
+  // Priority: Cloudflare bindings > process.env > empty string
+  // Required for local dev where secrets aren't in wrangler.jsonc
+  const secretKeys = [
+    "BETTER_AUTH_SECRET",
+    "GOOGLE_CLIENT_ID",
+    "GOOGLE_CLIENT_SECRET",
+    "OPENAI_API_KEY",
+  ] as const;
+
+  const env = {
+    ...cf.env,
+    ...Object.fromEntries(
+      secretKeys.map((key) => [key, (cf.env[key] || process.env[key]) ?? ""]),
+    ),
+    APP_NAME: cf.env.APP_NAME || process.env.APP_NAME || "Example",
+    APP_ORIGIN:
+      // Prefer origin set by `apps/app` at runtime
+      c.req.header("x-forwarded-origin") ||
+      c.env.APP_ORIGIN ||
+      process.env.APP_ORIGIN ||
+      "http://localhost:5173",
+  };
+
   c.set("db", db);
   c.set("dbDirect", dbDirect);
-  c.set("auth", createAuth(db, cf.env));
+  c.set("auth", createAuth(db, env));
   await next();
 });
 
-/**
- * Mount the main API routes.
- * All routes defined in ./lib/app.ts will be available at the root path.
- */
+// Routes from ./index.js mounted at root
 app.route("/", api);
 
 export default app;

apps/api/index.ts

@@ -17,8 +17,10 @@ export { createDb } from "./lib/db.js";
 export { default as app, appRouter } from "./lib/app.js";
 
 // Type exports
-export type { AppContext } from "./lib/context.js";
 export type { AppRouter } from "./lib/app.js";
+export type { AppContext } from "./lib/context.js";
+// Re-export context type to fix TypeScript portability issues
+export type * from "./lib/context.js";
 
 // Default export is the core app
 export { default } from "./lib/app.js";

apps/api/lib/auth.ts

@@ -6,6 +6,7 @@ import { betterAuth } from "better-auth";
 import type { DB } from "better-auth/adapters/drizzle";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { anonymous, organization } from "better-auth/plugins";
+import { passkey } from "better-auth/plugins/passkey";
 import type { Env } from "./env";
 
 /**
@@ -14,7 +15,11 @@ import type { Env } from "./env";
  */
 type AuthEnv = Pick<
   Env,
-  "BETTER_AUTH_SECRET" | "GOOGLE_CLIENT_ID" | "GOOGLE_CLIENT_SECRET"
+  | "APP_NAME"
+  | "APP_ORIGIN"
+  | "BETTER_AUTH_SECRET"
+  | "GOOGLE_CLIENT_ID"
+  | "GOOGLE_CLIENT_SECRET"
 >;
 
 /**
@@ -44,7 +49,13 @@ export function createAuth(
   db: DB,
   env: AuthEnv,
 ): ReturnType<typeof betterAuth> {
+  // Extract domain from APP_ORIGIN for passkey rpID
+  const appUrl = new URL(env.APP_ORIGIN);
+  const rpID = appUrl.hostname;
+
   return betterAuth({
+    baseURL: `${env.APP_ORIGIN}/api/auth`,
+    trustedOrigins: [env.APP_ORIGIN],
     secret: env.BETTER_AUTH_SECRET,
     database: drizzleAdapter(db, {
       provider: "pg",
@@ -54,6 +65,7 @@ export function createAuth(
         invitation: Db.invitation,
         member: Db.member,
         organization: Db.organization,
+        passkey: Db.passkey,
         session: Db.session,
         user: Db.user,
         verification: Db.verification,
@@ -84,6 +96,14 @@ export function createAuth(
         organizationLimit: 5,
         creatorRole: "owner",
       }),
+      passkey({
+        // rpID: Relying Party ID - domain name in production, 'localhost' for dev
+        rpID,
+        // rpName: Human-readable name for your app
+        rpName: env.APP_NAME,
+        // origin: URL where auth occurs (no trailing slash)
+        origin: env.APP_ORIGIN,
+      }),
     ],
 
     advanced: {

apps/api/lib/env.ts

@@ -11,6 +11,8 @@ import { z } from "zod";
  */
 export const envSchema = z.object({
   ENVIRONMENT: z.enum(["production", "staging", "preview", "development"]),
+  APP_NAME: z.string().default("Example"),
+  APP_ORIGIN: z.url(),
   DATABASE_URL: z.url(),
   BETTER_AUTH_SECRET: z.string().min(32),
   GOOGLE_CLIENT_ID: z.string(),

apps/api/package.json

@@ -21,24 +21,24 @@
     "@repo/core": "workspace:*",
     "@repo/db": "workspace:*",
     "@trpc/server": "^11.5.0",
-    "ai": "^5.0.28",
-    "better-auth": "^1.3.7",
+    "ai": "^5.0.30",
+    "better-auth": "^1.3.8",
     "dataloader": "^2.2.3",
     "drizzle-orm": "^0.44.5",
     "postgres": "^3.4.7"
   },
   "peerDependencies": {
-    "hono": "^4.9.5",
+    "hono": "^4.9.6",
     "zod": "^4.1.5"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250829.0",
+    "@cloudflare/workers-types": "^4.20250904.0",
     "@repo/typescript-config": "workspace:*",
     "@types/bun": "^1.2.21",
-    "hono": "^4.9.5",
+    "hono": "^4.9.6",
     "typescript": "~5.9.2",
     "vitest": "~3.2.4",
-    "wrangler": "^4.33.1",
+    "wrangler": "^4.33.2",
     "zod": "^4.1.5"
   }
 }

apps/api/wrangler.jsonc

@@ -26,6 +26,8 @@
   ],
   "vars": {
     "ENVIRONMENT": "production",
+    "APP_NAME": "Example",
+    "APP_ORIGIN": "https://example.com",
     "ALLOWED_ORIGINS": "https://example.com"
   },
   // prettier-ignore
@@ -41,6 +43,8 @@
     "dev": {
       "vars": {
         "ENVIRONMENT": "development",
+        "APP_NAME": "Example",
+        "APP_ORIGIN": "http://localhost:5173",
         "ALLOWED_ORIGINS": "http://localhost:5173,http://127.0.0.1:5173"
       },
       // prettier-ignore
@@ -61,6 +65,8 @@
       ],
       "vars": {
         "ENVIRONMENT": "staging",
+        "APP_NAME": "Example",
+        "APP_ORIGIN": "https://staging.example.com",
         "ALLOWED_ORIGINS": "https://staging.example.com"
       },
       // prettier-ignore
@@ -80,6 +86,8 @@
       ],
       "vars": {
         "ENVIRONMENT": "preview",
+        "APP_NAME": "Example",
+        "APP_ORIGIN": "https://preview.example.com",
         "ALLOWED_ORIGINS": "https://preview.example.com"
       },
       // prettier-ignore

apps/app/CLAUDE.md

@@ -1,3 +1,7 @@
+## Architecture
+
+This is a Single Page Application (SPA) and does not require Server-Side Rendering (SSR). All rendering is done on the client-side.
+
 ## Tech Stack
 
 React 19, TypeScript, Vite, TanStack Router, shadcn/ui, Tailwind CSS v4, Jotai, Better Auth.
@@ -14,3 +18,48 @@ React 19, TypeScript, Vite, TanStack Router, shadcn/ui, Tailwind CSS v4, Jotai,
 - `components/` - Reusable UI components
 - `lib/` - Utilities and shared logic
 - `styles/` - Global CSS and Tailwind config
+
+## Routing Conventions
+
+### Route Groups
+
+- `(app)/` - Protected routes requiring authentication
+- `(auth)/` - Public authentication routes
+- Parentheses create logical groups without affecting URLs
+
+### Components
+
+- Layout components use `<Outlet />` for nested routes
+- Access route context directly via `Route.useRouteContext()`, not props
+- Import route definitions for type-safe context access: `import { Route } from "@/routes/(app)/route"`
+
+### Navigation
+
+- Use `<Link>` from TanStack Router for internal routes
+- Use `<a>` for external links or undefined routes
+- Active styling via `activeProps` on `<Link>`
+
+### Authentication
+
+#### Core Decisions
+
+- **Provider:** Better Auth (cookie-based sessions, OAuth, passkeys)
+- **State:** TanStack Query wraps all auth calls via `useSessionQuery()` / `useSuspenseSessionQuery()`
+- **Protection:** Routes validate auth in `beforeLoad` hooks, not components
+- **Storage:** Server sessions only, no localStorage/sessionStorage
+
+#### Implementation Rules
+
+- Never use Better Auth's `useSession()` directly - use TanStack Query wrappers
+- Route groups: `(app)/` = protected, `(auth)/` = public
+- Auth checks validate both `session?.user` AND `session?.session` exist
+- Session queries cached 30s, auto-refresh on focus/reconnect
+- Invalidate session cache after login/logout for fresh data
+- Auth errors (401/403) trigger redirects via error boundaries
+
+#### Files
+
+- `lib/auth.ts` - Better Auth client setup
+- `lib/queries/session.ts` - TanStack Query session hooks
+- `routes/(app)/route.tsx` - Protected route guard
+- `components/auth/` - Auth UI components