@mesob/auth-hono 0.0.8 → 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# @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-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](./docs/routes.md) for complete API reference.
+
+## Requirements
+
+- Node.js 22+
+- PostgreSQL database
+- pnpm (recommended) or npm
+
+## License
+
+MIT

package/dist/index-CScADcDn.d.ts

@@ -0,0 +1,137 @@
+import * as hono from 'hono';
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { D as Database } from './index-ULpI-i0z.js';
+
+type AuthEnv = {
+    Variables: {
+        config: AuthConfig;
+        database: Database;
+        tenantId: string;
+        userId?: string;
+        user?: User;
+        session?: Session;
+    };
+};
+
+declare const createAuthRoutes: ({ config, database, }: CreateAuthRoutesOptions) => OpenAPIHono<AuthEnv, {}, "/">;
+
+type UserRole = {
+    id: string;
+    roleId: string;
+    code: string;
+    name: unknown;
+    description: unknown;
+};
+type User = {
+    id: string;
+    tenantId: string;
+    fullName: string;
+    email: string | null;
+    phone: string | null;
+    handle: string;
+    image: string | null;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    lastSignInAt: string | null;
+    bannedUntil?: string | null;
+    loginAttempt?: number;
+    userRoles?: UserRole[];
+};
+type SessionMeta = {
+    action?: string;
+    rememberMe?: boolean;
+};
+type Session = {
+    id: string;
+    tenantId: string;
+    userId: string;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt?: string;
+    userAgent: string | null;
+    ip: string | null;
+    meta?: SessionMeta | null;
+};
+type SendVerificationOTPParams = {
+    email?: string;
+    phone?: string;
+    code: string;
+    hash: string;
+    type: string;
+};
+type VerificationConfig = {
+    enabled: boolean;
+    required: boolean;
+    otpLength: number;
+    expiresIn: string;
+    maxAttempts: number;
+    resendInterval?: string;
+    sendVerificationOTP?: (params: SendVerificationOTPParams) => Promise<void> | void;
+};
+type EmailConfig = VerificationConfig;
+type PhoneConfig = VerificationConfig;
+type SessionConfig = {
+    /** Default session duration (e.g., '7d', '30d'). Default: '7d' */
+    expiresIn: string;
+    /** Session duration when "remember me" is checked (e.g., '30d'). Default: '30d' */
+    rememberMeExpiresIn: string;
+    /** Session duration when "remember me" is unchecked (e.g., '1h'). Default: '1h' */
+    shortSessionExpiresIn: string;
+    /** Refresh session if remaining time is less than this (e.g., '1d'). Default: '1d' */
+    updateAge: string;
+    /** Refresh short session if remaining time is less than this (e.g., '15m'). Default: '15m' */
+    shortSessionUpdateAge: string;
+    /** Maximum concurrent sessions per user */
+    maxPerUser?: number;
+};
+type SecurityConfig = {
+    maxLoginAttempts: number;
+    lockoutDuration: string;
+};
+type TenantConfig = {
+    enabled?: boolean;
+    tenantId?: string;
+    tenantDomains?: string[];
+};
+type DocsConfig = {
+    enabled?: boolean;
+    title?: string;
+    version?: string;
+    theme?: 'default' | 'moon' | 'purple' | 'saturn' | 'bluePlanet' | 'kepler' | 'mars';
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+};
+type CookieConfig = {
+    prefix?: string;
+};
+type AuthConfig = {
+    connectionString: string;
+    secret: string;
+    basePath?: string;
+    tenant?: TenantConfig;
+    docs?: DocsConfig;
+    cookie?: CookieConfig;
+    session: SessionConfig;
+    email: EmailConfig;
+    phone: PhoneConfig;
+    security?: SecurityConfig;
+};
+
+type CreateAuthRoutesOptions = {
+    config: AuthConfig;
+    database: Database;
+};
+type MesobAuth = {
+    routes: ReturnType<typeof createAuthRoutes>;
+    getSession: (c: hono.Context) => Promise<{
+        session: Session | null;
+        user: User | null;
+        sessionToken: string | null;
+    }>;
+    tenantMiddleware: hono.MiddlewareHandler;
+    sessionMiddleware: hono.MiddlewareHandler;
+};
+
+export type { AuthConfig as A, MesobAuth as M, SendVerificationOTPParams as S, User as U, Session as a, SessionConfig as b };