@eaccess/auth 0.1.21 → 1.0.0

package/README.md

@@ -1,4 +1,4 @@
-# @prsm/easy-auth
+# @eaccess/auth
 
 An Express authentication middleware specifically designed for Postgres that provides complete authentication functionality without being tied to any specific ORM, query builder, or user table structure. Comprehensive auth without overwhelming complexity. A clean separation of concerns -- not conflating authentication with user management.
 
@@ -17,7 +17,7 @@ An Express authentication middleware specifically designed for Postgres that pro
 ## Installation
 
 ```bash
-npm install @prsm/easy-auth express-session
+npm install @eaccess/auth express-session
 ```
 
 ## Quick Start
@@ -26,7 +26,7 @@ npm install @prsm/easy-auth express-session
 import express from 'express';
 import session from 'express-session';
 import { Pool } from 'pg';
-import { createAuthMiddleware, createAuthTables } from '@prsm/easy-auth';
+import { createAuthMiddleware, createAuthTables } from '@eaccess/auth';
 
 const app = express();
 const pool = new Pool({ connectionString: 'postgresql://...' });
@@ -93,7 +93,7 @@ app.get('/profile', (req, res) => {
   if (!req.auth.isLoggedIn()) {
     return res.status(401).json({ error: 'Not logged in' });
   }
-  
+
   res.json({
     email: req.auth.getEmail(),
     status: req.auth.getStatusName(),
@@ -113,7 +113,7 @@ Easy-auth supports OAuth providers (GitHub, Google, Azure) with a clean, extensi
 import express from 'express';
 import session from 'express-session';
 import { Pool } from 'pg';
-import { createAuthMiddleware, createAuthTables, type OAuthUserData } from '@prsm/easy-auth';
+import { createAuthMiddleware, createAuthTables, type OAuthUserData } from '@eaccess/auth';
 
 const app = express();
 const pool = new Pool({ connectionString: 'postgresql://...' });
@@ -131,11 +131,11 @@ const authConfig = {
       name: userData.name || userData.username,
       email: userData.email,
     }).returning();
-    
+
     return user.id; // Return the new user's ID
   },
   tablePrefix: 'auth_',
-  
+
   // OAuth provider configuration
   providers: {
     github: {
@@ -217,7 +217,7 @@ app.get('/auth/google/callback', async (req, res) => {
 ### OAuth Flow Explained
 
 1. **User clicks "Login with GitHub"** → Browser goes to `/auth/github`
-2. **Server redirects to GitHub** → User sees GitHub's login page  
+2. **Server redirects to GitHub** → User sees GitHub's login page
 3. **User authorizes your app** → GitHub redirects to `/auth/github/callback?code=abc123`
 4. **Server processes callback** → `handleCallback()` does:
    - Exchange code for access token
@@ -278,16 +278,16 @@ app.get('/auth/github/callback', async (req, res) => {
   try {
     // Get user data without logging in
     const userData = await req.auth.providers.github.getUserData(req);
-    
+
     // Your custom logic here
     const existingUser = await findUserByEmail(userData.email);
     if (existingUser && !existingUser.allowOAuth) {
       throw new Error('OAuth disabled for this account');
     }
-    
+
     // Then complete the OAuth flow manually
     await req.auth.providers.github.handleCallback(req);
-    
+
     res.json({ success: true, user: userData });
   } catch (error) {
     res.status(400).json({ error: error.message });
@@ -306,7 +306,7 @@ Enable MFA in your auth config:
 ```typescript
 const authConfig = {
   db: pool,
-  
+
   twoFactor: {
     enabled: true,
     requireForOAuth: false,    // Skip MFA for OAuth users (optional)
@@ -377,7 +377,7 @@ After receiving `SecondFactorRequiredError`, verify the second factor:
 app.post('/verify-2fa', async (req, res) => {
   try {
     const { code, method } = req.body;
-    
+
     // Verify based on method
     switch (method) {
       case 'totp':
@@ -397,7 +397,7 @@ app.post('/verify-2fa', async (req, res) => {
         await req.auth.twoFactor.verify.otp(code);
         break;
     }
-    
+
     // Complete login
     await req.auth.completeTwoFactorLogin();
     res.json({ success: true });
@@ -417,9 +417,9 @@ Users can enroll in multiple MFA methods:
 app.post('/setup-totp', async (req, res) => {
   try {
     const { secret, qrCode, backupCodes } = await req.auth.twoFactor.setup.totp();
-    
+
     // Show QR code to user for scanning with authenticator app
-    res.json({ 
+    res.json({
       secret,      // Manual entry secret
       qrCode,      // QR code URL for scanning
       backupCodes  // One-time backup codes
@@ -502,7 +502,7 @@ app.get('/mfa-status', async (req, res) => {
 // Disable MFA method
 app.delete('/mfa/:method', async (req, res) => {
   try {
-    const mechanism = req.params.method === 'totp' ? 1 : 
+    const mechanism = req.params.method === 'totp' ? 1 :
                      req.params.method === 'email' ? 2 : 3;
     await req.auth.twoFactor.disable(mechanism);
     res.json({ success: true });
@@ -534,15 +534,15 @@ The auth library maintains its own auth tables (accounts, roles, sessions) that
 app.post('/register', async (req, res) => {
   // Option 1: Let easy-auth auto-generate a UUID (simplest)
   const account = await req.auth.register(req.body.email, req.body.password);
-  
+
   // Option 2: Link to your existing user table
   const user = await db.insert(users).values({
     name: req.body.name,
     email: req.body.email
   }).returning();
-  
+
   const account = await req.auth.register(req.body.email, req.body.password, user.id);
-  
+
   res.json({ success: true, userId: user.id });
 });
 ```
@@ -559,7 +559,7 @@ const authConfig = {
       name: userData.name || userData.username,
       email: userData.email,
     }).returning();
-    
+
     return user.id; // This will be stored as user_id in auth tables
   }
 }
@@ -584,7 +584,7 @@ app.post('/login', async (req, res) => {
 
     throw error;
   }
-  
+
   res.json({ success: true });
 });
 ```
@@ -605,25 +605,26 @@ declare module "express-session" {
 interface AuthConfig {
   // PostgreSQL connection pool
   db: Pool;
-  
+
   // Optional OAuth new user creation function
   createUser?: (userData: OAuthUserData) => string | number | Promise<string | number>; // Called when OAuth user doesn't exist in your system
-  
+
   // Optional settings
   tablePrefix?: string;           // default: 'user_'
+  roles?: Record<string, number>; // custom roles from defineRoles(), default: AuthRole
   minPasswordLength?: number;     // default: 8
   maxPasswordLength?: number;     // default: 64
   rememberDuration?: string;      // default: '30d'
   rememberCookieName?: string;    // default: 'remember_token'
   resyncInterval?: string;        // default: '30s'
-  
+
   // OAuth provider configuration
   providers?: {
     github?: GitHubProviderConfig;
     google?: GoogleProviderConfig;
     azure?: AzureProviderConfig;
   };
-  
+
   // Multi-factor authentication
   twoFactor?: {
     enabled?: boolean;            // default: false
@@ -733,14 +734,14 @@ CREATE TABLE user_accounts (
 - `generateNewBackupCodes(): Promise<string[]>`
 - `getContact(mechanism): Promise<string | null>`
 
-### Admin Manager (`req.authAdmin`)
+### Admin Functions (also on `req.auth`)
 
 #### User Management
 - `createUser(credentials, callback?): Promise<AuthAccount>`
 - `loginAsUserBy(identifier): Promise<void>`
 - `deleteUserBy(identifier): Promise<void>`
 
-#### Role Management  
+#### Role Management
 - `addRoleForUserBy(identifier, role): Promise<void>`
 - `removeRoleForUserBy(identifier, role): Promise<void>`
 - `hasRoleForUserBy(identifier, role): Promise<boolean>`
@@ -753,7 +754,7 @@ CREATE TABLE user_accounts (
 ### Schema Utilities
 
 ```typescript
-import { createAuthTables, dropAuthTables, cleanupExpiredTokens, getAuthTableStats } from '@prsm/easy-auth';
+import { createAuthTables, dropAuthTables, cleanupExpiredTokens, getAuthTableStats } from '@eaccess/auth';
 
 // Setup tables
 await createAuthTables(config);
@@ -769,20 +770,68 @@ console.log(`${stats.accounts} accounts, ${stats.expiredRemembers} expired token
 await dropAuthTables(config);
 ```
 
+## Custom Roles
+
+The default `AuthRole` enum provides 21 predefined roles, but most apps need their own. Use `defineRoles` to create a custom role set:
+
+```typescript
+import { defineRoles } from '@eaccess/auth';
+
+const Roles = defineRoles('owner', 'editor', 'viewer');
+// { owner: 1, editor: 2, viewer: 4 }
+
+const authConfig = {
+  db: pool,
+  roles: Roles, // getRoleNames() will use these names
+};
+
+// usage
+await req.auth.addRoleForUserBy({ email: 'user@example.com' }, Roles.owner | Roles.editor);
+req.auth.getRoleNames(); // ['owner', 'editor']
+await req.auth.hasRole(Roles.editor); // true
+```
+
+Names are preserved exactly as provided - no transformation. Max 31 roles (Postgres INTEGER is 32-bit signed). If you don't set `config.roles`, the default `AuthRole` enum is used.
+
+The admin panel (`@eaccess/admin`) reads `config.roles` from the backend automatically, so custom roles show up in the user management UI without any extra configuration.
+
+## Standalone Auth (no request context)
+
+For server-side operations outside of Express routes (scripts, workers, cron jobs), use `createAuthContext`:
+
+```typescript
+import { createAuthContext } from '@eaccess/auth';
+
+const auth = createAuthContext(authConfig);
+
+await auth.createUser({ email: 'user@example.com', password: 'password123' });
+await auth.addRoleForUserBy({ email: 'user@example.com' }, Roles.editor);
+await auth.resetPassword('user@example.com', '1h', 3, (token) => sendResetEmail(token));
+```
+
+For WebSocket or raw HTTP authentication:
+
+```typescript
+import { authenticateRequest } from '@eaccess/auth';
+
+const result = await authenticateRequest(authConfig, req, sessionMiddleware);
+// result: { account: AuthAccount | null, source: 'session' | 'remember' | null }
+```
+
 ## Constants
 
 ```typescript
-import { AuthStatus, AuthRole } from '@prsm/easy-auth';
+import { AuthStatus, AuthRole } from '@eaccess/auth';
 
 // User statuses
 AuthStatus.Normal        // 0
-AuthStatus.Archived      // 1  
+AuthStatus.Archived      // 1
 AuthStatus.Banned        // 2
 AuthStatus.Locked        // 3
 AuthStatus.PendingReview // 4
 AuthStatus.Suspended     // 5
 
-// User roles (bitmask)
+// Default roles (bitmask) - or use defineRoles() for custom roles
 AuthRole.Admin           // 1
 AuthRole.Author          // 2
 AuthRole.Collaborator    // 4
@@ -792,13 +841,13 @@ AuthRole.Collaborator    // 4
 ## Error Handling
 
 ```typescript
-import { 
-  EmailTakenError, 
-  InvalidPasswordError, 
+import {
+  EmailTakenError,
+  InvalidPasswordError,
   UserNotFoundError,
   SecondFactorRequiredError,
   InvalidTwoFactorCodeError
-} from '@prsm/easy-auth';
+} from '@eaccess/auth';
 
 app.post('/register', async (req, res) => {
   try {
@@ -840,7 +889,7 @@ app.post('/login', async (req, res) => {
 ```typescript
 import { Pool } from 'pg';
 
-const pool = new Pool({ 
+const pool = new Pool({
   connectionString: 'postgresql://user:password@localhost:5432/dbname'
 });
 
@@ -857,17 +906,17 @@ app.get('/admin', async (req, res) => {
   if (!req.auth.isLoggedIn()) {
     return res.status(401).json({ error: 'Not logged in' });
   }
-  
+
   if (!await req.auth.hasRole(AuthRole.Admin)) {
     return res.status(403).json({ error: 'Admin access required' });
   }
-  
+
   // Admin-only content
 });
 
 // Add role to user
-await req.authAdmin.addRoleForUserBy(
-  { email: 'user@example.com' }, 
+await req.auth.addRoleForUserBy(
+  { email: 'user@example.com' },
   AuthRole.Admin | AuthRole.Editor
 );
 ```