@tacitai/mcp-server 0.1.1 → 0.3.0

package/dist/setup.js

@@ -1,67 +1,45 @@
-"use strict";
 // SPDX-License-Identifier: MIT
 /**
  * setup — wizard subcommand for @tacit/mcp-server
  *
  * Usage:
- *   node dist/index.js setup [--dry-run] [--api-url <url>] [--token <token>] [--smoke]
+ *   node dist/index.js setup [--dry-run] [--api-url <url>] [--token <token>] [--profile <name>] [--smoke]
  *
- * Contract (§2.1 of sparc_specification.md, Phase-2 QE resolutions):
+ * Contract (§2.1 of sparc_specification.md, Phase-2 QE resolutions + W5 device-auth):
  *   F1 smoke   — calls tacit_synthesize via getClient()/postSSE; exits non-zero on empty/error.
- *   F2 env-ref — writes TACIT_TOKEN as the LITERAL placeholder "${TACIT_TOKEN}" (never the real value).
- *   Merge      — deep-merges ONLY mcpServers.tacit; all other keys preserved.
- *   Idempotent — same --api-url → byte-identical mcp.json.
+ *   F2 env-ref — writes TACIT_TOKEN_* as the LITERAL placeholder "${TACIT_TOKEN_*}" (never the real value).
+ *   Merge      — deep-merges ONLY mcpServers[profile]; all other keys preserved.
+ *   Idempotent — same --api-url + --profile → byte-identical mcp.json.
  *   Secrets    — token NEVER written to any output stream.
  *
+ * W5 additions:
+ *   --profile <name>  — profile name (default: 'tacit'); drives env-var name + mcp.json key.
+ *   Device-auth flow  — when --token is NOT provided and token env var is absent, opens browser
+ *                       to ${apiUrl}/auth/device, waits for localhost:9123 callback, exchanges
+ *                       code for token, derives profile from workspace_name (unless --profile set).
+ *   Metadata file     — writes ~/.tacit/profiles/<profile>.json with { expires_at, api_url }.
+ *
  * Security invariants:
  *   - Token is NEVER logged or written to disk.
  *   - Authorization header value excluded from all logging paths.
+ *   - State nonce generated from crypto.randomBytes (never user-provided).
+ *   - Tampered state in device-auth callback → exit 1 (S-10/AC-13).
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setup = setup;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const os = __importStar(require("os"));
-const client_js_1 = require("./client.js");
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as http from 'http';
+import * as crypto from 'crypto';
+import { execFile } from 'child_process';
+import { TacitClient, TacitApiError } from './client.js';
 function parseArgs(argv) {
     const opts = {
         dryRun: false,
         apiUrl: null,
         token: null,
         smoke: false,
+        profile: 'tacit',
+        profileExplicit: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -89,9 +67,44 @@ function parseArgs(argv) {
             opts.token = next;
             i++;
         }
+        else if (arg === '--profile') {
+            const next = argv[i + 1];
+            if (!next || next.startsWith('--')) {
+                process.stderr.write('Error: --profile requires a value\n');
+                process.exit(1);
+            }
+            opts.profile = next;
+            opts.profileExplicit = true;
+            i++;
+        }
     }
     return opts;
 }
+// ─── Profile / env-var helpers ────────────────────────────────────────────────
+/**
+ * Derive the environment variable name for a given profile name.
+ *
+ * AC-3, AC-4, AC-10:
+ *   'tacit'          → 'TACIT_TOKEN'
+ *   'tacit-acme'     → 'TACIT_TOKEN_ACME'
+ *   'my-workspace'   → 'TACIT_TOKEN_MY_WORKSPACE'
+ */
+export function profileToEnvVar(profile) {
+    // Strip leading 'tacit-' prefix if present
+    const stripped = profile.startsWith('tacit-') ? profile.slice(6) : profile;
+    // Special case: default profile ('tacit') → stripped = '' → 'TACIT_TOKEN'
+    if (stripped === '' || stripped === 'tacit') {
+        return 'TACIT_TOKEN';
+    }
+    return 'TACIT_TOKEN_' + stripped.replace(/-/g, '_').toUpperCase();
+}
+/**
+ * Derive a profile name from a workspace_name returned by device-auth exchange.
+ * AC-12: lowercased, spaces→hyphens, non-alphanumeric-hyphen stripped.
+ */
+export function workspaceNameToProfile(name) {
+    return name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+}
 function claudeDir() {
     return path.join(os.homedir(), '.claude');
 }
@@ -113,26 +126,32 @@ function readExistingConfig() {
         return {};
     }
 }
-function buildTacitEntry(apiUrl) {
+/**
+ * Build the MCP server entry for a given profile.
+ * The env-var placeholder is the LITERAL string "${TACIT_TOKEN_*}" — never the real value.
+ */
+function buildProfileEntry(apiUrl, envVarName) {
     return {
         command: 'npx',
         args: ['-y', '@tacitai/mcp-server'],
         env: {
             // F2: literal placeholder — Claude Code expands ${VAR} at launch; real token NEVER on disk.
-            TACIT_TOKEN: '${TACIT_TOKEN}',
+            [envVarName]: `\${${envVarName}}`,
             // TACIT_API_URL is a non-secret URL; written as-is.
             TACIT_API_URL: apiUrl,
         },
     };
 }
-function mergeConfig(existing, tacitEntry) {
+/**
+ * Deep-merge ONLY the mcpServers[profileName] key; all other keys preserved.
+ */
+function mergeConfig(existing, profileName, entry) {
     const servers = existing.mcpServers ?? {};
-    // Deep-merge ONLY tacit key; all other mcpServers entries and top-level keys preserved.
     const merged = {
         ...existing,
         mcpServers: {
             ...servers,
-            tacit: tacitEntry,
+            [profileName]: entry,
         },
     };
     return merged;
@@ -140,10 +159,159 @@ function mergeConfig(existing, tacitEntry) {
 function configToBytes(cfg) {
     return JSON.stringify(cfg, null, 2) + '\n';
 }
+// ─── Metadata file ────────────────────────────────────────────────────────────
+/**
+ * Write ~/.tacit/profiles/<profile>.json with { expires_at, api_url }.
+ * Token plaintext is NEVER written here — metadata only.
+ */
+function writeProfileMetadata(profile, expiresAt, apiUrl) {
+    const metaDir = path.join(os.homedir(), '.tacit', 'profiles');
+    fs.mkdirSync(metaDir, { recursive: true });
+    fs.writeFileSync(path.join(metaDir, `${profile}.json`), JSON.stringify({ expires_at: expiresAt, api_url: apiUrl }, null, 2));
+}
+// ─── Device-auth flow ─────────────────────────────────────────────────────────
+const DEVICE_AUTH_CALLBACK_PORT = 9123;
+const DEVICE_AUTH_TIMEOUT_MS = 120_000;
+/**
+ * Opens a browser to the device-auth URL and waits for the OAuth callback.
+ * Returns the token, expiry, and workspace name from the exchange response.
+ *
+ * Security:
+ *   - State nonce is generated via crypto.randomBytes (never user-provided).
+ *   - Tampered state → exit 1 (S-10 / AC-13).
+ *   - Token plaintext is NEVER logged.
+ *
+ * Error paths:
+ *   - Port 9123 occupied → print error + --token fallback instructions → exit 1 (AC-15).
+ *   - 120s timeout → exit 1 (AC-15).
+ *   - Browser open fails → print URL to stdout for manual copy-paste (AC-16 fallback).
+ */
+async function deviceAuthFlow(apiUrl) {
+    // 1. Generate a cryptographically random state nonce (32 bytes, hex).
+    const stateNonce = crypto.randomBytes(32).toString('hex');
+    return new Promise((resolve, reject) => {
+        let server = null;
+        let timeoutHandle = null;
+        const cleanup = () => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (server) {
+                server.close(() => { });
+            }
+        };
+        // 2. Start localhost:9123 HTTP server for callback.
+        server = http.createServer(async (req, res) => {
+            const reqUrl = req.url ?? '';
+            if (!reqUrl.startsWith('/callback')) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const parsedUrl = new URL(reqUrl, `http://localhost:${DEVICE_AUTH_CALLBACK_PORT}`);
+            const returnedState = parsedUrl.searchParams.get('state') ?? '';
+            const code = parsedUrl.searchParams.get('code') ?? '';
+            // 6a. Verify state nonce — tampered state → exit 1 (S-10/AC-13).
+            if (returnedState !== stateNonce) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' });
+                res.end('Invalid state parameter.');
+                cleanup();
+                reject(new Error('CSRF state mismatch: state nonce did not match. Aborting device auth.'));
+                return;
+            }
+            if (!code) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' });
+                res.end('Missing code parameter.');
+                cleanup();
+                reject(new Error('Device auth callback missing code parameter.'));
+                return;
+            }
+            // 6c. Exchange code for token.
+            try {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Authentication complete. You may close this tab.</h1></body></html>');
+                const exchangeRes = await fetch(`${apiUrl}/api/v1/auth/device-exchange`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ code }),
+                });
+                if (!exchangeRes.ok) {
+                    const errBody = await exchangeRes.text().catch(() => '');
+                    cleanup();
+                    reject(new Error(`Device auth exchange failed (${exchangeRes.status}): ${errBody}`));
+                    return;
+                }
+                const data = await exchangeRes.json();
+                const token = typeof data['token'] === 'string' ? data['token'] : '';
+                const expiresAt = typeof data['expires_at'] === 'string' ? data['expires_at'] : '';
+                const workspaceName = typeof data['workspace_name'] === 'string' ? data['workspace_name'] : 'tacit';
+                if (!token) {
+                    cleanup();
+                    reject(new Error('Device auth exchange returned empty token.'));
+                    return;
+                }
+                cleanup();
+                resolve({ token, expiresAt, workspaceName });
+            }
+            catch (err) {
+                cleanup();
+                reject(err);
+            }
+        });
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                process.stderr.write(`Error: port ${DEVICE_AUTH_CALLBACK_PORT} is already in use.\n` +
+                    `Cannot start device-auth callback server.\n` +
+                    `Use --token <your-token> instead:\n` +
+                    `  npx @tacitai/mcp-server setup --api-url ${apiUrl} --token <your-token>\n` +
+                    `Get your token from: ${apiUrl}/settings\n`);
+                process.exit(1);
+            }
+            cleanup();
+            reject(err);
+        });
+        server.listen(DEVICE_AUTH_CALLBACK_PORT, '127.0.0.1', () => {
+            // 3. Build device URL.
+            const callbackUrl = `http://localhost:${DEVICE_AUTH_CALLBACK_PORT}/callback`;
+            const deviceUrl = `${apiUrl}/auth/device?callback=${encodeURIComponent(callbackUrl)}&state=${stateNonce}`;
+            // 4. Try to open the browser.
+            // Use execFile with an argument array (not exec) to avoid shell injection
+            // — deviceUrl is built from user-supplied --api-url and must not be
+            // interpolated into a shell command string.
+            const platform = process.platform;
+            const [openBin, openArgs] = platform === 'win32'
+                ? ['cmd', ['/c', 'start', '', deviceUrl]]
+                : platform === 'darwin'
+                    ? ['open', [deviceUrl]]
+                    : ['xdg-open', [deviceUrl]];
+            execFile(openBin, openArgs, (err) => {
+                if (err) {
+                    // AC-16 fallback: print URL for manual copy-paste.
+                    process.stdout.write(`Could not open browser automatically.\n` +
+                        `Open this URL in your browser to authenticate:\n` +
+                        `  ${deviceUrl}\n`);
+                }
+                else {
+                    process.stdout.write(`Opening browser for authentication...\n` +
+                        `If the browser does not open, visit:\n` +
+                        `  ${deviceUrl}\n`);
+                }
+            });
+            // 5. Timeout guard (AC-15).
+            timeoutHandle = setTimeout(() => {
+                cleanup();
+                process.stderr.write(`Error: device-auth timed out after ${DEVICE_AUTH_TIMEOUT_MS / 1000}s.\n` +
+                    `Use --token <your-token> instead:\n` +
+                    `  npx @tacitai/mcp-server setup --api-url ${apiUrl} --token <your-token>\n` +
+                    `Get your token from: ${apiUrl}/settings\n`);
+                process.exit(1);
+            }, DEVICE_AUTH_TIMEOUT_MS);
+        });
+    });
+}
 // ─── Smoke synthesis ──────────────────────────────────────────────────────────
 const SMOKE_QUERY = 'What is in this knowledge base?';
 async function runSmoke(apiUrl, token) {
-    const client = new client_js_1.TacitClient({
+    const client = new TacitClient({
         apiUrl,
         token: token ?? process.env['TACIT_TOKEN'] ?? '',
     });
@@ -157,7 +325,7 @@ async function runSmoke(apiUrl, token) {
         }
     }
     catch (err) {
-        const msg = err instanceof client_js_1.TacitApiError
+        const msg = err instanceof TacitApiError
             ? `API error ${err.statusCode}: ${err.body}`
             : err instanceof Error ? err.message : String(err);
         process.stderr.write(`SMOKE_SYNTH_FAIL: ${msg}\n`);
@@ -172,23 +340,52 @@ async function runSmoke(apiUrl, token) {
     process.exit(0);
 }
 // ─── Main export ──────────────────────────────────────────────────────────────
-async function setup(argv) {
+export async function setup(argv) {
     const opts = parseArgs(argv);
-    // Resolve api-url: flag > env. Token: flag > env (never logged).
+    // Resolve api-url: flag > env.
     const apiUrl = opts.apiUrl ?? process.env['TACIT_API_URL'] ?? null;
-    const token = opts.token ?? process.env['TACIT_TOKEN'] ?? null;
     if (!apiUrl) {
         process.stderr.write('Error: no API URL configured.\n' +
             'Provide --api-url <url> or set TACIT_API_URL environment variable.\n' +
-            'Example: node dist/index.js setup --api-url http://localhost:7473 --token <your-token>\n');
+            'Example: npx @tacitai/mcp-server setup --api-url https://tacit-beta-prod.fly.dev --token <your-token>\n' +
+            '\nGet your token from: https://beta.tacitai.app → Settings → Bearer token\n');
         process.exit(1);
     }
-    const tacitEntry = buildTacitEntry(apiUrl);
+    // Determine profile and token.
+    let profile = opts.profile;
+    let token = opts.token;
+    let expiresAt = '';
+    // Check env var for this profile (to support existing token path).
+    const envVarNameForProfile = profileToEnvVar(profile);
+    const envToken = process.env[envVarNameForProfile] ?? process.env['TACIT_TOKEN'] ?? null;
+    if (!token && !envToken && !opts.dryRun) {
+        // Neither --token nor env set and not a dry-run → run automated device-auth flow.
+        let deviceResult;
+        try {
+            deviceResult = await deviceAuthFlow(apiUrl);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`Error during device authentication: ${msg}\n`);
+            process.exit(1);
+            return; // unreachable; satisfies TypeScript
+        }
+        // Token from device flow — use in memory only (NEVER log/write).
+        token = deviceResult.token;
+        expiresAt = deviceResult.expiresAt;
+        // AC-12: derive profile from workspace_name unless --profile was explicit.
+        if (!opts.profileExplicit && deviceResult.workspaceName) {
+            profile = workspaceNameToProfile(deviceResult.workspaceName);
+        }
+    }
+    // Final env-var name derived from (possibly updated) profile.
+    const envVarName = profileToEnvVar(profile);
+    const profileEntry = buildProfileEntry(apiUrl, envVarName);
     const existing = readExistingConfig();
-    const merged = mergeConfig(existing, tacitEntry);
+    const merged = mergeConfig(existing, profile, profileEntry);
     const output = configToBytes(merged);
     // D10: emit confirmation string BEFORE writing (also printed in dry-run).
-    process.stdout.write('Writing tacit entry to ~/.claude/mcp.json...\n');
+    process.stdout.write(`Writing tacit entry to ~/.claude/mcp.json (profile: ${profile})...\n`);
     if (opts.dryRun) {
         process.stdout.write('(dry-run) Would write:\n');
         process.stdout.write(output);
@@ -202,6 +399,16 @@ async function setup(argv) {
     }
     const dest = mcpJsonPath();
     fs.writeFileSync(dest, output, { encoding: 'utf-8', mode: 0o600 });
+    // AC-12: write ~/.tacit/profiles/<profile>.json metadata (token NOT included).
+    if (expiresAt) {
+        writeProfileMetadata(profile, expiresAt, apiUrl);
+    }
+    // AC-11: print export snippet to stdout so user can set the env var.
+    // Token itself is NOT printed here — user must have received it through the device flow.
+    process.stdout.write(`\nSetup complete. Add this to your shell profile:\n` +
+        `  export ${envVarName}=<your-token>\n` +
+        `\nOr for this session:\n` +
+        `  export ${envVarName}=<your-token>\n`);
     if (opts.smoke) {
         await runSmoke(apiUrl, token);
         // runSmoke calls process.exit internally; return here for type safety.