Merge pull request #76 from php-telegram-bot/validate-secret_token

Add and validate new secret_token webhook parameter

Author: noplanman

CHANGELOG.md

@@ -7,6 +7,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ### Notes
 - [:ledger: View file changes][Unreleased]
 ### Added
+- Enforce `secret_token` webhook validation check.
 ### Changed
 ### Deprecated
 ### Removed

README.md

@@ -211,6 +211,8 @@ $bot = new BotManager([
         'max_connections' => 20,
         // (array) List the types of updates you want your bot to receive.
         'allowed_updates' => ['message', 'edited_channel_post', 'callback_query'],
+        // (string) Secret token to validate webhook requests.
+        'secret_token'    => 'super_secret_token',
     ],
 
     // (bool) Only allow webhook access from valid Telegram API IPs.

src/BotManager.php

@@ -206,6 +206,7 @@ public function validateAndSetWebhook(): self
                 'certificate'     => $webhook['certificate'] ?? null,
                 'max_connections' => $webhook['max_connections'] ?? null,
                 'allowed_updates' => $webhook['allowed_updates'] ?? null,
+                'secret_token'    => $webhook['secret_token'] ?? null,
             ], function ($v, $k) {
                 if ($k === 'allowed_updates') {
                     // Special case for allowed_updates, which can be an empty array.
@@ -562,6 +563,12 @@ public function isValidRequest(): bool
             return true;
         }
 
+        return $this->isValidRequestIp()
+            && $this->isValidRequestSecretToken();
+    }
+
+    protected function isValidRequestIp(): bool
+    {
         $ip = $_SERVER['REMOTE_ADDR'] ?? '0.0.0.0';
         foreach (['HTTP_CLIENT_IP', 'HTTP_X_FORWARDED_FOR'] as $key) {
             if (filter_var($_SERVER[$key] ?? null, FILTER_VALIDATE_IP)) {
@@ -576,6 +583,18 @@ public function isValidRequest(): bool
         ));
     }
 
+    protected function isValidRequestSecretToken(): bool
+    {
+        $secret_token     = $this->params->getBotParam('webhook.secret_token');
+        $secret_token_api = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? null;
+
+        if ($secret_token || $secret_token_api) {
+            return $secret_token === $secret_token_api;
+        }
+
+        return true;
+    }
+
     /**
      * Make sure this is a valid request.
      *

tests/BotManagerTest.php

@@ -47,14 +47,26 @@ public static function setUpBeforeClass(): void
         ];
     }
 
+    protected function setUp(): void
+    {
+        unset($_SERVER['HTTP_X_FORWARDED_FOR'], $_SERVER['HTTP_CLIENT_IP'], $_SERVER['REMOTE_ADDR'], $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN']);
+
+        parent::setUp();
+    }
+
     /**
      * To test the live commands, act as if we're being called by Telegram.
      */
-    protected function makeRequestValid(): void
+    protected function makeRequestIpValid(): void
     {
         $_SERVER['REMOTE_ADDR'] = '149.154.167.197';
     }
 
+    protected function applyRequestSecretToken(?string $token): void
+    {
+        $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] = $token;
+    }
+
     public function testSetParameters(): void
     {
         $botManager = new BotManager(array_merge(ParamsTest::$demo_vital_params, [
@@ -233,7 +245,7 @@ public function testValidateAndSetWebhookSuccessLiveBot(): void
      */
     public function testDeleteWebhookViaRunLiveBot(): void
     {
-        $this->makeRequestValid();
+        $this->makeRequestIpValid();
         $_GET       = ['a' => 'unset'];
         $botManager = new BotManager(array_merge(self::$live_params, [
             'webhook' => ['url' => 'https://example.com/hook.php'],
@@ -380,35 +392,33 @@ public function testIsValidRequestValidateByDefault(): void
         self::assertTrue($botManager->getParams()->getBotParam('validate_request'));
     }
 
-    public function testIsValidRequestFailValidation(): void
-    {
-        $botManager = new BotManager(ParamsTest::$demo_vital_params);
-
-        unset($_SERVER['HTTP_X_FORWARDED_FOR'], $_SERVER['HTTP_CLIENT_IP'], $_SERVER['REMOTE_ADDR']);
-
-        foreach (['HTTP_X_FORWARDED_FOR', 'HTTP_CLIENT_IP', 'REMOTE_ADDR'] as $key) {
-            $_SERVER[$key] = '1.1.1.1';
-            self::assertFalse($botManager->isValidRequest());
-            unset($_SERVER[$key]);
-        }
-    }
-
     public function testIsValidRequestSkipValidation(): void
     {
         $botManager = new BotManager(array_merge(ParamsTest::$demo_vital_params, [
             'validate_request' => false,
+            'webhook'          => ['secret_token' => 'top-secret'],
         ]));
 
-        unset($_SERVER['HTTP_X_FORWARDED_FOR'], $_SERVER['HTTP_CLIENT_IP'], $_SERVER['REMOTE_ADDR']);
+        $_SERVER['REMOTE_ADDR'] = '1.1.1.1';
+        $this->applyRequestSecretToken('not-legit');
 
         self::assertTrue($botManager->isValidRequest());
     }
 
-    public function testIsValidRequestValidate(): void
+    public function testIsValidRequestIpFailValidation(): void
     {
         $botManager = new BotManager(ParamsTest::$demo_vital_params);
 
-        unset($_SERVER['HTTP_X_FORWARDED_FOR'], $_SERVER['HTTP_CLIENT_IP'], $_SERVER['REMOTE_ADDR']);
+        foreach (['HTTP_X_FORWARDED_FOR', 'HTTP_CLIENT_IP', 'REMOTE_ADDR'] as $key) {
+            $_SERVER[$key] = '1.1.1.1';
+            self::assertFalse($botManager->isValidRequest());
+            unset($_SERVER[$key]);
+        }
+    }
+
+    public function testIsValidRequestIpValidate(): void
+    {
+        $botManager = new BotManager(ParamsTest::$demo_vital_params);
 
         // Lower range.
         $_SERVER['REMOTE_ADDR'] = '149.154.159.255';
@@ -431,13 +441,46 @@ public function testIsValidRequestValidate(): void
         self::assertFalse($botManager->isValidRequest());
     }
 
+    public function testIsValidRequestSecretTokenValidation(): void
+    {
+        $this->makeRequestIpValid();
+
+        // NO config + NO header = VALID
+        $botManager = new BotManager(ParamsTest::$demo_vital_params);
+        self::assertTrue($botManager->isValidRequest());
+
+        // NO config + YES header = INVALID
+        $this->applyRequestSecretToken('top-secret');
+        self::assertFalse($botManager->isValidRequest());
+
+        // YES config + NO header = INVALID
+        $botManager = new BotManager(array_merge(ParamsTest::$demo_vital_params, [
+            'webhook' => ['secret_token' => 'top-secret'],
+        ]));
+        $this->applyRequestSecretToken(null);
+        self::assertFalse($botManager->isValidRequest());
+
+        // YES config + YES header
+        $botManager = new BotManager(array_merge(ParamsTest::$demo_vital_params, [
+            'webhook' => ['secret_token' => 'top-secret'],
+        ]));
+
+        // + NO equal = INVALID
+        $this->applyRequestSecretToken('not-legit');
+        self::assertFalse($botManager->isValidRequest());
+
+        // + YES equal = VALID
+        $this->applyRequestSecretToken('top-secret');
+        self::assertTrue($botManager->isValidRequest());
+    }
+
     /**
      * @group live
      * @runInSeparateProcess
      */
     public function testGetUpdatesLiveBot(): void
     {
-        $this->makeRequestValid();
+        $this->makeRequestIpValid();
         $botManager = new BotManager(self::$live_params);
         $output     = $botManager->run()->getOutput();
         self::assertStringContainsString('Updates processed: 0', $output);
@@ -449,7 +492,7 @@ public function testGetUpdatesLiveBot(): void
      */
     public function testGetUpdatesLoopLiveBot(): void
     {
-        $this->makeRequestValid();
+        $this->makeRequestIpValid();
         // Webhook MUST NOT be set for this to work!
         $this->testDeleteWebhookViaRunLiveBot();