# client-access-gateway

**Repository Path**: git4chen/client-access-gateway

## Basic Information

- **Project Name**: client-access-gateway
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# client-access-gateway

三方系统调用管控网关。作为 API 提供方，面向外部客户端（Client）开放业务接口，通过 **OAuth 2.0 `client_credentials`** 认证调用方，并对每个请求实施**授权（scope）→ 状态 → 限流 → 审计**四层管控，保障接口安全与可追溯。

> 当前为 MVP：单实例部署，本地缓存（Caffeine）为唯一缓存层。

## 功能特性

- **客户端认证**：`client_credentials` 授权模式换令牌，凭证 BCrypt 哈希存储，有状态 Access Token 落 SQLite + 本地缓存校验
- **接口授权（scope）**：接口声明所需 scope，校验令牌携带的 scope 是否覆盖，不足返回 `403 INSUFFICIENT_SCOPE`
- **状态管控**：Client 禁用/启用、Token 吊销/黑名单，即时生效（`401 CLIENT_DISABLED` / `401 TOKEN_REVOKED`）
- **接口限流**：按 Client × 接口固定窗口限流，参数可配置（`429 RATE_LIMITED`）
- **调用审计**：每次调用同步落库，含 Client、接口、结果、耗时，可查询
- **验证控制台**：内嵌静态单页，可视化演示认证与五层管控，审计实时刷新、点击查看详情

## 技术栈

| 组件 | 说明 |
|------|------|
| Java | JDK 11 |
| Spring Boot | 2.7.18（Web + Validation） |
| MyBatis Plus | 3.5.5（ORM） |
| SQLite | 数据存储 |
| Caffeine | 本地缓存 |
| OAuth 2.0 | `client_credentials` 授权模式 |
| Spring Security Crypto | BCrypt |

## 快速开始

**前置**：JDK 11、Maven 3.6+。

```bash
# 打包
mvn clean package

# 启动（自动创建 data/ 目录与 SQLite 库，种子数据：demo / demo-read 两个客户端）
java -jar target/client-access-gateway-0.1.0.jar
```

启动后访问 **Verification Console**：<http://localhost:8080/>

### 内置演示客户端

| client_id | client_secret | scope | 用途 |
|-----------|---------------|-------|------|
| `demo` | `demo-secret` | read, write | 完整权限，演示 200 |
| `demo-read` | `demo-read-secret` | read | 仅读，演示 `403 INSUFFICIENT_SCOPE` |

## 核心接口

### 认证

```
POST /oauth/token
Content-Type: application/json
{"grantType":"client_credentials","clientId":"demo","clientSecret":"demo-secret"}
```

响应：`{"access_token":"...","token_type":"Bearer","expires_in":7200,"scope":["read","write"]}`

### 调用受管控接口

```
GET /api/orders          # 需 scope=read
POST /api/orders         # 需 scope=write
Authorization: Bearer <access_token>
```

### 管控运维（Verification Console 内部使用）

| 接口 | 说明 |
|------|------|
| `POST /internal/control/revoke-token?tokenHash=` | 吊销令牌 |
| `POST /internal/control/disable-client?clientId=` | 禁用 Client |
| `DELETE /internal/control/disable-client?clientId=` | 重新启用 Client |
| `POST /internal/control/refresh-cache` | 重置缓存 / 限流 |
| `GET /internal/control/audit?limit=N` | 查询最近审计记录 |

## 管控链

```
认证 → 授权(scope) → 状态/黑名单 → 限流 → 审计
```

| 层 | 判定 | 失败返回 |
|----|------|---------|
| 认证 | Bearer 令牌有效、未过期、未吊销 | `401` |
| 授权 | 令牌 scope 覆盖接口所需 scope | `403 INSUFFICIENT_SCOPE` |
| 状态 | Client 启用 / 令牌未黑名单 | `401 CLIENT_DISABLED` / `401 TOKEN_REVOKED` |
| 限流 | Client×接口 窗口内未超限 | `429 RATE_LIMITED` |
| 审计 | 记录每次调用 | — |

统一错误体：`{"code":"...","message":"..."}`。

## 项目结构

```
src/main/java/com/example/accesscontrol
├── controller/   # /oauth/token、受管控接口、管控运维接口
├── filter/       # 认证 + 管控过滤链
├── service/      # 认证/令牌/授权/状态/限流/审计
├── cache/        # Caffeine 本地缓存
├── mapper/       # MyBatis Plus Mapper
├── entity/       # SQLite 表实体
├── security/     # BCrypt / SHA-256
├── exception/    # 错误码
└── config/       # 配置、种子数据、异常处理
src/main/resources/static/index.html   # Verification Console
```

## 文档索引

- 方案说明：`docs/access-control-mvp.md`、`docs/frontend-verification-mvp.md`
- 决策记录（ADR）：`docs/adr/0001` ~ `0006`
- 术语表：`CONTEXT.md`
- Spec / Design / Tickets：`.scratch/access-control-mvp/`

## 路线（Out of Scope 于 MVP）

- 管理 API（`/admin`）增删改 Client 与 scope
- 多实例部署 / 集中缓存（Redis）
- 审计异步落库与报表分析
- 限流参数热更新、复杂限流算法