Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/profullstack/auth-system


https://github.com/profullstack/auth-system

Last synced: 4 months ago
JSON representation

Awesome Lists containing this project

README 

          
# @profullstack/auth-system



A flexible authentication system with user registration, login/logout, password reset, and session management.



## Features



- **User Management**: Registration, login, profile management

- **Authentication**: JWT-based authentication with access and refresh tokens

- **Password Management**: Secure password hashing, validation, reset

- **Email Verification**: Email verification for new accounts

- **Adapters**: Pluggable storage adapters (memory, Supabase, MySQL, PostgreSQL, MongoDB, PocketBase, etc.)

- **Middleware**: Express/Connect/Hono middleware for protected routes

- **Validation**: Input validation for emails, passwords, etc.

- **Customization**: Configurable password requirements, token expiry, etc.



## Installation



```bash

npm install @profullstack/auth-system

```



## Basic Usage



```javascript

import { createAuthSystem } from '@profullstack/auth-system';



// Create an auth system with default options

const authSystem = createAuthSystem({

  tokenOptions: {

    secret: 'your-secret-key-here',

    accessTokenExpiry: 3600, // 1 hour

    refreshTokenExpiry: 604800 // 7 days

  }

});



// Register a new user

const registrationResult = await authSystem.register({

  email: 'user@example.com',

  password: 'Password123',

  profile: {

    firstName: 'John',

    lastName: 'Doe'

  }

});



// Login

const loginResult = await authSystem.login({

  email: 'user@example.com',

  password: 'Password123'

});



// Use the tokens for authentication

const { accessToken, refreshToken } = loginResult.tokens;

```



## API Reference



### Creating an Auth System



```javascript

import { createAuthSystem, MemoryAdapter } from '@profullstack/auth-system';



const authSystem = createAuthSystem({

  // Storage adapter (optional, defaults to in-memory)

  adapter: new MemoryAdapter(),

  

  // Token configuration (optional)

  tokenOptions: {

    accessTokenExpiry: 3600, // 1 hour

    refreshTokenExpiry: 604800, // 7 days

    secret: 'your-secret-key-here'

  },

  

  // Password configuration (optional)

  passwordOptions: {

    minLength: 8,

    requireUppercase: true,

    requireLowercase: true,

    requireNumbers: true,

    requireSpecialChars: false

  },

  

  // Email configuration (optional)

  emailOptions: {

    sendEmail: async (emailData) => {

      // Your email sending implementation

    },

    fromEmail: 'noreply@example.com',

    resetPasswordTemplate: {

      subject: 'Reset Your Password',

      text: 'Click the link to reset your password: {resetLink}',

      html: '
Click the link to reset your password: {resetLink}
'

    },

    verificationTemplate: {

      subject: 'Verify Your Email',

      text: 'Click the link to verify your email: {verificationLink}',

      html: '
Click the link to verify your email: {verificationLink}
'

    }

  }

});

```



### User Registration



```javascript

const registrationResult = await authSystem.register({

  email: 'user@example.com',

  password: 'Password123',

  profile: {

    firstName: 'John',

    lastName: 'Doe'

  },

  autoVerify: false // Set to true to skip email verification

});

```



### User Login



```javascript

const loginResult = await authSystem.login({

  email: 'user@example.com',

  password: 'Password123'

});



// The login result contains user data and tokens

const { user, tokens } = loginResult;

```



### Token Refresh



```javascript

const refreshResult = await authSystem.refreshToken(refreshToken);



// The refresh result contains new tokens

const { accessToken, refreshToken } = refreshResult.tokens;

```



### Password Reset



```javascript

// Request password reset

const resetResult = await authSystem.resetPassword('user@example.com');



// Confirm password reset (in a real app, the token would come from the email link)

const confirmResult = await authSystem.resetPasswordConfirm({

  token: 'reset-token-from-email',

  password: 'NewPassword123'

});

```



### Email Verification



```javascript

// Verify email (in a real app, the token would come from the email link)

const verificationResult = await authSystem.verifyEmail('verification-token-from-email');

```



### User Profile Management



```javascript

// Get user profile

const profileResult = await authSystem.getProfile(userId);



// Update user profile

const updateResult = await authSystem.updateProfile({

  userId,

  profile: {

    firstName: 'John',

    lastName: 'Doe',

    phoneNumber: '555-123-4567'

  }

});



// Change password

const changePasswordResult = await authSystem.changePassword({

  userId,

  currentPassword: 'Password123',

  newPassword: 'NewPassword123'

});

```



### Token Validation



```javascript

// Validate an access token

const user = await authSystem.validateToken(accessToken);



if (user) {

  // Token is valid, user contains user data

  console.log(`Valid token for user: ${user.email}`);

} else {

  // Token is invalid or expired

  console.log('Invalid token');

}

```



### Logout



```javascript

// Logout (invalidates the refresh token)

const logoutResult = await authSystem.logout(refreshToken);

```



### Middleware



```javascript

import express from 'express';

import { createAuthSystem } from '@profullstack/auth-system';



const app = express();

const authSystem = createAuthSystem();



// Protect routes with authentication middleware

app.use('/api/protected', authSystem.middleware());



app.get('/api/protected/profile', (req, res) => {

  // req.user contains the authenticated user data

  res.json({ user: req.user });

});



app.listen(3000);

```



## Storage Adapters



### Memory Adapter (Default)



Stores user data in memory. Suitable for development or testing.



```javascript

import { createAuthSystem, MemoryAdapter } from '@profullstack/auth-system';



const authSystem = createAuthSystem({

  adapter: new MemoryAdapter()

});

```



### JWT Adapter



Uses JSON Web Tokens (JWT) for authentication. Requires a database adapter for user storage.



```javascript

import { createAuthSystem, MemoryAdapter, JwtAdapter } from '@profullstack/auth-system';



const dbAdapter = new MemoryAdapter();

const jwtAdapter = new JwtAdapter({

  dbAdapter,

  secret: 'your-secret-key-here'

});



const authSystem = createAuthSystem({

  adapter: jwtAdapter

});

```



### Supabase Adapter



Uses Supabase for user storage and authentication. Requires the `@supabase/supabase-js` package.



```javascript

import { createAuthSystem, SupabaseAdapter } from '@profullstack/auth-system';



const supabaseAdapter = new SupabaseAdapter({

  supabaseUrl: 'https://your-project-id.supabase.co',

  supabaseKey: 'your-supabase-api-key',

  tableName: 'users', // Optional: defaults to 'users'

  tokensTableName: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'

});



const authSystem = createAuthSystem({

  adapter: supabaseAdapter,

  tokenOptions: {

    secret: 'your-jwt-secret-key'

  }

});

```



> **Note:** Before using the Supabase adapter, you need to set up the required tables in your Supabase database. You can use the [supabase-schema.sql](./examples/supabase-schema.sql) file to create the necessary tables and indexes.



### MySQL Adapter



Uses MySQL for user storage and authentication. Requires the `mysql2` package.



```javascript

import { createAuthSystem, MySQLAdapter } from '@profullstack/auth-system';



const mysqlAdapter = new MySQLAdapter({

  host: 'localhost',

  port: 3306,

  database: 'auth_system',

  user: 'root',

  password: 'password',

  usersTable: 'users', // Optional: defaults to 'users'

  tokensTable: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'

});



const authSystem = createAuthSystem({

  adapter: mysqlAdapter,

  tokenOptions: {

    secret: 'your-jwt-secret-key'

  }

});

```



> **Note:** This is a stub implementation. You'll need to complete the implementation before using it in production.



### PostgreSQL Adapter



Uses PostgreSQL for user storage and authentication. Requires the `pg` package.



```javascript

import { createAuthSystem, PostgresAdapter } from '@profullstack/auth-system';



const postgresAdapter = new PostgresAdapter({

  host: 'localhost',

  port: 5432,

  database: 'auth_system',

  user: 'postgres',

  password: 'password',

  usersTable: 'users', // Optional: defaults to 'users'

  tokensTable: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'

});



const authSystem = createAuthSystem({

  adapter: postgresAdapter,

  tokenOptions: {

    secret: 'your-jwt-secret-key'

  }

});

```



> **Note:** This is a stub implementation. You'll need to complete the implementation before using it in production.



### MongoDB Adapter



Uses MongoDB for user storage and authentication. Requires the `mongodb` package.



```javascript

import { createAuthSystem, MongoDBAdapter } from '@profullstack/auth-system';



const mongodbAdapter = new MongoDBAdapter({

  uri: 'mongodb://localhost:27017',

  dbName: 'auth_system',

  usersCollection: 'users', // Optional: defaults to 'users'

  tokensCollection: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'

});



const authSystem = createAuthSystem({

  adapter: mongodbAdapter,

  tokenOptions: {

    secret: 'your-jwt-secret-key'

  }

});

```



> **Note:** This is a stub implementation. You'll need to complete the implementation before using it in production.



### PocketBase Adapter



Uses PocketBase for user storage and authentication. Requires the `pocketbase` package.



```javascript

import { createAuthSystem, PocketBaseAdapter } from '@profullstack/auth-system';



const pocketbaseAdapter = new PocketBaseAdapter({

  url: 'http://127.0.0.1:8090',

  usersCollection: 'auth_users', // Optional: defaults to 'auth_users'

  tokensCollection: 'auth_invalidated_tokens', // Optional: defaults to 'auth_invalidated_tokens'

  adminEmail: 'admin@example.com', // Optional: for admin authentication

  adminPassword: 'password' // Optional: for admin authentication

});



const authSystem = createAuthSystem({

  adapter: pocketbaseAdapter,

  tokenOptions: {

    secret: 'your-jwt-secret-key'

  }

});

```



### Creating Custom Adapters



You can create custom adapters by implementing the adapter interface:



```javascript

class CustomAdapter {

  async createUser(userData) { /* ... */ }

  async getUserById(userId) { /* ... */ }

  async getUserByEmail(email) { /* ... */ }

  async updateUser(userId, updates) { /* ... */ }

  async deleteUser(userId) { /* ... */ }

  async invalidateToken(token) { /* ... */ }

  async isTokenInvalidated(token) { /* ... */ }

}

```



> **Note:** Before using the PocketBase adapter, you need to set up the required collections in your PocketBase database. You can use the [pocketbase-schema.json](./examples/pocketbase-schema.json) file to create the necessary collections and indexes.



## Examples



See the [examples](./examples) directory for complete usage examples:



- [Basic Usage](./examples/basic-usage.js): Simple example of using the auth system

- [Supabase Usage](./examples/supabase-usage.js): Example of using the auth system with Supabase

- [Supabase Schema](./examples/supabase-schema.sql): SQL schema for setting up Supabase tables

- [PocketBase Usage](./examples/pocketbase-usage.js): Example of using the auth system with PocketBase

- [PocketBase Schema](./examples/pocketbase-schema.json): JSON schema for setting up PocketBase collections

- [Browser Integration](./examples/browser-integration/): Complete example of integrating the auth system into a browser-based web application



### Browser Integration



The browser integration example provides a complete authentication system for web applications, including:



- User registration with payment integration (Stripe, crypto)

- Login/logout functionality

- Password reset and change

- Profile management

- API key management

- Authentication status utilities



It includes a browser-friendly wrapper around the auth-system module with localStorage support and event handling. See the [Browser Integration README](./examples/browser-integration/README.md) for more details.



## License



MIT