diff --git a/README.md b/README.md index cb96608..470b553 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,66 @@ -# Auth Server +# toknd — Auth Broker -## Project Overview - -The Auth Server is a centralized authentication and token management service built with Bun, Hono, and Redis. It provides a generic interface for managing OAuth2 providers, handling token exchange, storage, and automatic refresh. This service is designed to be easily extensible and can be deployed using Docker for consistent environments. +**toknd** is a minimal, centralized authentication and token broker. Built with **Bun**, **Hono**, and **Redis**, it serves as a middleware layer that manages OAuth2 providers, token persistence, and automatic refreshes, allowing your applications to focus on their core logic. ## Features -- Generic OAuth2 provider implementation. -- Automatic token refresh management. -- Centralized configuration storage in Redis. -- Secure API access via API key authentication. +- Centralized management for multiple OAuth2 providers (Google, Trakt, GitHub, etc.). +- Automatic token refreshes. +- Secure and isolated API access via API key authentication. - Web-based dashboard for configuration management. -- Docker and Docker Compose support for simplified deployment. -- High performance powered by Bun and Redis. +- Docker Compose support for simplified deployment. +- High performance and low-latency powered by Bun and Redis. -## Setup Instructions +## Tech Stack -### Docker Deployment (Recommended) +- **Runtime**: [Bun](https://bun.sh/) +- **Web Framework**: [Hono](https://hono.dev/) +- **Data Store**: Redis +- **Styling**: Tailwind CSS & DaisyUI +- **Schema & Validation**: Zod -To deploy the Auth Server using Docker in production: +## Quick Start -1. Ensure you have Docker and Docker Compose installed on your system. -2. Clone the repository and navigate to the project directory. -3. Create a `.env` file based on `.env.example` and provide your `API_KEY`. -4. Run the following command to start the services: - ```bash - docker-compose up -d --build - ``` -5. The application will be available at `http://localhost:3000` (or the port specified in your `.env`). +### 1. Environment Setup +Clone the repository and create your environment file: +```bash +cp .env.example .env +``` +Ensure you define a strong `API_KEY` in your `.env`. -The Docker setup uses a multi-stage build for a slim production image and persistent Redis storage. +### 2. Local Development (with Auto-Watch) +We use a Docker Compose override system to enable hot-reloading locally: +```bash +podman compose up --build +``` +*Note: This mounts your ./src directory into the container and uses bun --hot to restart on any code changes.* -### Local Development Setup +### 3. Production Deployment +For production, only the core docker-compose.yml is used: +```bash +docker compose up -d --build +``` -To run the project locally without Docker: +## API Reference -1. Install [Bun](https://bun.sh/) on your machine. -2. Ensure you have a Redis instance running and accessible. -3. Install dependencies: - ```bash - bun install - ``` -4. Set up your environment variables in a `.env` file: - ```env - REDIS_URL=redis://localhost:6379 - API_KEY=your_secret_api_key - ``` -5. Start the development server: - ```bash - bun run dev - ``` +All protected endpoints require an Authorization header: +`Authorization: Bearer ` -## API Documentation +### Token Brokerage +- **Get Valid Token**: `GET /api/token/:provider` + - Returns a valid access token. Automatically triggers a refresh if the current one is expired. +- **Registry Status**: `GET /api/status` + - Returns the connectivity and refresh status of all configured providers. -All API requests except for the initial OAuth login and callback require an `Authorization` header: -`Authorization: Bearer ` - -### Configuration API - -#### Get All Providers -- **Endpoint**: `GET /api/config/` -- **Description**: Retrieves a list of all configured OAuth2 providers. - -#### Set Provider Configuration -- **Endpoint**: `POST /api/config/:provider` -- **Description**: Configures or updates an OAuth2 provider. -- **Payload**: - ```json - { - "clientId": "your_client_id", - "clientSecret": "your_client_secret", - "authUrl": "https://provider.com/oauth/authorize", - "tokenUrl": "https://provider.com/oauth/token", - "redirectUri": "http://localhost:3000/auth/:provider/callback", - "scope": "scope1 scope2" - } - ``` - -### Authentication API - -#### Initiate Login -- **Endpoint**: `GET /auth/:provider/login` -- **Description**: Redirects the user to the provider's authorization page. - -#### OAuth Callback -- **Endpoint**: `GET /auth/:provider/callback` -- **Description**: Handles the authorization code exchange and saves the tokens. - -### Token Management API - -#### Get Access Token -- **Endpoint**: `GET /api/token/:provider` -- **Description**: Retrieves a valid access token for the specified provider. If the token is expired, it will be automatically refreshed using the refresh token. +### Authentication Flow +1. **Initiate**: `GET /auth/:provider/login` +2. **Callback**: `GET /auth/callback` (Handled internally by toknd) ## Dashboard +Access the toknd dashboard at: +`http://localhost:3000/app` -The service includes a basic dashboard for managing configurations: -- **URL**: `http://localhost:3000/app/` +Authenticate the registry using your Master API Key to manage your providers and view live token status. -## Extensibility Guide +--- -To add support for a specific provider that requires custom logic beyond the generic implementation: - -1. Create a new class in `src/providers/` that implements the `IOAuthProvider` interface. -2. Update the routing logic in `src/routes/` to utilize your specialized provider based on the provider name. - -The generic provider implementation handles most standard OAuth2 flows out of the box. - -## Development Standards - -- **Runtime**: Bun 1.1+ -- **Linter/Formatter**: Biome -- **Language**: TypeScript -- **Database**: Redis diff --git a/src/views/dashboard.html b/src/views/dashboard.html index d121417..0dcb701 100644 --- a/src/views/dashboard.html +++ b/src/views/dashboard.html @@ -4,7 +4,7 @@ - Auth Server Dashboard + toknd — Auth Broker Dashboard @@ -27,10 +27,10 @@
- +
- Auth Server v1.0 + toknd auth broker