@m1a0rz/agent-identity 0.4.1 → 0.4.3

package/README-cn.md

@@ -39,6 +39,8 @@ UserPool OIDC 登录、TIP (Trusted Identity Provider) 令牌（通过 Identity
 | `list-tips`                     | 列出所有有效 TIP 令牌及其委托链、过期时间和环境变量绑定。            |
 | `config`                        | 显示 identity 插件配置（敏感信息脱敏）。                             |
 | `list-credentials` 或 `list [page]` | 分页列出控制台 provider 及已绑定的凭据。使用 `list 2` 加载更多。 |
+| `list-roles` | 列出 STS 角色类凭据提供方（非 OAuth/API key）。可选按名称前缀过滤。 |
+| `get-role <provider> [--use-tip] [--show-secrets]` | 获取某角色提供方的 STS 临时凭据（默认脱敏）。 |
 | `fetch <provider> [--flow=...]` | 添加凭据。flow 根据 provider 类型自动推断；可用 `--flow` 覆盖。       |
 | `set <provider> <envVar>`       | 将凭据绑定到环境变量供工具注入。无凭据时从 `process.env[envVar]` 导入。 |
 | `unset <provider>`              | 移除 provider 的环境变量绑定。                                       |
@@ -104,7 +106,8 @@ openclaw plugins install --link .
 
 **A. 平台侧访问配置（Identity）**：用于获取 TIP Token、拉取/托管凭据、做权限校验（可选）。
 
-- `endpoint`：Identity API 地址（例如 `https://id.cn-beijing.volcengineapi.com`）。不填时使用默认值。
+- `endpoint`（可选）：Identity API 根地址（例如 `https://id.cn-beijing.volcengineapi.com`）。**优先级最高**。
+- `regionMetadataUrl`（可选）：返回 **纯文本 region id**（如 `cn-beijing`）的 HTTP(S) URL。仅当 **未配置 `endpoint`** 时使用：客户端拼接 `https://id.{region}.volcengineapi.com`。单次请求约 10s 超时；失败或正文无效（如 `unknown`）时回退到 `https://id.cn-beijing.volcengineapi.com`。示例：`http://100.96.0.96/latest/region_id`（需网关能访问）。
 - `accessKeyId` / `secretAccessKey`：用于访问 Identity API。**可选**，可使用环境变量或凭据文件（见下）。
 - `workloadPoolName` / `workloadName`：用于签发 TIP Token。默认：`default`、`openclaw-agent`。
 - `audience` / `durationSeconds`：可选，令牌受众与有效期。
@@ -113,6 +116,10 @@ openclaw plugins install --link .
 - `roleTrn`：STS AssumeRole 的 Role TRN。设置后（且未设置 `workloadName`）不传 workload name，后端使用 roleName。优先级：`workloadName` > `roleTrn` > params。与 `credentialsMetadataUrl` 配合时用于 AssumeRole，或与显式 AK/SK 配合。
 - `sessionToken`：STS 会话令牌（或使用 `VOLCENGINE_SESSION_TOKEN` 环境变量）。
 
+**Identity API 地址解析**：已配置 `endpoint` → 否则用 `regionMetadataUrl` 拉取 region 拼接 URL → 否则 `https://id.cn-beijing.volcengineapi.com`。**SigV4 签名用 region** 从解析后的主机名匹配 `id.{region}.volcengineapi.com` 推断；否则为 `cn-beijing`。
+
+**工作负载池（凭据 / STS）**：`workloadPoolName`（默认 `default`）用于限定 `ListCredentialProviders`、`ListRoleCredentialProviders` 以及 `GetResourceOauth2Token`、`GetResourceApiKey`、`GetUserCredential`、`GetRoleCredentials` 等接口的 `PoolName`。若配置了 `userpool.userPoolName`，角色提供方列表还会在客户端按用户池再过滤。
+
 **凭据解析顺序**（AK/SK）：1）显式 config → 2）环境变量（`VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY`、`VOLCENGINE_SESSION_TOKEN`）→ 3）远程元数据（`credentialsMetadataUrl` + `roleTrn`，从完整 URL 拉取后做 AssumeRole；404 时回退）→ 4）凭据文件（config 的 `credentialsFile`，或 `VOLCENGINE_CREDENTIALS_FILE` 环境变量，或 `/var/run/secrets/iam/credential`）。凭据文件格式（VeFaaS）：`access_key_id`、`secret_access_key`、`session_token`（可选）、`role_trn`（可选，用于 AssumeRole）。`RUNTIME_IAM_ROLE_TRN` 环境变量可在从文件加载时提供 role TRN。
 
 **B. 用户登录配置（UserPool / OIDC）**：用于 `/identity login` 的用户登录与会话建立。
@@ -121,6 +128,8 @@ openclaw plugins install --link .
 - `clientId` / `clientSecret`（动态模式下可自动解析）
 - `callbackUrl`：OpenClaw 网关对外可访问的回调地址，例如 `http://127.0.0.1:18789/identity/oauth/callback`
 - `scope`：一般包含 `openid profile email`
+- `identityProvider`（可选）：授权 URL 中 `identity_provider` 对应的 IdP 名称；不填则使用 `ListIdentityProviders` 返回的第一条。
+- `useRelayCallback`（可选）：经 UserPool relay / `redirect_relay_uri` 的 OIDC 回调流程。默认 false。
 
 **C. 权限校验与风险审批（AuthZ，可选）**：用于 TIP + CheckPermission + 风险评估与用户审批。各开关独立，无统一 `enable`。
 
@@ -182,7 +191,8 @@ openclaw plugins install --link .
 
 | 参数 | 类型 | 必填 | 含义 |
 |------|------|------|------|
-| `endpoint` | string | 是 | Identity API 地址，如 `https://id.cn-beijing.volcengineapi.com` |
+| `endpoint` | string | 否 | Identity API 根地址。不填则通过 `regionMetadataUrl` 或默认 `https://id.cn-beijing.volcengineapi.com` |
+| `regionMetadataUrl` | string | 否 | 返回纯文本 region 的 URL；在未配置 `endpoint` 时拼接 `https://id.{region}.volcengineapi.com` |
 | `accessKeyId` | string | 否* | 火山引擎 Access Key。不填时从 `VOLCENGINE_ACCESS_KEY` 或 `credentialsFile` 读取 |
 | `secretAccessKey` | string | 否* | 火山引擎 Secret Key。不填时从 `VOLCENGINE_SECRET_KEY` 或 `credentialsFile` 读取 |
 | `workloadPoolName` | string | 否 | 工作负载池名称，默认 `default` |
@@ -195,6 +205,7 @@ openclaw plugins install --link .
 | `sessionToken` | string | 否 | STS 临时会话令牌（或 `VOLCENGINE_SESSION_TOKEN`） |
 | `subagentTipPropagation` | boolean | 否 | 将 TIP 和 session 传播到子 agent。默认 false |
 | `webchatSessionExchange` | boolean | 否 | 启用 `identity.session.put` / `identity.session.get` gateway WS 方法供 webchat 客户端使用。默认 false |
+| `personalSessionMode` | boolean | 否 | 个人/单用户模式：TIP、OIDC session、凭据仅存储在 `agent:main:main`（不做按发送者或 per-channel-peer 隔离）。子 agent 会话不变。默认 false；多租户或群聊共享场景勿开启。 |
 
 \* AK/SK 至少通过 `accessKeyId`+`secretAccessKey`、环境变量、`credentialsMetadataUrl`+`roleTrn` 或 `credentialsFile` 之一提供。
 
@@ -243,8 +254,8 @@ TIP token 通过 `GetWorkloadAccessTokenForJWT` 获取。工作负载行为：
 
 | 方法 | 参数 | 响应 | 描述 |
 | --- | --- | --- | --- |
-| `identity.session.put` | `{ sessionKey, idToken, senderId?, channel? }` | `{ sub, expiresAt, effectiveSessionKey, hasTip }` | 将 OIDC id_token 注入到插件 session。通过 `buildEffectiveSessionKey` 解析实际存储 key（与 hooks/commands 相同的隔离逻辑）。 |
-| `identity.session.get` | `{ sessionKey, senderId?, channel? }` | `{ userToken, sub, expiresAt, effectiveSessionKey }` | 获取指定 session 已存储的 user token。 |
+| `identity.session.put` | `{ sessionKey, idToken, refreshToken?, senderId?, channel? }` | `{ sub, expiresAt, effectiveSessionKey, hasTip }` | 将 OIDC id_token 注入到插件 session；可选传入 `refreshToken`（加密存储），用于静默续期。通过 `buildEffectiveSessionKey` 解析实际存储 key（与 hooks/commands 相同的隔离逻辑）。 |
+| `identity.session.get` | `{ sessionKey, senderId?, channel? }` | `{ userToken, sub, expiresAt, effectiveSessionKey, hasRefreshToken }` | 获取指定 session 已存储的 user token。`hasRefreshToken` 表示是否存有 refresh token；响应中不会返回 refresh token 明文。 |
 
 - `senderId` 默认值为 `"openclaw-control-ui"`。对于 main session，实际存储 key 为 `agent:main:main:user:<senderId>`。
 - `channel` 可选；当 session 来源于可发送消息的渠道（feishu、telegram 等）时传入，可启用 per-channel-peer key 提升。
@@ -264,7 +275,7 @@ TIP token 通过 `GetWorkloadAccessTokenForJWT` 获取。工作负载行为：
 **典型流程（BFF → webchat → plugin）：**
 
 1. BFF 完成 3LO 登录并获取用户的 OIDC `id_token`
-2. Webchat 客户端调用 `identity.session.put`，传入 session key 和 `id_token`
+2. Webchat 客户端调用 `identity.session.put`，传入 session key 和 `id_token`（若需静默续期，可一并传入 token 响应中的 `refresh_token` 作为 `refreshToken`）
 3. 插件校验 token，存储 session，并获取 TIP
 4. 后续该 session 中的 agent 运行拥有有效身份——无需手动登录
 
@@ -274,20 +285,22 @@ TIP token 通过 `GetWorkloadAccessTokenForJWT` 获取。工作负载行为：
 
 ## 工具
 
-- **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_config_suggest** - 生成 openclaw.json 配置片段（intent、lang）
-- **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** - 列出内置危险命令和敏感路径
+面向 Agent 的用法见 [`skills/SKILL.md`](skills/SKILL.md)。本插件注册的工具有：
+
+- **identity_whoami** — 会话身份（sub、TIP）
+- **identity_status** — 登录、TIP、凭据、绑定
+- **identity_login** / **identity_logout** — OIDC 登录或刷新 TIP；清除会话
+- **identity_list_credentials** — OAuth/API key 类 provider 与已存凭据（支持 `page`、`name`、`flow`、`type` 过滤）
+- **identity_list_roles** — STS 角色类凭据提供方（`name` 前缀过滤）
+- **identity_fetch** — 添加凭据（`provider`、`flow`、`redirectUrl`、`scopes`、`returnValue`）
+- **identity_get_role_credentials** — 某角色提供方的 STS 临时凭据（`providerName`、`useTip`）
+- **identity_get_tip_token** / **identity_get_session_token** — 原始 TIP JWT 或会话 user token（进阶场景）
+- **identity_config** — 当前生效配置（脱敏）
+- **identity_config_suggest** — 可合并的配置片段（`intent`、`lang`）
+- **identity_set_binding** / **identity_unset_binding** — 工具注入用的环境变量绑定
+- **identity_risk_check** / **identity_list_risk_patterns** — 风险评估（可选插件能力）
+- **identity_approve_tool** — 可选；**仅供人工审批** — 推荐 `/identity approve <id>`（模型不得自批）
+- **identity_list_tips** — 所有有效 TIP 与绑定（运维 / 多会话排查）
 
 ## 钩子
 

package/README.md

@@ -39,6 +39,8 @@ Single command `/identity` (alias `/id`) with subcommands. Default with no args:
 | `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. |
+| `list-roles`                        | List STS role credential providers (not OAuth/API key). Optional name prefix filter.                          |
+| `get-role <provider> [--use-tip] [--show-secrets]` | Get temporary STS credentials for a role provider (masked by default).                         |
 | `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.                                                                              |
@@ -104,7 +106,8 @@ The plugin typically needs three types of config:
 
 **A. Platform access (Identity)**: For TIP Token, credential fetch/hosting, and optional permission checks.
 
-- `endpoint`: Identity API URL (e.g. `https://id.cn-beijing.volcengineapi.com`). Default when omitted.
+- `endpoint` (optional): Full Identity API base URL (e.g. `https://id.cn-beijing.volcengineapi.com`). **Highest priority** for the API host.
+- `regionMetadataUrl` (optional): HTTP(S) URL that returns a **plain-text region id** (e.g. `cn-beijing`). Used only when `endpoint` is **unset**: the client builds `https://id.{region}.volcengineapi.com`. Request timeout ~10s; on failure or invalid body (e.g. `unknown`), falls back to `https://id.cn-beijing.volcengineapi.com`. Example metadata URL: `http://100.96.0.96/latest/region_id` (must be reachable from the gateway).
 - `accessKeyId` / `secretAccessKey`: For Identity API access. **Optional** when using env vars or credential file (see below).
 - `workloadPoolName` / `workloadName`: For issuing TIP Token. Defaults: `default`, `openclaw-agent`.
 - `audience` / `durationSeconds`: Optional, token audience and validity.
@@ -113,6 +116,10 @@ The plugin typically needs three types of config:
 - `roleTrn`: Role TRN for STS AssumeRole. When set (and `workloadName` not set), workload name is omitted; backend uses roleName. Priority: `workloadName` > `roleTrn` > params. Used with `credentialsMetadataUrl` (AssumeRole after fetch) or explicit AK/SK.
 - `sessionToken`: STS session token (or use `VOLCENGINE_SESSION_TOKEN` env).
 
+**Identity API host resolution**: `endpoint` if set → else region from `regionMetadataUrl` → else `https://id.cn-beijing.volcengineapi.com`. **SigV4 signing region** is inferred from the resolved host when it matches `id.{region}.volcengineapi.com`; otherwise `cn-beijing`.
+
+**Workload pool (credentials / STS)**: `workloadPoolName` (default `default`) scopes `ListCredentialProviders`, `ListRoleCredentialProviders`, and control-plane calls such as `GetResourceOauth2Token`, `GetResourceApiKey`, `GetUserCredential`, and `GetRoleCredentials` via `PoolName`. Role provider listing also filters by `userpool.userPoolName` when configured.
+
 **Credential resolution order** (AK/SK): 1) Explicit config → 2) Env vars (`VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY`, `VOLCENGINE_SESSION_TOKEN`) → 3) Remote metadata (`credentialsMetadataUrl` + `roleTrn`, fetches from full URL then AssumeRole; 404 falls through) → 4) Credential file (`credentialsFile` config, or `VOLCENGINE_CREDENTIALS_FILE` env, or `/var/run/secrets/iam/credential`). Credential file format (VeFaaS): `access_key_id`, `secret_access_key`, `session_token` (optional), `role_trn` (optional for AssumeRole). `RUNTIME_IAM_ROLE_TRN` env can supply role TRN when loading from file.
 
 **B. User login (UserPool / OIDC)**: For `/identity login` and session setup.
@@ -121,6 +128,8 @@ The plugin typically needs three types of config:
 - `clientId` / `clientSecret` (auto-resolved in dynamic mode)
 - `callbackUrl`: Public callback URL for OpenClaw gateway, e.g. `http://127.0.0.1:18789/identity/oauth/callback`
 - `scope`: Typically `openid profile email`
+- `identityProvider` (optional): IdP name for the `identity_provider` authorize param. When omitted, the first entry from `ListIdentityProviders` is used.
+- `useRelayCallback` (optional): UserPool relay / `redirect_relay_uri` flow for OIDC callback. Default false.
 
 **C. AuthZ and risk approval (optional)**: For TIP + CheckPermission + risk evaluation. Each flag is independent; no single "enable" switch.
 
@@ -182,7 +191,8 @@ Add to `openclaw.json` under `plugins.entries.agent-identity.config`:
 
 | Param | Type | Required | Description |
 |-------|------|----------|--------------|
-| `endpoint` | string | Yes | Identity API URL, e.g. `https://id.cn-beijing.volcengineapi.com` |
+| `endpoint` | string | No | Identity API base URL. Omit to use `regionMetadataUrl` or default `https://id.cn-beijing.volcengineapi.com` |
+| `regionMetadataUrl` | string | No | Plain-text region id URL; builds `https://id.{region}.volcengineapi.com` when `endpoint` unset |
 | `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` |
@@ -195,6 +205,7 @@ Add to `openclaw.json` under `plugins.entries.agent-identity.config`:
 | `sessionToken` | string | No | STS session token (or `VOLCENGINE_SESSION_TOKEN`) |
 | `subagentTipPropagation` | boolean | No | Propagate TIP and session to subagents. Default false |
 | `webchatSessionExchange` | boolean | No | Enable `identity.session.put` / `identity.session.get` gateway WS methods for webchat clients. Default false |
+| `personalSessionMode` | boolean | No | Single-user mode: TIP, OIDC session, and credentials are stored only under `agent:main:main` (no per-sender or per-channel-peer keys). Subagent sessions unchanged. Default false — do not enable for multi-tenant or shared groups. |
 
 \* AK/SK must be provided via `accessKeyId`+`secretAccessKey`, environment variables, `credentialsMetadataUrl`+`roleTrn`, or `credentialsFile`.
 
@@ -243,8 +254,8 @@ When `identity.webchatSessionExchange` is `true`, the plugin registers two gatew
 
 | Method | Params | Response | Description |
 | --- | --- | --- | --- |
-| `identity.session.put` | `{ sessionKey, idToken, senderId?, channel? }` | `{ sub, expiresAt, effectiveSessionKey, hasTip }` | Inject an OIDC id_token into a plugin session. Resolves effective storage key via `buildEffectiveSessionKey` (same sender isolation as hooks/commands). |
-| `identity.session.get` | `{ sessionKey, senderId?, channel? }` | `{ userToken, sub, expiresAt, effectiveSessionKey }` | Retrieve the stored user token for a session. |
+| `identity.session.put` | `{ sessionKey, idToken, refreshToken?, senderId?, channel? }` | `{ sub, expiresAt, effectiveSessionKey, hasTip }` | Inject an OIDC id_token into a plugin session; optional `refreshToken` is stored encrypted for silent token renewal. Resolves effective storage key via `buildEffectiveSessionKey` (same sender isolation as hooks/commands). |
+| `identity.session.get` | `{ sessionKey, senderId?, channel? }` | `{ userToken, sub, expiresAt, effectiveSessionKey, hasRefreshToken }` | Retrieve the stored user token for a session. `hasRefreshToken` indicates whether a refresh token is stored; the refresh token value is never returned. |
 
 - `senderId` defaults to `"openclaw-control-ui"`. The effective storage key is `agent:main:main:user:<senderId>` for main sessions.
 - `channel` is optional; when the session originates from a sendable channel (feishu, telegram, etc.), pass it to enable per-channel-peer key promotion.
@@ -264,7 +275,7 @@ Both methods are **restricted to webchat WS connections only** (`isWebchatConnec
 **Typical flow (BFF → webchat → plugin):**
 
 1. BFF completes 3LO login and obtains an OIDC `id_token` for the user
-2. Webchat client calls `identity.session.put` with the session key and `id_token`
+2. Webchat client calls `identity.session.put` with the session key and `id_token` (optionally `refreshToken` from the token response if silent renewal is desired)
 3. Plugin verifies the token, stores the session, and acquires TIP
 4. Subsequent agent runs in that session have a valid identity — no manual login needed
 
@@ -274,20 +285,22 @@ Follow-up messages (login success, credential fetch done) are not delivered when
 
 ## 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_config_suggest** - Generate config snippets for openclaw.json (intent, lang)
-- **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
+Agent-facing behavior is summarized in [`skills/SKILL.md`](skills/SKILL.md). Registered tools:
+
+- **identity_whoami** — Session identity (sub, TIP)
+- **identity_status** — Login, TIP, credentials, bindings
+- **identity_login** / **identity_logout** — OIDC login or refresh TIP; clear session
+- **identity_list_credentials** — OAuth/API key providers and stored credentials (`page`, `name`, `flow`, `type` filters)
+- **identity_list_roles** — STS role credential providers (`name` prefix filter)
+- **identity_fetch** — Add credential (`provider`, `flow`, `redirectUrl`, `scopes`, `returnValue`)
+- **identity_get_role_credentials** — STS credentials for a role provider (`providerName`, `useTip`)
+- **identity_get_tip_token** / **identity_get_session_token** — Raw TIP JWT or session user token (advanced)
+- **identity_config** — Effective plugin config (redacted)
+- **identity_config_suggest** — Config merge snippets (`intent`, `lang`)
+- **identity_set_binding** / **identity_unset_binding** — Env var bindings for tool injection
+- **identity_risk_check** / **identity_list_risk_patterns** — Risk evaluation (optional plugin)
+- **identity_approve_tool** — Optional; **human approval only** — prefer `/identity approve <id>` (agents must not self-approve)
+- **identity_list_tips** — All valid TIP tokens and bindings (ops / multi-session debug)
 
 ## Hooks
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA0E7D,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QAyatD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAmF7D,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QA+etD"}

package/dist/index.js

@@ -13,15 +13,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { runPluginPreflight } from "./src/preflight/plugin-preflight.js";
+import { pluginState } from "./src/preflight/plugin-state.js";
 import { createIdentityCommand, createIdCommand } from "./src/commands/identity-commands.js";
 import { createBeforeAgentStartHandler } from "./src/hooks/before-agent-start.js";
 import { createLlmInputHandler } from "./src/hooks/llm-input.js";
 import { createSessionsSendPropagationHandler } from "./src/hooks/sessions-send-propagation.js";
 import { createSessionsSpawnPropagationHandler } from "./src/hooks/sessions-spawn-propagation.js";
 import { createSubagentEndedCleanupHandler } from "./src/hooks/subagent-ended-cleanup.js";
-import { setSender, clearSender } from "./src/store/sender-session-store.js";
+import { setSender, clearSender, setPersonalSessionMode } from "./src/store/sender-session-store.js";
 import { deriveSessionKey, needsSenderIsolation, } from "./src/utils/derive-session-key.js";
 import { createBeforeToolCallHandler } from "./src/hooks/before-tool-call.js";
+import { createToolResultPersistHandler } from "./src/hooks/tool-result-persist.js";
 import { createAfterToolCallHandler } from "./src/hooks/after-tool-call.js";
 import * as skillPathStore from "./src/store/skill-path-store.js";
 import { createOIDCCallbackHandler, createOIDCCallbackHandlerLazy, } from "./src/routes/oidc-login.js";
@@ -34,7 +37,11 @@ import { createIdentityConfigSuggestTool } from "./src/tools/identity-config-sug
 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";
+import { createIdentityGetRoleCredentialsTool } from "./src/tools/identity-get-role-credentials.js";
+import { createIdentityGetTipTokenTool } from "./src/tools/identity-get-tip-token.js";
+import { createIdentityGetSessionTokenTool } from "./src/tools/identity-get-session-token.js";
 import { createIdentityListCredentialsTool } from "./src/tools/identity-list-credentials.js";
+import { createIdentityListRolesTool } from "./src/tools/identity-list-roles.js";
 import { createIdentityListTipsTool } from "./src/tools/identity-list-tips.js";
 import { createIdentityLoginTool } from "./src/tools/identity-login.js";
 import { createIdentityLogoutTool } from "./src/tools/identity-logout.js";
@@ -54,6 +61,7 @@ function hasAnyIdentityConfig(identity) {
     if (!identity)
         return false;
     return Boolean(identity.endpoint ||
+        identity.regionMetadataUrl ||
         identity.accessKeyId ||
         identity.secretAccessKey ||
         identity.sessionToken ||
@@ -70,11 +78,16 @@ export default function register(api) {
     const storeDir = api.resolvePath(PLUGIN_STORE_DIR);
     initEncryptionKey(storeDir);
     const identityCfg = pluginConfig.identity;
+    setPersonalSessionMode(identityCfg?.personalSessionMode === true);
+    if (identityCfg?.personalSessionMode) {
+        logInfo(api.logger, "identity.personalSessionMode: non-subagent TIP/session/credentials use agent:main:main only");
+    }
     const hasIdentity = hasAnyIdentityConfig(identityCfg);
     const userpool = pluginConfig.userpool;
     const identityClient = hasIdentity
         ? new IdentityClient({
-            endpoint: identityCfg?.endpoint ?? "https://id.cn-beijing.volcengineapi.com",
+            endpoint: identityCfg?.endpoint,
+            regionMetadataUrl: identityCfg?.regionMetadataUrl,
             accessKeyId: identityCfg?.accessKeyId,
             secretAccessKey: identityCfg?.secretAccessKey,
             sessionToken: identityCfg?.sessionToken,
@@ -96,6 +109,9 @@ export default function register(api) {
             getResourceApiKey: async () => {
                 throw new Error("Identity not configured.");
             },
+            getUserCredential: async () => {
+                throw new Error("Identity not configured.");
+            },
             checkPermission: async () => {
                 throw new Error("Identity not configured.");
             },
@@ -106,9 +122,24 @@ export default function register(api) {
                 PageNumber: 1,
                 PageSize: 20,
             }),
+            listRoleCredentialProviders: async () => ({
+                RoleCredentialProviders: [],
+                TotalCount: 0,
+                PageNumber: 1,
+                PageSize: 20,
+            }),
+            getRoleCredentials: async () => {
+                throw new Error("Identity not configured.");
+            },
             getUserPool: async () => {
                 throw new Error("Identity not configured.");
             },
+            listIdentityProviders: async () => ({
+                pageNumber: 1,
+                pageSize: 10,
+                totalCount: 0,
+                data: [],
+            }),
             listUserPools: async () => ({
                 pageNumber: 1,
                 pageSize: 10,
@@ -278,23 +309,29 @@ export default function register(api) {
         getOidcConfigForRefresh: getOidcConfigForRefresh ?? undefined,
         configWorkloadName: identityCfg?.workloadName,
         identityClient: hasIdentity ? identityClient : undefined,
+        workloadPoolName: identityCfg?.workloadPoolName ?? "default",
+        userPoolName: userpool?.userPoolName,
         logger: api.logger,
         pluginConfig,
         sendCredentialMessage: sendToSession,
     };
     api.registerCommand(createIdentityCommand(identityCommandsDeps));
     api.registerCommand(createIdCommand(identityCommandsDeps));
-    logInfo(api.logger, "commands /identity, /id (login, status, logout, list-tips, list-credentials, fetch, set, unset); HTTP callback /identity/oauth/callback (credential OAuth uses Identity callback)");
+    logInfo(api.logger, "commands /identity, /id (login, status, logout, list, list-roles, list-tips, fetch, set, unset); HTTP callback /identity/oauth/callback (credential OAuth uses Identity callback)");
     // Tools (share deps with commands). Optional = only included when agent allowlist explicitly adds them.
     api.registerTool(createIdentityWhoamiTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentityLogoutTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentityStatusTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentityLoginTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentityListCredentialsTool(identityCommandsDeps), { optional: false });
+    api.registerTool(createIdentityListRolesTool(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(createIdentityGetRoleCredentialsTool(identityCommandsDeps), { optional: false });
+    api.registerTool(createIdentityGetTipTokenTool(identityCommandsDeps), { optional: false });
+    api.registerTool(createIdentityGetSessionTokenTool(identityCommandsDeps), { optional: false });
     api.registerTool(createIdentitySetBindingTool(identityCommandsDeps), { optional: true });
     api.registerTool(createIdentityUnsetBindingTool(identityCommandsDeps), { optional: true });
     api.registerTool(createIdentityRiskCheckTool({ pluginConfig, logger: api.logger }), { optional: true });
@@ -391,12 +428,12 @@ export default function register(api) {
         logger: api.logger,
     }));
     if (skillReadCheck) {
-        api.on("session_end", (_event, ctx) => {
-            if (ctx.sessionId)
-                skillPathStore.clearSessionById(ctx.sessionId);
+        api.on("session_end", (event) => {
+            if (event.sessionId)
+                skillPathStore.clearSessionById(event.sessionId);
         });
     }
-    // before_tool_call: authz, credential injection, group sender context
+    // before_tool_call: authz, credential injection, group sender context, contract injection
     api.on("before_tool_call", createBeforeToolCallHandler({
         storeDir,
         identityClient: hasIdentity ? identityClient : undefined,
@@ -408,9 +445,11 @@ export default function register(api) {
         identityService: hasIdentity ? identityService : undefined,
         getOidcConfigForRefresh: getOidcConfigForRefresh ?? undefined,
         configWorkloadName: identityCfg?.workloadName,
+        workspaceDir: api.resolvePath?.(".") ?? undefined,
     }));
     // Companion after_tool_call: restore env snapshot set by credential injection
     api.on("after_tool_call", createAfterToolCallHandler({ logger: api.logger }));
+    api.on("tool_result_persist", createToolResultPersistHandler({ logger: api.logger }));
     // Gateway WS methods: webchat session exchange (inject / retrieve user token)
     if (identityCfg?.webchatSessionExchange && hasIdentity) {
         const sessionMethodDeps = {
@@ -424,4 +463,38 @@ export default function register(api) {
         api.registerGatewayMethod("identity.session.get", createSessionGetHandler(sessionMethodDeps));
         logInfo(api.logger, "gateway methods: identity.session.put, identity.session.get (webchat session exchange)");
     }
+    // Preflight: run async after register() returns so startup is never blocked.
+    // On any failure, set pluginState.degraded so hooks skip all interception.
+    const authzEnabled = !!(authz?.agentCheck || authz?.toolCheck || authz?.requireRiskApproval);
+    runPluginPreflight({
+        identityClient,
+        identityService,
+        hasIdentity,
+        credentialConfig: identityCfg
+            ? {
+                accessKeyId: identityCfg.accessKeyId,
+                secretAccessKey: identityCfg.secretAccessKey,
+                sessionToken: identityCfg.sessionToken,
+                credentialsFile: identityCfg.credentialsFile,
+                credentialsMetadataUrl: identityCfg.credentialsMetadataUrl,
+                roleTrn: identityCfg.roleTrn,
+            }
+            : undefined,
+        userpool: dynamicOidcEnabled
+            ? { mode: "dynamic", userPoolName: userpool?.userPoolName }
+            : explicitOidcEnabled
+                ? { mode: "explicit", discoveryUrl: userpool?.discoveryUrl }
+                : undefined,
+        workloadPoolName: identityCfg?.workloadPoolName,
+        authzEnabled,
+        namespaceName: authz?.namespaceName ?? "default",
+        logger: api.logger,
+    }).then((result) => {
+        if (!result.ok) {
+            pluginState.degraded = true;
+            pluginState.failures = result.failures;
+        }
+    }).catch((err) => {
+        logWarn(api.logger, `[identity] preflight threw unexpectedly: ${String(err)}`);
+    });
 }

package/dist/scripts/demo-get-session.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Demo: read local sessions.json (with field-level decryption), resolve one sessionKey, print userToken.
+ *
+ * Same path as the plugin: initEncryptionKey(storeDir) then getSession(storeDir, sessionKey).
+ *
+ * Usage (after `pnpm build`):
+ *   node dist/scripts/demo-get-session.js <sessionKey>
+ *   node dist/scripts/demo-get-session.js <storeDir> <sessionKey>
+ *   pnpm demo:get-session -- <sessionKey>
+ *
+ * Flags:
+ *   --print-token  Print full userToken (default: only prefix + length)
+ */
+export {};
+//# sourceMappingURL=demo-get-session.d.ts.map

package/dist/scripts/demo-get-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-get-session.d.ts","sourceRoot":"","sources":["../../scripts/demo-get-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/scripts/demo-get-session.js

@@ -0,0 +1,58 @@
+/**
+ * Demo: read local sessions.json (with field-level decryption), resolve one sessionKey, print userToken.
+ *
+ * Same path as the plugin: initEncryptionKey(storeDir) then getSession(storeDir, sessionKey).
+ *
+ * Usage (after `pnpm build`):
+ *   node dist/scripts/demo-get-session.js <sessionKey>
+ *   node dist/scripts/demo-get-session.js <storeDir> <sessionKey>
+ *   pnpm demo:get-session -- <sessionKey>
+ *
+ * Flags:
+ *   --print-token  Print full userToken (default: only prefix + length)
+ */
+import path from "node:path";
+import os from "node:os";
+import { initEncryptionKey } from "../src/store/encryption.js";
+import { getSession } from "../src/store/session-store.js";
+function usage() {
+    console.error(`Usage: demo-get-session [--print-token] <sessionKey>
+       demo-get-session [--print-token] <storeDir> <sessionKey>
+
+  storeDir defaults to ~/.openclaw/plugins/identity`);
+    process.exit(1);
+}
+async function main() {
+    const printToken = process.argv.includes("--print-token");
+    const args = process.argv.slice(2).filter((a) => a !== "--print-token");
+    if (args.length < 1 || args.length > 2)
+        usage();
+    const storeDir = args.length === 2
+        ? path.resolve(args[0])
+        : path.join(os.homedir(), ".openclaw", "plugins", "identity");
+    const sessionKey = args.length === 2 ? args[1] : args[0];
+    initEncryptionKey(storeDir);
+    const session = await getSession(storeDir, sessionKey);
+    if (!session) {
+        console.log(JSON.stringify({ ok: false, reason: "no session or expired", storeDir, sessionKey }, null, 2));
+        process.exit(2);
+    }
+    const tokenPreview = printToken
+        ? session.userToken
+        : `${session.userToken.slice(0, 12)}… (${session.userToken.length} chars)`;
+    console.log(JSON.stringify({
+        ok: true,
+        storeDir,
+        sessionKey,
+        sub: session.sub,
+        loginAt: session.loginAt,
+        expiresAt: session.expiresAt ?? null,
+        hasRefreshToken: Boolean(session.refreshToken),
+        claims: session.claims ?? null,
+        userToken: tokenPreview,
+    }, null, 2));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/src/actions/identity-actions.d.ts

@@ -15,6 +15,10 @@ export type OIDCConfigForCommand = {
     clientSecret?: string;
     scope?: string;
     callbackUrl: string;
+    /** UserPool UID (available when resolved dynamically via resolveOIDCConfig). */
+    poolUid?: string;
+    /** First identity provider cached at config resolve time. */
+    identityProvider?: string;
 };
 export type IdentityActionsLogger = {
     info?: (msg: string) => void;
@@ -28,11 +32,13 @@ export type IdentityActionsDeps = {
     getOidcConfigForRefresh?: () => Promise<OIDCConfigForRefresh>;
     configWorkloadName?: string;
     identityClient?: IdentityClientInterface;
+    workloadPoolName?: string;
+    userPoolName?: string;
     logger?: IdentityActionsLogger;
     pluginConfig?: PluginConfig;
     sendCredentialMessage?: (targetOrSessionKey: SessionKeyDeliveryTarget | string, text: string) => Promise<void>;
 };
-export type FetchFlow = "oauth2-user" | "oauth2-m2m" | "apikey";
+export type FetchFlow = "oauth2-user" | "oauth2-m2m" | "apikey" | "user";
 export type StatusResult = {
     loggedIn: boolean;
     sub: string | null;
@@ -69,14 +75,15 @@ export type LogoutResult = {
     ok: boolean;
 };
 export declare function runLogout(deps: IdentityActionsDeps, sessionKey: string): Promise<LogoutResult>;
+export type ProviderRow = {
+    name: string;
+    type: string;
+    flow?: string;
+    status: string;
+    binding?: string;
+};
 export type ListCredentialsResult = {
-    providers: Array<{
-        name: string;
-        type: string;
-        flow?: string;
-        status: string;
-        binding?: string;
-    }>;
+    providers: ProviderRow[];
     storedOnly: Array<{
         name: string;
         status: string;
@@ -89,8 +96,21 @@ export type ListCredentialsResult = {
 export type ListCredentialsFilter = {
     name?: string;
     flow?: string;
+    type?: string;
 };
 export declare function runListCredentials(deps: IdentityActionsDeps, sessionKey: string, page?: number, filter?: ListCredentialsFilter): Promise<ListCredentialsResult>;
+export type RoleProviderRow = {
+    name: string;
+    identitySource?: string;
+};
+export type ListRoleCredentialsResult = {
+    providers: RoleProviderRow[];
+    page: number;
+    hasMore: boolean;
+};
+export declare function runListRoleCredentials(deps: IdentityActionsDeps, sessionKey: string, filter?: {
+    name?: string;
+}): Promise<ListRoleCredentialsResult>;
 export type ListTipsResult = {
     tips: Array<{
         sessionKey: string;
@@ -148,4 +168,50 @@ export type UnsetBindingResult = {
 export declare function runUnsetBinding(deps: IdentityActionsDeps, sessionKey: string, params: {
     provider: string;
 }): Promise<UnsetBindingResult>;
+export type GetRoleCredentialsActionResult = {
+    kind: "success";
+    credentials: {
+        AccessKeyId: string;
+        SecretAccessKey: string;
+        SessionToken: string;
+        Expiration?: string;
+    };
+} | {
+    kind: "error";
+    message: string;
+};
+export declare function runGetRoleCredentials(deps: IdentityActionsDeps, sessionKey: string, params: {
+    providerName: string;
+    useTip?: boolean;
+    config?: import("openclaw/plugin-sdk").OpenClawConfig;
+}): Promise<GetRoleCredentialsActionResult>;
+export type GetTipTokenResult = {
+    kind: "success";
+    tipToken: string;
+    sub: string;
+    issuedAt: number;
+    expiresAt: number;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Return the current TIP JWT for the session (refresh/obtain via user token if needed).
+ */
+export declare function runGetTipToken(deps: IdentityActionsDeps, sessionKey: string, config?: OpenClawConfig): Promise<GetTipTokenResult>;
+export type GetSessionTokenResult = {
+    kind: "success";
+    /** OIDC id_token stored for the session. */
+    sessionIdToken: string;
+    sub: string;
+    loginAt: number;
+    expiresAt?: number;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Return the OIDC id_token (user / session identity token) for the session.
+ */
+export declare function runGetSessionToken(deps: IdentityActionsDeps, sessionKey: string): Promise<GetSessionTokenResult>;
 //# sourceMappingURL=identity-actions.d.ts.map