mnemospark 1.2.0 → 1.2.2

package/README.md

@@ -3,7 +3,7 @@
 **Wallet and go. 💙**  
 _No forms. No email. Just Base. 💙_
 
-mnemospark is an agentic service layer for OpenClaw and a standalone x402 payment and wallet-proof verification backend. It provides encrypted, authenticated, and fully autonomous access to cloud infrastructure and proprietary data, paid via x402 with USDC on Base. No human onboarding. No API keys. The blockchain transaction is the record.
+mnemospark is an agentic service layer for OpenClaw plus a standalone x402 payment + verification backend. It enables encrypted, authenticated, fully autonomous cloud and data workflows—paid via x402 with USDC on Base. No human onboarding. No API keys. The blockchain transaction is the record.
 
 ---
 
@@ -11,7 +11,7 @@ mnemospark is an agentic service layer for OpenClaw and a standalone x402 paymen
 
 mnemospark connects OpenClaw agents to cloud workflows with wallet-native auth + payment rails.
 
-- **Wallet-proof authentication** for storage/API actions
+- **Wallet-native authentication** for storage/API actions
 - **x402-native payments** with USDC on Base
 - **Agent-first flow** (quote → pay → provision)
 - **Encrypted payload support** and structured request signing
@@ -24,7 +24,7 @@ mnemospark connects OpenClaw agents to cloud workflows with wallet-native auth +
 ### 1) Install the plugin in OpenClaw
 
 ```bash
-openclaw plugins install mnemospark
+openclaw plugins install mnemospark --dangerously-force-unsafe-install
 openclaw gateway start
 ```
 
@@ -52,40 +52,63 @@ openclaw gateway restart
 
 ---
 
+## Slash command reference
+
+**Syntax**
+
+- **Chat / OpenClaw (primary):** use `key:value` for arguments (for example `wallet-address:0x…`, `region:us-east-1`). `key=value` is also accepted.
+- **Agent-driven workflows and CLI-style usage:** prefer `--parameter value` (for example `npx mnemospark` or shell scripts).
+
+**Top-level routes** (after `/mnemospark`)
+
+- `/mnemospark` or `/mnemospark help` — overview
+- `/mnemospark cloud …` — cloud storage (see below)
+- `/mnemospark wallet …` — wallet helpers
+
+**`/mnemospark cloud`** — includes: `cloud` / `cloud help`, `backup`, `price-storage`, `upload`, `payment-settle`, `ls`, `download`, `delete`, `op-status`. Optional flags include `async:true`, `orchestrator:inline|subagent`, `timeout-seconds:<n>`. For the full cloud guide, run `/mnemospark cloud help` in chat.
+
+**`/mnemospark wallet`**
+
+- `/mnemospark wallet` — address, balance, and key file path
+- `/mnemospark wallet help` — command list and funding link
+- `/mnemospark wallet export` — export private key for backup (sensitive)
+
+---
+
 ## Core Commands
 
-Use via `/mnemospark cloud …` (or `/mnemospark wallet …`) in OpenClaw chat.
+Use via `/mnemospark cloud …` (or `/mnemospark wallet …`) in OpenClaw chat. Prefer `key:value` in chat; use `--wallet-address` style for scripted or agent-driven flows.
 
 ### Get a storage quote
 
 ```text
-/mnemospark cloud price-storage --wallet-address <addr> --object-id <id> --object-id-hash <sha256> --gb <gb> --provider aws --region us-east-1
+/mnemospark cloud price-storage wallet-address:<addr> object-id:<id> object-id-hash:<sha256> gb:<gb> provider:aws region:us-east-1
 ```
 
-Use other regions by changing `--provider` and `--region` (defaults: `aws` / `us-east-1`).
+Use other regions by changing `provider:` and `region:` (defaults: `aws` / `us-east-1`).
 
 ### Upload using quote
 
 ```text
-/mnemospark cloud upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <sha256>
+/mnemospark cloud upload quote-id:<quote-id> wallet-address:<addr> object-id:<id> object-id-hash:<sha256>
 ```
 
 ### List objects
 
 ```text
-/mnemospark cloud ls --wallet-address <addr> --object-key <object-key>
+/mnemospark cloud ls wallet-address:<addr> object-key:<object-key>
 ```
 
 ### Download object
 
 ```text
-/mnemospark cloud download --wallet-address <addr> --object-key <object-key>
+/mnemospark cloud download wallet-address:<addr> object-key:<object-key>
 ```
 
 ### Delete object
 
 ```text
-/mnemospark cloud delete --wallet-address <addr> --object-key <object-key>
+/mnemospark cloud delete wallet-address:<addr> object-key:<object-key>
 ```
 
 ---
@@ -95,7 +118,7 @@ Use other regions by changing `--provider` and `--region` (defaults: `aws` / `us
 mnemospark follows a quote-and-pay execution model:
 
 1. Agent requests a quote.
-2. Agent provides wallet-proof + payment authorization.
+2. Agent provides wallet-native + payment authorization.
 3. Backend verifies payment/auth context.
 4. Storage action executes.
 
@@ -128,6 +151,7 @@ Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 | `MNEMOSPARK_DISABLED`             | Set to `true` or `1` to disable plugin registration.                                                                                                                                                                                      |
 | `MNEMOSPARK_DISABLE_SQLITE`       | Set to `1` to disable local SQLite (`state.db`); cloud commands that need local state will fail.                                                                                                                                          |
 | `MNEMOSPARK_SQLITE_STRICT`        | Set to `1` so certain SQLite consistency checks (e.g. friendly-name verification after upload) throw instead of warning.                                                                                                                  |
+| `MNEMOSPARK_PROXY_VERBOSE_404`    | When `1`, `true`, or `yes`, the local HTTP proxy includes a `message` field on **404** responses describing supported paths. Default (unset) is a generic JSON body `{ "error": "Not found" }` only (reduces reconnaissance).             |
 
 ---
 
@@ -141,11 +165,23 @@ Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 
 ---
 
+## OpenClaw Install Warning
+
+If OpenClaw shows a warning about **dangerous code patterns** when installing or updating mnemospark—often mentioning shell execution (`child_process`), environment variables, and network access—here is what is going on.
+
+mnemospark is an **OpenClaw plugin** that talks to **your configured mnemospark backend**, runs a **local HTTP proxy** for storage workflows, and can **invoke the `openclaw` CLI** and system tools when needed (for example creating archives with `tar` or running `npm` when you use the update command). Those features use the same low-level Node.js APIs—`child_process` and `fetch`—that security tools also associate with risky software, so the installer may warn you even when the behavior is intentional and benign.
+
+We also read **environment variables** you set on purpose (such as `MNEMOSPARK_BACKEND_API_BASE_URL`, `MNEMOSPARK_PROXY_PORT`, or wallet-related settings) so you can configure the plugin without editing code. Automated scans sometimes flag “environment access + network” as a possible credential-stealing pattern. In mnemospark, that combination exists because the plugin is **configurable and networked by design**, not because we are harvesting your unrelated secrets.
+
+mnemospark is **open source**. If you want extra assurance, review the repository, search for `child_process`, `process.env`, and `fetch`, and run your own tests in a safe environment. The warning helps keep the ecosystem safe; for mnemospark it reflects **capabilities**, not a finding of malicious intent.
+
+---
+
 ## Troubleshooting
 
 - **Missing wallet/auth errors**: verify wallet key is present and request signature headers are generated.
 - **402 payment required**: expected in challenge flow; ensure client retries with payment authorization.
-- **Upload/storage backend errors**: verify cloud permissions (e.g., bucket access + IAM role rights).
+- **Upload/storage backend errors**: verify cloud permissions (e.g. bucket access + IAM role rights).
 - **Command not recognized**: confirm plugin installed and gateway restarted.
 - **One-step operation correlation**: run `./skills/mnemospark/scripts/debug-operation.sh <operation-id>` (or omit ID to use latest).
 

package/dist/cli.js

@@ -157,6 +157,10 @@ var PROXY_PORT = (() => {
   return DEFAULT_PORT;
 })();
 var MNEMOSPARK_BACKEND_API_BASE_URL = (process.env.MNEMOSPARK_BACKEND_API_BASE_URL ?? "").trim();
+var MNEMOSPARK_PROXY_VERBOSE_404 = (() => {
+  const v = process.env.MNEMOSPARK_PROXY_VERBOSE_404?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+})();
 
 // src/mnemospark-request-sign.ts
 import { getAddress } from "viem";
@@ -1733,8 +1737,15 @@ async function readProxyJsonBody(req) {
   }
   return JSON.parse(bodyText);
 }
+function createJsonResponseHeaders() {
+  return {
+    "Content-Type": "application/json",
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store"
+  };
+}
 function sendJson(res, status, body) {
-  res.writeHead(status, { "Content-Type": "application/json" });
+  res.writeHead(status, createJsonResponseHeaders());
   res.end(JSON.stringify(body));
 }
 function logProxyEvent(level, event, fields = {}) {
@@ -1794,7 +1805,9 @@ function isAlreadySettledConflict(status, bodyText) {
 }
 function createBackendForwardHeaders(response) {
   const responseHeaders = {
-    "Content-Type": response.contentType
+    "Content-Type": response.contentType,
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store"
   };
   if (response.paymentRequired) {
     responseHeaders["PAYMENT-REQUIRED"] = response.paymentRequired;
@@ -1832,6 +1845,10 @@ function createWalletRequiredBody() {
     message: "wallet required for storage endpoints"
   });
 }
+function sendWalletRequired(res) {
+  res.writeHead(400, createJsonResponseHeaders());
+  res.end(createWalletRequiredBody());
+}
 function getProxyPort() {
   return PROXY_PORT;
 }
@@ -1931,6 +1948,18 @@ async function startProxy(options) {
         }
         correlation.wallet_address = requestPayload.wallet_address;
         correlation.object_id = requestPayload.object_id;
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_price_storage_wallet_mismatch", {
+            request_wallet: requestPayload.wallet_address,
+            proxy_wallet: account.address
+          });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
         emitProxyEvent("storage.call", "start", correlation, { target: "price-storage" });
         const walletSignature = await createBackendWalletSignature(
           "POST",
@@ -1939,8 +1968,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_price_storage_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2089,8 +2117,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_payment_settle_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2198,8 +2225,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_upload_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2246,8 +2272,7 @@ async function startProxy(options) {
         );
         if (!settleWalletSignature) {
           logProxyEvent("warn", "proxy_upload_settle_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "settle_signature_missing" });
           return;
         }
@@ -2387,8 +2412,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_upload_confirm_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2482,8 +2506,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_ls_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2577,8 +2600,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_download_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2694,8 +2716,7 @@ async function startProxy(options) {
         );
         if (!walletSignature) {
           logProxyEvent("warn", "proxy_delete_wallet_signature_missing");
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(createWalletRequiredBody());
+          sendWalletRequired(res);
           emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
@@ -2765,10 +2786,14 @@ async function startProxy(options) {
       sendJson(res, 200, response);
       return;
     }
-    sendJson(res, 404, {
-      error: "Not found",
-      message: "Supported paths: /health and /mnemospark/* storage endpoints"
-    });
+    if (MNEMOSPARK_PROXY_VERBOSE_404) {
+      sendJson(res, 404, {
+        error: "Not found",
+        message: "Supported paths: /health and /mnemospark/* storage endpoints"
+      });
+    } else {
+      sendJson(res, 404, { error: "Not found" });
+    }
   });
   const tryListen = (attempt) => {
     return new Promise((resolveAttempt, rejectAttempt) => {
@@ -4114,7 +4139,8 @@ var priceStorageSchema = {
   args: [
     { name: "wallet-address", aliases: ["wallet"], required: true },
     { name: "object-id", aliases: ["object"], required: true },
-    { name: "object-id-hash", aliases: ["hash"], required: true },
+    // Optional: omit when the object exists in local SQLite after backup; CLI resolves sha256 from state.db.
+    { name: "object-id-hash", aliases: ["hash"] },
     { name: "gb", required: true },
     { name: "provider", required: true },
     { name: "region", required: true }
@@ -4206,7 +4232,7 @@ var TAR_OVERHEAD_BYTES = 10 * 1024 * 1024;
 var QUOTE_VALIDITY_USER_NOTE = "Quotes are valid for one hour. Please run price-storage again if you need a new quote.";
 var MNEMOSPARK_SUPPORT_EMAIL = "pluggedin@mnemospark.ai";
 var CLOUD_HELP_FOOTER_STATE = "Local state: mnemospark records quotes, objects, payments, cron jobs, friendly names, and operation metadata in ~/.openclaw/mnemospark/state.db (SQLite). For troubleshooting and correlation, commands and the HTTP proxy append structured JSON lines to ~/.openclaw/mnemospark/events.jsonl. Monthly storage billing jobs are listed in ~/.openclaw/cron/jobs.json for OpenClaw scheduling.";
-var REQUIRED_PRICE_STORAGE = "wallet-address:, object-id:, object-id-hash:, gb:, provider:, region:";
+var REQUIRED_PRICE_STORAGE = "wallet-address:, object-id:, gb:, provider:, region: (object-id-hash: optional if the object exists in local SQLite after backup)";
 var REQUIRED_UPLOAD = "quote-id:, wallet-address:, object-id:, object-id-hash:";
 var REQUIRED_BACKUP = "<file|directory> and name:<friendly-name>";
 var REQUIRED_PAYMENT_SETTLE = "wallet-address: and (quote-id: | renewal:true with object-key:)";
@@ -4236,10 +4262,10 @@ var CLOUD_HELP_TEXT = [
   "  Purpose: create a local tar+gzip archive under ~/.openclaw/mnemospark/backup (filename from sanitized friendly name) and record metadata in SQLite for later price-storage and upload.",
   "  Required: " + REQUIRED_BACKUP,
   "",
-  "\u2022 `/mnemospark cloud price-storage wallet-address:<addr> object-id:<id> object-id-hash:<hash> gb:<gb> provider:aws region:us-east-1`",
-  "  Purpose: request a storage quote before upload (defaults shown; override `provider:` / `region:` for other regions).",
+  "\u2022 `/mnemospark cloud price-storage wallet-address:<addr> object-id:<id> [object-id-hash:<hash>] gb:<gb> provider:aws region:us-east-1`",
+  "  Purpose: request a storage quote before upload (defaults shown; override `provider:` / `region:` for other regions). Omit `object-id-hash:` when the object is already in local SQLite (e.g. after backup); mnemospark reads sha256 from ~/.openclaw/mnemospark/state.db.",
   "  Required: " + REQUIRED_PRICE_STORAGE,
-  "  Shorter: `wallet:\u2026 object:\u2026 hash:\u2026 gb:\u2026 provider:\u2026 region:\u2026`",
+  "  Shorter: `wallet:\u2026 object:\u2026 [hash:\u2026] gb:\u2026 provider:\u2026 region:\u2026`",
   "",
   "\u2022 `/mnemospark cloud upload quote-id:<quote-id> wallet-address:<addr> object-id:<id> object-id-hash:<hash> [name:<friendly-name>] [async:true] [orchestrator:<inline|subagent>] [timeout-seconds:<n>]`",
   "  Purpose: upload an encrypted object using a valid quote-id.",
@@ -4450,6 +4476,41 @@ function stripAsyncControlFlags(args) {
 function mergeArgParseWarnings(a, b) {
   return [...a, ...b];
 }
+async function resolvePriceStorageHashFromDatastore(datastore, partial) {
+  await datastore.ensureReady();
+  const row = await datastore.findObjectById(partial.object_id.trim());
+  const wallet = partial.wallet_address.trim().toLowerCase();
+  if (!row) {
+    return {
+      ok: false,
+      message: "Cannot resolve object-id-hash: no object found in local SQLite for this object-id. Run backup first, or pass --object-id-hash explicitly."
+    };
+  }
+  if (row.wallet_address.trim().toLowerCase() !== wallet) {
+    return {
+      ok: false,
+      message: "Cannot resolve object-id-hash: wallet-address does not match the object record in ~/.openclaw/mnemospark/state.db."
+    };
+  }
+  const sha = row.sha256?.trim();
+  if (!sha) {
+    return {
+      ok: false,
+      message: "Cannot resolve object-id-hash: local object record has no sha256 yet. Run backup first, or pass --object-id-hash explicitly."
+    };
+  }
+  return {
+    ok: true,
+    request: {
+      wallet_address: partial.wallet_address.trim(),
+      object_id: partial.object_id.trim(),
+      object_id_hash: sha.replace(/\s/g, ""),
+      gb: partial.gb,
+      provider: partial.provider.trim(),
+      region: partial.region.trim()
+    }
+  };
+}
 function parseCloudArgs(args) {
   const trimmed = args?.trim() ?? "";
   if (!trimmed) {
@@ -4519,18 +4580,38 @@ function parseCloudArgs(args) {
     }
     const flags = valuesToStringRecord(parsed.values);
     const gb = Number.parseFloat(flags.gb ?? "");
-    const request = parsePriceStorageQuoteRequest({
-      wallet_address: flags["wallet-address"],
-      object_id: flags["object-id"],
-      object_id_hash: flags["object-id-hash"],
-      gb,
-      provider: flags.provider,
-      region: flags.region
-    });
-    if (!request) {
+    const hashRaw = flags["object-id-hash"]?.trim();
+    const walletAddress = flags["wallet-address"]?.trim();
+    const objectId = flags["object-id"]?.trim();
+    const provider = flags.provider?.trim();
+    const region = flags.region?.trim();
+    if (!walletAddress || !objectId || !provider || !region || !Number.isFinite(gb)) {
       return { mode: "price-storage-invalid" };
     }
-    return { mode: "price-storage", priceStorageRequest: request };
+    if (hashRaw) {
+      const request = parsePriceStorageQuoteRequest({
+        wallet_address: walletAddress,
+        object_id: objectId,
+        object_id_hash: hashRaw,
+        gb,
+        provider,
+        region
+      });
+      if (!request) {
+        return { mode: "price-storage-invalid" };
+      }
+      return { mode: "price-storage", priceStorageRequest: request };
+    }
+    return {
+      mode: "price-storage-resolve-hash",
+      priceStoragePartial: {
+        wallet_address: walletAddress,
+        object_id: objectId,
+        gb,
+        provider,
+        region
+      }
+    };
   }
   if (subcommand === "upload") {
     const parsed = parseCommandArgs(rest, uploadSchema);
@@ -6667,10 +6748,23 @@ operation-id: ${operationId}`,
       };
     }
   }
-  if (parsed.mode === "price-storage") {
+  if (parsed.mode === "price-storage" || parsed.mode === "price-storage-resolve-hash") {
+    let priceStorageRequest;
+    if (parsed.mode === "price-storage-resolve-hash") {
+      const resolved = await resolvePriceStorageHashFromDatastore(
+        datastore,
+        parsed.priceStoragePartial
+      );
+      if (!resolved.ok) {
+        return { text: resolved.message, isError: true };
+      }
+      priceStorageRequest = resolved.request;
+    } else {
+      priceStorageRequest = parsed.priceStorageRequest;
+    }
     const correlation = buildRequestCorrelation();
     try {
-      const quote = await requestPriceStorageQuote(parsed.priceStorageRequest, {
+      const quote = await requestPriceStorageQuote(priceStorageRequest, {
         ...options.proxyQuoteOptions,
         correlation
       });
@@ -6728,8 +6822,8 @@ operation-id: ${operationId}`,
         {
           operation_id: correlation.operationId,
           trace_id: correlation.traceId,
-          wallet_address: parsed.priceStorageRequest.wallet_address,
-          object_id: parsed.priceStorageRequest.object_id,
+          wallet_address: priceStorageRequest.wallet_address,
+          object_id: priceStorageRequest.object_id,
           status: "failed"
         },
         mnemosparkHomeDir