Docblocks and error handling.

src/Bundle.php

@@ -27,10 +27,10 @@ class Bundle
     /**
      * Bundle constructor.
      *
-     * @param string $filePath
-     * @param string $sha256sum
-     * @param string $signature
-     * @param string $customValidator
+     * @param string $filePath        Path to the CACert bundle
+     * @param string $sha256sum       Hex-encoded string
+     * @param string $signature       Hex-encoded string
+     * @param string $customValidator Fully-Qualified Class Name
      * @throws \TypeError
      */
     public function __construct(
@@ -55,7 +55,7 @@ public function __construct(
     }
 
     /**
-     * Create a symbolic link that points to this bundle?
+     * Creates a symbolic link that points to this bundle.
      *
      * @param string $destination
      * @param bool $unlinkIfExists
@@ -83,6 +83,9 @@ public function getFilePath()
     }
 
     /**
+     * Get the SHA256 hash of this bundle's contents. Defaults
+     * to returning a hex-encoded string.
+     *
      * @param bool $raw
      * @return string
      */
@@ -95,6 +98,9 @@ public function getSha256Sum($raw = false)
     }
 
     /**
+     * Get the Ed25519 signature for this bundle. Defaults
+     * to returning a hex-encoded string.
+     *
      * @param bool $raw
      * @return string
      */
@@ -107,6 +113,8 @@ public function getSignature($raw = false)
     }
 
     /**
+     * Get the custom validator (assuming one is defined).
+     *
      * @return Validator
      * @throws \Exception
      */
@@ -119,6 +127,9 @@ public function getValidator()
     }
 
     /**
+     * Does this Bundle need a custom validator? This is typically only true
+     * if a custom CA cert is being employed in addition to the Mozilla bundles.
+     *
      * @return bool
      */
     public function hasCustom()

src/Fetch.php

@@ -14,6 +14,9 @@ class Fetch
 
     /**
      * Fetch constructor.
+     *
+     * You almost certainly want to use RemoteFetch instead.
+     *
      * @param string $dataDir
      */
     public function __construct($dataDir = '')
@@ -26,6 +29,9 @@ public function __construct($dataDir = '')
     }
 
     /**
+     * Get the latest bundle. Checks the SHA256 hash of the file versus what
+     * is expected. Optionally checks the Ed25519 signature.
+     *
      * @param bool|null $checkEd25519Signature
      * @return Bundle
      * @throws \Exception
@@ -58,6 +64,10 @@ public function getLatestBundle($checkEd25519Signature = null)
     }
 
     /**
+     * Get an array of all of the Bundles, ordered most-recent to oldest.
+     *
+     * No validation is perforemd automatically.
+     *
      * @param string $customValidator
      * @return array<int, Bundle>
      */

src/LocalCACertBuilder.php

@@ -50,6 +50,8 @@ public static function fromBundle(Bundle $old)
     }
 
     /**
+     * Load the original bundle's contents.
+     *
      * @return self
      * @throws \Exception
      */
@@ -64,6 +66,9 @@ public function loadOriginal()
     }
 
     /**
+     * Append a CACert file, containing your in-house certificates, to the bundle
+     * being compiled.
+     *
      * @param string $path
      * @return self
      * @throws \Exception
@@ -85,6 +90,8 @@ public function appendCACertFile($path = '')
     }
 
     /**
+     * Get the public key.
+     *
      * @param bool $raw
      * @return string
      * @throws \Error
@@ -101,6 +108,8 @@ public function getPublicKey($raw = false)
     }
 
     /**
+     * Sign and save the combined CA-Cert file.
+     *
      * @throws \Exception
      * @return bool
      */
@@ -155,6 +164,9 @@ public function save()
     }
 
     /**
+     * Specify the fully qualified class name for your custom
+     * Validator class.
+     *
      * @param string $string
      * @return self
      * @throws \TypeError
@@ -172,6 +184,9 @@ public function setCustomValidator($string = '')
     }
 
     /**
+     * Specify the full path of the file that the combined CA-cert will be
+     * written to when save() is invoked.
+     *
      * @param string $string
      * @return self
      */
@@ -182,6 +197,9 @@ public function setOutputPemFile($string = '')
     }
 
     /**
+     * Specify the full path of the file that will contain the updated
+     * sha256/Ed25519 metadata.
+     *
      * @param string $string
      * @return self
      */
@@ -192,12 +210,35 @@ public function setOutputJsonFile($string = '')
     }
 
     /**
+     * Specify the signing key to be used.
+     *
      * @param string $secretKey
      * @return self
+     * @throws \Exception
      */
     public function setSigningKey($secretKey = '')
     {
+        // Handle hex-encoded strings.
+        if (\ParagonIE_Sodium_Core_Util::substr($secretKey) === 128) {
+            /** @var string $secretKey */
+            $secretKey = Hex::decode($secretKey);
+            if (!\is_string($secretKey)) {
+                throw new \Exception('Signing secret keys must be SODIUM_CRYPTO_SIGN_SECRETKEYBYTES bytes long.');
+            }
+        } elseif (\ParagonIE_Sodium_Core_Util::substr($secretKey) !== 64) {
+            throw new \Exception('Signing secret keys must be SODIUM_CRYPTO_SIGN_SECRETKEYBYTES bytes long.');
+        }
         $this->secretKey = $secretKey;
         return $this;
     }
+
+    /**
+     * Don't leak secret keys.
+     *
+     * @return array
+     */
+    public function __debugInfo()
+    {
+        return [];
+    }
 }

src/RemoteFetch.php

@@ -68,6 +68,8 @@ public function __construct(
     }
 
     /**
+     * Do we need to fetch updates?
+     *
      * @return bool
      */
     public function cacheExpired()
@@ -102,6 +104,8 @@ protected function listBundles($customValidator = '')
     }
 
     /**
+     * This handles the actual HTTP request.
+     *
      * @return bool
      * @throws \Exception
      */
@@ -156,6 +160,18 @@ public function setCacheTimeout(\DateInterval $interval)
         return $this;
     }
 
+    /**
+     * Replace the HTTP client with a new one.
+     *
+     * @param Client $client
+     * @return $this
+     */
+    public function setHttpClient(Client $client)
+    {
+        $this->http = $client;
+        return $this;
+    }
+
     /**
      * @param string $url
      * @return self

src/Validator.php

@@ -13,6 +13,8 @@ class Validator
     const BACKUP_SIGNING_PUBKEY = '1cb438a66110689f1192b511a88030f02049c40d196dc1844f9e752531fdd195';
 
     /**
+     * Validate SHA256 checksums.
+     *
      * @param Bundle $bundle
      * @return bool
      */
@@ -23,6 +25,8 @@ public static function checkSha256Sum(Bundle $bundle)
     }
 
     /**
+     * Check Ed25519 signature for this bundle's contents.
+     *
      * @param Bundle $bundle  Which bundle to validate
      * @param bool $backupKey Use the backup key? (Only if the primary is compromised.)
      * @return bool