@alfe.ai/openclaw-identity 0.0.15 → 0.0.17

package/dist/index.d.cts

@@ -1,16 +1,40 @@
 import plugin from "./plugin.cjs";
 
-//#region src/policy-cache.d.ts
+//#region src/runtime-contract.d.ts
 
-type IdentityFailureMode = "open" | "closed" | "permissive";
 /**
- * Evaluate whether a tool call should be blocked based on the cached policy
- * and failure mode.
+ * OpenClaw runtime contract for the identity plugin's `before_tool_call` hook.
+ *
+ * Phase 1 Stage A.0 of the roles/permissions/sessions plan. The plugin's hook
+ * signature documents what the OpenClaw daemon must populate when a tool call
+ * is dispatched. The actual gate logic (Stage E) reads these fields to make a
+ * permit/deny decision via `@auriclabs/roles`.
+ *
+ * Contract:
+ *   - `ToolCallEvent` describes the tool being called (name + args).
+ *   - `ToolCallContext` describes the calling context (tenant, agent, actor).
+ *
+ * The hook receives `(event, ctx)`. Both arguments are required. The daemon
+ * is responsible for populating every required field; the plugin's gate
+ * applies the per-agent `IdentityFailureMode` when an optional field is
+ * absent and a permission decision can't be made cleanly.
+ *
+ * Round 6 note (gate context shape): the gate context passed to `sift` is
+ * `{ tool: event.toolName, args: event.toolArgs }` with strict namespacing
+ * (no spread). This prevents an attacker-controlled `tool` field inside
+ * `toolArgs` from overriding the gate's value.
  */
-
-//#endregion
-//#region src/runtime-contract.d.ts
-
+/**
+ * Per-agent fallback policy when an optional `ctx.actingIdentityId` is
+ * absent (e.g. autonomous tool_chain runs that don't carry a chat-side
+ * sender). Round-5 unified plan literals.
+ *
+ *   - "open"       — admit the call (legacy default).
+ *   - "closed"     — block the call (production default once Stage E ships).
+ *   - "permissive" — admit with a warn-level audit log; intermediate during
+ *                    the Stage H dwell window.
+ */
+type IdentityFailureMode = "open" | "closed" | "permissive";
 /**
  * The tool the agent is about to call.
  *

package/dist/index.d.ts

@@ -1,16 +1,40 @@
 import plugin from "./plugin.js";
 
-//#region src/policy-cache.d.ts
+//#region src/runtime-contract.d.ts
 
-type IdentityFailureMode = "open" | "closed" | "permissive";
 /**
- * Evaluate whether a tool call should be blocked based on the cached policy
- * and failure mode.
+ * OpenClaw runtime contract for the identity plugin's `before_tool_call` hook.
+ *
+ * Phase 1 Stage A.0 of the roles/permissions/sessions plan. The plugin's hook
+ * signature documents what the OpenClaw daemon must populate when a tool call
+ * is dispatched. The actual gate logic (Stage E) reads these fields to make a
+ * permit/deny decision via `@auriclabs/roles`.
+ *
+ * Contract:
+ *   - `ToolCallEvent` describes the tool being called (name + args).
+ *   - `ToolCallContext` describes the calling context (tenant, agent, actor).
+ *
+ * The hook receives `(event, ctx)`. Both arguments are required. The daemon
+ * is responsible for populating every required field; the plugin's gate
+ * applies the per-agent `IdentityFailureMode` when an optional field is
+ * absent and a permission decision can't be made cleanly.
+ *
+ * Round 6 note (gate context shape): the gate context passed to `sift` is
+ * `{ tool: event.toolName, args: event.toolArgs }` with strict namespacing
+ * (no spread). This prevents an attacker-controlled `tool` field inside
+ * `toolArgs` from overriding the gate's value.
  */
-
-//#endregion
-//#region src/runtime-contract.d.ts
-
+/**
+ * Per-agent fallback policy when an optional `ctx.actingIdentityId` is
+ * absent (e.g. autonomous tool_chain runs that don't carry a chat-side
+ * sender). Round-5 unified plan literals.
+ *
+ *   - "open"       — admit the call (legacy default).
+ *   - "closed"     — block the call (production default once Stage E ships).
+ *   - "permissive" — admit with a warn-level audit log; intermediate during
+ *                    the Stage H dwell window.
+ */
+type IdentityFailureMode = "open" | "closed" | "permissive";
 /**
  * The tool the agent is about to call.
  *

package/dist/plugin.d.cts

@@ -35,6 +35,7 @@ declare const plugin: {
   description: string;
   version: string;
   activate(api: PluginApi): void;
+  deactivate(api: PluginApi): void;
 };
 //#endregion
 export { plugin as default };

package/dist/plugin.d.ts

@@ -35,6 +35,7 @@ declare const plugin: {
   description: string;
   version: string;
   activate(api: PluginApi): void;
+  deactivate(api: PluginApi): void;
 };
 //#endregion
 export { plugin as default };

package/dist/plugin2.cjs

@@ -82,21 +82,49 @@ function resolveToolGatingMode() {
 	if (raw === "fail-open" || raw === "fail-closed") return raw;
 	return "fail-open";
 }
+/**
+* Evaluate `agent:chat` — the inbound conversational gate (Layer 2 of the
+* default-deny chat path). Mirrors `evaluateAgentExec` but with no
+* tool/args context — chat admission only depends on whether the
+* resolved identity holds `agent:chat` at the agent's scope.
+*
+* Layer 1 (`services/chat`) already gates this for chat WS + channel
+* adapter inject. The OpenClaw plugin's `message_received` hook is
+* defense-in-depth — it catches any path that reaches the agent
+* runtime without going through Layer 1.
+*/
+function evaluateAgentChat(permissions, args) {
+	if (!args.agentId) return { allowed: false };
+	const ability = (0, _auriclabs_roles.createAbility)(permissions);
+	const gatePermission = {
+		subject: "agent",
+		action: "chat",
+		scope: `agent:${args.agentId}`
+	};
+	return { allowed: ability.has(gatePermission, {}) };
+}
 //#endregion
 //#region src/plugin.ts
 /**
 * @alfe.ai/openclaw-identity — OpenClaw native plugin
 *
-* HTTP-based identity resolution + AccessConfig admission gate. Installed as
+* HTTP-based identity resolution + role-based admission gate. Installed as
 * part of the core alfe integration on every agent.
 *
 * Hooks:
-*   - message_received  → always resolves the sender, gates on accessAllowed,
-*                         blocks unknown senders (read-only resolve).
+*   - message_received  → resolves the sender via the agent API and gates
+*                         on `agent:chat` at the agent's scope using the
+*                         resolved identity's permission set
+*                         (`evaluateAgentChat`). Blocks unknown senders
+*                         and any identity without the permission. Layer 2
+*                         of the default-deny chat path.
 *   - before_tool_call  → typed `(event: ToolCallEvent, ctx: ToolCallContext)`
-*                         hook (Phase 1 Stage A.0). Today: permissive no-op
-*                         stub. Phase 1 Stage E swaps the stub for the
-*                         `agent:exec` + sift gate (Decision 17).
+*                         hook (Phase 1 Stage A.0). Gates `agent:exec`
+*                         via `evaluateAgentExec` against the token's
+*                         own permissions (token path) or the cached
+*                         resolved permissions (JWT path). Sift
+*                         conditions on the permission narrow which
+*                         tools the call may invoke.
 *
 * `after_tool_call` is intentionally absent — tool-call audit lives in a
 * future dedicated audit service, not in identity.
@@ -152,6 +180,8 @@ function defineTool(def) {
 		}
 	};
 }
+const ACTIVATED_KEY = "__alfeIdentityPluginActivated";
+const g = globalThis;
 const plugin = {
 	id: "@alfe.ai/openclaw-identity",
 	name: "Alfe Identity",
@@ -159,6 +189,11 @@ const plugin = {
 	version: pkg.version,
 	activate(api) {
 		const log = api.logger;
+		if (g[ACTIVATED_KEY] === true) {
+			log.debug("Alfe Identity plugin already activated — skipping duplicate");
+			return;
+		}
+		g[ACTIVATED_KEY] = true;
 		log.info("Alfe Identity plugin activating...");
 		let client;
 		try {
@@ -168,6 +203,7 @@ const plugin = {
 				apiUrl: config.apiUrl
 			});
 		} catch (err) {
+			g[ACTIVATED_KEY] = false;
 			log.error(`Identity plugin: failed to resolve config — ${err instanceof Error ? err.message : String(err)}`);
 			return;
 		}
@@ -353,6 +389,15 @@ const plugin = {
 			const provider = ctx.channelId ?? "unknown";
 			const senderId = event.metadata?.UserId ?? event.from;
 			if (!senderId) return;
+			const agentId = ctx.agentId;
+			if (!agentId) {
+				log.warn(`message_received without ctx.agentId — fail-closed`);
+				return {
+					block: true,
+					blockReason: "Identity: agentId missing on message context"
+				};
+			}
+			const forwarded = Array.isArray(event.metadata?.SenderPermissions) ? event.metadata.SenderPermissions.filter((p) => typeof p === "string") : [];
 			const cacheKey = ctx.conversationId ?? `${provider}:${senderId}`;
 			const cached = getCachedResolve(cacheKey);
 			if (cached) {
@@ -360,9 +405,9 @@ const plugin = {
 					block: true,
 					blockReason: "Identity: identity not provisioned for this channel"
 				};
-				if (!cached.accessAllowed) return {
+				if (!evaluateAgentChat([...cached.permissions, ...forwarded], { agentId }).allowed) return {
 					block: true,
-					blockReason: "Identity: access denied for this sender"
+					blockReason: "Identity: chat not permitted for this sender"
 				};
 				return;
 			}
@@ -373,8 +418,8 @@ const plugin = {
 				});
 				setCachedResolve(cacheKey, {
 					identityId: r.identityId,
-					accessAllowed: r.accessAllowed,
-					status: r.status
+					status: r.status,
+					permissions: [...r.permissions, ...forwarded]
 				});
 				if (r.identityId == null) {
 					log.warn(`Identity not provisioned for ${provider}:${senderId} — blocking inbound message`);
@@ -383,9 +428,10 @@ const plugin = {
 						blockReason: "Identity: identity not provisioned for this channel"
 					};
 				}
-				if (!r.accessAllowed) return {
+				const cachedAfterFill = getCachedResolve(cacheKey);
+				if (!evaluateAgentChat(cachedAfterFill ? [...cachedAfterFill.permissions] : [...r.permissions, ...forwarded], { agentId }).allowed) return {
 					block: true,
-					blockReason: "Identity: access denied for this sender"
+					blockReason: "Identity: chat not permitted for this sender"
 				};
 				log.info(`Identity resolved: ${senderId} → ${r.identityId} (${r.status})`);
 			} catch (e) {
@@ -405,10 +451,32 @@ const plugin = {
 				}), resolveToolGatingMode(), event.toolName);
 				return Promise.resolve(blocked);
 			}
-			return Promise.resolve(void 0);
+			const cacheKey = ctx.conversationId ?? (ctx.channelId && ctx.actingIdentityId ? `${ctx.channelId}:${ctx.actingIdentityId}` : null);
+			if (cacheKey) {
+				const cached = getCachedResolve(cacheKey);
+				if (cached && cached.permissions.length > 0) {
+					const blocked = applyGateMode(evaluateAgentExec([...cached.permissions], {
+						agentId: ctx.agentId,
+						toolName: event.toolName,
+						toolArgs: event.toolArgs
+					}), resolveToolGatingMode(), event.toolName);
+					return Promise.resolve(blocked);
+				}
+			}
+			const fallback = evaluateAgentExec([], {
+				agentId: ctx.agentId,
+				toolName: event.toolName,
+				toolArgs: event.toolArgs
+			});
+			const mode = resolveToolGatingMode();
+			return Promise.resolve(applyGateMode(fallback, mode, event.toolName));
 		};
 		api.on("before_tool_call", (...args) => beforeToolCallStub(args[0], args[1]), { priority: 100 });
 		log.info("Alfe Identity plugin activated");
+	},
+	deactivate(api) {
+		g[ACTIVATED_KEY] = false;
+		api.logger.info("Alfe Identity plugin deactivated");
 	}
 };
 //#endregion

package/dist/plugin2.js

@@ -82,21 +82,49 @@ function resolveToolGatingMode() {
 	if (raw === "fail-open" || raw === "fail-closed") return raw;
 	return "fail-open";
 }
+/**
+* Evaluate `agent:chat` — the inbound conversational gate (Layer 2 of the
+* default-deny chat path). Mirrors `evaluateAgentExec` but with no
+* tool/args context — chat admission only depends on whether the
+* resolved identity holds `agent:chat` at the agent's scope.
+*
+* Layer 1 (`services/chat`) already gates this for chat WS + channel
+* adapter inject. The OpenClaw plugin's `message_received` hook is
+* defense-in-depth — it catches any path that reaches the agent
+* runtime without going through Layer 1.
+*/
+function evaluateAgentChat(permissions, args) {
+	if (!args.agentId) return { allowed: false };
+	const ability = createAbility(permissions);
+	const gatePermission = {
+		subject: "agent",
+		action: "chat",
+		scope: `agent:${args.agentId}`
+	};
+	return { allowed: ability.has(gatePermission, {}) };
+}
 //#endregion
 //#region src/plugin.ts
 /**
 * @alfe.ai/openclaw-identity — OpenClaw native plugin
 *
-* HTTP-based identity resolution + AccessConfig admission gate. Installed as
+* HTTP-based identity resolution + role-based admission gate. Installed as
 * part of the core alfe integration on every agent.
 *
 * Hooks:
-*   - message_received  → always resolves the sender, gates on accessAllowed,
-*                         blocks unknown senders (read-only resolve).
+*   - message_received  → resolves the sender via the agent API and gates
+*                         on `agent:chat` at the agent's scope using the
+*                         resolved identity's permission set
+*                         (`evaluateAgentChat`). Blocks unknown senders
+*                         and any identity without the permission. Layer 2
+*                         of the default-deny chat path.
 *   - before_tool_call  → typed `(event: ToolCallEvent, ctx: ToolCallContext)`
-*                         hook (Phase 1 Stage A.0). Today: permissive no-op
-*                         stub. Phase 1 Stage E swaps the stub for the
-*                         `agent:exec` + sift gate (Decision 17).
+*                         hook (Phase 1 Stage A.0). Gates `agent:exec`
+*                         via `evaluateAgentExec` against the token's
+*                         own permissions (token path) or the cached
+*                         resolved permissions (JWT path). Sift
+*                         conditions on the permission narrow which
+*                         tools the call may invoke.
 *
 * `after_tool_call` is intentionally absent — tool-call audit lives in a
 * future dedicated audit service, not in identity.
@@ -152,6 +180,8 @@ function defineTool(def) {
 		}
 	};
 }
+const ACTIVATED_KEY = "__alfeIdentityPluginActivated";
+const g = globalThis;
 const plugin = {
 	id: "@alfe.ai/openclaw-identity",
 	name: "Alfe Identity",
@@ -159,6 +189,11 @@ const plugin = {
 	version: pkg.version,
 	activate(api) {
 		const log = api.logger;
+		if (g[ACTIVATED_KEY] === true) {
+			log.debug("Alfe Identity plugin already activated — skipping duplicate");
+			return;
+		}
+		g[ACTIVATED_KEY] = true;
 		log.info("Alfe Identity plugin activating...");
 		let client;
 		try {
@@ -168,6 +203,7 @@ const plugin = {
 				apiUrl: config.apiUrl
 			});
 		} catch (err) {
+			g[ACTIVATED_KEY] = false;
 			log.error(`Identity plugin: failed to resolve config — ${err instanceof Error ? err.message : String(err)}`);
 			return;
 		}
@@ -353,6 +389,15 @@ const plugin = {
 			const provider = ctx.channelId ?? "unknown";
 			const senderId = event.metadata?.UserId ?? event.from;
 			if (!senderId) return;
+			const agentId = ctx.agentId;
+			if (!agentId) {
+				log.warn(`message_received without ctx.agentId — fail-closed`);
+				return {
+					block: true,
+					blockReason: "Identity: agentId missing on message context"
+				};
+			}
+			const forwarded = Array.isArray(event.metadata?.SenderPermissions) ? event.metadata.SenderPermissions.filter((p) => typeof p === "string") : [];
 			const cacheKey = ctx.conversationId ?? `${provider}:${senderId}`;
 			const cached = getCachedResolve(cacheKey);
 			if (cached) {
@@ -360,9 +405,9 @@ const plugin = {
 					block: true,
 					blockReason: "Identity: identity not provisioned for this channel"
 				};
-				if (!cached.accessAllowed) return {
+				if (!evaluateAgentChat([...cached.permissions, ...forwarded], { agentId }).allowed) return {
 					block: true,
-					blockReason: "Identity: access denied for this sender"
+					blockReason: "Identity: chat not permitted for this sender"
 				};
 				return;
 			}
@@ -373,8 +418,8 @@ const plugin = {
 				});
 				setCachedResolve(cacheKey, {
 					identityId: r.identityId,
-					accessAllowed: r.accessAllowed,
-					status: r.status
+					status: r.status,
+					permissions: [...r.permissions, ...forwarded]
 				});
 				if (r.identityId == null) {
 					log.warn(`Identity not provisioned for ${provider}:${senderId} — blocking inbound message`);
@@ -383,9 +428,10 @@ const plugin = {
 						blockReason: "Identity: identity not provisioned for this channel"
 					};
 				}
-				if (!r.accessAllowed) return {
+				const cachedAfterFill = getCachedResolve(cacheKey);
+				if (!evaluateAgentChat(cachedAfterFill ? [...cachedAfterFill.permissions] : [...r.permissions, ...forwarded], { agentId }).allowed) return {
 					block: true,
-					blockReason: "Identity: access denied for this sender"
+					blockReason: "Identity: chat not permitted for this sender"
 				};
 				log.info(`Identity resolved: ${senderId} → ${r.identityId} (${r.status})`);
 			} catch (e) {
@@ -405,10 +451,32 @@ const plugin = {
 				}), resolveToolGatingMode(), event.toolName);
 				return Promise.resolve(blocked);
 			}
-			return Promise.resolve(void 0);
+			const cacheKey = ctx.conversationId ?? (ctx.channelId && ctx.actingIdentityId ? `${ctx.channelId}:${ctx.actingIdentityId}` : null);
+			if (cacheKey) {
+				const cached = getCachedResolve(cacheKey);
+				if (cached && cached.permissions.length > 0) {
+					const blocked = applyGateMode(evaluateAgentExec([...cached.permissions], {
+						agentId: ctx.agentId,
+						toolName: event.toolName,
+						toolArgs: event.toolArgs
+					}), resolveToolGatingMode(), event.toolName);
+					return Promise.resolve(blocked);
+				}
+			}
+			const fallback = evaluateAgentExec([], {
+				agentId: ctx.agentId,
+				toolName: event.toolName,
+				toolArgs: event.toolArgs
+			});
+			const mode = resolveToolGatingMode();
+			return Promise.resolve(applyGateMode(fallback, mode, event.toolName));
 		};
 		api.on("before_tool_call", (...args) => beforeToolCallStub(args[0], args[1]), { priority: 100 });
 		log.info("Alfe Identity plugin activated");
+	},
+	deactivate(api) {
+		g[ACTIVATED_KEY] = false;
+		api.logger.info("Alfe Identity plugin deactivated");
 	}
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/openclaw-identity",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "OpenClaw identity plugin — identity resolution, access gating, permission enforcement",
   "type": "module",
   "main": "./dist/plugin.js",