EdgeAuth v1 Technical Design Specification

[deepracticexs]

EdgeAuth v1 Technical Design Specification

Overview

EdgeAuth is an open-source authentication service built on Cloudflare's edge infrastructure. It provides email/username + password authentication with JWT tokens, designed to be simple, serverless, and globally distributed.

Core Philosophy

• Edge-first: Built on Cloudflare Workers for global low-latency
• Serverless: Zero infrastructure management
• Simple: Focus on core authentication features
• Open Source: Easy to deploy and customize

v1 Scope

✅ What we're building

1. Email/Username + Password authentication
2. JWT token generation and validation
3. REST API (no SDK yet)
4. Manual deployment via Wrangler

❌ What we're NOT building (v1)

1. OAuth providers (GitHub, Google, etc.)
2. Email verification / Password reset
3. Admin dashboard or management tools
4. SDK libraries
5. Refresh tokens

Technology Stack

• Runtime: Cloudflare Workers
• Database: D1 (SQLite)
• Password Hashing: Web Crypto API (PBKDF2)
• JWT Algorithm: HS256
• Project Structure: NodeSpec

Database Schema

CREATE TABLE users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  username TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

API Endpoints

Register

POST /auth/register

Request:
{
  "email": "string",
  "username": "string", 
  "password": "string"
}

Response:
{
  "token": "string",
  "user": {
    "id": "string",
    "email": "string",
    "username": "string",
    "created_at": number
  }
}

Login

POST /auth/login

Request:
{
  "account": "string",  // email or username
  "password": "string"
}

Response:
{
  "token": "string",
  "user": {
    "id": "string",
    "email": "string",
    "username": "string",
    "created_at": number
  }
}

Login Logic: The account field accepts either email or username. Backend determines type by checking if it contains @.

Get Current User

GET /auth/me

Headers:
{
  "Authorization": "Bearer <token>"
}

Response:
{
  "user": {
    "id": "string",
    "email": "string",
    "username": "string",
    "created_at": number
  }
}

Logout (Optional)

POST /auth/logout

Headers:
{
  "Authorization": "Bearer <token>"
}

Response:
{
  "success": true
}

JWT Configuration

Payload Structure:

{
  "sub": "user_id",
  "email": "user@example.com",
  "username": "username",
  "iat": 1234567890,
  "exp": 1234567890
}

Settings:

• Expiration: 30 days
• Algorithm: HS256
• No refresh token (re-login after expiration)

Error Handling

Unified Error Format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Error Codes:

• INVALID_CREDENTIALS - Login failed
• EMAIL_EXISTS - Email already registered
• USERNAME_EXISTS - Username already taken
• INVALID_TOKEN - Token invalid or expired
• VALIDATION_ERROR - Request validation failed

Deployment Flow

v1 Manual Deployment (simplified):

git clone https://github.com/Deepractice/EdgeAuth.git
cd EdgeAuth
pnpm install
cp .env.example .env  # Configure OAuth credentials, JWT secret
pnpm db:init          # Initialize D1 database
wrangler deploy

Configuration includes:

• JWT Secret
• Allowed callback domains
• D1 database binding

Security Considerations

1. Password Storage: Use Web Crypto API PBKDF2 with sufficient iterations
2. JWT Secret: Must be strong and kept secure
3. HTTPS Only: All endpoints must use HTTPS
4. CORS: Configurable allowed origins

Future Enhancements (Post v1)

• OAuth providers (GitHub, Google, etc.)
• Email verification
• Password reset flow
• Admin dashboard
• JavaScript/TypeScript SDK
• CLI deployment tool
• Refresh token support
• Rate limiting