mcp-server-framework 1.0.0

package/build/config/env.js

@@ -0,0 +1,441 @@
+/**
+ * Framework Environment Configuration
+ *
+ * Environment variables for the generic MCP server framework.
+ * These settings are NOT application-specific and apply to any MCP server
+ * built with this framework.
+ *
+ * @module config/env
+ */
+import { z } from "zod";
+import { booleanFromEnv, optionalCommaSeparatedList, commaSeparatedList, byteSizeSchema, } from "../utils/zod-helpers.js";
+import { BYTE_SIZE_REGEX } from "../utils/string-helpers.js";
+import { readFileSync, accessSync, constants as fsConstants } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// ============================================================================
+// Version Resolution
+// ============================================================================
+/** Path to baked-in VERSION file (created during Docker build) */
+const VERSION_FILE_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "VERSION");
+/**
+ * Resolve application version from available sources.
+ *
+ * Single Source of Truth: package.json
+ *
+ * Resolution:
+ * - Docker: Reads from build/VERSION (baked in from package.json during build)
+ * - npm run: Uses npm_package_version (injected by npm from package.json)
+ *
+ * @returns Version string or 'unknown' if resolution fails
+ */
+function resolveVersion() {
+    // Docker: VERSION file is baked in during build
+    try {
+        return readFileSync(VERSION_FILE_PATH, "utf-8").trim();
+    }
+    catch (_) {
+        // Not running in Docker container — VERSION file doesn't exist
+    }
+    // npm run: npm injects version from package.json
+    return process.env.npm_package_version ?? "unknown";
+}
+/** Cached version - resolved once at module load */
+const VERSION = resolveVersion();
+// ============================================================================
+// Schema Definition
+// ============================================================================
+/**
+ * Framework environment schema - application-agnostic settings.
+ *
+ * Includes:
+ * - Application metadata (version, environment)
+ * - MCP Transport settings (host, port, transport mode)
+ * - Security settings (DNS rebinding protection, rate limiting)
+ * - Logging configuration
+ * - OpenTelemetry settings
+ */
+export const frameworkEnvSchema = z
+    .object({
+    // ==========================================================================
+    // Application Metadata
+    // ==========================================================================
+    /**
+     * Application version (resolved at module load).
+     *
+     * Source of Truth: package.json
+     * - Docker: build/VERSION file (baked in during build)
+     * - npm run: npm_package_version environment variable
+     */
+    VERSION: z.string().default(VERSION),
+    /** Node environment (development, production, test) */
+    NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+    // ==========================================================================
+    // MCP Transport Settings
+    // ==========================================================================
+    /** Host to bind the MCP server to (default: 127.0.0.1) */
+    MCP_BIND_HOST: z.string().min(1).default("127.0.0.1"),
+    /** Port to listen on (default: 8000) */
+    MCP_PORT: z.coerce.number().int().min(1).max(65535).default(8000),
+    /** Transport mode: 'stdio' for CLI, 'http' for HTTP, 'https' for HTTPS with TLS (default: http) */
+    MCP_TRANSPORT: z.enum(["stdio", "http", "https"]).default("stdio"),
+    /**
+     * Enable Legacy SSE Transport (deprecated HTTP+SSE from protocol 2024-11-05)
+     * Default: false (only Streamable HTTP Transport enabled)
+     * Set to 'true' to enable backwards compatibility with older MCP clients
+     */
+    MCP_LEGACY_SSE_ENABLED: booleanFromEnv(false),
+    /**
+     * Operate in stateless mode (no session IDs).
+     *
+     * Each request gets a fresh McpSession and SDK transport.
+     * No Mcp-Session-Id headers are set. GET and DELETE return 405.
+     *
+     * @default false (stateful mode)
+     */
+    MCP_STATELESS: booleanFromEnv(false),
+    /**
+     * Prefer JSON responses over SSE streams for simple request-response.
+     *
+     * When enabled, the SDK returns `application/json` for non-streaming
+     * responses (e.g. tools/list, resources/list) instead of wrapping them
+     * in a `text/event-stream` SSE envelope.
+     *
+     * The MCP specification recommends: "If the server is only sending one
+     * response with no notifications, it SHOULD prefer application/json."
+     *
+     * Streaming responses (progress, notifications) always use SSE regardless.
+     *
+     * @default true (spec-compliant JSON responses)
+     */
+    MCP_JSON_RESPONSE: booleanFromEnv(true),
+    // ==========================================================================
+    // TLS Configuration (HTTPS mode)
+    // ==========================================================================
+    /** Path to TLS certificate file (PEM format). Required when MCP_TRANSPORT='https'. */
+    MCP_TLS_CERT_PATH: z.string().min(1).optional(),
+    /** Path to TLS private key file (PEM format). Required when MCP_TRANSPORT='https'. */
+    MCP_TLS_KEY_PATH: z.string().min(1).optional(),
+    /** Path to CA certificate file (PEM format). Optional for custom CA chains. */
+    MCP_TLS_CA_PATH: z.string().min(1).optional(),
+    // ==========================================================================
+    // Security Settings
+    // ==========================================================================
+    /** Allowed hosts for DNS rebinding protection (comma-separated) */
+    MCP_ALLOWED_HOSTS: optionalCommaSeparatedList(),
+    /** Rate limit window in milliseconds (default: 900000 = 15 minutes) */
+    MCP_RATE_LIMIT_WINDOW_MS: z.coerce.number().int().min(1000).default(900000),
+    /** Maximum requests per rate limit window (default: 1000) */
+    MCP_RATE_LIMIT_MAX: z.coerce.number().int().min(100).default(1000),
+    /**
+     * Maximum request body size for `express.json()` middleware.
+     *
+     * Accepts Express size strings (e.g. `'1mb'`, `'500kb'`, `'2mb'`)
+     * or plain byte counts (e.g. `'1048576'`).
+     *
+     * Validated against the `bytes` library format used by Express/body-parser.
+     * Invalid values are rejected at config time to prevent silent limit bypass.
+     *
+     * @default '1mb'
+     */
+    MCP_BODY_SIZE_LIMIT: z
+        .string()
+        .regex(BYTE_SIZE_REGEX, 'Invalid body size format. Use formats like "1mb", "500kb", "2gb", or a plain byte count like "1048576".')
+        .default("1mb"),
+    /**
+     * Trust proxy setting for Express.
+     *
+     * Required when running behind a reverse proxy (nginx, Traefik, cloud LB)
+     * to correctly resolve client IPs, protocol, and host from proxy headers
+     * (`X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`).
+     *
+     * Values:
+     * - Hop count (`'1'`, `'2'`) — Trust N hops from the front-facing proxy
+     * - Express keyword (`'loopback'`, `'linklocal'`, `'uniquelocal'`)
+     * - IP address (`'10.0.0.1'`, `'::1'`)
+     * - CIDR range (`'10.0.0.0/8'`, `'172.16.0.0/12'`)
+     * - DNS hostname (`'proxy.example.com'`) — resolved at startup
+     * - Comma-separated list (`'loopback, 10.0.0.1'`)
+     *
+     * Omit or leave unset to disable trust proxy.
+     *
+     * @see https://expressjs.com/en/guide/behind-proxies.html
+     */
+    MCP_TRUST_PROXY: z.string().min(1).optional(),
+    /**
+     * CORS allowed origins (comma-separated).
+     *
+     * When set, the CORS middleware is mounted globally and allows requests
+     * from the listed origins. When unset, CORS is disabled (no CORS headers).
+     *
+     * Use `'*'` to allow all origins (not recommended for production).
+     *
+     * @example 'https://app.example.com,https://admin.example.com'
+     */
+    MCP_CORS_ORIGIN: optionalCommaSeparatedList(),
+    /**
+     * Allow credentials in CORS requests (cookies, auth headers).
+     *
+     * Only effective when MCP_CORS_ORIGIN is set.
+     * Cannot be used with `origin: '*'`.
+     *
+     * @default false
+     */
+    MCP_CORS_CREDENTIALS: booleanFromEnv(false),
+    /**
+     * Enable HTTP Strict Transport Security (HSTS) header.
+     *
+     * When true, Helmet sets `Strict-Transport-Security` with `max-age=15552000`
+     * (180 days) and `includeSubDomains`. Only enable when serving over HTTPS.
+     *
+     * @default false (managed by reverse proxy in production)
+     */
+    MCP_HELMET_HSTS: booleanFromEnv(false),
+    /**
+     * Content Security Policy configuration.
+     *
+     * - Omit or leave unset: Helmet default CSP applies
+     * - `'false'`: Disable CSP entirely
+     * - Custom string: Used as CSP directives (e.g. `"default-src 'self'"`).
+     *   Parsed as directive-name + values separated by semicolons.
+     */
+    MCP_HELMET_CSP: z.string().min(1).optional(),
+    /**
+     * X-Frame-Options header value.
+     *
+     * Controls whether the server can be embedded in frames.
+     * - `'DENY'`: Never allow framing (most secure)
+     * - `'SAMEORIGIN'`: Allow framing from same origin
+     * - `'false'`: Disable X-Frame-Options header
+     *
+     * @default 'DENY'
+     */
+    MCP_HELMET_FRAME_OPTIONS: z.enum(["DENY", "SAMEORIGIN", "false"]).default("DENY"),
+    // ==========================================================================
+    // Authentication
+    // ==========================================================================
+    /**
+     * Required OAuth scopes for the `/mcp` endpoint (comma-separated).
+     *
+     * When set, all requests to `/mcp` must carry tokens with these scopes.
+     * Per-tool scopes can be configured via `ToolDefinition.auth.requiredScopes`.
+     *
+     * @example 'mcp:read,mcp:write'
+     */
+    MCP_AUTH_REQUIRED_SCOPES: optionalCommaSeparatedList(),
+    /**
+     * Protected Resource Metadata URL (RFC 9728).
+     *
+     * When set, included in `WWW-Authenticate` headers for 401 responses,
+     * allowing clients to discover the authorization server.
+     *
+     * @example 'https://api.example.com/.well-known/oauth-protected-resource'
+     */
+    MCP_AUTH_RESOURCE_METADATA_URL: z.string().url().optional(),
+    // ==========================================================================
+    // Session Management
+    // ==========================================================================
+    /** Maximum total concurrent sessions across all transports (default: 200) */
+    MCP_MAX_SESSIONS: z.coerce.number().int().min(1).default(200),
+    /** Maximum concurrent Streamable HTTP sessions (default: 100) */
+    MCP_MAX_STREAMABLE_HTTP_SESSIONS: z.coerce.number().int().min(1).default(100),
+    /** Maximum concurrent SSE sessions (default: 50) */
+    MCP_MAX_SSE_SESSIONS: z.coerce.number().int().min(1).default(50),
+    // ==========================================================================
+    // Logging Configuration
+    // ==========================================================================
+    /** Log level (trace, debug, info, warn, error) */
+    LOG_LEVEL: z.enum(["trace", "debug", "info", "warn", "error"]).default("info"),
+    /** Log format (text, json) */
+    LOG_FORMAT: z.enum(["text", "json"]).default("text"),
+    /** Include RFC 3339 timestamps in text log output (default: false) */
+    LOG_TIMESTAMP: booleanFromEnv(false),
+    /** Include component name (e.g. [server-runtime]) in text log output (default: false) */
+    LOG_COMPONENT: booleanFromEnv(false),
+    /** Directory to store logs (optional) */
+    LOG_DIR: z.string().min(1).optional(),
+    /**
+     * Maximum size of a single log file before rotation.
+     *
+     * Accepts human-readable size strings (e.g. `'10mb'`, `'500kb'`, `'1gb'`)
+     * or plain byte counts (e.g. `'1048576'`). Parsed to bytes at config time.
+     *
+     * @default '10mb'
+     */
+    LOG_MAX_FILE_SIZE: byteSizeSchema("10mb").pipe(z.number().int().min(1024)),
+    /** Maximum number of rotated log files to keep (default: 3) */
+    LOG_MAX_FILES: z.coerce.number().int().min(1).max(100).default(3),
+    /** Log file retention in days. Files older than this are deleted. 0 = disabled (default: 0) */
+    LOG_RETENTION_DAYS: z.coerce.number().int().min(0).default(0),
+    // ==========================================================================
+    // OpenTelemetry Configuration
+    //
+    // Standard OTEL env vars are parsed here so they can also be set via
+    // the config file. The SDK and exporters would read these from process.env
+    // natively, but routing them through the config system ensures a single
+    // source of truth and enables config-file-based setup.
+    // See: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+    // ==========================================================================
+    /** Enable OpenTelemetry (default: false). Master toggle for all OTEL features. */
+    OTEL_ENABLED: booleanFromEnv(false),
+    /**
+     * OpenTelemetry service name.
+     *
+     * When not set, defaults to the MCP server name from `createServer({ name })`.
+     * Can be overridden via env var or config file to distinguish deployments
+     * (e.g. 'app-mcp-prod' vs 'app-mcp-staging').
+     *
+     * Also read natively by the SDK's resource detector via OTEL_SERVICE_NAME.
+     */
+    OTEL_SERVICE_NAME: z.string().min(1).optional(),
+    /**
+     * OTLP exporter endpoint URL (e.g. http://localhost:4318).
+     *
+     * Used by both trace and metric OTLP exporters.
+     * Standard OTEL env var — also read natively by exporters,
+     * but parsed here to enable config file support.
+     */
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
+    /**
+     * Trace exporter selection.
+     *
+     * Standard OTEL env var. When set, the framework builds the
+     * trace exporter explicitly instead of leaving it to SDK auto-config.
+     * Supported: 'otlp' , 'console', 'none' (default).
+     */
+    OTEL_TRACES_EXPORTER: z.string().min(1).optional(),
+    /**
+     * Log exporter selection.
+     *
+     * Standard OTEL env var. Controls whether the NodeSDK auto-configures
+     * an OTLP log exporter. The framework uses its own logging system
+     * (see {@link Logger | framework logger}), so OTEL log export is disabled
+     * by default to prevent unwanted OTLP connections.
+     *
+     * Supported: 'otlp', 'console', 'none' (default).
+     */
+    OTEL_LOGS_EXPORTER: z.string().default("none"),
+    /**
+     * SDK diagnostic log level.
+     *
+     * Standard OTEL env var. Activates diag logging on the OTEL SDK.
+     * Values: 'NONE', 'ERROR', 'WARN', 'INFO', 'DEBUG', 'VERBOSE', 'ALL'.
+     */
+    OTEL_LOG_LEVEL: z.string().min(1).optional(),
+    /**
+     * Periodic metric export interval in milliseconds.
+     *
+     * Standard OTEL env var name. Controls how often PeriodicExportingMetricReader
+     * pushes metrics to the OTLP endpoint or console.
+     */
+    OTEL_METRIC_EXPORT_INTERVAL: z.coerce.number().int().positive().optional(),
+    /**
+     * Metric exporters to activate (comma-separated).
+     *
+     * Standard OTEL env var name. Supported values:
+     * - `otlp` — Push metrics to OTLP endpoint (reads OTEL_EXPORTER_OTLP_ENDPOINT natively)
+     * - `prometheus` — Prometheus scrape endpoint at /metrics on the MCP server
+     * - `console` — Log metrics to console (useful for debugging)
+     * - `none` — Disable all metric export
+     *
+     * Default: 'otlp,prometheus' (both OTLP push + Prometheus pull)
+     */
+    OTEL_METRICS_EXPORTER: commaSeparatedList({ lowercase: true }).default("otlp,prometheus"),
+})
+    .superRefine((data, ctx) => {
+    // Validate TLS configuration when HTTPS mode is selected
+    // Delegates to the shared constraint validator so the same rules
+    // apply regardless of config source (env, file, programmatic).
+    const violations = validateConfigConstraints(data);
+    for (const violation of violations) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: violation.message,
+            path: [...violation.path],
+        });
+    }
+});
+/**
+ * Validate cross-field constraints on the framework configuration.
+ *
+ * Extracted as a standalone function so it can be called:
+ * 1. By the Zod schema's `superRefine` (env-only parsing)
+ * 2. By the config cache after merging all sources (env + file + overrides)
+ *
+ * @param config - The (potentially merged) configuration to validate
+ * @returns Array of constraint violations (empty = valid)
+ */
+export function validateConfigConstraints(config) {
+    const violations = [];
+    // TLS constraint: HTTPS requires both cert and key paths
+    if (config.MCP_TRANSPORT === "https") {
+        if (!config.MCP_TLS_CERT_PATH) {
+            violations.push({
+                message: 'MCP_TLS_CERT_PATH is required when MCP_TRANSPORT is "https"',
+                path: ["MCP_TLS_CERT_PATH"],
+            });
+        }
+        if (!config.MCP_TLS_KEY_PATH) {
+            violations.push({
+                message: 'MCP_TLS_KEY_PATH is required when MCP_TRANSPORT is "https"',
+                path: ["MCP_TLS_KEY_PATH"],
+            });
+        }
+        // Validate TLS file existence and readability when paths are provided
+        if (config.MCP_TLS_CERT_PATH) {
+            try {
+                accessSync(config.MCP_TLS_CERT_PATH, fsConstants.R_OK);
+            }
+            catch {
+                violations.push({
+                    message: `TLS certificate file not found or not readable: ${config.MCP_TLS_CERT_PATH}`,
+                    path: ["MCP_TLS_CERT_PATH"],
+                });
+            }
+        }
+        if (config.MCP_TLS_KEY_PATH) {
+            try {
+                accessSync(config.MCP_TLS_KEY_PATH, fsConstants.R_OK);
+            }
+            catch {
+                violations.push({
+                    message: `TLS private key file not found or not readable: ${config.MCP_TLS_KEY_PATH}`,
+                    path: ["MCP_TLS_KEY_PATH"],
+                });
+            }
+        }
+        if (config.MCP_TLS_CA_PATH) {
+            try {
+                accessSync(config.MCP_TLS_CA_PATH, fsConstants.R_OK);
+            }
+            catch {
+                violations.push({
+                    message: `TLS CA certificate file not found or not readable: ${config.MCP_TLS_CA_PATH}`,
+                    path: ["MCP_TLS_CA_PATH"],
+                });
+            }
+        }
+    }
+    // Session limit hierarchy: transport-specific limits must not exceed the global limit
+    const transportSum = config.MCP_MAX_STREAMABLE_HTTP_SESSIONS + config.MCP_MAX_SSE_SESSIONS;
+    if (transportSum > config.MCP_MAX_SESSIONS) {
+        violations.push({
+            message: `MCP_MAX_STREAMABLE_HTTP_SESSIONS (${config.MCP_MAX_STREAMABLE_HTTP_SESSIONS}) + ` +
+                `MCP_MAX_SSE_SESSIONS (${config.MCP_MAX_SSE_SESSIONS}) = ${transportSum} exceeds ` +
+                `MCP_MAX_SESSIONS (${config.MCP_MAX_SESSIONS})`,
+            path: ["MCP_MAX_SESSIONS", "MCP_MAX_STREAMABLE_HTTP_SESSIONS", "MCP_MAX_SSE_SESSIONS"],
+        });
+    }
+    return violations;
+}
+/**
+ * Parse and validate an environment source against the framework schema.
+ *
+ * @param envSource - Key-value object to parse (defaults to `process.env`)
+ * @returns Validated framework configuration
+ * @internal Used only by config-cache.ts — consumers should use `getFrameworkConfig()`
+ */
+export function parseFrameworkEnv(envSource = process.env) {
+    return frameworkEnvSchema.parse(envSource);
+}
+//# sourceMappingURL=env.js.map

package/build/config/env.js.map

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

package/build/config/extensions.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Config Extensions
+ *
+ * Allows consumer projects to register custom config sections that
+ * are recognized during config file loading and validated with
+ * consumer-provided Zod schemas.
+ *
+ * This enables consumer-specific config file sections (e.g., `[myapp]`)
+ * without the framework warning about "unknown sections".
+ *
+ * @example
+ * ```typescript
+ * import { registerConfigSection, getAppConfig, z } from 'mcp-server-framework';
+ *
+ * // Register a custom section with a Zod schema
+ * registerConfigSection('myapp', z.object({
+ *   url: z.string().url(),
+ *   timeout_ms: z.number().int().positive().optional(),
+ * }));
+ *
+ * // After config is loaded, retrieve the validated section data
+ * const appConfig = getAppConfig<{ url: string; timeout_ms?: number }>('myapp');
+ * ```
+ *
+ * @module config/extensions
+ */
+import type { ZodTypeAny } from "zod";
+/**
+ * Register a custom config section for consumer use.
+ *
+ * Must be called **before** config initialization (i.e., before the
+ * first call to `getFrameworkConfig()`). Registered sections:
+ *
+ * 1. Are recognized in config files (no "unknown section" warning)
+ * 2. Are validated against the provided Zod schema
+ * 3. Can be retrieved via `getAppConfig(name)`
+ *
+ * @param name - Section name as it appears in the config file (e.g., 'myapp')
+ * @param schema - Zod schema to validate the section data
+ * @throws {ConfigurationError} If the section name is reserved, already registered,
+ *   or config has already been initialized
+ *
+ * @example
+ * ```typescript
+ * registerConfigSection('myapp', z.object({
+ *   url: z.string().url(),
+ *   api_key: z.string().optional(),
+ * }));
+ * ```
+ */
+export declare function registerConfigSection(name: string, schema: ZodTypeAny): void;
+/**
+ * Retrieve the validated data for a registered config section.
+ *
+ * Returns `undefined` if:
+ * - The section was not present in the config file
+ * - Config has not been loaded yet
+ *
+ * @param name - Section name (case-insensitive)
+ * @returns The validated section data, or `undefined`
+ *
+ * @example
+ * ```typescript
+ * interface MyAppConfig {
+ *   url: string;
+ *   timeout_ms?: number;
+ * }
+ * const config = getAppConfig<MyAppConfig>('myapp');
+ * if (config) {
+ *   console.log(config.url);
+ * }
+ * ```
+ */
+export declare function getAppConfig<T = unknown>(name: string): T | undefined;
+/**
+ * Get all registered consumer section names.
+ *
+ * Used by the config file loader to recognize consumer sections
+ * and suppress "unknown section" warnings.
+ *
+ * @internal
+ */
+export declare function getRegisteredSectionNames(): ReadonlySet<string>;
+/**
+ * Get the Zod schema for a registered section.
+ *
+ * @internal
+ */
+export declare function getRegisteredSectionSchema(name: string): ZodTypeAny | undefined;
+/**
+ * Store validated data for a registered section.
+ *
+ * Called by the config file loader after parsing and validating
+ * a consumer section from the config file.
+ *
+ * @internal
+ */
+export declare function setRegisteredSectionData(name: string, data: unknown): void;
+/**
+ * Reset all registered config sections.
+ *
+ * Intended for testing — clears all registrations and data.
+ *
+ * @internal
+ */
+export declare function resetConfigExtensions(): void;
+//# sourceMappingURL=extensions.d.ts.map

package/build/config/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/config/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAmCtC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAoB5E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAIrE;AAMD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,CAAC,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAK1E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}