@karmaniverous/jeeves-server 3.0.0-0

package/src/config/resolve.ts

@@ -0,0 +1,173 @@
+/**
+ * Config resolution — transforms raw validated config into runtime types.
+ *
+ * Handles: key resolution, insider merging with state, PlantUML server defaults,
+ * scope normalization, internal key derivation.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { computeInsiderKey } from '../util/crypto.js';
+import type { JeevesConfig } from './schema.js';
+import type {
+  NormalizedScopes,
+  ResolvedInsider,
+  ResolvedKey,
+  RuntimeConfig,
+  ServerState,
+} from './types.js';
+
+/**
+ * Normalize any scopes format to \{ allow, deny \}.
+ * - undefined/null → null (unrestricted)
+ * - string → \{ allow: [string], deny: [] \}
+ * - string[] → \{ allow: string[], deny: [] \}
+ * - \{ allow?, deny? \} → \{ allow: allow ?? ['/**'], deny: deny ?? [] \}
+ */
+export function normalizeScopes(raw: unknown): NormalizedScopes | null {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw === 'string') return { allow: [raw], deny: [] };
+  if (Array.isArray(raw)) return { allow: raw as string[], deny: [] };
+  if (typeof raw === 'object') {
+    const obj = raw as { allow?: string[]; deny?: string[] };
+    return {
+      allow: obj.allow ?? ['/**'],
+      deny: obj.deny ?? [],
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve raw key entries to ResolvedKey[].
+ */
+export function resolveKeys(
+  keys: Record<string, string | { key: string; scopes?: unknown }>,
+): ResolvedKey[] {
+  return Object.entries(keys).map(([name, entry]) => {
+    if (typeof entry === 'string') {
+      return { name, seed: entry, scopes: null };
+    }
+    return { name, seed: entry.key, scopes: normalizeScopes(entry.scopes) };
+  });
+}
+
+/**
+ * Resolve insider entries by merging config (identity + scopes) with state (keys).
+ */
+export function resolveInsiders(
+  insiders: Record<string, { scopes?: unknown }>,
+  stateFile: string,
+): ResolvedInsider[] {
+  let serverState: ServerState = {};
+  try {
+    if (fs.existsSync(stateFile)) {
+      serverState = JSON.parse(
+        fs.readFileSync(stateFile, 'utf8'),
+      ) as ServerState;
+    }
+  } catch {
+    /* empty state */
+  }
+
+  return Object.entries(insiders).map(([rawEmail, entry]) => {
+    const email = rawEmail.toLowerCase();
+    const scopes = normalizeScopes(entry.scopes);
+    const stateKey = serverState.insiderKeys?.[email];
+    return {
+      email,
+      seed: stateKey?.seed ?? '',
+      scopes,
+      keyCreatedAt: stateKey?.createdAt ?? null,
+    };
+  });
+}
+
+/**
+ * Resolve PlantUML config with auto-discovery and community server fallback.
+ *
+ * If no jarPath is configured, checks for a bundled jar at vendor/plantuml.jar
+ * (downloaded by the postinstall script).
+ */
+export function resolvePlantuml(
+  config?: {
+    jarPath?: string;
+    javaPath?: string;
+    servers?: string[];
+  },
+  rootDir?: string,
+): { jarPath?: string; javaPath?: string; servers: string[] } {
+  const COMMUNITY = 'https://www.plantuml.com/plantuml';
+  const servers = config?.servers ? [...config.servers] : [];
+  if (!servers.includes(COMMUNITY)) servers.push(COMMUNITY);
+
+  let jarPath = config?.jarPath;
+  if (!jarPath && rootDir) {
+    const vendorJar = path.join(rootDir, 'vendor', 'plantuml.jar');
+    if (fs.existsSync(vendorJar)) {
+      jarPath = vendorJar;
+    }
+  }
+
+  return { jarPath, javaPath: config?.javaPath, servers };
+}
+
+/**
+ * Derive the internal insider key from resolved keys.
+ */
+export function deriveInternalKey(resolvedKeys: ResolvedKey[]): string | null {
+  const internalKey = resolvedKeys.find((k) => k.name === '_internal');
+  return internalKey ? computeInsiderKey(internalKey.seed) : null;
+}
+
+/**
+ * Build the full RuntimeConfig from validated config, resolved runtime values, and paths.
+ *
+ * Centralizes the mapping from parsed config + resolved values → RuntimeConfig,
+ * keeping loadConfig focused on loading/validation and this module focused on resolution.
+ */
+export function buildRuntimeConfig(
+  config: JeevesConfig,
+  rootDir: string,
+  configPath: string,
+): RuntimeConfig {
+  const stateFile = path.join(rootDir, 'state.json');
+
+  const resolvedKeys = resolveKeys(
+    config.keys as Record<string, string | { key: string; scopes?: unknown }>,
+  );
+  const resolvedInsiders = resolveInsiders(
+    config.insiders as Record<string, { scopes?: unknown }>,
+    stateFile,
+  );
+
+  return {
+    port: config.port,
+    eventTimeoutMs: config.eventTimeoutMs,
+    eventLogPurgeMs: config.eventLogPurgeMs,
+    maxZipSizeMb: config.maxZipSizeMb,
+    chromePath: config.chromePath,
+    roots: config.roots,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    mermaidCliPath: config.mermaidCliPath,
+    plantuml: resolvePlantuml(config.plantuml, rootDir),
+    outsiderPolicy: normalizeScopes(config.outsiderPolicy) ?? null,
+    events: config.events,
+    authModes: config.auth.modes,
+    resolvedKeys,
+    resolvedInsiders,
+    googleAuth: config.auth.google ?? null,
+    sessionSecret: config.auth.sessionSecret ?? null,
+    internalInsiderKey: deriveInternalKey(resolvedKeys),
+    runnerUrl: config.runnerUrl,
+    watcherUrl: config.watcherUrl,
+    diagramCachePath: config.diagramCachePath,
+    configPath,
+    eventsLog: path.join(rootDir, 'logs', 'webhook-events.jsonl'),
+    stateFile,
+    eventQueuePath: path.join(rootDir, 'logs', 'event-queue.jsonl'),
+    eventQueueCursorPath: path.join(rootDir, 'logs', 'event-queue.cursor'),
+    eventLogPath: path.join(rootDir, 'logs', 'event-log.jsonl'),
+  };
+}

package/src/config/schema.ts

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+
+/** Supported authentication methods */
+export const authModeSchema = z.enum(['google', 'keys']);
+
+/** Google OAuth configuration */
+export const googleAuthSchema = z.object({
+  clientId: z.string().min(1),
+  clientSecret: z.string().min(1),
+});
+
+/** Auth configuration */
+export const authSchema = z.object({
+  /** Active authentication methods. Order determines priority. */
+  modes: z
+    .array(authModeSchema)
+    .min(1, { message: 'At least one auth mode is required' }),
+  /** Google OAuth config. Required if modes includes "google". */
+  google: googleAuthSchema.optional(),
+  /** Session cookie signing secret. Required if modes includes "google". */
+  sessionSecret: z.string().min(1).optional(),
+});
+
+/** Event webhook configuration */
+export const eventConfigSchema = z.object({
+  schema: z.record(z.string(), z.unknown()),
+  cmd: z.string(),
+  map: z.record(z.string(), z.unknown()).optional(),
+  timeoutMs: z.number().positive().optional(),
+});
+
+/**
+ * Scopes configuration â€" controls which paths a user/key can access.
+ *
+ * Three forms:
+ * - `string` â€" single allow pattern (e.g. '/d/*')
+ * - `string[]` — array of allow patterns (shorthand for \{ allow: [...] \})
+ * - `\{ allow?: string[], deny?: string[] \}` — explicit allow/deny rules
+ *
+ * Semantics:
+ * - Path must match at least one allow rule AND NOT match any deny rule
+ * - Omitting `allow` = implicit ['/*'] (allow everything)
+ * - Omitting `deny` = no exclusions
+ * - Omitting scopes entirely = unrestricted access
+ */
+export const scopesObjectSchema = z.object({
+  allow: z.array(z.string()).optional(),
+  deny: z.array(z.string()).optional(),
+});
+
+export const scopesSchema = z.union([
+  z.string(),
+  z.array(z.string()),
+  scopesObjectSchema,
+]);
+
+/** Insider entry (identity + scopes only; keys are in state.json) */
+export const insiderEntrySchema = z.object({
+  scopes: scopesSchema.optional(),
+});
+
+/** Key entry â€" plain string (seed, no scopes) or object with key + optional scopes */
+export const keyEntrySchema = z.union([
+  z.string().min(1),
+  z.object({
+    key: z.string().min(1),
+    scopes: scopesSchema.optional(),
+  }),
+]);
+
+/** Top-level Jeeves Server configuration */
+export const jeevesConfigSchema = z
+  .object({
+    port: z.number().int().positive().default(1934),
+    chromePath: z.string().min(1),
+    auth: authSchema,
+    insiders: z.record(z.email(), insiderEntrySchema).default({}),
+    keys: z.record(z.string(), keyEntrySchema).default({}),
+    events: z.record(z.string(), eventConfigSchema).default({}),
+    eventTimeoutMs: z.number().positive().default(30_000),
+    eventLogPurgeMs: z.number().positive().default(2_592_000_000),
+    /** Maximum directory size in MB for ZIP export. Directories exceeding this are refused. */
+    maxZipSizeMb: z.number().positive().default(100),
+    /**
+     * Filesystem roots for the file browser (Linux only).
+     * Map of id â†' filesystem path. On Windows this is ignored (drives are auto-discovered).
+     * Example: \{ home: '/home/user', projects: '/opt/projects' \}
+     * Default: \{ root: '/' \}
+     */
+    roots: z.record(z.string(), z.string()).optional(),
+    /**
+     * URL of the jeeves-runner API for process dashboard proxy.
+     * Default: 'http://127.0.0.1:3100'
+     */
+    runnerUrl: z.url().optional(),
+    /** @deprecated Mermaid is now bundled. This field is ignored but kept for backward compatibility. */
+    mermaidCliPath: z.string().optional(),
+    /**
+     * PlantUML rendering configuration.
+     * - jarPath: local PlantUML jar (requires Java). Tried first â€" supports !include.
+     * - servers: fallback PlantUML server URLs, tried in order.
+     *   The public community server (https://www.plantuml.com/plantuml) is always
+     *   appended as the last resort unless explicitly listed.
+     * If omitted entirely, only the community server is used.
+     */
+    plantuml: z
+      .object({
+        jarPath: z.string().optional(),
+        javaPath: z.string().optional(),
+        servers: z.array(z.url()).optional(),
+      })
+      .optional(),
+    /**
+     * Directory for cached rendered diagrams (content-addressed by source hash).
+     * Defaults to `.diagram-cache` in the server working directory.
+     */
+    diagramCachePath: z.string().optional(),
+    /**
+     * URL of the jeeves-watcher API for semantic search.
+     * When set, the search UI appears in the header. Example: 'http://localhost:3458'
+     */
+    watcherUrl: z.url().optional(),
+    /**
+     * Global outsider policy â€" constrains which paths are eligible for outsider sharing.
+     * Uses the same allow/deny model as insider scopes.
+     * If omitted, all paths are shareable with outsiders.
+     */
+    outsiderPolicy: scopesObjectSchema.optional(),
+  })
+  .superRefine((config, ctx) => {
+    // Google auth mode requires google config + sessionSecret
+    if (config.auth.modes.includes('google')) {
+      if (!config.auth.google) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'auth.google is required when auth.modes includes "google"',
+          path: ['auth', 'google'],
+        });
+      }
+      if (!config.auth.sessionSecret) {
+        ctx.addIssue({
+          code: 'custom',
+          message:
+            'auth.sessionSecret is required when auth.modes includes "google"',
+          path: ['auth', 'sessionSecret'],
+        });
+      }
+    }
+
+    // Keys auth mode requires at least one key
+    if (
+      config.auth.modes.includes('keys') &&
+      Object.keys(config.keys).length === 0
+    ) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'At least one key is required when auth.modes includes "keys"',
+        path: ['keys'],
+      });
+    }
+
+    // _internal and _plugin keys must not have scopes
+    for (const reserved of ['_internal', '_plugin'] as const) {
+      const key = config.keys[reserved];
+      if (key && typeof key === 'object' && 'scopes' in key && key.scopes) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `${reserved} key must not have scopes (it is always unscoped)`,
+          path: ['keys', reserved],
+        });
+      }
+    }
+  });
+
+/** Inferred config type */
+export type JeevesConfig = z.infer<typeof jeevesConfigSchema>;
+
+/** Auth mode type */
+export type AuthMode = z.infer<typeof authModeSchema>;

package/src/config/substituteEnvVars.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { substituteEnvVars } from './substituteEnvVars.js';
+
+describe('substituteEnvVars', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  afterEach(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('replaces a single env var in a string', () => {
+    process.env['TEST_VAR'] = 'hello';
+    expect(substituteEnvVars('${TEST_VAR}')).toBe('hello');
+  });
+
+  it('replaces multiple env vars in a string', () => {
+    process.env['HOST'] = 'localhost';
+    process.env['PORT'] = '3456';
+    expect(substituteEnvVars('http://${HOST}:${PORT}')).toBe(
+      'http://localhost:3456',
+    );
+  });
+
+  it('leaves unresolvable expressions untouched', () => {
+    expect(substituteEnvVars('${MISSING_VAR}')).toBe('${MISSING_VAR}');
+  });
+
+  it('handles non-string primitives unchanged', () => {
+    expect(substituteEnvVars(42)).toBe(42);
+    expect(substituteEnvVars(true)).toBe(true);
+    expect(substituteEnvVars(null)).toBe(null);
+  });
+
+  it('deep-walks objects', () => {
+    process.env['SECRET'] = 'abc123';
+    const input = { nested: { key: '${SECRET}' }, plain: 'no-sub' };
+    expect(substituteEnvVars(input)).toEqual({
+      nested: { key: 'abc123' },
+      plain: 'no-sub',
+    });
+  });
+
+  it('deep-walks arrays', () => {
+    process.env['ITEM'] = 'resolved';
+    expect(substituteEnvVars(['${ITEM}', 'literal'])).toEqual([
+      'resolved',
+      'literal',
+    ]);
+  });
+
+  it('handles mixed nested structures', () => {
+    process.env['A'] = 'alpha';
+    const input = { list: [{ val: '${A}' }, '${A}'], num: 5 };
+    expect(substituteEnvVars(input)).toEqual({
+      list: [{ val: 'alpha' }, 'alpha'],
+      num: 5,
+    });
+  });
+});

package/src/config/substituteEnvVars.ts

@@ -0,0 +1,52 @@
+/**
+ * @packageDocumentation
+ *
+ * Deep-walks config objects and replaces `${VAR_NAME}` patterns with environment variable values.
+ * Ported from jeeves-watcher — candidate for hoisting to shared `@karmaniverous/jeeves-config`.
+ */
+
+const ENV_PATTERN = /\$\{([^}]+)\}/g;
+
+/**
+ * Replace `${VAR_NAME}` patterns in a string with `process.env.VAR_NAME`.
+ *
+ * @param value - The string to process.
+ * @returns The string with resolved env vars; unresolvable expressions left untouched.
+ */
+function substituteString(value: string): string {
+  return value.replace(ENV_PATTERN, (match, varName: string) => {
+    const envValue = process.env[varName];
+    if (envValue === undefined) return match;
+    return envValue;
+  });
+}
+
+/**
+ * Deep-walk a value and substitute `${VAR_NAME}` patterns in all string values.
+ *
+ * @param value - The value to walk (object, array, or primitive).
+ * @returns A new value with all env var references resolved.
+ */
+export function substituteEnvVars<T>(value: T): T {
+  if (typeof value === 'string') {
+    return substituteString(value) as T;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item: unknown) => substituteEnvVars(item)) as T;
+  }
+
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = substituteEnvVars(val);
+    }
+    return result as T;
+  }
+
+  return value;
+}

package/src/config/types.ts

@@ -0,0 +1,129 @@
+/**
+ * Runtime and internal types for Jeeves Server.
+ * Config types are derived from Zod schema in schema.ts.
+ */
+
+import type { AuthMode, JeevesConfig } from './schema.js';
+
+// Re-export config types from schema
+export type { AuthMode, JeevesConfig };
+
+/**
+ * Normalized scopes — always resolved to \{ allow, deny \} form.
+ * null = unrestricted access.
+ */
+export interface NormalizedScopes {
+  allow: string[];
+  deny: string[];
+}
+
+/**
+ * Resolved key seed with normalized scopes
+ */
+export interface ResolvedKey {
+  name: string;
+  seed: string;
+  scopes: NormalizedScopes | null;
+}
+
+/**
+ * Resolved insider with normalized scopes
+ */
+export interface ResolvedInsider {
+  email: string;
+  seed: string;
+  scopes: NormalizedScopes | null;
+  keyCreatedAt: string | null;
+}
+
+/**
+ * Combined runtime configuration (post-resolution)
+ */
+export interface RuntimeConfig {
+  port: number;
+  eventTimeoutMs: number;
+  eventLogPurgeMs: number;
+  maxZipSizeMb: number;
+  chromePath: string;
+  roots?: Record<string, string>;
+  mermaidCliPath?: string;
+  plantuml: {
+    jarPath?: string;
+    javaPath?: string;
+    servers: string[];
+  };
+  diagramCachePath?: string;
+  runnerUrl?: string;
+  watcherUrl?: string;
+  outsiderPolicy: NormalizedScopes | null;
+  events: JeevesConfig['events'];
+  authModes: AuthMode[];
+  resolvedKeys: ResolvedKey[];
+  resolvedInsiders: ResolvedInsider[];
+  googleAuth: { clientId: string; clientSecret: string } | null;
+  sessionSecret: string | null;
+  internalInsiderKey: string | null;
+  configPath: string;
+  eventsLog: string;
+  stateFile: string;
+  eventQueuePath: string;
+  eventQueueCursorPath: string;
+  eventLogPath: string;
+}
+
+/**
+ * Insider key state (auto-generated, persisted in state.json)
+ */
+export interface InsiderKeyState {
+  seed: string;
+  createdAt: string;
+}
+
+/**
+ * State file structure (mutable runtime state, separate from config)
+ */
+export interface ServerState {
+  keyRotatedAt?: string;
+  /** Auto-generated insider keys, keyed by email */
+  insiderKeys?: Record<string, InsiderKeyState>;
+}
+
+/**
+ * Access mode for authenticated requests
+ */
+export type AccessMode = 'insider' | 'outsider';
+
+/**
+ * Key verification result
+ */
+export interface KeyVerificationResult {
+  valid: boolean;
+  mode: AccessMode | null;
+  keyName: string | null;
+  seed: string | null;
+  /** For directory outsider links, the ancestor path the key matched against */
+  matchedPath: string | null;
+}
+
+/**
+ * Queue entry for event processing
+ */
+export interface QueueEntry {
+  ts: string;
+  event: string;
+  cmd: string;
+  body: Record<string, unknown>;
+  timeoutMs: number;
+}
+
+/**
+ * Event log entry
+ */
+export interface EventLogEntry {
+  ts: string;
+  event: string | null;
+  matched: boolean;
+  exitCode?: number;
+  durationMs?: number;
+  bodyPreview?: string;
+}

package/src/routes/api/auth-status.ts

@@ -0,0 +1,85 @@
+/**
+ * Auth status API route.
+ *
+ * Handles: /api/auth/status
+ */
+
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+
+import {
+  findInsider,
+  resolveKeyAuth,
+  resolveSessionAuth,
+} from '../../auth/resolve.js';
+import { getConfig } from '../../config/index.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const authStatusRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get(
+    '/api/auth/status',
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      const config = getConfig();
+
+      // Try session cookie first
+      const sessionResult = resolveSessionAuth(config, request);
+      if (sessionResult.valid) {
+        const insider = findInsider(
+          config.resolvedInsiders,
+          sessionResult.email!,
+        );
+        // Get picture from session cookie directly
+        const cookieValue = (
+          request.cookies as Record<string, string> | undefined
+        )?.['jeeves_session'];
+        let picture: string | undefined;
+        if (cookieValue) {
+          try {
+            const b64 = cookieValue.slice(0, cookieValue.lastIndexOf('.'));
+            const payload = JSON.parse(
+              Buffer.from(b64, 'base64url').toString(),
+            ) as { picture?: string };
+            picture = payload.picture;
+          } catch {
+            /* ignore */
+          }
+        }
+
+        return reply.send({
+          authenticated: true,
+          email: sessionResult.email,
+          picture,
+          isInsider: !!insider?.seed,
+          keyCreatedAt: insider?.keyCreatedAt ?? null,
+          searchEnabled: !!config.watcherUrl,
+        });
+      }
+
+      // Try key-based auth
+      if (config.authModes.includes('keys')) {
+        const query = request.query as Record<string, string | undefined>;
+        const deepParams =
+          query.d !== undefined && query.s !== undefined
+            ? { d: query.d, dirs: query.dirs ?? '0', s: query.s }
+            : undefined;
+
+        const keyResult = resolveKeyAuth(
+          config,
+          query.path ?? '/',
+          query.key,
+          query.exp,
+          deepParams,
+        );
+        if (keyResult.valid) {
+          return reply.send({
+            authenticated: true,
+            email: `key:${String(keyResult.keyName)}`,
+            isInsider: keyResult.mode === 'insider',
+            keyCreatedAt: null,
+          });
+        }
+      }
+
+      return reply.send({ authenticated: false, isInsider: false });
+    },
+  );
+};