@coremail/lunkr-openclaw 1.0.0

package/docs/AUTHENTICATION.md

@@ -0,0 +1,254 @@
+# Lunkr Authentication Flow
+
+This document describes the complete authentication flow for the Lunkr channel plugin.
+
+## Overview
+
+Lunkr authentication involves two separate systems:
+
+1. **Coremail** - The email server that handles user authentication
+2. **Lunkr** - The collaboration platform that uses Coremail for authentication
+
+The authentication flow must first authenticate with Coremail, then obtain a Lunkr session.
+
+## Authentication Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Login Flow                                      │
+└─────────────────────────────────────────────────────────────────────────┘
+
+User Input                 Coremail Server                    Lunkr Server
+    │                           │                                  │
+    │  1. Discover Server       │                                  │
+    │  ─────────────────────>   │                                  │
+    │                           │                                  │
+    │  2. Get RSA Key           │                                  │
+    │  <─────────────────────   │                                  │
+    │                           │                                  │
+    │  3. Encrypt Password      │                                  │
+    │  ─────────────────────>   │                                  │
+    │                           │                                  │
+    │  4. user:login            │                                  │
+    │  ─────────────────────>   │                                  │
+    │                           │                                  │
+    │  5. Return Code           │                                  │
+    │  <─────────────────────   │                                  │
+    │                           │                                  │
+    │         ╔═════════════════════════════════════════════════╗   │
+    │         ║  Branch based on return code                    ║   │
+    │         ╠═════════════════════════════════════════════════╣   │
+    │         ║  S_OK / FA_NEED_ACCESS_SECRET → Continue       ║   │
+    │         ║  FA_NEED_DYNAMIC_PWD → OTP Flow                ║   │
+    │         ║  FA_NEED_VERIFY_CODE → Manual Login Required   ║   │
+    │         ╚═════════════════════════════════════════════════╝   │
+    │                           │                                  │
+    │  6. getLunkrSession       │                                  │
+    │  ──────────────────────────────────────────────────────────>   │
+    │                           │                                  │
+    │  7. cim.common:verify     │                                  │
+    │  <─────────────────────────────────────────────────────────   │
+    │  (returns login_key)      │                                  │
+    │                           │                                  │
+    │  8. Generate X-CM-TOKEN   │                                  │
+    │                           │                                  │
+    │  9. cim.user:login        │                                  │
+    │  ──────────────────────────────────────────────────────────>   │
+    │                           │                                  │
+    │  10. Lunkr Session        │                                  │
+    │  <─────────────────────────────────────────────────────────   │
+    │  (Cim cookie, Lunkr SID)  │                                  │
+```
+
+## Step-by-Step Flow
+
+### Step 1: Server Discovery
+
+First, discover the Coremail server for the user's email domain:
+
+```typescript
+const serverInfo = await DomainDiscoveryService.discoverAvailableServer(email);
+// Returns: { baseUrl, apiPath, apiUrl, uri }
+```
+
+### Step 2: Get RSA Key
+
+Request RSA public key for password encryption:
+
+```typescript
+const rsaInfo = await client.postJson({
+  func: 'user:get_rsa',
+  payload: { uid: email }
+});
+// Returns: { sid, authType, rsaE, rsaN }
+```
+
+### Step 3: Encrypt Password
+
+Encrypt the password using RSA:
+
+```typescript
+const encryptedPassword = encryptPasswordRsa(password, rsaInfo.rsaE, rsaInfo.rsaN);
+```
+
+### Step 4-5: Login Request
+
+Send login request with encrypted password and device info:
+
+```typescript
+const loginPayload = {
+  uid: email,
+  password: encryptedPassword,
+  authType: rsaInfo.authType,
+  device: {
+    uuid: deviceUuid,
+    os: 'macOS',
+    model: 'Desktop',
+    friendlyName: deviceName,
+  },
+  supportDynamicPwd: true,
+  supportBind2FA: true,
+  returnCookie: true,
+  // ... other fields
+};
+
+const response = await client.postJson({
+  func: 'user:login',
+  sid: rsaInfo.sid,
+  payload: loginPayload
+});
+```
+
+### Step 6: Handle Return Code
+
+The login response returns different codes:
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `S_OK` | Success | Proceed to getLunkrSession |
+| `FA_NEED_ACCESS_SECRET` | Device auth success | Proceed to getLunkrSession |
+| `FA_NEED_DYNAMIC_PWD` | OTP required | Trigger OTP flow |
+| `FA_NEED_VERIFY_CODE` | Captcha required | Manual login required |
+| `FA_USER_IN_GRAYLIST` | User restricted | Manual login required |
+
+### OTP Flow (FA_NEED_DYNAMIC_PWD)
+
+When OTP is required:
+
+1. **Trigger second auth**:
+   ```typescript
+   await client.postJson({
+     func: 'user:triggerSecondAuth',
+     payload: { type: 'OTP', device, tempSid, trans: 'login' }
+   });
+   ```
+
+2. **Wait for user** to complete OTP on another device
+
+3. **Query validation status**:
+   ```typescript
+   const result = await client.postJson({
+     func: 'user:querySecondAuthValidateStage',
+     payload: { tempSid, trans: 'login' }
+   });
+   // Wait for stage === 'VALIDATED'
+   ```
+
+4. **Re-login** without password (auth already verified)
+
+5. **Proceed to getLunkrSession**
+
+### Step 6-10: Get Lunkr Session
+
+After successful Coremail login, obtain a Lunkr session:
+
+#### 6.1: Call cim.common:verify
+
+```typescript
+const verifyResp = await httpsPost(
+  'https://lunkr.coremail.cn/lunkr/s/json?func=cim.common:verify',
+  '{}',
+  { Cookie: `Coremail=${coremailCookie}` }
+);
+// Returns: { login_key, login_index }
+```
+
+#### 6.2: Generate X-CM-TOKEN
+
+```typescript
+const dataToEncrypt = `${coremailSid}:${coremailCookie}`;
+const dataB64 = Buffer.from(dataToEncrypt).toString('base64');
+const xCmToken = encryptWithLoginKey(dataB64, loginKey);
+```
+
+#### 6.3: Call cim.user:login
+
+```typescript
+const loginResp = await httpsPost(
+  'https://lunkr.coremail.cn/lunkr/s/json?func=cim.user:login',
+  {
+    uid: email,
+    device: { uuid, os, model, friendlyName },
+    forceCookieCheck: true,
+    setCookieKey: true,
+    login_index: loginIndex
+  },
+  { 'X-CM-TOKEN': xCmToken }
+);
+// Returns: { sid, self_uid }
+// Set-Cookie header: Cim=...
+```
+
+## Session Data
+
+### Coremail Session
+
+```typescript
+{
+  sid: string,         // Coremail session ID
+  cookie: string,      // Coremail=...
+  baseUrl: string,     // e.g., https://mail.example.com
+  apiPath: string      // e.g., /coremail/s/json
+}
+```
+
+### Lunkr Session
+
+```typescript
+{
+  sid: string,         // Lunkr session ID
+  selfUid: string,     // User's Lunkr ID
+  cookie: string,      // Cim=...
+  baseUrl: string,     // https://lunkr.coremail.cn
+  apiPath: string      // /lunkr/s/json
+}
+```
+
+## Key Difference
+
+The critical difference is:
+
+- **Coremail session** is for the email server API
+- **Lunkr session** is for the collaboration platform API
+
+Both OTP flow and normal login flow must call `getLunkrSession()` to convert the Coremail session to a Lunkr session. The bug fixed in this version was that the OTP flow was returning the Coremail session directly instead of calling `getLunkrSession()`.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `PasswordError` | Wrong password | Check credentials |
+| `FA_NEED_VERIFY_CODE` | Captcha required | Login via webmail first |
+| `FA_USER_IN_GRAYLIST` | Account restricted | Contact admin |
+| `No Coremail cookie` | Login incomplete | Check server response |
+| `cim.common:verify failed` | Session invalid | Re-login required |
+
+## Session Validation
+
+Sessions are validated periodically (every 5 minutes) by calling:
+
+```typescript
+await client.checkSessionValid(sid);
+```
+
+If the session is invalid, the user must re-authenticate.

package/docs/CHEATSHEET.md

@@ -0,0 +1,112 @@
+# 命令速查表
+
+## npm scripts
+
+### 开发调试
+
+```bash
+npm run dev              # 热重载开发模式
+npm run dev:cli          # 直接运行 CLI (不编译)
+
+# 调试单个命令
+npx tsx src/bin/lunkr-cli.ts status
+npx tsx src/bin/lunkr-cli.ts login
+```
+
+### 测试
+
+```bash
+npm test                 # 运行测试
+npm run test:watch       # 测试监视模式
+npm run lint             # 代码检查
+```
+
+### 构建
+
+```bash
+npm run clean            # 清理 dist/
+npm run build            # 编译 TypeScript
+npm run build:release    # 生产构建 (esbuild)
+```
+
+### 部署
+
+```bash
+npm run deploy:local     # 快速部署 (仅复制)
+npm run deploy:local:full # 完整: clean → test → build → deploy
+```
+
+### 版本与发布
+
+```bash
+npm version patch        # 提升补丁版本 (1.0.0 → 1.0.1)
+npm version minor        # 提升小版本 (1.0.0 → 1.1.0)
+npm version major        # 提升大版本 (1.0.0 → 2.0.0)
+
+npm run pack             # 打包 .tgz
+npm publish              # 发布到 npm
+git push --follow-tags   # 推送代码和标签
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OPENCLAW_ROOT` | `~/work/ai/openclaw` | OpenClaw 根目录 |
+| `OPENCLAW_EXT` | `$OPENCLAW_ROOT/extensions` | 扩展目录 |
+| `LUNKR_LANG` | 自动检测 | 语言 (zh-CN, en-US) |
+
+## 典型工作流
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  开发                                                   │
+├─────────────────────────────────────────────────────────┤
+│  npm run test:watch    # 开着测试监视                   │
+│  # 编写代码...                                          │
+│  npm run deploy:local  # 快速部署测试                   │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  发布前验证                                             │
+├─────────────────────────────────────────────────────────┤
+│  npm run deploy:local:full  # 完整流程                  │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  打包/发布                                              │
+├─────────────────────────────────────────────────────────┤
+│  npm version patch   # 提升版本号                       │
+│  git push --follow-tags  # 推送代码和标签               │
+│  npm run pack        # 生成 .tgz (可选)                 │
+│  npm publish         # 发布到 npm                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+## CLI 命令
+
+```bash
+# 认证
+openclaw lunkr login --email <email>      # 登录
+openclaw lunkr login --email <email> --password <pwd>  # 密码登录
+openclaw lunkr logout                     # 登出
+openclaw lunkr status                     # 状态
+
+# 消息
+openclaw lunkr send -t <uid> -m "hello"   # 发送消息
+openclaw lunkr send-file -t <uid> -f file.pdf  # 发送文件
+openclaw lunkr download --file-id <id>    # 下载文件
+
+# 搜索
+openclaw lunkr search-contact <keyword>   # 搜索联系人
+openclaw lunkr search-group <keyword>     # 搜索讨论组
+
+# Bot 讨论
+openclaw lunkr create <name>              # 创建 Bot 讨论
+openclaw lunkr bot-list                   # 列出 Bot 讨论
+openclaw lunkr bot-delete --name <name>   # 删除 Bot 讨论
+
+# 其他
+openclaw lunkr list-msg -t <uid>          # 列出消息
+openclaw lunkr listen                     # 监听实时消息
+```

package/docs/DEVELOPMENT.md

@@ -0,0 +1,239 @@
+# Lunkr Extension 开发指南
+
+本文档提供 Lunkr 扩展的完整开发、测试和部署命令参考。
+
+## 快速参考
+
+| 场景 | 命令 |
+|------|------|
+| 安装依赖 | `npm install` |
+| 运行测试 | `npm test` |
+| 测试监视模式 | `npm run test:watch` |
+| 编译 | `npm run build` |
+| 快速部署 | `npm run deploy:local` |
+| 完整部署 | `npm run deploy:local:full` |
+| 打包发布 | `npm run pack` |
+
+## 开发工作流
+
+### 1. 日常开发
+
+```bash
+# 终端 1: 运行测试监视器
+npm run test:watch
+
+# 终端 2: 编辑代码...
+# 测试会自动运行
+```
+
+### 2. 调试 CLI 命令
+
+直接运行 TypeScript，无需编译：
+
+```bash
+# 使用 tsx 直接运行
+npx tsx src/bin/lunkr-cli.ts status
+npx tsx src/bin/lunkr-cli.ts login --email your@email.com
+npx tsx src/bin/lunkr-cli.ts search-contact test
+```
+
+### 3. 在 OpenClaw 中测试
+
+```bash
+# 快速部署（假设已编译）
+npm run deploy:local
+
+# 或完整流程：清理 → 测试 → 编译 → 部署
+npm run deploy:local:full
+
+# 测试
+openclaw lunkr status
+```
+
+## 命令详解
+
+### 开发命令
+
+| 命令 | 说明 |
+|------|------|
+| `npm run dev` | 热重载开发模式（监视文件变化） |
+| `npm run dev:cli` | 直接运行 CLI（不编译） |
+
+### 测试命令
+
+| 命令 | 说明 |
+|------|------|
+| `npm test` | 运行所有测试 |
+| `npm run test:watch` | 监视模式，文件变化自动重跑 |
+| `npm run lint` | 代码检查 |
+
+### 构建命令
+
+| 命令 | 说明 |
+|------|------|
+| `npm run clean` | 清理 dist/ 目录 |
+| `npm run build` | 编译 TypeScript → dist/ |
+| `npm run build:release` | 生产构建（esbuild 打包） |
+
+### 部署命令
+
+| 命令 | 说明 |
+|------|------|
+| `npm run deploy:local` | 快速部署到本地 OpenClaw（仅复制） |
+| `npm run deploy:local:full` | 完整部署：clean → test → build → deploy |
+
+### 发布命令
+
+| 命令 | 说明 |
+|------|------|
+| `npm run pack` | 打包为 .tgz 文件 |
+| `npm publish` | 发布到 npm registry |
+
+## 部署目标配置
+
+默认部署路径：
+```
+~/work/ai/openclaw/extensions/lunkr
+```
+
+可通过环境变量自定义：
+
+```bash
+# 自定义 OpenClaw 根目录
+export OPENCLAW_ROOT=/path/to/openclaw
+npm run deploy:local
+
+# 或自定义扩展目录
+export OPENCLAW_EXT=/custom/extensions/path
+npm run deploy:local
+```
+
+## 典型工作日
+
+```bash
+# 早上开始工作
+cd extensions/lunkr
+npm run test:watch          # 终端 1: 开着测试
+
+# 编写代码...
+# 测试自动运行
+
+# 中午想集成测试
+npm run deploy:local        # 快速部署（跳过测试，因为刚才测过了）
+
+# 继续开发...
+
+# 下班前提交
+npm run deploy:local:full   # 完整流程确保没问题
+```
+
+## 发布流程
+
+### 版本管理
+
+使用语义化版本号 (SemVer)：`MAJOR.MINOR.PATCH`
+
+```bash
+# 补丁版本 - bug fixes
+npm version patch   # 1.0.0 → 1.0.1
+
+# 小版本 - 新功能，向后兼容
+npm version minor   # 1.0.1 → 1.1.0
+
+# 大版本 - 破坏性变更
+npm version major   # 1.1.0 → 2.0.0
+```
+
+`npm version` 命令会：
+1. 更新 `package.json` 中的版本号
+2. 自动创建 git commit
+3. 自动创建 git tag
+
+### 打包测试
+
+```bash
+# 打包为 tar.gz
+npm run pack
+
+# 输出: coremail-lunkr-openclaw-1.0.0.tgz
+
+# 在其他地方测试安装
+npm install ./coremail-lunkr-openclaw-1.0.0.tgz
+```
+
+### 发布到 npm
+
+```bash
+# 1. 确保测试通过
+npm test
+
+# 2. 提升版本号
+npm version patch  # 或 minor / major
+
+# 3. 推送代码和标签
+git push --follow-tags
+
+# 4. 发布到 npm
+npm publish --access public
+```
+
+## 项目结构
+
+```
+extensions/lunkr/
+├── src/                    # TypeScript 源码
+│   ├── adapters/           # OpenClaw 适配器
+│   ├── cli/                # CLI 命令
+│   ├── core/               # 核心逻辑
+│   ├── i18n/               # 国际化
+│   ├── internal/           # 内部模块
+│   └── index.ts            # 入口
+├── dist/                   # 编译输出
+├── skills/                 # OpenClaw 技能
+├── docs/                   # 文档
+├── scripts/                # 构建脚本
+│   ├── deploy-local.mjs    # 本地部署
+│   └── build-release.js    # 生产构建
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 环境要求
+
+- **Node.js**: v22+
+- **npm**: v10+
+- **TypeScript**: v5+
+
+## 故障排除
+
+### 编译失败
+
+```bash
+# 清理后重试
+npm run clean
+npm run build
+```
+
+### 部署后不生效
+
+```bash
+# 确保 OpenClaw gateway 重启
+openclaw gateway restart
+
+# 或重启整个服务
+openclaw restart
+```
+
+### 测试失败
+
+```bash
+# 查看详细输出
+npm test -- --reporter=verbose
+```
+
+## 相关文档
+
+- [README.md](../README.md) - 项目介绍和配置
+- [USAGE.md](./USAGE.md) - 使用指南
+- [AUTHENTICATION.md](./AUTHENTICATION.md) - 认证说明