@zivis/mcp 0.1.8 → 0.1.10

package/dist/auth/keychain.js

@@ -1,15 +1,3 @@
-/**
- * OS Keychain credential storage
- *
- * Uses native OS CLI commands to store/retrieve credentials securely.
- * No native npm dependencies (no keytar).
- *
- * - macOS: Keychain Services via `security` CLI
- * - Linux: Secret Service API via `secret-tool` CLI
- * - Windows: DPAPI via PowerShell
- *
- * Falls back to encrypted file if keychain CLI is unavailable.
- */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import * as fs from "node:fs/promises";
@@ -18,48 +6,49 @@ import * as os from "node:os";
 import * as crypto from "node:crypto";
 import { ENV_CONFIG } from "../types.js";
 const execFileAsync = promisify(execFile);
-// Use environment-aware prefix so staging and production credentials are isolated
-const SERVICE_PREFIX = ENV_CONFIG.keychainPrefix;
-/**
- * Returns the keychain account key for a given session.
- * - No session or undefined → "oauth" (backward compatible)
- * - Named session → "oauth.{session}"
- */
+function resolvedStorage(storage) {
+    return (storage ?? {
+        keychainPrefix: ENV_CONFIG.keychainPrefix,
+        configDir: ENV_CONFIG.configDir,
+    });
+}
 export function getSessionAccount(session) {
     return session ? `oauth.${session}` : "oauth";
 }
-function getServiceName(account) {
-    return `${SERVICE_PREFIX}.${account}`;
+function getServiceName(account, keychainPrefix) {
+    return `${keychainPrefix}.${account}`;
 }
-function getFallbackDir() {
-    // Use environment-aware config dir so staging and production are isolated
-    const configDir = ENV_CONFIG.configDir;
+function getFallbackDir(configDir) {
     if (process.platform === "win32") {
         return path.join(process.env.APPDATA || os.homedir(), configDir);
     }
     return path.join(os.homedir(), ".config", configDir);
 }
-function getFallbackPath(account) {
-    return path.join(getFallbackDir(), `${account}.enc`);
-}
-// ── macOS Keychain ──
-async function macosStore(account, value) {
-    const service = getServiceName(account);
-    // Delete existing entry first (ignore errors if not found)
-    try {
-        await execFileAsync("security", [
-            "delete-generic-password",
-            "-a",
-            "zivis-mcp",
-            "-s",
-            service,
-        ]);
-    }
-    catch {
-        // Entry didn't exist, that's fine
+function getFallbackPath(account, storage) {
+    return path.join(getFallbackDir(storage.configDir), `${account}.enc`);
+}
+async function macosDeleteAll(service) {
+    for (let i = 0; i < 100; i++) {
+        try {
+            await execFileAsync("security", [
+                "delete-generic-password",
+                "-a",
+                "zivis-mcp",
+                "-s",
+                service,
+            ]);
+        }
+        catch {
+            return;
+        }
     }
+}
+async function macosStore(account, value, keychainPrefix) {
+    const service = getServiceName(account, keychainPrefix);
+    await macosDeleteAll(service);
     await execFileAsync("security", [
         "add-generic-password",
+        "-U",
         "-a",
         "zivis-mcp",
         "-s",
@@ -68,8 +57,8 @@ async function macosStore(account, value) {
         value,
     ]);
 }
-async function macosRead(account) {
-    const service = getServiceName(account);
+async function macosRead(account, keychainPrefix) {
+    const service = getServiceName(account, keychainPrefix);
     try {
         const { stdout } = await execFileAsync("security", [
             "find-generic-password",
@@ -85,43 +74,29 @@ async function macosRead(account) {
         return null;
     }
 }
-async function macosDelete(account) {
-    const service = getServiceName(account);
-    try {
-        await execFileAsync("security", [
-            "delete-generic-password",
-            "-a",
-            "zivis-mcp",
-            "-s",
-            service,
-        ]);
-    }
-    catch {
-        // Entry didn't exist
-    }
+async function macosDelete(account, keychainPrefix) {
+    await macosDeleteAll(getServiceName(account, keychainPrefix));
 }
-// ── Linux Secret Service ──
-async function linuxStore(account, value) {
+async function linuxStore(account, value, keychainPrefix) {
     const child = execFileAsync("secret-tool", [
         "store",
         "--label",
         `ZIVIS MCP ${account}`,
         "service",
-        SERVICE_PREFIX,
+        keychainPrefix,
         "account",
         account,
     ]);
-    // secret-tool reads value from stdin
     child.child.stdin?.write(value);
     child.child.stdin?.end();
     await child;
 }
-async function linuxRead(account) {
+async function linuxRead(account, keychainPrefix) {
     try {
         const { stdout } = await execFileAsync("secret-tool", [
             "lookup",
             "service",
-            SERVICE_PREFIX,
+            keychainPrefix,
             "account",
             account,
         ]);
@@ -131,44 +106,39 @@ async function linuxRead(account) {
         return null;
     }
 }
-async function linuxDelete(account) {
+async function linuxDelete(account, keychainPrefix) {
     try {
         await execFileAsync("secret-tool", [
             "clear",
             "service",
-            SERVICE_PREFIX,
+            keychainPrefix,
             "account",
             account,
         ]);
     }
     catch {
-        // Entry didn't exist
     }
 }
-// ── Encrypted File Fallback (Windows + fallback for all platforms) ──
 function deriveKey() {
-    // Use machine-specific data as encryption key seed
     const seed = `zivis-mcp:${os.hostname()}:${os.userInfo().username}`;
     return crypto.createHash("sha256").update(seed).digest();
 }
-async function fileStore(account, value) {
+async function fileStore(account, value, storage) {
     const key = deriveKey();
     const iv = crypto.randomBytes(16);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
     let encrypted = cipher.update(value, "utf8", "hex");
     encrypted += cipher.final("hex");
     const data = JSON.stringify({ iv: iv.toString("hex"), data: encrypted });
-    const dir = getFallbackDir();
+    const dir = getFallbackDir(storage.configDir);
     await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(getFallbackPath(account), data, { mode: 0o600 });
+    await fs.writeFile(getFallbackPath(account, storage), data, { mode: 0o600 });
 }
-async function fileRead(account) {
+async function fileRead(account, storage) {
     try {
-        const raw = await fs.readFile(getFallbackPath(account), "utf8");
+        const raw = await fs.readFile(getFallbackPath(account, storage), "utf8");
         const { iv, data } = JSON.parse(raw);
         const key = deriveKey();
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const decipher = crypto.createDecipheriv("aes-256-cbc", key, Buffer.from(iv, "hex"));
         let decrypted = decipher.update(data, "hex", "utf8");
         decrypted += decipher.final("utf8");
@@ -178,15 +148,13 @@ async function fileRead(account) {
         return null;
     }
 }
-async function fileDelete(account) {
+async function fileDelete(account, storage) {
     try {
-        await fs.unlink(getFallbackPath(account));
+        await fs.unlink(getFallbackPath(account, storage));
     }
     catch {
-        // File didn't exist
     }
 }
-// ── Platform Detection & Dispatch ──
 async function isKeychainAvailable() {
     try {
         if (process.platform === "darwin") {
@@ -210,56 +178,58 @@ async function useKeychain() {
     }
     return keychainAvailable;
 }
-// ── Public API ──
-export async function keychainStore(account, value) {
-    // Always store to encrypted file as fallback (for environments where keychain CLI
-    // may not be available, e.g., MCP servers spawned by IDEs with different $PATH)
-    await fileStore(account, value);
-    // Also store to native keychain if available
+export async function keychainStore(account, value, storage) {
+    const st = resolvedStorage(storage);
+    await fileStore(account, value, st);
     if (await useKeychain()) {
         if (process.platform === "darwin") {
-            await macosStore(account, value);
+            await macosStore(account, value, st.keychainPrefix);
         }
         else if (process.platform === "linux") {
-            await linuxStore(account, value);
+            await linuxStore(account, value, st.keychainPrefix);
         }
     }
 }
-export async function keychainRead(account) {
+const LEGACY_KEYCHAIN_PREFIX = "io.zivis.mcp";
+async function readFromBucket(account, storage) {
     if (await useKeychain()) {
         if (process.platform === "darwin")
-            return macosRead(account);
+            return macosRead(account, storage.keychainPrefix);
         if (process.platform === "linux")
-            return linuxRead(account);
-    }
-    return fileRead(account);
-}
-export async function keychainDelete(account) {
+            return linuxRead(account, storage.keychainPrefix);
+    }
+    return fileRead(account, storage);
+}
+export async function keychainRead(account, storage) {
+    const st = resolvedStorage(storage);
+    const primary = await readFromBucket(account, st);
+    if (primary !== null)
+        return primary;
+    if (st.keychainPrefix !== LEGACY_KEYCHAIN_PREFIX) {
+        return await readFromBucket(account, {
+            ...st,
+            keychainPrefix: LEGACY_KEYCHAIN_PREFIX,
+        });
+    }
+    return null;
+}
+export async function keychainDelete(account, storage) {
+    const st = resolvedStorage(storage);
+    await fileDelete(account, st);
     if (await useKeychain()) {
         if (process.platform === "darwin")
-            return macosDelete(account);
+            return macosDelete(account, st.keychainPrefix);
         if (process.platform === "linux")
-            return linuxDelete(account);
+            return linuxDelete(account, st.keychainPrefix);
     }
-    return fileDelete(account);
 }
-/**
- * Delete credentials for a specific session
- */
-export async function keychainClearSession(session) {
-    await keychainDelete(getSessionAccount(session));
+export async function keychainClearSession(session, storage) {
+    await keychainDelete(getSessionAccount(session), storage);
 }
-/**
- * Delete all stored credentials (default OAuth + API key).
- * Does NOT clear named sessions — use keychainClearSession() for those.
- */
-export async function keychainClearAll() {
-    await keychainDelete("oauth");
-    await keychainDelete("apikey");
+export async function keychainClearAll(storage) {
+    await keychainDelete("oauth", storage);
+    await keychainDelete("apikey", storage);
 }
-/**
- * Returns the storage mechanism name for display purposes
- */
 export function getStorageName() {
     if (process.platform === "darwin")
         return "macOS Keychain";
@@ -269,4 +239,3 @@ export function getStorageName() {
         return "encrypted file";
     return "encrypted file";
 }
-//# sourceMappingURL=keychain.js.map

package/dist/auth/oauth.d.ts

@@ -1,38 +1,9 @@
-/**
- * OAuth PKCE Authentication Flow
- *
- * Authorization Code Flow with Proof Key for Code Exchange (PKCE)
- * for native/CLI applications. Uses WorkOS as the identity provider.
- *
- * Flow:
- * 1. Generate PKCE code_verifier + code_challenge
- * 2. Start localhost callback server
- * 3. Open browser to WorkOS authorization URL
- * 4. Receive authorization code via callback
- * 5. Exchange code + verifier for tokens
- * 6. Store tokens in OS keychain
- */
 import type { OAuthTokens, ZivisConfig } from "../types.js";
-/**
- * Run the full OAuth PKCE login flow.
- *
- * 1. Generate PKCE pair + state
- * 2. Start localhost callback server
- * 3. Open browser to WorkOS
- * 4. Wait for callback
- * 5. Exchange code for tokens
- * 6. Store tokens in keychain (under session-qualified key)
- *
- * @param config - Server configuration
- * @param session - Optional named session for multi-tenant isolation
- * @param organizationId - Optional WorkOS org ID to scope the login to a specific org
- * @param opts - Display and confirmation options
- * @returns The OAuth tokens
- */
 export interface LoginOptions {
-    /** Human-readable org name, shown in the pre-browser confirmation prompt. */
     orgName?: string;
-    /** Skip the pre-browser confirmation prompt (for scripted/interactive-wizard callers). */
+    sessionLabel?: string;
     skipConfirm?: boolean;
+    printUrlOnly?: boolean;
+    incognito?: boolean;
 }
 export declare function login(config?: ZivisConfig, session?: string, organizationId?: string, opts?: LoginOptions): Promise<OAuthTokens>;

package/dist/auth/oauth.js

@@ -1,17 +1,3 @@
-/**
- * OAuth PKCE Authentication Flow
- *
- * Authorization Code Flow with Proof Key for Code Exchange (PKCE)
- * for native/CLI applications. Uses WorkOS as the identity provider.
- *
- * Flow:
- * 1. Generate PKCE code_verifier + code_challenge
- * 2. Start localhost callback server
- * 3. Open browser to WorkOS authorization URL
- * 4. Receive authorization code via callback
- * 5. Exchange code + verifier for tokens
- * 6. Store tokens in OS keychain
- */
 import * as crypto from "node:crypto";
 import * as http from "node:http";
 import * as readline from "node:readline/promises";
@@ -19,8 +5,8 @@ import { URL } from "node:url";
 import open from "open";
 import { keychainStore, getSessionAccount } from "./keychain.js";
 import { decodeJwtPayload } from "./jwt.js";
-import { DEFAULT_CONFIG } from "../types.js";
-const LOGIN_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+import { DEFAULT_CONFIG, credentialStorageFromConfig } from "../types.js";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 function generatePKCE() {
     const verifier = crypto.randomBytes(32).toString("base64url");
     const challenge = crypto
@@ -42,29 +28,15 @@ function buildAuthUrl(config, codeChallenge, state, organizationId) {
         state,
         scope: "openid profile email offline_access",
     });
-    // Scope the OAuth session to a specific org so the JWT has the correct org_id
     if (organizationId) {
         params.set("organization_id", organizationId);
     }
-    // Force the WorkOS login screen even when an active session exists.
-    // Why: users in multiple orgs must visually confirm which identity/org they're using —
-    // silent SSO could let them accidentally bind the wrong org to a project.
     params.set("prompt", "login");
-    // Handle both WorkOS (auth.workos.com -> /authorize) and custom AuthKit (authkit.app -> /oauth2/authorize)
-    const isAuthKit = config.oauthApiUrl.includes("authkit.app");
+    const isAuthKit = !config.oauthApiUrl.includes("workos.com");
     const authPath = isAuthKit ? "/oauth2/authorize" : "/authorize";
     const authUrl = `${config.oauthApiUrl}${authPath}?${params.toString()}`;
-    // We used to chain custom AuthKit hosts through /logout?return_to=... so
-    // browser cookies did not override organization_id. AuthKit OIDC metadata
-    // does not advertise end_session_endpoint, and *.authkit.app/logout returns
-    // 404 — so that redirect is unusable. Rely on prompt=login plus
-    // organization_id for org-scoped flows instead.
     return authUrl;
 }
-/**
- * Start a localhost HTTP server to receive the OAuth callback.
- * Returns the authorization code on success.
- */
 function startCallbackServer(port, expectedState) {
     return new Promise((resolve, reject) => {
         const server = http.createServer((req, res) => {
@@ -74,6 +46,11 @@ function startCallbackServer(port, expectedState) {
                 const state = parsedUrl.searchParams.get("state");
                 const error = parsedUrl.searchParams.get("error");
                 const errorDesc = parsedUrl.searchParams.get("error_description");
+                if (state !== expectedState) {
+                    res.writeHead(200, { "Content-Type": "text/html" });
+                    res.end(callbackHtml(false, "This is a stale authentication tab. You can close it — your login is continuing in the original window."));
+                    return;
+                }
                 res.writeHead(200, { "Content-Type": "text/html" });
                 if (error) {
                     res.end(callbackHtml(false, errorDesc || error));
@@ -81,12 +58,6 @@ function startCallbackServer(port, expectedState) {
                     reject(new Error(errorDesc || error));
                     return;
                 }
-                if (state !== expectedState) {
-                    res.end(callbackHtml(false, "State mismatch — possible CSRF attack"));
-                    server.close();
-                    reject(new Error("State mismatch"));
-                    return;
-                }
                 if (!code) {
                     res.end(callbackHtml(false, "No authorization code received"));
                     server.close();
@@ -98,14 +69,13 @@ function startCallbackServer(port, expectedState) {
                 resolve(code);
             }
             else {
-                // 404 for any other path
                 res.writeHead(404, { "Content-Type": "text/html" });
                 res.end(`<!DOCTYPE html>
 <html>
 <head><title>Not Found</title></head>
 <body style="font-family:system-ui;text-align:center;padding:50px;background:#0f0f1a;color:#fff;">
   <h1>404 - Not Found</h1>
-  <p>Expected callback at /callback, got ${parsedUrl.pathname}</p>
+  <p>Expected callback at /callback, got ${escapeHtml(parsedUrl.pathname)}</p>
 </body>
 </html>`);
             }
@@ -114,13 +84,20 @@ function startCallbackServer(port, expectedState) {
             reject(new Error(`Failed to start callback server on port ${port}: ${err.message}`));
         });
         server.listen(port, "127.0.0.1");
-        // Timeout
         setTimeout(() => {
             server.close();
             reject(new Error("Authentication timed out after 5 minutes"));
         }, LOGIN_TIMEOUT_MS);
     });
 }
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
 function callbackHtml(success, errorMessage) {
     if (success) {
         return `<!DOCTYPE html>
@@ -138,17 +115,13 @@ function callbackHtml(success, errorMessage) {
 <head><title>Authentication Failed</title></head>
 <body style="font-family:system-ui;text-align:center;padding:50px;background:#0f0f1a;color:#fff;">
   <h1 style="color:#ff5252;">Authentication Failed</h1>
-  <p>${errorMessage || "Unknown error"}</p>
+  <p>${escapeHtml(errorMessage || "Unknown error")}</p>
   <p>You can close this window.</p>
 </body>
 </html>`;
 }
-/**
- * Exchange authorization code for tokens via WorkOS token endpoint
- */
 async function exchangeCodeForTokens(config, code, codeVerifier) {
-    // Handle both WorkOS (auth.workos.com -> /oauth/token) and custom AuthKit (authkit.app -> /oauth2/token)
-    const tokenPath = config.oauthApiUrl.includes("authkit.app") ? "/oauth2/token" : "/oauth/token";
+    const tokenPath = config.oauthApiUrl.includes("workos.com") ? "/oauth/token" : "/oauth2/token";
     const tokenUrl = `${config.oauthApiUrl}${tokenPath}`;
     const response = await fetch(tokenUrl, {
         method: "POST",
@@ -169,6 +142,14 @@ async function exchangeCodeForTokens(config, code, codeVerifier) {
         throw new Error(errorMsg);
     }
     const data = (await response.json());
+    if (!data.refresh_token) {
+        console.error("[zivis] WARNING: WorkOS did not return a refresh_token. " +
+            "Verify the OAuth client has Refresh Tokens / offline_access enabled in the WorkOS dashboard. " +
+            "Without this, sessions will expire and require manual re-login.");
+    }
+    else {
+        console.error("[zivis] Token exchange complete — refresh_token received, session will auto-renew.");
+    }
     return {
         access_token: data.access_token,
         refresh_token: data.refresh_token,
@@ -183,13 +164,12 @@ export async function login(config = DEFAULT_CONFIG, session, organizationId, op
     const { verifier, challenge } = generatePKCE();
     const state = generateState();
     const authUrl = buildAuthUrl(config, challenge, state, organizationId);
-    // Pre-browser confirmation: only when an org is scoped AND the terminal is interactive.
-    // Protects users in multiple orgs from accidentally authenticating to the wrong tenant.
     if (organizationId && !opts.skipConfirm && process.stderr.isTTY && process.stdin.isTTY) {
         const orgLabel = opts.orgName
             ? `${opts.orgName} (${organizationId})`
             : organizationId;
-        const sessionLabel = session ? ` as session "${session}"` : "";
+        const displaySession = opts.sessionLabel ?? session;
+        const sessionLabel = displaySession ? ` as session "${displaySession}"` : "";
         console.error("");
         console.error(`[zivis] About to authenticate to org: ${orgLabel}${sessionLabel}`);
         const rl = readline.createInterface({
@@ -209,18 +189,46 @@ export async function login(config = DEFAULT_CONFIG, session, organizationId, op
     else if (organizationId) {
         console.error(`[zivis] Login scoped to organization: ${organizationId}`);
     }
-    // Start callback server before opening browser
     const codePromise = startCallbackServer(config.callbackPort, state);
-    console.error("[zivis] Opening browser for authentication...");
-    await open(authUrl);
-    console.error("[zivis] Waiting for login...");
-    // Wait for the authorization code
+    if (opts.printUrlOnly) {
+        console.error("[zivis] Open this URL in a private/incognito browser window:");
+        console.error("");
+        console.error(`  ${authUrl}`);
+        console.error("");
+        console.error("[zivis] Waiting for login...");
+    }
+    else if (opts.incognito) {
+        let opened = false;
+        for (const app of [
+            { name: "google chrome", args: ["--incognito"] },
+            { name: "chromium", args: ["--incognito"] },
+            { name: "firefox", args: ["-private-window"] },
+        ]) {
+            try {
+                await open(authUrl, { app: { name: app.name, arguments: [authUrl, ...app.args] } });
+                console.error(`[zivis] Opened private window in ${app.name} — waiting for login...`);
+                opened = true;
+                break;
+            }
+            catch {
+            }
+        }
+        if (!opened) {
+            console.error("[zivis] Could not open an incognito window automatically.");
+            console.error("[zivis] Paste this URL into a private/incognito browser window:");
+            console.error("");
+            console.error(`  ${authUrl}`);
+            console.error("");
+            console.error("[zivis] Waiting for login...");
+        }
+    }
+    else {
+        console.error("[zivis] Opening browser for authentication...");
+        await open(authUrl);
+        console.error("[zivis] Waiting for login...");
+    }
     const code = await codePromise;
-    // Exchange code for tokens
     const tokens = await exchangeCodeForTokens(config, code, verifier);
-    // Hard verification: if we requested a specific org, the returned JWT
-    // MUST be scoped to that org. Refuse to store mismatched tokens — this is
-    // the last-ditch guard against silently binding the wrong tenant.
     if (organizationId) {
         const claims = decodeJwtPayload(tokens.access_token);
         const jwtOrgId = claims?.org_id;
@@ -234,8 +242,6 @@ export async function login(config = DEFAULT_CONFIG, session, organizationId, op
         }
         console.error(`[zivis] \u2713 JWT org_id verified: ${jwtOrgId}`);
     }
-    // Store in keychain (session-qualified key for multi-tenant isolation)
-    await keychainStore(getSessionAccount(session), JSON.stringify(tokens));
+    await keychainStore(getSessionAccount(session), JSON.stringify(tokens), credentialStorageFromConfig(config));
     return tokens;
 }
-//# sourceMappingURL=oauth.js.map

package/dist/auth/sessions.d.ts

@@ -1,28 +1,8 @@
-/**
- * Session Index Management
- *
- * Tracks named OAuth sessions in a JSON file so users can list
- * and manage multiple tenant sessions without enumerating keychain entries.
- *
- * Session index file: ~/.config/{configDir}/sessions.json
- */
 import type { SessionIndex, SessionInfo } from "../types.js";
-/**
- * Load the session index from disk.
- * Returns an empty object if the file doesn't exist.
- */
-export declare function loadSessionIndex(): Promise<SessionIndex>;
-/**
- * Add or update a session entry in the index.
- */
-export declare function saveSessionEntry(name: string, email: string): Promise<void>;
-/**
- * Remove a session entry from the index.
- */
-export declare function removeSessionEntry(name: string): Promise<void>;
-/**
- * List all sessions with their metadata.
- */
-export declare function listSessions(): Promise<Array<{
+import { type CredentialStorage } from "../types.js";
+export declare function loadSessionIndex(storage?: CredentialStorage): Promise<SessionIndex>;
+export declare function saveSessionEntry(name: string, email: string, storage?: CredentialStorage): Promise<void>;
+export declare function removeSessionEntry(name: string, storage?: CredentialStorage): Promise<void>;
+export declare function listSessions(storage?: CredentialStorage): Promise<Array<{
     name: string;
 } & SessionInfo>>;