.. _library_http_authenticate:

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

This library provides HTTP Basic authentication helpers on top of the
normalized HTTP stack.

The library currently provides these public entities:

- ``http_authenticate_verifier_protocol`` server-side verifier protocol
  for checking plaintext credentials
- ``http_authenticate`` core Basic parsing, generation, request
  protection, and challenge helpers
- ``http_htpasswd_verifier(_)`` portable Apache ``.htpasswd`` subset
  verifier supporting ``{SHA}`` and ``$apr1$`` entries
- ``http_server_core_basic_handler(_, _, _)`` portable handler wrapper
  that applies Basic protection around another object implementing
  ``http_handler_protocol``
- ``http_router_basic_auth(_, _)`` router companion category that
  protects routes declaring ``basic_auth/1`` metadata

API documentation
-----------------

Open the
`../../apis/library_index.html#http_authenticate <../../apis/library_index.html#http_authenticate>`__
link in a web browser.

Loading
-------

To load the library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(http_authenticate(loader)).

Testing
-------

To test this library, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(http_authenticate(tester)).

Usage overview
--------------

Use ``http_authenticate`` directly when you need explicit control over
Basic challenge parsing and request verification:

::

   | ?- http_authenticate::protect_request(Request, verifier, Action, [realm('private')]).

Wrap a normal handler with ``http_server_core_basic_handler(_, _, _)``
when you want a portable middleware-style integration point for Basic
verification:

::

   | ?- Handler = http_server_core_basic_handler(verifier, app_handler, [realm('private')]).

Use ``http_router_basic_auth(_, _)`` in router objects importing
``http_router`` when you want per-route protection driven by normal
route metadata:

::

   authorize_routed_request(Request, Action) :-
       ^^authorize_basic_auth_request(Request, Action).

   route_metadata(show_secret, [basic_auth([])]).

Current scope
-------------

- deterministic Basic header parsing and generation for
  ``Authorization`` and ``WWW-Authenticate``
- server-side request protection through explicit verifier objects with
  malformed or missing client credentials mapped to ``401 Unauthorized``
  responses while verifier and configuration errors are rethrown
- middleware-style handler wrapping for generic
  ``http_handler_protocol`` objects
- route-level protection through ``http_router_basic_auth(_, _)`` and
  the ``authorize_routed_request/2`` router hook
- portable Apache ``.htpasswd`` subset verification for ``{SHA}`` and
  ``$apr1$`` entries using expanded file paths and rejecting malformed
  supported hash entries

Option validation
-----------------

- ``protect_request/4`` and ``unauthorized_response/3-4`` validate
  option values at the call boundary using the shared ``options``
  category support
- ``unauthorized_response/4`` only accepts overlay options for
  ``status/1``, ``headers/1``, ``body/1``, and ``properties/1``
- unauthorized-response ``status/1`` values remain limited to ``401``,
  but the reason phrase follows the shared HTTP ``text`` rules instead
  of requiring an atom representation
- invalid response customization ``headers/1`` and ``body/1`` values are
  rejected before any normalized HTTP response term is constructed

Non-implemented features
------------------------

- client-side session helpers
- automatic role or scope authorization metadata
- portable verification of bcrypt (``$2a$``, ``$2b$``, ``$2y$``) or
  traditional ``crypt()`` ``.htpasswd`` entries
