Documentation
¶
Overview ¶
Package dashauth provides authentication and authorization abstractions for the dashboard extension. It is intentionally decoupled from the auth extension so the dashboard has no hard dependency on any specific auth provider.
Index ¶
- func ForgeMiddleware(checker AuthChecker) forge.Middleware
- func IsAuthenticated(ctx context.Context) bool
- func PageMiddleware(level AccessLevel, loginPath string) router.Middleware
- func RequireRole(role string) router.Middleware
- func RequireScope(scope string) router.Middleware
- func WithUser(ctx context.Context, user *UserInfo) context.Context
- type AccessLevel
- type AuthChecker
- type AuthCheckerFunc
- type AuthPageDescriptor
- type AuthPageProvider
- type AuthPageType
- type UserInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ForgeMiddleware ¶
func ForgeMiddleware(checker AuthChecker) forge.Middleware
ForgeMiddleware returns forge.Middleware that runs the AuthChecker and stores the resulting UserInfo in the request context. This middleware runs on the forge.Router catch-all route, BEFORE the request reaches ForgeUI.
It does NOT block unauthenticated requests — it only populates the context. Access enforcement is handled by PageMiddleware at the ForgeUI layer.
func IsAuthenticated ¶
IsAuthenticated returns true if the context contains an authenticated user.
func PageMiddleware ¶
func PageMiddleware(level AccessLevel, loginPath string) router.Middleware
PageMiddleware returns ForgeUI router.Middleware that enforces an AccessLevel on a specific page. It reads the UserInfo from the request context (placed there by ForgeMiddleware) and decides whether to allow, redirect, or pass through.
- AccessPublic: always passes through.
- AccessPartial: always passes through (the page handler checks auth itself).
- AccessProtected: checks UserFromContext; redirects to loginPath if nil.
The loginPath should be the full dashboard path (e.g. "/dashboard/auth/login").
func RequireRole ¶
func RequireRole(role string) router.Middleware
RequireRole returns ForgeUI middleware that checks the user has a specific role. It assumes PageMiddleware(AccessProtected, ...) already ran, so the user is authenticated. If the user lacks the role, a 403 Forbidden response is returned.
func RequireScope ¶
func RequireScope(scope string) router.Middleware
RequireScope returns ForgeUI middleware that checks the user has a specific scope.
Types ¶
type AccessLevel ¶
type AccessLevel int
AccessLevel defines the protection level for a dashboard page or route.
const ( // AccessPublic means the page is always accessible without authentication. AccessPublic AccessLevel = iota // AccessProtected means authentication is required; unauthenticated users // are redirected to the login page. AccessProtected // AccessPartial means the page is always accessible but may render // differently depending on authentication state. The page handler should // check UserFromContext to adapt its output. AccessPartial )
func ParseAccessLevel ¶
func ParseAccessLevel(s string) AccessLevel
ParseAccessLevel parses a string into an AccessLevel. Accepted values: "public", "protected", "partial". Returns AccessPublic for unrecognized values.
func (AccessLevel) String ¶
func (a AccessLevel) String() string
String returns the string representation of the access level.
type AuthChecker ¶
type AuthChecker interface {
// CheckAuth inspects the request and returns a UserInfo if authenticated.
// Returns nil (not an error) when the request is unauthenticated.
// Returns an error only for infrastructure failures (e.g. token validation
// service unreachable).
CheckAuth(ctx context.Context, r *http.Request) (*UserInfo, error)
}
AuthChecker validates authentication state from HTTP requests. It is the primary abstraction the dashboard uses to check whether a request is authenticated. Implementations typically delegate to an auth extension's registry or a custom authentication mechanism.
type AuthCheckerFunc ¶
AuthCheckerFunc is a function adapter for AuthChecker.
type AuthPageDescriptor ¶
type AuthPageDescriptor struct {
// Type identifies the kind of auth page (login, logout, register, etc.).
Type AuthPageType
// Path is the route path relative to the auth base path (e.g. "/login").
Path string
// Title is the page title shown in the browser tab.
Title string
// Icon is the optional icon name for the page.
Icon string
}
AuthPageDescriptor describes an auth page contributed to the dashboard.
type AuthPageProvider ¶
type AuthPageProvider interface {
// AuthPages returns the list of auth pages this provider contributes.
AuthPages() []AuthPageDescriptor
// RenderAuthPage renders the HTML for an auth page (GET request).
// The page type identifies which auth page to render.
RenderAuthPage(ctx *router.PageContext, pageType AuthPageType) (g.Node, error)
// HandleAuthAction handles a form submission for an auth page (POST request).
// Returns:
// - redirectURL: if non-empty, the user should be redirected to this URL
// - errNode: if non-nil, re-render the page with this error content
// - err: infrastructure errors
HandleAuthAction(ctx *router.PageContext, pageType AuthPageType) (redirectURL string, errNode g.Node, err error)
}
AuthPageProvider contributes authentication pages to the dashboard. Auth extensions implement this interface to provide login, register, and other auth-related pages that integrate into the dashboard shell.
type AuthPageType ¶
type AuthPageType string
AuthPageType identifies the kind of authentication page.
const ( PageLogin AuthPageType = "login" PageLogout AuthPageType = "logout" PageRegister AuthPageType = "register" PageForgotPassword AuthPageType = "forgot-password" PageResetPassword AuthPageType = "reset-password" PageCallback AuthPageType = "callback" PageProfile AuthPageType = "profile" )
type UserInfo ¶
type UserInfo struct {
// Subject is the unique user identifier (e.g. user ID, email, or sub claim).
Subject string
// DisplayName is the user's display name.
DisplayName string
// Email is the user's email address.
Email string
// AvatarURL is the URL of the user's avatar image.
AvatarURL string
// Roles holds the user's roles (e.g. "admin", "editor").
Roles []string
// Scopes holds the user's OAuth2 scopes or permission strings.
Scopes []string
// ProviderName identifies which auth provider authenticated this user.
ProviderName string
// Claims holds additional authentication claims.
Claims map[string]any
// Metadata holds provider-specific metadata.
Metadata map[string]any
}
UserInfo represents an authenticated dashboard user. This type is decoupled from any specific auth provider — adapters convert provider-specific auth contexts into UserInfo.
func UserFromContext ¶
UserFromContext retrieves the UserInfo from the context. Returns nil if no user is stored (i.e. unauthenticated request).
func (*UserInfo) Authenticated ¶
Authenticated returns true if the user has a non-empty Subject.
func (*UserInfo) HasAnyRole ¶
HasAnyRole checks if the user has any of the specified roles.
Source Files