# Tauri 安全配置详细指南

基于 Tauri CLI Schema v2.6.2 的完整安全配置说明文档

## 📋 目录

- [SecurityConfig 安全配置](#securityconfig-安全配置)
- [CSP 内容安全策略](#csp-内容安全策略)
- [AssetProtocol 资源协议](#assetprotocol-资源协议)
- [最佳实践建议](#最佳实践建议)
- [常见配置示例](#常见配置示例)

---

## SecurityConfig 安全配置

### 📖 概述
`SecurityConfig` 是 Tauri 应用程序的核心安全配置对象，控制着应用的安全策略、内容安全策略(CSP)、资源访问协议等关键安全特性。

### 🔧 配置结构

```json
{
  "app": {
    "security": {
      "csp": "...",
      "devCsp": "...",
      "assetProtocol": {...},
      "dangerousDisableAssetCspModification": false,
      "freezePrototype": false,
      "pattern": {...},
      "capabilities": [...],
      "headers": {...}
    }
  }
}
```

---

## CSP 内容安全策略

### 📖 定义
Content Security Policy (CSP) 是一个重要的安全层，用于检测和减轻某些类型的攻击，包括跨站脚本 (XSS) 和数据注入攻击。

### 🔧 配置选项

#### 1. `csp` - 生产环境CSP
```json
{
  "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'"
}
```

**类型**: `string | object | null`
**默认值**: `null`
**用途**: 
- 定义生产环境下的内容安全策略
- 如果未设置 `devCsp`，开发环境也会使用此配置
- 控制哪些资源可以被加载和执行

#### 2. `devCsp` - 开发环境CSP
```json
{
  "devCsp": "default-src 'self' 'unsafe-eval'; script-src 'self' 'unsafe-inline'"
}
```

**类型**: `string | object | null`
**默认值**: `null`
**用途**:
- 专门用于开发环境的CSP配置
- 通常比生产环境更宽松，允许热重载等开发工具

### 📝 CSP 指令说明

#### 字符串格式
```json
{
  "csp": "default-src 'self'; img-src 'self' data: asset: http://asset.localhost; media-src 'self' asset: http://asset.localhost"
}
```

#### 对象格式
```json
{
  "csp": {
    "default-src": ["'self'"],
    "img-src": ["'self'", "data:", "asset:", "http://asset.localhost"],
    "media-src": ["'self'", "asset:", "http://asset.localhost"],
    "script-src": ["'self'", "'unsafe-inline'"],
    "style-src": ["'self'", "'unsafe-inline'"]
  }
}
```

### 🎯 常用CSP指令

| 指令 | 说明 | 示例值 |
|------|------|--------|
| `default-src` | 默认源策略 | `'self'` |
| `script-src` | JavaScript源 | `'self' 'unsafe-inline'` |
| `style-src` | CSS样式源 | `'self' 'unsafe-inline'` |
| `img-src` | 图片源 | `'self' data: asset:` |
| `media-src` | 媒体源 | `'self' asset:` |
| `connect-src` | 连接源 | `'self' ipc: http://ipc.localhost` |
| `font-src` | 字体源 | `'self' data:` |

---

## AssetProtocol 资源协议

### 📖 定义
AssetProtocol 配置控制 Tauri 的自定义资源协议，允许前端安全地访问本地文件系统资源。

### 🔧 配置结构

```json
{
  "assetProtocol": {
    "enable": true,
    "scope": ["**"]
  }
}
```

#### 1. `enable` - 启用资源协议
**类型**: `boolean`
**默认值**: `false`
**用途**:
- 控制是否启用 `asset://` 协议
- 启用后可以通过 `convertFileSrc()` 访问本地文件

#### 2. `scope` - 访问范围
**类型**: `string[]`
**默认值**: `[]`
**用途**:
- 定义资源协议可以访问的文件路径范围
- 使用 glob 模式匹配路径
- 空数组表示禁止访问任何文件

### 📝 Scope 配置示例

#### 允许访问所有文件 (⚠️ 不推荐)
```json
{
  "scope": ["**"]
}
```

#### 限制访问特定目录
```json
{
  "scope": [
    "$APPDATA/myapp/**",
    "$RESOURCE/**",
    "/Users/*/Documents/myapp/**"
  ]
}
```

#### 使用环境变量
```json
{
  "scope": [
    "$HOME/.myapp/**",
    "$TEMP/myapp-cache/**"
  ]
}
```

---

## 高级安全配置

### 1. `dangerousDisableAssetCspModification`

**类型**: `boolean | string[]`
**默认值**: `false`
**用途**: 禁用 Tauri 的 CSP 自动注入

```json
{
  "dangerousDisableAssetCspModification": false
}
```

**⚠️ 警告**: 只有在完全理解安全影响时才禁用此功能

#### 禁用所有CSP修改
```json
{
  "dangerousDisableAssetCspModification": true
}
```

#### 禁用特定指令的修改
```json
{
  "dangerousDisableAssetCspModification": ["script-src", "style-src"]
}
```

### 2. `freezePrototype`

**类型**: `boolean`
**默认值**: `false`
**用途**: 冻结 `Object.prototype` 以防止原型污染攻击

```json
{
  "freezePrototype": true
}
```

### 3. `pattern` - 安全模式

**类型**: `object`
**用途**: 定义应用的安全模式

#### Brownfield 模式 (默认)
```json
{
  "pattern": {
    "use": "brownfield"
  }
}
```

#### Isolation 模式 (推荐)
```json
{
  "pattern": {
    "use": "isolation",
    "options": {
      "dir": "../dist-isolation"
    }
  }
}
```

---

## 最佳实践建议

### 🔒 安全级别配置

#### 高安全级别 (推荐生产环境)
```json
{
  "security": {
    "csp": "default-src 'self'; img-src 'self' asset: data:; media-src 'self' asset:; script-src 'self'; style-src 'self' 'unsafe-inline'",
    "assetProtocol": {
      "enable": true,
      "scope": ["$APPDATA/myapp/**", "$RESOURCE/**"]
    },
    "freezePrototype": true,
    "pattern": {
      "use": "isolation",
      "options": {
        "dir": "../dist-isolation"
      }
    }
  }
}
```

#### 中等安全级别 (开发友好)
```json
{
  "security": {
    "csp": "default-src 'self'; img-src 'self' asset: data: http://asset.localhost; media-src 'self' asset: http://asset.localhost; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'",
    "devCsp": "default-src 'self' 'unsafe-eval'; img-src 'self' asset: data: http://asset.localhost; media-src 'self' asset: http://asset.localhost; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'",
    "assetProtocol": {
      "enable": true,
      "scope": ["**"]
    },
    "freezePrototype": false
  }
}
```

### 🎯 针对不同场景的配置

#### 媒体应用 (视频/音频)
```json
{
  "security": {
    "csp": {
      "default-src": ["'self'"],
      "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"],
      "media-src": ["'self'", "asset:", "http://asset.localhost"],
      "video-src": ["'self'", "asset:", "http://asset.localhost"],
      "script-src": ["'self'", "'unsafe-inline'"],
      "style-src": ["'self'", "'unsafe-inline'"],
      "connect-src": ["'self'", "ipc:", "http://ipc.localhost"]
    },
    "assetProtocol": {
      "enable": true,
      "scope": ["$HOME/Videos/**", "$HOME/Music/**", "$APPDATA/myapp/**"]
    }
  }
}
```

#### 文件管理应用
```json
{
  "security": {
    "csp": "default-src 'self'; img-src 'self' asset: data: http://asset.localhost; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' ipc: http://ipc.localhost",
    "assetProtocol": {
      "enable": true,
      "scope": ["$HOME/**", "$DESKTOP/**", "$DOCUMENT/**"]
    }
  }
}
```

---

## 🚨 安全注意事项

### 1. CSP 配置
- ❌ 避免使用 `'unsafe-eval'` 在生产环境
- ❌ 谨慎使用 `'unsafe-inline'`
- ✅ 优先使用 nonce 或 hash 值
- ✅ 定期审查和更新 CSP 策略

### 2. AssetProtocol 配置
- ❌ 避免使用 `["**"]` 作为 scope
- ✅ 限制访问范围到必要的目录
- ✅ 使用环境变量定义路径
- ✅ 定期审查文件访问权限

### 3. 开发 vs 生产
- 开发环境可以适当放宽限制
- 生产环境必须严格控制安全策略
- 使用 `devCsp` 区分开发和生产配置

---

## 🔧 故障排除指南

### 常见CSP错误及解决方案

#### 1. 视频/音频无法播放
**错误**: `Refused to load media from 'asset://...' because it violates CSP`

**解决方案**:
```json
{
  "csp": {
    "media-src": ["'self'", "asset:", "http://asset.localhost"],
    "video-src": ["'self'", "asset:", "http://asset.localhost"]
  }
}
```

#### 2. 图片无法显示
**错误**: `Refused to load image from 'asset://...' because it violates CSP`

**解决方案**:
```json
{
  "csp": {
    "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"]
  }
}
```

#### 3. 内联样式被阻止
**错误**: `Refused to apply inline style because it violates CSP`

**解决方案**:
```json
{
  "csp": {
    "style-src": ["'self'", "'unsafe-inline'"]
  }
}
```

### AssetProtocol 故障排除

#### 1. 文件访问被拒绝
**错误**: `Asset protocol access denied`

**检查项目**:
- 确认 `assetProtocol.enable` 为 `true`
- 检查文件路径是否在 `scope` 范围内
- 验证文件是否存在且有读取权限

#### 2. Windows 路径问题
**问题**: Windows 绝对路径无法访问

**解决方案**:
```json
{
  "assetProtocol": {
    "enable": true,
    "scope": [
      "C:\\Users\\**",
      "$APPDATA\\**",
      "$LOCALAPPDATA\\**"
    ]
  }
}
```

---

## 📊 配置验证工具

### 1. CSP 验证
使用浏览器开发者工具检查 CSP 违规:
```javascript
// 在控制台中检查 CSP 策略
console.log(document.querySelector('meta[http-equiv="Content-Security-Policy"]').content);
```

### 2. AssetProtocol 测试
```javascript
// 测试资源协议是否工作
import { convertFileSrc } from '@tauri-apps/api/core';

const testPath = '/path/to/test/file.txt';
const assetUrl = convertFileSrc(testPath);
console.log('Asset URL:', assetUrl);

// 测试文件访问
fetch(assetUrl)
  .then(response => response.text())
  .then(data => console.log('File content:', data))
  .catch(error => console.error('Access denied:', error));
```

---

## 🎯 完整配置示例

### 视频编辑应用配置
```json
{
  "app": {
    "security": {
      "csp": {
        "default-src": ["'self'"],
        "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"],
        "media-src": ["'self'", "asset:", "http://asset.localhost"],
        "video-src": ["'self'", "asset:", "http://asset.localhost"],
        "script-src": ["'self'", "'unsafe-inline'"],
        "style-src": ["'self'", "'unsafe-inline'"],
        "connect-src": ["'self'", "ipc:", "http://ipc.localhost"],
        "font-src": ["'self'", "data:"]
      },
      "devCsp": {
        "default-src": ["'self'", "'unsafe-eval'"],
        "img-src": ["'self'", "asset:", "data:", "http://asset.localhost"],
        "media-src": ["'self'", "asset:", "http://asset.localhost"],
        "video-src": ["'self'", "asset:", "http://asset.localhost"],
        "script-src": ["'self'", "'unsafe-inline'", "'unsafe-eval'"],
        "style-src": ["'self'", "'unsafe-inline'"],
        "connect-src": ["'self'", "ipc:", "http://ipc.localhost", "ws:", "wss:"],
        "font-src": ["'self'", "data:"]
      },
      "assetProtocol": {
        "enable": true,
        "scope": [
          "$HOME/Videos/**",
          "$HOME/Movies/**",
          "$DESKTOP/**",
          "$DOCUMENT/**",
          "$APPDATA/mixvideo/**",
          "$TEMP/mixvideo/**"
        ]
      },
      "freezePrototype": false,
      "dangerousDisableAssetCspModification": false
    }
  }
}
```

### 文件管理器配置
```json
{
  "app": {
    "security": {
      "csp": "default-src 'self'; img-src 'self' asset: data: http://asset.localhost; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' ipc: http://ipc.localhost",
      "assetProtocol": {
        "enable": true,
        "scope": [
          "$HOME/**",
          "$DESKTOP/**",
          "$DOCUMENT/**",
          "$DOWNLOAD/**",
          "C:\\**",
          "/Users/**",
          "/home/**"
        ]
      },
      "freezePrototype": true
    }
  }
}
```

---

## 📚 参考资源

- [Tauri 官方安全文档](https://v2.tauri.app/security/)
- [MDN CSP 文档](https://developer.mozilla.org/docs/Web/HTTP/CSP)
- [Tauri 配置参考](https://v2.tauri.app/reference/config/)
- [CSP 评估工具](https://csp-evaluator.withgoogle.com/)

---

*最后更新: 2025-01-11*
*基于 Tauri CLI Schema v2.6.2*