V3 API: Rework twofer API to avoid calling 'collect' from the auth and sign methods (#20)

A completed or failed order can only be collected a single time, and when
calling collect from the auth or sign endpoints, there is a small risk that
it will collect the completed/failed orderRef.

Author: larsve

api/models.go

@@ -1,6 +1,8 @@
 package api
 
 type (
+	// BankIdV6Response used as a catch all response for V2
+	// Deprecated: stick to V1 or move to V3
 	BankIdV6Response struct {
 		OrderRef       string                  `json:"orderRef"`
 		ErrorCode      string                  `json:"errorCode,omitempty"`
@@ -32,11 +34,113 @@ type (
 	BankIdV6StepUp struct {
 		MRTD bool `json:"mrtd,omitempty"`
 	}
+
+	// V3 request / response messages
+
+	// BankIdv6AuthSignRequestV3 is used to start either an auth or sign request against BankID
+	BankIdv6AuthSignRequestV3 struct {
+		// EndUserIp The user IP address as it is seen by your service
+		EndUserIp string `json:"endUserIp"`
+
+		// ReturnUrl Orders started on the same device as where the user's BankID is stored (started with autostart
+		// token) will call this URL when the order is completed
+		ReturnUrl string `json:"returnUrl,omitempty"`
+
+		// UserNonVisibleData Data that you wish to include but not display to the user
+		UserNonVisibleData string `json:"userNonVisibleData,omitempty"`
+
+		// UserVisibleData Text displayed to the user during the order
+		UserVisibleData string `json:"userVisibleData,omitempty"`
+
+		// UserVisibleDataFormat, 'plaintext' or 'simpleMarkdownV1'
+		UserVisibleDataFormat string `json:"userVisibleDataFormat,omitempty"`
+
+		// PersonalNumber The personal identity number allowed to confirm the identification
+		PersonalNumber string `json:"personalNumber,omitempty"`
+
+		// PinCode User is required to confirm the order with their security code even if they have biometrics activated
+		PinCode bool `json:"pinCode,omitempty"`
+
+		// Once if true, will start an auth/sign and just return a single QR code, if false, auth/sign endpoint return
+		// an SSE / NDJSON stream and send a new QR-code each second, for 30 seconds before returning
+		Once bool `json:"once,omitempty"`
+	}
+
+	// BankIdV6AuthSignResponseV3 is sent as a successful reply to an auth or sign request. If SSE / NDJSON is used, a
+	// new BankIdV6AuthSignResponseV3 is sent each second (for 30 seconds)
+	BankIdV6AuthSignResponseV3 struct {
+		// OrderRef The reference ID for an order
+		OrderRef string `json:"orderRef"`
+
+		// URI Start URL, for "BankID on this device"
+		URI string `json:"uri"`
+
+		// QR contain the data for the QR-code
+		QR string `json:"qr"`
+	}
+
+	// BankIdv6CollectRequestV3 is used to collect status on a started auth / sign request
+	BankIdv6CollectRequestV3 struct {
+		// OrderRef A reference ID for an order
+		OrderRef string `json:"orderRef"`
+
+		// WaitForChange allows the request to wait until a change is detected
+		WaitForChange bool `json:"waitForChange"`
+
+		// WaitUntilFinished allows the request to wait until the referenced request has either completed or failed,
+		// and will not return on state changes during the ongoing process.
+		WaitUntilFinished bool `json:"waitUntilFinished"`
+	}
+
+	// BankIdV6CollectResponseV3 is sent for a successful collect, if WaitUntilFinished is set in the request, it will
+	// only return once the order have either completed or failed. If WaitUntilFinished isn't set, it will return once
+	// a change is detected.
+	BankIdV6CollectResponseV3 struct {
+		// OrderRef The reference ID for an order
+		OrderRef       string                  `json:"orderRef"`
+		Status         string                  `json:"status,omitempty"`
+		HintCode       string                  `json:"hintCode,omitempty"`
+		CompletionData *BankIdV6CompletionData `json:"completionData,omitempty"`
+	}
+
+	// BankIdv6CancelRequestV3 request the cancellation of a pending auth / sign request
+	BankIdv6CancelRequestV3 struct {
+		// OrderRef A reference ID for an order
+		OrderRef string `json:"orderRef"`
+	}
+
+	BankIdv6CancelResponseV3 struct {
+		Status string `json:"status"`
+	}
+
+	// BankIdv6ErrorResponseV3 is sent when an endpoint return an error (4xx, 5xx) http status code
+	BankIdv6ErrorResponseV3 struct {
+		// Origin contains the origin of the error, currently either 'Twofer' or 'BankIDv6'
+		Origin string `json:"origin"` // Twofer / BankIDv6
+
+		// StatusCode contain the original HTTP status code, if the error originates from BankID
+		StatusCode int `json:"statusCode,omitempty"`
+
+		// ErrorCode contain the original error code that we may get from BankID when they return an http 400
+		Code string `json:"code,omitempty"`
+
+		// Detail may contain the original error detail that we may get from BankID when they return an http 400, or it
+		// can be an error message generated in twofer, for twofer errors
+		Detail string `json:"detail"`
+	}
 )
 
+// Status codes
 const (
 	StatusPending  = "pending"
 	StatusComplete = "complete"
 	StatusFailed   = "failed"
 	StatusError    = "error"
+	StatusQrCode   = "qrcode"
+)
+
+// Error origin codes
+const (
+	ErrorOriginTwofer   = "Twofer"
+	ErrorOriginBankIDv6 = "BankIDv6"
 )

cmd/twoferd/main.go

@@ -146,6 +146,7 @@ func startEid(e *echo.Echo) {
 		PemRootCA:     config.Get().BankID.GetRootCA(),
 		PemClientCert: config.Get().BankID.GetClientCert(),
 		PemClientKey:  config.Get().BankID.GetClientKey(),
+		PollInterval:  config.Get().BankID.PollInterval,
 	})
 	if err != nil {
 		fmt.Printf("failed to initate bankId %v", err)

internal/bankid/bankid_models.go

@@ -200,12 +200,13 @@ func (c *CancelRequest) Validate() error {
 }
 
 type BankIdError struct {
-	ErrorCode string `json:"errorCode"`
-	Details   string `json:"details"`
+	StatusCode int    `json:"-"`
+	ErrorCode  string `json:"errorCode"`
+	Details    string `json:"details"`
 }
 
 func (e BankIdError) Error() string {
-	return fmt.Sprintf("bankid: %s, %s", e.ErrorCode, e.Details)
+	return fmt.Sprintf("bankid: (%d) %s, %s", e.StatusCode, e.ErrorCode, e.Details)
 }
 
 type Empty struct{}

internal/bankid/endpoints.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"github.com/labstack/echo/v4"
 	"io"
 	"net/http"
 	"time"
@@ -19,14 +20,16 @@ const (
 )
 
 type API struct {
-	baseURL string
-	client  *http.Client
+	baseURL      string
+	client       *http.Client
+	pollInterval time.Duration
 }
 
-func NewAPI(client *http.Client, baseURL string) *API {
+func NewAPI(client *http.Client, baseURL string, pollInterval time.Duration) *API {
 	return &API{
-		client:  client,
-		baseURL: baseURL,
+		client:       client,
+		baseURL:      baseURL,
+		pollInterval: pollInterval,
 	}
 }
 
@@ -94,7 +97,7 @@ func (a *API) Change(ctx context.Context, r *ChangeRequest) (*CollectResponse, e
 		case <-ctx.Done():
 			err = ctx.Err()
 			return nil, err
-		case <-time.After(time.Second):
+		case <-time.After(a.pollInterval):
 		}
 
 		var resp *CollectResponse
@@ -113,6 +116,49 @@ func (a *API) Change(ctx context.Context, r *ChangeRequest) (*CollectResponse, e
 	}
 }
 
+func (a *API) ChangeV3(ctx context.Context, r *ChangeRequest) (*CollectResponse, error) {
+	err := r.Validate()
+	if err != nil {
+		return nil, err
+	}
+
+	collectRequest := &CollectRequest{OrderRef: r.OrderRef}
+
+	startState, err := a.Collect(ctx, collectRequest)
+	if err != nil {
+		return nil, err
+	}
+
+	if startState.Status == Complete || startState.Status == Failed {
+		return startState, nil
+	}
+
+	for {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(a.pollInterval):
+		}
+
+		var resp *CollectResponse
+		resp, err = a.Collect(ctx, collectRequest)
+		if err != nil {
+			return nil, err
+		}
+
+		if r.WaitUntilFinished {
+			if resp.Status != Pending {
+				return resp, nil
+			}
+			continue
+		}
+
+		if resp.HintCode != startState.HintCode {
+			return resp, nil
+		}
+	}
+}
+
 func (a *API) WatchForChange(ctx context.Context, orderRef string) <-chan WatchResponse {
 	watch := make(chan WatchResponse)
 
@@ -253,12 +299,14 @@ func post[Request any, Response any](ctx context.Context, client *http.Client, r
 	if res.StatusCode != 200 {
 		fmt.Printf("%s returned status code %d with data: %s\n", url, res.StatusCode, body)
 		var bidError BankIdError
-		err = json.Unmarshal(body, &bidError)
-		if err == nil {
-			err = bidError
+		if res.Header.Get(echo.HeaderContentType) == echo.MIMEApplicationJSON {
+			err = json.Unmarshal(body, &bidError)
+			if err != nil {
+				fmt.Printf("failed to unmarshal BankIdError, error: %v\n", err)
+			}
 		}
-
-		return nil, err
+		bidError.StatusCode = res.StatusCode
+		return nil, bidError
 	}
 
 	var response Response

internal/config/config.go

@@ -20,7 +20,7 @@ type Config struct {
 	WebAuthn  WebAuthn
 	PWD       PWD
 
-	StreamEncoder string `env:"STREAM_ENCODER" envDefault:"NDJSON"`
+	StreamEncoder string `env:"STREAM_ENCODER" envDefault:"SSE"`
 }
 
 func (c Config) EIDEnabled() bool {
@@ -36,14 +36,15 @@ type OTP struct {
 }
 
 type BankID struct {
-	Enabled        bool     `env:"EID_BANKID_ENABLE" envDefault:"FALSE"`
-	URL            *url.URL `env:"EID_BANKID_URL"`
-	RootCA         string   `env:"EID_BANKID_ROOT_CA_PEM"`
-	RootCAFile     string   `env:"EID_BANKID_ROOT_CA_PEM_FILE,file"`
-	ClientCert     string   `env:"EID_BANKID_CLIENT_CERT"`
-	ClientCertFile string   `env:"EID_BANKID_CLIENT_CERT_FILE,file"`
-	ClientKey      string   `env:"EID_BANKID_CLIENT_KEY"`
-	ClientKeyFile  string   `env:"EID_BANKID_CLIENT_KEY_FILE,file"`
+	Enabled        bool          `env:"EID_BANKID_ENABLE" envDefault:"FALSE"`
+	URL            *url.URL      `env:"EID_BANKID_URL"`
+	RootCA         string        `env:"EID_BANKID_ROOT_CA_PEM"`
+	RootCAFile     string        `env:"EID_BANKID_ROOT_CA_PEM_FILE,file"`
+	ClientCert     string        `env:"EID_BANKID_CLIENT_CERT"`
+	ClientCertFile string        `env:"EID_BANKID_CLIENT_CERT_FILE,file"`
+	ClientKey      string        `env:"EID_BANKID_CLIENT_KEY"`
+	ClientKeyFile  string        `env:"EID_BANKID_CLIENT_KEY_FILE,file"`
+	PollInterval   time.Duration `env:"EID_BANKID_POLL_INTERVAL" envDefault:"2s"` // Poll BankID every two seconds as default (according to their spec)
 }
 
 func (b BankID) GetRootCA() []byte {

internal/eid/bankid/bankid.go

@@ -8,6 +8,7 @@ import (
 	bankid_v51 "github.com/modfin/twofer/internal/eid/bankid/v5.1"
 	"github.com/modfin/twofer/internal/mtls"
 	"net/http"
+	"time"
 )
 
 type ClientConfig struct {
@@ -16,6 +17,8 @@ type ClientConfig struct {
 	PemRootCA     []byte
 	PemClientCert []byte
 	PemClientKey  []byte
+
+	PollInterval time.Duration
 }
 
 func New(config ClientConfig) (client *BankID, err error) {
@@ -47,7 +50,7 @@ func New(config ClientConfig) (client *BankID, err error) {
 
 	client.APIv51 = bankid_v51.NewEid(client.httpClient, config.BaseURL)
 
-	client.APIv60 = bankid.NewAPI(client.httpClient, client.baseURL)
+	client.APIv60 = bankid.NewAPI(client.httpClient, client.baseURL, config.PollInterval)
 
 	return
 }