@m1a0rz/agent-identity 0.2.0 → 0.2.1

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -23,6 +23,7 @@ import { IdentityService } from "./src/services/identity-service.js";
 import { sendNotificationFeishu } from "./src/services/send-notification-feishu.js";
 import { createIdentityApproveTool } from "./src/tools/identity-approve-tool.js";
 import { createIdentityConfigTool } from "./src/tools/identity-config.js";
+import { createIdentityConfigSuggestTool } from "./src/tools/identity-config-suggest.js";
 import { createIdentityListRiskPatternsTool } from "./src/tools/identity-list-risk-patterns.js";
 import { createIdentityRiskCheckTool } from "./src/tools/identity-risk-check.js";
 import { createIdentityFetchTool } from "./src/tools/identity-fetch.js";
@@ -278,6 +279,7 @@ export default function register(api) {
     api.registerTool(createIdentityListCredentialsTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentityListTipsTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentityConfigTool(identityCommandsDeps), { optional: false });
+    api.registerTool(createIdentityConfigSuggestTool(), { optional: false });
     api.registerTool(createIdentityFetchTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentitySetBindingTool(identityCommandsDeps), { optional: true });
     api.registerTool(createIdentityUnsetBindingTool(identityCommandsDeps), { optional: true });

package/dist/src/tools/identity-config-suggest.d.ts

@@ -0,0 +1,118 @@
+/**
+ * identity_config_suggest: generate config snippets for agent-identity plugin.
+ * Helps skill/agent assist users in configuring openclaw.json.
+ * Does not modify config; returns JSON and instructions for manual edit.
+ */
+declare const INTENTS: {
+    readonly identity: {
+        readonly label: "Identity API (AK/SK, endpoint)";
+        readonly config: {
+            readonly identity: {
+                readonly endpoint: "https://id.cn-beijing.volcengineapi.com";
+                readonly accessKeyId: "<your-access-key>";
+                readonly secretAccessKey: "<your-secret-key>";
+                readonly workloadPoolName: "default";
+                readonly workloadName: "openclaw-agent";
+            };
+        };
+        readonly instructions: {
+            readonly en: "Add under plugins.entries.agent-identity.config. Credentials can also come from env (VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY) or credentialsFile.";
+            readonly zh: "添加到 plugins.entries.agent-identity.config 下。凭据也可通过环境变量 (VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY) 或 credentialsFile 提供。";
+        };
+    };
+    readonly userpool: {
+        readonly label: "UserPool OIDC (login)";
+        readonly config: {
+            readonly userpool: {
+                readonly discoveryUrl: "https://your-idp.com/.well-known/openid-configuration";
+                readonly clientId: "<your-client-id>";
+                readonly clientSecret: "<optional-for-public-clients>";
+                readonly callbackUrl: "https://your-gateway/identity/oauth/callback";
+                readonly scope: "openid profile email";
+            };
+        };
+        readonly instructions: {
+            readonly en: "Required for /identity login. callbackUrl must match the URL registered with your IdP. For dynamic mode, use userPoolName + clientName instead of discoveryUrl + clientId.";
+            readonly zh: "登录功能必需。callbackUrl 需与 IdP 中注册的回调地址一致。动态模式可使用 userPoolName + clientName 替代 discoveryUrl + clientId。";
+        };
+    };
+    readonly authz: {
+        readonly label: "AuthZ (tool/skill permission, risk approval)";
+        readonly config: {
+            readonly authz: {
+                readonly toolCheck: true;
+                readonly skillReadCheck: false;
+                readonly requireRiskApproval: true;
+                readonly namespaceName: "default";
+                readonly lowRiskBypass: true;
+                readonly approvalTtlSeconds: 300;
+            };
+        };
+        readonly instructions: {
+            readonly en: "toolCheck: CheckPermission for tools. skillReadCheck: CheckPermission for SKILL.md reads. requireRiskApproval: user approval for high-risk tools (exec, write). Restart gateway after config change.";
+            readonly zh: "toolCheck: 对工具调用做 CheckPermission。skillReadCheck: 对 SKILL.md 读取做权限检查。requireRiskApproval: 高风险工具需用户审批。修改后需重启 gateway。";
+        };
+    };
+    readonly llm_risk: {
+        readonly label: "LLM risk check (re-evaluate medium-risk)";
+        readonly config: {
+            readonly authz: {
+                readonly requireRiskApproval: true;
+                readonly enableLlmRiskCheck: true;
+                readonly llmRiskCheck: {
+                    readonly endpoint: "http://localhost:11434";
+                    readonly api: "ollama";
+                    readonly model: "qwen3:8b";
+                    readonly timeoutMs: 10000;
+                    readonly cacheTtlMs: 300000;
+                };
+            };
+        };
+        readonly instructions: {
+            readonly en: "When rules return medium, LLM re-evaluates. Requires requireRiskApproval. endpoint: Ollama or OpenAI-compat base URL.";
+            readonly zh: "规则返回 medium 时由 LLM 二次评估。需同时开启 requireRiskApproval。endpoint 为 Ollama 或 OpenAI 兼容接口地址。";
+        };
+    };
+    readonly full: {
+        readonly label: "Full example (identity + userpool + authz)";
+        readonly config: {
+            readonly identity: {
+                readonly endpoint: "https://id.cn-beijing.volcengineapi.com";
+                readonly workloadPoolName: "default";
+                readonly workloadName: "openclaw-agent";
+            };
+            readonly userpool: {
+                readonly discoveryUrl: "https://your-idp.com/.well-known/openid-configuration";
+                readonly clientId: "<your-client-id>";
+                readonly callbackUrl: "https://your-gateway/identity/oauth/callback";
+                readonly scope: "openid profile email";
+            };
+            readonly authz: {
+                readonly toolCheck: false;
+                readonly skillReadCheck: false;
+                readonly requireRiskApproval: false;
+                readonly lowRiskBypass: true;
+            };
+        };
+        readonly instructions: {
+            readonly en: "Minimal full config. Fill in your IdP discoveryUrl, clientId, callbackUrl. Enable authz flags as needed.";
+            readonly zh: "完整示例。填入 IdP 的 discoveryUrl、clientId、callbackUrl。按需开启 authz 各项。";
+        };
+    };
+};
+export type ConfigSuggestIntent = keyof typeof INTENTS;
+export declare function createIdentityConfigSuggestTool(): () => {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        intent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        lang: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        intent?: ConfigSuggestIntent;
+        lang?: "en" | "zh";
+    }) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<unknown>>;
+};
+export {};
+//# sourceMappingURL=identity-config-suggest.d.ts.map

package/dist/src/tools/identity-config-suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-config-suggest.d.ts","sourceRoot":"","sources":["../../../src/tools/identity-config-suggest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgGH,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,OAAO,CAAC;AAEvD,wBAAgB,+BAA+B;;;;;;;;2BAoB5B,MAAM,UACX;QAAE,MAAM,CAAC,EAAE,mBAAmB,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE;EA2BjE"}

package/dist/src/tools/identity-config-suggest.js

@@ -0,0 +1,167 @@
+/**
+ * identity_config_suggest: generate config snippets for agent-identity plugin.
+ * Helps skill/agent assist users in configuring openclaw.json.
+ * Does not modify config; returns JSON and instructions for manual edit.
+ */
+import { Type } from "@sinclair/typebox";
+import { jsonResult } from "openclaw/plugin-sdk";
+const CONFIG_PATH = "plugins.entries.agent-identity.config";
+/** Identity credential defaults and resolution order. Included when intent is identity or full. */
+const IDENTITY_DEFAULTS = {
+    envVars: {
+        VOLCENGINE_ACCESS_KEY: "Access Key when accessKeyId not in config",
+        VOLCENGINE_SECRET_KEY: "Secret Key when secretAccessKey not in config",
+        VOLCENGINE_SESSION_TOKEN: "STS session token (optional)",
+        VOLCENGINE_CREDENTIALS_FILE: "Path to credential JSON; overrides default file path",
+        RUNTIME_IAM_ROLE_TRN: "Role TRN for AssumeRole when loading from credential file (fallback if file has no role_trn)",
+    },
+    defaultCredPath: "/var/run/secrets/iam/credential",
+    credentialResolutionOrder: [
+        "1. Explicit config (accessKeyId, secretAccessKey, sessionToken)",
+        "2. Environment variables (VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, VOLCENGINE_SESSION_TOKEN)",
+        "3. Credential file (credentialsFile config, or VOLCENGINE_CREDENTIALS_FILE env, or /var/run/secrets/iam/credential)",
+    ],
+    identityConfigDefaults: {
+        endpoint: "https://id.cn-beijing.volcengineapi.com",
+        workloadPoolName: "default",
+        workloadName: "openclaw-agent",
+    },
+    credentialFileFormat: {
+        access_key_id: "string",
+        secret_access_key: "string",
+        session_token: "optional, for STS",
+        role_trn: "optional, for AssumeRole",
+    },
+};
+const INTENTS = {
+    identity: {
+        label: "Identity API (AK/SK, endpoint)",
+        config: {
+            identity: {
+                endpoint: "https://id.cn-beijing.volcengineapi.com",
+                accessKeyId: "<your-access-key>",
+                secretAccessKey: "<your-secret-key>",
+                workloadPoolName: "default",
+                workloadName: "openclaw-agent",
+            },
+        },
+        instructions: {
+            en: "Add under plugins.entries.agent-identity.config. Credentials can also come from env (VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY) or credentialsFile.",
+            zh: "添加到 plugins.entries.agent-identity.config 下。凭据也可通过环境变量 (VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY) 或 credentialsFile 提供。",
+        },
+    },
+    userpool: {
+        label: "UserPool OIDC (login)",
+        config: {
+            userpool: {
+                discoveryUrl: "https://your-idp.com/.well-known/openid-configuration",
+                clientId: "<your-client-id>",
+                clientSecret: "<optional-for-public-clients>",
+                callbackUrl: "https://your-gateway/identity/oauth/callback",
+                scope: "openid profile email",
+            },
+        },
+        instructions: {
+            en: "Required for /identity login. callbackUrl must match the URL registered with your IdP. For dynamic mode, use userPoolName + clientName instead of discoveryUrl + clientId.",
+            zh: "登录功能必需。callbackUrl 需与 IdP 中注册的回调地址一致。动态模式可使用 userPoolName + clientName 替代 discoveryUrl + clientId。",
+        },
+    },
+    authz: {
+        label: "AuthZ (tool/skill permission, risk approval)",
+        config: {
+            authz: {
+                toolCheck: true,
+                skillReadCheck: false,
+                requireRiskApproval: true,
+                namespaceName: "default",
+                lowRiskBypass: true,
+                approvalTtlSeconds: 300,
+            },
+        },
+        instructions: {
+            en: "toolCheck: CheckPermission for tools. skillReadCheck: CheckPermission for SKILL.md reads. requireRiskApproval: user approval for high-risk tools (exec, write). Restart gateway after config change.",
+            zh: "toolCheck: 对工具调用做 CheckPermission。skillReadCheck: 对 SKILL.md 读取做权限检查。requireRiskApproval: 高风险工具需用户审批。修改后需重启 gateway。",
+        },
+    },
+    llm_risk: {
+        label: "LLM risk check (re-evaluate medium-risk)",
+        config: {
+            authz: {
+                requireRiskApproval: true,
+                enableLlmRiskCheck: true,
+                llmRiskCheck: {
+                    endpoint: "http://localhost:11434",
+                    api: "ollama",
+                    model: "qwen3:8b",
+                    timeoutMs: 10000,
+                    cacheTtlMs: 300000,
+                },
+            },
+        },
+        instructions: {
+            en: "When rules return medium, LLM re-evaluates. Requires requireRiskApproval. endpoint: Ollama or OpenAI-compat base URL.",
+            zh: "规则返回 medium 时由 LLM 二次评估。需同时开启 requireRiskApproval。endpoint 为 Ollama 或 OpenAI 兼容接口地址。",
+        },
+    },
+    full: {
+        label: "Full example (identity + userpool + authz)",
+        config: {
+            identity: {
+                endpoint: "https://id.cn-beijing.volcengineapi.com",
+                workloadPoolName: "default",
+                workloadName: "openclaw-agent",
+            },
+            userpool: {
+                discoveryUrl: "https://your-idp.com/.well-known/openid-configuration",
+                clientId: "<your-client-id>",
+                callbackUrl: "https://your-gateway/identity/oauth/callback",
+                scope: "openid profile email",
+            },
+            authz: {
+                toolCheck: false,
+                skillReadCheck: false,
+                requireRiskApproval: false,
+                lowRiskBypass: true,
+            },
+        },
+        instructions: {
+            en: "Minimal full config. Fill in your IdP discoveryUrl, clientId, callbackUrl. Enable authz flags as needed.",
+            zh: "完整示例。填入 IdP 的 discoveryUrl、clientId、callbackUrl。按需开启 authz 各项。",
+        },
+    },
+};
+export function createIdentityConfigSuggestTool() {
+    return () => ({
+        name: "identity_config_suggest",
+        label: "Identity Config Suggest",
+        description: "Generate config snippets for agent-identity plugin. Use when user asks to configure identity, login, authz, or risk approval. Returns JSON to add to openclaw.json under plugins.entries.agent-identity.config.",
+        parameters: Type.Object({
+            intent: Type.Optional(Type.String({
+                description: "Config intent: identity (AK/SK), userpool (OIDC login), authz (permission/approval), llm_risk (LLM re-eval), full (all). Default: full",
+            })),
+            lang: Type.Optional(Type.String({
+                description: "Instruction language: en or zh. Default: en",
+            })),
+        }),
+        execute: async (_toolCallId, params) => {
+            const intent = (params?.intent ?? "full");
+            const lang = params?.lang ?? "en";
+            const entry = INTENTS[intent] ?? INTENTS.full;
+            const includeIdentityDefaults = intent === "identity" || intent === "full";
+            const result = {
+                configPath: CONFIG_PATH,
+                intent,
+                label: entry.label,
+                config: entry.config,
+                instructions: entry.instructions[lang],
+                nextSteps: lang === "zh"
+                    ? "将上述 config 合并到 openclaw.json 的对应路径下，保存后重启 gateway。"
+                    : "Merge the config above into openclaw.json at the given path, save, and restart the gateway.",
+            };
+            if (includeIdentityDefaults) {
+                result.identityDefaults = IDENTITY_DEFAULTS;
+            }
+            return jsonResult(result);
+        },
+    });
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "agent-identity",
   "name": "Agent Identity",
-  "description": "UserPool (用户池) login, TIP token (工作负载令牌 GetWorkloadAccessTokenForJWT), credential 3LO (凭据托管), session management. Integrates with Volcengine 智能体身份和权限管理平台. Credentials from config, env, or file; STS AssumeRole supported.",
+  "description": "UserPool (用户池) login, TIP token (工作负载令牌 GetWorkloadAccessTokenForJWT), credential 3LO (凭据托管), session management, optional tool/skill permission control (CheckPermission) and risk approval. Integrates with Volcengine 智能体身份和权限管理平台. Credentials from config, env, or file; STS AssumeRole supported.",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@m1a0rz/agent-identity",
-  "version": "0.2.0",
-  "description": "Agent Identity: UserPool (用户池) login, TIP token (工作负载令牌), credential hosting (凭据托管 OAuth2/API key), optional tool risk approval. Integrates with Volcengine 智能体身份和权限管理平台.",
+  "version": "0.2.1",
+  "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",

package/skills/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: identity
 description: |
-  UserPool login, TIP token, credential hosting, and tool risk approval. Activate when user needs to check identity (whoami/status), log in, list/add credentials, manage env bindings, or diagnose/approve risky tool calls.
-  Also activates for: 用户说登录、查身份、获取凭据、添加/配置API密钥、绑定环境变量、审批工具调用、风险检查.
+  UserPool login, TIP token, credential hosting, and tool risk approval. Activate when user needs to check identity (whoami/status), log in, list/add credentials, manage env bindings, configure the plugin, or diagnose/approve risky tool calls.
+  Also activates for: 用户说登录、查身份、获取凭据、添加/配置API密钥、绑定环境变量、配置插件、审批工具调用、风险检查.
 metadata:
   {
     "openclaw":
@@ -53,6 +53,7 @@ Use the agent-identity plugin for UserPool OIDC login (入站授权), TIP token
 | `identity_list_credentials` | `page?`                                        | List providers and credentials (paginated) |
 | `identity_list_tips`        | —                                              | List valid TIP tokens and bindings         |
 | `identity_config`           | —                                              | Show plugin config (secrets redacted)      |
+| `identity_config_suggest`  | `intent?`, `lang?`                             | Generate config snippets for openclaw.json |
 | `identity_fetch`            | `provider`, `flow?`, `redirectUrl?`, `scopes?` | Add credential                             |
 | `identity_set_binding`      | `provider`, `envVar`                           | Bind provider → env var for tool injection |
 | `identity_unset_binding`    | `provider`                                     | Remove env binding                         |
@@ -204,6 +205,21 @@ Returns built-in dangerous command patterns and sensitive paths. No params. Use
 {}
 ```
 
+### identity_config_suggest
+
+Generates config snippets for the agent-identity plugin. **Call when:** user asks to configure identity, login, authz, risk approval, or "如何配置 identity 插件", "帮我配置登录", "怎么开启权限检查".
+
+| Param   | Type   | Required | Description                                                                 |
+| ------- | ------ | -------- | --------------------------------------------------------------------------- |
+| `intent`| string | No       | `identity` (AK/SK), `userpool` (OIDC login), `authz` (permission/approval), `llm_risk` (LLM re-eval), `full` (all). Default: full |
+| `lang`  | string | No       | `en` or `zh` for instructions. Default: en                                  |
+
+Returns: `configPath`, `config` (JSON to merge), `instructions`, `nextSteps`. When `intent` is `identity` or `full`, also returns `identityDefaults` (env vars, credential resolution order, config defaults, credential file format). User must manually add to openclaw.json and restart gateway.
+
+```json
+{ "intent": "userpool", "lang": "zh" }
+```
+
 ## Workflow: Adding a Credential
 
 1. **Check login**: `identity_whoami` (brief) or `identity_status` (full). If not logged in, use `identity_login` first (user opens auth URL).