@tacitai/mcp-server 0.1.1 → 0.3.0

package/dist/auth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * HTTPS transport auth + rate limiting.
+ *
+ * Security invariants:
+ *  - Token validation happens at the TACIT API; this module only checks presence.
+ *  - The Authorization header value is NEVER logged.
+ */
+import type { IncomingMessage } from 'node:http';
+import { type OAuthTokenInfo } from './oauth.js';
+/** Returns the Bearer token, or null if missing/empty. */
+export declare function authenticateRequest(req: IncomingMessage): string | null;
+export type AuthResult = {
+    type: 'bearer';
+    token: string;
+} | {
+    type: 'oauth';
+    info: OAuthTokenInfo;
+} | {
+    type: 'invalid_token';
+} | null;
+/**
+ * Dual-auth resolution: discriminates Bearer vs OAuth tokens.
+ * OAuth tokens carry the `tmo_` prefix; all others route to Bearer path.
+ */
+export declare function resolveAuth(req: IncomingMessage): AuthResult;
+export declare class RateLimiter {
+    private readonly buckets;
+    private readonly limit;
+    constructor(limit?: number);
+    /** Consumes one token for the IP; returns false when exhausted. */
+    tryConsume(ip: string): boolean;
+}

package/dist/auth.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+/**
+ * HTTPS transport auth + rate limiting.
+ *
+ * Security invariants:
+ *  - Token validation happens at the TACIT API; this module only checks presence.
+ *  - The Authorization header value is NEVER logged.
+ */
+import { validateOAuthToken } from './oauth.js';
+/** Returns the Bearer token, or null if missing/empty. */
+export function authenticateRequest(req) {
+    const header = req.headers['authorization'];
+    if (typeof header !== 'string')
+        return null;
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    const token = match?.[1]?.trim();
+    return token ? token : null;
+}
+/**
+ * Dual-auth resolution: discriminates Bearer vs OAuth tokens.
+ * OAuth tokens carry the `tmo_` prefix; all others route to Bearer path.
+ */
+export function resolveAuth(req) {
+    const header = req.headers['authorization'];
+    if (typeof header !== 'string')
+        return null;
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    const token = match?.[1]?.trim();
+    if (!token)
+        return null;
+    if (token.startsWith('tmo_')) {
+        const info = validateOAuthToken(token);
+        if (!info)
+            return { type: 'invalid_token' };
+        return { type: 'oauth', info };
+    }
+    return { type: 'bearer', token };
+}
+const REFILL_INTERVAL_MS = 60_000;
+export class RateLimiter {
+    buckets = new Map();
+    limit;
+    constructor(limit) {
+        const fromEnv = Number.parseInt(process.env['MCP_RATE_LIMIT_RPM'] ?? '', 10);
+        this.limit = limit ?? (Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 100);
+    }
+    /** Consumes one token for the IP; returns false when exhausted. */
+    tryConsume(ip) {
+        const now = Date.now();
+        let bucket = this.buckets.get(ip);
+        if (!bucket) {
+            bucket = { tokens: this.limit, lastRefill: now };
+            this.buckets.set(ip, bucket);
+        }
+        else if (now - bucket.lastRefill >= REFILL_INTERVAL_MS) {
+            bucket.tokens = this.limit;
+            bucket.lastRefill = now;
+        }
+        if (bucket.tokens <= 0)
+            return false;
+        bucket.tokens -= 1;
+        return true;
+    }
+}

package/dist/client.d.ts

@@ -9,6 +9,7 @@
  */
 export interface TacitClientOptions {
     apiUrl?: string;
+    appUrl?: string;
     token?: string;
     workspaceId?: string;
     /** Override the root directory used to locate .tacit/sync.json (default: process.cwd()). */
@@ -16,10 +17,13 @@ export interface TacitClientOptions {
 }
 export declare class TacitClient {
     private readonly apiUrl;
-    private readonly token;
+    private readonly _appUrl;
+    private token;
     private readonly _fetch;
     private readonly _rootDir;
-    readonly workspaceId: string;
+    private _workspaceId;
+    private _workspaceName;
+    private _initialized;
     /**
      * @param fetchOrOpts - Optional: a custom fetch implementation (for testing),
      *   or a TacitClientOptions object. If a function is provided it overrides
@@ -28,6 +32,13 @@ export declare class TacitClient {
      *   Only used when fetchOrOpts is a fetch function.
      */
     constructor(fetchOrOpts?: typeof globalThis.fetch | TacitClientOptions, opts?: TacitClientOptions);
+    get workspaceId(): string;
+    get workspaceName(): string | null;
+    initialize(): Promise<void>;
+    switchWorkspace(workspaceId: string): Promise<{
+        workspace_id: string;
+        name: string;
+    }>;
     /**
      * Resolve the workspace ID:
      *   1. Read workspace_id from <rootDir>/.tacit/sync.json if the file exists.
@@ -35,12 +46,38 @@ export declare class TacitClient {
      *   3. Return null if neither source is available.
      */
     resolveWorkspaceId(): Promise<string | null>;
-    /** Build auth headers. Value is NEVER written to logs. */
+    /**
+     * Build a user-facing URL for an entity in the TACIT web app.
+     * Returns null when TACIT_APP_URL is not configured.
+     *
+     * Route patterns (TanStack file-based routing in tacitai.app.beta):
+     *   artifact   → /view/:id
+     *   kb_article → /knowledge/:collectionId/:articleId
+     *   dossier    → /dossiers  (list; no single-dossier route yet)
+     *   guest      → /guest/view/:id
+     */
+    webUrl(entityType: string, id: string, extra?: {
+        collectionId?: string;
+    }): string | null;
+    /**
+     * Build auth headers. Value is NEVER written to logs.
+     *
+     * MV-1515n (W5 harness): when TACIT_SESSION_TOKEN is set (an HMAC
+     * X-Tacit-Session token, per tacit-internal-token-auth §HMAC session token
+     * format), it takes precedence and is sent as X-Tacit-Session instead of
+     * Authorization — this is additive and does not change default behavior
+     * (Bearer via TACIT_TOKEN) when TACIT_SESSION_TOKEN is unset.
+     */
     private authHeaders;
     /** GET request returning parsed JSON. */
     get<T = unknown>(endpoint: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
-    /** POST request returning parsed JSON. */
-    post<T = unknown>(endpoint: string, body: unknown): Promise<T>;
+    /** POST request returning parsed JSON. `extraHeaders` merges on top of auth headers (e.g. If-Match). */
+    post<T = unknown>(endpoint: string, body: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /** PUT request returning parsed JSON. */
+    put<T = unknown>(endpoint: string, body: unknown): Promise<T>;
+    /** DELETE request returning parsed JSON (or empty on 204). */
+    delete<T = unknown>(endpoint: string): Promise<T | null>;
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
     /** PATCH request returning parsed JSON. */
     patch<T = unknown>(endpoint: string, body: unknown): Promise<T>;
     /**
@@ -57,4 +94,22 @@ export declare class TacitApiError extends Error {
     readonly endpoint: string;
     constructor(statusCode: number, body: string, endpoint: string);
 }
+/**
+ * Thrown when the API returns 401 — indicates the developer token has expired
+ * or been revoked. Tools catch this and surface a user-actionable message.
+ *
+ * FEAT-193: The server grants a 7-day grace window after expiry — during that
+ * window, `POST /api/v1/developer-tokens/refresh` still works (no browser
+ * re-auth needed). After 7 days, full device-auth is required.
+ *
+ * Security invariant: token plaintext is NEVER included in this error.
+ */
+export declare class TokenExpiredError extends Error {
+    readonly renewalUrl: string;
+    readonly setupCommand: string;
+    constructor(renewalUrl: string, setupCommand: string);
+}
+/** HTTPS mode: bind the caller's token/apiUrl/principal to everything run inside fn. */
+export declare function runWithRequestContext<T>(token: string, apiUrl: string, fn: () => Promise<T>, principal?: string): Promise<T>;
+export declare function getRequestPrincipal(): string | null;
 export declare function getClient(): TacitClient;

package/dist/client.js

@@ -1,4 +1,3 @@
-"use strict";
 // SPDX-License-Identifier: MIT
 /**
  * TacitClient — REST/SSE client over TACIT_API_URL.
@@ -9,50 +8,22 @@
  *  - No anthropic/openai SDK import.
  *  - Token sourced exclusively from process.env.TACIT_TOKEN.
  */
-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.TacitApiError = exports.TacitClient = void 0;
-exports.getClient = getClient;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-class TacitClient {
+import * as fs from 'fs';
+import * as path from 'path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+function isHmacSessionToken(token) {
+    const parts = token.split('.');
+    return parts.length === 2 && /^[0-9a-f]{64}$/.test(parts[1]);
+}
+export class TacitClient {
     apiUrl;
+    _appUrl;
     token;
     _fetch;
     _rootDir;
-    workspaceId;
+    _workspaceId;
+    _workspaceName = null;
+    _initialized = false;
     /**
      * @param fetchOrOpts - Optional: a custom fetch implementation (for testing),
      *   or a TacitClientOptions object. If a function is provided it overrides
@@ -72,6 +43,7 @@ class TacitClient {
             this._fetch = globalThis.fetch.bind(globalThis);
         }
         this.apiUrl = (resolvedOpts.apiUrl ?? process.env['TACIT_API_URL'] ?? 'http://localhost:7473').replace(/\/$/, '');
+        this._appUrl = (resolvedOpts.appUrl ?? process.env['TACIT_APP_URL'] ?? '').replace(/\/$/, '');
         // Token from env only — NEVER log this value.
         this.token = resolvedOpts.token ?? process.env['TACIT_TOKEN'] ?? '';
         this._rootDir = resolvedOpts.rootDir ?? process.cwd();
@@ -90,7 +62,63 @@ class TacitClient {
         catch {
             // Soft-coupled: ignore read errors; fall back to env.
         }
-        this.workspaceId = resolvedWorkspaceId;
+        this._workspaceId = resolvedWorkspaceId;
+    }
+    get workspaceId() {
+        return this._workspaceId;
+    }
+    get workspaceName() {
+        return this._workspaceName;
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        try {
+            const data = await this.get('/api/v1/workspaces/mine');
+            if (data && typeof data === 'object') {
+                if ('active_workspace_id' in data && typeof data.active_workspace_id === 'string') {
+                    this._workspaceId = data.active_workspace_id;
+                }
+                if (Array.isArray(data.workspaces) && data.workspaces.length > 0) {
+                    const active = data.workspaces.find((w) => w.workspace_id === this._workspaceId || w.id === this._workspaceId);
+                    if (active) {
+                        const name = active.display_name ?? active.name;
+                        if (typeof name === 'string')
+                            this._workspaceName = name;
+                    }
+                    if (!this._workspaceId) {
+                        const first = data.workspaces[0];
+                        this._workspaceId = (first.workspace_id ?? first.id);
+                        const name = first.display_name ?? first.name;
+                        if (typeof name === 'string')
+                            this._workspaceName = name;
+                    }
+                }
+            }
+            this._initialized = true;
+        }
+        catch {
+            this._initialized = true;
+        }
+    }
+    async switchWorkspace(workspaceId) {
+        const data = await this.post('/api/v1/auth/switch-workspace', {
+            workspace_id: workspaceId,
+        });
+        if (data && typeof data === 'object' && 'token' in data && typeof data.token === 'string') {
+            this.token = data.token;
+        }
+        this._workspaceId = workspaceId;
+        if (data && typeof data === 'object' && 'name' in data && typeof data.name === 'string') {
+            this._workspaceName = data.name;
+        }
+        else {
+            this._workspaceName = null;
+        }
+        return {
+            workspace_id: workspaceId,
+            name: this._workspaceName ?? 'unknown',
+        };
     }
     /**
      * Resolve the workspace ID:
@@ -114,15 +142,71 @@ class TacitClient {
         const envId = process.env['TACIT_WORKSPACE_ID'];
         return (envId && envId.length > 0) ? envId : null;
     }
-    /** Build auth headers. Value is NEVER written to logs. */
-    authHeaders() {
+    /**
+     * Build a user-facing URL for an entity in the TACIT web app.
+     * Returns null when TACIT_APP_URL is not configured.
+     *
+     * Route patterns (TanStack file-based routing in tacitai.app.beta):
+     *   artifact   → /view/:id
+     *   kb_article → /knowledge/:collectionId/:articleId
+     *   dossier    → /dossiers  (list; no single-dossier route yet)
+     *   guest      → /guest/view/:id
+     */
+    webUrl(entityType, id, extra) {
+        if (!this._appUrl)
+            return null;
+        switch (entityType) {
+            case 'artifact':
+                return `${this._appUrl}/view/${id}`;
+            case 'kb_article':
+                return extra?.collectionId
+                    ? `${this._appUrl}/knowledge/${extra.collectionId}/${id}`
+                    : null;
+            case 'dossier':
+                return `${this._appUrl}/dossiers`;
+            case 'dossier_summary':
+                return `${this._appUrl}/summary/${id}`;
+            case 'dossier_scorecard':
+                return `${this._appUrl}/scorecard/${id}`;
+            case 'dossier_deliverable':
+                return extra?.collectionId
+                    ? `${this._appUrl}/deliverables/${extra.collectionId}/${id}`
+                    : `${this._appUrl}/dossiers`;
+            case 'guest':
+                return `${this._appUrl}/guest/view/${id}`;
+            case 'knowledge':
+                return `${this._appUrl}/knowledge`;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Build auth headers. Value is NEVER written to logs.
+     *
+     * MV-1515n (W5 harness): when TACIT_SESSION_TOKEN is set (an HMAC
+     * X-Tacit-Session token, per tacit-internal-token-auth §HMAC session token
+     * format), it takes precedence and is sent as X-Tacit-Session instead of
+     * Authorization — this is additive and does not change default behavior
+     * (Bearer via TACIT_TOKEN) when TACIT_SESSION_TOKEN is unset.
+     */
+    authHeaders(extra) {
         const headers = {
             'Content-Type': 'application/json',
         };
-        if (this.token) {
-            // Authorization header value intentionally excluded from all logging paths.
-            headers['Authorization'] = `Bearer ${this.token}`;
+        const sessionToken = process.env['TACIT_SESSION_TOKEN'];
+        if (sessionToken) {
+            headers['X-Tacit-Session'] = sessionToken;
+        }
+        else if (this.token) {
+            if (isHmacSessionToken(this.token)) {
+                headers['X-Tacit-Session'] = this.token;
+            }
+            else {
+                headers['Authorization'] = `Bearer ${this.token}`;
+            }
         }
+        if (extra)
+            Object.assign(headers, extra);
         return headers;
     }
     /** GET request returning parsed JSON. */
@@ -140,23 +224,72 @@ class TacitClient {
         });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
             throw new TacitApiError(res.status, body, endpoint);
         }
         return res.json();
     }
-    /** POST request returning parsed JSON. */
-    async post(endpoint, body) {
+    /** POST request returning parsed JSON. `extraHeaders` merges on top of auth headers (e.g. If-Match). */
+    async post(endpoint, body, extraHeaders) {
         const res = await this._fetch(`${this.apiUrl}${endpoint}`, {
             method: 'POST',
+            headers: this.authHeaders(extraHeaders),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
+            throw new TacitApiError(res.status, text, endpoint);
+        }
+        return res.json();
+    }
+    /** PUT request returning parsed JSON. */
+    async put(endpoint, body) {
+        const res = await this._fetch(`${this.apiUrl}${endpoint}`, {
+            method: 'PUT',
             headers: this.authHeaders(),
             body: JSON.stringify(body),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
             throw new TacitApiError(res.status, text, endpoint);
         }
         return res.json();
     }
+    /** DELETE request returning parsed JSON (or empty on 204). */
+    async delete(endpoint) {
+        const res = await this._fetch(`${this.apiUrl}${endpoint}`, {
+            method: 'DELETE',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
+            throw new TacitApiError(res.status, text, endpoint);
+        }
+        if (res.status === 204)
+            return null;
+        return res.json();
+    }
+    async request(method, path, body) {
+        switch (method.toUpperCase()) {
+            case 'GET': return this.get(path);
+            case 'POST': return this.post(path, body);
+            case 'PUT': return this.put(path, body);
+            case 'PATCH': return this.patch(path, body);
+            case 'DELETE': return this.delete(path);
+            default: throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+    }
     /** PATCH request returning parsed JSON. */
     async patch(endpoint, body) {
         const res = await this._fetch(`${this.apiUrl}${endpoint}`, {
@@ -166,8 +299,14 @@ class TacitClient {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
             throw new TacitApiError(res.status, text, endpoint);
         }
+        if (res.status === 204) {
+            return {};
+        }
         return res.json();
     }
     /**
@@ -185,6 +324,9 @@ class TacitClient {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
             throw new TacitApiError(res.status, text, endpoint);
         }
         if (!res.body) {
@@ -236,13 +378,15 @@ class TacitClient {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => '');
+            if (res.status === 401) {
+                throw new TokenExpiredError(`${this.apiUrl}/settings`, `npx @tacitai/mcp-server setup --api-url ${this.apiUrl}`);
+            }
             throw new TacitApiError(res.status, text, endpoint);
         }
         return res.json();
     }
 }
-exports.TacitClient = TacitClient;
-class TacitApiError extends Error {
+export class TacitApiError extends Error {
     statusCode;
     body;
     endpoint;
@@ -254,10 +398,47 @@ class TacitApiError extends Error {
         this.name = 'TacitApiError';
     }
 }
-exports.TacitApiError = TacitApiError;
+/**
+ * Thrown when the API returns 401 — indicates the developer token has expired
+ * or been revoked. Tools catch this and surface a user-actionable message.
+ *
+ * FEAT-193: The server grants a 7-day grace window after expiry — during that
+ * window, `POST /api/v1/developer-tokens/refresh` still works (no browser
+ * re-auth needed). After 7 days, full device-auth is required.
+ *
+ * Security invariant: token plaintext is NEVER included in this error.
+ */
+export class TokenExpiredError extends Error {
+    renewalUrl;
+    setupCommand;
+    constructor(renewalUrl, setupCommand) {
+        const msg = [
+            'Developer token expired or revoked.',
+            'Re-authenticate within 7 days for easy refresh (no browser flow needed).',
+            `Renew at: ${renewalUrl}`,
+            `Re-run setup: ${setupCommand}`,
+        ].join('\n');
+        super(msg);
+        this.renewalUrl = renewalUrl;
+        this.setupCommand = setupCommand;
+        this.name = 'TokenExpiredError';
+    }
+}
+const requestStore = new AsyncLocalStorage();
+/** HTTPS mode: bind the caller's token/apiUrl/principal to everything run inside fn. */
+export function runWithRequestContext(token, apiUrl, fn, principal) {
+    return requestStore.run({ token, apiUrl, principal: principal ?? 'anonymous' }, fn);
+}
+export function getRequestPrincipal() {
+    return requestStore.getStore()?.principal ?? null;
+}
 /** Shared singleton client (initialized lazily on first use). */
 let _defaultClient = null;
-function getClient() {
+export function getClient() {
+    const ctx = requestStore.getStore();
+    if (ctx) {
+        return new TacitClient({ apiUrl: ctx.apiUrl, token: ctx.token });
+    }
     if (!_defaultClient) {
         _defaultClient = new TacitClient();
     }