Skip to content

README.md

Latest commit

 

History

History
337 lines (242 loc) · 9.25 KB

README.md

File metadata and controls

337 lines (242 loc) · 9.25 KB

EdgeAuth · Edge-Native Authentication Service

🌍 Authentication at the Speed of Light - Globally distributed, zero-latency auth built on Cloudflare's edge

Core Capabilities: JWT Authentication | OAuth 2.0 Provider | SSO Sessions | Admin Management

Serverless authentication service that runs on Cloudflare Workers - simple, secure, and globally fast

Stars Views License

TypeScript Cloudflare Workers D1 Database Hono

Architecture | Schema | API

🚀 Why EdgeAuth?

⚡ Edge-First Architecture

Built on Cloudflare Workers, your authentication runs in 300+ cities worldwide. Users get sub-10ms response times, no matter where they are.

🎯 Simple by Design

No complex setup. No infrastructure management. Just deploy and use.

// That's it. Authentication in 3 lines.
const token = await auth.login(email, password);
const user = await auth.verify(token);
const session = await sso.createSession(user);

🏗️ Clean Architecture

Built with Domain-Driven Design and clean architecture principles:

  • Domain Layer: Pure business logic
  • Core Layer: Technical implementation (crypto, JWT, persistence)
  • Services Layer: Edge-native workers

🔐 Security First

  • PBKDF2 password hashing with Web Crypto API
  • HS256 JWT tokens
  • Secure session management
  • Built-in rate limiting (coming soon)

⚡ Quick Start

📦 Installation

# Clone the repository
git clone https://github.com/Deepractice/EdgeAuth.git
cd EdgeAuth

# Install dependencies
pnpm install

🚀 Production Deployment

Automated deployment via GitHub Actions:

  1. Create a release/v0.x.x branch
  2. Merge to main
  3. Deployment happens automatically!

Required GitHub Secrets:

CLOUDFLARE_API_TOKEN  # Cloudflare API token with D1 and Workers permissions
GH_PAT                # GitHub Personal Access Token with repo and workflow permissions
JWT_SECRET            # Secret key for JWT signing (generate with: openssl rand -base64 32)
PLUNK_API_KEY         # Plunk email service API key

All secrets are automatically configured to Workers during deployment - no manual Cloudflare secret management needed!

💻 Local Development

One-command setup:

# Set up local environment (creates local DBs, runs migrations)
pnpm setup:local

# Start a worker
cd services/account-api && wrangler dev

📖 Full Deployment Guide →

🎨 Features

✅ Current (v0.1)

  • ✨ Email/Username + Password Authentication
  • 🔑 JWT Token Generation & Validation
  • 🔐 Secure Password Hashing (PBKDF2)
  • 🌍 Edge-Native Performance
  • 📦 Cloudflare D1 Persistence
  • 🎯 Clean REST API
  • 📚 Full TypeScript Support

🚧 In Progress

  • 🔄 SSO Session Management
  • 👨‍💼 Admin Management API
  • 🔌 OAuth 2.0 Provider (complete)

📋 Planned

  • 📧 Email Verification
  • 🔄 Password Reset Flow
  • 🎨 Admin Dashboard (UI)
  • 📦 SDK Libraries (JS/TS, Python, Go)
  • ⚡ Refresh Token Support
  • 🚦 Rate Limiting
  • 🔗 OAuth Providers (GitHub, Google, etc.)

📐 Architecture

EdgeAuth uses a single database architecture with Cloudflare's native migration system:

┌─────────────────────────────────────────────────────┐
│              edgeauth-db (Single Database)          │
│  • users table                                      │
│  • sso_sessions table                               │
│  • oauth_clients, tokens tables                     │
└─────────────────────┬───────────────────────────────┘
                      │
        ┌─────────────┼─────────────────┐
        ▼             ▼                 ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Admin Worker │ │  SSO Worker  │ │ OAuth Worker │
│ • User CRUD  │ │  • Auth flow │ │  • OAuth 2.0 │
│ • Binds: DB  │ │  • Binds: DB │ │  • Binds: DB │
└──────────────┘ └──────────────┘ └──────────────┘

🗄️ Single Database

  • edgeauth-db - All tables in one database
    • users - User accounts
    • sso_sessions - SSO sessions
    • oauth_clients, authorization_codes, access_tokens, refresh_tokens - OAuth

✨ Key Benefits

  • ✅ Cloudflare native migrations (automatic tracking)
  • ✅ Idempotent deployments
  • ✅ Simplified management
  • ✅ No cross-database complexity

📖 Read Full Architecture Docs →

🛠️ API Examples

Register New User

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "username",
  "password": "securepassword"
}

Login

POST /auth/login
Content-Type: application/json

{
  "account": "user@example.com",  // email or username
  "password": "securepassword"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "username": "username"
  }
}

Get Current User

GET /auth/me
Authorization: Bearer <token>

🧪 Development

Run Tests

# Run all tests
pnpm test

# Watch mode
pnpm test:dev

# Coverage
pnpm test:ci

Type Checking

pnpm typecheck

Format Code

# Format all files
pnpm format

# Check formatting
pnpm format:check

📚 Technology Stack

Category Technology
Runtime Cloudflare Workers
Database Cloudflare D1 (SQLite)
Framework Hono
Language TypeScript 5.9+
Build tsup, Turbo
Test Vitest + BDD (Cucumber)
Security Web Crypto API (PBKDF2), JWT (HS256)
Monorepo pnpm workspaces

🎓 Project Structure

EdgeAuth/
├── migrations/            # Database migrations (Cloudflare native)
├── src/
│   ├── core/              # Technical core (crypto, JWT, persistence)
│   └── domain/            # Business logic (User, OAuth, SSO)
├── services/
│   ├── admin-api/         # Admin API
│   ├── account-api/       # User registration & login
│   ├── oauth-api/         # OAuth 2.0 Provider
│   └── sso-api/           # SSO authentication
├── .github/workflows/     # CI/CD pipelines
├── docs/                  # Documentation
└── scripts/               # Development scripts

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Process

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

🏢 About

Proudly brought to you by Deepractice

Making AI your professional partner

🌐 Official Site | 🔧 GitHub | 📚 Documentation | 💬 Forum | 🎮 Discord

Connect with Founder

Sean's WeChat

Scan to connect with Sean (Founder & CEO) on WeChat

📞 Support