login

type Account[P any] struct {
	Principal P
	// PasswordHash is empty for an account without a password.
	PasswordHash string
	// SecondFactor reports that a second step follows a right password.
	SecondFactor bool
}

type Config[P any] struct {
	Throttle Throttle
	Store    Store[P]
	// Gate, when set, reports that an account may not sign in yet (an Unverified User,
	// ADR 0030). It is consulted for every known account, before the password result is
	// acted on.
	Gate func(P) bool
	// Challenge mints the second step's token for an account with a second factor.
	Challenge func(ctx context.Context, principal P) (string, error)
	// Parse turns a challenge token into its Pending, or returns ErrChallengeInvalid.
	Parse func(ctx context.Context, token string) (Pending[P], error)
	// Verify checks a code for a Pending under the adapter's lock (a TOTP code, or a
	// recovery code, which it spends). It returns ErrInvalidCode for a wrong code and
	// ErrChallengeInvalid when the challenge stopped standing (the factor is gone, or a
	// racing second step moved it first).
	Verify func(ctx context.Context, p Pending[P], code string) error
	// PasskeyFind names the account (Pending.Principal and the throttle key Pending.Address)
	// a Passkey response belongs to, by its credential id, or returns ErrPasskeyUnknown. It
	// verifies nothing. Left nil, the surface has no Passkey login.
	PasskeyFind func(ctx context.Context, a PasskeyAssertion) (Pending[P], error)
	// PasskeyVerify checks the response for the account PasskeyFind named: signature,
	// challenge, user verification, single use. It returns ErrPasskeyInvalid when it does not
	// hold.
	PasskeyVerify func(ctx context.Context, p Pending[P], a PasskeyAssertion) error
}

type Delay struct {
	Wait  time.Duration
	Limit int
	Now   time.Time
}

type Module[P any] struct {
	// contains filtered or unexported fields
}

type Outcome int

type PasskeyAssertion struct {
	Ceremony string
	Response []byte
}

type PasskeyOutcome int

type PasskeyResult[P any] struct {
	// Delay is set for a PasskeyThrottled result.
	Delay

	Outcome   PasskeyOutcome
	Principal P
}

type Pending[P any] struct {
	Principal P
	// Address is the account's throttle key (normalized again by the module).
	Address string
	// Method names how the first step proved the person; ProviderLoginAt is the time of
	// a provider login the challenge follows (zero for a password login).
	Method          string
	ProviderLoginAt time.Time
	// Binding is the adapter's own single-use proof, handed back to Verify.
	Binding string
}

type Proof int

type ProofResult struct {
	// Delay is set for ProofThrottled.
	Delay

	Proof Proof
}

type Result[P any] struct {
	// Delay is set for a Throttled result.
	Delay

	Outcome   Outcome
	Principal P
	// Challenge is the second step's token, for a SecondFactor result.
	Challenge string
}

type SecondOutcome int

type SecondResult[P any] struct {
	// Delay is set for a SecondThrottled result.
	Delay

	Outcome         SecondOutcome
	Principal       P
	Method          string
	ProviderLoginAt time.Time
}

type Store[P any] interface {
	Lookup(ctx context.Context, address string) (acc Account[P], ok bool, err error)
}

type Throttle interface {
	Delay(ctx context.Context, address string) (time.Duration, error)
	RecordFailure(ctx context.Context, address string) error
	RecordSuccess(ctx context.Context, address string) error
	Limit() int
	Now() time.Time
}