.. -*- coding: utf-8 -*-
.. :Project:   SoL
.. :Created:   dom 11 gen 2026, 15:59:04
.. :Author:    Lele Gaifax <lele@metapensiero.it>
.. :License:   GNU General Public License version 3 or later
.. :Copyright: © 2026 Lele Gaifax
..

======================
 Authentication views
======================

.. automodule:: sol.views.auth

.. index::
   triple: Route; POST; /auth/login

.. autofunction:: auth_user

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/login``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - username
               - the name of the user
             + - password
               - its password

   Upon successful authentication, the client receives back a ``JSON`` structure containing
   information about the user and his preferences, and a ``session`` cookie__.

   __ https://en.wikipedia.org/wiki/HTTP_cookie

   .. rubric:: Invalid credentials

   .. tab:: GNU/Linux and Curl

      .. code-block:: shell

         curl --silent \\
              --data "username=foo" \\
              --data "password="bar" \\
              http://server.sol/auth/login

   .. tab:: MS-Windows and Powershell

      .. code-block:: powershell

         $params = @{
           Uri = 'http://server.sol/auth/login'
           Method = 'POST'
           Body = @{
             username = "foo"
             password = "bar"
           }
         }
         (Invoke-WebRequest @params).Content

   This emits a ``JSON`` response similar to the following:

   .. code-block:: json

      {
        "success": false,
        "message": "The inserted user and password, or one of the two, are wrong!",
        "errors": {
          "username": "Invalid credentials",
          "password": "Invalid credentials"
        }
      }

   .. rubric:: Successful call

   .. tab:: GNU/Linux and Curl

      .. code-block:: shell

         curl --silent \\
              --data "username=lele" \\
              --data "password=therightpassword" \\
              --cookie-jar cookies.txt \\
              http://server.sol/auth/login

   .. tab:: MS-Windows and Powershell

      .. code-block:: powershell

         $params = @{
           Uri = 'http://server.sol/auth/login'
           Method = 'POST'
           Body = @{
             username = "lele"
             password = "therightpassword"
           }
         }
         $res = Invoke-WebRequest @params
         $ses.Cookies | Export-Clixml -Path "cookies.txt"

   This time the ``JSON`` response contains something like:

   .. code-block:: json

      {
        "success": true,
        "fullname": "Lele Gaifax",
        "is_admin": false,
        "is_nationalliable": null,
        "is_ownersadmin": true,
        "is_playersmanager": true,
        "user_id": 1,
        "maxratinglevel": "2",
        "reload_l10n": false,
        "ui_language": null,
        "modules": [ "…" ],
        "shortcuts": [ "…" ],
        "quickstart": [ "…" ]
      }


.. index::
   triple: Route; GET; /auth/logout

.. autofunction:: logout

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/logout``
      * - Method
        - ``GET``
      * - Response
        - ``JSON``

   This can be called only by an :func:`authenticated user <auth_user>`.

   .. rubric:: Unauthorized call

   .. tab:: GNU/Linux and Curl

      .. code-block:: shell

         curl --silent --out-null \\
              --write-out '%{http_code}\n' \\
              http://server.sol/auth/logout

      ::

         401

   .. tab:: MS-Windows and Powershell

      .. code-block:: powershell

         $params = @{ Uri = 'http://server.sol/auth/login' }
         $res = Invoke-WebRequest @params
         $res.StatusCode

      ::

         401

   .. rubric:: Successful call

   .. tab:: GNU/Linux and Curl

      .. code-block:: shell

         curl --silent \\
              --cookie cookies.txt \\
              http://server.sol/auth/logout

   .. tab:: MS-Windows and Powershell

      .. code-block:: powershell

         $ses = Import-Clixml -Path "cookies.txt"
         $params = @{
           Uri = 'http://server.sol/auth/logout'
           Method = 'POST'
           SessionVariable = 'ses'
         }
         (Invoke-WebRequest @params).Content

   The ``JSON`` response contains something like:

   .. code-block:: json

      {
        "success": true,
        "message": "Goodbye"
      }


.. index::
   triple: Route; POST; /auth/signin

.. autofunction:: create_new_user

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/signin``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - email
               - the email address of the new account
             + - password
               - the password of the new account
             + - firstname
               - the first name of the user
             + - lastname
               - the family name of the user
             + - language
               - the preferred language

   Once an anonymous visitor fills the self registration form and confirms the data this
   method validates it and if everything is good a new :class:`user <sol.models.user.User>` is
   created and an email is sent to the new potential user, with an ``URL`` she must visit to
   :func:`complete <confirm_new_user>` the procedure.


.. index::
   triple: Route; GET; /auth/signin

.. autofunction:: confirm_new_user

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/signin``
      * - Method
        - ``GET``
      * - Response
        - ``HTML``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - confirm
               - the *signed* `id` of the new user

   This concludes the self registration procedure: if `confirm` is valid the new account is
   activated and the visitor is redirected to the login page.


.. index::
   triple: Route; POST; /auth/lost_password

.. autofunction:: lost_password

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/lost_password``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - email
               - the user's email address

   This sends an email to the specified address, with an ``URL`` that the user must visit to
   reset her own password.


.. index::
   triple: Route; POST; /auth/reset_password

.. autofunction:: reset_password

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/reset_password``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - token
               - a *signed* token
             + - password
               - the *new* password


   This changes the user's password to a new one.


.. index::
   triple: Route; POST; /auth/change_password

.. autofunction:: change_password

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/change_password``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - oldpassword
               - the *old* password
             + - newpassword
               - the *new* password

   This replaces `oldpassword` with `newpassword` for the authenticated user.

.. rubric:: Unauthorized call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent --out-null \\
           --write-out '%{http_code}\n' \\
           http://server.sol/auth/change_password

   ::

      401

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $params = @{ Uri = 'http://server.sol/auth/change_password' }
      $res = Invoke-WebRequest @params
      $res.StatusCode

   ::

      401

.. rubric:: Successful call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent \\
           --cookie cookies.txt \\
           --data "oldpassword=foo" \\
           --data "newpassword=bar" \\
           http://server.sol/auth/change_password

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $ses = Import-Clixml -Path "cookies.txt"
      $params = @{
        Uri = 'http://server.sol/auth/change_password'
        Method = 'POST'
        SessionVariable = 'ses'
        Body = @{
          oldpassword = 'foo'
          oldpassword = 'bar'
        }
      }
      (Invoke-WebRequest @params).Content

The ``JSON`` response contains something like:

.. code-block:: json

   {
     "success": true
   }


.. index::
   triple: Route; POST; /auth/change_language

.. autofunction:: change_language

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/auth/change_language``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - language
               - the `ISO code <http://en.wikipedia.org/wiki/ISO_639-1>`_ of the language

   This sets the language used by the ``UI`` for the authenticated user.

.. rubric:: Unauthorized call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent --out-null \\
           --write-out '%{http_code}\n' \\
           http://server.sol/auth/change_language

   ::

      401

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $params = @{ Uri = 'http://server.sol/auth/change_language' }
      $res = Invoke-WebRequest @params
      $res.StatusCode

   ::

      401

.. rubric:: Successful call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent \\
           --cookie cookies.txt \\
           --data "language=xy" \\
           http://server.sol/auth/change_language

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $ses = Import-Clixml -Path "cookies.txt"
      $params = @{
        Uri = 'http://server.sol/auth/change_language'
        Method = 'POST'
        SessionVariable = 'ses'
        Body = @{
          language = 'xy'
        }
      }
      (Invoke-WebRequest @params).Content

The ``JSON`` response contains something like:

.. code-block:: json

   {
     "success": true
   }
