@frontmcp/utils 0.0.1 → 0.7.1

package/crypto/secret-persistence/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Secret persistence utilities for storing encryption secrets.
+ *
+ * Provides a secure way to persist secrets to disk for development environments.
+ * In production, use environment variables instead.
+ *
+ * @module @frontmcp/utils/secret-persistence
+ *
+ * @example
+ * ```typescript
+ * import { getOrCreateSecret } from '@frontmcp/utils';
+ *
+ * // Get or create a persisted secret
+ * const secret = await getOrCreateSecret({
+ *   name: 'remember',
+ *   secretPath: '.frontmcp/remember-secret.json',
+ * });
+ *
+ * // Use the secret for encryption
+ * const key = await deriveKey(secret);
+ * ```
+ */
+export type { SecretData, SecretPersistenceOptions, SecretValidationResult } from './types';
+export { secretDataSchema, validateSecretData, parseSecretData } from './schema';
+export { isSecretPersistenceEnabled, resolveSecretPath, loadSecret, saveSecret, deleteSecret, generateSecret, createSecretData, getOrCreateSecret, clearCachedSecret, isSecretCached, } from './persistence';

package/crypto/secret-persistence/persistence.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Secret persistence utilities for storing encryption secrets.
+ *
+ * Follows the same pattern as OAuth JWK dev-key-persistence for consistency.
+ * Stores a random secret to a JSON file for use when no environment variable is set.
+ *
+ * This enables development environments to have consistent encryption keys
+ * without requiring manual configuration.
+ *
+ * @module @frontmcp/utils/secret-persistence
+ */
+import type { SecretData, SecretPersistenceOptions } from './types';
+/**
+ * Check if secret persistence is enabled based on environment and options.
+ *
+ * By default, persistence is:
+ * - Enabled in development (NODE_ENV !== 'production')
+ * - Disabled in production unless forceEnable is true
+ *
+ * @param options - Persistence options
+ * @returns true if persistence is enabled
+ */
+export declare function isSecretPersistenceEnabled(options?: SecretPersistenceOptions): boolean;
+/**
+ * Resolve the secret file path.
+ *
+ * @param options - Persistence options
+ * @returns Absolute path to secret file
+ */
+export declare function resolveSecretPath(options?: SecretPersistenceOptions): string;
+/**
+ * Load persisted secret from file.
+ *
+ * @param options - Persistence options
+ * @returns The loaded secret data or null if not found/invalid
+ */
+export declare function loadSecret(options?: SecretPersistenceOptions): Promise<SecretData | null>;
+/**
+ * Save secret to file.
+ *
+ * Uses atomic write (temp file + rename) to prevent corruption.
+ * Sets file permissions to 0o600 (owner read/write only) for security.
+ *
+ * @param secretData - Secret data to persist
+ * @param options - Persistence options
+ * @returns true if save succeeded, false otherwise
+ */
+export declare function saveSecret(secretData: SecretData, options?: SecretPersistenceOptions): Promise<boolean>;
+/**
+ * Delete persisted secret.
+ *
+ * @param options - Persistence options
+ * @returns true if deleted or didn't exist, false on error
+ */
+export declare function deleteSecret(options?: SecretPersistenceOptions): Promise<boolean>;
+/**
+ * Generate a new random secret.
+ *
+ * @param bytes - Number of random bytes (default 32 = 256 bits)
+ * @returns Base64url-encoded random string
+ */
+export declare function generateSecret(bytes?: number): string;
+/**
+ * Create a new secret data object with current timestamp.
+ *
+ * @param options - Options including secret bytes
+ * @returns New SecretData object
+ */
+export declare function createSecretData(options?: SecretPersistenceOptions): SecretData;
+/**
+ * Get or create a persisted secret.
+ *
+ * This is the main entry point for getting a secret.
+ * It will:
+ * 1. Return cached secret if available (for this name)
+ * 2. Load from file if exists
+ * 3. Generate new secret and persist it
+ *
+ * Thread-safe: concurrent calls will share the same generation promise.
+ *
+ * @param options - Persistence options
+ * @returns The secret string
+ */
+export declare function getOrCreateSecret(options?: SecretPersistenceOptions): Promise<string>;
+/**
+ * Clear the cached secret (for testing).
+ *
+ * @param options - Options to identify which secret to clear (by path)
+ */
+export declare function clearCachedSecret(options?: SecretPersistenceOptions): void;
+/**
+ * Check if a secret is cached.
+ *
+ * @param options - Options to identify which secret to check
+ * @returns true if cached
+ */
+export declare function isSecretCached(options?: SecretPersistenceOptions): boolean;

package/crypto/secret-persistence/schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Validation schema for secret data.
+ *
+ * @module @frontmcp/utils/secret-persistence
+ */
+import { z } from 'zod';
+import type { SecretData, SecretValidationResult } from './types';
+/**
+ * Zod schema for SecretData.
+ */
+export declare const secretDataSchema: z.ZodObject<{
+    secret: z.ZodString;
+    createdAt: z.ZodNumber;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Validate secret data structure.
+ *
+ * Checks:
+ * - Schema validation
+ * - createdAt is not in the future (with 1 minute drift allowance)
+ * - createdAt is not too old (100 years)
+ *
+ * @param data - Data to validate
+ * @returns Validation result
+ */
+export declare function validateSecretData(data: unknown): SecretValidationResult;
+/**
+ * Parse and validate secret data.
+ *
+ * @param data - Raw data to parse
+ * @returns Parsed secret data or null if invalid
+ */
+export declare function parseSecretData(data: unknown): SecretData | null;

package/crypto/secret-persistence/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Types for secret persistence utilities.
+ *
+ * @module @frontmcp/utils/secret-persistence
+ */
+/**
+ * Data structure for a persisted secret.
+ */
+export interface SecretData {
+    /** Random secret, base64url encoded (typically 32 bytes = 256 bits) */
+    secret: string;
+    /** Creation timestamp (ms since epoch) */
+    createdAt: number;
+    /** Version for future migrations */
+    version: number;
+}
+/**
+ * Options for secret persistence operations.
+ */
+export interface SecretPersistenceOptions {
+    /**
+     * Path to store the secret file.
+     * If relative, resolved from current working directory.
+     * @default '.frontmcp/<name>-secret.json'
+     */
+    secretPath?: string;
+    /**
+     * Secret name used in default path and log messages.
+     * @default 'default'
+     */
+    name?: string;
+    /**
+     * Enable persistence in production (NOT RECOMMENDED for multi-server).
+     * In production, use environment variables instead.
+     * @default false
+     */
+    forceEnable?: boolean;
+    /**
+     * Number of bytes to generate for new secrets.
+     * @default 32 (256 bits)
+     */
+    secretBytes?: number;
+    /**
+     * Enable logging of persistence operations.
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Custom logger for persistence messages.
+     * Defaults to console.warn/console.error.
+     */
+    logger?: {
+        warn: (message: string) => void;
+        error: (message: string) => void;
+    };
+}
+/**
+ * Result of validating secret data.
+ */
+export interface SecretValidationResult {
+    /** Whether the secret data is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}

package/crypto/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Crypto Provider Types
+ *
+ * Defines the interface for cryptographic operations that work across
+ * Node.js and browser environments.
+ */
+/**
+ * Encrypted blob structure for AES-256-GCM encryption.
+ * All fields are base64url encoded.
+ */
+export interface EncBlob {
+    alg: 'A256GCM';
+    iv: string;
+    tag: string;
+    data: string;
+}
+/**
+ * Crypto provider interface for cross-platform cryptographic operations.
+ * All operations are synchronous for consistency across platforms.
+ */
+export interface CryptoProvider {
+    /**
+     * Generate a UUID v4 string.
+     */
+    randomUUID(): string;
+    /**
+     * Generate cryptographically secure random bytes.
+     */
+    randomBytes(length: number): Uint8Array;
+    /**
+     * Compute SHA-256 hash.
+     */
+    sha256(data: string | Uint8Array): Uint8Array;
+    /**
+     * Compute SHA-256 hash and return as hex string.
+     */
+    sha256Hex(data: string | Uint8Array): string;
+    /**
+     * Compute HMAC-SHA256.
+     */
+    hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
+    /**
+     * HKDF-SHA256 key derivation (RFC 5869).
+     */
+    hkdfSha256(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Uint8Array;
+    /**
+     * Encrypt using AES-256-GCM.
+     */
+    encryptAesGcm(key: Uint8Array, plaintext: Uint8Array, iv: Uint8Array): {
+        ciphertext: Uint8Array;
+        tag: Uint8Array;
+    };
+    /**
+     * Decrypt using AES-256-GCM.
+     */
+    decryptAesGcm(key: Uint8Array, ciphertext: Uint8Array, iv: Uint8Array, tag: Uint8Array): Uint8Array;
+    /**
+     * Constant-time comparison to prevent timing attacks.
+     */
+    timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+}

package/escape/escape.d.ts

@@ -0,0 +1,101 @@
+/**
+ * HTML and JavaScript Escaping Utilities
+ *
+ * Functions for escaping strings to prevent XSS attacks in HTML output.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Escape HTML special characters to prevent XSS.
+ *
+ * Handles null/undefined by returning empty string.
+ * Converts non-string values to string before escaping.
+ *
+ * @param str - Value to escape (will be converted to string)
+ * @returns Escaped string safe for HTML content
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>')
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ *
+ * escapeHtml(null)  // Returns: ''
+ * escapeHtml(123)   // Returns: '123'
+ * ```
+ */
+export declare function escapeHtml(str: unknown): string;
+/**
+ * Escape string for use in HTML attributes.
+ *
+ * Lighter version that only escapes & and " characters,
+ * suitable for attribute values that are already quoted.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for HTML attributes
+ *
+ * @example
+ * ```typescript
+ * escapeHtmlAttr('value with "quotes" & ampersand')
+ * // Returns: 'value with &quot;quotes&quot; &amp; ampersand'
+ * ```
+ */
+export declare function escapeHtmlAttr(str: string): string;
+/**
+ * Escape string for use in JavaScript string literals.
+ *
+ * Escapes characters that could break out of a JS string context.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for JS string literals
+ *
+ * @example
+ * ```typescript
+ * escapeJsString("it's a \"test\"")
+ * // Returns: "it\\'s a \\\"test\\\""
+ * ```
+ */
+export declare function escapeJsString(str: string): string;
+/**
+ * Escape script closing tags in JSON strings to prevent XSS.
+ *
+ * When embedding JSON in a <script> tag, the string `</script>` will
+ * prematurely close the script block. This function escapes the closing
+ * tag by replacing `</` with `<\/`.
+ *
+ * @param jsonString - JSON string (already passed through JSON.stringify)
+ * @returns Escaped JSON string safe for embedding in script tags
+ *
+ * @example
+ * ```typescript
+ * const json = JSON.stringify({ html: '</script><script>alert(1)</script>' });
+ * escapeScriptClose(json);
+ * // Returns: '{"html":"<\\/script><script>alert(1)<\\/script>"}'
+ * ```
+ */
+export declare function escapeScriptClose(jsonString: string): string;
+/**
+ * Safely serialize a value to JSON for embedding in HTML <script> tags.
+ *
+ * Combines JSON.stringify with escapeScriptClose to prevent XSS attacks
+ * where malicious data contains `</script>` or other HTML-sensitive sequences.
+ *
+ * Handles edge cases:
+ * - undefined: Returns 'null' (since undefined is not valid JSON)
+ * - Circular references: Returns error placeholder
+ * - BigInt: Converted to string representation
+ * - Functions/Symbols: Omitted (standard JSON.stringify behavior)
+ *
+ * @param value - Value to serialize
+ * @returns Escaped JSON string safe for embedding in script tags
+ *
+ * @example
+ * ```typescript
+ * const data = { html: '</script><script>alert("xss")</script>' };
+ * const safe = safeJsonForScript(data);
+ * // Returns: '{"html":"<\\/script><script>alert(\\"xss\\")<\\/script>"}'
+ *
+ * // Safe to use in:
+ * // <script>const data = ${safeJsonForScript(data)};</script>
+ * ```
+ */
+export declare function safeJsonForScript(value: unknown): string;

package/escape/index.d.ts

@@ -0,0 +1 @@
+export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';