@karmaniverous/jeeves-server 3.0.0-0

package/src/auth/keys.ts

@@ -0,0 +1,252 @@
+/**
+ * Authentication key verification and management.
+ *
+ * Key model: each configured key is an API key "seed". Insider and outsider
+ * keys are derived from seeds via HMAC. Verification iterates all seeds,
+ * checking derived keys. Scopes (if present) further restrict which paths
+ * a seed grants access to.
+ *
+ * Directory outsider links: an outsider key generated for a directory path
+ * grants access to all descendants. Verification checks the provided key
+ * against the requested path AND all ancestor paths.
+ */
+
+import picomatch from 'picomatch';
+
+import type {
+  KeyVerificationResult,
+  NormalizedScopes,
+  ResolvedInsider,
+  ResolvedKey,
+} from '../config/types.js';
+import {
+  computeDeepShareKey,
+  computeInsiderKey,
+  computeOutsiderKeyWithExpiry,
+  computePathKey,
+  type DeepShareParams,
+  timingSafeEqual,
+} from '../util/crypto.js';
+
+/**
+ * Check whether a path matches a list of scope patterns.
+ * Uses picomatch for glob matching — standard glob semantics apply.
+ * Use `/**` for recursive matching, `/*` for single-level only.
+ */
+function pathMatchesPatterns(requestPath: string, patterns: string[]): boolean {
+  const normalized = requestPath.toLowerCase().replace(/\/+$/, '');
+  const isMatch = picomatch(
+    patterns.map((p) => p.toLowerCase().replace(/\/+$/, '')),
+    { dot: true },
+  );
+  return isMatch(normalized);
+}
+
+/**
+ * Check whether a request path matches normalized scopes (allow/deny).
+ * Path must match at least one allow rule AND NOT match any deny rule.
+ */
+function pathMatchesScopes(
+  requestPath: string,
+  scopes: NormalizedScopes,
+): boolean {
+  if (!pathMatchesPatterns(requestPath, scopes.allow)) return false;
+  if (scopes.deny.length > 0 && pathMatchesPatterns(requestPath, scopes.deny))
+    return false;
+  return true;
+}
+
+/**
+ * Get the requested path and all ancestor paths.
+ * E.g. "/d/projects/foo/bar.md" results in that path plus all ancestors.
+ */
+function getPathAndAncestors(urlPath: string): string[] {
+  const paths = [urlPath];
+  let current = urlPath;
+  while (current.includes('/')) {
+    current = current.substring(0, current.lastIndexOf('/'));
+    paths.push(current);
+  }
+  return paths;
+}
+
+/**
+ * Check an outsider key against a seed for exact path or any ancestor (directory links).
+ * Returns the matched path if found, or null.
+ */
+function checkOutsiderKey(
+  seed: string,
+  urlPath: string,
+  providedKey: string,
+  expParam: string | undefined,
+  deepParams?: { d: string; dirs: string; s: string },
+): string | null {
+  // Deep share key check (when d and s params are present)
+  if (deepParams) {
+    const params: DeepShareParams = {
+      depth: parseInt(deepParams.d, 10),
+      dirs: deepParams.dirs === '1',
+      stack: deepParams.s,
+      exp: expParam,
+    };
+    if (!isNaN(params.depth)) {
+      // Check expiry if present
+      if (params.exp) {
+        const expiry = parseInt(params.exp, 10);
+        if (isNaN(expiry) || expiry < Date.now()) return null;
+      }
+      const expectedKey = computeDeepShareKey(seed, urlPath, params);
+      if (timingSafeEqual(providedKey, expectedKey)) return urlPath;
+    }
+    return null; // Deep params present but invalid — don't fall through to legacy
+  }
+
+  // Legacy outsider key check (no deep params)
+  const pathsToCheck = getPathAndAncestors(urlPath);
+
+  for (const checkPath of pathsToCheck) {
+    // Check with expiry
+    if (expParam) {
+      const expiry = parseInt(expParam, 10);
+      if (!isNaN(expiry) && expiry >= Date.now()) {
+        const expectedKey = computeOutsiderKeyWithExpiry(
+          seed,
+          checkPath,
+          expParam,
+        );
+        if (timingSafeEqual(providedKey, expectedKey)) return checkPath;
+      }
+    }
+
+    // Check without expiry
+    const expectedKey = computePathKey(seed, checkPath);
+    if (timingSafeEqual(providedKey, expectedKey)) return checkPath;
+  }
+
+  return null;
+}
+
+/**
+ * Verify a provided key against all configured seeds and determine access mode.
+ *
+ * Machine API keys can grant both insider and outsider access.
+ * Insider (Google OAuth) seeds can only grant outsider access — they are
+ * never valid as insider URL keys.
+ *
+ * Outsider keys are checked against the requested path and all ancestor
+ * paths, enabling directory-level outsider links.
+ */
+export function verifyKey(
+  resolvedKeys: ResolvedKey[],
+  urlPath: string,
+  providedKey: string | undefined,
+  expParam: string | undefined,
+  resolvedInsiders: ResolvedInsider[] = [],
+  deepParams?: { d: string; dirs: string; s: string },
+): KeyVerificationResult {
+  const fail: KeyVerificationResult = {
+    valid: false,
+    mode: null,
+    keyName: null,
+    seed: null,
+    matchedPath: null,
+  };
+
+  if (!providedKey) return fail;
+
+  // Check machine API keys (insider + outsider access)
+  for (const rk of resolvedKeys) {
+    // Check insider key (exact only, no ancestor check)
+    const insiderKey = computeInsiderKey(rk.seed);
+    if (timingSafeEqual(providedKey, insiderKey)) {
+      if (rk.scopes && !pathMatchesScopes(urlPath, rk.scopes)) {
+        continue;
+      }
+      return {
+        valid: true,
+        mode: 'insider',
+        keyName: rk.name,
+        seed: rk.seed,
+        matchedPath: null,
+      };
+    }
+
+    // Check outsider key (exact path + ancestors for directory links)
+    const machineMatch = checkOutsiderKey(
+      rk.seed,
+      urlPath,
+      providedKey,
+      expParam,
+      deepParams,
+    );
+    if (machineMatch !== null) {
+      if (rk.scopes && !pathMatchesScopes(urlPath, rk.scopes)) {
+        continue;
+      }
+      return {
+        valid: true,
+        mode: 'outsider',
+        keyName: rk.name,
+        seed: rk.seed,
+        matchedPath: machineMatch,
+      };
+    }
+  }
+
+  // Check insider seeds for outsider access ONLY (never insider access)
+  for (const ri of resolvedInsiders) {
+    if (!ri.seed) continue;
+
+    const insiderMatch = checkOutsiderKey(
+      ri.seed,
+      urlPath,
+      providedKey,
+      expParam,
+      deepParams,
+    );
+    if (insiderMatch !== null) {
+      if (ri.scopes && !pathMatchesScopes(urlPath, ri.scopes)) {
+        continue;
+      }
+      return {
+        valid: true,
+        mode: 'outsider',
+        keyName: ri.email,
+        seed: ri.seed,
+        matchedPath: insiderMatch,
+      };
+    }
+  }
+
+  return fail;
+}
+
+/**
+ * Check whether a directory should be visible given allow scope patterns.
+ * A directory is visible if any allowed scope is under it OR above it.
+ * This enables navigating toward allowed paths through parent directories.
+ */
+function directoryVisibleUnderScopes(
+  dirUrlPath: string,
+  allowPatterns: string[],
+): boolean {
+  const normalized = dirUrlPath.toLowerCase().replace(/\/+$/, '');
+  for (const pattern of allowPatterns) {
+    const p = pattern.toLowerCase().replace(/\/+$/, '');
+    // Strip trailing glob parts to get the "prefix" of the pattern
+    const prefix = p.replace(/\/\*\*$/, '').replace(/\/\*$/, '');
+    // Directory is above a scope (navigate toward it)
+    if (prefix.startsWith(normalized + '/') || prefix === normalized)
+      return true;
+    // Directory is under a scope (already inside an allowed area)
+    if (normalized.startsWith(prefix + '/') || normalized === prefix)
+      return true;
+  }
+  return false;
+}
+
+export {
+  directoryVisibleUnderScopes as _directoryVisibleUnderScopes,
+  pathMatchesPatterns as _pathMatchesPatterns,
+  pathMatchesScopes as _pathMatchesScopes,
+};

package/src/auth/resolve.ts

@@ -0,0 +1,157 @@
+/**
+ * Unified auth resolution — single function to resolve authentication
+ * from any combination of key params, session cookies, and insider seeds.
+ *
+ * Replaces duplicated auth resolution logic across middleware, keys, sharing,
+ * and auth-status routes.
+ */
+
+import type { FastifyRequest } from 'fastify';
+
+import type {
+  AccessMode,
+  NormalizedScopes,
+  ResolvedInsider,
+  RuntimeConfig,
+} from '../config/types.js';
+import { computeInsiderKey, timingSafeEqual } from '../util/crypto.js';
+import { formatRelativeTime } from '../util/formatters.js';
+import { verifyKey } from './keys.js';
+import { COOKIE_NAME, verifySessionCookie } from './session.js';
+
+export interface AuthResult {
+  valid: boolean;
+  mode?: AccessMode;
+  seed?: string;
+  scopes?: NormalizedScopes | null;
+  email?: string;
+  keyAge?: string | null;
+  keyName?: string | null;
+  matchedPath?: string | null;
+  deepShareParams?: { d: string; dirs: string; s: string };
+}
+
+const FAIL: AuthResult = { valid: false };
+
+/**
+ * Resolve auth from a key parameter (machine API keys + insider outsider keys).
+ * Checks both resolvedKeys and resolvedInsiders.
+ */
+export function resolveKeyAuth(
+  config: RuntimeConfig,
+  urlPath: string,
+  key: string | undefined,
+  expParam: string | undefined,
+  deepParams?: { d: string; dirs: string; s: string },
+): AuthResult {
+  if (!key) return FAIL;
+
+  const result = verifyKey(
+    config.resolvedKeys,
+    urlPath,
+    key,
+    expParam,
+    config.resolvedInsiders,
+    deepParams,
+  );
+
+  if (result.valid) {
+    return {
+      valid: true,
+      mode: result.mode ?? undefined,
+      seed: result.seed ?? undefined,
+      keyName: result.keyName,
+      matchedPath: result.matchedPath,
+      deepShareParams: deepParams,
+    };
+  }
+
+  return FAIL;
+}
+
+/**
+ * Resolve auth from a key that might be an insider key (derived from seed).
+ * Used when we need to match a provided key against insider seeds directly.
+ */
+export function resolveInsiderKeyAuth(
+  config: RuntimeConfig,
+  key: string,
+): AuthResult {
+  // Check machine keys
+  for (const rk of config.resolvedKeys) {
+    const insiderKey = computeInsiderKey(rk.seed);
+    if (timingSafeEqual(key, insiderKey)) {
+      return {
+        valid: true,
+        mode: 'insider',
+        seed: rk.seed,
+        scopes: rk.scopes,
+        keyName: rk.name,
+      };
+    }
+  }
+
+  // Check insider seeds
+  for (const ri of config.resolvedInsiders) {
+    if (!ri.seed) continue;
+    const insiderKey = computeInsiderKey(ri.seed);
+    if (timingSafeEqual(key, insiderKey)) {
+      return {
+        valid: true,
+        mode: 'insider',
+        seed: ri.seed,
+        scopes: ri.scopes,
+        email: ri.email,
+        keyName: ri.email,
+      };
+    }
+  }
+
+  return FAIL;
+}
+
+/**
+ * Resolve auth from a session cookie.
+ * Returns insider auth if the session email matches a configured insider with a seed.
+ */
+export function resolveSessionAuth(
+  config: RuntimeConfig,
+  request: FastifyRequest,
+): AuthResult {
+  const { sessionSecret } = config;
+  if (!sessionSecret) return FAIL;
+
+  const cookieValue = (request.cookies as Record<string, string> | undefined)?.[
+    COOKIE_NAME
+  ];
+  if (!cookieValue) return FAIL;
+
+  const session = verifySessionCookie(cookieValue, sessionSecret);
+  if (!session) return FAIL;
+
+  const insider = config.resolvedInsiders.find(
+    (i) => i.email.toLowerCase() === session.email.toLowerCase(),
+  );
+  if (!insider?.seed) return FAIL;
+
+  return {
+    valid: true,
+    mode: 'insider',
+    seed: insider.seed,
+    scopes: insider.scopes,
+    email: insider.email,
+    keyAge: insider.keyCreatedAt
+      ? formatRelativeTime(insider.keyCreatedAt)
+      : null,
+  };
+}
+
+/**
+ * Find a resolved insider by email.
+ */
+export function findInsider(
+  insiders: ResolvedInsider[],
+  email: string,
+): ResolvedInsider | undefined {
+  return insiders.find((i) => i.email.toLowerCase() === email.toLowerCase());
+}

package/src/auth/session.ts

@@ -0,0 +1,77 @@
+/**
+ * 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
+
+export interface SessionPayload {
+  email: string;
+  picture?: string;
+  exp: number;
+}
+
+/**
+ * Create a signed session cookie value.
+ */
+export function createSessionCookie(
+  email: string,
+  sessionSecret: string,
+  picture?: string,
+): string {
+  const payload: SessionPayload = {
+    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: string,
+  sessionSecret: string,
+): SessionPayload | null {
+  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(),
+    ) as SessionPayload;
+    if (payload.exp < Date.now()) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+export { COOKIE_NAME };

package/src/cli/commands/config.test.ts

@@ -0,0 +1,107 @@
+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: string, config: unknown): string {
+  const filePath = path.join(dir, 'jeeves-server.config.json');
+  fs.writeFileSync(filePath, JSON.stringify(config));
+  return filePath;
+}
+
+async function runCli(
+  args: string[],
+): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync('node', [CLI_PATH, ...args], { timeout: 10_000 });
+}
+
+describe('jeeves-server config validate', () => {
+  let tmpDir: string;
+
+  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: string;
+
+  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/src/cli/commands/config.ts

@@ -0,0 +1,113 @@
+/**
+ * @packageDocumentation
+ *
+ * CLI commands: config validate, config show.
+ */
+
+import type { Command } from '@commander-js/extra-typings';
+
+import { loadConfig } from '../../config/index.js';
+import type { NormalizedScopes } from '../../config/types.js';
+
+function formatScopes(scopes: NormalizedScopes | null): string {
+  return scopes
+    ? `scoped (allow: ${String(scopes.allow.length)}, deny: ${String(scopes.deny.length)})`
+    : 'unscoped';
+}
+
+export function registerConfigCommand(cli: Command): void {
+  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);
+      }
+    });
+}