README.md

---
title: HF OAuth Demo
emoji: 🔐
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
hf_oauth: true
hf_oauth_scopes:
  - inference-api
---

# HF OAuth Demo

一个基于 Node.js + Express 的 Hugging Face OAuth 测试应用，部署为 Hugging Face Docker Space。支持 OAuth 登录流程测试、Token 换取、UserInfo 查询以及 Hugging Face API（models/datasets/spaces）代理调用。

## 项目结构

```
hf-oauth-demo/
├── server.js              # 后端服务主文件，OAuth 流程入口
├── oauth_endpoints.js     # OAuth 端点代理（token/userinfo/jwks/register）
├── api_endpoints.js       # Hugging Face API 代理（whoami/models/datasets/spaces）
├── public/
│   ├── index.html         # 登录引导页
│   ├── callback_success.html  # 授权成功页
│   └── test_interface.html    # API 测试工具
├── Dockerfile             # Docker Space 构建文件
├── package.json           # 项目依赖
├── .env.example           # 本地开发环境变量模板
└── README.md              # 项目说明
```

## 本地开发

1. 安装依赖：
   ```bash
   npm install
   ```

2. 复制环境变量模板并填写：
   ```bash
   cp .env.example .env
   ```

3. 启动服务：
   ```bash
   npm start
   ```

4. 访问 http://127.0.0.1:7860 开始测试。

## 部署到 Hugging Face Spaces

```bash
# 创建 Docker Space（仅需执行一次）
hf repos create iSolver-AI/hf-oauth-demo --type space --space-sdk docker

# 添加远程仓库并推送
git remote add hf https://huggingface.co/spaces/iSolver-AI/hf-oauth-demo.git
git push hf master:main
```

推送后，Space 会自动构建并运行。由于 `README.md` 中已配置 `hf_oauth: true`，Hugging Face 会自动创建 OAuth app 并注入以下环境变量：

- `OAUTH_CLIENT_ID`
- `OAUTH_CLIENT_SECRET`
- `OAUTH_SCOPES`
- `SPACE_HOST`

访问地址：https://isolver-ai-hf-oauth-demo.hf.space

## 功能说明

### OAuth 流程

- `GET /login`：直接重定向到 Hugging Face 授权页
- `GET /api/oauth/start`：返回授权 URL（测试模式，不自动重定向）
- `GET /api/oauth/code/:state`：查询指定 state 关联的授权码
- `GET /callback`：接收授权码并保存到 state，重定向到测试页面
- `POST /api/oauth/token`：用 code 换取 access_token
- `GET /api/oauth/userinfo`：获取当前用户信息
- `GET /api/oauth/jwks`：获取 JWKS
- `POST /api/oauth/register`：动态客户端注册

### Hugging Face API 代理

- `GET /api/whoami`：当前用户信息
- `GET /api/models/:owner`：指定用户的模型列表
- `GET /api/datasets/:owner`：指定用户的数据集列表
- `GET /api/spaces/:owner`：指定用户的 Spaces 列表
- `GET /api/models/:owner/:repo`：模型详情
- `GET /api/datasets/:owner/:repo`：数据集详情
- `GET /api/spaces/:owner/:repo`：Space 详情

## 安全说明

- `client_id` / `client_secret` 仅保存在服务端环境变量中，不暴露给前端。
- 本地开发时使用 `.env` 文件，生产环境（Hugging Face Space）由平台自动注入。
- `.env` 已加入 `.gitignore`，避免误提交到仓库。