RefreshableClaims API is hard to understand, and possibly broken

[Benjamin Cable]

Naming:

I believe the following methods are incorrectly named:

• VerifyExpiresAt(now time.Time) bool
• VerifyIssuedAt(now time.Time) bool
• VerifyNotBefore(now time.Time) bool

Since they are boolean returns, their names feel very strange, indeed I think the following could be better:

• IsExpired(now time.Time, grace time.Duration) bool
• IsIssuedBefore(now time.Time) bool
• NotValidBefore(now time.Time) bool

Behaviour:

The current behaviour of VerifyExpiresAt seems wrong, and is hard to understand:

// VerifyExpiresAt compares the exp claim against a timestamp.
// Will change behaviour depending on the value of corelush.TimeFunc
func (c *Claims) VerifyExpiresAt(now time.Time) bool {
	if c.ExpiresAt == 0 {
		return false
	}
	return now.Unix() <= c.ExpiresAt // <--- this is very confusing to me
}

I would suggest changing it to the following:

// VerifyExpiresAt compares the exp claim against a timestamp.
// Will change behaviour depending on the value of corelush.TimeFunc
func (c *Claims) VerifyExpiresAt(now time.Time, grace time.Duration) bool {
        if grace < 0 {
                grace = 0
        }
        if c.ExpiresAt == 0 {
	    	return false
        }
        graceDate := time.Unix(c.ExpiresAt, 0).Add(grace)
        return now.After(graceDate)
}