@karmaniverous/jeeves-server-core 0.1.4 → 0.1.6

package/README.md

@@ -14,6 +14,21 @@ Shared workspace package providing cryptographic utilities and API types consume
 | `computeDeepShareKey(seed, path, params)` | HMAC-SHA256 key for deep directory shares with depth/dirs/stack/expiry |
 | `timingSafeEqual(a, b)` | Constant-time string comparison to prevent timing attacks |
 
+### Config Schema
+
+| Export | Description |
+|--------|-------------|
+| `loggingConfigSchema` | Zod schema for `logging` config block (`level`, `file`, both optional) |
+| `LoggingConfig` | Inferred TypeScript type from `loggingConfigSchema` |
+| `jeevesConfigSchema` | Full server config Zod schema (includes `logging`, `oauth`, all other fields) |
+
+### Endpoint Catalog
+
+| Export | Description |
+|--------|-------------|
+| `EndpointEntry` | Interface describing a single API operation (method, path, description, auth flags) |
+| `serverEndpoints` | Complete declarative catalog of all jeeves-server API endpoints (38 entries) |
+
 ### API Types
 
 | Type | Description |
@@ -36,6 +51,9 @@ Shared workspace package providing cryptographic utilities and API types consume
 import {
   computeInsiderKey,
   computePathKey,
+  serverEndpoints,
+  type EndpointEntry,
+  type LoggingConfig,
   type ShareRequest,
 } from '@karmaniverous/jeeves-server-core';
 ```

package/dist/src/endpoints.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Declarative endpoint catalog — single source of truth for the jeeves-server
+ * API surface. Consumers (CLI, OpenClaw plugin) derive their registrations
+ * from this catalog.
+ *
+ * @packageDocumentation
+ */
+import type { z } from 'zod';
+/**
+ * Describes a single API operation.
+ */
+export interface EndpointEntry {
+    /** HTTP method. */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** URL path pattern (Fastify-style, e.g. '/api/file/*'). */
+    path: string;
+    /** Human-readable operation description. */
+    description: string;
+    /** Zod schema for query params (GET) or request body (POST/PUT). */
+    params?: z.ZodType;
+    /** Zod schema for the response body. */
+    response?: z.ZodType;
+    /** Whether the endpoint requires insider auth. */
+    insiderOnly?: boolean;
+    /** Whether the endpoint is unauthenticated. */
+    unauthenticated?: boolean;
+}
+/**
+ * Complete API endpoint catalog for jeeves-server.
+ *
+ * Keys are stable operation identifiers used by consumers to reference
+ * specific endpoints. Values describe the HTTP operation.
+ */
+export declare const serverEndpoints: Record<string, EndpointEntry>;

package/dist/src/endpoints.js

@@ -0,0 +1,235 @@
+/**
+ * Declarative endpoint catalog — single source of truth for the jeeves-server
+ * API surface. Consumers (CLI, OpenClaw plugin) derive their registrations
+ * from this catalog.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Complete API endpoint catalog for jeeves-server.
+ *
+ * Keys are stable operation identifiers used by consumers to reference
+ * specific endpoints. Values describe the HTTP operation.
+ */
+const serverEndpoints = {
+    // --- Status & Config ---
+    status: {
+        method: 'GET',
+        path: '/status',
+        description: 'Server health: name, version, uptime, status, health details.',
+        unauthenticated: true,
+    },
+    config: {
+        method: 'GET',
+        path: '/config',
+        description: 'Query running config with optional JSONPath filter (?path=).',
+        unauthenticated: true,
+    },
+    'config-apply': {
+        method: 'POST',
+        path: '/config/apply',
+        description: 'Push config patch to running service (deep-merge + validate + reload).',
+        insiderOnly: true,
+    },
+    // --- Authentication ---
+    'auth-status': {
+        method: 'GET',
+        path: '/api/auth/status',
+        description: 'Check current authentication status (no auth required).',
+        unauthenticated: true,
+    },
+    'auth-login': {
+        method: 'GET',
+        path: '/auth/login',
+        description: 'Redirect to Google OAuth consent screen.',
+        unauthenticated: true,
+    },
+    'auth-callback': {
+        method: 'GET',
+        path: '/auth/callback',
+        description: 'Handle Google OAuth callback, set session cookie.',
+        unauthenticated: true,
+    },
+    'auth-logout': {
+        method: 'GET',
+        path: '/auth/logout',
+        description: 'Clear session cookie.',
+        unauthenticated: true,
+    },
+    // --- File Browser ---
+    drives: {
+        method: 'GET',
+        path: '/api/drives',
+        description: 'List available root drives/labels configured on the server.',
+    },
+    path: {
+        method: 'GET',
+        path: '/api/path/*',
+        description: 'Get directory listing for a path.',
+    },
+    'file-get': {
+        method: 'GET',
+        path: '/api/file/*',
+        description: 'Get file content with type-specific handling (markdown, csv, diagrams, etc.).',
+    },
+    'file-put': {
+        method: 'PUT',
+        path: '/api/file/*',
+        description: 'Overwrite file content (insider-only; file must already exist).',
+        insiderOnly: true,
+    },
+    'file-mutate': {
+        method: 'POST',
+        path: '/api/file/*',
+        description: 'Apply structured .md mutations: edit-block, delete-block, insert-block, edit-cell, toggle-checkbox.',
+        insiderOnly: true,
+    },
+    raw: {
+        method: 'GET',
+        path: '/api/raw/*',
+        description: 'Direct file download with appropriate content type.',
+    },
+    // --- Export ---
+    export: {
+        method: 'GET',
+        path: '/api/export/*',
+        description: 'Trigger export (PDF, DOCX, ZIP) and return download.',
+    },
+    'export-cache-clear': {
+        method: 'DELETE',
+        path: '/api/export-cache/*',
+        description: 'Clear export and diagram caches for a given path.',
+        insiderOnly: true,
+    },
+    'mermaid-export': {
+        method: 'GET',
+        path: '/api/mermaid-export/*',
+        description: 'Export Mermaid diagram (svg, png, pdf).',
+    },
+    'plantuml-export': {
+        method: 'GET',
+        path: '/api/plantuml-export/*',
+        description: 'Export PlantUML diagram (svg, png, pdf, eps).',
+    },
+    // --- Diagrams ---
+    diagram: {
+        method: 'GET',
+        path: '/api/diagram/:type/:hash',
+        description: 'Fetch rendered diagram by type and content hash.',
+        unauthenticated: true,
+    },
+    // --- Sharing ---
+    share: {
+        method: 'POST',
+        path: '/api/share',
+        description: 'Generate HMAC-signed share link for a path.',
+        insiderOnly: true,
+    },
+    'share-for': {
+        method: 'POST',
+        path: '/api/util/share-for',
+        description: 'Generate share link targeting specific insiders with configurable expiry/depth.',
+        insiderOnly: true,
+    },
+    'readme-link': {
+        method: 'GET',
+        path: '/api/readme-link',
+        description: 'Pre-computed share link for the first README.md in the directory hierarchy.',
+        unauthenticated: true,
+    },
+    'content-link': {
+        method: 'GET',
+        path: '/api/content-link/:file',
+        description: 'Pre-computed deep share URL for pinned content files (privacy, terms).',
+        unauthenticated: true,
+    },
+    'link-info': {
+        method: 'GET',
+        path: '/api/link-info/*',
+        description: 'Query available link types for a path (page, raw, PDF, DOCX, etc.).',
+    },
+    'rotate-key': {
+        method: 'POST',
+        path: '/api/rotate-key',
+        description: 'Rotate the authenticated insider API key (invalidates all existing share links).',
+        insiderOnly: true,
+    },
+    // --- Events ---
+    event: {
+        method: 'POST',
+        path: '/event',
+        description: 'Event gateway webhook receiver (scoped key auth).',
+    },
+    events: {
+        method: 'GET',
+        path: '/api/events',
+        description: 'Query recent event log entries (limit capped at 100).',
+    },
+    // --- Search ---
+    search: {
+        method: 'POST',
+        path: '/api/search',
+        description: 'Semantic search (proxied to watcher).',
+    },
+    'search-facets': {
+        method: 'GET',
+        path: '/api/search/facets',
+        description: 'Search facet metadata (proxied to watcher).',
+    },
+    // --- Runner ---
+    runner: {
+        method: 'GET',
+        path: '/api/runner/*',
+        description: 'Runner API proxy (proxied to jeeves-runner).',
+    },
+    // --- OAuth ---
+    'oauth-start': {
+        method: 'POST',
+        path: '/api/oauth/start',
+        description: 'Initiate OAuth2 authorization code flow.',
+        insiderOnly: true,
+    },
+    'oauth-status': {
+        method: 'GET',
+        path: '/api/oauth/status',
+        description: 'Check if valid OAuth2 credentials exist for a provider/account.',
+        insiderOnly: true,
+    },
+    'oauth-token': {
+        method: 'GET',
+        path: '/api/oauth/token',
+        description: 'Retrieve valid access token (with lazy refresh).',
+        insiderOnly: true,
+    },
+    'oauth-callback': {
+        method: 'GET',
+        path: '/oauth/callback',
+        description: 'OAuth2 callback (browser redirect target, unauthenticated).',
+        unauthenticated: true,
+    },
+    // --- Keys ---
+    'insider-key': {
+        method: 'GET',
+        path: '/insider-key',
+        description: 'Get insider key for the authenticated user.',
+    },
+    key: {
+        method: 'GET',
+        path: '/key',
+        description: 'Compute path-specific key.',
+    },
+    'share-legacy': {
+        method: 'GET',
+        path: '/share',
+        description: 'Generate outsider share link (top-level legacy route).',
+    },
+    // --- Shortlinks ---
+    go: {
+        method: 'GET',
+        path: '/go/:slug',
+        description: 'Shortlink redirect (unauthenticated).',
+        unauthenticated: true,
+    },
+};
+
+export { serverEndpoints };

package/dist/src/endpoints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index.d.ts

@@ -4,5 +4,6 @@
  * @packageDocumentation
  */
 export { computeDeepShareKey, computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, type DeepShareParams, timingSafeEqual, } from './crypto.js';
-export { type AuthMode, authModeSchema, authSchema, DEPRECATED_CONFIG_PROPS, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, type JeevesConfig, jeevesConfigSchema, keyEntrySchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema, } from './schema.js';
+export { type EndpointEntry, serverEndpoints } from './endpoints.js';
+export { type AuthMode, authModeSchema, authSchema, type Branding, brandingSchema, DEFAULT_BRANDING, DEPRECATED_CONFIG_PROPS, emailAuthSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, type JeevesConfig, jeevesConfigSchema, keyEntrySchema, type LoggingConfig, loggingConfigSchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema, themeOverridesSchema, } from './schema.js';
 export type { AuthStatusResponse, DriveEntry, ExportCacheClearResponse, ExportLink, FileMutationAction, LinkInfoResponse, OAuthStartRequest, OAuthStartResponse, RotateKeyResponse, ShareForRequest, ShareForResponse, ShareRequest, ShareResponse, } from './types.js';

package/dist/src/index.js

@@ -1,2 +1,3 @@
 export { computeDeepShareKey, computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, timingSafeEqual } from './crypto.js';
-export { DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema } from './schema.js';
+export { serverEndpoints } from './endpoints.js';
+export { DEFAULT_BRANDING, DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, brandingSchema, emailAuthSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, loggingConfigSchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema, themeOverridesSchema } from './schema.js';

package/dist/src/schema.d.ts

@@ -3,25 +3,36 @@ import { z } from 'zod';
 export declare const DEPRECATED_CONFIG_PROPS: readonly ["host", "runnerUrl", "watcherUrl", "metaUrl"];
 /** Supported authentication methods */
 export declare const authModeSchema: z.ZodEnum<{
-    google: "google";
     keys: "keys";
+    google: "google";
+    email: "email";
 }>;
 /** Google OAuth configuration */
 export declare const googleAuthSchema: z.ZodObject<{
     clientId: z.ZodString;
     clientSecret: z.ZodString;
 }, z.core.$strip>;
+/** Email (magic link) authentication configuration */
+export declare const emailAuthSchema: z.ZodObject<{
+    smtpUrl: z.ZodString;
+    fromAddress: z.ZodEmail;
+}, z.core.$strip>;
 /** Auth configuration */
 export declare const authSchema: z.ZodObject<{
     modes: z.ZodArray<z.ZodEnum<{
-        google: "google";
         keys: "keys";
+        google: "google";
+        email: "email";
     }>>;
     google: z.ZodOptional<z.ZodObject<{
         clientId: z.ZodString;
         clientSecret: z.ZodString;
     }, z.core.$strip>>;
     sessionSecret: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodObject<{
+        smtpUrl: z.ZodString;
+        fromAddress: z.ZodEmail;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Event webhook configuration */
 export declare const eventConfigSchema: z.ZodObject<{
@@ -75,6 +86,13 @@ export declare const keyEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodObje
 }, z.core.$strip>]>;
 /** Check if a string is a named scope identifier (not a path glob). */
 export declare function isScopeName(v: string): boolean;
+/** Logging configuration. Not hot-reloadable — changes require service restart. */
+export declare const loggingConfigSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred logging config type. */
+export type LoggingConfig = z.infer<typeof loggingConfigSchema>;
 /** OAuth provider configuration */
 export declare const oauthProviderSchema: z.ZodObject<{
     authUrl: z.ZodPipe<z.ZodString, z.ZodURL>;
@@ -92,20 +110,37 @@ export declare const oauthSchema: z.ZodObject<{
         defaultScopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+/** Theme overrides for light and dark modes */
+export declare const themeOverridesSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/** Instance branding configuration */
+export declare const brandingSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    emoji: z.ZodDefault<z.ZodString>;
+    theme: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        dark: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    emailTemplate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /** Top-level Jeeves Server configuration */
 export declare const jeevesConfigSchema: z.ZodObject<{
     port: z.ZodDefault<z.ZodNumber>;
     chromePath: z.ZodString;
     auth: z.ZodObject<{
         modes: z.ZodArray<z.ZodEnum<{
-            google: "google";
             keys: "keys";
+            google: "google";
+            email: "email";
         }>>;
         google: z.ZodOptional<z.ZodObject<{
             clientId: z.ZodString;
             clientSecret: z.ZodString;
         }, z.core.$strip>>;
         sessionSecret: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodObject<{
+            smtpUrl: z.ZodString;
+            fromAddress: z.ZodEmail;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     scopes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -151,6 +186,10 @@ export declare const jeevesConfigSchema: z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
         deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>]>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     oauth: z.ZodOptional<z.ZodObject<{
         credentialDir: z.ZodString;
         providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -161,8 +200,24 @@ export declare const jeevesConfigSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     go: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    branding: z.ZodOptional<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        emoji: z.ZodDefault<z.ZodString>;
+        theme: z.ZodOptional<z.ZodObject<{
+            light: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            dark: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>;
+        emailTemplate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Inferred config type */
 export type JeevesConfig = z.infer<typeof jeevesConfigSchema>;
 /** Auth mode type */
 export type AuthMode = z.infer<typeof authModeSchema>;
+/** Inferred branding type */
+export type Branding = z.infer<typeof brandingSchema>;
+/** Default branding values. Single source of truth for all fallbacks. */
+export declare const DEFAULT_BRANDING: {
+    readonly name: "Jeeves Server";
+    readonly emoji: "🎩";
+};

package/dist/src/schema.js

@@ -9,12 +9,19 @@ const DEPRECATED_CONFIG_PROPS = [
     'metaUrl',
 ];
 /** Supported authentication methods */
-const authModeSchema = z.enum(['google', 'keys']);
+const authModeSchema = z.enum(['google', 'keys', 'email']);
 /** Google OAuth configuration */
 const googleAuthSchema = z.object({
     clientId: z.string().min(1),
     clientSecret: z.string().min(1),
 });
+/** Email (magic link) authentication configuration */
+const emailAuthSchema = z.object({
+    /** SMTP connection string (e.g. smtps://user:pass@smtp.example.com:465) */
+    smtpUrl: z.string().min(1),
+    /** Sender email address for magic link emails */
+    fromAddress: z.email(),
+});
 /** Auth configuration */
 const authSchema = z.object({
     /** Active authentication methods. Order determines priority. */
@@ -25,6 +32,8 @@ const authSchema = z.object({
     google: googleAuthSchema.optional(),
     /** Session cookie signing secret. Required if modes includes "google". */
     sessionSecret: z.string().min(1).optional(),
+    /** Email (magic link) auth config. Required if modes includes "email". */
+    email: emailAuthSchema.optional(),
 });
 /** Event webhook configuration */
 const eventConfigSchema = z.object({
@@ -101,6 +110,19 @@ function getScopeRefs(scopes) {
     }
     return [];
 }
+/** Logging configuration. Not hot-reloadable — changes require service restart. */
+const loggingConfigSchema = z.object({
+    /** Log level. */
+    level: z
+        .string()
+        .optional()
+        .describe('Logging level (trace, debug, info, warn, error, fatal).'),
+    /** Log file path. */
+    file: z
+        .string()
+        .optional()
+        .describe('Path to log file (logs to stdout if omitted).'),
+});
 /** OAuth provider configuration */
 const oauthProviderSchema = z.object({
     authUrl: z.string().pipe(z.url()),
@@ -113,6 +135,24 @@ const oauthSchema = z.object({
     credentialDir: z.string(),
     providers: z.record(z.string(), oauthProviderSchema).default({}),
 });
+/** Theme overrides for light and dark modes */
+const themeOverridesSchema = z.record(z.string(), z.string());
+/** Instance branding configuration */
+const brandingSchema = z.object({
+    /** Instance display name (used in page title, navbar, emails) */
+    name: z.string().default('Jeeves Server'),
+    /** Instance emoji (used as home icon in navbar) */
+    emoji: z.string().default('🎩'),
+    /** CSS variable overrides grouped by theme mode */
+    theme: z
+        .object({
+        light: themeOverridesSchema.optional(),
+        dark: themeOverridesSchema.optional(),
+    })
+        .optional(),
+    /** Handlebars template for magic link emails. Supports {{magicLink}}, {{branding.name}}, {{branding.emoji}} */
+    emailTemplate: z.string().optional(),
+});
 /** Top-level Jeeves Server configuration */
 const jeevesConfigSchema = z
     .object({
@@ -163,6 +203,11 @@ const jeevesConfigSchema = z
      * If omitted, all paths are shareable with outsiders.
      */
     outsiderPolicy: scopesSchema.optional(),
+    /**
+     * Logging configuration.
+     * Not hot-reloadable — changes require a service restart.
+     */
+    logging: loggingConfigSchema.optional(),
     /** OAuth2 credential management configuration */
     oauth: oauthSchema.optional(),
     /**
@@ -180,6 +225,8 @@ const jeevesConfigSchema = z
         message: 'Target must be a relative path starting with / or an absolute URL',
     }))
         .default({}),
+    /** Instance branding (name, emoji, theme overrides, email template) */
+    branding: brandingSchema.optional(),
 })
     .superRefine((config, ctx) => {
     // Google auth mode requires google config + sessionSecret
@@ -199,6 +246,23 @@ const jeevesConfigSchema = z
             });
         }
     }
+    // Email auth mode requires email config
+    if (config.auth.modes.includes('email')) {
+        if (!config.auth.email) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'auth.email is required when auth.modes includes "email"',
+                path: ['auth', 'email'],
+            });
+        }
+        if (!config.auth.sessionSecret) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'auth.sessionSecret is required when auth.modes includes "email"',
+                path: ['auth', 'sessionSecret'],
+            });
+        }
+    }
     // Keys auth mode requires at least one key
     if (config.auth.modes.includes('keys') &&
         Object.keys(config.keys).length === 0) {
@@ -248,5 +312,10 @@ const jeevesConfigSchema = z
     if (outsiderRefs.length > 0)
         validateRefs(outsiderRefs, ['outsiderPolicy']);
 });
+/** Default branding values. Single source of truth for all fallbacks. */
+const DEFAULT_BRANDING = {
+    name: 'Jeeves Server',
+    emoji: '🎩',
+};
 
-export { DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema };
+export { DEFAULT_BRANDING, DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, brandingSchema, emailAuthSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, loggingConfigSchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema, themeOverridesSchema };

package/package.json

@@ -86,5 +86,5 @@
   },
   "type": "module",
   "types": "dist/src/index.d.ts",
-  "version": "0.1.4"
+  "version": "0.1.6"
 }