@alfe.ai/openclaw-identity 0.1.27 → 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

@@ -11,18 +11,19 @@ import { t as 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

@@ -11,18 +11,19 @@ import { t as 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

@@ -5,16 +5,6 @@ import { TSchema } from "@sinclair/typebox";
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 //#region src/tools.d.ts
-/**
- * Tool-definition helpers — the `defineTool` / `ok` / `errResult` trio that
- * was copy-pasted across 8 plugins (identity, google, teams, mobile,
- * whatsapp, voice, chat a2a-tools, base openclaw).
- *
- * Error handling is standardized on the openclaw-google variant — the only
- * copy that survived non-`Error` throws (`e instanceof Error ? e.message :
- * "Unknown error"`). The other copies did `(e as Error).message`, which
- * crashes the tool executor when a handler throws a string/object.
- */
 /** Shape returned to OpenClaw from a tool `execute`. */
 interface ToolResult {
   content: {
@@ -22,15 +12,8 @@ interface ToolResult {
     text: string;
   }[];
   details: unknown;
+  isError?: boolean;
 }
-/**
- * An OpenClaw tool definition.
- *
- * `parameters` is generic because the fleet is split between TypeBox
- * `TSchema` schemas (identity/google/teams/mobile/whatsapp) and plain
- * JSON-Schema objects (chat a2a-tools). Instantiate with whichever schema
- * type the plugin uses — the kit itself has no schema dependency.
- */
 interface ToolDef<TParameters = unknown> {
   name: string;
   description: string;
@@ -38,7 +21,7 @@ interface ToolDef<TParameters = unknown> {
   parameters: TParameters;
   execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
 }
-/** Wrap a successful handler result in the OpenClaw tool-result envelope. */
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
 //#endregion
 //#region src/plugin.d.ts
 

package/dist/plugin.d.ts

@@ -5,16 +5,6 @@ import { TSchema } from "@sinclair/typebox";
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 //#region src/tools.d.ts
-/**
- * Tool-definition helpers — the `defineTool` / `ok` / `errResult` trio that
- * was copy-pasted across 8 plugins (identity, google, teams, mobile,
- * whatsapp, voice, chat a2a-tools, base openclaw).
- *
- * Error handling is standardized on the openclaw-google variant — the only
- * copy that survived non-`Error` throws (`e instanceof Error ? e.message :
- * "Unknown error"`). The other copies did `(e as Error).message`, which
- * crashes the tool executor when a handler throws a string/object.
- */
 /** Shape returned to OpenClaw from a tool `execute`. */
 interface ToolResult {
   content: {
@@ -22,15 +12,8 @@ interface ToolResult {
     text: string;
   }[];
   details: unknown;
+  isError?: boolean;
 }
-/**
- * An OpenClaw tool definition.
- *
- * `parameters` is generic because the fleet is split between TypeBox
- * `TSchema` schemas (identity/google/teams/mobile/whatsapp) and plain
- * JSON-Schema objects (chat a2a-tools). Instantiate with whichever schema
- * type the plugin uses — the kit itself has no schema dependency.
- */
 interface ToolDef<TParameters = unknown> {
   name: string;
   description: string;
@@ -38,7 +21,7 @@ interface ToolDef<TParameters = unknown> {
   parameters: TParameters;
   execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
 }
-/** Wrap a successful handler result in the OpenClaw tool-result envelope. */
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
 //#endregion
 //#region src/plugin.d.ts