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
Web Framework: Hono
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:

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):
```
podman compose up --build
```
Production:
```
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.

Install Dependencies:
```
bun install
```
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 (or /docs)
OpenAPI Spec (JSON): 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.