plugin

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

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 Plugin interface {
	// ID returns the stable plugin identifier.
	ID() string
	// Register contributes routes, schema, hooks, and OpenAPI operations.
	Register(r *Registry) error
}

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

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 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
}