AddrAuth (Address Authentication)

Overview

AddrAuth is a lightweight, flexible authentication package designed for blockchain applications. It provides a secure and efficient way to verify wallet ownership across multiple chains and wallet types, enabling easy implementation of gated access in "decentralized" applications.

Features

Multi-chain support: Compatible with various blockchain networks
Wallet adapters: Works seamlessly with multiple wallet types (Not yet implemented, but coming soon!)
Challenge-response authentication: Ensures secure verification of wallet ownership
JWT integration: Provides persistent authentication sessions
Open-source: Easily customizable and extendable

How It Works

AddrAuth implements a simple yet powerful authentication flow:

Challenge Generation: The server creates a unique challenge for the client.
Signature Request: The client signs the challenge using their wallet.
Verification: The server verifies the signature to authenticate the user.
JWT Issuance: Upon successful verification, a JWT is issued for persistent authentication.

Installation

Install AddrAuth using npm or yarn:

npm install addrauth
# or
yarn add addrauth

Usage

Here's a basic example of how to use AddrAuth:

import AddrAuth from "addrauth";

// Initialize AddrAuth
const addrAuth = new AddrAuth({
  verifySignature: yourSignatureVerificationFunction, // Adapter helpers are still in development
  JWTSecret: "your-secret-key",
  challengeExpiresIn: "10m", // How long the challenge is valid for, default is 10 minutes
  JWTExpiresIn: "100d", // After the user has authenticated, how long the persistent JWT is valid for, default is 100 days
});

// Generate a challenge (Returns challenge and JWT)
// Address should be sent from the client to the server
const { challenge, JWT } = addrAuth.generateChallenge(userAddress);

// Verify a challenge (Returns persistent JWT and address)
const { JWT: authToken, address } = addrAuth.verifyChallenge(
  JWT,
  signature,
  publicKey,
  address,
  included // included is an optional object that can be used to store additional data in the JWT
);

// Verify a JWT (Returns JWT payload if valid)
const payload = addrAuth.verifyJWT(authToken);

For more detailed examples, including server-side implementation and frontend integration, please refer to the examples folder in the repository.

API Reference

`AddrAuth` Class

Constructor

new AddrAuth({
  verifySignature: Function,
  JWTSecret: string,
  challengeExpiresIn?: string,
  JWTExpiresIn?: string
})

Methods

generateChallenge(address: string): { challenge: string, JWT: string }
verifyChallenge(token: string, signature: string, publicKey: string, address: string, included?: Object): { JWT: string, address: string }
verifyJWT(token: string): Object

Contributing

Contributions to AddrAuth are welcome! Here's how you can contribute:

Fork the repository
Create a new branch for your feature or bug fix
Make your changes and commit them with clear, descriptive messages
Push your changes to your fork
Submit a pull request to the main repository

License

AddrAuth is open-source software licensed under the MIT license.

Support

If you encounter any issues or have questions, please open an issue on GitHub.

ducksquaddd/AddrAuth