Merge pull request #4 from redbitcz/plugin

Add Plugin ability

Author: jakubboucek

.gitattributes

@@ -1,4 +1,5 @@
 .gitattributes export-ignore
 .gitignore export-ignore
 .github export-ignore
+phpstan.neon export-ignores
 tests export-ignore

.github/workflows/code_analysis.yaml

@@ -18,11 +18,11 @@ jobs:
             run: composer phpstan
 
           - name: Nette Tester
-            run: composer tester
+            run: composer tester -- -C
+
         php:
           - "7.4"
           - "8.0"
-          - "8.1"
 
     name: ${{ matrix.actions.name }} on PHP ${{ matrix.php }}
     runs-on: ubuntu-latest
@@ -38,6 +38,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
+          extensions: json
           coverage: none
 
 
@@ -53,8 +54,6 @@ jobs:
           path: |
             ${{ steps.composer-cache.outputs.dir }}
           key: ${{ runner.os }}-composer-data-${{ hashFiles('composer.json') }}-php-${{ matrix.php }}
-          restore-keys: |
-            ${{ runner.os }}-composer-data-
 
 
       - uses: actions/cache@v2

.gitignore

@@ -1,4 +1,5 @@
-/vendor
 /composer.lock
-/tests/temp
+/tests/**/output
 /tests/lock
+/tests/temp
+/vendor

.phpstorm.meta.php

@@ -34,4 +34,47 @@
         \Redbitcz\DebugMode\Detector::MODE_ENV,
         \Redbitcz\DebugMode\Detector::MODE_IP
     );
+
+    expectedArguments(
+        \Redbitcz\DebugMode\Plugin\SignedUrl::__construct(),
+        1,
+        'ES384',
+        'ES256',
+        'HS256',
+        'HS384',
+        'HS512',
+        'RS256',
+        'RS384',
+        'RS512'
+    );
+
+    expectedArguments(
+        \Redbitcz\DebugMode\Plugin\SignedUrl::signUrl(),
+        2,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::MODE_REQUEST,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::MODE_ENABLER,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::MODE_DEACTIVATE_ENABLER
+    );
+
+    expectedArguments(
+        \Redbitcz\DebugMode\Plugin\SignedUrl::signUrl(),
+        3,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::VALUE_DISABLE,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::VALUE_ENABLE
+    );
+
+    expectedArguments(
+        \Redbitcz\DebugMode\Plugin\SignedUrl::getToken(),
+        3,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::MODE_REQUEST,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::MODE_ENABLER,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::MODE_DEACTIVATE_ENABLER
+    );
+
+    expectedArguments(
+        \Redbitcz\DebugMode\Plugin\SignedUrl::getToken(),
+        4,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::VALUE_DISABLE,
+        \Redbitcz\DebugMode\Plugin\SignedUrl::VALUE_ENABLE
+    );
 }

README.md

@@ -113,5 +113,74 @@ services:
         imported: true
 ```  
 
+## Plugins
+
+Detector supports custom plugin. You can build custom plugin to provide your own roles to manage Debug Mode. Plugin must
+implements `Plugin` interface what means add `__invoke()` method. That method is called always is Detector aksed to
+detect mode.
+
+Plugin retuns result of detection:
+
+- `null` – no result – Detector will try to ask another plugin or detection method to decide
+- `true` – force turn-on debug mode for current request
+- `false` – force turn-off debug mode for current request
+
+Note: You should return `null` value when Plugin doesn't explicitly matches rule. Boolean value is always stops
+processing detection rules.
+
+Don't do this:
+
+```php
+if (…) {
+    return true;
+} else {
+    return false;
+}
+```
+
+instead return `null` when your rule is not matched: 
+
+```php
+if (…) {
+    return true;
+} else {
+    return null;
+}
+```
+
+Your Plugin you can register to Detector with method `appendPlugin()` or `prepedndPlugin()`.
+
+```php
+$detector = new \Redbitcz\DebugMode\Detector();
+
+$plugin = new MyPlugin();
+
+$detector->appendPlugin($plugin);
+
+$detector->isDebugMode(); // <---- this invoke all Plugins
+```
+
+## SignUrl plugin
+
+`SignUrl` plugin provide secure way to share link with activated Debug Mode. 
+
+```php
+$plugin = new \Redbitcz\DebugMode\Plugin\SignedUrl('secretkey', 'HS256', 'https://myapp.cz');
+$detector->appendPlugin($plugin);
+
+$signedUrl = $plugin->signUrl('https://myapp.cz/failingPage', '+1 hour');
+
+echo 'Private link with activated Debug mode: ' . htmlspecialchars($signedUrl, ENT_QUOTES | ENT_HTML5 | ENT_SUBSTITUTE);
+```
+
+### Security notes
+
+Wrong usage of the `SignUrl` plugin can open critical vulnerability issue at your App. Follow this instructions:  
+
+- Always create `SignUrl` with strong and Secret key, use key generator like: `base64_encode(random_bytes(32))`
+- Always create `SignUrl` with specified `$audience` parameter which distinguishes versions of app (stage vs production)
+to prevent unwanted re-using signatures between them
+([read more about importance of audience](https://stackoverflow.com/a/41237822/1641372)).
+
 ## License
 The MIT License (MIT). Please see [License File](LICENSE) for more information.

composer.json

@@ -16,8 +16,17 @@
     ],
     "require": {
         "php": ">=7.4",
+        "ext-json": "*",
         "nette/utils": "^3.0"
     },
+    "require-dev": {
+        "firebase/php-jwt": "^5.0",
+        "nette/tester": "^2.4",
+        "phpstan/phpstan": "^0.12.98"
+    },
+    "suggest": {
+        "firebase/php-jwt": "Optional, required for SignedUrl plugin"
+    },
     "autoload": {
         "psr-4": {
             "Redbitcz\\DebugMode\\": "src/"
@@ -36,10 +45,6 @@
             "dev-master": "2.0-dev"
         }
     },
-    "require-dev": {
-        "phpstan/phpstan": "^0.12.98",
-        "nette/tester": "^2.4"
-    },
     "scripts": {
         "phpstan": "phpstan analyze src -c phpstan.neon --level 8",
         "tester": "tester tests"

src/Detector.php

@@ -8,6 +8,8 @@
 
 namespace Redbitcz\DebugMode;
 
+use Redbitcz\DebugMode\Plugin\Plugin;
+
 class Detector
 {
     /** Name of Environment variable used to detect Debug mode */
@@ -36,10 +38,12 @@ class Detector
 
 
     private ?Enabler $enabler;
-    private int $mode;
     /** @var string[] */
     private array $ips = ['::1', '127.0.0.1'];
 
+    /** @var array<int, callable> */
+    private array $detections;
+
     /**
      * @param int $mode Enables methods which is used to detect Debug mode
      * @param Enabler|null $enabler Enabler instance. Optional, but required when Enabler mode is enabled
@@ -52,8 +56,21 @@ public function __construct(int $mode = self::MODE_SIMPLE, ?Enabler $enabler = n
             );
         }
 
+        $this->detections = array_filter(
+            [
+                $mode & self::MODE_ENABLER ? [$this, 'isDebugModeByEnabler'] : null,
+                $mode & self::MODE_COOKIE ? [$this, 'isDebugModeByCookie'] : null,
+                $mode & self::MODE_ENV ? [$this, 'isDebugModeByEnv'] : null,
+                $mode & self::MODE_IP ? [$this, 'isDebugModeByIp'] : null,
+            ]
+        );
+
         $this->enabler = $enabler;
-        $this->mode = $mode;
+    }
+
+    public function hasEnabler(): bool
+    {
+        return $this->enabler !== null;
     }
 
     public function getEnabler(): Enabler
@@ -74,11 +91,12 @@ public function getEnabler(): Enabler
      */
     public function isDebugMode(?bool $default = false): ?bool
     {
-        return ($this->mode & self::MODE_ENABLER ? $this->isDebugModeByEnabler() : null)
-            ?? ($this->mode & self::MODE_COOKIE ? $this->isDebugModeByCookie() : null)
-            ?? ($this->mode & self::MODE_ENV ? $this->isDebugModeByEnv() : null)
-            ?? ($this->mode & self::MODE_IP ? $this->isDebugModeByIp() : null)
-            ?? $default;
+        foreach ($this->detections as $detection) {
+            if (($result = $detection($this)) !== null) {
+                return $result;
+            }
+        }
+        return $default;
     }
 
     /**
@@ -152,6 +170,7 @@ public function isDebugModeByIp(): ?bool
 
     /**
      * Set client IP address with allowed Debug mode
+     * @return static
      */
     public function setAllowedIp(string ...$ips): self
     {
@@ -161,13 +180,28 @@ public function setAllowedIp(string ...$ips): self
 
     /**
      * Add client IP address with allowed Debug mode
+     * @return static
      */
     public function addAllowedIp(string ...$ips): self
     {
         $this->ips = array_merge($this->ips, $ips);
         return $this;
     }
 
+    /** @return static */
+    public function prependPlugin(Plugin $plugin): self
+    {
+        array_unshift($this->detections, $plugin);
+        return $this;
+    }
+
+    /** @return static */
+    public function appendPlugin(Plugin $plugin): self
+    {
+        $this->detections[] = $plugin;
+        return $this;
+    }
+
     /**
      * Shortcut to simple detect Debug mode by all method enabled by Detector mode (argument `$mode`)
      *

src/Enabler.php

@@ -8,6 +8,7 @@
 
 namespace Redbitcz\DebugMode;
 
+use DateTimeInterface;
 use Nette\IOException;
 use Nette\Utils\DateTime as NetteDateTime;
 use Nette\Utils\FileSystem;
@@ -68,14 +69,17 @@ public function setCookieOptions(
         return $this;
     }
 
-    public function activate(bool $isDebug, ?string $time = self::DEFAULT_TTL): void
+    /**
+     * @param string|int|DateTimeInterface|null $expires
+     */
+    public function activate(bool $isDebug, $expires = null): void
     {
         if ($tokenName = $this->getTokenName()) {
             $this->destroyToken($tokenName);
         }
 
-        $tokenExpires = (int)NetteDateTime::from($time ?? self::DEFAULT_TTL)->format('U');
-        $cookieExpires = $time === null ? 0 : $tokenExpires;
+        $tokenExpires = (int)NetteDateTime::from($expires ?? self::DEFAULT_TTL)->format('U');
+        $cookieExpires = $expires === null ? 0 : $tokenExpires;
         $tokenName = $this->createToken($isDebug, $tokenExpires);
         setcookie(self::DEBUG_COOKIE_NAME, $tokenName, ['expires' => $cookieExpires] + $this->cookieOptions);
 

src/Plugin/Plugin.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Redbitcz\DebugMode\Plugin;
+
+use Redbitcz\DebugMode\Detector;
+
+interface Plugin
+{
+    /**
+     * Method invoked when Debug mode detection is called
+     * Returned value:
+     *   - `true` (force to turn-on debug mode)
+     *   - `false` (force to turn-off debug mode)
+     *   - `null` (unknown debug mode state, next detection method will be called)
+     */
+    public function __invoke(Detector $detector): ?bool;
+}