cap

type Cap struct {
	// contains filtered or unexported fields
}

type Challenge struct {
	// The token used to identify the challenge.
	ChallengeToken string

	// The redeem token, returned for correct solutions.
	// This can be redeemed once by a client once received.
	RedeemToken string

	// The parameters used to generate the challenge and verify its solution.
	Params ChallengeParams

	// The expiration time, when solutions will no longer be accepted and the redeem token
	// will no longer be accepted.
	Expires time.Time
}

type ChallengeParams struct {
	// The difficulty level of the challenge.
	Difficulty int `json:"d"`

	// The number of challenges to generate.
	Count int `json:"c"`

	// The size of the salt in bytes.
	SaltSize int `json:"s"`
}

type ChallengeRequest struct {
	// The parameters for the challenge.
	Params ChallengeParams

	// The IP address that is requesting the challenge.
	// Can be nil.
	// Used by the driver for optional rate limiting.
	IP *netip.Addr

	// The duration for which the challenge is valid.
	ValidDuration time.Duration
}

type ChallengeResponse struct {
	// The challenge parameters.
	Params ChallengeParams `json:"challenge"`

	// The challenge hash/token.
	ChallengeHash string `json:"token"`

	// The UNIX millisecond timestamp when the challenge expires.
	ExpiresMs int64 `json:"expires"`
}

type Driver interface {
	// Store stores a challenge.
	// The challenge must not be nil.
	// The driver is responsible for clearing expired challenges.
	//
	// If `ip` is not nil, it can be used for rate limiting, and the
	// driver may return ErrRateLimited.
	Store(ctx context.Context, challenge *Challenge, ip *netip.Addr) error

	// GetUnredeemedChallenge returns the unredeemed challenge with the specified challenge token.
	// Returns nil if the challenge does not exist, is expired, or is already redeemed.
	//
	// Will not return ErrRateLimited.
	GetUnredeemedChallenge(ctx context.Context, challengeToken string) (*Challenge, error)

	// UseRedeemToken redeems the specified redeem token.
	// If the challenge did not exist, was expired, or was already redeemed, returns false.
	// If the redemption was successful, returns true.
	// The redeem token must not be able to be re-used after calling this function with it.
	//
	// Will not return ErrRateLimited.
	UseRedeemToken(ctx context.Context, redeemToken string) (wasRedeemed bool, err error)
}

type RateLimitOptions struct {
	IPv4SignificantBits int
	IPv6SignificantBits int

	MaxChallengesPerIP  int
	MaxChallengesWindow time.Duration
}

type RedeemData struct {
	RedeemToken string
	Expires     time.Time
}

type VerifySolutionsRequest struct {
	ChallengeToken string   `json:"token"`
	Solutions      []uint32 `json:"solutions"`
}