Wallet-native authentication built with Next.js 16, React 19, Reown AppKit, Wagmi and SIWE.
Keypass is a portfolio project that demonstrates how to build wallet-based authentication for a modern web application. Instead of treating a wallet connection as proof of identity, the project implements the complete Sign-In with Ethereum (SIWE) flow: the user connects a wallet, receives a one-time nonce, signs a human-readable EIP-4361 message, and the server verifies that signature before creating an authenticated session.
This repository demonstrates practical experience with:
- Web3 wallet connectivity and network switching
- Cryptographic authentication with SIWE / EIP-4361
- Nonce generation and replay-attack prevention
- Server-side signature verification in Next.js Route Handlers
- Secure session cookies using signed JWTs and
HttpOnly - Client/server boundaries in the Next.js App Router
- Responsive authentication UI
The project supports Ethereum, Base, and Optimism through Reown AppKit, Wagmi, and Viem.
sequenceDiagram
participant User
participant Wallet
participant App
participant Server
User->>App: Connect wallet
App->>Wallet: Request connection
Wallet-->>App: Connected address and chain
User->>App: Sign in
App->>Server: Request one-time nonce
Server-->>App: Nonce in HttpOnly cookie
App->>Wallet: Request SIWE message signature
Wallet-->>App: Signed message
App->>Server: Submit message and signature
Server->>Server: Verify domain, nonce, signature, and time
Server-->>App: Session JWT in HttpOnly cookie
The private key never leaves the wallet. The application receives only the public address and the signature required to verify wallet ownership.
- Next.js 16 — App Router and Route Handlers
- React 19 and TypeScript
- Reown AppKit — wallet connection UI
- Wagmi 2 and Viem — Ethereum interactions
- SIWE — EIP-4361 message creation and verification
- JOSE — signed JWT session tokens
- Tailwind CSS — styling foundation
src/
|-- app/
| |-- api/auth/nonce/route.ts # One-time nonce endpoint
| |-- api/auth/verify/route.ts # SIWE verification and session creation
| |-- providers.tsx # AppKit, Wagmi, and React Query providers
| |-- page.tsx # Authentication experience
| `-- globals.css # Visual system and responsive layout
|-- components/
| `-- wallet-auth.tsx # Connect, sign in, and disconnect actions
`-- lib/
`-- wagmi.ts # Supported networks and Wagmi configuration
- Node.js 20+
- npm
- An Ethereum-compatible wallet, such as MetaMask or Coinbase Wallet
- A Reown project ID
npm installCreate .env.local in the project root:
NEXT_PUBLIC_REOWN_PROJECT_ID=your_reown_project_id
AUTH_SECRET=replace-with-a-long-random-secretAUTH_SECRET is required. The server deliberately refuses to create authentication sessions when it is missing rather than falling back to an insecure development secret.
Start the development server:
npm run devOpen http://localhost:3000 and connect a wallet to test the flow.
npm run dev # Start the development server
npm run build # Create a production build
npm run start # Start the production server
npm run lint # Run ESLintKeypass treats wallet connection and authentication as separate operations.
Connecting a wallet only exposes the public address. Authentication requires a fresh server-generated nonce and an EIP-4361 signature. The server validates the signature, expected domain, nonce, and message time before issuing a signed session token in an HttpOnly cookie. The nonce is deleted after successful verification to prevent reuse.
This keeps private keys inside the user's wallet while allowing the application server to establish an authenticated session based on cryptographic proof of address ownership.
This project provides the authentication foundation rather than a complete user-management system. A production application should additionally:
- persist users and sessions in an appropriate datastore;
- manage
AUTH_SECRETthrough the deployment platform's secret manager; - implement logout and session revocation;
- enforce authorization on protected resources;
- apply application-specific rate limiting and monitoring.
MIT