KBeam Auth Gateway
KBeam Auth Gateway is a standalone server for wallet-based login flows. It is
intended to become a public reference implementation for the KBeam login
protocol, while application-specific code and private deployment details remain
outside this repository.
The core idea is simple: never build another password login. A protected site can
let KBeam approve a short-lived challenge, while the site keeps its own session,
permissions, data, and private routes.
Live Demo
Try the hosted demo:
https://kbeam.app/auth-gateway-test/
KBeam Auth Gateway is a source-available KBeam/Kaspa wallet authentication
gateway for websites and protected areas. It is comparable in spirit to
SIWE/Web3 wallet login, but built for KBeam-compatible Kaspa wallet login flows
with QR, same-device app return, server-side sessions, and self-hosted access
control.
Goal
The gateway owns authentication only:
- create login tickets
- create QR codes and same-device approve links
- create deterministic challenge messages
- verify wallet signatures
- check allowed wallets or later users and organizations
- issue, validate, and revoke HttpOnly session cookies
- provide a healthcheck
- support reverse-proxy integration through nginx
auth_request
- provide demo and integration examples
Application business logic, payment flows, mobile app source code, production
secrets, private hostnames, and internal infrastructure notes are out of scope.
Documentation
Current Status
This repository contains the extracted planning foundation, a FastAPI runtime
skeleton, native Schnorr signature verification, a local demo UI, tests, and
generic deployment examples.
Vision
KBeam Auth Gateway starts with one clear purpose: secure login with KBeam,
without passwords and without KBeam knowing the protected content of the website
that embeds it.
The next stage is intended to add optional user management. A wallet address
could be connected to a customer account, while each website still controls its
own roles, permissions, data, and protected areas.
Future versions are also planned to support optional contact and support flows
after login. Users could choose to be reachable for support, direct chat,
follow-up questions, or later features such as payments and customer-related
actions.
These additions are not part of the first release. The first step remains a
transparent, self-hostable auth gateway. The development direction is to grow it
into a base for secure customer accounts, support, and future product workflows.
License
This project uses the
KBeam Auth Gateway Source Available Compatibility License 1.1.
You may use, host, integrate, modify, and distribute the gateway, including for
commercial protected areas. The required condition is that the KBeam-compatible
login path remains working in forks, deployments, and derivative versions that
include this gateway's login flow.
This is a source-available license with a compatibility requirement, not an
OSI-approved open source license. See LICENSE, NOTICE,
KBEAM-COMPATIBILITY.md, and
Licensing notes. KBeam brand usage is covered by
TRADEMARKS.md.
Local Development
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
Run the gateway locally:
cp .env.example .env
.venv/bin/kbeam-auth-gateway
The first runtime skeleton exposes /health, /api/auth/device-login,
/api/auth/session, /api/auth/validate, and logout/session endpoints. The
demo UI is available at http://127.0.0.1:18090/demo.
The default signature verifier mode is native. It verifies a 64-byte Schnorr
signature over the raw UTF-8 challenge message with a 32-byte x-only secp256k1
public key and checks that the derived Kaspa address matches the challenge
address. demo mode is available only for local flow tests.
Production Features
- SQLite or Postgres-backed tickets, sessions, wallets, and audit log
- wallet policy:
open for demos or allowlist for protected deployments
- admin API protected by
KBEAM_AUTH_ADMIN_TOKEN
- per-IP rate limits for ticket creation, polling, SSE, challenge, approval, and admin routes
- maximum pending-ticket cap
- SSE ticket events with polling fallback in the demo
- automatic QR expiry handling in the demo
- KBeam-compatible
kbeam:// QR links, currently kbeam://pos-login, with
webApproveURL fallback
- same-device demo login button with
returnTo
Admin examples:
curl -H "Authorization: Bearer $KBEAM_AUTH_ADMIN_TOKEN" \
https://auth.example.com/api/admin/wallets
curl -X POST -H "Authorization: Bearer $KBEAM_AUTH_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"address":"kaspa:example","label":"Example Wallet","role":"admin","enabled":true}' \
https://auth.example.com/api/admin/wallets
Use KBEAM_AUTH_STORE_BACKEND=postgres with KBEAM_AUTH_POSTGRES_DSN when the
gateway should share durable state across rolling releases or multiple workers.
Docker
cp .env.example .env
docker compose up -d --build
curl -f http://127.0.0.1:18090/health
