@karmaniverous/jeeves-server 3.0.0-0 → 3.0.0

package/dist/src/routes/keys.js

@@ -53,7 +53,7 @@ export const keysRoute = async (fastify) => {
             const insiderResult = resolveInsiderKeyAuth(config, provided);
             if (insiderResult.valid && insiderResult.email) {
                 // Insider key rotation
-                return rotateInsiderSeed(insiderResult.email, config);
+                return await rotateInsiderSeed(insiderResult.email, config);
             }
             // Machine key rotation is not supported with TS config
             const matched = config.resolvedKeys.find((rk) => timingSafeEqual(provided, computeInsiderKey(rk.seed)));
@@ -67,7 +67,7 @@ export const keysRoute = async (fastify) => {
         // Try session-based auth
         const sessionResult = resolveSessionAuth(config, request);
         if (sessionResult.valid && sessionResult.email) {
-            return rotateInsiderSeed(sessionResult.email, config);
+            return await rotateInsiderSeed(sessionResult.email, config);
         }
         return reply.code(401).send({ error: 'Invalid insider key' });
     });
@@ -93,7 +93,7 @@ export const keysRoute = async (fastify) => {
         return reply.code(401).send({ error: 'Invalid insider key' });
     });
 };
-function rotateInsiderSeed(email, config) {
+async function rotateInsiderSeed(email, config) {
     const insider = findInsider(config.resolvedInsiders, email);
     if (!insider?.seed)
         return { ok: false, error: 'Insider not found' };
@@ -106,7 +106,7 @@ function rotateInsiderSeed(email, config) {
         at: timestamp,
     });
     setKeyRotationTimestamp(timestamp);
-    resetConfig();
+    await resetConfig();
     return { ok: true, keyName: insider.email };
 }
 function buildShareResponse(seed, targetPath, expiry) {

package/dist/src/services/deepShareLinks.js

@@ -33,14 +33,14 @@ export function encodeStack(stack) {
 /**
  * Compute the remaining depth for a given stack.
  */
-export function remainingDepth(maxDepth, stack) {
+function remainingDepth(maxDepth, stack) {
     return maxDepth - (stack.length - 1);
 }
 /**
  * Compute a sub-link URL for an outgoing link target.
  * Returns null if the link should be stripped (depth exhausted or type not allowed).
  */
-export function computeSubLink(seed, targetUrlPath, currentStack, maxDepth, dirs, exp, isDirectory) {
+function computeSubLink(seed, targetUrlPath, currentStack, maxDepth, dirs, exp, isDirectory) {
     // Check if directories are allowed
     if (isDirectory && !dirs)
         return null;

package/dist/src/services/diagramCache.js

@@ -33,7 +33,7 @@ function cacheKey(type, source) {
  * Look up a cached diagram. Returns the content as a string or null on miss.
  * @param format - Output format extension (e.g. 'svg', 'png', 'pdf'). Defaults to 'svg'.
  */
-export function getCachedDiagram(type, source, format = 'svg') {
+function getCachedDiagram(type, source, format = 'svg') {
     if (!cacheDir)
         return null;
     const file = path.join(cacheDir, `${cacheKey(type, source)}.${format}`);
@@ -63,7 +63,7 @@ export function getCachedDiagramBuffer(type, source, format) {
  * Store a rendered diagram in the cache (string content).
  * @param format - Output format extension. Defaults to 'svg'.
  */
-export function cacheDiagram(type, source, content, format = 'svg') {
+function cacheDiagram(type, source, content, format = 'svg') {
     if (!cacheDir)
         return;
     const file = path.join(cacheDir, `${cacheKey(type, source)}.${format}`);

package/dist/src/services/embeddedDiagrams.js

@@ -40,7 +40,7 @@ function startCleanup() {
 /**
  * Compute content hash matching the cache key format.
  */
-export function diagramHash(type, source) {
+function diagramHash(type, source) {
     return crypto.createHash('sha256').update(`${type}\0${source}`).digest('hex');
 }
 /** Module-level context directory for the current markdown parse. */

package/dist/src/services/export.js

@@ -12,7 +12,7 @@ const MAX_HEIGHT_PX = 768;
 /**
  * Export page as PDF.
  */
-export async function exportPDF(options) {
+async function exportPDF(options) {
     const browser = await launchBrowser();
     try {
         const page = await browser.newPage();
@@ -33,7 +33,7 @@ export async function exportPDF(options) {
 /**
  * Export page as DOCX.
  */
-export async function exportDOCX(options) {
+async function exportDOCX(options) {
     const browser = await launchBrowser();
     try {
         const page = await browser.newPage();

package/dist/src/util/state.js

@@ -6,7 +6,7 @@ import { getConfig } from '../config/index.js';
 /**
  * Load state from file
  */
-export function loadState() {
+function loadState() {
     const { stateFile } = getConfig();
     try {
         if (fs.existsSync(stateFile)) {
@@ -22,7 +22,7 @@ export function loadState() {
 /**
  * Save state to file
  */
-export function saveState(state) {
+function saveState(state) {
     const { stateFile } = getConfig();
     fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
 }

package/knip.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://unpkg.com/knip@latest/schema.json",
+  "entry": [
+    "src/cli/index.ts"
+  ],
+  "project": [
+    "src/**/*.ts"
+  ],
+  "ignoreBinaries": [
+    "tsx",
+    "rimraf",
+    "tsc",
+    "cross-env",
+    "vitest",
+    "auto-changelog",
+    "dotenvx",
+    "release-it",
+    "eslint",
+    "knip"
+  ],
+  "ignoreDependencies": [
+    "puppeteer",
+    "@dotenvx/dotenvx",
+    "auto-changelog",
+    "cross-env",
+    "release-it",
+    "rimraf"
+  ],
+  "ignoreExportsUsedInFile": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-server",
-  "version": "3.0.0-0",
+  "version": "3.0.0",
   "description": "Secure file browser, markdown viewer, and webhook gateway with PDF/DOCX export and expiring share links",
   "keywords": [
     "fastify",

package/src/auth/google.ts

@@ -7,7 +7,7 @@ const GOOGLE_AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
 const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const GOOGLE_USERINFO_URL = 'https://openidconnect.googleapis.com/v1/userinfo';
 
-export interface GoogleTokens {
+interface GoogleTokens {
   access_token: string;
   id_token?: string;
   refresh_token?: string;
@@ -15,7 +15,7 @@ export interface GoogleTokens {
   token_type: string;
 }
 
-export interface GoogleUserInfo {
+interface GoogleUserInfo {
   sub: string;
   email: string;
   email_verified: boolean;

package/src/auth/resolve.ts

@@ -19,7 +19,7 @@ import { formatRelativeTime } from '../util/formatters.js';
 import { verifyKey } from './keys.js';
 import { COOKIE_NAME, verifySessionCookie } from './session.js';
 
-export interface AuthResult {
+interface AuthResult {
   valid: boolean;
   mode?: AccessMode;
   seed?: string;

package/src/auth/session.ts

@@ -10,7 +10,7 @@ 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 {
+interface SessionPayload {
   email: string;
   picture?: string;
   exp: number;

package/src/config/index.ts

@@ -75,6 +75,7 @@ export async function loadConfig(configPath?: string): Promise<RuntimeConfig> {
 }
 
 let configInstance: RuntimeConfig | null = null;
+let lastConfigPath: string | undefined;
 
 /**
  * Check if the config singleton has been initialized.
@@ -101,13 +102,22 @@ export function getConfig(): RuntimeConfig {
  * @param configPath - Optional explicit path to a config file.
  */
 export async function initConfig(configPath?: string): Promise<RuntimeConfig> {
+  lastConfigPath = configPath;
   configInstance = await loadConfig(configPath);
   return configInstance;
 }
 
 /**
- * Reset the config singleton (for testing).
+ * Reload the config singleton from the last-used config path.
+ * Call after mutating state that affects resolved config (e.g., key rotation).
  */
-export function resetConfig(): void {
+export async function resetConfig(): Promise<void> {
+  configInstance = await loadConfig(lastConfigPath);
+}
+
+/**
+ * Clear the config singleton (for testing only).
+ */
+export function clearConfig(): void {
   configInstance = null;
 }

package/src/config/loadConfig.test.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
-import { getConfig, initConfig, loadConfig, resetConfig } from './index.js';
+import { clearConfig, getConfig, initConfig, loadConfig } from './index.js';
 
 const VALID_CONFIG = {
   port: 9999,
@@ -28,12 +28,12 @@ describe('loadConfig', () => {
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
-    resetConfig();
+    clearConfig();
   });
 
   afterEach(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
-    resetConfig();
+    clearConfig();
   });
 
   it('loads a valid JSON config file', async () => {
@@ -120,6 +120,35 @@ describe('loadConfig', () => {
       'c'.repeat(64),
     );
   });
+
+  it('rejects undefined named scope references', async () => {
+    const configPath = writeConfig(tmpDir, {
+      ...VALID_CONFIG,
+      scopes: { restricted: { allow: ['/**'], deny: ['/secret'] } },
+      insiders: {
+        'a@example.com': { scopes: 'restricted' },
+        'b@example.com': { scopes: 'missing' },
+      },
+    });
+
+    await expect(loadConfig(configPath)).rejects.toThrow(
+      'Scope "missing" is not defined',
+    );
+  });
+
+  it('does not treat path globs as named scope references', async () => {
+    const configPath = writeConfig(tmpDir, {
+      ...VALID_CONFIG,
+      insiders: {
+        'a@example.com': { scopes: ['/docs/**'] },
+      },
+    });
+
+    const config = await loadConfig(configPath);
+    expect(
+      config.resolvedInsiders.find((i) => i.email === 'a@example.com')?.scopes,
+    ).toEqual({ allow: ['/docs/**'], deny: [] });
+  });
 });
 
 describe('config singleton', () => {
@@ -127,12 +156,12 @@ describe('config singleton', () => {
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
-    resetConfig();
+    clearConfig();
   });
 
   afterEach(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
-    resetConfig();
+    clearConfig();
   });
 
   it('throws if getConfig called before initConfig', () => {
@@ -146,10 +175,10 @@ describe('config singleton', () => {
     expect(config.port).toBe(9999);
   });
 
-  it('resetConfig clears the singleton', async () => {
+  it('clearConfig clears the singleton', async () => {
     const configPath = writeConfig(tmpDir, VALID_CONFIG);
     await initConfig(configPath);
-    resetConfig();
+    clearConfig();
     expect(() => getConfig()).toThrow('Config not initialized');
   });
 });

package/src/config/resolve.test.ts

@@ -10,6 +10,7 @@ import {
   normalizeScopes,
   resolveInsiders,
   resolveKeys,
+  resolveNamedScopes,
   resolvePlantuml,
 } from './resolve.js';
 import type { JeevesConfig } from './schema.js';
@@ -49,26 +50,32 @@ describe('normalizeScopes', () => {
 
 describe('resolveKeys', () => {
   it('handles string key entries', () => {
-    const result = resolveKeys({ primary: 'seed123' });
+    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'] },
-    });
+    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'] } },
-    });
+    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'] });
@@ -88,7 +95,7 @@ describe('resolveInsiders', () => {
 
   it('normalizes email to lowercase', () => {
     const stateFile = path.join(tmpDir, 'state.json');
-    const result = resolveInsiders({ 'Test@Example.COM': {} }, stateFile);
+    const result = resolveInsiders({ 'Test@Example.COM': {} }, {}, stateFile);
     expect(result[0].email).toBe('test@example.com');
   });
 
@@ -102,19 +109,53 @@ describe('resolveInsiders', () => {
         },
       }),
     );
-    const result = resolveInsiders({ 'test@example.com': {} }, stateFile);
+    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);
+    const result = resolveInsiders({ 'new@example.com': {} }, {}, stateFile);
     expect(result[0].seed).toBe('');
     expect(result[0].keyCreatedAt).toBe(null);
   });
 });
 
+describe('resolveNamedScopes', () => {
+  it('resolves a single named scope', () => {
+    const named = { restricted: { allow: ['/**'], deny: ['/secret'] } };
+    expect(resolveNamedScopes(named, 'restricted')).toEqual({
+      allow: ['/**'],
+      deny: ['/secret'],
+    });
+  });
+
+  it('unions multiple named scopes and merges overrides', () => {
+    const named = {
+      restricted: { allow: ['/**'], deny: ['/secret'] },
+      noVc: { deny: ['/vc/**'] },
+    };
+    expect(
+      resolveNamedScopes(named, ['restricted', 'noVc'], {
+        allow: ['/extra'],
+        deny: ['/more'],
+      }),
+    ).toEqual({
+      allow: ['/**', '/extra'],
+      deny: ['/secret', '/vc/**', '/more'],
+    });
+  });
+
+  it('falls back to legacy inline scope strings', () => {
+    const named = { restricted: { allow: ['/**'] } };
+    expect(resolveNamedScopes(named, '/docs')).toEqual({
+      allow: ['/docs'],
+      deny: [],
+    });
+  });
+});
+
 describe('resolvePlantuml', () => {
   it('appends community server as fallback', () => {
     const result = resolvePlantuml();
@@ -170,6 +211,7 @@ describe('buildRuntimeConfig', () => {
       eventLogPurgeMs: 2592000000,
       maxZipSizeMb: 100,
       chromePath: '/usr/bin/chrome',
+      scopes: {},
       events: {},
       auth: { modes: ['keys' as const] },
       keys: { primary: 'a'.repeat(64) },

package/src/config/resolve.ts

@@ -39,17 +39,92 @@ export function normalizeScopes(raw: unknown): NormalizedScopes | null {
   return null;
 }
 
+/**
+ * Resolve named scope references (string or string[]) against the top-level scopes map,
+ * optionally merging explicit allow/deny overrides.
+ *
+ * Returns null if no scopes are provided.
+ * Falls back to normalizeScopes() for legacy inline scope formats.
+ */
+export function resolveNamedScopes(
+  named: Record<string, { allow?: string[]; deny?: string[] } | undefined>,
+  rawScopes: unknown,
+  overrides?: { allow?: string[]; deny?: string[] },
+): NormalizedScopes | null {
+  if (rawScopes === undefined || rawScopes === null) {
+    if (overrides?.allow?.length || overrides?.deny?.length) {
+      return {
+        allow: overrides.allow ?? ['/**'],
+        deny: overrides.deny ?? [],
+      };
+    }
+    return null;
+  }
+
+  // Determine whether rawScopes is a named reference (identifier(s))
+  const isName = (v: string): boolean => /^[A-Za-z0-9_-]+$/.test(v);
+
+  const refs =
+    typeof rawScopes === 'string'
+      ? isName(rawScopes)
+        ? [rawScopes]
+        : null
+      : Array.isArray(rawScopes) &&
+          rawScopes.every((v) => typeof v === 'string')
+        ? rawScopes.filter((v) => isName(v))
+        : null;
+
+  if (refs && refs.length > 0) {
+    const allow: string[] = [];
+    const deny: string[] = [];
+
+    for (const ref of refs) {
+      const scope = named[ref];
+      if (!scope) continue; // schema should have validated
+      if (scope.allow) allow.push(...scope.allow);
+      if (scope.deny) deny.push(...scope.deny);
+    }
+
+    if (overrides?.allow) allow.push(...overrides.allow);
+    if (overrides?.deny) deny.push(...overrides.deny);
+
+    return {
+      allow: allow.length > 0 ? allow : ['/**'],
+      deny,
+    };
+  }
+
+  // Legacy inline scopes
+  const normalized = normalizeScopes(rawScopes);
+  if (!normalized) return null;
+  if (overrides?.allow) normalized.allow.push(...overrides.allow);
+  if (overrides?.deny) normalized.deny.push(...overrides.deny);
+  return normalized;
+}
+
 /**
  * Resolve raw key entries to ResolvedKey[].
  */
 export function resolveKeys(
-  keys: Record<string, string | { key: string; scopes?: unknown }>,
+  keys: Record<
+    string,
+    | string
+    | { key: string; scopes?: unknown; allow?: string[]; deny?: string[] }
+  >,
+  namedScopes: Record<string, { allow?: string[]; deny?: string[] }>,
 ): 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) };
+    return {
+      name,
+      seed: entry.key,
+      scopes: resolveNamedScopes(namedScopes, entry.scopes, {
+        allow: entry.allow,
+        deny: entry.deny,
+      }),
+    };
   });
 }
 
@@ -57,7 +132,11 @@ export function resolveKeys(
  * Resolve insider entries by merging config (identity + scopes) with state (keys).
  */
 export function resolveInsiders(
-  insiders: Record<string, { scopes?: unknown }>,
+  insiders: Record<
+    string,
+    { scopes?: unknown; allow?: string[]; deny?: string[] }
+  >,
+  namedScopes: Record<string, { allow?: string[]; deny?: string[] }>,
   stateFile: string,
 ): ResolvedInsider[] {
   let serverState: ServerState = {};
@@ -73,7 +152,10 @@ export function resolveInsiders(
 
   return Object.entries(insiders).map(([rawEmail, entry]) => {
     const email = rawEmail.toLowerCase();
-    const scopes = normalizeScopes(entry.scopes);
+    const scopes = resolveNamedScopes(namedScopes, entry.scopes, {
+      allow: entry.allow,
+      deny: entry.deny,
+    });
     const stateKey = serverState.insiderKeys?.[email];
     return {
       email,
@@ -135,10 +217,19 @@ export function buildRuntimeConfig(
   const stateFile = path.join(rootDir, 'state.json');
 
   const resolvedKeys = resolveKeys(
-    config.keys as Record<string, string | { key: string; scopes?: unknown }>,
+    config.keys as Record<
+      string,
+      | string
+      | { key: string; scopes?: unknown; allow?: string[]; deny?: string[] }
+    >,
+    config.scopes as Record<string, { allow?: string[]; deny?: string[] }>,
   );
   const resolvedInsiders = resolveInsiders(
-    config.insiders as Record<string, { scopes?: unknown }>,
+    config.insiders as Record<
+      string,
+      { scopes?: unknown; allow?: string[]; deny?: string[] }
+    >,
+    config.scopes as Record<string, { allow?: string[]; deny?: string[] }>,
     stateFile,
   );
 
@@ -152,7 +243,24 @@ export function buildRuntimeConfig(
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     mermaidCliPath: config.mermaidCliPath,
     plantuml: resolvePlantuml(config.plantuml, rootDir),
-    outsiderPolicy: normalizeScopes(config.outsiderPolicy) ?? null,
+    outsiderPolicy:
+      resolveNamedScopes(
+        config.scopes as Record<string, { allow?: string[]; deny?: string[] }>,
+        (config.outsiderPolicy as unknown) &&
+          typeof config.outsiderPolicy === 'object' &&
+          !Array.isArray(config.outsiderPolicy)
+          ? ((config.outsiderPolicy as { scopes?: unknown }).scopes ??
+              config.outsiderPolicy)
+          : config.outsiderPolicy,
+        (config.outsiderPolicy as unknown) &&
+          typeof config.outsiderPolicy === 'object' &&
+          !Array.isArray(config.outsiderPolicy)
+          ? {
+              allow: (config.outsiderPolicy as { allow?: string[] }).allow,
+              deny: (config.outsiderPolicy as { deny?: string[] }).deny,
+            }
+          : undefined,
+      ) ?? null,
     events: config.events,
     authModes: config.auth.modes,
     resolvedKeys,