owlmem 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OwlMem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# owlmem
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command line for [OwlMem](https://owlmem.com) — shared memory and an end-to-end encrypted vault for your AI agents.
+
+```sh
+npx owlmem login            # paste the agent's token from the OwlMem console
+npx owlmem vault unlock     # paste your recovery code, once per machine
+npx owlmem vault ls
+npx owlmem run --env DB_PASSWORD=prod/db:password -- ./deploy.sh
+npx owlmem vault import bitwarden_export.json   # also 1Password / KeePass CSV, .env
+```
+
+Vault items are encrypted on your machine with a key only you hold; OwlMem stores ciphertext it cannot read.
+Every read or write needs the space owner's approval in the console (passkey, authenticator app or GitHub).
+
+Let your AI use the vault directly through a local MCP server:
+
+```sh
+claude mcp add owlmem-vault -- npx -y owlmem mcp
+```
+
+Tools: `vault_list`, `vault_run` (secrets are injected into the command and masked in its output), `vault_get`, `vault_put`.
+
+Requires Node 18+. No dependencies.

package/owlmem.mjs

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+// owlmem — OwlMem command line. Zero dependencies (Node 18+ WebCrypto).
+//
+// The vault is end-to-end encrypted: items are encrypted here with your space key (AES-256-GCM) and the
+// server only ever sees ciphertext. Your space key comes from the recovery code shown once when the vault
+// was set up in the console; `owlmem vault unlock` stores it on this machine (0600).
+//
+//   owlmem login                         save this agent's token (from the console)
+//   owlmem vault unlock                  paste the recovery code once per machine
+//   owlmem vault ls
+//   owlmem vault get <name> [field]      prints the item (or one field) to stdout
+//   owlmem vault put <name> [--desc text] < value-or-json
+//   owlmem vault rm <name>
+//   owlmem vault import <file> [--format bitwarden-json|bitwarden-csv|1password-csv|keepass-csv|env] [--prefix folder/]
+//   owlmem vault export [--format bitwarden-json|keepass-csv|env] > file
+//   owlmem run --env VAR=<name>[:field] [...] -- <command> [args]   run a command with secrets in its environment
+//   owlmem vault keygen                  (setup without a browser) print a new recovery code and its key check
+//   owlmem mcp                           local MCP server for your AI (vault_list, vault_run, vault_get, vault_put)
+//                                        e.g. claude mcp add owlmem-vault -- node ~/owlmem.mjs mcp
+//
+// Reading, writing, deleting and exporting need the space owner's approval in the console; this program waits
+// for it (up to 5 minutes). Secrets go to stdout only; messages go to stderr.
+
+import { webcrypto as crypto } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { spawn } from "node:child_process";
+
+export const VERSION = "0.3.0";
+const BASE = (process.env.OWLMEM_URL || "https://app.owlmem.com").replace(/\/$/, "");
+const DIR = process.env.OWLMEM_HOME || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "owlmem");
+const enc = new TextEncoder(), dec = new TextDecoder();
+const say = (...a) => process.stderr.write(a.join(" ") + "\n");
+class Fail extends Error {}
+
+// ── encoding ──
+const B32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+export function b32encode(bytes) {
+  let bits = 0, val = 0, out = "";
+  for (const b of bytes) { val = (val << 8) | b; bits += 8; while (bits >= 5) { out += B32[(val >>> (bits - 5)) & 31]; bits -= 5; } }
+  if (bits > 0) out += B32[(val << (5 - bits)) & 31];
+  return out;
+}
+export function b32decode(s) {
+  let bits = 0, val = 0; const out = [];
+  for (const ch of s) { const i = B32.indexOf(ch); if (i < 0) throw new Fail("That recovery code has a character that doesn't belong in it."); val = (val << 5) | i; bits += 5; if (bits >= 8) { out.push((val >>> (bits - 8)) & 255); bits -= 8; } }
+  return new Uint8Array(out);
+}
+const b64 = (u8) => Buffer.from(u8).toString("base64");
+const unb64 = (s) => new Uint8Array(Buffer.from(s, "base64"));
+
+// ── keys ──
+export function recoveryCode(key) { return "OWL-" + b32encode(key).match(/.{1,4}/g).join("-"); }
+export function parseRecovery(code) {
+  // 终端「括号粘贴」会在前后加 ESC[200~ / ESC[201~，里面的 2、0 会被当成 base32 字符（10-23 站长解锁失败）：先去掉控制序列；
+  // 再只取 OWL- 后面那一段，前后多粘了别的也认得出
+  let s = String(code || "").replace(/\x1b\[[0-9;]*[~A-Za-z]/g, "").replace(/[\x00-\x1f\x7f]/g, "").toUpperCase();
+  const m = /OWL[-\s]*((?:[A-Z2-7]{4}[-\s]*){12}[A-Z2-7]{4})/.exec(s);
+  s = (m ? m[1] : s.replace(/^\s*OWL/, "")).replace(/[^A-Z2-7]/g, "");
+  if (s.length !== 52) throw new Fail(`That doesn't look like a complete recovery code: got ${s.length} code characters, a recovery code has 52 after "OWL-". Copy the whole code and try again.`);
+  const key = b32decode(s);
+  if (key.length !== 32) throw new Fail("That doesn't look like a complete recovery code.");
+  return key;
+}
+const aesKey = (raw) => crypto.subtle.importKey("raw", raw, "AES-GCM", false, ["encrypt", "decrypt"]);
+// AAD binds a ciphertext to its space and item name, so a stored ciphertext can't be moved to another name.
+const aad = (space, name) => enc.encode(space + "\n" + name);
+export async function seal(raw, space, name, obj) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: aad(space, name) }, await aesKey(raw), enc.encode(JSON.stringify(obj)));
+  return { nonce: b64(iv), ciphertext: b64(new Uint8Array(ct)) };
+}
+export async function open(raw, space, name, nonce, ciphertext) {
+  try {
+    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: unb64(nonce), additionalData: aad(space, name) }, await aesKey(raw), unb64(ciphertext));
+    return JSON.parse(dec.decode(pt));
+  } catch { throw new Fail(`Can't decrypt "${name}": wrong space key, or the item was tampered with.`); }
+}
+const KEY_CHECK = "!key-check";
+export async function keyCheck(raw, space) { const s = await seal(raw, space, KEY_CHECK, { owlmem: "key-check-v1" }); return s.nonce + "." + s.ciphertext; }
+export async function verifyKeyCheck(raw, space, kc) {
+  const [n, c] = String(kc).split(".");
+  try { return (await open(raw, space, KEY_CHECK, n, c)).owlmem === "key-check-v1"; } catch { return false; }
+}
+
+// ── config ──
+function cfg() { try { return JSON.parse(readFileSync(join(DIR, "config.json"), "utf8")); } catch { return {}; } }
+function saveFile(path, text) { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); writeFileSync(path, text, { mode: 0o600 }); chmodSync(path, 0o600); }
+function token() {
+  const t = process.env.OWLMEM_TOKEN || cfg().token;
+  if (!t) throw new Fail("No token. Create one for this agent in the console (AI agents & tokens), then run: owlmem login");
+  return t;
+}
+function spaceKey(space) {
+  const p = join(DIR, "keys", space + ".key");
+  if (!existsSync(p)) throw new Fail("This machine doesn't have the space key yet. Run: owlmem vault unlock");
+  return unb64(readFileSync(p, "utf8").trim());
+}
+
+// ── http ──
+async function call(method, path, body) {
+  let r;
+  try {
+    r = await fetch(BASE + "/v1/vault/" + path, { method, headers: { Authorization: "Bearer " + token(), "Content-Type": "application/json", "User-Agent": "owlmem-cli/" + VERSION },
+                                                  body: body === undefined ? undefined : JSON.stringify(body) });
+  } catch (e) { throw new Fail("Can't reach OwlMem (" + BASE + "): " + e.message); }
+  const data = await r.json().catch(() => ({}));
+  return { status: r.status, data };
+}
+// Ask, and if the owner has to approve, wait for it (polling every 3 s, up to 5 minutes), then ask again.
+let WAIT_MS = 5 * 60 * 1000;     // 命令行等 5 分钟；MCP 里只等 30 秒，免得 AI 客户端的工具调用超时
+async function approved(method, path, body, kind = "access") {
+  let extra = "";
+  for (let round = 0; round < 3; round++) {
+    const r = await call(method, path + extra, body);
+    if (r.status < 400) return r.data;
+    if (r.data.error !== "approval_required") throw new Fail(r.data.detail || r.data.error || "HTTP " + r.status);
+    const id = r.data.request;
+    say(`Waiting for approval in the OwlMem console (request ${id}${kind === "access" ? "" : ", " + kind}) …`);
+    const until = Date.now() + WAIT_MS;
+    let st = "pending";
+    while (Date.now() < until) {
+      await new Promise((res) => setTimeout(res, Number(process.env.OWLMEM_POLL_MS || 3000)));
+      st = (await call("GET", "requests/" + id)).data.status;
+      if (st !== "pending") break;
+    }
+    if (st === "pending") throw new Fail(`Waiting for approval (request ${id}). Ask the space owner to approve it in the OwlMem console (Vault), then try again.`);
+    if (st !== "approved") throw new Fail(st === "denied" ? "The request was denied." : "The request expired before it was approved.");
+    say("Approved.");
+    if (kind !== "access") extra = (path.includes("?") ? "&" : "?") + "request=" + encodeURIComponent(id);
+  }
+  throw new Fail("Still not allowed after approval; try again.");
+}
+async function space() { const r = await call("GET", "key-check"); if (r.status >= 400) throw new Fail(r.data.detail || r.data.error); return r.data; }
+const itemPath = (name) => "items/" + name.split("/").map(encodeURIComponent).join("/");
+
+// ── import / export formats ──
+export function parseCSV(text) {
+  const rows = []; let row = [], f = "", q = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (q) { if (c === '"') { if (text[i + 1] === '"') { f += '"'; i++; } else q = false; } else f += c; }
+    else if (c === '"') q = true;
+    else if (c === ",") { row.push(f); f = ""; }
+    else if (c === "\n" || c === "\r") { if (c === "\r" && text[i + 1] === "\n") i++; row.push(f); rows.push(row); row = []; f = ""; }
+    else f += c;
+  }
+  if (f !== "" || row.length) { row.push(f); rows.push(row); }
+  const [head, ...rest] = rows.filter((r) => r.some((x) => x !== ""));
+  return (rest || []).map((r) => Object.fromEntries((head || []).map((h, i) => [h.trim(), r[i] ?? ""])));
+}
+const csvCell = (v) => /[",\n\r]/.test(String(v ?? "")) ? '"' + String(v).replace(/"/g, '""') + '"' : String(v ?? "");
+export function slug(s) { return String(s || "item").toLowerCase().normalize("NFKD").replace(/[^a-z0-9._/-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 90) || "item"; }
+const BW_TYPES = { 1: "login", 2: "note", 3: "card", 4: "identity" };
+
+export function fromBitwardenJSON(text) {
+  const j = JSON.parse(text);
+  if (j.encrypted) throw new Fail("That is an encrypted Bitwarden export. Export again as JSON without a password (the unencrypted format).");
+  return (j.items || []).map((it) => {
+    const body = { type: BW_TYPES[it.type] || "note", title: it.name || "", notes: it.notes || "" };
+    if (it.login) Object.assign(body, { username: it.login.username || "", password: it.login.password || "", totp: it.login.totp || "", uris: (it.login.uris || []).map((u) => u.uri).filter(Boolean) });
+    if (it.card) body.card = it.card;
+    if (it.identity) body.identity = it.identity;
+    if (it.fields?.length) body.fields = Object.fromEntries(it.fields.map((f) => [f.name, f.value]));
+    return { name: slug(it.name), description: it.login?.uris?.[0]?.uri || body.type, body };
+  });
+}
+export function fromBitwardenCSV(text) {
+  return parseCSV(text).map((r) => {
+    const fields = Object.fromEntries((r.fields || "").split("\n").filter(Boolean).map((l) => { const i = l.indexOf(": "); return i < 0 ? [l, ""] : [l.slice(0, i), l.slice(i + 2)]; }));
+    const body = { type: r.type === "note" ? "note" : "login", title: r.name || "", notes: r.notes || "", username: r.login_username || "", password: r.login_password || "",
+                   totp: r.login_totp || "", uris: (r.login_uri || "").split(",").filter(Boolean) };
+    if (Object.keys(fields).length) body.fields = fields;
+    return { name: slug(r.name), description: r.login_uri || body.type, body };
+  });
+}
+export function fromEnv(text, prefix = "env/") {
+  return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#") && l.includes("=")).map((l) => {
+    const i = l.indexOf("="); const key = l.slice(0, i).replace(/^export\s+/, "").trim();
+    let value = l.slice(i + 1).trim();
+    if (/^(['"]).*\1$/.test(value)) value = value.slice(1, -1);
+    return { name: slug(prefix + key), description: "env " + key, body: { type: "env", key, value } };
+  });
+}
+// 1Password CSV export (Title, Website/URL, Username, Password, One-time password/OTPAuth, Notes, plus any extra columns)
+export function from1PasswordCSV(text) {
+  const pick = (r, ...ks) => { for (const k of ks) { const hit = Object.keys(r).find((x) => x.toLowerCase() === k.toLowerCase()); if (hit && r[hit]) return r[hit]; } return ""; };
+  const known = new Set(["title", "website", "url", "urls", "username", "password", "otpauth", "one-time password", "notes", "notesplain", "type", "tags"]);
+  return parseCSV(text).map((r) => {
+    const title = pick(r, "Title"); const url = pick(r, "Website", "URL", "URLs");
+    const fields = Object.fromEntries(Object.entries(r).filter(([k, v]) => v && !known.has(k.toLowerCase())));
+    const body = { type: pick(r, "Password", "Username") ? "login" : "note", title, notes: pick(r, "Notes", "notesPlain"), username: pick(r, "Username"),
+                   password: pick(r, "Password"), totp: pick(r, "OTPAuth", "One-time password"), uris: url ? [url] : [] };
+    if (Object.keys(fields).length) body.fields = fields;
+    return { name: slug(title), description: url || body.type, body };
+  });
+}
+// KeePass 2 / KeePassXC CSV export ("Group","Title","Username","Password","URL","Notes","TOTP",…)
+export function fromKeePassCSV(text) {
+  return parseCSV(text).map((r) => {
+    const group = (r.Group || r.Account || "").replace(/^Root\/?/i, "");
+    const body = { type: "login", title: r.Title || "", notes: r.Notes || "", username: r.Username || r["Login Name"] || "", password: r.Password || "",
+                   totp: r.TOTP || "", uris: (r.URL || r["Web Site"] || "") ? [r.URL || r["Web Site"]] : [] };
+    if (group) body.group = group;
+    return { name: slug((group ? group + "/" : "") + (r.Title || "item")), description: body.uris[0] || "login", body };
+  });
+}
+export function toKeePassCSV(items) {
+  const head = ["Group", "Title", "Username", "Password", "URL", "Notes", "TOTP"];
+  const rows = items.map(({ name, body: b }) => [b.group || name.split("/").slice(0, -1).join("/"), b.title || name.split("/").pop(), b.username || b.key || "",
+    b.password ?? (b.type === "env" || b.type === "secret" ? String(b.value ?? "") : ""), (b.uris || [])[0] || "", b.notes || "", b.totp || ""]);
+  return [head, ...rows].map((r) => r.map(csvCell).join(",")).join("\n") + "\n";
+}
+export function toBitwardenJSON(items) {
+  const T = { login: 1, note: 2, card: 3, identity: 4 };
+  return JSON.stringify({ encrypted: false, folders: [], items: items.map(({ name, body: b }) => {
+    const it = { id: crypto.randomUUID(), organizationId: null, folderId: null, type: T[b.type] || 2, name: b.title || name, notes: b.notes || (b.type === "env" || b.type === "secret" ? String(b.value ?? "") : ""),
+                 favorite: false, fields: Object.entries(b.fields || {}).map(([k, v]) => ({ name: k, value: v, type: 0 })) };
+    if (b.type === "env") it.fields.push({ name: b.key, value: b.value, type: 1 });
+    if (it.type === 1) it.login = { username: b.username || "", password: b.password || "", totp: b.totp || null, uris: (b.uris || []).map((u) => ({ match: null, uri: u })) };
+    if (it.type === 2) it.secureNote = { type: 0 };
+    if (b.card) it.card = b.card;
+    if (b.identity) it.identity = b.identity;
+    return it;
+  }) }, null, 2);
+}
+export function toEnv(items) {
+  return items.filter(({ body }) => body.type === "env" || body.type === "secret")
+    .map(({ name, body }) => `${body.key || name.split("/").pop().toUpperCase().replace(/[^A-Z0-9_]/g, "_")}=${JSON.stringify(String(body.value ?? ""))}`).join("\n") + "\n";
+}
+
+// which CSV is this? by its header row
+export function guessCSV(text) {
+  const head = text.split(/\r?\n/, 1)[0].toLowerCase();
+  if (head.includes("login_username") || head.includes("login_uri")) return "bitwarden-csv";
+  if (head.includes('"group"') || head.startsWith("group,") || head.includes("last modified")) return "keepass-csv";
+  return "1password-csv";
+}
+
+// ── prompts ──
+function readStdin() { return new Promise((res) => { let s = ""; process.stdin.setEncoding("utf8"); process.stdin.on("data", (d) => (s += d)); process.stdin.on("end", () => res(s)); }); }
+function ask(question, hidden = true) {
+  if (!process.stdin.isTTY) return readStdin().then((s) => s.split("\n")[0].trim());
+  return new Promise((res) => {
+    process.stderr.write(question);
+    const stdin = process.stdin; let s = "";
+    stdin.setRawMode(true); stdin.resume(); stdin.setEncoding("utf8");
+    const on = (ch) => {
+      if (ch === "\r" || ch === "\n" || ch === "\u0004") { stdin.setRawMode(false); stdin.pause(); stdin.off("data", on); process.stderr.write("\n"); res(s.trim()); }
+      else if (ch === "\u0003") { process.stderr.write("\n"); process.exit(130); }
+      else if (ch === "\u007f" || ch === "\b") { if (s) { s = s.slice(0, -1); process.stderr.write("\b \b"); } }
+      else { for (const c of ch) { if (c < " ") continue; s += c; process.stderr.write(hidden ? "•" : c); } }   // 粘贴时整段一起来；隐藏输入也给个「•」，免得以为卡住了
+    };
+    stdin.on("data", on);
+  });
+}
+
+// ── commands ──
+function flag(args, name, dflt) { const i = args.indexOf(name); if (i < 0) return dflt; const v = args[i + 1]; args.splice(i, 2); return v; }
+async function fetchItem(name) {
+  const sp = await space(); const raw = spaceKey(sp.space);
+  const it = await approved("GET", itemPath(name));
+  return open(raw, sp.space, name, it.nonce, it.ciphertext);
+}
+function pick(body, field) {
+  if (!field) return body.type === "env" || body.type === "secret" ? String(body.value ?? "") : JSON.stringify(body, null, 2);
+  const v = body[field] ?? body.fields?.[field];
+  if (v === undefined) throw new Fail(`No field "${field}". Fields: ${[...Object.keys(body), ...Object.keys(body.fields || {})].join(", ")}`);
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+
+// ── local MCP server (stdio): lets Claude Code, Codex, Cursor… use the vault. Decryption happens here, on this machine. ──
+const MCP_TOOLS = [
+  { name: "vault_list", description: "List the credentials in the team vault (names and descriptions only; no secrets).", inputSchema: { type: "object", properties: {} } },
+  { name: "vault_run",
+    description: "PREFERRED way to use a secret: run a shell command with vault items injected as environment variables. The secret values are masked as **** in the output returned to you, so they never enter the conversation. Needs the space owner's approval in the OwlMem console the first time (then 15 min – 2 h).",
+    inputSchema: { type: "object", properties: {
+      command: { type: "string", description: "Shell command to run (sh -c)" },
+      env: { type: "object", description: 'Map of ENV_VAR to "item" or "item:field", e.g. {"DB_PASSWORD": "prod/db:password"}', additionalProperties: { type: "string" } },
+      cwd: { type: "string", description: "Working directory (optional)" },
+      timeout_seconds: { type: "integer", description: "Kill the command after this many seconds (default 600)" } }, required: ["command", "env"] } },
+  { name: "vault_get",
+    description: "Read one credential and return it IN PLAIN TEXT into this conversation. Only use it when a secret must be shown or pasted somewhere; to use a secret in a command, call vault_run instead. Needs the owner's approval.",
+    inputSchema: { type: "object", properties: { name: { type: "string" }, field: { type: "string", description: "Optional field, e.g. password or username" } }, required: ["name"] } },
+  { name: "vault_put",
+    description: "Store a credential in the team vault (encrypted on this machine before it is sent). value is a string, or a JSON object such as {\"type\":\"login\",\"username\":\"…\",\"password\":\"…\"}. Needs the owner's approval.",
+    inputSchema: { type: "object", properties: { name: { type: "string", description: "lowercase, e.g. prod/db or env/api_key" }, value: { description: "string or object" }, description: { type: "string" } }, required: ["name", "value"] } },
+];
+async function mcpCall(name, a) {
+  if (name === "vault_list") {
+    const r = await call("GET", "items"); if (r.status >= 400) throw new Fail(r.data.detail || r.data.error);
+    return r.data.items.length ? r.data.items.map((i) => `${i.name}  —  ${i.description || ""}`).join("\n") : "The vault is empty.";
+  }
+  if (name === "vault_get") return pick(await fetchItem(String(a.name || "")), a.field ? String(a.field) : undefined);
+  if (name === "vault_put") {
+    const nm = String(a.name || ""); const body = typeof a.value === "object" && a.value ? a.value : { type: "secret", value: String(a.value ?? "") };
+    const sp = await space(); const raw = spaceKey(sp.space);
+    await approved("PUT", itemPath(nm), { description: String(a.description || ""), ...(await seal(raw, sp.space, nm, body)) });
+    return "Saved " + nm + ".";
+  }
+  if (name === "vault_run") {
+    const env = { ...process.env }, secrets = [];
+    for (const [k, ref] of Object.entries(a.env || {})) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) throw new Fail("Bad variable name " + k);
+      const [item, field] = String(ref).split(":");
+      const v = pick(await fetchItem(item), field); env[k] = v; if (v && v.length >= 4) secrets.push(v);
+    }
+    const mask = (t) => secrets.sort((x, y) => y.length - x.length).reduce((acc, v) => acc.split(v).join("****"), t);
+    const out = await new Promise((res) => {
+      const ch = spawn("sh", ["-c", String(a.command || "")], { env, cwd: a.cwd || process.cwd(), stdio: ["ignore", "pipe", "pipe"] });
+      let o = "", e = ""; const cap = 64 * 1024;
+      ch.stdout.on("data", (d) => { if (o.length < cap) o += d; }); ch.stderr.on("data", (d) => { if (e.length < cap) e += d; });
+      const timer = setTimeout(() => ch.kill("SIGKILL"), 1000 * Number(a.timeout_seconds || 600));
+      ch.on("close", (code, sig) => { clearTimeout(timer); res({ code, sig, o, e }); });
+    });
+    return `exit code: ${out.sig ? "killed (" + out.sig + ")" : out.code}\n--- stdout ---\n${mask(out.o)}${out.e ? "\n--- stderr ---\n" + mask(out.e) : ""}`;
+  }
+  throw new Fail("Unknown tool " + name);
+}
+async function mcpServe() {
+  WAIT_MS = Number(process.env.OWLMEM_MCP_WAIT_MS || 30000);
+  const reply = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
+  let buf = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", async (chunk) => {
+    buf += chunk; let i;
+    while ((i = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1); if (!line) continue;
+      let req; try { req = JSON.parse(line); } catch { reply({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }); continue; }
+      const { id, method, params = {} } = req;
+      if (id === undefined || id === null) continue;                     // notifications
+      if (method === "initialize") reply({ jsonrpc: "2.0", id, result: { protocolVersion: params.protocolVersion || "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "owlmem-vault", version: VERSION } } });
+      else if (method === "ping") reply({ jsonrpc: "2.0", id, result: {} });
+      else if (method === "tools/list") reply({ jsonrpc: "2.0", id, result: { tools: MCP_TOOLS } });
+      else if (method === "tools/call") {
+        try { reply({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: await mcpCall(params.name, params.arguments || {}) }], isError: false } }); }
+        catch (e) { reply({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: e instanceof Fail ? e.message : "Error: " + (e?.message || e) }], isError: true } }); }
+      } else reply({ jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found: " + method } });
+    }
+  });
+  await new Promise((res) => process.stdin.on("end", res));
+}
+
+export async function main(argv) {
+  const [cmd, sub, ...rest] = argv;
+  if (cmd === "--version" || cmd === "version") { console.log(VERSION); return; }
+  if (cmd === "mcp") { await mcpServe(); return; }
+  if (cmd === "login") {
+    const t = (process.env.OWLMEM_TOKEN || await ask("Paste this agent's token (om_…, shown as dots), then Enter: ")).replace(/\x1b\[[0-9;]*[~A-Za-z]/g, "").replace(/[^A-Za-z0-9_-]/g, "");
+    if (!/^om_[A-Za-z0-9_-]{20,80}$/.test(t)) throw new Fail("That doesn't look like an OwlMem agent token (om_…).");
+    process.env.OWLMEM_TOKEN = t;
+    const r = await call("GET", "key-check");
+    if (r.status === 401) throw new Fail("The server didn't accept that token.");
+    saveFile(join(DIR, "config.json"), JSON.stringify({ ...cfg(), token: t }, null, 2));
+    say("Saved. " + (r.status === 404 ? "The vault isn't set up for this space yet (do that in the console)." : "Next: owlmem vault unlock"));
+    return;
+  }
+  if (cmd === "run") {
+    const dash = argv.indexOf("--"); if (dash < 0 || dash === argv.length - 1) throw new Fail("Usage: owlmem run --env VAR=item[:field] ... -- command [args]");
+    const opts = argv.slice(1, dash), command = argv.slice(dash + 1), env = { ...process.env };
+    for (let i = 0; i < opts.length; i++) {
+      if (opts[i] !== "--env") throw new Fail("Unknown option " + opts[i]);
+      const m = /^([A-Za-z_][A-Za-z0-9_]*)=([^:]+)(?::(.+))?$/.exec(opts[++i] || "");
+      if (!m) throw new Fail("Use --env VAR=item or --env VAR=item:field");
+      env[m[1]] = pick(await fetchItem(m[2]), m[3] || (undefined));
+    }
+    const child = spawn(command[0], command.slice(1), { stdio: "inherit", env });
+    await new Promise((res) => child.on("exit", (code, sig) => { process.exitCode = sig ? 1 : code; res(); }));
+    return;
+  }
+  if (cmd !== "vault") { say(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//")).slice(0, 26).map((l) => l.slice(3)).join("\n")); process.exitCode = cmd ? 2 : 0; return; }
+  const args = [...rest];
+  if (sub === "keygen") {
+    const sp = process.env.OWLMEM_SPACE || (await space().catch(() => ({}))).space;
+    if (!sp) throw new Fail("Set OWLMEM_SPACE to the space id (shown in the console).");
+    const raw = crypto.getRandomValues(new Uint8Array(32));
+    console.log(JSON.stringify({ space: sp, recovery_code: recoveryCode(raw), key_check: await keyCheck(raw, sp) }, null, 2));
+    return;
+  }
+  if (sub === "unlock") {
+    const sp = await space();
+    const raw = parseRecovery(await ask("Paste your recovery code (OWL-…, shown as dots), then Enter: "));
+    if (!(await verifyKeyCheck(raw, sp.space, sp.key_check))) throw new Fail("That recovery code doesn't match this space's vault.");
+    saveFile(join(DIR, "keys", sp.space + ".key"), b64(raw));
+    say("Unlocked: this machine can now decrypt the vault of space " + sp.space + ".");
+    return;
+  }
+  if (sub === "ls") {
+    const r = await call("GET", "items"); if (r.status >= 400) throw new Fail(r.data.detail || r.data.error);
+    for (const it of r.data.items) console.log(`${it.name.padEnd(36)} ${it.description}`);
+    return;
+  }
+  if (sub === "get") { const [name, field] = args; if (!name) throw new Fail("Usage: owlmem vault get <name> [field]"); process.stdout.write(pick(await fetchItem(name), field) + (process.stdout.isTTY ? "\n" : "")); return; }
+  if (sub === "put") {
+    const desc = flag(args, "--desc", ""), [name] = args; if (!name) throw new Fail("Usage: owlmem vault put <name> [--desc text] < value-or-json");
+    const text = (await readStdin()).replace(/\n$/, ""); let body;
+    try { body = JSON.parse(text); if (typeof body !== "object" || Array.isArray(body) || !body) throw 0; } catch { body = { type: "secret", value: text }; }
+    const sp = await space(); const raw = spaceKey(sp.space);
+    await approved("PUT", itemPath(name), { description: desc, ...(await seal(raw, sp.space, name, body)) });
+    say("Saved " + name + ".");
+    return;
+  }
+  if (sub === "rm") { const [name] = args; if (!name) throw new Fail("Usage: owlmem vault rm <name>"); await approved("DELETE", itemPath(name), undefined, "delete"); say("Deleted " + name + " (it stays in the vault history)."); return; }
+  if (sub === "import") {
+    const format = flag(args, "--format", null), prefix = flag(args, "--prefix", ""), [file] = args; if (!file) throw new Fail("Usage: owlmem vault import <file> [--format …] [--prefix folder/]");
+    const text = readFileSync(file, "utf8");
+    const fmt = format || (file.endsWith(".json") ? "bitwarden-json" : file.endsWith(".csv") ? guessCSV(text) : "env");
+    const items = fmt === "bitwarden-json" ? fromBitwardenJSON(text) : fmt === "bitwarden-csv" ? fromBitwardenCSV(text) : fmt === "1password-csv" ? from1PasswordCSV(text)
+                : fmt === "keepass-csv" ? fromKeePassCSV(text) : fmt === "env" ? fromEnv(text, prefix || "env/") : null;
+    if (!items) throw new Fail("Formats: bitwarden-json, bitwarden-csv, 1password-csv, keepass-csv, env");
+    const sp = await space(); const raw = spaceKey(sp.space); const seen = new Set();
+    for (const it of items) {
+      let name = slug((fmt === "env" ? "" : prefix) + it.name), n = 2; while (seen.has(name)) name = slug(it.name) + "-" + n++; seen.add(name);
+      await approved("PUT", itemPath(name), { description: it.description, ...(await seal(raw, sp.space, name, it.body)) });
+      say("  imported " + name);
+    }
+    say(`Imported ${items.length} item(s).`);
+    return;
+  }
+  if (sub === "export") {
+    const format = flag(args, "--format", "bitwarden-json");
+    const sp = await space(); const raw = spaceKey(sp.space);
+    const data = await approved("GET", "export", undefined, "export");
+    const items = []; for (const it of data.items) items.push({ name: it.name, body: await open(raw, sp.space, it.name, it.nonce, it.ciphertext) });
+    process.stdout.write(format === "env" ? toEnv(items) : format === "keepass-csv" ? toKeePassCSV(items) : toBitwardenJSON(items));
+    say(`Exported ${items.length} item(s). This file is NOT encrypted — keep it safe and delete it when done.`);
+    return;
+  }
+  throw new Fail("Unknown command. Run owlmem without arguments for help.");
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/owlmem") || process.argv[1]?.endsWith("owlmem.mjs")) {
+  main(process.argv.slice(2)).catch((e) => { say(e instanceof Fail ? e.message : "Error: " + (e?.stack || e)); process.exitCode = 1; });
+}

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "owlmem",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "OwlMem command line: end-to-end encrypted vault for your AI agents, and a local MCP server.",
+  "type": "module",
+  "bin": { "owlmem": "owlmem.mjs" },
+  "files": ["owlmem.mjs", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "homepage": "https://owlmem.com",
+  "keywords": ["mcp", "ai-agents", "vault", "secrets", "claude", "codex", "cursor"],
+  "license": "MIT"
+}