@karmaniverous/jeeves-server 3.0.0-0

package/dist/src/routes/api/sharing.js

@@ -0,0 +1,203 @@
+/**
+ * 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 { _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, } 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 = 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;
+        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('/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;
+        let shareUrl;
+        if ((depth && depth > 0) || dirs) {
+            const stack = encodeStack([targetPath]);
+            const deepParams = {
+                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('/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 = [];
+        const unknownIds = [];
+        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 = {
+            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 = {
+            url: shareUrl,
+            type: 'outsider-share',
+        };
+        if (outsiderPolicy &&
+            !policyEnforced &&
+            !_pathMatchesScopes(targetPath, outsiderPolicy)) {
+            response.warning = 'Outsider policy would deny this path';
+        }
+        return reply.send(response);
+    });
+};

package/dist/src/routes/api/status.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { getConfig } from '../../config/index.js';
+import { packageVersion } from '../../util/packageVersion.js';
+const startTime = Date.now();
+async function checkService(url) {
+    try {
+        const res = await fetch(`${url}/status`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            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 = 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/dist/src/routes/api/status.test.js

@@ -0,0 +1,62 @@
+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 = {};
+        const fakeFastify = {
+            get: (path, handler) => {
+                routes[path] = handler;
+            },
+        };
+        await statusRoutes(fakeFastify, {});
+        const handler = routes['/api/status'];
+        expect(handler).toBeDefined();
+        const result = await handler({ accessMode: 'insider' });
+        const status = result;
+        expect(status).toHaveProperty('version');
+        expect(status).toHaveProperty('uptime');
+        expect(status.port).toBe(1934);
+        expect(status.chrome.configured).toBe(true);
+        expect(status.auth.insiderCount).toBe(2);
+        expect(status.auth.keyCount).toBe(1);
+        expect(status.events).toHaveLength(2);
+        expect(status.exportFormats).toEqual(['pdf', 'docx', 'zip']);
+        expect(status.diagrams.mermaid).toBe(true);
+    });
+    it('rejects non-insider requests', async () => {
+        const routes = {};
+        const fakeFastify = {
+            get: (path, handler) => {
+                routes[path] = handler;
+            },
+        };
+        await statusRoutes(fakeFastify, {});
+        const result = await routes['/api/status']({ accessMode: 'outsider' });
+        expect(result).toEqual({ error: 'Insider auth required' });
+    });
+});

package/dist/src/routes/auth.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { 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) {
+    const proto = request.headers['x-forwarded-proto'] ?? 'http';
+    const host = request.headers['host'] ?? request.hostname;
+    return `${proto}://${host}/auth/callback`;
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+export const authRoute = async (fastify) => {
+    // GET /auth/login
+    fastify.get('/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('/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'] ===
+                '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('/');
+    });
+};

package/dist/src/routes/event.js

@@ -0,0 +1,77 @@
+/**
+ * Event Gateway webhook endpoint
+ */
+import { JsonMap } from '@karmaniverous/jsonmap';
+import Ajv from 'ajv';
+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();
+/**
+ * Match request body against configured event schemas
+ */
+function matchEvent(body) {
+    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, map) {
+    if (!map)
+        return body;
+    // JsonMap with radash available as $.lib._
+    const mapper = new JsonMap(map, { _: _ });
+    const result = await mapper.transform(body);
+    return result;
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+export const eventRoute = async (fastify) => {
+    // Auth middleware
+    fastify.addHook('preHandler', async (request, reply) => {
+        if (!request.url.startsWith('/event'))
+            return;
+        const provided = request.query.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('/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 };
+        }
+    });
+};