cursor-keys 1.2.4 → 1.3.0

package/README.md

@@ -48,7 +48,29 @@ npm install -g cursor-keys
 
 Requires Node ≥18, the Cursor CLI (`Shell Command: Install 'cursor' in PATH`), and sqlite3 (preinstalled on macOS). Key injection is macOS-only; everything else is cross-platform shaped.
 
-On global install, the companion Cursor extension is linked into `~/.cursor/extensions` automatically and a one-time hint prints (opt out of both: `CURSOR_KEYS_NO_POSTINSTALL=1`). Restart Cursor, then `Cmd+Shift+P` → "cursor-keys: Open Project...".
+The package runs **no install scripts** (`ignore-scripts=true` safe). Link the companion extension once yourself:
+
+```bash
+cursor-keys install-extension   # or install "cursor-keys" from the Open VSX marketplace in Cursor
+```
+
+Restart Cursor, then `Cmd+Shift+P` → "cursor-keys: Open Project...".
+
+## No terminal? Let Cursor's agent set it up
+
+Open your project in Cursor, paste this into the agent chat (`Cmd+L`), and it runs the whole setup for you. Your API key goes into a hidden terminal prompt, never into the chat:
+
+```text
+Set up cursor-keys (github.com/L-ubu/cursor-keys) for this project, step by step:
+1. Run `npm install -g cursor-keys`.
+2. Run `cursor-keys config baseUrl <your-gateway-url>` (replace with my gateway URL, e.g. https://gateway.example.com/v1).
+3. Register this workspace: `cursor-keys add <folder-name> --path <this workspace's path>`.
+4. Run `cursor-keys clone <folder-name>` to inherit my Cursor sign-in and settings.
+5. Run `cursor-keys set-key <folder-name>` and ask me to paste the project API key at the hidden terminal prompt. Never write the key into files, chat, or logs.
+6. Run `cursor-keys doctor <folder-name>` and fix what it flags.
+7. Run `cursor-keys aliases --install` and `cursor-keys wrap --install` for the shell extras.
+8. Open the project in its profile with `cursor-keys open <folder-name>`, then explain how I can tell it worked.
+```
 
 ## Quick start
 
@@ -72,7 +94,7 @@ One-time extras for the full experience:
 ```bash
 cursor-keys wrap --install        # plain `cursor <path>` auto-picks the profile
 cursor-keys aliases --install     # per-project aliases, `ck` shortcut, zsh tab completion
-cursor-keys install-extension     # status bar + wrong-window guard (auto-linked on global npm install)
+cursor-keys install-extension     # status bar + wrong-window guard
 ```
 
 ## How it works
@@ -81,7 +103,7 @@ One window, one profile, one key. Each project gets an isolated `--user-data-dir
 
 Settings flow one way, main to profiles: `sync` re-copies your main `settings.json` into every profile and re-applies that profile's title bar color on top. `open` does this automatically before every launch, and open windows hot-reload the file, so tweaks in your main Cursor show up everywhere. Changes made inside a profile window are overwritten on the next sync.
 
-`clone` copies your main Cursor state (SQLite backup) so profiles open signed-in with your theme and model config. `set-key` encrypts your project key with Cursor's own safeStorage (Chromium OSCrypt, key from the "Cursor Safe Storage" macOS Keychain item) and writes it into the profile's secret store, round-trip verified. macOS asks for Keychain permission once; click Always Allow.
+`clone` copies your main Cursor state (SQLite backup) so profiles open signed-in with your theme and model config, then scrubs donor secrets (`secret://` rows, MCP OAuth tokens, extension secrets) out of the copy. The sign-in session itself is the one thing that does carry over, see [Security](#security). `set-key` encrypts your project key with Cursor's own safeStorage (Chromium OSCrypt, key from the "Cursor Safe Storage" macOS Keychain item) and writes it into the profile's secret store, round-trip verified. When macOS asks for Keychain permission, click **Allow**: one run, one prompt. Always Allow also works, but it permanently grants the calling binary access to that Keychain item, which is the same pattern infostealers abuse against browser safe storage.
 
 ## "Which key am I on?" in three layers
 
@@ -96,7 +118,7 @@ Settings flow one way, main to profiles: `sync` re-copies your main `settings.js
 | `init [--root DIR] [--all]`                    | Discover git repos and register them                            |
 | `add <name> [--path] [--color] [--clone main]` | Create a project profile                                        |
 | `clone <name> [--from main]`                   | Copy sign-in + settings + model config from a donor profile     |
-| `set-key <name> [--key sk-...]`                | Inject the project API key (encrypted, verified)                |
+| `set-key <name>`                               | Inject the project API key (hidden prompt or stdin, encrypted)  |
 | `color <name> [#hex]`                          | Show or set the project title bar color                         |
 | `open [name]`                                  | Launch Cursor with the profile (auto-detect from cwd)           |
 | `status`                                       | Projects, colors, running windows, key configured               |
@@ -107,7 +129,7 @@ Settings flow one way, main to profiles: `sync` re-copies your main `settings.js
 | `wrap [--install]`                             | zsh function so plain `cursor <path>` auto-picks the profile    |
 | `aliases [--install]`                          | Per-project shell aliases (also `ck` shortcut + tab completion) |
 | `completion`                                   | Print zsh tab completion (auto-sourced by `aliases --install`)  |
-| `install-extension`                            | Link the Cursor extension (auto-linked on global npm install)   |
+| `install-extension`                            | Link the Cursor extension (status bar + wrong-window guard)     |
 | `rm <name> [--delete]`                         | Unregister (optionally delete the profile)                      |
 
 `cursor-keys ls` prints registered project names one per line for scripts and tab completion; it is hidden from `--help`.
@@ -137,9 +159,13 @@ cursor-keys config get profilesRoot
 
 ## Security
 
-- Keys go **straight into Cursor's own encrypted store** (`secret://cursorAuth/openAIKey`), encrypted with the same safeStorage mechanism Cursor uses. Never in config files, logs, or stdout.
-- `set-key` reads the "Cursor Safe Storage" Keychain item to encrypt, the same key Cursor itself uses. Nothing leaves your machine.
-- `clone` copies `state.vscdb` locally via SQLite backup. The donor can keep running; the target profile window must be closed.
+Full threat model in [SECURITY.md](SECURITY.md). The short version:
+
+- Keys go **straight into Cursor's own encrypted store** (`secret://cursorAuth/openAIKey`), encrypted with the same safeStorage mechanism Cursor uses. Never in config files, logs, or stdout. `set-key` takes the key from a hidden prompt or stdin, so it never appears in shell history or a process list.
+- `set-key` reads the "Cursor Safe Storage" Keychain item to encrypt, the same key Cursor itself uses. Nothing leaves your machine. Click **Allow** at the prompt; Always Allow permanently ACLs the calling binary to that item.
+- `clone` copies `state.vscdb` locally via SQLite backup, then **scrubs donor secrets from the copy**: all `secret://` rows (the donor's API key, extension secrets) and MCP OAuth tokens are deleted. MCP servers re-auth once per profile.
+- What clone deliberately keeps is your Cursor **sign-in session** (so profiles open signed-in). That means N profiles hold N+1 copies of the session tokens, stored exactly as Cursor stores them. Delete profiles you no longer use: `cursor-keys rm <name> --delete`.
+- Supply chain: zero runtime dependencies, **no install scripts**, and releases are published from GitHub Actions with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) over OIDC trusted publishing (no long-lived npm token).
 
 ## Known limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-keys",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Per-project Cursor profiles so each window uses the correct BYOK API key. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -13,8 +13,7 @@
   "files": [
     "bin",
     "src",
-    "extension",
-    "scripts"
+    "extension"
   ],
   "keywords": [
     "cursor",
@@ -32,7 +31,6 @@
   },
   "scripts": {
     "test": "node --test",
-    "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "npm test"
   }
 }

package/src/commands.mjs

@@ -215,7 +215,9 @@ async function cmdConfig(args) {
     console.log(
       `${bold}Config${reset} ${dim}(${collapseHome(CONFIG_FILE)})${reset}`,
     );
-    console.log(`  baseUrl:      ${config.baseUrl}`);
+    console.log(
+      `  baseUrl:      ${config.baseUrl || `${dim}(not set: cursor-keys config baseUrl <url>)${reset}`}`,
+    );
     console.log(`  profilesRoot: ${config.profilesRoot}`);
     console.log(
       `  projects:     ${count} registered ${dim}(see cursor-keys status)${reset}`,
@@ -382,7 +384,7 @@ async function cmdAdd(args) {
     }
   }
 
-  createProfile({
+  const { scrubbed } = createProfile({
     profileDir: project.profileDir,
     projectName: name,
     color,
@@ -392,6 +394,11 @@ async function cmdAdd(args) {
   console.log(ok(`Profile ready: ${collapseHome(project.profileDir)}`));
   console.log(`  Repo:  ${collapseHome(project.path)}`);
   console.log(`  Color: ${color} ${blockSwatch(color)}`);
+  if (cloneFrom) {
+    console.log(
+      `  ${dim}Scrubbed ${scrubbed} donor secret row(s) from the clone; sign-in retained.${reset}`,
+    );
+  }
   if (shouldShowFirstRunChecklist(project.profileDir)) {
     printFirstRunChecklist(name, config.baseUrl);
   }
@@ -483,6 +490,26 @@ async function cmdStatus() {
   });
 
   printTable(["Project", "Color", "Windows", "Key", "Repo"], rows);
+  if (!companionExtensionLinked()) {
+    console.log(
+      `\n${dim}Companion extension not linked: cursor-keys install-extension (status bar + wrong-window guard)${reset}`,
+    );
+  }
+}
+
+/**
+ * Best-effort check that the companion extension is linked into Cursor.
+ * Looks for the lubu.cursor-keys-* folder the extension manifest produces.
+ */
+function companionExtensionLinked() {
+  try {
+    const extDir = path.join(os.homedir(), ".cursor", "extensions");
+    return fs
+      .readdirSync(extDir)
+      .some((d) => d.startsWith("lubu.cursor-keys"));
+  } catch {
+    return false;
+  }
 }
 
 async function cmdCurrent() {
@@ -562,9 +589,16 @@ async function cmdDoctor(args) {
       console.log(
         `  ${stateDbHasKey(db, SUBAGENT_OVERRIDES_KEY) ? ok("✓") : warn("✗")} Explore subagent overrides present`,
       );
-      console.log(
-        `  ${stateDbValueContains(db, baseUrlFragment(config)) ? ok("✓") : warn("✗")} Base URL (${baseUrlFragment(config)}) in profile state`,
-      );
+      const fragment = baseUrlFragment(config);
+      if (fragment) {
+        console.log(
+          `  ${stateDbValueContains(db, fragment) ? ok("✓") : warn("✗")} Base URL (${fragment}) in profile state`,
+        );
+      } else {
+        console.log(
+          `  ${dim}- baseUrl not set, skipping gateway check: cursor-keys config baseUrl <url>${reset}`,
+        );
+      }
     } else {
       console.log(`  ${warn("✗")} Open profile once: cursor-keys open ${name}`);
     }
@@ -814,10 +848,13 @@ async function cmdClone(args) {
     donorRoot = donor.profileDir;
   }
 
-  cloneStateDb(donorRoot, project.profileDir);
+  const scrubbed = cloneStateDb(donorRoot, project.profileDir);
   console.log(ok(`Cloned state from ${from} into ${name}`));
   console.log(
-    `${dim}Sign-in, settings, and model config carried over. Now set the project key:${reset}`,
+    `${dim}Scrubbed ${scrubbed} donor secret row(s) from the copy (API keys, MCP OAuth, extension secrets); sign-in retained.${reset}`,
+  );
+  console.log(
+    `${dim}Settings and model config carried over. Now set the project key:${reset}`,
   );
   console.log(`  cursor-keys set-key ${name}`);
 }
@@ -879,6 +916,14 @@ async function cmdColor(args) {
   console.log(`${dim}Open Cursor windows reload settings automatically.${reset}`);
 }
 
+/**
+ * Read the API key from piped stdin. Only called when stdin is not an
+ * interactive TTY; interactive runs get the hidden prompt instead.
+ */
+function readStdinKey() {
+  return fs.readFileSync(0, "utf8").trim();
+}
+
 function promptHidden(question) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -899,18 +944,24 @@ function promptHidden(question) {
 async function cmdSetKey(args) {
   const { flags, positional } = parseFlags(args);
   if (flags.help) {
-    console.log("Usage: cursor-keys set-key <name> [--key sk-...]");
+    console.log("Usage: cursor-keys set-key <name>");
     console.log(
       "Writes the key into the profile's encrypted store (Cursor must",
     );
     console.log(
-      "not have that profile window open). Prompts hidden if --key omitted.",
+      "not have that profile window open). Hidden prompt when interactive;",
     );
+    console.log("reads stdin when piped. No inline key flag exists:");
+    console.log("shell history and process lists are not secret-safe.");
     return;
   }
   const name = positional[0];
-  if (!name)
-    throw new Error("Usage: cursor-keys set-key <name> [--key sk-...]");
+  if (!name) throw new Error("Usage: cursor-keys set-key <name>");
+  if (flags.key !== undefined) {
+    throw new Error(
+      `Inline --key is not accepted: shell history and process lists are not secret-safe. Use the hidden prompt or pipe stdin instead: op read op://vault/item/password | cursor-keys set-key ${name}`,
+    );
+  }
 
   const config = loadConfig();
   const project = getProject(config, name);
@@ -926,8 +977,10 @@ async function cmdSetKey(args) {
     throw new Error(`Close the "${name}" Cursor window first, then retry.`);
   }
 
-  let key = flags.key;
-  if (!key) {
+  let key;
+  if (!process.stdin.isTTY) {
+    key = readStdinKey();
+  } else {
     console.log(
       `\nPaste the API key for ${bold}${name}${reset} below, then press Enter.`,
     );

package/src/config.mjs

@@ -48,7 +48,9 @@ export function collapseHome(p) {
 export function defaultConfig() {
   return {
     profilesRoot: collapseHome(DEFAULT_PROFILES_ROOT),
-    baseUrl: "https://connect.iobonzai.com/cursor",
+    // No built-in gateway URL: every install sets its own via
+    // `cursor-keys config baseUrl <url>`.
+    baseUrl: "",
     projects: {},
   };
 }
@@ -97,10 +99,7 @@ export function validateConfig(data) {
     typeof data.profilesRoot === "string"
       ? data.profilesRoot
       : collapseHome(DEFAULT_PROFILES_ROOT);
-  const baseUrl =
-    typeof data.baseUrl === "string" && data.baseUrl
-      ? data.baseUrl
-      : "https://connect.iobonzai.com/cursor";
+  const baseUrl = typeof data.baseUrl === "string" ? data.baseUrl : "";
   const projects = {};
   if (data.projects && typeof data.projects === "object") {
     for (const [name, entry] of Object.entries(data.projects)) {
@@ -120,7 +119,7 @@ export function validateConfig(data) {
   return { profilesRoot, baseUrl, projects };
 }
 
-/** "https://connect.iobonzai.com/cursor" -> "connect.iobonzai.com/cursor" */
+/** "https://gateway.example.com/v1" -> "gateway.example.com/v1" */
 export function baseUrlFragment(config) {
   return String(config.baseUrl || "").replace(/^https?:\/\//, "");
 }

package/src/detect.mjs

@@ -166,7 +166,8 @@ export function stateDbKeysLike(stateDbPath, likePattern) {
 }
 
 /**
- * Check if Bonzai base URL appears in any ItemTable value (substring, no key dump)
+ * Check if a URL fragment (e.g. the configured gateway base URL) appears in
+ * any ItemTable value (substring, no key dump)
  * @param {string} stateDbPath
  * @param {string} urlFragment
  */
@@ -211,4 +212,3 @@ function shellQuote(s) {
 
 export const SECRET_OPENAI_KEY = "secret://cursorAuth/openAIKey";
 export const SUBAGENT_OVERRIDES_KEY = "cursor/subagentModelOverrides";
-export const BONZAI_BASE_URL_FRAGMENT = "connect.iobonzai.com/cursor";

package/src/profile.mjs

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -80,9 +80,18 @@ export function symlinkSharedUserFiles(profileDir) {
   }
 }
 
+/**
+ * Row patterns scrubbed from every cloned state DB. Donor secrets (API keys,
+ * MCP OAuth tokens, extension secrets) never propagate into project profiles.
+ * The Cursor sign-in session (cursorAuth/*) intentionally stays: profiles
+ * open signed-in, which is the whole point of clone.
+ */
+export const CLONE_SCRUB_LIKE_PATTERNS = ["secret://%", "mcpOAuth.%"];
+
 /**
  * @param {string} donorProfileDir - main Cursor or another profile root (parent of User)
  * @param {string} targetProfileDir
+ * @returns {number} how many donor secret rows were scrubbed from the copy
  */
 export function cloneStateDb(donorProfileDir, targetProfileDir) {
   const runningProfiles = listRunningCursorProfiles();
@@ -126,6 +135,29 @@ export function cloneStateDb(donorProfileDir, targetProfileDir) {
   execSync(`sqlite3 ${shellQuote(src)} "VACUUM INTO ${shellQuote(dest)}"`, {
     stdio: "ignore",
   });
+
+  return scrubClonedSecrets(dest);
+}
+
+/**
+ * Delete donor secret rows from a freshly cloned state DB (keys only, values
+ * are never read). Returns the number of deleted rows.
+ * @param {string} stateDbPath
+ */
+export function scrubClonedSecrets(stateDbPath) {
+  let scrubbed = 0;
+  for (const pattern of CLONE_SCRUB_LIKE_PATTERNS) {
+    const out = execFileSync(
+      "sqlite3",
+      [
+        stateDbPath,
+        `DELETE FROM ItemTable WHERE key LIKE '${pattern}'; SELECT changes();`,
+      ],
+      { encoding: "utf8" },
+    );
+    scrubbed += parseInt(out.trim(), 10) || 0;
+  }
+  return scrubbed;
 }
 
 function shellQuote(s) {
@@ -150,19 +182,23 @@ export function needsFirstRunChecklist(profileDir) {
  */
 export function buildFirstRunChecklist(
   projectName,
-  baseUrl = "https://gateway.example.com/v1",
+  baseUrl = "",
   platform = process.platform,
 ) {
+  const gateway = baseUrl || "https://gateway.example.com/v1";
+  const gatewayStep = baseUrl
+    ? ""
+    : `  cursor-keys config baseUrl <your-gateway-url>   # one-time, e.g. ${gateway}\n`;
   if (platform === "darwin") {
     return `
 First-time setup for "${projectName}" · copy-paste in order:
 
-  cursor-keys clone ${projectName}    # inherit sign-in, settings, model config from main Cursor
+${gatewayStep}  cursor-keys clone ${projectName}    # inherit sign-in, settings, model config from main Cursor
   cursor-keys set-key ${projectName}  # inject the project API key (encrypted, hidden prompt)
   cursor-keys doctor ${projectName}   # verify the profile
 
 Manual alternative: Cursor Settings → Models → API keys, paste the key under
-OpenAI API Key, enable "Override OpenAI Base URL" with: ${baseUrl}
+OpenAI API Key, enable "Override OpenAI Base URL" with: ${gateway}
 
 Already inside this profile's window? Close it before running clone or set-key.
 `;
@@ -171,12 +207,12 @@ Already inside this profile's window? Close it before running clone or set-key.
   return `
 First-time setup for "${projectName}" · copy-paste in order:
 
-  cursor-keys clone ${projectName}    # inherit sign-in, settings, model config from main Cursor
+${gatewayStep}  cursor-keys clone ${projectName}    # inherit sign-in, settings, model config from main Cursor
   cursor-keys open ${projectName}     # open once so Cursor creates its state
   cursor-keys doctor ${projectName}   # verify the profile
 
 Then in that window: Cursor Settings → Models → API keys, paste the key under
-OpenAI API Key, enable "Override OpenAI Base URL" with: ${baseUrl}
+OpenAI API Key, enable "Override OpenAI Base URL" with: ${gateway}
 
 Already inside this profile's window? Close it before running clone.
 `;
@@ -193,9 +229,11 @@ export function createProfile({ profileDir, projectName, color, cloneFrom }) {
   fs.mkdirSync(profileDir, { recursive: true });
   writeProfileSettings(profileDir, projectName, color);
   symlinkSharedUserFiles(profileDir);
+  let scrubbed = 0;
   if (cloneFrom) {
-    cloneStateDb(cloneFrom, profileDir);
+    scrubbed = cloneStateDb(cloneFrom, profileDir);
   }
+  return { scrubbed };
 }
 
 export function profileIntegrityChecks(profileDir) {

package/scripts/postinstall.mjs

@@ -1,58 +0,0 @@
-// Postinstall: one-time hint + best-effort companion extension install.
-// Never breaks the install: the whole body is guarded and exits 0.
-// Quiet installs: CURSOR_KEYS_NO_POSTINSTALL=1
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-try {
-  if (process.env.CURSOR_KEYS_NO_POSTINSTALL) process.exit(0);
-  const yellow = "\x1b[33m";
-  const dim = "\x1b[2m";
-  const reset = "\x1b[0m";
-
-  const pkgRoot = path.join(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "..",
-  );
-  const extSrc = path.join(pkgRoot, "extension");
-  const extPkgPath = path.join(extSrc, "package.json");
-  const cursorDir = path.join(os.homedir(), ".cursor");
-
-  // Auto-link the companion extension on global installs when Cursor exists.
-  let extLine = "";
-  const isGlobal = process.env.npm_config_global === "true";
-  if (isGlobal && fs.existsSync(cursorDir) && fs.existsSync(extPkgPath)) {
-    try {
-      const extPkg = JSON.parse(fs.readFileSync(extPkgPath, "utf8"));
-      const extDir = path.join(cursorDir, "extensions");
-      fs.mkdirSync(extDir, { recursive: true });
-      const target = path.join(
-        extDir,
-        `${extPkg.publisher || "lubu"}.${extPkg.name}-${extPkg.version}`,
-      );
-      fs.rmSync(target, { recursive: true, force: true });
-      try {
-        fs.symlinkSync(extSrc, target, "dir");
-      } catch {
-        fs.cpSync(extSrc, target, { recursive: true });
-      }
-      extLine = `\n  Cursor extension linked ${dim}· restart Cursor, then Cmd+Shift+P: "cursor-keys: Open Project..."${reset}`;
-    } catch {
-      extLine = `\n  cursor-keys install-extension   link the Cursor extension (status bar + warnings)`;
-    }
-  }
-
-  console.log(`
-${yellow}cursor-keys installed${reset}
-
-  cursor-keys --help              commands
-  cursor-keys aliases --install   aliases, 'ck' shortcut, tab completion
-  cursor-keys wrap --install      plain 'cursor <path>' picks the profile
-${extLine}
-${dim}Quiet installs: CURSOR_KEYS_NO_POSTINSTALL=1${reset}
-`);
-} catch {
-  /* postinstall must never break install */
-}