npm package: @nevx/auth
Description: Stateless, production-grade Web3 Authentication SDK
Author: Ryan Shelby
Latest version: 0.2.0

# @nevx/auth

<div align="center">

**Stateless, Production-Grade Web3 Authentication SDK**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![NPM](https://img.shields.io/badge/NPM-%40nevx%2Fauth-red.svg)](https://www.npmjs.com/package/@nevx/auth)

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

</div>

---

## ⚡ 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

```bash
npm install @nevx/auth viem
```

## 🚀 Quick Start

### 1. Initialize

```typescript
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

```typescript
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.

```typescript
// 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.

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

### Audit Logging
Track what's happening inside the security context.

```typescript
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](https://github.com/MdSagorMunshi)