dero-auth

dero-auth

Sign in with your DERO wallet. No email. No password. Just cryptographic proof of wallet ownership.

dero-auth is a TypeScript library that provides wallet-based authentication for DERO — a privacy-focused cryptocurrency with encrypted transactions. It works like "Sign in with Ethereum" (SIWE/EIP-4361), but for DERO's privacy chain.

Privacy advantage: Unlike Ethereum auth, authenticating with DERO doesn't expose your transaction history. Your on-chain activity remains invisible to the service.

Features

• Pure TypeScript signature verification (Schnorr on BN256) — no wallet needed server-side
• React components — drop-in <SignInWithDero /> button and useDeroAuth() hook
• Next.js integration — ready-made API route handlers and auth middleware
• XSWD client — connects to DERO wallets (Engram, CLI) via WebSocket
• SIWE-style message format — human-readable, domain-bound, replay-protected
• JWT sessions — standard token-based session management
• Zero personal data — just a cryptographic address

Quick Start

Install

npm install dero-auth

Set a JWT Secret (required)

Use a strong secret (at least 32 bytes):

export JWT_SECRET="$(openssl rand -base64 32)"

1. Server: Create API Routes (Next.js App Router)

// app/api/auth/challenge/route.ts
import { createAuthHandlers } from "dero-auth/next";

const { challengeHandler } = createAuthHandlers({
  domain: "myapp.com",
  uri: "https://myapp.com",
  jwtSecret: process.env.JWT_SECRET!,
});

export const POST = challengeHandler;

// app/api/auth/verify/route.ts
import { createAuthHandlers } from "dero-auth/next";

const { verifyHandler } = createAuthHandlers({
  domain: "myapp.com",
  uri: "https://myapp.com",
  jwtSecret: process.env.JWT_SECRET!,
});

export const POST = verifyHandler;

For production deployments, use a shared nonce store (Redis/DB) via the nonceStore option so replay protection works across multiple instances.

Production Nonce Store (Redis)

dero-auth includes a Redis-backed NonceStore adapter with atomic consume:

import { createClient } from "redis";
import { createAuthHandlers } from "dero-auth/next";
import { createRedisNonceStoreFromNodeRedis } from "dero-auth/server";

const redis = createClient({ url: process.env.REDIS_URL! });
await redis.connect();

const nonceStore = createRedisNonceStoreFromNodeRedis(redis, {
  keyPrefix: "myapp:auth:nonce:",
});

const { challengeHandler, verifyHandler } = createAuthHandlers({
  domain: "myapp.com",
  uri: "https://myapp.com",
  jwtSecret: process.env.JWT_SECRET!,
  nonceStore,
});

Install a Redis client of your choice in your app (redis or ioredis).

2. Client: Add the Provider and Button

// app/layout.tsx (or any parent component)
import { DeroAuthProvider } from "dero-auth/react";

export default function Layout({ children }) {
  return (
    <DeroAuthProvider appName="My App">
      {children}
    </DeroAuthProvider>
  );
}

// app/page.tsx (or any page)
import { SignInWithDero } from "dero-auth/react";

export default function LoginPage() {
  return <SignInWithDero />;
}

That's it. The button handles the full flow: wallet connection, challenge signing, and verification.

3. Custom Hook (Alternative)

If you don't want the provider pattern:

"use client";
import { useDeroAuth } from "dero-auth/react";

export default function LoginPage() {
  const { signIn, signOut, isAuthenticated, address, isLoading } = useDeroAuth();

  if (isAuthenticated) {
    return (
      <div>
        <p>Signed in as {address}</p>
        <button onClick={signOut}>Sign Out</button>
      </div>
    );
  }

  return (
    <button onClick={signIn} disabled={isLoading}>
      {isLoading ? "Connecting..." : "Sign In with DERO"}
    </button>
  );
}

How It Works

Authentication Flow

User                    Browser                   Server
 |                         |                         |
 | Click "Sign In"         |                         |
 |------------------------>|                         |
 |                         | POST /auth/challenge     |
 |                         |   { address }            |
 |                         |------------------------>|
 |                         |   { messageText, nonce } |
 |                         |<------------------------|
 |                         |                         |
 |  Wallet: "Sign this?"   | XSWD: SignData(message) |
 |  [Approve] [Deny]       |                         |
 |------------------------>|                         |
 |  PEM signature           |                         |
 |                         | POST /auth/verify        |
 |                         |   { signature, nonce }   |
 |                         |------------------------>|
 |                         |     Verify Schnorr sig   |
 |                         |     Check domain/nonce   |
 |                         |   { session (JWT) }      |
 |                         |<------------------------|
 |  Authenticated!          |                         |

Message Format

The message shown to the user in their wallet:

myapp.com wants you to sign in with your DERO wallet:
dero1qy...abc123

Sign in to My App

URI: https://myapp.com
Version: 1
Chain ID: dero-mainnet
Nonce: k8j2m4n6p8q0
Issued At: 2026-02-14T12:00:00.000Z
Expiration Time: 2026-02-14T12:05:00.000Z

Cryptography

• Signature scheme: Schnorr signatures on BN256 (Barreto-Naehrig 254-bit curve)
• Hash function: Keccak-256, reduced modulo the curve order
• Address format: Bech32 with 33-byte compressed G1 public key
• Verification: Pure TypeScript using @noble/curves (audited by Cure53)
• No blockchain query needed: Signatures are verified mathematically, offline

Package Exports

Import	Description
dero-auth	Core types and message format
dero-auth/crypto	Pure crypto: Schnorr verify, BN256, address parsing
dero-auth/server	Server SDK: challenges, verification, JWT sessions
dero-auth/client	Browser SDK: XSWD wallet connection, signing flow
dero-auth/react	React: Provider, button, hooks
dero-auth/next	Next.js: API handlers, auth middleware

API Reference

Core (dero-auth)

import {
  serializeMessage,   // DeroAuthMessage → string
  parseMessage,        // string → DeroAuthMessage
  validateMessage,     // Check domain, nonce, expiry
  generateNonce,       // Crypto-random nonce string
  type DeroAuthMessage,
  type DeroAuthConfig,
  type DeroAuthSession,
} from "dero-auth";

Crypto (dero-auth/crypto)

import {
  verifySignature,     // Verify PEM signature → { address, message }
  parsePEM,            // Parse DERO PEM format
  decodeAddress,       // DERO address → public key
  encodeAddress,       // Public key → DERO address
  isValidAddress,      // Validate address format
  reducedHash,         // Keccak256 mod curve order
  decompressG1,        // 33 bytes → G1 point
  compressG1,          // G1 point → 33 bytes
} from "dero-auth/crypto";

Server (dero-auth/server)

import {
  createChallengeServer,  // Challenge generation + nonce management
  verifyAuth,             // Full verification pipeline
  createSessionManager,   // JWT session creation/verification
} from "dero-auth/server";

Client (dero-auth/client)

import {
  XSWDClient,         // Low-level XSWD WebSocket client
  createAuthClient,   // High-level auth flow client
} from "dero-auth/client";

React (dero-auth/react)

import {
  DeroAuthProvider,    // Context provider
  SignInWithDero,      // Drop-in button
  useDeroAuth,         // Standalone hook
  useDeroAuthContext,  // Hook for use within provider
} from "dero-auth/react";

Next.js (dero-auth/next)

import {
  createAuthHandlers,        // API route handlers
  createDeroAuthMiddleware,  // Auth middleware
  getAuthAddress,            // Extract address from request
} from "dero-auth/next";

Protecting Routes (Next.js Middleware)

// middleware.ts
import { createDeroAuthMiddleware } from "dero-auth/next";

export const middleware = createDeroAuthMiddleware({
  jwtSecret: process.env.JWT_SECRET!,
  protectedPaths: ["/dashboard", "/api/protected"],
  loginPath: "/login",
});

export const config = {
  matcher: ["/dashboard/:path*", "/api/protected/:path*"],
};

Requirements

• DERO wallet: Engram (desktop) or DERO CLI wallet with XSWD enabled
• Node.js: >= 20.19.0
• React: 18+ or 19+ (optional, for React components)
• Next.js: 14+ (optional, for Next.js helpers)

Wallet Compatibility

Wallet	Connection	Status
Engram (desktop)	XSWD (ws://localhost:44326)	Supported
DERO CLI wallet	XSWD (ws://localhost:10103)	Supported

Why Not Just Use Ethereum Auth?

	Ethereum (SIWE)	DERO Auth
Transaction privacy	All transactions visible on-chain	Transactions encrypted, invisible to verifier
Wallet extension	MetaMask required	Connects to local wallet via WebSocket
Personal data	Address links to full history	Address reveals nothing about activity
Verification	Pure JS (ecrecover)	Pure JS (Schnorr on BN256)

Development

# Install dependencies
npm install

# Run tests
npm test

# Type check
npx tsc --noEmit

# Build
npm run build

# Run demo app
JWT_SECRET="$(openssl rand -base64 32)" cd demo && npm install && npm run dev

License

MIT — see LICENSE

DHEBP is not affiliated with or endorsed by the DERO Project or its core developers.