@1claw/openclaw-plugin 0.1.0

package/src/tools/get-secret.ts

@@ -0,0 +1,46 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import { OneClawApiError } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function getSecretTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_get_secret",
+        description:
+            "Fetch the decrypted value of a secret from the 1claw vault by its path. Use this immediately before making an API call that requires the credential. Do not store the value or include it in summaries.",
+        parameters: Type.Object({
+            path: Type.String({
+                minLength: 1,
+                description: "Secret path, e.g. 'api-keys/stripe'",
+            }),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const path = params.path as string;
+            try {
+                const secret = await client.getSecret(path);
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            path: secret.path,
+                            type: secret.type,
+                            version: secret.version,
+                            value: secret.value,
+                        }),
+                    }],
+                };
+            } catch (err) {
+                if (err instanceof OneClawApiError) {
+                    if (err.status === 410) {
+                        return { content: [{ type: "text", text: `Error: Secret at path '${path}' is expired or has exceeded its maximum access count.` }] };
+                    }
+                    if (err.status === 404) {
+                        return { content: [{ type: "text", text: `Error: No secret found at path '${path}'.` }] };
+                    }
+                }
+                throw err;
+            }
+        },
+    };
+}

package/src/tools/grant-access.ts

@@ -0,0 +1,50 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function grantAccessTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_grant_access",
+        description:
+            "Grant a user or agent access to one of your vaults. You can only grant access on vaults you created.",
+        parameters: Type.Object({
+            vault_id: Type.String({ description: "UUID of the vault to share" }),
+            principal_type: Type.Union([Type.Literal("user"), Type.Literal("agent")], {
+                description: "Type of principal",
+            }),
+            principal_id: Type.String({ description: "UUID of the user or agent" }),
+            permissions: Type.Optional(
+                Type.Array(Type.String(), { description: "Permissions to grant (default: ['read'])" }),
+            ),
+            secret_path_pattern: Type.Optional(
+                Type.String({ description: "Glob pattern for secret paths (default: '**')" }),
+            ),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const permissions = (params.permissions as string[]) ?? ["read"];
+            const pathPattern = (params.secret_path_pattern as string) ?? "**";
+
+            const policy = await client.createPolicy(
+                params.vault_id as string,
+                params.principal_type as string,
+                params.principal_id as string,
+                permissions,
+                pathPattern,
+            );
+
+            return {
+                content: [{
+                    type: "text",
+                    text:
+                        `Access granted.\n` +
+                        `  Policy ID: ${policy.id}\n` +
+                        `  Vault: ${policy.vault_id}\n` +
+                        `  Granted to: ${policy.principal_type}:${policy.principal_id}\n` +
+                        `  Permissions: ${policy.permissions.join(", ")}\n` +
+                        `  Path pattern: ${policy.secret_path_pattern}`,
+                }],
+            };
+        },
+    };
+}

package/src/tools/index.ts

@@ -0,0 +1,92 @@
+import type { OneClawClient } from "../client.js";
+import type { PluginApi, PluginTool, ToolResult } from "../types.js";
+import type { ResolvedConfig } from "../config.js";
+import { inspectInput, inspectOutput } from "../security/index.js";
+
+import { listSecretsTool } from "./list-secrets.js";
+import { getSecretTool } from "./get-secret.js";
+import { putSecretTool } from "./put-secret.js";
+import { deleteSecretTool } from "./delete-secret.js";
+import { describeSecretTool } from "./describe-secret.js";
+import { rotateAndStoreTool } from "./rotate-and-store.js";
+import { getEnvBundleTool } from "./get-env-bundle.js";
+import { createVaultTool } from "./create-vault.js";
+import { listVaultsTool } from "./list-vaults.js";
+import { grantAccessTool } from "./grant-access.js";
+import { shareSecretTool } from "./share-secret.js";
+import { simulateTransactionTool } from "./simulate-transaction.js";
+import { submitTransactionTool } from "./submit-transaction.js";
+
+type ToolFactory = (client: OneClawClient) => PluginTool;
+
+const ALL_TOOL_FACTORIES: ToolFactory[] = [
+    listSecretsTool,
+    getSecretTool,
+    putSecretTool,
+    deleteSecretTool,
+    describeSecretTool,
+    rotateAndStoreTool,
+    getEnvBundleTool,
+    createVaultTool,
+    listVaultsTool,
+    grantAccessTool,
+    shareSecretTool,
+    simulateTransactionTool,
+    submitTransactionTool,
+];
+
+function wrapWithSecurity(
+    tool: PluginTool,
+    api: PluginApi,
+    config: ResolvedConfig,
+): PluginTool {
+    const originalExecute = tool.execute;
+
+    return {
+        ...tool,
+        execute: async (id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const inputCheck = inspectInput(tool.name, params, config.securityMode);
+
+            if (!inputCheck.passed) {
+                const threat = inputCheck.threats[0];
+                api.logger.warn(
+                    `[1claw/security] Blocked ${tool.name}: ${threat?.type} (${threat?.pattern})`,
+                );
+                return {
+                    content: [{ type: "text", text: `Security check failed: ${threat?.type} detected` }],
+                };
+            }
+
+            if (inputCheck.threats.length > 0) {
+                api.logger.info(
+                    `[1claw/security] Warnings for ${tool.name}: ${inputCheck.threats.map((t) => t.pattern).join(", ")}`,
+                );
+            }
+
+            const result = await originalExecute(id, params);
+
+            const outputText = result.content.map((c) => c.text).join("\n");
+            const outputCheck = inspectOutput(tool.name, outputText);
+            if (outputCheck.threats.length > 0) {
+                api.logger.info(
+                    `[1claw/security] Output warnings for ${tool.name}: ${outputCheck.threats.map((t) => t.pattern).join(", ")}`,
+                );
+            }
+
+            return result;
+        },
+    };
+}
+
+export function registerAllTools(
+    api: PluginApi,
+    client: OneClawClient,
+    config: ResolvedConfig,
+): void {
+    for (const factory of ALL_TOOL_FACTORIES) {
+        const tool = factory(client);
+        const secured = wrapWithSecurity(tool, api, config);
+        api.registerTool(secured);
+    }
+    api.logger.info(`[1claw] Registered ${ALL_TOOL_FACTORIES.length} agent tools`);
+}

package/src/tools/list-secrets.ts

@@ -0,0 +1,39 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function listSecretsTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_list_secrets",
+        description:
+            "List all secrets stored in the 1claw vault. Returns paths, types, versions, and metadata — never secret values. Use this to discover what credentials are available before fetching one.",
+        parameters: Type.Object({
+            prefix: Type.Optional(
+                Type.String({ description: "Path prefix to filter secrets (e.g. 'api-keys/')" }),
+            ),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const data = await client.listSecrets();
+            let secrets = data.secrets;
+            const prefix = params.prefix as string | undefined;
+
+            if (prefix) {
+                secrets = secrets.filter((s) => s.path.startsWith(prefix));
+            }
+
+            if (secrets.length === 0) {
+                return { content: [{ type: "text", text: "No secrets found in this vault." }] };
+            }
+
+            const lines = secrets.map(
+                (s) =>
+                    `- ${s.path}  (type: ${s.type}, version: ${s.version}, expires: ${s.expires_at ?? "never"})`,
+            );
+
+            return {
+                content: [{ type: "text", text: `Found ${secrets.length} secret(s):\n${lines.join("\n")}` }],
+            };
+        },
+    };
+}

package/src/tools/list-vaults.ts

@@ -0,0 +1,29 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function listVaultsTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_list_vaults",
+        description:
+            "List all vaults accessible to you. Returns vault IDs, names, and creators. Use this to discover available vaults.",
+        parameters: Type.Object({}),
+        optional: true,
+        execute: async (): Promise<ToolResult> => {
+            const data = await client.listVaults();
+            const vaults = data.vaults;
+
+            if (vaults.length === 0) {
+                return { content: [{ type: "text", text: "No vaults found. Create one with oneclaw_create_vault." }] };
+            }
+
+            const lines = vaults.map(
+                (v) => `- ${v.name}  (id: ${v.id}, created by: ${v.created_by_type}, ${v.created_at})`,
+            );
+
+            return {
+                content: [{ type: "text", text: `Found ${vaults.length} vault(s):\n${lines.join("\n")}` }],
+            };
+        },
+    };
+}

package/src/tools/put-secret.ts

@@ -0,0 +1,44 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function putSecretTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_put_secret",
+        description:
+            "Store a new secret or update an existing one in the 1claw vault. Each call creates a new version. Supports optional expiry and max access count.",
+        parameters: Type.Object({
+            path: Type.String({ minLength: 1, description: "Secret path, e.g. 'api-keys/stripe'" }),
+            value: Type.String({ minLength: 1, description: "The secret value to store" }),
+            type: Type.Optional(
+                Type.Union([
+                    Type.Literal("api_key"),
+                    Type.Literal("password"),
+                    Type.Literal("private_key"),
+                    Type.Literal("certificate"),
+                    Type.Literal("file"),
+                    Type.Literal("note"),
+                    Type.Literal("ssh_key"),
+                    Type.Literal("env_bundle"),
+                ], { description: "Secret type (default: api_key)" }),
+            ),
+            metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional JSON metadata" })),
+            expires_at: Type.Optional(Type.String({ description: "Optional ISO 8601 expiry datetime" })),
+            max_access_count: Type.Optional(Type.Integer({ minimum: 1, description: "Max reads before auto-expiry" })),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const result = await client.putSecret(params.path as string, {
+                value: params.value as string,
+                type: (params.type as string) ?? "api_key",
+                metadata: params.metadata as Record<string, unknown> | undefined,
+                expires_at: params.expires_at as string | undefined,
+                max_access_count: params.max_access_count as number | undefined,
+            });
+
+            return {
+                content: [{ type: "text", text: `Secret stored at '${params.path}' (version ${result.version}, type: ${result.type}).` }],
+            };
+        },
+    };
+}

package/src/tools/rotate-and-store.ts

@@ -0,0 +1,25 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function rotateAndStoreTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_rotate_and_store",
+        description:
+            "Store a new value for an existing secret (creating a new version). Use after regenerating an API key at a provider.",
+        parameters: Type.Object({
+            path: Type.String({ minLength: 1, description: "Secret path to rotate" }),
+            value: Type.String({ minLength: 1, description: "The new secret value" }),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const result = await client.putSecret(params.path as string, {
+                value: params.value as string,
+                type: "api_key",
+            });
+            return {
+                content: [{ type: "text", text: `Rotated secret at '${params.path}'. New version: ${result.version}.` }],
+            };
+        },
+    };
+}

package/src/tools/share-secret.ts

@@ -0,0 +1,61 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function shareSecretTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_share_secret",
+        description:
+            "Share a specific secret with a user, agent, or your creator (the human who registered you). " +
+            "Use recipient_type 'creator' to share back with the human — no recipient_id needed.",
+        parameters: Type.Object({
+            secret_id: Type.String({ description: "UUID of the secret to share" }),
+            recipient_type: Type.Union([
+                Type.Literal("user"),
+                Type.Literal("agent"),
+                Type.Literal("anyone_with_link"),
+                Type.Literal("creator"),
+            ], { description: "Recipient type" }),
+            recipient_id: Type.Optional(Type.String({ description: "UUID of recipient (required for user/agent)" })),
+            expires_at: Type.String({ description: "ISO-8601 expiry date" }),
+            max_access_count: Type.Optional(Type.Integer({ minimum: 1, description: "Max accesses (default: 5)" })),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const recipientType = params.recipient_type as string;
+            const recipientId = params.recipient_id as string | undefined;
+
+            if ((recipientType === "user" || recipientType === "agent") && !recipientId) {
+                return {
+                    content: [{ type: "text", text: `Error: recipient_id is required when sharing with a ${recipientType}.` }],
+                };
+            }
+
+            const share = await client.shareSecret(params.secret_id as string, {
+                recipient_type: recipientType,
+                recipient_id: recipientId,
+                expires_at: params.expires_at as string,
+                max_access_count: (params.max_access_count as number) ?? 5,
+            });
+
+            const recipientLabel =
+                recipientType === "creator"
+                    ? "your creator (the human who registered this agent)"
+                    : `${recipientType}${recipientId ? ` (${recipientId})` : ""}`;
+
+            return {
+                content: [{
+                    type: "text",
+                    text:
+                        `Secret shared successfully.\n` +
+                        `  Share ID: ${share.id}\n` +
+                        `  Recipient: ${recipientLabel}\n` +
+                        `  Expires: ${share.expires_at}\n` +
+                        `  Max accesses: ${share.max_access_count}\n` +
+                        `  URL: ${share.share_url}\n\n` +
+                        `The recipient must accept the share before they can access the secret.`,
+                }],
+            };
+        },
+    };
+}

package/src/tools/simulate-transaction.ts

@@ -0,0 +1,66 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import { OneClawApiError } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function simulateTransactionTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_simulate_transaction",
+        description:
+            "Simulate an EVM transaction via Tenderly without signing or broadcasting. Returns balance changes, gas estimates, and success/revert status.",
+        parameters: Type.Object({
+            to: Type.String({ description: "Destination address (0x-prefixed)" }),
+            value: Type.String({ description: "Value in ETH (e.g. '0.01')" }),
+            chain: Type.String({ description: "Chain name or numeric chain ID" }),
+            data: Type.Optional(Type.String({ description: "Hex-encoded calldata" })),
+            signing_key_path: Type.Optional(Type.String({ description: "Vault path to signing key" })),
+            gas_limit: Type.Optional(Type.Integer({ description: "Gas limit (default: 21000)" })),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const agentId = client.agentId;
+            if (!agentId) {
+                return { content: [{ type: "text", text: "Error: simulate_transaction requires agent authentication." }] };
+            }
+
+            try {
+                const result = await client.simulateTransaction(agentId, {
+                    to: params.to as string,
+                    value: params.value as string,
+                    chain: params.chain as string,
+                    data: params.data as string | undefined,
+                    signing_key_path: params.signing_key_path as string | undefined,
+                    gas_limit: params.gas_limit as number | undefined,
+                });
+
+                const lines: string[] = [
+                    `Simulation ${result.status.toUpperCase()}`,
+                    `Gas used: ${result.gas_used}`,
+                ];
+
+                if (result.gas_estimate_usd) lines.push(`Gas estimate: ${result.gas_estimate_usd}`);
+
+                if (result.balance_changes.length > 0) {
+                    lines.push("", "Balance changes:");
+                    for (const bc of result.balance_changes) {
+                        const token = bc.token_symbol ?? bc.token ?? "ETH";
+                        lines.push(`  ${bc.address}: ${bc.change ?? "?"} ${token}`);
+                    }
+                }
+
+                if (result.error) lines.push("", `Error: ${result.error}`);
+                if (result.error_human_readable) lines.push(`Reason: ${result.error_human_readable}`);
+                if (result.tenderly_dashboard_url) lines.push("", `Tenderly: ${result.tenderly_dashboard_url}`);
+
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            } catch (err) {
+                if (err instanceof OneClawApiError) {
+                    if (err.status === 400 || err.status === 403 || err.status === 422) {
+                        return { content: [{ type: "text", text: `Error: ${err.detail}` }] };
+                    }
+                }
+                throw err;
+            }
+        },
+    };
+}

package/src/tools/submit-transaction.ts

@@ -0,0 +1,69 @@
+import { Type } from "@sinclair/typebox";
+import type { OneClawClient } from "../client.js";
+import { OneClawApiError } from "../client.js";
+import type { PluginTool, ToolResult } from "../types.js";
+
+export function submitTransactionTool(client: OneClawClient): PluginTool {
+    return {
+        name: "oneclaw_submit_transaction",
+        description:
+            "Submit an EVM transaction to be signed by 1claw's Intents API and optionally broadcast. Supports legacy and EIP-1559 fee modes.",
+        parameters: Type.Object({
+            to: Type.String({ description: "Destination address (0x-prefixed)" }),
+            value: Type.String({ description: "Value in ETH (e.g. '0.01')" }),
+            chain: Type.String({ description: "Chain name or numeric chain ID" }),
+            data: Type.Optional(Type.String({ description: "Hex-encoded calldata" })),
+            signing_key_path: Type.Optional(Type.String({ description: "Vault path to signing key" })),
+            nonce: Type.Optional(Type.Integer({ description: "Transaction nonce (auto-resolved if omitted)" })),
+            gas_price: Type.Optional(Type.String({ description: "Gas price in wei (legacy mode)" })),
+            gas_limit: Type.Optional(Type.Integer({ description: "Gas limit (default: 21000)" })),
+            max_fee_per_gas: Type.Optional(Type.String({ description: "EIP-1559 max fee per gas in wei" })),
+            max_priority_fee_per_gas: Type.Optional(Type.String({ description: "EIP-1559 max priority fee in wei" })),
+            simulate_first: Type.Optional(Type.Boolean({ description: "Run simulation before signing (default: true)" })),
+        }),
+        optional: true,
+        execute: async (_id: unknown, params: Record<string, unknown>): Promise<ToolResult> => {
+            const agentId = client.agentId;
+            if (!agentId) {
+                return { content: [{ type: "text", text: "Error: submit_transaction requires agent authentication." }] };
+            }
+
+            try {
+                const result = await client.submitTransaction(agentId, {
+                    to: params.to as string,
+                    value: params.value as string,
+                    chain: params.chain as string,
+                    data: params.data as string | undefined,
+                    signing_key_path: params.signing_key_path as string | undefined,
+                    nonce: params.nonce as number | undefined,
+                    gas_price: params.gas_price as string | undefined,
+                    gas_limit: params.gas_limit as number | undefined,
+                    max_fee_per_gas: params.max_fee_per_gas as string | undefined,
+                    max_priority_fee_per_gas: params.max_priority_fee_per_gas as string | undefined,
+                    simulate_first: (params.simulate_first as boolean) ?? true,
+                });
+
+                const lines: string[] = [
+                    `Transaction ${result.status.toUpperCase()}`,
+                    `ID: ${result.id}`,
+                    `Chain: ${result.chain} (${result.chain_id})`,
+                    `To: ${result.to}`,
+                    `Value: ${result.value_wei} wei`,
+                ];
+
+                if (result.tx_hash) lines.push(`Tx hash: ${result.tx_hash}`);
+                if (result.simulation_id) lines.push(`Simulation: ${result.simulation_id} (${result.simulation_status})`);
+                if (result.error_message) lines.push(`Error: ${result.error_message}`);
+
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            } catch (err) {
+                if (err instanceof OneClawApiError) {
+                    if (err.status === 400 || err.status === 403 || err.status === 422) {
+                        return { content: [{ type: "text", text: `Error: ${err.detail}` }] };
+                    }
+                }
+                throw err;
+            }
+        },
+    };
+}