@warriorteam/redai-zalo-sdk 1.2.0 → 1.4.0

package/docs/AUTHENTICATION.md

@@ -0,0 +1,709 @@
+# RedAI Zalo SDK - Authentication Guide
+
+## Tổng quan
+
+RedAI Zalo SDK hỗ trợ đầy đủ các authentication flows của Zalo, bao gồm:
+
+- **Official Account (OA) Authentication** - Để truy cập OA APIs
+- **Social API Authentication** - Để truy cập thông tin user social
+- **Token Management** - Refresh và validate tokens
+- **PKCE Support** - Security enhancement cho Social API
+
+---
+
+## Official Account Authentication
+
+### 1. Tạo Authorization URL
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-oa-app-id",
+  appSecret: "your-oa-app-secret"
+});
+
+// Tạo authorization URL cho OA
+const authUrl = zalo.createOAAuthUrl(
+  "https://your-app.com/auth/callback",  // redirect_uri
+  "optional-state-parameter"             // state (tùy chọn)
+);
+
+console.log("Redirect user to:", authUrl);
+// Output: https://oauth.zaloapp.com/v4/oa/permission?app_id=xxx&redirect_uri=xxx&state=xxx
+```
+
+### 2. Xử lý Callback và Lấy Access Token
+
+```typescript
+// Trong route callback của bạn
+app.get('/auth/callback', async (req, res) => {
+  const { code, state } = req.query;
+  
+  try {
+    // Lấy access token từ authorization code
+    const tokenResponse = await zalo.getOAAccessToken(
+      code as string,
+      "https://your-app.com/auth/callback"
+    );
+    
+    console.log("OA Access Token:", tokenResponse.access_token);
+    console.log("Refresh Token:", tokenResponse.refresh_token);
+    console.log("Expires In:", tokenResponse.expires_in); // seconds
+    
+    // Lưu tokens vào database/session
+    await saveTokens(tokenResponse);
+    
+    res.redirect('/dashboard');
+  } catch (error) {
+    console.error("Auth error:", error);
+    res.redirect('/auth/error');
+  }
+});
+```
+
+### 3. Token Response Structure
+
+```typescript
+interface AccessToken {
+  access_token: string;      // Token để gọi API
+  refresh_token: string;     // Token để refresh
+  expires_in: number;        // Thời gian sống (seconds)
+  token_type: "Bearer";      // Loại token
+  scope: string;             // Quyền được cấp
+}
+```
+
+### 4. Sử dụng Access Token
+
+```typescript
+// Lấy thông tin OA
+const oaInfo = await zalo.getOAInfo(tokenResponse.access_token);
+console.log("OA Name:", oaInfo.name);
+console.log("Followers:", oaInfo.num_follower);
+
+// Gửi tin nhắn consultation
+await zalo.sendConsultationText(
+  tokenResponse.access_token,
+  "user-zalo-id",
+  "Xin chào! Cảm ơn bạn đã quan tâm đến dịch vụ của chúng tôi."
+);
+```
+
+---
+
+## Social API Authentication
+
+### 1. Tạo Authorization URL (Basic)
+
+```typescript
+const zalo = new ZaloSDK({
+  appId: "your-social-app-id",
+  appSecret: "your-social-app-secret"
+});
+
+// Tạo authorization URL cho Social API
+const authUrl = zalo.createSocialAuthUrl(
+  "https://your-app.com/social/callback",
+  "optional-state"
+);
+
+console.log("Redirect user to:", authUrl);
+```
+
+### 2. Tạo Authorization URL với PKCE (Khuyến nghị)
+
+```typescript
+// Tạo PKCE parameters cho bảo mật cao hơn
+const pkce = zalo.generatePKCE();
+console.log("Code Verifier:", pkce.code_verifier);
+console.log("Code Challenge:", pkce.code_challenge);
+
+// Lưu code_verifier vào session/state
+req.session.codeVerifier = pkce.code_verifier;
+
+const authUrl = zalo.createSocialAuthUrl(
+  "https://your-app.com/social/callback",
+  "social-login"
+);
+```
+
+### 3. PKCE Generation
+
+```typescript
+interface PKCEConfig {
+  code_verifier: string;     // Random string 43-128 chars
+  code_challenge: string;    // base64url(sha256(code_verifier))
+  code_challenge_method: "S256";
+}
+
+// SDK tự động tạo PKCE theo chuẩn RFC 7636
+const pkce = zalo.generatePKCE();
+```
+
+### 4. Xử lý Social Callback
+
+```typescript
+app.get('/social/callback', async (req, res) => {
+  const { code, state } = req.query;
+  const codeVerifier = req.session.codeVerifier; // Lấy từ session
+  
+  try {
+    const tokenResponse = await zalo.getSocialAccessToken(
+      code as string,
+      "https://your-app.com/social/callback",
+      codeVerifier // Bắt buộc nếu dùng PKCE
+    );
+    
+    // Lấy thông tin user
+    const userInfo = await zalo.getSocialUserInfo(
+      tokenResponse.access_token,
+      "id,name,picture,birthday,gender" // fields cần lấy
+    );
+    
+    console.log("User Info:", userInfo);
+    
+    // Lưu vào database
+    await createOrUpdateUser(userInfo, tokenResponse);
+    
+    res.redirect('/profile');
+  } catch (error) {
+    console.error("Social auth error:", error);
+    res.redirect('/login?error=auth_failed');
+  }
+});
+```
+
+### 5. Social User Info Response
+
+```typescript
+interface SocialUserInfo {
+  id: string;                    // Zalo user ID
+  name: string;                  // Tên hiển thị
+  picture?: {
+    data: {
+      url: string;              // Avatar URL
+    }
+  };
+  birthday?: string;             // Ngày sinh (YYYY-MM-DD)
+  gender?: number;               // 1: Nam, 2: Nữ
+  locale?: string;               // Locale
+  // Các fields khác tùy theo quyền được cấp
+}
+```
+
+---
+
+## Token Management
+
+### 1. Refresh OA Access Token
+
+```typescript
+async function refreshOAToken(refreshToken: string): Promise<AccessToken> {
+  try {
+    const newTokens = await zalo.refreshOAAccessToken(refreshToken);
+    
+    // Lưu tokens mới
+    await updateTokens(newTokens);
+    
+    return newTokens;
+  } catch (error) {
+    console.error("Failed to refresh OA token:", error);
+    // Redirect to re-authentication
+    throw new Error("Re-authentication required");
+  }
+}
+```
+
+### 2. Refresh Social Access Token
+
+```typescript
+async function refreshSocialToken(refreshToken: string): Promise<AccessToken> {
+  try {
+    const newTokens = await zalo.refreshSocialAccessToken(refreshToken);
+    return newTokens;
+  } catch (error) {
+    console.error("Failed to refresh social token:", error);
+    throw error;
+  }
+}
+```
+
+### 3. Auto Token Refresh Middleware
+
+```typescript
+// Express middleware để auto refresh tokens
+export const autoRefreshToken = async (req: Request, res: Response, next: NextFunction) => {
+  const { accessToken, refreshToken, expiresAt } = req.user;
+  
+  // Kiểm tra token sắp hết hạn (trước 5 phút)
+  const willExpireSoon = Date.now() > (expiresAt - 5 * 60 * 1000);
+  
+  if (willExpireSoon && refreshToken) {
+    try {
+      const tokenType = req.path.includes('/oa/') ? 'oa' : 'social';
+      
+      const newTokens = tokenType === 'oa' 
+        ? await zalo.refreshOAAccessToken(refreshToken)
+        : await zalo.refreshSocialAccessToken(refreshToken);
+      
+      // Cập nhật user với tokens mới
+      req.user.accessToken = newTokens.access_token;
+      req.user.refreshToken = newTokens.refresh_token;
+      req.user.expiresAt = Date.now() + (newTokens.expires_in * 1000);
+      
+      // Lưu vào database
+      await updateUserTokens(req.user.id, newTokens);
+      
+      console.log("Token refreshed successfully");
+    } catch (error) {
+      console.error("Auto refresh failed:", error);
+      return res.status(401).json({ error: "Authentication expired" });
+    }
+  }
+  
+  next();
+};
+```
+
+---
+
+## Token Validation
+
+### 1. Validate Access Token
+
+```typescript
+// Validate OA token
+const isValidOA = await zalo.validateAccessToken(accessToken, 'oa');
+console.log("OA Token valid:", isValidOA);
+
+// Validate Social token
+const isValidSocial = await zalo.validateAccessToken(accessToken, 'social');
+console.log("Social Token valid:", isValidSocial);
+```
+
+### 2. Advanced Token Validation
+
+```typescript
+// Sử dụng service trực tiếp để có thêm thông tin
+const validation = await zalo.auth.validateAccessToken(accessToken);
+
+interface TokenValidation {
+  valid: boolean;
+  expires_in?: number;      // Thời gian còn lại (seconds)
+  scope?: string;           // Quyền hiện tại
+  app_id?: string;         // App ID của token
+  user_id?: string;        // User ID (nếu có)
+}
+```
+
+---
+
+## Security Best Practices
+
+### 1. State Parameter
+
+Luôn sử dụng `state` parameter để chống CSRF:
+
+```typescript
+// Tạo random state
+const state = crypto.randomBytes(16).toString('hex');
+req.session.authState = state;
+
+const authUrl = zalo.createOAAuthUrl(redirectUri, state);
+
+// Trong callback, verify state
+if (req.query.state !== req.session.authState) {
+  throw new Error("Invalid state parameter");
+}
+```
+
+### 2. PKCE cho Social API
+
+Luôn sử dụng PKCE cho Social API:
+
+```typescript
+// ✅ Đúng - với PKCE
+const pkce = zalo.generatePKCE();
+req.session.codeVerifier = pkce.code_verifier;
+
+// ❌ Sai - không dùng PKCE
+const authUrl = zalo.createSocialAuthUrl(redirectUri);
+```
+
+### 3. Token Storage
+
+```typescript
+// ✅ Đúng - mã hóa tokens khi lưu
+const encryptedToken = encrypt(accessToken);
+await db.users.update(userId, { 
+  access_token: encryptedToken,
+  refresh_token: encrypt(refreshToken)
+});
+
+// ❌ Sai - lưu plain text
+await db.users.update(userId, { 
+  access_token: accessToken // Không an toàn
+});
+```
+
+### 4. Token Scope Validation
+
+```typescript
+// Kiểm tra token có đúng scope không
+async function requireScope(requiredScope: string) {
+  const validation = await zalo.auth.validateAccessToken(accessToken);
+  
+  if (!validation.scope?.includes(requiredScope)) {
+    throw new Error(`Missing required scope: ${requiredScope}`);
+  }
+}
+
+// Usage
+await requireScope('oa.message.send');
+```
+
+---
+
+## Error Handling
+
+### 1. Common Auth Errors
+
+```typescript
+try {
+  const tokens = await zalo.getOAAccessToken(code, redirectUri);
+} catch (error) {
+  if (error.code === -201) {
+    // Invalid parameters (code expired, wrong redirect_uri, etc.)
+    console.error("Invalid auth parameters:", error.message);
+  } else if (error.code === -216) {
+    // Invalid app credentials
+    console.error("Invalid app_id or app_secret");
+  } else {
+    console.error("Unexpected auth error:", error);
+  }
+}
+```
+
+### 2. Token Refresh Errors
+
+```typescript
+async function handleTokenRefresh(refreshToken: string) {
+  try {
+    return await zalo.refreshOAAccessToken(refreshToken);
+  } catch (error) {
+    if (error.code === -216) {
+      // Refresh token expired/invalid
+      console.log("Refresh token expired, require re-authentication");
+      redirectToLogin();
+    } else {
+      console.error("Refresh failed:", error);
+      throw error;
+    }
+  }
+}
+```
+
+---
+
+## Complete Authentication Flow Examples
+
+### 1. OA Authentication với Express
+
+```typescript
+import express from 'express';
+import { ZaloSDK } from '@warriorteam/redai-zalo-sdk';
+
+const app = express();
+const zalo = new ZaloSDK({
+  appId: process.env.ZALO_OA_APP_ID!,
+  appSecret: process.env.ZALO_OA_APP_SECRET!,
+  debug: process.env.NODE_ENV === 'development'
+});
+
+// Route bắt đầu auth
+app.get('/auth/oa', (req, res) => {
+  const state = generateRandomState();
+  req.session.authState = state;
+  
+  const authUrl = zalo.createOAAuthUrl(
+    `${process.env.BASE_URL}/auth/oa/callback`,
+    state
+  );
+  
+  res.redirect(authUrl);
+});
+
+// Callback handler
+app.get('/auth/oa/callback', async (req, res) => {
+  try {
+    const { code, state, error } = req.query;
+    
+    if (error) {
+      return res.redirect(`/auth/error?reason=${error}`);
+    }
+    
+    if (state !== req.session.authState) {
+      return res.status(400).json({ error: 'Invalid state' });
+    }
+    
+    const tokens = await zalo.getOAAccessToken(
+      code as string,
+      `${process.env.BASE_URL}/auth/oa/callback`
+    );
+    
+    // Lấy thông tin OA
+    const oaInfo = await zalo.getOAInfo(tokens.access_token);
+    
+    // Lưu vào database
+    const oaAccount = await OAAccount.create({
+      oa_id: oaInfo.oa_id,
+      name: oaInfo.name,
+      access_token: encrypt(tokens.access_token),
+      refresh_token: encrypt(tokens.refresh_token),
+      expires_at: new Date(Date.now() + tokens.expires_in * 1000),
+      scope: tokens.scope
+    });
+    
+    req.session.oaId = oaAccount.id;
+    res.redirect('/oa/dashboard');
+    
+  } catch (error) {
+    console.error('OA Auth error:', error);
+    res.redirect('/auth/error');
+  }
+});
+```
+
+### 2. Social Authentication với Next.js
+
+```typescript
+// pages/api/auth/social/login.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { ZaloSDK } from '@warriorteam/redai-zalo-sdk';
+
+const zalo = new ZaloSDK({
+  appId: process.env.ZALO_SOCIAL_APP_ID!,
+  appSecret: process.env.ZALO_SOCIAL_APP_SECRET!
+});
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'GET') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+  
+  // Generate PKCE
+  const pkce = zalo.generatePKCE();
+  const state = generateRandomState();
+  
+  // Lưu vào session/cookie (hoặc Redis)
+  res.setHeader('Set-Cookie', [
+    `pkce_verifier=${pkce.code_verifier}; HttpOnly; Secure; SameSite=Strict`,
+    `auth_state=${state}; HttpOnly; Secure; SameSite=Strict`
+  ]);
+  
+  const authUrl = zalo.createSocialAuthUrl(
+    `${process.env.NEXTAUTH_URL}/api/auth/social/callback`,
+    state
+  );
+  
+  res.redirect(authUrl);
+}
+
+// pages/api/auth/social/callback.ts
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  try {
+    const { code, state } = req.query;
+    const cookies = parseCookies(req.headers.cookie || '');
+    
+    if (state !== cookies.auth_state) {
+      throw new Error('Invalid state');
+    }
+    
+    const tokens = await zalo.getSocialAccessToken(
+      code as string,
+      `${process.env.NEXTAUTH_URL}/api/auth/social/callback`,
+      cookies.pkce_verifier
+    );
+    
+    const userInfo = await zalo.getSocialUserInfo(
+      tokens.access_token,
+      'id,name,picture,birthday'
+    );
+    
+    // Tạo hoặc cập nhật user
+    const user = await User.upsert({
+      zalo_id: userInfo.id,
+      name: userInfo.name,
+      avatar: userInfo.picture?.data.url,
+      birthday: userInfo.birthday
+    });
+    
+    // Lưu tokens
+    await UserToken.create({
+      user_id: user.id,
+      access_token: encrypt(tokens.access_token),
+      refresh_token: encrypt(tokens.refresh_token),
+      expires_at: new Date(Date.now() + tokens.expires_in * 1000),
+      token_type: 'social'
+    });
+    
+    // Tạo session
+    const sessionToken = jwt.sign(
+      { userId: user.id, zaloId: userInfo.id },
+      process.env.JWT_SECRET!,
+      { expiresIn: '7d' }
+    );
+    
+    res.setHeader('Set-Cookie', `session=${sessionToken}; HttpOnly; Secure`);
+    res.redirect('/profile');
+    
+  } catch (error) {
+    console.error('Social auth error:', error);
+    res.redirect('/login?error=auth_failed');
+  }
+}
+```
+
+---
+
+## Environment Configuration
+
+```typescript
+// .env file
+ZALO_OA_APP_ID=your_oa_app_id
+ZALO_OA_APP_SECRET=your_oa_app_secret
+ZALO_SOCIAL_APP_ID=your_social_app_id
+ZALO_SOCIAL_APP_SECRET=your_social_app_secret
+
+// config.ts
+export const zaloConfig = {
+  oa: {
+    appId: process.env.ZALO_OA_APP_ID!,
+    appSecret: process.env.ZALO_OA_APP_SECRET!,
+  },
+  social: {
+    appId: process.env.ZALO_SOCIAL_APP_ID!,
+    appSecret: process.env.ZALO_SOCIAL_APP_SECRET!,
+  }
+};
+
+// Khởi tạo SDK instances
+export const zaloOA = new ZaloSDK(zaloConfig.oa);
+export const zaloSocial = new ZaloSDK(zaloConfig.social);
+```
+
+---
+
+## Testing Authentication
+
+### 1. Unit Tests
+
+```typescript
+// auth.test.ts
+import { ZaloSDK } from '@warriorteam/redai-zalo-sdk';
+
+describe('Authentication', () => {
+  const zalo = new ZaloSDK({
+    appId: 'test_app_id',
+    appSecret: 'test_app_secret'
+  });
+  
+  it('should create OA auth URL', () => {
+    const url = zalo.createOAAuthUrl('http://localhost:3000/callback', 'test-state');
+    expect(url).toContain('oauth.zaloapp.com/v4/oa/permission');
+    expect(url).toContain('app_id=test_app_id');
+    expect(url).toContain('state=test-state');
+  });
+  
+  it('should generate valid PKCE', () => {
+    const pkce = zalo.generatePKCE();
+    expect(pkce.code_verifier).toHaveLength(128);
+    expect(pkce.code_challenge_method).toBe('S256');
+    expect(pkce.code_challenge).toBeDefined();
+  });
+});
+```
+
+### 2. Integration Tests
+
+```typescript
+// auth.integration.test.ts
+describe('Authentication Integration', () => {
+  it('should complete OA auth flow', async () => {
+    // Sử dụng test credentials
+    const testCode = 'test_authorization_code';
+    const testRedirectUri = 'http://localhost:3000/callback';
+    
+    const tokens = await zalo.getOAAccessToken(testCode, testRedirectUri);
+    
+    expect(tokens.access_token).toBeDefined();
+    expect(tokens.refresh_token).toBeDefined();
+    expect(tokens.expires_in).toBeGreaterThan(0);
+  });
+});
+```
+
+---
+
+## Troubleshooting
+
+### 1. Common Issues
+
+**Q: "Invalid redirect_uri" error**
+```
+A: Đảm bảo redirect_uri trong callback chính xác giống với lúc tạo auth URL
+   và đã được đăng ký trong Zalo Developer Console
+```
+
+**Q: "Invalid code" error**
+```
+A: Authorization code chỉ dùng được 1 lần và có thời gian sống ngắn (~10 phút)
+   Đảm bảo xử lý callback ngay sau khi user authorize
+```
+
+**Q: "Invalid app_id or app_secret"**
+```
+A: Kiểm tra credentials trong Zalo Developer Console
+   Đảm bảo dùng đúng app_id/app_secret cho môi trường (dev/prod)
+```
+
+### 2. Debug Authentication
+
+```typescript
+// Enable debug logging
+const zalo = new ZaloSDK({
+  appId: 'your_app_id',
+  appSecret: 'your_app_secret',
+  debug: true  // Bật debug logs
+});
+
+// Manual token validation
+async function debugToken(accessToken: string) {
+  try {
+    const validation = await zalo.auth.validateAccessToken(accessToken);
+    console.log('Token validation:', validation);
+    
+    if (validation.valid) {
+      console.log(`Token expires in: ${validation.expires_in} seconds`);
+      console.log(`Token scope: ${validation.scope}`);
+    }
+  } catch (error) {
+    console.error('Token validation failed:', error);
+  }
+}
+```
+
+---
+
+## Next Steps
+
+Sau khi hoàn thành authentication:
+
+1. **[ZNS Service](./ZNS_SERVICE.md)** - Gửi notification messages
+2. **[Message Services](./MESSAGE_SERVICES.md)** - Gửi các loại tin nhắn khác nhau
+3. **[User Management](./USER_MANAGEMENT.md)** - Quản lý user profiles
+4. **[Group Management](./GROUP_MANAGEMENT.md)** - Quản lý Zalo groups
+5. **[Webhook Integration](./WEBHOOK_EVENTS.md)** - Xử lý real-time events
+
+Tham khảo **[API Reference](./API_REFERENCE.md)** để biết chi tiết về tất cả methods có sẵn.