auth

type Argon2 struct {
	Memory  uint32
	Time    uint32
	Threads uint8
}

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

type Config struct {
	// Users is the app's Users: a value, or a constructor the app's
	// container builds (func(deps…) Users). Nil: the one provided type
	// implementing Users, such as a @web.Service.
	Users any

	// PublicByDefault makes routes without a gate public, as they are
	// without auth: only those marked Required or Requires need a sign-in.
	// By default every route, live page and live event needs one unless
	// marked @auth.Public.
	PublicByDefault bool

	// LoginPath is where a page visit without a sign-in is sent, with
	// ?next=<the page>; "/login" by default. The app serves it (LoginPage
	// is ready to), and marks it @auth.Public.
	LoginPath string
	// Home is where a sign-in goes without a next; "/" by default.
	Home string
	// Endpoints mounts the login, logout, me and token endpoints under a
	// prefix ("/auth": POST /auth/login, POST /auth/logout, GET /auth/me,
	// POST /auth/token); none when empty.
	Endpoints string

	// Roles maps a role to its perms: Identity.Roles adds them.
	Roles map[string][]string

	// Sessions holds cookie sessions; Tokens, bearer tokens. Both are in
	// memory by default: lost on restart, and not shared between replicas
	// (see MemorySessions).
	Sessions SessionStore
	Tokens   TokenStore
	// SessionTTL is how long a session lasts from sign-in; 14 days by
	// default. SessionIdle, when set, ends a session not used for that
	// long. TokenTTL is how long a bearer token lasts; 30 days by default.
	SessionTTL, SessionIdle, TokenTTL time.Duration
	// RememberMe makes staying signed in the user's choice at the login
	// endpoint: a sign-in whose form has the remember field checked (or
	// whose JSON has "remember": true) keeps its session for SessionTTL in
	// a cookie that outlives the browser; any other gets a cookie that
	// ends with the browser session, and a session of a day at most.
	// LoginForm's Remember shows the checkbox. Off, every sign-in is
	// remembered.
	RememberMe bool
	// Cookie names the session cookie; "vk_session" by default.
	Cookie string
	// SecureCookie sets the cookie's Secure flag on every response, not
	// only on HTTPS requests (r.TLS, or X-Forwarded-Proto: https): set it
	// when TLS ends at a proxy that doesn't say so.
	SecureCookie bool

	// Passwords are the hashing parameters of new hashes; Argon2id's
	// defaults (Argon2Defaults) when zero.
	Passwords Argon2
	// Hashers read password encodings auth doesn't (another system's,
	// FindLogin's encoded password as it stored it): a login checks the
	// first that knows the encoding. A match is stale, so the login
	// stores a fresh hash when Users has SetPassword.
	Hashers []Hasher
	// Throttle limits failed logins; ThrottleDefaults when zero.
	Throttle Throttle
	// FailedLoginTime is the least time a failed login takes, so that an
	// unknown login, a wrong password, a stored hash of another cost or
	// encoding and a refused attempt look alike; 300ms by default,
	// negative for none.
	FailedLoginTime time.Duration
	// ClientIP is the address throttling counts a request against;
	// web.ClientIP by default: the connection's peer, or, behind the app's
	// web.TrustedProxies, the address they pass on.
	ClientIP func(r *http.Request) string

	// JWT verifies bearer JWTs issued elsewhere; nil: none accepted.
	JWT *JWT

	// Policies decide Check for the types they name.
	Policies []Policy

	// TrustedOrigins may send cross-origin POSTs and the like (web.CSRF).
	TrustedOrigins []string

	// LaxGates lets a gated method's call that nothing attributes to an
	// identity run, as the app's own work: no request's or live page's
	// context, no live event running it, no auth.WithIdentity or
	// auth.System. By default (StrictGates) such a call is refused: code
	// outside requests (main, a job; crons are marked by themselves) marks
	// its context with auth.System(ctx), and gated methods take a
	// context.Context to be given one. Whatever the setting, a call on a
	// goroutine serving a request is checked against the request's
	// identity, never run as the app's own. It holds for the whole process
	// once an app with it is built.
	LaxGates bool
	// StrictGates is the default; set it to keep an app strict whatever
	// another app of the process says (LaxGates).
	StrictGates bool

	// LiveRecheck is how often a live page loads its identity again
	// (Users.Load) to see that the user is still there with the same perms
	// and roles; a page whose identity changed reloads, signed in afresh
	// or sent to the login page. 60 seconds by default; negative for never.
	// It is looked at when web.LiveCheckEvery checks the page.
	//
	// A live page's sign-in is checked when the page mounts: its join and
	// each navigation run its route, which reads the session or token. Its
	// events trust the identity it mounted with. A sign-in ended through
	// auth — SignOut, Revoke, RevokeUser, a new SignIn replacing the
	// browser's session, a session found expired — closes its pages at
	// once (web's CloseLive); one ended elsewhere (a store row deleted by
	// hand, another process) is caught by the check every
	// web.LiveCheckEvery (30 seconds by default).
	LiveRecheck time.Duration

	// UserCache keeps the identity Users.Load returns for a user this long,
	// so a request signed in with a session or token reads only the
	// session or token: 0 (the default) loads it on every request. A
	// cached identity is dropped when RevokeUser, SetPassword or SignOut
	// touch its user, when Load finds the user gone, and when the app
	// calls Refresh after changing a user's perms, roles or record; a sign-in
	// and LiveRecheck always load afresh. The cache is the process's own:
	// another replica keeps its copy until it expires.
	UserCache time.Duration
}

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

type Hasher interface {
	// Check reports whether password is the one encoded; known is false
	// when encoded isn't in this hasher's encoding.
	Check(encoded, password string) (ok, known bool)
}

type Identity struct {
	ID string // the user's id, as Users.Load takes it
	// Perms are what the user may do: "orders.write", or a wildcard,
	// "orders.*" (everything under orders) or "*" (everything).
	Perms []string
	// Roles name sets of perms (Config.Roles), added to Perms when the
	// identity is loaded.
	Roles []string
	User  any // the app's own user record, for handlers; never sent anywhere by auth
}

type JWT struct {
	Key       []byte         // HS256's secret, at least 32 bytes
	PublicKey *rsa.PublicKey // RS256's key
	Issuer    string         // the "iss" a token must carry, when set
	Audience  string         // an "aud" a token must list, when set
	Leeway    time.Duration  // clock skew allowed on exp and nbf; a minute when 0
}

type LoginFormProps struct {
	Action string // where it posts; "/auth/login" by default
	Next   string // where to go once signed in (SafeNext), else Config.Home
	Error  string // a message to show above the fields
	Login  string // the login field's value: what was typed, on a re-render
	// Remember adds a "Remember me" checkbox, the remember field
	// Config.RememberMe reads.
	Remember bool
	Class    string
}

type LoginPageProps struct {
	// Request fills the form: on a GET its ?next= and ?error=; on a form
	// post (an app's own login handler re-rendering the page) the posted
	// login and next, so what was typed stays.
	Request *http.Request
	Title   string // "Sign in" by default
	Action  string // LoginForm's
	Error   string // the message to show, over Request's ?error= (LoginMessage)
	// Remember is LoginForm's: a "Remember me" checkbox.
	Remember bool
}

type Me struct {
	ID    string   `json:"id"`
	Roles []string `json:"roles,omitempty"`
	Perms []string `json:"perms,omitempty"`
	User  any      `json:"user,omitempty"`
}

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

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

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

type Session struct {
	UserID  string
	Created time.Time
	Seen    time.Time // last used, within a minute
	Expires time.Time
}

type SessionStore interface {
	Get(ctx context.Context, key string) (*Session, error)
	Save(ctx context.Context, key string, s Session) error
	Delete(ctx context.Context, key string) error
	DeleteUser(ctx context.Context, uid string) error
}

type Throttle struct {
	PerLogin int
	PerIP    int
	Window   time.Duration
}

type ThrottledError struct{ RetryAfter time.Duration }

type Token struct {
	UserID  string
	Name    string // what it is for: "cli", "ci"
	Created time.Time
	Expires time.Time
}

type TokenResponse struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int64  `json:"expires_in"`
}

type TokenStore interface {
	Get(ctx context.Context, key string) (*Token, error)
	Save(ctx context.Context, key string, t Token) error
	Delete(ctx context.Context, key string) error
	DeleteUser(ctx context.Context, uid string) error
}

type Users interface {
	FindLogin(ctx context.Context, login string) (*Identity, string, error)
	Load(ctx context.Context, id string) (*Identity, error)
}