TEMP VOP

Philipp91 · Philipp91 · commit b27e17ec9c8d · 2025-10-15T22:56:07.000+02:00
diff --git a/lib/Fhp/BaseAction.php b/lib/Fhp/BaseAction.php
@@ -4,6 +4,7 @@
 
 namespace Fhp;
 
+use Fhp\Model\PollingToken;
 use Fhp\Model\TanRequest;
 use Fhp\Protocol\ActionIncompleteException;
 use Fhp\Protocol\BPD;
@@ -48,6 +49,9 @@ abstract class BaseAction implements \Serializable
     /** If set, the last response from the server regarding this action asked for a TAN from the user. */
     protected ?TanRequest $tanRequest = null;
 
+    /** If set, this action is currently waiting for a long-running operation on the server to complete. */
+    protected ?PollingToken $pollingToken = null;
+
     protected bool $isDone = false;
 
     /**
@@ -139,6 +143,16 @@ public function getTanRequest(): ?TanRequest
         return $this->tanRequest;
     }
 
+    public function needsPollingWait(): bool
+    {
+        return !$this->isDone() && $this->pollingToken !== null;
+    }
+
+    public function getPollingToken(): ?PollingToken
+    {
+        return $this->pollingToken;
+    }
+
     /**
      * Throws an exception unless this action has been successfully executed, i.e. in the following cases:
      *  - the action has not been {@link FinTs::execute()}-d at all or the {@link FinTs::execute()} call for it threw an
@@ -248,4 +262,10 @@ final public function setTanRequest(?TanRequest $tanRequest): void
     {
         $this->tanRequest = $tanRequest;
     }
+
+    /** To be called only by the FinTs instance that executes this action. */
+    final public function setPollingToken(?PollingToken $pollingToken): void
+    {
+        $this->pollingToken = $pollingToken;
+    }
 }
diff --git a/lib/Fhp/FinTs.php b/lib/Fhp/FinTs.php
@@ -26,6 +26,9 @@
 use Fhp\Segment\TAN\HKTAN;
 use Fhp\Segment\TAN\HKTANFactory;
 use Fhp\Segment\TAN\HKTANv6;
+use Fhp\Segment\VPP\HKVPPv1;
+use Fhp\Segment\VPP\VopHelper;
+use Fhp\Segment\VPP\VopPollingToken;
 use Fhp\Syntax\InvalidResponseException;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
@@ -285,17 +288,32 @@ public function login(): DialogInitialization
 
     /**
      * Executes an action. Be sure to {@link login()} first. See the `\Fhp\Action` package for actions that can be
-     * executed with this function. Note that, after this function returns, the action can be in two possible states:
+     * executed with this function. Note that, after this function returns, the action can be in the following states:
      * 1. If {@link BaseAction::needsTan()} returns true, the action isn't completed yet because needs a TAN or other
      *    kind of two-factor authentication (2FA). In this case, use {@link BaseAction::getTanRequest()} to get more
      *    information about the TAN/2FA that is needed. Your application then needs to interact with the user to obtain
      *    the TAN (which should be passed into {@link submitTan()}) or to have them complete the 2FA check (which can
      *    be verified with {@link checkDecoupledSubmission()}). Both of those functions require passing the same
      *    {@link BaseAction} argument as an argument, and once they succeed, the action will be in the same completed
      *    state as if it had been completed right away.
-     * 2. If {@link BaseAction::needsTan()} returns false, the action was completed right away. Use the respective
-     *    getters on the action instance to retrieve the result. In case the action fails, the corresponding exception
-     *    will be thrown from this function.
+     * 2. If {@link BaseAction::needsPollingWait()} returns true, the action isn't completed yet because the server is
+     *    still running some slow operation. Importantly, the server has not necessarily accepted the action yet, so it
+     *    is absolutely required that the client keeps polling if they don't want the action to be abandoned.
+     *    In this case, use {@link BaseAction::getPollingToken()} to get more information on how frequently to poll, and
+     *    do the polling through {@link pollAction()}.
+     * 3. If {@link BaseAction::needsVopConfirmation()} returns true, the action isn't completed yet because the payee
+     *    information couldn't be matched automatically, so an explicit confirmation from the user is required. In this
+     *    case, use TODO.
+     * 4. If none of the above return true, the action was completed right away.
+     *    Use the respective getters on the action instance to retrieve the result. In case the action fails, the
+     *    corresponding exception will be thrown from this function.
+     *
+     * Note that all conditions above that leave the action in an incomplete state require some action from the client
+     * application. These actions then change the state of the action again, but they don't necessarily complete it.
+     * In practice, the typical sequence is: Maybe polling, maybe VoP confirmation, maybe TAN, done. That said, you
+     * should ideally implement your application to deal with any sequence of states. Just execute the action, check
+     * what's state it's in, resolve that state as appropriate, and then check again (using the same code as before). Do
+     * this repeatedly until none of the special conditions above happen anymore, at which point the action is done.
      *
      * @param BaseAction $action The action to be executed. Its {@link BaseAction::isDone()} status will be updated when
      *     this function returns successfully.
@@ -324,7 +342,13 @@ public function execute(BaseAction $action): void
                     $this->requireTanMode(), $this->selectedTanMedium, $needTanForSegment));
             }
         }
-        $request = $this->buildMessage($message, $this->getSelectedTanMode());
+
+        // Add HKVPP for VoP verification if necessary.
+        $hkvpp = null;
+        if ($this->bpd?->vopRequiredForRequest($requestSegments) !== null) {
+            $hkvpp = VopHelper::createHKVPPForInitialRequest($this->bpd);
+            $message->add($hkvpp);
+        }
 
         // Construct the request and tell the action about the segment numbers that were assigned.
         $request = $this->buildMessage($message, $this->getSelectedTanMode()); // This fills in the segment numbers.
@@ -372,7 +396,15 @@ private function processServerResponse(BaseAction $action, Message $response, ?H
             return;
         }
 
-        // If no TAN is needed, process the response normally, and maybe keep going for more pages.
+        // Detect if the bank needs us to do something for Verification of Payee.
+        if ($hkvpp != null) {
+            if ($pollingToken = VopHelper::checkPollingRequired($response, $hkvpp->getSegmentNumber())) {
+                $action->setPollingToken($pollingToken);
+                return;
+            }
+        }
+
+        // If no TAN or VOP is needed, process the response normally, and maybe keep going for more pages.
         $this->processActionResponse($action, $response->filterByReferenceSegments($action->getRequestSegmentNumbers()));
         if ($action instanceof PaginateableAction && $action->hasMorePages()) {
             $this->execute($action);
@@ -384,9 +416,9 @@ private function processServerResponse(BaseAction $action, Message $response, ?H
      * `false`, this function sends the given $tan to the server to complete the action. By using {@link persist()},
      * this can be done asynchronously, i.e., not in the same PHP process as the original {@link execute()} call.
      *
-     * After this function returns, the `$action` is completed. That is, its result is available through its getters
-     * just as if it had been completed by the original call to {@link execute()} right away. In case the action fails,
-     * the corresponding exception will be thrown from this function.
+     * After this function returns, the `$action` is in any of the same states as after {@link execute()}, see there.
+     * In practice, the action is fully completed after completing the decoupled submission.
+     * In case the action fails, the corresponding exception will be thrown from this function.
      *
      * @link https://www.hbci-zka.de/dokumente/spezifikation_deutsch/fintsv3/FinTS_3.0_Security_Sicherheitsverfahren_PINTAN_2020-07-10_final_version.pdf
      * Section B.4.2.1.1
@@ -452,7 +484,9 @@ public function submitTan(BaseAction $action, string $tan): void
      * For an action where {@link BaseAction::needsTan()} returns `true` and {@link TanMode::isDecoupled()} returns
      * `true`, this function checks with the server whether the second factor authentication has been completed yet on
      * the secondary device of the user.
-     * -   If so, this completes the given action and returns `true`.
+     * -   If so, this function returns `true` and the `$action` is then in any of the same states as after
+     *     {@link execute()} (except {@link BaseAction::needsTan()} won't happen again). See there for documentation.
+     *     In practice, the action is fully completed after completing the decoupled submission.
      * -   In case the action fails, the corresponding exception will be thrown from this function.
      * -   If the authentication has not been completed yet, this returns `false` and the action remains in its
      *     previous, uncompleted state.
@@ -468,9 +502,10 @@ public function submitTan(BaseAction $action, string $tan): void
      * Section B.4.2.2
      *
      * @param BaseAction $action The action to be completed.
-     * @return bool True if the decoupled authentication is done and the $action was completed. If false, the
-     *     {@link TanRequest} inside the action has been updated, which *may* provide new/more instructions to the user,
-     *     though probably it rarely does in practice.
+     * @return bool True if the decoupled authentication is done and the $action was completed or entered one of the
+     *     other states documented on {@link execute()}.
+     *     If false, the {@link TanRequest} inside the action has been updated, which *may* provide new/more
+     *     instructions to the user, though probably it rarely does in practice.
      * @throws CurlException When the connection fails in a layer below the FinTS protocol.
      * @throws UnexpectedResponseException When the server responds with a valid but unexpected message.
      * @throws ServerException When the server responds with a (FinTS-encoded) error message, which includes most things
@@ -549,6 +584,52 @@ public function checkDecoupledSubmission(BaseAction $action): bool
         return true;
     }
 
+    /**
+     * For an action where {@link BaseAction::needsPollingWait()} returns `true`, this function polls the server.
+     * By using {@link persist()}, this can be done asynchronously, i.e., not in the same PHP process as the original
+     * {@link execute()} call or the previous {@link pollAction()} call.
+     *
+     * After this function returns, the `$action` is in any of the same states as after {@link execute()}, see there. In
+     * particular, it's possible that the long-running operation on the server has not completed yet and thus
+     * {@link BaseAction::needsPollingWait()} still returns `true`. In practice, actions often require VoP confirmation
+     * or a TAN after the polling is over, though they can also complete right away.
+     * In case the action fails, the corresponding exception will be thrown from this function.
+     *
+     * @param BaseAction $action The action to be completed.
+     * @throws CurlException When the connection fails in a layer below the FinTS protocol.
+     * @throws UnexpectedResponseException When the server responds with a valid but unexpected message.
+     * @throws ServerException When the server responds with a (FinTS-encoded) error message, which includes most things
+     *     that can go wrong with the action itself, like wrong credentials, invalid IBANs, locked accounts, etc.
+     * @link FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf
+     * Section C.10.7.1.1 a)
+     *
+     */
+    public function pollAction(BaseAction $action): void
+    {
+        $pollingToken = $action->getPollingToken();
+        if ($pollingToken === null) {
+            throw new \InvalidArgumentException('This action is not awaiting polling for a long-running operation');
+        } elseif ($pollingToken instanceof VopPollingToken) {
+            // Only send a new HKVPP.
+            $hkvpp = VopHelper::createHKVPPForPollingRequest($this->bpd, $pollingToken);
+            $message = MessageBuilder::create()->add($hkvpp);
+
+            // Add HKTAN for authentication if necessary.
+            if (!($this->getSelectedTanMode() instanceof NoPsd2TanMode)) {
+                if (($needTanForSegment = $action->getNeedTanForSegment()) !== null) {
+                    $message->add(HKTANFactory::createProzessvariante2Step1(
+                        $this->requireTanMode(), $this->selectedTanMedium, $needTanForSegment));
+                }
+            }
+
+            // Execute the request and process the response.
+            $response = $this->sendMessage($this->buildMessage($message, $this->getSelectedTanMode()));
+            $this->processServerResponse($action, $response, $hkvpp);
+        } else {
+            throw new \InvalidArgumentException('Unexpected polling token type: ' . gettype($pollingToken));
+        }
+    }
+
     /**
      * Closes the session/dialog/connection, if open. This is equivalent to logging out. You should call this function
      * when you're done with all the actions, but NOT when you're persisting the instance to fulfill the TAN request of
diff --git a/lib/Fhp/Model/PollingToken.php b/lib/Fhp/Model/PollingToken.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Fhp\Model;
+
+/**
+ * Provides information that the client application should use to poll for the completion of a long-running operation on
+ * the server.
+ */
+interface PollingToken
+{
+    /**
+     * @return ?int The number of seconds (measured from the time when the client received this {@link PollingToken})
+     *     after which the client is allowed to contact the server again regarding this action. If this returns null,
+     *     there is no restriction.
+     */
+    public function getNextAttemptInSeconds(): ?int;
+
+    /**
+     * @return ?string A user-readable text (either in the bank's language or in English!) that the application may
+     *     display to the user to inform them (on a very high level) about why they have to wait.
+     */
+    public function getInformationForUser(): ?string;
+}
diff --git a/lib/Fhp/Protocol/BPD.php b/lib/Fhp/Protocol/BPD.php
@@ -10,6 +10,7 @@
 use Fhp\Segment\HIPINS\HIPINSv1;
 use Fhp\Segment\SegmentInterface;
 use Fhp\Segment\TAN\HITANS;
+use Fhp\Segment\VPP\HIVPPSv1;
 
 /**
  * Segmentfolge: Bankparameterdaten (Version 3)
@@ -152,6 +153,28 @@ public function tanRequiredForRequest(array $requestSegments): ?string
         return null;
     }
 
+    /**
+     * @param SegmentInterface[] $requestSegments The segments that shall be sent to the bank.
+     * @return string|null Identifier of the (first) segment that requires Verification of Payee according to HIPINS, or
+     *     null if none of the segments require verification.
+     */
+    public function vopRequiredForRequest(array $requestSegments): ?string
+    {
+        /** @var HIVPPSv1 $hivpps */
+        $hivpps = $this->getLatestSupportedParameters('HIVPPS');
+        $vopRequiredTypes = $hivpps?->parameter?->vopPflichtigerZahlungsverkehrsauftrag;
+        if ($vopRequiredTypes === null) {
+            return null;
+        }
+
+        foreach ($requestSegments as $segment) {
+            if (in_array($segment->getName(), $vopRequiredTypes)) {
+                return $segment->getName();
+            }
+        }
+        return null;
+    }
+
     /**
      * @return bool Whether the BPD indicates that the bank supports PSD2.
      */
diff --git a/lib/Fhp/Protocol/Message.php b/lib/Fhp/Protocol/Message.php
@@ -190,12 +190,17 @@ public function filterByReferenceSegments(array $referenceNumbers): Message
 
     /**
      * @param int $code The response code to search for.
+     * @param ?int $requestSegmentNumber If set, only consider Rueckmeldungen that pertain to this request segment.
      * @return Rueckmeldung|null The corresponding Rueckmeldung instance, or null if not found.
      */
-    public function findRueckmeldung(int $code): ?Rueckmeldung
+    public function findRueckmeldung(int $code, ?int $requestSegmentNumber = null): ?Rueckmeldung
     {
         foreach ($this->plainSegments as $segment) {
-            if ($segment instanceof RueckmeldungContainer) {
+            if (
+                $segment instanceof RueckmeldungContainer && (
+                    $requestSegmentNumber === null || $segment->segmentkopf->bezugselement === $requestSegmentNumber
+                )
+            ) {
                 $rueckmeldung = $segment->findRueckmeldung($code);
                 if ($rueckmeldung !== null) {
                     return $rueckmeldung;
diff --git a/lib/Fhp/Segment/VPP/VopHelper.php b/lib/Fhp/Segment/VPP/VopHelper.php
@@ -0,0 +1,62 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Protocol\BPD;
+use Fhp\Protocol\Message;
+use Fhp\Segment\HIRMS\Rueckmeldungscode;
+
+/** Creates request segments and interprets response segments and Ruckmeldungscodes for anything related to VoP. */
+class VopHelper
+{
+    /**
+     * @param BPD $bpd The BPD.
+     * @return HKVPPv1 A segment to prompt the server to do Verification of Payee.
+     */
+    public static function createHKVPPForInitialRequest(BPD $bpd): HKVPPv1
+    {
+        // For now just pretend we support all formats.
+        /** @var HIVPPSv1 $hivpps */
+        $hivpps = $bpd->getLatestSupportedParameters('HIVPPS');
+        $supportedFormats = explode(';', $hivpps->parameter->unterstuetztePaymentStatusReportDatenformate);
+
+        $hkvpp = HKVPPv1::createEmpty();
+        $hkvpp->unterstuetztePaymentStatusReports->paymentStatusReportDescriptor = $supportedFormats;
+        return $hkvpp;
+    }
+
+    /**
+     * @param BPD $bpd The BPD.
+     * @param VopPollingToken $pollingToken The polling token we got on the immediately preceding request.
+     * @return HKVPPv1 A segment to poll the server for the completion of Verification of Payee.
+     */
+    public static function createHKVPPForPollingRequest(BPD $bpd, VopPollingToken $pollingToken): HKVPPv1
+    {
+        $hkvpp = static::createHKVPPForInitialRequest($bpd);
+        $hkvpp->aufsetzpunkt = $pollingToken->getAufsetzpunkt();
+        $hkvpp->pollingId = $pollingToken->getPollingId();
+        return $hkvpp;
+    }
+
+    /**
+     * @param Message $response The response we just received from the server.
+     * @param int $hkvppSegmentNumber The number of the HKVPP segment in the request we had sent.
+     * @return ?VopPollingToken If the response indicates that the Verification of Payee is still ongoing, such that the
+     *     client should keep polling the server to (actively) wait until the result is available, this function returns
+     *     a corresponding polling token. If no polling is required, it returns null.
+     */
+    public static function checkPollingRequired(Message $response, int $hkvppSegmentNumber): ?VopPollingToken
+    {
+        $aufsetzpunkt = $response->findRueckmeldung(Rueckmeldungscode::AUFSETZPUNKT, $hkvppSegmentNumber);
+        if ($aufsetzpunkt === null) {
+            return null;
+        }
+        /** @var HIVPPv1 $hivpp */
+        $hivpp = $response->findSegment('HIVPP');
+        return new VopPollingToken(
+            $aufsetzpunkt->rueckmeldungsparameter[0],
+            $hivpp?->pollingId,
+            $hivpp?->wartezeitVorNaechsterAbfrage,
+        );
+    }
+}
diff --git a/lib/Fhp/Segment/VPP/VopPollingToken.php b/lib/Fhp/Segment/VPP/VopPollingToken.php
