@amaster.ai/auth-client 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amaster Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,472 @@
+# @amaster.ai/auth-client
+
+Authentication SDK for Amaster Platform - Complete client-side authentication solution with OAuth, session management, and permission checks.
+
+## Features
+
+- 🔐 **Multiple Authentication Methods**: Username/Email/Phone + Password, Verification Code, OAuth
+- 🔄 **Automatic Token Refresh**: JWT token auto-refresh before expiration
+- 📦 **Token Storage**: localStorage or sessionStorage with SSR support
+- 🎯 **Permission System**: Role-based and permission-based access control
+- 🔗 **OAuth Integration**: Google, GitHub, WeChat, and custom OAuth providers
+- 📡 **Event System**: Listen to login, logout, and token events
+- 💾 **Session Management**: View and revoke active sessions
+- 🔒 **Type-Safe**: Full TypeScript support
+
+## Installation
+
+```bash
+pnpm add @amaster.ai/auth-client
+# or
+npm install @amaster.ai/auth-client
+```
+
+## Quick Start
+
+```typescript
+import { createAuthClient } from "@amaster.ai/auth-client";
+
+// Initialize the client (with optional callbacks)
+const authClient = createAuthClient({
+  onTokenExpired: () => {
+    window.location.href = "/login";
+  },
+  onUnauthorized: () => {
+    window.location.href = "/login";
+  },
+});
+
+// Register a new user
+await authClient.register({
+  email: "user@example.com",
+  password: "Password@123",
+  displayName: "John Doe",
+});
+
+// Login
+const result = await authClient.login({
+  loginType: "email",
+  email: "user@example.com",
+  password: "Password@123",
+});
+
+if (result.data) {
+  console.log("Logged in:", result.data.user);
+}
+
+// Get current user
+const user = await authClient.getMe();
+
+// Check permissions
+if (authClient.hasPermission("user.read")) {
+  // Show user list
+}
+```
+
+## Configuration
+
+```typescript
+interface AuthClientOptions {
+  baseURL?: string; // API base URL, defaults to window.location.origin
+  storage?: "localStorage" | "sessionStorage"; // Token storage type, defaults to localStorage
+  onTokenExpired?: () => void; // Token expiration callback
+  onUnauthorized?: () => void; // Unauthorized (401) callback
+}
+```
+
+**Built-in Features (Zero Config):**
+
+- ✅ **Auto Token Refresh**: Refreshes 5 minutes before expiry
+- ✅ **Auto Permission Sync**: Syncs on page load and every token refresh
+- ✅ **Lightweight Data**: Only permission names cached, not full objects
+- ✅ **On-Demand DataScope**: Loads only when needed
+- ✅ **SSR Compatible**: Works in both browser and server environments
+
+## Authentication
+
+### Register
+
+```typescript
+await authClient.register({
+  email: "user@example.com",
+  password: "Password@123",
+  displayName: "John Doe",
+});
+```
+
+**With Captcha:**
+
+```typescript
+// 1. Get captcha
+const captchaData = await authClient.getCaptcha();
+document.getElementById("captcha-img").src = captchaData.data.captchaImage;
+
+// 2. Register with captcha
+const userInputCode = "AB12";
+await authClient.register({
+  email: "user@example.com",
+  password: "Password@123",
+  captcha: `${captchaData.data.captchaId}:${userInputCode}`,
+});
+```
+
+### Login
+
+**Password Login:**
+
+```typescript
+await authClient.login({
+  loginType: "email",
+  email: "user@example.com",
+  password: "Password@123",
+});
+```
+
+**Verification Code Login:**
+
+```typescript
+// 1. Send code
+await authClient.sendCode({
+  type: "email",
+  email: "user@example.com",
+});
+
+// 2. Login with code
+await authClient.loginWithCode({
+  loginType: "email",
+  email: "user@example.com",
+  code: "123456",
+});
+```
+
+### OAuth Login
+
+**Full-page redirect (recommended):**
+
+```typescript
+// Login page
+sessionStorage.setItem("oauth_redirect", "/dashboard");
+authClient.loginWithOAuth("google");
+
+// Callback page (/auth/callback)
+const { user } = await authClient.handleOAuthCallback();
+const redirectUrl = sessionStorage.getItem("oauth_redirect") || "/";
+window.location.href = redirectUrl;
+```
+
+**Popup window:**
+
+```typescript
+// Main page
+const popup = window.open(
+  "/api/auth/oauth/google",
+  "oauth-login",
+  "width=600,height=700"
+);
+
+window.addEventListener("message", (event) => {
+  if (event.data.type === "oauth-success") {
+    authClient.setAccessToken(event.data.accessToken);
+    popup?.close();
+  }
+});
+
+// Callback page
+if (window.opener) {
+  const { accessToken } = await authClient.handleOAuthCallback();
+  window.opener.postMessage({ type: "oauth-success", accessToken }, origin);
+}
+```
+
+### Logout
+
+```typescript
+await authClient.logout();
+```
+
+## User Management
+
+### Get Current User
+
+```typescript
+const result = await authClient.getMe();
+if (result.data) {
+  console.log(result.data); // User object
+}
+```
+
+### Update Profile
+
+```typescript
+await authClient.updateMe({
+  displayName: "New Name",
+  avatarUrl: "https://example.com/avatar.jpg",
+});
+```
+
+### Change Password
+
+```typescript
+await authClient.changePassword({
+  oldPassword: "OldPassword@123",
+  newPassword: "NewPassword@123",
+});
+```
+
+## Permission Checks
+
+### Local Permission Checks (Fast)
+
+Permissions are cached locally as string arrays for fast UI checks:
+
+```typescript
+// Check single role
+if (authClient.hasRole("admin")) {
+  // Admin only
+}
+
+// Check single permission
+if (authClient.hasPermission("user.read")) {
+  // Can read users
+}
+
+// Check any permission
+if (authClient.hasAnyPermission(["user.read", "user.manage"])) {
+  // Has at least one permission
+}
+
+// Check all permissions
+if (authClient.hasAllPermissions(["user.read", "user.write"])) {
+  // Has all permissions
+}
+```
+
+### On-Demand Data Scope Loading
+
+Data scopes are loaded only when needed to reduce data transfer:
+
+```typescript
+// Get data scope for a specific permission
+const result = await authClient.getPermissionScope("user.read");
+if (result.data) {
+  const { dataScope } = result.data;
+  
+  if (dataScope.scopeType === "department") {
+    // Filter users by department
+    const users = await api.getUsers({
+      departmentId: dataScope.scopeFilter.departmentId
+    });
+  } else if (dataScope.scopeType === "all") {
+    // Show all users
+    const users = await api.getUsers();
+  }
+}
+```
+
+**Optimized Data Structure:**
+
+```typescript
+// User object (lightweight)
+{
+  uid: "xxx",
+  email: "user@example.com",
+  roles: ["admin", "user"],  // Only role codes
+  permissions: ["user.read", "user.write", "order.read"],  // Only permission names
+  // NO dataScopes - loaded on demand
+}
+```
+
+## OAuth Bindings
+
+### Get Bindings
+
+```typescript
+const result = await authClient.getOAuthBindings();
+if (result.data) {
+  console.log(result.data); // Array of OAuthBinding
+}
+```
+
+### Bind OAuth Account
+
+```typescript
+authClient.bindOAuth("google"); // Redirects to OAuth flow
+```
+
+### Unbind OAuth Account
+
+```typescript
+await authClient.unbindOAuth("google");
+```
+
+## Session Management
+
+### Get Sessions
+
+```typescript
+const result = await authClient.getSessions();
+if (result.data) {
+  result.data.forEach((session) => {
+    console.log(session.ip, session.userAgent, session.isCurrent);
+  });
+}
+```
+
+### Revoke Session
+
+```typescript
+await authClient.revokeSession("session-id");
+```
+
+### Revoke All Sessions
+
+```typescript
+const result = await authClient.revokeAllSessions();
+if (result.data) {
+  console.log(`Revoked ${result.data.revokedCount} sessions`);
+}
+```
+
+## Event System
+
+### Available Events
+
+- `login` - User logged in, callback: `(user: User) => void`
+- `logout` - User logged out, callback: `() => void`
+- `tokenExpired` - Token expired, callback: `() => void`
+- `tokenRefreshed` - Token refreshed, callback: `(token: string) => void`
+- `unauthorized` - Unauthorized (401), callback: `() => void`
+
+### Usage
+
+```typescript
+// Subscribe to events
+authClient.on("unauthorized", () => {
+  authClient.clearAuth();
+  window.location.href = "/login";
+});
+
+authClient.on("login", (user) => {
+  console.log("User logged in:", user.displayName);
+});
+
+authClient.on("tokenRefreshed", (token) => {
+  console.log("Token refreshed");
+});
+
+// Unsubscribe
+const handler = () => console.log("Logged out");
+authClient.on("logout", handler);
+authClient.off("logout", handler);
+```
+
+## Utility Methods
+
+### Check Authentication Status
+
+```typescript
+if (authClient.isAuthenticated()) {
+  // User is logged in
+}
+```
+
+### Get Access Token
+
+```typescript
+const token = authClient.getAccessToken();
+```
+
+### Set Access Token
+
+```typescript
+authClient.setAccessToken("your-token-here");
+```
+
+### Clear Auth Data
+
+```typescript
+authClient.clearAuth(); // Clears token and user data
+```
+
+## Error Handling
+
+```typescript
+try {
+  await authClient.login({ ... });
+} catch (error) {
+  // Network error or exception
+  console.error("Login failed:", error);
+}
+
+// Or use result pattern
+const result = await authClient.login({ ... });
+if (result.error) {
+  // API error response
+  if (result.error.status === 401) {
+    alert("Invalid email or password");
+  } else if (result.error.status === 403) {
+    alert("Account is disabled");
+  } else {
+    alert(`Login failed: ${result.error.message}`);
+  }
+}
+```
+
+## Best Practices
+
+### Token Management
+
+- SDK automatically manages Access Token and Refresh Token
+- Access Token is stored in localStorage/sessionStorage
+- Refresh Token is managed by backend via HttpOnly Cookie
+- Token is automatically refreshed 5 minutes before expiration (configurable)
+
+### Permission Sync
+
+- **On Page Load**: User info and permissions automatically sync from backend
+- **On Token Refresh**: Permissions re-sync every 5 minutes when token refreshes
+- **Manual Sync**: Call `await authClient.getMe()` to force sync anytime
+
+**Behavior:**
+- Permissions always stay fresh without any configuration
+- Page refresh loads latest permissions from backend
+- Background sync happens automatically every 5 minutes
+
+### Permission Checks
+
+- **Frontend permission checks are for UI control only** (show/hide buttons, menus)
+- **Backend must verify permissions again** - frontend checks are NOT security measures
+- Use permission checks to improve UX, not as security enforcement
+
+### SSR Support
+
+The SDK detects SSR environments and uses a no-op storage adapter:
+
+```typescript
+// Safe in both browser and SSR
+const authClient = createAuthClient();
+```
+
+## TypeScript
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type {
+  User,
+  LoginResponse,
+  Permission,
+  Role,
+  DataScope,
+  Session,
+  OAuthBinding,
+} from "@amaster.ai/auth-client";
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.

package/dist/auth.d.cts

@@ -0,0 +1,138 @@
+/**
+ * ============================================================================
+ * @amaster.ai/auth-client - Type Definitions
+ * ============================================================================
+ * 
+ * 🤖 AI NAVIGATION - Read these files based on your task:
+ * 
+ * 1. Need LOGIN/REGISTER/LOGOUT? → Read: ./auth.d.ts
+ * 2. Need PERMISSION checks? → Read: ./permissions.d.ts
+ * 3. Need USER profile management? → Read: ./user.d.ts
+ * 4. Need OAUTH binding? → Read: ./oauth.d.ts
+ * 5. Need SESSION management? → Read: ./sessions.d.ts
+ * 
+ * ============================================================================
+ */
+import { HttpClient, ClientResult } from '@amaster.ai/http-client';
+import { s as User, k as RegisterParams, f as LoginResponse, L as LoginParams, d as CodeLoginParams, S as SendCodeParams, r as SuccessResponse, b as CaptchaResponse, h as OAuthProvider, R as RefreshTokenResponse } from './types-4MBObpYA.cjs';
+
+/**
+ * Authentication Module
+ *
+ * @module auth
+ * @category Authentication
+ *
+ * Handles user authentication including:
+ * - Registration
+ * - Login (email/username/phone + password)
+ * - Verification code login
+ * - OAuth social login
+ * - Logout and token refresh
+ */
+
+interface AuthModuleDeps {
+    http: HttpClient;
+    onLoginSuccess: (user: User, accessToken: string) => void;
+    storage: {
+        getItem: (key: string) => string | null;
+    };
+    clearAuth: () => void;
+}
+declare function createAuthModule(deps: AuthModuleDeps): {
+    /**
+     * Register a new user account
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * const result = await auth.register({
+     *   email: "user@example.com",
+     *   password: "Password@123",
+     *   displayName: "John Doe",
+     * });
+     * ```
+     */
+    register(params: RegisterParams): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Login with username/email/phone and password
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * await auth.login({
+     *   loginType: "email",
+     *   email: "user@example.com",
+     *   password: "Password@123",
+     * });
+     * ```
+     */
+    login(params: LoginParams): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Login with verification code
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * await auth.loginWithCode({
+     *   loginType: "email",
+     *   email: "user@example.com",
+     *   code: "123456",
+     * });
+     * ```
+     */
+    loginWithCode(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Send verification code to email or phone
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * await auth.sendCode({
+     *   type: "email",
+     *   email: "user@example.com",
+     * });
+     * ```
+     */
+    sendCode(params: SendCodeParams): Promise<ClientResult<SuccessResponse>>;
+    /**
+     * Get captcha image
+     *
+     * @category Authentication
+     */
+    getCaptcha(): Promise<ClientResult<CaptchaResponse>>;
+    /**
+     * Redirect to OAuth provider for authentication
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * auth.loginWithOAuth("google");
+     * ```
+     */
+    loginWithOAuth(provider: OAuthProvider, redirectUrl?: string): void;
+    /**
+     * Handle OAuth callback
+     *
+     * @category Authentication
+     */
+    handleOAuthCallback(): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Logout current user
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * await auth.logout();
+     * ```
+     */
+    logout(): Promise<ClientResult<SuccessResponse>>;
+    /**
+     * Refresh access token
+     *
+     * @category Authentication
+     */
+    refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
+};
+type AuthModule = ReturnType<typeof createAuthModule>;
+
+export { type AuthModule, type AuthModuleDeps, createAuthModule };