@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/security/idGenerator.js

@@ -0,0 +1,301 @@
+/**
+ * @fileoverview Provides a utility class `IdGenerator` for creating customizable, prefixed unique identifiers,
+ * and a standalone `generateUUID` function for generating standard UUIDs.
+ * The `IdGenerator` supports entity-specific prefixes, custom character sets, and lengths.
+ *
+ * Note: Logging has been removed from this module to prevent circular dependencies
+ * with the `requestContextService`, which itself uses `generateUUID` from this module.
+ * This was causing `ReferenceError: Cannot access 'generateUUID' before initialization`
+ * during application startup.
+ * @module src/utils/security/idGenerator
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+/**
+ * Returns cryptographically secure random bytes using the Web Crypto API (`crypto.getRandomValues`).
+ * Available in Node.js 19+, Cloudflare Workers, and browsers — no Node.js-specific imports needed.
+ * @param count - Number of random bytes to generate.
+ * @returns A `Uint8Array` of `count` random bytes.
+ */
+function getRandomBytes(count) {
+    const bytes = new Uint8Array(count);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export class IdGenerator {
+    /**
+     * Default character set for the random part of the ID.
+     * @private
+     */
+    static DEFAULT_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    /**
+     * Default separator character between prefix and random part.
+     * @private
+     */
+    static DEFAULT_SEPARATOR = '_';
+    /**
+     * Default length for the random part of the ID.
+     * @private
+     */
+    static DEFAULT_LENGTH = 6;
+    /**
+     * Stores the mapping of entity types to their prefixes.
+     * @private
+     */
+    entityPrefixes = {};
+    /**
+     * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+     * @private
+     */
+    prefixToEntityType = {};
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes = {}) {
+        // Logging removed to prevent circular dependency with requestContextService.
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal reverse lookup map.
+     * @param entityPrefixes - A map where keys are entity type names and values are their desired ID prefixes.
+     */
+    setEntityPrefixes(entityPrefixes) {
+        // Logging removed.
+        this.entityPrefixes = { ...entityPrefixes };
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix.toLowerCase()] = type; // Store lowercase for case-insensitive lookup
+            return acc;
+        }, {});
+    }
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random string.
+     * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
+     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @returns The generated random string.
+     */
+    generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        let result = '';
+        // Determine the largest multiple of charset.length that is less than or equal to 256
+        // This is the threshold for rejection sampling to avoid bias.
+        const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
+        while (result.length < length) {
+            const byteBuffer = getRandomBytes(1);
+            const byte = byteBuffer[0];
+            // If the byte is within the valid range (i.e., it won't introduce bias),
+            // use it to select a character from the charset. Otherwise, discard and try again.
+            if (byte !== undefined && byte < maxValidByteValue) {
+                const charIndex = byte % charset.length;
+                const char = charset[charIndex];
+                if (char) {
+                    result += char;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Generates a unique ID, optionally prepended with a prefix.
+     * @param prefix - An optional prefix for the ID.
+     * @param options - Optional parameters for ID generation (length, separator, charset).
+     * @returns A unique identifier string.
+     */
+    generate(prefix, options = {}) {
+        // Logging removed.
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, } = options;
+        const randomPart = this.generateRandomString(length, charset);
+        const generatedId = prefix ? `${prefix}${separator}${randomPart}` : randomPart;
+        return generatedId;
+    }
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * @param entityType - The type of entity (must be registered).
+     * @param options - Optional parameters for ID generation.
+     * @returns A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered.
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Unknown entity type: ${entityType}. No prefix registered.`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if an ID conforms to the expected format for a specific entity type.
+     * @param id - The ID string to validate.
+     * @param entityType - The expected entity type of the ID.
+     * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, // Use charset from options or default
+         } = options;
+        if (!prefix) {
+            return false;
+        }
+        // Build regex character class from the charset
+        // Escape characters that have special meaning inside a regex character class `[]`
+        const escapedCharsetForClass = charset.replace(/[[\]\\^-]/g, '\\$&');
+        const charsetRegexPart = `[${escapedCharsetForClass}]`;
+        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}${charsetRegexPart}{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * Strips the prefix and separator from an ID string, returning only the random part.
+     * If the separator does not appear in the string, the original ID is returned unchanged.
+     * Handles edge cases where the separator character appears in the random part by
+     * rejoining all parts after the first split.
+     *
+     * @param id - The full ID string (e.g., `"PROJ_A6B3J0"`).
+     * @param separator - The separator character used in the ID. Defaults to `'_'`.
+     * @returns The random part of the ID without the prefix (e.g., `"A6B3J0"`), or the
+     *   original string if the separator is not present.
+     *
+     * @example
+     * ```ts
+     * idGenerator.stripPrefix('PROJ_A6B3J0');         // → 'A6B3J0'
+     * idGenerator.stripPrefix('PROJ-A6B3J0', '-');    // → 'A6B3J0'
+     * idGenerator.stripPrefix('NOPREFIXID');           // → 'NOPREFIXID'
+     * ```
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        return parts.length > 1 ? parts.slice(1).join(separator) : id; // Handle separators in random part
+    }
+    /**
+     * Determines the entity type from an ID string by its prefix (case-insensitive).
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The determined entity type.
+     * @throws {McpError} If ID format is invalid or prefix is unknown.
+     */
+    getEntityType(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        if (parts.length < 2 || !parts[0]) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Invalid ID format: ${id}. Expected format like: PREFIX${separator}RANDOMPART`);
+        }
+        const prefix = parts[0];
+        const entityType = this.prefixToEntityType[prefix.toLowerCase()];
+        if (!entityType) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Unknown entity type for prefix: ${prefix}`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID so that the prefix matches its registered casing and the random
+     * part is uppercased. Delegates to {@link getEntityType} to resolve the canonical prefix.
+     *
+     * Note: Uppercasing the random part is correct for the default `A-Z0-9` charset. For custom
+     * charsets that include lowercase or non-alphabetic characters, `toUpperCase()` may produce
+     * unexpected results.
+     *
+     * @param id - The ID to normalize (e.g., `"proj_a6b3j0"`).
+     * @param separator - The separator used in the ID. Defaults to `'_'`.
+     * @returns The normalized ID with canonical prefix casing and uppercase random part
+     *   (e.g., `"PROJ_A6B3J0"`).
+     * @throws {McpError} With {@link JsonRpcErrorCode.ValidationError} if the entity type
+     *   cannot be determined from the ID's prefix.
+     *
+     * @example
+     * ```ts
+     * idGenerator.setEntityPrefixes({ project: 'PROJ' });
+     * idGenerator.normalize('proj_a6b3j0'); // → 'PROJ_A6B3J0'
+     * idGenerator.normalize('PROJ_a6b3j0'); // → 'PROJ_A6B3J0'
+     * ```
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const entityType = this.getEntityType(id, separator);
+        const registeredPrefix = this.entityPrefixes[entityType];
+        const idParts = id.split(separator);
+        const randomPart = idParts.slice(1).join(separator);
+        // Consider if randomPart.toUpperCase() is always correct for custom charsets.
+        // For now, maintaining existing behavior.
+        return `${registeredPrefix}${separator}${randomPart.toUpperCase()}`;
+    }
+}
+/**
+ * Default singleton instance of {@link IdGenerator}, initialized with no entity prefixes.
+ * Call `idGenerator.setEntityPrefixes({ ... })` during application startup to register prefixes
+ * before calling `generateForEntity` or `getEntityType`.
+ */
+export const idGenerator = new IdGenerator();
+/**
+ * Generates a standard Version 4 UUID using the Web Crypto API (`crypto.randomUUID()`).
+ * Cross-runtime: works in Node.js 19+, Cloudflare Workers, and browsers.
+ *
+ * @returns A new UUID v4 string (e.g., `"110e8400-e29b-41d4-a716-446655440000"`).
+ *
+ * @example
+ * ```ts
+ * const id = generateUUID(); // → '110e8400-e29b-41d4-a716-446655440000'
+ * ```
+ */
+export const generateUUID = () => crypto.randomUUID();
+/**
+ * Generates a short, human-readable request context ID in the format `XXXXX-XXXXX`
+ * (two 5-character alphanumeric segments joined by a hyphen, e.g., `"A3K9Z-BQ72M"`).
+ *
+ * This function is self-contained — it does not call `IdGenerator` or any other module-level
+ * export — specifically to avoid circular dependencies with `requestContextService`, which
+ * itself calls this function during initialization.
+ *
+ * Uses rejection sampling against the Web Crypto API for uniform, bias-free character selection.
+ *
+ * @returns A 11-character string in `XXXXX-XXXXX` format suitable for request tracing.
+ *
+ * @example
+ * ```ts
+ * const reqId = generateRequestContextId(); // → 'A3K9Z-BQ72M'
+ * ```
+ */
+export const generateRequestContextId = () => {
+    /**
+     * Generates a cryptographically secure random string of a given length from a given charset.
+     * @param length The desired length of the string.
+     * @param charset The characters to use for generation.
+     * @returns The generated random string.
+     */
+    const generateSecureRandomString = (length, charset) => {
+        let result = '';
+        const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
+        while (result.length < length) {
+            const byteBuffer = getRandomBytes(1);
+            const byte = byteBuffer[0];
+            if (byte !== undefined && byte < maxValidByteValue) {
+                const charIndex = byte % charset.length;
+                const char = charset[charIndex];
+                if (char) {
+                    result += char;
+                }
+            }
+        }
+        return result;
+    };
+    const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    const part1 = generateSecureRandomString(5, charset);
+    const part2 = generateSecureRandomString(5, charset);
+    return `${part1}-${part2}`;
+};
+//# sourceMappingURL=idGenerator.js.map

package/dist/utils/security/idGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idGenerator.js","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"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"}

package/dist/utils/security/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel export for security utilities.
+ * @module utils/security
+ */
+export { type EntityPrefixConfig, generateRequestContextId, generateUUID, type IdGenerationOptions, IdGenerator, idGenerator, } from './idGenerator.js';
+export { type RateLimitConfig, type RateLimitEntry, RateLimiter } from './rateLimiter.js';
+export { type HtmlSanitizeConfig, type PathSanitizeOptions, Sanitization, type SanitizedPathInfo, type SanitizeStringOptions, sanitization, sanitizeInputForLogging, } from './sanitization.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/security/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,wBAAwB,EACxB,YAAY,EACZ,KAAK,mBAAmB,EACxB,WAAW,EACX,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,YAAY,EACZ,uBAAuB,GACxB,MAAM,mBAAmB,CAAC"}

package/dist/utils/security/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel export for security utilities.
+ * @module utils/security
+ */
+export { generateRequestContextId, generateUUID, IdGenerator, idGenerator, } from './idGenerator.js';
+export { RateLimiter } from './rateLimiter.js';
+export { Sanitization, sanitization, sanitizeInputForLogging, } from './sanitization.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/security/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,wBAAwB,EACxB,YAAY,EAEZ,WAAW,EACX,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAA6C,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAGL,YAAY,EAGZ,YAAY,EACZ,uBAAuB,GACxB,MAAM,mBAAmB,CAAC"}

package/dist/utils/security/rateLimiter.d.ts

@@ -0,0 +1,171 @@
+import type { config as ConfigType } from '../../config/index.js';
+import type { logger as LoggerType } from '../../utils/internal/logger.js';
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Defines configuration options for the {@link RateLimiter}.
+ */
+export interface RateLimitConfig {
+    /** How often, in milliseconds, to clean up expired entries. */
+    cleanupInterval?: number;
+    /** Custom error message template. Can include `{waitTime}` placeholder. */
+    errorMessage?: string;
+    /** Optional function to generate a custom key for rate limiting. */
+    keyGenerator?: (identifier: string, context?: RequestContext) => string;
+    /** Maximum number of requests allowed in the window. */
+    maxRequests: number;
+    /** Maximum number of tracked keys. When exceeded, oldest entries are evicted (LRU). Default: 10000 */
+    maxTrackedKeys?: number;
+    /** If true, skip rate limiting in development. */
+    skipInDevelopment?: boolean;
+    /** Time window in milliseconds. */
+    windowMs: number;
+}
+/**
+ * Represents an individual entry for tracking requests against a rate limit key.
+ */
+export interface RateLimitEntry {
+    /** Current request count. */
+    count: number;
+    /** Last access timestamp for LRU eviction. */
+    lastAccess: number;
+    /** When the window resets (timestamp in milliseconds). */
+    resetTime: number;
+}
+/**
+ * A configurable, in-process rate limiter that enforces request quotas per key within a sliding
+ * time window. Tracks request counts in a `Map`, evicts least-recently-used entries when the
+ * tracked-key cap is reached, and periodically cleans up expired windows via a background timer.
+ *
+ * Throws {@link McpError} with {@link JsonRpcErrorCode.RateLimited} when the limit is exceeded.
+ * Integrates with OpenTelemetry by annotating the active span with rate-limit attributes.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(config, logger);
+ * limiter.configure({ maxRequests: 60, windowMs: 60_000 });
+ *
+ * // In a request handler:
+ * limiter.check(clientId, requestContext); // throws McpError if over limit
+ * ```
+ */
+export declare class RateLimiter {
+    private config;
+    private logger;
+    private readonly limits;
+    private cleanupTimer;
+    private readonly effectiveConfig;
+    /**
+     * Creates a new `RateLimiter` instance with sensible defaults:
+     * - 100 requests per 15-minute window
+     * - 5-minute cleanup interval
+     * - Up to 10,000 tracked keys (LRU eviction beyond that)
+     *
+     * Call {@link configure} to override any of these defaults before first use.
+     *
+     * @param config - Application config, used to check `environment` when `skipInDevelopment` is set.
+     * @param logger - Logger instance for debug output on cleanup and eviction events.
+     */
+    constructor(config: typeof ConfigType, logger: typeof LoggerType);
+    /**
+     * Evicts the least recently used entry from the limits Map.
+     * This prevents unbounded memory growth in high-traffic scenarios.
+     * @private
+     */
+    private evictLRUEntry;
+    /**
+     * Starts (or restarts) the periodic cleanup interval using the current `cleanupInterval` config.
+     * Clears any existing timer first. The timer is unref'd so it does not prevent Node.js from exiting.
+     * No-ops if `cleanupInterval` is 0 or unset.
+     * @private
+     */
+    private startCleanupTimer;
+    /**
+     * Iterates all tracked entries and deletes any whose `resetTime` has passed.
+     * Called automatically by the cleanup timer. Logs the number of removed entries at debug level.
+     * @private
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Merges the provided partial config into the current effective configuration.
+     * If `cleanupInterval` is included, the background timer is restarted with the new interval.
+     *
+     * @param config - Partial {@link RateLimitConfig} fields to apply.
+     *
+     * @example
+     * ```ts
+     * limiter.configure({ maxRequests: 30, windowMs: 60_000, skipInDevelopment: true });
+     * ```
+     */
+    configure(config: Partial<RateLimitConfig>): void;
+    /**
+     * Returns a shallow copy of the current effective {@link RateLimitConfig}.
+     *
+     * @returns A copy of the active rate limit configuration.
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Clears all tracked rate limit entries, effectively resetting every key's counter.
+     * Useful for testing or emergency bypass scenarios.
+     */
+    reset(): void;
+    /**
+     * Checks whether the given key has exceeded its rate limit and throws if so.
+     *
+     * On each call:
+     * 1. No-ops if `skipInDevelopment` is `true` and `config.environment === 'development'`.
+     * 2. Resolves the effective key via `keyGenerator` if configured, otherwise uses `key` as-is.
+     * 3. Creates a new window entry on first call or after the previous window expired.
+     *    If the tracked-key cap is reached, the least-recently-used entry is evicted first.
+     * 4. Increments the count and updates the LRU timestamp.
+     * 5. If count exceeds `maxRequests`, throws {@link McpError} with {@link JsonRpcErrorCode.RateLimited}
+     *    and error data containing `waitTimeSeconds`, `key`, `limit`, and `windowMs`.
+     *
+     * The active OpenTelemetry span is annotated with rate-limit attributes on every call.
+     *
+     * @param key - The identifier to rate-limit (e.g., a client ID, IP address, or tool name).
+     * @param context - Optional request context passed to the `keyGenerator`, if configured.
+     * @throws {McpError} With code {@link JsonRpcErrorCode.RateLimited} when the limit is exceeded.
+     *
+     * @example
+     * ```ts
+     * // Basic usage
+     * rateLimiter.check('client-abc');
+     *
+     * // With request context for custom key generation
+     * rateLimiter.check('client-abc', requestContext);
+     * ```
+     */
+    check(key: string, context?: RequestContext): void;
+    /**
+     * Returns the current rate limit status for a given key, or `null` if the key is not tracked
+     * (i.e., no requests have been made in the current window).
+     *
+     * Note: This method does **not** apply the `keyGenerator` — pass the already-resolved key
+     * if a custom generator is configured.
+     *
+     * @param key - The rate limit key to query.
+     * @returns An object with `current` count, configured `limit`, `remaining` requests, and
+     *   `resetTime` (ms epoch when the window resets), or `null` if the key has no active entry.
+     *
+     * @example
+     * ```ts
+     * const status = rateLimiter.getStatus('client-abc');
+     * if (status) {
+     *   console.log(`${status.remaining} requests remaining, resets at ${new Date(status.resetTime)}`);
+     * }
+     * ```
+     */
+    getStatus(key: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    } | null;
+    /**
+     * Stops the background cleanup timer and clears all tracked entries.
+     * Should be called during application shutdown to allow the process to exit cleanly
+     * (even though the timer is unref'd, explicit disposal is good practice).
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/utils/security/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../../src/utils/security/rateLimiter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAEhG;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACxE,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IAiBpB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IAjBhB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAElD;;;;;;;;;;OAUG;gBAEO,MAAM,EAAE,OAAO,UAAU,EACzB,MAAM,EAAE,OAAO,UAAU;IAenC;;;;OAIG;IACH,OAAO,CAAC,aAAa;IA2BrB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;;;;;;;;;OAUG;IACI,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IAOxD;;;;OAIG;IACI,SAAS,IAAI,eAAe;IAInC;;;OAGG;IACI,KAAK,IAAI,IAAI;IAQpB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IAmEzD;;;;;;;;;;;;;;;;;;OAkBG;IACI,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG;QAC7B,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAWR;;;;OAIG;IACI,OAAO,IAAI,IAAI;CAOvB"}