# retoor <retoor@molodetz.nl>

from .._shared import endpoint, field

GROUP = {
        "slug": "auth",
        "title": "Authentication",
        "intro": """
# Authentication

Create an account, sign in, recover your password, and log out. These are the only endpoints
that set or clear the `session` cookie; every other request authenticates with the methods
described in [Authentication](/docs/authentication.html). The shared rules (content
negotiation, pagination, status codes) live in [Conventions and Errors](/docs/conventions.html).

## Page vs. action

The GET endpoints render HTML sign-up, login, and password-reset forms; they also return the
page data as JSON when requested with `Accept: application/json` (including `page` to
distinguish the form type).

The POST endpoints are **actions**: they accept form fields, set or clear the `session` cookie,
and return a `302` redirect (or the JSON envelope for JSON callers).

**Sign-up requires a unique `username` and `email`** plus a `confirm_password` that matches the
password; **you log in with your `email` and password**. JSON callers receive validation errors
as a `422` with the shape `{ "fields": {...}, "messages": [...] }`.
""",
        "endpoints": [
            endpoint(
                id="auth-signup",
                method="GET",
                path="/auth/signup",
                title="Sign up page",
                summary="Render the registration form. Returns an HTML page.",
                auth="public",
                interactive=True,
            ),
            endpoint(
                id="auth-signup-post",
                method="POST",
                path="/auth/signup",
                title="Sign up",
                summary="Create a new account. Sets the session cookie on success.",
                auth="public",
                encoding="form",
                destructive=False,
                params=[
                    field("username", "form", "string", True, "alice", "Username, 3-32 characters (letters, numbers, hyphens, underscores)."),
                    field("email", "form", "string", True, "alice@example.com", "Email address; must be unique and contain an @."),
                    field("password", "form", "string", True, "mysecret", "Password, 6+ characters."),
                    field("confirm_password", "form", "string", True, "mysecret", "Must match password."),
                ],
            ),
            endpoint(
                id="auth-login",
                method="GET",
                path="/auth/login",
                title="Log in page",
                summary="Render the login form. Returns an HTML page.",
                auth="public",
                interactive=True,
                params=[
                    field("next", "query", "string", False, "", "Redirect target after login."),
                ],
            ),
            endpoint(
                id="auth-login-post",
                method="POST",
                path="/auth/login",
                title="Log in",
                summary="Authenticate with email and password. Sets the session cookie.",
                auth="public",
                encoding="form",
                params=[
                    field("email", "form", "string", True, "alice@example.com", "Your registered email."),
                    field("password", "form", "string", True, "mysecret", "Your password."),
                    field("remember_me", "form", "string", False, "on", "Send 'on' to extend the session to the remember-me lifetime."),
                    field("next", "form", "string", False, "", "Redirect target after login."),
                ],
            ),
            endpoint(
                id="auth-forgot-password",
                method="GET",
                path="/auth/forgot-password",
                title="Forgot password page",
                summary="Render the forgot-password form. Returns an HTML page.",
                auth="public",
                interactive=True,
            ),
            endpoint(
                id="auth-forgot-password-post",
                method="POST",
                path="/auth/forgot-password",
                title="Request password reset",
                summary="Send a password-reset email with a one-time link.",
                auth="public",
                encoding="form",
                params=[
                    field("email", "form", "string", True, "alice@example.com", "Your registered email."),
                ],
            ),
            endpoint(
                id="auth-reset-password",
                method="GET",
                path="/auth/reset-password/{token}",
                title="Reset password page",
                summary="Render the password-reset form (only valid with a one-time token). Returns an HTML page.",
                auth="public",
                interactive=True,
                params=[
                    field("token", "path", "string", True, "RESET_TOKEN", "The one-time reset token from the email."),
                ],
            ),
            endpoint(
                id="auth-reset-password-post",
                method="POST",
                path="/auth/reset-password/{token}",
                title="Reset password",
                summary="Set a new password using a one-time reset token.",
                auth="public",
                encoding="form",
                params=[
                    field("token", "path", "string", True, "RESET_TOKEN", "The one-time reset token from the email."),
                    field("password", "form", "string", True, "newpass", "New password, 6+ characters."),
                    field("confirm_password", "form", "string", True, "newpass", "Must match password."),
                ],
            ),
            endpoint(
                id="auth-logout",
                method="GET",
                path="/auth/logout",
                title="Log out",
                summary="Clear the session cookie and redirect to the landing page.",
                auth="public",
                interactive=False,
            ),
        ],
}