Update notification based signature to use v3.1 endpoints (#141)

* SLIB-126 - add util to create callbackUrl with url-token

* SLIB-126 - move UrlSafeTokenGenerator and CallbackUrl to common package

* SLIB-116 - update notification-based signature path and request object

* SLIB-116 - update notification-based signature session request builder

* SLIB-116 - add pattern validation for verification code value

* SLIB-116 - convert NotificationCertificateChoiceSessionResponse into record

* SLIB-116 - convert NotificationSignatureSessionResponse into record

* SLIB-116 - convert VerificationCode into record

* SLIB-116 - fix notification-based signature session readme integration tests

* SLIB-116 - improve tests for notification-based signature flow

* SLIB-116 - fix typo in package name

* SLIB-116 - code style improvements

* SLIB-116 - improve documentation for idempotent behaviour in Readme

Author: umuser

CHANGELOG.md

@@ -4,6 +4,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Changes mentioned under 3.1.x version have not been published yet. Will be released when v3.1 is stable.
 
+## [3.1.17] - 2025-10-07
+- Updated SmartIdRestConnector to use v3.1 notification-based signature endpoint
+
 ## [3.1.16] - 2025-10-04
 - Updated SmartIdRestConnector to use v3.1 notification-based certificate choice endpoint
 - Added AccountUnusableException to handle ACCOUNT_UNUSABLE endResult from session status response

README.md

@@ -990,7 +990,7 @@ the Smart-ID API will stay waiting for the RP to start the [linked notification-
 * `relyingPartyUUID`: Required. UUID of the Relying Party.
 * `relyingPartyName`: Required. Friendly name of the Relying Party, limited to 32 bytes in UTF-8 encoding.
 * `certificateLevel`: Level of certificate requested. ADVANCED/QUALIFIED/QSCD, defaults to QUALIFIED.
-* `nonce`: Random string, up to 30 characters. If present, must have at least 1 character. Used for overriding idempotency.
+* `nonce`: Random string, up to 30 characters. If present, must have at least 1 character. Used for overriding idempotent behaviour. 
 * `capabilities`: Used only when agreed with Smart-ID provider. When omitted, request capabilities are derived from certificateLevel.
 * `requestProperties`: A request properties object as a set of name/value pairs. For example, requesting the IP address of the user's device.
 * `initialCallbackUrl` : Optional. Must match regex `^https:\/\/([^\\|]+)$`. If it contains the vertical bar `|`, it must be percent-encoded. Should be used for same-device flow.
@@ -1218,9 +1218,6 @@ Jump to [Query session status](#example-of-using-session-status-poller-to-query-
 
 ### Notification-based signature session
 
-> [!CAUTION]
-> The notification-based signature has not yet been updated to be used with Smart-ID API v3.1
-
 #### Request Parameters
 The request parameters for the notification-based signature session are as follows:
 
@@ -1230,21 +1227,23 @@ The request parameters for the notification-based signature session are as follo
 * `signatureProtocol`: Required. Signature protocol to use. Currently, the only allowed value is RAW_DIGEST_SIGNATURE.
 * `signatureProtocolParameters`: Required. Parameters for the RAW_DIGEST_SIGNATURE signature protocol.
     * `digest`: Required. Base64 encoded digest to be signed.
-    * `signatureAlgorithm`: Required. Signature algorithm name. Supported values are `sha256WithRSAEncryption`, `sha384WithRSAEncryption`, `sha512WithRSAEncryption`.
-* `allowedInteractionsOrder`: Required. An array of interaction objects defining the allowed interactions in order of preference.
+    * `signatureAlgorithm`: Required. Signature algorithm name. Only `rsassa-pss` is currently supported.
+    * `signatureAlgorithmParameters`: Required. Parameters for the signature algorithm.
+        * `hashAlgorithm`: Required. Hash algorithm used for digest. Supported values are `SHA-256`, `SHA-384`, `SHA-512`, `SHA3-256`, `SHA3-384`, `SHA3-512`.
+* `interactions`: Required. Base64-encoded string of interactions to be used for a session. The interactions are defined in order of preference.
     * Each interaction object includes:
-        * `type`: Required. Type of interaction. Allowed types are `verificationCodeChoice`, `confirmationMessageAndVerificationCodeChoice`.
+        * `type`: Required. Type of interaction. Allowed types are `displayTextAndPIN`, `confirmationMessage`, `confirmationMessageAndVerificationCodeChoice`.
         * `displayText60` or `displayText200`: Required based on type. Text to display to the user. `displayText60` is limited to 60 characters, and `displayText200` is limited to 200 characters.
-* `nonce`: Optional. Random string, up to 30 characters. If present, must have at least 1 character.
+* `nonce`: Optional. Random string, up to 30 characters. If present, must have at least 1 character. To be used for overriding idempotency.
 * `requestProperties`: requestProperties:
     * `shareMdClientIpAddress`: Optional. Boolean indicating whether to request the IP address of the user's device.
 * `capabilities`: Optional. Array of strings specifying capabilities. Used only when agreed with the Smart-ID provider.
 
 #### Response Parameters
 * `sessionID`: Required. String used to request the operation result.
-* `verificationCode`: Required. Object describing the Verification Code to be displayed.
-    * `type`: Required. Type of the VC code. Currently, the only allowed type is `alphaNumeric4`.
-    * `value`: Required. Value of the VC code.
+* `vc`: Required. Object describing the verification code details.
+    * `type`: Required. Type of the verification code. Currently, the only allowed type is `numeric4`.
+    * `value`: Required. Value of the verification code to be displayed to the user.
 
 #### Examples of initiating a notification-based signature session
 
@@ -1262,21 +1261,20 @@ SemanticsIdentifier semanticsIdentifier = new SemanticsIdentifier(
 );
 
 // Build the notification signature request
-NotificationSignatureSessionResponse signatureSessionResponse = client.createNotificationSignature()
-    .withRelyingPartyUUID(client.getRelyingPartyUUID())
-    .withRelyingPartyName(client.getRelyingPartyName())
-    .withCertificateLevel(CertificateLevel.QUALIFIED)
-    .withSignableData(signableData)
-    .withSemanticsIdentifier(semanticsIdentifier)
-    .withAllowedInteractionsOrder(List.of(
-        NotificationInteraction.confirmationMessage("Please sign the <document-name>"))) // Display text should be concise and specific.
-    .initSignatureSession();
+NotificationSignatureSessionResponse signatureSessionResponse = smartIdClient.createNotificationSignature()
+        .withCertificateLevel(CertificateLevel.QSCD)
+        .withSignableData(signableData)
+        .withSemanticsIdentifier(semanticsIdentifier)
+        .withInteractions(List.of(
+                NotificationInteraction.confirmationMessage("Please sign the <document-name>")) // Display text should be concise and specific.
+        ) 
+        .initSignatureSession();
 
-// Process the querying sessions status response
+// Get the session ID and continue to querying session status
 String sessionID = signatureSessionResponse.sessionID();
 
 // Display verification code to the user
-String verificationCode = signatureSessionResponse.getVc().getValue();
+String verificationCode = signatureSessionResponse.vc().getValue();
 ```
 Jump to [Query session status](#example-of-using-session-status-poller-to-query-final-sessions-status) for an example of session querying.
 
@@ -1300,11 +1298,11 @@ NotificationSignatureSessionResponse signatureResponse = client.createNotificati
             NotificationInteraction.confirmationMessage("Please sign the <document-name>"))) // Display text should be concise and specific.
     .initSignatureSession();
 
-// Process the signature response
+// Get the session ID and continue to querying session status
 String sessionID = signatureResponse.sessionID();
 
 // Display verification code to the user
-String verificationCode = signatureResponse.getVc().getValue();
+String verificationCode = signatureResponse.vc().getValue();
 ```
 Jump to [Query session status](#example-of-using-session-status-poller-to-query-final-sessions-status) for an example of session querying.
 
@@ -1339,7 +1337,12 @@ try {
 
 #### Using nonce to override idempotent behaviour
 
-Authentication is used as an example, nonce can also be used with certificate choice and signature sessions requests by using method `withNonce("randomValue")`.
+Idempotent behaviour means that if the session request with same values is made multiple times within a 15-second window,
+the same response with identical values will be returned. If there is a need to override this behaviour, a nonce can be used.
+Nonce value must be a random string with a minimum length of 1 and a maximum length of 30 characters.
+
+Notification-based signature request is used as an example. Nonce can also be used with other signing session request
+(device-link signature and certificate choice; notification-based certificate choice) by using method `withNonce("randomValue")`.
 
 ```java
 NotificationSignatureSessionResponse signatureSessionResponse = smartIdClient.createNotificationSignature()

src/main/java/ee/sk/smartid/DeviceLinkSignatureSessionRequestBuilder.java

@@ -40,7 +40,7 @@
 import ee.sk.smartid.rest.dao.RequestProperties;
 import ee.sk.smartid.rest.dao.SemanticsIdentifier;
 import ee.sk.smartid.rest.dao.SignatureAlgorithmParameters;
-import ee.sk.smartid.rest.dao.SignatureSessionRequest;
+import ee.sk.smartid.rest.dao.DeviceLinkSignatureSessionRequest;
 import ee.sk.smartid.util.InteractionUtil;
 import ee.sk.smartid.util.SetUtil;
 import ee.sk.smartid.util.StringUtil;
@@ -67,7 +67,7 @@ public class DeviceLinkSignatureSessionRequestBuilder {
     private String initialCallbackUrl;
     private DigestInput digestInput;
 
-    private SignatureSessionRequest signatureSessionRequest;
+    private DeviceLinkSignatureSessionRequest deviceLinkSignatureSessionRequest;
 
     /**
      * Constructs a new Smart-ID signature request builder with the given connector.
@@ -251,29 +251,32 @@ public DeviceLinkSignatureSessionRequestBuilder withInitialCallbackUrl(String in
      */
     public DeviceLinkSessionResponse initSignatureSession() {
         validateRequestParameters();
-        SignatureSessionRequest signatureSessionRequest = createSignatureSessionRequest();
-        DeviceLinkSessionResponse deviceLinkSignatureSessionResponse = initSignatureSession(signatureSessionRequest);
+        DeviceLinkSignatureSessionRequest deviceLinkSignatureSessionRequest = createSignatureSessionRequest();
+        DeviceLinkSessionResponse deviceLinkSignatureSessionResponse = initSignatureSession(deviceLinkSignatureSessionRequest);
         validateResponseParameters(deviceLinkSignatureSessionResponse);
-        this.signatureSessionRequest = signatureSessionRequest;
+        this.deviceLinkSignatureSessionRequest = deviceLinkSignatureSessionRequest;
         return deviceLinkSignatureSessionResponse;
     }
 
     /**
-     * Gets the SignatureSessionRequest that was used to initiate the signature session.
+     * Gets the DeviceLinkSignatureSessionRequest that was used to initiate the signature session.
      * <p>
      * This method can only be called after {@link #initSignatureSession()} has been invoked.
      *
      * @return the signature request that was used to initiate the session
      * @throws SmartIdClientException if called before initSignatureSession()
      */
-    public SignatureSessionRequest getSignatureSessionRequest() {
-        if (signatureSessionRequest == null) {
+    public DeviceLinkSignatureSessionRequest getSignatureSessionRequest() {
+        if (deviceLinkSignatureSessionRequest == null) {
             throw new SmartIdClientException("Signature session has not been initiated yet");
         }
-        return signatureSessionRequest;
+        return deviceLinkSignatureSessionRequest;
     }
 
-    private DeviceLinkSessionResponse initSignatureSession(SignatureSessionRequest request) {
+    private DeviceLinkSessionResponse initSignatureSession(DeviceLinkSignatureSessionRequest request) {
+        if (semanticsIdentifier != null && documentNumber != null) {
+            throw new SmartIdRequestSetupException("Only one of 'semanticsIdentifier' or 'documentNumber' may be set");
+        }
         if (!StringUtil.isEmpty(documentNumber)) {
             return connector.initDeviceLinkSignature(request, documentNumber);
         } else if (semanticsIdentifier != null) {
@@ -283,11 +286,11 @@ private DeviceLinkSessionResponse initSignatureSession(SignatureSessionRequest r
         }
     }
 
-    private SignatureSessionRequest createSignatureSessionRequest() {
+    private DeviceLinkSignatureSessionRequest createSignatureSessionRequest() {
         var signatureProtocolParameters = new RawDigestSignatureProtocolParameters(digestInput.getDigestInBase64(),
                 signatureAlgorithm.getAlgorithmName(),
                 new SignatureAlgorithmParameters(digestInput.hashAlgorithm().getAlgorithmName()));
-        return new SignatureSessionRequest(relyingPartyUUID,
+        return new DeviceLinkSignatureSessionRequest(relyingPartyUUID,
                 relyingPartyName,
                 certificateLevel != null ? certificateLevel.name() : null,
                 SignatureProtocol.RAW_DIGEST_SIGNATURE.name(),

src/main/java/ee/sk/smartid/ErrorResultHandler.java

@@ -58,7 +58,7 @@ public class ErrorResultHandler {
      * @throws SmartIdClientException                when input parameter sessionResult is null
      * @throws UserActionException                   sub-exceptions based on end result
      * @throws UserAccountException                  sub-exceptions based on end result
-     * @throws ProtocolFailureException              when there was an error in the process (e.g. shcema name is incorrect)
+     * @throws ProtocolFailureException              when there was an error in the process (e.g. schema name is incorrect)
      * @throws ExpectedLinkedSessionException        when different session type was started than expected
      * @throws SmartIdServerException                when technical error occurred on server side
      * @throws UnprocessableSmartIdResponseException when unexpected end result was received

src/main/java/ee/sk/smartid/NonQualifiedSignatureCertificatePurposeValidator.java

@@ -28,7 +28,7 @@
 
 import java.security.cert.X509Certificate;
 
-import ee.sk.smartid.common.certifiate.NonQualifiedSmartIdCertificateValidator;
+import ee.sk.smartid.common.certificate.NonQualifiedSmartIdCertificateValidator;
 import ee.sk.smartid.exception.UnprocessableSmartIdResponseException;
 import ee.sk.smartid.util.CertificateAttributeUtil;
 

src/main/java/ee/sk/smartid/NotificationCertificateChoiceSessionRequestBuilder.java

@@ -187,7 +187,7 @@ private NotificationCertificateChoiceSessionRequest createCertificateChoiceReque
     }
 
     private void validateResponseParameters(NotificationCertificateChoiceSessionResponse notificationCertificateChoiceSessionResponse) {
-        if (StringUtil.isEmpty(notificationCertificateChoiceSessionResponse.getSessionID())) {
+        if (StringUtil.isEmpty(notificationCertificateChoiceSessionResponse.sessionID())) {
             throw new UnprocessableSmartIdResponseException("Notification-based certificate choice response field 'sessionID' is missing or empty");
         }
     }