Implement @objectstack/plugin-auth with Better-Auth integration

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

.env.example

@@ -0,0 +1,20 @@
+# Better-Auth Configuration
+# Required: Secret key for signing tokens (minimum 32 characters)
+BETTER_AUTH_SECRET=your-super-secret-key-change-this-in-production-min-32-chars
+
+# Required: Base URL where your application is hosted
+BETTER_AUTH_URL=http://localhost:3000
+
+# Optional: Node environment
+NODE_ENV=development
+
+# Optional: Google OAuth (if using social auth)
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# Optional: GitHub OAuth (if using social auth)
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# Optional: Database connection (for ObjectQL)
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname

.gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+*.log
+.DS_Store
+.env
+.env.local
+*.tsbuildinfo

README.md

@@ -1 +1,262 @@
-# plugin-auth
+# @objectstack/plugin-auth
+
+🔐 Better-Auth plugin for ObjectStack - A battery-included authentication and identity layer for the ObjectStack ecosystem.
+
+## Features
+
+- **Storage Agnostic**: Uses ObjectQL as the storage adapter, meaning authentication data can live in Postgres, Redis, or even Excel files
+- **Type Safe**: End-to-end typed session objects with TypeScript
+- **RBAC Integration**: Automatic permission injection from ObjectOS into session objects
+- **React Hooks**: Pre-built hooks for easy client-side integration
+- **Framework Agnostic**: Works with any JavaScript framework
+
+## Installation
+
+```bash
+npm install @objectstack/plugin-auth better-auth
+```
+
+## Quick Start
+
+### Server Setup
+
+```typescript
+import { createAuthPlugin } from '@objectstack/plugin-auth';
+import { createQLClient } from '@objectstack/ql';
+
+// Initialize ObjectQL client
+const ql = createQLClient({
+  driver: 'postgres', // or 'redis', 'excel', etc.
+  connection: process.env.DATABASE_URL,
+});
+
+// Create auth plugin
+const authPlugin = createAuthPlugin({
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: process.env.BETTER_AUTH_URL,
+  
+  // RBAC Integration: Inject permissions into session
+  onGetPermissions: async (userId) => {
+    return await os.getPermissions(userId);
+  },
+  
+  // Optional: Configure email/password auth
+  emailProvider: {
+    enabled: true,
+    sendVerificationEmail: async ({ user, url }) => {
+      // Send email logic
+    },
+  },
+  
+  // Optional: Configure social providers
+  socialProviders: [
+    {
+      id: 'google',
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    },
+  ],
+});
+
+// Enable the plugin
+await authPlugin.onEnable({
+  ql,
+  app: yourExpressApp, // or any compatible server
+});
+```
+
+### Client Setup (React)
+
+```typescript
+import { useSession, usePermissions, signIn, signOut } from '@objectstack/plugin-auth';
+
+function App() {
+  const { data: session, isPending } = useSession();
+  const { permissions } = usePermissions();
+
+  if (isPending) return <div>Loading...</div>;
+
+  if (!session) {
+    return (
+      <button onClick={() => signIn.email({ 
+        email: 'user@example.com', 
+        password: 'password' 
+      })}>
+        Sign In
+      </button>
+    );
+  }
+
+  return (
+    <div>
+      <p>Welcome, {session.user.name}!</p>
+      <p>Email: {session.user.email}</p>
+      <p>Permissions: {permissions?.join(', ')}</p>
+      <button onClick={() => signOut()}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+## Architecture
+
+### ObjectQL Adapter
+
+The plugin implements a custom Better-Auth adapter that maps all CRUD operations to ObjectQL entities:
+
+```typescript
+// Example: Creating a user
+const user = await ql.entity('User').create({
+  data: {
+    email: 'user@example.com',
+    name: 'John Doe',
+  },
+});
+```
+
+This means if ObjectQL is configured with an Excel driver, new users will be written as rows in an Excel file!
+
+### Schema Definition
+
+The plugin defines authentication entities in GraphQL:
+
+```graphql
+type User {
+  id: ID!
+  email: String!
+  emailVerified: Boolean!
+  name: String
+  image: String
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+type Session {
+  id: ID!
+  userId: ID!
+  expiresAt: DateTime!
+  token: String!
+  # ... more fields
+}
+```
+
+### RBAC Integration
+
+The plugin bridges Better-Auth (authentication) with ObjectOS (authorization):
+
+```typescript
+// In server config
+onGetPermissions: async (userId) => {
+  // Query ObjectOS for permissions
+  return await os.getPermissions(userId);
+}
+
+// In client
+const { permissions } = usePermissions();
+// permissions are automatically available in session
+```
+
+## API Reference
+
+### Server API
+
+#### `createAuthPlugin(config)`
+
+Creates the auth plugin instance.
+
+**Options:**
+- `secret` - Secret key for signing tokens
+- `baseURL` - Base URL for auth endpoints
+- `trustedOrigins` - Array of trusted origins for CORS
+- `emailProvider` - Email provider configuration
+- `socialProviders` - Array of social provider configs
+- `onGetPermissions` - Callback to get user permissions
+
+#### `createAuthServer(config)`
+
+Low-level API to create Better-Auth server instance.
+
+#### `getSession(auth, request)`
+
+Extract session from HTTP request.
+
+### Client API
+
+#### `useSession()`
+
+React hook to get current session.
+
+```typescript
+const { data: session, isPending, error } = useSession();
+```
+
+#### `usePermissions()`
+
+React hook to get user permissions.
+
+```typescript
+const { permissions, isPending, isAuthenticated } = usePermissions();
+```
+
+#### `useHasPermission(permission)`
+
+Check if user has a specific permission.
+
+```typescript
+const { hasPermission, isPending } = useHasPermission('admin.write');
+```
+
+#### `signIn`
+
+Sign in methods for different providers.
+
+```typescript
+// Email/password
+await signIn.email({ email, password });
+
+// Social
+await signIn.social({ provider: 'google' });
+```
+
+#### `signOut`
+
+Sign out the current user.
+
+```typescript
+await signOut();
+```
+
+## Environment Variables
+
+```bash
+BETTER_AUTH_SECRET=your-secret-key-min-32-chars
+BETTER_AUTH_URL=http://localhost:3000
+NODE_ENV=development
+```
+
+## Directory Structure
+
+```
+src/
+├── adapter/
+│   └── index.ts          # ObjectQL Adapter implementation
+├── schema/
+│   └── auth.gql          # GraphQL schema definitions
+├── client/
+│   └── hooks.ts          # React hooks
+├── server/
+│   └── index.ts          # Server-side initialization
+└── index.ts              # Main entry point
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.

example.config.ts

@@ -0,0 +1,78 @@
+/**
+ * Example configuration for @objectstack/plugin-auth
+ * 
+ * Copy this file to your project and customize as needed
+ */
+
+import { createAuthPlugin } from '@objectstack/plugin-auth';
+import type { AuthPluginConfig } from '@objectstack/plugin-auth';
+
+// Example: Full configuration with all options
+export const authConfig: AuthPluginConfig = {
+  // Required: Secret for signing tokens (min 32 characters)
+  secret: process.env.BETTER_AUTH_SECRET,
+
+  // Required: Base URL where your app is hosted
+  baseURL: process.env.BETTER_AUTH_URL || 'http://localhost:3000',
+
+  // Optional: Additional trusted origins for CORS
+  trustedOrigins: [
+    'http://localhost:5173', // Vite dev server
+    'https://yourdomain.com',
+  ],
+
+  // Optional: Email/password authentication
+  emailProvider: {
+    enabled: true,
+    
+    // Implement your email sending logic
+    sendVerificationEmail: async ({ user, url }) => {
+      console.log(`Send verification email to ${user.email}: ${url}`);
+      // Example: await sendEmail(user.email, 'Verify Email', url);
+    },
+    
+    // Implement password reset email
+    sendResetPasswordEmail: async ({ user, url }) => {
+      console.log(`Send password reset to ${user.email}: ${url}`);
+      // Example: await sendEmail(user.email, 'Reset Password', url);
+    },
+  },
+
+  // Optional: Social authentication providers
+  socialProviders: [
+    // Google OAuth
+    {
+      id: 'google',
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+    
+    // GitHub OAuth
+    {
+      id: 'github',
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+  ],
+
+  // Optional: RBAC Integration
+  // Inject ObjectOS permissions into session
+  onGetPermissions: async (userId: string) => {
+    // Example: Query your permission system
+    // const permissions = await os.getPermissions(userId);
+    // return permissions;
+    
+    // For now, return mock permissions
+    return ['user.read', 'user.write'];
+  },
+};
+
+// Example: Minimal configuration
+export const minimalAuthConfig: AuthPluginConfig = {
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: process.env.BETTER_AUTH_URL,
+};
+
+// Usage in your app:
+// const authPlugin = createAuthPlugin(authConfig);
+// await authPlugin.onEnable({ ql, app });

objectstack.config.ts

@@ -0,0 +1,16 @@
+import type { ObjectStackConfig } from '@objectstack/protocol';
+
+const config: ObjectStackConfig = {
+  type: 'plugin',
+  name: '@objectstack/plugin-auth',
+  version: '0.1.0',
+  description: 'Better-Auth authentication plugin for ObjectStack',
+  entities: ['./src/schema/*.gql'],
+  dependencies: {
+    '@objectstack/ql': '*',
+    '@objectstack/protocol': '*',
+    'better-auth': '^1.0.0'
+  }
+};
+
+export default config;