@bastards/bcs-auth-env 🔐

A simple and secure environment-based authentication layer for BCS that uses environment variables to manage users and authentication settings.

Features 🌟

• Environment-Based User Management 👥

  • Define users directly in environment variables
  • Support for multiple users with different roles
  • Base64 encoded password storage
  • No database required

• JWT Authentication 🎫

  • Secure token-based authentication
  • Configurable JWT secret
  • Role-based access control
  • Simple integration with BCS admin UI

• Security First 🛡️

  • Environment-based configuration
  • Secure password handling
  • JWT token validation
  • Role-based permissions

• Developer Experience 💻

  • Zero database setup
  • Easy deployment
  • TypeScript support
  • Framework agnostic

Installation 📦

npm install @bastards/bcs-auth-env
# or
pnpm add @bastards/bcs-auth-env
# or
yarn add @bastards/bcs-auth-env

Usage 🚀

1. Set up your environment variables:

# Required: JWT secret for token signing
BCS_AUTH_JWT_SECRET=your-secret-key

# Required: User definitions in format "username:base64_password:role"
BCS_AUTH_USERS="admin:YWRtaW4xMjM=:admin;user:dXNlcjEyMw==:user"

2. Configure the authentication endpoints in your bcs.config.ts:

import { defineConfig } from '@bastards/bcs';

export default defineConfig({
  admin: {
    // ... other admin config
    data: {
      auth: '/api/bcs/auth'  // Your auth endpoint
    }
  }
});

3. Set up the authentication API endpoint in your application (example in SvelteKit):

// src/routes/api/bcs/auth/+server.ts
import { envAuth } from '@bastards/bcs-auth-env';

export const POST = async ({ request }) => {
  const auth = envAuth();
  // The auth handler will automatically handle login/logout requests
  return auth.handleRequest(request);
};

Environment Variables 🔧

| Variable | Description | Format | Required | |----------|-------------|---------|----------| | BCS_AUTH_JWT_SECRET | Secret key for JWT signing | String | Yes | | BCS_AUTH_USERS | User definitions | username:base64_password:role[;username:base64_password:role]* | Yes |

User Management 👥

Users are defined in the BCS_AUTH_USERS environment variable using the following format:

username:base64_password:role[;username:base64_password:role]*

Example:

BCS_AUTH_USERS="admin:YWRtaW4xMjM=:admin;user:dXNlcjEyMw==:user"

To generate a base64 password:

echo -n "your-password" | base64

API Reference 📚

The package exports the following:

function envAuth(options?: {
  jwtSecret?: string;    // Override JWT_SECRET from env
  users?: string;        // Override USERS from env
}): AuthHandler;

interface AuthHandler {
  handleRequest(request: Request): Promise<Response>;
  verifyToken(token: string): Promise<User>;
}

Security Best Practices 🔒

1. Use a strong, unique JWT secret
2. Store environment variables securely
3. Use strong passwords for users
4. Keep base64 encoded passwords private
5. Use HTTPS in production

Contributing 🤝

We welcome contributions! Please see our Contributing Guide for details.

License 📄

MIT - see the main project repository for details.

Learn More 📚

For more information about BCS and its features, check out:

• BCS Documentation (Coming soon, still working on it!)
• Main Project README
• Software Bastards