________________________________________________________________________

This file is part of Logtalk <https://logtalk.org/>
SPDX-FileCopyrightText: 1998-2026 Paulo Moura <pmoura@logtalk.org>
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
________________________________________________________________________


`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
