Hero Auth

Minimal OAuth2 authorization server for the Hero ecosystem. Runs locally on each machine and provides centralized authentication for all local services.

Built with Axum, featuring user management, JWT token issuance, encrypted config storage, and three integration methods: REST API, JSON-RPC 2.0, and MCP (Model Context Protocol).

Quick Start

# Run (HERO_SECRET is required)
HERO_SECRET=your_secret_here cargo run -- --port 3350

# Or via Make
make run

# First run: visit http://localhost:3350 to create admin account

Features

• OAuth2 Client Credentials grant for service-to-service auth
• User login/registration with email + password
• JWT tokens (HS256, 1-hour TTL) with hierarchical scopes (read < write < admin)
• Encrypted config — user database stored as AES-256-GCM encrypted TOML
• JSON-RPC 2.0 endpoint at /rpc with OpenRPC discovery
• MCP server at /mcp for AI agent integration (Claude, etc.)
• Admin dashboard with user management UI
• Zero-dependency token validation — any service with the same HERO_SECRET can verify tokens locally

Configuration

Variable	Required	Default	Description
HERO_SECRET	Yes	—	Master key for JWT signing and config encryption
--port	No	3350	Listen port
--config	No	~/hero/cfg/hero_auth.toml	Path to encrypted config file

API Endpoints

Authentication

Method	Path	Description
POST	/token	OAuth2 client_credentials grant (client_id + client_secret)
POST	/login	User login (email + password)
POST	/register	Self-register (returns JWT + one-time client_secret)
POST	/validate	Validate a JWT token
GET	/health	Health check

Admin (requires admin JWT)

Method	Path	Description
GET	/	Admin dashboard
POST	/users/add	Add user (returns one-time client_secret)
POST	/users/delete	Delete user
POST	/users/scope	Update user scope

JSON-RPC 2.0

Method	Path	Description
POST	/rpc	JSON-RPC endpoint (methods: health, stats, users.list, users.add, users.delete, token.create, token.validate, login)
GET	/rpc/discover	OpenRPC 1.3.2 specification

MCP (Model Context Protocol)

Method	Path	Description
POST	/mcp	MCP endpoint for AI agents (10 tools)

MCP setup for Claude Code:

claude mcp add --transport http hero-auth http://localhost:3350/mcp

Scope Hierarchy

Scope	Includes	Description
read	—	Default for self-registered users
write	read	Can modify data
admin	read, write	Can manage users and change scopes

JWT Claims

{
  "sub": "client_id (UUID)",
  "iss": "hero_auth",
  "iat": 1234567890,
  "exp": 1234571490,
  "scope": "read|write|admin"
}

Hero Ecosystem Integration

Other services validate tokens locally using the same HERO_SECRET — no network calls to hero_auth needed after initial token issuance. Services check the scope claim to enforce authorization.

Typical flow:

1. Service gets client_id + client_secret from admin
2. Service calls POST /token to get a JWT
3. Service includes JWT in requests to other services
4. Receiving service validates JWT locally with shared HERO_SECRET

Security

Function	Algorithm
JWT signing	HS256
Config encryption	AES-256-GCM
Password storage	SHA-256 hash
Key derivation	SHA-256(HERO_SECRET)

Build

make build      # Release build (optimized for size, stripped)
make test       # Run tests (4 crypto tests)
make install    # Build and install to ~/hero/bin/
make lint       # Run clippy
make fmt        # Format code

Port

3350 (registered in hero_ports)