@nevx/auth

Stateless, Production-Grade Web3 Authentication SDK

A 100% free, open-source, stateless authentication primitive for the decentralized web.
No servers. No databases. No API keys. Just cryptography.

⚡ Features & Roadmap

• [x] 🔒 Zero-Server Architecture: Works entirely client-side on IPFS, static sites, and edge networks.
• [x] 🔑 Cryptographic Truth: Auth is a mathematical proof of ownership + domain binding (EIP-712).
• [x] 🛡️ High-Level Security:
  • [x] Encrypted Vault: Store sensitive data (API keys) encrypted by the user's session.
  • [x] Panic Protocol: Instant "Red Button" to wipe memory, storage, and sessions.
  • [x] Audit Logs: Local, ephemeral tracking of security-critical events.
• [x] ⚡ Ephemeral Sessions: HKDF-derived session keys that exist only in memory.
• [x] 🔌 Universal Wallet Support: Built-in support for EIP-6963 (Multi-Injected Providers).
• [ ] 👆 Biometric Bridge: WebAuthn & Passkey integration for hardware-level security.
• [ ] ⛓️ Multi-Chain Adapter: Native support for Solana, Cosmos, and Bitcoin.
• [ ] ⚛️ Framework Hooks: useAuth (React) and composables (Vue) for faster integration.
• [ ] 🤖 Smart Accounts: First-class support for ERC-4337 Account Abstraction.

📦 Installation

npm install @nevx/auth viem

🚀 Quick Start

1. Initialize

import { NevxAuth } from '@nevx/auth';

const auth = new NevxAuth({
  domain: window.location.hostname, // Security: Must match current domain
  chainId: 1,                       // Ethereum Mainnet
  challengeTTL: 300,                // 5 minutes
  sessionTTL: 3600,                 // 1 hour
});

2. Connect & Sign In

import { connectWallet, signTypedData } from '@nevx/auth/adapters/injected'; // or your preferred adapter

async function login() {
  // A. Connect Wallet
  const address = await connectWallet();
  
  // B. Generate Challenge & Sign
  const challenge = auth.generateChallenge(address);
  
  // Note: users sign a readable EIP-712 message, not opaque hashes
  const signature = await signTypedData(address, { 
      domain: { name: 'Nevx Auth', version: '1', chainId: 1 },
      types: { ... }, // (Helper available in SDK)
      message: challenge 
  });
  
  // C. Verify & Create Session
  const user = await auth.signIn({ message: challenge, signature });
  console.log('Secure Session Established:', user.address);
}

🔐 Advanced Security Features

Encrypted Vault

Store secrets that are only accessible while the user is logged in. Data is encrypted using AES-256-GCM with a key derived from the session signature.

// Save a secret (e.g., an OpenAI Key)
await auth.vault.setItem('api_key', 'sk-...');

// Retrieve it later
const apiKey = await auth.vault.getItem('api_key');

Panic Protocol

Detect a compromise? Trigger the panic protocol to instantly nuke all sensitive data from memory and storage.

// Bind to a UI button or intrusion detection system
auth.security.panic();

Audit Logging

Track what's happening inside the security context.

const logs = auth.audit.getLogs();
// [
//   { type: 'AUTH_SUCCESS', timestamp: 1700000000, details: { address: '0x...' } },
//   { type: 'VAULT_ACCESS', timestamp: 1700000005, details: { key: 'api_key' } }
// ]

🛡️ Security Model

1. Replay Protection: Challenges include high-entropy 256-bit nonces and strict TTLs.
2. Domain Binding: Signatures are bound to window.location.hostname. A signature from evil.com is mathematically invalid on app.yoursite.com.
3. Memory-Only Keys: Session keys are never written to disk. If the tab is closed, the key is gone.
4. Client-Side Integrity: While we provide isCompromised() checks, true security relies on the transport layer (HTTPS) and the user's device integrity.

🔄 Changelog

v0.2.0 - High-Level Security Update

• New Feature: Encrypted Vault: Securely store sensitive data using session-derived encryption.
• New Feature: Panic Protocol: Instant emergency wipe functionality for memory and storage.
• New Feature: Audit Logging: Local tracking of authentication and security events.
• Enhanced: Updated NevxAuth core to integrate security modules.

License

MIT © Ryan Shelby