@alfe.ai/openclaw-identity 0.0.14 → 0.0.16

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/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.
@@ -353,6 +381,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 +397,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 +410,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 +420,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,7 +443,25 @@ 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");

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.
@@ -353,6 +381,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 +397,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 +410,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 +420,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,7 +443,25 @@ 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");

package/openclaw.plugin.json

@@ -7,5 +7,21 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {}
+  },
+  "activation": { "onStartup": true },
+  "contracts": {
+    "tools": [
+      "who_is_this",
+      "lookup_identity",
+      "tag_identity",
+      "add_identity_note",
+      "update_identity",
+      "merge_identities",
+      "unmerge_identities",
+      "request_identity_verification",
+      "confirm_identity_verification",
+      "get_identity_changelog",
+      "rollback_identity"
+    ]
   }
 }

package/package.json

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