@frontmcp/utils 0.0.1 → 0.7.1

package/naming/index.d.ts

@@ -0,0 +1 @@
+export { NameCase, splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString } from './naming';

package/naming/naming.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared naming and case conversion utilities.
+ *
+ * Provides functions for transforming strings between different naming conventions
+ * (camelCase, snake_case, kebab-case, etc.) and generating unique identifiers.
+ */
+/**
+ * Supported naming conventions for identifiers.
+ */
+export type NameCase = 'snake' | 'kebab' | 'dot' | 'camel';
+/**
+ * Split a string into words, handling camelCase, PascalCase, and delimiters.
+ *
+ * @param input - The string to split
+ * @returns Array of words
+ *
+ * @example
+ * splitWords("myFunctionName") // ["my", "Function", "Name"]
+ * splitWords("my_function_name") // ["my", "function", "name"]
+ * splitWords("MyClassName") // ["My", "Class", "Name"]
+ */
+export declare function splitWords(input: string): string[];
+/**
+ * Convert words to a specific naming case.
+ *
+ * @param words - Array of words to convert
+ * @param kind - Target naming case
+ * @returns Converted string
+ *
+ * @example
+ * toCase(["my", "function"], "snake") // "my_function"
+ * toCase(["my", "function"], "kebab") // "my-function"
+ * toCase(["my", "function"], "camel") // "myFunction"
+ * toCase(["My", "Class"], "dot") // "my.class"
+ */
+export declare function toCase(words: string[], kind: NameCase): string;
+/**
+ * Get the separator character for a naming case.
+ *
+ * @param kind - The naming case
+ * @returns Separator character ('_', '-', '.', or '' for camelCase)
+ */
+export declare function sepFor(kind: NameCase): string;
+/**
+ * Generate a short hash (6 hex chars) from a string.
+ * Uses djb2 algorithm for fast, reasonable distribution.
+ *
+ * @param s - String to hash
+ * @returns 6-character hex string
+ *
+ * @example
+ * shortHash("some-string") // "a1b2c3"
+ */
+export declare function shortHash(s: string): string;
+/**
+ * Ensure a name fits within a maximum length, using hash truncation if needed.
+ * Preserves meaningful suffix while adding a hash for uniqueness.
+ *
+ * @param name - The name to potentially truncate
+ * @param max - Maximum allowed length
+ * @returns Name within max length, with hash if truncated
+ *
+ * @example
+ * ensureMaxLen("short", 20) // "short"
+ * ensureMaxLen("very-long-name-that-exceeds-limit", 20) // "very-a1b2c3-limit"
+ */
+export declare function ensureMaxLen(name: string, max: number): string;
+/**
+ * Convert a string to a valid identifier by removing invalid characters.
+ * Replaces any run of invalid characters with a hyphen.
+ *
+ * @param name - The string to convert
+ * @returns Valid identifier (alphanumeric, hyphens, underscores, max 64 chars)
+ *
+ * @example
+ * idFromString("My Function Name!") // "My-Function-Name"
+ * idFromString("foo@bar#baz") // "foo-bar-baz"
+ */
+export declare function idFromString(name: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "0.0.1",
+  "version": "0.7.1",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -25,7 +25,8 @@
   "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/utils/README.md",
   "dependencies": {
     "@noble/hashes": "^2.0.1",
-    "@noble/ciphers": "^2.1.1"
+    "@noble/ciphers": "^2.1.1",
+    "ast-guard": "^2.4.0"
   },
   "type": "commonjs",
   "main": "./index.js",

package/path/index.d.ts

@@ -0,0 +1 @@
+export { trimSlashes, joinPath } from './path';

package/path/path.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Path utilities for URL and file path manipulation.
+ *
+ * Provides common operations for normalizing and joining path segments.
+ */
+/**
+ * Trim leading and trailing slashes from a string.
+ *
+ * Uses a safe non-regex approach to avoid ReDoS vulnerabilities
+ * (the pattern /^\/+|\/+$/g can cause polynomial backtracking).
+ *
+ * @param s - The string to trim (null/undefined treated as empty string)
+ * @returns String with leading/trailing slashes removed
+ *
+ * @example
+ * trimSlashes('/path/to/resource/') // 'path/to/resource'
+ * trimSlashes('no-slashes') // 'no-slashes'
+ * trimSlashes('///multiple///') // 'multiple'
+ */
+export declare function trimSlashes(s: string | null | undefined): string;
+/**
+ * Join URL path segments with a single slash and no trailing slash.
+ * Empty segments are filtered out.
+ *
+ * @param parts - Path segments to join
+ * @returns Joined path starting with / or empty string
+ *
+ * @example
+ * joinPath('api', 'v1', 'users') // '/api/v1/users'
+ * joinPath('/api/', '/v1/', '/users/') // '/api/v1/users'
+ * joinPath('', 'path', '') // '/path'
+ * joinPath() // ''
+ */
+export declare function joinPath(...parts: string[]): string;

package/regex/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Safe regex utilities for preventing ReDoS (Regular Expression Denial of Service) attacks.
+ *
+ * Uses ast-guard's analyzeForReDoS function to validate patterns and provides
+ * input length guards to prevent polynomial-time attacks on untrusted data.
+ *
+ * @example
+ * ```typescript
+ * import { isPatternSafe, safeTest, safeReplace, trimBoth } from '@frontmcp/utils';
+ *
+ * // Check if a pattern is safe
+ * if (isPatternSafe(myPattern)) {
+ *   // Use pattern
+ * }
+ *
+ * // Safe regex operations with input length guards
+ * const result = safeTest(/foo/, userInput, { maxInputLength: 10000 });
+ *
+ * // Pre-built safe patterns for common operations
+ * const trimmed = trimBoth(input, '/');
+ * ```
+ */
+export * from './safe-regex';
+export * from './patterns';

package/regex/patterns.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Pre-built safe pattern utilities for common string operations.
+ *
+ * These utilities avoid vulnerable regex patterns like alternation with
+ * greedy quantifiers (e.g., /^\/+|\/+$/g) that can cause ReDoS attacks.
+ */
+/**
+ * Remove leading occurrences of a character from a string.
+ *
+ * This is a safe alternative to patterns like /^X+/ that avoids
+ * potential ReDoS issues with alternation patterns.
+ *
+ * @param input - String to trim
+ * @param char - Single character to remove from the start
+ * @returns String with leading characters removed
+ *
+ * @example
+ * ```typescript
+ * trimLeading('///path', '/'); // 'path'
+ * trimLeading('---name', '-'); // 'name'
+ * trimLeading('hello', 'x'); // 'hello'
+ * ```
+ */
+export declare function trimLeading(input: string, char: string): string;
+/**
+ * Remove trailing occurrences of a character from a string.
+ *
+ * This is a safe alternative to patterns like /X+$/ that avoids
+ * potential ReDoS issues with alternation patterns.
+ *
+ * @param input - String to trim
+ * @param char - Single character to remove from the end
+ * @returns String with trailing characters removed
+ *
+ * @example
+ * ```typescript
+ * trimTrailing('path///', '/'); // 'path'
+ * trimTrailing('name---', '-'); // 'name'
+ * trimTrailing('hello', 'x'); // 'hello'
+ * ```
+ */
+export declare function trimTrailing(input: string, char: string): string;
+/**
+ * Remove both leading and trailing occurrences of a character from a string.
+ *
+ * This is a safe alternative to the vulnerable pattern /^X+|X+$/g
+ * which uses alternation with greedy quantifiers and can cause ReDoS.
+ *
+ * @param input - String to trim
+ * @param char - Single character to remove from both ends
+ * @returns String with leading and trailing characters removed
+ *
+ * @example
+ * ```typescript
+ * trimBoth('///path///', '/'); // 'path'
+ * trimBoth('---name---', '-'); // 'name'
+ * trimBoth('/single/', '/'); // 'single'
+ * ```
+ */
+export declare function trimBoth(input: string, char: string): string;
+/**
+ * Remove multiple leading/trailing characters from a string.
+ *
+ * @param input - String to trim
+ * @param chars - Set of characters to remove from both ends
+ * @returns String with specified characters removed from both ends
+ *
+ * @example
+ * ```typescript
+ * trimChars('  -name-  ', new Set([' ', '-'])); // 'name'
+ * ```
+ */
+export declare function trimChars(input: string, chars: Set<string>): string;
+/**
+ * Extract parameters from a braced template string safely.
+ *
+ * Uses a non-backtracking approach to parse {param} patterns,
+ * avoiding the vulnerable /\{([^}]+)\}/g pattern.
+ *
+ * @param template - Template string containing {param} placeholders
+ * @param maxLength - Maximum template length to process (default: 50000)
+ * @returns Array of parameter names found in the template
+ *
+ * @example
+ * ```typescript
+ * extractBracedParams('/users/{userId}/posts/{postId}');
+ * // ['userId', 'postId']
+ *
+ * extractBracedParams('Hello {name}!');
+ * // ['name']
+ * ```
+ */
+export declare function extractBracedParams(template: string, maxLength?: number): string[];
+/**
+ * Expand a template string by replacing {param} placeholders with values.
+ *
+ * Uses a safe character-by-character approach instead of regex.
+ *
+ * @param template - Template string containing {param} placeholders
+ * @param values - Object mapping parameter names to values
+ * @param maxLength - Maximum template length to process (default: 50000)
+ * @returns Expanded string with placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * expandTemplate('/users/{userId}', { userId: '123' });
+ * // '/users/123'
+ *
+ * expandTemplate('Hello {name}!', { name: 'World' });
+ * // 'Hello World!'
+ * ```
+ */
+export declare function expandTemplate(template: string, values: Record<string, string>, maxLength?: number): string;
+/**
+ * Check if a string contains template placeholders.
+ *
+ * Uses a simple indexOf check instead of regex.
+ *
+ * @param str - String to check
+ * @param maxLength - Maximum string length to check (default: 50000)
+ * @returns true if string contains {param} style placeholders
+ */
+export declare function hasTemplatePlaceholders(str: string, maxLength?: number): boolean;
+/**
+ * Collapse multiple consecutive characters into a single occurrence.
+ *
+ * Safe alternative to patterns like /X+/g which can be combined
+ * with other patterns to create ReDoS vulnerabilities.
+ *
+ * @param input - String to process
+ * @param char - Character to collapse
+ * @returns String with consecutive characters collapsed
+ *
+ * @example
+ * ```typescript
+ * collapseChar('foo///bar', '/'); // 'foo/bar'
+ * collapseChar('hello   world', ' '); // 'hello world'
+ * ```
+ */
+export declare function collapseChar(input: string, char: string): string;
+/**
+ * Collapse all whitespace to single spaces.
+ *
+ * Safe alternative to /\s+/g which can be part of vulnerable patterns.
+ *
+ * @param input - String to process
+ * @param maxLength - Maximum input length to process (default: 50000)
+ * @returns String with whitespace collapsed to single spaces
+ *
+ * @example
+ * ```typescript
+ * collapseWhitespace('hello   world\n\nfoo'); // 'hello world foo'
+ * ```
+ */
+export declare function collapseWhitespace(input: string, maxLength?: number): string;

package/regex/safe-regex.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Safe regex utilities using ast-guard's ReDoS analysis.
+ *
+ * These utilities protect against ReDoS (Regular Expression Denial of Service)
+ * attacks by validating patterns and enforcing input length limits.
+ */
+import { REDOS_THRESHOLDS } from 'ast-guard';
+/**
+ * Default maximum input length for safe regex operations.
+ * Inputs longer than this will be rejected to prevent ReDoS attacks.
+ */
+export declare const DEFAULT_MAX_INPUT_LENGTH = 50000;
+/**
+ * Configuration options for safe regex operations.
+ */
+export interface SafeRegexOptions {
+    /**
+     * Maximum input length to process.
+     * If input exceeds this, operations return null/fallback.
+     * @default 50000
+     */
+    maxInputLength?: number;
+    /**
+     * Analysis level for pattern vulnerability detection.
+     * - 'catastrophic': Only detect exponential-time vulnerabilities (faster)
+     * - 'polynomial': Also detect polynomial-time vulnerabilities (more thorough)
+     * @default 'polynomial'
+     */
+    level?: 'catastrophic' | 'polynomial';
+    /**
+     * If true, throw an error when pattern is vulnerable instead of returning null.
+     * @default false
+     */
+    throwOnVulnerable?: boolean;
+}
+/**
+ * Result from pattern analysis.
+ */
+export interface PatternAnalysisResult {
+    /** Whether the pattern is safe to use */
+    safe: boolean;
+    /** Vulnerability score (0-100, higher = more vulnerable) */
+    score: number;
+    /** Type of vulnerability detected, if any */
+    vulnerabilityType?: string;
+    /** Human-readable explanation of the vulnerability */
+    explanation?: string;
+}
+/**
+ * Analyze a regex pattern for ReDoS vulnerability.
+ *
+ * Uses ast-guard's analyzeForReDoS to detect patterns that could cause
+ * exponential or polynomial backtracking on malicious input.
+ *
+ * @param pattern - Regex pattern to analyze (string or RegExp)
+ * @param level - Analysis level: 'catastrophic' or 'polynomial'
+ * @returns Analysis result with safety assessment
+ *
+ * @example
+ * ```typescript
+ * const result = analyzePattern('(a+)+');
+ * // result.safe === false (nested quantifiers)
+ *
+ * const result2 = analyzePattern('[a-z]+');
+ * // result2.safe === true
+ * ```
+ */
+export declare function analyzePattern(pattern: string | RegExp, level?: 'catastrophic' | 'polynomial'): PatternAnalysisResult;
+/**
+ * Check if a regex pattern is safe from ReDoS vulnerabilities.
+ *
+ * @param pattern - Regex pattern to check (string or RegExp)
+ * @param level - Analysis level: 'catastrophic' or 'polynomial'
+ * @returns true if pattern is safe, false if vulnerable
+ *
+ * @example
+ * ```typescript
+ * isPatternSafe('(a+)+'); // false - nested quantifiers
+ * isPatternSafe('[a-z]+'); // true
+ * isPatternSafe(/^foo$/); // true
+ * ```
+ */
+export declare function isPatternSafe(pattern: string | RegExp, level?: 'catastrophic' | 'polynomial'): boolean;
+/**
+ * Create a validated RegExp that has been checked for ReDoS vulnerabilities.
+ *
+ * @param pattern - Pattern string
+ * @param flags - Optional regex flags
+ * @param options - Safety options
+ * @returns RegExp if pattern is safe, null if vulnerable or invalid
+ *
+ * @example
+ * ```typescript
+ * const regex = createSafeRegExp('[a-z]+', 'g');
+ * if (regex) {
+ *   // Pattern is safe to use
+ * }
+ * ```
+ */
+export declare function createSafeRegExp(pattern: string, flags?: string, options?: SafeRegexOptions): RegExp | null;
+/**
+ * Execute regex test() with input length protection.
+ *
+ * Returns null if input exceeds maxInputLength to prevent ReDoS attacks.
+ *
+ * @param pattern - RegExp to test with
+ * @param input - String to test
+ * @param options - Safety options including maxInputLength
+ * @returns Match result, or null if input is too long
+ *
+ * @example
+ * ```typescript
+ * const result = safeTest(/foo/, userInput, { maxInputLength: 10000 });
+ * if (result === null) {
+ *   // Input was too long, rejected for safety
+ * } else if (result) {
+ *   // Pattern matched
+ * }
+ * ```
+ */
+export declare function safeTest(pattern: RegExp, input: string, options?: SafeRegexOptions): boolean | null;
+/**
+ * Execute regex match() with input length protection.
+ *
+ * Returns null if input exceeds maxInputLength to prevent ReDoS attacks.
+ *
+ * @param pattern - RegExp to match with
+ * @param input - String to match against
+ * @param options - Safety options including maxInputLength
+ * @returns Match result array, or null if input is too long or no match
+ *
+ * @example
+ * ```typescript
+ * const matches = safeMatch(/(\d+)/, userInput, { maxInputLength: 5000 });
+ * ```
+ */
+export declare function safeMatch(pattern: RegExp, input: string, options?: SafeRegexOptions): RegExpMatchArray | null;
+/**
+ * Execute regex replace() with input length protection.
+ *
+ * Returns original input unchanged if it exceeds maxInputLength to prevent ReDoS attacks.
+ *
+ * @param input - String to perform replacement on
+ * @param pattern - RegExp pattern to match
+ * @param replacement - Replacement string or function
+ * @param options - Safety options including maxInputLength
+ * @returns Replaced string, or original input if too long
+ *
+ * @example
+ * ```typescript
+ * const result = safeReplace(userInput, /foo/g, 'bar', { maxInputLength: 10000 });
+ * ```
+ */
+export declare function safeReplace(input: string, pattern: RegExp, replacement: string | ((match: string, ...args: unknown[]) => string), options?: SafeRegexOptions): string;
+/**
+ * Execute regex exec() with input length protection.
+ *
+ * Returns null if input exceeds maxInputLength to prevent ReDoS attacks.
+ *
+ * @param pattern - RegExp to execute
+ * @param input - String to execute against
+ * @param options - Safety options including maxInputLength
+ * @returns Exec result array, or null if input is too long or no match
+ *
+ * @example
+ * ```typescript
+ * const result = safeExec(/(\w+)/, userInput, { maxInputLength: 10000 });
+ * ```
+ */
+export declare function safeExec(pattern: RegExp, input: string, options?: SafeRegexOptions): RegExpExecArray | null;
+/**
+ * Check if input length is within safe limits for regex operations.
+ *
+ * @param input - String to check
+ * @param maxLength - Maximum allowed length
+ * @returns true if input is within limits
+ */
+export declare function isInputLengthSafe(input: string, maxLength?: number): boolean;
+export { REDOS_THRESHOLDS };

package/serialization/index.d.ts

@@ -0,0 +1 @@
+export { safeStringify } from './serialization';

package/serialization/serialization.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Safe JSON Serialization Utilities
+ *
+ * Utilities for safely serializing values to JSON, handling circular references
+ * and other edge cases that would cause JSON.stringify to fail.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Safely stringify a value, handling circular references and other edge cases.
+ *
+ * Uses a WeakSet to track visited objects and replaces circular references
+ * with the string '[Circular]' instead of throwing an error.
+ *
+ * @param value - The value to stringify
+ * @param space - Optional indentation for pretty-printing (passed to JSON.stringify)
+ * @returns JSON string representation of the value
+ *
+ * @example
+ * ```typescript
+ * // Normal object
+ * safeStringify({ name: 'test' }); // '{"name":"test"}'
+ *
+ * // Circular reference
+ * const obj = { name: 'test' };
+ * obj.self = obj;
+ * safeStringify(obj); // '{"name":"test","self":"[Circular]"}'
+ *
+ * // Pretty print
+ * safeStringify({ name: 'test' }, 2); // '{\n  "name": "test"\n}'
+ * ```
+ */
+export declare function safeStringify(value: unknown, space?: number): string;

package/storage/adapters/base.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Base Storage Adapter
+ *
+ * Abstract base class for storage adapters.
+ * Provides common validation and default implementations.
+ */
+import type { StorageAdapter, SetOptions, SetEntry, MessageHandler, Unsubscribe } from '../types';
+/**
+ * Abstract base class for storage adapters.
+ * Subclasses must implement the abstract methods.
+ */
+export declare abstract class BaseStorageAdapter implements StorageAdapter {
+    /**
+     * Backend name for error messages (e.g., 'memory', 'redis').
+     */
+    protected abstract readonly backendName: string;
+    /**
+     * Whether the adapter is currently connected.
+     */
+    protected connected: boolean;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract ping(): Promise<boolean>;
+    /**
+     * Ensure adapter is connected before operations.
+     * @throws StorageNotConnectedError if not connected
+     */
+    protected ensureConnected(): void;
+    abstract get(key: string): Promise<string | null>;
+    /**
+     * Set with validation.
+     */
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    /**
+     * Internal set implementation. Override in subclass.
+     */
+    protected abstract doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract exists(key: string): Promise<boolean>;
+    /**
+     * Default mget: sequential gets.
+     * Override for more efficient implementations.
+     */
+    mget(keys: string[]): Promise<(string | null)[]>;
+    /**
+     * Default mset: sequential sets.
+     * Override for atomic/pipelined implementations.
+     */
+    mset(entries: SetEntry[]): Promise<void>;
+    /**
+     * Default mdelete: sequential deletes.
+     * Override for more efficient implementations.
+     */
+    mdelete(keys: string[]): Promise<number>;
+    abstract expire(key: string, ttlSeconds: number): Promise<boolean>;
+    abstract ttl(key: string): Promise<number | null>;
+    abstract keys(pattern?: string): Promise<string[]>;
+    /**
+     * Default count: keys().length.
+     * Override for more efficient implementations.
+     */
+    count(pattern?: string): Promise<number>;
+    abstract incr(key: string): Promise<number>;
+    abstract decr(key: string): Promise<number>;
+    abstract incrBy(key: string, amount: number): Promise<number>;
+    /**
+     * Default: pub/sub not supported.
+     * Override in adapters that support it.
+     */
+    supportsPubSub(): boolean;
+    /**
+     * Default: throw not supported error.
+     * Override in adapters that support pub/sub.
+     */
+    publish(_channel: string, _message: string): Promise<number>;
+    /**
+     * Default: throw not supported error.
+     * Override in adapters that support pub/sub.
+     */
+    subscribe(_channel: string, _handler: MessageHandler): Promise<Unsubscribe>;
+    /**
+     * Get suggestion message for pub/sub not supported error.
+     * Override in specific adapters.
+     */
+    protected getPubSubSuggestion(): string;
+    /**
+     * Validate set options.
+     */
+    protected validateSetOptions(options?: SetOptions): void;
+}

package/storage/adapters/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Storage Adapters
+ *
+ * Export all storage adapter implementations.
+ */
+export { BaseStorageAdapter } from './base';
+export { MemoryStorageAdapter } from './memory';
+export { RedisStorageAdapter } from './redis';
+export { VercelKvStorageAdapter } from './vercel-kv';
+export { UpstashStorageAdapter } from './upstash';