Skip to content
OrionDevStarPublic

About

Secure wallet-native authentication with SIWE, Next.js, Reown AppKit and Wagmi.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Keypass

Wallet-native authentication built with Next.js 16, React 19, Reown AppKit, Wagmi and SIWE.

Web3 authentication with real server-side verification

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.

Authentication flow

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
Loading

The private key never leaves the wallet. The application receives only the public address and the signature required to verify wallet ownership.

Technology stack

  • 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

Project structure

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

Getting started

Requirements

  • Node.js 20+
  • npm
  • An Ethereum-compatible wallet, such as MetaMask or Coinbase Wallet
  • A Reown project ID

Installation

npm install

Create .env.local in the project root:

NEXT_PUBLIC_REOWN_PROJECT_ID=your_reown_project_id
AUTH_SECRET=replace-with-a-long-random-secret

AUTH_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 dev

Open http://localhost:3000 and connect a wallet to test the flow.

Available scripts

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 ESLint

Security model

Keypass 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.

Production considerations

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_SECRET through the deployment platform's secret manager;
  • implement logout and session revocation;
  • enforce authorization on protected resources;
  • apply application-specific rate limiting and monitoring.

License

MIT

About

Secure wallet-native authentication with SIWE, Next.js, Reown AppKit and Wagmi.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages