plugin

type CreateUserInput struct {
	Email       string
	DisplayName string
	ImageURL    string
	// EmailVerified marks the address as proven by the calling flow.
	EmailVerified bool
}

type CredentialResolver interface {
	// Claims reports whether the resolver owns the bearer value. It must look
	// at the shape of the value only, and it must make no database call.
	Claims(bearer string) bool
	// Resolve returns the principal of the bearer value. It returns an error
	// when the credential does not authenticate.
	Resolve(ctx context.Context, bearer string) (*Principal, error)
}

type HTTPService interface {
	// CheckOrigin rejects a state-changing request from an untrusted origin.
	CheckOrigin(r *http.Request) error
	// DecodeJSON reads a JSON request body.
	DecodeJSON(r *http.Request, dst any) error
	// WriteJSON writes a JSON response.
	WriteJSON(w http.ResponseWriter, status int, body any)
	// WriteError writes the public error envelope.
	WriteError(w http.ResponseWriter, err error)
	// SafeRedirect returns candidate when it points at a trusted origin, and
	// fallback otherwise.
	SafeRedirect(candidate, fallback string) string
	// ClientIP returns the request IP for rate-limit keys.
	ClientIP(r *http.Request) string
}

type IssueTokenInput struct {
	// Kind separates token namespaces, for example "magic-link".
	Kind string
	// UserID is optional. A flow for an unknown address leaves it nil.
	UserID *string
	// Identifier is the subject of the token, normally a normalized email.
	Identifier string
	// TTL is the token lifetime.
	TTL time.Duration
	// ReplaceExisting removes outstanding tokens of the same kind and
	// identifier before it issues the new token.
	ReplaceExisting bool
}

type MFAService interface {
	// Challenge reports whether the user must pass a second factor, and
	// returns a single-use challenge token when so. The caller must issue no
	// session while required is true.
	Challenge(ctx context.Context, user *store.User) (token string, required bool, err error)
	// SetCookie writes the challenge into the short-lived challenge cookie. A
	// redirect flow uses it, because a token in a query parameter reaches the
	// browser history, the server log, and any leaked Referer header.
	SetCookie(w http.ResponseWriter, token string)
	// MarkRedirect adds the marker that tells the application to ask for a
	// code. The marker names no token, so it is safe in a URL.
	MarkRedirect(target string) string
}

type PasswordService interface {
	// CheckPassword reports whether a password meets the configured policy.
	CheckPassword(password string) error
	// HashPassword returns the argon2id hash of a password.
	HashPassword(password string) (string, error)
}

type Plugin interface {
	// ID returns the stable plugin identifier.
	ID() string
	// Register contributes routes, schema, hooks, and OpenAPI operations.
	Register(r *Registry) error
}

type Principal struct {
	// User is the owner of the credential. It must not be nil.
	User *store.User
	// Session is nil for a credential that is no session.
	Session *store.Session
	// APIKey is nil for a session credential.
	APIKey *store.APIKey
	// Role is the effective role of the request.
	Role string
	// Method names the authentication method, for example "api_key".
	Method string
}

type PrincipalService interface {
	// Current returns the principal of the request context. It returns nil
	// when no middleware authenticated the request.
	Current(ctx context.Context) *Principal
}

type PrincipalServices interface {
	Principals() PrincipalService
}

type ProtectService interface {
	// Protect refuses a request with no principal, and it refuses an unsafe
	// cross-site request that a cookie authenticated.
	Protect(next http.Handler) http.Handler
}

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

type RoleConfigurator interface {
	// SetRoles installs the ordered hierarchy and the default role.
	SetRoles(names []string, defaultRole string) error
}

type RoleService interface {
	// Names returns the roles from the lowest to the highest.
	Names() []string
	// Default returns the role of a user whose role is empty.
	Default() string
	// Rank returns the position of a role. A role that the configuration does
	// not name ranks below every role, so its rank is negative.
	Rank(role string) int
	// AtLeast reports whether role ranks equal to or above min.
	AtLeast(role, min string) bool
}

type RoleServices interface {
	Roles() RoleService
}

type Route struct {
	// Method is the HTTP method.
	Method string
	// Path is relative to the configured Auth-All base path and starts with /.
	Path string
	// Handler serves the route.
	Handler http.Handler
	// Operation documents the route. A route without an operation stays out of
	// the OpenAPI document and out of the generated client.
	Operation *openapi.Operation
}

type SchemaService interface {
	// SchemaOptions returns the physical options of the effective schema.
	SchemaOptions() schema.Options
}

type Services interface {
	// Store returns the configured storage adapter.
	Store() store.Store
	// Email returns the configured email sender.
	Email() email.Sender
	// Events returns the observability emitter.
	Events() *events.Emitter
	// Now returns the configured clock.
	Now() time.Time
	// BasePath returns the mounted base path, for example /api/auth.
	BasePath() string
	// BaseURL returns the absolute public base URL of the application.
	BaseURL() string
	// RateLimiter returns the configured limiter. It is never nil.
	RateLimiter() ratelimit.Limiter
	// Logger returns the configured logger.
	Logger() *slog.Logger

	// Users exposes user operations that run the configured hooks.
	Users() UserService
	// Sessions exposes session operations.
	Sessions() SessionService
	// Tokens exposes one-time token operations.
	Tokens() TokenService
	// HTTP exposes the request helpers Auth-All uses for its own routes.
	HTTP() HTTPService
	// MFA exposes the second-factor gate. A plugin that authenticates a user
	// must consult it before it issues a session.
	MFA() MFAService
}

type SessionService interface {
	// Issue creates a session for the user and writes the session cookie.
	// Method names the authentication method for hooks and events.
	Issue(ctx context.Context, w http.ResponseWriter, r *http.Request, user *store.User, method string) (*store.Session, error)
	// Current resolves the session of a request. It returns nil values when no
	// valid session exists.
	Current(ctx context.Context, r *http.Request) (*store.Session, *store.User, error)
	// Revoke deletes one session.
	Revoke(ctx context.Context, sessionID string) error
	// RevokeAll deletes every session of one user and returns the count.
	RevokeAll(ctx context.Context, userID string) (int, error)
	// Clear removes the session cookie.
	Clear(w http.ResponseWriter)
}

type TokenService interface {
	Issue(ctx context.Context, in IssueTokenInput) (plaintext string, token *store.Token, err error)
	// Consume atomically consumes a token. Two concurrent calls for the same
	// token produce at most one success.
	Consume(ctx context.Context, kind, plaintext string) (*store.Token, error)
	// Peek returns a token and consumes nothing. It reports an invalid token
	// for a value that is missing, expired, or already consumed.
	//
	// A confirmation page calls Peek, so a repeated page load and a mail
	// scanner that pre-fetches a link do not destroy the token.
	Peek(ctx context.Context, kind, plaintext string) (*store.Token, error)
}

type UserService interface {
	ByID(ctx context.Context, id string) (*store.User, error)
	// ByEmail looks a user up by the normalized form of the address.
	ByEmail(ctx context.Context, address string) (*store.User, error)
	// Create inserts a user and runs the user creation hooks.
	Create(ctx context.Context, in CreateUserInput) (*store.User, error)
	// MarkEmailVerified records proven ownership of the user email address. It
	// changes no other row. A passwordless flow calls ProveEmailOwnership
	// instead.
	MarkEmailVerified(ctx context.Context, userID string) error
	// DeleteCredential removes the password credential of a user. It succeeds
	// for a user that has no password credential.
	DeleteCredential(ctx context.Context, userID string) error
	// ProveEmailOwnership records proven control of the address of a user.
	//
	// A passwordless flow calls it after the flow proves that the person
	// controls the address. When the address was not verified yet, somebody can
	// have set a password and started a session before the proof. The method
	// therefore deletes the password credential of the user, revokes every
	// session of the user, and marks the address verified. It performs the
	// three steps in one transaction.
	//
	// The method does nothing for a user whose address is already verified, so
	// a normal repeat sign-in keeps its password and its sessions.
	//
	// A plugin that proves control of an address must call this method before
	// it issues a session.
	ProveEmailOwnership(ctx context.Context, userID string) error
}