03-安全机制

# 安全机制

> **文档版本**: v1.0.0
> **创建日期**: 2024-01-25
> **最后更新**: 2024-01-25
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 开放平台, 安全机制, 认证授权, 数据加密

---

## &#128203; 目录

- [1. 安全架构](#1-安全架构)
- [2. 认证安全](#2-认证安全)
- [3. 权限控制](#3-权限控制)
- [4. 数据安全](#4-数据安全)
- [5. 安全配置](#5-安全配置)
- [6. 安全检查清单](#6-安全检查清单)

---

## 1. 安全架构

### 1.1 安全层次模型

```
┌─────────────────────────────────────────────────────────────────┐
│                       应用安全层                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ 认证鉴权  │ │ 权限控制  │ │ 数据脱敏  │ │ 输入校验  │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                       传输安全层                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ HTTPS    │ │ 证书校验  │ │ 请求签名  │ │ 防重放   │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                       数据安全层                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ 敏感加密  │ │ 数据备份  │ │ 访问审计  │ │ 数据隔离  │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

### 1.2 安全防护体系

| 防护层 | 安全措施 | 防护目标 |
|--------|---------|---------|
| 网络层 | DDoS防护、WAF、IP白名单 | 网络攻击、恶意访问 |
| 传输层 | HTTPS、证书校验、请求签名 | 中间人攻击、数据篡改 |
| 应用层 | 认证鉴权、权限控制、输入校验 | 未授权访问、注入攻击 |
| 数据层 | 敏感加密、数据脱敏、访问审计 | 数据泄露、违规访问 |

---

## 2. 认证安全

### 2.1 API Key 安全策略

#### 密钥生成规则

```
API Key 格式: {prefix}_{env}_{random}

- prefix: 密钥类型前缀 (ak=API Key, sk=Secret Key)
- env: 环境标识 (live=生产, test=测试)
- random: 32位随机字符串

示例:
  API Key:    ak_live_abc123def456ghi789jkl012mno345pqr
  API Secret: sk_live_stu678vwx901yza234bcd567efg890hij
```

#### 密钥生命周期管理

| 阶段 | 说明 | 操作 |
|------|------|------|
| 创建 | 生成密钥对 | 加密存储 |
| 激活 | 启用密钥 | 状态变更 |
| 使用 | 正常调用 | 记录日志 |
| 轮换 | 定期更换 | 推荐90天 |
| 废弃 | 标记废弃 | 保留30天 |
| 删除 | 物理删除 | 数据清理 |

### 2.2 请求签名机制

#### 签名算法

```typescript
/**
 * 请求签名生成
 */
function generateSignature(
  method: string,
  path: string,
  timestamp: number,
  nonce: string,
  body: string,
  apiSecret: string
): string {
  // 1. 构造签名字符串
  const parts = [
    method.toUpperCase(),
    path,
    timestamp.toString(),
    nonce,
    body ? crypto.createHash('md5').update(body).digest('hex') : ''
  ];
  const signatureString = parts.join('\n');

// 2. HMAC-SHA256签名
  const hmac = crypto.createHmac('sha256', apiSecret);
  hmac.update(signatureString);
  
  // 3. Base64编码
  return hmac.digest('base64');
}
```

#### 签名验证流程

```
1. 检查时间戳有效性 (±5分钟内)
2. 检查Nonce唯一性 (Redis缓存)
3. 获取API Secret
4. 重新计算签名
5. 签名验证通过
```

### 2.3 防重放攻击

```typescript
// 使用Redis存储Nonce，设置5分钟过期
async function checkNonce(nonce: string): Promise<boolean> {
  const key = `nonce:${nonce}`;
  const exists = await redis.exists(key);
  
  if (exists) {
    return false; // Nonce已存在，拒绝请求
  }
  
  // 存储Nonce，5分钟过期
  await redis.setex(key, 300, '1');
  return true;
}
```

---

## 3. 权限控制

### 3.1 RBAC 权限模型

```
┌──────────┐         ┌──────────┐         ┌──────────┐
│   用户   │────────▶│   角色   │────────▶│   权限   │
│  (User)  │  分配    │  (Role)  │  包含    │(Permission)│
└──────────┘         └──────────┘         └──────────┘
     │                    │                     │
     │                    ▼                     │
     │              ┌──────────┐                │
     └─────────────▶│  应用    │◀───────────────┘
                    │  (App)   │    授权
                    └──────────┘
```

### 3.2 数据权限隔离

| 隔离方式 | 说明 | 实现方式 |
|---------|------|---------|
| 按公司隔离 | 应用只能访问授权公司数据 | company_id 过滤 |
| 按应用隔离 | 应用间数据完全隔离 | app_id 标识 |
| 行级安全 | 数据库层面强制隔离 | RLS 策略 |

### 3.3 接口权限控制

```typescript
// 权限装饰器
function RequirePermission(permission: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    
    descriptor.value = async function (...args: any[]) {
      const context = args[0];
      
      // 检查权限
      const hasPermission = await checkPermission(context.appId, permission);
      
      if (!hasPermission) {
        throw new ForbiddenError(`缺少权限: ${permission}`);
      }
      
      return originalMethod.apply(this, args);
    };
  };
}
```

---

## 4. 数据安全

### 4.1 敏感数据加密

#### 加密策略

| 数据类型 | 加密算法 | 密钥管理 |
|---------|---------|---------|
| API Secret | AES-256-GCM | 主密钥加密 |
| 身份证号 | AES-256-CBC | 应用密钥 |
| 手机号 | AES-256-CBC | 应用密钥 |
| 银行卡号 | AES-256-CBC | 应用密钥 |
| 密码/密钥 | bcrypt/Argon2 | 单向哈希 |

#### 加密实现

```typescript
// 敏感数据加密
function encryptSensitiveData(plaintext: string, key: Buffer): string {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  
  let encrypted = cipher.update(plaintext, 'utf8', 'base64');
  encrypted += cipher.final('base64');
  
  return iv.toString('base64') + ':' + encrypted;
}
```

### 4.2 数据脱敏

```typescript
// 脱敏规则
const MASKING_RULES = {
  // 手机号: 138****1234
  phone: (value: string) => value.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'),
  
  // 身份证: 110101********1234
  idCard: (value: string) => value.replace(/(\d{6})\d{8}(\d{4})/, '$1********$2'),
  
  // 银行卡: 6222 **** **** 1234
  bankCard: (value: string) => value.replace(/(\d{4})\d{8}(\d{4})/, '$1 **** **** $2'),
  
  // 姓名: 张*
  name: (value: string) => value.charAt(0) + '*'.repeat(value.length - 1)
};
```

### 4.3 审计日志

#### 审计事件类型

| 类型 | 编码 | 说明 |
|------|------|------|
| 认证事件 | auth.* | 登录、登出、令牌刷新 |
| API事件 | api.* | 接口调用、错误记录 |
| 数据事件 | data.* | 增删改查、导出操作 |
| 管理事件 | admin.* | 密钥管理、权限变更 |

#### 审计日志格式

```json
{
  "id": "audit_123",
  "event_type": "api.call",
  "timestamp": "2024-01-15T10:30:00Z",
  "actor": {
    "type": "app",
    "id": "app_123",
    "name": "SCMR系统"
  },
  "resource": {
    "type": "employee",
    "id": "emp_456"
  },
  "action": {
    "method": "GET",
    "path": "/v1/employees/emp_456",
    "ip": "192.168.1.100"
  },
  "result": {
    "status": "success",
    "status_code": 200
  }
}
```

---

## 5. 安全配置

### 5.1 安全响应头

```typescript
const securityHeaders = {
  'X-Content-Type-Options': 'nosniff',
  'X-Frame-Options': 'DENY',
  'X-XSS-Protection': '1; mode=block',
  'Strict-Transport-Security': 'max-age=31536000',
  'Content-Security-Policy': "default-src 'self'"
};
```

### 5.2 CORS配置

```typescript
const corsConfig = {
  origin: ['https://app.example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Api-Key'],
  credentials: true,
  maxAge: 86400
};
```

---

## 6. 安全检查清单

### 6.1 开发阶段

- [ ] 所有 API 接口必须有认证
- [ ] 敏感数据必须加密存储
- [ ] 输入数据必须校验和转义
- [ ] 使用参数化查询防止 SQL 注入
- [ ] 禁止在日志中输出敏感信息
- [ ] 禁止硬编码密钥和密码

### 6.2 测试阶段

- [ ] 执行渗透测试
- [ ] 执行代码安全审计
- [ ] 执行依赖漏洞扫描
- [ ] 测试认证绕过场景
- [ ] 测试权限提升场景

### 6.3 上线阶段

- [ ] 配置 HTTPS 证书
- [ ] 配置 WAF 规则
- [ ] 配置 DDoS 防护
- [ ] 启用审计日志
- [ ] 配置安全告警

### 6.4 运维阶段

- [ ] 定期更新依赖版本
- [ ] 定期轮换密钥
- [ ] 定期审查权限配置
- [ ] 定期备份审计日志
- [ ] 监控异常行为