@alfe.ai/openclaw-identity 0.1.26 → 0.1.28

package/README.md

@@ -0,0 +1,14 @@
+# `@alfe.ai/openclaw-identity`
+
+OpenClaw plugin for Alfe identity resolution, self-service verification, and
+role-based `agent:exec` tool gating.
+
+The plugin registers identity tools, prepares a short-lived sender context from
+inbound messages, and evaluates tool calls with `@auriclabs/roles`. The
+`OPENCLAW_TOOL_GATING` environment variable accepts `fail-open` or
+`fail-closed`; it intentionally defaults to `fail-open` while the staged
+permission rollout is incomplete.
+
+This package is installed by the core Alfe integration. For platform setup and
+documentation, visit [alfe.ai](https://alfe.ai) and
+[docs.alfe.ai](https://docs.alfe.ai).

package/dist/index.cjs

@@ -7,7 +7,7 @@ const require_plugin = require("./plugin2.cjs");
 /**
 * Build the gate context object used by sift evaluation. This is the
 * round-6 "strict namespacing" shape — `args` is a top-level field, not
-* spread, so an attacker-controlled `tool` field inside `toolArgs` cannot
+* spread, so an attacker-controlled `tool` field inside `params` cannot
 * override the gate's `tool` value.
 *
 * Stage E's gate calls:
@@ -19,7 +19,7 @@ const require_plugin = require("./plugin2.cjs");
 function buildGateContext(event) {
 	return {
 		tool: event.toolName,
-		args: event.toolArgs
+		args: event.params
 	};
 }
 //#endregion

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import plugin from "./plugin.cjs";
+import { t as plugin } from "./plugin.cjs";
 
 //#region src/runtime-contract.d.ts
 
@@ -11,18 +11,19 @@ import plugin from "./plugin.cjs";
  * permit/deny decision via `@auriclabs/roles`.
  *
  * Contract:
- *   - `ToolCallEvent` describes the tool being called (name + args).
- *   - `ToolCallContext` describes the calling context (tenant, agent, actor).
+ *   - `ToolCallEvent` describes the tool being called (name + params).
+ *   - `ToolCallContext` mirrors the fields OpenClaw actually supplies.
  *
- * 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.
+ * The hook receives `(event, ctx)`. OpenClaw currently supplies tool identity,
+ * run/session identity, and an optional agent id. It does not supply tenant,
+ * conversation, actor, auth-method, or token-permission fields. The plugin
+ * bridges the active conversation from `message_received` into the run instead
+ * of pretending those absent fields are runtime guarantees.
  *
  * Round 6 note (gate context shape): the gate context passed to `sift` is
- * `{ tool: event.toolName, args: event.toolArgs }` with strict namespacing
+ * `{ tool: event.toolName, args: event.params }` with strict namespacing
  * (no spread). This prevents an attacker-controlled `tool` field inside
- * `toolArgs` from overriding the gate's value.
+ * `params` from overriding the gate's value.
  */
 /**
  * Per-agent fallback policy when an optional `ctx.actingIdentityId` is
@@ -47,7 +48,11 @@ interface ToolCallEvent {
   /** Namespaced tool name, e.g. "gmail:send_email". */
   readonly toolName: string;
   /** Arbitrary argument bag passed to the tool's `execute` function. */
-  readonly toolArgs: Record<string, unknown>;
+  readonly params: Record<string, unknown>;
+  /** Stable run identifier for this invocation, when supplied. */
+  readonly runId?: string;
+  /** Provider-specific tool-call identifier, when supplied. */
+  readonly toolCallId?: string;
 }
 /**
  * What initiated the tool call. Three buckets:
@@ -97,18 +102,24 @@ interface RuntimePermission {
   readonly type?: "can" | "cannot";
 }
 /**
- * Calling context for the tool call. Populated by the OpenClaw daemon at
- * dispatch time.
+ * Calling context for the tool call. This is the production OpenClaw hook
+ * shape (verified against the installed runtime), not an aspirational Alfe
+ * authorization envelope.
  */
 interface ToolCallContext {
-  /** Required: the tenant (`org_*`) that owns the agent. */
-  readonly tenantId: string;
-  /** Required: the agent (`agt_*`) that is about to call the tool. */
-  readonly agentId: string;
-  /** Required: how the caller authenticated. */
-  readonly authMethod: ToolCallAuthMethod;
-  /** Required: what initiated the call. */
-  readonly trigger: ToolCallTrigger;
+  readonly toolName: string;
+  readonly agentId?: string;
+  readonly sessionKey?: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly toolCallId?: string;
+  /**
+   * Compatibility fields for an Alfe-augmented runtime. Stock OpenClaw does
+   * not currently populate these; callers must not depend on their presence.
+   */
+  readonly tenantId?: string;
+  readonly authMethod?: ToolCallAuthMethod;
+  readonly trigger?: ToolCallTrigger;
   /**
    * The identity (`idn_*`) the agent is acting on behalf of. Resolution
    * order:
@@ -136,25 +147,26 @@ interface ToolCallContext {
   readonly channelId?: string;
 }
 /**
- * Return value of the `before_tool_call` hook.
- *   - `undefined` — allow.
- *   - `{ block: true, blockReason: string }` — deny with reason surfaced to
- *     the agent's response (Stage E behaviour).
+ * Relevant subset of OpenClaw's `before_tool_call` return value.
+ *   - `undefined` — allow without changing parameters.
+ *   - `{ params }` — allow with parameters merged into the tool invocation.
+ *   - `{ block: true, blockReason }` — deny with a surfaced reason.
  */
 type ToolCallHookResult = undefined | {
+  params: Record<string, unknown>;
+} | {
   block: true;
   blockReason: string;
 };
 /**
- * Strongly-typed `before_tool_call` hook signature. The plugin's stub uses
- * this signature today; Stage E swaps the stub for the real `agent:exec` +
- * sift gate against `@auriclabs/roles`.
+ * Strongly-typed `before_tool_call` hook signature used by the live
+ * `agent:exec` + sift gate against `@auriclabs/roles`.
  */
 type BeforeToolCallHook = (event: ToolCallEvent, ctx: ToolCallContext) => Promise<ToolCallHookResult>;
 /**
  * Build the gate context object used by sift evaluation. This is the
  * round-6 "strict namespacing" shape — `args` is a top-level field, not
- * spread, so an attacker-controlled `tool` field inside `toolArgs` cannot
+ * spread, so an attacker-controlled `tool` field inside `params` cannot
  * override the gate's `tool` value.
  *
  * Stage E's gate calls:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import plugin from "./plugin.js";
+import { t as plugin } from "./plugin.js";
 
 //#region src/runtime-contract.d.ts
 
@@ -11,18 +11,19 @@ import plugin from "./plugin.js";
  * permit/deny decision via `@auriclabs/roles`.
  *
  * Contract:
- *   - `ToolCallEvent` describes the tool being called (name + args).
- *   - `ToolCallContext` describes the calling context (tenant, agent, actor).
+ *   - `ToolCallEvent` describes the tool being called (name + params).
+ *   - `ToolCallContext` mirrors the fields OpenClaw actually supplies.
  *
- * 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.
+ * The hook receives `(event, ctx)`. OpenClaw currently supplies tool identity,
+ * run/session identity, and an optional agent id. It does not supply tenant,
+ * conversation, actor, auth-method, or token-permission fields. The plugin
+ * bridges the active conversation from `message_received` into the run instead
+ * of pretending those absent fields are runtime guarantees.
  *
  * Round 6 note (gate context shape): the gate context passed to `sift` is
- * `{ tool: event.toolName, args: event.toolArgs }` with strict namespacing
+ * `{ tool: event.toolName, args: event.params }` with strict namespacing
  * (no spread). This prevents an attacker-controlled `tool` field inside
- * `toolArgs` from overriding the gate's value.
+ * `params` from overriding the gate's value.
  */
 /**
  * Per-agent fallback policy when an optional `ctx.actingIdentityId` is
@@ -47,7 +48,11 @@ interface ToolCallEvent {
   /** Namespaced tool name, e.g. "gmail:send_email". */
   readonly toolName: string;
   /** Arbitrary argument bag passed to the tool's `execute` function. */
-  readonly toolArgs: Record<string, unknown>;
+  readonly params: Record<string, unknown>;
+  /** Stable run identifier for this invocation, when supplied. */
+  readonly runId?: string;
+  /** Provider-specific tool-call identifier, when supplied. */
+  readonly toolCallId?: string;
 }
 /**
  * What initiated the tool call. Three buckets:
@@ -97,18 +102,24 @@ interface RuntimePermission {
   readonly type?: "can" | "cannot";
 }
 /**
- * Calling context for the tool call. Populated by the OpenClaw daemon at
- * dispatch time.
+ * Calling context for the tool call. This is the production OpenClaw hook
+ * shape (verified against the installed runtime), not an aspirational Alfe
+ * authorization envelope.
  */
 interface ToolCallContext {
-  /** Required: the tenant (`org_*`) that owns the agent. */
-  readonly tenantId: string;
-  /** Required: the agent (`agt_*`) that is about to call the tool. */
-  readonly agentId: string;
-  /** Required: how the caller authenticated. */
-  readonly authMethod: ToolCallAuthMethod;
-  /** Required: what initiated the call. */
-  readonly trigger: ToolCallTrigger;
+  readonly toolName: string;
+  readonly agentId?: string;
+  readonly sessionKey?: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly toolCallId?: string;
+  /**
+   * Compatibility fields for an Alfe-augmented runtime. Stock OpenClaw does
+   * not currently populate these; callers must not depend on their presence.
+   */
+  readonly tenantId?: string;
+  readonly authMethod?: ToolCallAuthMethod;
+  readonly trigger?: ToolCallTrigger;
   /**
    * The identity (`idn_*`) the agent is acting on behalf of. Resolution
    * order:
@@ -136,25 +147,26 @@ interface ToolCallContext {
   readonly channelId?: string;
 }
 /**
- * Return value of the `before_tool_call` hook.
- *   - `undefined` — allow.
- *   - `{ block: true, blockReason: string }` — deny with reason surfaced to
- *     the agent's response (Stage E behaviour).
+ * Relevant subset of OpenClaw's `before_tool_call` return value.
+ *   - `undefined` — allow without changing parameters.
+ *   - `{ params }` — allow with parameters merged into the tool invocation.
+ *   - `{ block: true, blockReason }` — deny with a surfaced reason.
  */
 type ToolCallHookResult = undefined | {
+  params: Record<string, unknown>;
+} | {
   block: true;
   blockReason: string;
 };
 /**
- * Strongly-typed `before_tool_call` hook signature. The plugin's stub uses
- * this signature today; Stage E swaps the stub for the real `agent:exec` +
- * sift gate against `@auriclabs/roles`.
+ * Strongly-typed `before_tool_call` hook signature used by the live
+ * `agent:exec` + sift gate against `@auriclabs/roles`.
  */
 type BeforeToolCallHook = (event: ToolCallEvent, ctx: ToolCallContext) => Promise<ToolCallHookResult>;
 /**
  * Build the gate context object used by sift evaluation. This is the
  * round-6 "strict namespacing" shape — `args` is a top-level field, not
- * spread, so an attacker-controlled `tool` field inside `toolArgs` cannot
+ * spread, so an attacker-controlled `tool` field inside `params` cannot
  * override the gate's `tool` value.
  *
  * Stage E's gate calls:

package/dist/index.js

@@ -3,7 +3,7 @@ import { t as plugin } from "./plugin2.js";
 /**
 * Build the gate context object used by sift evaluation. This is the
 * round-6 "strict namespacing" shape — `args` is a top-level field, not
-* spread, so an attacker-controlled `tool` field inside `toolArgs` cannot
+* spread, so an attacker-controlled `tool` field inside `params` cannot
 * override the gate's `tool` value.
 *
 * Stage E's gate calls:
@@ -15,7 +15,7 @@ import { t as plugin } from "./plugin2.js";
 function buildGateContext(event) {
 	return {
 		tool: event.toolName,
-		args: event.toolArgs
+		args: event.params
 	};
 }
 //#endregion

package/dist/plugin.cjs

@@ -1,2 +1,6 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
 const require_plugin = require("./plugin2.cjs");
-module.exports = require_plugin.plugin;
+exports.default = require_plugin.plugin;

package/dist/plugin.d.cts

@@ -1,5 +1,28 @@
 import { TSchema } from "@sinclair/typebox";
 
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
 //#region src/plugin.d.ts
 
 interface PluginLogger {
@@ -8,23 +31,10 @@ interface PluginLogger {
   error: (...args: unknown[]) => void;
   debug: (...args: unknown[]) => void;
 }
-interface ToolDef {
-  name: string;
-  description: string;
-  label: string;
-  parameters: TSchema;
-  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<{
-    content: {
-      type: "text";
-      text: string;
-    }[];
-    details: unknown;
-  }>;
-}
 interface PluginApi {
   logger: PluginLogger;
   registrationMode?: "full" | "setup-only" | "setup-runtime" | "cli-metadata";
-  registerTool: (tool: ToolDef) => void;
+  registerTool: (tool: ToolDef<TSchema>) => void;
   on: (event: string, handler: (...args: unknown[]) => Promise<unknown>, options?: {
     priority?: number;
   }) => void;
@@ -38,4 +48,4 @@ declare const plugin: {
   deactivate(api: PluginApi): void;
 };
 //#endregion
-export { plugin as default };
+export { plugin as t };

package/dist/plugin.d.ts

@@ -1,5 +1,28 @@
 import { TSchema } from "@sinclair/typebox";
 
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
 //#region src/plugin.d.ts
 
 interface PluginLogger {
@@ -8,23 +31,10 @@ interface PluginLogger {
   error: (...args: unknown[]) => void;
   debug: (...args: unknown[]) => void;
 }
-interface ToolDef {
-  name: string;
-  description: string;
-  label: string;
-  parameters: TSchema;
-  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<{
-    content: {
-      type: "text";
-      text: string;
-    }[];
-    details: unknown;
-  }>;
-}
 interface PluginApi {
   logger: PluginLogger;
   registrationMode?: "full" | "setup-only" | "setup-runtime" | "cli-metadata";
-  registerTool: (tool: ToolDef) => void;
+  registerTool: (tool: ToolDef<TSchema>) => void;
   on: (event: string, handler: (...args: unknown[]) => Promise<unknown>, options?: {
     priority?: number;
   }) => void;
@@ -38,4 +48,4 @@ declare const plugin: {
   deactivate(api: PluginApi): void;
 };
 //#endregion
-export { plugin as default };
+export { plugin as t };