@frontmcp/utils 1.9.6 → 1.9.7

package/README.md

@@ -1,10 +1,8 @@
 # @frontmcp/utils
 
-Shared utility functions for the FrontMCP ecosystem.
+Shared helpers for the FrontMCP packages: names and URI templates, cross-platform crypto, key-value storage, file system access, environment detection and more. This is an internal package: `@frontmcp/sdk` and the other `@frontmcp/*` packages depend on it and install it for you. Import it directly only when your own code, like a plugin, needs one of these helpers.
 
-[![NPM](https://img.shields.io/npm/v/@frontmcp/utils.svg)](https://www.npmjs.com/package/@frontmcp/utils)
-
-> **Internal package.** Used by `@frontmcp/sdk` and other `@frontmcp/*` libraries — most users do not need to install this directly.
+[![npm](https://img.shields.io/npm/v/@frontmcp/utils.svg)](https://www.npmjs.com/package/@frontmcp/utils) [![License](https://img.shields.io/npm/l/@frontmcp/utils.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)
 
 ## Install
 
@@ -12,40 +10,63 @@ Shared utility functions for the FrontMCP ecosystem.
 npm install @frontmcp/utils
 ```
 
-## Features
-
-**Naming** — `splitWords`, `toCase`, `shortHash`, `ensureMaxLen`, `idFromString` for string manipulation and case conversion
-
-**URI** — `isValidMcpUri`, `extractUriScheme`, `parseUriTemplate`, `matchUriTemplate`, `expandUriTemplate` (RFC 3986 / RFC 6570)
-
-**Path** — `trimSlashes`, `joinPath` for URL path operations
+It needs Node.js 24 or later. The crypto, async context, event emitter, environment and path helpers also have browser builds, picked through the package's `imports` map. `@frontmcp/lazy-zod` is a required peer dependency (it needs `zod` 4). The others are optional, one per storage backend:
 
-**Content** — `sanitizeToJson`, `inferMimeType` for safe serialization and MIME detection
+| Optional peer    | Enables                                                      |
+| ---------------- | ------------------------------------------------------------ |
+| `ioredis`        | `createStorage({ type: 'redis' })` and `RedisStorageAdapter` |
+| `@vercel/kv`     | `createStorage({ type: 'vercel-kv' })`                       |
+| `@upstash/redis` | `createStorage({ type: 'upstash' })`                         |
 
-**HTTP** — `validateBaseUrl` for URL validation and normalization
-
-**Crypto** — `sha256`, `sha256Hex`, `sha256Base64url`, `hkdfSha256`, `encryptAesGcm`, `decryptAesGcm`, `randomBytes`, `randomUUID`, `generateCodeVerifier`, `generateCodeChallenge`, `generatePkcePair`, `base64urlEncode`, `base64urlDecode` for cross-platform cryptography
-
-**File system** — `readFile`, `writeFile`, `mkdir`, `stat`, `fileExists`, `readJSON`, `writeJSON`, `ensureDir`, `isDirEmpty`, `runCmd` and more — lazy-loaded for Node.js environments
-
-## Quick Example
+## Usage
 
 ```ts
-import { fileExists, matchUriTemplate, sha256Hex } from '@frontmcp/utils';
+import { createStorage, expandUriTemplate, matchUriTemplate, sha256Hex, toCase } from '@frontmcp/utils';
 
-const params = matchUriTemplate('users/{id}/posts/{postId}', 'users/123/posts/456');
-// { id: '123', postId: '456' }
+matchUriTemplate('tickets://{id}/comments/{commentId}', 'tickets://T-1/comments/42');
+// { id: 'T-1', commentId: '42' }
 
-const hash = sha256Hex('hello world');
+expandUriTemplate('tickets://{id}', { id: 'T-2' }); // 'tickets://T-2'
+toCase(['create', 'ticket'], 'snake'); // 'create_ticket'
+sha256Hex('hello world'); // 'b94d27b9...'
 
-const exists = await fileExists('/path/to/file');
+const storage = await createStorage({ type: 'memory' });
+await storage.set('ticket:T-1', 'open', { ttlSeconds: 60 });
+await storage.get('ticket:T-1'); // 'open'
 ```
 
-## Related Packages
-
-- [`@frontmcp/sdk`](../sdk) — core framework
-- [`@frontmcp/auth`](../auth) — uses crypto utilities for PKCE, encryption
+## What's in it
+
+| Area             | Exports                                                                                                                                                                   |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Naming           | `splitWords`, `toCase`, `shortHash`, `ensureMaxLen`, `idFromString`                                                                                                       |
+| URIs             | `isValidMcpUri`, `extractUriScheme`, `parseUriTemplate`, `matchUriTemplate`, `expandUriTemplate`, `extractTemplateParams` (RFC 3986 URIs, RFC 6570 templates)             |
+| Paths            | `trimSlashes`, `joinPath`, and cross-platform `pathJoin`, `pathResolve`, `basename`, `dirname`, `extname`                                                                 |
+| Content          | `sanitizeToJson`, `inferMimeType`, `safeStringify`                                                                                                                        |
+| HTTP             | `validateBaseUrl`, `buildSetCookie`, `parseCookies`, `getCookie`, `isLocalhost`, `isSecureRequest`                                                                        |
+| Network          | `classifyIpAddress`, `parseIpv4`, `expandIpv6`, `isRedirectResponse`, for SSRF (server-side request forgery) checks                                                       |
+| Escaping         | `escapeHtml`, `escapeHtmlAttr`, `escapeJsString`, `safeJsonForScript`                                                                                                     |
+| Crypto           | `sha256`, `sha256Hex`, `hmacSha256`, `hkdfSha256`, `encryptAesGcm`, `decryptAesGcm`, `randomBytes`, `randomUUID`, `timingSafeEqual`, `base64urlEncode`, `base64urlDecode` |
+| PKCE             | `generateCodeVerifier`, `generateCodeChallenge`, `verifyCodeChallenge`, `generatePkcePair` (RFC 7636)                                                                     |
+| Encryption, keys | `encryptValue`, `decryptValue`, `signData`, `verifyData`, `KeyPersistence`, `createKeyPersistence`                                                                        |
+| Storage          | `createStorage`, `createMemoryStorage`, `TypedStorage`, `EncryptedTypedStorage`, and adapters for memory, Redis, Vercel KV, Upstash and the file system                   |
+| File system      | `readFile`, `writeFile`, `mkdir`, `stat`, `fileExists`, `readJSON`, `writeJSON`, `ensureDir`, `isDirEmpty`, `runCmd` and more. Node.js only; `fs` loads on first use.     |
+| Environment      | `getEnv`, `isProduction`, `isDevelopment`, `isEdgeRuntime`, `isServerless`, `getRuntimeContext`, `isNode`, `isBrowser`                                                    |
+| Context, events  | `AsyncLocalStorage`, `EventEmitter`, both with browser builds                                                                                                             |
+| Safe regex       | `isPatternSafe`, `createSafeRegExp`, `safeTest`, `safeMatch`, `safeReplace`, against ReDoS (regular expression denial of service)                                         |
+| Model tool calls | `processPlatformToolCalls`, which passes OpenAI, Claude or Vercel AI tool calls to your `callTool` function and returns the results in that platform's format             |
+| Machine ID       | `getMachineId`, `setMachineIdOverride`, `getHostname`                                                                                                                     |
+
+## Related packages
+
+- [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): the framework, built on these helpers.
+- [`@frontmcp/auth`](https://www.npmjs.com/package/@frontmcp/auth): uses the crypto, PKCE and storage helpers.
+- [`@frontmcp/storage-sqlite`](https://www.npmjs.com/package/@frontmcp/storage-sqlite): a SQLite storage adapter that implements this package's `StorageAdapter`.
+
+## Contributing
+
+Source: [`libs/utils`](https://github.com/agentfront/frontmcp/tree/main/libs/utils). Issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md).
 
 ## License
 
-Apache-2.0 — see [LICENSE](../../LICENSE).
+Apache-2.0. See [LICENSE](https://github.com/agentfront/frontmcp/blob/main/LICENSE).

package/esm/index.mjs

@@ -1283,6 +1283,14 @@ var init_base = __esm({
           "Use the memory, Redis, Upstash or Vercel KV adapter for an atomic compare-and-delete."
         );
       }
+      /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
+      async expireIfEquals(_key, _expectedValue, _ttlSeconds) {
+        throw new StorageNotSupportedError(
+          "expireIfEquals",
+          this.backendName,
+          "Use the memory, Redis, Upstash or Vercel KV adapter for an atomic compare-and-expire."
+        );
+      }
       // ============================================
       // Pub/Sub (default: not supported)
       // ============================================
@@ -1438,6 +1446,12 @@ var init_memory = __esm({
         if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
         return this.deleteEntry(key);
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        this.ensureConnected();
+        const entry = this.store.get(key);
+        if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
+        return this.expire(key, ttlSeconds);
+      }
       async exists(key) {
         this.ensureConnected();
         const entry = this.store.get(key);
@@ -2951,11 +2965,12 @@ var init_utils = __esm({
 });
 
 // libs/utils/src/storage/utils/compare-and-delete.ts
-var COMPARE_AND_DELETE_SCRIPT;
+var COMPARE_AND_DELETE_SCRIPT, COMPARE_AND_EXPIRE_SCRIPT;
 var init_compare_and_delete = __esm({
   "libs/utils/src/storage/utils/compare-and-delete.ts"() {
     "use strict";
     COMPARE_AND_DELETE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+    COMPARE_AND_EXPIRE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('EXPIRE', KEYS[1], ARGV[2]) end return 0`;
   }
 });
 
@@ -3200,6 +3215,17 @@ var init_redis = __esm({
         );
         return deleted === 1;
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        validateTTL(ttlSeconds);
+        const extended = await this.getConnectedClient().eval(
+          COMPARE_AND_EXPIRE_SCRIPT,
+          1,
+          this.prefixKey(key),
+          expectedValue,
+          String(ttlSeconds)
+        );
+        return extended === 1;
+      }
       async exists(key) {
         const result = await this.getConnectedClient().exists(this.prefixKey(key));
         return result > 0;
@@ -3533,6 +3559,15 @@ var init_vercel_kv = __esm({
         );
         return deleted === 1;
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        validateTTL(ttlSeconds);
+        const extended = await this.getConnectedClient().eval(
+          COMPARE_AND_EXPIRE_SCRIPT,
+          [this.prefixKey(key)],
+          [expectedValue, String(ttlSeconds)]
+        );
+        return extended === 1;
+      }
       async exists(key) {
         const result = await this.getConnectedClient().exists(this.prefixKey(key));
         return result > 0;
@@ -3768,6 +3803,15 @@ var init_upstash = __esm({
         );
         return deleted === 1;
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        validateTTL(ttlSeconds);
+        const extended = await this.getConnectedClient().eval(
+          COMPARE_AND_EXPIRE_SCRIPT,
+          [this.prefixKey(key)],
+          [expectedValue, String(ttlSeconds)]
+        );
+        return extended === 1;
+      }
       async exists(key) {
         const result = await this.getConnectedClient().exists(this.prefixKey(key));
         return result > 0;
@@ -5113,6 +5157,12 @@ var NamespacedStorageImpl = class _NamespacedStorageImpl {
     }
     return this.adapter.deleteIfEquals(this.prefixKey(key), expectedValue);
   }
+  async expireIfEquals(key, expectedValue, ttlSeconds) {
+    if (!this.adapter.expireIfEquals) {
+      throw new StorageNotSupportedError("expireIfEquals", "this storage adapter");
+    }
+    return this.adapter.expireIfEquals(this.prefixKey(key), expectedValue, ttlSeconds);
+  }
   // ============================================
   // Pub/Sub (with channel prefixing)
   // ============================================

package/index.js

@@ -1285,6 +1285,14 @@ var init_base = __esm({
           "Use the memory, Redis, Upstash or Vercel KV adapter for an atomic compare-and-delete."
         );
       }
+      /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
+      async expireIfEquals(_key, _expectedValue, _ttlSeconds) {
+        throw new StorageNotSupportedError(
+          "expireIfEquals",
+          this.backendName,
+          "Use the memory, Redis, Upstash or Vercel KV adapter for an atomic compare-and-expire."
+        );
+      }
       // ============================================
       // Pub/Sub (default: not supported)
       // ============================================
@@ -1440,6 +1448,12 @@ var init_memory = __esm({
         if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
         return this.deleteEntry(key);
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        this.ensureConnected();
+        const entry = this.store.get(key);
+        if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
+        return this.expire(key, ttlSeconds);
+      }
       async exists(key) {
         this.ensureConnected();
         const entry = this.store.get(key);
@@ -2953,11 +2967,12 @@ var init_utils = __esm({
 });
 
 // libs/utils/src/storage/utils/compare-and-delete.ts
-var COMPARE_AND_DELETE_SCRIPT;
+var COMPARE_AND_DELETE_SCRIPT, COMPARE_AND_EXPIRE_SCRIPT;
 var init_compare_and_delete = __esm({
   "libs/utils/src/storage/utils/compare-and-delete.ts"() {
     "use strict";
     COMPARE_AND_DELETE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+    COMPARE_AND_EXPIRE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('EXPIRE', KEYS[1], ARGV[2]) end return 0`;
   }
 });
 
@@ -3202,6 +3217,17 @@ var init_redis = __esm({
         );
         return deleted === 1;
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        validateTTL(ttlSeconds);
+        const extended = await this.getConnectedClient().eval(
+          COMPARE_AND_EXPIRE_SCRIPT,
+          1,
+          this.prefixKey(key),
+          expectedValue,
+          String(ttlSeconds)
+        );
+        return extended === 1;
+      }
       async exists(key) {
         const result = await this.getConnectedClient().exists(this.prefixKey(key));
         return result > 0;
@@ -3535,6 +3561,15 @@ var init_vercel_kv = __esm({
         );
         return deleted === 1;
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        validateTTL(ttlSeconds);
+        const extended = await this.getConnectedClient().eval(
+          COMPARE_AND_EXPIRE_SCRIPT,
+          [this.prefixKey(key)],
+          [expectedValue, String(ttlSeconds)]
+        );
+        return extended === 1;
+      }
       async exists(key) {
         const result = await this.getConnectedClient().exists(this.prefixKey(key));
         return result > 0;
@@ -3770,6 +3805,15 @@ var init_upstash = __esm({
         );
         return deleted === 1;
       }
+      async expireIfEquals(key, expectedValue, ttlSeconds) {
+        validateTTL(ttlSeconds);
+        const extended = await this.getConnectedClient().eval(
+          COMPARE_AND_EXPIRE_SCRIPT,
+          [this.prefixKey(key)],
+          [expectedValue, String(ttlSeconds)]
+        );
+        return extended === 1;
+      }
       async exists(key) {
         const result = await this.getConnectedClient().exists(this.prefixKey(key));
         return result > 0;
@@ -5323,6 +5367,12 @@ var NamespacedStorageImpl = class _NamespacedStorageImpl {
     }
     return this.adapter.deleteIfEquals(this.prefixKey(key), expectedValue);
   }
+  async expireIfEquals(key, expectedValue, ttlSeconds) {
+    if (!this.adapter.expireIfEquals) {
+      throw new StorageNotSupportedError("expireIfEquals", "this storage adapter");
+    }
+    return this.adapter.expireIfEquals(this.prefixKey(key), expectedValue, ttlSeconds);
+  }
   // ============================================
   // Pub/Sub (with channel prefixing)
   // ============================================

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.9.6",
-  "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
+  "version": "1.9.7",
+  "description": "Shared helpers for FrontMCP: URI templates, naming, cross-platform crypto and PKCE, key-value storage, file system and environment detection",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
   "keywords": [
+    "frontmcp",
+    "mcp",
     "utils",
-    "utilities",
-    "uri",
-    "url",
-    "string",
-    "path",
-    "typescript",
-    "mcp"
+    "uri-template",
+    "crypto",
+    "pkce",
+    "storage",
+    "redis",
+    "typescript"
   ],
   "repository": {
     "type": "git",
@@ -22,7 +23,7 @@
   "bugs": {
     "url": "https://github.com/agentfront/frontmcp/issues"
   },
-  "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/utils/README.md",
+  "homepage": "https://frontmcp.dev",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -32,7 +33,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.9.6",
+    "@frontmcp/lazy-zod": "1.9.7",
     "@upstash/redis": "^1.34.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"

package/storage/adapters/base.d.ts

@@ -68,6 +68,8 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
      * Override in adapters whose backend can compare and delete in one step.
      */
     deleteIfEquals(_key: string, _expectedValue: string): Promise<boolean>;
+    /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
+    expireIfEquals(_key: string, _expectedValue: string, _ttlSeconds: number): Promise<boolean>;
     /**
      * Default: pub/sub not supported.
      * Override in adapters that support it.

package/storage/adapters/memory.d.ts

@@ -43,6 +43,7 @@ export declare class MemoryStorageAdapter extends BaseStorageAdapter {
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
+    expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     expire(key: string, ttlSeconds: number): Promise<boolean>;
     ttl(key: string): Promise<number | null>;

package/storage/adapters/redis.d.ts

@@ -59,6 +59,7 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
+    expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mset(entries: import('../types').SetEntry[]): Promise<void>;

package/storage/adapters/upstash.d.ts

@@ -53,6 +53,7 @@ export declare class UpstashStorageAdapter extends BaseStorageAdapter {
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
+    expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mdelete(keys: string[]): Promise<number>;

package/storage/adapters/vercel-kv.d.ts

@@ -88,6 +88,7 @@ export declare class VercelKvStorageAdapter extends BaseStorageAdapter {
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
+    expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mdelete(keys: string[]): Promise<number>;

package/storage/namespace.d.ts

@@ -67,6 +67,7 @@ export declare class NamespacedStorageImpl implements NamespacedStorage {
     decr(key: string): Promise<number>;
     incrBy(key: string, amount: number): Promise<number>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
+    expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     publish(channel: string, message: string): Promise<number>;
     subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
     supportsPubSub(): boolean;

package/storage/types.d.ts

@@ -214,6 +214,16 @@ export interface StorageAdapter {
      * @throws StorageNotSupportedError if the backend has no atomic compare-and-delete
      */
     deleteIfEquals?(key: string, expectedValue: string): Promise<boolean>;
+    /**
+     * Atomically set a key's TTL only while it still holds `expectedValue` (compare-and-expire).
+     *
+     * @param key - Storage key
+     * @param expectedValue - The exact value the key must hold
+     * @param ttlSeconds - The new time to live, in seconds
+     * @returns true if this call set the TTL, false if the key was missing or held another value
+     * @throws StorageNotSupportedError if the backend has no atomic compare-and-expire
+     */
+    expireIfEquals?(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     /**
      * Publish a message to a channel.
      * Not all adapters support pub/sub (e.g., Vercel KV doesn't).
@@ -278,6 +288,8 @@ export interface NamespacedStorage extends StorageAdapter {
     namespace(name: string, id?: string): NamespacedStorage;
     /** {@link StorageAdapter.deleteIfEquals}; throws StorageNotSupportedError when the adapter has none. */
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
+    /** {@link StorageAdapter.expireIfEquals}; throws StorageNotSupportedError when the adapter has none. */
+    expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
     /**
      * Get the underlying root adapter (for advanced use).
      * Use with caution - operations bypass namespace prefixing.

package/storage/utils/compare-and-delete.d.ts

@@ -1,2 +1,4 @@
 /** Redis Lua script for `deleteIfEquals`: deletes KEYS[1] only while it holds ARGV[1], returning 1 or 0. */
 export declare const COMPARE_AND_DELETE_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0";
+/** Redis Lua script for `expireIfEquals`: sets KEYS[1]'s TTL to ARGV[2] seconds only while it holds ARGV[1]. */
+export declare const COMPARE_AND_EXPIRE_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('EXPIRE', KEYS[1], ARGV[2]) end return 0";