# Skill 认证

将 Skill credential 放在环境中的 XMEMO_KEY 或支持的 device-login flow 中，绝不放入 public output。

- Canonical: https://docs.xmemo.dev/zh/docs/skills/authentication
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: be9eeb314af1163f47f713234e990cb81a2e76a585a0fe87f77a4a45fcecb506
- Edition-Digest: 4f5e6abfb471181913740f6268994de21ba968c62f7429c9e32026ebb1af9db7
- Source-Revision: sha256:bd8b11d078e9e281fe66b1a4a5591f15aaaae0518de04b052b0c28ef43a177c1

## Credential 解析优先级

独立 Skill 运行时按照严格的三级优先级解析 credential。托管的外部密钥始终优先于本地文件，确保在提供了环境密钥时不会将 token 重复写入磁盘。

- 1. XMEMO_KEY：环境变量或托管密钥库（Doppler、1Password、Vault）。首选方式；绝不会复制到本地 credential 文件中。
- 2. Meta Muse Secure Vault：在受支持的 Meta Muse 环境中的替代保险库解析。
- 3. 本地 credential 文件：~/.xmemo/skill-credentials.json（或 $XMEMO_CREDENTIALS_PATH），仅在未设置环境 credential 时作为回退读取。
- OpenClaw 出站要求：OpenClaw 出站是在 XMEMO_KEY 分支内部处理的传输要求（auth-state.mjs）。如果检测到 OpenClaw 哨兵，将强制要求出站代理可达；这是 XMEMO_KEY 内部的传输验证，而非单独的 credential 来源。
- 零 token 暴露：命令和 doctor 诊断绝不会打印活动 token 或密钥前缀。

```bash
# Preferred: provide credential via environment or secret store
export XMEMO_KEY='<your-xmemo-token>'

# Inspect active credential source and scopes without printing secrets:
node scripts/xmemo-skill.mjs auth status --verify
```

## 设备登录与知情明文选择

当不存在托管环境密钥时，交互式设置使用基于浏览器的设备授权。用户在浏览器中批准访问，且浏览器绝不会显示 bearer token 值。

- 显式明文许可：login 命令需要 --allow-plaintext 以确认将 token 未加密保存在本地机器上的知情许可。
- 受限文件权限：~/.xmemo/skill-credentials.json 以 0600 POSIX 权限创建（仅所有者可读写）。
- 安全标准输入导入：使用 auth add --from-stdin --allow-plaintext 通过标准输入导入现有 token，避免命令行参数和 shell 历史记录。
- 设备授权端点：POST /v1/auth/device/start（启动流程），POST /v1/auth/device/token（轮询与交换），POST /v1/auth/token/validate（验证），POST /v1/auth/token/revoke-self（撤回）。

```bash
# Start interactive device login (requires explicit plaintext flag):
node scripts/xmemo-skill.mjs login --allow-plaintext

# Or pipe an existing token securely from standard input:
printf '%s' "$XMEMO_KEY" | node scripts/xmemo-skill.mjs auth add --from-stdin --allow-plaintext

# Verify active session status:
node scripts/xmemo-skill.mjs auth status --verify
```

## 临时注册边界

对于无人值守环境或人工拒绝正式登录的情况，Skill 可以注册临时记忆沙盒。临时记忆受到严格限制，仅用于短暂的运行连续性。

- 仅限无人值守或已拒绝：node scripts/xmemo-skill.mjs register --reason <unattended|declined> --allow-plaintext。
- 容量上限：限制为最多 100 项。
- 保留 TTL：14 天不活跃 TTL 和 30 天绝对最长生命周期。
- 两阶段认领移交：生成一个绑定 URL（bind_url），允许人工操作员认领该临时账户并将其绑定到正式 credential。
- 认领管理命令：auth claim-status 检查待处理的认领，auth claim-confirm 接受正式 token 移交，auth claim-deny 拒绝绑定。
- 沙盒限制：临时账户无法捕获重启快照（restart-snapshot）或访问知识库（recall-context --include_knowledge true）。

```bash
# Register temporary sandbox:
node scripts/xmemo-skill.mjs register --reason unattended --allow-plaintext

# Inspect and manage claim binding:
node scripts/xmemo-skill.mjs auth claim-status --allow-plaintext
node scripts/xmemo-skill.mjs auth claim-confirm --allow-plaintext
node scripts/xmemo-skill.mjs auth claim-deny --allow-plaintext
```

## 注销与适当提供商的撤回

注销会取消本地 credential 文件的链接，并在服务器上自行撤回活动会话 token。外部密钥提供商必须在其自身环境中进行管理。

- 本地会话注销：node scripts/xmemo-skill.mjs logout 移除 ~/.xmemo/skill-credentials.json 并调用 /v1/auth/token/revoke-self。
- 外部环境 token：当 XMEMO_KEY 提供活动 credential 时，注销会保留该 token，除非显式传递了 --revoke-environment-token。
- 本地移除不等于全局撤回：移除本地 skill 目录或在本地注销不会撤回存储在云密钥保险库、CI/CD runner 或其他机器中的 token。
- 外部清理：在 shell 中取消设置 XMEMO_KEY 或从密钥管理器中删除密钥以永久取消访问授权。

```bash
# Log out and revoke local credential file:
node scripts/xmemo-skill.mjs logout

# Log out and revoke external environment token remotely:
node scripts/xmemo-skill.mjs logout --revoke-environment-token
```