@karmaniverous/jeeves-server 3.0.0-0

package/src/routes/api/middleware.ts

@@ -0,0 +1,156 @@
+/**
+ * API authentication middleware (preHandler hook).
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import {
+  resolveInsiderKeyAuth,
+  resolveKeyAuth,
+  resolveSessionAuth,
+} from '../../auth/resolve.js';
+import { getConfig } from '../../config/index.js';
+import { decodeStack } from '../../services/deepShareLinks.js';
+
+/**
+ * Add the API auth preHandler hook directly to a Fastify instance.
+ * Must be called on the parent context (not via register()) so the hook
+ * applies to all sibling and child routes.
+ */
+export function addAuthMiddleware(fastify: FastifyInstance): void {
+  fastify.addHook('preHandler', async (request, reply) => {
+    if (!request.url.startsWith('/api')) return;
+    if (request.url.startsWith('/api/readme-link')) return;
+    if (request.url.startsWith('/api/content-link/')) return;
+    if (request.url.startsWith('/api/auth/status')) return;
+    if (request.url.startsWith('/api/diagram/')) return;
+
+    const config = getConfig();
+
+    // Utility endpoints handle their own scope checking
+    if (request.url.startsWith('/api/util/')) {
+      const query = request.query as { key?: string; exp?: string };
+
+      // Try key-based auth
+      if (query.key) {
+        const keyResult = resolveKeyAuth(config, '/', query.key, query.exp);
+        if (keyResult.valid && keyResult.mode === 'insider') {
+          request.accessMode = 'insider';
+          request.authSeed = keyResult.seed;
+          request.insiderScopes = keyResult.scopes ?? null;
+          return;
+        }
+
+        // Try as a direct insider key
+        const insiderResult = resolveInsiderKeyAuth(config, query.key);
+        if (insiderResult.valid) {
+          request.accessMode = 'insider';
+          request.authSeed = insiderResult.seed;
+          request.insiderScopes = insiderResult.scopes ?? null;
+          request.insiderEmail = insiderResult.email;
+          return;
+        }
+      }
+
+      // Try session cookie
+      const sessionResult = resolveSessionAuth(config, request);
+      if (sessionResult.valid) {
+        request.accessMode = 'insider';
+        request.authSeed = sessionResult.seed;
+        request.insiderScopes = sessionResult.scopes ?? null;
+        request.insiderEmail = sessionResult.email;
+        return;
+      }
+
+      reply
+        .code(401)
+        .send({ error: 'Insider auth required for utility endpoints' });
+      return;
+    }
+
+    // General API auth
+    const query = request.query as {
+      key?: string;
+      exp?: string;
+      d?: string;
+      dirs?: string;
+      s?: string;
+    };
+    const deepParams =
+      query.d !== undefined && query.s !== undefined
+        ? { d: query.d, dirs: query.dirs ?? '0', s: query.s }
+        : undefined;
+
+    const urlPath = request.url
+      .split('?')[0]
+      .replace('/api/path', '')
+      .replace('/api/drives', '/')
+      .replace('/api/file', '')
+      .replace('/api/raw', '')
+      .replace('/api/export-cache', '')
+      .replace('/api/export', '');
+
+    // Try key-based auth
+    let authResult = resolveKeyAuth(
+      config,
+      urlPath || '/',
+      query.key,
+      query.exp,
+      deepParams,
+    );
+
+    // Retry with dirs fallback (directory shares)
+    if (
+      !authResult.valid &&
+      deepParams &&
+      deepParams.dirs === '1' &&
+      query.key
+    ) {
+      const stack = decodeStack(deepParams.s);
+      const lastStackEntry = stack[stack.length - 1];
+      if (lastStackEntry && lastStackEntry !== urlPath) {
+        authResult = resolveKeyAuth(
+          config,
+          lastStackEntry,
+          query.key,
+          query.exp,
+          deepParams,
+        );
+      }
+    }
+
+    // Try session cookie (always check — insiders visiting outsider links
+    // should be upgraded to insider access)
+    const sessionResult = resolveSessionAuth(config, request);
+
+    if (authResult.valid && sessionResult.valid) {
+      // Both key and session are valid — prefer insider session
+      request.accessMode = 'insider';
+      request.authSeed = sessionResult.seed;
+      request.insiderEmail = sessionResult.email;
+      request.insiderScopes = sessionResult.scopes ?? null;
+      request.keyAge = sessionResult.keyAge;
+      return;
+    }
+
+    if (authResult.valid) {
+      request.accessMode = authResult.mode;
+      request.authSeed = authResult.seed;
+      request.deepShareParams = authResult.deepShareParams;
+      request.authMatchedPath = authResult.matchedPath;
+      return;
+    }
+
+    if (sessionResult.valid) {
+      request.accessMode = 'insider';
+      request.authSeed = sessionResult.seed;
+      request.insiderEmail = sessionResult.email;
+      request.insiderScopes = sessionResult.scopes ?? null;
+      request.keyAge = sessionResult.keyAge;
+      return;
+    }
+
+    reply.code(401).send({ error: 'Unauthorized' });
+    return;
+  });
+}

package/src/routes/api/raw.ts

@@ -0,0 +1,54 @@
+/**
+ * Raw file serving API route.
+ *
+ * Handles: GET /api/raw/*
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import { getConfig } from '../../config/index.js';
+import { getContentType, isInlineType } from '../../util/fileDetection.js';
+import { getRoots, urlPathToFs } from '../../util/platform.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const rawRoutes: FastifyPluginAsync = async (fastify) => {
+  const roots = getRoots(getConfig().roots);
+
+  fastify.get<{ Params: { '*': string } }>(
+    '/api/raw/*',
+    async (request, reply) => {
+      const reqPath = request.params['*'];
+      if (!reqPath) return reply.code(400).send({ error: 'Path required' });
+
+      const rawFsPath = urlPathToFs(reqPath, roots);
+      if (!rawFsPath) return reply.code(404).send({ error: 'Invalid path' });
+      const resolved = path.resolve(rawFsPath);
+
+      if (!fs.existsSync(resolved))
+        return reply.code(404).send({ error: 'Not found', path: resolved });
+
+      const stats = fs.statSync(resolved);
+      if (stats.isDirectory()) {
+        return reply.code(400).send({
+          error: 'Cannot serve directory as raw — use /api/export for ZIP',
+        });
+      }
+
+      const ext = path.extname(resolved).toLowerCase();
+      const contentType = getContentType(ext);
+      reply.header('Content-Type', contentType);
+
+      if (!isInlineType(contentType)) {
+        reply.header(
+          'Content-Disposition',
+          `attachment; filename="${path.basename(resolved)}"`,
+        );
+      }
+
+      return reply.send(fs.readFileSync(resolved));
+    },
+  );
+};

package/src/routes/api/runner.ts

@@ -0,0 +1,107 @@
+/**
+ * Runner proxy routes — proxies requests to the local jeeves-runner API.
+ *
+ * All routes require insider auth. The runner only listens on localhost,
+ * so jeeves-server acts as an authenticated gateway.
+ */
+
+import type { FastifyPluginAsync, FastifyReply } from 'fastify';
+
+import { getConfig } from '../../config/index.js';
+
+const DEFAULT_RUNNER_URL = 'http://127.0.0.1:3100';
+
+function getRunnerUrl(): string {
+  return getConfig().runnerUrl ?? DEFAULT_RUNNER_URL;
+}
+
+/** Proxy a request to the runner and send the response via reply. */
+async function proxyToRunner(
+  reply: FastifyReply,
+  path: string,
+  method: 'GET' | 'POST' = 'GET',
+): Promise<void> {
+  try {
+    const res = await fetch(`${getRunnerUrl()}${path}`, { method });
+    const text = await res.text();
+    void reply
+      .code(res.status)
+      .header(
+        'content-type',
+        res.headers.get('content-type') ?? 'application/json',
+      )
+      .send(text);
+  } catch {
+    void reply.code(502).send(JSON.stringify({ error: 'Runner unreachable' }));
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const runnerRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.addHook('preHandler', async (request, reply) => {
+    if (request.accessMode !== 'insider') {
+      return reply.code(403).send({ error: 'Insider access required' });
+    }
+  });
+
+  fastify.get('/api/runner/health', async (_req, reply) => {
+    await proxyToRunner(reply, '/health');
+  });
+
+  fastify.get('/api/runner/jobs', async (_req, reply) => {
+    await proxyToRunner(reply, '/jobs');
+  });
+
+  fastify.get<{ Params: { id: string } }>(
+    '/api/runner/jobs/:id',
+    async (req, reply) => {
+      await proxyToRunner(reply, `/jobs/${encodeURIComponent(req.params.id)}`);
+    },
+  );
+
+  fastify.get<{ Params: { id: string }; Querystring: { limit?: string } }>(
+    '/api/runner/jobs/:id/runs',
+    async (req, reply) => {
+      const limit = req.query.limit ?? '20';
+      const id = encodeURIComponent(req.params.id);
+      await proxyToRunner(reply, `/jobs/${id}/runs?limit=${limit}`);
+    },
+  );
+
+  fastify.post<{ Params: { id: string } }>(
+    '/api/runner/jobs/:id/run',
+    async (req, reply) => {
+      await proxyToRunner(
+        reply,
+        `/jobs/${encodeURIComponent(req.params.id)}/run`,
+        'POST',
+      );
+    },
+  );
+
+  fastify.post<{ Params: { id: string } }>(
+    '/api/runner/jobs/:id/enable',
+    async (req, reply) => {
+      await proxyToRunner(
+        reply,
+        `/jobs/${encodeURIComponent(req.params.id)}/enable`,
+        'POST',
+      );
+    },
+  );
+
+  fastify.post<{ Params: { id: string } }>(
+    '/api/runner/jobs/:id/disable',
+    async (req, reply) => {
+      await proxyToRunner(
+        reply,
+        `/jobs/${encodeURIComponent(req.params.id)}/disable`,
+        'POST',
+      );
+    },
+  );
+
+  fastify.get('/api/runner/stats', async (_req, reply) => {
+    await proxyToRunner(reply, '/stats');
+  });
+};

package/src/routes/api/search.ts

@@ -0,0 +1,321 @@
+/**
+ * Search API route — proxies to jeeves-watcher for semantic search.
+ *
+ * Handles: POST /api/search
+ * Insider-only. Results filtered by insider's scope.
+ */
+
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { FastifyPluginAsync } from 'fastify';
+import picomatch from 'picomatch';
+
+import { getConfig } from '../../config/index.js';
+import type { NormalizedScopes } from '../../config/types.js';
+
+/** Check if a path passes the insider's scope rules. */
+function pathAllowedByScope(
+  urlPath: string,
+  scopes: NormalizedScopes | null,
+): boolean {
+  if (!scopes) return true; // null = unrestricted
+  const normalized = urlPath.toLowerCase().replace(/\/+$/, '');
+  const allowMatch = picomatch(
+    scopes.allow.map((p) => p.toLowerCase().replace(/\/+$/, '')),
+  );
+  if (!allowMatch(normalized)) return false;
+  if (scopes.deny.length > 0) {
+    const denyMatch = picomatch(
+      scopes.deny.map((p) => p.toLowerCase().replace(/\/+$/, '')),
+    );
+    if (denyMatch(normalized)) return false;
+  }
+  return true;
+}
+
+interface WatcherResult {
+  id: string;
+  score: number;
+  payload: {
+    file_path?: string;
+    chunk_text?: string;
+    chunk_index?: number;
+    total_chunks?: number;
+    domains?: string[];
+    title?: string;
+    author?: string;
+    participants?: string;
+    content_hash?: string;
+    [key: string]: unknown;
+  };
+}
+
+interface GroupedResult {
+  filePath: string;
+  browsePath: string;
+  fileName: string;
+  bestScore: number;
+  mtime?: string;
+  domains?: string[];
+  title?: string;
+  author?: string;
+  participants?: string;
+  chunks: Array<{
+    text: string;
+    index: number;
+    score: number;
+  }>;
+}
+
+/**
+ * Resolve a browse path back to a filesystem path using roots config.
+ * Inverse of fsPathToBrowsePath.
+ */
+function browsePathToFsPath(
+  browsePath: string,
+  roots: Record<string, string>,
+): string | null {
+  const parts = browsePath.split('/');
+  const label = parts[0];
+  const rest = parts.slice(1).join('/');
+
+  // Check if label matches a root
+  if (roots[label]) {
+    return path.join(roots[label], rest);
+  }
+
+  // Windows drive letter: j/foo/bar → J:\foo\bar
+  if (/^[a-zA-Z]$/.test(label)) {
+    return `${label.toUpperCase()}:\\${rest.replace(/\//g, '\\')}`;
+  }
+
+  return null;
+}
+
+/**
+ * Convert an absolute filesystem path to a browse URL path.
+ * Maps drive letters and root mounts back to the URL scheme.
+ */
+function fsPathToBrowsePath(
+  fsPath: string,
+  roots: Record<string, string>,
+): string | null {
+  const normalized = fsPath.replace(/\\/g, '/');
+
+  // Windows drive letter: j:/foo/bar → j/foo/bar
+  const driveMatch = normalized.match(/^([a-zA-Z]):\/(.*)$/);
+  if (driveMatch) {
+    return `${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
+  }
+
+  // Linux roots: find matching root prefix
+  for (const [label, rootPath] of Object.entries(roots)) {
+    const normalizedRoot = rootPath.replace(/\\/g, '/').replace(/\/$/, '');
+    if (normalized.startsWith(normalizedRoot + '/')) {
+      const relative = normalized.slice(normalizedRoot.length + 1);
+      return `${label}/${relative}`;
+    }
+    if (normalized === normalizedRoot) {
+      return label;
+    }
+  }
+
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const searchRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.post<{
+    Body: {
+      query: string;
+      limit?: number;
+      filter?: Record<string, unknown>;
+    };
+  }>('/api/search', async (request, reply) => {
+    // Insider-only
+    if (request.accessMode !== 'insider') {
+      return reply.code(403).send({ error: 'Insider access required' });
+    }
+
+    const config = getConfig();
+    if (!config.watcherUrl) {
+      return reply.code(501).send({ error: 'Search not configured' });
+    }
+
+    const { query, limit = 20, filter } = request.body;
+    if (!query || typeof query !== 'string') {
+      return reply.code(400).send({ error: 'query is required' });
+    }
+
+    const insiderScopes = request.insiderScopes;
+    const roots = config.roots ?? {};
+
+    // Over-fetch to account for scope filtering
+    const fetchLimit = Math.min(limit * 5, 200);
+
+    try {
+      const watcherRes = await fetch(`${config.watcherUrl}/search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ query, limit: fetchLimit, filter }),
+      });
+
+      if (!watcherRes.ok) {
+        const msg = await watcherRes.text().catch(() => '');
+        return await reply
+          .code(502)
+          .send({ error: `Watcher search failed: ${msg}` });
+      }
+
+      const rawResults = (await watcherRes.json()) as WatcherResult[];
+
+      // Filter by insider scope and map paths
+      const permitted: Array<WatcherResult & { browsePath: string }> = [];
+      for (const r of rawResults) {
+        const fp = r.payload.file_path;
+        if (!fp) continue;
+
+        const browsePath = fsPathToBrowsePath(fp, roots);
+        if (!browsePath) continue;
+
+        // Check insider scope
+        const urlPath = `/${browsePath}`;
+        if (!pathAllowedByScope(urlPath, insiderScopes ?? null)) continue;
+
+        permitted.push({ ...r, browsePath });
+      }
+
+      // Group by file path, take top `limit` files
+      const fileMap = new Map<string, GroupedResult>();
+      for (const r of permitted) {
+        const key = r.browsePath;
+        let group = fileMap.get(key);
+        if (!group) {
+          const parts = key.split('/');
+          group = {
+            filePath: r.payload.file_path ?? key,
+            browsePath: key,
+            fileName: parts[parts.length - 1],
+            bestScore: r.score,
+            domains: Array.isArray(r.payload.domains)
+              ? r.payload.domains
+              : r.payload.domain
+                ? [r.payload.domain as string]
+                : [],
+            title: r.payload.title,
+            author: r.payload.author,
+            participants: r.payload.participants,
+            chunks: [],
+          };
+          fileMap.set(key, group);
+        }
+        if (r.score > group.bestScore) group.bestScore = r.score;
+        group.chunks.push({
+          text: r.payload.chunk_text ?? '',
+          index: r.payload.chunk_index ?? 0,
+          score: r.score,
+        });
+      }
+
+      // Sort by best score, limit
+      const grouped = [...fileMap.values()]
+        .sort((a, b) => b.bestScore - a.bestScore)
+        .slice(0, limit);
+
+      // Sort chunks within each group by index, and fetch mtime
+      await Promise.all(
+        grouped.map(async (g) => {
+          g.chunks.sort((a, b) => a.index - b.index);
+          const fsPath = browsePathToFsPath(g.browsePath, roots);
+          if (fsPath) {
+            try {
+              const s = await stat(fsPath);
+              g.mtime = s.mtime.toISOString();
+            } catch {
+              /* file may not be accessible */
+            }
+          }
+        }),
+      );
+
+      // Extract distinct metadata values for filter chips
+      const metadata = {
+        domains: [
+          ...new Set(grouped.flatMap((g) => g.domains || []).filter(Boolean)),
+        ],
+        authors: [...new Set(grouped.map((g) => g.author).filter(Boolean))],
+        participants: [
+          ...new Set(
+            grouped.flatMap((g) => {
+              try {
+                const p = JSON.parse(g.participants ?? '[]') as string[];
+                return Array.isArray(p) ? p : [];
+              } catch {
+                return g.participants ? [g.participants] : [];
+              }
+            }),
+          ),
+        ].filter(Boolean),
+      };
+
+      return await reply.send({ results: grouped, metadata });
+    } catch (err) {
+      return await reply
+        .code(502)
+        .send({ error: `Watcher unreachable: ${String(err)}` });
+    }
+  });
+
+  // Cached facets manifest
+  let facetsCache: { data: unknown; fetchedAt: number } | null = null;
+  let facetsFetchPromise: Promise<unknown> | null = null;
+  const FACETS_CACHE_TTL_MS = 60_000; // 1 minute
+
+  fastify.get('/api/search/facets', async (request, reply) => {
+    if (request.accessMode !== 'insider') {
+      return reply.code(403).send({ error: 'Insider access required' });
+    }
+
+    const config = getConfig();
+    if (!config.watcherUrl) {
+      return reply.code(501).send({ error: 'Search not configured' });
+    }
+
+    // Return cached if fresh
+    if (
+      facetsCache &&
+      Date.now() - facetsCache.fetchedAt < FACETS_CACHE_TTL_MS
+    ) {
+      return reply.send(facetsCache.data);
+    }
+
+    try {
+      // Guard against cache stampede: reuse in-flight fetch
+      if (!facetsFetchPromise) {
+        const watcherUrl = config.watcherUrl;
+        facetsFetchPromise = (async () => {
+          const watcherRes = await fetch(`${watcherUrl}/search/facets`, {
+            signal: AbortSignal.timeout(5000),
+          });
+          if (!watcherRes.ok) {
+            throw new Error(`HTTP ${String(watcherRes.status)}`);
+          }
+          const data: unknown = await watcherRes.json();
+          facetsCache = { data, fetchedAt: Date.now() };
+          return data;
+        })().finally(() => {
+          facetsFetchPromise = null;
+        });
+      }
+
+      const data = await facetsFetchPromise;
+      return await reply.send(data);
+    } catch (err) {
+      return await reply.code(502).send({
+        error: 'Failed to reach watcher',
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+};