@karmaniverous/jeeves-server 3.0.0-0

package/src/routes/event.test.ts

@@ -0,0 +1,248 @@
+/**
+ * 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, { _: _ as never });
+      const result = (await mapper.transform(body)) as Record<string, unknown>;
+
+      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, { _: _ as never });
+      const result = (await mapper.transform(body)) as Record<string, unknown>;
+
+      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, { _: _ as never });
+      const result = (await mapper.transform(body)) as Record<string, unknown>;
+
+      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: { timeoutMs?: number } = {}; // 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?: number } = { 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/src/routes/event.ts

@@ -0,0 +1,109 @@
+/**
+ * Event Gateway webhook endpoint
+ */
+
+import { JsonMap } from '@karmaniverous/jsonmap';
+import Ajv from 'ajv';
+import type { FastifyPluginAsync } from 'fastify';
+import * as _ from 'radash';
+
+import { verifyKey } from '../auth/keys.js';
+import { getConfig } from '../config/index.js';
+import { logEvent } from '../services/eventLog.js';
+import { enqueue } from '../services/eventQueue.js';
+
+const ajv = new Ajv();
+
+interface EventRequest {
+  Body: Record<string, unknown>;
+  Querystring: { key?: string };
+}
+
+/**
+ * Match request body against configured event schemas
+ */
+function matchEvent(
+  body: Record<string, unknown>,
+): { name: string; cmd: string; map?: object; timeoutMs: number } | null {
+  const { events, eventTimeoutMs } = getConfig();
+
+  for (const [name, eventConfig] of Object.entries(events)) {
+    const validate = ajv.compile(eventConfig.schema);
+
+    if (validate(body)) {
+      return {
+        name,
+        cmd: eventConfig.cmd,
+        map: eventConfig.map,
+        timeoutMs: eventConfig.timeoutMs ?? eventTimeoutMs,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Transform body using JsonMap (if map is defined)
+ */
+async function transformBody(
+  body: Record<string, unknown>,
+  map?: object,
+): Promise<Record<string, unknown>> {
+  if (!map) return body;
+
+  // JsonMap with radash available as $.lib._
+  const mapper = new JsonMap(map, { _: _ as never });
+  const result = await mapper.transform(body);
+  return result as Record<string, unknown>;
+}
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const eventRoute: FastifyPluginAsync = async (fastify) => {
+  // Auth middleware
+  fastify.addHook('preHandler', async (request, reply) => {
+    if (!request.url.startsWith('/event')) return;
+
+    const provided = (request.query as { key?: string }).key;
+    const config = getConfig();
+
+    const result = verifyKey(
+      config.resolvedKeys,
+      '/event',
+      provided,
+      undefined,
+    );
+
+    if (!result.valid) {
+      reply.code(401).send({ error: 'Unauthorized' });
+    }
+  });
+
+  // Event endpoint
+  fastify.post<EventRequest>('/event', async (request) => {
+    const body = request.body;
+
+    // Match against configured events
+    const match = matchEvent(body);
+
+    if (match) {
+      // Transform body if map is defined
+      const transformedBody = await transformBody(body, match.map);
+
+      // Enqueue for processing
+      enqueue(match.name, match.cmd, transformedBody, match.timeoutMs);
+
+      return { matched: match.name };
+    } else {
+      // Log unmatched event
+      logEvent({
+        event: null,
+        matched: false,
+        bodyPreview: JSON.stringify(body),
+      });
+
+      // Always return 200 for unmatched events (prevents webhook retry/disable)
+      return { matched: null };
+    }
+  });
+};

package/src/routes/health.ts

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

package/src/routes/keys.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 type { FastifyPluginAsync } from 'fastify';
+
+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: FastifyPluginAsync = async (fastify) => {
+  // GET /key - Compute path-specific outsider key (requires raw API key seed in header)
+  fastify.get<{ Querystring: { path?: string } }>(
+    '/key',
+    async (request, reply) => {
+      const provided = request.headers['x-api-key'] as string;
+      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'] as string;
+    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<{ Querystring: { key?: string } }>(
+    '/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<{ Querystring: { key?: string; path?: string; exp?: string } }>(
+    '/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: string,
+  config: ReturnType<typeof getConfig>,
+) {
+  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: string, targetPath: string, expiry?: string) {
+  let outsiderKey: string;
+  let shareUrl: string;
+
+  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/src/routes/path/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Legacy /path redirect — sends all /path/* requests to /browse/*
+ */
+
+import type { FastifyPluginAsync } from 'fastify';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const pathRoute: FastifyPluginAsync = async (fastify) => {
+  // Redirect /path (root) to /browse
+  fastify.get('/path', async (_request, reply) => {
+    return reply.redirect('/browse');
+  });
+
+  // Redirect /path/* to /browse/*
+  fastify.get<{ Params: { '*': string } }>(
+    '/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/src/routes/static.ts

@@ -0,0 +1,54 @@
+/**
+ * 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';
+
+import type { FastifyPluginAsync } from 'fastify';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const staticRoutes: FastifyPluginAsync = 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));
+  });
+};