Merge pull request #218 from Slamdunk/microsoft_pop3_xoauth2

Add support for Microsoft POP3 XOAUTH2

src/Protocol/Pop3.php

@@ -2,6 +2,7 @@
 
 namespace Laminas\Mail\Protocol;
 
+use Laminas\Mail\Protocol\Pop3\Response;
 use Laminas\Stdlib\ErrorHandler;
 
 use function explode;
@@ -151,25 +152,14 @@ public function sendRequest($request)
  */
  public function readResponse($multiline = false)
  {
- ErrorHandler::start();
- $result = fgets($this->socket);
- $error = ErrorHandler::stop();
- if (! is_string($result)) {
- throw new Exception\RuntimeException('read failed - connection closed?', 0, $error);
- }
+ $response = $this->readRemoteResponse();
 
- $result = trim($result);
- if (strpos($result, ' ')) {
- [$status, $message] = explode(' ', $result, 2);
- } else {
- $status = $result;
- $message = '';
- }
-
- if ($status != '+OK') {
+ if ($response->status() != '+OK') {
  throw new Exception\RuntimeException('last request failed');
  }
 
+ $message = $response->message();
+
  if ($multiline) {
  $message = '';
  $line = fgets($this->socket);
@@ -185,6 +175,32 @@ public function readResponse($multiline = false)
  return $message;
  }
 
+ /**
+ * read a response
+ * return extracted status / message from response
+
+ * @throws Exception\RuntimeException
+ */
+ protected function readRemoteResponse(): Response
+ {
+ ErrorHandler::start();
+ $result = fgets($this->socket);
+ $error = ErrorHandler::stop();
+ if (! is_string($result)) {
+ throw new Exception\RuntimeException('read failed - connection closed?', 0, $error);
+ }
+
+ $result = trim($result);
+ if (strpos($result, ' ')) {
+ [$status, $message] = explode(' ', $result, 2);
+ } else {
+ $status = $result;
+ $message = '';
+ }
+
+ return new Response($status, $message);
+ }
+
  /**
  * Send request and get response
  *

src/Protocol/Pop3/Response.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Mail\Protocol\Pop3;
+
+/**
+ * POP3 response value object
+ *
+ * @internal
+ */
+final class Response
+{
+ /** @var string $status */
+ private $status;
+
+ /** @var string $message */
+ private $message;
+
+ public function __construct(string $status, string $message)
+ {
+ $this->status = $status;
+ $this->message = $message;
+ }
+
+ public function status(): string
+ {
+ return $this->status;
+ }
+
+ public function message(): string
+ {
+ return $this->message;
+ }
+}

src/Protocol/Pop3/Xoauth2/Microsoft.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Laminas\Mail\Protocol\Pop3\Xoauth2;
+
+use Laminas\Mail\Protocol\Exception\RuntimeException;
+use Laminas\Mail\Protocol\Pop3;
+use Laminas\Mail\Protocol\Xoauth2\Xoauth2;
+
+/**
+ * @final
+ */
+class Microsoft extends Pop3
+{
+ protected const AUTH_INITIALIZE_REQUEST = 'AUTH XOAUTH2';
+ protected const AUTH_RESPONSE_INITIALIZED_OK = '+';
+
+ /**
+ * @param string $user the target mailbox to access
+ * @param string $password OAUTH2 accessToken
+ * @param bool $tryApop obsolete parameter not used here
+ */
+ public function login($user, $password, $tryApop = true): void
+ {
+ $this->sendRequest(self::AUTH_INITIALIZE_REQUEST);
+
+ $response = $this->readRemoteResponse();
+
+ if ($response->status() != self::AUTH_RESPONSE_INITIALIZED_OK) {
+ throw new RuntimeException($response->message());
+ }
+
+ $this->request(Xoauth2::encodeXoauth2Sasl($user, $password));
+ }
+}

src/Protocol/Xoauth2/Xoauth2.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Mail\Protocol\Xoauth2;
+
+use function base64_encode;
+use function chr;
+use function sprintf;
+
+/**
+ * @internal
+ */
+final class Xoauth2
+{
+ /**
+ * encodes accessToken and target mailbox to Xoauth2 SASL base64 encoded string
+ */
+ public static function encodeXoauth2Sasl(string $targetMailbox, string $accessToken): string
+ {
+ return base64_encode(
+ sprintf(
+ "user=%s%sauth=Bearer %s%s%s",
+ $targetMailbox,
+ chr(0x01),
+ $accessToken,
+ chr(0x01),
+ chr(0x01)
+ )
+ );
+ }
+}

test/Protocol/Pop3/ResponseTest.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Mail\Protocol\Pop3;
+
+use Laminas\Mail\Protocol\Pop3\Response;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @covers Laminas\Mail\Protocol\Pop3\Response
+ */
+class ResponseTest extends TestCase
+{
+ /** @psalm-suppress InternalClass */
+ public function testIntegration(): void
+ {
+ /** @psalm-suppress InternalMethod */
+ $response = new Response('+OK', 'Auth');
+
+ /** @psalm-suppress InternalMethod */
+ $this->assertEquals('+OK', $response->status());
+
+ /** @psalm-suppress InternalMethod */
+ $this->assertEquals('Auth', $response->message());
+ }
+}

test/Protocol/Pop3/Xoauth2/MicrosoftTest.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Mail\Protocol\Pop3\Xoauth2;
+
+use Laminas\Mail\Exception\RuntimeException;
+use Laminas\Mail\Protocol\Pop3\Response;
+use Laminas\Mail\Protocol\Pop3\Xoauth2\Microsoft;
+use Laminas\Mail\Protocol\Xoauth2\Xoauth2;
+use PHPUnit\Framework\TestCase;
+
+use function fopen;
+use function rewind;
+use function str_replace;
+use function stream_get_contents;
+
+/**
+ * @covers Laminas\Mail\Protocol\Pop3\Xoauth2\Microsoft
+ */
+class MicrosoftTest extends TestCase
+{
+ /** @psalm-suppress InternalClass */
+ public function testIntegration(): void
+ {
+ /**
+ * @psalm-suppress PropertyNotSetInConstructor
+ * @psalm-suppress InvalidExtendClass
+ */
+ $protocol = new class () extends Microsoft {
+ private string $step;
+
+ /** @psalm-suppress InternalClass */
+ public function readRemoteResponse(): Response
+ {
+ if ($this->step === self::AUTH_INITIALIZE_REQUEST) {
+ /** @psalm-suppress InternalMethod */
+ return new Response(self::AUTH_RESPONSE_INITIALIZED_OK, 'Auth initialized');
+ }
+
+ /** @psalm-suppress InternalMethod */
+ return new Response('+OK', 'Authenticated');
+ }
+
+ /**
+ * Send a request
+ *
+ * @param string $request your request without newline
+ * @throws RuntimeException
+ */
+ public function sendRequest($request): void
+ {
+ $this->step = $request;
+ parent::sendRequest($request);
+ }
+
+ /**
+ * Open connection to POP3 server
+ *
+ * @param string $host hostname or IP address of POP3 server
+ * @param int|null $port of POP3 server, default is 110 (995 for ssl)
+ * @param string|bool $ssl use 'SSL', 'TLS' or false
+ * @throws RuntimeException
+ * @return string welcome message
+ */
+ public function connect($host, $port = null, $ssl = false)
+ {
+ $this->socket = fopen("php://memory", 'rw+');
+ return '';
+ }
+
+ /**
+ * @return null|resource
+ */
+ public function getSocket()
+ {
+ return $this->socket;
+ }
+ };
+
+ $protocol->connect('localhost', 0, false);
+
+ $protocol->login('[email protected]', '123');
+
+ $this->assertInstanceOf(Microsoft::class, $protocol);
+
+ $streamContents = '';
+ if ($socket = $protocol->getSocket()) {
+ rewind($socket);
+ $streamContents = stream_get_contents($socket);
+ $streamContents = str_replace("\r\n", "\n", $streamContents);
+ }
+
+ /** @psalm-suppress InternalMethod */
+ $xoauth2Sasl = Xoauth2::encodeXoauth2Sasl('[email protected]', '123');
+
+ $this->assertEquals(
+ 'AUTH XOAUTH2' . "\n" . $xoauth2Sasl . "\n",
+ $streamContents
+ );
+ }
+}

test/Protocol/Xoauth2/Xoauth2Test.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Mail\Protocol\Xoauth2;
+
+use Laminas\Mail\Protocol\Xoauth2\Xoauth2;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @covers Laminas\Mail\Protocol\Xoauth2\Xoauth2
+ */
+class Xoauth2Test extends TestCase
+{
+ /** @psalm-suppress InternalClass */
+ public function testEncodeXoauth2Sasl(): void
+ {
+ $accessToken = 'dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVyIEV3QkFBbDNCQUFVRkZwVUFvN';
+ $accessToken .= '0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==';
+
+ /**
+ * @psalm-suppress InternalMethod
+ */
+ $this->assertEquals(
+ $accessToken,
+ Xoauth2::encodeXoauth2Sasl(
+ '[email protected]',
+ 'EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA'
+ )
+ );
+ }
+}