Documentation
¶
Overview ¶
Package auth provides passwordless visitor accounts for a site: a user proves an email address by clicking a magic link and then carries a signed session cookie. Users are stored as SML below the site's data directory; there is no database. The package knows nothing about pages or features — internal/server wires it to HTTP (see CWUP/tasks/feature_requests.md).
Index ¶
- Constants
- Variables
- func NormalizeEmail(email string) (key string, ok bool)
- func RenderConfirm(d ConfirmData) (template.HTML, error)
- func RenderLoginForm(d LoginFormData) (template.HTML, error)
- func RenderSent(lang, email string) (template.HTML, error)
- func SafeNext(next string) string
- func T(lang, key string) string
- type ConfirmData
- type LoginFormData
- type Mail
- type Service
- func (s *Service) CSRFToken(r *http.Request) string
- func (s *Service) CheckCSRF(r *http.Request, token string) bool
- func (s *Service) CheckToken(token string) (email string, ok bool)
- func (s *Service) ConsumeToken(token string) (*User, string, error)
- func (s *Service) Current(r *http.Request) *User
- func (s *Service) IsBlocked(id string) bool
- func (s *Service) Login(w http.ResponseWriter, u *User)
- func (s *Service) Logout(w http.ResponseWriter)
- func (s *Service) NewLoginToken(email, next string) (string, error)
- func (s *Service) SetBlocked(id string, blocked bool) error
- func (s *Service) Sign(purpose, msg string) string
- func (s *Service) User(id string) (*User, bool)
- func (s *Service) UserByKey(key string) (*User, bool)
- func (s *Service) Verify(purpose, msg, sig string) bool
- type User
Constants ¶
const ( // CookieName is the session cookie. CookieName = "fcms_session" // SessionTTL is how long a login lasts. SessionTTL = 30 * 24 * time.Hour // TokenTTL is how long a magic link is valid. TokenTTL = 15 * time.Minute // MaxEmailLen is the longest address accepted (RFC 5321 path limit). MaxEmailLen = 254 )
const HoneypotField = "website"
HoneypotField is a login form field hidden from people; bots fill it in.
Variables ¶
var ErrInvalidToken = errors.New("invalid or expired login link")
ErrInvalidToken is returned for unknown, used or expired login tokens.
Functions ¶
func NormalizeEmail ¶
NormalizeEmail returns the key that makes an account unique: lower case, "+tag" removed, and for Gmail the dots in the local part removed, so one mailbox cannot open several accounts through address aliases. ok is false for anything that is not a single plain address.
func RenderConfirm ¶
func RenderConfirm(d ConfirmData) (template.HTML, error)
RenderConfirm renders the page behind a magic link.
func RenderLoginForm ¶
func RenderLoginForm(d LoginFormData) (template.HTML, error)
RenderLoginForm renders the login page (or "logged in as" with logout).
func RenderSent ¶
RenderSent renders the "check your inbox" page.
Types ¶
type ConfirmData ¶
ConfirmData feeds the page behind a magic link. Email is empty for an invalid link.
type LoginFormData ¶
type LoginFormData struct {
Lang string
Next string
Email string
Error string
Privacy string // route path of the privacy policy, optional
User *User // set when already logged in
CSRF string
}
LoginFormData feeds the login page.
type Service ¶
type Service struct {
// Secure sets the Secure flag on the session cookie (https sites).
Secure bool
// contains filtered or unexported fields
}
Service holds the users and login tokens of one site. Pending login tokens live in memory only: a restart invalidates open links (15 minutes at most), which is acceptable and keeps no secrets on disk.
func Open ¶
Open loads (and creates, mode 0700) the auth directory: the signing secret (generated on first start) and users.sml.
func (*Service) CSRFToken ¶
CSRFToken returns the token that POST forms of a logged-in user carry. It is bound to the session cookie, so it changes with every login.
func (*Service) CheckToken ¶
CheckToken reports whether token is a valid, unused login token, without using it up (mail scanners open links; only the POST logs in).
func (*Service) ConsumeToken ¶
ConsumeToken uses up a login token and returns the user, creating the account on first login.
func (*Service) Login ¶
func (s *Service) Login(w http.ResponseWriter, u *User)
Login sets the session cookie for u.
func (*Service) Logout ¶
func (s *Service) Logout(w http.ResponseWriter)
Logout clears the session cookie.
func (*Service) NewLoginToken ¶
NewLoginToken creates a magic-link token for email (which the caller has validated as a plain address). After login the user is sent to next. Only the token's hash is kept.
func (*Service) SetBlocked ¶
SetBlocked blocks or unblocks a user. A blocked user stays logged in but the application ignores what the user did (e.g. votes).
func (*Service) Sign ¶
Sign returns a URL-safe HMAC of msg with the site secret, for links that other modules hand out (e.g. newsletter confirm/unsubscribe). purpose separates the uses, so a signature of one kind never passes as another.