@karmaniverous/jeeves-server-core 0.3.0 → 0.4.0

package/README.md

@@ -14,26 +14,34 @@ 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 |
 
+### URL Key Parameter
+
+| Export | Description |
+| --- | --- |
+| `URL_KEY_PARAM` | `'k'`: the query parameter every generated URL carries its auth key in |
+| `LEGACY_URL_KEY_PARAM` | `'key'`: the old name, still accepted everywhere |
+| `getUrlKey(query)` | Read the auth key from a parsed query object or `URLSearchParams`: `k` wins when both names are present; empty values count as absent; the first of repeated values is used |
+
 ### 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) |
+| `jeevesConfigSchema` | Full server config Zod schema (includes `logging`, `oauth`, `publicUrl`, `trustProxyHeaders` and all other fields; requires `publicUrl` or `trustProxyHeaders: true` when email, Google or OAuth login is configured) |
 
 ### 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) |
+| `serverEndpoints` | Complete declarative catalog of all jeeves-server API endpoints (39 entries) |
 
 ### API Types
 
 | Type | Description |
 | --- | --- |
-| `ShareRequest` / `ShareResponse` | `POST /api/share` payloads |
+| `ShareRequest` / `ShareResponse` | `POST /api/share` payloads (`ShareResponse.isDirectory`, optional: whether the shared path is an existing directory; sent by servers from 3.15.0) |
 | `ShareForRequest` / `ShareForResponse` | `POST /api/util/share-for` payloads (audience-based sharing) |
 | `AuthStatusResponse` | `GET /api/auth/status` response |
 | `RotateKeyResponse` | `POST /api/rotate-key` response |

package/dist/src/endpoints.js

@@ -19,6 +19,12 @@ const serverEndpoints = {
         description: 'Server health: name, version, uptime, status, health details.',
         unauthenticated: true,
     },
+    health: {
+        method: 'GET',
+        path: '/health',
+        description: 'Liveness check: returns { ok: true }, no downstream checks.',
+        unauthenticated: true,
+    },
     config: {
         method: 'GET',
         path: '/config',
@@ -122,7 +128,7 @@ const serverEndpoints = {
     share: {
         method: 'POST',
         path: '/api/share',
-        description: 'Generate HMAC-signed share link for a path.',
+        description: 'Generate HMAC-signed share link for a path; the response reports whether the path is a directory (isDirectory).',
         insiderOnly: true,
     },
     'share-for': {
@@ -148,6 +154,12 @@ const serverEndpoints = {
         path: '/api/link-info/*',
         description: 'Query available link types for a path (page, raw, PDF, DOCX, etc.).',
     },
+    'resolve-path': {
+        method: 'GET',
+        path: '/api/resolve-path',
+        description: 'Map an absolute filesystem path to its browse path and URLs (?fsPath=).',
+        insiderOnly: true,
+    },
     'rotate-key': {
         method: 'POST',
         path: '/api/rotate-key',
@@ -163,7 +175,8 @@ const serverEndpoints = {
     events: {
         method: 'GET',
         path: '/api/events',
-        description: 'Query recent event log entries (limit capped at 100).',
+        description: 'Query recent event log entries (insiders with no scopes configured; limit capped at 100).',
+        insiderOnly: true,
     },
     // --- Search ---
     search: {

package/dist/src/index.d.ts

@@ -7,3 +7,4 @@ export { computeDeepShareKey, computeInsiderKey, computeOutsiderKeyWithExpiry, c
 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';
+export { getUrlKey, LEGACY_URL_KEY_PARAM, URL_KEY_PARAM } from './urlKey.js';

package/dist/src/index.js

@@ -1,3 +1,4 @@
 export { computeDeepShareKey, computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, timingSafeEqual } from './crypto.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';
+export { LEGACY_URL_KEY_PARAM, URL_KEY_PARAM, getUrlKey } from './urlKey.js';

package/dist/src/schema.d.ts

@@ -212,6 +212,7 @@ export declare const jeevesConfigSchema: z.ZodObject<{
     eventQueue: z.ZodOptional<z.ZodString>;
     eventQueueConcurrency: z.ZodDefault<z.ZodNumber>;
     publicUrl: z.ZodOptional<z.ZodURL>;
+    trustProxyHeaders: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Inferred config type */
 export type JeevesConfig = z.infer<typeof jeevesConfigSchema>;

package/dist/src/schema.js

@@ -239,6 +239,12 @@ const jeevesConfigSchema = z
     eventQueueConcurrency: z.number().int().positive().default(3),
     /** Public base URL (e.g. https://jeeves.johngalt.id). When set, API responses include full public URLs. */
     publicUrl: z.url().optional(),
+    /**
+     * Trust `X-Forwarded-Proto` / `X-Forwarded-Host` / `Host` to build the
+     * public origin when `publicUrl` is unset. Enable only behind a proxy
+     * that sets or strips these headers itself. Default: false.
+     */
+    trustProxyHeaders: z.boolean().default(false),
 })
     .superRefine((config, ctx) => {
     // Google auth mode requires google config + sessionSecret
@@ -275,6 +281,22 @@ const jeevesConfigSchema = z
             });
         }
     }
+    // Login links and OAuth redirects are absolute URLs on a trusted public
+    // origin: publicUrl, or forwarding headers only when explicitly trusted.
+    const loginFlows = [
+        config.auth.modes.includes('email') ? 'email login' : null,
+        config.auth.modes.includes('google') ? 'Google login' : null,
+        config.oauth ? 'OAuth (oauth)' : null,
+    ].filter((flow) => flow !== null);
+    if (loginFlows.length > 0 &&
+        !config.publicUrl &&
+        !config.trustProxyHeaders) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `publicUrl is required when ${loginFlows.join(', ')} is configured (or set trustProxyHeaders: true behind a proxy that sets X-Forwarded-* headers)`,
+            path: ['publicUrl'],
+        });
+    }
     // Keys auth mode requires at least one key
     if (config.auth.modes.includes('keys') &&
         Object.keys(config.keys).length === 0) {

package/dist/src/schema.publicUrl.test.d.ts

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

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

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

package/dist/src/types.d.ts

@@ -17,6 +17,11 @@ export interface ShareResponse {
     exp: string | null;
     depth?: number;
     dirs?: boolean;
+    /**
+     * Whether the shared path is an existing directory. Sent by servers from
+     * 3.15.0; absent from older servers.
+     */
+    isDirectory?: boolean;
 }
 /** POST /api/util/share-for request body. */
 export interface ShareForRequest {

package/dist/src/urlKey.d.ts

@@ -0,0 +1,24 @@
+/**
+ * URL auth-key query parameter names and a reader that accepts both: `k`
+ * (generated since 3.15.0) and the legacy `key`. Pure; no I/O.
+ *
+ * @remarks
+ * OpenClaw masks the value of any query parameter named `key` in
+ * model-visible tool output, so agents could not relay share links (#279).
+ * Generated URLs therefore carry the key as `k`. `key` is still accepted
+ * everywhere so existing links, bookmarks and webhook URLs keep working.
+ *
+ * @packageDocumentation
+ */
+/** Query parameter name used for auth keys in every generated URL. */
+export declare const URL_KEY_PARAM = "k";
+/** Legacy query parameter name, still accepted for backward compatibility. */
+export declare const LEGACY_URL_KEY_PARAM = "key";
+/**
+ * Read the auth key from a parsed query object or `URLSearchParams`.
+ * `k` wins when both names are present; empty values count as absent.
+ *
+ * @param query - Parsed query (e.g. Fastify `request.query`) or search params.
+ * @returns The key, or `undefined` when neither parameter carries one.
+ */
+export declare function getUrlKey(query: unknown): string | undefined;

package/dist/src/urlKey.js

@@ -0,0 +1,43 @@
+/**
+ * URL auth-key query parameter names and a reader that accepts both: `k`
+ * (generated since 3.15.0) and the legacy `key`. Pure; no I/O.
+ *
+ * @remarks
+ * OpenClaw masks the value of any query parameter named `key` in
+ * model-visible tool output, so agents could not relay share links (#279).
+ * Generated URLs therefore carry the key as `k`. `key` is still accepted
+ * everywhere so existing links, bookmarks and webhook URLs keep working.
+ *
+ * @packageDocumentation
+ */
+/** Query parameter name used for auth keys in every generated URL. */
+const URL_KEY_PARAM = 'k';
+/** Legacy query parameter name, still accepted for backward compatibility. */
+const LEGACY_URL_KEY_PARAM = 'key';
+/** First non-empty string in a parsed query value (string or repeated). */
+function firstString(value) {
+    const candidate = Array.isArray(value) ? value[0] : value;
+    return typeof candidate === 'string' && candidate !== ''
+        ? candidate
+        : undefined;
+}
+/**
+ * Read the auth key from a parsed query object or `URLSearchParams`.
+ * `k` wins when both names are present; empty values count as absent.
+ *
+ * @param query - Parsed query (e.g. Fastify `request.query`) or search params.
+ * @returns The key, or `undefined` when neither parameter carries one.
+ */
+function getUrlKey(query) {
+    if (query instanceof URLSearchParams) {
+        return (firstString(query.get(URL_KEY_PARAM)) ??
+            firstString(query.get(LEGACY_URL_KEY_PARAM)));
+    }
+    if (query === null || typeof query !== 'object')
+        return undefined;
+    const record = query;
+    return (firstString(record[URL_KEY_PARAM]) ??
+        firstString(record[LEGACY_URL_KEY_PARAM]));
+}
+
+export { LEGACY_URL_KEY_PARAM, URL_KEY_PARAM, getUrlKey };

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

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

package/package.json

@@ -1,21 +1,21 @@
 {
   "author": "Jeeves",
   "dependencies": {
-    "@karmaniverous/jeeves": "0.6.0",
-    "zod": "^4.6.5"
+    "@karmaniverous/jeeves": "0.7.0",
+    "zod": "^4.6.7"
   },
   "description": "Shared cryptographic utilities and API types for jeeves-server packages.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^2.30.0",
+    "@dotenvx/dotenvx": "^2.35.0",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "cross-env": "^10.1.0",
-    "release-it": "^21.1.0",
-    "rollup": "^4.63.5",
+    "release-it": "^21.1.1",
+    "rollup": "^4.64.6",
     "tslib": "^2.8.1",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.4"
   },
   "engines": {
     "node": ">=22"
@@ -44,10 +44,13 @@
       "tagName": "core/${version}"
     },
     "github": {
-      "release": true
+      "release": true,
+      "releaseName": "${name.split('/').pop()}@${version}",
+      "releaseNotes": "npx git-cliff --tag core/${version} --unreleased --strip header"
     },
     "hooks": {
       "after:bump": [
+        "npx git-cliff --tag core/${version} -o CHANGELOG.md",
         "npm install --package-lock-only --ignore-scripts",
         "git add ../../package-lock.json"
       ],
@@ -63,7 +66,6 @@
         "git switch ${branchName}"
       ],
       "before:npm:release": [
-        "npx git-cliff -o CHANGELOG.md",
         "git add -A"
       ]
     },
@@ -90,5 +92,5 @@
   },
   "type": "module",
   "types": "dist/src/index.d.ts",
-  "version": "0.3.0"
+  "version": "0.4.0"
 }