binoauth 0.0.11 → 0.0.12

package/README.md

@@ -1,6 +1,16 @@
-# binoauth
+# BinoAuth Core SDK
 
-A simplified Node.js SDK for BinoAuth authentication that provides OAuth2-compatible tokens without the complexity of traditional OAuth2 flows.
+A comprehensive TypeScript SDK for BinoAuth authentication platform with support for multiple authentication flows, user management, and admin operations.
+
+## Features
+
+- **Multiple Authentication Methods**: Password, Magic Link, OTP, OAuth 2.0, Social Login
+- **Multi-Factor Authentication**: TOTP, SMS, Email verification
+- **Admin Operations**: User management, tenant management, API key management
+- **Secure Token Storage**: Encrypted token storage with multiple strategies
+- **Cross-Platform**: Works in browsers, Node.js, React Native
+- **Type Safe**: Full TypeScript support with comprehensive types
+- **OAuth 2.0 Complete**: Authorization Code, Device Code, Client Credentials, and Refresh Token flows
 
 ## Installation
 
@@ -14,274 +24,458 @@ bun add binoauth
 
 ## Quick Start
 
+### Basic Authentication
+
 ```typescript
-import BinoAuth from "binoauth";
+import { BinoAuthClient } from 'binoauth';
 
-const auth = new BinoAuth({
-  apiKey: "ak_live_your_api_key",
-  tenant: "your-tenant-id",
+const auth = new BinoAuthClient({
+  issuer: 'https://auth.binoauth.com',
+  clientId: 'your_client_id',
+  redirectUri: 'https://yourapp.com/callback'
 });
 
-// Email OTP
-const resp = await auth.sendEmailOTP("user@example.com");
-if (resp.ok) {
-  console.log("OTP sent successfully");
+// Password authentication
+const result = await auth.loginWithPassword('user@example.com', 'password123');
+if (result.success) {
+  console.log('Welcome,', result.user.name);
 }
 
-// Login with password
-const loginResp = await auth.login("password", {
-  email: "user@example.com",
-  password: "password123",
+// Magic link authentication
+await auth.magicLink.sendMagicLink({
+  email: 'user@example.com',
+  returnTo: 'https://yourapp.com/dashboard'
 });
 
-if (loginResp.ok) {
-  console.log("Login successful:", loginResp.data);
-}
+// Check authentication status
+const isLoggedIn = await auth.isAuthenticated();
 ```
 
-## Features
-
-### Authentication Methods
+### OAuth 2.0 Flow
 
-- **Email OTP**: Send and verify email-based one-time passwords
-- **Phone OTP**: Send and verify SMS-based one-time passwords
-- **Password Login**: Traditional email/password authentication
-- **Magic Links**: Passwordless email-based authentication
-- **Device Code Flow**: For CLI applications and IoT devices
+```typescript
+// Authorization Code Flow
+const authUrl = await auth.oauth.getAuthorizationUrl();
+window.location.href = authUrl;
+
+// Handle callback
+const urlParams = new URLSearchParams(window.location.search);
+await auth.oauth.handleCallback(
+  urlParams.get('code')!,
+  urlParams.get('state')!
+);
+
+// Device Code Flow (for devices without browsers)
+const deviceAuth = await auth.oauth.requestDeviceCode();
+console.log(`Visit: ${deviceAuth.verification_uri}`);
+console.log(`Enter code: ${deviceAuth.user_code}`);
+
+// Poll for authorization
+await auth.oauth.pollForToken(deviceAuth.device_code);
+```
 
-### Token Management
+## Authentication Flows
 
-- **OAuth2 Compatible**: All tokens work with existing OAuth2 resource servers
-- **Refresh Tokens**: Automatic token refresh capabilities
-- **Session Management**: Secure logout and session invalidation
+### 1. Password Authentication
 
-### User Management
+```typescript
+import { PasswordFlow } from 'binoauth';
 
-- **Profile Access**: Get and update user profiles
-- **User Administration**: Create, read, update, delete users (admin API)
+const passwordFlow = new PasswordFlow(config);
 
-## API Reference
+// Login
+const result = await passwordFlow.login('user@example.com', 'password123');
 
-### Constructor
+// Register new user
+await passwordFlow.register({
+  email: 'newuser@example.com',
+  password: 'securepassword',
+  name: 'John Doe',
+  acceptTerms: true
+});
 
-```typescript
-const auth = new BinoAuth({
-  apiKey: string;     // Your BinoAuth API key
-  tenant: string;     // Your tenant ID
-  baseUrl?: string;   // Optional: Custom API base URL
+// Login with credentials object
+await passwordFlow.loginWithCredentials({
+  email: 'user@example.com',
+  password: 'password123',
+  rememberMe: true
 });
 ```
 
-### Authentication Methods
-
-#### `sendEmailOTP(email: string)`
-
-Send an OTP code to the user's email address.
+### 2. Magic Link Authentication
 
 ```typescript
-const result = await auth.sendEmailOTP("user@example.com");
-```
+import { MagicLinkFlow } from 'binoauth';
 
-#### `sendPhoneOTP(phone: string)`
+const magicLinkFlow = new MagicLinkFlow(config);
 
-Send an OTP code to the user's phone number.
+// Send magic link
+await magicLinkFlow.sendMagicLink({
+  email: 'user@example.com',
+  returnTo: 'https://yourapp.com/dashboard'
+});
 
-```typescript
-const result = await auth.sendPhoneOTP("+1234567890");
-```
+// Verify magic link token
+const result = await magicLinkFlow.verifyMagicLink(token);
 
-#### `sendMagicLink(email: string)`
+// Verify magic link code
+const result = await magicLinkFlow.verifyMagicLinkCode(code);
+```
 
-Send a magic link to the user's email address.
+### 3. OTP Authentication
 
 ```typescript
-const result = await auth.sendMagicLink("user@example.com");
-```
-
-#### `login(type: 'password' | 'otp', credentials: LoginCredentials)`
+import { OTPFlow } from 'binoauth';
 
-Authenticate a user with different methods.
+const otpFlow = new OTPFlow(config);
 
-```typescript
-// Password login
-const result = await auth.login("password", {
-  email: "user@example.com",
-  password: "password123",
+// Send phone OTP
+await otpFlow.sendPhoneOTP({
+  phoneNumber: '+1234567890'
 });
 
-// OTP login
-const result = await auth.login("otp", {
-  otp: "123456",
-  phone: "+1234567890", // Optional: specify if phone OTP
+// Verify phone OTP
+const result = await otpFlow.verifyPhoneOTP({
+  phoneNumber: '+1234567890',
+  code: '123456'
 });
 ```
 
-### Password Reset
-
-#### `sendResetPasswordEmailOTP(email: string)`
-
-Send a password reset OTP to email.
+### 4. Multi-Factor Authentication
 
 ```typescript
-const result = await auth.sendResetPasswordEmailOTP("user@example.com");
-```
+import { MFAFlow } from 'binoauth';
 
-#### `sendResetPasswordPhoneOTP(phone: string)`
+const mfaFlow = new MFAFlow(config);
 
-Send a password reset OTP to phone.
+// Send MFA challenge
+await mfaFlow.sendMFAChallenge({
+  challengeId: 'challenge_123',
+  method: 'sms'
+});
 
-```typescript
-const result = await auth.sendResetPasswordPhoneOTP("+1234567890");
+// Verify MFA challenge
+const result = await mfaFlow.verifyMFAChallenge({
+  challengeId: 'challenge_123',
+  code: '123456',
+  method: 'sms'
+});
 ```
 
-#### `resetPassword(params: ResetPasswordParams)`
-
-Reset user password with OTP verification.
+### 5. Social Authentication
 
 ```typescript
-const result = await auth.resetPassword({
-  otp: "123456",
-  newPassword: "newpassword123",
-  repeatNewPassword: "newpassword123",
-});
-```
+import { SocialFlow } from 'binoauth';
 
-### Token Management
+const socialFlow = new SocialFlow(config);
 
-#### `refreshToken(refreshToken: string)`
+// Get authentication URL for provider
+const googleUrl = await socialFlow.getAuthUrl('google');
+window.location.href = googleUrl;
 
-Refresh an access token using a refresh token.
+// Handle callback
+const result = await socialFlow.handleCallback('google', code, state);
 
-```typescript
-const result = await auth.refreshToken("refresh_token_here");
+// Get available providers
+const providers = await socialFlow.getAvailableProviders();
 ```
 
-#### `logout(accessToken?: string)`
+## OAuth 2.0 Flows
 
-Logout and invalidate session.
+### Authorization Code Flow
 
 ```typescript
-const result = await auth.logout("access_token_here");
-```
+import { BinoAuthOAuth } from 'binoauth';
 
-### User Profile
+const oauth = new BinoAuthOAuth(config, storageConfig);
 
-#### `getProfile()`
+// Get authorization URL
+const authUrl = await oauth.getAuthorizationUrl();
 
-Get the current user's profile information.
-
-```typescript
-const result = await auth.getProfile();
+// Handle callback
+const result = await oauth.handleCallback(code, state);
 ```
 
 ### Device Code Flow
 
-#### `requestDeviceCode()`
+```typescript
+// Request device code
+const deviceAuth = await oauth.requestDeviceCode();
+
+// Poll for token
+await oauth.pollForToken(deviceAuth.device_code);
+```
 
-Request a device code for CLI/IoT authentication.
+### Client Credentials Flow
 
 ```typescript
-const result = await auth.requestDeviceCode();
-console.log(`Visit: ${result.data.verification_uri}`);
-console.log(`Code: ${result.data.user_code}`);
+// Get client credentials token
+const tokenSet = await oauth.getClientCredentialsToken();
 ```
 
-#### `pollDeviceToken(deviceCode: string)`
-
-Poll for device authorization completion.
+### Refresh Token Flow
 
 ```typescript
-const result = await auth.pollDeviceToken("device_code_here");
+// Refresh access token
+const newTokenSet = await oauth.refreshAccessToken();
 ```
 
-### User Management (Admin API)
+## Admin Operations
 
-#### `getUser(userId: string)`
+```typescript
+import { AdminClient } from 'binoauth';
 
-Get user information by ID.
+const adminClient = new AdminClient({
+  baseUrl: 'https://auth.binoauth.com',
+  apiKey: 'admin_api_key',
+  tenantId: 'your_tenant_id'
+});
 
-```typescript
-const result = await auth.getUser("user_id_here");
+// User management
+const users = await adminClient.getUsers();
+const user = await adminClient.getUser('user_id');
+
+// Tenant management
+const tenants = await adminClient.listTenants();
+const tenant = await adminClient.getTenant('tenant_id');
+await adminClient.createTenant(tenantData);
+await adminClient.updateTenant('tenant_id', updateData);
+
+// API key management
+const apiKeys = await adminClient.listApiKeys();
+const apiKey = await adminClient.createApiKey(apiKeyData);
+await adminClient.revokeApiKey('key_id');
+
+// OAuth client management
+const clients = await adminClient.listClients();
+const client = await adminClient.createClient(clientData);
+const clientInfo = await adminClient.getClient('client_id');
+
+// Provider management
+const providers = await adminClient.listProviders();
+const provider = await adminClient.createProvider(providerData);
+
+// Statistics and health
+const stats = await adminClient.getStats();
+const health = await adminClient.healthCheck();
+
+// Admin authentication
+const adminAuth = await adminClient.adminLogin('admin@example.com', 'password');
+const currentAdmin = await adminClient.getCurrentAdmin();
+await adminClient.adminLogout();
 ```
 
-#### `getUsers(params?: { page?: number; limit?: number })`
+## Configuration
 
-Get paginated list of users.
+### Basic Configuration
 
 ```typescript
-const result = await auth.getUsers({ page: 1, limit: 10 });
+const config = {
+  issuer: 'https://auth.binoauth.com',
+  clientId: 'your_client_id',
+  redirectUri: 'https://yourapp.com/callback'
+};
 ```
 
-#### `createUser(userData: any)`
-
-Create a new user (not implemented in current admin SDK).
+### Advanced Configuration
 
-#### `updateUser(userId: string, userData: any)`
-
-Update user information (not implemented in current admin SDK).
+```typescript
+const config = {
+  issuer: 'https://auth.binoauth.com',
+  clientId: 'your_client_id',
+  clientSecret: 'your_client_secret', // For server-side apps
+  redirectUri: 'https://yourapp.com/callback',
+  scope: 'openid profile email',
+  
+  // OAuth endpoints (auto-discovered by default)
+  authorizeEndpoint: 'https://auth.binoauth.com/oauth/authorize',
+  tokenEndpoint: 'https://auth.binoauth.com/oauth/token',
+  userinfoEndpoint: 'https://auth.binoauth.com/oauth/userinfo',
+  
+  // Additional config
+  tenant: 'your_tenant_id',
+  apiKey: 'your_api_key'
+};
+```
 
-#### `deleteUser(userId: string)`
+### Token Storage Configuration
 
-Delete a user (not implemented in current admin SDK).
+```typescript
+import { LocalStorageTokenStorage, SessionStorageTokenStorage, InMemoryTokenStorage } from 'binoauth';
 
-## Response Format
+// Use localStorage (default for browsers)
+const storage = new LocalStorageTokenStorage({
+  clientId: 'your_client_id',
+  encryptionKey: 'your-encryption-key'
+});
 
-All methods return a `BinoAuthResponse` object:
+// Use sessionStorage (cleared when browser closes)
+const sessionStorage = new SessionStorageTokenStorage({
+  clientId: 'your_client_id',
+  encryptionKey: 'your-encryption-key'
+});
 
-```typescript
-interface BinoAuthResponse<T = any> {
-  ok: boolean; // Success indicator
-  data?: T; // Response data (if successful)
-  error?: string; // Error message (if failed)
-  error_description?: string; // Detailed error description (if failed)
-}
+// Use in-memory storage (for server-side or testing)
+const memoryStorage = new InMemoryTokenStorage({
+  clientId: 'your_client_id',
+  encryptionKey: 'your-encryption-key'
+});
 ```
 
 ## Error Handling
 
 ```typescript
-const result = await auth.login("password", {
-  email: "user@example.com",
-  password: "wrong_password",
-});
-
-if (!result.ok) {
-  console.error("Login failed:", result.error);
-  console.error("Details:", result.error_description);
-} else {
-  console.log("Login successful:", result.data);
+import { AuthError, AuthErrorCode } from 'binoauth';
+
+try {
+  await auth.loginWithPassword('user@example.com', 'wrong_password');
+} catch (error) {
+  if (error instanceof AuthError) {
+    switch (error.code) {
+      case AuthErrorCode.INVALID_CREDENTIALS:
+        console.log('Invalid email or password');
+        break;
+      case AuthErrorCode.MFA_REQUIRED:
+        console.log('MFA required:', error.details);
+        break;
+      case AuthErrorCode.ACCOUNT_LOCKED:
+        console.log('Account is locked');
+        break;
+      case AuthErrorCode.ACCOUNT_NOT_FOUND:
+        console.log('Account not found');
+        break;
+      case AuthErrorCode.NETWORK_ERROR:
+        console.log('Network connection error');
+        break;
+      default:
+        console.log('Auth error:', error.message);
+    }
+  }
 }
 ```
 
-## OAuth2 Compatibility
+## TypeScript Support
 
-All tokens generated by this SDK are OAuth2-compatible JWT tokens that can be used with:
+The SDK is built with TypeScript and provides comprehensive type definitions:
 
-- Resource servers expecting OAuth2 Bearer tokens
-- Existing OAuth2 middleware and libraries
-- Standard Authorization headers: `Authorization: Bearer <token>`
+```typescript
+import type {
+  AuthConfig,
+  AuthResult,
+  User,
+  LoginRequest,
+  SignupRequest,
+  TokenSet,
+  MFAChallenge,
+  AdminConfig
+} from 'binoauth';
+
+// All methods are fully typed
+const result: AuthResult = await auth.loginWithPassword(email, password);
+const user: User = result.user;
+```
 
-## Development
+## Available Error Codes
+
+- `INVALID_CREDENTIALS` - Invalid email or password
+- `INVALID_EMAIL` - Invalid email format
+- `INVALID_PASSWORD` - Invalid password
+- `INVALID_OTP` - Invalid OTP code
+- `EXPIRED_OTP` - OTP code has expired
+- `INVALID_TOKEN` - Invalid or expired token
+- `ACCOUNT_NOT_FOUND` - User account not found
+- `ACCOUNT_LOCKED` - Account is locked
+- `ACCOUNT_DISABLED` - Account is disabled
+- `EMAIL_NOT_VERIFIED` - Email verification required
+- `MFA_REQUIRED` - Multi-factor authentication required
+- `TOO_MANY_ATTEMPTS` - Too many failed attempts
+- `RATE_LIMITED` - Rate limit exceeded
+- `EMAIL_ALREADY_EXISTS` - Email already registered
+- `WEAK_PASSWORD` - Password is too weak
+- `NETWORK_ERROR` - Network connection error
+- `SERVER_ERROR` - Server error
+- `INVALID_CONFIG` - Invalid configuration
+- `OAUTH_ERROR` - OAuth-specific error
+
+## Examples
+
+### React Integration
 
-```bash
-# Install dependencies
-bun install
+```typescript
+import { BinoAuthClient } from 'binoauth';
+import { useEffect, useState } from 'react';
+
+function App() {
+  const [auth] = useState(() => new BinoAuthClient(config));
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    auth.isAuthenticated().then(isAuth => {
+      if (isAuth) {
+        auth.getUser().then(setUser);
+      }
+    });
+  }, []);
+
+  const handleLogin = async (email, password) => {
+    try {
+      const result = await auth.loginWithPassword(email, password);
+      if (result.success) {
+        setUser(result.user);
+      }
+    } catch (error) {
+      console.error('Login failed:', error.message);
+    }
+  };
+
+  return (
+    <div>
+      {user ? (
+        <div>Welcome, {user.name}!</div>
+      ) : (
+        <LoginForm onLogin={handleLogin} />
+      )}
+    </div>
+  );
+}
+```
+
+### Node.js Server
 
-# Build the package
-bun run build
+```typescript
+import { BinoAuthClient } from 'binoauth';
+import express from 'express';
+
+const app = express();
+const auth = new BinoAuthClient({
+  issuer: 'https://auth.binoauth.com',
+  clientId: process.env.BINOAUTH_CLIENT_ID,
+  clientSecret: process.env.BINOAUTH_CLIENT_SECRET,
+  redirectUri: 'https://yourapp.com/callback'
+});
 
-# Watch mode for development
-bun run dev
+app.get('/auth/callback', async (req, res) => {
+  try {
+    const result = await auth.oauth.handleCallback(
+      req.query.code,
+      req.query.state
+    );
+    
+    // Store tokens and redirect
+    req.session.tokens = result.tokens;
+    res.redirect('/dashboard');
+  } catch (error) {
+    res.status(401).send('Authentication failed');
+  }
+});
 ```
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details.
 
 ## Support
 
-For issues and questions:
-
-- GitHub Issues: [binoauth/binoauth](https://github.com/binoauth/binoauth/issues)
-- Email: support@binoauth.com
-- Documentation: [docs.binoauth.com](https://docs.binoauth.com)
+- **Documentation**: [https://docs.binoauth.com](https://docs.binoauth.com)
+- **Issues**: [GitHub Issues](https://github.com/binoauth/binoauth/issues)
+- **Email**: support@binoauth.com