Metadata-Version: 2.4
Name: he-sso
Version: 1.0.0
Summary: HappyElements SSO client — Python library and CLI tool
Project-URL: Homepage, https://github.com/xykong/ChatGPT
Author-email: "xy.kong" <xy.kong@gmail.com>
License: MIT
Keywords: authentication,cli,sso
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# he-sso

HappyElements SSO 客户端，提供 Python 函数 API 和命令行工具（CLI），用于在脚本或应用中获取当前用户的 SSO 认证信息。

## 安装

```bash
pip install he-sso
```

## 函数 API

```python
from he_sso import get_user_info, logout

# 获取用户信息（自动缓存 token，失效时触发浏览器登录）
info = get_user_info()
print(info["email"])
print(info["username"])
print(info["unique_id"])   # 工号
print(info["token"])       # SSO token

# 强制重新登录（忽略本地缓存）
info = get_user_info(refresh=True)

# 不自动开浏览器（适合 CI/无头环境，打印 URL 手动访问）
info = get_user_info(open_browser=False)

# 自定义服务地址
info = get_user_info(service_url="https://sso.example.com")

# 删除本地缓存
logout()
```

### 返回值结构

`get_user_info()` 返回一个字典：

```python
{
    "username": "张三",
    "unique_id": "12345",          # 工号
    "email": "zhangsan@example.com",
    "mobile": "13800138000",
    "mobile_area_code": "+86",
    "account_type": "employee",
    "login_channel": "wework",
    "token": "<sso-token>",
}
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SSO_SERVICE_URL` | SSO 服务根 URL | 内置默认地址 |
| `SSO_TOKEN_DIR` | 本地凭证目录 | `~/.config/happyelements-sso` |

> ⚠️ `token` 字段属于敏感信息，请勿将其写入日志或输出到不受控的位置。

## CLI

```bash
he-sso                              # 输出用户信息
he-sso --refresh                    # 强制重新登录
he-sso --json                       # JSON 格式输出（含 token）
he-sso --delete                     # 删除本地缓存
he-sso --no-browser                 # 不自动开浏览器
he-sso --service-url https://...    # 指定服务地址
he-sso --help                       # 查看所有选项
```

## 工作原理

1. 优先读取本地缓存 token（`~/.config/happyelements-sso/credentials.json`）
2. 向服务端验证 token 有效性
3. token 不存在或已失效时，创建浏览器登录会话并轮询直到认证完成
4. 新 token 自动保存到本地（目录权限 `0700`，文件权限 `0600`）

AppSecret 仅保存在服务端，客户端零配置。
