zigmini 1.0.0-beta.2 → 1.1.0-beta.1

package/src/agent/managed-call.ts

@@ -0,0 +1,144 @@
+import { createHash, createHmac, timingSafeEqual, type KeyObject } from "node:crypto";
+
+/** Authenticated call identity, not a file grant, owner credential or action authority. */
+export interface ManagedCallIdentity {
+	readonly role: "main" | "agent";
+	readonly agentId: string | null;
+	readonly convId: string;
+	readonly convEpoch: number;
+	readonly lifecycleEpoch: number;
+	readonly sessionPath: string;
+	readonly durableSessionId: string;
+	readonly sessionIncarnation: string;
+	readonly gatewayGeneration: string;
+	readonly inputId: string;
+	readonly toolCallId: string;
+	readonly logicalCallId: string;
+	readonly activationId: string | null;
+}
+
+export interface ManagedCallRequest {
+	readonly method: string;
+	/** Exact origin-form request target, including the query string. */
+	readonly route: string;
+	readonly operation: string;
+	/** Exact transmitted bytes, not a reparsed JSON object. */
+	readonly body: Uint8Array;
+}
+
+export interface ManagedCallProof {
+	readonly version: 1;
+	readonly identity: ManagedCallIdentity;
+	readonly nonce: string;
+	readonly bodySha256: string;
+	readonly mac: string;
+}
+
+export interface ManagedCallBinding {
+	readonly identity: ManagedCallIdentity;
+	/** Provisioned only through the gateway-controlled native bind/handshake. */
+	readonly secret: KeyObject;
+	/** Atomic, synchronous claim. Retain claims until this native binding is retired. */
+	claimNonce(nonce: string): boolean;
+}
+
+/**
+ * Resolve a CURRENT Hub/native binding and its stored logical-call mapping.
+ * The argument is an untrusted selector, never a binding to copy back.
+ * Returning null rejects retired/foreign instances or an unproven post-rotation mapping.
+ * Resolve and claim must not yield; retirement must serialize on the same owner.
+ */
+export type ManagedCallBindingResolver = (identity: ManagedCallIdentity) => ManagedCallBinding | null;
+
+const verified = Symbol("VerifiedManagedCall");
+export interface VerifiedManagedCall extends ManagedCallIdentity, ManagedCallRequest {
+	readonly [verified]: true;
+	readonly nonce: string;
+	readonly bodySha256: string;
+}
+
+export class ManagedCallError extends Error {
+	constructor(readonly code: "invalid_proof" | "binding_mismatch" | "invalid_mac" | "nonce_reused" | "native_context_mismatch") {
+		super(code);
+		this.name = "ManagedCallError";
+	}
+}
+
+const IDENTITY_KEYS = [
+	"role", "agentId", "convId", "convEpoch", "lifecycleEpoch", "sessionPath", "durableSessionId",
+	"sessionIncarnation", "gatewayGeneration", "inputId", "toolCallId", "logicalCallId", "activationId",
+] as const;
+const HEX256 = /^[a-f0-9]{64}$/;
+const record = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const epoch = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+/** Parse once at the wire boundary; retain no caller-owned identity object. */
+export function parseManagedCallIdentity(value: unknown): ManagedCallIdentity {
+	if (!record(value) || Object.keys(value).length !== IDENTITY_KEYS.length ||
+		!IDENTITY_KEYS.every(key => Object.hasOwn(value, key))) throw new ManagedCallError("invalid_proof");
+	const { role, agentId, convId, convEpoch, lifecycleEpoch, sessionPath, durableSessionId,
+		sessionIncarnation, gatewayGeneration, inputId, toolCallId, logicalCallId, activationId } = value;
+	if (!(agentId === null || text(agentId))) throw new ManagedCallError("invalid_proof");
+	switch (role) {
+		case "main": if (agentId !== null) throw new ManagedCallError("invalid_proof"); break;
+		case "agent": if (agentId === null) throw new ManagedCallError("invalid_proof"); break;
+		default: throw new ManagedCallError("invalid_proof");
+	}
+	if (!text(convId) || !epoch(convEpoch) || !epoch(lifecycleEpoch) || !text(sessionPath) ||
+		!text(durableSessionId) || !text(sessionIncarnation) || !text(gatewayGeneration) ||
+		!text(inputId) || !text(toolCallId) || !text(logicalCallId) ||
+		!(activationId === null || text(activationId))) throw new ManagedCallError("invalid_proof");
+	return Object.freeze({ role, agentId, convId, convEpoch, lifecycleEpoch, sessionPath, durableSessionId,
+		sessionIncarnation, gatewayGeneration, inputId, toolCallId, logicalCallId, activationId });
+}
+
+export function sameManagedCallIdentity(left: ManagedCallIdentity, right: ManagedCallIdentity): boolean {
+	return IDENTITY_KEYS.every(key => left[key] === right[key]);
+}
+
+export function managedCallBodyDigest(body: Uint8Array): string {
+	return createHash("sha256").update(body).digest("hex");
+}
+
+/** One canonical signing implementation, shared by bridge and gateway. */
+export function managedCallSignature(
+	binding: Pick<ManagedCallBinding, "identity" | "secret">,
+	request: ManagedCallRequest,
+	content: Pick<ManagedCallProof, "nonce" | "bodySha256">,
+): string {
+	if (!/^[A-Z]+$/.test(request.method) || !request.route.startsWith("/") || request.route.startsWith("//") ||
+		/[\r\n#]/.test(request.route) || !text(request.operation) ||
+		!HEX256.test(content.nonce) || !HEX256.test(content.bodySha256)) throw new ManagedCallError("invalid_proof");
+	if (binding.secret.type !== "secret" || binding.secret.symmetricKeySize !== 32) throw new ManagedCallError("invalid_proof");
+	const message = JSON.stringify(["zigmini.managed-call", 1, IDENTITY_KEYS.map(key => binding.identity[key]),
+		request.method, request.route, request.operation, content.bodySha256, content.nonce]);
+	return createHmac("sha256", binding.secret).update(message).digest("hex");
+}
+
+/**
+ * Synchronous authentication and one-use claim. The result is a snapshot only:
+ * consumers still recheck binding/revisions at their final commit/content release.
+ */
+export function verifyManagedCall(
+	request: ManagedCallRequest & { readonly proof: unknown },
+	bindingResolver: ManagedCallBindingResolver,
+): VerifiedManagedCall {
+	const proof = request.proof;
+	if (!record(proof) || Object.keys(proof).length !== 5 || proof.version !== 1 ||
+		typeof proof.nonce !== "string" || !HEX256.test(proof.nonce) ||
+		typeof proof.bodySha256 !== "string" || !HEX256.test(proof.bodySha256) ||
+		typeof proof.mac !== "string" || !HEX256.test(proof.mac)) throw new ManagedCallError("invalid_proof");
+	const identity = parseManagedCallIdentity(proof.identity);
+	const binding = bindingResolver(identity);
+	if (binding === null || !sameManagedCallIdentity(identity, binding.identity)) throw new ManagedCallError("binding_mismatch");
+	const bodySha256 = managedCallBodyDigest(request.body);
+	if (bodySha256 !== proof.bodySha256) throw new ManagedCallError("invalid_mac");
+	const content = { nonce: proof.nonce, bodySha256 };
+	const mac = managedCallSignature(binding, request, content);
+	if (!timingSafeEqual(Buffer.from(mac, "hex"), Buffer.from(proof.mac, "hex"))) throw new ManagedCallError("invalid_mac");
+	if (!binding.claimNonce(proof.nonce)) throw new ManagedCallError("nonce_reused");
+	return Object.freeze({ ...identity, method: request.method, route: request.route, operation: request.operation,
+		body: Uint8Array.from(request.body), nonce: proof.nonce, bodySha256, [verified]: true as const });
+}

package/src/agent/tool-catalog.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import type {
+	AgentAccessView, AuthorizationOutcome, GrantReconcile, RegisteredToolMeta, RestrictionAdapter, ToolAvailability,
+	ToolDescriptor, ToolEffect, ToolGrant, ToolKind, ToolSourceKind,
+} from "./tool-permission-types.ts";
+
+interface CatalogEntry {
+	readonly exposedName: string;
+	readonly sourceKind: ToolSourceKind;
+	readonly ownerId: string;
+	readonly originalName: string;
+	readonly kind: ToolKind;
+	readonly effect: ToolEffect;
+	readonly operations: readonly string[];
+	readonly restrictionAdapter: RestrictionAdapter;
+	readonly availability: ToolAvailability;
+	readonly bootstrap: boolean;
+	readonly grantable: boolean;
+	readonly roleOnly: "work" | null;
+}
+
+type Row = [names: readonly string[], kind: ToolKind, effect: ToolEffect, operations: readonly string[], adapter: RestrictionAdapter];
+
+const ENGINE_ROWS: readonly Row[] = [
+	[["read", "grep", "find", "glob", "ls"], "file_read", "read", ["read", "list"], "path_scope"],
+	[["edit", "write", "apply_patch"], "file_write", "local_write", ["write"], "path_scope"],
+	[["bash", "powershell", "eval", "monitor"], "exec", "execution", ["execute"], "restricted_exec"],
+	[["bash_output", "bash_input", "bash_resize", "kill_bash"], "exec_control", "control", ["control_owned"], "owned_exec_handle"],
+	[["web_search", "$web_search"], "web", "read", ["search"], "web_origin"],
+	[["webfetch"], "web", "read", ["fetch"], "web_origin"],
+	[["generate_image"], "media", "external_write", ["generate"], "media_io"],
+	[["read_video", "look_at"], "media", "read", ["inspect"], "media_io"],
+	[["show_html_page"], "display", "read", ["display"], "display_surface"],
+	[["lsp_diagnostics", "lsp_goto_definition", "lsp_find_references", "lsp_symbols", "lsp_prepare_rename"], "lsp", "read", ["read"], "path_scope"],
+	[["lsp_rename"], "lsp", "local_write", ["write"], "path_scope"],
+	[["computer", "omo_browser_bridge", "omo_desktop_toolkit"], "browser", "control", ["observe", "act"], "browser_target"],
+	[["task", "task_send", "task_cancel", "task_output", "workflow", "workpool", "team_create", "team_delete", "task_create", "task_get", "task_list", "task_update"],
+		"subtask", "control", ["control_owned"], "owned_child"],
+	[["thread_create", "thread_list", "thread_read", "thread_send", "thread_interrupt", "thread_handoff", "thread_rename", "thread_set_model",
+		"thread_set_reasoning", "thread_bind", "thread_unbind", "thread_rebind", "thread_bindings", "thread_report", "thread_outbox", "thread_outbox_ack", "thread_answer"],
+		"session", "control", ["control_owned"], "owned_session"],
+	[["todo", "create_goal", "update_goal", "get_goal", "schedule_wakeup", "schedule_prompt"], "self_state", "control", ["self"], "self_state"],
+	[["onboarding_session_history", "onboarding_understand"], "memory", "read", ["read_self"], "self_identity"],
+	[["onboarding_memory_apply", "memory"], "memory", "local_write", ["write_self"], "self_identity"],
+	[["list_relocation_targets", "relocate_session"], "relocation", "control", ["relocate"], "relocation_target"],
+	[["request_user_input"], "communication", "control", ["ask"], "metadata_only"],
+	[["tool_search"], "discovery", "read", ["search_metadata"], "metadata_only"],
+	[["mcp_list_resources", "mcp_read_resource"], "mcp_resource", "read", ["read"], "mcp_resource"],
+];
+
+const entry = (exposedName: string, sourceKind: ToolSourceKind, ownerId: string, originalName: string, kind: ToolKind, effect: ToolEffect,
+	operations: readonly string[], restrictionAdapter: RestrictionAdapter, availability: ToolAvailability,
+	extra: Partial<Pick<CatalogEntry, "bootstrap" | "grantable" | "roleOnly">> = {}): CatalogEntry =>
+	({ exposedName, sourceKind, ownerId, originalName, kind, effect, operations, restrictionAdapter, availability, bootstrap: false, grantable: true, roleOnly: null, ...extra });
+
+const mcpEntry = (exposedName: string, server: string, tool: string, kind: ToolKind, effect: ToolEffect, operations: readonly string[], adapter: RestrictionAdapter) =>
+	entry(exposedName, "mcp", server, tool, kind, effect, operations, adapter, "mcp_dynamic");
+
+const gateway = (name: string, kind: ToolKind, effect: ToolEffect, operations: readonly string[], adapter: RestrictionAdapter, availability: ToolAvailability,
+	extra: Partial<Pick<CatalogEntry, "bootstrap" | "grantable" | "roleOnly">> = {}) =>
+	entry(name, "gateway", "gateway", name, kind, effect, operations, adapter, availability, extra);
+
+/** Every classified tool. Anything not found here by (sourceKind, ownerId, originalName) is opaque and default-deny. */
+export const CATALOG: readonly CatalogEntry[] = [
+	...ENGINE_ROWS.flatMap(([names, kind, effect, operations, adapter]) =>
+		names.map((name) => entry(name, "builtin", "engine", name, kind, effect, operations, adapter, "registered"))),
+	entry("ask_user_question", "builtin", "engine", "ask_user_question", "communication", "control", ["ask"], "metadata_only", "registered", { bootstrap: true }),
+	entry("web_search_exa", "builtin", "engine", "web_search_exa", "web", "read", ["search"], "not_grantable", "internal_provider", { grantable: false }),
+	entry("mcp", "builtin", "engine", "mcp", "mcp_proxy", "control", ["invoke"], "mcp_proxy", "registered", { grantable: false }),
+	mcpEntry("mcp_context7_query-docs", "context7", "query-docs", "mcp_docs", "read", ["query"], "web_origin"),
+	mcpEntry("mcp_context7_resolve-library-id", "context7", "resolve-library-id", "mcp_docs", "read", ["query"], "web_origin"),
+	mcpEntry("mcp_grep_app_searchGitHub", "grep_app", "searchGitHub", "mcp_docs", "read", ["query"], "web_origin"),
+	mcpEntry("mcp__ast_grep_scan", "ast_grep", "scan", "mcp_ast", "read", ["read"], "path_scope"),
+	mcpEntry("mcp__ast_grep_search", "ast_grep", "search", "mcp_ast", "read", ["read"], "path_scope"),
+	mcpEntry("mcp__ast_grep_rewrite", "ast_grep", "rewrite", "mcp_ast", "local_write", ["write"], "path_scope"),
+	gateway("zgw_work_report", "work_role", "control", ["report"], "role_only", "gateway_work", { roleOnly: "work" }),
+	gateway("zgw_agent_history_search", "agent_history", "read", ["search"], "own_history", "gateway_agent"),
+	gateway("zgw_attachment_read", "attachment", "read", ["read"], "attachment_selection", "gateway_agent"),
+	// 294 C7: the narrow Aside browser tool of a registered agent (host/omo-bridge/agent-control.ts registers it).
+	gateway("zgw_aside", "browser", "control", ["read", "view", "open_owned", "navigate", "click", "fill", "close"], "browser_target", "gateway_agent"),
+	gateway("zgw_tool_catalog", "bootstrap", "control", ["list_metadata"], "metadata_only", "planned", { bootstrap: true }),
+	gateway("zgw_tool_request", "bootstrap", "control", ["request"], "metadata_only", "planned", { bootstrap: true }),
+	gateway("zgw_tool_status", "bootstrap", "control", ["status_self"], "metadata_only", "planned", { bootstrap: true }),
+];
+
+const identity = (sourceKind: string, ownerId: string, originalName: string) => JSON.stringify([sourceKind, ownerId, originalName]);
+const BY_IDENTITY = new Map(CATALOG.map((row) => [identity(row.sourceKind, row.ownerId, row.originalName), row]));
+
+function canonical(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value && typeof value === "object")
+		return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical((value as Record<string, unknown>)[key])]));
+	return value;
+}
+
+/** sha256 over source, owner, original name and parameter schema. The exposed name is display only and excluded. */
+export function registrationDigest(meta: RegisteredToolMeta): string {
+	const body = JSON.stringify(canonical({ sourceKind: meta.sourceKind, ownerId: meta.ownerId, originalName: meta.originalName, parameters: meta.parameters ?? null }));
+	return createHash("sha256").update(body).digest("hex");
+}
+
+export function describeTool(meta: RegisteredToolMeta): ToolDescriptor {
+	const digest = registrationDigest(meta);
+	const key = { sourceKind: meta.sourceKind, ownerId: meta.ownerId, originalName: meta.originalName, registrationDigest: digest };
+	const known = BY_IDENTITY.get(identity(meta.sourceKind, meta.ownerId, meta.originalName));
+	if (!known) {
+		return { key, exposedName: meta.name, kind: "unclassified", effect: "external_write", operations: ["invoke_exact"], scopeSchema: "exact_args",
+			availability: "unknown", restrictionAdapter: "exact_args", registrationDigest: digest, opaque: true, bootstrap: false, grantable: true, roleOnly: null };
+	}
+	return { key, exposedName: meta.name, kind: known.kind, effect: known.effect, operations: known.operations, scopeSchema: known.restrictionAdapter,
+		availability: known.availability, restrictionAdapter: known.restrictionAdapter, registrationDigest: digest, opaque: false,
+		bootstrap: known.bootstrap, grantable: known.grantable, roleOnly: known.roleOnly };
+}
+
+const sameTool = (grant: ToolGrant, descriptor: ToolDescriptor) =>
+	grant.toolKey.sourceKind === descriptor.key.sourceKind && grant.toolKey.ownerId === descriptor.key.ownerId
+	&& grant.toolKey.originalName === descriptor.key.originalName;
+
+/** A grant stays active only for the same registration; a changed schema or source suspends it as tool_changed. */
+export function reconcileGrant(grant: ToolGrant, descriptor: ToolDescriptor): GrantReconcile {
+	if (!sameTool(grant, descriptor)) return { state: "unrelated" };
+	if (grant.toolKey.registrationDigest !== descriptor.registrationDigest) return { state: "suspended", reason: "tool_changed" };
+	return { state: "active" };
+}
+
+/** zgw_aside input operation -> catalog operation (C7). A grant names catalog operations. */
+export const ASIDE_OPERATIONS: Readonly<Record<string, string>> = {
+	read: "read", screenshot: "view", open_owned: "open_owned", navigate_owned: "navigate", click: "click", fill: "fill", close_owned: "close",
+};
+
+/**
+ * The request identity of a call the engine held: the catalog source and owner by exposed name (an unlisted tool stays
+ * opaque under its own source) and the catalog operation the call needs. MCP names are never resolved by exposed name.
+ */
+export function heldToolRequest(tool: { readonly name: string; readonly parameters: unknown; readonly sourceKind?: ToolSourceKind }, args: unknown):
+	{ readonly toolKey: ToolDescriptor["key"]; readonly operation: string } {
+	const known = CATALOG.find((row) => row.exposedName === tool.name && row.sourceKind !== "mcp");
+	const descriptor = describeTool({ name: tool.name, sourceKind: known?.sourceKind ?? tool.sourceKind ?? "extension", ownerId: known?.ownerId ?? "unknown",
+		originalName: tool.name, parameters: tool.parameters });
+	const asked = tool.name === "zgw_aside" && args !== null && typeof args === "object" ? (args as { operation?: unknown }).operation : undefined;
+	const operation = typeof asked === "string" && Object.hasOwn(ASIDE_OPERATIONS, asked) ? ASIDE_OPERATIONS[asked]! : descriptor.operations[0]!;
+	return { toolKey: descriptor.key, operation };
+}
+
+export interface AuthorizeInput {
+	readonly descriptor: ToolDescriptor;
+	readonly grant: ToolGrant | null;
+	readonly access: AgentAccessView;
+	readonly operation: string;
+	readonly role: "agent" | "work";
+}
+
+export function authorizeTool(input: AuthorizeInput): AuthorizationOutcome {
+	const { descriptor, grant, access, operation } = input;
+	if (access.accessState !== "open") return { decision: "deny", reason: "agent_access_blocked" };
+	if (!descriptor.grantable) return { decision: "deny", reason: "not_grantable" };
+	if (descriptor.roleOnly !== null && descriptor.roleOnly !== input.role) return { decision: "deny", reason: "role_only" };
+	if (!descriptor.operations.includes(operation)) return { decision: "deny", reason: "unknown_operation" };
+	if (descriptor.bootstrap) return { decision: "allow" };
+	if (grant === null) return { decision: "deny", reason: "no_grant" };
+	if (grant.agentId !== access.agentId) return { decision: "deny", reason: "grant_agent_mismatch" };
+	if (grant.incarnation !== access.lifecycleEpoch) return { decision: "deny", reason: "lifecycle_epoch_mismatch" };
+	if (grant.authorityEpoch !== access.authorityEpoch) return { decision: "deny", reason: "authority_epoch_mismatch" };
+	if (grant.state !== "active") return { decision: "deny", reason: "grant_not_active" };
+	const reconcile = reconcileGrant(grant, descriptor);
+	if (reconcile.state === "unrelated") return { decision: "deny", reason: "grant_tool_mismatch" };
+	if (reconcile.state === "suspended") return { decision: "hold", reason: "tool_changed" };
+	if (!grant.operations.includes(operation)) return { decision: "deny", reason: "operation_not_granted" };
+	return { decision: "allow" };
+}
+
+export interface CallInput extends Omit<AuthorizeInput, "descriptor"> {
+	readonly tool: RegisteredToolMeta;
+	/** Resolved inner tool of a proxy/nested call; null when it could not be resolved. */
+	readonly target: RegisteredToolMeta | null;
+}
+
+/** A proxy exposure never grants anything itself: the inner tool is checked as if called directly. */
+export function authorizeCall(input: CallInput): AuthorizationOutcome {
+	const outer = describeTool(input.tool);
+	if (outer.restrictionAdapter !== "mcp_proxy") return authorizeTool({ ...input, descriptor: outer });
+	if (input.target === null) return { decision: "deny", reason: "proxy_target_unresolved" };
+	return authorizeTool({ ...input, descriptor: describeTool(input.target) });
+}