@smartforge/auth-core

SmartForge Authentication Engine - SIWE, JWT, and role-based permissions.

Installation

npm install @smartforge/auth-core
# or
pnpm add @smartforge/auth-core

Usage

Basic Setup

import { AuthService } from "@smartforge/auth-core";

const authService = new AuthService({
  jwt: {
    secret: process.env.JWT_SECRET!,
    expiresIn: "7d",
  },
  domain: "https://yourdomain.com",
});

Sign In with Wallet (SIWE)

import { generateSIWEMessage, verifySIWE } from "@smartforge/auth-core";

// Generate SIWE message
const message = generateSIWEMessage({
  domain: "yourdomain.com",
  address: "0x...",
  statement: "Sign in to SmartForge",
  uri: "https://yourdomain.com",
  version: "1",
  chainId: 8453,
  nonce: "random-nonce",
  issuedAt: new Date(),
});

// Verify SIWE message and signature
const result = verifySIWE(message, signature);
if (result.valid) {
  console.log("Verified address:", result.parsed?.address);
}

JWT Token Management

import {
  issueToken,
  verifyToken,
  hasRole,
  UserRole,
} from "@smartforge/auth-core";

// Issue a JWT token
const token = issueToken(
  {
    userId: "user-id",
    walletAddress: "0x...",
    role: UserRole.ADMIN,
  },
  {
    secret: process.env.JWT_SECRET!,
    expiresIn: "7d",
  }
);

// Verify token
const verification = verifyToken(token, {
  secret: process.env.JWT_SECRET!,
  expiresIn: "7d",
});

// Check role permissions
const canWrite = hasRole(UserRole.WRITER, UserRole.READER); // true
const canAdmin = hasRole(UserRole.READER, UserRole.ADMIN); // false

Complete Authentication Flow

const result = await authService.signInWithWallet(
  message,
  signature,
  async (address) => {
    // Get user by address from database
    return await db.getUserByAddress(address);
  },
  async (address) => {
    // Create new user if doesn't exist
    return await db.createUser({ address });
  }
);

if (result.success) {
  console.log("Token:", result.token);
  console.log("User:", result.user);
}

API

AuthService

Main authentication service class.

Methods:

• signInWithWallet() - Authenticate with SIWE
• signInWithEmail() - Email authentication (stub)
• verifyToken() - Verify JWT token
• checkPermission() - Check role permissions
• generateSignInMessage() - Generate SIWE message

UserRole

Enum of user roles:

• UserRole.ADMIN - Full access
• UserRole.WRITER - Can create/modify
• UserRole.READER - Read-only access

SIWE Functions

• generateSIWEMessage() - Generate SIWE message
• parseSIWEMessage() - Parse SIWE message string
• verifySIWE() - Verify SIWE message and signature

JWT Functions

• issueToken() - Create JWT token
• verifyToken() - Verify JWT token
• decodeToken() - Decode token without verification
• hasRole() - Check role hierarchy

License

ISC