@kido/zalo-mini-authCopy Anchor Link

Architecture Paradigm: OAuth 2.0 with PKCE Challenge Verification + Pure Node.js Crypto AES-128-CBC Phone Decryptor + Vietnamese Telecom E.164 Normalizer + Golden Customer Record Identity Mapping.

💥 The Real-World BottleneckCopy Anchor Link

Integrating Zalo Mini Apps and Zalo Official Accounts (OA) into modern backend architectures introduces specific security and operational failure modes:

1. AES-128-CBC Phone Token Decryption Crashes: Zalo Mini App returns an encrypted token for user phone numbers. Developers hand-rolling crypto logic frequently encounter:
   • Wrong secret key transformations (Zalo requires using the first 16 bytes of appSecret or specific padding).
   • Unhandled PKCS#7 padding exceptions that crash the entire Node.js server.
2. Vietnamese Phone Number Format Chaos: Users enter phone numbers with irregular formats (+84912345678, 0912.345.678, 840912345678, 912345678). Inconsistent formatting causes duplicated user accounts and broken CRM lookups during checkout.
3. Token Expiry Cascades & Zalo 429 Rate Limiting: Zalo access tokens expire every 25 hours. When multiple API pods attempt to refresh expired tokens simultaneously, they trigger race conditions, invalidating active tokens and exhausting Zalo OAuth rate limit quotas.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

@kido/zalo-mini-auth is strictly modularized with zero third-party framework coupling:

1. OAuth & PKCE Helpers (src/oauth.ts)Copy Anchor Link

• getZaloLoginUrl(options): Generates compliant OAuth 2.0 authorization URLs with code_challenge (PKCE SHA-256) and state parameter.
• calculateTokenExpiresAt(expiresIn, bufferSeconds): Calculates exact expiration timestamp with configurable safety buffer.
• isTokenExpired(expiresAt, bufferSeconds): Proactively detects token freshness to avoid mid-request 401 errors.
• ZaloOAuthError: Strongly-typed error wrapper capturing Zalo OAuth error codes and messages.

2. Phone Decryption Engine (src/phone.ts)Copy Anchor Link

• decryptPhoneNumberAes(token, appSecret): Pure Node.js crypto AES-128-CBC decryptor with automatic key/IV preparation and PKCS#7 unpadding.
• encryptPhoneNumberAes(options): Testing utility to generate valid encrypted phone payloads for CI/CD test suites.
• ZaloPhoneDecryptionError: Explicit error handling for expired tokens, corrupt payloads, or incorrect app secrets.

3. Vietnamese Phone Normalizer (src/phone-utils.ts)Copy Anchor Link

• normalizeVietnamesePhoneNumber(phone): Strips non-digits and unifies all variations (+84, 84, 840, 0, space/dot/dash separated) into the standard 10-digit format (09xxxxxxxx).
• isValidVietnamesePhoneNumber(phone): Validates prefixes against active Vietnamese telecom operators (Viettel 03x/086/096/097/098, Mobifone 07x/089/090/093, Vinaphone 08x/091/094, Vietnamobile 05x/092).
• formatVietnamesePhoneNumber(phone, format): Formats phone numbers for UI presentation (national, dotted, international, raw).

4. Golden Customer Profile Mapper (src/mapper.ts)Copy Anchor Link

• mapToCustomerProfile(input): Unifies both Zalo Web OAuth (/v2.0/me) and Zalo Mini App SDK (getUserInfo) payloads into a standardized CustomerProfile DTO.
• mapZaloMiniAppToCustomerProfile(rawUserInfo, options): Maps Mini App user info including Official Account (OA) follow status and avatar.

💻 Production Implementation & Code SnippetCopy Anchor Link

Complete Zalo Mini App Login & Phone Extraction EndpointCopy Anchor Link

import { Hono } from 'hono';
import { 
  decryptPhoneNumberAes, 
  normalizeVietnamesePhoneNumber,
  mapToCustomerProfile,
  formatVietnamesePhoneNumber
} from '@kido/zalo-mini-auth';

const app = new Hono();
const ZALO_APP_SECRET = process.env.ZALO_APP_SECRET!;

app.post('/api/auth/zalo-mini-app', async (c) => {
  const body = await c.req.json();
  const { phoneToken, userInfo } = body;

  let phoneNumber: string | null = null;

  // 1. Decrypt phone number securely using pure Node crypto
  if (phoneToken) {
    try {
      const decrypted = decryptPhoneNumberAes(phoneToken, ZALO_APP_SECRET);
      phoneNumber = normalizeVietnamesePhoneNumber(decrypted.number);
    } catch (err) {
      console.error('Phone decryption error:', err);
      return c.json({ error: 'Invalid or expired phone token' }, 400);
    }
  }

  // 2. Map to Universal Customer Profile DTO
  const customer = mapToCustomerProfile({
    source: 'zalo_mini_app',
    userInfo,
    phoneNumber,
    metadata: {
      clientIp: c.req.header('x-forwarded-for') || '127.0.0.1',
      loginTime: new Date().toISOString(),
    },
  });

  // 3. Upsert into database
  /*
  const user = await db.user.upsert({
    where: { zaloId: customer.zaloId },
    create: {
      zaloId: customer.zaloId,
      name: customer.name,
      phoneNumber: customer.phoneNumber,
      avatar: customer.avatar,
    },
    update: {
      name: customer.name,
      phoneNumber: customer.phoneNumber ?? undefined,
      avatar: customer.avatar ?? undefined,
    },
  });
  */

  return c.json({
    success: true,
    user: {
      id: customer.zaloId,
      name: customer.name,
      phoneFormatted: phoneNumber ? formatVietnamesePhoneNumber(phoneNumber, 'dotted') : null,
      avatar: customer.avatar,
    },
  });
});

export default app;

⚡ Benchmark & Verified k6 PerformanceCopy Anchor Link

Benchmarked on Bun 1.3 / Node.js 22 LTS (M3 Max / AMD EPYC single vCPU):

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

# Install directly via Kido CLI
npx @kido/cli add @kido/zalo-mini-auth