miolo 3.0.0-beta.154 → 3.0.0-beta.155

package/template/.agent/skills/miolo-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: miolo-auth
-description: Authentication configuration and strategies for miolo applications. Use when implementing, modifying, or troubleshooting authentication, configuring auth strategies (credentials, basic, guest), or setting up user sessions.
+description: Authentication configuration and strategies for miolo applications. Use when implementing, modifying, or troubleshooting authentication, configuring auth strategies (passport, basic, guest), or setting up user sessions.
 ---
 
 # Miolo Authentication
@@ -9,14 +9,13 @@ Authentication configuration and strategies for miolo applications.
 
 ## Authentication Strategies
 
-Miolo supports multiple built-in authentication strategies in `src/server/miolo/auth/`:
+Miolo supports multiple built-in authentication strategies:
 
 ```
 src/server/miolo/auth/
-├── credentials.mjs    # Username/password authentication
+├── passport.mjs       # Passport-based auth (local + OAuth2)
 ├── basic.mjs          # HTTP Basic authentication
-├── guest.mjs          # Guest/anonymous access
-└── custom.mjs         # Custom authentication logic
+└── guest.mjs          # Guest/anonymous access
 ```
 
 ## Configuring Authentication
@@ -24,56 +23,189 @@ src/server/miolo/auth/
 Authentication is configured in `src/server/miolo/index.mjs`:
 
 ```javascript
-import auth from './auth/credentials.mjs'
+import passport from './auth/passport.mjs'
 // or: import auth from './auth/basic.mjs'
 // or: import auth from './auth/guest.mjs'
 
 export default {
-  auth,
+  auth: {
+    passport  // Enables Passport.js with local + Google OAuth2
+  },
   // ... other config
 }
 ```
 
-## Credentials Strategy (Default)
+## Passport Strategy (Recommended)
 
-Username/password authentication with database-backed users.
+Unified authentication using Passport.js supporting both **local (username/password)** and **Google OAuth2**.
 
-**File:** `src/server/miolo/auth/credentials.mjs`
+**File:** `src/server/miolo/auth/passport.mjs`
 
 ```javascript
-import { db_user_auth } from '#server/db/io/users/auth.mjs'
+import { db_find_user_by_id, db_auth_user, 
+         db_user_find_or_create_from_google } from '#server/db/io/users/auth.mjs'
+
+const get_user_id = (user, done, ctx) => {
+  const uid = user?.id
+  if (uid != undefined) {
+    return done(null, uid)
+  } else {
+    const err = new Error('User id is undefined')
+    return done(err, null)
+  }
+}
 
-export default {
-  urls: {
-    login: '/page/login',
-    logout: '/page/logout',
-    home: '/'
-  },
+const find_user_by_id = (id, done, ctx) => {
+  ctx.miolo.logger.debug(`[auth] find_user_by_id() - Searching user id ${id}`)
+  db_find_user_by_id(ctx.miolo, id).then(user => {
+    if (user == undefined) {
+      const err = new Error('User not found')
+      return done(err, null)
+    } else {
+      return done(null, user)
+    }
+  })
+}
 
-  async login(ctx, credentials) {
-    const { username, password } = credentials
-    
-    const user = await db_user_auth(ctx, { username, password })
-    
-    if (!user) {
-      return { ok: false, error: 'Invalid credentials' }
+const local_auth_user = (username, password, done, ctx) => {
+  ctx.miolo.logger.debug(`[auth][local] Checking credentials for ${username}`)
+  
+  db_auth_user(ctx.miolo, username, password).then(([user, msg]) => {
+    if (user == undefined) {
+      const err = new Error(msg)
+      return done(err, null)
+    } else {
+      return done(null, user)
     }
-    
-    return { ok: true, user }
-  },
+  })
+}
 
-  async logout(ctx) {
-    // Cleanup if needed
-    return { ok: true }
+const google_auth_user = async (accessToken, refreshToken, profile, done, ctx) => {
+  try {
+    const google_id = profile.id
+    const email = profile.emails?.[0]?.value
+    const name = profile.displayName
+    const google_picture = profile.photos?.[0]?.value
+
+    ctx.miolo.logger.info(`[auth][google] Authenticated user: ${email}`)
+
+    return db_user_find_or_create_from_google(
+      ctx.miolo, email, name, google_id, google_picture
+    ).then(([user, msg]) => {
+      if (user == undefined) {
+        const err = new Error(msg)
+        return done(err, null)
+      } else {
+        return done(null, user)
+      }
+    })
+  } catch (error) {
+    ctx.miolo.logger.error(`[auth][google] Error: ${error}`)
+    return done(error, null)
   }
 }
+
+export default {
+  get_user_id,
+  find_user_by_id,
+  local_auth_user,
+  local_url_login: '/login',
+  local_url_logout: '/logout',
+  local_url_login_redirect: undefined,
+  local_url_logout_redirect: '/',
+  google_auth_user,
+  google_client_id: process.env.MIOLO_AUTH_GOOGLE_CLIENT_ID,
+  google_client_secret: process.env.MIOLO_AUTH_GOOGLE_CLIENT_SECRET,
+  google_url_login: '/auth/google',
+  google_url_callback: process.env.MIOLO_AUTH_GOOGLE_CALLBACK_URL || '/auth/google/callback',
+  google_url_logout: '/logout',
+  google_url_logout_redirect: '/'
+}
 ```
 
-**Key elements:**
-- `urls` - Define login, logout, home page paths
-- `login(ctx, credentials)` - Validates credentials, returns user or error
-- `logout(ctx)` - Optional cleanup on logout
-- Uses database function from `db/io/users/auth.mjs`
+### Passport Configuration Elements
+
+#### Common Functions
+- `get_user_id(user, done, ctx)` - Extracts user ID for session storage
+- `find_user_by_id(id, done, ctx)` - Retrieves user by ID (session deserialization)
+
+#### Local Authentication (Username/Password)
+- `local_auth_user(username, password, done, ctx)` - Validates credentials
+- `local_url_login` - Login endpoint (default: `/login`)
+- `local_url_logout` - Logout endpoint (default: `/logout`)
+- `local_url_login_redirect` - Redirect after login (optional)
+- `local_url_logout_redirect` - Redirect after logout (default: `/`)
+
+#### Google OAuth2 Authentication
+- `google_auth_user(accessToken, refreshToken, profile, done, ctx)` - Handles Google profile
+- `google_client_id` - Google OAuth2 client ID (from env)
+- `google_client_secret` - Google OAuth2 client secret (from env)
+- `google_url_login` - OAuth initiation endpoint (default: `/auth/google`)
+- `google_url_callback` - OAuth callback endpoint (from env or `/auth/google/callback`)
+- `google_url_logout` - Logout endpoint (default: `/logout`)
+- `google_url_logout_redirect` - Redirect after logout (default: `/`)
+
+### Environment Variables
+
+**Required for Google OAuth2 (.env):**
+```
+MIOLO_AUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+MIOLO_AUTH_GOOGLE_CLIENT_SECRET=your-client-secret
+MIOLO_AUTH_GOOGLE_CALLBACK_URL=http://localhost:8001/auth/google/callback
+```
+
+**Session configuration:**
+```
+MIOLO_SESSION_SALT=your-random-salt-here
+MIOLO_SESSION_SECRET=your-session-secret
+MIOLO_SESSION_SAME_SITE=lax  # Required for Google OAuth2
+```
+
+### Google Cloud Console Setup
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project or select existing one
+3. Enable Google+ API
+4. Create OAuth 2.0 credentials:
+   - Application type: Web application
+   - Authorized JavaScript origins: `http://localhost:8001`
+   - Authorized redirect URIs: `http://localhost:8001/auth/google/callback`
+5. Copy Client ID and Client Secret to your `.env`
+
+### OAuth2 Flow
+
+1. User clicks "Login with Google" → `window.location.href = '/auth/google'`
+2. Server redirects to Google authentication page
+3. User authenticates with Google
+4. Google redirects back to `/auth/google/callback`
+5. `google_auth_user` processes Google profile
+6. User found/created in database
+7. User logged in and redirected to home
+
+### Frontend Login Button
+
+```jsx
+// For local login (POST form)
+<form onSubmit={handleLocalLogin}>
+  <input name="username" />
+  <input name="password" type="password" />
+  <button type="submit">Login</button>
+</form>
+
+// For Google OAuth2 (Navigate to endpoint)
+<button onClick={() => window.location.href = '/auth/google'}>
+  Login with Google
+</button>
+```
+
+**IMPORTANT:** Google OAuth2 requires **navigation**, not fetch/AJAX:
+```javascript
+// ✅ CORRECT
+window.location.href = '/auth/google'
+
+// ❌ WRONG - Causes CORS errors
+fetch('/auth/google')
+```
 
 ## Basic Authentication
 
@@ -86,7 +218,6 @@ export default {
   async login(ctx, credentials) {
     const { username, password } = credentials
     
-    // Validate against environment or database
     if (username === process.env.API_USER && 
         password === process.env.API_PASSWORD) {
       return {
@@ -100,19 +231,16 @@ export default {
 }
 ```
 
-## Guest/Anonymous Access
+## Guest Authentication
 
-Allow unauthenticated access (useful for read-only apps).
+Anonymous access without credentials.
 
 **File:** `src/server/miolo/auth/guest.mjs`
 
 ```javascript
 export default {
-  async login(ctx) {
-    return {
-      ok: true,
-      user: { id: 0, username: 'guest', role: 'guest' }
-    }
+  make_guest_token: (session) => {
+    return `guest-${Date.now()}-${Math.random()}`
   }
 }
 ```
@@ -124,12 +252,15 @@ After successful login, user is available in routes:
 ```javascript
 export async function r_protected_route(ctx, params) {
   const user = ctx.state.user
+  const isAuthenticated = ctx.session.authenticated
   
   // User object contains:
   // - id
-  // - username
+  // - username (for local auth)
   // - email
-  // - any other fields returned from login
+  // - name
+  // - google_id (for Google auth)
+  // - google_picture (for Google auth)
   
   ctx.miolo.logger.info(`User ${user.id} accessing route`)
   
@@ -160,36 +291,91 @@ export default [{
 }]
 ```
 
-## Database User Authentication
+## Database Functions
 
-User authentication typically queries the database:
+### User Authentication (Local)
 
 **File:** `src/server/db/io/users/auth.mjs`
 
 ```javascript
 import { sha512 } from '#server/utils/crypt.mjs'
 
-export async function db_user_auth(ctx, params) {
-  const { username, password } = params
+export async function db_auth_user(miolo, username, password) {
+  const conn = miolo.db
+  const options = { transaction: undefined }
   
   const salt = process.env.MIOLO_SESSION_SALT
   const hashedPassword = sha512(password, salt)
   
-  const user = await ctx.miolo.db.query(`
-    SELECT id, username, email, name
+  const query = `
+    SELECT id, username, name, email, active, admin
+    FROM u_user
+    WHERE username = $1 AND password = $2 AND active = 1`
+  
+  const ruser = await conn.selectOne(query, [username, hashedPassword], options)
+  
+  if (ruser?.id == undefined) {
+    return [undefined, 'Invalid credentials']
+  } else {
+    return [ruser, undefined]
+  }
+}
+```
+
+### User by ID
+
+```javascript
+export async function db_find_user_by_id(miolo, id) {
+  const conn = miolo.db
+  const options = { transaction: undefined }
+  
+  const query = `
+    SELECT id, username, name, email, active, admin, 
+           google_id, google_picture
     FROM u_user
-    WHERE username = $1 AND password = $2
-  `, [username, hashedPassword])
+    WHERE id = $1`
   
-  return user.rows[0] || null
+  const ruser = await conn.selectOne(query, [id], options)
+  return ruser
 }
 ```
 
-**Key elements:**
-- Hash password with session salt
-- Query user by username and hashed password
-- Return user object or null
-- Don't return password in user object
+### Google OAuth2 User
+
+```javascript
+export async function db_user_find_or_create_from_google(
+  miolo, email, name, google_id, google_picture
+) {
+  const conn = miolo.db
+  const options = { transaction: undefined }
+  
+  // Try to find existing user by google_id
+  const query = `
+    SELECT id, username, name, email, active, admin, 
+           google_id, google_picture
+    FROM u_user
+    WHERE google_id = $1`
+  
+  const ruser = await conn.selectOne(query, [google_id], options)
+  
+  if (ruser?.id == undefined) {
+    // Create new user
+    const UUser = await conn.get_model('u_user')
+    const data = {
+      name,
+      email,
+      google_id,
+      google_picture,
+      active: 1
+    }
+    const uid = await UUser.insert(data, options)
+    data.id = uid
+    return [data, undefined]
+  } else {
+    return [ruser, undefined]
+  }
+}
+```
 
 ## Password Hashing
 
@@ -207,71 +393,38 @@ const hashedPassword = sha512(plainPassword, salt)
 MIOLO_SESSION_SALT=your-random-salt-here
 ```
 
-## Changing Password
+## Database Trigger for Password Hashing
 
-Pattern for password change:
-
-**File:** `src/server/db/io/users/pwd.mjs`
+**File:** `src/server/db/triggers/user.mjs`
 
 ```javascript
 import { sha512 } from '#server/utils/crypt.mjs'
 
-export async function db_user_change_password(ctx, params) {
-  const { user_id, old_password, new_password } = params
-  
-  const salt = process.env.MIOLO_SESSION_SALT
-  
-  // Verify old password
-  const user = await ctx.miolo.db.query(`
-    SELECT id FROM u_user
-    WHERE id = $1 AND password = $2
-  `, [user_id, sha512(old_password, salt)])
-  
-  if (user.rows.length === 0) {
-    throw new Error('Invalid current password')
+async function beforeInsertUser(conn, params, options) {
+  const raw_pwd = params?.password
+  if (raw_pwd) {
+    const cry_pwd = sha512(raw_pwd, process.env.MIOLO_SESSION_SALT)
+    params.password = cry_pwd
   }
-  
-  // Update to new password
-  const newHash = sha512(new_password, salt)
-  await ctx.miolo.db.query(`
-    UPDATE u_user
-    SET password = $1
-    WHERE id = $2
-  `, [newHash, user_id])
-
-  return { changed: true }
+  return [params, options, true]
 }
-```
 
-## Custom Authentication
+export default {
+  before_insert: beforeInsertUser
+}
+```
 
-For complex scenarios, implement custom logic:
+## Session Configuration
 
-**File:** `src/server/miolo/auth/custom.mjs`
+**Important for OAuth2:** The session must use `sameSite: 'lax'` to work with Google redirects.
 
+**In** `packages/miolo/src/config/defaults.mjs`:
 ```javascript
-export default {
-  urls: {
-    login: '/auth/custom',
-    logout: '/auth/logout',
-    home: '/'
-  },
-
-  async login(ctx, credentials) {
-    // Custom logic: OAuth, LDAP, etc.
-    const user = await yourCustomAuthLogic(credentials)
-    
-    if (!user) {
-      return { ok: false, error: 'Authentication failed' }
-    }
-    
-    return { ok: true, user }
-  },
-
-  async logout(ctx) {
-    // Custom cleanup
-    await yourCustomLogoutLogic(ctx)
-    return { ok: true }
+session: {
+  options: {
+    sameSite: 'lax',  // Required for OAuth2
+    secure: false,     // Set true in production with HTTPS
+    maxAge: 86400000,  // 24 hours
   }
 }
 ```
@@ -280,16 +433,18 @@ export default {
 
 1. **Never store plain passwords** - Always hash with salt
 2. **Use strong session salt** - Set `MIOLO_SESSION_SALT` in `.env`
-3. **Don't return passwords** - User object should never include password
+3. **Don't return passwords** - User object should never include password field
 4. **Validate on server** - Never trust client-side authentication
 5. **Use HTTPS in production** - Protect credentials in transit
-6. **Rate limit login attempts** - Prevent brute force attacks
-7. **Log authentication events** - Track successful and failed logins
+6. **Set secure cookies in production** - `MIOLO_SESSION_SECURE=true`
+7. **Use sameSite=lax for OAuth2** - Required for external OAuth redirects
+8. **Rate limit login attempts** - Prevent brute force attacks
+9. **Log authentication events** - Track successful and failed logins
 
 ## Examples from miolo-sample
 
 See actual implementations:
-- `src/server/miolo/auth/credentials.mjs` - Default auth strategy
-- `src/server/db/io/users/auth.mjs` - User authentication query
-- `src/server/db/io/users/pwd.mjs` - Password change logic
+- `src/server/miolo/auth/passport.mjs` - Passport authentication config
+- `src/server/db/io/users/auth.mjs` - User authentication queries
+- `src/server/db/triggers/user.mjs` - Password hashing trigger
 - `src/server/utils/crypt.mjs` - Hashing utilities

package/template/.agent/skills/miolo-session-context/SKILL.md

@@ -59,11 +59,12 @@ export async function r_get_profile(ctx, params) {
 **Available properties:**
 - `ctx.session.user` - User object (or `null`)
 - `ctx.session.authenticated` - Boolean authentication status
+- `ctx.session.auth_method` - Authentication method (local, google, etc.)
 - `ctx.session.token` - Auth token (guest auth only)
 
 ### Credentials Auth Methods
 
-When using credentials authentication strategy, additional methods are available:
+When using local authentication strategy, additional methods are available:
 
 ```javascript
 export async function r_user_login(ctx, params) {
@@ -99,14 +100,14 @@ export async function r_protected_route(ctx, params) {
 }
 ```
 
-**Available methods (credentials auth):**
+**Available methods (local auth):**
 - `ctx.isAuthenticated()` - Returns `true` if user is authenticated
 - `ctx.isUnauthenticated()` - Returns `true` if user is NOT authenticated
 - `await ctx.login(username, password)` - Attempt to authenticate user
 - `ctx.logout()` - End user session
 
 **User access:**
-- `ctx.state.user` - Authenticated user object (credentials auth)
+- `ctx.state.user` - Authenticated user object (local auth)
 - `ctx.session.user` - User object (all auth methods)
 
 ### Backend Usage Example

package/template/.env

@@ -21,6 +21,13 @@ MIOLO_REQUEST_SLOW=4 # seconds to consider slow a request
 MIOLO_GEOIP_ENABLED=true
 MIOLO_GEOIP_LOCAL_IPS=127.0.0.1,172.22.0.1,172.19.0.1
 
+#
+# If google auth
+#
+MIOLO_AUTH_GOOGLE_CLIENT_ID=123456
+MIOLO_AUTH_GOOGLE_CLIENT_SECRET=123456
+MIOLO_AUTH_GOOGLE_CALLBACK_URL=/auth/google/callback
+
 #
 # Session
 #
@@ -30,7 +37,7 @@ MIOLO_SESSION_SECRET=00000000-0000-0000-0000-000000000000
 MIOLO_SESSION_MAX_AGE=864000000
 MIOLO_SESSION_SECURE=false
 MIOLO_SESSION_RENEW=true
-MIOLO_SESSION_SAME_SITE=strict # lax | strict
+MIOLO_SESSION_SAME_SITE=lax # lax | strict
 
 #
 # Database
@@ -51,7 +58,7 @@ MIOLO_DB_POOL_IDLE_TIMEOUT_MS=10000
 # Logging
 #
 
-MIOLO_LOG_LEVEL=info
+MIOLO_LOG_LEVEL=debug
 MIOLO_LOG_CONSOLE_ENABLED=true
 MIOLO_LOG_FILE_ENABLED=false
 MIOLO_LOG_MAIL_ENABLED=false

package/template/db/sql/01_users.sql

@@ -10,6 +10,9 @@ CREATE TABLE u_user (
 
     admin boolean,
 
+    google_id text,
+    google_picture text,
+
     last_login_date integer,
     last_login_ip text,
     login_count integer DEFAULT 0,

package/template/package.json

@@ -36,17 +36,17 @@
     "@radix-ui/react-separator": "^1.1.8",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@stepperize/react": "^6.0.0",
-    "@tailwindcss/postcss": "^4.1.18",
+    "@stepperize/react": "^6.0.1",
+    "@tailwindcss/postcss": "^4.2.0",
     "@tanstack/react-table": "^8.21.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "farrapa": "^3.0.0-beta.3",
     "intre": "^3.0.0-beta.3",
     "joi": "^18.0.2",
-    "lucide-react": "^0.563.0",
-    "miolo-cli": "^3.0.0-beta.154",
-    "miolo-react": "^3.0.0-beta.154",
+    "lucide-react": "^0.574.0",
+    "miolo-cli": "^3.0.0-beta.155",
+    "miolo-react": "^3.0.0-beta.155",
     "next-themes": "^0.4.6",
     "radix-ui": "^1.4.3",
     "react": "^19.2.4",
@@ -55,12 +55,12 @@
     "recharts": "^3.7.0",
     "sonner": "^2.0.7",
     "tailwind": "^4.0.0",
-    "tailwind-merge": "^3.4.0",
+    "tailwind-merge": "^3.4.1",
     "tinguir": "^0.0.7",
     "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
-    "miolo": "^3.0.0-beta.154",
+    "miolo": "^3.0.0-beta.155",
     "sass-embedded": "^1.97.3",
     "xeira": "^2.0.0-beta.10"
   },

package/template/src/cli/pages/offline/Login.jsx

@@ -1,10 +1,8 @@
 import React from 'react'
 
-import useSessionContext from '#cli/context/session/useSessionContext.mjs'
 import { LoginForm } from "./LoginForm.jsx"
 
 const Login = () => {
-  const {login} = useSessionContext()
   
   return (
     <div className="grid min-h-svh lg:grid-cols-2">
@@ -29,7 +27,6 @@ const Login = () => {
         <div className="flex flex-1 items-center justify-center">
           <div className="w-full max-w-xs">
             <LoginForm
-               onLogin = {login}
               /* TODO orgotLink*/
               />
           </div>