password

type Challenge string

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

type Options struct {
	Sessions             *session.Store // required
	Storage              Storage        // required
	PathPrefix           string         // default "/auth/password"; segments of A-Z a-z 0-9 . _ ~ -, no trailing "/", no "." or ".." segment
	DisableUsernameLogin bool
	DisableEmailLogin    bool // both true: error
	EnableRegistration   bool // off by default: POST {prefix}/register is not even routed
	Policy               Policy
	TOTP                 TOTPOptions
	HashParameters       Parameters                                      // zero value: DefaultParameters(); at least 32 MiB, 1 iteration, salt and key 16 bytes
	LegacyVerifier       func(password, storedHash string) (bool, error) // optional, e.g. VerifyBcrypt; consulted for stored hashes that are not Argon2id
	OnLogin              auth.Hook                                       // must keep UserID, the Storage user ID that Refresh and the TOTP routes look users up by; a login whose hook replaces it fails (500)
	OnLogout             auth.LogoutHook
	Observer             auth.Observer
}

type Parameters struct {
	Memory      uint32 // KiB
	Iterations  uint32
	Parallelism uint8
	SaltLength  uint32
	KeyLength   uint32
}

type Policy struct {
	MinimumLength    int // in characters (runes); default 12; maximum length is fixed at 128 bytes
	RequireUppercase bool
	RequireLowercase bool
	RequireDigit     bool
	RequireSpecial   bool // any rune that is neither letter nor digit
}

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

type Storage interface {
	// CreateUser stores a new user. A username or email another user already has, ignoring case, is
	// ErrUserExists; let a unique constraint decide it (e.g. on lower(email)), not a lookup before the insert.
	CreateUser(ctx context.Context, user *User) error
	// GetUserByUsername returns the user with username, ignoring case (e.g. WHERE lower(username) = lower($1)),
	// or ErrUserNotFound. The provider passes identifiers as typed.
	GetUserByUsername(ctx context.Context, username string) (*User, error)
	// GetUserByEmail returns the user with email, ignoring case, or ErrUserNotFound.
	GetUserByEmail(ctx context.Context, email string) (*User, error)
	// GetUserByID returns the user with id, or ErrUserNotFound.
	GetUserByID(ctx context.Context, id uuid.UUID) (*User, error)
	// UpdatePasswordHash replaces the password hash only while the stored one still equals currentHash
	// (compare-and-swap, e.g. UPDATE ... WHERE id = $1 AND password_hash = $2); a mismatch is not an error, so a
	// concurrent password change is never overwritten.
	UpdatePasswordHash(ctx context.Context, id uuid.UUID, currentHash, newHash string) error
	// ConsumeTOTPAttempt reserves one second-factor attempt before a code is checked: below maximum it
	// increments the counter and returns the attempts left after this one (never negative); otherwise it changes
	// nothing and returns ErrTOTPAttemptsExhausted. Check and increment are one atomic step, e.g.
	// UPDATE ... SET attempts = attempts + 1 WHERE id = $1 AND attempts < $2 RETURNING $2 - attempts.
	ConsumeTOTPAttempt(ctx context.Context, id uuid.UUID, maximum int) (remaining int, err error)
	// ResetTOTPAttempts sets the attempt counter to zero. The provider calls it after a verified second factor;
	// the application calls it to unlock a user whose attempts are exhausted.
	ResetTOTPAttempts(ctx context.Context, id uuid.UUID) error
	// ConsumeTOTPStep marks the TOTP time step starting at step as the last one the user used: when step is later
	// than the step it holds (or it holds none), it records step and returns true; otherwise it changes nothing
	// and returns false, so a code is accepted once and never after a later one. Check and write are one atomic
	// step, e.g. UPDATE ... SET totp_step = $2 WHERE id = $1 AND (totp_step IS NULL OR totp_step < $2).
	// SetTOTP and ClearTOTP keep it.
	ConsumeTOTPStep(ctx context.Context, id uuid.UUID, step time.Time) (bool, error)
	// ConsumeBackupCode removes hash from BackupCodeHashes and reports whether it was there; of two concurrent
	// calls with the same hash at most one returns true.
	ConsumeBackupCode(ctx context.Context, id uuid.UUID, hash string) (bool, error)
	// SetTOTP enables TOTP with secret and backupCodeHashes and resets the attempt counter, but only while TOTP is
	// disabled: it reports whether it did, and changes nothing for a user who has TOTP enabled, so a concurrent
	// enrollment never replaces the second factor another one just set. Check and write are one atomic step, e.g.
	// UPDATE ... SET totp_enabled = true, ... WHERE id = $1 AND NOT totp_enabled.
	SetTOTP(ctx context.Context, id uuid.UUID, secret string, backupCodeHashes []string) (bool, error)
	// ClearTOTP disables TOTP, clears the secret and the backup codes and resets the attempt counter.
	ClearTOTP(ctx context.Context, id uuid.UUID) error
}

type TOTPOptions struct {
	Enabled            bool          // routes the TOTP endpoints and challenges users who enabled TOTP; while off, their logins fail (500)
	Required           bool          // users without TOTP enroll during login; needs Enabled
	Issuer             string        // required when Enabled (otpauth issuer)
	Period             uint          // default 30 s; at most 3600
	Digits             uint          // 6 or 8; default 6
	Skew               uint          // periods accepted before and after the current one; default 1; at most 10
	MaximumAttempts    int           // default 5 wrong codes in a row, across logins; then the second factor stays locked until Storage.ResetTOTPAttempts
	PendingTTL         time.Duration // default 5 min (password step to code step)
	DisableBackupCodes bool
	BackupCodeCount    int    // default 10; at most 20
	BackupCodeLength   int    // default 10; at most 128 bytes per code and at least a million distinct codes
	BackupCodeAlphabet string // default "0123456789"; at least 2 distinct runes, no white space; stored lower-case, repeated runes count once
}

type User struct {
	ID               uuid.UUID
	Username         *string // nil when the user has none; at least one of Username and Email is set
	Email            *string
	PasswordHash     string   // Argon2id (Hash), or a legacy hash Options.LegacyVerifier understands
	TOTPEnabled      bool     // set by SetTOTP, cleared by ClearTOTP
	TOTPSecret       *string  // base32 TOTP secret while TOTPEnabled
	BackupCodeHashes []string // Argon2id hashes of the unused backup codes
}