@opensaas/stack-auth 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @opensaas/stack-auth@0.1.0 build /home/runner/work/stack/stack/packages/auth
+> tsc
+

package/INTEGRATION_SUMMARY.md

@@ -0,0 +1,425 @@
+# Better-Auth Integration Summary
+
+This document summarizes the complete better-auth integration for the OpenSaas Stack.
+
+## What Was Built
+
+### 1. Core Package (`@opensaas/stack-auth`)
+
+**Location:** `packages/auth/`
+
+**Exports:**
+
+- **Main** (`@opensaas/stack-auth`):
+  - `withAuth()` - Config wrapper that adds auth lists
+  - `authConfig()` - Auth configuration builder
+  - `getAuthLists()` - Get all auth list definitions
+
+- **Server** (`@opensaas/stack-auth/server`):
+  - `createAuth()` - Creates better-auth instance
+  - `getSessionFromAuth()` - Session extraction helper
+
+- **Client** (`@opensaas/stack-auth/client`):
+  - `createClient()` - Creates better-auth React client
+
+- **UI** (`@opensaas/stack-auth/ui`):
+  - `<SignInForm />` - Pre-built sign in form
+  - `<SignUpForm />` - Pre-built sign up form
+  - `<ForgotPasswordForm />` - Pre-built password reset form
+
+### 2. Auto-Generated Lists
+
+The package automatically creates four lists matching better-auth's schema:
+
+**User:**
+
+```typescript
+{
+  id: string
+  name: string
+  email: string (unique)
+  emailVerified: boolean
+  image?: string
+  sessions: Session[]
+  accounts: Account[]
+  createdAt: Date
+  updatedAt: Date
+  // + custom fields via extendUserList
+}
+```
+
+**Session:**
+
+```typescript
+{
+  id: string
+  token: string (unique)
+  userId: string
+  expiresAt: Date
+  ipAddress?: string
+  userAgent?: string
+  user: User
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+**Account:**
+
+```typescript
+{
+  id: string
+  userId: string
+  accountId: string
+  providerId: string
+  accessToken?: string
+  refreshToken?: string
+  // ... OAuth token fields
+  password?: string
+  user: User
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+**Verification:**
+
+```typescript
+{
+  id: string
+  identifier: string
+  value: string
+  expiresAt: Date
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+### 3. Example Application (`examples/auth-demo`)
+
+A complete working example showing:
+
+- ✅ Email/password authentication
+- ✅ Sign up, sign in, forgot password pages
+- ✅ Session-based access control
+- ✅ Protected admin routes
+- ✅ Author-only post editing
+- ✅ Auto-generated auth tables
+
+## Usage Pattern
+
+### Step 1: Config
+
+```typescript
+// opensaas.config.ts
+import { withAuth, authConfig } from '@opensaas/stack-auth'
+
+export default withAuth(
+  config({
+    db: { provider: 'sqlite', url: 'file:./dev.db' },
+    lists: {
+      /* your custom lists */
+    },
+  }),
+  authConfig({
+    emailAndPassword: { enabled: true },
+    sessionFields: ['userId', 'email', 'name'],
+  }),
+)
+```
+
+### Step 2: Generate
+
+```bash
+pnpm generate  # Generates auth tables in Prisma schema
+pnpm db:push   # Creates database with all tables
+```
+
+### Step 3: Server Setup
+
+```typescript
+// lib/auth.ts
+import { createAuth } from '@opensaas/stack-auth/server'
+export const auth = createAuth(config)
+export const GET = auth.handler
+export const POST = auth.handler
+
+// app/api/auth/[...all]/route.ts
+export { GET, POST } from '@/lib/auth'
+```
+
+### Step 4: Client Setup
+
+```typescript
+// lib/auth-client.ts
+'use client'
+import { createClient } from '@opensaas/stack-auth/client'
+export const authClient = createClient({ baseURL: '...' })
+```
+
+### Step 5: Use UI Components
+
+```typescript
+// app/sign-in/page.tsx
+import { SignInForm } from '@opensaas/stack-auth/ui'
+import { authClient } from '@/lib/auth-client'
+
+<SignInForm authClient={authClient} redirectTo="/admin" />
+```
+
+### Step 6: Access Control Works Automatically
+
+```typescript
+// opensaas.config.ts
+lists: {
+  Post: list({
+    access: {
+      operation: {
+        create: ({ session }) => !!session, // ✅ session available!
+        update: ({ session, item }) => {
+          return session?.userId === item?.authorId
+        },
+      },
+    },
+  })
+}
+```
+
+## Key Features
+
+### 1. Zero Boilerplate
+
+No manual User model, no manual session handling, no manual auth routes. Everything is auto-generated.
+
+### 2. Type-Safe Sessions
+
+```typescript
+authConfig({
+  sessionFields: ['userId', 'email', 'name', 'role'],
+})
+
+// Session type is inferred:
+// { userId: string, email: string, name: string, role: string }
+```
+
+### 3. Extensible User Model
+
+```typescript
+authConfig({
+  extendUserList: {
+    fields: {
+      role: select({ options: [...] }),
+      company: text(),
+    }
+  }
+})
+```
+
+### 4. Pre-Built UI with Customization
+
+All forms accept custom props and callbacks:
+
+```typescript
+<SignInForm
+  authClient={authClient}
+  redirectTo="/dashboard"
+  showSocialProviders={true}
+  socialProviders={['github', 'google']}
+  onSuccess={() => console.log('Success!')}
+  onError={(error) => console.error(error)}
+  className="my-custom-class"
+/>
+```
+
+### 5. Multiple Auth Methods
+
+Configure what you need:
+
+```typescript
+authConfig({
+  emailAndPassword: { enabled: true },
+  emailVerification: { enabled: true },
+  passwordReset: { enabled: true },
+  socialProviders: {
+    github: { clientId: '...', clientSecret: '...' },
+    google: { clientId: '...', clientSecret: '...' },
+  },
+})
+```
+
+## Architecture Decisions
+
+### 1. Better-Auth vs NextAuth/Clerk
+
+**Why better-auth?**
+
+- TypeScript-first
+- Framework-agnostic (works with any React framework)
+- Simpler configuration
+- No dependency on external services
+- Modern security practices built-in
+
+### 2. Auto-Generation vs Manual Setup
+
+The package auto-generates all auth tables to:
+
+- Reduce boilerplate
+- Ensure consistency with better-auth schema
+- Make updates easier (just update package version)
+- Provide a "batteries included" experience
+
+Users can still extend the User model via `extendUserList`.
+
+### 3. Configurable Session Fields
+
+Instead of including all user data in session, developers choose what they need:
+
+```typescript
+sessionFields: ['userId', 'email', 'name']
+```
+
+This balances convenience with performance (smaller session objects).
+
+### 4. Silent Access Control Integration
+
+Sessions are automatically available in all access control functions. No manual `getSession()` calls needed.
+
+### 5. Component Registry Pattern
+
+UI components follow the stack's registry pattern:
+
+- Pre-built components for common use cases
+- Fully replaceable for custom designs
+- Props-based customization for quick tweaks
+
+## Testing the Integration
+
+See `examples/auth-demo` for a complete working example.
+
+### Quick Test
+
+```bash
+cd examples/auth-demo
+pnpm install
+pnpm generate
+pnpm db:push
+pnpm dev
+```
+
+Visit `http://localhost:3003/sign-up` to create an account!
+
+## Future Enhancements
+
+Potential additions:
+
+1. **Two-Factor Authentication** - Add 2FA support via better-auth plugins
+2. **Magic Links** - Email-based passwordless auth
+3. **Role-Based Access Control** - Built-in role checking helpers
+4. **Admin UI Integration** - Show auth tables in admin panel
+5. **Session Management UI** - View/revoke active sessions
+6. **Audit Logging** - Track auth events
+
+## Files Created
+
+```
+packages/auth/
+├── src/
+│   ├── config/
+│   │   ├── index.ts        # withAuth(), authConfig()
+│   │   └── types.ts        # Auth config types
+│   ├── lists/
+│   │   └── index.ts        # User, Session, Account, Verification
+│   ├── server/
+│   │   └── index.ts        # createAuth()
+│   ├── client/
+│   │   └── index.ts        # createClient()
+│   ├── ui/
+│   │   ├── components/
+│   │   │   ├── SignInForm.tsx
+│   │   │   ├── SignUpForm.tsx
+│   │   │   └── ForgotPasswordForm.tsx
+│   │   └── index.ts
+│   └── index.ts            # Main exports
+├── package.json
+├── tsconfig.json
+└── README.md
+
+examples/auth-demo/
+├── app/
+│   ├── api/auth/[...all]/route.ts
+│   ├── sign-in/page.tsx
+│   ├── sign-up/page.tsx
+│   └── forgot-password/page.tsx
+├── lib/
+│   ├── auth.ts
+│   └── auth-client.ts
+├── opensaas.config.ts
+├── .env
+└── README.md
+```
+
+## Performance Considerations
+
+### Session Caching
+
+Better-auth supports cookie caching to reduce database queries:
+
+```typescript
+// Future enhancement
+authConfig({
+  session: {
+    cookieCaching: true, // Validate at cookie level
+  },
+})
+```
+
+### Session Field Selection
+
+Only include necessary fields to keep session objects small:
+
+```typescript
+// Good - minimal session
+sessionFields: ['userId']
+
+// Less optimal - large session
+sessionFields: ['userId', 'email', 'name', 'bio', 'preferences', ...]
+```
+
+## Security
+
+### Built-in Security
+
+Better-auth provides:
+
+- ✅ Bcrypt password hashing
+- ✅ CSRF protection
+- ✅ Secure session tokens
+- ✅ XSS protection
+- ✅ Rate limiting (configurable)
+
+### Environment Variables
+
+Always set these in production:
+
+```bash
+BETTER_AUTH_SECRET=<strong-random-secret>
+BETTER_AUTH_URL=https://your-domain.com
+```
+
+Generate secrets with:
+
+```bash
+openssl rand -base64 32
+```
+
+## Conclusion
+
+The `@opensaas/stack-auth` package provides a complete, production-ready authentication solution for OpenSaas Stack applications. It follows the stack's design principles:
+
+- Config-first approach
+- Self-contained field/list definitions
+- Type-safe throughout
+- Minimal boilerplate
+- Extensible and customizable
+
+Developers can go from zero to fully authenticated app in under 5 minutes! 🎉