@volcengine/agent-identity 1.3.2

package/identity/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: identity
+description: |
+  UserPool login, TIP token, credential hosting, and tool risk evaluation. Activate when user needs to check identity (whoami/status), log in, list/add credentials, manage env bindings, configure the plugin, or diagnose risky tool calls.
+  Also activates for: 用户说登录、查身份、获取凭据、添加/配置API密钥、绑定环境变量、配置插件、风险检查.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔐",
+        "skillKey": "identity",
+        "requires": { "config": ["plugins.entries.agent-identity.enabled"] },
+      },
+  }
+---
+
+# Agent Identity
+
+Use the agent-identity plugin for UserPool OIDC login, TIP token, credential hosting (OAuth2, API key), and optional tool risk approval (AuthZ).
+
+**Agent rules:**
+
+- Call tools directly. Never suggest slash commands to the user.
+- When any tool returns an `authUrl` field, **always display it as a markdown link** to the user, e.g. `[Click here to log in](https://...)` or `[Click here to authorize](https://...)`. Never paste the bare URL as plain text — long OAuth URLs with special characters get truncated by chat platforms.
+- **Critical — auto-login on AuthZ block:** When ANY tool call fails with an error containing "TIP token required" or "session has no valid identity", you MUST immediately call `identity_login` to initiate login, display the `authUrl` to the user, and wait for them to complete authentication. After login succeeds, retry the original tool call. Do NOT skip the blocked action, try alternative approaches, or tell the user to run commands manually.
+- **Critical — always report permission errors to the user:** When a tool call is blocked with errors like "CheckPermission denied", "permission denied", "requires approval", or any `[agent-identity]` prefixed error, you MUST:
+  1. **Tell the user clearly** what was blocked and why (include the tool/skill name and the error message).
+  2. **Never silently ignore** the error or skip to something else without informing the user.
+  3. For "CheckPermission denied for skill ..." — tell the user they do not have access to that skill and suggest contacting an administrator.
+  4. For "CheckPermission denied for tool ..." — tell the user the tool is restricted and they lack permission to use it.
+  5. For "High-risk tool requires approval" — OpenClaw will present the native approval UI automatically; wait for the user to approve before retrying.
+  6. For "Failed to verify permission" — report a temporary error and suggest retrying later.
+
+## Tool Parameters
+
+### identity_login
+
+Starts OIDC login or refreshes TIP. **Call when:** "login", "登录", "sign in", "我需要先登录". Required before `identity_fetch`. No params.
+
+**Returns:**
+
+- Already logged in: `{ ok: true, sub, message }` — inform user they are already authenticated.
+- Needs login: `{ ok: false, authUrl, message }` — **you MUST display the `authUrl` as a markdown link** and tell them to open it in a browser. After they authorize, a success message will be sent to the chat automatically. Example response: "Please complete login in your browser: [Click here to log in](authUrl)"
+- Error: `{ error, authUrl: null }` — report the error.
+
+### identity_whoami
+
+Brief identity check. **Call when:** "who am I", "查身份", "am I logged in", "当前登录状态". No params.
+
+Returns: `sub`, `hasTip`, `loggedIn`, `sessionLoginAt`, `sessionExpiresAt`, `tipIssuedAt`, `tipExpiresAt`, `tipExpiresInSeconds`, `tipChain`.
+
+### identity_status
+
+Full status including credentials and bindings. **Call when:** "status", "查看完整状态", "我的凭据和绑定", "show my credentials and bindings". No params.
+
+Returns: `loggedIn`, `sub`, `hasTip`, `session` (loginAt, expiresAt), `tip` (issuedAt, expiresAt, chain), `credentialProviders`, `bindings`.
+
+### identity_logout
+
+Clear session and TIP. **Call when:** "logout", "登出", "sign out". No params.
+
+### identity_list_credentials
+
+Lists available credential providers and stored credentials. Supports filtering by name or flow to locate a specific provider without paging through all results. **Call when:** "有哪些服务可以连接", "what providers are available", "我添加了哪些凭据", "list my credentials", "查找某个 provider"
+
+| Param  | Type   | Required | Description                                                        |
+| ------ | ------ | -------- | ------------------------------------------------------------------ |
+| `page` | number | No       | Page number (default: 1)                                           |
+| `name` | string | No       | Filter providers by name (exact or prefix match)                   |
+| `flow` | string | No       | Filter providers by flow, e.g. `M2M` or `USER_FEDERATION`         |
+
+When looking for a specific provider (e.g. before `identity_fetch`), prefer passing `name` filter instead of paging through results.
+
+Returns: `providers`, `storedOnly`, `page`, `hasMore`.
+
+### identity_list_roles
+
+Lists **STS role credential providers** (not OAuth/API key — use `identity_list_credentials` for those). **Call when:** "role credentials", "STS providers", "IAM role 凭据", "有哪些角色凭据". Requires login session.
+
+Optional param: `name` — prefix filter on provider name.
+
+Returns: `providers` (each may include `identitySource`). To obtain temporary keys for a provider, use `identity_get_role_credentials` with that provider name.
+
+### identity_fetch
+
+Adds a credential for a provider (OAuth2 or API key). **Call when the user wants to add, get, or configure credentials:**
+
+- "帮我添加 Google 凭据", "get credentials for OpenAI", "connect my GitHub", "配置 API key", "授权访问某平台"
+
+First ensure user is logged in (`identity_whoami`); if not, use `identity_login`. Then call `identity_fetch` with the provider.
+
+| Param         | Type     | Required | Description                                                                             |
+| ------------- | -------- | -------- | --------------------------------------------------------------------------------------- |
+| `provider`    | string   | Yes      | Provider name (e.g. `google`, `openai`)                                                 |
+| `flow`        | string   | No       | `oauth2-user` (default for 3LO), `oauth2-m2m`, or `apikey`. Auto-inferred when omitted. |
+| `redirectUrl` | string   | No       | OAuth redirect URL (when provider requires custom)                                      |
+| `scopes`      | string[] | No       | OAuth scopes (e.g. `["email", "profile"]`)                                              |
+| `returnValue` | boolean  | No       | When true and fetch succeeds, include credential `value` in result. Default false.       |
+
+**Response:**
+
+- **OAuth2-user (success: true)**: Server had a cached token — credential added immediately. No further action needed.
+- **OAuth2-user (authUrl)**: User must authorize. **Display as markdown link** `[Click here to authorize](authUrl)`. A background process will detect when authorization completes and trigger the agent to continue automatically. If that does not happen within a reasonable time, **call `identity_fetch` again with the same provider** to check status.
+- **OAuth2-m2m** / **apikey**: `success: true`, `message` (completes immediately). If `returnValue: true`, also includes `value`.
+
+### identity_set_binding
+
+Binds a stored credential to an env var for tool injection. **Call when:** "让工具能用我的凭据", "bind my credential for tools", "inject my key for API calls"
+
+Credential must exist first (`identity_fetch`). Common env vars: `GOOGLE_ACCESS_TOKEN`, `OPENAI_API_KEY`, `GITHUB_TOKEN`.
+
+| Param      | Type   | Required | Description                                                                              |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
+| `provider` | string | Yes      | Provider name (e.g. `google`)                                                            |
+| `envVar`   | string | Yes      | Env var for injection (e.g. `GOOGLE_ACCESS_TOKEN`). Must match `[A-Za-z_][A-Za-z0-9_]*`. |
+
+If credential exists: binds it. Else: imports from `process.env[envVar]` as api_key.
+
+### identity_unset_binding
+
+| Param      | Type   | Required | Description                             |
+| ---------- | ------ | -------- | --------------------------------------- |
+| `provider` | string | Yes      | Provider name to unbind (e.g. `google`) |
+
+### identity_risk_check
+
+Evaluates risk of a command or tool call. **Call when:** "这个命令安全吗", "is this risky", "帮我评估风险"
+
+| Param      | Type     | Required | Description                                            |
+| ---------- | -------- | -------- | ------------------------------------------------------ |
+| `command`  | string   | No*      | Shell command to evaluate                              |
+| `toolName` | string   | No*      | Tool name (e.g. write, apply_patch). Use with `params`. |
+| `params`   | object   | No       | Tool params                                            |
+
+*Provide either `command` or `toolName`. Returns `risk`, `reason`, `source`.
+
+### identity_list_risk_patterns
+
+Returns built-in dangerous command patterns and sensitive paths. No params.
+
+### identity_config_suggest
+
+Generates config snippets. **Call when:** "如何配置 identity 插件", "帮我配置登录", "怎么开启权限检查"
+
+| Param   | Type   | Required | Description                                                                 |
+| ------- | ------ | -------- | --------------------------------------------------------------------------- |
+| `intent`| string | No       | `identity`, `userpool`, `authz`, `llm_risk`, or `full` (default)            |
+| `lang`  | string | No       | `en` or `zh`. Default: en                                                   |
+
+Returns: `configPath`, `config` (JSON to merge), `instructions`, `nextSteps`.
+
+## Workflow: Adding a Credential
+
+1. **Check login**: `identity_whoami`. If not logged in, call `identity_login`. When it returns `authUrl`, **display as markdown link** `[Click here to log in](authUrl)`.
+2. **Add credential**: `identity_fetch` with `provider`. If it returns `authUrl`, display the link. The agent will be notified automatically when the user completes authorization. If not resumed automatically, **call `identity_fetch` again** to check status.
+3. **Bind for tools** (optional): `identity_set_binding` so the credential is injected as an env var when tools run.
+
+## Workflow: Checking Risk
+
+1. `identity_risk_check` with `command` or `toolName`+`params`. Returns risk level and reason.
+2. `identity_list_risk_patterns` to see what triggers high-risk.
+
+## Notes
+
+- `identity_login`, `identity_logout`, `identity_whoami`, `identity_status`, and `identity_config_suggest` work without login.
+- `identity_risk_check` and `identity_list_risk_patterns` work without login.

package/openclaw.plugin.json

@@ -0,0 +1,243 @@
+{
+  "id": "agent-identity",
+  "name": "Agent Identity",
+  "description": "UserPool (用户池) login, TIP token (工作负载令牌 GetWorkloadAccessTokenForJWT), credential 3LO (凭据托管), session management, optional agent/tool/skill permission control (CheckPermission) and risk approval. Integrates with Volcengine 智能体身份和权限管理平台. Credentials from config, env, or file; STS AssumeRole supported.",
+  "skills": ["./identity"],
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "identity_whoami",
+      "identity_logout",
+      "identity_status",
+      "identity_login",
+      "identity_list_credentials",
+      "identity_list_roles",
+      "identity_list_tips",
+      "identity_config",
+      "identity_config_suggest",
+      "identity_fetch",
+      "identity_get_role_credentials",
+      "identity_get_tip_token",
+      "identity_get_session_token",
+      "identity_set_binding",
+      "identity_unset_binding",
+      "identity_risk_check",
+      "identity_list_risk_patterns"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "identity": {
+        "type": "object",
+        "description": "Identity API config (service code: id).",
+        "properties": {
+          "endpoint": {
+            "type": "string",
+            "description": "Identity API endpoint, e.g. https://id.cn-beijing.volcengineapi.com. Highest priority; when set, regionMetadataUrl is ignored for the base URL."
+          },
+          "regionMetadataUrl": {
+            "type": "string",
+            "description": "GET this URL for plain-text region id (e.g. http://100.96.0.96/latest/region_id). When endpoint is unset, builds https://id.{region}.volcengineapi.com. Request timeout ~10s; on failure falls back to https://id.cn-beijing.volcengineapi.com"
+          },
+          "accessKeyId": {
+            "type": "string",
+            "description": "Optional. When omitted, loaded from VOLCENGINE_ACCESS_KEY or credentialsFile"
+          },
+          "secretAccessKey": {
+            "type": "string",
+            "description": "Optional. When omitted, loaded from VOLCENGINE_SECRET_KEY or credentialsFile"
+          },
+          "sessionToken": {
+            "type": "string",
+            "description": "Optional STS session token (or VOLCENGINE_SESSION_TOKEN)"
+          },
+          "credentialsFile": {
+            "type": "string",
+            "description": "Path to credential JSON (VeFaaS style). Default: VOLCENGINE_CREDENTIALS_FILE or /var/run/secrets/iam/credential"
+          },
+          "credentialsMetadataUrl": {
+            "type": "string",
+            "description": "Full URL for remote credential fetch. When set with roleTrn, fetches from URL then AssumeRole with roleTrn. Response: AccessKeyId, SecretAccessKey, SessionToken. 404 falls through to credentialsFile. Caches AssumeRole result by ExpiredTime. Must be explicitly configured."
+          },
+          "roleTrn": {
+            "type": "string",
+            "description": "Role TRN for STS AssumeRole. When set (and workloadName not set), workload name is omitted; backend uses roleName. Priority: workloadName > roleTrn > params."
+          },
+          "workloadName": {
+            "type": "string",
+            "description": "Workload name for TIP. When set, takes precedence over roleTrn. Default when neither set: agentId or openclaw-agent."
+          },
+          "workloadPoolName": {
+            "type": "string",
+            "default": "default"
+          },
+          "audience": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Audience for the TIP token"
+          },
+          "durationSeconds": {
+            "type": "number",
+            "default": 3600
+          },
+          "subagentTipPropagation": {
+            "type": "boolean",
+            "default": false,
+            "description": "Propagate TIP and session to subagents (sessions_spawn, sessions_send). When true, subagents get their own TIP token."
+          },
+          "webchatSessionExchange": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable identity.session.put / identity.session.get gateway WS methods for webchat clients. Allows BFF to inject OIDC id_token into plugin sessions without redirect flow."
+          },
+          "personalSessionMode": {
+            "type": "boolean",
+            "default": false,
+            "description": "Single-user mode: store TIP, OIDC session, and credentials under agent:main:main only (no per-sender or per-channel-peer keys). Subagent sessions are unchanged. Not for multi-tenant or shared group chats."
+          },
+          "localServer": {
+            "type": "boolean",
+            "default": false,
+            "description": "Start a local HTTP-over-UDS server so other processes on the same machine can retrieve TIP tokens and session info."
+          },
+          "localServerAllowlist": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Additional process names/paths allowed to connect to the local server (beyond defaults)."
+          },
+          "localServerFailOpen": {
+            "type": "boolean",
+            "default": true,
+            "description": "When the local server cannot identify the connecting process (lsof unavailable, race condition, etc.), allow the request with a warning. Set to false for strict mode (deny unresolvable peers)."
+          }
+        }
+      },
+      "userpool": {
+        "type": "object",
+        "description": "UserPool OIDC: explicit (discoveryUrl+clientId) or dynamic (userPoolName+clientName)",
+        "properties": {
+          "discoveryUrl": {
+            "type": "string",
+            "description": "OIDC discovery base (explicit mode)"
+          },
+          "clientId": { "type": "string" },
+          "clientSecret": { "type": "string" },
+          "callbackUrl": {
+            "type": "string",
+            "description": "Full callback URL registered with UserPool client"
+          },
+          "scope": { "type": "string" },
+          "userPoolName": {
+            "type": "string",
+            "description": "Dynamic: resolve pool by name (from_veidentity style)"
+          },
+          "clientName": {
+            "type": "string",
+            "description": "Dynamic: resolve client by name"
+          },
+          "autoCreate": {
+            "type": "boolean",
+            "default": true,
+            "description": "Create UserPool/Client when not found (dynamic mode)"
+          },
+          "identityProvider": {
+            "type": "string",
+            "description": "External identity provider name to use in the OAuth2 authorization URL (identity_provider param). When omitted, the first provider returned by ListIdentityProviders is used automatically."
+          },
+          "useRelayCallback": {
+            "type": "boolean",
+            "description": "When true, the OIDC flow goes through the UserPool relay (redirect_relay_uri). The callback handler will detect the relay state format (base64 JSON with request_id/provider_id/request_state) and first forward the authorization code to the UserPool's generic_oauth callback endpoint, then perform the token exchange. The app state is recovered from request_state."
+          }
+        }
+      },
+      "authz": {
+        "type": "object",
+        "properties": {
+          "agentCheck": {
+            "type": "boolean",
+            "description": "Run CheckPermission for agents (resource type agent) in before_agent_start. Verifies that the authenticated user has permission to invoke the current agent. Uses the outermost actor from the TIP delegation chain as the resource id. Default: false.",
+            "default": false
+          },
+          "toolCheck": {
+            "type": "boolean",
+            "description": "Run CheckPermission for tools (resource type tool). Default: false.",
+            "default": false
+          },
+          "skillReadCheck": {
+            "type": "boolean",
+            "description": "Run CheckPermission for read of SKILL.md (resource type skill). Parses available_skills from system prompt. Default: false.",
+            "default": false
+          },
+          "requireRiskApproval": {
+            "type": "boolean",
+            "description": "Require user approval for high-risk tools. Default: false.",
+            "default": false
+          },
+          "namespaceName": {
+            "type": "string",
+            "description": "Namespace for CheckPermission (Cedar policy). Default: default.",
+            "default": "default"
+          },
+          "lowRiskBypass": {
+            "type": "boolean",
+            "description": "Skip TIP+CheckPermission for built-in low-risk tools",
+            "default": true
+          },
+          "lowRiskTools": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Extra tool names to treat as low-risk"
+          },
+          "enableLlmRiskCheck": {
+            "type": "boolean",
+            "description": "Use LLM to re-evaluate user-provided commands/paths when rules return medium. Risk reason is shown in approval prompts and block messages.",
+            "default": false
+          },
+          "llmRiskCheck": {
+            "type": "object",
+            "description": "LLM provider config for risk check. Evaluates commands (exec, process) and file paths (write, apply_patch). Reason is passed to approval flow.",
+            "properties": {
+              "endpoint": {
+                "type": "string",
+                "description": "Base URL: Ollama (http://localhost:11434) or OpenAI-compat (https://api.openai.com/v1)"
+              },
+              "api": {
+                "type": "string",
+                "enum": ["ollama", "openai-completions"],
+                "description": "API style: ollama for /api/generate, openai-completions for /chat/completions",
+                "default": "ollama"
+              },
+              "model": {
+                "type": "string",
+                "description": "Model name (e.g. qwen3:8b, gpt-4o-mini)"
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "API key for OpenAI-compatible providers (omit for Ollama)"
+              },
+              "timeoutMs": {
+                "type": "number",
+                "description": "Timeout in ms",
+                "default": 10000
+              },
+              "cacheTtlMs": {
+                "type": "number",
+                "description": "Cache TTL in ms for same tool+params. 0 to disable. Default 300000",
+                "default": 300000
+              }
+            }
+          },
+          "approvalTtlSeconds": {
+            "type": "number",
+            "description": "Approval TTL in seconds",
+            "default": 300
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@volcengine/agent-identity",
+  "version": "1.3.2",
+  "description": "Agent Identity: UserPool (用户池) login, TIP token (工作负载令牌), credential hosting (凭据托管 OAuth2/API key), optional tool/skill permission control (CheckPermission) and risk approval. Integrates with Volcengine 智能体身份和权限管理平台.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build:bundle": "npm run clean && npm run build:types && node -e \"require('node:fs').rmSync('dist/src',{recursive:true,force:true})\" && esbuild index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --sourcemap --minify --external:openclaw --external:openclaw/* --external:koffi",
+    "test": "vitest run",
+    "test:ci": "vitest run --reporter=verbose",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build:bundle"
+  },
+  "keywords": [
+    "openclaw",
+    "identity",
+    "volcengine",
+    "userpool",
+    "credential",
+    "TIP",
+    "auth",
+    "agent"
+  ],
+  "license": "Apache-2.0",
+  "optionalDependencies": {
+    "koffi": "^2.15.2"
+  },
+  "devDependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.3",
+    "jose": "^5.9.6",
+    "json5": "^2.2.3",
+    "openclaw": "^2026.3.28",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0",
+    "ws": "^8.19.0",
+    "yaml": "^2.4.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": "^0.58.0",
+    "openclaw": ">=2026.3.24"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24",
+      "minGatewayVersion": "2026.3.24"
+    },
+    "build": {
+      "openclawVersion": "2026.3.28",
+      "pluginSdkVersion": "2026.3.28"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README-cn.md",
+    "identity/SKILL.md",
+    "openclaw.plugin.json"
+  ]
+}