@tacitai/mcp-server 0.1.1 → 0.3.0

package/dist/oauth.js

@@ -0,0 +1,619 @@
+// SPDX-License-Identifier: MIT
+/**
+ * OAuth 2.0 Authorization Server for MCP (FEAT-176).
+ *
+ * Authorization code flow with PKCE S256. In-memory stores for auth codes
+ * and access tokens — process restart voids all grants.
+ *
+ * Security invariants:
+ *  - PINs, auth codes, and token values are NEVER logged.
+ *  - OAuth path NEVER falls back to process.env.TACIT_TOKEN.
+ *  - Unknown client_id → 400 (never redirect to unregistered URI).
+ *  - code_challenge_method must be S256 (plain rejected).
+ */
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+function timingSafeCompare(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) {
+        timingSafeEqual(bufA, bufA);
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+// ─── Configuration ──────────────────────────────────────────────────────────
+const CODE_TTL_MS = 5 * 60 * 1000;
+const CODE_STORE_CAP = 1000;
+const TOKEN_STORE_CAP = 10000;
+const CSRF_TTL_MS = 10 * 60 * 1000;
+const CSRF_STORE_CAP = 500;
+const LOGIN_RATE_LIMIT = 5;
+const LOGIN_RATE_WINDOW_MS = 15 * 60 * 1000;
+const DYNAMIC_CLIENT_CAP = 500;
+export function getTokenTtlSeconds() {
+    const env = Number.parseInt(process.env['MCP_OAUTH_TOKEN_TTL_SECONDS'] ?? '', 10);
+    return Number.isFinite(env) && env > 0 && env <= 3600 ? env : 3600;
+}
+export function isOAuthEnabled() {
+    const v = process.env['MCP_OAUTH_ENABLED'];
+    return v === '1' || v === 'true';
+}
+// ─── Client Registry ────────────────────────────────────────────────────────
+let _clients = null;
+const dynamicClients = new Map();
+export function getRegisteredClients() {
+    if (_clients)
+        return _clients;
+    const env = process.env['MCP_OAUTH_CLIENTS'];
+    if (env) {
+        try {
+            const parsed = JSON.parse(env);
+            if (Array.isArray(parsed)) {
+                _clients = parsed;
+                return _clients;
+            }
+        }
+        catch { /* fall through to default */ }
+    }
+    _clients = [];
+    return _clients;
+}
+export function resetClientRegistry() {
+    _clients = null;
+    dynamicClients.clear();
+}
+export function findClient(client_id) {
+    return getRegisteredClients().find((c) => c.client_id === client_id) ?? dynamicClients.get(client_id);
+}
+export function validateRedirectUri(client, redirect_uri) {
+    return client.redirect_uris.includes(redirect_uri);
+}
+export function registerDynamicClient(params) {
+    if (dynamicClients.size >= DYNAMIC_CLIENT_CAP) {
+        const oldest = dynamicClients.keys().next().value;
+        if (oldest)
+            dynamicClients.delete(oldest);
+    }
+    const client_id = `dyn_${randomBytes(16).toString('hex')}`;
+    const client_secret = randomBytes(32).toString('base64url');
+    const client_name = params.client_name || 'Dynamic Client';
+    const authMethod = params.token_endpoint_auth_method === 'none' ? 'none' : 'client_secret_post';
+    dynamicClients.set(client_id, {
+        client_id,
+        client_secret: authMethod === 'none' ? undefined : client_secret,
+        redirect_uris: params.redirect_uris,
+        client_name,
+    });
+    return {
+        client_id,
+        client_secret,
+        client_id_issued_at: Math.floor(Date.now() / 1000),
+        redirect_uris: params.redirect_uris,
+        client_name,
+        token_endpoint_auth_method: authMethod,
+    };
+}
+// ─── Auth Code Store ────────────────────────────────────────────────────────
+const authCodes = new Map();
+function evictExpiredCodes() {
+    const now = Date.now();
+    for (const [code, entry] of authCodes) {
+        if (now - entry.created_at > CODE_TTL_MS)
+            authCodes.delete(code);
+    }
+}
+function generateCode() {
+    return randomBytes(16).toString('hex');
+}
+export function issueAuthCode(params) {
+    evictExpiredCodes();
+    if (authCodes.size >= CODE_STORE_CAP) {
+        const oldest = authCodes.keys().next().value;
+        if (oldest !== undefined)
+            authCodes.delete(oldest);
+    }
+    const code = generateCode();
+    authCodes.set(code, { ...params, created_at: Date.now() });
+    return code;
+}
+export function consumeAuthCode(code) {
+    evictExpiredCodes();
+    const entry = authCodes.get(code);
+    if (!entry)
+        return null;
+    authCodes.delete(code);
+    if (Date.now() - entry.created_at > CODE_TTL_MS)
+        return null;
+    return entry;
+}
+// ─── Access Token Store ─────────────────────────────────────────────────────
+const accessTokens = new Map();
+function evictExpiredTokens() {
+    const now = Date.now();
+    for (const [token, entry] of accessTokens) {
+        if (now >= entry.expires_at)
+            accessTokens.delete(token);
+    }
+}
+function generateTokenValue() {
+    return `tmo_${randomBytes(16).toString('hex')}`;
+}
+export function issueAccessToken(params) {
+    evictExpiredTokens();
+    if (accessTokens.size >= TOKEN_STORE_CAP) {
+        const oldest = accessTokens.keys().next().value;
+        if (oldest !== undefined)
+            accessTokens.delete(oldest);
+    }
+    const ttl = getTokenTtlSeconds();
+    const now = Date.now();
+    const token = generateTokenValue();
+    accessTokens.set(token, {
+        ...params,
+        created_at: now,
+        expires_at: now + ttl * 1000,
+    });
+    return { access_token: token, expires_in: ttl };
+}
+export function validateOAuthToken(token) {
+    if (!token.startsWith('tmo_'))
+        return null;
+    evictExpiredTokens();
+    const entry = accessTokens.get(token);
+    if (!entry)
+        return null;
+    if (Date.now() >= entry.expires_at) {
+        accessTokens.delete(token);
+        return null;
+    }
+    return {
+        user_email: entry.user_email,
+        workspace_id: entry.workspace_id,
+        tacit_token: entry.tacit_token,
+        client_id: entry.client_id,
+    };
+}
+// ─── PKCE ───────────────────────────────────────────────────────────────────
+export function verifyPkce(code_verifier, code_challenge) {
+    const computed = createHash('sha256').update(code_verifier).digest('base64url');
+    return computed === code_challenge;
+}
+// ─── CSRF Store ─────────────────────────────────────────────────────────────
+const csrfTokens = new Map();
+function evictExpiredCsrf() {
+    const now = Date.now();
+    for (const [token, entry] of csrfTokens) {
+        if (now - entry.created_at > CSRF_TTL_MS)
+            csrfTokens.delete(token);
+    }
+}
+export function generateCsrfToken(params) {
+    evictExpiredCsrf();
+    if (csrfTokens.size >= CSRF_STORE_CAP) {
+        const oldest = csrfTokens.keys().next().value;
+        if (oldest !== undefined)
+            csrfTokens.delete(oldest);
+    }
+    const token = randomBytes(16).toString('hex');
+    csrfTokens.set(token, { ...params, created_at: Date.now() });
+    return token;
+}
+export function consumeCsrfToken(token) {
+    evictExpiredCsrf();
+    const entry = csrfTokens.get(token);
+    if (!entry)
+        return null;
+    csrfTokens.delete(token);
+    if (Date.now() - entry.created_at > CSRF_TTL_MS)
+        return null;
+    return entry;
+}
+// ─── Login Rate Limiter ─────────────────────────────────────────────────────
+const loginAttempts = new Map();
+export function checkLoginRateLimit(email) {
+    const now = Date.now();
+    const key = email.toLowerCase();
+    const entry = loginAttempts.get(key);
+    if (!entry || now - entry.window_start > LOGIN_RATE_WINDOW_MS) {
+        loginAttempts.set(key, { count: 1, window_start: now });
+        return true;
+    }
+    if (entry.count >= LOGIN_RATE_LIMIT)
+        return false;
+    entry.count += 1;
+    return true;
+}
+// ─── Discovery ──────────────────────────────────────────────────────────────
+export function getAuthorizationServerMetadata(issuer) {
+    return {
+        issuer,
+        authorization_endpoint: `${issuer}/authorize`,
+        token_endpoint: `${issuer}/token`,
+        registration_endpoint: `${issuer}/register`,
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: ['none', 'client_secret_post'],
+    };
+}
+export function getProtectedResourceMetadata(resource, issuer) {
+    return {
+        resource,
+        authorization_servers: [issuer],
+    };
+}
+// ─── Login Page HTML ────────────────────────────────────────────────────────
+export function renderLoginPage(params) {
+    const errorHtml = params.error
+        ? `<p style="color:#e74c3c;margin:0 0 16px">${escapeHtml(params.error)}</p>`
+        : '';
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>TACIT — Authorize ${escapeHtml(params.client_name)}</title>
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:system-ui,sans-serif;background:#1a1a2e;color:#e0e0e0;display:flex;justify-content:center;align-items:center;min-height:100vh;padding:16px}
+.card{background:#16213e;border-radius:12px;padding:32px;max-width:400px;width:100%;box-shadow:0 4px 24px rgba(0,0,0,0.3)}
+h1{font-size:1.25rem;margin-bottom:8px;color:#f0f0f0}
+.sub{color:#8892b0;font-size:0.875rem;margin-bottom:24px}
+label{display:block;font-size:0.875rem;color:#8892b0;margin-bottom:4px}
+input{display:block;width:100%;padding:10px 12px;border:1px solid #2a2a4a;border-radius:6px;background:#0f0f23;color:#e0e0e0;font-size:1rem;margin-bottom:16px}
+input:focus{outline:none;border-color:#64ffda}
+button{width:100%;padding:12px;border:none;border-radius:6px;background:#64ffda;color:#0a0a1a;font-size:1rem;font-weight:600;cursor:pointer}
+button:hover{background:#52e0c4}
+</style>
+</head>
+<body>
+<div class="card">
+<h1>Authorize ${escapeHtml(params.client_name)}</h1>
+<p class="sub">Sign in to grant access to your TACIT workspace</p>
+${errorHtml}
+<form method="POST" action="/authorize">
+<input type="hidden" name="csrf_token" value="${escapeHtml(params.csrf_token)}">
+<label for="email">Email</label>
+<input id="email" name="email" type="email" required autocomplete="email">
+<label for="pin">PIN</label>
+<input id="pin" name="pin" type="password" required autocomplete="current-password" inputmode="numeric">
+<button type="submit">Authorize</button>
+</form>
+</div>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+// ─── HTTP Handlers ──────────────────────────────────────────────────────────
+function sendJsonResponse(res, status, body) {
+    if (res.headersSent)
+        return;
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function sendHtmlResponse(res, status, html) {
+    if (res.headersSent)
+        return;
+    res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+}
+function parseQuery(url) {
+    const idx = url.indexOf('?');
+    if (idx === -1)
+        return {};
+    const params = {};
+    for (const part of url.slice(idx + 1).split('&')) {
+        const [k, ...rest] = part.split('=');
+        if (k)
+            params[decodeURIComponent(k)] = decodeURIComponent(rest.join('='));
+    }
+    return params;
+}
+function parseFormBody(body) {
+    const params = {};
+    for (const part of body.split('&')) {
+        const [k, ...rest] = part.split('=');
+        if (k)
+            params[decodeURIComponent(k)] = decodeURIComponent(rest.join('='));
+    }
+    return params;
+}
+function readRequestBody(req, maxBytes = 64_000) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new Error('body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+export async function handleAuthorizeGet(req, res) {
+    const query = parseQuery(req.url ?? '');
+    const { client_id, redirect_uri, response_type, code_challenge, code_challenge_method, state, scope } = query;
+    if (response_type !== 'code') {
+        sendJsonResponse(res, 400, { error: 'unsupported_response_type', error_description: 'Only response_type=code is supported' });
+        return;
+    }
+    if (!client_id) {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'client_id is required' });
+        return;
+    }
+    const client = findClient(client_id);
+    if (!client) {
+        sendJsonResponse(res, 400, { error: 'invalid_client', error_description: 'Unknown client_id' });
+        return;
+    }
+    if (!redirect_uri || !validateRedirectUri(client, redirect_uri)) {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'Invalid or missing redirect_uri' });
+        return;
+    }
+    if (!code_challenge) {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'code_challenge is required (PKCE S256)' });
+        return;
+    }
+    if (code_challenge_method && code_challenge_method !== 'S256') {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'Only S256 code_challenge_method is supported' });
+        return;
+    }
+    const csrf = generateCsrfToken({
+        client_id,
+        redirect_uri,
+        code_challenge,
+        code_challenge_method: 'S256',
+        state: state ?? '',
+        scope: scope ?? '',
+    });
+    sendHtmlResponse(res, 200, renderLoginPage({ client_name: client.client_name, csrf_token: csrf }));
+}
+export async function handleAuthorizePost(req, res, apiUrl) {
+    let body;
+    try {
+        body = await readRequestBody(req);
+    }
+    catch {
+        sendJsonResponse(res, 400, { error: 'invalid_request' });
+        return;
+    }
+    const form = parseFormBody(body);
+    const { csrf_token, email, pin } = form;
+    if (!csrf_token) {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'Missing CSRF token' });
+        return;
+    }
+    const csrf = consumeCsrfToken(csrf_token);
+    if (!csrf) {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'Invalid or expired CSRF token' });
+        return;
+    }
+    if (!email || !pin) {
+        const client = findClient(csrf.client_id);
+        const newCsrf = generateCsrfToken(csrf);
+        sendHtmlResponse(res, 400, renderLoginPage({
+            client_name: client?.client_name ?? 'Unknown',
+            csrf_token: newCsrf,
+            error: 'Email and PIN are required',
+        }));
+        return;
+    }
+    if (!checkLoginRateLimit(email)) {
+        const client = findClient(csrf.client_id);
+        const newCsrf = generateCsrfToken(csrf);
+        sendHtmlResponse(res, 429, renderLoginPage({
+            client_name: client?.client_name ?? 'Unknown',
+            csrf_token: newCsrf,
+            error: 'Too many login attempts. Please try again later.',
+        }));
+        return;
+    }
+    try {
+        const loginRes = await fetch(`${apiUrl}/api/v1/auth/login`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email, pin }),
+        });
+        if (!loginRes.ok) {
+            const client = findClient(csrf.client_id);
+            const newCsrf = generateCsrfToken(csrf);
+            sendHtmlResponse(res, 401, renderLoginPage({
+                client_name: client?.client_name ?? 'Unknown',
+                csrf_token: newCsrf,
+                error: 'Invalid email or PIN',
+            }));
+            return;
+        }
+        const loginData = await loginRes.json();
+        const tacit_token = (loginData['token'] ?? loginData['session_token'] ?? '');
+        const workspace_id = (loginData['workspace_id'] ?? loginData['active_workspace_id'] ?? '');
+        if (!tacit_token) {
+            const client = findClient(csrf.client_id);
+            const newCsrf = generateCsrfToken(csrf);
+            sendHtmlResponse(res, 500, renderLoginPage({
+                client_name: client?.client_name ?? 'Unknown',
+                csrf_token: newCsrf,
+                error: 'Authentication succeeded but no session token was returned',
+            }));
+            return;
+        }
+        const code = issueAuthCode({
+            client_id: csrf.client_id,
+            redirect_uri: csrf.redirect_uri,
+            code_challenge: csrf.code_challenge,
+            user_email: email,
+            workspace_id,
+            tacit_token,
+            state: csrf.state,
+        });
+        const redirectUrl = new URL(csrf.redirect_uri);
+        redirectUrl.searchParams.set('code', code);
+        if (csrf.state)
+            redirectUrl.searchParams.set('state', csrf.state);
+        res.writeHead(302, { Location: redirectUrl.toString() });
+        res.end();
+    }
+    catch {
+        const client = findClient(csrf.client_id);
+        const newCsrf = generateCsrfToken(csrf);
+        sendHtmlResponse(res, 502, renderLoginPage({
+            client_name: client?.client_name ?? 'Unknown',
+            csrf_token: newCsrf,
+            error: 'Failed to reach authentication service',
+        }));
+    }
+}
+export async function handleTokenExchange(req, res) {
+    let body;
+    try {
+        body = await readRequestBody(req);
+    }
+    catch {
+        sendJsonResponse(res, 400, { error: 'invalid_request' });
+        return;
+    }
+    let params;
+    const ct = req.headers['content-type'] ?? '';
+    if (ct.includes('application/json')) {
+        try {
+            params = JSON.parse(body);
+        }
+        catch {
+            sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'Invalid JSON' });
+            return;
+        }
+    }
+    else {
+        params = parseFormBody(body);
+    }
+    const { grant_type, code, client_id, redirect_uri, code_verifier } = params;
+    if (grant_type !== 'authorization_code') {
+        sendJsonResponse(res, 400, { error: 'unsupported_grant_type' });
+        return;
+    }
+    if (!code || !client_id || !redirect_uri || !code_verifier) {
+        sendJsonResponse(res, 400, { error: 'invalid_request', error_description: 'Missing required parameters' });
+        return;
+    }
+    const client = findClient(client_id);
+    if (!client) {
+        sendJsonResponse(res, 400, { error: 'invalid_client' });
+        return;
+    }
+    if (client.client_secret) {
+        const client_secret = params['client_secret'];
+        if (!client_secret || !timingSafeCompare(client_secret, client.client_secret)) {
+            sendJsonResponse(res, 401, { error: 'invalid_client', error_description: 'Client authentication failed' });
+            return;
+        }
+    }
+    const entry = consumeAuthCode(code);
+    if (!entry) {
+        sendJsonResponse(res, 400, { error: 'invalid_grant', error_description: 'Invalid, expired, or already-used authorization code' });
+        return;
+    }
+    if (entry.client_id !== client_id) {
+        sendJsonResponse(res, 400, { error: 'invalid_grant', error_description: 'client_id mismatch' });
+        return;
+    }
+    if (entry.redirect_uri !== redirect_uri) {
+        sendJsonResponse(res, 400, { error: 'invalid_grant', error_description: 'redirect_uri mismatch' });
+        return;
+    }
+    if (!verifyPkce(code_verifier, entry.code_challenge)) {
+        sendJsonResponse(res, 400, { error: 'invalid_grant', error_description: 'PKCE verification failed' });
+        return;
+    }
+    const { access_token, expires_in } = issueAccessToken({
+        client_id: entry.client_id,
+        user_email: entry.user_email,
+        workspace_id: entry.workspace_id,
+        tacit_token: entry.tacit_token,
+    });
+    sendJsonResponse(res, 200, {
+        access_token,
+        token_type: 'Bearer',
+        expires_in,
+    });
+}
+export async function handleClientRegistration(req, res) {
+    let body;
+    try {
+        body = await readRequestBody(req);
+    }
+    catch {
+        sendJsonResponse(res, 400, { error: 'invalid_request' });
+        return;
+    }
+    let params;
+    try {
+        params = JSON.parse(body);
+    }
+    catch {
+        sendJsonResponse(res, 400, { error: 'invalid_client_metadata', error_description: 'Invalid JSON' });
+        return;
+    }
+    const redirect_uris = params['redirect_uris'];
+    if (!Array.isArray(redirect_uris) || redirect_uris.length === 0 || !redirect_uris.every((u) => typeof u === 'string')) {
+        sendJsonResponse(res, 400, { error: 'invalid_client_metadata', error_description: 'redirect_uris must be a non-empty array of strings' });
+        return;
+    }
+    for (const uri of redirect_uris) {
+        try {
+            new URL(uri);
+        }
+        catch {
+            sendJsonResponse(res, 400, { error: 'invalid_redirect_uri', error_description: `Invalid redirect URI: ${uri}` });
+            return;
+        }
+    }
+    const result = registerDynamicClient({
+        redirect_uris: redirect_uris,
+        client_name: typeof params['client_name'] === 'string' ? params['client_name'] : undefined,
+        token_endpoint_auth_method: typeof params['token_endpoint_auth_method'] === 'string' ? params['token_endpoint_auth_method'] : undefined,
+    });
+    sendJsonResponse(res, 201, result);
+}
+export function handleDiscovery(res, issuer) {
+    sendJsonResponse(res, 200, getAuthorizationServerMetadata(issuer));
+}
+export function handleProtectedResource(res, resource, issuer) {
+    sendJsonResponse(res, 200, getProtectedResourceMetadata(resource, issuer));
+}
+// ─── Periodic Cleanup ───────────────────────────────────────────────────────
+let _cleanupInterval = null;
+export function startCleanupInterval() {
+    if (_cleanupInterval)
+        return;
+    _cleanupInterval = setInterval(() => {
+        evictExpiredCodes();
+        evictExpiredTokens();
+        evictExpiredCsrf();
+    }, 60_000);
+    _cleanupInterval.unref();
+}
+export function stopCleanupInterval() {
+    if (_cleanupInterval) {
+        clearInterval(_cleanupInterval);
+        _cleanupInterval = null;
+    }
+}
+// ─── Test Helpers ───────────────────────────────────────────────────────────
+export function _testClearStores() {
+    authCodes.clear();
+    accessTokens.clear();
+    csrfTokens.clear();
+    loginAttempts.clear();
+    dynamicClients.clear();
+    _clients = null;
+}
+export function _testGetStoreSize() {
+    return { codes: authCodes.size, tokens: accessTokens.size, csrf: csrfTokens.size };
+}

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+import { z } from 'zod';
+const ASSISTANT_SYSTEM_PROMPT = "You are TACIT's workspace assistant. Answer from the user's workspace through TACIT tools. " +
+    'Prefer a single read tool for direct lookups, synthesis for open questions, and ask before any write or dispatch.';
+function userText(text) {
+    return { messages: [{ role: 'user', content: { type: 'text', text } }] };
+}
+export function registerPrompts(server) {
+    server.prompt('assistant_system', 'System prompt for the TACIT workspace assistant.', () => userText(ASSISTANT_SYSTEM_PROMPT));
+    server.prompt('lookup', 'Fetch a specific item or list using a single TACIT read tool.', { request: z.string().describe('What to look up, e.g. "list programs"') }, ({ request }) => userText(`Use exactly one TACIT read tool to answer, without synthesis. Request: ${request}`));
+    server.prompt('synthesis', 'Answer a question with grounded synthesis and citations.', { question: z.string().describe('The question to answer') }, ({ question }) => userText(`Call tacit_synthesize for this question and cite the sources it returns. Question: ${question}`));
+}

package/dist/setup.d.ts

@@ -2,17 +2,40 @@
  * 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).
+ */
+/**
+ * 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 declare function profileToEnvVar(profile: string): string;
+/**
+ * Derive a profile name from a workspace_name returned by device-auth exchange.
+ * AC-12: lowercased, spaces→hyphens, non-alphanumeric-hyphen stripped.
  */
+export declare function workspaceNameToProfile(name: string): string;
 export declare function setup(argv: string[]): Promise<void>;