@zivis/cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/internal/binding-token-mint.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Mint a Local Project Binding Token via POST /api/auth/bind and store it as
+ * apikey.<session>. Shared by `zivis auth bind` and post-login auto-mint.
+ */
+import { type ZivisConfig } from "@zivis/mcp/types";
+export type MintBindingTokenResult = {
+    ok: true;
+    keyName: string;
+    key: string;
+    orgName: string;
+    workosOrgId: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Calls the bind API with a fresh access JWT and persists the minted WorkOS API key.
+ * Does not start OAuth nor update IDE configs.
+ */
+export declare function mintLocalProjectBindingToken(params: {
+    config: ZivisConfig;
+    session: string;
+    accessToken: string;
+    cwd: string;
+}): Promise<MintBindingTokenResult>;
+export interface TryAutoMintOptions {
+    cwd: string;
+    sessionName: string;
+    accessToken: string;
+    /** Caller flag (e.g. `zivis auth login --no-mint-key`). */
+    skip?: boolean;
+    /**
+     * When false (login after ensureProjectBinding): mint failures log a warning and return.
+     * When true (`zivis auth bind`): caller should exit 1 if result not ok — not handled here.
+     */
+    warnOnFailure: boolean;
+}
+/**
+ * After OAuth login finishes, mint an MCP-friendly API key if the repo is bound
+ * and JWT org matches `.zivis/project.json`.
+ * Skips if `apikey.<session>` already exists (avoid spawning keys on every login).
+ */
+export declare function tryAutoMintBindingTokenAfterLogin(opts: TryAutoMintOptions): Promise<{
+    ran: boolean;
+    ok: boolean;
+    message?: string;
+}>;
+/**
+ * Drop the OAuth tokens stored under `oauth.<session>` (or `oauth` when no
+ * session). OAuth exists only to mint the MCP API key — once login finishes,
+ * MCP and tenant API calls go through `apikey.<session>`. Keeping the OAuth
+ * tokens around adds attack surface and risks org-drift if the refresh token
+ * outlives the binding.
+ *
+ * Best-effort: failures are swallowed so they cannot mask a successful mint.
+ */
+export declare function discardOauthAfterLogin(params: {
+    session: string | undefined;
+    config: ZivisConfig;
+}): Promise<void>;

package/dist/internal/binding-token-mint.js

@@ -0,0 +1,185 @@
+/**
+ * Mint a Local Project Binding Token via POST /api/auth/bind and store it as
+ * apikey.<session>. Shared by `zivis auth bind` and post-login auto-mint.
+ */
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import * as child_process from "node:child_process";
+import { keychainClearSession, keychainRead, keychainStore } from "@zivis/mcp/auth";
+import { decodeJwtPayload } from "@zivis/mcp/auth/jwt";
+import { DEFAULT_CONFIG, credentialStorageFromConfig } from "@zivis/mcp/types";
+import { detectProjectBinding, resolveConfigFromBinding } from "@zivis/mcp/project-binding";
+/** Same fingerprint strategy as bind command — stable-ish per-repo key name suffix. */
+function getRepoFingerprint(cwd) {
+    try {
+        const remote = child_process
+            .execSync("git remote get-url origin 2>/dev/null", { cwd, encoding: "utf8" })
+            .trim();
+        if (remote) {
+            return crypto.createHash("sha256").update(remote).digest("hex").slice(0, 12);
+        }
+    }
+    catch {
+        /* no git or no remote */
+    }
+    return crypto.createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+}
+/**
+ * Calls the bind API with a fresh access JWT and persists the minted WorkOS API key.
+ * Does not start OAuth nor update IDE configs.
+ */
+export async function mintLocalProjectBindingToken(params) {
+    const { config, session, accessToken, cwd } = params;
+    const credentialStorage = credentialStorageFromConfig(config);
+    const repoFingerprint = getRepoFingerprint(cwd);
+    const hostname = os.hostname();
+    let bindResult;
+    try {
+        const response = await fetch(`${config.apiBaseUrl}/api/auth/bind`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+                "User-Agent": "@zivis/cli",
+            },
+            body: JSON.stringify({ repoFingerprint, hostname }),
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            return {
+                ok: false,
+                error: body.message ?? body.error ?? `HTTP ${response.status}`,
+            };
+        }
+        bindResult = (await response.json());
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    const apiKeyAccount = `apikey.${session}`;
+    try {
+        await keychainStore(apiKeyAccount, bindResult.key, credentialStorage);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : "Failed to store key in OS keychain",
+        };
+    }
+    return {
+        ok: true,
+        keyName: bindResult.keyName,
+        key: bindResult.key,
+        orgName: bindResult.orgName,
+        workosOrgId: bindResult.workosOrgId,
+    };
+}
+/**
+ * After OAuth login finishes, mint an MCP-friendly API key if the repo is bound
+ * and JWT org matches `.zivis/project.json`.
+ * Skips if `apikey.<session>` already exists (avoid spawning keys on every login).
+ */
+export async function tryAutoMintBindingTokenAfterLogin(opts) {
+    if (opts.skip) {
+        return { ran: false, ok: true };
+    }
+    const fullConfig = { ...DEFAULT_CONFIG, ...resolveConfigFromBinding(opts.cwd) };
+    const claims = decodeJwtPayload(opts.accessToken);
+    const jwtOrgId = claims?.org_id;
+    if (!jwtOrgId) {
+        return {
+            ran: false,
+            ok: true,
+            message: "JWT has no org_id — skipped MCP binding-key mint.",
+        };
+    }
+    const detected = detectProjectBinding(opts.cwd);
+    const bindingOrg = detected?.binding.workosOrgId;
+    const bindingSession = detected?.binding.session;
+    if (!bindingOrg || !bindingSession) {
+        return {
+            ran: false,
+            ok: true,
+            message: "No project binding with workosOrgId — skipped MCP binding-key mint.",
+        };
+    }
+    if (bindingOrg !== jwtOrgId) {
+        const msg = `JWT org does not match project binding — skipped MCP binding-key mint.`;
+        if (opts.warnOnFailure) {
+            console.log("");
+            console.log(`  WARNING: ${msg}`);
+        }
+        return { ran: false, ok: false, message: msg };
+    }
+    if (bindingSession !== opts.sessionName) {
+        const msg = `Session "${opts.sessionName}" does not match binding session "${bindingSession}" — skipped MCP binding-key mint.`;
+        if (opts.warnOnFailure) {
+            console.log("");
+            console.log(`  WARNING: ${msg}`);
+        }
+        return { ran: false, ok: false, message: msg };
+    }
+    const st = credentialStorageFromConfig(fullConfig);
+    const existing = await keychainRead(`apikey.${bindingSession}`, st).catch(() => null);
+    if (existing) {
+        console.log("");
+        console.log(`✓ MCP API key already present for session "${bindingSession}" — skipped mint.`);
+        return { ran: false, ok: true };
+    }
+    console.log("");
+    console.log("Minting Local Project Binding Token for MCP (one-time per machine/session)…");
+    const result = await mintLocalProjectBindingToken({
+        config: fullConfig,
+        session: bindingSession,
+        accessToken: opts.accessToken,
+        cwd: opts.cwd,
+    });
+    if (!result.ok) {
+        const msg = result.error;
+        if (opts.warnOnFailure) {
+            printMintFailureBanner(msg);
+        }
+        return { ran: true, ok: false, message: msg };
+    }
+    console.log(`✓ MCP API key stored (${result.keyName}; org: ${result.orgName})`);
+    return { ran: true, ok: true };
+}
+/**
+ * Drop the OAuth tokens stored under `oauth.<session>` (or `oauth` when no
+ * session). OAuth exists only to mint the MCP API key — once login finishes,
+ * MCP and tenant API calls go through `apikey.<session>`. Keeping the OAuth
+ * tokens around adds attack surface and risks org-drift if the refresh token
+ * outlives the binding.
+ *
+ * Best-effort: failures are swallowed so they cannot mask a successful mint.
+ */
+export async function discardOauthAfterLogin(params) {
+    const storage = credentialStorageFromConfig(params.config);
+    await keychainClearSession(params.session, storage).catch(() => {
+        /* OAuth was never written, nothing to clean up. */
+    });
+}
+function printMintFailureBanner(message) {
+    const bar = "═".repeat(70);
+    console.error("");
+    console.error(bar);
+    console.error("  ACTION REQUIRED — MCP API KEY WAS NOT MINTED");
+    console.error(bar);
+    console.error("");
+    console.error(`  Reason: ${message}`);
+    console.error("");
+    console.error("  Why this matters:");
+    console.error("    The MCP server in your IDE authenticates with an org-scoped");
+    console.error("    API key. Without it, every zivis_* tool call will fail with");
+    console.error("    \"Not authenticated\" until you mint one.");
+    console.error("");
+    console.error("  To fix, run from this repo:");
+    console.error("    zivis auth bind");
+    console.error("");
+    console.error(bar);
+    console.error("");
+}
+//# sourceMappingURL=binding-token-mint.js.map

package/dist/internal/binding-token-mint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-token-mint.js","sourceRoot":"","sources":["../../src/internal/binding-token-mint.ts"],"names":[],"mappings":"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"}

package/dist/internal/ide-setup.d.ts

@@ -1,7 +1,38 @@
-export declare function setupCursor(session?: string): Promise<void>;
-export declare function setupVsCodeCopilot(session?: string): Promise<void>;
-export declare function setupVsCodeClaude(session?: string): Promise<void>;
-export declare function setupClaudeCodeCli(session?: string): Promise<void>;
-export declare function setupCline(session?: string): Promise<void>;
-export declare function setupWindsurf(session?: string): Promise<void>;
-export declare function printClaudeCodeManual(session?: string): void;
+export type GuidanceClient = "cursor" | "claude-code-cli" | "vscode-copilot" | "vscode-claude" | "cline" | "windsurf";
+export interface GuidanceOptions {
+    /** Workspace root to write guidance files into */
+    cwd: string;
+    /** Which IDE client to write guidance for */
+    client: GuidanceClient;
+}
+/**
+ * Write IDE guidance files for the given client.
+ *
+ * The guidance files teach the host AI (Cursor, Claude Code, etc.)
+ * when to suggest ZIVIS tools — no security knowledge required from the user.
+ *
+ * All writes are idempotent: re-running replaces only the ZIVIS-managed
+ * block, never user content.
+ *
+ * Returns the list of file paths written.
+ */
+export declare function writeGuidance(opts: GuidanceOptions): string[];
+/**
+ * Detect which IDE configs are present in the given workspace.
+ * Returns client identifiers whose config files/dirs were found.
+ */
+export declare function detectIdesInRepo(cwd: string): GuidanceClient[];
+export declare function setupCursor(): Promise<void>;
+/**
+ * Write a workspace-level .cursor/mcp.json with `--workspace <cwd>` so Cursor
+ * starts an isolated MCP process bound to this specific repo.
+ * One process = one org = zero cross-tenant risk, regardless of what other
+ * repos are open in Cursor.
+ */
+export declare function setupCursorWorkspace(): Promise<void>;
+export declare function setupVsCodeCopilot(): Promise<void>;
+export declare function setupVsCodeClaude(): Promise<void>;
+export declare function setupClaudeCodeCli(): Promise<void>;
+export declare function setupCline(): Promise<void>;
+export declare function setupWindsurf(): Promise<void>;
+export declare function printClaudeCodeManual(): void;