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

• Public gateway plan
• Protocol v1
• KBeam compatibility specification
• Public login transparency
• Native signature verifier
• Nginx auth request integration
• Deployment examples
• Production hardening
• KBeam app device-login fix
• Same-device demo login
• Security and secret hygiene
• Rollback notes

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