@karmaniverous/jeeves-server 3.0.0-0

package/dist/src/config/resolve.js

@@ -0,0 +1,134 @@
+/**
+ * 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';
+/**
+ * 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) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === 'string')
+        return { allow: [raw], deny: [] };
+    if (Array.isArray(raw))
+        return { allow: raw, deny: [] };
+    if (typeof raw === 'object') {
+        const obj = raw;
+        return {
+            allow: obj.allow ?? ['/**'],
+            deny: obj.deny ?? [],
+        };
+    }
+    return null;
+}
+/**
+ * Resolve raw key entries to ResolvedKey[].
+ */
+export function resolveKeys(keys) {
+    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, stateFile) {
+    let serverState = {};
+    try {
+        if (fs.existsSync(stateFile)) {
+            serverState = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+        }
+    }
+    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, rootDir) {
+    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) {
+    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, rootDir, configPath) {
+    const stateFile = path.join(rootDir, 'state.json');
+    const resolvedKeys = resolveKeys(config.keys);
+    const resolvedInsiders = resolveInsiders(config.insiders, 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/dist/src/config/resolve.test.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildRuntimeConfig, deriveInternalKey, normalizeScopes, resolveInsiders, resolveKeys, resolvePlantuml, } from './resolve.js';
+describe('normalizeScopes', () => {
+    it('returns null for undefined', () => {
+        expect(normalizeScopes(undefined)).toBe(null);
+    });
+    it('returns null for null', () => {
+        expect(normalizeScopes(null)).toBe(null);
+    });
+    it('wraps a string in allow array', () => {
+        expect(normalizeScopes('/docs')).toEqual({ allow: ['/docs'], deny: [] });
+    });
+    it('wraps an array as allow', () => {
+        expect(normalizeScopes(['/a', '/b'])).toEqual({
+            allow: ['/a', '/b'],
+            deny: [],
+        });
+    });
+    it('fills defaults for partial object', () => {
+        expect(normalizeScopes({ deny: ['/secret'] })).toEqual({
+            allow: ['/**'],
+            deny: ['/secret'],
+        });
+    });
+    it('passes through complete object', () => {
+        const scopes = { allow: ['/a'], deny: ['/b'] };
+        expect(normalizeScopes(scopes)).toEqual(scopes);
+    });
+});
+describe('resolveKeys', () => {
+    it('handles string key entries', () => {
+        const result = resolveKeys({ primary: 'seed123' });
+        expect(result).toEqual([
+            { name: 'primary', seed: 'seed123', scopes: null },
+        ]);
+    });
+    it('handles object key entries with scopes', () => {
+        const result = resolveKeys({
+            scoped: { key: 'seed456', scopes: ['/docs'] },
+        });
+        expect(result[0].name).toBe('scoped');
+        expect(result[0].seed).toBe('seed456');
+        expect(result[0].scopes).toEqual({ allow: ['/docs'], deny: [] });
+    });
+    it('handles mixed entries', () => {
+        const result = resolveKeys({
+            plain: 'abc',
+            complex: { key: 'def', scopes: { allow: ['/x'], deny: ['/y'] } },
+        });
+        expect(result).toHaveLength(2);
+        expect(result[0].scopes).toBe(null);
+        expect(result[1].scopes).toEqual({ allow: ['/x'], deny: ['/y'] });
+    });
+});
+describe('resolveInsiders', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-resolve-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('normalizes email to lowercase', () => {
+        const stateFile = path.join(tmpDir, 'state.json');
+        const result = resolveInsiders({ 'Test@Example.COM': {} }, stateFile);
+        expect(result[0].email).toBe('test@example.com');
+    });
+    it('merges state keys when available', () => {
+        const stateFile = path.join(tmpDir, 'state.json');
+        fs.writeFileSync(stateFile, JSON.stringify({
+            insiderKeys: {
+                'test@example.com': { seed: 'stateseed', createdAt: '2026-01-01' },
+            },
+        }));
+        const result = resolveInsiders({ 'test@example.com': {} }, stateFile);
+        expect(result[0].seed).toBe('stateseed');
+        expect(result[0].keyCreatedAt).toBe('2026-01-01');
+    });
+    it('returns empty seed when no state exists', () => {
+        const stateFile = path.join(tmpDir, 'state.json');
+        const result = resolveInsiders({ 'new@example.com': {} }, stateFile);
+        expect(result[0].seed).toBe('');
+        expect(result[0].keyCreatedAt).toBe(null);
+    });
+});
+describe('resolvePlantuml', () => {
+    it('appends community server as fallback', () => {
+        const result = resolvePlantuml();
+        expect(result.servers).toContain('https://www.plantuml.com/plantuml');
+    });
+    it('does not duplicate community server if already listed', () => {
+        const result = resolvePlantuml({
+            servers: ['https://www.plantuml.com/plantuml'],
+        });
+        expect(result.servers.filter((s) => s === 'https://www.plantuml.com/plantuml')).toHaveLength(1);
+    });
+    it('preserves configured servers before community', () => {
+        const result = resolvePlantuml({
+            servers: ['https://private.example.com'],
+        });
+        expect(result.servers[0]).toBe('https://private.example.com');
+        expect(result.servers[1]).toBe('https://www.plantuml.com/plantuml');
+    });
+    it('passes through jarPath and javaPath', () => {
+        const result = resolvePlantuml({
+            jarPath: '/opt/plantuml.jar',
+            javaPath: '/usr/bin/java',
+        });
+        expect(result.jarPath).toBe('/opt/plantuml.jar');
+        expect(result.javaPath).toBe('/usr/bin/java');
+    });
+});
+describe('deriveInternalKey', () => {
+    it('returns null when no _internal key exists', () => {
+        const keys = [{ name: 'primary', seed: 'abc', scopes: null }];
+        expect(deriveInternalKey(keys)).toBe(null);
+    });
+    it('derives a key from _internal seed', () => {
+        const keys = [{ name: '_internal', seed: 'x'.repeat(64), scopes: null }];
+        const result = deriveInternalKey(keys);
+        expect(result).toBeTypeOf('string');
+        expect(result.length).toBeGreaterThan(0);
+    });
+});
+describe('buildRuntimeConfig', () => {
+    it('constructs correct path fields', () => {
+        const config = {
+            port: 1934,
+            eventTimeoutMs: 30000,
+            eventLogPurgeMs: 2592000000,
+            maxZipSizeMb: 100,
+            chromePath: '/usr/bin/chrome',
+            events: {},
+            auth: { modes: ['keys'] },
+            keys: { primary: 'a'.repeat(64) },
+            insiders: {},
+        };
+        const result = buildRuntimeConfig(config, '/srv/jeeves', '/srv/jeeves/config.json');
+        expect(result.stateFile).toBe(path.join('/srv/jeeves', 'state.json'));
+        expect(result.eventsLog).toBe(path.join('/srv/jeeves', 'logs', 'webhook-events.jsonl'));
+        expect(result.configPath).toBe('/srv/jeeves/config.json');
+        expect(result.port).toBe(1934);
+        expect(result.authModes).toEqual(['keys']);
+    });
+});

package/dist/src/config/schema.js

@@ -0,0 +1,159 @@
+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']) {
+        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],
+            });
+        }
+    }
+});

package/dist/src/config/substituteEnvVars.js

@@ -0,0 +1,45 @@
+/**
+ * @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) {
+    return value.replace(ENV_PATTERN, (match, varName) => {
+        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(value) {
+    if (typeof value === 'string') {
+        return substituteString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => substituteEnvVars(item));
+    }
+    if (value !== null &&
+        typeof value === 'object' &&
+        Object.getPrototypeOf(value) === Object.prototype) {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = substituteEnvVars(val);
+        }
+        return result;
+    }
+    return value;
+}

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

@@ -0,0 +1,51 @@
+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/dist/src/config/types.js

@@ -0,0 +1,5 @@
+/**
+ * Runtime and internal types for Jeeves Server.
+ * Config types are derived from Zod schema in schema.ts.
+ */
+export {};

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

@@ -0,0 +1,56 @@
+/**
+ * Auth status API route.
+ *
+ * Handles: /api/auth/status
+ */
+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 = async (fastify) => {
+    fastify.get('/api/auth/status', async (request, reply) => {
+        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?.['jeeves_session'];
+            let picture;
+            if (cookieValue) {
+                try {
+                    const b64 = cookieValue.slice(0, cookieValue.lastIndexOf('.'));
+                    const payload = JSON.parse(Buffer.from(b64, 'base64url').toString());
+                    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;
+            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 });
+    });
+};

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

@@ -0,0 +1,35 @@
+/**
+ * Diagram rendering API route.
+ *
+ * Handles: /api/diagram/:type/:hash
+ */
+import { getDiagramSource, renderDiagramToSvg, } from '../../services/embeddedDiagrams.js';
+// eslint-disable-next-line @typescript-eslint/require-await
+export const diagramsRoutes = async (fastify) => {
+    fastify.get('/api/diagram/:type/:hash', async (request, reply) => {
+        const { type, hash: hashWithExt } = request.params;
+        const hash = hashWithExt.replace(/\.svg$/, '');
+        if (!['mermaid', 'plantuml'].includes(type)) {
+            return reply.code(400).send({ error: 'Invalid diagram type' });
+        }
+        if (!/^[a-f0-9]{64}$/.test(hash)) {
+            return reply.code(400).send({ error: 'Invalid hash' });
+        }
+        const entry = getDiagramSource(hash);
+        if (!entry) {
+            return reply
+                .code(404)
+                .send({ error: 'Diagram source not found (may have expired)' });
+        }
+        const svg = await renderDiagramToSvg(type, entry.source, entry.contextDir);
+        if (!svg) {
+            return reply
+                .code(500)
+                .send({ error: 'Renderer returned empty result' });
+        }
+        return reply
+            .header('Content-Type', 'image/svg+xml')
+            .header('Cache-Control', 'public, max-age=86400, immutable')
+            .send(svg);
+    });
+};