# 认证边界

区分 OAuth 同意、bearer token 存储、identity header 与已认证访问决策。

- Canonical: https://docs.xmemo.dev/zh/docs/security/authentication
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 7db78d94f9134263232f217ac1a0f2eb57b88ca22e0cf065f3048a20722fd448
- Edition-Digest: 8e64df02232da573fe9fe8647bd2a12cc2c26e6957bf63c7e6774514dd2b5323
- Source-Revision: sha256:ee40679d8c2e2aed685ae161cfdb51750fe7be7d9ee62448f8afa4760b35e76c

## 每种凭据应放在哪里

认证边界区分 OAuth 同意、bearer token 存储、非机密 identity header 与实际访问决策。把它们混在一起是 token 泄露最常见的原因。

- OAuth 同意发生在客户端；在这条路径上 XMemo 不会看到粘贴的 token。
- XMEMO_KEY 应放在环境或受支持的 secret store 中，绝不要放进已提交到 git 的配置文件。
- Identity header 只是普通标签，可以安全地写入配置。
- 公共 discovery 只读且不包含 secret。

## 基于 token 的客户端配置

在客户端配置中引用环境变量，使真实值永远不会出现在文件里。

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}
```

## 被拒绝的请求是什么样

缺少凭据或凭据权限不足时，请求会在读取任何 memory 之前被拒绝。空结果集是有效的无匹配响应，不代表授权信号。

```text
401 — no valid bearer token or API key was supplied.
403 — the credential is valid but lacks memory:read or memory:write.
200 with zero results — authorized, nothing matched.
```

## Memory Console 控制

XMemo 不只是一个 MCP endpoint。Memory Console 是面向用户的管理入口，可查看、修正、删除和导出记忆，同时保留 agent 归因可见。

### 查看和搜索记忆

打开控制台查看已保存的记忆、检查路径和记忆类型，并确认某次召回是否应该返回特定条目。

### 编辑或修正条目

修正过时事实、移动到更清晰的路径，或替换旧备注，让后续助手召回用户认可的最新上下文。

### 删除和导出

使用账号流程删除不再需要的记忆，并找到账号范围记忆审查的导出路径。

### Agent 归因

查看是哪一个客户端或 runner 写入了记忆，包括客户端发送的非密钥 agent 与 instance 标签。

### 隐私与凭据控制

在扩大个人或团队试点前，保持 OAuth 授权、direct-token 使用、环境变量密钥交接和支持边界可见。