@mesob/auth-hono

Complete Identity and Access Management (IAM) system for Hono applications with type-safe APIs, OpenAPI documentation, and RPC client support.

Features

• 🔐 Complete Authentication: Sign up, sign in, sign out with email/phone
• 👤 User Management: Profile updates, email/phone changes
• 🔑 Password Management: Forgot, reset, change, verify
• ✉️ Email Verification: Request and confirm email verification
• 📱 Phone Verification: OTP-based phone verification
• 🏢 Multi-Tenant Support: Tenant isolation with configurable setup
• 👥 IAM System: Users, tenants, domains, roles, permissions management
• 📚 OpenAPI Docs: Interactive API documentation with Scalar UI
• 🔷 Type-Safe RPC: Generate type-safe clients for frontend
• 🛡️ Type Safety: Full TypeScript support with Hono typed context

Quick Start

Installation

pnpm add @mesob/auth-hono

Basic Setup

import { mesobAuth } from '@mesob/auth-hono';

const auth = mesobAuth({
  connectionString: process.env.DATABASE_URL!,
  secret: process.env.AUTH_SECRET!,
  title: 'My App IAM API',
  docsTheme: 'saturn',
  enableTenant: true,
  session: {
    expiresIn: '30d',
    maxPerUser: 5,
  },
  email: {
    enabled: true,
    verificationRequired: true,
    verificationExpiresIn: '1h',
    resend: {
      apiKey: process.env.RESEND_API_KEY!,
      from: '[email protected]',
    },
  },
  phone: {
    enabled: true,
    verificationRequired: true,
    otpLength: 6,
    otpExpiresIn: '10m',
    smsConfig: {
      baseUrl: process.env.SMS_BASE_URL!,
      identifierId: process.env.SMS_IDENTIFIER_ID!,
      senderName: 'MyApp',
      apiKey: process.env.SMS_API_KEY!,
    },
  },
});

Integration

import { Hono } from 'hono';

const app = new Hono();

// Mount auth routes
app.route('/api/auth', auth.app);

// Or use as standalone handler
app.all('/api/auth/*', (c) => {
  return auth.handler.fetch(c.req.raw);
});

Access Session

app.use('*', async (c, next) => {
  const session = await auth.getSession(c);
  if (session.user) {
    c.set('user', session.user);
  }
  await next();
});

Access Documentation

After mounting routes, access:

• /api/auth/docs - Interactive Scalar UI
• /api/auth/openapi.json - OpenAPI specification

Type-Safe RPC Client

Generate type-safe clients for your frontend:

import { hc } from 'hono/client';
import type { MesobAuthApp } from '@mesob/auth-hono';

const authClient = hc<MesobAuthApp>('http://localhost:3000/api/auth', {
  init: {
    credentials: 'include', // Required for cookies
  },
});

// All API calls are fully type-safe
const user = await authClient.me.$get();
const result = await authClient['sign-in'].$post({
  json: { identifier: '[email protected]', password: 'password' },
});

Documentation

• Installation Guide - Step-by-step setup
• Configuration - All configuration options
• Routes Reference - Complete API documentation
• IAM System - IAM system overview
• RPC Client - Frontend client usage

API Routes

Authentication

• POST /sign-up - Sign up with email/phone
• POST /sign-in - Sign in
• POST /sign-out - Sign out
• POST /check-user - Check if user exists

Profile

• GET /me - Get current user
• GET /session - Get current session
• PUT /update - Update profile
• PUT /update-email - Request email change
• PUT /update-phone - Request phone change

Password

• POST /password/forgot - Request password reset
• POST /password/reset - Reset password
• POST /password/verify - Verify password
• PUT /password/change - Change password

Email Verification

• POST /email/verification/request - Request verification code
• POST /email/verification/confirm - Confirm verification

Phone Verification

• POST /phone/verification/request - Request OTP
• POST /phone/verification/confirm - Confirm OTP

IAM Management

• GET /users - List users
• GET /users/{id} - Get user
• More IAM routes coming soon...

See routes.md for complete API reference.

Requirements

• Node.js 22+
• PostgreSQL database
• pnpm (recommended) or npm

License

MIT