understanding-tauri-runtime-authority

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tauri Runtime Authority

The runtime authority is a core Tauri component that enforces security policies during application execution. It validates permissions, resolves capabilities, and injects scopes before commands execute.

Runtime Authority是Tauri的核心组件，负责在应用执行期间实施安全策略。它会验证权限、解析能力，并在命令执行前注入作用域。

What Is Runtime Authority?

什么是Runtime Authority？

Runtime authority is the enforcement layer that sits between the WebView frontend and Tauri commands. It acts as a gatekeeper for all IPC (Inter-Process Communication) requests.

Runtime Authority是位于WebView前端与Tauri命令之间的执行层，充当所有IPC（进程间通信）请求的守门人。

Core Function

核心功能

When a webview invokes a Tauri command, the runtime authority:

Receives the invoke request from the webview
Validates the origin is permitted to call the requested command
Confirms the origin belongs to applicable capabilities
Injects defined scopes into the request
Passes the validated request to the Tauri command

If the origin is not allowed, the request is denied and the command never executes.

当WebView调用Tauri命令时，Runtime Authority会执行以下操作：

接收来自WebView的调用请求
验证发起请求的源是否被允许调用该命令
确认该源属于适用的capability（能力）
将定义的作用域注入到请求中
将验证通过的请求传递给Tauri命令

如果源不被允许，请求会被拒绝，命令永远不会执行。

Trust Boundary Model

信任边界模型

Tauri implements a trust boundary separating Rust core code from WebView frontend code:

Zone	Trust Level	Access
Rust Core	Full trust	Unrestricted system access
WebView Frontend	Limited trust	Only exposed resources via IPC

The runtime authority enforces this boundary at execution time.

Tauri实现了一个信任边界，将Rust核心代码与WebView前端代码分隔开：

区域	信任级别	访问权限
Rust Core	完全信任	无限制的系统访问
WebView Frontend	有限信任	仅能通过IPC访问暴露的资源

Runtime Authority会在执行时强制实施这个边界。

Security Architecture

安全架构

How Runtime Authority Fits

Runtime Authority的定位

Frontend (WebView)
       |
       v
[IPC Invoke Request]
       |
       v
+------------------+
| Runtime Authority|  <-- Validates permissions, capabilities, scopes
+------------------+
       |
       v (if allowed)
[Tauri Command Execution]
       |
       v
[System Resources]

Frontend (WebView)
       |
       v
[IPC Invoke Request]
       |
       v
+------------------+
| Runtime Authority|  <-- 验证权限、能力、作用域
+------------------+
       |
       v (如果允许)
[Tauri Command Execution]
       |
       v
[System Resources]

Key Components

关键组件

Component	Role in Runtime
Permissions	Define what commands exist and their access rules
Capabilities	Map permissions to specific windows/webviews
Scopes	Restrict command behavior with path/resource limits
Runtime Authority	Enforces all of the above at execution time

组件	运行时角色
Permissions（权限）	定义可用的命令及其访问规则
Capabilities（能力）	将权限映射到特定窗口/WebView
Scopes（作用域）	通过路径/资源限制来约束命令行为
Runtime Authority	在执行时强制实施上述所有规则

Capability Resolution at Runtime

运行时能力解析

When a command is invoked, the runtime authority resolves which capabilities apply.

当命令被调用时，Runtime Authority会解析适用的capability。

Resolution Process

解析流程

Identify Origin: Determine which window/webview made the request
Match Capabilities: Find all capabilities that include this window
Collect Permissions: Aggregate all permissions from matched capabilities
Check Command Access: Verify the command is allowed
Merge Scopes: Combine all applicable scope restrictions
Validate or Deny: Either proceed with scope injection or reject

识别源：确定发起请求的窗口/WebView
匹配能力：找到所有包含该窗口的capability
收集权限：汇总所有匹配capability中的权限
检查命令访问权限：验证该命令是否被允许
合并作用域：组合所有适用的作用域限制
验证或拒绝：要么继续注入作用域，要么拒绝请求

Window Capability Merging

窗口能力合并

When a window is part of multiple capabilities, security boundaries merge:

json

// capability-1.json
{
  "identifier": "basic-access",
  "windows": ["main"],
  "permissions": ["fs:allow-read-file"]
}

// capability-2.json
{
  "identifier": "write-access",
  "windows": ["main"],
  "permissions": ["fs:allow-write-file"]
}

Result: The "main" window gets both read and write permissions.

当一个窗口属于多个capability时，安全边界会合并：

json

// capability-1.json
{
  "identifier": "basic-access",
  "windows": ["main"],
  "permissions": ["fs:allow-read-file"]
}

// capability-2.json
{
  "identifier": "write-access",
  "windows": ["main"],
  "permissions": ["fs:allow-write-file"]
}

结果："main"窗口同时获得读取和写入权限。

Platform-Specific Resolution

平台特定解析

Capabilities can target specific platforms. At runtime, only capabilities matching the current platform are considered:

json

{
  "identifier": "desktop-features",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["shell:allow-execute"]
}

On iOS/Android, this capability is ignored at runtime.

Capabilities可以针对特定平台。在运行时，只会考虑与当前平台匹配的capability：

json

{
  "identifier": "desktop-features",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["shell:allow-execute"]
}

在iOS/Android上，该capability在运行时会被忽略。

Access Control Enforcement

访问控制实施

Deny Precedence Rule

拒绝优先规则

When evaluating access, deny rules always take precedence:

json

{
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.ssh/**" }]
    }
  ]
}

At runtime:

Request to read
```
$HOME/documents/file.txt
```
- Allowed
Request to read
```
$HOME/.ssh/id_rsa
```
- Denied (deny rule matches)

评估访问权限时，拒绝规则始终优先：

json

{
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.ssh/**" }]
    }
  ]
}

在运行时：

读取
```
$HOME/documents/file.txt
```
的请求 - 允许
读取
```
$HOME/.ssh/id_rsa
```
的请求 - 拒绝（匹配拒绝规则）

Command-Level Validation

命令级验证

Before any command executes:

Runtime authority checks if the command permission exists
Verifies the calling window has that permission via its capabilities
Validates any scope restrictions are satisfied

Window "editor" calls fs.readFile("/home/user/doc.txt")
                        |
                        v
Runtime Authority checks:
  - Does "editor" have fs:allow-read-file? Yes
  - Is "/home/user/doc.txt" in allowed scope? Yes
  - Is it in any deny scope? No
                        |
                        v
Command executes with scopes injected

在任何命令执行前：

Runtime Authority检查该命令权限是否存在
验证调用窗口是否通过其capability拥有该权限
验证所有作用域限制是否被满足

Window "editor" 调用 fs.readFile("/home/user/doc.txt")
                        |
                        v
Runtime Authority 检查：
  - "editor" 是否拥有 fs:allow-read-file？是
  - "/home/user/doc.txt" 是否在允许的作用域内？是
  - 它是否在任何拒绝作用域内？否
                        |
                        v
命令在注入作用域后执行

Scope Injection

作用域注入

How Scopes Work at Runtime

作用域在运行时的工作方式

Scopes are not just validation rules; they are injected into command execution context. Commands can access their applicable scopes to enforce restrictions.

作用域不仅是验证规则，还会被注入到命令执行上下文中。命令可以访问其适用的作用域来实施限制。

Scope Variables

作用域变量

At runtime, scope variables resolve to actual paths:

Variable	Runtime Resolution
`$APP`	Application install directory
`$APPDATA`	App data directory
`$APPCONFIG`	App config directory
`$HOME`	User home directory
`$TEMP`	Temporary directory
`$DOCUMENT`	Documents directory
`$DOWNLOAD`	Downloads directory
`$DESKTOP`	Desktop directory

在运行时，作用域变量会解析为实际路径：

变量	运行时解析结果
`$APP`	应用安装目录
`$APPDATA`	应用数据目录
`$APPCONFIG`	应用配置目录
`$HOME`	用户主目录
`$TEMP`	临时目录
`$DOCUMENT`	文档目录
`$DOWNLOAD`	下载目录
`$DESKTOP`	桌面目录

Scope Combination Example

作用域组合示例

json

{
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$APPDATA/*" }]
    },
    {
      "identifier": "fs:allow-write-file",
      "allow": [{ "path": "$APPDATA/config.json" }]
    }
  ]
}

At runtime for the "main" window:

Read operations allowed in
```
$APPDATA/*
```
Write operations only allowed for
```
$APPDATA/config.json
```

json

{
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$APPDATA/*" }]
    },
    {
      "identifier": "fs:allow-write-file",
      "allow": [{ "path": "$APPDATA/config.json" }]
    }
  ]
}

在运行时，"main"窗口：

允许在
```
$APPDATA/*
```
目录下执行读取操作
仅允许在
```
$APPDATA/config.json
```
文件执行写入操作

Path Traversal Prevention

路径遍历防护

The runtime authority includes built-in path traversal protection:

Request: /usr/path/to/../../../etc/passwd
Result: DENIED (path traversal detected)

Parent directory accessors (

..

) in paths are blocked, ensuring scope restrictions cannot be bypassed.

Runtime Authority内置了路径遍历防护机制：

请求：/usr/path/to/../../../etc/passwd
结果：拒绝（检测到路径遍历）

路径中的父目录访问符（

..

）会被阻止，确保作用域限制无法被绕过。

Configuration Examples

配置示例

Basic Runtime Security Setup

基础运行时安全设置

src-tauri/capabilities/default.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default-capability",
  "description": "Default runtime permissions",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:event:default",
    "core:window:default"
  ]
}

src-tauri/capabilities/default.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default-capability",
  "description": "Default runtime permissions",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:event:default",
    "core:window:default"
  ]
}

Scoped Filesystem Access

作用域化文件系统访问

src-tauri/capabilities/files.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "file-access",
  "description": "Controlled filesystem access",
  "windows": ["main"],
  "permissions": [
    "fs:default",
    {
      "identifier": "fs:allow-read-file",
      "allow": [
        { "path": "$APPDATA/**" },
        { "path": "$DOCUMENT/**" }
      ],
      "deny": [
        { "path": "$DOCUMENT/private/**" }
      ]
    },
    {
      "identifier": "fs:allow-write-file",
      "allow": [
        { "path": "$APPDATA/**" }
      ]
    }
  ]
}

src-tauri/capabilities/files.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "file-access",
  "description": "Controlled filesystem access",
  "windows": ["main"],
  "permissions": [
    "fs:default",
    {
      "identifier": "fs:allow-read-file",
      "allow": [
        { "path": "$APPDATA/**" },
        { "path": "$DOCUMENT/**" }
      ],
      "deny": [
        { "path": "$DOCUMENT/private/**" }
      ]
    },
    {
      "identifier": "fs:allow-write-file",
      "allow": [
        { "path": "$APPDATA/**" }
      ]
    }
  ]
}

Multi-Window Security Boundaries

多窗口安全边界

src-tauri/capabilities/editor.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "editor-capability",
  "description": "Full editor permissions",
  "windows": ["editor"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "dialog:default"
  ]
}

src-tauri/capabilities/preview.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "preview-capability",
  "description": "Read-only preview permissions",
  "windows": ["preview"],
  "permissions": [
    "core:window:default",
    "core:event:default",
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$TEMP/preview/**" }]
    }
  ]
}

At runtime:

"editor" window can read/write files and open dialogs
"preview" window can only read from temp preview directory

src-tauri/capabilities/editor.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "editor-capability",
  "description": "Full editor permissions",
  "windows": ["editor"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "dialog:default"
  ]
}

src-tauri/capabilities/preview.json

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "preview-capability",
  "description": "Read-only preview permissions",
  "windows": ["preview"],
  "permissions": [
    "core:window:default",
    "core:event:default",
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$TEMP/preview/**" }]
    }
  ]
}

在运行时：

"editor"窗口可以读写文件并打开对话框
"preview"窗口只能从临时预览目录读取文件

HTTP Request Scoping

HTTP请求作用域化

json

{
  "identifier": "api-access",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "http:default",
      "allow": [
        { "url": "https://api.myapp.com/*" },
        { "url": "https://cdn.myapp.com/*" }
      ],
      "deny": [
        { "url": "https://api.myapp.com/admin/*" }
      ]
    }
  ]
}

json

{
  "identifier": "api-access",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "http:default",
      "allow": [
        { "url": "https://api.myapp.com/*" },
        { "url": "https://cdn.myapp.com/*" }
      ],
      "deny": [
        { "url": "https://api.myapp.com/admin/*" }
      ]
    }
  ]
}

Runtime Security Guarantees

运行时安全保障

What Runtime Authority Protects

Runtime Authority防护的威胁

Threat	Protection
Frontend compromise	Limits damage to granted permissions only
Unauthorized command access	Commands denied without explicit capability
Path traversal attacks	Built-in prevention at runtime
Scope bypass attempts	All scopes enforced before command execution
Cross-window access	Each window isolated to its capabilities

威胁	防护措施
前端被攻陷	将损害限制在已授予的权限范围内
未授权命令访问	无明确capability的命令会被拒绝
路径遍历攻击	运行时内置防护机制
作用域绕过尝试	所有作用域在命令执行前强制实施
跨窗口访问	每个窗口被隔离到其自身的capability中

What Runtime Authority Does NOT Protect

Runtime Authority不防护的威胁

Threat	Why Not Protected
Malicious Rust code	Rust core has full trust
Overly permissive config	Developer responsibility
WebView vulnerabilities	OS WebView security boundary
Supply chain attacks	Dependency security

威胁	未防护原因
恶意Rust代码	Rust核心拥有完全信任权限
过于宽松的配置	属于开发者的责任
WebView漏洞	属于操作系统WebView的安全边界
供应链攻击	属于依赖项安全范畴

Debugging Runtime Authority

调试Runtime Authority

Permission Denied Errors

权限拒绝错误

When a command fails with permission denied:

Check Window Label: Verify the window making the request
Check Capability: Ensure a capability targets that window
Check Permission: Verify the permission is in the capability
Check Scope: Verify the resource is in allowed scope and not denied

当命令因权限拒绝失败时：

检查窗口标签：确认发起请求的窗口
检查Capability：确保存在针对该窗口的capability
检查Permission：验证该权限是否在capability中
检查作用域：验证资源是否在允许的作用域内且未被拒绝

Common Runtime Issues

常见运行时问题

Issue	Cause	Solution
Command not allowed	Missing permission in capability	Add permission to capability
Scope not applied	No scope defined for permission	Add allow scope
Access denied despite allow	Deny rule takes precedence	Remove conflicting deny
Window has no permissions	Capability not targeting window	Check window label in capability

问题	原因	解决方案
命令不被允许	Capability中缺少对应权限	向capability添加该权限
作用域未生效	权限未定义作用域	添加允许作用域
已设置允许但仍被拒绝	拒绝规则优先	移除冲突的拒绝规则
窗口无任何权限	Capability未针对该窗口	检查capability中的窗口标签

Verifying Runtime Configuration

验证运行时配置

Check generated schemas to see what permissions are available:

src-tauri/gen/schemas/desktop-schema.json
src-tauri/gen/schemas/mobile-schema.json

查看生成的架构文件以了解可用的权限：

src-tauri/gen/schemas/desktop-schema.json
src-tauri/gen/schemas/mobile-schema.json

Best Practices

最佳实践

Principle of Least Privilege

最小权限原则

Grant only the permissions each window actually needs:

json

// Good: Specific permissions
{
  "windows": ["settings"],
  "permissions": [
    "core:window:allow-close",
    "fs:allow-read-file"
  ]
}

// Avoid: Overly broad permissions
{
  "windows": ["settings"],
  "permissions": ["fs:default", "shell:default"]
}

仅为每个窗口授予其实际需要的权限：

json

// 推荐：特定权限
{
  "windows": ["settings"],
  "permissions": [
    "core:window:allow-close",
    "fs:allow-read-file"
  ]
}

// 避免：过于宽泛的权限
{
  "windows": ["settings"],
  "permissions": ["fs:default", "shell:default"]
}

Always Define Scopes

始终定义作用域

Never leave filesystem or network permissions unscoped:

json

// Good: Scoped access
{
  "identifier": "fs:allow-read-file",
  "allow": [{ "path": "$APPDATA/**" }]
}

// Avoid: Unscoped access
{
  "permissions": ["fs:allow-read-file"]
}

永远不要让文件系统或网络权限处于无作用域状态：

json

// 推荐：作用域化访问
{
  "identifier": "fs:allow-read-file",
  "allow": [{ "path": "$APPDATA/**" }]
}

// 避免：无作用域访问
{
  "permissions": ["fs:allow-read-file"]
}

Deny Sensitive Paths

拒绝敏感路径

Explicitly deny access to sensitive locations:

json

{
  "identifier": "fs:allow-read-file",
  "allow": [{ "path": "$HOME/**" }],
  "deny": [
    { "path": "$HOME/.ssh/**" },
    { "path": "$HOME/.gnupg/**" },
    { "path": "$HOME/.aws/**" }
  ]
}

明确拒绝访问敏感位置：

json

{
  "identifier": "fs:allow-read-file",
  "allow": [{ "path": "$HOME/**" }],
  "deny": [
    { "path": "$HOME/.ssh/**" },
    { "path": "$HOME/.gnupg/**" },
    { "path": "$HOME/.aws/**" }
  ]
}

Separate Capabilities by Trust Level

按信任级别分离Capabilities

Create distinct capabilities for different security contexts:

capabilities/
  main-trusted.json      # Full access for main window
  plugin-limited.json    # Restricted for plugin windows
  preview-readonly.json  # Read-only for preview

为不同的安全上下文创建不同的capabilities：

capabilities/
  main-trusted.json      # 主窗口的完全访问权限
  plugin-limited.json    # 插件窗口的受限权限
  preview-readonly.json  # 预览窗口的只读权限

Platform-Specific Security

平台特定安全

Use platform targeting for OS-specific permissions:

json

{
  "identifier": "desktop-shell",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["shell:allow-execute"]
}

This prevents desktop-only permissions from being evaluated on mobile.

使用平台定位来设置特定操作系统的权限：

json

{
  "identifier": "desktop-shell",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["shell:allow-execute"]
}

这可以防止仅适用于桌面的权限在移动设备上被评估。

Summary

总结

The runtime authority is Tauri's enforcement mechanism for the ACL-based security model:

Every IPC request passes through runtime authority validation
Capabilities resolve at runtime based on the calling window
Scopes inject into command execution context
Deny rules always take precedence over allow rules
Path traversal is blocked automatically
Security boundaries merge when windows have multiple capabilities

Configure capabilities and permissions correctly, and the runtime authority ensures they are enforced consistently throughout application execution.

Runtime Authority是Tauri基于ACL的安全模型的实施机制：

所有IPC请求都要经过Runtime Authority验证
Capabilities会根据调用窗口在运行时解析
作用域会被注入到命令执行上下文中
拒绝规则始终优先于允许规则
路径遍历会被自动阻止
安全边界会在窗口拥有多个capabilities时合并

正确配置capabilities和权限后，Runtime Authority会确保它们在应用执行期间被一致地实施。