# @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

```bash
pnpm add @mesob/auth-hono
```

### Basic Setup

```typescript
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: 'noreply@example.com',
    },
  },
  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

```typescript
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

```typescript
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:

```typescript
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: 'user@example.com', password: 'password' },
});
```

## Documentation

- [Installation Guide](./docs/installation.md) - Step-by-step setup
- [Configuration](./docs/configuration.md) - All configuration options
- [Routes Reference](./docs/routes.md) - Complete API documentation
- [IAM System](./docs/iam.md) - IAM system overview
- [RPC Client](./docs/rpc-client.md) - 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-account` - Check if account 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](./docs/routes.md) for complete API reference.

## Requirements

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

## License

MIT
