@karmaniverous/jeeves-server 3.0.0-0

package/src/routes/api/sharing.ts

@@ -0,0 +1,259 @@
+/**
+ * Sharing API routes.
+ *
+ * Handles: /api/share, /api/util/share-for, /api/readme-link, /api/rotate-key
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import { _pathMatchesScopes } from '../../auth/keys.js';
+import { findInsider } from '../../auth/resolve.js';
+import { getConfig, resetConfig } from '../../config/index.js';
+import { encodeStack } from '../../services/deepShareLinks.js';
+import {
+  computeDeepShareKey,
+  computeOutsiderKeyWithExpiry,
+  computePathKey,
+  type DeepShareParams,
+} from '../../util/crypto.js';
+import { fsPathToUrl, getRoots } from '../../util/platform.js';
+import { setInsiderKey } from '../../util/state.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const sharingRoutes: FastifyPluginAsync = async (fastify) => {
+  const roots = getRoots(getConfig().roots);
+
+  // GET /api/readme-link
+  fastify.get('/api/readme-link', async (_request, reply) => {
+    const config = getConfig();
+    const internalKey = config.resolvedKeys.find((k) => k.name === '_internal');
+    if (!internalKey?.seed)
+      return reply.code(503).send({ error: 'No _internal key configured' });
+
+    const seed = internalKey.seed;
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const serverRoot = path.resolve(__dirname, '..', '..', '..');
+    const readmePath = path.join(serverRoot, 'README.md');
+    if (!fs.existsSync(readmePath))
+      return reply.code(404).send({ error: 'README.md not found' });
+
+    const urlPath = fsPathToUrl(readmePath, roots);
+    const stack = encodeStack([urlPath]);
+    const deepParams = { depth: 2, dirs: false, stack, exp: undefined };
+    const key = computeDeepShareKey(seed, urlPath, deepParams);
+    const shareUrl = `/browse${urlPath}?key=${key}&d=2&dirs=0&s=${stack}`;
+
+    return reply.send({ url: shareUrl });
+  });
+
+  // GET /api/content-link/:file — share link for content/*.md (terms, privacy)
+  fastify.get('/api/content-link/:file', async (request, reply) => {
+    const config = getConfig();
+    const internalKey = config.resolvedKeys.find((k) => k.name === '_internal');
+    if (!internalKey?.seed)
+      return reply.code(503).send({ error: 'No _internal key configured' });
+
+    const { file } = request.params as { file: string };
+    if (!/^[\w-]+$/.test(file))
+      return reply.code(400).send({ error: 'Invalid file name' });
+
+    const seed = internalKey.seed;
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const serverRoot = path.resolve(__dirname, '..', '..', '..');
+    const contentPath = path.join(serverRoot, 'content', `${file}.md`);
+    if (!fs.existsSync(contentPath))
+      return reply.code(404).send({ error: `${file}.md not found` });
+
+    const urlPath = fsPathToUrl(contentPath, roots);
+    const stack = encodeStack([urlPath]);
+    const deepParams = { depth: 0, dirs: false, stack, exp: undefined };
+    const key = computeDeepShareKey(seed, urlPath, deepParams);
+    const shareUrl = `/browse${urlPath}?key=${key}&d=0&dirs=0&s=${stack}`;
+
+    return reply.send({ url: shareUrl });
+  });
+
+  // POST /api/share
+  fastify.post<{
+    Body: { path: string; expiry?: string; depth?: number; dirs?: boolean };
+  }>('/api/share', async (request, reply) => {
+    const seed = request.authSeed;
+    if (!seed) return reply.code(401).send({ error: 'Insider auth required' });
+
+    const { path: targetPath, expiry, depth, dirs } = request.body;
+    if (!targetPath) return reply.code(400).send({ error: 'path is required' });
+
+    let outsiderKey: string;
+    let shareUrl: string;
+
+    if ((depth && depth > 0) || dirs) {
+      const stack = encodeStack([targetPath]);
+      const deepParams: DeepShareParams = {
+        depth: depth ?? 0,
+        dirs: dirs ?? false,
+        stack,
+        exp: expiry,
+      };
+      outsiderKey = computeDeepShareKey(seed, targetPath, deepParams);
+      shareUrl = `/browse${targetPath}?key=${outsiderKey}&d=${String(depth ?? 0)}&dirs=${dirs ? '1' : '0'}&s=${stack}`;
+      if (expiry) shareUrl += `&exp=${expiry}`;
+    } else 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 reply.send({
+      url: shareUrl,
+      path: targetPath,
+      exp: expiry ?? null,
+      depth: depth ?? 0,
+      dirs: dirs ?? false,
+    });
+  });
+
+  // POST /api/rotate-key
+  fastify.post('/api/rotate-key', async (request, reply) => {
+    const insiderEmail = request.insiderEmail;
+    if (!insiderEmail)
+      return reply.code(403).send({ error: 'Insider auth required' });
+
+    const config = getConfig();
+    const insider = findInsider(config.resolvedInsiders, insiderEmail);
+    if (!insider) return reply.code(403).send({ error: 'Not an insider' });
+
+    const newSeed = crypto.randomBytes(32).toString('hex');
+    const now = new Date().toISOString();
+    setInsiderKey(insider.email, newSeed, now);
+    resetConfig();
+
+    return reply.send({ ok: true, keyCreatedAt: now });
+  });
+
+  // POST /api/util/share-for
+  fastify.post<{
+    Body: {
+      path: string;
+      insiders: string[];
+      depth?: number;
+      dirs?: boolean;
+      enforceOutsiderPolicy?: boolean;
+    };
+  }>('/api/util/share-for', async (request, reply) => {
+    const config = getConfig();
+    const sharerSeed = request.authSeed;
+    const sharerScopes = request.insiderScopes ?? null;
+    if (!sharerSeed)
+      return reply.code(401).send({ error: 'Authentication required' });
+
+    const {
+      path: targetPath,
+      insiders: audienceIds,
+      depth,
+      dirs,
+      enforceOutsiderPolicy,
+    } = request.body;
+    if (!targetPath) return reply.code(400).send({ error: 'path is required' });
+    if (!Array.isArray(audienceIds))
+      return reply.code(400).send({ error: 'insiders array is required' });
+
+    if (sharerScopes && !_pathMatchesScopes(targetPath, sharerScopes)) {
+      return reply.send({
+        url: null,
+        type: 'blocked',
+        reason: 'Sharer does not have access to this path',
+        blocked: [],
+      });
+    }
+
+    const blockedInsiders: string[] = [];
+    const unknownIds: string[] = [];
+
+    for (const id of audienceIds) {
+      const insider = findInsider(config.resolvedInsiders, id);
+      if (!insider || !insider.seed) {
+        unknownIds.push(id);
+        continue;
+      }
+      if (insider.scopes && !_pathMatchesScopes(targetPath, insider.scopes)) {
+        blockedInsiders.push(id);
+      }
+    }
+
+    if (blockedInsiders.length > 0) {
+      return reply.send({
+        url: null,
+        type: 'blocked',
+        reason: 'Insider(s) do not have access to this path',
+        blocked: blockedInsiders,
+      });
+    }
+
+    const hasOutsiders = unknownIds.length > 0;
+
+    if (!hasOutsiders) {
+      const proto = String(request.headers['x-forwarded-proto'] || 'https');
+      const host = String(
+        request.headers['x-forwarded-host'] || request.headers.host,
+      );
+      return reply.send({
+        url: `${proto}://${host}/browse${targetPath}`,
+        type: 'insider',
+      });
+    }
+
+    const outsiderPolicy = config.outsiderPolicy;
+    const policyEnforced = enforceOutsiderPolicy !== false;
+
+    if (outsiderPolicy && policyEnforced) {
+      if (!_pathMatchesScopes(targetPath, outsiderPolicy)) {
+        return reply.send({
+          url: null,
+          type: 'policy-denied',
+          reason: 'Outsider policy does not allow sharing this path',
+        });
+      }
+    }
+
+    const shareDepth = depth ?? 0;
+    const shareDirs = dirs ?? false;
+    const stack = encodeStack([targetPath]);
+    const deepParams: DeepShareParams = {
+      depth: shareDepth,
+      dirs: shareDirs,
+      stack,
+    };
+    const outsiderKey = computeDeepShareKey(sharerSeed, targetPath, deepParams);
+    const proto = String(request.headers['x-forwarded-proto'] || 'https');
+    const host = String(
+      request.headers['x-forwarded-host'] || request.headers.host,
+    );
+
+    let shareUrl = `${proto}://${host}/browse${targetPath}?key=${outsiderKey}`;
+    if (shareDepth > 0) shareUrl += `&d=${String(shareDepth)}`;
+    shareUrl += `&dirs=${shareDirs ? '1' : '0'}`;
+    if (stack) shareUrl += `&s=${stack}`;
+
+    const response: Record<string, unknown> = {
+      url: shareUrl,
+      type: 'outsider-share',
+    };
+
+    if (
+      outsiderPolicy &&
+      !policyEnforced &&
+      !_pathMatchesScopes(targetPath, outsiderPolicy)
+    ) {
+      response.warning = 'Outsider policy would deny this path';
+    }
+
+    return reply.send(response);
+  });
+};

package/src/routes/api/status.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Mock config
+const mockConfig = {
+  port: 1934,
+  chromePath: '/usr/bin/chromium',
+  authModes: ['keys'],
+  resolvedInsiders: [{ email: 'a@b.com' }, { email: 'c@d.com' }],
+  resolvedKeys: [{ name: 'primary' }],
+  events: {
+    deploy: { cmd: 'deploy.sh', schema: {} },
+    notify: { cmd: 'notify.sh', schema: {} },
+  },
+  mermaidCliPath: '/tools/mermaid',
+  plantuml: {
+    jarPath: '/tools/plantuml.jar',
+    servers: ['https://plantuml.com/plantuml'],
+  },
+  watcherUrl: null,
+  runnerUrl: null,
+  exportFormats: ['pdf', 'docx', 'zip'],
+};
+
+vi.mock('../../config/index.js', () => ({
+  getConfig: () => mockConfig,
+}));
+
+// Must import AFTER mock
+const { statusRoutes } = await import('./status.js');
+
+describe('GET /api/status', () => {
+  it('returns structured status for insider requests', async () => {
+    // Create a minimal Fastify-like test harness
+    const routes: Record<string, (req: unknown) => Promise<unknown>> = {};
+    const fakeFastify = {
+      get: (path: string, handler: (req: unknown) => Promise<unknown>) => {
+        routes[path] = handler;
+      },
+    };
+
+    await statusRoutes(fakeFastify as never, {});
+
+    const handler = routes['/api/status'];
+    expect(handler).toBeDefined();
+
+    const result = await handler({ accessMode: 'insider' });
+    const status = result as Record<string, unknown>;
+
+    expect(status).toHaveProperty('version');
+    expect(status).toHaveProperty('uptime');
+    expect(status.port).toBe(1934);
+    expect((status.chrome as { configured: boolean }).configured).toBe(true);
+    expect((status.auth as { insiderCount: number }).insiderCount).toBe(2);
+    expect((status.auth as { keyCount: number }).keyCount).toBe(1);
+    expect(status.events).toHaveLength(2);
+    expect(status.exportFormats).toEqual(['pdf', 'docx', 'zip']);
+    expect((status.diagrams as { mermaid: boolean }).mermaid).toBe(true);
+  });
+
+  it('rejects non-insider requests', async () => {
+    const routes: Record<string, (req: unknown) => Promise<unknown>> = {};
+    const fakeFastify = {
+      get: (path: string, handler: (req: unknown) => Promise<unknown>) => {
+        routes[path] = handler;
+      },
+    };
+
+    await statusRoutes(fakeFastify as never, {});
+    const result = await routes['/api/status']({ accessMode: 'outsider' });
+    expect(result).toEqual({ error: 'Insider auth required' });
+  });
+});

package/src/routes/api/status.ts

@@ -0,0 +1,82 @@
+/**
+ * Server status endpoint — structured metadata for diagnostics and TOOLS.md generation.
+ *
+ * Returns version, uptime, port, connected services reachability,
+ * event schemas, insider count (no PII), and export capabilities.
+ */
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import { getConfig } from '../../config/index.js';
+import { packageVersion } from '../../util/packageVersion.js';
+
+const startTime = Date.now();
+
+interface ServiceStatus {
+  url: string;
+  reachable: boolean;
+  version?: string;
+}
+
+async function checkService(url: string): Promise<ServiceStatus> {
+  try {
+    const res = await fetch(`${url}/status`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (res.ok) {
+      const data = (await res.json()) as { version?: string };
+      return { url, reachable: true, version: data.version };
+    }
+    return { url, reachable: false };
+  } catch {
+    return { url, reachable: false };
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const statusRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get('/api/status', async (request) => {
+    const config = getConfig();
+
+    // Only insiders get status
+    if (request.accessMode !== 'insider') {
+      return { error: 'Insider auth required' };
+    }
+
+    const [watcher, runner] = await Promise.all([
+      config.watcherUrl ? checkService(config.watcherUrl) : null,
+      config.runnerUrl ? checkService(config.runnerUrl) : null,
+    ]);
+
+    return {
+      version: packageVersion,
+      uptime: Math.floor((Date.now() - startTime) / 1000),
+      port: config.port,
+      chrome: {
+        configured: Boolean(config.chromePath),
+        path: config.chromePath,
+      },
+      auth: {
+        modes: config.authModes,
+        insiderCount: config.resolvedInsiders.length,
+        keyCount: config.resolvedKeys.length,
+      },
+      events: Object.entries(config.events).map(([name, schema]) => ({
+        name,
+        cmd: schema.cmd,
+      })),
+      exportFormats: ['pdf', 'docx', 'zip'],
+      diagrams: {
+        mermaid: true, // bundled via @mermaid-js/mermaid-cli
+        plantuml: {
+          localJar: Boolean(config.plantuml.jarPath),
+          servers: config.plantuml.servers,
+        },
+      },
+      services: {
+        watcher,
+        runner,
+      },
+    };
+  });
+};

package/src/routes/auth.ts

@@ -0,0 +1,143 @@
+/**
+ * Google OAuth authentication routes.
+ *
+ * GET /auth/login    - Redirect to Google consent screen
+ * GET /auth/callback - Handle OAuth callback, set session cookie
+ * GET /auth/logout   - Clear session cookie
+ */
+
+import crypto from 'node:crypto';
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import { buildAuthUrl, exchangeCode, getUserInfo } from '../auth/google.js';
+import { COOKIE_NAME, createSessionCookie } from '../auth/session.js';
+import { getConfig, resetConfig } from '../config/index.js';
+import { setInsiderKey } from '../util/state.js';
+
+/**
+ * Build the redirect URI from the request.
+ * Uses the Host header to include port, and X-Forwarded-Proto for scheme.
+ */
+function getRedirectUri(request: {
+  headers: Record<string, string | string[] | undefined>;
+  hostname: string;
+}): string {
+  const proto =
+    (request.headers['x-forwarded-proto'] as string | undefined) ?? 'http';
+  const host =
+    (request.headers['host'] as string | undefined) ?? request.hostname;
+  return `${proto}://${host}/auth/callback`;
+}
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const authRoute: FastifyPluginAsync = async (fastify) => {
+  // GET /auth/login
+  fastify.get<{ Querystring: { returnTo?: string } }>(
+    '/auth/login',
+    async (request, reply) => {
+      const config = getConfig();
+      const google = config.googleAuth;
+      if (!google) {
+        return reply.code(500).send({ error: 'Google OAuth not configured' });
+      }
+
+      const state = request.query.returnTo
+        ? Buffer.from(request.query.returnTo).toString('base64url')
+        : undefined;
+
+      const url = buildAuthUrl(google.clientId, getRedirectUri(request), state);
+      return reply.redirect(url);
+    },
+  );
+
+  // GET /auth/callback
+  fastify.get<{
+    Querystring: { code?: string; error?: string; state?: string };
+  }>('/auth/callback', async (request, reply) => {
+    const config = getConfig();
+    const google = config.googleAuth;
+    const sessionSecret = config.sessionSecret;
+
+    if (!google || !sessionSecret) {
+      return reply.code(500).send({ error: 'Google OAuth not configured' });
+    }
+
+    if (request.query.error) {
+      return reply
+        .code(403)
+        .send({ error: `OAuth error: ${request.query.error}` });
+    }
+
+    const code = request.query.code;
+    if (!code) {
+      return reply.code(400).send({ error: 'Missing authorization code' });
+    }
+
+    // Exchange code for tokens
+    const tokens = await exchangeCode(
+      google.clientId,
+      google.clientSecret,
+      getRedirectUri(request),
+      code,
+    );
+
+    // Get user info
+    const userInfo = await getUserInfo(tokens.access_token);
+    if (!userInfo.email_verified) {
+      return reply.code(403).send({ error: 'Email not verified' });
+    }
+
+    const email = userInfo.email.toLowerCase();
+
+    // Check if user is a configured insider
+    const insider = config.resolvedInsiders.find(
+      (i) => i.email.toLowerCase() === email,
+    );
+    if (!insider) {
+      return reply.code(403).send({
+        error: 'Access denied. Your email is not authorized.',
+      });
+    }
+
+    // Auto-generate insider key on first login if missing
+    if (!insider.seed) {
+      const newSeed = crypto.randomBytes(32).toString('hex');
+      const timestamp = new Date().toISOString();
+      insider.seed = newSeed;
+
+      // Persist to state.json (mutable runtime state)
+      setInsiderKey(insider.email, newSeed, timestamp);
+      resetConfig(); // Reload to pick up new state
+    }
+
+    // Set session cookie
+    const cookieValue = createSessionCookie(
+      email,
+      sessionSecret,
+      userInfo.picture,
+    );
+    void reply.setCookie(COOKIE_NAME, cookieValue, {
+      path: '/',
+      httpOnly: true,
+      secure:
+        (request.headers['x-forwarded-proto'] as string | undefined) ===
+        'https',
+      sameSite: 'lax',
+      maxAge: 30 * 24 * 60 * 60, // 30 days in seconds
+    });
+
+    // Redirect to returnTo or root
+    const returnTo = request.query.state
+      ? Buffer.from(request.query.state, 'base64url').toString()
+      : '/browse';
+    return reply.redirect(returnTo);
+  });
+
+  // GET /auth/logout
+
+  fastify.get('/auth/logout', async (_request, reply) => {
+    void reply.clearCookie(COOKIE_NAME, { path: '/' });
+    return reply.redirect('/');
+  });
+};