.. index:: single: http_authenticate
.. _http_authenticate/0:

.. rst-class:: right

**object**

``http_authenticate``
=====================

HTTP Basic authentication parsing, generation, challenge building, and request verification helpers.

| **Availability:** 
|    ``logtalk_load(http_authenticate(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-06-26

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`options <options/0>`
|    ``public`` :ref:`http_text_helpers <http_text_helpers/0>`
| **Uses:**
|    :ref:`base64 <base64/0>`
|    :ref:`http_core <http_core/0>`
|    :ref:`list <list/0>`
|    :ref:`type <type/0>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: challenge/2
.. _http_authenticate/0::challenge/2:

``challenge/2``
^^^^^^^^^^^^^^^

Returns the single parsed Basic ``WWW-Authenticate`` challenge from a normalized HTTP response when present.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``challenge(Response,Challenge)``
| **Mode and number of proofs:**
|    ``challenge(+compound,-compound)`` - ``zero_or_one``


------------

.. index:: authorization/2
.. _http_authenticate/0::authorization/2:

``authorization/2``
^^^^^^^^^^^^^^^^^^^

Returns the single parsed Basic ``Authorization`` header from a normalized HTTP request when present.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``authorization(Request,Authorization)``
| **Mode and number of proofs:**
|    ``authorization(+compound,-compound)`` - ``zero_or_one``


------------

.. index:: parse_challenge/2
.. _http_authenticate/0::parse_challenge/2:

``parse_challenge/2``
^^^^^^^^^^^^^^^^^^^^^

Parses one Basic challenge header field value into a normalized ``basic_challenge/1`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_challenge(Text,Challenge)``
| **Mode and number of proofs:**
|    ``parse_challenge(++text,-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Text`` is not a valid Basic challenge header value:
|        ``domain_error(http_authenticate_header(www_authenticate),invalid(syntax))``
|    ``Text`` uses an unsupported authentication scheme:
|        ``domain_error(http_authenticate_header(www_authenticate),unsupported_scheme(Scheme))``
|    ``Text`` contains a duplicated Basic challenge directive:
|        ``domain_error(http_authenticate_header(www_authenticate),duplicate(Name))``
|    ``Text`` is missing a required Basic challenge directive:
|        ``domain_error(http_authenticate_header(www_authenticate),missing(Name))``
|    ``Text`` contains an unexpected Basic challenge directive:
|        ``domain_error(http_authenticate_header(www_authenticate),unexpected(Name))``
|    ``Text`` contains an invalid Basic challenge charset:
|        ``domain_error(http_authenticate_header(www_authenticate),invalid(charset))``


------------

.. index:: generate_challenge/2
.. _http_authenticate/0::generate_challenge/2:

``generate_challenge/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Generates one canonical Basic challenge header field value from a normalized ``basic_challenge/1`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_challenge(Challenge,HeaderValue)``
| **Mode and number of proofs:**
|    ``generate_challenge(+compound,-atom)`` - ``one_or_error``

| **Exceptions:**
|    ``Challenge`` is not a valid normalized Basic challenge term:
|        ``domain_error(http_authenticate_term(challenge),Challenge)``
|    ``Challenge`` is missing a required field:
|        ``domain_error(http_authenticate_term(challenge),missing(Name))``
|    ``Challenge`` contains a duplicated field:
|        ``domain_error(http_authenticate_term(challenge),duplicate(Name))``
|    ``Challenge`` contains an unexpected field:
|        ``domain_error(http_authenticate_term(challenge),unexpected(Name))``
|    ``Challenge`` contains an invalid field:
|        ``domain_error(http_authenticate_term(challenge),invalid(Field))``


------------

.. index:: parse_authorization/2
.. _http_authenticate/0::parse_authorization/2:

``parse_authorization/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Parses one Basic authorization header field value into a normalized ``basic_authorization/1`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_authorization(Text,Authorization)``
| **Mode and number of proofs:**
|    ``parse_authorization(++text,-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Text`` is not a valid Basic authorization header value:
|        ``domain_error(http_authenticate_header(authorization),invalid(syntax))``
|    ``Text`` uses an unsupported authentication scheme:
|        ``domain_error(http_authenticate_header(authorization),unsupported_scheme(Scheme))``
|    ``Text`` contains invalid Basic credentials:
|        ``domain_error(http_authenticate_header(authorization),invalid(credentials))``


------------

.. index:: generate_authorization/2
.. _http_authenticate/0::generate_authorization/2:

``generate_authorization/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates one canonical Basic authorization header field value from a normalized ``basic_authorization/1`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_authorization(Authorization,HeaderValue)``
| **Mode and number of proofs:**
|    ``generate_authorization(+compound,-atom)`` - ``one_or_error``

| **Exceptions:**
|    ``Authorization`` is not a valid normalized Basic authorization term:
|        ``domain_error(http_authenticate_term(authorization),Authorization)``
|    ``Authorization`` contains an invalid Basic username:
|        ``domain_error(http_authenticate_value(username),Username)``


------------

.. index:: protect_request/4
.. _http_authenticate/0::protect_request/4:

``protect_request/4``
^^^^^^^^^^^^^^^^^^^^^

Verifies a normalized HTTP request using a Basic verifier object and returns either ``continue(Request)`` or ``respond(Response)``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``protect_request(Request,Verifier,Action,Options)``
| **Mode and number of proofs:**
|    ``protect_request(+compound,+object_identifier,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Request`` is not a valid normalized HTTP request term:
|        ``domain_error(http_request,Request)``
|    ``Verifier`` is a variable:
|        ``instantiation_error``
|    ``Verifier`` is neither a variable nor an existing object:
|        ``existence_error(http_authenticate_verifier,Verifier)``
|    ``Verifier`` does not implement the Basic verifier protocol:
|        ``domain_error(http_authenticate_verifier,Verifier)``
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    ``Options`` contains an invalid Basic-auth status:
|        ``domain_error(http_authenticate_status,Status)``
|    ``Options`` contains invalid Basic-auth headers:
|        ``domain_error(http_headers,Headers)``
|    ``Options`` contains an invalid Basic-auth body:
|        ``domain_error(http_body,Body)``
|    ``Options`` contains invalid Basic-auth properties:
|        ``domain_error(http_properties,Properties)``


------------

.. index:: unauthorized_response/3
.. _http_authenticate/0::unauthorized_response/3:

``unauthorized_response/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds a normalized ``401 Unauthorized`` response and returns the generated normalized Basic challenge term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``unauthorized_response(Challenge,Response,Options)``
| **Mode and number of proofs:**
|    ``unauthorized_response(-compound,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    ``Options`` contains an invalid Basic-auth status:
|        ``domain_error(http_authenticate_status,Status)``
|    ``Options`` contains invalid Basic-auth headers:
|        ``domain_error(http_headers,Headers)``
|    ``Options`` contains an invalid Basic-auth body:
|        ``domain_error(http_body,Body)``
|    ``Options`` contains invalid Basic-auth properties:
|        ``domain_error(http_properties,Properties)``
|    The generated response headers violate normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The generated response properties violate normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: unauthorized_response/4
.. _http_authenticate/0::unauthorized_response/4:

``unauthorized_response/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Decorates a normalized HTTP response with an explicit normalized Basic challenge term and returns the resulting ``401 Unauthorized`` response.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``unauthorized_response(Challenge,Response0,Response,Options)``
| **Mode and number of proofs:**
|    ``unauthorized_response(+compound,+compound,-compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Challenge`` is not a valid normalized Basic challenge term:
|        ``domain_error(http_authenticate_term(challenge),Challenge)``
|    ``Response0`` is not a valid normalized HTTP response term:
|        ``domain_error(http_response,Response0)``
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid unauthorized-response overlay option:
|        ``domain_error(http_authenticate_unauthorized_response_overlay_option,Option)``
|    ``Options`` contains an invalid Basic-auth status:
|        ``domain_error(http_authenticate_status,Status)``
|    ``Options`` contains invalid Basic-auth headers:
|        ``domain_error(http_headers,Headers)``
|    ``Options`` contains an invalid Basic-auth body:
|        ``domain_error(http_body,Body)``
|    ``Options`` contains invalid Basic-auth properties:
|        ``domain_error(http_properties,Properties)``
|    The decorated response headers violate normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The decorated response properties violate normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)