@m1a0rz/agent-identity 0.4.0 → 0.4.1

package/README-cn.md

@@ -193,6 +193,8 @@ openclaw plugins install --link .
 | `credentialsFile` | string | 否 | 凭证 JSON 文件路径。默认 `VOLCENGINE_CREDENTIALS_FILE` 或 `/var/run/secrets/iam/credential` |
 | `credentialsMetadataUrl` | string | 否 | 远程凭据拉取的完整 URL。与 `roleTrn` 同时配置时拉取后做 AssumeRole。404 时回退到 `credentialsFile` |
 | `sessionToken` | string | 否 | STS 临时会话令牌（或 `VOLCENGINE_SESSION_TOKEN`） |
+| `subagentTipPropagation` | boolean | 否 | 将 TIP 和 session 传播到子 agent。默认 false |
+| `webchatSessionExchange` | boolean | 否 | 启用 `identity.session.put` / `identity.session.get` gateway WS 方法供 webchat 客户端使用。默认 false |
 
 \* AK/SK 至少通过 `accessKeyId`+`secretAccessKey`、环境变量、`credentialsMetadataUrl`+`roleTrn` 或 `credentialsFile` 之一提供。
 
@@ -235,6 +237,37 @@ TIP token 通过 `GetWorkloadAccessTokenForJWT` 获取。工作负载行为：
 
 **审批消息**（当高风险工具被拦截时）：若要向飞书（或 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 Session Exchange（Gateway WS 方法）
+
+当 `identity.webchatSessionExchange` 为 `true` 时，插件注册两个 gateway WebSocket 方法，允许 webchat 客户端直接注入和获取 session token，无需走 OIDC 重定向流程：
+
+| 方法 | 参数 | 响应 | 描述 |
+| --- | --- | --- | --- |
+| `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。 |
+
+- `senderId` 默认值为 `"openclaw-control-ui"`。对于 main session，实际存储 key 为 `agent:main:main:user:<senderId>`。
+- `channel` 可选；当 session 来源于可发送消息的渠道（feishu、telegram 等）时传入，可启用 per-channel-peer key 提升。
+
+两个方法均**限制为 webchat WS 连接**（`isWebchatConnect` 检查），非 webchat 客户端会收到 `FORBIDDEN` 错误。
+
+**配置：**
+
+```json
+{
+  "identity": {
+    "webchatSessionExchange": true
+  }
+}
+```
+
+**典型流程（BFF → webchat → plugin）：**
+
+1. BFF 完成 3LO 登录并获取用户的 OIDC `id_token`
+2. Webchat 客户端调用 `identity.session.put`，传入 session key 和 `id_token`
+3. 插件校验 token，存储 session，并获取 TIP
+4. 后续该 session 中的 agent 运行拥有有效身份——无需手动登录
+
 ### WebChat / TUI
 
 用户从 WebChat 或 TUI 运行 `/identity` 时，跟进消息不会投递；插件无 API 推送至这些渠道。请使用 `/identity status` 确认结果。

package/README.md

@@ -193,6 +193,8 @@ Add to `openclaw.json` under `plugins.entries.agent-identity.config`:
 | `credentialsFile` | string | No | Path to credential JSON. Default: `VOLCENGINE_CREDENTIALS_FILE` or `/var/run/secrets/iam/credential` |
 | `credentialsMetadataUrl` | string | No | Full URL for remote credential fetch. When set with `roleTrn`, fetches then AssumeRole. 404 falls through to `credentialsFile` |
 | `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 |
 
 \* AK/SK must be provided via `accessKeyId`+`secretAccessKey`, environment variables, `credentialsMetadataUrl`+`roleTrn`, or `credentialsFile`.
 
@@ -235,6 +237,37 @@ Login success and credential fetch follow-up messages (e.g. "✓ Credential for
 
 **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 Session Exchange (Gateway WS Methods)
+
+When `identity.webchatSessionExchange` is `true`, the plugin registers two gateway WebSocket methods for webchat clients to inject and retrieve session tokens without going through the OIDC redirect flow:
+
+| 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. |
+
+- `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.
+
+Both methods are **restricted to webchat WS connections only** (`isWebchatConnect` check). Non-webchat clients receive a `FORBIDDEN` error.
+
+**Config:**
+
+```json
+{
+  "identity": {
+    "webchatSessionExchange": true
+  }
+}
+```
+
+**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`
+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
+
 ### 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.

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;AAsE7D,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,QA2ZtD"}
+{"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"}

package/dist/index.js

@@ -43,6 +43,7 @@ import { createIdentityStatusTool } from "./src/tools/identity-status.js";
 import { createIdentityUnsetBindingTool } from "./src/tools/identity-unset-binding.js";
 import { createIdentityWhoamiTool } from "./src/tools/identity-whoami.js";
 import { parseSessionKeyToDeliveryTarget, } from "./src/utils/derive-session-key.js";
+import { createSessionPutHandler, createSessionGetHandler, } from "./src/gateway/identity-session-methods.js";
 import { logDebug, logInfo, logWarn } from "./src/utils/logger.js";
 import { initEncryptionKey } from "./src/store/encryption.js";
 const PLUGIN_STORE_DIR = "~/.openclaw/plugins/identity";
@@ -410,4 +411,17 @@ export default function register(api) {
     }));
     // Companion after_tool_call: restore env snapshot set by credential injection
     api.on("after_tool_call", createAfterToolCallHandler({ logger: api.logger }));
+    // Gateway WS methods: webchat session exchange (inject / retrieve user token)
+    if (identityCfg?.webchatSessionExchange && hasIdentity) {
+        const sessionMethodDeps = {
+            storeDir,
+            identityService,
+            getOidcConfigForRefresh: getOidcConfigForRefresh ?? undefined,
+            configWorkloadName: identityCfg?.workloadName,
+            logger: api.logger,
+        };
+        api.registerGatewayMethod("identity.session.put", createSessionPutHandler(sessionMethodDeps));
+        api.registerGatewayMethod("identity.session.get", createSessionGetHandler(sessionMethodDeps));
+        logInfo(api.logger, "gateway methods: identity.session.put, identity.session.get (webchat session exchange)");
+    }
 }

package/dist/src/gateway/identity-session-methods.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Gateway WS methods for webchat session exchange:
+ *
+ *   identity.session.put  — inject an OIDC id_token into a plugin session
+ *   identity.session.get  — retrieve the stored user token for a session
+ *
+ * Both methods are restricted to webchat WS connections and gated by
+ * config.identity.webchatSessionExchange.
+ */
+import type { IdentityService } from "../services/identity-service.js";
+import type { OIDCConfigForRefresh } from "../services/session-refresh.js";
+type RespondFn = (ok: boolean, payload?: unknown, error?: {
+    code: string;
+    message: string;
+}) => void;
+type GatewayMethodOptions = {
+    req: {
+        id: string;
+        method: string;
+        params?: unknown;
+    };
+    params: Record<string, unknown>;
+    client: {
+        connect?: {
+            client?: {
+                mode?: string;
+            };
+        };
+    } | null;
+    isWebchatConnect: (params: unknown) => boolean;
+    respond: RespondFn;
+    context: Record<string, unknown>;
+};
+export type GatewayMethodHandler = (opts: GatewayMethodOptions) => Promise<void> | void;
+export type IdentitySessionMethodsDeps = {
+    storeDir: string;
+    identityService: IdentityService;
+    getOidcConfigForRefresh?: () => Promise<OIDCConfigForRefresh>;
+    configWorkloadName?: string;
+    logger: {
+        info?: (msg: string) => void;
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+};
+/**
+ * identity.session.put — inject id_token into a session.
+ *
+ * Params: { sessionKey: string, idToken: string, senderId?: string, channel?: string }
+ * Response: { sub: string, expiresAt: number, effectiveSessionKey: string, hasTip: boolean }
+ *
+ * senderId defaults to "openclaw-control-ui". The effective storage key is derived
+ * via buildEffectiveSessionKey (same logic as hooks/commands) to ensure correct
+ * sender isolation.
+ */
+export declare function createSessionPutHandler(deps: IdentitySessionMethodsDeps): GatewayMethodHandler;
+/**
+ * identity.session.get — retrieve stored user token for a session.
+ *
+ * Params: { sessionKey: string, senderId?: string, channel?: string }
+ * Response: { userToken: string, sub: string, expiresAt: number | null, effectiveSessionKey: string }
+ *
+ * senderId defaults to "openclaw-control-ui".
+ */
+export declare function createSessionGetHandler(deps: IdentitySessionMethodsDeps): GatewayMethodHandler;
+export {};
+//# sourceMappingURL=identity-session-methods.d.ts.map

package/dist/src/gateway/identity-session-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-session-methods.d.ts","sourceRoot":"","sources":["../../../src/gateway/identity-session-methods.ts"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAQ3E,KAAK,SAAS,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAErG,KAAK,oBAAoB,GAAG;IAC1B,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE;gBAAE,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,gBAAgB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC/C,OAAO,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAExF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,eAAe,CAAC;IACjC,uBAAuB,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACvG,CAAC;AAUF;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,0BAA0B,GAAG,oBAAoB,CA8D9F;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,0BAA0B,GAAG,oBAAoB,CAqC9F"}

package/dist/src/gateway/identity-session-methods.js

@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { getSession, setSession } from "../store/session-store.js";
+import { buildEffectiveSessionKey } from "../store/sender-session-store.js";
+import { getOrRefreshTIPToken } from "../services/tip-with-refresh.js";
+import { logDebug, logInfo, logWarn } from "../utils/logger.js";
+const DEFAULT_WEBCHAT_SENDER_ID = "openclaw-control-ui";
+function respondError(respond, code, message) {
+    respond(false, undefined, { code, message });
+}
+function isWebchat(opts) {
+    return opts.isWebchatConnect(opts.client?.connect ?? null);
+}
+/**
+ * identity.session.put — inject id_token into a session.
+ *
+ * Params: { sessionKey: string, idToken: string, senderId?: string, channel?: string }
+ * Response: { sub: string, expiresAt: number, effectiveSessionKey: string, hasTip: boolean }
+ *
+ * senderId defaults to "openclaw-control-ui". The effective storage key is derived
+ * via buildEffectiveSessionKey (same logic as hooks/commands) to ensure correct
+ * sender isolation.
+ */
+export function createSessionPutHandler(deps) {
+    const { storeDir, identityService, getOidcConfigForRefresh, configWorkloadName, logger } = deps;
+    return async (opts) => {
+        if (!isWebchat(opts)) {
+            return respondError(opts.respond, "FORBIDDEN", "identity.session.put is only available for webchat connections");
+        }
+        const { params } = opts;
+        const sessionKey = typeof params.sessionKey === "string" ? params.sessionKey.trim() : "";
+        const idToken = typeof params.idToken === "string" ? params.idToken.trim() : "";
+        const senderId = typeof params.senderId === "string" && params.senderId.trim()
+            ? params.senderId.trim()
+            : DEFAULT_WEBCHAT_SENDER_ID;
+        const channel = typeof params.channel === "string" && params.channel.trim()
+            ? params.channel.trim()
+            : undefined;
+        if (!sessionKey) {
+            return respondError(opts.respond, "INVALID_PARAMS", "sessionKey is required");
+        }
+        if (!idToken) {
+            return respondError(opts.respond, "INVALID_PARAMS", "idToken is required");
+        }
+        const effectiveKey = buildEffectiveSessionKey(sessionKey, senderId, channel);
+        const parsed = identityService.parseUserToken(idToken);
+        if (!parsed.valid || !parsed.sub) {
+            return respondError(opts.respond, "INVALID_TOKEN", "idToken is not a valid JWT or missing sub claim");
+        }
+        let expiresAt = Date.now() + 3600 * 1000;
+        try {
+            const payload = JSON.parse(Buffer.from(idToken.split(".")[1], "base64url").toString("utf-8"));
+            if (payload.exp)
+                expiresAt = payload.exp * 1000;
+        }
+        catch { /* use default */ }
+        await setSession(storeDir, effectiveKey, {
+            userToken: idToken,
+            sub: parsed.sub,
+            loginAt: Date.now(),
+            expiresAt,
+        });
+        logInfo(logger, `identity.session.put: session injected for effectiveKey=${effectiveKey} sub=${parsed.sub}`);
+        const tipRefreshOptions = getOidcConfigForRefresh
+            ? { identityService, getOidcConfigForRefresh, configWorkloadName, logger }
+            : undefined;
+        const tip = await getOrRefreshTIPToken(storeDir, effectiveKey, tipRefreshOptions).catch((err) => {
+            logWarn(logger, `identity.session.put: TIP acquisition failed after inject: ${String(err)}`);
+            return null;
+        });
+        opts.respond(true, {
+            sub: parsed.sub,
+            expiresAt,
+            effectiveSessionKey: effectiveKey,
+            hasTip: Boolean(tip),
+        });
+    };
+}
+/**
+ * identity.session.get — retrieve stored user token for a session.
+ *
+ * Params: { sessionKey: string, senderId?: string, channel?: string }
+ * Response: { userToken: string, sub: string, expiresAt: number | null, effectiveSessionKey: string }
+ *
+ * senderId defaults to "openclaw-control-ui".
+ */
+export function createSessionGetHandler(deps) {
+    const { storeDir, logger } = deps;
+    return async (opts) => {
+        if (!isWebchat(opts)) {
+            return respondError(opts.respond, "FORBIDDEN", "identity.session.get is only available for webchat connections");
+        }
+        const { params } = opts;
+        const sessionKey = typeof params.sessionKey === "string" ? params.sessionKey.trim() : "";
+        const senderId = typeof params.senderId === "string" && params.senderId.trim()
+            ? params.senderId.trim()
+            : DEFAULT_WEBCHAT_SENDER_ID;
+        const channel = typeof params.channel === "string" && params.channel.trim()
+            ? params.channel.trim()
+            : undefined;
+        if (!sessionKey) {
+            return respondError(opts.respond, "INVALID_PARAMS", "sessionKey is required");
+        }
+        const effectiveKey = buildEffectiveSessionKey(sessionKey, senderId, channel);
+        const session = await getSession(storeDir, effectiveKey);
+        if (!session) {
+            return respondError(opts.respond, "NOT_FOUND", `No session found for effectiveKey=${effectiveKey}`);
+        }
+        logDebug(logger, `identity.session.get: returning token for effectiveKey=${effectiveKey} sub=${session.sub}`);
+        opts.respond(true, {
+            userToken: session.userToken,
+            sub: session.sub,
+            expiresAt: session.expiresAt ?? null,
+            effectiveSessionKey: effectiveKey,
+        });
+    };
+}

package/dist/src/store/sender-session-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sender-session-store.d.ts","sourceRoot":"","sources":["../../../src/store/sender-session-store.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAGpE;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAQpE;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEpD;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CASrE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAOR;AASD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAInE;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3F;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAElD"}
+{"version":3,"file":"sender-session-store.d.ts","sourceRoot":"","sources":["../../../src/store/sender-session-store.ts"],"names":[],"mappings":"AAmCA,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAGpE;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAQpE;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEpD;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAQR;AASD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAInE;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3F;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAElD"}

package/dist/src/store/sender-session-store.js

@@ -21,7 +21,7 @@
  * per-channel-peer format (agent:{id}:{channel}:direct:{senderId}), making it
  * parseable for message delivery after OIDC login and approval flows.
  */
-import { needsSenderIsolation, isMainSharedSessionKey, parseAgentIdFromSessionKey, isSendableChannel, } from "../utils/derive-session-key.js";
+import { needsSenderIsolation, isMainSharedSessionKey, parseAgentIdFromSessionKey, isSendableChannel, normalizeMainSessionKey, } from "../utils/derive-session-key.js";
 const SESSION_TTL_MS = 2 * 60 * 60 * 1000;
 const store = new Map();
 export function setSender(sessionKey, info) {
@@ -67,27 +67,29 @@ function promoteMainToChannelPeerKey(sessionKey, channel, senderId) {
  * appending :user:<senderId>.
  */
 export function resolveEffectiveSessionKey(sessionKey) {
-    if (!needsSenderIsolation(sessionKey))
-        return sessionKey;
-    const sender = getSender(sessionKey);
+    const normalized = normalizeMainSessionKey(sessionKey);
+    if (!needsSenderIsolation(normalized))
+        return normalized;
+    const sender = getSender(normalized);
     if (!sender?.senderId)
-        return sessionKey;
-    const promoted = promoteMainToChannelPeerKey(sessionKey, sender.channelId, sender.senderId);
+        return normalized;
+    const promoted = promoteMainToChannelPeerKey(normalized, sender.channelId, sender.senderId);
     if (promoted)
         return promoted;
-    return `${sessionKey}:user:${sender.senderId}`;
+    return `${normalized}:user:${sender.senderId}`;
 }
 /**
  * Same as resolveEffectiveSessionKey but takes explicit senderId and channel
  * (used by commands where ctx.senderId and ctx.channel are directly available).
  */
 export function buildEffectiveSessionKey(sessionKey, senderId, channel) {
-    if (!senderId || !needsSenderIsolation(sessionKey))
-        return sessionKey;
-    const promoted = promoteMainToChannelPeerKey(sessionKey, channel, senderId);
+    const normalized = normalizeMainSessionKey(sessionKey);
+    if (!senderId || !needsSenderIsolation(normalized))
+        return normalized;
+    const promoted = promoteMainToChannelPeerKey(normalized, channel, senderId);
     if (promoted)
         return promoted;
-    return `${sessionKey}:user:${senderId}`;
+    return `${normalized}:user:${senderId}`;
 }
 // --------------- freeze-by-runId ---------------
 const RUN_TTL_MS = 2 * 60 * 60 * 1000;

package/dist/src/types.d.ts

@@ -31,6 +31,8 @@ export type IdentityConfig = {
     durationSeconds?: number;
     /** Propagate TIP and session to subagents (sessions_spawn, sessions_send to subagent). Default: false. */
     subagentTipPropagation?: boolean;
+    /** Enable identity.session.put / identity.session.get gateway WS methods for webchat clients. Default: false. */
+    webchatSessionExchange?: boolean;
 };
 export type UserPoolConfig = {
     /** Explicit: discovery URL for OIDC. */

package/dist/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/derive-session-key.d.ts

@@ -22,6 +22,12 @@ type DeriveSessionKeyParams = {
     accountId?: string;
     config: ConfigWithSession;
 };
+/**
+ * Normalize 3-segment gateway-assigned session keys to canonical main form.
+ * `agent:{id}:<uuid>` → `agent:{id}:main`.
+ * Keys that are already `agent:{id}:main` or have 4+ segments are returned as-is.
+ */
+export declare function normalizeMainSessionKey(sessionKey: string): string;
 /**
  * Derive agentId from config. Fallback when ctx.agentId and sessionKey are not available.
  */
@@ -59,7 +65,10 @@ export declare function isSubagentSessionKey(sessionKey: string | undefined | nu
  */
 export declare function isGroupOrChannelSessionKey(sessionKey: string | undefined | null): boolean;
 /**
- * Check whether sessionKey is the default "main" shared session (agent:{id}:main).
+ * Check whether sessionKey is the default "main" shared session.
+ * Matches any 3-segment key: `agent:{id}:main` as well as gateway-assigned
+ * variants like `agent:{id}:<uuid>` (e.g. `agent:main:db222689-...`).
+ *
  * When dmScope is unset, all DM users share this key — including:
  * - Feishu/Telegram/etc. DMs (have senderId, will be isolated)
  * - webchat/tui (typically no senderId; single-user, so no isolation needed)

package/dist/src/utils/derive-session-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-session-key.d.ts","sourceRoot":"","sources":["../../../src/utils/derive-session-key.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"derive-session-key.d.ts","sourceRoot":"","sources":["../../../src/utils/derive-session-key.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/derive-session-key.js

@@ -15,6 +15,19 @@
  */
 const DEFAULT_AGENT_ID = "main";
 const DEFAULT_ACCOUNT_ID = "default";
+/**
+ * Normalize 3-segment gateway-assigned session keys to canonical main form.
+ * `agent:{id}:<uuid>` → `agent:{id}:main`.
+ * Keys that are already `agent:{id}:main` or have 4+ segments are returned as-is.
+ */
+export function normalizeMainSessionKey(sessionKey) {
+    const parts = sessionKey.split(":");
+    if (parts.length !== 3 || parts[0]?.toLowerCase() !== "agent")
+        return sessionKey;
+    if (parts[2].toLowerCase() === "main")
+        return sessionKey;
+    return `${parts[0]}:${parts[1]}:main`;
+}
 function normalizeAgentId(value) {
     const trimmed = (value ?? "").trim();
     return trimmed ? trimmed.toLowerCase() : DEFAULT_AGENT_ID;
@@ -84,7 +97,10 @@ export function isGroupOrChannelSessionKey(sessionKey) {
     return scope === "group" || scope === "channel";
 }
 /**
- * Check whether sessionKey is the default "main" shared session (agent:{id}:main).
+ * Check whether sessionKey is the default "main" shared session.
+ * Matches any 3-segment key: `agent:{id}:main` as well as gateway-assigned
+ * variants like `agent:{id}:<uuid>` (e.g. `agent:main:db222689-...`).
+ *
  * When dmScope is unset, all DM users share this key — including:
  * - Feishu/Telegram/etc. DMs (have senderId, will be isolated)
  * - webchat/tui (typically no senderId; single-user, so no isolation needed)
@@ -93,7 +109,7 @@ export function isMainSharedSessionKey(sessionKey) {
     const raw = (sessionKey ?? "").trim().toLowerCase();
     if (!raw)
         return false;
-    return /^agent:[^:]+:main$/.test(raw);
+    return /^agent:[^:]+:[^:]+$/.test(raw);
 }
 /**
  * Whether the sessionKey may be shared by multiple users and thus requires

package/openclaw.plugin.json

@@ -60,6 +60,11 @@
             "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."
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1a0rz/agent-identity",
-  "version": "0.4.0",
+  "version": "0.4.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",
@@ -9,7 +9,16 @@
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["openclaw", "identity", "volcengine", "userpool", "credential", "TIP", "auth", "agent"],
+  "keywords": [
+    "openclaw",
+    "identity",
+    "volcengine",
+    "userpool",
+    "credential",
+    "TIP",
+    "auth",
+    "agent"
+  ],
   "license": "Apache-2.0",
   "dependencies": {
     "@sinclair/typebox": "0.34.48",
@@ -17,7 +26,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "ws": "^8.19.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.8"
@@ -28,7 +38,15 @@
     }
   },
   "openclaw": {
-    "extensions": ["./dist/index.js"]
+    "extensions": [
+      "./dist/index.js"
+    ]
   },
-  "files": ["dist", "README.md", "README-cn.md", "skills/SKILL.md", "openclaw.plugin.json"]
+  "files": [
+    "dist",
+    "README.md",
+    "README-cn.md",
+    "skills/SKILL.md",
+    "openclaw.plugin.json"
+  ]
 }