ramvignesh-b
83 lines
2.8 KiB
Markdown
83 lines
2.8 KiB
Markdown
# toknd — Auth Broker
|
|
|
|
|
|
**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
|
|
|
|
- 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 Compose support for simplified deployment.
|
|
- High performance and low-latency powered by Bun and Redis.
|
|
|
|
## Tech Stack
|
|
|
|
- **Runtime**: [Bun](https://bun.sh/)
|
|
- **Web Framework**: [Hono](https://hono.dev/)
|
|
- **Data Store**: Redis
|
|
- **Styling**: Tailwind CSS & DaisyUI
|
|
- **Schema & Validation**: Zod
|
|
|
|
## Getting Started
|
|
|
|
toknd can be deployed either as a containerized service or self-hosted directly on your hardware.
|
|
|
|
### 1. Environment Setup
|
|
Clone the repository and create your environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
Define a strong `API_KEY` and ensure `REDIS_URL` points to a valid Redis instance.
|
|
|
|
### 2. Choose Deployment Method
|
|
|
|
#### Option A: Containerized (Recommended)
|
|
This is the easiest way to get up and running, as it bundles the application and a Redis instance together.
|
|
|
|
- **Development (with Hot-Reload)**:
|
|
```bash
|
|
podman compose up --build
|
|
```
|
|
- **Production**:
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
#### Option B: Self-Hosting (Bare Metal)
|
|
Ideal for lightweight deployments or custom environments where you already have Bun and Redis.
|
|
|
|
1. **Install Dependencies**:
|
|
```bash
|
|
bun install
|
|
```
|
|
2. **Start the Server**:
|
|
- **Development**: `bun run dev` (with hot-reload)
|
|
- **Production**: `bun run start`
|
|
*Note: Ensure your Redis server is running and accessible via the `REDIS_URL` in your `.env`.*
|
|
|
|
---
|
|
|
|
## API Reference
|
|
|
|
toknd provides a built-in **Scalar API Reference** that allows you to explore and test all endpoints directly from your browser.
|
|
|
|
- **Interactive UI**: [http://localhost:3000/api](http://localhost:3000/api) (or `/docs`)
|
|
- **OpenAPI Spec (JSON)**: [http://localhost:3000/doc](http://localhost:3000/doc)
|
|
|
|
All protected endpoints require a Bearer token in the `Authorization` header:
|
|
`Authorization: Bearer <your_master_api_key>`
|
|
|
|
### Core Concepts
|
|
- **Token Brokerage**: Automated access token retrieval and background refreshes for all configured providers.
|
|
- **Provider Management**: Register and manage OAuth2 providers via the Dashboard or the configuration API.
|
|
|
|
## Dashboard
|
|
Access the **toknd** dashboard at:
|
|
`http://localhost:3000/app`
|
|
|
|
The dashboard allows you to manage provider configurations, view live token statuses, and manually trigger refreshes. Authenticate using your **Master API Key**.
|
|
|
|
---
|