# 权限

主体、能力、Space 角色、读写根路径和 API Key 的限制如何共同决定一次请求。

## 请求的判定

一次请求必须同时满足以下条件，任一条件不满足即被拒绝：

```text
allowed = capability in (principal.capabilities ∩ key.capabilities)
        and space in key.allowed_space_ids   (when set)
        and the Space role is sufficient
        and the path is under the member's read_root / write_root   (when set)
```

## 主体

| 类型 | 说明 |
| --- | --- |
| 人 | `kind: human`，可以具备 `tenant_admin` 角色 |
| Agent | `kind: agent`，有自己的权限、记忆和审计身份 |
| API Key | 凭据，不是主体，只能收窄所属主体 |

主体没有显示名，请自行按 `id` 记录名称。[`POST /v2/principals`](https://mirabase.io/zh/developers/api/principals.md#principals-create) 只能创建 `human` 和 `agent`，`tenant_admin` 角色不能通过 API 授予。

## 能力

能力是对一类操作的许可，例如 `knowledge:read`、`knowledge:write`、`knowledge:manage`、`knowledge:answer` 和 `memory:confirm`。一个 API Key 的有效能力是主体能力和 Key 能力的交集。[`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 的 `effective_capabilities` 给出这个交集。

每种能力允许的操作见参考页的 [DevCapability](https://mirabase.io/zh/developers/api/schemas.md#DevCapability)；每个操作需要的能力写在参考页该操作的条目里。

## Space 角色

成员在每个 Space 中有一个角色：`owner`、`editor` 或 `viewer`。一次操作既要求能力，也要求最低角色。各角色可执行的操作见 [DevSpaceRole](https://mirabase.io/zh/developers/api/schemas.md#DevSpaceRole)；每个操作需要的能力和更严格的规则，见 [API 参考](https://mirabase.io/zh/developers/api.md) 中该操作的说明。

Space 所有者用 [`PUT /v2/spaces/{space_id}/members/{principal_id}`](https://mirabase.io/zh/developers/api/spaces.md#spaces-setmember) 设置成员的角色、`write_mode`、`write_root` 和 `read_root`。

## Agent 的写入模式

`write_mode` 只对 Agent 生效，且只针对不属于它的文件。新成员默认为 `proposal`：修改他人的文件返回 403 `proposal_required`，移动和删除也一样，不会创建任何内容。设为 `direct` 后可以直接写入。Space 所有者始终是 `direct`。

`proposal` 模式的 Agent 可以带 `Prefer: handling=proposal` 把这类写入变成提案，由审核人批准，见 [提案](https://mirabase.io/zh/developers/files.md#proposals)。

## 写入根路径和读取根路径

Space 所有者可以在设置成员时把它限制在一棵子树内。两种根路径都只会收窄：角色、能力和 API Key 的限制照常生效，没有拒绝规则。取值规则见 [write_root](https://mirabase.io/zh/developers/api/spaces.md#spaces-setmember.body.write_root) 和 [read_root](https://mirabase.io/zh/developers/api/spaces.md#spaces-setmember.body.read_root)。

curl:

```bash
# The Agent reads /projects/acme and writes only under /projects/acme/drafts.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor", "write_mode": "direct",
       "read_root": "/projects/acme", "write_root": "/projects/acme/drafts"}'
```

TypeScript:

```ts
await mirabase.spaces.members.set(agentId, {
  role: "editor",
  write_mode: "direct",
  read_root: "/projects/acme",
  write_root: "/projects/acme/drafts",
});
```

Python:

```python
# agent_id is the Agent's principal id. It reads /projects/acme and writes only under /projects/acme/drafts.
mb.spaces.members.set(agent_id, {
    "role": "editor",
    "write_mode": "direct",
    "read_root": "/projects/acme",
    "write_root": "/projects/acme/drafts",
})
```

| 根路径 | 范围内 | 范围外 |
| --- | --- | --- |
| `write_root` | 在该目录下写入，不能重命名、移动或删除目录本身 | 403 `outside_write_root`，读取不受影响 |
| `read_root` | 读取该目录及其下所有内容；没有 `write_root` 时也在此写入 | 404，与不存在相同；检索、上下文、记忆和变更流都不包含范围外的内容 |

- 没有路径的 Entry（`ingest`、项目记忆、提炼的事实）在两种范围之外，成员自己的 Agent 记忆除外。
- 读取根路径和写入根路径在目录重命名或移动后仍然有效。删除某个成员的读取根路径或写入根路径，或包含这些路径的目录时，服务返回 409 `directory_is_write_root` 或 `directory_is_read_root`，Space 所有者执行此操作时也是如此。
- `write_root` 不限制分支；合并写入主线时逐个路径检查，全部通过或全部不生效。
- [`GET /v2/spaces`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 和 [`GET /v2/spaces/{space_id}`](https://mirabase.io/zh/developers/api/spaces.md#spaces-read) 返回你自己的 `read_root` 和 `write_root`，从那里开始读 `tree`。

## 为 Agent 配置权限

为 Agent 创建独立的主体，不要共用人的 API Key。这样它的写入、记忆和审计都有自己的身份，吊销时不影响他人。

```bash
# 1. Create the Agent. Without grant_capabilities it gets knowledge:read.
curl -X POST https://api.mirabase.dev/v2/principals \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "agent", "grant_capabilities": ["knowledge:read", "knowledge:write"]}'

# 2. Make it a member of one Space. write_mode direct lets it change files it does not own.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor", "write_mode": "direct"}'

# 3. Issue its key, narrowed to that Space.
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$AGENT_ID'", "name": "docs-agent",
       "grant_capabilities": ["knowledge:read", "knowledge:write"],
       "allowed_space_ids": ["'$SPACE_ID'"]}'
```

## 按 Space 限定 API Key

- 访问收窄范围外的 Space 时，服务返回 404，与 Space 不存在时的响应相同。
- 受范围限制的 API Key 不能访问账户级和租户级功能：账户记忆、[`GET /v2/principals`](https://mirabase.io/zh/developers/api/principals.md#principals-list)、[`GET /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-list)、[`GET /v2/audit/events`](https://mirabase.io/zh/developers/api/audit.md#audit-events)。
- 比所属主体窄的 Key 只能为该主体签发 Key，因此切换身份也无法绕过限制。

## 不可见即不存在

看不见的资源和不存在的资源返回同一个 404。收到 403 时查看 [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami)，收到 404 时检查 id、Key 的 Space 范围和成员关系。

## 审计

[`GET /v2/audit/events`](https://mirabase.io/zh/developers/api/audit.md#audit-events) 返回治理和访问事件。事件只含标识符，不含用户内容。治理动作与它所做的修改在同一事务里记录，失败时一起回滚。

> **说明：** 权限变更在下一条语句立即生效，API Key 吊销也是如此，没有缓存窗口。

## 下一步

- [认证与 API Key](https://mirabase.io/zh/developers/authentication.md)：创建、轮换和吊销 Key。
- [文件与版本](https://mirabase.io/zh/developers/files.md#proposals)：提案的提交和审核。
- [错误码](https://mirabase.io/zh/developers/errors.md#codes)：403 的各个错误码分别表示什么。
