@xcelsior/serverless-auth

A reusable serverless authentication package with role-based access control and configurable email notifications.

Features

• User authentication (signup, signin)
• Email verification
• Password reset flow
• Role-based access control (RBAC)
• Configurable email providers (SMTP, AWS SES)
• Multiple storage providers (DynamoDB, with MongoDB and PostgreSQL coming soon)
• JWT-based authentication
• Middleware for protecting routes

Installation

npm install @xcelsior/serverless-auth
# or
yarn add @xcelsior/serverless-auth
# or
pnpm add @xcelsior/serverless-auth

Usage

Configuration

import { AuthService, AuthConfig } from '@xcelsior/serverless-auth';

const config: AuthConfig = {
  jwt: {
    secret: 'your-jwt-secret',
    expiresIn: '1d',
  },
  // Storage configuration
  storage: {
    // DynamoDB configuration
    type: 'dynamodb',
    options: {
      tableName: 'your-users-table',
      region: 'us-east-1',
    },
    // Or MongoDB configuration (coming soon)
    // type: 'mongodb',
    // options: {
    //   uri: 'mongodb://localhost:27017',
    //   dbName: 'auth',
    //   collectionName: 'users',
    // },
    // Or PostgreSQL configuration (coming soon)
    // type: 'postgres',
    // options: {
    //   connectionString: 'postgresql://user:pass@localhost:5432/db',
    //   schema: 'public',
    //   tableName: 'users',
    // },
  },
  // Email configuration
  email: {
    // SMTP configuration
    type: 'smtp',
    from: '[email protected]',
    options: {
      host: 'smtp.provider.com',
      port: 587,
      secure: false,
      auth: {
        user: 'your-smtp-username',
        pass: 'your-smtp-password',
      },
    },
    // Or AWS SES configuration
    // type: 'ses',
    // from: '[email protected]',
    // options: {
    //   region: 'us-east-1',
    //   credentials: {
    //     accessKeyId: 'your-access-key',
    //     secretAccessKey: 'your-secret-key',
    //   },
    //   sourceArn: 'arn:aws:ses:region:account-id:identity/yourdomain.com', // Optional: ARN of the verified identity
    // },
    // Optional: Custom email templates (defaults will be used if not provided)
    templates: {
      verification: {
        subject: 'Verify your email',
        html: (token) => `
          <h1>Verify your email</h1>
          <p>Click the link below to verify your email:</p>
          <a href="https://yourdomain.com/verify-email?token=${token}">Verify Email</a>
        `,
      },
      resetPassword: {
        subject: 'Reset your password',
        html: (token) => `
          <h1>Reset your password</h1>
          <p>Click the link below to reset your password:</p>
          <a href="https://yourdomain.com/reset-password?token=${token}">Reset Password</a>
        `,
      },
    },
  },
};

const authService = new AuthService(config);

Authentication

// Signup
const { user, token } = await authService.signup('[email protected]', 'password');

// Signin
const { user, token } = await authService.signin('[email protected]', 'password');

// Verify email
await authService.verifyEmail(verificationToken);

// Reset password flow
await authService.initiatePasswordReset('[email protected]');
await authService.resetPassword(resetToken, 'newPassword');

Middleware Usage

import express from 'express';
import { AuthMiddleware } from '@xcelsior/serverless-auth';

const app = express();
const authMiddleware = new AuthMiddleware(authService);

// Protect routes
app.use(authMiddleware.verifyToken());

// Require specific roles
app.get('/admin', 
  authMiddleware.requireRoles(['ADMIN']),
  (req, res) => {
    res.json({ message: 'Admin access granted' });
  }
);

// Require verified email
app.post('/sensitive-action',
  authMiddleware.requireEmailVerified(),
  (req, res) => {
    res.json({ message: 'Action performed' });
  }
);

Storage Providers

DynamoDB

Create a DynamoDB table with the following structure:

• Table Name: (your choice)
• Partition Key: id (string)
• GSI (EmailIndex):
  • Partition Key: email (string)

MongoDB (Coming Soon)

The MongoDB provider will support:

• Custom database and collection names
• Automatic indexing setup
• Flexible schema support

PostgreSQL (Coming Soon)

The PostgreSQL provider will support:

• Custom schema and table names
• Automatic table creation
• Migration support

Email Providers

Both email providers come with built-in default templates for:

• Email verification
• Password reset

The default templates are responsive, mobile-friendly, and follow email best practices. You can override these templates by providing your own in the configuration.

SMTP

The SMTP provider supports any SMTP server, including:

• Gmail
• SendGrid
• Mailgun
• Custom SMTP servers

AWS SES

The AWS SES provider supports:

• Direct email sending through AWS SES
• Region configuration
• AWS credentials management
• Production access management
• Source ARN configuration for verified identities

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT