user

type AccountState struct {
	Email         string
	EmailVerified bool
	// Locked is an explicit lock (store.LockoutStore.LockAccount).
	Locked bool
	// Throttled is the temporary lockout derived from recent failures.
	Throttled bool
	TwoFactor bool
}

type AuthResult struct {
	User                  store.User
	Tokens                *TokenPair
	RequiresTwoFactor     bool
	PendingTwoFactorToken string
}

type Config struct {
	// SessionMode selects the session model. Defaults to SessionModeJWT.
	SessionMode SessionMode
	// SessionSlidingWindow is how much of a session's life must elapse
	// before using it extends it, in SessionModeOpaque. Defaults to a
	// quarter of RefreshTokenTTL; a negative value disables extension, so
	// sessions expire a fixed time after being issued.
	//
	// A threshold rather than extending on every request, because the
	// latter is a write per request. Nothing here is consulted in
	// SessionModeJWT.
	SessionSlidingWindow time.Duration
	// AccessTokenTTL is how long an issued access JWT is valid for.
	// Ignored in SessionModeOpaque, which issues no JWT.
	AccessTokenTTL time.Duration
	// RefreshTokenTTL is how long a refresh token (session) stays valid if
	// never revoked.
	RefreshTokenTTL time.Duration
	// PasswordResetTTL is how long a password reset link stays valid.
	PasswordResetTTL time.Duration
	// EmailVerificationTTL is how long an email verification link stays
	// valid.
	EmailVerificationTTL time.Duration
	// PendingTwoFactorTTL is how long a caller has to complete the 2FA step
	// after a correct password before having to log in again.
	PendingTwoFactorTTL time.Duration
	// MaxFailedLoginAttempts is how many recent failed logins put an
	// address into temporary lockout. Both the password step and the
	// second-factor step count against it, and it is only reset once a
	// login fully succeeds -- so an attacker holding a valid password gets
	// this many guesses at the second factor per FailedLoginWindow, not
	// unlimited guesses.
	MaxFailedLoginAttempts int
	// FailedLoginWindow is the lookback window used when counting recent
	// failed attempts, and therefore also how long a temporary lockout
	// lasts: it lifts once the recorded attempts age out. Nothing has to
	// unlock the account, and no operator action is required.
	FailedLoginWindow time.Duration
	// TOTPIssuer is the issuer name embedded in generated TOTP QR codes.
	TOTPIssuer string
	// TOTPEncryptionKey encrypts TOTP secrets at rest (AES-256-GCM). Must be
	// exactly 32 bytes. Required if 2FA methods are used.
	TOTPEncryptionKey []byte
	// BackupCodeCount is how many backup codes are generated on 2FA setup.
	BackupCodeCount int
	// EmailVerification decides whether Authenticate gates login on
	// User.EmailVerified. Defaults to EmailVerificationRequired.
	EmailVerification EmailVerificationPolicy
	// AuditLogger receives security-relevant events (login, lockout,
	// password/2FA changes, session revocation). Nil means events are not
	// recorded — see package audit.
	AuditLogger audit.Logger
	// PasswordHasher hashes and verifies passwords. Nil means
	// crypto.DefaultHasher() — Argon2id at OWASP's recommended minimum.
	//
	// Changing this does not invalidate existing passwords: every Hasher
	// verifies any format authit has written, and Authenticate re-hashes a
	// user's password on their next successful login once the configured
	// hasher reports NeedsRehash. An application upgrading from a version
	// that hardcoded bcrypt migrates its corpus by doing nothing.
	PasswordHasher authitcrypto.Hasher
	// PasswordValidator rejects unacceptable passwords on registration,
	// change and reset. Nil means crypto.DefaultPasswordPolicy() (length
	// only). It is never consulted on login, so tightening it does not lock
	// out existing users; set it to a no-op func to disable it entirely.
	PasswordValidator authitcrypto.PasswordValidator
	// RateLimiter throttles the paths where refusing early matters. Nil
	// means ratelimit.Noop — the control is off, not broken.
	//
	// This does not replace rate limiting in your HTTP middleware, which
	// sees routes, headers and every request; it covers what middleware
	// cannot reach. Its most important job is refusing an attacker
	// *before* Authenticate runs the password KDF: Argon2id costs 19 MiB
	// and real CPU per attempt by default, so an unauthenticated flood is
	// a resource-exhaustion vector regardless of whether any password is
	// ever guessed.
	//
	// Keys passed to Allow, so an implementation can apply its own policy
	// per operation:
	//
	//	login:ip:<ip>                      Authenticate, per source address
	//	login:email:<email>                Authenticate, per account
	//	two-factor:ip:<ip>                 VerifyTwoFactorLogin
	//	two-factor:user:<user id>          VerifyTwoFactorLogin
	//	password-reset:email:<email>       RequestPasswordReset
	//	email-verification:email:<email>   RequestEmailVerificationByEmail
	//	email-verification:user:<user id>  RequestEmailVerification
	//
	// The email in a key is always the normalised form (see
	// store.NormalizeEmail), so case cannot be used to get a fresh budget.
	// An empty IP address is skipped rather than collapsing every caller
	// into one bucket, so a host that does not supply one loses the
	// per-address limit but keeps the rest.
	RateLimiter ratelimit.Limiter
	// Hooks are optional callbacks into the host's own code at the points
	// where a flow stops being authit's business. The zero value does
	// nothing. See Hooks for what Before and After each guarantee, which
	// differs depending on whether Stores.Tx is configured.
	Hooks Hooks
}

type EmailSender interface {
	SendPasswordReset(ctx context.Context, email, token string) error
	SendEmailVerification(ctx context.Context, email, token string) error
}

type EmailVerificationPolicy int

type Hooks struct {
	// BeforeRegister runs before a new account is created, with the
	// normalised address. Returning an error refuses the registration.
	//
	// It fires before authit checks whether the address is already taken,
	// so it is reached even for a duplicate registration: it is a cheap
	// gate — an invite-only check, a domain allow-list — and making it pay
	// for a database round trip first would defeat the point.
	BeforeRegister func(ctx context.Context, email string) error

	// AfterRegister runs once the account exists.
	AfterRegister func(ctx context.Context, u store.User) error

	// BeforeAuthenticate runs before the password is verified, with the
	// normalised address. Returning an error refuses the login.
	//
	// It runs after rate limiting and the lockout check, so it cannot be
	// used to bypass either, and before the password hash comparison, so
	// refusing here costs no KDF work.
	BeforeAuthenticate func(ctx context.Context, email string) error

	// AfterAuthenticate runs when a login has *fully* succeeded — which
	// for an account with two-factor enabled means after the second
	// factor, not after the password. A hook stamping a last-seen
	// timestamp must not fire for a login that stopped half way.
	AfterAuthenticate func(ctx context.Context, u store.User) error

	// AfterPasswordChange runs after ChangePassword or ResetPassword, with
	// the user as they now are.
	AfterPasswordChange func(ctx context.Context, u store.User) error
}

type NoopEmailSender struct{}

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

type Session struct {
	ID        string
	IsCurrent bool
	UserAgent string
	IPAddress string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type SessionMode int

type Stores struct {
	Users              store.UserStore
	RefreshTokens      store.RefreshTokenStore
	PasswordResets     store.PasswordResetStore
	EmailVerifications store.EmailVerificationStore
	TOTP               store.TOTPStore
	PendingTwoFactor   store.PendingTwoFactorStore
	Lockouts           store.LockoutStore
	// Tx is optional. Supplying it makes the flows that write more than
	// once atomic -- Refresh, VerifyTwoFactorLogin and ResetPassword. Nil
	// leaves them as a sequence of independent writes, which is what they
	// have always been. See store.TxRunner for the obligation it puts on
	// an implementation; it is not a formality.
	Tx store.TxRunner
}

type TokenPair struct {
	AccessToken  string
	RefreshToken string
	ExpiresAt    time.Time
}

type TwoFactorEnrollment struct {
	BackupCodes []string
}

type TwoFactorSetup struct {
	Secret     string
	OTPAuthURL string
}

type TwoFactorStatus struct {
	Enabled              bool
	VerifiedAt           *time.Time
	RemainingBackupCodes int
}