Philosophy

Traditional authentication systems rely on storing secrets (hashed passwords) on the server. If the database is compromised, those secrets are exposed to offline brute-force attacks.

VoidAuth flips the script. Inspired by blockchain security and modern cryptography, VoidAuth ensures that the server never handles user secrets. Period.

Core Principle

"If the server doesn't know the secret, it can't lose the secret."

  • Server Knowledge: Zero. Stores only a Public Commitment (Ed25519 Public Key).
  • Client Ownership: Absolute. The Private Key never leaves the user's device.
  • Verification: Cryptographic. Achieved via a Challenge-Response proof.

Security Architecture

Authentication in VoidAuth is a four-step cryptographic handshake:

  1. Handshake: Client requests a challenge (random nonce) from the server.
  2. Signature: Client signs the challenge using their local Private Key.
  3. Proof: Client sends the signature and challenge back to the server.
  4. Verification: Server uses the stored Public Key to verify the signature.

Installation

Install the package via pip to enter the void.

pip install django-voidauth

Prerequisites

  • Django 3.2+
  • Python 3.8+
  • Modern Browser (Web Crypto API support)

Project Setup

Configure your Django settings to enable the asymmetric handshake.

1. Update INSTALLED_APPS

INSTALLED_APPS = [
    ...
    'voidauth',
]

2. Configure Auth Backends

AUTHENTICATION_BACKENDS = [
    'voidauth.backend.VoidAuthBackend',
    'django.contrib.auth.backends.ModelBackend', # Fallback for admin
]

3. Add Middleware

MIDDLEWARE = [
    ...
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'voidauth.middleware.VoidAuthMiddleware',
    ...
]

4. Include URLs

urlpatterns = [
    ...
    path('voidauth/', include('voidauth.urls')),
]

Void Architect

The AI-powered setup assistant that performs a deep scan of your project to automate the integration process.

python manage.py void_architect --auto

The Architect will analyze your project structure, find your specific auth templates, detect form field names, and apply non-destructive patches using template tags.

View Shield

The View Shield is an indentation-agnostic defensive layer designed specifically for Django registration views. It ensures that critical cryptographic keys are verified before any user data is committed to the database.

Surgical Integrity

Unlike standard middleware, the View Shield performs surgical, indentation-agnostic patching. This means it can safely protect registration logic even when nested deep within complex conditional blocks or decorators.

This technology is automatically injected by the Void Architect when using the --auto flag, providing an out-of-the-box defense against incomplete hardware handshakes.

Client-Side Setup

First, include the required cryptographic libraries and the VoidAuth logic in your base template:

<!-- Cryptography Libraries -->
<script src="{% static 'voidauth/js/libsodium.js' %}"></script>
<script src="{% static 'voidauth/js/bip39.js' %}"></script>
<!-- VoidAuth Logic -->
<script src="{% static 'voidauth/js/voidauth.js' %}"></script>

JavaScript API

The global VoidAuth object provides everything you need to manage the client-side lifecycle.

Method Description
VoidAuth.register(u, e, p) Generates keys, creates account, and returns recovery mnemonic.
VoidAuth.login(username) Performs the challenge-response handshake.
VoidAuth.recover(u, m, p) Restores account access on a new device.

Template Tags

VoidAuth ships with built-in Django template tags for a "plug-and-play" integration.

{% load voidauth_tags %}

Recovery Modal

Ensures users save their 12-word seed phrase before finishing registration.

{% void_recovery_modal %}

Secure Login Button

Enable passwordless authentication inside your login form.

{% void_secure_login_button redirect_url='/dashboard' %}

Recovery Architecture

VoidAuth provides a unique dual-path recovery system:

Path A: Seed Phrase

12-word phrase re-derives the Private Key entirely on the client side. No server interaction required.

Path B: Recovery Blob

Server provides an AES-GCM encrypted version of the key. Client decrypts it locally using a master password.

Browser Compatibility

VoidAuth leverages the Web Crypto API and IndexedDB.

  • Chrome 37+
  • Firefox 34+
  • Edge 12+
  • Safari 10.1+