feat: add password hashing

innocenzi · innocenzi · commit d4edc5d00090 · 2025-07-03T17:51:44.000+02:00
diff --git a/composer.json b/composer.json
@@ -75,6 +75,7 @@
         "tempest/console": "self.version",
         "tempest/container": "self.version",
         "tempest/core": "self.version",
+        "tempest/cryptography": "self.version",
         "tempest/database": "self.version",
         "tempest/datetime": "self.version",
         "tempest/debug": "self.version",
@@ -110,6 +111,7 @@
             "Tempest\\Console\\": "packages/console/src",
             "Tempest\\Container\\": "packages/container/src",
             "Tempest\\Core\\": "packages/core/src",
+            "Tempest\\Cryptography\\": "packages/cryptography/src",
             "Tempest\\Database\\": "packages/database/src",
             "Tempest\\DateTime\\": "packages/datetime/src",
             "Tempest\\Debug\\": "packages/debug/src",
@@ -173,6 +175,7 @@
             "Tempest\\Console\\Tests\\": "packages/console/tests",
             "Tempest\\Container\\Tests\\": "packages/container/tests",
             "Tempest\\Core\\Tests\\": "packages/core/tests",
+            "Tempest\\Cryptography\\Tests\\": "packages/cryptography/tests",
             "Tempest\\Database\\Tests\\": "packages/database/tests",
             "Tempest\\DateTime\\Tests\\": "packages/datetime/tests",
             "Tempest\\EventBus\\Tests\\": "packages/event-bus/tests",
diff --git a/packages/cryptography/.gitattributes b/packages/cryptography/.gitattributes
@@ -0,0 +1,14 @@
+# Exclude build/test files from the release
+.github/                  export-ignore
+tests/                    export-ignore
+.gitattributes            export-ignore
+.gitignore                export-ignore
+phpunit.xml               export-ignore
+README.md                 export-ignore
+
+# Configure diff output
+*.view.php diff=html
+*.php diff=php
+*.css diff=css
+*.html diff=html
+*.md diff=markdown
diff --git a/packages/cryptography/LICENCE.md b/packages/cryptography/LICENCE.md
@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Brent Roose brendt@stitcher.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/packages/cryptography/composer.json b/packages/cryptography/composer.json
@@ -0,0 +1,21 @@
+{
+    "name": "tempest/cryptography",
+    "description": "A component for working with passwords, hashing, and cryptography.",
+    "license": "MIT",
+    "minimum-stability": "dev",
+    "require": {
+        "php": "^8.4",
+        "tempest/container": "dev-main",
+        "tempest/support": "dev-main"
+    },
+    "autoload": {
+        "psr-4": {
+            "Tempest\\Cryptography\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Tempest\\Cryptography\\Tests\\": "tests"
+        }
+    }
+}
diff --git a/packages/cryptography/phpunit.xml b/packages/cryptography/phpunit.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.4/phpunit.xsd"
+	bootstrap="vendor/autoload.php"
+	executionOrder="depends,defects"
+	beStrictAboutOutputDuringTests="true"
+	displayDetailsOnPhpunitDeprecations="true"
+	failOnPhpunitDeprecation="false"
+	failOnRisky="true"
+	failOnWarning="true"
+>
+	<testsuites>
+		<testsuite name="Tempest cryptography">
+			<directory>tests</directory>
+		</testsuite>
+	</testsuites>
+	<source restrictNotices="true" restrictWarnings="true" ignoreIndirectDeprecations="true">
+		<include>
+			<directory>src</directory>
+		</include>
+	</source>
+</phpunit>
diff --git a/packages/cryptography/src/Password/ArgonConfig.php b/packages/cryptography/src/Password/ArgonConfig.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+final class ArgonConfig implements PasswordHashingConfig
+{
+    public HashingAlgorithm $algorithm = HashingAlgorithm::ARGON2ID;
+
+    public array $options {
+        get => [
+            'memory_cost' => $this->memoryCost,
+            'time_cost' => $this->timeCost,
+            'threads' => $this->threads,
+        ];
+    }
+
+    /**
+     * @param int $memoryCost The amount of memory in bytes that Argon will use while trying to compute a hash. The higher, the more resistant to GPU/ASIC attacks, but also more resource-intensive and slow.
+     * @param int $timeCost Number of passes Argon will perform over the memory. Increasing this increases the computation time but makes brute-force attacks slower.
+     * @param int $threads Number of threads used to compute the hash. More threads can improve performance on multi-core CPUs by parallelizing the computation, but may impact other processes.
+     */
+    public function __construct(
+        public int $memoryCost = PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
+        public int $timeCost = PASSWORD_ARGON2_DEFAULT_TIME_COST,
+        public int $threads = PASSWORD_ARGON2_DEFAULT_THREADS,
+    ) {}
+}
diff --git a/packages/cryptography/src/Password/BcryptConfig.php b/packages/cryptography/src/Password/BcryptConfig.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+use Tempest\Cryptography\Password\HashingAlgorithm;
+
+final class BcryptConfig implements PasswordHashingConfig
+{
+    public HashingAlgorithm $algorithm = HashingAlgorithm::BCRYPT;
+
+    public array $options {
+        get => [
+            'cost' => $this->cost,
+        ];
+    }
+
+    /**
+     * @param int $cost Number of iterations bcrypt will perform. Increasing this increases the computation time but makes brute-force attacks slower.
+     */
+    public function __construct(
+        public int $cost = PASSWORD_BCRYPT_DEFAULT_COST,
+    ) {}
+}
diff --git a/packages/cryptography/src/Password/Exceptions/HashingFailed.php b/packages/cryptography/src/Password/Exceptions/HashingFailed.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace Tempest\Cryptography\Password\Exceptions;
+
+use Exception;
+
+final class HashingFailed extends Exception implements PasswordHashingException
+{
+    public static function forUnknownReason(): self
+    {
+        return new self('Hashing resulted in an error.');
+    }
+
+    public static function forEmptyPassword(): self
+    {
+        return new self('Could not hash an empty password.');
+    }
+}
diff --git a/packages/cryptography/src/Password/Exceptions/PasswordHashingException.php b/packages/cryptography/src/Password/Exceptions/PasswordHashingException.php
@@ -0,0 +1,7 @@
+<?php
+
+namespace Tempest\Cryptography\Password\Exceptions;
+
+interface PasswordHashingException
+{
+}
diff --git a/packages/cryptography/src/Password/GenericPasswordHasher.php b/packages/cryptography/src/Password/GenericPasswordHasher.php
@@ -0,0 +1,67 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+use Tempest\Cryptography\Password\Exceptions\HashingFailed;
+use Tempest\Cryptography\Password\HashingAlgorithm;
+
+final class GenericPasswordHasher implements PasswordHasher
+{
+    public HashingAlgorithm $algorithm {
+        get => $this->config->algorithm;
+    }
+
+    public function __construct(
+        private readonly PasswordHashingConfig $config,
+    ) {}
+
+    public function hash(#[\SensitiveParameter] string $password): string
+    {
+        $hash = password_hash($password, $this->algorithm->value, $this->config->options);
+
+        if ($hash === false) {
+            throw HashingFailed::forUnknownReason();
+        }
+
+        if (mb_strlen($password) === 0) {
+            throw HashingFailed::forEmptyPassword();
+        }
+
+        return $hash;
+    }
+
+    public function verify(#[\SensitiveParameter] string $password, #[\SensitiveParameter] string $hash): bool
+    {
+        if (mb_strlen($hash) === 0) {
+            return false;
+        }
+
+        return password_verify($password, $hash);
+    }
+
+    public function needsRehash(#[\SensitiveParameter] string $hash): bool
+    {
+        return password_needs_rehash($hash, $this->algorithm->value, $this->config->options);
+    }
+
+    public function analyze(#[\SensitiveParameter] string $hash): Hash
+    {
+        $info = password_get_info($hash);
+        $algorithm = HashingAlgorithm::from($info['algo']);
+
+        return new Hash(
+            hash: $hash,
+            algorithm: $algorithm,
+            config: match ($algorithm) {
+                HashingAlgorithm::BCRYPT => new BcryptConfig(
+                    cost: $info['options']['cost'] ?? PASSWORD_BCRYPT_DEFAULT_COST,
+                ),
+                HashingAlgorithm::ARGON2ID => new ArgonConfig(
+                    memoryCost: $info['options']['memory_cost'] ?? PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
+                    timeCost: $info['options']['time_cost'] ?? PASSWORD_ARGON2_DEFAULT_TIME_COST,
+                    threads: $info['options']['threads'] ?? PASSWORD_ARGON2_DEFAULT_THREADS,
+                ),
+            },
+        );
+    }
+}
diff --git a/packages/cryptography/src/Password/Hash.php b/packages/cryptography/src/Password/Hash.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+final readonly class Hash
+{
+    public function __construct(
+        #[\SensitiveParameter]
+        public string $hash,
+        public HashingAlgorithm $algorithm,
+        public PasswordHashingConfig $config,
+    ) {}
+}
diff --git a/packages/cryptography/src/Password/HashingAlgorithm.php b/packages/cryptography/src/Password/HashingAlgorithm.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+enum HashingAlgorithm: string
+{
+    /**
+     * @see https://en.wikipedia.org/wiki/Argon2
+     */
+    case ARGON2ID = PASSWORD_ARGON2ID;
+
+    /**
+     * @see https://en.wikipedia.org/wiki/bcrypt
+     */
+    case BCRYPT = PASSWORD_BCRYPT;
+}
diff --git a/packages/cryptography/src/Password/PasswordHasher.php b/packages/cryptography/src/Password/PasswordHasher.php
@@ -0,0 +1,33 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+use Tempest\Cryptography\Password\HashingAlgorithm;
+
+interface PasswordHasher
+{
+    public HashingAlgorithm $algorithm {
+        get;
+    }
+
+    /**
+     * Hashes the specified password.
+     */
+    public function hash(#[\SensitiveParameter] string $password): string;
+
+    /**
+     * Checks if the given pain-text password matches the given hash.
+     */
+    public function verify(#[\SensitiveParameter] string $password, string $hash): bool;
+
+    /**
+     * Checks if the given hash needs to be rehashed, which happens
+     * when the initial hash was created with different algorithm options.
+     */
+    public function needsRehash(#[\SensitiveParameter] string $hash): bool;
+
+    /**
+     * Returns informations about the given hash, such as the algorithm used and its options.
+     */
+    public function analyze(#[\SensitiveParameter] string $hash): Hash;
+}
diff --git a/packages/cryptography/src/Password/PasswordHasherInitializer.php b/packages/cryptography/src/Password/PasswordHasherInitializer.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+
+final class PasswordHasherInitializer implements Initializer
+{
+    #[Singleton]
+    public function initialize(Container $container): PasswordHasher
+    {
+        return new GenericPasswordHasher($container->get(PasswordHashingConfig::class));
+    }
+}
diff --git a/packages/cryptography/src/Password/PasswordHashingConfig.php b/packages/cryptography/src/Password/PasswordHashingConfig.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace Tempest\Cryptography\Password;
+
+interface PasswordHashingConfig
+{
+    public HashingAlgorithm $algorithm {
+        get;
+    }
+
+    /**
+     * Options for PHP's `password_hash` and `password_verify` functions.
+     */
+    public array $options {
+        get;
+    }
+}
diff --git a/packages/cryptography/src/Password/hashing.config.php b/packages/cryptography/src/Password/hashing.config.php
@@ -0,0 +1,5 @@
+<?php
+
+use Tempest\Cryptography\Password\ArgonConfig;
+
+return new ArgonConfig();
diff --git a/packages/cryptography/tests/Password/PasswordHasherTest.php b/packages/cryptography/tests/Password/PasswordHasherTest.php
diff --git a/tests/Integration/Cryptography/PasswordHasherTest.php b/tests/Integration/Cryptography/PasswordHasherTest.php

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +<?php
++
 +namespace Tempest\Cryptography\Password\Exceptions;
++
 +interface PasswordHashingException
 +{
 +}