@telvok/librarian-mcp 2.0.0 → 2.3.0

package/dist/library/sensitive-scanner.d.ts

@@ -0,0 +1,20 @@
+export interface SensitiveFinding {
+    entry: string;
+    file?: string;
+    matches: string[];
+}
+interface ScannableEntry {
+    title: string;
+    content: string;
+    intent?: string;
+    context?: string;
+    reasoning?: string;
+    example?: string;
+    originalPath?: string;
+}
+/**
+ * Scan entries for sensitive data patterns.
+ * Returns findings grouped by entry.
+ */
+export declare function scanForSensitiveData(entries: ScannableEntry[]): SensitiveFinding[];
+export {};

package/dist/library/sensitive-scanner.js

@@ -0,0 +1,56 @@
+// ============================================================================
+// Sensitive Data Scanner
+// Shared module for scanning entries before they leave the user's machine.
+// Used by: library_publish (mandatory), audit tool (on-demand)
+// ============================================================================
+const SENSITIVE_PATTERNS = [
+    // API keys and tokens
+    { pattern: /sk_(live|test)_[a-zA-Z0-9]{10,}/g, label: 'Stripe secret key' },
+    { pattern: /whsec_[a-zA-Z0-9]{10,}/g, label: 'Stripe webhook secret' },
+    { pattern: /tvk_[a-zA-Z0-9]{20,}/g, label: 'Telvok API key' },
+    { pattern: /ghp_[a-zA-Z0-9]{36}/g, label: 'GitHub personal access token' },
+    { pattern: /xoxb-[a-zA-Z0-9-]+/g, label: 'Slack bot token' },
+    { pattern: /eyJ[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}/g, label: 'JWT token' },
+    { pattern: /AKIA[A-Z0-9]{16}/g, label: 'AWS access key' },
+    { pattern: /npm_[a-zA-Z0-9]{36}/g, label: 'npm token' },
+    // Credentials in assignments
+    { pattern: /password\s*[:=]\s*['"][^'"]+['"]/gi, label: 'password value' },
+    { pattern: /secret\s*[:=]\s*['"][^'"]+['"]/gi, label: 'secret value' },
+    { pattern: /api[_-]?key\s*[:=]\s*['"][^'"]+['"]/gi, label: 'API key value' },
+    // Personal data
+    { pattern: /\b[a-zA-Z0-9._%+-]+@(?!example\.com)[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/g, label: 'email address' },
+    // Connection strings with credentials
+    { pattern: /:\/\/[^:]+:[^@]+@[^/\s]+/g, label: 'URL with embedded credentials' },
+];
+/**
+ * Scan entries for sensitive data patterns.
+ * Returns findings grouped by entry.
+ */
+export function scanForSensitiveData(entries) {
+    const findings = [];
+    for (const entry of entries) {
+        const textToScan = [
+            entry.title,
+            entry.content,
+            entry.intent,
+            entry.context,
+            entry.reasoning,
+            entry.example,
+        ].filter(Boolean).join('\n');
+        const matches = [];
+        for (const { pattern, label } of SENSITIVE_PATTERNS) {
+            pattern.lastIndex = 0;
+            if (pattern.test(textToScan)) {
+                matches.push(label);
+            }
+        }
+        if (matches.length > 0) {
+            findings.push({
+                entry: entry.title,
+                file: entry.originalPath,
+                matches,
+            });
+        }
+    }
+    return findings;
+}

package/dist/server.js

@@ -27,6 +27,7 @@ import { bountySubmitTool } from './tools/bounty-submit.js';
 import { myBountiesTool } from './tools/my-bounties.js';
 import { deleteTool } from './tools/delete.js';
 import { unsubscribeTool } from './tools/unsubscribe.js';
+import { auditTool } from './tools/audit.js';
 const allTools = [
     // Core tools — local knowledge management
     { tool: briefTool, group: 'core' },
@@ -36,6 +37,7 @@ const allTools = [
     { tool: importMemoriesTool, group: 'core' },
     { tool: rebuildIndexTool, group: 'core' },
     { tool: deleteTool, group: 'core' },
+    { tool: auditTool, group: 'core' },
     // Marketplace tools — cloud features
     { tool: librarySearchTool, group: 'marketplace' },
     { tool: libraryBuyTool, group: 'marketplace' },

package/dist/tools/audit.d.ts

@@ -0,0 +1,27 @@
+import { type SensitiveFinding } from '../library/sensitive-scanner.js';
+interface AuditResult {
+    success: boolean;
+    message: string;
+    total_scanned: number;
+    findings: SensitiveFinding[];
+    clean: boolean;
+}
+export declare const auditTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            entries: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+    };
+    handler(args: unknown): Promise<AuditResult>;
+};
+export {};

package/dist/tools/audit.js

@@ -0,0 +1,126 @@
+// ============================================================================
+// Audit Tool
+// Scan local entries for sensitive data before publishing
+// ============================================================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import { getLibraryPath, getLocalPath } from '../library/storage.js';
+import { scanForSensitiveData } from '../library/sensitive-scanner.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const auditTool = {
+    name: 'audit',
+    title: 'Audit Entries',
+    description: `Scan local entries for sensitive data (API keys, passwords, emails, tokens, credentials).
+
+USE THIS TOOL WHEN:
+- Before publishing a book — catches leaks before they go public
+- User says "audit", "check for secrets", or "scan my entries"
+- After recording entries that involved credentials or auth work
+- Proactively before any library_publish() call
+
+Returns a list of entries with sensitive data findings, or confirms all clear.
+
+TRIGGER PATTERNS:
+- Before publishing → audit()
+- "Check my entries for secrets" → audit()
+- Scan specific entries → audit({ entries: ["file1.md", "file2.md"] })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            entries: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Specific entry filenames to audit (omit to scan all local/)',
+            },
+        },
+    },
+    async handler(args) {
+        const { entries: entryFilter } = (args || {});
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        // Collect entries
+        const collectedEntries = [];
+        try {
+            const files = await glob(path.join(localPath, '**/*.md'), { nodir: true });
+            for (const filePath of files) {
+                const filename = path.basename(filePath);
+                if (entryFilter && entryFilter.length > 0) {
+                    const matchesFilter = entryFilter.some(f => filename === f ||
+                        filename === f + '.md' ||
+                        filePath.endsWith(f) ||
+                        filePath.endsWith(f + '.md'));
+                    if (!matchesFilter)
+                        continue;
+                }
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const { data: frontmatter, content: body } = matter(content);
+                    const trimmedBody = body.trim();
+                    if (!trimmedBody)
+                        continue;
+                    let title = frontmatter.title;
+                    if (!title) {
+                        const headingMatch = trimmedBody.match(/^#\s+(.+)$/m);
+                        title = headingMatch ? headingMatch[1].trim() : path.basename(filePath, '.md');
+                    }
+                    // Extract sections
+                    const reasoningMatch = trimmedBody.match(/##\s*Reasoning\s*\n([\s\S]*?)(?=##|$)/i);
+                    const exampleMatch = trimmedBody.match(/##\s*Example\s*\n([\s\S]*?)(?=##|$)/i);
+                    collectedEntries.push({
+                        title,
+                        content: trimmedBody,
+                        intent: frontmatter.intent || undefined,
+                        context: frontmatter.context || undefined,
+                        reasoning: reasoningMatch ? reasoningMatch[1].trim() : undefined,
+                        example: exampleMatch ? exampleMatch[1].trim() : undefined,
+                        originalPath: filePath,
+                    });
+                }
+                catch {
+                    // Skip unparseable files
+                }
+            }
+        }
+        catch {
+            return {
+                success: false,
+                message: 'No .librarian/local/ directory found.',
+                total_scanned: 0,
+                findings: [],
+                clean: false,
+            };
+        }
+        if (collectedEntries.length === 0) {
+            return {
+                success: true,
+                message: 'No entries found to audit.',
+                total_scanned: 0,
+                findings: [],
+                clean: true,
+            };
+        }
+        // Run scan
+        const findings = scanForSensitiveData(collectedEntries);
+        if (findings.length === 0) {
+            return {
+                success: true,
+                message: `✅ All clear — scanned ${collectedEntries.length} entries, no sensitive data found.`,
+                total_scanned: collectedEntries.length,
+                findings: [],
+                clean: true,
+            };
+        }
+        const warnings = findings.map(f => `  ⚠ ${f.entry}: ${f.matches.join(', ')}`).join('\n');
+        return {
+            success: true,
+            message: `⚠ Found sensitive data in ${findings.length} of ${collectedEntries.length} entries:\n${warnings}\n\nClean these up with record() or delete() before publishing.`,
+            total_scanned: collectedEntries.length,
+            findings,
+            clean: false,
+        };
+    },
+};

package/dist/tools/library-publish.d.ts

@@ -1,6 +1,7 @@
 interface PublishResult {
     success: boolean;
     message: string;
+    publish_token?: string;
     book?: {
         id?: string;
         slug: string;
@@ -85,6 +86,10 @@ export declare const libraryPublishTool: {
                 type: string;
                 description: string;
             };
+            publish_token: {
+                type: string;
+                description: string;
+            };
             entries: {
                 type: string;
                 items: {

package/dist/tools/library-publish.js

@@ -4,36 +4,41 @@
 // ============================================================================
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import * as crypto from 'crypto';
 import { glob } from 'glob';
 import matter from 'gray-matter';
 import { loadApiKey } from './auth.js';
 import { getLibraryPath, getLocalPath } from '../library/storage.js';
+import { scanForSensitiveData } from '../library/sensitive-scanner.js';
 const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+const TOKEN_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+let pendingPublish = null;
 // ============================================================================
 // Tool Definition
 // ============================================================================
 export const libraryPublishTool = {
     name: 'library_publish',
     title: 'Publish Book',
-    description: `Publish local entries as a book on Telvok marketplace.
+    description: `Publish local entries as a book on Telvok library.
 
-USE THIS TOOL WHEN:
-- User wants to share/sell their recorded knowledge
-- User says "publish", "share", or "sell" their entries
-- Creating a book from .librarian/local/ entries
+⚠️ TWO-STEP PUBLISH FLOW (MANDATORY):
 
-ALWAYS use preview: true first to show what will be published.
+Step 1: ALWAYS call with preview: true first. This shows what will be published
+and returns a publish_token. Show the preview to the user and ASK FOR CONFIRMATION.
+
+Step 2: ONLY after the user explicitly confirms, call again with the publish_token
+from the preview response. Publishing WITHOUT a valid token will be rejected.
+
+DO NOT skip the preview. DO NOT publish without user confirmation.
+The tool will refuse to publish without a valid publish_token from a preview.
 
 TRIGGER PATTERNS:
 - "Publish my entries" → library_publish({ name: "...", pricing: { type: "open" }, preview: true })
-- "Sell my knowledge" → library_publish({ name: "...", pricing: { type: "one_time", price_cents: 500 }, preview: true })
-- After preview approval → add attestation and consumption, remove preview
-
-Required for actual publish: name, pricing, consumption, attestation (all true).
+- User says "yes, publish it" → library_publish({ ..., publish_token: "<token from preview>" })
 
 Examples:
 - Preview: library_publish({ name: "My Book", pricing: { type: "open" }, preview: true })
-- Publish: library_publish({ name: "My Book", pricing: { type: "open" }, consumption: "download", attestation: { original_work: true, no_secrets: true, terms_accepted: true } })`,
+- Publish: library_publish({ name: "My Book", pricing: { type: "open" }, consumption: "download", attestation: { original_work: true, no_secrets: true, terms_accepted: true }, publish_token: "abc123" })`,
     inputSchema: {
         type: 'object',
         properties: {
@@ -78,7 +83,11 @@ Examples:
             },
             preview: {
                 type: 'boolean',
-                description: 'If true, show what would be published without publishing',
+                description: 'If true, show what would be published without publishing. Returns a publish_token.',
+            },
+            publish_token: {
+                type: 'string',
+                description: 'Token from preview response. Required to actually publish. Single-use, expires in 5 minutes.',
             },
             entries: {
                 type: 'array',
@@ -99,7 +108,7 @@ Examples:
         required: ['name', 'pricing'],
     },
     async handler(args) {
-        const { name, description, pricing, consumption, attestation, preview, entries: entryFilter, tags, license } = args;
+        const { name, description, pricing, consumption, attestation, preview, publish_token, entries: entryFilter, tags, license } = args;
         // Validate name
         if (!name || typeof name !== 'string' || name.trim().length < 3) {
             throw new Error('Book name is required (minimum 3 characters)');
@@ -130,6 +139,24 @@ Examples:
         }
         // Collect entries from local/ (needed for preview and publish)
         const collectedEntries = await collectLocalEntries(entryFilter);
+        // Scan for sensitive data before publishing
+        const sensitiveFindings = scanForSensitiveData(collectedEntries);
+        if (sensitiveFindings.length > 0) {
+            const warnings = sensitiveFindings.map(f => `  ⚠ ${f.entry}: ${f.matches.join(', ')}`).join('\n');
+            if (preview) {
+                // In preview mode, show warnings but continue
+                return {
+                    success: true,
+                    preview: true,
+                    message: `⚠ SENSITIVE DATA DETECTED in ${sensitiveFindings.length} entry(s):\n${warnings}\n\nReview these entries before publishing. Remove credentials, API keys, passwords, and personal data.`,
+                };
+            }
+            // In publish mode, block and require cleanup
+            return {
+                success: false,
+                message: `🚫 Publish blocked — sensitive data detected in ${sensitiveFindings.length} entry(s):\n${warnings}\n\nClean up these entries with record() or delete() before publishing. Use library_publish({ preview: true }) to re-check.`,
+            };
+        }
         if (collectedEntries.length === 0) {
             return {
                 success: false,
@@ -140,12 +167,20 @@ Examples:
         const pricingDisplay = pricing.type === 'open'
             ? 'Free'
             : `$${((pricing.price_cents || 0) / 100).toFixed(2)}`;
-        // Handle preview mode - return summary without publishing
+        // Handle preview mode - return summary with publish token
         if (preview) {
+            const token = crypto.randomBytes(16).toString('hex');
+            pendingPublish = {
+                token,
+                name: name.trim(),
+                entries_count: collectedEntries.length,
+                created: Date.now(),
+            };
             return {
                 success: true,
                 preview: true,
-                message: `Preview of "${name.trim()}" - NOT published`,
+                message: `Preview of "${name.trim()}" - NOT published yet.\n\n⚠️ Show this to the user and ask for confirmation before publishing.`,
+                publish_token: token,
                 summary: {
                     name: name.trim(),
                     pricing: { type: pricing.type, display: pricingDisplay },
@@ -155,9 +190,34 @@ Examples:
                         file: path.basename(e.originalPath),
                     })),
                 },
-                next_steps: 'To publish, add consumption type and attestation fields.',
+                next_steps: 'Show preview to user. After they confirm, call library_publish() again with the publish_token to publish.',
+            };
+        }
+        // ========================================================================
+        // PUBLISH TOKEN VALIDATION
+        // Cannot publish without a valid token from preview
+        // ========================================================================
+        if (!publish_token) {
+            return {
+                success: false,
+                message: '🚫 Publishing requires a publish_token from a preview.\n\nYou must call library_publish({ preview: true, ... }) first, show the preview to the user, get their confirmation, then call again with the publish_token.\n\nThis is a safety measure to prevent accidental publishing.',
+            };
+        }
+        if (!pendingPublish || pendingPublish.token !== publish_token) {
+            return {
+                success: false,
+                message: '🚫 Invalid or expired publish_token. Run a new preview first with library_publish({ preview: true, ... }).',
+            };
+        }
+        if (Date.now() - pendingPublish.created > TOKEN_EXPIRY_MS) {
+            pendingPublish = null;
+            return {
+                success: false,
+                message: '🚫 Publish token expired (5 minute limit). Run a new preview first.',
             };
         }
+        // Token is valid — consume it (single use)
+        pendingPublish = null;
         // Validate consumption type (required for actual publish)
         if (!consumption) {
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telvok/librarian-mcp",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "Knowledge capture MCP server - remember what you learn with AI",
   "type": "module",
   "main": "dist/server.js",