Better API Documentation

.air.toml

@@ -14,7 +14,7 @@ tmp_dir = "tmp"
   follow_symlink = false
   full_bin = ""
   include_dir = []
-  include_ext = ["go", "tpl", "tmpl", "html", "jet", "js", "css"]
+  include_ext = ["go", "tpl", "tmpl", "html", "jet", "js", "css", "json", "yaml"]
   kill_delay = "0s"
   log = "build-errors.log"
   send_interrupt = false

go.mod

@@ -18,7 +18,6 @@ require (
 	github.com/rotationalio/confire v1.0.0
 	github.com/rs/zerolog v1.33.0
 	github.com/stretchr/testify v1.9.0
-	github.com/swaggest/swgui v1.8.1
 	github.com/trisacrypto/directory v1.8.0
 	github.com/trisacrypto/trisa v1.3.0
 	github.com/urfave/cli/v2 v2.27.2

go.sum

@@ -26,8 +26,6 @@ github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
 github.com/bombsimon/tld-validator v1.2.33 h1:FajZi0jt1gYpelma29CT3ed/zAf/PwnU2TzJPdK+g/o=
 github.com/bombsimon/tld-validator v1.2.33/go.mod h1:Tw75x7N4Znt8h4p+8VgOsEjwe7/FYjXw9/65bh0lQVU=
-github.com/bool64/dev v0.2.32 h1:DRZtloaoH1Igky3zphaUHV9+SLIV2H3lsf78JsJHFg0=
-github.com/bool64/dev v0.2.32/go.mod h1:iJbh1y/HkunEPhgebWRNcs8wfGq7sjvJ6W5iabL8ACg=
 github.com/bytedance/sonic v1.11.9 h1:LFHENlIY/SLzDWverzdOvgMztTxcfcF+cqNsz9pK5zg=
 github.com/bytedance/sonic v1.11.9/go.mod h1:LysEHSvpvDySVdC2f87zGWf6CIKJcAvqab1ZaiQtds4=
 github.com/bytedance/sonic/loader v0.1.1 h1:c+e5Pt1k/cy5wMveRDyk2X4B9hF4g7an8N3zCYjJFNM=
@@ -251,8 +249,6 @@ github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-github.com/swaggest/swgui v1.8.1 h1:OLcigpoelY0spbpvp6WvBt0I1z+E9egMQlUeEKya+zU=
-github.com/swaggest/swgui v1.8.1/go.mod h1:YBaAVAwS3ndfvdtW8A4yWDJpge+W57y+8kW+f/DqZtU=
 github.com/syndtr/goleveldb v1.0.0 h1:fBdIW9lB4Iz0n9khmH8w27SJ3QEJ7+IgjPEwGSZiFdE=
 github.com/syndtr/goleveldb v1.0.0/go.mod h1:ZVVdQEZoIme9iO1Ch2Jdy24qqXrMMOU6lpPAyBWyWuQ=
 github.com/trisacrypto/directory v1.8.0 h1:CLFfUtKvU8AIY9ENuV1/u2ihmmLIFMG1yRXUovwnF6g=

pkg/node/node.go

@@ -85,6 +85,11 @@ func New(conf config.Config) (node *Node, err error) {
 	if node.network, err = network.New(conf.Node); err != nil {
 		return nil, err
 	}
+	log.Debug().
+		Str("endpoint", conf.Node.Endpoint).
+		Str("gds", conf.Node.Directory.Endpoint).
+		Str("members", conf.Node.Directory.MembersEndpoint).
+		Msg("trisa initialized")
 
 	// Create the admin web ui server if it is enabled
 	if node.admin, err = web.New(conf, node.store, node.network); err != nil {

pkg/web/accounts.go

@@ -74,7 +74,10 @@ func (s *Server) CreateAccount(c *gin.Context) {
 		return
 	}
 
-	// TODO: validate the account input
+	if err = in.Validate(true); err != nil {
+		c.JSON(http.StatusUnprocessableEntity, err)
+		return
+	}
 
 	// Convert the API account request into a database model
 	if account, err = in.Model(); err != nil {
@@ -100,7 +103,7 @@ func (s *Server) CreateAccount(c *gin.Context) {
 	}
 
 	// Content negotiation
-	c.Negotiate(http.StatusOK, gin.Negotiate{
+	c.Negotiate(http.StatusCreated, gin.Negotiate{
 		Offered:  []string{binding.MIMEJSON, binding.MIMEHTML},
 		Data:     out,
 		HTMLName: "account_create.html",
@@ -220,7 +223,10 @@ func (s *Server) UpdateAccount(c *gin.Context) {
 		return
 	}
 
-	// TODO: validate the account input
+	if err = in.Validate(false); err != nil {
+		c.JSON(http.StatusUnprocessableEntity, err)
+		return
+	}
 
 	// Convert the API account request into a database model
 	if account, err = in.Model(); err != nil {
@@ -366,7 +372,10 @@ func (s *Server) CreateCryptoAddress(c *gin.Context) {
 		return
 	}
 
-	// TODO: validate the input
+	if err = in.Validate(true); err != nil {
+		c.JSON(http.StatusUnprocessableEntity, err)
+		return
+	}
 
 	// Convert the request into a database model
 	if model, err = in.Model(nil); err != nil {
@@ -400,7 +409,7 @@ func (s *Server) CreateCryptoAddress(c *gin.Context) {
 	}
 
 	// Content negotiation
-	c.Negotiate(http.StatusOK, gin.Negotiate{
+	c.Negotiate(http.StatusCreated, gin.Negotiate{
 		Offered:  []string{binding.MIMEJSON, binding.MIMEHTML},
 		Data:     out,
 		HTMLName: "crypto_address_create.html",
@@ -492,7 +501,10 @@ func (s *Server) UpdateCryptoAddress(c *gin.Context) {
 		return
 	}
 
-	// TODO: validate the crypto address input
+	if err = in.Validate(false); err != nil {
+		c.JSON(http.StatusUnprocessableEntity, err)
+		return
+	}
 
 	// Convert the crypto address request into a database model
 	if model, err = in.Model(nil); err != nil {

pkg/web/api/v1/account.go

@@ -2,16 +2,21 @@ package api
 
 import (
 	"database/sql"
+	"encoding/base64"
 	"encoding/json"
 	"errors"
+	"strings"
 	"time"
 
 	dberr "github.com/trisacrypto/envoy/pkg/store/errors"
 	"github.com/trisacrypto/envoy/pkg/store/models"
+	"github.com/trisacrypto/envoy/pkg/ulids"
+	"google.golang.org/protobuf/proto"
 
 	"github.com/oklog/ulid/v2"
 	"github.com/rs/zerolog/log"
 	"github.com/trisacrypto/trisa/pkg/ivms101"
+	"github.com/trisacrypto/trisa/pkg/slip0044"
 )
 
 //===========================================================================
@@ -25,7 +30,7 @@ type Account struct {
 	LastName        string           `json:"last_name"`
 	TravelAddress   string           `json:"travel_address,omitempty"`
 	IVMSRecord      string           `json:"ivms101,omitempty"`
-	CryptoAddresses []*CryptoAddress `json:"crypto_addresses"`
+	CryptoAddresses []*CryptoAddress `json:"crypto_addresses,omitempty"`
 	Created         time.Time        `json:"created,omitempty"`
 	Modified        time.Time        `json:"modified,omitempty"`
 }
@@ -34,8 +39,8 @@ type CryptoAddress struct {
 	ID            ulid.ULID `json:"id,omitempty"`
 	CryptoAddress string    `json:"crypto_address"`
 	Network       string    `json:"network"`
-	AssetType     string    `json:"asset_type"`
-	Tag           string    `json:"tag"`
+	AssetType     string    `json:"asset_type,omitempty"`
+	Tag           string    `json:"tag,omitempty"`
 	TravelAddress string    `json:"travel_address,omitempty"`
 	Created       time.Time `json:"created,omitempty"`
 	Modified      time.Time `json:"modified,omitempty"`
@@ -62,13 +67,14 @@ func NewAccount(model *models.Account) (out *Account, err error) {
 		Modified:      model.Modified,
 	}
 
-	// Render the IVMS101 data as as JSON string
+	// Render the IVMS101 data as as base64 encoded JSON string
+	// TODO: select rendering using protocol buffers or JSON as a config option.
 	if model.IVMSRecord != nil {
 		if data, err := json.Marshal(model.IVMSRecord); err != nil {
 			// Log the error but do not stop processing
 			log.Error().Err(err).Str("account_id", model.ID.String()).Msg("could not marshal IVMS101 record to JSON")
 		} else {
-			out.IVMSRecord = string(data)
+			out.IVMSRecord = base64.URLEncoding.EncodeToString(data)
 		}
 	}
 
@@ -91,7 +97,6 @@ func NewAccount(model *models.Account) (out *Account, err error) {
 }
 
 func NewAccountList(page *models.AccountsPage) (out *AccountsList, err error) {
-	// TODO: convert PageInfo to PageQuery
 	out = &AccountsList{
 		Page:     &PageQuery{},
 		Accounts: make([]*Account, 0, len(page.Accounts)),
@@ -103,6 +108,11 @@ func NewAccountList(page *models.AccountsPage) (out *AccountsList, err error) {
 			return nil, err
 		}
 
+		// Remove list fields not needed for the summary info
+		// TODO: instead of removing, do not select this data from the database.
+		account.IVMSRecord = ""
+		account.CryptoAddresses = nil
+
 		out.Accounts = append(out.Accounts, account)
 	}
 
@@ -124,8 +134,7 @@ func (a *Account) Model() (model *models.Account, err error) {
 	}
 
 	if a.IVMSRecord != "" {
-		model.IVMSRecord = &ivms101.Person{}
-		if err = json.Unmarshal([]byte(a.IVMSRecord), model.IVMSRecord); err != nil {
+		if model.IVMSRecord, err = a.IVMS101(); err != nil {
 			return nil, err
 		}
 	}
@@ -143,6 +152,56 @@ func (a *Account) Model() (model *models.Account, err error) {
 	return model, nil
 }
 
+func (a *Account) IVMS101() (p *ivms101.Person, err error) {
+	// Don't handle empty strings.
+	if a.IVMSRecord == "" {
+		return nil, ErrParsingIVMS101Person
+	}
+
+	// Try decoding URL base64 first, then STD before resorting to a string
+	var data []byte
+	if data, err = base64.URLEncoding.DecodeString(a.IVMSRecord); err != nil {
+		if data, err = base64.StdEncoding.DecodeString(a.IVMSRecord); err != nil {
+			data = []byte(a.IVMSRecord)
+		}
+	}
+
+	// Try unmarshaling JSON first, then protocol buffers
+	p = &ivms101.Person{}
+	if err = json.Unmarshal(data, p); err != nil {
+		if err = proto.Unmarshal(data, p); err != nil {
+			return nil, ErrParsingIVMS101Person
+		}
+	}
+
+	return p, nil
+}
+
+func (a *Account) Validate(create bool) (err error) {
+	if create {
+		if !ulids.IsZero(a.ID) {
+			err = ValidationError(err, ReadOnlyField("id"))
+		}
+	}
+
+	if a.LastName == "" {
+		err = ValidationError(err, MissingField("last_name"))
+	}
+
+	if a.TravelAddress != "" {
+		err = ValidationError(err, ReadOnlyField("travel_address"))
+	}
+
+	if _, perr := a.IVMS101(); perr != nil {
+		err = ValidationError(err, IncorrectField("ivms101", perr.Error()))
+	}
+
+	if len(a.CryptoAddresses) > 0 {
+		err = ValidationError(err, ReadOnlyField("crypto_addresses"))
+	}
+	return err
+}
+
 func NewCryptoAddress(model *models.CryptoAddress) (*CryptoAddress, error) {
 	return &CryptoAddress{
 		ID:            model.ID,
@@ -157,7 +216,6 @@ func NewCryptoAddress(model *models.CryptoAddress) (*CryptoAddress, error) {
 }
 
 func NewCryptoAddressList(page *models.CryptoAddressPage) (out *CryptoAddressList, err error) {
-	// TODO: convert PageInfo to PageQuery
 	out = &CryptoAddressList{
 		Page:            &PageQuery{},
 		CryptoAddresses: make([]*CryptoAddress, 0, len(page.CryptoAddresses)),
@@ -194,3 +252,32 @@ func (c *CryptoAddress) Model(acct *models.Account) (*models.CryptoAddress, erro
 	}
 	return addr, nil
 }
+
+func (c *CryptoAddress) Validate(create bool) (err error) {
+	if create {
+		if !ulids.IsZero(c.ID) {
+			err = ValidationError(err, ReadOnlyField("id"))
+		}
+	}
+
+	c.CryptoAddress = strings.TrimSpace(c.CryptoAddress)
+	if c.CryptoAddress == "" {
+		err = ValidationError(err, MissingField("crypto_address"))
+	}
+
+	c.Network = strings.TrimSpace(c.Network)
+	if c.Network == "" {
+		err = ValidationError(err, MissingField("network"))
+	} else {
+		// TODO: also try parsing DTI
+		if _, perr := slip0044.ParseCoinType(c.Network); perr != nil {
+			err = ValidationError(err, IncorrectField("network", perr.Error()))
+		}
+	}
+
+	if c.TravelAddress != "" {
+		err = ValidationError(err, ReadOnlyField("travel_address"))
+	}
+
+	return err
+}

pkg/web/api/v1/api.go

@@ -98,7 +98,6 @@ type Client interface {
 type Reply struct {
 	Success     bool        `json:"success"`
 	Error       string      `json:"error,omitempty"`
-	Version     string      `json:"version,omitempty"`
 	ErrorDetail ErrorDetail `json:"errors,omitempty"`
 }