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` options
`public` http_text_helpers
Uses:
base64
http_core
list
type
user
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `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`

### `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`

### `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))`

### `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))`

### `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))`

### `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)`

### `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)`

### `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)`

### `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)