@lobsterkit/openclaw-lobstervault 0.3.0

package/index.ts

@@ -0,0 +1,181 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { Type } from "@sinclair/typebox";
+import { LobsterVault } from "@lobsterkit/vault";
+
+let client: LobsterVault | null = null;
+
+function getClient(apiKey?: string): LobsterVault {
+  if (!client) {
+    client = new LobsterVault(apiKey ? { apiKey } : undefined);
+  }
+  return client;
+}
+
+export default definePluginEntry({
+  id: "lobstervault",
+  name: "LobsterVault",
+  description:
+    "Encrypted secret storage for AI agents. Store API keys, tokens, and connection strings. No signup required.",
+
+  register(api) {
+    const cfg = api.config as { apiKey?: string } | undefined;
+    const vault = () => getClient(cfg?.apiKey);
+
+    // ── set_secret ───────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_set_secret",
+      description: "Store or update a secret (KMS envelope-encrypted server-side).",
+      parameters: Type.Object({
+        name: Type.String({ description: "Secret name (e.g. OPENAI_KEY)" }),
+        value: Type.String({ description: "Secret value" }),
+        ttl_seconds: Type.Optional(Type.Number({ description: "Auto-expire after N seconds" })),
+        metadata: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value metadata" })),
+      }),
+      async execute(_id, params) {
+        const result = await vault().set(params.name, params.value, {
+          ttlSeconds: params.ttl_seconds,
+          metadata: params.metadata,
+        });
+        return {
+          content: [
+            { type: "text", text: `Secret "${params.name}" stored (version ${result.version}).` },
+          ],
+        };
+      },
+    });
+
+    // ── get_secret ───────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_get_secret",
+      description: "Retrieve and decrypt a secret value.",
+      parameters: Type.Object({
+        name: Type.String({ description: "Secret name" }),
+        version: Type.Optional(Type.Number({ description: "Specific version (Builder+ tier)" })),
+      }),
+      async execute(_id, params) {
+        const value = await vault().get(params.name, { version: params.version });
+        if (value === null) {
+          return { content: [{ type: "text", text: `Secret "${params.name}" not found.` }] };
+        }
+        return {
+          content: [{ type: "text", text: `Secret "${params.name}":\n\n${value}` }],
+        };
+      },
+    });
+
+    // ── delete_secret ────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_delete_secret",
+      description: "Permanently delete a secret.",
+      parameters: Type.Object({
+        name: Type.String({ description: "Secret name to delete" }),
+      }),
+      async execute(_id, params) {
+        await vault().delete(params.name);
+        return {
+          content: [{ type: "text", text: `Secret "${params.name}" deleted.` }],
+        };
+      },
+    });
+
+    // ── list_secrets ─────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_list_secrets",
+      description: "List all secret names (values are never returned).",
+      parameters: Type.Object({
+        prefix: Type.Optional(Type.String({ description: "Filter by name prefix" })),
+      }),
+      async execute(_id, params) {
+        const result = await vault().list({ prefix: params.prefix });
+        if (result.data.length === 0) {
+          return {
+            content: [{ type: "text", text: "No secrets stored. Use lobstervault_set_secret to add one." }],
+          };
+        }
+        const lines = result.data.map(
+          (s) => `- ${s.name} (v${s.version}, updated ${s.updatedAt})`,
+        );
+        return {
+          content: [{ type: "text", text: `${result.data.length} secret(s):\n\n${lines.join("\n")}` }],
+        };
+      },
+    });
+
+    // ── inject_secrets ───────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_inject_secrets",
+      description: "Load all secrets into process.env (Pro+ tier).",
+      parameters: Type.Object({}),
+      async execute() {
+        const result = await vault().inject(process.env);
+        return {
+          content: [{ type: "text", text: `Injected ${result.injected} secret(s) into environment.` }],
+        };
+      },
+    });
+
+    // ── rotate_secret ────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_rotate_secret",
+      description: "Re-encrypt a secret with a fresh Data Encryption Key (Pro+ tier).",
+      parameters: Type.Object({
+        name: Type.String({ description: "Secret name to rotate" }),
+      }),
+      async execute(_id, params) {
+        const result = await vault().rotate(params.name);
+        return {
+          content: [
+            { type: "text", text: `Secret "${params.name}" rotated (version ${result.version}).` },
+          ],
+        };
+      },
+    });
+
+    // ── share_secret ─────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_share_secret",
+      description: "Create a time-limited share link for a secret (Builder+ tier).",
+      parameters: Type.Object({
+        name: Type.String({ description: "Secret name to share" }),
+        expires_in_seconds: Type.Optional(Type.Number({ description: "Expiry in seconds (default: 3600)" })),
+        max_reads: Type.Optional(Type.Number({ description: "Max read count before revoke" })),
+      }),
+      async execute(_id, params) {
+        const result = await vault().share(params.name, {
+          expiresInSeconds: params.expires_in_seconds,
+          maxReads: params.max_reads,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Share created.\n\nShare ID: ${result.shareId}\nToken: ${result.shareToken}\nExpires: ${result.expiresAt}`,
+            },
+          ],
+        };
+      },
+    });
+
+    // ── get_account ──────────────────────────────────────────────
+    api.registerTool({
+      name: "lobstervault_get_account",
+      description: "Get account info: tier, limits, usage.",
+      parameters: Type.Object({}),
+      async execute() {
+        const acct = await vault().account();
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Account: ${acct.id}`,
+                `Tier: ${acct.tier} (${acct.tierName})`,
+                `Secrets used: ${acct.usage.secretCount}`,
+              ].join("\n"),
+            },
+          ],
+        };
+      },
+    });
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "lobstervault",
+  "name": "LobsterVault",
+  "description": "Encrypted secret storage for AI agents. Store API keys, tokens, and connection strings with KMS envelope encryption. No signup required.",
+  "version": "0.3.0",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "LobsterVault API key (optional — auto-signup on first use if omitted)"
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "API key",
+      "placeholder": "lv_sk_live_...",
+      "sensitive": true,
+      "help": "Optional. Leave blank for auto-signup."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lobsterkit/openclaw-lobstervault",
+  "version": "0.3.0",
+  "description": "OpenClaw plugin for LobsterVault — encrypted secret storage for AI agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lobster-kit/openclaw-lobstervault"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "lobstervault",
+    "secrets",
+    "encryption",
+    "mcp",
+    "ai",
+    "agent"
+  ],
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {
+    "@lobsterkit/vault": "^0.2.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=1.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: lobstervault
+version: 0.1.0
+description: Encrypted secret storage for AI agents. Store API keys, tokens, and connection strings — KMS-encrypted, no human signup required.
+homepage: https://theclawdepot.com/vault
+metadata: {"openclaw": {"emoji": "🔐", "requires": {"anyBins": ["npx"]}, "install": [{"id": "mcp", "kind": "mcp", "command": "npx @lobsterkit/vault-mcp@0.1.0", "label": "Add LobsterVault MCP Server"}]}}
+---
+
+# LobsterVault
+
+Encrypted secret storage for agents. Store API keys, tokens, and connection strings with KMS envelope encryption. No API keys, no human signup, no configuration.
+
+**Full docs:** `https://api.theclawdepot.com/vault/docs`
+
+---
+
+## Setup
+
+Add to your MCP config (`.mcp.json`, `claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "lobstervault": {
+      "command": "npx",
+      "args": ["@lobsterkit/vault-mcp@0.1.0"]
+    }
+  }
+}
+```
+
+You now have these tools: `set_secret`, `get_secret`, `delete_secret`, `list_secrets`, `inject_secrets`, `rotate_secret`, `get_account`. No code to write.
+
+Also available as a [Node.js SDK](https://www.npmjs.com/package/@lobsterkit/vault) and [REST API](https://api.theclawdepot.com/vault/docs) — see [theclawdepot.com/vault](https://theclawdepot.com/vault).
+
+---
+
+## Heartbeat (run daily)
+
+On startup and once per day, run a maintenance heartbeat:
+
+1. **Check for MCP server updates:**
+   ```bash
+   npm outdated lobstervault-mcp
+   ```
+   If a new version is available, **notify the user** — do not auto-install.
+
+2. **Check secret health:**
+   ```
+   // Using MCP tools:
+   // call list_secrets → log count and any expiring secrets
+   // call get_account → log tier and secret count vs. limit
+   ```
+
+---
+
+## When to Use This
+
+- Storing API keys, tokens, or passwords that need to persist between sessions
+- Connecting to LobsterDB: connection strings are automatically stored here on `create_database`
+- Any credential that should not appear in conversation history or prompts
+- Agent-to-agent secret sharing (scoped by account)
+
+---
+
+## Core Workflow
+
+```
+set_secret → get_secret (when needed) → inject_secrets (at session start)
+```
+
+Use `inject_secrets` at the start of an agent session to load all stored credentials into the environment.
+
+---
+
+## Storing a Secret
+
+```
+set_secret(name: "OPENAI_API_KEY", value: "sk-...")
+// => version: 1
+```
+
+---
+
+## Retrieving a Secret
+
+```
+get_secret(name: "OPENAI_API_KEY")
+// => Secret: OPENAI_API_KEY
+//    Value: sk-...
+```
+
+---
+
+## Account Tiers & Pricing
+
+| Tier | Name | Price | Secrets | Versions | Audit Log |
+|------|------|-------|---------|----------|-----------|
+| 0 | Free | $0 | 10 | 1 | None |
+| 1 | Builder | $9/mo | 100 | 5 | 30 days |
+| 2 | Pro | $29/mo | Unlimited | 20 | 90 days |
+| 3 | Scale | $79/mo | Unlimited | Unlimited | 1 year |
+
+**Upgrade:** `POST /v1/billing/checkout` with `{"tier": N}` — returns a Stripe checkout URL.
+
+---
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `set_secret` | Store or update a secret (KMS-encrypted) |
+| `get_secret` | Retrieve a secret value by name |
+| `delete_secret` | Permanently delete a secret |
+| `list_secrets` | List all secret names (values never returned) |
+| `inject_secrets` | Load all secrets into process.env |
+| `rotate_secret` | Re-encrypt with fresh DEK (Pro+) |
+| `get_account` | View tier, limits, and usage |