fenghuo/packages/oidc-provider/README.md

# OIDC Provider

OpenID Connect Provider 实现，支持标准的 OIDC 协议流程。

## 特性

- 完整的 OIDC 协议支持
- 密码认证策略
- 会话管理
- 令牌管理（访问令牌、刷新令牌、ID令牌）
- PKCE 支持
- 可自定义的存储适配器

## 快速开始

### 1. 安装

```bash
npm install @nice/oidc-provider
```

### 2. 配置

```typescript
import { createOIDCProvider } from '@nice/oidc-provider/middleware/hono';
import { MemoryStorageAdapter } from '@nice/oidc-provider/storage';

const config = {
    issuer: 'https://your-domain.com',
    signingKey: 'your-signing-key',
    storage: new MemoryStorageAdapter(),
    
    // 用户和客户端查找函数
    findUser: async (userId: string) => {
        // 从数据库查找用户
        return await db.user.findUnique({ where: { id: userId } });
    },
    
    findClient: async (clientId: string) => {
        // 从数据库查找客户端
        return await db.client.findUnique({ where: { id: clientId } });
    },
    
    // 认证配置
    authConfig: {
        // 密码验证器
        passwordValidator: async (username: string, password: string) => {
            const user = await db.user.findUnique({ where: { username } });
            if (user && await bcrypt.compare(password, user.hashedPassword)) {
                return user.id;
            }
            return null;
        },
        
        // 会话配置
        sessionTTL: 24 * 60 * 60, // 24小时
        rememberMeMaxAge: 30 * 24 * 60 * 60, // 30天
        
        // 页面配置
        pageConfig: {
            title: '用户登录',
            brandName: '我的应用',
            logoUrl: '/logo.png'
        }
    }
};

// 创建 OIDC Provider Hono 应用
const oidcApp = createOIDCProvider(config);
```

### 3. 集成到 Hono 应用

```typescript
import { Hono } from 'hono';

const app = new Hono();

// 挂载 OIDC Provider
app.route('/oidc', oidcApp);

export default app;
```

## API 端点

创建后的 OIDC Provider 将提供以下标准端点：

- `POST /login` - 用户登录
- `GET /logout` - 用户登出
- `POST /logout` - 用户登出（POST 方式）
- `GET /.well-known/openid-configuration` - OIDC 发现文档
- `GET /.well-known/jwks.json` - JSON Web Key Set
- `GET /auth` - 授权端点
- `POST /token` - 令牌端点
- `GET /userinfo` - 用户信息端点
- `POST /revoke` - 令牌撤销端点
- `POST /introspect` - 令牌内省端点

## 配置选项

### OIDCProviderConfig

| 字段 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `issuer` | string | ✓ | 发行者标识符 |
| `signingKey` | string | ✓ | JWT 签名密钥 |
| `storage` | StorageAdapter | ✓ | 存储适配器 |
| `findUser` | function | ✓ | 用户查找函数 |
| `findClient` | function | ✓ | 客户端查找函数 |
| `authConfig` | AuthConfig | - | 认证配置 |
| `tokenTTL` | TokenTTLConfig | - | 令牌过期时间配置 |

### AuthConfig

| 字段 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `passwordValidator` | function | - | 密码验证函数 |
| `sessionTTL` | number | - | 会话过期时间（秒） |
| `rememberMeMaxAge` | number | - | 记住我最长时间（秒） |
| `pageConfig` | PageConfig | - | 登录页面配置 |

### PageConfig

| 字段 | 类型 | 描述 |
|------|------|------|
| `title` | string | 登录页面标题 |
| `brandName` | string | 品牌名称 |
| `logoUrl` | string | Logo URL |

## 存储适配器

项目提供了多种存储适配器：

- `MemoryStorageAdapter` - 内存存储（适用于开发和测试）
- `RedisStorageAdapter` - Redis 存储
- `DatabaseStorageAdapter` - 数据库存储

### 自定义存储适配器

```typescript
import { StorageAdapter } from '@nice/oidc-provider/storage';

class CustomStorageAdapter implements StorageAdapter {
    // 实现所需的方法
}
```

## 安全考虑

1. **签名密钥安全**：确保 `signingKey` 足够复杂且妥善保管
2. **HTTPS**：生产环境必须使用 HTTPS
3. **客户端验证**：实现严格的客户端验证逻辑
4. **密码策略**：在 `passwordValidator` 中实现适当的密码策略

## 许可证

MIT