/**
 * ARCHITECTURE DOCUMENTATION: HttpServer - Web Server and Real-Time Notification Hub
 * ===================================================================================
 *
 * HttpServer provides the HTTP/HTTPS server for Minecraft Creator Tools and serves as
 * a central hub for real-time client notifications via WebSocket connections. It exposes
 * REST APIs for server management and proxies events from DedicatedServer instances.
 *
 * ## Core Responsibilities
 *
 * 1. **HTTP Server**: Serves static files, API endpoints, and the web application
 * 2. **WebSocket Notifications**: Broadcasts real-time events to connected clients
 * 3. **Storage Watching**: Monitors NodeStorage for file changes and broadcasts updates
 * 4. **Authentication**: Manages session tokens and permission levels
 * 5. **MCP Server Integration**: Hosts Model Context Protocol server
 * 6. **Server Management API**: REST endpoints for controlling DedicatedServer instances
 *
 * ## API Architecture
 *
 * The HTTP server exposes REST endpoints for remote server management:
 *
 * ```
 * /api/auth              - Authentication with passcode
 * /api/<slot>/start      - Start a DedicatedServer on the specified slot
 * /api/<slot>/stop       - Stop the server on the specified slot
 * /api/<slot>/status     - Get server status and recent log messages
 * /api/<slot>/command    - Send a slash command to the server
 * /api/<slot>/deploy     - Deploy add-on content to the server
 * /api/content/<path>    - Access files when in view/edit mode
 * /api/validate          - Validate Minecraft content
 * /api/shutdown          - Graceful shutdown (view mode only)
 * /api/acceptEula        - Accept Minecraft EULA (admin only, enables BDS features)
 * /api/eulaStatus        - Check if EULA has been accepted
 * /api/commands          - List available ToolCommands
 * /api/commands/<cmd>    - Execute a ToolCommand (POST with args/flags JSON body)
 * ```
 *
 * ## Real-Time Sync Architecture
 *
 * HttpServer sits between server-side file changes and client-side updates:
 *
 * ```
 * NodeStorage (fs.watch)  ──→  HttpServer  ──→  WebSocket  ──→  HttpStorage (client)
 *      │                           │                                   │
 *      └── IStorageChangeEvent ────┘                                   │
 *                                  │                                   │
 *                   IServerNotification ─────────────────→  onFileUpdated event
 *                                                                      │
 *                                                               MCWorld ─→ WorldView
 * ```
 *
 * ## WebSocket Event Types
 *
 * The WebSocket connection broadcasts various event types to clients:
 *
 * | Event Name         | Description                                     |
 * |--------------------|-------------------------------------------------|
 * | statusUpdate       | Server status changed (starting, started, etc.)|
 * | playerJoined       | Player connected to the Minecraft server        |
 * | playerLeft         | Player disconnected from the server             |
 * | playerMoved        | Player position changed (from position polling) |
 * | storage/change     | File in watched storage was modified            |
 * | debugConnected     | Script debugger connection established          |
 * | debugStats         | Profiling statistics from script debugger       |
 * | gameEvent          | Generic game event from server                  |
 * | serverShutdown     | MCT server is shutting down (sent before close) |
 *
 * ## Storage Watcher Integration
 *
 * The server maintains watchers for NodeStorage instances and converts storage events
 * to WebSocket notifications:
 *
 * - **startWatchingStorage()**: Registers a storage for watching with a unique slot ID
 * - **stopWatchingStorage()**: Stops watching a specific storage
 * - **stopAllStorageWatchers()**: Cleanup when server stops
 * - **_handleStorageChange()**: Converts IStorageChangeEvent to IServerNotification
 *
 * ## Authentication & Permission Levels
 *
 * Four permission levels control access to different features:
 *
 * | Level              | Access                                          |
 * |--------------------|-------------------------------------------------|
 * | displayReadOnly    | View server status and logs                     |
 * | fullReadOnly       | Above + file browsing                           |
 * | updateState        | Above + start/stop servers, deploy content      |
 * | admin              | Full access including shutdown                  |
 *
 * Passcodes are set via command line and validated using encrypted tokens.
 *
 * ## SSL/TLS Support (Experimental)
 *
 * HttpServer supports experimental HTTPS via command-line configuration:
 * - Certificate and key files specified at startup
 * - Not persisted to disk for security
 * - Optional HTTPS-only mode
 *
 * ## Integration with ServerManager
 *
 * HttpServer receives events from ServerManager and converts them to notifications:
 *
 * ```
 * DedicatedServer ──► ServerManager ──► HttpServer ──► WebSocket Clients
 *       │                  │                │
 *       │                  │ bubbleServerStarted
 *       │                  │     │
 *       │                  │     └─► notify({ eventName: 'statusUpdate', ... })
 *       │                  │
 *       │                  │ bubblePlayerConnected
 *       │                  │     │
 *       │                  │     └─► notify({ eventName: 'playerJoined', ... })
 * ```
 *
 * ## Related Files
 *
 * - ServerManager.ts: Creates HttpServer and forwards server events
 * - IServerNotification.ts: Notification message types
 * - NodeStorage.ts: Server-side file watching with fs.watch()
 * - HttpStorage.ts: Client-side notification receiver
 * - IStorageWatcher.ts: Interface definitions for watcher system
 * - MinecraftMcpServer.ts: MCP server for AI tool integration
 *
 * ## Key Methods
 *
 * - init(): Initialize HTTP/HTTPS server and WebSocket
 * - stop(): Cleanup resources including storage watchers
 * - notify(): Broadcast notification to all connected WebSocket clients
 * - notifyStatusUpdate(): Send server status change to a specific slot
 * - sendNotificationToSlot(): Send notification to clients subscribed to a slot
 * - startWatchingStorage(): Begin monitoring a NodeStorage instance
 * - processRequest(): Main HTTP request handler and router
 */
import * as http from "http";
import ServerManager from "./ServerManager";
import LocalEnvironment from "./LocalEnvironment";
import NodeStorage from "./NodeStorage";
import { ServerPermissionLevel } from "./IAuthenticationToken";
import CreatorTools from "../app/CreatorTools";
import { ISlotConfig } from "../app/CreatorToolsAuthentication";
import { DedicatedServerStatus, OutputLine } from "./DedicatedServer";
import IStorage from "../storage/IStorage";
import ISslConfig from "./ISslConfig";
import { IServerNotification, IServerNotificationBody } from "./IServerNotification";
export interface CartoServerAuthenticationResponse {
    token?: string;
    iv?: string;
    authTag?: string;
    permissionLevel: ServerPermissionLevel;
    serverStatus: CartoServerStatusResponse[];
    /** Whether the Minecraft EULA has been accepted (required for BDS features) */
    eulaAccepted?: boolean;
}
export interface CartoServerStatusResponse {
    id: number;
    status?: DedicatedServerStatus;
    time: number;
    /** Recent log messages from the server */
    recentMessages?: OutputLine[];
    /** Slot configuration - included in initial auth response */
    slotConfig?: ISlotConfig;
    /** World ID currently associated with this slot */
    worldId?: string;
}
export default class HttpServer {
    host: string;
    port: number;
    creatorTools: CreatorTools | undefined;
    headers: {
        "Access-Control-Allow-Origin": string;
        "Access-Control-Allow-Methods": string;
        "Access-Control-Max-Age": number;
        "Access-Control-Allow-Headers": string;
        "Access-Control-Allow-Credentials": string;
    };
    private _webStorage;
    private _resStorage;
    private _dataStorage;
    private _distStorage;
    private _schemasStorage;
    private _formsStorage;
    private _esbuildWasmStorage;
    private _serverManager;
    private _localEnvironment;
    private _algorithm;
    private _httpsServer;
    private _httpServer;
    private _mcpServer;
    private _pwdHash;
    private _isListeningMetaFlag;
    private _readyResolvers;
    /**
     * Returns true if the HTTP server is actually listening and accepting connections.
     * This checks the underlying server state, not just the flag.
     */
    get isListening(): boolean;
    /**
     * Returns a promise that resolves when the server is ready to accept connections.
     * If the server is already listening, resolves immediately.
     * @param timeoutMs Optional timeout in milliseconds. If provided and the server
     *   doesn't become ready in time, the promise rejects with a timeout error.
     */
    waitForReady(timeoutMs?: number): Promise<void>;
    /**
     * Called when the server starts listening to mark it as ready and resolve any pending waiters.
     */
    private _markAsListening;
    private _sslConfig?;
    get sslConfig(): ISslConfig | undefined;
    set sslConfig(config: ISslConfig | undefined);
    private _tempContent;
    private _contentStorage;
    private _contentPath;
    private _isViewMode;
    private _isEditMode;
    private _mcpRequireAuth;
    private _mcpServerInitPromise;
    private _wsServer;
    private _wsClients;
    private _storageWatchers;
    private _slotStorages;
    private static readonly BLOCKED_FILE_NAMES;
    private static readonly SAFE_EXTENSIONS;
    /** Whether local res/ storage includes the vanilla serve folder with PNG textures */
    private _hasLocalVanillaServe;
    constructor(localEnv: LocalEnvironment, serverManager: ServerManager);
    init(): void;
    /**
     * Initialize HTTPS server with experimental SSL configuration.
     * SSL config is passed via command line arguments - nothing is persisted.
     */
    private initHttps;
    /**
     * Build HTTPS server options from experimental SSL configuration.
     */
    private buildHttpsOptions;
    /**
     * Initialize WebSocket server for pushing notifications to clients.
     * The WebSocket server shares the HTTP server and handles upgrade requests to /ws/notifications.
     */
    private initWebSocketServer;
    /**
     * Authenticate a WebSocket upgrade request.
     * Returns the permission level if authenticated, undefined otherwise.
     *
     * Requires a valid auth token via query string (?token=...) or mctauth cookie.
     * Localhost connections are NOT exempted — all WebSocket clients must authenticate.
     */
    private authenticateWebSocketRequest;
    /**
     * Handle a new WebSocket connection.
     */
    private handleWebSocketConnection;
    /**
     * Handle incoming WebSocket message (subscription requests).
     */
    private handleWebSocketMessage;
    /**
     * Validate an encrypted auth token and return the permission level.
     */
    private validateToken;
    /**
     * Broadcast a notification to all subscribed WebSocket clients.
     * @param notification The notification to broadcast
     */
    broadcastNotification(notification: IServerNotification): void;
    /**
     * Create and broadcast a notification.
     * Helper method for common notification patterns.
     */
    notify(body: IServerNotificationBody): void;
    /**
     * Notify clients of a file change in world content.
     */
    notifyFileChange(eventName: "fileChanged" | "fileAdded" | "fileRemoved", slot: number, category: "behavior_packs" | "resource_packs" | "world", path: string): void;
    /**
     * Notify clients of a server state change.
     */
    notifyServerState(slot: number, state: "starting" | "started" | "stopping" | "stopped" | "error", message?: string): void;
    /**
     * Notify clients of a player movement.
     */
    notifyPlayerMoved(slot: number, playerName: string, position: {
        x: number;
        y: number;
        z: number;
    }, rotation?: {
        yaw: number;
        pitch: number;
    }, dimension?: string): void;
    /**
     * Forward a game event from Minecraft to WebSocket clients.
     */
    notifyGameEvent(slot: number, minecraftEventName: string, data: object): void;
    /**
     * Notify clients of a full status update for a server slot.
     * This replaces the need for polling /api/{slot}/status/
     *
     * @param slot The server slot number
     * @param status The current DedicatedServerStatus value
     * @param recentMessages Recent messages from the server
     * @param title Optional server title
     */
    notifyStatusUpdate(slot: number, status: number, recentMessages?: Array<{
        message: string;
        received: number;
        type?: number;
    }>, title?: string): void;
    /**
     * Start watching a NodeStorage for file changes and broadcast them via WebSocket.
     * This enables real-time synchronization of file changes to connected clients.
     *
     * @param storage The NodeStorage to watch
     * @param slot The server slot number this storage is associated with
     * @param category The category of content (behavior_packs, resource_packs, world)
     */
    startWatchingStorage(storage: NodeStorage, slot: number, category: "behavior_packs" | "resource_packs" | "world"): void;
    /**
     * Stop watching a specific storage.
     */
    stopWatchingStorage(storage: NodeStorage): void;
    /**
     * Stop watching all storages.
     */
    stopAllStorageWatchers(): void;
    /**
     * Handle a storage change event and broadcast it to WebSocket clients.
     */
    private _handleStorageChange;
    stop(reason?: string): Promise<void>;
    private _salt;
    getPasswordHash(): Buffer<ArrayBufferLike>;
    getSalt(): Buffer<ArrayBufferLike>;
    /**
     * Generates a generic fingerprint hash for token binding.
     * Uses partial IP and browser family to balance security with usability.
     *
     * Note: This is intentionally "soft" binding - we only use partial IP
     * to avoid breaking sessions for mobile users while still providing
     * some protection against token theft across different networks.
     */
    generateFingerprint(userAgent?: string, ipAddress?: string): string;
    /**
     * Validates that a token fingerprint matches current request.
     * Uses timing-safe comparison to prevent timing attacks.
     */
    validateFingerprint(storedFingerprint: string, currentFingerprint: string): boolean;
    /**
     * Gets the expected session ID for a given permission level.
     * Used to validate that tokens were issued for the current server session.
     * This prevents replay attacks with tokens from previous server restarts.
     */
    getExpectedSessionIdForPermission(permissionLevel: ServerPermissionLevel): string | undefined;
    getAllowedCorsOrigins(): string[];
    /**
     * Check if an origin is allowed for CORS.
     * Allows any localhost/127.0.0.1 port for development convenience.
     */
    isOriginAllowed(origin: string | undefined): boolean;
    getCorsHeaders(req: http.IncomingMessage): {
        [key: string]: string;
    };
    /**
     * Register temporary content to be served at a specific path.
     * Useful for serving project-specific content for headless rendering.
     * @param urlPath The URL path to serve (e.g., "/temp/geometry.json")
     * @param content The content to serve (string for JSON/text, Uint8Array for binary)
     * @param contentType The content type (e.g., "application/json", "image/png")
     */
    registerTempContent(urlPath: string, content: string | Uint8Array, contentType: string): void;
    /**
     * Unregister temporary content.
     * @param urlPath The URL path to remove
     */
    unregisterTempContent(urlPath: string): void;
    /**
     * Clear all temporary content.
     */
    clearTempContent(): void;
    /**
     * Set the content path for serving local files via /api/content.
     * Used by the 'view' command to serve Minecraft content for browsing.
     * @param contentPath Absolute path to the local folder to serve
     */
    setContentPath(contentPath: string): void;
    /**
     * Get the content path if set.
     */
    getContentPath(): string | undefined;
    /**
     * Set whether the server is running in "view" mode.
     * When true, enables the /api/shutdown endpoint for graceful shutdown.
     */
    setViewMode(isViewMode: boolean): void;
    /**
     * Check if the server is running in view mode.
     */
    isViewMode(): boolean;
    /**
     * Set whether the server is running in "edit" mode.
     * When true, enables write operations (PUT/DELETE) on /api/content endpoints.
     * Edit mode also enables view mode features like /api/shutdown.
     */
    setEditMode(isEditMode: boolean): void;
    /**
     * Check if the server is running in edit mode.
     */
    isEditMode(): boolean;
    /**
     * Set whether MCP requires authentication even from localhost.
     * When false (default), localhost requests to /mcp bypass authentication.
     * When true, all /mcp requests must authenticate via passcode or session token.
     */
    setMcpRequireAuth(requireAuth: boolean): void;
    /**
     * Handles an MCP request by lazily initializing the MCP server and delegating.
     * Sets CORS headers before handing off to the MCP transport, which manages
     * its own response headers (the SDK's StreamableHTTPServerTransport).
     */
    private _handleMcpRequest;
    /**
     * Check if a file name is safe to serve (not in blocked list and has safe extension).
     */
    private isFileSafeToServe;
    /**
     * Check if a folder name is safe to traverse (not hidden or blocked).
     */
    private isFolderSafeToServe;
    getRootPath(): string;
    /**
     * Get the path to the res/ folder, checking both the default location
     * and the public/ folder for development environments.
     *
     * The serve vanilla folder (with PNG-converted textures) is often only
     * available under public/res/ — not under toolbuild/jsn/res/. This method
     * checks multiple candidate paths to find the one that actually contains
     * vanilla resource data.
     */
    getResRootPath(): string;
    /**
     * Check if a URL path is for vanilla resources (under /res/latest/van/)
     */
    isVanillaResourcePath(urlPath: string): boolean;
    parseCookies(req: http.IncomingMessage): {
        [name: string]: string;
    };
    processRequest(req: http.IncomingMessage, res: http.ServerResponse): void;
    getStatus(portOrSlot: number, includeConfig?: boolean): CartoServerStatusResponse;
    /**
     * Handle requests to /api/content/* for serving local Minecraft content.
     * Generates synthetic index.json files for folders and serves safe file types.
     * In edit mode, also handles PUT (create/update), DELETE, and POST (mkdir) operations.
     */
    private handleContentRequest;
    /**
     * Generate and serve a synthetic index.json for a folder.
     */
    private serveContentFolderListing;
    /**
     * Serve a file from the content storage.
     */
    private serveContentFile;
    /**
     * Handle requests to /api/worldContent/{slot}/* for serving dedicated server world content.
     * This endpoint exposes a virtualized view of the server's content folders:
     * - /api/worldContent/{slot}/behavior_packs/ -> development_behavior_packs
     * - /api/worldContent/{slot}/resource_packs/ -> development_resource_packs
     * - /api/worldContent/{slot}/world/ -> worlds/defaultWorld
     *
     * The slot parameter is the port number of the dedicated server.
     */
    private handleWorldContentRequest;
    /**
     * Serve the root listing of world content categories.
     */
    private serveWorldContentRootListing;
    /**
     * Serve a folder listing for world content.
     */
    private serveWorldContentFolderListing;
    /**
     * Serve a file from world content.
     */
    private serveWorldContentFile;
    /**
     * Handle PUT requests to /api/content/* for creating or updating files.
     * Requires edit mode and updateState permission.
     */
    private handleContentPut;
    /**
     * Handle DELETE requests to /api/content/* for deleting files.
     * Requires edit mode and updateState permission.
     */
    private handleContentDelete;
    /**
     * Handle POST requests to /api/content/* for creating directories or other actions.
     * Requires edit mode and updateState permission.
     */
    private handleContentPost;
    /**
     * Read the full request body as a Buffer.
     */
    private readRequestBody;
    sendErrorRequest(statusCode: number, message: string, req: http.IncomingMessage, res: http.ServerResponse): void;
    hasPermissionLevel(currentPermLevel: ServerPermissionLevel, requiredPermissionLevel: ServerPermissionLevel, req: http.IncomingMessage, res: http.ServerResponse): boolean;
    serveContent(baseSegment: string, relativeUrl: string, storage: IStorage, res: http.ServerResponse): Promise<void>;
    encrypt(text: string): {
        iv: string;
        content: string;
        authTag: string;
    };
    decrypt(iv: string, content: string, authTag?: string): string;
    getMimeTypeForFile(extension: string): "application/json" | "application/zip" | "image/jpeg" | "image/png" | "image/svg+xml" | "image/x-icon" | "text/css" | "text/javascript" | "font/woff" | "font/woff2" | "font/ttf";
    /**
     * Escapes a string for safe inclusion in HTML/JavaScript.
     * Prevents XSS attacks from user-controlled content.
     */
    private escapeForHtml;
    /**
     * Escapes a string for safe inclusion in a JavaScript string literal.
     */
    private escapeForJs;
    /**
     * Handle upload requests with lazy server initialization.
     * This allows edit/view modes to deploy content to BDS without requiring
     * the server to be pre-configured on startup.
     *
     * The server will be lazily initialized when the first deploy is attempted.
     */
    private handleUploadWithLazyInit;
    /**
     * Handle POST /api/{slot}/stop - Stop the server on a specific slot.
     */
    private handleSlotStop;
    /**
     * Handle POST /api/{slot}/restart - Restart the server on a specific slot.
     */
    private handleSlotRestart;
    /**
     * Handle requests to /api/worlds/* endpoints.
     * Provides CRUD operations for managed worlds and their backups.
     *
     * Endpoints:
     * GET  /api/worlds - List all managed worlds
     * POST /api/worlds - Create a new managed world
     * GET  /api/worlds/{id} - Get world info
     * DELETE /api/worlds/{id} - Delete a world (requires admin)
     * GET  /api/worlds/{id}/backups - List backups for a world
     * POST /api/worlds/{id}/backups - Create a new backup (with source slot)
     * GET  /api/worlds/{id}/backups/{timestamp} - Get backup info
     * DELETE /api/worlds/{id}/backups/{timestamp} - Delete a backup
     * POST /api/worlds/{id}/backups/{timestamp}/restore - Restore backup to slot
     * GET  /api/worlds/{id}/backups/{timestamp}/export - Export as .mcworld
     */
    private handleWorldsRequest;
    /**
     * Read request body as JSON with size limit and error handling.
     */
    private readRequestBodyJson;
    /**
     * Handle /api/commands/* endpoints for invoking ToolCommands via REST API.
     *
     * Endpoints:
     * GET  /api/commands - List available commands
     * POST /api/commands/{commandName} - Execute a command
     *
     * Request body for POST (JSON):
     * {
     *   "args": ["arg1", "arg2"],
     *   "flags": { "session": "mySession", "traits": ["tameable"] }
     * }
     *
     * Response (JSON):
     * {
     *   "success": true/false,
     *   "message": "...",
     *   "data": { ... },
     *   "error": { "code": "...", "message": "..." }
     * }
     */
    private handleCommandsRequest;
    getMainContent(req: http.IncomingMessage): string;
}