Open Source

A transparent, MIT-licensed Lightning login system you can read, run, and adapt.

What This Page Is For

This page is here to give you a clear, non-technical-first overview of how the Key-Rex codebase is structured, what is actually open source, and what kind of data the system uses. If you are a developer, you can drill into the file and directory references. If you are less technical, you can still get a high-level understanding of how things work and where to look if your team needs more detail.

Everything described here reflects the current implementation of Key-Rex (including the admin dashboard, analytics, documentation, and public pages). Outdated parts of the earlier prototype (like the original onboarding flow and old subscription system) have been removed from both the product and this page.

Repository & License

The complete Key-Rex source code is available in our public repository. All code is released under the MIT License, which means you can use, modify, and distribute it freely.

Source Code Repository

The full Key-Rex codebase is available on GitHub. You can browse the code, review the implementation, fork it for your own use, or contribute improvements.

Note: Repository link will be added when the GitHub repository is created. For now, the source code is available through the hosted Key-Rex service.

License File

The complete MIT License text is included in the LICENSE file in the repository root. Once the repository is available, you can view it directly there.

The license grants you permission to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to including the copyright notice and license text in any redistributed copies.

License

Key-Rex is released under the MIT License.

In practical terms, MIT means you can:

  • Use the code in your own projects (commercial or non-commercial)
  • Modify it to fit your needs
  • Fork it, host it yourself, or build your own version
  • Bundle it into a broader product you sell

The main requirement is that if you redistribute the code (for example, in your own open source project or product), you keep the original license text and copyright notice.

You are not required to give Key-Rex credit when you use the code, but it's appreciated if you do.

What Is Open Source in Key-Rex?

Key-Rex is designed as a fully open-source application. The same code that powers the public website, customer dashboard, admin dashboard, and embed script is available in this repository.

That means you (or your developers) can:

  • Inspect all authentication logic (including LNURL-auth and signature checks)
  • Review how domains, analytics, and settings are stored and used
  • See exactly what data is collected and how it flows through the system
  • Understand the admin tools and how they aggregate system-wide metrics

There are no hidden proprietary services, closed-source “black box” enforcement modules, or secret tracking libraries injected at runtime. When in doubt, you can always search the code under the app/, components/, and lib/ directories to see exactly how something works.

Data Collection & Privacy

This section focuses on what the Key-Rex service itself uses in order to run. For a more policy-focused explanation, see the Support page. Here we focus on how it shows up in the code.

What Key-Rex Does Not Track for Your Visitors

  • No email addresses or names from your end users
  • No marketing pixels or behavioral tracking scripts
  • No browser fingerprinting or device IDs for visitors
  • No IP address storage for your end users' sign-ins

What Key-Rex Does Use

  • xpub (extended public identifier) – a deterministic identifier derived from a wallet's public key, used as the "username" for authentication.
  • Site ID – a unique ID that ties your Key-Rex account to the embed script on your site.
  • Allowed domains and verification status – the list of domains that are permitted to use your Key-Rex integration. Production domains require DNS TXT record verification to prove ownership before authentication works. Test domains (localhost, *.test, staging.*) are automatically verified.
  • Analytics metrics – counts of logins and high-level patterns (e.g., per domain, per wallet type, browser/device categories, day-of-week, new vs returning).
  • Account-owner metadata – when you accept the disclaimer or submit the contact form, the code captures IP address and user agent for audit/support purposes.

All of this behavior is implemented in first-party code under lib/storage.ts, lib/db.ts, and various API routes in app/api/. There are no hidden third-party analytics SDKs.

Where Things Live in the Code

If you (or your developers) want to understand or audit a specific part of Key-Rex, this high-level map shows where to start. It is not an exhaustive per-file listing, but it covers the main areas most people look for.

Core App & Public Pages

app/page.tsx
Homepage and main marketing content, including the Key-Rex button preview and onboarding entry points.
app/faq/page.tsx
Frequently Asked Questions with plain-language explanations for website owners.
app/support/page.tsx
Combined support page with service availability, support model, data retention/privacy, custom solutions, and contact form.
app/how-it-works/page.tsx
Explains how Lightning wallet authentication works and what is required to integrate Key-Rex.
app/requirements/page.tsx
Technical requirements for using Key-Rex on a website (backend, domains, HTTPS, etc.).
app/why-keyrex/page.tsx
Why Key-Rex exists, what makes it different, and how it fits Bitcoin-first companies.
app/for-wallets/page.tsx
Wallet Partnerships page for Lightning wallet providers who want to integrate with Key-Rex.
app/docs/page.tsx
Developer documentation and integration guide with quick start, framework examples, API reference, and troubleshooting.

Dashboard & Admin

app/dashboard/page.tsx
Main user dashboard: integration code, domains, analytics, troubleshooting, documentation, and settings.
app/admin/login/page.tsx
Admin login using LNURL-auth for the Key-Rex administrator.
app/admin/dashboard/page.tsx
Admin dashboard for system-wide analytics, user management, contact submissions, and featured wallets.
app/onboarding/page.tsx
Multi-step onboarding wizard for new Key-Rex customers, guiding them through account setup and first integration.

Authentication & Embed

components/LoginButton.tsx
Reusable login button that initiates LNURL-auth via WebLN or QR code.
app/embed/route.ts
Serves the embeddable JavaScript for the Key-Rex button, including verified domain validation and branding rules.
app/embed/qr/page.tsx
QR-code-based sign-in flow for users on mobile wallets or without WebLN.
app/auth/success/page.tsx
Post-authentication success page that receives the xpub from the auth flow and redirects the user back to the client site.
app/api/auth/callback/route.ts
LNURL-auth callback handler that verifies signatures and derives a deterministic xpub identifier.
app/api/verify/route.ts
Verifies each login, enforces verified domain checks (only verified domains can authenticate), records analytics, and respects integration shutdown.

APIs & Storage

app/api/user/route.ts
Returns the current authenticated Key-Rex account (website owner) based on signed cookies.
app/api/domains/route.ts
Create, update, and delete allowed domains for a Key-Rex account. Manages domain verification status (pending, verified, failed).
app/api/domains/verify/route.ts
Verifies domain ownership by checking DNS TXT records. Production domains require verification before authentication works.
app/api/embed/config/route.ts
Provides configuration for the embed script and live previews, including featured wallets.
app/api/contact/route.ts
Stores contact form submissions in the database and captures basic metadata for support.
app/api/admin/*
Admin-only APIs for authentication, system stats, users, contact submissions, and wallet management.
lib/storage.ts
PostgreSQL storage layer using Prisma ORM for users, domains, analytics, and contact submissions. All functions are async and return Promises.
lib/db.ts
Prisma database client singleton with connection pooling for serverless, retry logic for transient errors, and Map/Set to JSON serialization helpers.
prisma/schema.prisma
PostgreSQL database schema defining all models: User, Domain, UsageStats, ActivityLog, AuthSession, FeaturedWallet, and ContactSubmission.
types/index.ts
Shared TypeScript types for users, analytics, activity logs, and admin data.

Security & Utilities

lib/auth.ts
Low-level LNURL-auth helpers: signature verification and deterministic xpub derivation.
lib/admin-auth.ts
Admin-only authentication helpers that check the configured ADMIN_XPUB.
lib/utils.ts
Utility helpers including device/wallet detection used for analytics, domain validation, and verification token generation.
lib/domain-verification.ts
DNS TXT record lookup and domain verification logic. Checks for keyrex-verification tokens in domain DNS records.
lib/lnurl.ts
LNURL bech32 encoding and decoding used to generate Lightning authentication challenge URLs.
lib/cors.ts
Cross-origin request validation for the embed script, checking request origins against allowed domains.
lib/rate-limit.ts
Rate limiting middleware to protect API endpoints from abuse.

Configuration & Meta

package.json
Project dependencies and scripts (Next.js, React, Tailwind, TypeScript, analytics libraries, etc.).
tsconfig.json
TypeScript configuration for the project.
tailwind.config.ts
Tailwind CSS theme and utility configuration.
next.config.js
Next.js configuration.
LICENSE
MIT License text for Key-Rex.
README.md
High-level project overview and development setup instructions.

Running Key-Rex Yourself

Many open source projects include a "how to run this yourself" section. Key-Rex is no different – you can run the full stack locally or deploy your own instance if you want complete control.

  1. Clone the repository and install dependencies (see README.md).
  2. Run the development server (usually npm run dev).
  3. Set any required environment variables (for example, ADMIN_XPUB for admin login).
  4. In production, set DATABASE_URL to your PostgreSQL connection string and run npx prisma migrate deploy to initialize the database.
  5. Deploy to your preferred host (Vercel, your own infrastructure, etc.).

⚠️ Important: Known Limitations for Production Use

The current implementation includes some simplified implementations that work for development and basic use, but should be enhanced for production deployments:

  • Database: Uses PostgreSQL via Prisma ORM. Connection pooling may need tuning for serverless environments (e.g., Vercel). See lib/db.ts for the current pooling configuration.
  • Signature Verification: Uses production-grade libraries (@noble/secp256k1 and elliptic) with support for both compact and DER-encoded signatures. Consider reducing verbose debug logging in lib/auth.ts for production.
  • xpub Derivation: Uses a simplified derivation method. For production, consider implementing proper HD wallet derivation if you need to link multiple keys from the same wallet.

These limitations are documented in DEPLOYMENT.md. Review and address these before deploying to production.

Self-hosting is optional and requires engineering time. For most sites, using the hosted Key-Rex service is simpler, but the open source code is there if you ever need to move or customize.

Security & Vulnerabilities

Security is a priority for Key-Rex. If you discover a security vulnerability, we appreciate responsible disclosure so we can address it before it becomes public.

Security Policy

A detailed security policy is available in the SECURITY.md file in the repository root. This file follows GitHub's standard security policy format and provides complete details on how to report vulnerabilities.

If you find a security vulnerability in Key-Rex, please report it privately rather than opening a public issue. This gives us time to fix the issue before it's disclosed publicly.

Security Email: Please use the contact form on our website with "SECURITY" in the subject line, or email us directly at the address below.

Note: Security email address will be added when available. For now, please use the contact form with "SECURITY" in the subject line.

What to Include in Your Report

  • Description of the vulnerability and potential impact
  • Steps to reproduce the issue (if applicable)
  • Affected versions or components
  • Suggested fix (if you have one)

Our Commitment

We commit to acknowledging receipt of security reports within 48 hours and providing an initial assessment within 7 days. Critical vulnerabilities will be prioritized for immediate attention. We will work with you to coordinate public disclosure after the issue is resolved.

Contributing & Reporting Issues

At this stage, Key-Rex is focused on being a reliable, understandable reference implementation. Contribution guidelines are available in the CONTRIBUTING.md file in the repository (when available). If you are interested in contributing, auditing, or suggesting improvements, you can:

  • Review the public code and raise questions through the contact form on the website.
  • Fork the project and maintain your own internal version if you have very specific needs.
  • Share feedback on documentation gaps or confusing areas so the public pages and dashboard docs can be improved.
  • Check the CHANGELOG.md file for version history and recent changes.

Third-Party Dependencies

Key-Rex uses several open source libraries. Key dependencies include:

  • Next.js & React - Web framework and UI library
  • Prisma & @prisma/client - Database ORM and PostgreSQL access layer
  • @noble/secp256k1 - Cryptographic signature verification
  • bech32 - LNURL encoding/decoding
  • qrcode - QR code generation for mobile authentication

See package.json for the complete list of dependencies and their licenses.

Over time, more formal contribution guidelines (pull requests, coding standards, security disclosure process) can be added. For now, the priority is clarity and auditability for people deciding whether to trust Key-Rex as their Lightning login layer.