feat: digest auth - docs

Author: chr15k

README.md

@@ -2,7 +2,7 @@
 
 [![Latest Stable Version](https://poser.pugx.org/chr15k/php-auth-generator/v)](https://packagist.org/packages/chr15k/php-auth-generator) [![Total Downloads](https://poser.pugx.org/chr15k/php-auth-generator/downloads)](https://packagist.org/packages/chr15k/php-auth-generator) [![Latest Unstable Version](https://poser.pugx.org/chr15k/php-auth-generator/v/unstable)](https://packagist.org/packages/chr15k/php-auth-generator) [![License](https://poser.pugx.org/chr15k/php-auth-generator/license)](https://packagist.org/packages/chr15k/php-auth-generator) [![PHP Version Require](https://poser.pugx.org/chr15k/php-auth-generator/require/php)](https://packagist.org/packages/chr15k/php-auth-generator)
 
-A PHP library that focuses exclusively on **generating** HTTP authentication tokens, including Basic Auth, Bearer tokens, and JWTs with a fluent API. Built with zero dependencies, it's lightweight and adds token creation capabilities without bloating your project.
+A PHP library that focuses exclusively on **generating** HTTP authentication tokens, including Basic Auth, Bearer tokens, Digest Auth, and JWTs with a fluent API. Built with zero dependencies, it's lightweight and adds token creation capabilities without bloating your project.
 
 > [!IMPORTANT]
 > This package is designed solely for **generating** authentication tokens. It does not include any token decoding, validation, or verification functionality.

docs/API_CHEATSHEET.md

@@ -144,6 +144,13 @@ $headers = AuthGenerator::jwt()
     ->claim('user_id', 123)
     ->toArray();
 
+// Digest Auth headers
+$headers = AuthGenerator::digestAuth()
+    ->username('user')
+    ->password('pass')
+    ->realm('example.com')
+    ->toArray();
+
 // Fluent formatting with toHeader() method
 $header = AuthGenerator::jwt()
     ->key('secret-key')
@@ -167,3 +174,14 @@ The following algorithms are supported for JWT tokens:
 | Algorithm::ES384 | ECDSA using P-384 curve and SHA-384 |
 | Algorithm::ES256K | ECDSA using secp256k1 curve and SHA-256 |
 | Algorithm::EdDSA | Edwards-curve Digital Signature Algorithm (EdDSA) |
+
+## Digest Auth Algorithms
+
+The following algorithms are supported for Digest Authentication:
+
+| Algorithm | Description |
+|-----------|-------------|
+| DigestAlgorithm::MD5 | MD5 algorithm (RFC 2617) |
+| DigestAlgorithm::MD5_SESS | MD5-sess variant with client nonce (RFC 2617) |
+| DigestAlgorithm::SHA256 | SHA-256 algorithm (RFC 7616) |
+| DigestAlgorithm::SHA256_SESS | SHA-256-sess variant with client nonce (RFC 7616) |

docs/USER_GUIDE.md

@@ -100,7 +100,14 @@ $header = AuthGenerator::bearerToken()
 
 ## Digest Auth
 
-Digest Authentication is an authentication mechanism that improves upon Basic Authentication by avoiding sending the password in plaintext over the network. It uses a challenge-response mechanism and MD5 cryptographic hashing.
+Digest Authentication is an authentication mechanism that improves upon Basic Authentication by avoiding sending the password in plaintext over the network. It uses a challenge-response mechanism and cryptographic hashing (MD5 or SHA-256).
+
+The Digest authentication process typically involves:
+1. A server challenge containing a nonce value
+2. A client response with a cryptographic hash that proves password knowledge without revealing it
+3. The response includes various components like realm, nonce, URI, and algorithm details
+
+This implementation provides a convenient way to generate properly formatted Digest Auth tokens for HTTP requests. It supports all RFC 2617 and RFC 7616 algorithm variants including MD5, MD5-sess, SHA-256, and SHA-256-sess.
 
 ### Generating a Digest Auth Token
 
@@ -327,7 +334,7 @@ $response = $client->request('GET', 'https://api.example.com/resources');
 use Chr15k\AuthGenerator\AuthGenerator;
 use Illuminate\Support\Facades\Http;
 
-// Make request with Laravel HTTP client
+// Make request with Laravel HTTP client and Bearer token
 $response = Http::withHeaders(
     AuthGenerator::bearerToken()
         ->length(48)
@@ -336,6 +343,19 @@ $response = Http::withHeaders(
             'Accept' => 'application/json',
         ])
 )->get('https://api.example.com/resources');
+
+// Using Digest Authentication
+$response = Http::withHeaders(
+    AuthGenerator::digestAuth()
+        ->username('api_user')
+        ->password('secure_password')
+        ->realm('api.example.com')
+        ->uri('/protected-resource')
+        ->method('GET')
+        ->toArray([
+            'Accept' => 'application/json',
+        ])
+)->get('https://api.example.com/protected-resource');
 ```
 
 ## Advanced Usage
@@ -344,15 +364,28 @@ If you need more control, you can access the underlying generator instance.
 
 ```php
 use Chr15k\AuthGenerator\AuthGenerator;
+use Chr15k\AuthGenerator\Enums\DigestAlgorithm;
 
-// Get the generator instance
+// Get the generator instance (Basic Auth example)
 $generator = AuthGenerator::basicAuth()
     ->username('user')
     ->password('pass')
     ->build();
 
 // Now you can work directly with the generator
 $token = $generator->generate();
+
+// Advanced Digest Auth example
+$digestGenerator = AuthGenerator::digestAuth()
+    ->username('user')
+    ->password('pass')
+    ->realm('example.com')
+    ->uri('/api/resource')
+    ->algorithm(DigestAlgorithm::SHA256)
+    ->build();
+
+// Generate the digest token directly
+$digestToken = $digestGenerator->generate();
 ```
 
 

src/Builders/DigestAuthBuilder.php

@@ -11,32 +11,76 @@
 use Chr15k\AuthGenerator\Generators\DigestAuth as DigestAuthGenerator;
 use SensitiveParameter;
 
+/**
+ * Builder for generating HTTP Digest Authentication tokens.
+ *
+ * Digest Authentication improves upon Basic Authentication by avoiding transmission
+ * of the password in plaintext. It uses a challenge-response mechanism and various
+ * cryptographic algorithms (MD5, SHA-256) including their session variants.
+ */
 final class DigestAuthBuilder implements Builder
 {
+    /**
+     * The username for authentication.
+     */
     private string $username = '';
 
+    /**
+     * The password for authentication.
+     */
     private string $password = '';
 
+    /**
+     * The algorithm used for digest calculation.
+     */
     private DigestAlgorithm $algorithm = DigestAlgorithm::MD5;
 
+    /**
+     * The authentication realm.
+     */
     private string $realm = '';
 
+    /**
+     * The HTTP method for the request.
+     */
     private string $method = 'GET';
 
+    /**
+     * The URI of the request.
+     */
     private string $uri = '/';
 
+    /**
+     * The server nonce value.
+     */
     private string $nonce = '';
 
+    /**
+     * The nonce count.
+     */
     private string $nc = '';
 
+    /**
+     * The client nonce value.
+     */
     private string $cnonce = '';
 
+    /**
+     * The quality of protection. Common values: 'auth', 'auth-int'.
+     */
     private string $qop = '';
 
+    /**
+     * The opaque server value.
+     */
     private string $opaque = '';
 
+    /**
+     * Initialize a new DigestAuthBuilder with random nonce values.
+     */
     public function __construct()
     {
+        // Generate secure random nonce values
         $this->nonce = bin2hex(random_bytes(16));
         $this->cnonce = bin2hex(random_bytes(8));
     }

src/DataTransfer/DigestAuthData.php

@@ -9,6 +9,16 @@
 
 /**
  * @internal
+ *
+ * Data transfer object containing all the parameters needed for Digest Authentication.
+ *
+ * This class encapsulates all the components required to generate a Digest Auth token:
+ * - username and password for authentication
+ * - realm, nonce, and algorithm as provided by the server challenge
+ * - method and URI from the HTTP request
+ * - nc (nonce count), cnonce (client nonce), qop (quality of protection) for auth-int
+ * - opaque value as provided by the server
+ * - entityBody for auth-int quality of protection (optional)
  */
 final readonly class DigestAuthData
 {

src/Enums/DigestAlgorithm.php

@@ -6,13 +6,29 @@
 
 use Closure;
 
+/**
+ * Represents the algorithms available for Digest Authentication.
+ *
+ * These algorithms are used to generate the cryptographic digest responses
+ * in HTTP Digest Authentication according to RFC 2617 and RFC 7616.
+ *
+ * - MD5: Original algorithm from RFC 2617
+ * - MD5_SESS: Session variant of MD5 that includes client nonce
+ * - SHA256: More secure SHA-256 algorithm from RFC 7616
+ * - SHA256_SESS: Session variant of SHA-256 that includes client nonce
+ */
 enum DigestAlgorithm: string
 {
     case MD5 = 'MD5';
     case MD5_SESS = 'MD5-sess';
     case SHA256 = 'SHA-256';
     case SHA256_SESS = 'SHA-256-sess';
 
+    /**
+     * Get the PHP hash algorithm identifier for this digest algorithm.
+     *
+     * @return string The hash algorithm name compatible with PHP's hash functions
+     */
     public function algo(): string
     {
         return match ($this) {
@@ -21,11 +37,22 @@ public function algo(): string
         };
     }
 
+    /**
+     * Get a closure that can be used to hash data with this algorithm.
+     *
+     * @return Closure A function that accepts a string and returns its hash
+     */
     public function func(): Closure
     {
         return fn (string $data): string => hash($this->algo(), $data);
     }
 
+    /**
+     * Determines if this is a session variant algorithm (MD5-sess or SHA-256-sess).
+     * Session variants incorporate the client nonce in the calculation.
+     *
+     * @return bool True if this is a session variant, false otherwise
+     */
     public function isSessionVariant(): bool
     {
         return str_ends_with($this->value, '-sess');

src/Generators/DigestAuth.php

@@ -11,6 +11,19 @@
 
 /**
  * @internal
+ *
+ * Generates an HTTP Digest Authentication token based on provided data.
+ *
+ * This class implements the token generation process according to RFC 2617 and RFC 7616,
+ * supporting various digest algorithms (MD5, SHA-256) and their session variants.
+ *
+ * The Digest Authentication method improves security compared to Basic Auth by not
+ * sending the password over the network in plaintext. Instead, it uses a cryptographic
+ * hash of the username, password, realm, and other components to prove the client
+ * knows the credentials without revealing them.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc2617 Original Digest Auth specification
+ * @see https://datatracker.ietf.org/doc/html/rfc7616 SHA-256 and other improvements
  */
 final readonly class DigestAuth implements Generator
 {
@@ -45,27 +58,27 @@ public function generate(): string
 
     private function generateResponse(): string
     {
-        $func = $this->data->algorithm->func();
+        $hash = $this->data->algorithm->func();
 
-        $ha1 = $func(sprintf('%s:%s:%s', $this->data->username, $this->data->realm, $this->data->password));
+        $ha1 = $hash(sprintf('%s:%s:%s', $this->data->username, $this->data->realm, $this->data->password));
 
         if ($this->data->algorithm->isSessionVariant()) {
-            $ha1 = $func(sprintf('%s:%s:%s', $ha1, $this->data->nonce, $this->data->cnonce));
+            $ha1 = $hash(sprintf('%s:%s:%s', $ha1, $this->data->nonce, $this->data->cnonce));
         }
 
         if ($this->data->qop === 'auth-int') {
-            $ha2 = $func(sprintf(
+            $ha2 = $hash(sprintf(
                 '%s:%s:%s',
                 $this->data->method,
                 $this->data->uri,
-                $func($this->data->entityBody)
+                $hash($this->data->entityBody)
             ));
         } else {
-            $ha2 = $func(sprintf('%s:%s', $this->data->method, $this->data->uri));
+            $ha2 = $hash(sprintf('%s:%s', $this->data->method, $this->data->uri));
         }
 
         if ($this->data->qop !== '' && $this->data->qop !== '0') {
-            return $func(sprintf(
+            return $hash(sprintf(
                 '%s:%s:%s:%s:%s:%s',
                 $ha1,
                 $this->data->nonce,
@@ -76,6 +89,6 @@ private function generateResponse(): string
             ));
         }
 
-        return $func("{$ha1}:{$this->data->nonce}:{$ha2}");
+        return $hash("{$ha1}:{$this->data->nonce}:{$ha2}");
     }
 }