Ryan Malloy
4c82487e0e
Ship an Astro middleware (src/middleware.ts) that runs on every request
and requires a valid Heady session for anything other than the login
flow itself. Previously any anonymous visitor could load /machines,
/users, /acls, /dns, /settings and the mock /api/users endpoint over
plaintext -- the SSR templates rendered as public shells and only the
front-end auth guard blocked interaction. That's a defense-in-depth
gap now that data endpoints are being wired up.
- src/middleware.ts: onRequest handler validates the heady_session
cookie via HeadySessionManager.validateSession(). Public allowlist:
/api/auth/*, /login, static assets. Unauthenticated /api/* returns
401 JSON; unauthenticated pages redirect to /api/auth/login with a
return_to query param so the OIDC round-trip lands back on the
original URL. Authenticated requests get context.locals.user set so
downstream pages can read Astro.locals.user without a second lookup.
- src/env.d.ts: type App.Locals.user as SessionUser so pages / APIs get
IDE feedback on typos.
- src/pages/{index,machines,acls,dns,users}.astro: 'export const
prerender = false' -- these pages render per-user data, they must
hit middleware on every request rather than being served as a
static file baked at build time. Without this, middleware runs
once during prerender (with no cookie) and writes a redirect as
the static HTML for the route.
- src/pages/api/{acls,users,dns/magic,dns/tailnet,settings/auth-keys}.ts:
same reason. API endpoints must be SSR so the middleware can gate
them at request time.
|
||
|---|---|---|
| .github | ||
| .zed | ||
| authentik-blueprints | ||
| cmd | ||
| docs | ||
| drizzle | ||
| examples | ||
| internal | ||
| nix | ||
| patches | ||
| public | ||
| remote-access | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| .npmrc | ||
| .tool-versions | ||
| agent.Dockerfile | ||
| ALPINE_ASTRO_TRANSFORMATION.md | ||
| astro.config.mjs | ||
| AUTHENTIK_HEADY_ARCHITECTURE.md | ||
| AUTHENTIK_SETUP_GUIDE.md | ||
| BETTER_ROLE_MAPPING_CONFIG.yaml | ||
| biome.json | ||
| Caddyfile | ||
| CHANGELOG.md | ||
| compose.yaml | ||
| config.example.yaml | ||
| CONFIGURABLE_ROLE_MAPPING_SOLUTION.md | ||
| DEBUGGING_ANALYSIS_REPORT.md | ||
| docker-compose.local.yml | ||
| Dockerfile | ||
| Dockerfile.dev | ||
| drizzle.config.ts | ||
| flake.lock | ||
| flake.nix | ||
| go.mod | ||
| go.sum | ||
| GUACAMOLE_REMOTE_ACCESS_DESIGN.md | ||
| headplane-security-assessment.md | ||
| HEADY_MANIFESTO.md | ||
| IMPROVEMENTS_DEMO.md | ||
| lefthook.yml | ||
| LICENSE | ||
| mise.toml | ||
| OIDC_IMPROVEMENTS_SUMMARY.md | ||
| package.json | ||
| pnpm-lock.yaml | ||
| PR_DRAFT_OIDC_ROLE_MAPPING.md | ||
| README.md | ||
| role-mapping-examples.yaml | ||
| SMART_IMPROVEMENTS.md | ||
| tailwind.config.mjs | ||
| TESTING_PLAN.md | ||
| tsconfig.json | ||
| vitest.config.ts | ||
| WASM_SSH_REMOVAL.md | ||
| wrangler.toml | ||
🤠 Heady
Strategic VPN management for Headscale that's actually awesome to use!
Headscale is the de-facto self-hosted version of Tailscale, a popular Wireguard based VPN service. By default, it does not ship with a web UI, which is where Heady comes in.
Heady is strategic VPN management that prioritizes security, thoughtful design, and awesome user experience. Unlike feature-heavy alternatives, Heady focuses on doing the important things incredibly well.
🎯 What Makes Heady Different
Security-First Design: Every feature is evaluated for security impact first
Convention Over Configuration: Smart defaults that just work for 90% of setups
Quality Over Quantity: Fewer features, done awesomely well
Community-Driven: Built for real users, not corporate feature checklists
✨ Awesome Features
- Smart Machine Management: Intuitive node administration with clear status and controls
- Intelligent ACL Configuration: Visual access control with tagging support
- Revolutionary OIDC Integration: Zero-config role mapping that just works with any identity provider
- DNS Made Simple: Easy MagicDNS setup and custom record management
- Thoughtful Configuration: Headscale settings that make sense
🚀 Getting Started
Heady runs as a web application alongside your Headscale server. Quick setup with smart defaults gets you running fast.
Quick Start (Docker - Recommended)
# Coming soon - simplified Docker deployment
🔧 Zero-Config OIDC Setup
Heady's revolutionary OIDC system works with any identity provider out of the box:
oidc:
issuer: "https://your-provider.com"
client_id: "your-client-id"
client_secret: "your-secret"
# That's it! Role mapping, scopes, and redirect URIs are auto-configured
Want custom roles? Easy:
HEADPLANE_ADMIN_GROUPS="admin,managers"
HEADPLANE_OWNER_GROUPS="ceo,founders"
📖 Documentation & Community
- 📋 OIDC Setup Guide - Zero-config authentication
- 🏗️ Architecture Design - Security-first remote access
- 🤠 Heady Manifesto - Our philosophy and values
- 🔧 Configuration Examples - Smart defaults you can customize
🎯 Deployment Options
Heady v1.0 features a unified architecture with all awesome features available in every deployment:
-
Standard Deployment
Quick deployment with smart defaults. All features available, with optional integrations configured as needed.
-
Advanced Integration
Enable Docker, Kubernetes, or native process integration for automatic DNS management and configuration updates.
Versioning
Headplane uses semantic versioning for its releases (since v0.6.0).
Pre-release builds are available under the next tag and get updated when a new release
PR is opened and actively in testing.
Contributing
Headplane is an open-source project and contributions are welcome! If you have any suggestions, bug reports, or feature requests, please open an issue. Also refer to the contributor guidelines for more info.
Copyright (c) 2025 Aarnav Tale