@m1a0rz/agent-identity 0.1.2

package/README-cn.md

@@ -0,0 +1,223 @@
+# Agent Identity 插件
+
+UserPool OIDC 登录、TIP (Trusted Identity Provider) 令牌（通过 Identity GetWorkloadAccessTokenForJWT 获取）、凭据 3LO（GetResourceOauth2Token/Oauth2Callback）以及 OpenClaw 的会话管理。
+
+集成 [火山引擎智能体身份和权限管理平台](https://www.volcengine.com/docs/86848)。术语映射：用户池 (UserPool)、入站授权 (OIDC login)、出站授权 (credential fetch)、工作负载令牌 (TIP)、凭据托管 (credential hosting)、权限管控 (CheckPermission)。
+
+> For English documentation, see [README.md](README.md)
+
+## 功能特性
+
+- **OIDC 登录**：`/identity login` 返回 IdP 授权 URL。用户打开 URL 后，IdP 重定向到 `/identity/oauth/callback`。
+- **TIP 令牌**：当会话中有已登录用户时，`before_agent_start` 钩子会获取 TIP 令牌。
+- **凭据 3LO**：`/identity fetch <provider>` 返回授权 URL。IdP 重定向到 Identity 提供的回调地址（控制台配置）。
+- **凭据绑定**：`/identity set <provider> <envVar>` 将存储的凭据绑定到环境变量。工具运行时在 `before_agent_start` 中注入到 `process.env`。
+- **动态 UserPool**：通过 `userPoolName` + `clientName` 解析 OIDC 配置（无需手动配置 clientId）。
+- **凭证加载**：从环境变量、文件或 STS AssumeRole 加载 AK/SK（veadk 风格）。
+
+## HTTP 端点
+
+仅暴露 OIDC 登录回调。凭据 OAuth 使用 Identity 回调。其余逻辑在 slash 命令中执行。
+
+| 路径                       | 方法 | 描述                     |
+| -------------------------- | ---- | ------------------------- |
+| `/identity/oauth/callback` | GET  | OIDC 登录回调（IdP 重定向到此） |
+
+## Slash 命令
+
+单一命令 `/identity`（别名 `/id`）及其子命令。无参数时默认：`status`。
+
+| 子命令                          | 描述                                                                 |
+| ------------------------------- | -------------------------------------------------------------------- |
+| _(无)_                          | 显示帮助。                                                           |
+| `whoami`                        | 显示当前会话身份（sub、TIP 状态）。                                  |
+| `login`                         | 已登录：刷新 TIP。未登录：返回需打开的 OIDC IdP URL。                |
+| `status`                        | 登录状态、TIP、凭据。会话存在时尝试刷新 TIP。                         |
+| `logout`                        | 清除当前会话的 session 和 TIP。                                      |
+| `list-tips`                     | 列出所有有效 TIP 令牌及其委托链、过期时间和环境变量绑定。            |
+| `config`                        | 显示 identity 插件配置（敏感信息脱敏）。                             |
+| `list-credentials` 或 `list [page]` | 分页列出控制台 provider 及已绑定的凭据。使用 `list 2` 加载更多。 |
+| `fetch <provider> [--flow=...]` | 添加凭据。flow 根据 provider 类型自动推断；可用 `--flow` 覆盖。       |
+| `set <provider> <envVar>`       | 将凭据绑定到环境变量供工具注入。无凭据时从 `process.env[envVar]` 导入。 |
+| `unset <provider>`              | 移除 provider 的环境变量绑定。                                       |
+| `approve <approval_id>`         | 审批待处理的高风险工具调用。                                         |
+| `reject <approval_id>`          | 拒绝待处理的高风险工具调用。                                         |
+
+## OIDC 登录流程
+
+1. 用户在聊天中发送 `/identity login`（如 Telegram、Discord）
+2. 命令根据 channel/sender 推导 sessionKey，构建 IdP 授权 URL，保存 state
+3. 命令返回 IdP URL，用户在浏览器中打开
+4. 用户在 UserPool IdP 完成登录
+5. IdP 携带 `code` 和 `state` 重定向到 `/identity/oauth/callback`
+6. 插件交换 code，创建会话，显示成功页并向聊天发送消息
+
+## 凭据获取流程
+
+**OAuth2（用户联邦或 M2M）：**
+
+1. 用户发送 `/identity fetch google` 或 `/identity fetch google --flow=oauth2-m2m`（在 `/identity login` 之后）
+2. 命令使用 TIP 调用 Identity API，返回授权 URL 或直接返回 token
+3. 若有授权 URL：用户打开，IdP 重定向到 Identity 回调（控制台 provider 配置）
+4. Identity 处理回调，获取 token；用户可再次执行 fetch 拉取凭据
+
+**API Key：**
+
+1. 用户发送 `/identity fetch openai`（控制台 provider 类型为 api_key）或 `/identity fetch openai --flow=apikey`
+2. 命令使用 TIP 调用 GetResourceApiKey，直接存储 API key
+
+flow 根据 ListCredentialProviders 的 Type 和 Flow 自动推断。可通过 `--flow=oauth2-user|oauth2-m2m|apikey` 覆盖。
+
+## 开通火山引擎 Agent Identity 服务
+
+使用本插件前，需先在火山引擎开通 **智能体身份和权限管理平台** 并完成授权。详见：
+
+- [开通智能体身份和权限管理平台并完成授权](https://www.volcengine.com/docs/86848/2123358?lang=zh)
+
+## 获取火山引擎 AK/SK
+
+插件调用 Identity API 需要火山引擎访问密钥（Access Key / Secret Key）。获取方式：
+
+- [创建 Access Key - 火山引擎文档](https://www.volcengine.com/docs/6291/65568?lang=zh)
+
+在控制台创建 AK/SK 后，可通过配置传入，或使用环境变量 `VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY`。
+
+## 安装
+
+```bash
+openclaw plugins install @m1a0rz/agent-identity
+```
+
+开发模式（link）：
+
+```bash
+openclaw plugins install --link .
+```
+
+## 配置
+
+在 `openclaw.json` 的 `plugins.entries.agent-identity.config` 下添加：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "agent-identity": {
+        "config": {
+          "identity": {
+            "endpoint": "https://id.cn-beijing.volcengineapi.com",
+            "accessKeyId": "<your-ak>",
+            "secretAccessKey": "<your-sk>",
+            "workloadPoolName": "default",
+            "workloadName": "openclaw-agent",
+            "audience": ["asi-gateway"],
+            "durationSeconds": 3600
+          },
+          "userpool": {
+            "discoveryUrl": "https://userpool-xxx.userpool.auth.id.cn-beijing.volces.com",
+            "clientId": "<client-id>",
+            "clientSecret": "<client-secret>",
+            "callbackUrl": "https://gateway.example.com/identity/oauth/callback",
+            "scope": "openid profile email"
+          },
+          "authz": {
+            "enable": false,
+            "namespaceName": "default",
+            "enableLlmRiskCheck": false,
+            "llmRiskCheck": {
+              "endpoint": "http://localhost:11434",
+              "api": "ollama",
+              "model": "qwen3:8b"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### identity 配置（必填与可选）
+
+| 参数 | 类型 | 必填 | 含义 |
+|------|------|------|------|
+| `endpoint` | string | 是 | Identity API 地址，如 `https://id.cn-beijing.volcengineapi.com` |
+| `accessKeyId` | string | 否* | 火山引擎 Access Key。不填时从 `VOLCENGINE_ACCESS_KEY` 或 `credentialsFile` 读取 |
+| `secretAccessKey` | string | 否* | 火山引擎 Secret Key。不填时从 `VOLCENGINE_SECRET_KEY` 或 `credentialsFile` 读取 |
+| `workloadPoolName` | string | 否 | 工作负载池名称，默认 `default` |
+| `workloadName` | string | 否 | 工作负载名称。不填时用 agentId 或 `openclaw-agent` |
+| `audience` | string[] | 否 | TIP token 的 audience |
+| `durationSeconds` | number | 否 | TIP token 有效期（秒），默认 3600 |
+| `roleTrn` | string | 否 | STS AssumeRole 的 Role TRN。设置后不传 workload name，后端使用 roleName |
+| `credentialsFile` | string | 否 | 凭证 JSON 文件路径。默认 `VOLCENGINE_CREDENTIALS_FILE` 或 `/var/run/secrets/iam/credential` |
+| `sessionToken` | string | 否 | STS 临时会话令牌（或 `VOLCENGINE_SESSION_TOKEN`） |
+
+\* AK/SK 至少通过 `accessKeyId`+`secretAccessKey`、环境变量或 `credentialsFile` 之一提供。
+
+### userpool 配置（OIDC 登录）
+
+**Explicit 模式**（必填）：`discoveryUrl`、`clientId`、`clientSecret`、`callbackUrl`、`scope`
+
+**Dynamic 模式**（必填）：`userPoolName`、`clientName`、`callbackUrl`；`autoCreate` 默认 true
+
+OAuth2 credential fetch 使用控制台配置的 redirect URL 和 scopes。可通过 `/identity fetch <provider> --redirectUrl` 和 `--scopes` 覆盖。
+
+### authz 配置（可选，默认关闭）
+
+| 参数 | 类型 | 含义 |
+|------|------|------|
+| `enable` | boolean | 是否启用 TIP + CheckPermission + 风险审批，默认 false |
+| `namespaceName` | string | CheckPermission 命名空间，默认 `default` |
+| `requireRiskApproval` | boolean | 高风险工具调用需用户审批，默认 true |
+| `enableLlmRiskCheck` | boolean | 规则返回 medium 时用 LLM 二次评估，默认 false |
+| `llmRiskCheck` | object | LLM 配置：`endpoint`、`api`、`model` 等 |
+
+### 工作负载与 TIP
+
+TIP token 通过 `GetWorkloadAccessTokenForJWT` 获取。工作负载行为：
+
+- **workloadName**（可选）：发送给 API 的工作负载名称。默认：会话中的 `agentId` 或 `"openclaw-agent"`。仅在不使用 `roleTrn` 时生效。
+- **roleTrn**（可选）：设置后（AssumeRole），插件**不**传递 workload name，后端使用 roleName。用于委托执行（如 VeFaaS、K8s IRSA）。
+- **自动创建工作负载**：当 `GetWorkloadAccessTokenForJWT` 返回 404（工作负载不存在）时，插件调用 `CreateWorkloadIdentity` 创建工作负载（Category: Agent），然后重试。仅在使用 workload name 时生效（未设置 `roleTrn`）。并发创建产生的 Duplicated (409) 会被忽略。
+
+### 飞书通知
+
+当用户从飞书聊天运行 `/identity` 时，登录成功和凭据获取的跟进消息会通过飞书发送。凭据从 openclaw.json 的 `channels.feishu` 读取（与 feishu 扩展相同：`appId`、`appSecret`，可选 `accounts`）。agent-identity 无需额外配置。
+
+**审批消息**（当高风险工具被拦截时）：若要向飞书（或 Telegram、Slack 等）推送审批请求，请在 openclaw.json 中将 `session.dmScope` 设置为 `per-channel-peer` 或 `per-account-channel-peer`。默认 `session.dmScope: "main"` 时，sessionKey 不包含 channel/peer 信息，插件无法推导推送目标，审批消息不会推送。用户仍可在 agent 的错误回复中看到 block/approval_id；使用 `/identity approve <id>` 审批。
+
+### WebChat / TUI
+
+用户从 WebChat 或 TUI 运行 `/identity` 时，跟进消息不会投递；插件无 API 推送至这些渠道。请使用 `/identity status` 确认结果。
+
+## 工具
+
+- **identity_whoami** - 显示当前会话身份（sub、TIP 状态）
+- **identity_status** - 登录状态、凭据、绑定
+- **identity_login** - 启动 OIDC 登录或刷新 TIP
+- **identity_logout** - 清除 session 和 TIP
+- **identity_list_credentials** - 列出 provider 和凭据（分页）
+- **identity_list_tips** - 列出有效 TIP 令牌和绑定
+- **identity_config** - 显示插件配置（脱敏）
+- **identity_fetch** - 添加凭据（provider、flow?、redirectUrl?、scopes?）
+- **identity_set_binding** - 绑定 provider → 环境变量
+- **identity_unset_binding** - 移除环境变量绑定
+- **identity_approve_tool** - 可选工具；按 approval_id 审批高风险工具调用。推荐用户使用 `/identity approve <id>`（仅人工；agent 不得自批）。
+- **identity_risk_check** - 诊断命令或工具调用的风险（command 或 toolName+params）
+- **identity_list_risk_patterns** - 列出内置危险命令和敏感路径
+
+## 钩子
+
+- **before_agent_start** - 获取 TIP token；按 credential-env-bindings（按 session）将凭据注入到 `process.env`
+- **after_tool_call** - 在 `sessions_spawn` 时将 TIP 传播到子会话
+- **before_tool_call** - 当 authz.enable 时可选 AuthZ（TIP + CheckPermission + 风险审批）。评估用户提供的命令/路径风险（规则 + 可选 LLM）。高风险调用需审批；LLM 风险原因会出现在审批提示和拦截消息中。
+
+## 数据存储
+
+插件数据位于 `~/.openclaw/plugins/identity/`：
+
+- `sessions.json` - sessionKey → userToken 映射（加载/保存时清理过期）
+- `tip-tokens.json` - sessionKey → TIP token 缓存（加载/保存时清理过期）
+- Credentials - 仅内存，按 session（api_key、oauth2）；gateway 重启后丢失；logout 时清除
+- `credential-env-bindings.json` - 按 session：`{ [sessionKey]: { [provider]: envVar } }`
+- OIDC state - 仅内存（临时，5 分钟 TTL）

package/README.md

@@ -0,0 +1,223 @@
+# Agent Identity Plugin
+
+UserPool OIDC login, TIP (Trusted Identity Provider) token via Identity GetWorkloadAccessTokenForJWT, credential 3LO (GetResourceOauth2Token/Oauth2Callback), and session management for OpenClaw.
+
+> 中文文档请参阅 [README-cn.md](README-cn.md)
+
+Integrates with [Volcengine Agent Identity and Permission Management](https://www.volcengine.com/docs/86848).
+
+## Features
+
+- **OIDC Login**: `/identity login` returns IdP auth URL (no HTTP start endpoint). User opens URL, IdP redirects to `/identity/oauth/callback`.
+- **TIP Token**: `before_agent_start` hook fetches TIP token when session has a logged-in user
+- **Credential 3LO**: `/identity fetch <provider>` returns auth URL. IdP redirects to Identity-provided callback (control-plane config).
+- **Credential Binding**: `/identity set <provider> <envVar>` binds stored credential to env var. Credentials are injected into `process.env` in `before_agent_start` when tools run.
+- **Dynamic UserPool**: Resolve OIDC config by `userPoolName` + `clientName` (no manual clientId)
+- **Credentials**: Load AK/SK from env, file, or STS AssumeRole (veadk-style)
+
+## HTTP Endpoints
+
+Only the OIDC login callback is exposed. Credential OAuth uses Identity callback. All other logic runs in slash commands.
+
+| Path                       | Method | Description                              |
+| -------------------------- | ------ | ---------------------------------------- |
+| `/identity/oauth/callback` | GET    | OIDC login callback (IdP redirects here) |
+
+## Slash Commands
+
+Single command `/identity` (alias `/id`) with subcommands. Default with no args: `status`.
+
+| Subcommand                          | Description                                                                                                   |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| _(none)_                            | Show help.                                                                                                    |
+| `whoami`                            | Show current session identity (sub, TIP status).                                                              |
+| `login`                             | If logged in: refresh TIP. If not: return OIDC IdP URL to open.                                               |
+| `status`                            | Show login status, TIP, credentials. Tries to refresh TIP when session exists.                                |
+| `logout`                            | Clear session and TIP for current session.                                                                    |
+| `list-tips`                         | List all valid TIP tokens with delegation chain, expiry, and env bindings.                                    |
+| `config`                            | Show identity plugin config (sensitive values redacted).                                                      |
+| `list-credentials` or `list [page]` | List providers from control plane (paginated) and your credentials with bound env. Use `list 2` to load more. |
+| `fetch <provider> [--flow=...]`     | Add credential. Flow auto-inferred from provider type (api_key/oauth2/m2m); override with `--flow`.           |
+| `set <provider> <envVar>`           | Bind credential to env var for tool injection. If no credential, import from `process.env[envVar]`.           |
+| `unset <provider>`                  | Remove env binding for provider.                                                                              |
+| `approve <approval_id>`             | Approve a pending high-risk tool call.                                                                         |
+| `reject <approval_id>`              | Reject a pending high-risk tool call.                                                                          |
+
+## OIDC Login Flow
+
+1. User sends `/identity login` in chat (e.g. Telegram, Discord)
+2. Command derives sessionKey from channel/sender, builds IdP authorize URL, stores state
+3. Command returns the IdP URL; user opens it in browser
+4. User completes login at UserPool IdP
+5. IdP redirects to `/identity/oauth/callback` with `code` and `state`
+6. Plugin exchanges code, creates session, shows success page and sends message to chat
+
+## Credential Fetch Flow
+
+**OAuth2 (user federation or M2M):**
+
+1. User sends `/identity fetch google` or `/identity fetch google --flow=oauth2-m2m` (after `/identity login`)
+2. Command uses TIP to call Identity API; returns auth URL or direct token
+3. If auth URL: user opens it; IdP redirects to Identity callback (control-plane provider config)
+4. Identity handles callback; token obtained via Identity; user may re-run fetch to pull credential
+
+**API Key:**
+
+1. User sends `/identity fetch openai` (provider type api_key in control plane) or `/identity fetch openai --flow=apikey`
+2. Command uses TIP to call GetResourceApiKey; API key stored directly
+
+Flow is auto-inferred from ListCredentialProviders (Type + Flow). Override with `--flow=oauth2-user|oauth2-m2m|apikey` when needed.
+
+## Enable Volcengine Agent Identity Service
+
+Before using this plugin, you must enable **Agent Identity and Permission Management** in Volcengine and complete authorization. See:
+
+- [Enable Agent Identity Service (Chinese)](https://www.volcengine.com/docs/86848/2123358?lang=zh)
+
+## Get Volcengine AK/SK
+
+The plugin requires Volcengine Access Key and Secret Key to call the Identity API. To create credentials:
+
+- [Create Access Key - Volcengine Docs](https://www.volcengine.com/docs/6291/65568?lang=zh)
+
+After creating AK/SK in the console, pass them via config or use environment variables `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`.
+
+## Installation
+
+```bash
+openclaw plugins install @m1a0rz/agent-identity
+```
+
+Or with link for development:
+
+```bash
+openclaw plugins install --link .
+```
+
+## Configuration
+
+Add to `openclaw.json` under `plugins.entries.agent-identity.config`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "agent-identity": {
+        "config": {
+          "identity": {
+            "endpoint": "https://id.cn-beijing.volcengineapi.com",
+            "accessKeyId": "<your-ak>",
+            "secretAccessKey": "<your-sk>",
+            "workloadPoolName": "default",
+            "workloadName": "openclaw-agent",
+            "audience": ["asi-gateway"],
+            "durationSeconds": 3600
+          },
+          "userpool": {
+            "discoveryUrl": "https://userpool-xxx.userpool.auth.id.cn-beijing.volces.com",
+            "clientId": "<client-id>",
+            "clientSecret": "<client-secret>",
+            "callbackUrl": "https://gateway.example.com/identity/oauth/callback",
+            "scope": "openid profile email"
+          },
+          "authz": {
+            "enable": false,
+            "namespaceName": "default",
+            "enableLlmRiskCheck": false,
+            "llmRiskCheck": {
+              "endpoint": "http://localhost:11434",
+              "api": "ollama",
+              "model": "qwen3:8b"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### identity config (required vs optional)
+
+| Param | Type | Required | Description |
+|-------|------|----------|--------------|
+| `endpoint` | string | Yes | Identity API URL, e.g. `https://id.cn-beijing.volcengineapi.com` |
+| `accessKeyId` | string | No* | Volcengine Access Key. Omit to load from `VOLCENGINE_ACCESS_KEY` or `credentialsFile` |
+| `secretAccessKey` | string | No* | Volcengine Secret Key. Omit to load from `VOLCENGINE_SECRET_KEY` or `credentialsFile` |
+| `workloadPoolName` | string | No | Workload pool name, default `default` |
+| `workloadName` | string | No | Workload name. Default: agentId or `openclaw-agent` |
+| `audience` | string[] | No | TIP token audience |
+| `durationSeconds` | number | No | TIP token TTL (seconds), default 3600 |
+| `roleTrn` | string | No | Role TRN for STS AssumeRole. When set, workload name is omitted; backend uses roleName |
+| `credentialsFile` | string | No | Path to credential JSON. Default: `VOLCENGINE_CREDENTIALS_FILE` or `/var/run/secrets/iam/credential` |
+| `sessionToken` | string | No | STS session token (or `VOLCENGINE_SESSION_TOKEN`) |
+
+\* AK/SK must be provided via `accessKeyId`+`secretAccessKey`, environment variables, or `credentialsFile`.
+
+### userpool config (OIDC login)
+
+**Explicit mode** (required): `discoveryUrl`, `clientId`, `clientSecret`, `callbackUrl`, `scope`
+
+**Dynamic mode** (required): `userPoolName`, `clientName`, `callbackUrl`; `autoCreate` defaults to true
+
+OAuth2 credential fetch uses control-plane redirect URL and scopes. Override via `/identity fetch <provider> --redirectUrl` and `--scopes`.
+
+### authz config (optional, disabled by default)
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `enable` | boolean | Enable TIP + CheckPermission + risk approval, default false |
+| `namespaceName` | string | CheckPermission namespace, default `default` |
+| `requireRiskApproval` | boolean | Require user approval for high-risk tools, default true |
+| `enableLlmRiskCheck` | boolean | Re-evaluate with LLM when rules return medium, default false |
+| `llmRiskCheck` | object | LLM config: `endpoint`, `api`, `model`, etc. |
+
+### Workload and TIP
+
+TIP token is obtained via `GetWorkloadAccessTokenForJWT`. Workload behavior:
+
+- **workloadName** (optional): Workload name sent to the API. Default: `agentId` from session, or `"openclaw-agent"`. Used only when not using `roleTrn`.
+- **roleTrn** (optional): When set (AssumeRole), the plugin does **not** pass workload name; the backend uses the role name. Use this for delegated execution (e.g. VeFaaS, K8s IRSA).
+- **Auto-create workload**: When `GetWorkloadAccessTokenForJWT` returns 404 (workload not found), the plugin calls `CreateWorkloadIdentity` to create the workload (Category: Agent), then retries. Only applies when a workload name is used (no `roleTrn`). Duplicated (409) from concurrent create is ignored.
+
+### Feishu notifications
+
+Login success and credential fetch follow-up messages (e.g. "✓ Credential for `google` added.") are sent via Feishu when the user runs `/identity` from a Feishu chat. Credentials are read from `channels.feishu` in openclaw.json (same as feishu extension: `appId`, `appSecret`, optional `accounts`). No extra config in agent-identity is required.
+
+**Approval messages** (when a high-risk tool is blocked): For approval requests to be delivered to Feishu (or Telegram, Slack, etc.), set `session.dmScope` to `per-channel-peer` or `per-account-channel-peer` in openclaw.json. With default `session.dmScope: "main"`, the sessionKey does not include channel/peer info, so the plugin cannot derive a delivery target and approval messages are not pushed. The user will still see the block/approval_id in the agent's error reply; use `/identity approve <id>` to approve.
+
+### WebChat / TUI
+
+Follow-up messages (login success, credential fetch done) are not delivered when the user runs `/identity` from WebChat or TUI; the plugin has no API to push to those channels. Use `/identity status` to confirm results.
+
+## Tools
+
+- **identity_whoami** - Show current session identity (sub, TIP status)
+- **identity_status** - Login status, credentials, bindings
+- **identity_login** - Start OIDC login or refresh TIP
+- **identity_logout** - Clear session and TIP
+- **identity_list_credentials** - List providers and credentials (paginated)
+- **identity_list_tips** - List valid TIP tokens and bindings
+- **identity_config** - Show plugin config (redacted)
+- **identity_fetch** - Add credential (provider, flow?, redirectUrl?, scopes?)
+- **identity_set_binding** - Bind provider → env var
+- **identity_unset_binding** - Remove env binding
+- **identity_approve_tool** - Optional tool; approve high-risk tool call by approval_id. Prefer `/identity approve <id>` (human-only; agent must not self-approve).
+- **identity_risk_check** - Diagnose risk for a command or tool call (command, or toolName+params)
+- **identity_list_risk_patterns** - List built-in dangerous commands and sensitive paths
+
+## Hooks
+
+- **before_agent_start** - Fetch TIP token; inject credentials into `process.env` per credential-env-bindings (per-session)
+- **after_tool_call** - Propagate TIP to child session on `sessions_spawn`
+- **before_tool_call** - Optional AuthZ (TIP + CheckPermission + risk approval) when authz.enable. Evaluates user-provided commands/paths for risk (rules + optional LLM). High-risk calls require approval; the LLM risk reason is included in approval prompts and block messages when available.
+
+## Data Storage
+
+Plugin data at `~/.openclaw/plugins/identity/`:
+
+- `sessions.json` - sessionKey → userToken mapping (expired pruned on load/save)
+- `tip-tokens.json` - sessionKey → TIP token cache (expired pruned on load/save)
+- Credentials - in-memory only, per-session (api_key, oauth2); lost on gateway restart; cleared on logout
+- `credential-env-bindings.json` - per-session: `{ [sessionKey]: { [provider]: envVar } }`
+- OIDC state - in-memory only (ephemeral, 5 min TTL)

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent Identity Plugin
+ *
+ * - UserPool login via /identity login (OIDC URL returned directly, no HTTP start endpoint)
+ * - Credential hosting: list-credentials, fetch <provider>, set <provider> <envVar>
+ * - TIP token via CIS GetWorkloadAccessTokenForJWT in before_agent_start
+ * - Sub-agent TIP propagation in after_tool_call (sessions_spawn)
+ * - Optional AuthZ in before_tool_call
+ * - HTTP callback: /identity/oauth/callback (OIDC login). Credential OAuth uses Identity-provided callback.
+ * - Tools: identity_whoami, identity_logout
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+export default function register(api: OpenClawPluginApi): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAwD7D,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAgTtD"}