@minecraft-docker/mcctl-api 1.7.6

package/dist/plugins/auth.js

@@ -0,0 +1,194 @@
+import fp from 'fastify-plugin';
+import bcrypt from 'bcrypt';
+import ipRangeCheck from 'ip-range-check';
+// ============================================================
+// Plugin Implementation
+// ============================================================
+const authPlugin = async (fastify, opts) => {
+    const { config } = opts;
+    // Validate config based on mode
+    validateAuthConfig(config);
+    // Decorate fastify with auth utilities
+    fastify.decorate('authConfig', config);
+    fastify.decorate('isAuthenticated', false);
+    // Default excluded paths
+    const excludedPaths = new Set(config.excludePaths ?? ['/health', '/health/']);
+    // Skip authentication if disabled
+    if (config.mode === 'disabled') {
+        fastify.log.warn('Authentication is DISABLED. This should only be used in development!');
+        return;
+    }
+    // Add preHandler hook for authentication
+    fastify.addHook('preHandler', async (request, reply) => {
+        // Skip authentication for excluded paths
+        if (excludedPaths.has(request.url)) {
+            return;
+        }
+        // Normalize URL for path matching (remove query string)
+        const urlPath = request.url.split('?')[0] ?? request.url;
+        if (excludedPaths.has(urlPath)) {
+            return;
+        }
+        try {
+            await authenticate(request, reply, config, fastify);
+        }
+        catch (error) {
+            if (error instanceof AuthError) {
+                reply.code(error.statusCode).send({
+                    error: error.name,
+                    message: error.message,
+                });
+                return reply;
+            }
+            throw error;
+        }
+    });
+};
+// ============================================================
+// Authentication Logic
+// ============================================================
+class AuthError extends Error {
+    statusCode;
+    constructor(message, statusCode = 401) {
+        super(message);
+        this.name = 'AuthenticationError';
+        this.statusCode = statusCode;
+    }
+}
+async function authenticate(request, _reply, config, fastify) {
+    switch (config.mode) {
+        case 'api-key':
+            await authenticateApiKey(request, config, fastify);
+            break;
+        case 'ip-whitelist':
+            await authenticateIpWhitelist(request, config, fastify);
+            break;
+        case 'basic':
+            await authenticateBasic(request, config, fastify);
+            break;
+        case 'combined':
+            await authenticateCombined(request, config, fastify);
+            break;
+        default:
+            throw new AuthError('Invalid authentication mode', 500);
+    }
+}
+async function authenticateApiKey(request, config, fastify) {
+    const apiKey = request.headers['x-api-key'];
+    if (!apiKey) {
+        throw new AuthError('Missing X-API-Key header');
+    }
+    if (apiKey !== config.apiKey) {
+        fastify.log.warn({ ip: getClientIp(request) }, 'Invalid API key attempt');
+        throw new AuthError('Invalid API key');
+    }
+}
+async function authenticateIpWhitelist(request, config, fastify) {
+    const clientIp = getClientIp(request);
+    const whitelist = config.ipWhitelist ?? [];
+    if (whitelist.length === 0) {
+        throw new AuthError('IP whitelist is empty', 500);
+    }
+    const isAllowed = ipRangeCheck(clientIp, whitelist);
+    if (!isAllowed) {
+        fastify.log.warn({ ip: clientIp }, 'IP not in whitelist');
+        throw new AuthError('IP address not allowed', 403);
+    }
+}
+async function authenticateBasic(request, config, fastify) {
+    const authHeader = request.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Basic ')) {
+        throw new AuthError('Missing or invalid Authorization header');
+    }
+    const base64Credentials = authHeader.substring(6);
+    const credentials = Buffer.from(base64Credentials, 'base64').toString('utf-8');
+    const [username, password] = credentials.split(':');
+    if (!username || !password) {
+        throw new AuthError('Invalid credentials format');
+    }
+    const users = config.users ?? [];
+    const user = users.find((u) => u.username === username);
+    if (!user) {
+        fastify.log.warn({ username, ip: getClientIp(request) }, 'Unknown user attempt');
+        throw new AuthError('Invalid credentials');
+    }
+    const isValid = await bcrypt.compare(password, user.passwordHash);
+    if (!isValid) {
+        fastify.log.warn({ username, ip: getClientIp(request) }, 'Invalid password attempt');
+        throw new AuthError('Invalid credentials');
+    }
+}
+async function authenticateCombined(request, config, fastify) {
+    // Both API key AND IP whitelist must pass
+    await authenticateApiKey(request, config, fastify);
+    await authenticateIpWhitelist(request, config, fastify);
+}
+// ============================================================
+// Utilities
+// ============================================================
+function getClientIp(request) {
+    // Check for forwarded headers (reverse proxy scenarios)
+    const xForwardedFor = request.headers['x-forwarded-for'];
+    if (xForwardedFor) {
+        const ips = Array.isArray(xForwardedFor) ? xForwardedFor[0] : xForwardedFor.split(',')[0];
+        if (ips) {
+            return ips.trim();
+        }
+    }
+    const xRealIp = request.headers['x-real-ip'];
+    if (xRealIp) {
+        const ip = Array.isArray(xRealIp) ? xRealIp[0] : xRealIp;
+        if (ip) {
+            return ip;
+        }
+    }
+    // Fallback to socket IP
+    return request.ip;
+}
+function validateAuthConfig(config) {
+    switch (config.mode) {
+        case 'disabled':
+            // No validation needed
+            break;
+        case 'api-key':
+            if (!config.apiKey) {
+                throw new Error('API key is required for api-key authentication mode');
+            }
+            break;
+        case 'ip-whitelist':
+            if (!config.ipWhitelist || config.ipWhitelist.length === 0) {
+                throw new Error('IP whitelist is required for ip-whitelist authentication mode');
+            }
+            break;
+        case 'basic':
+            if (!config.users || config.users.length === 0) {
+                throw new Error('Users are required for basic authentication mode');
+            }
+            break;
+        case 'combined':
+            if (!config.apiKey) {
+                throw new Error('API key is required for combined authentication mode');
+            }
+            if (!config.ipWhitelist || config.ipWhitelist.length === 0) {
+                throw new Error('IP whitelist is required for combined authentication mode');
+            }
+            break;
+        default:
+            throw new Error(`Unknown authentication mode: ${config.mode}`);
+    }
+}
+// ============================================================
+// Helper for generating password hashes
+// ============================================================
+export async function hashPassword(password, saltRounds = 10) {
+    return bcrypt.hash(password, saltRounds);
+}
+// ============================================================
+// Export
+// ============================================================
+export default fp(authPlugin, {
+    name: 'auth',
+    fastify: '5.x',
+});
+export { authPlugin, AuthError };
+//# sourceMappingURL=auth.js.map

package/dist/plugins/auth.js.map

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

package/dist/plugins/swagger.d.ts

@@ -0,0 +1,170 @@
+import { FastifyPluginAsync } from 'fastify';
+export interface SwaggerPluginOptions {
+    title?: string;
+    description?: string;
+    version?: string;
+    routePrefix?: string;
+}
+declare const swaggerPlugin: FastifyPluginAsync<SwaggerPluginOptions>;
+/**
+ * Common response schemas for reuse across routes
+ */
+export declare const commonSchemas: {
+    errorResponse: {
+        type: string;
+        properties: {
+            error: {
+                type: string;
+                description: string;
+            };
+            message: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    healthResponse: {
+        type: string;
+        properties: {
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            timestamp: {
+                type: string;
+                format: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    serverNameParam: {
+        type: string;
+        description: string;
+        pattern: string;
+        examples: string[];
+    };
+    worldNameParam: {
+        type: string;
+        description: string;
+        pattern: string;
+        examples: string[];
+    };
+    playerNameParam: {
+        type: string;
+        description: string;
+        pattern: string;
+        examples: string[];
+    };
+};
+/**
+ * Common route options for consistent error responses
+ */
+export declare const commonRouteOptions: {
+    unauthorizedResponse: {
+        description: string;
+        content: {
+            'application/json': {
+                schema: {
+                    type: string;
+                    properties: {
+                        error: {
+                            type: string;
+                            description: string;
+                        };
+                        message: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                example: {
+                    error: string;
+                    message: string;
+                };
+            };
+        };
+    };
+    forbiddenResponse: {
+        description: string;
+        content: {
+            'application/json': {
+                schema: {
+                    type: string;
+                    properties: {
+                        error: {
+                            type: string;
+                            description: string;
+                        };
+                        message: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                example: {
+                    error: string;
+                    message: string;
+                };
+            };
+        };
+    };
+    notFoundResponse: {
+        description: string;
+        content: {
+            'application/json': {
+                schema: {
+                    type: string;
+                    properties: {
+                        error: {
+                            type: string;
+                            description: string;
+                        };
+                        message: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                example: {
+                    error: string;
+                    message: string;
+                };
+            };
+        };
+    };
+    internalErrorResponse: {
+        description: string;
+        content: {
+            'application/json': {
+                schema: {
+                    type: string;
+                    properties: {
+                        error: {
+                            type: string;
+                            description: string;
+                        };
+                        message: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                example: {
+                    error: string;
+                    message: string;
+                };
+            };
+        };
+    };
+};
+declare const _default: FastifyPluginAsync<SwaggerPluginOptions>;
+export default _default;
+export { swaggerPlugin };
+//# sourceMappingURL=swagger.d.ts.map

package/dist/plugins/swagger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.d.ts","sourceRoot":"","sources":["../../src/plugins/swagger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAS9D,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,QAAA,MAAM,aAAa,EAAE,kBAAkB,CAAC,oBAAoB,CAuG3D,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwD9B,CAAC;;AAMF,wBAIG;AAEH,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/plugins/swagger.js

@@ -0,0 +1,211 @@
+import fp from 'fastify-plugin';
+import swagger from '@fastify/swagger';
+import swaggerUi from '@fastify/swagger-ui';
+// ============================================================
+// Plugin Implementation
+// ============================================================
+const swaggerPlugin = async (fastify, opts) => {
+    const { title = 'mcctl-api', description = 'REST API for managing Docker Minecraft servers', version = '0.1.0', routePrefix = '/docs', } = opts;
+    // Register Swagger (OpenAPI spec generation)
+    await fastify.register(swagger, {
+        openapi: {
+            openapi: '3.1.0',
+            info: {
+                title,
+                description,
+                version,
+                license: {
+                    name: 'Apache-2.0',
+                    url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
+                },
+                contact: {
+                    name: 'smallmiro',
+                    url: 'https://github.com/smallmiro/minecraft-server-manager',
+                },
+            },
+            externalDocs: {
+                url: 'https://minecraft-server-manager.readthedocs.io/',
+                description: 'Full documentation',
+            },
+            servers: [
+                {
+                    url: '/',
+                    description: 'Current server (relative)',
+                },
+                {
+                    url: 'http://localhost:5000',
+                    description: 'Local development server',
+                },
+                {
+                    url: 'http://192.168.20.37:5000',
+                    description: 'LAN server',
+                },
+            ],
+            tags: [
+                { name: 'health', description: 'Health check endpoints' },
+                { name: 'servers', description: 'Minecraft server management' },
+                { name: 'console', description: 'RCON console access' },
+                { name: 'worlds', description: 'World management' },
+                { name: 'players', description: 'Player management' },
+            ],
+            components: {
+                securitySchemes: {
+                    apiKey: {
+                        type: 'apiKey',
+                        name: 'X-API-Key',
+                        in: 'header',
+                        description: 'API key for authentication',
+                    },
+                    basicAuth: {
+                        type: 'http',
+                        scheme: 'basic',
+                        description: 'Basic HTTP authentication',
+                    },
+                },
+            },
+            security: [{ apiKey: [] }],
+        },
+    });
+    // Register Swagger UI
+    await fastify.register(swaggerUi, {
+        routePrefix,
+        uiConfig: {
+            docExpansion: 'list',
+            deepLinking: true,
+            displayRequestDuration: true,
+            filter: true,
+            showExtensions: true,
+            showCommonExtensions: true,
+            syntaxHighlight: {
+                activate: true,
+                theme: 'monokai',
+            },
+        },
+        uiHooks: {
+            onRequest: function (_request, _reply, next) {
+                next();
+            },
+            preHandler: function (_request, _reply, next) {
+                next();
+            },
+        },
+        staticCSP: false,
+        transformStaticCSP: (header) => header,
+        transformSpecification: (swaggerObject) => swaggerObject,
+        transformSpecificationClone: true,
+    });
+    fastify.log.info(`Swagger UI available at ${routePrefix}`);
+    fastify.log.info(`OpenAPI spec available at ${routePrefix}/json`);
+};
+// ============================================================
+// Common Schemas
+// ============================================================
+/**
+ * Common response schemas for reuse across routes
+ */
+export const commonSchemas = {
+    // Error response schema
+    errorResponse: {
+        type: 'object',
+        properties: {
+            error: { type: 'string', description: 'Error type' },
+            message: { type: 'string', description: 'Error message' },
+        },
+        required: ['error', 'message'],
+    },
+    // Health check response schema
+    healthResponse: {
+        type: 'object',
+        properties: {
+            status: { type: 'string', enum: ['ok'], description: 'Health status' },
+            timestamp: { type: 'string', format: 'date-time', description: 'ISO 8601 timestamp' },
+        },
+        required: ['status', 'timestamp'],
+    },
+    // Common parameters
+    serverNameParam: {
+        type: 'string',
+        description: 'Server name (without mc- prefix)',
+        pattern: '^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$',
+        examples: ['survival', 'creative', 'modded'],
+    },
+    worldNameParam: {
+        type: 'string',
+        description: 'World name',
+        pattern: '^[a-zA-Z0-9][a-zA-Z0-9_-]*$',
+        examples: ['world', 'survival_world', 'creative-world'],
+    },
+    playerNameParam: {
+        type: 'string',
+        description: 'Minecraft player name',
+        pattern: '^[a-zA-Z0-9_]{3,16}$',
+        examples: ['Notch', 'Steve', 'Alex'],
+    },
+};
+/**
+ * Common route options for consistent error responses
+ */
+export const commonRouteOptions = {
+    // 401 Unauthorized
+    unauthorizedResponse: {
+        description: 'Authentication required',
+        content: {
+            'application/json': {
+                schema: commonSchemas.errorResponse,
+                example: {
+                    error: 'AuthenticationError',
+                    message: 'Missing X-API-Key header',
+                },
+            },
+        },
+    },
+    // 403 Forbidden
+    forbiddenResponse: {
+        description: 'Access denied',
+        content: {
+            'application/json': {
+                schema: commonSchemas.errorResponse,
+                example: {
+                    error: 'AuthenticationError',
+                    message: 'IP address not allowed',
+                },
+            },
+        },
+    },
+    // 404 Not Found
+    notFoundResponse: {
+        description: 'Resource not found',
+        content: {
+            'application/json': {
+                schema: commonSchemas.errorResponse,
+                example: {
+                    error: 'NotFound',
+                    message: 'Server not found',
+                },
+            },
+        },
+    },
+    // 500 Internal Server Error
+    internalErrorResponse: {
+        description: 'Internal server error',
+        content: {
+            'application/json': {
+                schema: commonSchemas.errorResponse,
+                example: {
+                    error: 'InternalError',
+                    message: 'An unexpected error occurred',
+                },
+            },
+        },
+    },
+};
+// ============================================================
+// Export
+// ============================================================
+export default fp(swaggerPlugin, {
+    name: 'swagger',
+    fastify: '5.x',
+    dependencies: [], // No dependencies, should be registered early
+});
+export { swaggerPlugin };
+//# sourceMappingURL=swagger.js.map

package/dist/plugins/swagger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.js","sourceRoot":"","sources":["../../src/plugins/swagger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChC,OAAO,OAAO,MAAM,kBAAkB,CAAC;AACvC,OAAO,SAAS,MAAM,qBAAqB,CAAC;AAa5C,+DAA+D;AAC/D,wBAAwB;AACxB,+DAA+D;AAE/D,MAAM,aAAa,GAA6C,KAAK,EACnE,OAAwB,EACxB,IAA0B,EAC1B,EAAE;IACF,MAAM,EACJ,KAAK,GAAG,WAAW,EACnB,WAAW,GAAG,gDAAgD,EAC9D,OAAO,GAAG,OAAO,EACjB,WAAW,GAAG,OAAO,GACtB,GAAG,IAAI,CAAC;IAET,6CAA6C;IAC7C,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE;QAC9B,OAAO,EAAE;YACP,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE;gBACJ,KAAK;gBACL,WAAW;gBACX,OAAO;gBACP,OAAO,EAAE;oBACP,IAAI,EAAE,YAAY;oBAClB,GAAG,EAAE,kDAAkD;iBACxD;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,WAAW;oBACjB,GAAG,EAAE,uDAAuD;iBAC7D;aACF;YACD,YAAY,EAAE;gBACZ,GAAG,EAAE,kDAAkD;gBACvD,WAAW,EAAE,oBAAoB;aAClC;YACD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,GAAG;oBACR,WAAW,EAAE,2BAA2B;iBACzC;gBACD;oBACE,GAAG,EAAE,uBAAuB;oBAC5B,WAAW,EAAE,0BAA0B;iBACxC;gBACD;oBACE,GAAG,EAAE,2BAA2B;oBAChC,WAAW,EAAE,YAAY;iBAC1B;aACF;YACD,IAAI,EAAE;gBACJ,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE;gBACzD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,6BAA6B,EAAE;gBAC/D,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,qBAAqB,EAAE;gBACvD,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE;gBACnD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,mBAAmB,EAAE;aACtD;YACD,UAAU,EAAE;gBACV,eAAe,EAAE;oBACf,MAAM,EAAE;wBACN,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,WAAW;wBACjB,EAAE,EAAE,QAAQ;wBACZ,WAAW,EAAE,4BAA4B;qBAC1C;oBACD,SAAS,EAAE;wBACT,IAAI,EAAE,MAAM;wBACZ,MAAM,EAAE,OAAO;wBACf,WAAW,EAAE,2BAA2B;qBACzC;iBACF;aACF;YACD,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;SAC3B;KACF,CAAC,CAAC;IAEH,sBAAsB;IACtB,MAAM,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE;QAChC,WAAW;QACX,QAAQ,EAAE;YACR,YAAY,EAAE,MAAM;YACpB,WAAW,EAAE,IAAI;YACjB,sBAAsB,EAAE,IAAI;YAC5B,MAAM,EAAE,IAAI;YACZ,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,eAAe,EAAE;gBACf,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,SAAS;aACjB;SACF;QACD,OAAO,EAAE;YACP,SAAS,EAAE,UAAU,QAAQ,EAAE,MAAM,EAAE,IAAI;gBACzC,IAAI,EAAE,CAAC;YACT,CAAC;YACD,UAAU,EAAE,UAAU,QAAQ,EAAE,MAAM,EAAE,IAAI;gBAC1C,IAAI,EAAE,CAAC;YACT,CAAC;SACF;QACD,SAAS,EAAE,KAAK;QAChB,kBAAkB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM;QACtC,sBAAsB,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC,aAAa;QACxD,2BAA2B,EAAE,IAAI;KAClC,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,2BAA2B,WAAW,EAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,WAAW,OAAO,CAAC,CAAC;AACpE,CAAC,CAAC;AAEF,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,wBAAwB;IACxB,aAAa,EAAE;QACb,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE;YACpD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE;SAC1D;QACD,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;KAC/B;IAED,+BAA+B;IAC/B,cAAc,EAAE;QACd,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,eAAe,EAAE;YACtE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,oBAAoB,EAAE;SACtF;QACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;KAClC;IAED,oBAAoB;IACpB,eAAe,EAAE;QACf,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,kCAAkC;QAC/C,OAAO,EAAE,yCAAyC;QAClD,QAAQ,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC;KAC7C;IAED,cAAc,EAAE;QACd,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,YAAY;QACzB,OAAO,EAAE,6BAA6B;QACtC,QAAQ,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,CAAC;KACxD;IAED,eAAe,EAAE;QACf,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,uBAAuB;QACpC,OAAO,EAAE,sBAAsB;QAC/B,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;KACrC;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,mBAAmB;IACnB,oBAAoB,EAAE;QACpB,WAAW,EAAE,yBAAyB;QACtC,OAAO,EAAE;YACP,kBAAkB,EAAE;gBAClB,MAAM,EAAE,aAAa,CAAC,aAAa;gBACnC,OAAO,EAAE;oBACP,KAAK,EAAE,qBAAqB;oBAC5B,OAAO,EAAE,0BAA0B;iBACpC;aACF;SACF;KACF;IAED,gBAAgB;IAChB,iBAAiB,EAAE;QACjB,WAAW,EAAE,eAAe;QAC5B,OAAO,EAAE;YACP,kBAAkB,EAAE;gBAClB,MAAM,EAAE,aAAa,CAAC,aAAa;gBACnC,OAAO,EAAE;oBACP,KAAK,EAAE,qBAAqB;oBAC5B,OAAO,EAAE,wBAAwB;iBAClC;aACF;SACF;KACF;IAED,gBAAgB;IAChB,gBAAgB,EAAE;QAChB,WAAW,EAAE,oBAAoB;QACjC,OAAO,EAAE;YACP,kBAAkB,EAAE;gBAClB,MAAM,EAAE,aAAa,CAAC,aAAa;gBACnC,OAAO,EAAE;oBACP,KAAK,EAAE,UAAU;oBACjB,OAAO,EAAE,kBAAkB;iBAC5B;aACF;SACF;KACF;IAED,4BAA4B;IAC5B,qBAAqB,EAAE;QACrB,WAAW,EAAE,uBAAuB;QACpC,OAAO,EAAE;YACP,kBAAkB,EAAE;gBAClB,MAAM,EAAE,aAAa,CAAC,aAAa;gBACnC,OAAO,EAAE;oBACP,KAAK,EAAE,eAAe;oBACtB,OAAO,EAAE,8BAA8B;iBACxC;aACF;SACF;KACF;CACF,CAAC;AAEF,+DAA+D;AAC/D,SAAS;AACT,+DAA+D;AAE/D,eAAe,EAAE,CAAC,aAAa,EAAE;IAC/B,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,KAAK;IACd,YAAY,EAAE,EAAE,EAAE,8CAA8C;CACjE,CAAC,CAAC;AAEH,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/routes/auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Authentication Routes
+ *
+ * Handles user authentication for the mcctl-console.
+ * Validates credentials against users.yaml file.
+ */
+import { FastifyInstance } from 'fastify';
+/**
+ * Register authentication routes
+ */
+export default function authRoutes(app: FastifyInstance): Promise<void>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/routes/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/routes/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAYxE;;GAEG;AACH,wBAA8B,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJ5E"}