@alfe.ai/openclaw-identity 0.0.10 → 0.0.12

package/dist/index.cjs

@@ -1,2 +1,27 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
 const require_plugin = require("./plugin2.cjs");
-module.exports = require_plugin.plugin;
+//#region src/runtime-contract.ts
+/**
+* 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
+* override the gate's `tool` value.
+*
+* Stage E's gate calls:
+*   ability.has(
+*     { subject: "agent", action: "exec", scope: `agent:${ctx.agentId}` },
+*     buildGateContext(event),
+*   );
+*/
+function buildGateContext(event) {
+	return {
+		tool: event.toolName,
+		args: event.toolArgs
+	};
+}
+//#endregion
+exports.buildGateContext = buildGateContext;
+exports.default = require_plugin.plugin;

package/dist/index.d.cts

@@ -1,2 +1,147 @@
 import plugin from "./plugin.cjs";
-export { plugin as default };
+
+//#region src/policy-cache.d.ts
+
+type IdentityFailureMode = "open" | "closed" | "permissive";
+/**
+ * Evaluate whether a tool call should be blocked based on the cached policy
+ * and failure mode.
+ */
+
+//#endregion
+//#region src/runtime-contract.d.ts
+
+/**
+ * The tool the agent is about to call.
+ *
+ * `toolName` SHOULD be namespaced (e.g., `gmail:send_email`, `calendar:create_event`)
+ * so sift `$glob: "gmail:*"` conditions work and namespace collisions are
+ * impossible. Plugins that don't yet namespace their tools will be migrated
+ * during Stage I rollout.
+ */
+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>;
+}
+/**
+ * What initiated the tool call. Three buckets:
+ *   - "user_message"  — a human (or another agent) sent a message that the
+ *                       agent is now responding to. `actingIdentityId` is the
+ *                       identity of the message sender.
+ *   - "scheduled"     — autonomous run (cron/trigger). `actingIdentityId` is
+ *                       the agent's own identity (`idn_agt_*`).
+ *   - "tool_chain"    — a follow-up tool call from a previous tool's result
+ *                       within the same agent invocation. `actingIdentityId`
+ *                       is whatever resolved at the start of the chain.
+ *   - "api"           — a tool call invoked via the agent's REST API by an
+ *                       external caller authenticated with an `alfe_*` token.
+ *                       `actingIdentityId` may be undefined; `tokenPermissions`
+ *                       carries the gate-relevant `Permission[]`.
+ */
+type ToolCallTrigger = "user_message" | "scheduled" | "tool_chain" | "api";
+/**
+ * How the caller authenticated.
+ *   - "jwt"   — Clerk JWT path (human user). `actingIdentityId` resolved from
+ *               the JWT's `sub` via the identity service.
+ *   - "agent" — autonomous agent (no external caller). `actingIdentityId` is
+ *               the agent's own `idn_agt_*`.
+ *   - "token" — `alfe_*` API token. `tokenPermissions` is set; the gate uses
+ *               the token's permissions directly without an identity lookup.
+ *   - "none"  — no auth context (fail-closed in prod via IdentityFailureMode).
+ */
+type ToolCallAuthMethod = "jwt" | "agent" | "token" | "none";
+/**
+ * Permission shape the gate consumes. This is a structural duplicate of
+ * `Permission` from `@auriclabs/roles@0.1.1` so the openclaw plugin doesn't
+ * have to depend on the library directly (the library is consumed inside the
+ * gate itself in Stage E). Keep the two shapes in lockstep.
+ */
+interface RuntimePermission {
+  readonly subject: string;
+  readonly action: string;
+  readonly scope?: string;
+  /**
+   * Round 7 storage shape: sift conditions stored per-permission. The runtime
+   * gate evaluates the condition against `{ tool, args }` (round 6 strict
+   * namespacing). Glob source travels under `$glob`; the compiled regex
+   * travels under `_glob_re` with a `_glob_v` version marker (round 7 audit
+   * 3.6 storage shape).
+   */
+  readonly conditions?: Record<string, unknown>;
+  readonly type?: "can" | "cannot";
+}
+/**
+ * Calling context for the tool call. Populated by the OpenClaw daemon at
+ * dispatch time.
+ */
+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;
+  /**
+   * The identity (`idn_*`) the agent is acting on behalf of. Resolution
+   * order:
+   *   1. If `trigger === "user_message"`: the chat-context identity (sender).
+   *   2. If `trigger === "scheduled"` or `trigger === "tool_chain"`: the
+   *      agent's own `idn_agt_*` (autonomous default).
+   *   3. If `authMethod === "token"`: optional; the token-path gate uses
+   *      `tokenPermissions` and may skip identity resolution entirely.
+   *   4. Otherwise: undefined; the per-agent `IdentityFailureMode` decides
+   *      whether to allow / deny / log-and-continue.
+   */
+  readonly actingIdentityId?: string;
+  /**
+   * Round 5 / Round 7: `alfe_*` tokens carry their own flat `Permission[]`
+   * directly. When `authMethod === "token"`, the daemon populates this with
+   * `TokenEntity.permissions` (post Stage B.0.7 atomic flip — pre-flip the
+   * authorizer derives this from `record.scopes` via `scopesToPermissions`).
+   * The Stage E gate evaluates these permissions directly at scope
+   * `agent:<agentId>` without an identity lookup.
+   */
+  readonly tokenPermissions?: readonly RuntimePermission[];
+  /** Optional: chat conversation id (when trigger is `user_message`). */
+  readonly conversationId?: string;
+  /** Optional: channel id (when trigger is `user_message`). */
+  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).
+ */
+type ToolCallHookResult = undefined | {
+  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`.
+ */
+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
+ * override the gate's `tool` value.
+ *
+ * Stage E's gate calls:
+ *   ability.has(
+ *     { subject: "agent", action: "exec", scope: `agent:${ctx.agentId}` },
+ *     buildGateContext(event),
+ *   );
+ */
+declare function buildGateContext(event: ToolCallEvent): {
+  tool: string;
+  args: Record<string, unknown>;
+};
+//#endregion
+export { type BeforeToolCallHook, type IdentityFailureMode, type RuntimePermission, type ToolCallAuthMethod, type ToolCallContext, type ToolCallEvent, type ToolCallHookResult, type ToolCallTrigger, buildGateContext, plugin as default };

package/dist/index.d.ts

@@ -1,2 +1,147 @@
 import plugin from "./plugin.js";
-export { plugin as default };
+
+//#region src/policy-cache.d.ts
+
+type IdentityFailureMode = "open" | "closed" | "permissive";
+/**
+ * Evaluate whether a tool call should be blocked based on the cached policy
+ * and failure mode.
+ */
+
+//#endregion
+//#region src/runtime-contract.d.ts
+
+/**
+ * The tool the agent is about to call.
+ *
+ * `toolName` SHOULD be namespaced (e.g., `gmail:send_email`, `calendar:create_event`)
+ * so sift `$glob: "gmail:*"` conditions work and namespace collisions are
+ * impossible. Plugins that don't yet namespace their tools will be migrated
+ * during Stage I rollout.
+ */
+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>;
+}
+/**
+ * What initiated the tool call. Three buckets:
+ *   - "user_message"  — a human (or another agent) sent a message that the
+ *                       agent is now responding to. `actingIdentityId` is the
+ *                       identity of the message sender.
+ *   - "scheduled"     — autonomous run (cron/trigger). `actingIdentityId` is
+ *                       the agent's own identity (`idn_agt_*`).
+ *   - "tool_chain"    — a follow-up tool call from a previous tool's result
+ *                       within the same agent invocation. `actingIdentityId`
+ *                       is whatever resolved at the start of the chain.
+ *   - "api"           — a tool call invoked via the agent's REST API by an
+ *                       external caller authenticated with an `alfe_*` token.
+ *                       `actingIdentityId` may be undefined; `tokenPermissions`
+ *                       carries the gate-relevant `Permission[]`.
+ */
+type ToolCallTrigger = "user_message" | "scheduled" | "tool_chain" | "api";
+/**
+ * How the caller authenticated.
+ *   - "jwt"   — Clerk JWT path (human user). `actingIdentityId` resolved from
+ *               the JWT's `sub` via the identity service.
+ *   - "agent" — autonomous agent (no external caller). `actingIdentityId` is
+ *               the agent's own `idn_agt_*`.
+ *   - "token" — `alfe_*` API token. `tokenPermissions` is set; the gate uses
+ *               the token's permissions directly without an identity lookup.
+ *   - "none"  — no auth context (fail-closed in prod via IdentityFailureMode).
+ */
+type ToolCallAuthMethod = "jwt" | "agent" | "token" | "none";
+/**
+ * Permission shape the gate consumes. This is a structural duplicate of
+ * `Permission` from `@auriclabs/roles@0.1.1` so the openclaw plugin doesn't
+ * have to depend on the library directly (the library is consumed inside the
+ * gate itself in Stage E). Keep the two shapes in lockstep.
+ */
+interface RuntimePermission {
+  readonly subject: string;
+  readonly action: string;
+  readonly scope?: string;
+  /**
+   * Round 7 storage shape: sift conditions stored per-permission. The runtime
+   * gate evaluates the condition against `{ tool, args }` (round 6 strict
+   * namespacing). Glob source travels under `$glob`; the compiled regex
+   * travels under `_glob_re` with a `_glob_v` version marker (round 7 audit
+   * 3.6 storage shape).
+   */
+  readonly conditions?: Record<string, unknown>;
+  readonly type?: "can" | "cannot";
+}
+/**
+ * Calling context for the tool call. Populated by the OpenClaw daemon at
+ * dispatch time.
+ */
+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;
+  /**
+   * The identity (`idn_*`) the agent is acting on behalf of. Resolution
+   * order:
+   *   1. If `trigger === "user_message"`: the chat-context identity (sender).
+   *   2. If `trigger === "scheduled"` or `trigger === "tool_chain"`: the
+   *      agent's own `idn_agt_*` (autonomous default).
+   *   3. If `authMethod === "token"`: optional; the token-path gate uses
+   *      `tokenPermissions` and may skip identity resolution entirely.
+   *   4. Otherwise: undefined; the per-agent `IdentityFailureMode` decides
+   *      whether to allow / deny / log-and-continue.
+   */
+  readonly actingIdentityId?: string;
+  /**
+   * Round 5 / Round 7: `alfe_*` tokens carry their own flat `Permission[]`
+   * directly. When `authMethod === "token"`, the daemon populates this with
+   * `TokenEntity.permissions` (post Stage B.0.7 atomic flip — pre-flip the
+   * authorizer derives this from `record.scopes` via `scopesToPermissions`).
+   * The Stage E gate evaluates these permissions directly at scope
+   * `agent:<agentId>` without an identity lookup.
+   */
+  readonly tokenPermissions?: readonly RuntimePermission[];
+  /** Optional: chat conversation id (when trigger is `user_message`). */
+  readonly conversationId?: string;
+  /** Optional: channel id (when trigger is `user_message`). */
+  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).
+ */
+type ToolCallHookResult = undefined | {
+  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`.
+ */
+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
+ * override the gate's `tool` value.
+ *
+ * Stage E's gate calls:
+ *   ability.has(
+ *     { subject: "agent", action: "exec", scope: `agent:${ctx.agentId}` },
+ *     buildGateContext(event),
+ *   );
+ */
+declare function buildGateContext(event: ToolCallEvent): {
+  tool: string;
+  args: Record<string, unknown>;
+};
+//#endregion
+export { type BeforeToolCallHook, type IdentityFailureMode, type RuntimePermission, type ToolCallAuthMethod, type ToolCallContext, type ToolCallEvent, type ToolCallHookResult, type ToolCallTrigger, buildGateContext, plugin as default };

package/dist/index.js

@@ -1,2 +1,22 @@
 import { t as plugin } from "./plugin2.js";
-export { plugin as default };
+//#region src/runtime-contract.ts
+/**
+* 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
+* override the gate's `tool` value.
+*
+* Stage E's gate calls:
+*   ability.has(
+*     { subject: "agent", action: "exec", scope: `agent:${ctx.agentId}` },
+*     buildGateContext(event),
+*   );
+*/
+function buildGateContext(event) {
+	return {
+		tool: event.toolName,
+		args: event.toolArgs
+	};
+}
+//#endregion
+export { buildGateContext, plugin as default };