@karmaniverous/jeeves-server 3.0.0-0

package/dist/src/auth/session.js

@@ -0,0 +1,57 @@
+/**
+ * Cookie-based session management for Google OAuth insiders.
+ *
+ * Session cookie = base64(payload) + "." + HMAC(sessionSecret, base64part)
+ * No server-side session store needed — config has all insider state.
+ */
+import crypto from 'node:crypto';
+const COOKIE_NAME = 'jeeves_session';
+const SESSION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/**
+ * Create a signed session cookie value.
+ */
+export function createSessionCookie(email, sessionSecret, picture) {
+    const payload = {
+        email,
+        ...(picture ? { picture } : {}),
+        exp: Date.now() + SESSION_MAX_AGE_MS,
+    };
+    const b64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const sig = crypto
+        .createHmac('sha256', sessionSecret)
+        .update(b64)
+        .digest('hex');
+    return `${b64}.${sig}`;
+}
+/**
+ * Verify and decode a session cookie. Returns null if invalid/expired.
+ */
+export function verifySessionCookie(cookieValue, sessionSecret) {
+    const dotIdx = cookieValue.lastIndexOf('.');
+    if (dotIdx < 0)
+        return null;
+    const b64 = cookieValue.slice(0, dotIdx);
+    const sig = cookieValue.slice(dotIdx + 1);
+    const expectedSig = crypto
+        .createHmac('sha256', sessionSecret)
+        .update(b64)
+        .digest('hex');
+    try {
+        if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(Buffer.from(b64, 'base64url').toString());
+        if (payload.exp < Date.now())
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+export { COOKIE_NAME };

package/dist/src/cli/commands/config.js

@@ -0,0 +1,100 @@
+/**
+ * @packageDocumentation
+ *
+ * CLI commands: config validate, config show.
+ */
+import { loadConfig } from '../../config/index.js';
+function formatScopes(scopes) {
+    return scopes
+        ? `scoped (allow: ${String(scopes.allow.length)}, deny: ${String(scopes.deny.length)})`
+        : 'unscoped';
+}
+export function registerConfigCommand(cli) {
+    const config = cli.command('config').description('Configuration management');
+    config
+        .command('validate')
+        .description('Validate the configuration file')
+        .option('-c, --config <path>', 'Path to configuration file')
+        .action(async (options) => {
+        try {
+            const cfg = await loadConfig(options.config);
+            console.log('\u2713 Configuration valid');
+            console.log(`  Port: ${String(cfg.port)}`);
+            console.log(`  Auth modes: ${cfg.authModes.join(', ')}`);
+            console.log(`  Keys: ${String(cfg.resolvedKeys.length)}`);
+            console.log(`  Insiders: ${String(cfg.resolvedInsiders.length)}`);
+            console.log(`  Events: ${String(Object.keys(cfg.events).length)} schemas`);
+            if (cfg.watcherUrl)
+                console.log(`  Watcher: ${cfg.watcherUrl}`);
+            if (cfg.runnerUrl)
+                console.log(`  Runner: ${cfg.runnerUrl}`);
+        }
+        catch (error) {
+            console.error('\u2717 Configuration invalid');
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    config
+        .command('show')
+        .description('Display resolved configuration with provenance')
+        .option('-c, --config <path>', 'Path to configuration file')
+        .action(async (options) => {
+        try {
+            const cfg = await loadConfig(options.config);
+            console.log(`Config file: ${cfg.configPath}`);
+            console.log('');
+            console.log('Server:');
+            console.log(`  port: ${String(cfg.port)}`);
+            console.log(`  chromePath: ${cfg.chromePath}`);
+            if (cfg.roots) {
+                console.log(`  roots: ${JSON.stringify(cfg.roots)}`);
+            }
+            console.log('');
+            console.log('Auth:');
+            console.log(`  modes: ${cfg.authModes.join(', ')}`);
+            console.log(`  googleAuth: ${cfg.googleAuth ? 'configured' : 'none'}`);
+            console.log(`  sessionSecret: ${cfg.sessionSecret ? '***' : 'none'}`);
+            console.log('');
+            console.log('Keys:');
+            for (const key of cfg.resolvedKeys) {
+                console.log(`  ${key.name}: ${key.seed.slice(0, 8)}... (${formatScopes(key.scopes)})`);
+            }
+            console.log('');
+            console.log('Insiders:');
+            for (const insider of cfg.resolvedInsiders) {
+                console.log(`  ${insider.email}: ${formatScopes(insider.scopes)}`);
+            }
+            console.log('');
+            console.log('Integrations:');
+            console.log(`  watcherUrl: ${cfg.watcherUrl ?? 'not configured'}`);
+            console.log(`  runnerUrl: ${cfg.runnerUrl ?? 'not configured'}`);
+            console.log('');
+            console.log('Events:');
+            const eventNames = Object.keys(cfg.events);
+            if (eventNames.length === 0) {
+                console.log('  (none)');
+            }
+            else {
+                for (const name of eventNames) {
+                    console.log(`  ${name}: ${cfg.events[name].cmd}`);
+                }
+            }
+            console.log('');
+            console.log('Diagrams:');
+            console.log(`  mermaidCliPath: ${cfg.mermaidCliPath ?? 'not configured'}`);
+            console.log(`  plantuml.jarPath: ${cfg.plantuml.jarPath ?? 'not configured'}`);
+            console.log(`  plantuml.servers: ${cfg.plantuml.servers.join(', ')}`);
+            console.log('');
+            console.log('Paths:');
+            console.log(`  stateFile: ${cfg.stateFile}`);
+            console.log(`  eventsLog: ${cfg.eventsLog}`);
+            console.log(`  diagramCachePath: ${cfg.diagramCachePath ?? '(default)'}`);
+        }
+        catch (error) {
+            console.error('Failed to load config');
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+}

package/dist/src/cli/commands/config.test.js

@@ -0,0 +1,84 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+const execFileAsync = promisify(execFile);
+const CLI_PATH = path.resolve(import.meta.dirname, '../../../dist/src/cli/index.js');
+const VALID_CONFIG = {
+    port: 8765,
+    chromePath: '/usr/bin/chromium',
+    auth: { modes: ['keys'] },
+    keys: {
+        primary: 'a'.repeat(64),
+        _internal: 'b'.repeat(64),
+    },
+    events: {},
+};
+function writeConfig(dir, config) {
+    const filePath = path.join(dir, 'jeeves-server.config.json');
+    fs.writeFileSync(filePath, JSON.stringify(config));
+    return filePath;
+}
+async function runCli(args) {
+    return execFileAsync('node', [CLI_PATH, ...args], { timeout: 10_000 });
+}
+describe('jeeves-server config validate', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-cli-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('validates a valid config and prints summary', async () => {
+        const configPath = writeConfig(tmpDir, VALID_CONFIG);
+        const { stdout } = await runCli(['config', 'validate', '-c', configPath]);
+        expect(stdout).toContain('Configuration valid');
+        expect(stdout).toContain('Port: 8765');
+        expect(stdout).toContain('Auth modes: keys');
+        expect(stdout).toContain('Keys: 2');
+    });
+    it('exits with error for invalid config', async () => {
+        const configPath = writeConfig(tmpDir, { port: 1234 });
+        await expect(runCli(['config', 'validate', '-c', configPath])).rejects.toMatchObject({
+            code: 1,
+        });
+    });
+});
+describe('jeeves-server config show', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-cli-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('shows resolved config with key and insider details', async () => {
+        const configPath = writeConfig(tmpDir, {
+            ...VALID_CONFIG,
+            insiders: { 'test@example.com': {} },
+            watcherUrl: 'http://localhost:3458',
+        });
+        const { stdout } = await runCli(['config', 'show', '-c', configPath]);
+        expect(stdout).toContain('Config file:');
+        expect(stdout).toContain('port: 8765');
+        expect(stdout).toContain('modes: keys');
+        expect(stdout).toContain('primary:');
+        expect(stdout).toContain('unscoped');
+        expect(stdout).toContain('test@example.com');
+        expect(stdout).toContain('watcherUrl: http://localhost:3458');
+    });
+    it('shows scoped keys correctly', async () => {
+        const configPath = writeConfig(tmpDir, {
+            ...VALID_CONFIG,
+            keys: {
+                ...VALID_CONFIG.keys,
+                scoped: { key: 'c'.repeat(64), scopes: ['/docs'] },
+            },
+        });
+        const { stdout } = await runCli(['config', 'show', '-c', configPath]);
+        expect(stdout).toContain('scoped (allow: 1, deny: 0)');
+    });
+});

package/dist/src/cli/commands/service.js

@@ -0,0 +1,93 @@
+/**
+ * @packageDocumentation
+ *
+ * CLI commands: service install, service uninstall, service start/stop/restart.
+ */
+import { Command } from '@commander-js/extra-typings';
+const DEFAULT_SERVICE_NAME = 'JeevesServer';
+const LINUX_SERVICE_NAME = 'jeeves-server';
+export function registerServiceCommand(cli) {
+    const service = cli
+        .command('service')
+        .description('System service management');
+    service.addCommand(new Command('install')
+        .description('Print install instructions for a system service')
+        .option('-c, --config <path>', 'Path to configuration file')
+        .option('-n, --name <name>', 'Service name', process.platform === 'win32'
+        ? DEFAULT_SERVICE_NAME
+        : LINUX_SERVICE_NAME)
+        .action((options) => {
+        const name = options.name;
+        const configArg = options.config ? ` --config "${options.config}"` : '';
+        if (process.platform === 'win32') {
+            console.log('# NSSM install commands:');
+            console.log(`nssm install ${name} node "%CD%\\node_modules\\@karmaniverous\\jeeves-server\\dist\\src\\cli\\index.js" start${configArg}`);
+            console.log(`nssm set ${name} AppDirectory "%CD%"`);
+            console.log(`nssm set ${name} AppStdout "%CD%\\logs\\service.log"`);
+            console.log(`nssm set ${name} AppStderr "%CD%\\logs\\service-error.log"`);
+            console.log(`nssm set ${name} Start SERVICE_AUTO_START`);
+            console.log(`nssm start ${name}`);
+            return;
+        }
+        const unit = [
+            '[Unit]',
+            'Description=Jeeves Server',
+            'After=network.target',
+            '',
+            '[Service]',
+            'Type=simple',
+            'WorkingDirectory=%h',
+            `ExecStart=/usr/bin/env jeeves-server start${configArg}`,
+            'Restart=on-failure',
+            '',
+            '[Install]',
+            'WantedBy=default.target',
+        ].join('\n');
+        console.log('# systemd unit file');
+        console.log(`# Save to: ~/.config/systemd/user/${name}.service`);
+        console.log('');
+        console.log(unit);
+        console.log('');
+        console.log('# Then run:');
+        console.log('systemctl --user daemon-reload');
+        console.log(`systemctl --user enable --now ${name}.service`);
+    }));
+    service.addCommand(new Command('uninstall')
+        .description('Print uninstall instructions for a system service')
+        .option('-n, --name <name>', 'Service name', process.platform === 'win32'
+        ? DEFAULT_SERVICE_NAME
+        : LINUX_SERVICE_NAME)
+        .action((options) => {
+        const name = options.name;
+        if (process.platform === 'win32') {
+            console.log('# NSSM uninstall commands:');
+            console.log(`nssm stop ${name}`);
+            console.log(`nssm remove ${name} confirm`);
+            return;
+        }
+        console.log('# systemd uninstall:');
+        console.log(`systemctl --user disable --now ${name}.service`);
+        console.log(`rm ~/.config/systemd/user/${name}.service`);
+        console.log('systemctl --user daemon-reload');
+    }));
+    for (const action of ['start', 'stop', 'restart']) {
+        service.addCommand(new Command(action)
+            .description(`${action.charAt(0).toUpperCase() + action.slice(1)} the system service`)
+            .option('-n, --name <name>', 'Service name', process.platform === 'win32'
+            ? DEFAULT_SERVICE_NAME
+            : LINUX_SERVICE_NAME)
+            .action((options) => {
+            const name = options.name;
+            if (process.platform === 'win32') {
+                if (action === 'restart') {
+                    console.log(`nssm restart ${name}`);
+                }
+                else {
+                    console.log(`nssm ${action} ${name}`);
+                }
+                return;
+            }
+            console.log(`systemctl --user ${action} ${name}.service`);
+        }));
+    }
+}

package/dist/src/cli/commands/start.js

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * CLI command: start — launches the Fastify server.
+ */
+export function registerStartCommand(cli) {
+    cli
+        .command('start')
+        .description('Start the jeeves-server')
+        .option('-c, --config <path>', 'Path to configuration file')
+        .action(async (options) => {
+        try {
+            // Dynamic import to avoid loading server code at CLI parse time
+            const { initConfig } = await import('../../config/index.js');
+            await initConfig(options.config);
+            // Import server after config is initialized
+            await import('../../server.js');
+        }
+        catch (error) {
+            console.error('Failed to start:', error);
+            process.exit(1);
+        }
+    });
+}

package/dist/src/cli/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * @packageDocumentation
+ *
+ * jeeves-server CLI entrypoint.
+ * Commands: start, config validate, config show, service install/uninstall.
+ */
+import { Command } from '@commander-js/extra-typings';
+import { packageVersion } from '../util/packageVersion.js';
+import { registerConfigCommand } from './commands/config.js';
+import { registerServiceCommand } from './commands/service.js';
+import { registerStartCommand } from './commands/start.js';
+const cli = new Command()
+    .name('jeeves-server')
+    .description('Self-hosted file browser, document server, and webhook gateway')
+    .version(packageVersion);
+registerStartCommand(cli);
+registerConfigCommand(cli);
+registerServiceCommand(cli);
+cli.parse();

package/dist/src/config/index.js

@@ -0,0 +1,90 @@
+/**
+ * @packageDocumentation
+ *
+ * Config loading and singleton management.
+ * Loads config via cosmiconfig, validates with Zod, applies env var substitution,
+ * resolves runtime types via resolve.ts, and exposes getConfig()/resetConfig().
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cosmiconfig } from 'cosmiconfig';
+import { buildRuntimeConfig } from './resolve.js';
+import { jeevesConfigSchema } from './schema.js';
+import { substituteEnvVars } from './substituteEnvVars.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '../../..');
+const MODULE_NAME = 'jeeves-server';
+/**
+ * Load and validate jeeves-server configuration via cosmiconfig.
+ *
+ * Searches for `jeeves-server.config.{json,yaml,yml,js,ts,cjs,mjs}`
+ * or `.jeeves-serverrc` in the package root and parent directories.
+ *
+ * @param configPath - Optional explicit path to a config file.
+ * @returns Resolved runtime configuration.
+ */
+export async function loadConfig(configPath) {
+    const explorer = cosmiconfig(MODULE_NAME, {
+        searchPlaces: [
+            'package.json',
+            `.${MODULE_NAME}rc`,
+            `.${MODULE_NAME}rc.json`,
+            `.${MODULE_NAME}rc.yaml`,
+            `.${MODULE_NAME}rc.yml`,
+            `${MODULE_NAME}.config.json`,
+            `${MODULE_NAME}.config.yaml`,
+            `${MODULE_NAME}.config.yml`,
+            `${MODULE_NAME}.config.js`,
+            `${MODULE_NAME}.config.ts`,
+            `${MODULE_NAME}.config.mjs`,
+            `${MODULE_NAME}.config.cjs`,
+        ],
+    });
+    const result = configPath
+        ? await explorer.load(configPath)
+        : await explorer.search(rootDir);
+    if (!result || result.isEmpty) {
+        throw new Error(`No jeeves-server configuration found. Create a jeeves-server.config.json (or .yaml) file.\n` +
+            `Searched from: ${rootDir}`);
+    }
+    const substituted = substituteEnvVars(result.config);
+    const parseResult = jeevesConfigSchema.safeParse(substituted);
+    if (!parseResult.success) {
+        const issues = parseResult.error.issues
+            .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Invalid configuration in ${result.filepath}:\n${issues}`);
+    }
+    return buildRuntimeConfig(parseResult.data, rootDir, result.filepath);
+}
+let configInstance = null;
+/**
+ * Check if the config singleton has been initialized.
+ */
+export function isConfigInitialized() {
+    return configInstance !== null;
+}
+/**
+ * Get the singleton config instance. Initializes on first call.
+ * @throws If config has not been initialized — call initConfig() first.
+ */
+export function getConfig() {
+    if (!configInstance) {
+        throw new Error('Config not initialized. Call initConfig() before getConfig().');
+    }
+    return configInstance;
+}
+/**
+ * Initialize the config singleton. Must be called once at startup.
+ * @param configPath - Optional explicit path to a config file.
+ */
+export async function initConfig(configPath) {
+    configInstance = await loadConfig(configPath);
+    return configInstance;
+}
+/**
+ * Reset the config singleton (for testing).
+ */
+export function resetConfig() {
+    configInstance = null;
+}

package/dist/src/config/loadConfig.test.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { getConfig, initConfig, loadConfig, resetConfig } from './index.js';
+const VALID_CONFIG = {
+    port: 9999,
+    chromePath: '/usr/bin/chromium',
+    auth: { modes: ['keys'] },
+    keys: {
+        primary: 'a'.repeat(64),
+        _internal: 'b'.repeat(64),
+    },
+    events: {},
+};
+function writeConfig(dir, config) {
+    const filePath = path.join(dir, 'jeeves-server.config.json');
+    fs.writeFileSync(filePath, JSON.stringify(config));
+    return filePath;
+}
+describe('loadConfig', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
+        resetConfig();
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        resetConfig();
+    });
+    it('loads a valid JSON config file', async () => {
+        const configPath = writeConfig(tmpDir, VALID_CONFIG);
+        const config = await loadConfig(configPath);
+        expect(config.port).toBe(9999);
+        expect(config.chromePath).toBe('/usr/bin/chromium');
+        expect(config.configPath).toBe(configPath);
+    });
+    it('throws on missing config', async () => {
+        await expect(loadConfig(path.join(tmpDir, 'nonexistent.json'))).rejects.toThrow();
+    });
+    it('throws on invalid config (missing auth)', async () => {
+        const configPath = writeConfig(tmpDir, { port: 1234 });
+        await expect(loadConfig(configPath)).rejects.toThrow('Invalid configuration');
+    });
+    it('applies env var substitution', async () => {
+        const original = process.env['TEST_CHROME_PATH'];
+        process.env['TEST_CHROME_PATH'] = '/custom/chrome';
+        try {
+            const configPath = writeConfig(tmpDir, {
+                ...VALID_CONFIG,
+                chromePath: '${TEST_CHROME_PATH}',
+            });
+            const config = await loadConfig(configPath);
+            expect(config.chromePath).toBe('/custom/chrome');
+        }
+        finally {
+            if (original === undefined)
+                delete process.env['TEST_CHROME_PATH'];
+            else
+                process.env['TEST_CHROME_PATH'] = original;
+        }
+    });
+    it('applies default port when omitted', async () => {
+        const noPort = { ...VALID_CONFIG };
+        delete noPort.port;
+        const configPath = writeConfig(tmpDir, noPort);
+        const config = await loadConfig(configPath);
+        expect(config.port).toBe(1934);
+    });
+    it('rejects _plugin key with scopes', async () => {
+        const configPath = writeConfig(tmpDir, {
+            ...VALID_CONFIG,
+            keys: {
+                ...VALID_CONFIG.keys,
+                _plugin: { key: 'c'.repeat(64), scopes: ['/restricted'] },
+            },
+        });
+        await expect(loadConfig(configPath)).rejects.toThrow('_plugin key must not have scopes');
+    });
+    it('rejects _internal key with scopes', async () => {
+        const configPath = writeConfig(tmpDir, {
+            ...VALID_CONFIG,
+            keys: {
+                ...VALID_CONFIG.keys,
+                _internal: { key: 'b'.repeat(64), scopes: ['/restricted'] },
+            },
+        });
+        await expect(loadConfig(configPath)).rejects.toThrow('_internal key must not have scopes');
+    });
+    it('accepts _plugin key without scopes', async () => {
+        const configPath = writeConfig(tmpDir, {
+            ...VALID_CONFIG,
+            keys: {
+                ...VALID_CONFIG.keys,
+                _plugin: 'c'.repeat(64),
+            },
+        });
+        const config = await loadConfig(configPath);
+        expect(config.resolvedKeys.find((k) => k.name === '_plugin')?.seed).toBe('c'.repeat(64));
+    });
+});
+describe('config singleton', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
+        resetConfig();
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        resetConfig();
+    });
+    it('throws if getConfig called before initConfig', () => {
+        expect(() => getConfig()).toThrow('Config not initialized');
+    });
+    it('initConfig populates getConfig', async () => {
+        const configPath = writeConfig(tmpDir, VALID_CONFIG);
+        await initConfig(configPath);
+        const config = getConfig();
+        expect(config.port).toBe(9999);
+    });
+    it('resetConfig clears the singleton', async () => {
+        const configPath = writeConfig(tmpDir, VALID_CONFIG);
+        await initConfig(configPath);
+        resetConfig();
+        expect(() => getConfig()).toThrow('Config not initialized');
+    });
+});