SPECIFICATION

第 7 章：资源访问模式

本章定义 Resource_Access_Mode 的语义、读写锁矩阵、约束条件应用和与 Session 权限的关系。本章对应蓝图 §2.5 的设计意图。

7.1 模式定义

CAP 协议定义 4 种访问模式：

AccessMode = enum["read", "write", "execute", "configure"]

7.1.1 read

语义：对 Terminal_Resource 进行只读访问，不修改资源状态。

典型操作：

读取传感器实时数据（温度、湿度、定位）
查看媒体文件（照片、视频）
查询设备状态属性（电量、连接状态）

并发性：可共享。多个 Session MAY 同时持有同一资源的 read 模式访问权。

7.1.2 write

语义：对 Terminal_Resource 进行数据写入或状态修改。

典型操作：

写入文件到存储设备
修改设备的运行参数（音量、亮度、温度设定）
向应用窗口发送内容输入

并发性：排他。同一资源在同一时刻最多有一个 Session 持有 write 模式。

7.1.3 execute

语义：对 Terminal_Resource 触发执行操作指令。

典型操作：

启动应用程序
触发硬件操作指令（拍照、起飞、打印）
调用 RPC 接口

并发性：排他。

write 与 execute 的区别：write 修改数据状态，execute 触发动作（即使两者最终都改变状态）。终端的访问控制粒度可能无法严格区分两者，此时实现 MAY 将 execute 视为 write 的子类（持有 write 权限自动具备 execute 能力）。但本规范的默认语义是两者独立——持有 execute 权限不自动获得 write 权限，反之亦然。

7.1.4 configure

语义：对 Terminal_Resource 进行系统级配置变更。

典型操作：

修改设备的硬件参数（摄像头分辨率、网络 SSID）
调整安全策略（防火墙规则、配对设置）
更改资源的访问策略（如 Handover_Policy 配置）

并发性：排他且高权限。configure 通常需要更高级别的授权才能行使（参见 §7.4.3）。

7.2 读写锁矩阵

读写锁矩阵定义同一资源在不同模式下的兼容性。新请求与现有占用的兼容性如下：

现有占用 \ 新请求	read	write	execute	configure
无	✓	✓	✓	✓
read（≥1 个）	✓	✗	✗	✗
write	✗	✗	✗	✗
execute	✗	✗	✗	✗
configure	✗	✗	✗	✗

✓：兼容，新请求被允许立即创建 Session。 ✗：不兼容，新请求被拒绝（返回 E_RESOURCE_BUSY）。

7.2.1 矩阵语义说明

read 之间相互兼容：多个只读 Session 可并发存在
write/execute/configure 之间任意两两不兼容：任意排他模式占用资源时，其他排他模式请求被拒绝
read 与排他模式互斥：read 占用时禁止排他请求；排他占用时禁止 read 请求

7.2.2 终端的处理

终端在处理 AuthRequest 时 MUST：

在校验通过后、Session 进入 creating 之前，按矩阵检查兼容性
不兼容时直接返回 E_RESOURCE_BUSY，不自动排队等待
iFay_Runtime 可选择重试或发起交接请求（参见第 6 章）

7.3 与 Session 权限的关系

7.3.1 权限列表

每个 Session 在创建时携带一个 granted_modes 列表（参见 §2.5），列表内容来自 Authorization_Descriptor.grants 或 Trusted_Ticket.grants 中匹配的 Grant.modes。

Fay 通过该 Session 操作资源时，仅能使用 granted_modes 中包含的模式
iFay_Runtime 在 AuthRequest 中指定的 access_mode MUST 是 Grant 授权列表的子集

7.3.2 最小权限原则

iFay_Runtime SHOULD 在 AuthRequest 中仅请求当前任务必需的最低权限模式。例如，仅需读取数据时请求 read，而不是 read + write。

签发方 SHOULD 在 Authorization_Descriptor 中按最小权限原则授权，避免不必要的权限放宽。

7.3.3 模式间无层级包含

CAP v1 中各访问模式相互独立，无层级包含关系：

持有 configure MUST NOT 自动获得 read / write / execute 能力
持有 write MUST NOT 自动获得 read 能力
每种访问模式 MUST 独立授权

实现 MUST NOT 自动扩展授权范围。

7.3.4 权限不可提升

Session 创建后，其 granted_modes MUST NOT 在生命周期内提升。若 Fay 需要更高权限的模式：

iFay_Runtime 主动释放当前 Session
发起新的 AuthRequest，使用具备所需模式的凭证
终端按完整流程创建新 Session

实现 MUST NOT 提供任何"权限升级"的运行时接口。

7.4 约束条件应用

Grant.constraints 是签发方对授权的附加限制条件。本规范定义以下标准约束键，实现 MUST 支持。MAY 支持自定义约束（自定义约束的语义由签发方与终端协商，但 MUST 在 schema 文档中声明）。

7.4.1 时间窗口约束

constraints["time_window"] = "08:00-22:00"           // 每日 8:00-22:00 有效
constraints["time_window_tz"] = "Asia/Shanghai"     // 时区，默认 UTC

校验时机：在 §3.3.2 第 6 步检查每个 Grant 是否满足约束。当前时间不在窗口内 → Grant 不匹配。

7.4.2 频率限制约束

constraints["max_calls_per_hour"] = "60"
constraints["max_calls_per_day"]  = "1000"

终端 SHOULD 维护每个 (descriptor_id, fay_id, resource_id) 组合的调用计数。超过限制时 → Grant 不匹配（返回 E_RATE_LIMIT_EXCEEDED）。

7.4.3 高敏感模式约束

constraints["require_human_confirmation"] = "true"

当 access_mode == "configure" 或满足该约束的其他场景，终端 MUST 在 Session 创建前向人类用户请求一次性确认。确认 UI 与 §6.4.3 共享同一通道。

7.4.4 地理围栏约束

constraints["geo_fence"] = "geohash:wx4g0bm"        // 仅在指定地理范围内有效
constraints["geo_fence_radius_m"] = "1000"

终端的位置来源 SHOULD 使用经过校准的 GPS 或网络定位。位置不可用时 → Grant 不匹配（保守拒绝）。

7.4.5 未识别约束的处理

终端遇到未识别的 constraints 键时 MUST：

默认拒绝该 Grant（保守原则）
返回 E_UNSUPPORTED_CONSTRAINT 并附带未识别的键名

签发方在使用自定义约束时 SHOULD 通过其他渠道告知终端约束语义，避免授权失败。

7.5 模式与 OS 访问控制的映射

终端通过操作系统的访问控制接口实施 access_mode 的执行。本节定义模式到 OS 控制的推荐映射。具体实现可因平台不同而有差异，但 MUST 保持语义等价。

资源类型	read	write	execute	configure
文件/目录	文件系统读权限	文件系统写权限	执行权限	元数据修改权限
设备文件	设备读	设备写	ioctl/控制接口	设备配置寄存器
应用进程	查询状态	输入注入	启动/调用	修改启动参数
网络资源	接收数据	发送数据	建立连接	修改路由/防火墙
摄像头	读取画面	不适用	拍摄/录制控制	调整分辨率/帧率

平台特定的访问控制机制（如 SELinux、AppArmor、macOS Sandbox、Android Permission）由终端实现选择并集成。

7.6 模式更换的约束

同一 (Session, Resource) 在生命周期内 MUST 维持初始的 access_mode 不变。模式更换通过新 Session 实现：

释放当前 Session
创建新 Session 时指定新 access_mode
终端按矩阵重新评估资源占用兼容性

终端 MUST NOT 提供"模式切换"的运行时接口。

7.7 资源访问的可观测性

终端 SHOULD 记录每次资源访问的关键信息（用于审计）：

session_id
fay_id
resource_id
access_mode
操作类型（如读取大小、写入字节数）
时间戳

具体审计日志格式不在本规范范围内（参见蓝图 §3.2 排除项 "审计日志标准化格式"）。

7.8 模式语义的边界

7.8.1 read 模式不阻止资源被并发修改

read 模式仅授权"读取"权限，并不保证读取过程中资源不被其他控制方修改：

多个 read Session 之间互不干扰，但若资源处于"无活跃 Session"状态时被人类用户直接操作（绕过 CAP 协议），read Session 仍可能读到变化的数据
read 模式不提供事务一致性保证

7.8.2 write 模式的原子性

write 模式仅在协议层提供"同一时刻最多一个 write Session"的保证。具体写操作的原子性（如部分写入失败）取决于资源底层语义，不在 CAP 协议范围内。

7.8.3 execute 模式的副作用

execute 模式触发的操作 MAY 改变资源状态。Fay 通过 execute 触发的副作用由该 Fay 负责。CAP 协议不提供 execute 操作的回滚能力。

7.9 完整决策流程

终端在处理资源访问的完整决策流程：

[AuthRequest 到达]
        │
        ▼
  ┌─────────────────────┐
  │ §3 / §4 凭证校验    │
  └──────┬──────────────┘
         │ 通过
         ▼
  ┌─────────────────────┐
  │ §7.4 约束条件评估   │
  │ （constraints）     │
  └──────┬──────────────┘
         │ 通过
         ▼
  ┌─────────────────────┐
  │ §7.2 读写锁矩阵检查 │
  └──────┬──────────────┘
         │ 兼容
         ▼
  ┌─────────────────────┐
  │ §5.2 创建 Session   │
  └──────┬──────────────┘
         │
         ▼
  ┌─────────────────────┐
  │ §7.5 OS 访问控制    │
  │     下发            │
  └──────┬──────────────┘
         │
         ▼
  [返回 AuthResult granted]

任一步骤失败均返回对应错误码并不进入后续步骤。