@55387.ai/uniauth-client 1.2.3 → 1.2.5

package/README.md

@@ -69,6 +69,9 @@ auth.startSocialLogin('google');
 ### 🔐 SSO / 单点登录
 
 ```typescript
+// ⚠️ Must call configureSso() before using loginWithSSO()
+// ⚠️ 使用 loginWithSSO() 前必须调用 configureSso()
+
 // Configure / 配置
 auth.configureSso({
   ssoUrl: 'https://sso.55387.xyz',
@@ -164,6 +167,31 @@ try {
 }
 ```
 
+## 🤖 AI Agent Prompts / AI 智能体提示词
+
+This package includes AI-ready integration prompts for multiple scenarios. Copy them into your AI coding assistant (Claude, Cursor, Copilot, etc.) to generate a complete UniAuth integration automatically.
+
+本包附带多个场景的 AI 集成提示词。将其复制到 AI 编程助手中，即可自动生成完整的 UniAuth 集成代码。
+
+```bash
+# After install, find prompts at:
+# 安装后，提示词文件位于：
+ls node_modules/@55387.ai/uniauth-client/ai-prompts/
+# → full-stack.md, oauth2-provider.md, mobile-trusted-client.md
+```
+
+| Prompt | Scenario / 场景 |
+|--------|----------------|
+| `full-stack.md` | Full-stack app with React + Node.js / 全栈应用 |
+| `oauth2-provider.md` | Use UniAuth as OAuth2/OIDC provider / OAuth2 提供者 |
+| `mobile-trusted-client.md` | Mobile & trusted client API / 移动端可信客户端 |
+
+> [!TIP]
+> Replace placeholders like `YOUR_UNIAUTH_URL` and `YOUR_CLIENT_ID` before pasting into your AI assistant.
+> 粘贴到 AI 助手前，请替换 `YOUR_UNIAUTH_URL` 和 `YOUR_CLIENT_ID` 等占位符。
+
+See all prompts: [docs/ai-prompts/](../../docs/ai-prompts/README.md)
+
 ## License
 
 MIT

package/ai-prompts/full-stack.md

@@ -0,0 +1,167 @@
+# 🤖 AI Prompt: Full-Stack App with UniAuth
+
+> Copy everything below the line and paste into your AI coding assistant.
+>
+> 复制下方分割线以下的全部内容，粘贴到你的 AI 编程助手中。
+
+---
+
+You are an expert full-stack TypeScript developer. Help me build a complete web application with UniAuth authentication, from scratch.
+
+## Project Context
+
+- **UniAuth Server URL**: `YOUR_UNIAUTH_URL` (e.g. `https://auth.55387.xyz`)
+- **Client ID**: `YOUR_CLIENT_ID`
+- **Client Secret**: `YOUR_CLIENT_SECRET` (backend only!)
+- **App Key**: `YOUR_APP_KEY`
+- **Redirect URI**: `YOUR_REDIRECT_URI` (e.g. `http://localhost:5173/auth/callback`)
+
+## SDK Packages
+
+### Frontend: `@55387.ai/uniauth-react`
+
+```bash
+npm install @55387.ai/uniauth-react
+```
+
+**UniAuthProvider** — Wrap your app:
+```tsx
+import { UniAuthProvider } from '@55387.ai/uniauth-react';
+
+<UniAuthProvider config={{
+  baseUrl: 'YOUR_UNIAUTH_URL',
+  appKey: 'YOUR_APP_KEY',
+  clientId: 'YOUR_CLIENT_ID',
+  storage: 'localStorage',
+  sso: {
+    ssoUrl: 'YOUR_UNIAUTH_URL',
+    clientId: 'YOUR_CLIENT_ID',
+    redirectUri: 'YOUR_REDIRECT_URI',
+    scope: 'openid profile email',
+  },
+}}>
+  <App />
+</UniAuthProvider>
+```
+
+**useUniAuth()** — Access auth state:
+```tsx
+const { user, isAuthenticated, isLoading, login, logout, updateProfile, client, getToken } = useUniAuth();
+```
+
+**Key client methods** (via `client`):
+```typescript
+await client.sendCode(phone, 'login');          // SMS code
+await client.loginWithCode(phone, code);        // Phone login
+await client.sendEmailCode(email, 'login');     // Email code
+await client.loginWithEmailCode(email, code);   // Email code login
+await client.loginWithEmail(email, password);   // Email password login
+await client.registerWithEmail(email, password, nickname);
+await client.verifyMFA(mfaToken, code);         // MFA step
+client.startSocialLogin('google');              // Social login redirect
+client.loginWithSSO({ usePKCE: true });         // SSO redirect
+await client.getAccessToken();                  // Auto-refresh token
+```
+
+**Types**:
+```typescript
+interface UserInfo { id: string; phone: string|null; email: string|null; nickname: string|null; avatar_url: string|null; }
+interface LoginResult { user: UserInfo; access_token: string; refresh_token: string; expires_in: number; is_new_user: boolean; mfa_required?: boolean; mfa_token?: string; }
+```
+
+### Backend: `@55387.ai/uniauth-server`
+
+```bash
+npm install @55387.ai/uniauth-server
+```
+
+```typescript
+import { UniAuthServer, ServerAuthError } from '@55387.ai/uniauth-server';
+
+const auth = new UniAuthServer({
+  baseUrl: process.env.UNIAUTH_URL!,
+  clientId: process.env.UNIAUTH_CLIENT_ID!,
+  clientSecret: process.env.UNIAUTH_CLIENT_SECRET!,
+});
+
+// Express middleware
+app.use('/api/*', auth.middleware());
+// req.user → UserInfo, req.authPayload → TokenPayload
+
+// Hono middleware
+app.use('/api/*', auth.honoMiddleware());
+// c.get('user') → UserInfo, c.get('authPayload') → TokenPayload
+
+// Manual verification
+const payload = await auth.verifyToken(token);
+const user = await auth.getUser(payload.sub);
+```
+
+## Requirements
+
+### Architecture
+- **Frontend**: React + Vite (or Next.js)
+- **Backend**: Express or Hono
+- **Language**: TypeScript throughout
+- **Auth**: Frontend sends `Authorization: Bearer <token>` header, backend validates via `@55387.ai/uniauth-server`
+
+### Frontend Features
+1. **Login Page**: SSO login button + optional phone/email login tabs
+2. **Protected Routes**: Redirect to login if not authenticated
+3. **Dashboard**: Show user info, sample data from protected API
+4. **Settings Page** (required):
+   - Language: Chinese 中文 / English
+   - Theme: Dark / Light / System
+   - User profile display (nickname, avatar, email)
+   - Logout button
+5. **Toast Notifications**: Never use `alert()` or `confirm()`
+6. **i18n**: Chinese + English bilingual UI
+7. **Dark Mode**: Light, Dark, System
+8. **Responsive**: Desktop + Tablet + Mobile
+
+### Backend Features
+1. **Protected API routes** using UniAuth middleware
+2. **Public routes** for health check
+3. **User-specific data**: Use `req.user.id` or `c.get('user').id` to scope data
+4. **Error handling**: JSON error responses with proper status codes
+5. **CORS**: Allow frontend origin
+
+### Design Tokens (Fan Design System)
+```
+Primary: #07C160 | Error: #FA5151 | Warning: #FFBE00 | Link: #576B95
+Border Radius: button 8px, card 12px, input 4px
+Font: base 17px, h1 20px, caption 14px, small 12px
+Spacing: page edge 16px, element gap 8px, unit 4px
+Background Light: page #F2F2F2, card #FFFFFF
+Background Dark: page #111111, card #191919
+Text Light: primary rgba(0,0,0,0.9), secondary rgba(0,0,0,0.5)
+Text Dark: primary rgba(255,255,255,0.8), secondary rgba(255,255,255,0.5)
+Button height: 48px, Navbar height: 44px
+```
+
+### Environment Variables
+
+**Frontend** (`.env`):
+```env
+VITE_UNIAUTH_URL=YOUR_UNIAUTH_URL
+VITE_UNIAUTH_CLIENT_ID=YOUR_CLIENT_ID
+VITE_UNIAUTH_APP_KEY=YOUR_APP_KEY
+VITE_UNIAUTH_REDIRECT_URI=http://localhost:5173/auth/callback
+VITE_API_URL=http://localhost:3000
+```
+
+**Backend** (`.env`):
+```env
+UNIAUTH_URL=YOUR_UNIAUTH_URL
+UNIAUTH_CLIENT_ID=YOUR_CLIENT_ID
+UNIAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
+PORT=3000
+FRONTEND_URL=http://localhost:5173
+```
+
+### Testing
+- Frontend: Vitest + React Testing Library
+- Backend: Vitest + supertest
+- Include tests for auth flow, protected routes, and error handling
+
+Generate the complete project with both frontend and backend. Ensure all code compiles and follows TypeScript best practices.

package/ai-prompts/mobile-trusted-client.md

@@ -0,0 +1,185 @@
+# 🤖 AI Prompt: Mobile / Trusted Client Integration
+
+> Copy everything below the line and paste into your AI coding assistant.
+>
+> 复制下方分割线以下的全部内容，粘贴到你的 AI 编程助手中。
+
+---
+
+You are an expert mobile/native app developer. Help me integrate UniAuth authentication into my mobile or native application using the **Trusted Client API**.
+
+The Trusted Client API allows server-to-server or privileged native apps to perform direct authentication (phone/email login) without browser redirects. This is ideal for mobile apps, desktop apps, and backend services.
+
+## Project Context
+
+- **UniAuth Server URL**: `YOUR_UNIAUTH_URL` (e.g. `https://auth.55387.xyz`)
+- **Trusted Client ID**: `YOUR_CLIENT_ID`
+- **Trusted Client Secret**: `YOUR_CLIENT_SECRET`
+
+## Trusted Client API Reference
+
+All Trusted Client endpoints require these headers:
+
+```http
+X-Client-Id: YOUR_CLIENT_ID
+X-Client-Secret: YOUR_CLIENT_SECRET
+Content-Type: application/json
+```
+
+### Phone Authentication
+
+**Send SMS Code:**
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/phone/send-code
+
+{
+  "phone": "+8613800138000",
+  "type": "login"
+}
+```
+Response: `{ "success": true, "data": { "expires_in": 300, "retry_after": 60 } }`
+
+**Verify Phone Code:**
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/phone/verify
+
+{
+  "phone": "+8613800138000",
+  "code": "123456"
+}
+```
+Response: `{ "success": true, "data": { "user": {...}, "access_token": "...", "refresh_token": "...", "expires_in": 3600 } }`
+
+### Email Authentication
+
+**Send Email Code:**
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/email/send-code
+
+{
+  "email": "user@example.com",
+  "type": "login"
+}
+```
+
+**Verify Email Code:**
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/email/verify
+
+{
+  "email": "user@example.com",
+  "code": "123456"
+}
+```
+
+**Email Password Login:**
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/email/login
+
+{
+  "email": "user@example.com",
+  "password": "user_password"
+}
+```
+
+### MFA Verification
+
+When a login returns `mfa_required: true`, complete MFA:
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/mfa/verify
+
+Headers: X-Client-Id, X-Client-Secret
+{
+  "mfa_token": "temporary_mfa_token",
+  "code": "123456"
+}
+```
+
+### Token Refresh
+
+```http
+POST YOUR_UNIAUTH_URL/api/v1/trusted/token/refresh
+
+Headers: X-Client-Id, X-Client-Secret
+{
+  "refresh_token": "current_refresh_token"
+}
+```
+Response: `{ "success": true, "data": { "access_token": "new_token", "refresh_token": "new_refresh", "expires_in": 3600 } }`
+
+### Get User Info (with token)
+
+```http
+GET YOUR_UNIAUTH_URL/api/v1/user/me
+Authorization: Bearer ACCESS_TOKEN
+```
+Response: `{ "success": true, "data": { "id": "...", "phone": "...", "email": "...", "nickname": "...", "avatar_url": "..." } }`
+
+## Response Types
+
+```typescript
+// Successful login response
+interface LoginResponse {
+  success: true;
+  data: {
+    user: {
+      id: string;
+      phone: string | null;
+      email: string | null;
+      nickname: string | null;
+      avatar_url: string | null;
+    };
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    is_new_user: boolean;
+    mfa_required?: boolean;
+    mfa_token?: string;
+    mfa_methods?: string[];
+  };
+}
+
+// Error response
+interface ErrorResponse {
+  success: false;
+  error: {
+    code: string;    // e.g. 'INVALID_CODE', 'RATE_LIMITED'
+    message: string; // Human-readable error
+  };
+}
+```
+
+## Requirements
+
+1. **Auth Service Layer**: Create a service/manager class that encapsulates all Trusted Client API calls. Securely store `Client-Id` and `Client-Secret` in the app (use secure storage on mobile).
+
+2. **Login Flow**:
+   - Phone login: Send code → Verify code → Get tokens
+   - Email login: Send code → Verify code, OR email + password login
+   - Handle `mfa_required` response → prompt user for MFA code → verify
+
+3. **Token Management**:
+   - Store `access_token` and `refresh_token` in secure storage (Keychain on iOS, EncryptedSharedPreferences on Android)
+   - Auto-refresh tokens before expiry using the refresh endpoint
+   - Include `Authorization: Bearer <access_token>` in all API requests
+
+4. **Error Handling**: Handle network errors, expired tokens, rate limiting, and invalid credentials gracefully. Display user-friendly error messages.
+
+5. **UI/UX**:
+   - Login screen with phone/email tabs
+   - SMS/email code input with countdown timer
+   - MFA code input when required
+   - Loading states during API calls
+   - Toast notifications for errors (no `alert()`)
+
+6. **Security**:
+   - Never log tokens or secrets
+   - Use HTTPS for all API calls
+   - Validate phone number format (E.164) before sending
+   - Implement retry-after logic to respect rate limits
+
+7. **i18n**: Support Chinese and English.
+
+8. **Testing**: Include unit tests for the auth service layer.
+
+Generate the complete implementation for my target platform (React Native / Flutter / Swift / Kotlin).

package/ai-prompts/oauth2-provider.md

@@ -0,0 +1,176 @@
+# 🤖 AI Prompt: OAuth2 / OIDC Provider Integration
+
+> Copy everything below the line and paste into your AI coding assistant.
+>
+> 复制下方分割线以下的全部内容，粘贴到你的 AI 编程助手中。
+
+---
+
+You are an expert developer specializing in OAuth2 and OpenID Connect. Help me integrate UniAuth as my application's OAuth2/OIDC provider.
+
+## Project Context
+
+- **UniAuth Server URL**: `YOUR_UNIAUTH_URL` (e.g. `https://auth.55387.xyz`)
+- **Client ID**: `YOUR_CLIENT_ID`
+- **Client Secret**: `YOUR_CLIENT_SECRET`
+- **Redirect URI**: `YOUR_REDIRECT_URI`
+
+## OIDC Discovery
+
+UniAuth supports OpenID Connect Discovery. Your app can auto-configure by fetching:
+
+```
+GET YOUR_UNIAUTH_URL/.well-known/openid-configuration
+```
+
+Response includes:
+```json
+{
+  "issuer": "YOUR_UNIAUTH_URL",
+  "authorization_endpoint": "YOUR_UNIAUTH_URL/api/v1/oauth2/authorize",
+  "token_endpoint": "YOUR_UNIAUTH_URL/api/v1/oauth2/token",
+  "userinfo_endpoint": "YOUR_UNIAUTH_URL/api/v1/oidc/userinfo",
+  "jwks_uri": "YOUR_UNIAUTH_URL/.well-known/jwks.json",
+  "introspection_endpoint": "YOUR_UNIAUTH_URL/api/v1/oauth2/introspect",
+  "response_types_supported": ["code"],
+  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
+  "subject_types_supported": ["public"],
+  "id_token_signing_alg_values_supported": ["RS256"],
+  "scopes_supported": ["openid", "profile", "email", "phone"]
+}
+```
+
+## API Endpoints
+
+### 1. Authorization Code Flow
+
+**Step 1: Redirect user to authorize**
+```
+GET YOUR_UNIAUTH_URL/api/v1/oauth2/authorize
+  ?client_id=YOUR_CLIENT_ID
+  &redirect_uri=YOUR_REDIRECT_URI
+  &response_type=code
+  &scope=openid profile email
+  &state=random_csrf_state
+  &code_challenge=BASE64URL_CHALLENGE     # PKCE (recommended)
+  &code_challenge_method=S256
+```
+
+**Step 2: Exchange code for tokens**
+```http
+POST YOUR_UNIAUTH_URL/api/v1/oauth2/token
+Content-Type: application/json
+
+{
+  "grant_type": "authorization_code",
+  "client_id": "YOUR_CLIENT_ID",
+  "client_secret": "YOUR_CLIENT_SECRET",
+  "code": "AUTHORIZATION_CODE",
+  "redirect_uri": "YOUR_REDIRECT_URI",
+  "code_verifier": "PKCE_VERIFIER"
+}
+```
+
+Response:
+```json
+{
+  "access_token": "eyJ...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "eyJ...",
+  "id_token": "eyJ..."
+}
+```
+
+### 2. Client Credentials Flow (Machine-to-Machine)
+
+```http
+POST YOUR_UNIAUTH_URL/api/v1/oauth2/token
+Content-Type: application/json
+
+{
+  "grant_type": "client_credentials",
+  "client_id": "YOUR_CLIENT_ID",
+  "client_secret": "YOUR_CLIENT_SECRET",
+  "scope": "read write"
+}
+```
+
+### 3. Token Introspection (RFC 7662)
+
+```http
+POST YOUR_UNIAUTH_URL/api/v1/oauth2/introspect
+Authorization: Basic BASE64(client_id:client_secret)
+Content-Type: application/json
+
+{ "token": "ACCESS_TOKEN" }
+```
+
+### 4. UserInfo Endpoint
+
+```http
+GET YOUR_UNIAUTH_URL/api/v1/oidc/userinfo
+Authorization: Bearer ACCESS_TOKEN
+```
+
+### 5. JWKS (for local JWT verification)
+
+```
+GET YOUR_UNIAUTH_URL/.well-known/jwks.json
+```
+
+## Using the Client SDK (Optional)
+
+```bash
+npm install @55387.ai/uniauth-client
+```
+
+```typescript
+import { UniAuthClient } from '@55387.ai/uniauth-client';
+
+const client = new UniAuthClient({
+  baseUrl: 'YOUR_UNIAUTH_URL',
+  clientId: 'YOUR_CLIENT_ID',
+});
+
+// Start OAuth2 flow with PKCE
+const authUrl = await client.startOAuth2Flow({
+  redirectUri: 'YOUR_REDIRECT_URI',
+  scope: 'openid profile email',
+  usePKCE: true,
+});
+window.location.href = authUrl;
+
+// On callback page — exchange code for tokens
+const tokens = await client.exchangeOAuth2Code(
+  code,               // from URL query param
+  'YOUR_REDIRECT_URI',
+  'YOUR_CLIENT_SECRET' // optional, for confidential clients
+);
+```
+
+## Requirements
+
+1. **Authorization Code + PKCE**: Implement the full flow for browser-based apps (public clients). Always use PKCE.
+
+2. **Client Credentials**: Implement M2M token acquisition for backend services that need to call UniAuth-protected APIs.
+
+3. **Token Validation**: On your backend, validate tokens using either:
+   - **Introspection endpoint** (recommended for most cases)
+   - **JWKS-based local verification** (better performance, use JWKS endpoint)
+
+4. **OIDC Discovery**: Auto-configure your app using the `.well-known/openid-configuration` endpoint instead of hardcoding URLs.
+
+5. **State & CSRF**: Generate random `state` parameters and validate on callback.
+
+6. **Token Storage**: Store access tokens securely. Refresh tokens before expiry.
+
+7. **Environment Variables**:
+```env
+UNIAUTH_URL=YOUR_UNIAUTH_URL
+UNIAUTH_CLIENT_ID=YOUR_CLIENT_ID
+UNIAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
+UNIAUTH_REDIRECT_URI=YOUR_REDIRECT_URI
+```
+
+Generate the complete implementation for my target platform/framework.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@55387.ai/uniauth-client",
-    "version": "1.2.3",
+    "version": "1.2.5",
     "description": "UniAuth Frontend SDK - Phone, Email, SSO login for browser",
     "type": "module",
     "main": "./dist/index.js",
@@ -8,7 +8,8 @@
     "types": "./dist/index.d.ts",
     "files": [
         "dist",
-        "README.md"
+        "README.md",
+        "ai-prompts"
     ],
     "exports": {
         ".": {
@@ -30,6 +31,7 @@
     },
     "devDependencies": {
         "@types/node": "^22.10.2",
+        "jsdom": "^27.3.0",
         "tsup": "^8.3.5",
         "typescript": "^5.7.2",
         "vitest": "^2.1.9"
@@ -41,4 +43,4 @@
         "login",
         "sdk"
     ]
-}
+}