{
    "openapi": "3.0.0",
    "info": {
        "title": "Simple HTTP Server Authentication API",
        "version": "1.0.0"
    },
    "paths": {
        "/api/user/login": {
            "post": {
                "summary": "Authenticate user",
                "description": "Authenticates user with username and password hash. On success, sets an HTTP-only session cookie.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "description": "Username for authentication"
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "FNV-1a hash of the password"
                                    }
                                },
                                "required": ["username", "password"]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Authentication successful",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "Success": {
                                        "value": "OK"
                                    }
                                }
                            }
                        },
                        "headers": {
                            "Set-Cookie": {
                                "description": "HTTP-only session cookie",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication failed",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "Unauthorized": {
                                        "value": "Unauthorized"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/user/logout": {
            "post": {
                "summary": "Logout user",
                "description": "Logs out the current user by clearing the session cookie",
                "responses": {
                    "204": {
                        "description": "Logout successful",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "No Content": {
                                        "value": "No Content"
                                    }
                                }
                            }
                        },
                        "headers": {
                            "Set-Cookie": {
                                "description": "Clears the session cookie",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/captcha": {
            "get": {
                "summary": "Get captcha image",
                "description": "Generates a new captcha image and sets a http-only captcha session cookie (used for registration). The captcha session expires after 5 minutes.",
                "responses": {
                    "200": {
                        "description": "Captcha image generated successfully",
                        "content": {
                            "image/png": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        },
                        "headers": {
                            "Set-Cookie": {
                                "description": "HTTP-only captcha session cookie (captcha_session_id)",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "Method Not Allowed": {
                                        "value": "Method Not Allowed"
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "Internal Server Error": {
                                        "value": "Failed to generate captcha: [error message]"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/user/register": {
            "post": {
                "summary": "Register new user (starting from v2.2.0)",
                "description": "Registers a new user account. Requires valid captcha code and captcha session cookie. Password should be FNV-1a hash (will be hashed again on server side).",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "identity": {
                                        "type": "string",
                                        "description": "User identity (username, 3-50 characters, alphanumeric + underscore/hyphen only)",
                                        "minLength": 3,
                                        "maxLength": 50
                                    },
                                    "password": {
                                        "type": "string",
                                        "description": "FNV-1a hash of the password (will be hashed again on server side)"
                                    },
                                    "captcha_code": {
                                        "type": "string",
                                        "description": "Captcha code from the captcha image"
                                    }
                                },
                                "required": ["identity", "password", "captcha_code"]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Registration successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "User registered successfully"
                                        }
                                    }
                                },
                                "examples": {
                                    "Success": {
                                        "value": {
                                            "success": true,
                                            "message": "User registered successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request - validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "examples": [
                                                "Identity is required",
                                                "Password is required",
                                                "Captcha code is required",
                                                "Captcha session is required",
                                                "Invalid captcha code",
                                                "Identity is already in use",
                                                "Identity must be at least 3 characters long",
                                                "Identity must be no more than 50 characters long",
                                                "Identity can only contain letters, numbers, underscores, and hyphens",
                                                "This identity is reserved",
                                                "Password must be at least 6 characters long",
                                                "Password must be no more than 100 characters long",
                                                "Failed to create user account",
                                                "Error during registration: [error message]"
                                            ]
                                        }
                                    }
                                },
                                "examples": {
                                    "Validation Error": {
                                        "value": {
                                            "success": false,
                                            "error": "Identity is required"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "Method Not Allowed": {
                                        "value": "Method Not Allowed"
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "text/plain": {
                                "examples": {
                                    "Internal Server Error": {
                                        "value": "Registration failed: [error message]"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}