github.com/decred/politeia@v1.4.0/politeiad/plugins/usermd/usermd.go (about)

     1  // Copyright (c) 2020-2021 The Decred developers
     2  // Use of this source code is governed by an ISC
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package usermd provides a politeiad plugin that extends records with user
     6  // metadata and provides an API for retrieving records by user metadata.
     7  package usermd
     8  
     9  const (
    10  	// PluginID is the unique identifier for this plugin.
    11  	PluginID = "usermd"
    12  
    13  	// CmdAuthor command retrieves the record author.
    14  	CmdAuthor = "author"
    15  
    16  	// CmdUserRecords command returns all records submitted by the given user.
    17  	CmdUserRecords = "userrecords"
    18  )
    19  
    20  // Stream IDs are the metadata stream IDs for metadata defined in this package.
    21  const (
    22  	// StreamIDUserMetadata is the politeiad metadata stream ID for the
    23  	// UserMetadata structure.
    24  	StreamIDUserMetadata uint32 = 1
    25  
    26  	// StreamIDStatusChanges is the politeiad metadata stream ID for
    27  	// the status changes metadata. Status changes are appended onto
    28  	// this metadata stream.
    29  	StreamIDStatusChanges uint32 = 2
    30  )
    31  
    32  // ErrorCodeT represents a plugin error that was caused by the user.
    33  type ErrorCodeT uint32
    34  
    35  const (
    36  	// ErrorCodeInvalid is an invalid error code.
    37  	ErrorCodeInvalid ErrorCodeT = 0
    38  
    39  	// ErrorCodeUserMetadataNotFound is returned when a record does
    40  	// not contain a metdata stream for user metadata.
    41  	ErrorCodeUserMetadataNotFound ErrorCodeT = 1
    42  
    43  	// ErrorCodeUserIDInvalid is returned when a user ID is changed
    44  	// between versions of a record.
    45  	ErrorCodeUserIDInvalid ErrorCodeT = 2
    46  
    47  	// ErrorCodePublicKeyInvalid is returned when a public key used
    48  	// in a signature is not valid.
    49  	ErrorCodePublicKeyInvalid ErrorCodeT = 3
    50  
    51  	// ErrorCodeSignatureInvalid is returned when the signature does
    52  	// not match the expected signature.
    53  	ErrorCodeSignatureInvalid ErrorCodeT = 4
    54  
    55  	// ErrorCodeStatusChangeMetadataNotFound is returned when a record
    56  	// is having its status updated but is missing the status change
    57  	// metadata.
    58  	ErrorCodeStatusChangeMetadataNotFound ErrorCodeT = 5
    59  
    60  	// ErrorCodeTokenInvalid is returned when a token that is included
    61  	// in the metadata does not match the token of the record that the
    62  	// command is being executed on.
    63  	ErrorCodeTokenInvalid ErrorCodeT = 6
    64  
    65  	// ErrorCodeStatusInvalid is returned when the status defined in
    66  	// the status change metadata does not match the record status.
    67  	ErrorCodeStatusInvalid ErrorCodeT = 7
    68  
    69  	// ErrorCodeReasonMissing is returned when the status change reason
    70  	// is required but is not included.
    71  	ErrorCodeReasonMissing ErrorCodeT = 8
    72  
    73  	// ErrorCodeLast unit test only.
    74  	ErrorCodeLast ErrorCodeT = 9
    75  )
    76  
    77  var (
    78  	// ErrorCodes contains the human readable errors.
    79  	ErrorCodes = map[ErrorCodeT]string{
    80  		ErrorCodeInvalid:                      "error code invalid",
    81  		ErrorCodeUserMetadataNotFound:         "user metadata not found",
    82  		ErrorCodeUserIDInvalid:                "user id invalid",
    83  		ErrorCodePublicKeyInvalid:             "public key invalid",
    84  		ErrorCodeSignatureInvalid:             "signature invalid",
    85  		ErrorCodeStatusChangeMetadataNotFound: "status change metadata not found",
    86  		ErrorCodeTokenInvalid:                 "token invalid",
    87  		ErrorCodeStatusInvalid:                "status invalid",
    88  		ErrorCodeReasonMissing:                "status change reason is missing",
    89  	}
    90  )
    91  
    92  // UserMetadata contains user metadata about a politeiad record. It is
    93  // generated by the server and saved to politeiad as a metadata stream.
    94  //
    95  // Signature is the client signature of the hex encoded record merkle root. The
    96  // merkle root is the ordered merkle root of all user submitted politeiad
    97  // files. The merkle root is hex encoded before being signed so that the
    98  // signature is consistent with how politeiad signs the merkle root.
    99  type UserMetadata struct {
   100  	UserID    string `json:"userid"`    // Author user ID
   101  	PublicKey string `json:"publickey"` // Key used for signature
   102  	Signature string `json:"signature"` // Signature of merkle root
   103  }
   104  
   105  // StatusChangeMetadata contains the user signature for a record status change.
   106  //
   107  // Signature is the client signature of the Token+Version+Status+Reason.
   108  type StatusChangeMetadata struct {
   109  	Token     string `json:"token"`
   110  	Version   uint32 `json:"version"`
   111  	Status    uint32 `json:"status"`
   112  	Reason    string `json:"reason,omitempty"`
   113  	PublicKey string `json:"publickey"`
   114  	Signature string `json:"signature"`
   115  	Timestamp int64  `json:"timestamp"`
   116  }
   117  
   118  // Author returns the user ID of a record's author.
   119  type Author struct{}
   120  
   121  // AuthorReply is the reply to the Author command.
   122  type AuthorReply struct {
   123  	UserID string `json:"userid"`
   124  }
   125  
   126  // UserRecords retrieves the tokens of all records that were submitted by the
   127  // provided user ID. The returned tokens are sorted from newest to oldest.
   128  type UserRecords struct {
   129  	UserID string `json:"userid"`
   130  }
   131  
   132  // UserRecordsReply is the reply to the UserInv command.
   133  type UserRecordsReply struct {
   134  	Unvetted []string `json:"unvetted"`
   135  	Vetted   []string `json:"vetted"`
   136  }