auth

type Auth interface {
	// Create and return a new token that allows access to each API endpoint for
	// [duration] such that the API's path ends with an element of [endpoints].
	// If one of the elements of [endpoints] is "*", all APIs are accessible.
	NewToken(pw string, duration time.Duration, endpoints []string) (string, error)

	// Revokes [token]; it will not be accepted as authorization for future API
	// calls. If the token is invalid, this is a no-op.  If a token is revoked
	// and then the password is changed, and then changed back to the current
	// password, the token will be un-revoked. Therefore, passwords shouldn't be
	// re-used before previously revoked tokens have expired.
	RevokeToken(pw, token string) error

	// Authenticates [token] for access to [url].
	AuthenticateToken(token, url string) error

	// Change the password required to create and revoke tokens.
	// [oldPW] is the current password.
	// [newPW] is the new password. It can't be the empty string and it can't be
	//         unreasonably long.
	// Changing the password makes tokens issued under a previous password
	// invalid.
	ChangePassword(oldPW, newPW string) error

	// Create the API endpoint for this auth handler.
	CreateHandler() (http.Handler, error)

	// WrapHandler wraps an http.Handler. Before passing a request to the
	// provided handler, the auth token is authenticated.
	WrapHandler(h http.Handler) http.Handler
}

type ChangePasswordArgs struct {
	OldPassword string `json:"oldPassword"` // Current authorization password
	NewPassword string `json:"newPassword"` // New authorization password
}

type NewTokenArgs struct {
	Password
	// Endpoints that may be accessed with this token e.g. if endpoints is
	// ["/ext/bc/X", "/ext/admin"] then the token holder can hit the X-Chain API
	// and the admin API. If [Endpoints] contains an element "*" then the token
	// allows access to all API endpoints. [Endpoints] must have between 1 and
	// [maxEndpoints] elements
	Endpoints []string `json:"endpoints"`
}

type Password struct {
	Password string `json:"password"` // The authorization password
}

type RevokeTokenArgs struct {
	Password
	Token
}

type Token struct {
	Token string `json:"token"` // The new token. Expires in [TokenLifespan].
}