@1claw/openclaw-plugin 0.1.0

package/src/client.ts

@@ -0,0 +1,379 @@
+import type {
+    SecretMetadata,
+    SecretWithValue,
+    SecretListResponse,
+    VaultResponse,
+    VaultListResponse,
+    PolicyResponse,
+    ShareLinkResponse,
+    SimulationResponse,
+    BundleSimulationResponse,
+    TransactionResponse,
+    AgentProfile,
+    ApiErrorBody,
+} from "./types.js";
+
+export class OneClawApiError extends Error {
+    constructor(
+        public status: number,
+        public detail: string,
+    ) {
+        super(detail);
+        this.name = "OneClawApiError";
+    }
+}
+
+export interface ClientConfig {
+    baseUrl: string;
+    token: string;
+    vaultId: string;
+}
+
+export interface AgentCredentials {
+    baseUrl: string;
+    agentId?: string;
+    apiKey: string;
+    vaultId?: string;
+}
+
+interface AgentTokenResponse {
+    access_token: string;
+    expires_in: number;
+    agent_id?: string;
+    vault_ids?: string[];
+}
+
+function encodePath(path: string): string {
+    return path
+        .split("/")
+        .map((s) => encodeURIComponent(s))
+        .join("/");
+}
+
+const REFRESH_BUFFER_MS = 60_000;
+
+export class OneClawClient {
+    private baseUrl: string;
+    private token: string;
+    private _vaultId: string;
+    private _resolvedAgentId?: string;
+
+    private agentCredentials?: { agentId?: string; apiKey: string };
+    private tokenExpiresAt = 0;
+
+    constructor(config: ClientConfig | AgentCredentials) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this._vaultId = config.vaultId ?? "";
+
+        if ("apiKey" in config && !("token" in config)) {
+            this.agentCredentials = {
+                agentId: config.agentId,
+                apiKey: config.apiKey,
+            };
+            this.token = "";
+        } else {
+            this.token = (config as ClientConfig).token;
+        }
+    }
+
+    async ensureToken(): Promise<void> {
+        if (!this.agentCredentials) return;
+        if (this.token && Date.now() < this.tokenExpiresAt - REFRESH_BUFFER_MS)
+            return;
+
+        const body: Record<string, string> = {
+            api_key: this.agentCredentials.apiKey,
+        };
+        if (this.agentCredentials.agentId) {
+            body.agent_id = this.agentCredentials.agentId;
+        }
+
+        const res = await fetch(`${this.baseUrl}/v1/auth/agent-token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+
+        if (!res.ok) {
+            let detail = `HTTP ${res.status}`;
+            try {
+                const errBody = (await res.json()) as ApiErrorBody;
+                if (errBody.detail) detail = errBody.detail;
+            } catch {
+                /* use default */
+            }
+            throw new OneClawApiError(
+                res.status,
+                `Agent auth failed: ${detail}`,
+            );
+        }
+
+        const data = (await res.json()) as AgentTokenResponse;
+        this.token = data.access_token;
+        this.tokenExpiresAt = Date.now() + data.expires_in * 1000;
+
+        if (data.agent_id) {
+            this._resolvedAgentId = data.agent_id;
+            if (this.agentCredentials && !this.agentCredentials.agentId) {
+                this.agentCredentials.agentId = data.agent_id;
+            }
+        }
+
+        if (!this._vaultId && data.vault_ids && data.vault_ids.length === 1) {
+            this._vaultId = data.vault_ids[0];
+        }
+    }
+
+    private async autoDiscoverVault(): Promise<void> {
+        const vaults = await this.listVaults();
+        if (vaults.vaults && vaults.vaults.length > 0) {
+            this._vaultId = vaults.vaults[0].id;
+        }
+    }
+
+    private async headers(): Promise<Record<string, string>> {
+        await this.ensureToken();
+        return {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        };
+    }
+
+    private async resolveVaultUrl(suffix = ""): Promise<string> {
+        if (!this._vaultId) {
+            await this.autoDiscoverVault();
+        }
+        if (!this._vaultId) {
+            throw new OneClawApiError(
+                400,
+                "No vault configured. Set ONECLAW_VAULT_ID, bind the agent to a vault, or create a vault first.",
+            );
+        }
+        return `${this.baseUrl}/v1/vaults/${this._vaultId}${suffix}`;
+    }
+
+    private async request<T>(url: string, init?: RequestInit): Promise<T> {
+        const hdrs = await this.headers();
+        const res = await fetch(url, {
+            ...init,
+            headers: { ...hdrs, ...(init?.headers as Record<string, string>) },
+        });
+
+        if (!res.ok) {
+            let detail = `HTTP ${res.status}`;
+            let errorType = "";
+            try {
+                const body = (await res.json()) as ApiErrorBody;
+                if (body.detail) detail = body.detail;
+                if (body.type) errorType = body.type;
+            } catch {
+                // use default detail
+            }
+
+            if (res.status === 402) {
+                throw new OneClawApiError(
+                    402,
+                    "Quota exhausted. Ask your human to upgrade the plan, add prepaid credits, or enable x402 micropayments at https://1claw.xyz/settings/billing",
+                );
+            }
+
+            if (
+                res.status === 403 &&
+                errorType === "resource_limit_exceeded"
+            ) {
+                throw new OneClawApiError(
+                    403,
+                    `Resource limit reached: ${detail}. Ask your human to upgrade the plan at https://1claw.xyz/settings/billing`,
+                );
+            }
+
+            throw new OneClawApiError(res.status, detail);
+        }
+
+        if (res.status === 204) return undefined as T;
+        return res.json() as Promise<T>;
+    }
+
+    get agentId(): string | undefined {
+        return this._resolvedAgentId ?? this.agentCredentials?.agentId;
+    }
+
+    get vaultId(): string {
+        return this._vaultId;
+    }
+
+    get tokenTtlMs(): number {
+        if (!this.tokenExpiresAt) return 0;
+        return Math.max(0, this.tokenExpiresAt - Date.now());
+    }
+
+    get isAuthenticated(): boolean {
+        return !!this.token;
+    }
+
+    // ── Secrets ──────────────────────────────────────────
+
+    async listSecrets(): Promise<SecretListResponse> {
+        return this.request<SecretListResponse>(
+            await this.resolveVaultUrl("/secrets"),
+        );
+    }
+
+    async getSecret(path: string): Promise<SecretWithValue> {
+        return this.request<SecretWithValue>(
+            await this.resolveVaultUrl(`/secrets/${encodePath(path)}`),
+        );
+    }
+
+    async putSecret(
+        path: string,
+        body: {
+            value: string;
+            type: string;
+            metadata?: Record<string, unknown>;
+            expires_at?: string;
+            max_access_count?: number;
+        },
+    ): Promise<SecretMetadata> {
+        return this.request<SecretMetadata>(
+            await this.resolveVaultUrl(`/secrets/${encodePath(path)}`),
+            { method: "PUT", body: JSON.stringify(body) },
+        );
+    }
+
+    async deleteSecret(path: string): Promise<void> {
+        await this.request<void>(
+            await this.resolveVaultUrl(`/secrets/${encodePath(path)}`),
+            { method: "DELETE" },
+        );
+    }
+
+    // ── Vaults ───────────────────────────────────────────
+
+    async createVault(
+        name: string,
+        description?: string,
+    ): Promise<VaultResponse> {
+        return this.request<VaultResponse>(`${this.baseUrl}/v1/vaults`, {
+            method: "POST",
+            body: JSON.stringify({ name, description: description ?? "" }),
+        });
+    }
+
+    async listVaults(): Promise<VaultListResponse> {
+        return this.request<VaultListResponse>(`${this.baseUrl}/v1/vaults`);
+    }
+
+    // ── Policies ─────────────────────────────────────────
+
+    async createPolicy(
+        vaultId: string,
+        principalType: string,
+        principalId: string,
+        permissions: string[],
+        secretPathPattern = "**",
+    ): Promise<PolicyResponse> {
+        return this.request<PolicyResponse>(
+            `${this.baseUrl}/v1/vaults/${vaultId}/policies`,
+            {
+                method: "POST",
+                body: JSON.stringify({
+                    secret_path_pattern: secretPathPattern,
+                    principal_type: principalType,
+                    principal_id: principalId,
+                    permissions,
+                }),
+            },
+        );
+    }
+
+    // ── Sharing ──────────────────────────────────────────
+
+    async shareSecret(
+        secretId: string,
+        options: {
+            recipient_type: string;
+            email?: string;
+            recipient_id?: string;
+            expires_at: string;
+            max_access_count?: number;
+        },
+    ): Promise<ShareLinkResponse> {
+        return this.request<ShareLinkResponse>(
+            `${this.baseUrl}/v1/secrets/${secretId}/share`,
+            { method: "POST", body: JSON.stringify(options) },
+        );
+    }
+
+    // ── Transactions ─────────────────────────────────────
+
+    async simulateTransaction(
+        agentId: string,
+        tx: {
+            to: string;
+            value: string;
+            chain: string;
+            data?: string;
+            signing_key_path?: string;
+            gas_limit?: number;
+        },
+    ): Promise<SimulationResponse> {
+        return this.request<SimulationResponse>(
+            `${this.baseUrl}/v1/agents/${agentId}/transactions/simulate`,
+            { method: "POST", body: JSON.stringify(tx) },
+        );
+    }
+
+    async simulateBundle(
+        agentId: string,
+        transactions: Array<{
+            to: string;
+            value: string;
+            chain: string;
+            data?: string;
+            signing_key_path?: string;
+            gas_limit?: number;
+        }>,
+    ): Promise<BundleSimulationResponse> {
+        return this.request<BundleSimulationResponse>(
+            `${this.baseUrl}/v1/agents/${agentId}/transactions/simulate-bundle`,
+            { method: "POST", body: JSON.stringify({ transactions }) },
+        );
+    }
+
+    async submitTransaction(
+        agentId: string,
+        tx: {
+            to: string;
+            value: string;
+            chain: string;
+            data?: string;
+            signing_key_path?: string;
+            nonce?: number;
+            gas_price?: string;
+            gas_limit?: number;
+            max_fee_per_gas?: string;
+            max_priority_fee_per_gas?: string;
+            simulate_first?: boolean;
+        },
+        idempotencyKey?: string,
+    ): Promise<TransactionResponse> {
+        const key = idempotencyKey ?? crypto.randomUUID();
+        return this.request<TransactionResponse>(
+            `${this.baseUrl}/v1/agents/${agentId}/transactions`,
+            {
+                method: "POST",
+                body: JSON.stringify(tx),
+                headers: { "Idempotency-Key": key },
+            },
+        );
+    }
+
+    // ── Agent profile ────────────────────────────────────
+
+    async getAgentProfile(): Promise<AgentProfile> {
+        return this.request<AgentProfile>(
+            `${this.baseUrl}/v1/agents/me`,
+        );
+    }
+}

package/src/commands/index.ts

@@ -0,0 +1,18 @@
+import type { OneClawClient } from "../client.js";
+import type { PluginApi } from "../types.js";
+import type { ResolvedConfig } from "../config.js";
+import { statusCommand } from "./status.js";
+import { listCommand } from "./list.js";
+import { rotateCommand } from "./rotate.js";
+
+export function registerAllCommands(
+    api: PluginApi,
+    client: OneClawClient,
+    config: ResolvedConfig,
+): void {
+    api.registerCommand(statusCommand(client, config));
+    api.registerCommand(listCommand(client));
+    api.registerCommand(rotateCommand(client));
+
+    api.logger.info("[1claw] Registered 3 slash commands (/oneclaw, /oneclaw-list, /oneclaw-rotate)");
+}

package/src/commands/list.ts

@@ -0,0 +1,33 @@
+import type { OneClawClient } from "../client.js";
+
+export function listCommand(client: OneClawClient) {
+    return {
+        name: "oneclaw-list",
+        description: "List secret paths in the vault (metadata only, no values)",
+        acceptsArgs: true,
+        handler: async (ctx: { args?: string }) => {
+            try {
+                const data = await client.listSecrets();
+                let secrets = data.secrets;
+                const prefix = ctx.args?.trim();
+
+                if (prefix) {
+                    secrets = secrets.filter((s) => s.path.startsWith(prefix));
+                }
+
+                if (secrets.length === 0) {
+                    return { text: prefix ? `No secrets matching prefix '${prefix}'.` : "No secrets in vault." };
+                }
+
+                const lines = secrets.map(
+                    (s) => `${s.path}  (${s.type}, v${s.version}${s.expires_at ? `, expires ${s.expires_at}` : ""})`,
+                );
+
+                return { text: `${secrets.length} secret(s):\n${lines.join("\n")}` };
+            } catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { text: `Error listing secrets: ${msg}` };
+            }
+        },
+    };
+}

package/src/commands/rotate.ts

@@ -0,0 +1,39 @@
+import type { OneClawClient } from "../client.js";
+
+export function rotateCommand(client: OneClawClient) {
+    return {
+        name: "oneclaw-rotate",
+        description: "Rotate a secret to a new value: /oneclaw-rotate <path> <new-value>",
+        acceptsArgs: true,
+        requireAuth: true,
+        handler: async (ctx: { args?: string }) => {
+            const args = ctx.args?.trim();
+            if (!args) {
+                return { text: "Usage: /oneclaw-rotate <path> <new-value>" };
+            }
+
+            const spaceIdx = args.indexOf(" ");
+            if (spaceIdx === -1) {
+                return { text: "Usage: /oneclaw-rotate <path> <new-value>\nBoth path and new value are required." };
+            }
+
+            const path = args.slice(0, spaceIdx);
+            const newValue = args.slice(spaceIdx + 1).trim();
+
+            if (!newValue) {
+                return { text: "Usage: /oneclaw-rotate <path> <new-value>\nNew value cannot be empty." };
+            }
+
+            try {
+                const result = await client.putSecret(path, {
+                    value: newValue,
+                    type: "api_key",
+                });
+                return { text: `Rotated '${path}' to version ${result.version}.` };
+            } catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { text: `Error rotating '${path}': ${msg}` };
+            }
+        },
+    };
+}

package/src/commands/status.ts

@@ -0,0 +1,46 @@
+import type { OneClawClient } from "../client.js";
+import type { ResolvedConfig } from "../config.js";
+
+export function statusCommand(client: OneClawClient, config: ResolvedConfig) {
+    return {
+        name: "oneclaw",
+        description: "Show 1claw connection status, vault info, token TTL, and enabled features",
+        handler: async () => {
+            const lines: string[] = ["1Claw Status", "─".repeat(30)];
+
+            lines.push(`API: ${config.baseUrl}`);
+            lines.push(`Shroud: ${config.shroudUrl}`);
+            lines.push(`Authenticated: ${client.isAuthenticated ? "yes" : "no"}`);
+
+            if (client.agentId) {
+                lines.push(`Agent ID: ${client.agentId}`);
+            }
+
+            if (client.vaultId) {
+                lines.push(`Vault ID: ${client.vaultId}`);
+            }
+
+            const ttlMin = Math.round(client.tokenTtlMs / 60_000);
+            lines.push(`Token TTL: ${ttlMin > 0 ? `${ttlMin} min` : "expired or not set"}`);
+
+            lines.push("", "Features:");
+            const features = config.features;
+            lines.push(`  Tools: ${features.tools ? "on" : "off"}`);
+            lines.push(`  Secret injection: ${features.secretInjection ? "on" : "off"}`);
+            lines.push(`  Secret redaction: ${features.secretRedaction ? "on" : "off"}`);
+            lines.push(`  Shroud routing: ${features.shroudRouting ? "on" : "off"}`);
+            lines.push(`  Key rotation monitor: ${features.keyRotationMonitor ? "on" : "off"}`);
+            lines.push(`  Slash commands: ${features.slashCommands ? "on" : "off"}`);
+            lines.push(`  Security mode: ${config.securityMode}`);
+
+            try {
+                const vaults = await client.listVaults();
+                lines.push("", `Vaults accessible: ${vaults.vaults.length}`);
+            } catch {
+                lines.push("", "Vaults: unable to list (check credentials)");
+            }
+
+            return { text: lines.join("\n") };
+        },
+    };
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+export interface ResolvedFeatures {
+    tools: boolean;
+    secretInjection: boolean;
+    secretRedaction: boolean;
+    shroudRouting: boolean;
+    keyRotationMonitor: boolean;
+    slashCommands: boolean;
+}
+
+export interface ResolvedConfig {
+    apiKey: string | undefined;
+    agentId: string | undefined;
+    vaultId: string | undefined;
+    baseUrl: string;
+    shroudUrl: string;
+    features: ResolvedFeatures;
+    securityMode: "block" | "surgical" | "log_only";
+}
+
+interface RawPluginConfig {
+    apiKey?: string;
+    agentId?: string;
+    vaultId?: string;
+    baseUrl?: string;
+    shroudUrl?: string;
+    features?: Partial<ResolvedFeatures>;
+    securityMode?: string;
+}
+
+const DEFAULT_FEATURES: ResolvedFeatures = {
+    tools: true,
+    secretInjection: false,
+    secretRedaction: true,
+    shroudRouting: false,
+    keyRotationMonitor: false,
+    slashCommands: true,
+};
+
+function resolveSecurityMode(
+    raw: string | undefined,
+): "block" | "surgical" | "log_only" {
+    if (raw === "surgical" || raw === "log_only") return raw;
+    return "block";
+}
+
+export function resolveConfig(pluginConfig?: RawPluginConfig): ResolvedConfig {
+    const raw = pluginConfig ?? {};
+
+    return {
+        apiKey:
+            raw.apiKey ??
+            process.env.ONECLAW_AGENT_API_KEY ??
+            undefined,
+        agentId:
+            raw.agentId ??
+            process.env.ONECLAW_AGENT_ID ??
+            undefined,
+        vaultId:
+            raw.vaultId ??
+            process.env.ONECLAW_VAULT_ID ??
+            undefined,
+        baseUrl:
+            raw.baseUrl ??
+            process.env.ONECLAW_BASE_URL ??
+            "https://api.1claw.xyz",
+        shroudUrl:
+            raw.shroudUrl ??
+            process.env.ONECLAW_SHROUD_URL ??
+            "https://shroud.1claw.xyz",
+        features: {
+            ...DEFAULT_FEATURES,
+            ...(raw.features ?? {}),
+        },
+        securityMode: resolveSecurityMode(
+            raw.securityMode ??
+                process.env.ONECLAW_MCP_SANITIZATION_MODE,
+        ),
+    };
+}

package/src/hooks/index.ts

@@ -0,0 +1,24 @@
+import type { OneClawClient } from "../client.js";
+import type { PluginApi } from "../types.js";
+import type { ResolvedConfig } from "../config.js";
+import { registerSecretRedaction } from "./secret-redaction.js";
+import { registerSecretInjection } from "./secret-injection.js";
+import { registerShroudRouting } from "./shroud-routing.js";
+
+export function registerAllHooks(
+    api: PluginApi,
+    client: OneClawClient,
+    config: ResolvedConfig,
+): void {
+    if (config.features.secretRedaction) {
+        registerSecretRedaction(api, client);
+    }
+
+    if (config.features.secretInjection) {
+        registerSecretInjection(api, client);
+    }
+
+    if (config.features.shroudRouting) {
+        registerShroudRouting(api, client, config.shroudUrl);
+    }
+}

package/src/hooks/secret-injection.ts

@@ -0,0 +1,58 @@
+import type { OneClawClient } from "../client.js";
+import type { PluginApi } from "../types.js";
+
+const PLACEHOLDER_RE = /\{\{1claw:([^}]+)\}\}/g;
+
+interface PromptBuildEvent {
+    messages?: Array<{ role: string; content: string }>;
+}
+
+export function registerSecretInjection(api: PluginApi, client: OneClawClient): void {
+    api.on(
+        "before_prompt_build",
+        async (event: unknown, _ctx: unknown) => {
+            const ev = event as PromptBuildEvent;
+            if (!ev.messages || ev.messages.length === 0) return {};
+
+            let injected = 0;
+
+            for (const msg of ev.messages) {
+                if (!msg.content) continue;
+
+                const matches = [...msg.content.matchAll(PLACEHOLDER_RE)];
+                if (matches.length === 0) continue;
+
+                for (const match of matches) {
+                    const fullPlaceholder = match[0];
+                    const secretPath = match[1];
+
+                    try {
+                        const secret = await client.getSecret(secretPath);
+                        msg.content = msg.content.replace(fullPlaceholder, secret.value);
+                        injected++;
+                    } catch (err) {
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        api.logger.warn(
+                            `[1claw/injection] Failed to resolve ${secretPath}: ${errMsg}`,
+                        );
+                        msg.content = msg.content.replace(
+                            fullPlaceholder,
+                            `[1CLAW_UNAVAILABLE:${secretPath}]`,
+                        );
+                    }
+                }
+            }
+
+            if (injected > 0) {
+                api.logger.info(
+                    `[1claw/injection] Injected ${injected} secret(s) into conversation`,
+                );
+            }
+
+            return {};
+        },
+        { priority: 90 },
+    );
+
+    api.logger.info("[1claw] Secret injection hook registered");
+}