@alfe.ai/openclaw-identity 0.0.11 → 0.0.13

package/dist/plugin2.cjs

@@ -0,0 +1,420 @@
+let _alfe_ai_config = require("@alfe.ai/config");
+let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
+let _sinclair_typebox = require("@sinclair/typebox");
+let node_module = require("node:module");
+let _auriclabs_roles = require("@auriclabs/roles");
+//#region src/agent-exec-gate.ts
+/**
+* Phase 1 Stage E — `agent:exec` gate evaluation.
+*
+* Round 6 strict-namespacing gate context (`{tool, args}`): the gate
+* passes the tool name as a sift CONTEXT field, not as the action.
+* Permissions narrow which tools an identity may exec via sift
+* conditions on the `tool` field. `args` is its own field — never
+* spread — so a tool whose args legitimately include a `tool` key
+* can't override the gate's value (closes the round-5 toolArgs.tool
+* collision).
+*
+* The function is a thin wrapper around `createAbility(...).has(...)`
+* that asserts the architecture-invariant "exactly one ability.has
+* call per gate" rule from the verify-roles-architecture script. Any
+* caller that loops over multiple scopes and OR-aggregates the result
+* silently loses `cannot` semantics — the wrapper makes the contract
+* explicit and testable.
+*
+* Today this function is wired into `before_tool_call` only for the
+* TOKEN path (B.0.7 atomic flip carries the token's `Permission[]` in
+* `ctx.tokenPermissions`). The JWT path still falls back to permissive
+* because the agent runtime can't yet fetch the resolved permission
+* set for `ctx.actingIdentityId` (needs an AgentApiClient endpoint
+* that doesn't exist yet — landing alongside Stage D's full rollout).
+*/
+/**
+* Evaluate the round-6 strict-namespacing gate. Single
+* `ability.has({...}, {tool, args})` call per invocation — never
+* fan out across multiple permission shapes.
+*
+* `permissions` is whatever the caller already has on hand (a token's
+* `Permission[]`, a session-cached resolved set, etc.). The function
+* doesn't fetch, doesn't cache, doesn't memoize — those concerns live
+* one layer up.
+*/
+function evaluateAgentExec(permissions, args) {
+	if (!args.agentId) return { allowed: false };
+	const ability = (0, _auriclabs_roles.createAbility)(permissions);
+	const gatePermission = {
+		subject: "agent",
+		action: "exec",
+		scope: `agent:${args.agentId}`
+	};
+	return { allowed: ability.has(gatePermission, {
+		tool: args.toolName,
+		args: args.toolArgs
+	}) };
+}
+/**
+* Translate the gate decision into the before_tool_call hook's return
+* shape. `undefined` means "no opinion — allow"; `{ block: true, ... }`
+* means deny.
+*
+* - `allowed === true` → undefined (allow regardless of mode).
+* - `allowed === false` + mode === "fail-closed" → block.
+* - `allowed === false` + mode === "fail-open" → undefined (warn-only;
+*   caller should log the would-deny but let it through). Returning
+*   undefined here is what makes the rollout safe — Stage H flips the
+*   env to fail-closed once the deny-rate metric stabilizes.
+*/
+function applyGateMode(decision, mode, toolName) {
+	if (decision.allowed) return void 0;
+	if (mode === "fail-open") return void 0;
+	return {
+		block: true,
+		blockReason: `Permissions: tool '${toolName}' not allowed for this identity`
+	};
+}
+/**
+* Resolve the kill-switch from process.env. Defaults to "fail-closed"
+* in production and "fail-open" elsewhere — Stage H flips production
+* to fail-closed once metrics confirm a stable deny rate.
+*/
+function resolveToolGatingMode() {
+	const raw = process.env.OPENCLAW_TOOL_GATING;
+	if (raw === "fail-open" || raw === "fail-closed") return raw;
+	return "fail-open";
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* @alfe.ai/openclaw-identity — OpenClaw native plugin
+*
+* HTTP-based identity resolution + AccessConfig 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).
+*   - 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).
+*
+* `after_tool_call` is intentionally absent — tool-call audit lives in a
+* future dedicated audit service, not in identity.
+*/
+const pkg = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
+const RESOLVE_CACHE_TTL_MS = 6e4;
+const resolveCache = /* @__PURE__ */ new Map();
+function getCachedResolve(key) {
+	const entry = resolveCache.get(key);
+	if (!entry) return null;
+	if (Date.now() > entry.expiresAt) {
+		resolveCache.delete(key);
+		return null;
+	}
+	return entry;
+}
+function setCachedResolve(key, value) {
+	resolveCache.set(key, {
+		...value,
+		expiresAt: Date.now() + RESOLVE_CACHE_TTL_MS
+	});
+}
+function ok(data) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data)
+		}],
+		details: data
+	};
+}
+function errResult(message) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({ error: message })
+		}],
+		details: { error: message }
+	};
+}
+function defineTool(def) {
+	return {
+		name: def.name,
+		description: def.description,
+		label: def.name,
+		parameters: def.parameters,
+		execute: async (_toolCallId, params) => {
+			try {
+				return ok(await def.handler(params));
+			} catch (e) {
+				return errResult(e.message);
+			}
+		}
+	};
+}
+const plugin = {
+	id: "@alfe.ai/openclaw-identity",
+	name: "Alfe Identity",
+	description: "Identity resolution and access gating for inbound messages",
+	version: pkg.version,
+	activate(api) {
+		const log = api.logger;
+		log.info("Alfe Identity plugin activating...");
+		let client;
+		try {
+			const config = (0, _alfe_ai_config.resolveConfig)();
+			client = new _alfe_ai_agent_api_client.AgentApiClient({
+				apiKey: config.apiKey,
+				apiUrl: config.apiUrl
+			});
+		} catch (err) {
+			log.error(`Identity plugin: failed to resolve config — ${err instanceof Error ? err.message : String(err)}`);
+			return;
+		}
+		const tools = [
+			defineTool({
+				name: "who_is_this",
+				description: "Look up an identity by provider + platformId — returns full identity context (profile, contacts, platforms, notes, tags, recent changelog). Returns `{found:false}` for unknown senders. This tool DOES NOT create new identities.",
+				parameters: _sinclair_typebox.Type.Object({
+					provider: _sinclair_typebox.Type.String({ description: "Provider name (discord, slack, chat, google-chat, clerk, etc.)" }),
+					platformId: _sinclair_typebox.Type.String({ description: "Provider-specific user identifier" })
+				}),
+				handler: async (params) => {
+					const result = await client.resolveIdentity({
+						provider: params.provider,
+						platformId: params.platformId
+					});
+					if (!result.identityId) return { found: false };
+					return client.getIdentityContext(result.identityId);
+				}
+			}),
+			defineTool({
+				name: "lookup_identity",
+				description: "Search identities by name. Returns multiple matches.",
+				parameters: _sinclair_typebox.Type.Object({
+					query: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Text search query" })),
+					status: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String())
+				}),
+				handler: (params) => client.searchIdentities({
+					q: params.query,
+					status: params.status
+				})
+			}),
+			defineTool({
+				name: "merge_identities",
+				description: "Merge two identity records — transfers contacts, platforms, notes, tags, aliases to the survivor. Hard-move, transactional.",
+				parameters: _sinclair_typebox.Type.Object({
+					survivorId: _sinclair_typebox.Type.String({ description: "Identity to keep" }),
+					mergedId: _sinclair_typebox.Type.String({ description: "Identity to merge into survivor" })
+				}),
+				handler: (params) => client.mergeIdentities(params.survivorId, {
+					mergedId: params.mergedId,
+					changedBy: {
+						type: "agent",
+						id: "plugin"
+					}
+				})
+			}),
+			defineTool({
+				name: "unmerge_identities",
+				description: "Reverse a merge — restore previously merged identity.",
+				parameters: _sinclair_typebox.Type.Object({ mergedId: _sinclair_typebox.Type.String({ description: "Identity that was merged (has mergedInto pointer)" }) }),
+				handler: (params) => client.unmergeIdentity(params.mergedId, { changedBy: {
+					type: "agent",
+					id: "plugin"
+				} })
+			}),
+			defineTool({
+				name: "add_identity_note",
+				description: "Add an observation or note about an identity. Use category 'context' for unverified affiliation claims (self-reported title/company) — those do NOT belong on the identity row directly.",
+				parameters: _sinclair_typebox.Type.Object({
+					identityId: _sinclair_typebox.Type.String(),
+					content: _sinclair_typebox.Type.String(),
+					category: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "observation, preference, relationship, context, or warning" }))
+				}),
+				handler: (params) => client.addIdentityNote(params.identityId, {
+					content: params.content,
+					category: params.category,
+					changedBy: {
+						type: "agent",
+						id: "plugin"
+					}
+				})
+			}),
+			defineTool({
+				name: "tag_identity",
+				description: "Add or remove a tag on an identity.",
+				parameters: _sinclair_typebox.Type.Object({
+					identityId: _sinclair_typebox.Type.String(),
+					tag: _sinclair_typebox.Type.String(),
+					action: _sinclair_typebox.Type.String({ description: "'add' or 'remove'" })
+				}),
+				handler: (params) => client.tagIdentity(params.identityId, {
+					tag: params.tag,
+					action: params.action,
+					changedBy: {
+						type: "agent",
+						id: "plugin"
+					}
+				})
+			}),
+			defineTool({
+				name: "get_identity_changelog",
+				description: "Get the changelog for an identity — versions, diffs, who changed what.",
+				parameters: _sinclair_typebox.Type.Object({
+					identityId: _sinclair_typebox.Type.String(),
+					limit: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.Number())
+				}),
+				handler: (params) => client.getIdentityChangelog(params.identityId, { limit: params.limit })
+			}),
+			defineTool({
+				name: "rollback_identity",
+				description: "Revert an identity to a previous version.",
+				parameters: _sinclair_typebox.Type.Object({
+					identityId: _sinclair_typebox.Type.String(),
+					targetVersion: _sinclair_typebox.Type.Number()
+				}),
+				handler: (params) => client.rollbackIdentity(params.identityId, {
+					targetVersion: params.targetVersion,
+					changedBy: {
+						type: "agent",
+						id: "plugin"
+					}
+				})
+			}),
+			defineTool({
+				name: "update_identity",
+				description: "Update display-shape fields on an identity: name / avatarUrl / timezone / locale. Contact mutations go through the verify flow — this tool will NOT accept email or mobile. Title and company live on org membership rows, not here.",
+				parameters: _sinclair_typebox.Type.Object({
+					identityId: _sinclair_typebox.Type.String(),
+					name: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String()),
+					avatarUrl: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String()),
+					timezone: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String()),
+					locale: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String())
+				}),
+				handler: (params) => {
+					const { identityId, ...rest } = params;
+					return client.updateIdentity(identityId, rest);
+				}
+			}),
+			defineTool({
+				name: "request_identity_verification",
+				description: "Send a verification phrase to verify the user controls an email or mobile endpoint. Use this when the user has just told you their email or mobile number and you want them to confirm it. Pass exactly one of `contactEmail` or `contactMobile`. The person must relay the phrase back via `confirm_identity_verification`.",
+				parameters: _sinclair_typebox.Type.Object({
+					claimedIdentityId: _sinclair_typebox.Type.String({ description: "Identity being claimed" }),
+					requestingIdentityId: _sinclair_typebox.Type.String({ description: "Identity of the person making the claim" }),
+					requestingProvider: _sinclair_typebox.Type.String({ description: "Provider the requester is on (discord, slack, chat, etc.)" }),
+					requestingPlatformId: _sinclair_typebox.Type.String({ description: "Requester's provider-specific user ID" }),
+					contactEmail: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Email to verify (mutually exclusive with contactMobile)" })),
+					contactMobile: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "E.164 mobile to verify (mutually exclusive with contactEmail)" })),
+					preferredChannel: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "When neither contactEmail nor contactMobile is provided, pick which existing verified contact to deliver to: 'mobile' or 'email'" }))
+				}),
+				handler: (params) => {
+					const contactEmail = params.contactEmail;
+					const contactMobile = params.contactMobile;
+					if (contactEmail && contactMobile) return Promise.resolve({ error: "Specify exactly one of contactEmail or contactMobile, not both" });
+					const contact = contactEmail ? {
+						channel: "email",
+						value: contactEmail
+					} : contactMobile ? {
+						channel: "mobile",
+						value: contactMobile
+					} : void 0;
+					return client.requestIdentityVerification({
+						claimedIdentityId: params.claimedIdentityId,
+						requestingIdentityId: params.requestingIdentityId,
+						requestingProvider: params.requestingProvider,
+						requestingPlatformId: params.requestingPlatformId,
+						preferredChannel: params.preferredChannel,
+						contact
+					});
+				}
+			}),
+			defineTool({
+				name: "confirm_identity_verification",
+				description: "Confirm a verification by submitting the phrase the user received. Returns `{ verified, identityId, action }` where `action` is 'merged' (the verified contact already lived on another identity, which is now the survivor) or 'contact_verified' (the contact was attached to the claimed identity).",
+				parameters: _sinclair_typebox.Type.Object({
+					claimedIdentityId: _sinclair_typebox.Type.String({ description: "Identity being claimed (matches request)" }),
+					verificationId: _sinclair_typebox.Type.String({ description: "Verification ID returned from request_identity_verification" }),
+					phrase: _sinclair_typebox.Type.String({ description: "Three-word phrase the person received via mobile or email" })
+				}),
+				handler: (params) => client.confirmIdentityVerification({
+					claimedIdentityId: params.claimedIdentityId,
+					verificationId: params.verificationId,
+					phrase: params.phrase
+				})
+			})
+		];
+		for (const tool of tools) api.registerTool(tool);
+		log.info(`Registered ${String(tools.length)} identity tools`);
+		api.on("message_received", async (...args) => {
+			const event = args[0];
+			const ctx = args[1];
+			const provider = ctx.channelId ?? "unknown";
+			const senderId = event.metadata?.UserId ?? event.from;
+			if (!senderId) return;
+			const cacheKey = ctx.conversationId ?? `${provider}:${senderId}`;
+			const cached = getCachedResolve(cacheKey);
+			if (cached) {
+				if (cached.identityId == null) return {
+					block: true,
+					blockReason: "Identity: identity not provisioned for this channel"
+				};
+				if (!cached.accessAllowed) return {
+					block: true,
+					blockReason: "Identity: access denied for this sender"
+				};
+				return;
+			}
+			try {
+				const r = await client.resolveIdentity({
+					provider,
+					platformId: senderId
+				});
+				setCachedResolve(cacheKey, {
+					identityId: r.identityId,
+					accessAllowed: r.accessAllowed,
+					status: r.status
+				});
+				if (r.identityId == null) {
+					log.warn(`Identity not provisioned for ${provider}:${senderId} — blocking inbound message`);
+					return {
+						block: true,
+						blockReason: "Identity: identity not provisioned for this channel"
+					};
+				}
+				if (!r.accessAllowed) return {
+					block: true,
+					blockReason: "Identity: access denied for this sender"
+				};
+				log.info(`Identity resolved: ${senderId} → ${r.identityId} (${r.status})`);
+			} catch (e) {
+				log.error(`Identity resolution failed for ${senderId}: ${e.message}`);
+				return {
+					block: true,
+					blockReason: "Identity: identity service unavailable — access denied (fail-closed)"
+				};
+			}
+		}, { priority: 100 });
+		const beforeToolCallStub = (event, ctx) => {
+			if (ctx.authMethod === "token" && ctx.tokenPermissions !== void 0) {
+				const blocked = applyGateMode(evaluateAgentExec(ctx.tokenPermissions, {
+					agentId: ctx.agentId,
+					toolName: event.toolName,
+					toolArgs: event.toolArgs
+				}), resolveToolGatingMode(), event.toolName);
+				return Promise.resolve(blocked);
+			}
+			return Promise.resolve(void 0);
+		};
+		api.on("before_tool_call", (...args) => beforeToolCallStub(args[0], args[1]), { priority: 100 });
+		log.info("Alfe Identity plugin activated");
+	}
+};
+//#endregion
+Object.defineProperty(exports, "plugin", {
+	enumerable: true,
+	get: function() {
+		return plugin;
+	}
+});