me/toknd_auth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

style: rebrand Auth Server to toknd with updated branding and icons

Browse Source
This commit is contained in:
ramvignesh-b
2026-05-11 14:18:56 +05:30
parent 5248ae05db
commit 60ceeaacec
3 changed files with 59 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+46 -95
View File
@@ -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 <your_master_api_key>`
## 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 <your_api_key>`
### 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
src/views/dashboard.html
+6 -6
View File
@@ -4,7 +4,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Auth Server Dashboard</title>
<title>toknd — Auth Broker Dashboard</title>
<link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<link href="https://cdn.jsdelivr.net/npm/daisyui@5/themes.css" rel="stylesheet" type="text/css" />
@@ -27,10 +27,10 @@
<div class="flex items-center gap-2">
<div
class="w-8 h-8 bg-primary rounded-lg flex items-center justify-center text-primary-content font-bold text-lg">
<i class="ph ph-shield-check"></i>
<i class="ph-duotone ph-fingerprint"></i>
</div>
<a class="text-xl font-bold tracking-tight">Auth Server <span
class="text-xs font-normal opacity-50 ml-1">v1.0</span></a>
<a class="text-xl font-bold tracking-tight">toknd <span
class="text-xs font-normal opacity-50 ml-1">auth broker</span></a>
</div>
</div>
<div class="flex-none hidden sm:flex">
@@ -268,8 +268,8 @@
providerRegistry.innerHTML = `
<div class="col-span-full text-center py-20 opacity-30">
<div class="flex flex-col items-center gap-3">
<i class="ph-bold ph-lock-key text-6xl"></i>
<p class="font-medium">Enter Master API Key to access registry</p>
<i class="ph-duotone ph-fingerprint text-6xl"></i>
<p class="font-medium italic">Unlock toknd to access the broker registry</p>
</div>
</div>`;
return;
src/views/success.html
+7 -15
View File
@@ -4,7 +4,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Authentication Successful</title>
<title>toknd — Authentication Successful</title>
<link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<link href="https://cdn.jsdelivr.net/npm/daisyui@5/themes.css" rel="stylesheet" type="text/css" />
@@ -12,15 +12,17 @@
</head>
<body class="bg-base-200/50 min-h-screen flex items-center justify-center p-4 antialiased">
<div class="card bg-base-100 shadow-2xl max-w-md w-full border border-base-300 transform transition-all duration-500 scale-100">
<div
class="card bg-base-100 shadow-2xl max-w-md w-full border border-base-300 transform transition-all duration-500 scale-100">
<div class="card-body items-center text-center p-8 md:p-12">
<div class="w-20 h-20 bg-success/10 text-success rounded-2xl flex items-center justify-center mb-6 shadow-inner animate-bounce-short">
<div
class="w-20 h-20 bg-success/10 text-success rounded-2xl flex items-center justify-center mb-6 shadow-inner animate-pulse">
<i class="ph ph-check-circle text-5xl"></i>
</div>
<h2 class="card-title text-3xl font-black tracking-tight mb-2">Authenticated!</h2>
<p class="text-base-content/60 leading-relaxed">
Successfully connected to <span class="font-bold text-base-content">__PROVIDER_NAME__</span>.
Successfully connected to <span class="font-bold text-base-content">__PROVIDER_NAME__</span>.
You can now close this window or return to the dashboard.
</p>
@@ -34,16 +36,6 @@
</div>
</div>
</div>
<style>
@keyframes bounce-short {
0%, 100% { transform: translateY(0); }
50% { transform: translateY(-10px); }
}
.animate-bounce-short {
animation: bounce-short 2s ease-in-out infinite;
}
</style>
</body>
</html>