PermissionManager API 文档

概述

PermissionManager 是 ZerOS 内核的权限管理系统，负责管理所有程序的内核操作权限。提供权限声明、权限检查、动态权限申请和权限持久化功能。权限管理系统是 ZerOS 安全架构的核心组件，确保所有内核 API 调用都经过严格的权限验证。

依赖

ProcessManager - 进程管理器（用于获取程序信息）
LStorage - 本地存储（用于权限持久化）
GUIManager - GUI 管理器（用于显示权限请求对话框）

权限级别

权限管理系统定义了三种权限级别：

NORMAL（普通权限）：自动授予，仅记录，无需用户确认
SPECIAL（特殊权限）：需要用户确认，首次使用时弹出权限请求对话框
DANGEROUS（危险权限）：需要用户明确授权，每次使用时都可能弹出权限请求对话框

权限枚举

系统级权限

PermissionManager.PERMISSION.SYSTEM_NOTIFICATION      // 发送系统通知
PermissionManager.PERMISSION.SYSTEM_STORAGE_READ      // 读取系统级本地存储
PermissionManager.PERMISSION.SYSTEM_STORAGE_WRITE     // 写入系统级本地存储（基础权限，仅可写入非敏感键）

// 系统存储细粒度权限（危险权限，仅管理员可授予）
PermissionManager.PERMISSION.SYSTEM_STORAGE_WRITE_USER_CONTROL         // 写入用户控制相关存储（userControl.*）
PermissionManager.PERMISSION.SYSTEM_STORAGE_WRITE_PERMISSION_CONTROL   // 写入权限控制相关存储（permissionControl.*, permissionManager.*）

// 系统存储细粒度权限（特殊权限，普通用户可以授予）
PermissionManager.PERMISSION.SYSTEM_STORAGE_WRITE_DESKTOP              // 写入桌面相关存储（desktop.*）

PermissionManager.PERMISSION.PROCESS_MANAGE           // 管理其他进程（启动/终止）

// 服务扩展权限（最高等级，DANGEROUS）
PermissionManager.PERMISSION.SERVER_SERVICE_MANAGE    // 启动/停止/查询 D/server 服务（Server.* API）

PermissionManager.PERMISSION.THEME_READ               // 读取系统主题配置
PermissionManager.PERMISSION.THEME_WRITE              // 更改系统主题配置
PermissionManager.PERMISSION.DESKTOP_MANAGE           // 管理桌面快捷方式和背景
PermissionManager.PERMISSION.DESKTOP_SHORTCUT         // 创建/删除桌面快捷方式（普通权限）

文件系统权限

PermissionManager.PERMISSION.KERNEL_DISK_READ         // 读取磁盘文件
PermissionManager.PERMISSION.KERNEL_DISK_WRITE        // 写入磁盘文件
PermissionManager.PERMISSION.KERNEL_DISK_DELETE       // 删除磁盘文件
PermissionManager.PERMISSION.KERNEL_DISK_CREATE       // 创建磁盘文件/目录
PermissionManager.PERMISSION.KERNEL_DISK_LIST         // 列出磁盘文件/目录

内存权限

PermissionManager.PERMISSION.KERNEL_MEMORY_READ       // 读取内核内存数据
PermissionManager.PERMISSION.KERNEL_MEMORY_WRITE      // 写入内核内存数据

网络权限

PermissionManager.PERMISSION.NETWORK_ACCESS           // 访问网络（fetch, XMLHttpRequest等）

GUI权限

PermissionManager.PERMISSION.GUI_WINDOW_CREATE        // 创建GUI窗口
PermissionManager.PERMISSION.GUI_WINDOW_MANAGE        // 管理其他程序的GUI窗口（最小化/最大化/关闭）

加密权限

PermissionManager.PERMISSION.CRYPT_GENERATE_KEY       // 生成密钥对
PermissionManager.PERMISSION.CRYPT_IMPORT_KEY         // 导入密钥对
PermissionManager.PERMISSION.CRYPT_DELETE_KEY         // 删除密钥
PermissionManager.PERMISSION.CRYPT_ENCRYPT            // 加密数据
PermissionManager.PERMISSION.CRYPT_DECRYPT            // 解密数据
PermissionManager.PERMISSION.CRYPT_MD5                // MD5 哈希
PermissionManager.PERMISSION.CRYPT_RANDOM             // 随机数生成

地理位置权限

PermissionManager.PERMISSION.GEOGRAPHY_LOCATION       // 获取地理位置信息

拖拽权限

PermissionManager.PERMISSION.DRAG_ELEMENT            // 元素拖拽
PermissionManager.PERMISSION.DRAG_FILE                // 文件拖拽
PermissionManager.PERMISSION.DRAG_WINDOW              // 窗口拖拽

事件权限

PermissionManager.PERMISSION.EVENT_LISTENER           // 注册事件监听器

缓存权限

PermissionManager.PERMISSION.CACHE_READ               // 读取缓存
PermissionManager.PERMISSION.CACHE_WRITE              // 写入/删除缓存

语音识别权限

PermissionManager.PERMISSION.SPEECH_RECOGNITION       // 语音识别

媒体访问权限

PermissionManager.PERMISSION.MEDIA_ACCESS            // 访问摄像头和麦克风

语言包权限

PermissionManager.PERMISSION.LANGUAGES_READ           // 读取语言包、按常量名获取文本、列出语言包
PermissionManager.PERMISSION.LANGUAGES_WRITE          // 加载语言包、设置当前语言

初始化

权限管理器在系统启动时自动初始化，无需手动调用。

// 自动初始化（在 BootLoader 中）
await PermissionManager.init();

API 方法

权限注册

`registerProgramPermissions(pid, programInfoOrPermissions)`

注册程序的权限声明。在程序启动时由 ProcessManager 自动调用。

参数:

pid (number): 进程ID
programInfoOrPermissions (Object|Array): 程序信息对象（包含 permissions 数组）或权限数组（向后兼容）

返回值: Promise<void>

示例:

// 在程序的 __info__ 方法中声明权限
__info__() {
    return {
        name: 'myapp',
        type: 'GUI',
        version: '1.0.0',
        permissions: [
            PermissionManager.PERMISSION.GUI_WINDOW_CREATE,
            PermissionManager.PERMISSION.KERNEL_DISK_READ,
            PermissionManager.PERMISSION.KERNEL_DISK_WRITE,
            PermissionManager.PERMISSION.SYSTEM_NOTIFICATION
        ]
    };
}

// ProcessManager 会自动调用
await PermissionManager.registerProgramPermissions(pid, programInfo);

权限检查

`hasPermission(pid, permission)`

检查程序是否已有指定权限。

参数:

pid (number): 进程ID
permission (string): 权限名称

返回值: boolean - 是否有权限

示例:

const hasNotify = PermissionManager.hasPermission(pid, PermissionManager.PERMISSION.SYSTEM_NOTIFICATION);
if (hasNotify) {
    // 程序已有通知权限
}

`checkAndRequestPermission(pid, permission)`

检查并申请权限（如果未授予）。这是权限检查的核心方法，会自动处理权限请求流程。

参数:

pid (number): 进程ID
permission (string): 权限名称

返回值: Promise<boolean> - 是否获得权限

工作流程:

检查是否已有权限（包括缓存）
如果是普通权限，自动授予
如果是特殊/危险权限，弹出权限请求对话框
用户选择后返回结果
结果会被缓存 5 秒，避免重复检查

示例:

// 在创建通知前检查权限
const hasPermission = await PermissionManager.checkAndRequestPermission(
    this.pid,
    PermissionManager.PERMISSION.SYSTEM_NOTIFICATION
);

if (hasPermission) {
    // 创建通知
    NotificationManager.createNotification(this.pid, {...});
} else {
    // 权限被拒绝
    console.error('没有通知权限');
}

权限管理

`revokePermission(pid, permission)`

撤销程序的指定权限。

参数:

pid (number): 进程ID
permission (string): 权限名称

示例:

PermissionManager.revokePermission(pid, PermissionManager.PERMISSION.SYSTEM_NOTIFICATION);

`clearProgramPermissions(pid)`

清除程序的所有权限。在程序终止时由 ProcessManager 自动调用。

参数:

pid (number): 进程ID

示例:

// ProcessManager 会自动调用
PermissionManager.clearProgramPermissions(pid);

`getProgramPermissions(pid)`

获取程序的所有权限列表。

参数:

pid (number): 进程ID

返回值: Array<string> - 权限列表

示例:

const permissions = PermissionManager.getProgramPermissions(pid);
console.log('程序权限:', permissions);

缓存管理

`clearPermissionCache(pid)`

清除权限检查缓存。用于强制重新检查权限。

参数:

pid (number|null): 进程ID，如果为 null 则清除所有缓存

示例:

// 清除指定程序的缓存
PermissionManager.clearPermissionCache(pid);

// 清除所有缓存
PermissionManager.clearPermissionCache(null);

审计和统计

`getPermissionStats()`

获取权限统计信息（用于调试和监控）。

返回值: Object - 统计信息对象

totalPrograms (number): 已注册权限的程序数量
totalPermissions (number): 总权限数量
cacheSize (number): 缓存大小
pendingChecks (number): 正在进行的权限检查数量
pendingRequests (number): 待处理的权限请求数量
initialized (boolean): 是否已初始化
auditLogSize (number): 审计日志条数
violationLogSize (number): 违规日志条数
permissionStats (Object): 每个权限的详细统计（granted, denied, checked）

示例:

const stats = PermissionManager.getPermissionStats();
console.log('权限统计:', stats);

`getAuditLog(filters, limit)`

获取权限审计日志。记录所有权限检查、授予、拒绝等操作。

参数:

filters (Object, 可选): 过滤条件
- pid (number, 可选): 进程ID
- permission (string, 可选): 权限名称
- action (string, 可选): 操作类型（'check', 'grant', 'deny', 'request'）
- result (boolean, 可选): 操作结果
limit (number, 可选): 返回的最大条数，默认 100

返回值: Array<Object> - 审计日志条目数组

timestamp (number): 时间戳
pid (number): 进程ID
programName (string): 程序名称
permission (string): 权限名称
action (string): 操作类型
result (boolean): 操作结果
level (string): 权限级别
context (Object): 上下文信息

示例:

// 获取所有审计日志
const allLogs = PermissionManager.getAuditLog();

// 获取特定程序的审计日志
const programLogs = PermissionManager.getAuditLog({ pid: 10001 }, 50);

// 获取特定权限的审计日志
const permissionLogs = PermissionManager.getAuditLog({ 
    permission: 'KERNEL_DISK_WRITE' 
}, 20);

`getViolationLog(filters, limit)`

获取权限违规日志。记录所有未授权访问尝试。

参数:

filters (Object, 可选): 过滤条件
- pid (number, 可选): 进程ID
- permission (string, 可选): 权限名称
limit (number, 可选): 返回的最大条数，默认 100

返回值: Array<Object> - 违规日志条目数组

timestamp (number): 时间戳
pid (number): 进程ID
programName (string): 程序名称
permission (string): 权限名称
context (Object): 上下文信息
stack (string): 调用栈

示例:

// 获取所有违规记录
const violations = PermissionManager.getViolationLog();

// 获取特定程序的违规记录
const programViolations = PermissionManager.getViolationLog({ pid: 10001 });

// 获取最近的 10 条违规记录
const recentViolations = PermissionManager.getViolationLog({}, 10);

`clearAuditLog(clearViolations)`

清除审计日志和/或违规日志。

参数:

clearViolations (boolean, 可选): 是否同时清除违规日志，默认 false

示例:

// 只清除审计日志
PermissionManager.clearAuditLog();

// 同时清除审计日志和违规日志
PermissionManager.clearAuditLog(true);

权限级别映射

普通权限（自动授予）

普通权限会在程序启动时自动授予，或在首次使用时根据"自动授予普通权限"设置决定是否自动授予。

KERNEL_DISK_READ - 读取文件
KERNEL_DISK_LIST - 列出目录
GUI_WINDOW_CREATE - 创建窗口
THEME_READ - 读取主题
SYSTEM_NOTIFICATION - 系统通知
NETWORK_ACCESS - 网络访问（普通权限，自动授予）
EVENT_LISTENER - 事件监听
CACHE_READ - 读取缓存
CACHE_WRITE - 写入缓存
CRYPT_MD5 - MD5 哈希
CRYPT_RANDOM - 随机数生成
DRAG_ELEMENT - 拖拽元素
DRAG_FILE - 拖拽文件
DRAG_WINDOW - 拖拽窗口

特殊权限（需要用户确认）

特殊权限首次使用时需要用户确认，用户允许后会被持久化保存。

KERNEL_DISK_WRITE - 写入文件
KERNEL_DISK_CREATE - 创建文件/目录
KERNEL_DISK_DELETE - 删除文件
KERNEL_MEMORY_READ - 读取内存
KERNEL_MEMORY_WRITE - 写入内存
GUI_WINDOW_MANAGE - 管理窗口
SYSTEM_STORAGE_READ - 读取系统存储
SYSTEM_STORAGE_WRITE - 写入系统存储（基础权限，仅可写入非敏感键）
SYSTEM_STORAGE_WRITE_DESKTOP - 写入桌面相关存储（desktop.* 键）
THEME_WRITE - 修改主题
DESKTOP_MANAGE - 管理桌面
DESKTOP_SHORTCUT - 创建/删除桌面快捷方式（普通权限，自动授予）
MULTITHREADING_CREATE - 创建线程
MULTITHREADING_EXECUTE - 执行多线程任务
GEOGRAPHY_LOCATION - 获取地理位置
CRYPT_GENERATE_KEY - 生成密钥对
CRYPT_IMPORT_KEY - 导入密钥对
CRYPT_DELETE_KEY - 删除密钥
CRYPT_ENCRYPT - 加密数据
CRYPT_DECRYPT - 解密数据

危险权限（需要明确授权，仅管理员可授予）

危险权限每次使用时都可能需要用户确认，需要用户明确授权。只有管理员用户才能授权危险权限给程序，普通用户无法授权。

PROCESS_MANAGE - 管理进程（启动/终止其他程序）
SYSTEM_STORAGE_WRITE_USER_CONTROL - 写入用户控制相关存储（userControl.* 键，注意：userControl.users 键只能由内核模块写入，用户程序即使获得此权限也无法写入该键）
SYSTEM_STORAGE_WRITE_PERMISSION_CONTROL - 写入权限控制相关存储（permissionControl.*、permissionManager.permissions 键）

使用示例

示例 1: 在程序中声明权限

// system/service/DISK/D/application/myapp/myapp.js
__info__() {
    return {
        name: 'myapp',
        type: 'GUI',
        version: '1.0.0',
        permissions: [
            PermissionManager.PERMISSION.GUI_WINDOW_CREATE,
            PermissionManager.PERMISSION.KERNEL_DISK_READ,
            PermissionManager.PERMISSION.KERNEL_DISK_WRITE,
            PermissionManager.PERMISSION.SYSTEM_NOTIFICATION
        ]
    };
}

示例 2: 检查权限后调用 API

// 在创建通知前检查权限
async function createNotification() {
    const hasPermission = await PermissionManager.checkAndRequestPermission(
        this.pid,
        PermissionManager.PERMISSION.SYSTEM_NOTIFICATION
    );
    
    if (!hasPermission) {
        console.error('没有通知权限');
        return;
    }
    
    // 创建通知
    await NotificationManager.createNotification(this.pid, {
        type: 'snapshot',
        title: '通知标题',
        content: '通知内容'
    });
}

示例 3: 通过 ProcessManager 调用内核 API（自动权限检查）

// ProcessManager 会自动检查权限
try {
    const content = await ProcessManager.callKernelAPI(
        this.pid,
        'FileSystem.read',
        ['D:/myfile.txt']
    );
    console.log('文件内容:', content);
} catch (e) {
    if (e.message.includes('没有权限')) {
        console.error('权限被拒绝:', e.message);
    } else {
        console.error('读取文件失败:', e.message);
    }
}

权限请求对话框

当程序请求特殊或危险权限时，系统会自动弹出权限请求对话框：

程序信息：显示请求权限的程序名称
权限信息：显示权限名称和详细描述
权限级别：显示权限级别（特殊权限/危险权限）
用户选择：用户可以选择"允许"或"拒绝"

权限请求对话框使用拟态设计，提供良好的用户体验。

权限持久化

权限管理器使用 LStorage 持久化权限记录：

权限记录保存在 permissionManager.permissions 键中
程序关闭后，已授予的权限会被保存
下次启动时，已授予的权限会自动恢复
普通权限会在程序启动时自动授予

性能优化

权限检查缓存

权限检查结果会被缓存 5 秒（CACHE_TTL）
避免短时间内重复检查同一权限
权限授予/撤销时自动清除相关缓存

并发请求去重

同一程序同时请求同一权限时，会共享同一个 Promise
避免同时弹出多个权限请求对话框
提高用户体验和系统性能

异步持久化

权限保存使用异步操作，不阻塞主线程
初始化时异步等待依赖就绪

权限管控功能

黑名单和白名单

权限管理系统支持程序黑名单和白名单功能，通过 PermissionControl 程序进行管理：

黑名单：黑名单中的程序会被拒绝所有权限请求（Exploit 程序除外）
白名单：白名单中的程序在请求普通权限时会自动授予
自动授予设置：可以控制是否自动授予普通权限（仅影响普通权限）

权限审计

权限管理系统提供完整的审计功能：

审计日志：记录所有权限检查、授予、拒绝操作
违规日志：记录所有未授权访问尝试
权限统计：统计每个权限的使用情况（授予次数、拒绝次数、检查次数）

注意：在权限请求流程中（用户正在确认权限时），系统不会记录违规。只有在权限被明确拒绝后，程序再次尝试访问时才会记录违规。

权限缓存

权限检查结果会被缓存 5 秒（CACHE_TTL）
使用缓存时仍会检查黑名单（因为黑名单可能动态变化）
权限授予/撤销时自动清除相关缓存

注意事项

权限检查是强制性的：所有需要权限的内核 API 调用都必须经过权限检查
权限被拒绝时 API 调用会被拒绝：如果权限被拒绝，相应的 API 调用会立即抛出错误
Exploit 程序享有特权：Exploit 程序（PID 10000）享有直接通信权限，无需权限检查，不受黑名单限制
权限声明是必需的：程序必须在 __info__ 中声明所需权限
普通权限自动授予：普通权限会根据"自动授予普通权限"设置决定是否自动授予
特殊权限需要用户确认：特殊权限首次使用时需要用户确认，用户允许后会被持久化保存
权限持久化：已授予的权限会被持久化保存，下次启动时自动恢复
违规记录时机：只有在权限被明确拒绝后，程序再次尝试访问时才会记录违规。在权限请求流程中不会记录违规
黑名单优先级最高：黑名单检查在权限检查前进行，黑名单中的程序会被直接拒绝
权限请求流程：在权限请求流程中，系统使用 isRequesting 标志避免误记录违规
系统存储细粒度权限：系统存储写入权限分为多个级别，危险键需要危险权限（仅管理员可授予），特殊键需要特殊权限（普通用户可以授予）
userControl.users 键特殊保护：userControl.users 键只能由 UserControl 内核模块写入，用户程序即使获得 SYSTEM_STORAGE_WRITE_USER_CONTROL 权限也无法写入该键，这是为了防止权限提升攻击
危险权限授权限制：危险权限只能由管理员用户授权，普通用户无法授权危险权限给程序