@karmaniverous/jeeves-server 3.0.0-0

package/dist/src/routes/event.test.js

@@ -0,0 +1,206 @@
+/**
+ * Event route tests
+ */
+import { JsonMap } from '@karmaniverous/jsonmap';
+import Ajv from 'ajv';
+import * as _ from 'radash';
+import { describe, expect, it } from 'vitest';
+const ajv = new Ajv();
+describe('event route', () => {
+    describe('schema matching', () => {
+        it('should match against JSON Schema', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    type: { const: 'page.content_updated' },
+                },
+                required: ['type'],
+            };
+            const validate = ajv.compile(schema);
+            expect(validate({ type: 'page.content_updated', data: {} })).toBe(true);
+            expect(validate({ type: 'other' })).toBe(false);
+            expect(validate({ data: {} })).toBe(false);
+        });
+        it('should match first schema in order', () => {
+            const schema1 = {
+                type: 'object',
+                properties: {
+                    source: { const: 'github' },
+                },
+                required: ['source'],
+            };
+            const schema2 = {
+                type: 'object',
+                properties: {
+                    type: { const: 'generic' },
+                },
+                required: ['type'],
+            };
+            const body = { source: 'github', type: 'generic' };
+            const validate1 = ajv.compile(schema1);
+            const validate2 = ajv.compile(schema2);
+            // Both match, but first wins
+            expect(validate1(body)).toBe(true);
+            expect(validate2(body)).toBe(true);
+        });
+        it('should handle complex nested schemas', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    data: {
+                        type: 'object',
+                        properties: {
+                            page_id: { type: 'string' },
+                        },
+                        required: ['page_id'],
+                    },
+                },
+                required: ['data'],
+            };
+            const validate = ajv.compile(schema);
+            expect(validate({ data: { page_id: 'abc123' } })).toBe(true);
+            expect(validate({ data: {} })).toBe(false);
+            expect(validate({})).toBe(false);
+        });
+    });
+    describe('JsonMap transformation', () => {
+        it('should extract fields using radash get', async () => {
+            const body = {
+                type: 'page.content_updated',
+                data: {
+                    page_id: 'abc123',
+                    title: 'Test Page',
+                },
+            };
+            const map = {
+                pageId: {
+                    $: { method: '$.lib._.get', params: ['$.input', 'data.page_id'] },
+                },
+                type: {
+                    $: { method: '$.lib._.get', params: ['$.input', 'type'] },
+                },
+            };
+            const mapper = new JsonMap(map, { _: _ });
+            const result = (await mapper.transform(body));
+            expect(result.pageId).toBe('abc123');
+            expect(result.type).toBe('page.content_updated');
+        });
+        it('should handle missing fields gracefully', async () => {
+            const body = {
+                type: 'event',
+            };
+            const map = {
+                pageId: {
+                    $: { method: '$.lib._.get', params: ['$.input', 'data.page_id'] },
+                },
+                type: {
+                    $: { method: '$.lib._.get', params: ['$.input', 'type'] },
+                },
+            };
+            const mapper = new JsonMap(map, { _: _ });
+            const result = (await mapper.transform(body));
+            expect(result.pageId).toBeUndefined();
+            expect(result.type).toBe('event');
+        });
+        it('should preserve full body when no map is defined', () => {
+            const body = {
+                type: 'event',
+                data: { foo: 'bar' },
+                nested: { a: { b: 'c' } },
+            };
+            // No transformation when map is undefined
+            const result = body;
+            expect(result).toEqual(body);
+            expect(result.data).toEqual({ foo: 'bar' });
+            expect(result.nested).toEqual({ a: { b: 'c' } });
+        });
+        it('should handle nested path extraction', async () => {
+            const body = {
+                metadata: {
+                    author: {
+                        name: 'Alice',
+                        email: 'alice@example.com',
+                    },
+                    tags: ['important', 'review'],
+                },
+            };
+            const map = {
+                authorName: {
+                    $: {
+                        method: '$.lib._.get',
+                        params: ['$.input', 'metadata.author.name'],
+                    },
+                },
+                authorEmail: {
+                    $: {
+                        method: '$.lib._.get',
+                        params: ['$.input', 'metadata.author.email'],
+                    },
+                },
+            };
+            const mapper = new JsonMap(map, { _: _ });
+            const result = (await mapper.transform(body));
+            expect(result.authorName).toBe('Alice');
+            expect(result.authorEmail).toBe('alice@example.com');
+        });
+    });
+    describe('queue entry formatting', () => {
+        it('should format entry with all required fields', () => {
+            const entry = {
+                ts: new Date().toISOString(),
+                event: 'test-event',
+                cmd: 'node test.js',
+                body: { foo: 'bar' },
+                timeoutMs: 30000,
+            };
+            expect(entry.ts).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+            expect(entry.event).toBe('test-event');
+            expect(entry.cmd).toBe('node test.js');
+            expect(entry.body).toEqual({ foo: 'bar' });
+            expect(entry.timeoutMs).toBe(30000);
+        });
+        it('should use default timeout when not specified', () => {
+            const defaultTimeoutMs = 30000;
+            const eventConfig = {}; // Simulate config without timeoutMs
+            const timeoutMs = eventConfig.timeoutMs ?? defaultTimeoutMs;
+            expect(timeoutMs).toBe(30000);
+        });
+        it('should use event-specific timeout when specified', () => {
+            const defaultTimeoutMs = 30000;
+            const eventConfig = { timeoutMs: 60000 };
+            const timeoutMs = eventConfig.timeoutMs ?? defaultTimeoutMs;
+            expect(timeoutMs).toBe(60000);
+        });
+    });
+    describe('event log formatting', () => {
+        it('should format matched event log entry', () => {
+            const entry = {
+                ts: new Date().toISOString(),
+                event: 'test-event',
+                matched: true,
+                exitCode: 0,
+                durationMs: 1234,
+            };
+            expect(entry.matched).toBe(true);
+            expect(entry.event).toBe('test-event');
+            expect(entry.exitCode).toBe(0);
+            expect(entry.durationMs).toBe(1234);
+        });
+        it('should format unmatched event log entry', () => {
+            const entry = {
+                ts: new Date().toISOString(),
+                event: null,
+                matched: false,
+                bodyPreview: '{"type":"unknown"}',
+            };
+            expect(entry.matched).toBe(false);
+            expect(entry.event).toBeNull();
+            expect(entry.bodyPreview).toBe('{"type":"unknown"}');
+        });
+        it('should truncate body preview to reasonable length', () => {
+            const longBody = { data: 'x'.repeat(300) };
+            const preview = JSON.stringify(longBody).slice(0, 200);
+            expect(preview.length).toBe(200);
+        });
+    });
+});

package/dist/src/routes/health.js

@@ -0,0 +1,10 @@
+/**
+ * Health check endpoint
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export const healthRoute = async (fastify) => {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    fastify.get('/health', async () => {
+        return { ok: true, uptime: process.uptime() };
+    });
+};

package/dist/src/routes/keys.js

@@ -0,0 +1,129 @@
+/**
+ * Key generation and management endpoints (legacy API-key-header auth).
+ *
+ * These endpoints use X-API-Key header auth (raw seed) for machine-to-machine
+ * access. The SPA equivalents in api/sharing.ts use cookie/URL-key auth.
+ */
+import crypto from 'node:crypto';
+import { findInsider, resolveInsiderKeyAuth, resolveSessionAuth, } from '../auth/resolve.js';
+import { getConfig, resetConfig } from '../config/index.js';
+import { appendEvent } from '../services/eventQueue.js';
+import { computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, timingSafeEqual, } from '../util/crypto.js';
+import { setInsiderKey, setKeyRotationTimestamp } from '../util/state.js';
+// eslint-disable-next-line @typescript-eslint/require-await
+export const keysRoute = async (fastify) => {
+    // GET /key - Compute path-specific outsider key (requires raw API key seed in header)
+    fastify.get('/key', async (request, reply) => {
+        const provided = request.headers['x-api-key'];
+        const config = getConfig();
+        if (!provided) {
+            return reply.code(401).send({ error: 'X-API-Key header required' });
+        }
+        const matched = config.resolvedKeys.find((rk) => timingSafeEqual(provided, rk.seed));
+        if (!matched) {
+            return reply.code(401).send({ error: 'Invalid API key' });
+        }
+        const targetPath = request.query.path;
+        if (!targetPath) {
+            return reply.code(400).send({ error: 'path query param required' });
+        }
+        const key = computePathKey(matched.seed, targetPath);
+        return { path: targetPath, key };
+    });
+    // GET /insider-key - Generate insider key (requires raw API key seed in header)
+    fastify.get('/insider-key', async (request, reply) => {
+        const provided = request.headers['x-api-key'];
+        const config = getConfig();
+        if (!provided) {
+            return reply.code(401).send({ error: 'X-API-Key header required' });
+        }
+        const matched = config.resolvedKeys.find((rk) => timingSafeEqual(provided, rk.seed));
+        if (!matched) {
+            return reply.code(401).send({ error: 'Invalid API key' });
+        }
+        const key = computeInsiderKey(matched.seed);
+        return { key };
+    });
+    // POST /rotate-key - Rotate key (insider key or session cookie)
+    fastify.post('/rotate-key', async (request, reply) => {
+        const provided = request.query.key;
+        const config = getConfig();
+        if (provided) {
+            // Try insider key auth
+            const insiderResult = resolveInsiderKeyAuth(config, provided);
+            if (insiderResult.valid && insiderResult.email) {
+                // Insider key rotation
+                return rotateInsiderSeed(insiderResult.email, config);
+            }
+            // Machine key rotation is not supported with TS config
+            const matched = config.resolvedKeys.find((rk) => timingSafeEqual(provided, computeInsiderKey(rk.seed)));
+            if (matched) {
+                return reply.code(501).send({
+                    error: 'Machine key rotation is not supported with TypeScript config. ' +
+                        'Update the key manually in jeeves.config.ts and restart the server.',
+                });
+            }
+        }
+        // Try session-based auth
+        const sessionResult = resolveSessionAuth(config, request);
+        if (sessionResult.valid && sessionResult.email) {
+            return rotateInsiderSeed(sessionResult.email, config);
+        }
+        return reply.code(401).send({ error: 'Invalid insider key' });
+    });
+    // GET /share - Generate outsider link (insider key or session cookie)
+    fastify.get('/share', async (request, reply) => {
+        const config = getConfig();
+        const targetPath = request.query.path;
+        if (!targetPath) {
+            return reply.code(400).send({ error: 'path query param required' });
+        }
+        // Try provided key
+        if (request.query.key) {
+            const insiderResult = resolveInsiderKeyAuth(config, request.query.key);
+            if (insiderResult.valid && insiderResult.seed) {
+                return buildShareResponse(insiderResult.seed, targetPath, request.query.exp);
+            }
+        }
+        // Try session cookie
+        const sessionResult = resolveSessionAuth(config, request);
+        if (sessionResult.valid && sessionResult.seed) {
+            return buildShareResponse(sessionResult.seed, targetPath, request.query.exp);
+        }
+        return reply.code(401).send({ error: 'Invalid insider key' });
+    });
+};
+function rotateInsiderSeed(email, config) {
+    const insider = findInsider(config.resolvedInsiders, email);
+    if (!insider?.seed)
+        return { ok: false, error: 'Insider not found' };
+    const rotatedSeed = crypto.randomBytes(32).toString('hex');
+    const timestamp = new Date().toISOString();
+    setInsiderKey(insider.email, rotatedSeed, timestamp);
+    appendEvent({
+        kind: 'insider_key_rotated',
+        email: insider.email,
+        at: timestamp,
+    });
+    setKeyRotationTimestamp(timestamp);
+    resetConfig();
+    return { ok: true, keyName: insider.email };
+}
+function buildShareResponse(seed, targetPath, expiry) {
+    let outsiderKey;
+    let shareUrl;
+    if (expiry) {
+        outsiderKey = computeOutsiderKeyWithExpiry(seed, targetPath, expiry);
+        shareUrl = `/browse${targetPath}?key=${outsiderKey}&exp=${expiry}`;
+    }
+    else {
+        outsiderKey = computePathKey(seed, targetPath);
+        shareUrl = `/browse${targetPath}?key=${outsiderKey}`;
+    }
+    return {
+        path: targetPath,
+        key: outsiderKey,
+        exp: expiry ?? null,
+        url: shareUrl,
+    };
+}

package/dist/src/routes/path/index.js

@@ -0,0 +1,17 @@
+/**
+ * Legacy /path redirect — sends all /path/* requests to /browse/*
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export const pathRoute = async (fastify) => {
+    // Redirect /path (root) to /browse
+    fastify.get('/path', async (_request, reply) => {
+        return reply.redirect('/browse');
+    });
+    // Redirect /path/* to /browse/*
+    fastify.get('/path/*', async (request, reply) => {
+        const reqPath = request.params['*'];
+        const url = new URL(request.url, 'http://localhost');
+        const query = url.search;
+        return reply.redirect(`/browse/${reqPath}${query}`);
+    });
+};

package/dist/src/routes/static.js

@@ -0,0 +1,30 @@
+/**
+ * Static asset routes — serves locally-bundled libraries from node_modules.
+ * Eliminates CDN dependencies for Lucide, Panzoom, and highlight.js.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// eslint-disable-next-line @typescript-eslint/require-await
+export const staticRoutes = async (fastify) => {
+    // robots.txt — block all crawlers
+    fastify.get('/robots.txt', async (_request, reply) => {
+        reply.type('text/plain').send('User-agent: *\nDisallow: /\n');
+    });
+    // Favicon
+    fastify.get('/favicon.svg', async (_request, reply) => {
+        const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y="0.9em" font-size="90">🎩</text></svg>`;
+        reply.type('image/svg+xml').send(svg);
+    });
+    // Lucide icons
+    fastify.get('/static/lucide.min.js', async (_request, reply) => {
+        const filePath = path.join(__dirname, '..', 'node_modules', 'lucide', 'dist', 'umd', 'lucide.min.js');
+        return reply.type('application/javascript').send(fs.readFileSync(filePath));
+    });
+    // Panzoom
+    fastify.get('/static/panzoom.min.js', async (_request, reply) => {
+        const filePath = path.join(__dirname, '..', 'node_modules', '@panzoom', 'panzoom', 'dist', 'panzoom.min.js');
+        return reply.type('application/javascript').send(fs.readFileSync(filePath));
+    });
+};

package/dist/src/server.js

@@ -0,0 +1,90 @@
+/**
+ * Jeeves Server - Main entry point
+ * Fastify server for webhooks, file serving, and markdown rendering
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import cookie from '@fastify/cookie';
+import fastifyStatic from '@fastify/static';
+import Fastify from 'fastify';
+import { getConfig, initConfig, isConfigInitialized } from './config/index.js';
+import { apiRoute } from './routes/api/index.js';
+import { authRoute } from './routes/auth.js';
+import { eventRoute } from './routes/event.js';
+import { healthRoute } from './routes/health.js';
+import { keysRoute } from './routes/keys.js';
+import { pathRoute } from './routes/path/index.js';
+import { staticRoutes } from './routes/static.js';
+import { initDiagramCache } from './services/diagramCache.js';
+import { startQueueProcessor } from './services/eventQueue.js';
+import { initExportCache } from './services/exportCache.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+async function start() {
+    try {
+        const config = isConfigInitialized() ? getConfig() : await initConfig();
+        const fastify = Fastify({
+            logger: true,
+        });
+        // Register plugins
+        await fastify.register(cookie);
+        // X-Robots-Tag on all responses — invisible to search engines
+        fastify.addHook('onSend', async (_request, reply) => {
+            void reply.header('X-Robots-Tag', 'noindex, nofollow');
+        });
+        // Register routes
+        await fastify.register(staticRoutes);
+        await fastify.register(healthRoute);
+        await fastify.register(authRoute);
+        await fastify.register(keysRoute);
+        await fastify.register(eventRoute);
+        await fastify.register(apiRoute);
+        await fastify.register(pathRoute);
+        // Serve React SPA (if built)
+        const clientDir = path.join(__dirname, '..', 'client');
+        if (fs.existsSync(clientDir)) {
+            await fastify.register(fastifyStatic, {
+                root: clientDir,
+                prefix: '/app/',
+            });
+            // SPA fallback for React routes
+            fastify.get('/', async (_request, reply) => {
+                return reply.sendFile('index.html', clientDir);
+            });
+            fastify.get('/browse', async (_request, reply) => {
+                return reply.sendFile('index.html', clientDir);
+            });
+            fastify.get('/browse/*', async (_request, reply) => {
+                return reply.sendFile('index.html', clientDir);
+            });
+            fastify.get('/runner', async (_request, reply) => {
+                return reply.sendFile('index.html', clientDir);
+            });
+            fastify.get('/runner/*', async (_request, reply) => {
+                return reply.sendFile('index.html', clientDir);
+            });
+        }
+        // Initialize caches
+        initDiagramCache(config.diagramCachePath);
+        initExportCache();
+        // Start queue processor
+        startQueueProcessor();
+        await fastify.listen({ port: config.port, host: '0.0.0.0' });
+        console.log(`Jeeves server listening on port ${String(config.port)}`);
+        console.log(`Endpoints:`);
+        console.log(`  GET  /browse/* - File browser SPA`);
+        console.log(`  GET  /api/raw/*    - Raw file serving`);
+        console.log(`  GET  /api/export/* - PDF/DOCX/ZIP export`);
+        console.log(`  POST /event    - Event Gateway (key auth)`);
+        console.log(`  GET  /key      - Compute path key (X-API-Key auth)`);
+        console.log(`  GET  /health   - Health check (no auth)`);
+    }
+    catch (err) {
+        console.error('Fatal startup error:', err);
+        process.exit(1);
+    }
+}
+start().catch((err) => {
+    console.error('Unhandled startup error:', err);
+    process.exit(1);
+});

package/dist/src/services/deepShareLinks.js

@@ -0,0 +1,163 @@
+/**
+ * Deep share link rewriting for outsider access with depth traversal.
+ *
+ * Rewrites outgoing links in rendered HTML with computed sub-keys,
+ * enabling outsiders to follow links up to N levels deep.
+ */
+import * as cheerio from 'cheerio';
+import LZString from 'lz-string';
+import { computeDeepShareKey } from '../util/crypto.js';
+/**
+ * Parse a compressed stack string into an array of paths.
+ */
+export function decodeStack(compressed) {
+    if (!compressed)
+        return [];
+    const json = LZString.decompressFromEncodedURIComponent(compressed);
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Encode a path stack array into a compressed string.
+ */
+export function encodeStack(stack) {
+    return LZString.compressToEncodedURIComponent(JSON.stringify(stack));
+}
+/**
+ * Compute the remaining depth for a given stack.
+ */
+export function remainingDepth(maxDepth, stack) {
+    return maxDepth - (stack.length - 1);
+}
+/**
+ * Compute a sub-link URL for an outgoing link target.
+ * Returns null if the link should be stripped (depth exhausted or type not allowed).
+ */
+export function computeSubLink(seed, targetUrlPath, currentStack, maxDepth, dirs, exp, isDirectory) {
+    // Check if directories are allowed
+    if (isDirectory && !dirs)
+        return null;
+    // Compute new stack
+    const existingIndex = currentStack.indexOf(targetUrlPath);
+    let newStack;
+    if (existingIndex >= 0) {
+        // Revisiting — truncate stack to that point
+        newStack = currentStack.slice(0, existingIndex + 1);
+    }
+    else {
+        // New page — append
+        newStack = [...currentStack, targetUrlPath];
+    }
+    // Check remaining depth
+    const remaining = remainingDepth(maxDepth, newStack);
+    if (remaining < 0)
+        return null;
+    const compressedStack = encodeStack(newStack);
+    // Compute key for the target
+    const params = {
+        depth: maxDepth,
+        dirs,
+        stack: compressedStack,
+        exp,
+    };
+    const key = computeDeepShareKey(seed, targetUrlPath, params);
+    // Build URL
+    let url = `/browse${targetUrlPath}?key=${key}&d=${String(maxDepth)}&dirs=${dirs ? '1' : '0'}&s=${compressedStack}`;
+    if (exp)
+        url += `&exp=${exp}`;
+    return url;
+}
+/**
+ * Rewrite outgoing links in rendered HTML for deep share access.
+ *
+ * For outsiders with depth \> 0:
+ * - Internal links get rewritten with sub-keys
+ * - Links beyond depth get stripped (text preserved, link removed)
+ * - External links (http/https) are left unchanged
+ * - Anchor links (#) are left unchanged
+ */
+export function rewriteLinksForDeepShare(html, seed, currentPath, maxDepth, dirs, stackCompressed, exp) {
+    const currentStack = decodeStack(stackCompressed);
+    // Ensure current path is in the stack
+    if (currentStack.length === 0 ||
+        currentStack[currentStack.length - 1] !== currentPath) {
+        currentStack.push(currentPath);
+    }
+    const remaining = remainingDepth(maxDepth, currentStack);
+    const $ = cheerio.load(html, null, false);
+    // Rewrite <a> tags
+    $('a').each((_i, el) => {
+        const $el = $(el);
+        const href = $el.attr('href');
+        if (!href)
+            return;
+        // Skip external links, anchors, and data URLs
+        if (href.startsWith('http://') ||
+            href.startsWith('https://') ||
+            href.startsWith('#') ||
+            href.startsWith('//') ||
+            href.startsWith('data:') ||
+            href.startsWith('mailto:')) {
+            return;
+        }
+        // If no remaining depth, strip the link (keep text)
+        if (remaining <= 0) {
+            $el.replaceWith($el.html() ?? '');
+            return;
+        }
+        // Raw file links — leave as-is (these are for images/downloads)
+        if (href.startsWith('/api/raw/'))
+            return;
+        // Determine target path
+        let targetPath;
+        if (href.startsWith('/browse/')) {
+            targetPath = '/' + href.replace('/browse/', '').split('?')[0];
+        }
+        else if (href.startsWith('/')) {
+            targetPath = href.split('?')[0];
+        }
+        else {
+            // Relative link — resolve against current path directory
+            const dir = currentPath.substring(0, currentPath.lastIndexOf('/'));
+            targetPath = dir
+                ? `${dir}/${href.split('?')[0]}`
+                : `/${href.split('?')[0]}`;
+        }
+        // Normalize
+        targetPath = targetPath.replace(/\/+/g, '/');
+        const isDirectory = targetPath.endsWith('/');
+        const subLink = computeSubLink(seed, targetPath, currentStack, maxDepth, dirs, exp, isDirectory);
+        if (subLink === null) {
+            // Strip link, keep text
+            $el.replaceWith($el.html() ?? '');
+        }
+        else {
+            $el.attr('href', subLink);
+        }
+    });
+    // Rewrite <img> src for images that use /api/raw/ — add key auth
+    $('img').each((_i, el) => {
+        const $el = $(el);
+        const src = $el.attr('src');
+        if (!src || !src.startsWith('/api/raw/'))
+            return;
+        const params = {
+            depth: maxDepth,
+            dirs,
+            stack: stackCompressed,
+            exp,
+        };
+        const rawPath = '/' + src.replace('/api/raw/', '').split('?')[0];
+        const key = computeDeepShareKey(seed, rawPath, params);
+        const authSrc = `${src}${src.includes('?') ? '&' : '?'}key=${key}&d=${String(maxDepth)}&dirs=${dirs ? '1' : '0'}&s=${stackCompressed}${exp ? `&exp=${exp}` : ''}`;
+        $el.attr('src', authSrc);
+    });
+    return $.html();
+}